Merge branch 'v1.0'

.babelrc

@@ -0,0 +1,14 @@
+{
+  "presets": [
+    ["env",{
+      "modules":false,
+      "targets":{
+        node: 6
+      }
+    }]
+  ],
+  "plugins": [
+    "transform-async-to-generator",
+    "external-helpers"
+  ]
+}

.gitignore

@@ -1,5 +1,5 @@
+*.sublime-*
 node_modules
 auth.js
-credentials.js
-*.sublime-*
 dist
+npm-debug.log

.npmignore

@@ -1,4 +1,5 @@
-src
+*.sublime-*
 node_modules
 auth.js
-*.sublime-*
+src
+dist

README.md

@@ -13,11 +13,68 @@ const api = new ScreepsAPI({
   password: 'notMyPass'
 });
 
-Promise.resolve()
-  .then(() => api.connect())
-  .then(() => api.memory.get())
+// Dump Memory
+api.memory.get()
   .then(memory => {
     fs.writeFileSync('memory.json', JSON.stringify(memory))
   })
   .catch(err => console.error(err));
+
+
+// Dump Memory Path
+api.memory.get('rooms.W0N0')
+  .then(memory => {
+    fs.writeFileSync('memory.rooms.W0N0.json', JSON.stringify(memory))
+  })
+  .catch(err => console.error(err));
+
+// Get user info
+api.me().then((user)=>console.log(user))
+
+// Socket API
+
+api.socket.connect()
+// Events have the structure of:
+// {
+//   channel: 'room',
+//   id: 'E3N3', // Only on certain events
+//   data: { ... }	
+// }
+api.socket.on('connected',()=>{
+	// Do stuff after conntected
+})
+api.socket.on('auth',(event)=>{
+	event.data.status contains either 'ok' or 'failed'	
+	// Do stuff after auth
+})
+
+// Events: (Not a complete list)
+// connected disconnected message auth time protocol package subscribe unsubscribe console
+
+// Subscribtions can be queued even before the socket connects or auths, 
+// although you may want to subscribe from the connected or auth callback to better handle reconnects
+
+api.socket.subscribe('console')
+api.socket.on('console',(event)=>{
+	event.data.messages.log // List of console.log output for tick
+})
+
+
+// Starting in 1.0, you can also pass a handler straight to subscribe!
+api.socket.subscribe('console', (event)=>{
+	event.data.messages.log // List of console.log output for tick
+})
+
+// More common examples
+api.socket.subscribe('cpu',(event)=>console.log('cpu',event.data))
+api.code.get('default').then(data=>console.log('code',data))
+api.code.set('default',{
+	main: 'module.exports.loop = function(){ ... }'
+})
+api.socket.subscribe('memory/stats',(event)=>{
+	console.log('stats',event.data)
+})
+api.socket.subscribe('memory/rooms.E0N0',(event)=>{
+	console.log('E0N0 Memory',event.data)
+})
 ```

docs/Endpoints.md

@@ -0,0 +1,236 @@
+Copied from [python-screeps](https://github.com/screepers/python-screeps/blob/master/docs/Endpoints.md)
+
+Start by sending a request to `auth/signin` with your e-mail address and
+password in a JSON object in the POST data. The response JSON object contains a
+token (a hex string); remember that value. Each time you make a request that
+requires authentication (the leaderboard and terrain ones, at least, don't),
+send the most recent token value as both the `X-Token` and `X-Username`
+headers. The response will contain a new token value in the `X-Token` header
+with which you should replace your saved token. (You can send the token on every
+request and just check for a new one in the response, so you don't have to know
+exactly which calls require authentication.)
+
+Example request parameters are given below, along with schemata for the server's
+responses.
+
+Memory and console endpoints are from
+[bzy-xyz](https://gist.github.com/bzy-xyz/9c4d8c9f9498a2d7983d).
+
+You can access the PTR by changing `screeps.com` to `screeps.com/ptr` in all URLs.
+
+# Enumeration values
+When an endpoint takes `interval` or `statName` as an argument, the valid values
+are the ones listed below.
+
+- interval: 8, 180, 1440
+- statName: creepsLost, creepsProduced, energyConstruction, energyControl, energyCreeps, energyHarvested
+
+# Authentication
+- [POST] `https://screeps.com/api/auth/signin`
+    - post data: `{ email, password }`
+    - response: `{ ok, token }`
+
+# Room information
+- `https://screeps.com/api/game/room-overview?interval=8&room=E1N8`
+    - `{ ok, owner: { username, badge: { type, color1, color2, color3, param, flip } }, stats: { energyHarvested: [ { value, endTime } ], energyConstruction: [ { value, endTime } ], energyCreeps: [ { value, endTime } ], energyControl: [ { value, endTime } ], creepsProduced: [ { value, endTime } ], creepsLost: [ { value, endTime } ] }, statsMax: { energy1440, energyCreeps1440, energy8, energyControl8, creepsLost180, energyHarvested8, energy180, energyConstruction180, creepsProduced8, energyControl1440, energyCreeps8, energyHarvested1440, creepsLost1440, energyConstruction1440, energyHarvested180, creepsProduced180, creepsProduced1440, energyCreeps180, energyControl180, energyConstruction8, creepsLost8 } }`
+
+- `https://screeps.com/api/game/room-terrain?room=E1N8`
+    - `{ ok, terrain: [ { room, x, y, type } ] }`
+    - `type` in each element of `terrain` can be "wall" or "swamp"
+
+- `https://screeps.com/api/game/room-terrain?room=E1N8&encoded=1`
+    - `{ ok, terrain: [ { _id, room, terrain, type } ] }`
+    - `terrain` is a string of digits, giving the terrain left-to-right and top-to-bottom
+    - 0: plain, 1: wall, 2: swamp, 3: also wall
+    - encoded argument can be anything non-empty
+
+- `https://screeps.com/api/game/room-status?room=E1N8`
+    - `{ _id, status, novice }`
+    - `status` can at least be "normal" or "out of borders"
+    - if the room is in a novice area, `novice` will contain the Unix timestamp of the end of the protection (otherwise it is absent)
+
+- `https://screeps.com/api/experimental/pvp?interval=50`
+    - `{ ok, time, rooms: [ { _id, lastPvpTime } ] }`
+    - `time` is the current server tick
+    - `_id` contains the room name for each room, and `lastPvpTime` contains the last tick pvp occurred
+    - if neither a valid `interval` nor a valid `start` argument is provided, the result of the call is still `ok`, but with an empty rooms array.
+
+- `https://screeps.com/api/experimental/pvp?start=14787157`
+    - `{ ok, time, rooms: [ { _id, lastPvpTime } ] }`
+
+# Market information
+
+- `https://screeps.com/api/game/market/orders-index`
+  - `{"ok":1,"list":[{"_id":"XUHO2","count":2}]}`
+  - `_id` is the resource type, and there will only be one of each type.
+  - `count` is the number of orders.
+
+  - `https://screeps.com/api/game/market/my-orders`
+    - `{ ok, list: [ { _id, created, user, active, type, amount, remainingAmount, resourceType, price, totalAmount, roomName } ] }`
+
+  - `https://screeps.com/api/game/market/orders?resourceType=Z`
+    - `{ ok, list: [ { _id, created, user, active, type, amount, remainingAmount, resourceType, price, totalAmount, roomName } ] }`
+    - `resourceType` is one of the RESOURCE_* constants.
+
+  - `https://screeps.com/api/user/money-history`
+    - `{"ok":1,"page":0,"list":[ { _id, date, tick, user, type, balance, change, market: {} } ] }`
+    - `page` used for pagination.
+    - `hasMore` is true if there are more pages to view.
+    - `market`
+      - New Order- `{ order: { type, resourceType, price, totalAmount, roomName } }`
+      - Extended Order- `{ extendOrder: { orderId, addAmount } }`
+      - Fulfilled Order- `{ resourceType, roomName, targetRoomName, price, npc, amount }`
+      - Price Change - `{ changeOrderPrice: { orderId, oldPrice, newPrice } }`
+
+# Leaderboard
+- `https://screeps.com/api/leaderboard/seasons`
+    - `{ ok, seasons: [ { _id, name, date } ] }`
+    - the `_id` returned here is used for the season name in the other leaderboard calls
+
+- `https://screeps.com/api/leaderboard/find?mode=world&season=2015-09&username=danny`
+    - `{ ok, _id, season, user, score, rank }`
+    - `user` (not `_id`) is the user's _id, as returned by `me` and `user/find`
+    - `rank` is 0-based
+
+- `https://screeps.com/api/leaderboard/find?mode=world&username=danny`
+    - `{ ok, list: [ _id, season, user, score, rank ] }`
+    - lists ranks in all seasons
+
+- `https://screeps.com/api/leaderboard/list?limit=10&mode=world&offset=10&season=2015-09`
+    - `{ ok, list: [ { _id, season, user, score, rank } ], count, users: { <user's _id>: { _id, username, badge: { type, color1, color2, color3, param, flip }, gcl } } }`
+
+# Messages
+- `https://screeps.com/api/user/messages/index`
+    - `{ ok, messages: [ { _id, message: { _id, user, respondent, date, type, text, unread } } ], users: { <user's _id>: { _id, username, badge: { type, color1, color2, color3, param, flip } } } }`
+
+- `https://screeps.com/api/user/messages/list?respondent=55605a6654db1fa952de8d90`
+    - `{ ok, messages: [ { _id, date, type, text, unread } ] }`
+
+- [POST] `https://screeps.com/api/user/messages/send`
+    - post data: `{ respondent, text }`
+    - `respondent` is the long _id of the user, not the username
+    - response: `{ ok }`
+
+- `https://screeps.com/api/user/messages/unread-count`
+    - `{ ok, count }`
+
+# User information
+- `https://screeps.com/api/auth/me`
+    - `{ ok, _id, email, username, cpu, badge: { type, color1, color2, color3, param, flip }, password, notifyPrefs: { sendOnline, errorsInterval, disabledOnMessages, disabled, interval }, gcl, credits, lastChargeTime, lastTweetTime, github: { id, username }, twitter: { username, followers_count } }`
+
+- `https://screeps.com/api/user/find?username=danny`
+    - `{ ok, user: { _id, username, badge: { type, color1, color2, color3, param, flip }, gcl } }`
+
+- `https://screeps.com/api/user/find?id=55c91dc66e36d62a6167e1b5`
+    - `{ ok, user: { _id, username, badge: { type, color1, color2, color3, param, flip }, gcl } }`
+
+- `https://screeps.com/api/user/overview?interval=1440&statName=energyControl`
+    - `{ ok, rooms: [ <room name> ], stats: { <room name>: [ { value, endTime } ] }, statsMax }`
+
+- `https://screeps.com/api/user/respawn-prohibited-rooms`
+    - `{ ok, rooms: [ <room name> ] }`
+
+- `https://screeps.com/api/user/world-status`
+    - `{ ok, status }`
+    - `status` is usually "normal"; it's unknown what else it can be
+
+- `https://screeps.com/api/user/world-start-room`
+    - `{ ok, room:  [ <room name> ] }`
+    - `room` is an array, but seems to always contain only one element
+
+- `https://screeps.com/api/xsolla/user`
+    - `{ ok, active }`
+    - `active` is the Unix timestamp of the end of your current subscribed time
+
+- [POST] `https://screeps.com/api/user/console`
+    - post data: `{ expression }`
+    - response: `{ ok, result: { ok, n }, ops: [ { user, expression, _id } ], insertedCount, insertedIds: [ <mongodb id> ] }`
+
+- `https://screeps.com/api/user/memory?path=flags.Flag1`
+    - `{ ok, data }`
+    - `data` is the string `gz:` followed by base64-encoded gzipped JSON encoding of the requested memory path
+    - the path may be empty or absent to retrieve all of Memory
+
+- [POST] `https://screeps.com/api/user/memory`
+    - post data: `{ path, value }`
+    - response: `{ ok, result: { ok, n }, ops: [ { user, expression, hidden } ], data, insertedCount, insertedIds }`
+
+- `https://screeps.com/api/user/memory-segment?segment=[0-99]`
+    - `{ okay, data }`
+    - response: `{ ok, data: '' }`
+
+- [POST ]`https://screeps.com/api/user/memory-segment`
+    - post data: `{ segment, data }`
+
+
+# Manipulating the game world
+- [POST] `https://screeps.com/api/game/gen-unique-object-name`
+    - post data: `{ type }`
+    - response: `{ ok, name }`
+    - `type` can be at least "flag" or "spawn"
+
+- [POST] `https://screeps.com/api/game/create-flag`
+    - post data: `{ room, x, y, name, color, secondaryColor }`
+    - response: `{ ok, result: { nModified, ok, upserted: [ { index, _id } ], n }, connection: { host, id, port } }`
+    - if the name is new, `result.upserted[0]._id` is the game id of the created flag
+    - if not, this moves the flag and the response does not contain the id (but the id doesn't change)
+    - `connection` looks like some internal MongoDB thing that is irrelevant to us
+
+- [POST] `https://screeps.com/api/game/change-flag`
+    - post data: `{ _id, room, x, y }`
+    - response: `{ ok, result: { nModified, ok, n }, connection: { host, id, port } }`
+
+- [POST] `https://screeps.com/api/game/change-flag-color`
+    - post data: `{ _id, color, secondaryColor }`
+    - response: `{ ok, result: { nModified, ok, n }, connection: { host, id, port } }`
+
+- [POST] `https://screeps.com/api/game/add-object-intent`
+    - post data: `{ _id, room, name, intent }`
+    - response: `{ ok, result: { nModified, ok, upserted: [ { index, _id } ], n }, connection: { host, id, port } }`
+    - `_id` is the game id of the object to affect (except for destroying structures), `room` is the name of the room it's in
+    - this method is used for a variety of actions, depending on the `name` and `intent` parameters
+        - remove flag: `name = "remove"`, `intent = {}`
+        - destroy structure: `_id = "room"`, `name = "destroyStructure"`, `intent = [ {id: <structure id>, roomName, <room name>, user: <user id>} ]`
+            - can destroy multiple structures at once
+        - suicide creep: `name = "suicide"`, `intent = {id: <creep id>}`
+        - unclaim controller: `name = "unclaim"`, `intent = {id: <controller id>}`
+             - intent can be an empty object for suicide and unclaim, but the web interface sends the id in it, as described
+        - remove construction site: `name = "remove"`, `intent = {}`
+
+- [POST] `https://screeps.com/api/game/set-notify-when-attacked`
+    - post data: `{ _id, enabled }`
+    - `enabled` is either `true` or `false` (literal values, not strings)
+    - response: `{ ok, result: { ok, nModified, n }, connection: { id, host, port } }`
+
+- [POST] `https://screeps.com/api/game/create-construction`
+    - post data: `{ room, structureType, x, y}`
+    - `structureType` is the same value as one of the in-game STRUCTURE_* constants ('road', 'spawn', etc.)
+    - `{ ok, result: { ok, n }, ops: [ { type, room, x, y, structureType, user, progress, progressTotal, _id } ], insertedCount, insertedIds }`
+
+# Other
+- `https://screeps.com/api/game/time`
+    - `{ ok, time }`
+
+- [GET/POST] `https://screeps.com/api/user/code`
+    - for pushing or pulling code, as documented at http://support.screeps.com/hc/en-us/articles/203022612
+
+- [POST] `https://screeps.com/api/game/map-stats`
+    - post data: `{ rooms: [ <room name> ], statName: "..."}`
+    - statName can be "owner0", "claim0", or a stat (see the enumeration above) followed by an interval
+    - if it is owner0 or claim0, there's no separate stat block in the response
+    - response: `{ ok, stats: { <room name>: { status, novice, own: { user, level }, <stat>: [ { user, value } ] } }, users: { <user's _id>: { _id, username, badge: { type, color1, color2, color3, param, flip } } } }`
+    - `status` and `novice` are as per the `room-status` call
+    - `level` can be 0 to indicate a reserved room
+
+- `https://screeps.com/room-history/E1N8/12340.json`
+    - `{ timestamp, room, base, ticks: { <time>: <tick update object> } }`
+    - the number in the URL is the tick to retrieve information for (from 5e5 ticks ago to about 50 ticks ago)
+        - note that the web interface only shows up to 3e5 ticks ago
+    - the tick must be a multiple of 20; the response includes information for the 20 ticks starting then
+    - for the first tick in the result, the tick update object maps from object ids to full object descriptions
+    - for later ticks, the update includes only changed attributes
+    - timestamp is milliseconds since the Unix epoch
+
+- [POST] `https://screeps.com/user/activate-ptr`
+    - `{ok, result: { ok, nModified, n }, connection: { id, host, port } }`
+	- only works on the PTR

examples/README.md

@@ -0,0 +1,3 @@
+# Examples
+
+Warning: These examples may be outdated and plain broken.

examples/console.js

@@ -1,5 +1,5 @@
 'use strict'
-const ScreepsAPI = require('../')
+const { ScreepsAPI } = require('../')
 // const auth = require('../auth')
 const readline = require('readline')
 const util = require('util')