@awesomate/sdk 0.5.0 → 0.7.0

package/README.md

@@ -79,6 +79,26 @@ Every failure is an `AwesomateError` with a `code`: `unauthenticated`, `forbidde
 The token is your account's hosting token. Use it in a server, a script or a scheduled job, never
 in a browser. For a browser, sign your app's own users in (below).
 
+## Your app's server: a key of its own
+
+An app's own server, or an n8n workflow, should not carry the account's token. Give it a server
+key instead: Claude makes one with `awesomate_crm_apps` (`create_key`), read or write, for every
+kind or only the ones it names. The key is shown once; put it in the server's environment.
+
+```ts
+const db = createClient({ token: process.env.AWESOMATE_APP_KEY! }); // ak_...
+const { rows } = await db.query('job', { where: { status: 'booked' } });
+await db.write('job', { status: 'done' }, { id: rows[0].id });
+await db.call('book_job', { customer, title: 'Gutter clean', status: 'booked' });
+```
+
+A key reads and writes records and runs saved queries and recipes, only for its kinds (a recipe
+that writes anything else is refused). It reads every attribute of an app kind, and the contact
+list only as Claude does. Writes need Support Plus and above. It cannot change kinds, rules,
+queries or recipes, and it never works from a browser. Revoking a key stops it at once; switching
+the app off stops all of them. From n8n, send it as `Authorization: Bearer ak_...` to
+`https://hub.awesomate.ai/api/sdk/v1/server/rows/query` (and `/call`, `/queries/<key>/run`).
+
 ## 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
@@ -91,19 +111,26 @@ 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
@@ -122,7 +149,7 @@ Outside a browser, give it a WebSocket: `createAppClient({ publishableKey, WebSo
 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,7 +13,7 @@
  * 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
  *
@@ -22,7 +22,7 @@
  * 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.5.0";
+export declare const VERSION = "0.7.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -143,7 +143,11 @@ export declare class AwesomateError extends Error {
     serverCode?: string | undefined);
 }
 export interface ClientOptions {
-    /** The account's hosting token (amt_pat_...) with crm:read. */
+    /**
+     * The account's hosting token (amt_pat_...) with crm:read, or an app's server key (ak_...) from
+     * the account's apps. A key reads and writes records and runs saved queries and recipes, for the
+     * kinds it was made for; changing kinds, queries or recipes needs the account's token.
+     */
     token: string;
     baseUrl?: string;
     fetch?: typeof fetch;
@@ -152,6 +156,8 @@ export declare class AwesomateClient {
     private readonly opts;
     private readonly base;
     private readonly doFetch;
+    /** An app key talks to its own routes, which carry only what a key may do. */
+    private readonly appKey;
     constructor(opts: ClientOptions);
     private request;
     /** The kinds this token can read, their columns, operators and examples. */
@@ -375,6 +381,12 @@ export interface AppClientOptions {
     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 {
@@ -416,8 +428,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: {
@@ -428,14 +445,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>;
@@ -443,6 +467,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. */

package/dist/index.js

@@ -13,7 +13,7 @@
  * 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
  *
@@ -22,7 +22,7 @@
  * queries works on every plan; writing app data (kinds, records, saved queries, recipes) needs
  * crm:write, Support Plus and above.
  */
-export const VERSION = '0.5.0';
+export const VERSION = '0.7.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 {
@@ -58,20 +58,37 @@ function errorCode(status, server) {
         return 'not_found';
     return 'unavailable';
 }
+const ACCOUNT = '/api/my-crm/v1';
+const KEY_ROUTES = [
+    ['GET', /^\/rows\/schema$/], ['POST', /^\/rows\/query$/], ['GET', /^\/rows\/[^/]+\/[^/?]+(\?.*)?$/], ['POST', /^\/call$/],
+    ['GET', /^\/queries$/], ['POST', /^\/queries\/[^/]+\/run$/], ['GET', /^\/recipes$/],
+];
+/** The same call on an app key's routes, or a clear refusal for what only the account may do. */
+function keyPath(method, path) {
+    const rest = path.startsWith(ACCOUNT) ? path.slice(ACCOUNT.length) : path;
+    if (KEY_ROUTES.some(([m, re]) => m === method && re.test(rest)))
+        return `/api/sdk/v1/server${rest}`;
+    throw new AwesomateError('forbidden', 'An app key reads and writes records and runs saved queries and recipes. This needs the account\'s token.', 0);
+}
 export class AwesomateClient {
     opts;
     base;
     doFetch;
+    /** An app key talks to its own routes, which carry only what a key may do. */
+    appKey;
     constructor(opts) {
         this.opts = opts;
         if (!opts?.token)
-            throw new Error('createClient needs a token (the account\'s hosting token with crm:read).');
+            throw new Error('createClient needs a token: the account\'s hosting token, or an app\'s server key (ak_...).');
+        this.appKey = opts.token.startsWith('ak_');
         this.base = (opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, '');
         this.doFetch = opts.fetch ?? globalThis.fetch;
         if (!this.doFetch)
             throw new Error('No fetch available: use Node 18 or later, or pass fetch.');
     }
     async request(method, path, body, retry = true) {
+        if (this.appKey)
+            path = keyPath(method, path);
         const res = await this.doFetch(`${this.base}${path}`, {
             method,
             headers: {
@@ -233,6 +250,9 @@ 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;
@@ -246,32 +266,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();
@@ -316,22 +382,35 @@ 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);
-        this.socket?.tokenChanged(s);
+        // 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)
@@ -357,11 +436,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;
@@ -568,6 +653,30 @@ class LiveSocket {
             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)

package/package.json

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