Beef up the API docs.

git-svn-id: https://www.unprompted.com/svn/projects/tildefriends/trunk@4453 ed5197a5-7fde-0310-b194-c3ffbd925b24

apps/api/docs.js

@@ -0,0 +1,241 @@
+export const docs = {};
+
+docs.global = `# <span style="color: #aaf">App Globals</span>
+The following are functions and values exposed to all apps in their \`app.js\` or \`handler.js\`.  Most
+of these are asynchronous, returning a \`Promise\` that will be resolved when the call completes, unless
+noted otherwise.
+
+This is all a work in progess. These are liable to change without warning.  Feedback is welcome.
+
+The exposed functions in this API balance multiple competing needs:
+ * The surface area of the exposed API ought to be fairlyl minimal.  If something can be implemented entirely app-side, that is
+   generally preferred over building it into the core.
+ * Everything is built on this API.  Ideally the admin app, the SSB app, and the editor all use standard API exposed to all
+   apps, with appropriate permission guards in place making it so that only trusted apps do potentially destructive operations.
+   There will be some things here that aren't necessarily general use to support what's required.
+`;
+
+docs['core.user.credentials.session.name'] = `
+*String* The name of the authenticated user.
+`;
+
+docs['app.setDocument()'] = `
+Set the contents of the client &lt;iframe/&gt;.
+### Parameters
+ * *String* **html** The HTML contents.
+`;
+
+docs['ssb.sqlAsync()'] = `
+Run an SQL query against the sqlite database.
+### Parameters
+ * *String* **query** The sqlite query.
+ * *Array* **args** The query arguments to bind.
+ * *Function* **callback** Callback called for each row result.
+`;
+
+docs['ssb.appendMessageWithIdentity()'] = `
+Signs and stores a message in the SSB database.
+### Parameters
+ * *String* **id** The public key of an SSB identity owned by the authenticated user.
+ * *Object* **message** The unsigned message.
+`;
+
+docs['ssb.storeMessage()'] = `
+Verifies and stores a signed message in the SSB database.
+### Parameters
+ * *Object* **message** The valid, signed message to store.
+`;
+
+docs['ssb.blobStore()'] = `
+Store a blob in the SSB database.
+### Parameters
+ * *String*/*Uint8Array* **blob** The blob contents to store
+### Returns
+*String* The stored blob ID.
+`;
+
+docs['print()'] = `
+Log debug information both to the server's console and to the visiting user's browser console when possible.
+### Parameters
+ * **...** Whatever you want to log.  Will be joined with spaces.
+`;
+
+docs['database()'] = `
+Returns a database instance that is specific to the authenticated user and the given key.
+### Parameters
+ * *String* **key** The database key.
+### Returns
+ *Database* A database.
+`;
+
+docs['my_shared_database()'] = `
+Returns a database instance that is specific to the authenticated user and the given key.
+### Parameters
+ * *String* **package_name** The database package name.
+ * *String* **key** The database key.
+### Returns
+ *Database* A database.
+`;
+
+docs['shared_database()'] = `
+Returns a database instance that is shared between all users of the app, determined by its owner and app name.
+### Parameters
+ * *String* **key** The database key.
+### Returns
+ *Database* A database.
+`;
+
+docs['utf8Decode()'] =`
+Decode UTF-8 bytes to a string.
+
+Completes synchronously.
+### Parameters
+ * *Uint8Array* **value** The value to decode.
+### Returns
+*String* The value as a string.
+`;
+
+docs['utf8Encode()'] =`
+Encodes a string to UTF-8 bytes.
+
+Completes synchronously.
+### Parameters
+ * *String* **value** The value to encode.
+### Returns
+*Uint8Array* The encoded \`value\`.
+`;
+
+docs['sha1Digest()'] =`
+Calculates a SHA1 digest.
+
+Completes synchronously.
+### Parameters
+ * *String* **value** The value for which to calculate the digest.
+### Returns
+*String* The SHA1 digest of UTF-8 encoded \`value\`.
+`;
+
+docs['maskBytes()'] = `
+Masks bytes for WebSocket communication.
+
+Completes synchronously.
+### Parameters
+ * *Uint8Array* **bytes** The byte array of data to mask.
+ * *Uint32* **mask** The mask to apply.
+### Returns
+*Uint32Array* The masked bytes.
+`;
+
+docs['exit()'] = `
+Exits the app.  But why would you want to do that?
+
+Completes synchronously.
+### Parameters
+ * *Integer* **exit_code** System exit code.
+`;
+
+docs['version()'] = `
+Gets version information for the running server.
+### Returns
+*Object* Keys are things like \`name\` and \`number\` for the server itself and \`libuv\` and \`openssl\` for
+dependencies.  Values are *String* version numbers.
+`;
+
+docs['platform()'] = `
+Gets the host operating system platform of the running server.
+### Returns
+*String* The platform, one of \`windows\`, \`android\`, \`linux\`, or \`other\`.
+`;
+
+docs['getFile()'] = `
+Gets a file from the running app.
+### Parameters
+ * *String* **name** Name of the file to retrieve.
+### Returns
+*Uint8Array* The contents of a file from the app with the given name, or *undefined*.
+`;
+
+docs.database = `
+# <span style="color: #aaf">Database</span>
+Local-only storage is provided by a \`Database\` type representing a key-value store.
+`;
+
+docs['database.get()'] = `
+Gets a value from the database.
+### Parameters
+ * *String* **key** The key.
+### Returns
+*String* The value from the database or undefined if not found.
+`;
+
+docs['database.getAll()'] = `
+Gets all keys from the database.
+### Returns
+*Array* An array of *String* key names for all keys in the given database.
+`;
+
+docs['database.getLike()'] = `
+Gets all keys and values from the database matching a pattern.
+### Parameters
+ * *String* **pattern** An sqlite \`LIKE\` pattern to match keys against.
+### Returns
+*Object* An object whose keys are the database keys and values are the database values that match the given pattern.
+`;
+
+docs['database.set()'] = `
+Sets a value in the database, creating a new entry or replacing an existing entry.
+### Parameters
+ * *String* **key** The key.
+ * *String* **value** The value.
+`;
+
+docs['database.exchange()'] = `
+Performs an atomic compare and exchange operation, setting a value in the database only if its current value matches what is expected.
+### Parameters
+ * *String* **key** The key.
+ * *String* **expected** The expected value.
+ * *String* **value** The new value.
+ ### Returns
+ *Boolean* true if the value is now the given value.
+`;
+
+docs['database.remove()'] = `
+Removes an entry from the database if it exists.
+### Parameters
+ * *String* **key** The key.
+`;
+
+docs.tfrpc = `
+# <span style="color: #aaf">tfrpc</span>
+\`tfrpc.js\` is a small helper script that is available to be used to facilitate communication between parts of an application.
+
+\`tfrpc.js\` can be used to asynchronously make calls between the app in the browser and the app process on the server.
+
+From \`app.js\`:
+\`\`\`
+import * as tfrpc from '/tfrpc.js';
+\`\`\`
+
+
+From script running in the browser:
+\`\`\`
+import * as tfrpc from '/static/tfrpc.js';
+\`\`\`
+
+Either side can register or call functions, though they must be registered before they can be called.  Arguments and return
+values are ultimately serialized by means that attempt to preserve most JSON-serializable values as well as functions themselves.
+`;
+
+docs['tfrpc.register()'] = `
+Register a function, allowing it to be called remotely.
+### Parameters
+ * *Function* **function** The function to register.  Its name will be how it will be called.
+`;
+
+docs['tfrpc.rpc.*()'] = `
+Call a remote function.
+### Parameters
+ * **...** Parameters to pass to the function.
+### Returns
+The return value of the called function.
+`;