@awesomate/sdk 0.8.0 → 0.10.0

package/README.md

@@ -146,6 +146,11 @@ and takes a fresh copy when it does. Up to 200 rows a list and 20 lists a connec
 `{ onRows, onError }` to hear about a list the server refused (a column that does not exist).
 Outside a browser, give it a WebSocket: `createAppClient({ publishableKey, WebSocket })`.
 
+While a list is open in a browser, the connection also tells the hub whether the tab is in front.
+If the account switched on reply emails, someone looking at the app isn't emailed about a reply,
+but a tab left open in the background doesn't count as looking, and closing the last one counts as
+leaving straight away.
+
 ### Staff find a customer
 
 People in an app read no contacts but their own, so by default staff cannot put a job under a
@@ -160,6 +165,22 @@ await app.write('job', { title: 'Gutters' }, { links: { customer: jo.id } });
 
 Name, email and phone only, and nothing the owner marked sensitive. Anyone else is refused.
 
+An attribute can also be visible to some roles only (`awesomate_crm_kinds`, `set_visibility`, for
+example a cost only `staff` see). For everyone else it comes back `null` and a write that sets it
+is refused, whatever the app asks for.
+
+Some things a customer should do without being able to edit the record: accept their quote, say.
+Save it as a write recipe and open it to their role (`awesomate_crm_recipes`, `run_by`, Pro and
+above), then:
+
+```ts
+await app.call('accept_quote', { job: job.id });
+```
+
+The database lets them do exactly the recipe's steps: only its params take their values, every
+other value is fixed, and an existing record must be one they can already read. A recipe not
+opened to their role is "not found".
+
 The rules are kept in your own database, which applies them to every read and write, so a mistake
 in the app cannot show anyone more than their role allows. A disabled person is refused on their
 next call. Sessions are kept in `localStorage`; in a Capacitor app pass `storage` (Preferences) and

package/dist/index.d.ts

@@ -492,6 +492,13 @@ export declare class AwesomateAppClient {
     /** Create a record (returns its id) or change one with options.id, inside the kind's write rule for this user. */
     write<K extends KindName>(kind: K, data: Partial<RowOf<K>> | Record<string, unknown>, options?: WriteOptions): Promise<string>;
     archive<K extends KindName>(kind: K, id: string): Promise<void>;
+    /**
+     * Run a recipe the account opened to this person's role: "accept this quote", something their
+     * write rule would not let them do by hand. Every step commits or none does; a recipe they may
+     * not run reads as not found. Never retried once sent: a write that may have landed is not safe
+     * to send twice (a refused sign-in is, and is retried after a refresh like every data call).
+     */
+    call<R extends RecipeName>(recipe: R, args?: ArgsOf<R>): Promise<RecipeResult>;
     /**
      * Customers by name or email (two characters or more), or by id, so staff can find one and put
      * a record under them. Only for a role the account lets look customers up in this app; anyone

package/dist/index.js

@@ -514,6 +514,15 @@ export class AwesomateAppClient {
     async archive(kind, id) {
         await this.data('POST', '/call', { fn: 'archive_record', args: { kind, id } });
     }
+    /**
+     * Run a recipe the account opened to this person's role: "accept this quote", something their
+     * write rule would not let them do by hand. Every step commits or none does; a recipe they may
+     * not run reads as not found. Never retried once sent: a write that may have landed is not safe
+     * to send twice (a refused sign-in is, and is retried after a refresh like every data call).
+     */
+    async call(recipe, args = {}) {
+        return (await this.data('POST', '/call', { fn: recipe, args })).result;
+    }
     /**
      * Customers by name or email (two characters or more), or by id, so staff can find one and put
      * a record under them. Only for a role the account lets look customers up in this app; anyone
@@ -544,6 +553,10 @@ function unref(t) {
     t.unref?.();
     return t;
 }
+/** The page's document, when there is one: the part live() reads to say whether the tab is in front. */
+function pageDocument() {
+    return globalThis.document;
+}
 /** The one WebSocket behind live(). */
 class LiveSocket {
     o;
@@ -560,6 +573,15 @@ class LiveSocket {
     connecting = false;
     constructor(o) {
         this.o = o;
+        // Reply emails wait only while one of the person's tabs is in front, so the hub hears when this
+        // one goes to the back or comes forward. Outside a browser there is no tab, and nothing is sent.
+        pageDocument()?.addEventListener?.('visibilitychange', () => this.sendPresence());
+    }
+    /** Whether this tab is in front, to the hub (from 0.10.0; an older hub ignores the frame). */
+    sendPresence() {
+        const d = pageDocument();
+        if (this.ready && typeof d?.visibilityState === 'string')
+            this.send({ type: 'presence', visible: d.visibilityState === 'visible' });
     }
     add(spec, handlers) {
         const id = `l${++this.seq}`;
@@ -623,6 +645,7 @@ class LiveSocket {
             this.attempt = 0;
             for (const [id, e] of this.entries)
                 this.send({ type: 'sub', id, spec: e.spec });
+            this.sendPresence();
             this.pinger = unref(setInterval(() => this.send({ type: 'ping' }), 25_000));
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Your own Awesomate data from Node and the browser: query contacts and app data with generated types, and sign your app's own users in",
   "license": "MIT",
   "type": "module",