@awesomate/sdk 0.4.0 → 0.6.0

package/README.md

@@ -91,23 +91,45 @@ 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` });
+// Render on every change of person: signed in, signed out, a new role.
+app.auth.onChange((u) => render(u));
+app.auth.onSignInError((err) => showMessage(err.message));
 
-// /signed-in: exchanges the link for a session and clears it from the address bar.
-const user = await app.auth.completeSignIn();
+// The sign-in page: an email link, no password. The answer is the same for any address.
+await app.auth.signInWithLink(email, { redirectTo: location.href });
 
 // 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();
 ```
 
+The link signs them in by itself. In a browser the client takes the link from the address bar,
+on load or when it arrives in a tab that is already open (only the part after `#` changes, so
+the page does not reload), clears it at once and tells `onChange`. A link that has expired or
+was already used goes to `onSignInError`. `await app.auth.completeSignIn()` still works and
+returns the same sign-in, never a second exchange. Pass `handleSignInLinks: false` to take links
+yourself. `onChange` hears about people, not tokens: the routine token refresh is silent.
+
+### 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
+call `completeSignIn(url)` with 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

@@ -13,15 +13,16 @@
  * 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
+ *   app.auth.onChange((user) => render(user));      // the link signs them in by itself
  *   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.6.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,43 @@ 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;
+    /**
+     * Default true in a browser: a sign-in link is taken up by itself, when the page loads with one
+     * and when one arrives in a tab already showing the page (only the #fragment changes then, and
+     * the page does not reload). Set false when another client on the page handles links.
+     */
+    handleSignInLinks?: boolean;
+}
+/** 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,7 +422,13 @@ export declare class AwesomateAppClient {
     private session;
     private refreshing;
     private readonly listeners;
+    private readonly linkErrorListeners;
+    /** The sign-in link being (or last) exchanged, so the same link is never exchanged twice. */
+    private link;
+    private socket;
     constructor(opts: AppClientOptions);
