tildefriends/apps/api/docs.js

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.
`;