@awesomate/sdk 0.4.0 → 0.5.0

package/README.md

@@ -104,6 +104,21 @@ app.auth.onChange((u) => render(u));
 await app.auth.signOut();
 ```
 
+### Lists that keep themselves current
+
+```ts
+const stop = app.live('job', { orderBy: ['created_at', 'desc'], limit: 50 }, (rows) => render(rows));
+// later: stop();
+```
+
+`live()` calls you with the whole list at first and again whenever a row in it is added, changed,
+removed, or stops being one this person may read (a job moved to another customer leaves their
+list, with its memos). Changes made anywhere reach the list: in this app, by your team in Claude
+Code, by an n8n workflow. One connection serves every list on the client; it reconnects by itself
+and takes a fresh copy when it does. Up to 200 rows a list and 20 lists a connection. Pass
+`{ 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 })`.
+
 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

@@ -15,13 +15,14 @@
  *   await app.auth.signInWithLink(email, { redirectTo: `${location.origin}/signed-in` });
  *   await app.auth.completeSignIn();               // on /signed-in
  *   const { rows } = await app.query('job', {});    // their jobs only
+ *   const stop = app.live('job', {}, (rows) => render(rows)); // and kept current as they change
  *
  * The account's token (a hosting PAT with crm:read) is a secret: use it on a server, never in a
  * browser. End-user sign-in for browser apps comes in a later version. Reading and running saved
  * queries works on every plan; writing app data (kinds, records, saved queries, recipes) needs
  * crm:write, Support Plus and above.
  */
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.5.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -126,7 +127,8 @@ export interface Page<R> {
     };
     asAt: string;
 }
-export type ErrorCode = 'unauthenticated' | 'forbidden' | 'not_found' | 'validation' | 'consent_blocked' | 'rate_limited' | 'conflict' | 'unavailable';
+declare const ERROR_CODES: readonly ["unauthenticated", "forbidden", "not_found", "validation", "consent_blocked", "rate_limited", "conflict", "unavailable"];
+export type ErrorCode = (typeof ERROR_CODES)[number];
 export declare class AwesomateError extends Error {
     readonly code: ErrorCode;
     readonly status: number;
@@ -371,6 +373,37 @@ export interface AppClientOptions {
     storage?: SessionStorageLike;
     /** Default: one per publishable key. */
     storageKey?: string;
+    /** For live(): the WebSocket class. Default: the browser's (and Node 22's) global WebSocket. */
+    WebSocket?: WebSocketLike;
+}
+/** The part of the WebSocket API live() uses: the browser's, Node 22's, or the ws package's. */
+export interface WebSocketLike {
+    new (url: string): {
+        readyState: number;
+        send(data: string): void;
+        close(code?: number, reason?: string): void;
+        onopen: ((ev: unknown) => void) | null;
+        onmessage: ((ev: {
+            data: unknown;
+        }) => void) | null;
+        onclose: ((ev: {
+            code: number;
+            reason: string;
+        }) => void) | null;
+        onerror: ((ev: unknown) => void) | null;
+    };
+}
+export interface LiveChange<R> {
+    /** Rows that are new or changed since the last call. */
+    upserts: R[];
+    /** Ids that left the list. */
+    removes: string[];
+}
+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;
+    /** A refusal for this list (a column that does not exist, too many lists); the list stops. */
+    onError?: (err: AwesomateError) => void;
 }
 /** The sign-in token a link carries, from a URL's fragment (#awesomate_token=...), or null. */
 export declare function signInTokenFrom(url: string): string | null;
@@ -383,6 +416,7 @@ export declare class AwesomateAppClient {
     private session;
     private refreshing;
     private readonly listeners;
+    private socket;
     constructor(opts: AppClientOptions);
     readonly auth: {
         /** Email a sign-in link. The answer is the same whether or not the address can sign in. */
@@ -426,6 +460,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>;
+    /**
+     * A list kept current: onRows gets the whole list (up to 200 rows, the query's order) at first
+     * and again whenever a row in it is added, changed, removed, or stops being one this person may
+     * read. One connection serves every live list on this client; it reconnects by itself and takes
+     * 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;
 }
 export declare function createAppClient(options: AppClientOptions): AwesomateAppClient;
 export declare function createClient(options: ClientOptions): AwesomateClient;

package/dist/index.js

@@ -15,14 +15,16 @@
  *   await app.auth.signInWithLink(email, { redirectTo: `${location.origin}/signed-in` });
  *   await app.auth.completeSignIn();               // on /signed-in
  *   const { rows } = await app.query('job', {});    // their jobs only
+ *   const stop = app.live('job', {}, (rows) => render(rows)); // and kept current as they change
  *
  * The account's token (a hosting PAT with crm:read) is a secret: use it on a server, never in a
  * browser. End-user sign-in for browser apps comes in a later version. Reading and running saved
  * queries works on every plan; writing app data (kinds, records, saved queries, recipes) needs
  * crm:write, Support Plus and above.
  */
-export const VERSION = '0.4.0';
+export const VERSION = '0.5.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
+const ERROR_CODES = ['unauthenticated', 'forbidden', 'not_found', 'validation', 'consent_blocked', 'rate_limited', 'conflict', 'unavailable'];
 export class AwesomateError extends Error {
     code;
     status;
@@ -231,6 +233,7 @@ export class AwesomateAppClient {
     session;
     refreshing = null;
     listeners = new Set();
+    socket = null;
     constructor(opts) {
         this.opts = opts;
         if (!opts?.publishableKey?.startsWith('pk_'))
@@ -323,6 +326,7 @@ export class AwesomateAppClient {
         await this.storage.setItem(this.key, JSON.stringify(s));
         for (const l of this.listeners)
             l(s.user);
+        this.socket?.tokenChanged(s);
         return s;
     }
     async clear() {
@@ -332,6 +336,8 @@ export class AwesomateAppClient {
         if (had)
             for (const l of this.listeners)
                 l(null);
+        this.socket?.signedOut();
+        this.socket = null;
     }
     /** A session whose access token has at least half a minute left, refreshing if not. */
     async current() {
@@ -423,6 +429,204 @@ export class AwesomateAppClient {
     async archive(kind, id) {
         await this.data('POST', '/call', { fn: 'archive_record', args: { kind, id } });
     }
+    /**
+     * A list kept current: onRows gets the whole list (up to 200 rows, the query's order) at first
+     * and again whenever a row in it is added, changed, removed, or stops being one this person may
+     * read. One connection serves every live list on this client; it reconnects by itself and takes
+     * a fresh snapshot when it does. Returns stop().
+     */
+    live(kind, options, handlers) {
+        const h = typeof handlers === 'function' ? { onRows: handlers } : handlers;
+        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);
+    }
+}
+/** 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 one WebSocket behind live(). */
+class LiveSocket {
+    o;
+    ws = null;
+    ready = false;
+    entries = new Map();
+    seq = 0;
+    attempt = 0;
+    pinger = null;
+    refresher = null;
+    retry = null;
+    stopped = false;
+    /** One connection attempt at a time: two lists added together share it. */
+    connecting = false;
+    constructor(o) {
+        this.o = o;
+    }
+    add(spec, handlers) {
+        const id = `l${++this.seq}`;
+        this.entries.set(id, { spec, handlers, rows: new Map(), order: [] });
+        if (this.ready)
+            this.send({ type: 'sub', id, spec });
+        else if (!this.ws && !this.connecting)
+            void this.connect();
+        return () => {
+            if (!this.entries.delete(id))
+                return;
+            if (this.ready)
+                this.send({ type: 'unsub', id });
+            if (!this.entries.size)
+                this.shut();
+        };
+    }
+    send(f) {
+        if (this.ws && this.ws.readyState === 1)
+            this.ws.send(JSON.stringify(f));
+    }
+    async connect() {
+        if (this.stopped || this.ws || this.connecting || !this.entries.size)
+            return;
+        if (!this.o.WebSocket) {
+            this.failAll(new AwesomateError('unavailable', 'No WebSocket here: pass createAppClient({ WebSocket }).', 0));
+            return;
+        }
+        this.connecting = true;
+        let session;
+        try {
+            session = await this.o.session();
+        }
+        finally {
+            this.connecting = false;
+        }
+        if (!session) {
+            this.failAll(new AwesomateError('unauthenticated', 'Sign in first.', 401));
+            return;
+        }
+        if (this.stopped || this.ws || !this.entries.size)
+            return;
+        this.scheduleRefresh(session);
+        const ws = new this.o.WebSocket(this.o.url);
+        this.ws = ws;
+        ws.onopen = () => ws.send(JSON.stringify({ type: 'hello', token: session.access_token }));
+        ws.onmessage = (ev) => this.frame(String(ev.data));
+        ws.onclose = (ev) => void this.closed(ws, ev.code);
+        ws.onerror = () => undefined;
+    }
+    frame(raw) {
+        let f;
+        try {
+            f = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (f.type === 'ready') {
+            this.ready = true;
+            this.attempt = 0;
+            for (const [id, e] of this.entries)
+                this.send({ type: 'sub', id, spec: e.spec });
+            this.pinger = unref(setInterval(() => this.send({ type: 'ping' }), 25_000));
+            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';
+            const err = new AwesomateError(code, String(f.message ?? 'Refused.'), 0, typeof f.field === 'string' ? f.field : undefined, String(f.code));
+            if (e && typeof f.id === 'string') {
+                this.entries.delete(f.id);
+                e.handlers.onError?.(err);
+            }
+            return;
+        }
+        if (!e)
+            return;
+        const order = Array.isArray(f.order) ? f.order.map(String) : [];
+        if (f.type === 'snapshot') {
+            e.rows = new Map((f.rows ?? []).map((r) => [String(r.id), r]));
+            e.order = order;
+            e.handlers.onRows(order.map((id) => e.rows.get(id)).filter(Boolean), null);
+        }
+        else if (f.type === 'change') {
+            const upserts = f.upserts ?? [];
+            const removes = (f.removes ?? []).map(String);
+            for (const r of upserts)
+                e.rows.set(String(r.id), r);
+            for (const id of removes)
+                e.rows.delete(id);
+            e.order = order;
+            e.handlers.onRows(order.map((id) => e.rows.get(id)).filter(Boolean), { upserts, removes });
+        }
+    }
+    /** A refreshed session: the open socket carries on as the same person with the new token. */
+    tokenChanged(s) {
+        if (this.ready)
+            this.send({ type: 'token', token: s.access_token });
+        this.scheduleRefresh(s);
+    }
+    /** Keep the socket's token fresh even when the app makes no other calls. */
+    scheduleRefresh(s) {
+        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)
+            void this.o.refresh(); }, ms));
+    }
+    async closed(ws, code) {
+        if (this.ws !== ws)
+            return;
+        this.ws = null;
+        this.ready = false;
+        if (this.pinger)
+            clearInterval(this.pinger);
+        this.pinger = null;
+        if (this.stopped || !this.entries.size)
+            return;
+        if (code === 4401) {
+            // Refused as unauthenticated: one refresh; if that is refused too, the person is signed out.
+            const s = await this.o.refresh().catch(() => null);
+            if (!s)
+                return this.failAll(new AwesomateError('unauthenticated', 'Sign in again.', 401));
+        }
+        if (code === 4403)
+            return this.failAll(new AwesomateError('forbidden', 'Live updates are not available for this app here.', 403));
+        const wait = Math.min(30_000, 1000 * 2 ** this.attempt++) * (code === 4429 ? 4 : 1);
+        this.retry = unref(setTimeout(() => void this.connect(), wait));
+    }
+    failAll(err) {
+        const all = [...this.entries.values()];
+        this.entries.clear();
+        for (const e of all)
+            e.handlers.onError?.(err);
+        this.shut();
+    }
+    shut() {
+        if (this.retry)
+            clearTimeout(this.retry);
+        if (this.refresher)
+            clearTimeout(this.refresher);
+        if (this.pinger)
+            clearInterval(this.pinger);
+        this.retry = this.refresher = this.pinger = null;
+        const ws = this.ws;
+        this.ws = null;
+        this.ready = false;
+        if (ws && ws.readyState <= 1) {
+            try {
+                ws.send(JSON.stringify({ type: 'bye' }));
+            }
+            catch { /* closing */ }
+            ws.close(1000, 'bye');
+        }
+    }
+    signedOut() {
+        this.stopped = true;
+        this.failAll(new AwesomateError('unauthenticated', 'Signed out.', 401));
+    }
 }
 export function createAppClient(options) {
     return new AwesomateAppClient(options);

package/package.json

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