cory/tildefriends
4
5
Fork 1
Code Issues 29 Pull Requests 1 Actions Releases 26 Wiki Activity

api docs work in progress.

Browse Source 
git-svn-id: https://www.unprompted.com/svn/projects/tildefriends/trunk@4460 ed5197a5-7fde-0310-b194-c3ffbd925b24
This commit is contained in:
Cory McWilliams 2023-09-13 23:00:47 +00:00
parent d2485583fd
commit 15d0383349
2 changed files with 117 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
apps/api/app.js
View File

@ -27,17 +27,51 @@ function markdown(md) {
function document(api) {
let doc = markdown(docs.docs[api.split(' = ')[0]]);
return `
<a id="${api}"></a>
<a name="${api}"></a>
<h2 style="color: #aaf">${api}</h2>
<div>${doc}</div>
`;
}
app.setDocument(`<body style="color:#fff">
app.setDocument(`<head>
<base target="_top">
<style type="text/css">
a:link {
color: #268bd2;
}
a:visited {
color: #6c71c4;
}
a:hover {
color: #859900;
}
a:active {
color: #2aa198;
}
</style>
</head>
<body style="color:#fff">
${markdown(docs.docs.global)}
${[...treeify('', globalThis)].map(x => document(x)).join('\n')}
<a id="Database"></a>
${markdown(docs.docs.database)}
${['database.get()', 'database.set()', 'database.exchange()', 'database.remove()', 'database.getAll()', 'database.getLike()'].map(x => document(x)).join('\n')}
${markdown(docs.docs.tfrpc)}
${['tfrpc.register()', 'tfprc.rpc.*()'].map(x => document(x)).join('\n')}
${['tfrpc.register()', 'tfrpc.rpc.*()'].map(x => document(x)).join('\n')}
<script>
window.onload = function() {
console.log('load');
for (let tag of document.getElementsByTagName('a')) {
console.log(tag.href);
tag.onclick = function() {
document.getElementById(tag.href.split('#')[1]).scrollIntoView();
return false;
}
delete tag.href;
}
}
</script>
</body>`);

88
apps/api/docs.js
View File

@ -1,6 +1,15 @@
export const docs = {};
docs.global = `# <span style="color: #aaf">App Globals</span>
docs.global = `# Tilde Friends API Documentation
Welcome to the Tilde Friends API documentation.
* [App Globals](#App_Globals)
* [Database Interface](#Database)
* [Remote Procedure Calls](#tfrpc)
<a id="App_Globals"></a>
## <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.
@ -8,11 +17,14 @@ 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
* The surface area of the exposed API ought to be fairly 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.
If you are looking at the [Tilde Friends source code](https://www.tildefriends.net/~cory/releases/),
the vast majority of these are implemented in \`src/*.js.c\` files, and exposed to apps via \`core/core.js\`.
`;
docs['core.user.credentials.session.name'] = `
@ -54,6 +66,14 @@ Store a blob in the SSB database.
*String* The stored blob ID.
`;
docs['ssb.blobGet()'] = `
Fetches a blob from the database.
### Parameters
* *String* **blob_id** The blob identifier to fetch (\`&....sha256\`).
### Returns
*ArrayBuffer* The blob data.
`;
docs['print()'] = `
Log debug information both to the server's console and to the visiting user's browser console when possible.
### Parameters
@ -74,7 +94,7 @@ Returns a database instance that is specific to the authenticated user and the g
* *String* **package_name** The database package name.
* *String* **key** The database key.
### Returns
*Database* A database.
*Database* A database.
`;
docs['shared_database()'] = `
@ -82,10 +102,30 @@ Returns a database instance that is shared between all users of the app, determi
### Parameters
* *String* **key** The database key.
### Returns
*Database* A database.
*Database* A database.
`;
docs['utf8Decode()'] =`
docs['base64Decode()'] = `
Decode a base64 string to bytes.
Completes synchronously.
### Parameters
* *String* value The base64-encoded string.
### Returns
*Uint8Array* The decoded bytes.
`;
docs['base64Encode()'] = `
Encode bytes to a base64 string.
Completes synchronously.
### Parameters
* *Uint8Array* The bytes to encode.
### Returns
*String* The base64-encoded string.
`;
docs['utf8Decode()'] = `
Decode UTF-8 bytes to a string.
Completes synchronously.
@ -95,7 +135,7 @@ Completes synchronously.
*String* The value as a string.
`;
docs['utf8Encode()'] =`
docs['utf8Encode()'] = `
Encodes a string to UTF-8 bytes.
Completes synchronously.
@ -105,6 +145,37 @@ Completes synchronously.
*Uint8Array* The encoded \`value\`.
`;
docs['setTimeout()'] = `
Call a function after some delay.
### Parameters
* *Function* **callback** The function to call.
* *Number* **timeout** Number of milliseconds to wait before calling the callback function.
`;
docs['parseHttpRequest()'] = `
Parses an HTTP request.
### Parameters
* *Uint8Array* **request** The request data. Maybe be partial or contain extra data. The return value will
indicate when and where it is complete.
* *Number* **last_length** The length of the data passed on a previous attempt for the same request, or 0 initially.
### Returns
* *Integer* **-2** if the request is incomplete.
* *Integer* **-1** if the request could not be parsed.
* *Object* An object with **bytes_parsed**, **minor_version**, **path**, and **headers** fields on successful parse.
`;
docs['parseHttpResponse()'] = `
Parses an HTTP response.
### Parameters
* *Uint8Array* **response** The response data. Maybe be partial or contain extra data. The return value will
indicate when and where it is complete.
* *Number* **last_length** The length of the data passed on a previous attempt for the same response, or 0 initially.
### Returns
* *Integer* **-2** if the response is incomplete.
* *Integer* **-1** if the response could not be parsed.
* *Object* An object with **bytes_parsed**, **minor_version**, **status**, **message**, and **headers** fields on successful parse.
`;
docs['sha1Digest()'] =`
Calculates a SHA1 digest.
@ -206,10 +277,11 @@ Removes an entry from the database if it exists.
`;
docs.tfrpc = `
# <span style="color: #aaf">tfrpc</span>
# <span style="color: #aaf" id="tfrpc">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.
\`tfrpc.js\` can be used to asynchronously make calls between the app code running in a sandboxed iframe in the browser
and the app process on the server.
From \`app.js\`:
\`\`\`