@awesomate/sdk 0.3.0 → 0.5.0

package/README.md

@@ -77,6 +77,52 @@ Every failure is an `AwesomateError` with a `code`: `unauthenticated`, `forbidde
 ## Keep the token on a server
 
 The token is your account's hosting token. Use it in a server, a script or a scheduled job, never
-in a browser. Sign-in for your own app's users comes in a later version.
+in a browser. For a browser, sign your app's own users in (below).
+
+## Your app's users sign in (Pro and above)
+
+Set the app up first (Claude Code: `awesomate_crm_apps`): its name, the origins it runs on, and
+whether anyone may sign up or only people you add. That gives you a publishable key, which is not a
+secret. Then say who may read and change each kind (`awesomate_crm_kinds`, `set_access`), for
+example members read jobs whose customer is them and the memos on those jobs.
+
+```ts
+import { createAppClient } from '@awesomate/sdk';
+
+const app = createAppClient({ publishableKey: 'pk_...' });
+
+// The sign-in page: an email link, no password. The answer is the same for any address.
+await app.auth.signInWithLink(email, { redirectTo: `${location.origin}/signed-in` });
+
+// /signed-in: exchanges the link for a session and clears it from the address bar.
+const user = await app.auth.completeSignIn();
+
+// Everywhere else: the same calls as the server client, as this person.
+const { rows } = await app.query('job', { orderBy: ['created_at', 'desc'] });
+await app.write('forum_post', { body: 'Booked for Tuesday' }, { links: { job: rows[0].id } });
+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
+call `completeSignIn(url)` from the deep link that opened the app. Your own server can verify
+`await app.auth.accessToken()` against `https://hub.awesomate.ai/api/sdk/v1/jwks.json`.
 
 MIT licence.

package/dist/index.d.ts

@@ -9,12 +9,20 @@
  *   const open = await db.run('open_jobs_in', { suburb: 'Carindale' }); // a saved query, by name
  *   await db.call('log_visit', { customer, title: 'Possum in the roof' }); // a write recipe, one transaction
  *
+ * In the browser, an app's own users sign in by email link and read only what the account's
+ * access rules let them (Pro and above):
+ *   const app = createAppClient({ publishableKey: 'pk_...' });
+ *   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.3.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 {
 }
@@ -119,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;
@@ -342,5 +351,123 @@ export interface RecipeResult {
     /** Every record the recipe wrote or archived, in step order. */
     records: string[];
 }
