@awesomate/sdk 0.9.0 → 0.11.0

package/README.md

@@ -146,6 +146,24 @@ 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.
+
+A conversation can also show who else has it open and who is typing:
+
+```ts
+const room = app.here(job.id, (people) => showWhoIsHere(people)); // [{ user, role, name, typing, assistant? }]
+messageBox.oninput = () => room.typing(true);   // sent at most every few seconds
+messageBox.onblur = () => room.typing(false);
+// later: room.leave();
+```
+
+Everyone else with that record open and their tab in front is listed once, and the app's
+assistant appears while it writes a reply. The hub checks this person may read the record, and
+keeps checking; a refusal goes to the optional third argument, `onError`. Nothing is stored.
+
 ### Staff find a customer
 
 People in an app read no contacts but their own, so by default staff cannot put a job under a

package/dist/index.d.ts

@@ -418,6 +418,26 @@ export interface LiveChange<R> {
     /** Ids that left the list. */
     removes: string[];
 }
+/** Someone else with the same record open (app.here), as the hub sends them. */
+export interface HerePerson {
+    /** Their app user id, or 'assistant' for the app's AI assistant. */
+    user: string;
+    role: string;
+    /** Their first name from the account's Contacts, or null. */
+    name: string | null;
+    typing: boolean;
+    /** The app's AI assistant, writing a reply. */
+    assistant?: true;
+}
+export interface HereHandle {
+    /**
+     * Say this person is typing (call it on each keystroke: it sends at most every few seconds) or has
+     * stopped (on send or blur). Without another call, typing ends on its own after a few seconds.
+     */
+    typing(on: boolean): void;
+    /** Close the record: the others stop seeing this person on it. */
+    leave(): void;
+}
 export interface LiveHandlers<R> {
     /** Called with the whole list, in the query's order, at first and after every change. */
     onRows: (rows: R[], change: LiveChange<R> | null) => void;
@@ -516,6 +536,15 @@ export declare class AwesomateAppClient {
      * a fresh snapshot when it does. Returns stop().
      */
     live<K extends KindName, S extends keyof RowOf<K> = keyof RowOf<K>>(kind: K, options: Omit<QueryOptions<RowOf<K>, S>, 'after'>, handlers: LiveHandlers<Pick<RowOf<K>, S>> | ((rows: Array<Pick<RowOf<K>, S>>, change: LiveChange<Pick<RowOf<K>, S>> | null) => void)): () => void;
+    /** The one live connection behind live() and here(), made on first use. */
+    private liveSocket;
+    /**
+     * Open a record (a job's conversation) for who-is-here: onPeople gets everyone else who has it
+     * open with their tab in front, and who is typing, at first and on every change; the app's
+     * assistant appears while it writes a reply. The hub checks this person may read the record, and
+     * keeps checking; onError hears a refusal. Shares the one live connection. Returns typing() and leave().
+     */
+    here(recordId: string, onPeople: (people: HerePerson[]) => void, onError?: (err: AwesomateError) => void): HereHandle;
 }
 export declare function createAppClient(options: AppClientOptions): AwesomateAppClient;
 export declare function createClient(options: ClientOptions): AwesomateClient;

package/dist/index.js

@@ -539,20 +539,38 @@ export class AwesomateAppClient {
      */
     live(kind, options, handlers) {
         const h = typeof handlers === 'function' ? { onRows: handlers } : handlers;
-        this.socket ??= new LiveSocket({
+        return this.liveSocket().add({ kind, ...options }, h);
+    }
+    /** The one live connection behind live() and here(), made on first use. */
+    liveSocket() {
+        return this.socket ??= new LiveSocket({
             url: `${this.base.replace(/^http/, 'ws')}/api/sdk/v1/socket`,
             WebSocket: this.opts.WebSocket ?? globalThis.WebSocket,
             session: () => this.current(),
             refresh: async () => { const s = await this.load(); return s ? this.refresh(s) : null; },
         });
-        return this.socket.add({ kind, ...options }, h);
+    }
+    /**
+     * Open a record (a job's conversation) for who-is-here: onPeople gets everyone else who has it
+     * open with their tab in front, and who is typing, at first and on every change; the app's
+     * assistant appears while it writes a reply. The hub checks this person may read the record, and
+     * keeps checking; onError hears a refusal. Shares the one live connection. Returns typing() and leave().
+     */
+    here(recordId, onPeople, onError) {
+        return this.liveSocket().join(recordId, onPeople, onError);
     }
 }
+/** A page saying "still typing" more often than this is not sent: the hub keeps it for six seconds. */
+const TYPING_RESEND_MS = 2_500;
 /** Timers must never keep a Node process (a test, a server-side render) alive; browsers have no unref. */
 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;
@@ -569,6 +587,50 @@ 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' });
+    }
+    /** Records open with here(): who else is on them goes to onPeople. */
+    rooms = new Map();
+    get wanted() {
+        return this.entries.size > 0 || this.rooms.size > 0;
+    }
+    join(id, onPeople, onError) {
+        const room = { onPeople, onError, typingSentAt: 0 };
+        this.rooms.set(id, room);
+        if (this.ready)
+            this.send({ type: 'here', id, on: true });
+        else if (!this.ws && !this.connecting)
+            void this.connect();
+        return {
+            typing: (on) => {
+                if (this.rooms.get(id) !== room || !this.ready)
+                    return;
+                const now = Date.now();
+                if (on && now - room.typingSentAt < TYPING_RESEND_MS)
+                    return;
+                if (!on && !room.typingSentAt)
+                    return;
+                room.typingSentAt = on ? now : 0;
+                this.send({ type: 'typing', id, on });
+            },
+            leave: () => {
+                if (this.rooms.get(id) !== room)
+                    return;
+                this.rooms.delete(id);
+                if (this.ready)
+                    this.send({ type: 'here', id, on: false });
+                if (!this.wanted)
+                    this.shut();
+            },
+        };
     }
     add(spec, handlers) {
         const id = `l${++this.seq}`;
@@ -582,7 +644,7 @@ class LiveSocket {
                 return;
             if (this.ready)
                 this.send({ type: 'unsub', id });
-            if (!this.entries.size)
+            if (!this.wanted)
                 this.shut();
         };
     }
@@ -591,7 +653,7 @@ class LiveSocket {
             this.ws.send(JSON.stringify(f));
     }
     async connect() {
-        if (this.stopped || this.ws || this.connecting || !this.entries.size)
+        if (this.stopped || this.ws || this.connecting || !this.wanted)
             return;
         if (!this.o.WebSocket) {
             this.failAll(new AwesomateError('unavailable', 'No WebSocket here: pass createAppClient({ WebSocket }).', 0));
@@ -609,7 +671,7 @@ class LiveSocket {
             this.failAll(new AwesomateError('unauthenticated', 'Sign in first.', 401));
             return;
         }
-        if (this.stopped || this.ws || !this.entries.size)
+        if (this.stopped || this.ws || !this.wanted)
             return;
         this.scheduleRefresh(session);
         const ws = new this.o.WebSocket(this.o.url);
@@ -632,9 +694,30 @@ class LiveSocket {
             this.attempt = 0;
             for (const [id, e] of this.entries)
                 this.send({ type: 'sub', id, spec: e.spec });
+            this.sendPresence();
+            for (const [id, room] of this.rooms) {
+                room.typingSentAt = 0;
+                this.send({ type: 'here', id, on: true });
+            }
             this.pinger = unref(setInterval(() => this.send({ type: 'ping' }), 25_000));
             return;
         }
+        if (f.type === 'people' && typeof f.id === 'string') {
+            this.rooms.get(f.id)?.onPeople(Array.isArray(f.people) ? f.people : []);
+            return;
+        }
+        if (f.type === 'error' && typeof f.id === 'string' && f.id.startsWith('here:')) {
+            const id = f.id.slice(5);
+            const room = this.rooms.get(id);
+            if (!room)
+                return;
+            this.rooms.delete(id);
+            const code = ERROR_CODES.includes(String(f.code)) ? f.code : 'unavailable';
+            room.onError?.(new AwesomateError(code, String(f.message ?? 'Refused.'), 0, undefined, String(f.code)));
+            if (!this.wanted)
+                this.shut();
+            return;
+        }
         const e = typeof f.id === 'string' ? this.entries.get(f.id) : undefined;
         if (f.type === 'error') {
             const code = ERROR_CODES.includes(String(f.code)) ? f.code : 'unavailable';
@@ -699,7 +782,8 @@ class LiveSocket {
         if (this.refresher)
             clearTimeout(this.refresher);
         const ms = Math.max(5_000, s.expires_at - Date.now() - 60_000);
-        this.refresher = unref(setTimeout(() => { if (this.entries.size)
+        // A socket kept open only by here() needs a fresh token too, or the hub closes it at expiry.
+        this.refresher = unref(setTimeout(() => { if (this.wanted)
             void this.o.refresh(); }, ms));
     }
     async closed(ws, code) {
@@ -710,7 +794,7 @@ class LiveSocket {
         if (this.pinger)
             clearInterval(this.pinger);
         this.pinger = null;
-        if (this.stopped || !this.entries.size)
+        if (this.stopped || !this.wanted)
             return;
         if (code === 4401) {
             // Refused as unauthenticated: one refresh; if that is refused too, the person is signed out.
@@ -725,9 +809,13 @@ class LiveSocket {
     }
     failAll(err) {
         const all = [...this.entries.values()];
+        const rooms = [...this.rooms.values()];
         this.entries.clear();
+        this.rooms.clear();
         for (const e of all)
             e.handlers.onError?.(err);
+        for (const r of rooms)
+            r.onError?.(err);
         this.shut();
     }
     shut() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/sdk",
-  "version": "0.9.0",
+  "version": "0.11.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",