+    /** A sign-in link in the address bar, exchanged in the background; a failure goes to onSignInError. */
+    private takeLink;
     readonly auth: {
         /** Email a sign-in link. The answer is the same whether or not the address can sign in. */
         signInWithLink: (email: string, options: {
@@ -394,14 +439,21 @@ export declare class AwesomateAppClient {
         }>;
         /**
          * 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.
+         * opened (Capacitor). Returns the user, or null when the address carries no sign-in. The token
+         * is removed from the browser's address bar. In a browser this happens by itself (see
+         * handleSignInLinks); calling it as well is safe, and returns the same sign-in, never a second.
          */
         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). */
+        /**
+         * Called with the user when someone signs in (or their details change: a new role, a linked
+         * contact) and with null on sign-out, including a refresh that was refused. A routine token
+         * refresh does not call it.
+         */
         onChange: (listener: (user: AppUser | null) => void) => (() => void);
+        /** Called when a sign-in link could not be used (expired, already used, not this app's). */
+        onSignInError: (listener: (err: AwesomateError) => void) => (() => void);
         signOut: () => Promise<void>;
         /** A current access token, for the app's own server to verify against the JWKS. */
         accessToken: () => Promise<string | null>;
@@ -409,6 +461,7 @@ export declare class AwesomateAppClient {
     private request;
     private read;
     private load;
+    /** signedIn: a sign-in, always announced; otherwise a refresh, announced only when the person changed. */
     private save;
     private clear;
     /** A session whose access token has at least half a minute left, refreshing if not. */
@@ -426,6 +479,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

@@ -13,16 +13,18 @@
  * 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
+ *   app.auth.onChange((user) => render(user));      // the link signs them in by itself
  *   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.6.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,10 @@ export class AwesomateAppClient {
     session;
     refreshing = null;
     listeners = new Set();
+    linkErrorListeners = new Set();
+    /** The sign-in link being (or last) exchanged, so the same link is never exchanged twice. */
+    link = null;
+    socket = null;
     constructor(opts) {
         this.opts = opts;
         if (!opts?.publishableKey?.startsWith('pk_'))
@@ -243,32 +249,78 @@ export class AwesomateAppClient {
             throw new Error('No fetch available.');
         this.storage = opts.storage ?? browserStorage();
         this.key = opts.storageKey ?? `awesomate.session.${opts.publishableKey.slice(-10)}`;
+        const w = globalThis.window;
+        if (opts.handleSignInLinks !== false && w && typeof location !== 'undefined') {
+            this.takeLink();
+            w.addEventListener?.('hashchange', () => this.takeLink());
+        }
+    }
+    /** A sign-in link in the address bar, exchanged in the background; a failure goes to onSignInError. */
+    takeLink() {
+        if (signInTokenFrom(location.href))
+            void this.auth.completeSignIn().catch(() => undefined);
     }
     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.
+         * opened (Capacitor). Returns the user, or null when the address carries no sign-in. The token
+         * is removed from the browser's address bar. In a browser this happens by itself (see
+         * handleSignInLinks); calling it as well is safe, and returns the same sign-in, never a second.
          */
-        completeSignIn: async (url) => {
+        completeSignIn: (url) => {
             const here = typeof location !== 'undefined' ? location.href : '';
             const token = signInTokenFrom(url ?? here);
+            // The client may already have read the link from the address bar and cleared it.
             if (!token)
-                return null;
+                return this.link && !this.link.settled ? this.link.promise : Promise.resolve(null);
+            // Before anything else: a reload must never find a link that was already used.
             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 same link again (a second click of the email) is the same sign-in, until a sign-out.
+            if (this.link?.token === token)
+                return this.link.promise;
+            const entry = { token, settled: false };
+            entry.promise = this.request('POST', '/auth/verify', { token }).then(async (r) => {
+                // Signed out, or another link taken, while this one was at the hub: it is not a sign-in any more.
+                if (this.link !== entry) {
+                    void this.request('POST', '/auth/sign-out', { refresh_token: r.refresh_token }).catch(() => undefined);
+                    return null;
+                }
+                return (await this.save(r, true)).user;
+            });
+            entry.promise.then(() => { entry.settled = true; }, (err) => {
+                entry.settled = true;
+                // Abandoned (a sign-out, or a newer link took over): nobody is waiting on this one any more.
+                if (this.link !== entry)
+                    return;
+                // A failure is not remembered: the same link again goes back to the hub (a blip may have passed).
+                this.link = null;
+                const e = err instanceof AwesomateError ? err : new AwesomateError('unavailable', String(err?.message ?? err), 0);
+                for (const l of this.linkErrorListeners)
+                    l(e);
+            });
+            this.link = entry;
+            return entry.promise;
         },
         /** 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). */
+        /**
+         * Called with the user when someone signs in (or their details change: a new role, a linked
+         * contact) and with null on sign-out, including a refresh that was refused. A routine token
+         * refresh does not call it.
+         */
         onChange: (listener) => {
             this.listeners.add(listener);
             return () => { this.listeners.delete(listener); };
         },
+        /** Called when a sign-in link could not be used (expired, already used, not this app's). */
+        onSignInError: (listener) => {
+            this.linkErrorListeners.add(listener);
+            return () => { this.linkErrorListeners.delete(listener); };
+        },
         signOut: async () => {
             const s = await this.load();
             await this.clear();
@@ -313,25 +365,41 @@ export class AwesomateAppClient {
         }
     }
     async load() {
+        if (this.session !== undefined)
+            return this.session;
+        const s = await this.read();
+        // A sign-in or sign-out that landed while storage was being read is newer than what was read.
         if (this.session === undefined)
-            this.session = await this.read();
+            this.session = s;
         return this.session;
     }
-    async save(r) {
+    /** signedIn: a sign-in, always announced; otherwise a refresh, announced only when the person changed. */
+    async save(r, signedIn = false) {
+        const before = this.session === undefined ? await this.read() : this.session;
         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);
+        // Listeners hear about people, not tokens: a refresh that returns the same user is silent.
+        if (signedIn || !before || JSON.stringify(before.user) !== JSON.stringify(s.user))
+            for (const l of this.listeners)
+                l(s.user);
+        // A token frame carries on as the same person; anyone else needs a connection of their own.
+        if (before && before.user.id !== s.user.id)
+            this.socket?.personChanged();
+        else
+            this.socket?.tokenChanged(s);
         return s;
     }
     async clear() {
         const had = this.session !== null;
         this.session = null;
+        this.link = 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() {
@@ -351,11 +419,17 @@ export class AwesomateAppClient {
                 return stored;
             }
             try {
-                return await this.save(await this.request('POST', '/auth/refresh', { refresh_token: s.refresh_token }));
+                const r = await this.request('POST', '/auth/refresh', { refresh_token: s.refresh_token });
+                // Someone signed in or out while this was at the hub: theirs is the session now.
+                if (this.session !== s)
+                    return this.session ?? null;
+                return await this.save(r);
             }
             catch (err) {
                 if (!(err instanceof AwesomateError) || err.code !== 'unauthenticated')
                     throw err;
+                if (this.session !== s)
+                    return this.session ?? null;
                 const after = await this.read();
                 if (after && after.refresh_token !== s.refresh_token) {
                     this.session = after;
@@ -423,6 +497,228 @@ 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);
+    }
+    /**
+     * Someone else signed in: the open connection said hello as the person before, so start again as
+     * the new one. Every list stays and takes a fresh snapshot, which the database writes for them.
+     */
+    personChanged() {
+        const ws = this.ws;
+        this.ws = null;
+        this.ready = false;
+        this.stopped = false;
+        this.attempt = 0;
+        if (this.pinger)
+            clearInterval(this.pinger);
+        if (this.retry)
+            clearTimeout(this.retry);
+        this.pinger = this.retry = null;
+        if (ws && ws.readyState <= 1) {
+            try {
+                ws.send(JSON.stringify({ type: 'bye' }));
+            }
+            catch { /* closing */ }
+            ws.close(1000, 'bye');
+        }
+        void this.connect();
+    }
+    /** 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.6.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",