+/** Where a session is kept: localStorage, Capacitor Preferences, or anything with these three. */
+export interface SessionStorageLike {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+export interface AppUser {
+    id: string;
+    email: string;
+    /** owner, staff, member or one of the account's own; the database re-reads it on every call */
+    role: string;
+    contact_id: string | null;
+}
+export interface AppClientOptions {
+    /** The app's publishable key (pk_...). Not a secret: it belongs in browser code. */
+    publishableKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /** Default: localStorage in a browser, memory elsewhere. In Capacitor, pass Preferences. */
+    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;
+export declare class AwesomateAppClient {
+    private readonly opts;
+    private readonly base;
+    private readonly doFetch;
+    private readonly storage;
+    private readonly key;
+    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. */
+        signInWithLink: (email: string, options: {
+            redirectTo: string;
+        }) => Promise<{
+            sent: boolean;
+            message: string;
+        }>;
+        /**
+         * Finish signing in from the link: the current page's address by default, or a URL a deep link
+         * opened (Capacitor). Returns the user, or null when the address carries no sign-in. The
+         * token is removed from the browser's address bar.
+         */
+        completeSignIn: (url?: string) => Promise<AppUser | null>;
+        /** The signed-in user, or null. */
+        user: () => Promise<AppUser | null>;
+        /** Called with the user on sign-in and null on sign-out (including a refresh that was refused). */
+        onChange: (listener: (user: AppUser | null) => void) => (() => void);
+        signOut: () => Promise<void>;
+        /** A current access token, for the app's own server to verify against the JWKS. */
+        accessToken: () => Promise<string | null>;
+    };
+    private request;
+    private read;
+    private load;
+    private save;
+    private clear;
+    /** A session whose access token has at least half a minute left, refreshing if not. */
+    private current;
+    /** One refresh at a time per client; a refresh another tab already did is picked up from storage. */
+    private refresh;
+    /** A data call as the signed-in user: refused once (a disable, a key change), it refreshes and tries again; refused twice, it signs out. */
+    private data;
+    query<K extends KindName, S extends keyof RowOf<K> = keyof RowOf<K>>(kind: K, options?: QueryOptions<RowOf<K>, S>): Promise<Omit<Page<Pick<RowOf<K>, S>>, 'hidden'>>;
+    queryAll<K extends KindName, S extends keyof RowOf<K> = keyof RowOf<K>>(kind: K, options?: Omit<QueryOptions<RowOf<K>, S>, 'after'> & {
+        maxRows?: number;
+    }): AsyncGenerator<Pick<RowOf<K>, S>>;
+    /** One record by id, or null when there is none this user may read. */
+    get<K extends KindName>(kind: K, id: string): Promise<RowOf<K> | null>;
+    /** 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;
 export {};

package/dist/index.js

@@ -9,13 +9,22 @@
  *   const open = await db.run('open_jobs_in', { suburb: 'Carindale' }); // a saved query, by name
  *   await db.call('log_visit', { customer, title: 'Possum in the roof' }); // a write recipe, one transaction
  *
+ * In the browser, an app's own users sign in by email link and read only what the account's
+ * access rules let them (Pro and above):
+ *   const app = createAppClient({ publishableKey: 'pk_...' });
+ *   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.3.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;
@@ -194,6 +203,434 @@ export class AwesomateClient {
         return this.request('POST', '/api/my-crm/v1/data/query', request);
     }
 }
+function memoryStorage() {
+    const m = new Map();
+    return { getItem: (k) => m.get(k) ?? null, setItem: (k, v) => { m.set(k, v); }, removeItem: (k) => { m.delete(k); } };
+}
+function browserStorage() {
+    try {
+        if (typeof localStorage !== 'undefined') {
+            localStorage.getItem('awesomate.probe');
+            return localStorage;
+        }
+    }
+    catch { /* storage blocked: a private window, a sandboxed frame */ }
+    return memoryStorage();
+}
+/** The sign-in token a link carries, from a URL's fragment (#awesomate_token=...), or null. */
+export function signInTokenFrom(url) {
+    const hash = url.includes('#') ? url.slice(url.indexOf('#') + 1) : '';
+    const v = new URLSearchParams(hash).get('awesomate_token');
+    return v && v.length >= 20 ? v : null;
+}
+const REFRESH_EARLY_MS = 30_000;
+export class AwesomateAppClient {
+    opts;
+    base;
+    doFetch;
+    storage;
+    key;
+    session;
+    refreshing = null;
+    listeners = new Set();
+    socket = null;
+    constructor(opts) {
+        this.opts = opts;
+        if (!opts?.publishableKey?.startsWith('pk_'))
+            throw new Error('createAppClient needs the app\'s publishable key (pk_...).');
+        if (/^amt_(pat|bs)_/.test(opts.publishableKey))
+            throw new Error('That is the account\'s own token. Never put it in browser code; use the app\'s publishable key.');
+        this.base = (opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, '');
+        this.doFetch = opts.fetch ?? globalThis.fetch?.bind(globalThis);
+        if (!this.doFetch)
+            throw new Error('No fetch available.');
+        this.storage = opts.storage ?? browserStorage();
+        this.key = opts.storageKey ?? `awesomate.session.${opts.publishableKey.slice(-10)}`;
+    }
+    auth = {
+        /** Email a sign-in link. The answer is the same whether or not the address can sign in. */
+        signInWithLink: (email, options) => this.request('POST', '/auth/magic-link', { email, redirect_to: options.redirectTo }),
+        /**
+         * Finish signing in from the link: the current page's address by default, or a URL a deep link
+         * opened (Capacitor). Returns the user, or null when the address carries no sign-in. The
+         * token is removed from the browser's address bar.
+         */
+        completeSignIn: async (url) => {
+            const here = typeof location !== 'undefined' ? location.href : '';
+            const token = signInTokenFrom(url ?? here);
+            if (!token)
+                return null;
+            if (!url && typeof history !== 'undefined' && typeof location !== 'undefined') {
+                history.replaceState(history.state, '', location.pathname + location.search);
+            }
+            return (await this.save(await this.request('POST', '/auth/verify', { token }))).user;
+        },
+        /** The signed-in user, or null. */
+        user: async () => (await this.load())?.user ?? null,
+        /** Called with the user on sign-in and null on sign-out (including a refresh that was refused). */
+        onChange: (listener) => {
+            this.listeners.add(listener);
+            return () => { this.listeners.delete(listener); };
+        },
+        signOut: async () => {
+            const s = await this.load();
+            await this.clear();
+            if (s)
+                await this.request('POST', '/auth/sign-out', { refresh_token: s.refresh_token }).catch(() => undefined);
+        },
+        /** A current access token, for the app's own server to verify against the JWKS. */
+        accessToken: async () => (await this.current())?.access_token ?? null,
+    };
+    async request(method, path, body, token) {
+        const res = await this.doFetch(`${this.base}/api/sdk/v1${path}`, {
+            method,
+            headers: {
+                'x-awesomate-key': this.opts.publishableKey,
+                ...(token ? { authorization: `Bearer ${token}` } : {}),
+                ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        let json = {};
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch { /* a proxy's error page */ }
+        if (res.ok)
+            return json;
+        const server = typeof json.code === 'string' ? json.code : undefined;
+        const message = typeof json.error === 'string' ? json.error : `The hub answered ${res.status}.`;
+        throw new AwesomateError(errorCode(res.status, server), message, res.status, typeof json.field === 'string' ? json.field : undefined, server);
+    }
+    async read() {
+        try {
+            const raw = await this.storage.getItem(this.key);
+            const s = raw ? JSON.parse(raw) : null;
+            return s?.access_token && s.refresh_token && s.user ? s : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async load() {
+        if (this.session === undefined)
+            this.session = await this.read();
+        return this.session;
+    }
+    async save(r) {
+        const s = { access_token: r.access_token, refresh_token: r.refresh_token, expires_at: Date.now() + r.expires_in * 1000, user: r.user };
+        this.session = s;
+        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() {
+        const had = this.session !== null;
+        this.session = null;
+        await this.storage.removeItem(this.key);
+        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() {
+        const s = await this.load();
+        if (!s)
+            return null;
+        return s.expires_at - Date.now() > REFRESH_EARLY_MS ? s : this.refresh(s);
+    }
+    /** One refresh at a time per client; a refresh another tab already did is picked up from storage. */
+    refresh(s) {
+        if (this.refreshing)
+            return this.refreshing;
+        this.refreshing = (async () => {
+            const stored = await this.read();
+            if (stored && stored.refresh_token !== s.refresh_token && stored.expires_at - Date.now() > REFRESH_EARLY_MS) {
+                this.session = stored;
+                return stored;
+            }
+            try {
+                return await this.save(await this.request('POST', '/auth/refresh', { refresh_token: s.refresh_token }));
+            }
+            catch (err) {
+                if (!(err instanceof AwesomateError) || err.code !== 'unauthenticated')
+                    throw err;
+                const after = await this.read();
+                if (after && after.refresh_token !== s.refresh_token) {
+                    this.session = after;
+                    return after;
+                }
+                await this.clear();
+                return null;
+            }
+        })().finally(() => { this.refreshing = null; });
+        return this.refreshing;
+    }
+    /** A data call as the signed-in user: refused once (a disable, a key change), it refreshes and tries again; refused twice, it signs out. */
+    async data(method, path, body) {
+        let s = await this.current();
+        if (!s)
+            throw new AwesomateError('unauthenticated', 'Sign in first.', 401);
+        try {
+            return await this.request(method, path, body, s.access_token);
+        }
+        catch (err) {
+            if (!(err instanceof AwesomateError) || err.code !== 'unauthenticated')
+                throw err;
+            s = await this.refresh(s);
+            if (!s)
+                throw err;
+            return this.request(method, path, body, s.access_token);
+        }
+    }
+    async query(kind, options = {}) {
+        const r = await this.data('POST', '/rows/query', { kind, ...options });
+        return { rows: r.rows, next: r.next, count: r.count, applied: r.applied, asAt: r.as_at };
+    }
+    async *queryAll(kind, options = {}) {
+        const { maxRows = 10_000, ...rest } = options;
+        let after;
+        let seen = 0;
+        do {
+            const page = await this.query(kind, { limit: 1000, ...rest, ...(after ? { after } : {}) });
+            for (const row of page.rows) {
+                if (seen++ >= maxRows)
+                    return;
+                yield row;
+            }
+            after = page.next ?? undefined;
+        } while (after);
+    }
+    /** One record by id, or null when there is none this user may read. */
+    async get(kind, id) {
+        try {
+            return (await this.data('GET', `/rows/${encodeURIComponent(kind)}/${encodeURIComponent(id)}`)).row;
+        }
+        catch (err) {
+            if (err instanceof AwesomateError && err.code === 'not_found')
+                return null;
+            throw err;
+        }
+    }
+    /** Create a record (returns its id) or change one with options.id, inside the kind's write rule for this user. */
+    async write(kind, data, options = {}) {
+        const r = await this.data('POST', '/call', {
+            fn: 'write_record', args: { kind, data, links: options.links ?? {}, ...(options.id ? { id: options.id } : {}) },
+        });
+        return r.result.id;
+    }
+    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);
+}
 export function createClient(options) {
     return new AwesomateClient(options);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@awesomate/sdk",
-  "version": "0.3.0",
-  "description": "Read your own Awesomate data from Node: query and page through your contact list with types generated from your fields",
+  "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",
   "publishConfig": {