@awesomate/sdk 0.10.0 → 0.12.0

package/README.md

@@ -30,6 +30,18 @@ const one = await db.get('contact', rows[0].id); // null if there is none
 const byPlan = await db.aggregate({ measures: [{ column: 'people', agg: 'count' }], dimensions: ['plan'] });
 ```
 
+## The business itself
+
+```js
+const biz = await db.business();
+biz.name;                                  // 'Acme Plumbing'
+for (const g of biz.groups) for (const f of g.facts) console.log(g.title, f.label, f.value, f.status, f.source);
+biz.completeness;                          // { core_set: 7, core_total: 8, missing_core: ['logo'] }
+const waiting = await db.businessSuggestions(); // details waiting for the owner's yes
+```
+
+The details Awesomate keeps about the business: name, what it does, voice, colours, how customers reach it. Each one says where it came from. `confirmed` details are the ones agents and automations use. A `suggestion` waits for the owner, who confirms it on Knowledge, Your business in the hub. This needs the account's token, on every plan, never an app key.
+
 ## Writing app data (Support Plus and above)
 
 Define the tables an app keeps, then write to them. There's no migration and no SQL; every value is
@@ -151,6 +163,19 @@ If the account switched on reply emails, someone looking at the app isn't emaile
 but a tab left open in the background doesn't count as looking, and closing the last one counts as
 leaving straight away.
 
+A conversation can also show who else has it open and who is typing:
+
+```ts
+const room = app.here(job.id, (people) => showWhoIsHere(people)); // [{ user, role, name, typing, assistant? }]
+messageBox.oninput = () => room.typing(true);   // sent at most every few seconds
+messageBox.onblur = () => room.typing(false);
+// later: room.leave();
+```
+
+Everyone else with that record open and their tab in front is listed once, and the app's
+assistant appears while it writes a reply. The hub checks this person may read the record, and
+keeps checking; a refusal goes to the optional third argument, `onError`. Nothing is stored.
+
 ### Staff find a customer
 
 People in an app read no contacts but their own, so by default staff cannot put a job under a

package/dist/index.d.ts

@@ -224,6 +224,15 @@ export declare class AwesomateClient {
      * Never retried: a write that may have landed is not safe to send twice.
      */
     call<R extends RecipeName>(recipe: R, args?: ArgsOf<R>): Promise<RecipeResult>;
+    /**
+     * The business itself: the details Awesomate keeps about it (name, what it does, voice, colours,
+     * how customers reach it), grouped, each with where it came from. `confirmed` details are the
+     * ones agents and automations use; `suggestion` ones wait for the owner. Needs the account's
+     * token (hosting:read, every plan), never an app key.
+     */
+    business(): Promise<BusinessIdentity>;
+    /** Details waiting for the owner's yes on Your business: from the website, the account, a team member or a file. */
+    businessSuggestions(): Promise<BusinessSuggestion[]>;
     /** Grouped numbers (counts, sums) in the Business Data API's shape. */
     aggregate(request: {
         measures: Array<{
@@ -251,6 +260,43 @@ export declare class AwesomateClient {
         limit?: number;
     }): Promise<Record<string, unknown>>;
 }
+/** One detail about the business. */
+export interface BusinessFact {
+    key: string;
+    label: string;
+    value: string;
+    /** confirmed: in use by agents and automations. suggestion: waiting for the owner. */
+    status: 'confirmed' | 'suggestion';
+    /** Where it came from, in words: "confirmed by the owner", "added by a team member", "website research"... */
+    source: string;
+}
+export interface BusinessIdentity {
+    account: string;
+    name: string | null;
+    groups: Array<{
+        id: string;
+        title: string;
+        facts: BusinessFact[];
+    }>;
+    /** The eight core details every business should have, and which are missing. */
+    completeness: {
+        core_set: number;
+        core_total: number;
+        missing_core: string[];
+    };
+    /** Whether each source could be read: 'read', 'empty' or 'unavailable'. */
+    sources: Record<'confirmed_details' | 'saved_details' | 'account_details' | 'website_research', string>;
+    how_to_change: string;
+}
+export interface BusinessSuggestion {
+    id: number;
+    key: string;
+    value: string;
+    /** website, research, import, team_member, staff, upload, legacy_variables... */
+    sourceKind: string;
+    sourceRef: string | null;
+    recordedAt: string;
+}
 export interface AttributeSpec {
     key: string;
     label?: string;
@@ -418,6 +464,26 @@ export interface LiveChange<R> {
     /** Ids that left the list. */
     removes: string[];
 }
+/** Someone else with the same record open (app.here), as the hub sends them. */
+export interface HerePerson {
+    /** Their app user id, or 'assistant' for the app's AI assistant. */
+    user: string;
+    role: string;
+    /** Their first name from the account's Contacts, or null. */
+    name: string | null;
+    typing: boolean;
+    /** The app's AI assistant, writing a reply. */
+    assistant?: true;
+}
+export interface HereHandle {
+    /**
+     * Say this person is typing (call it on each keystroke: it sends at most every few seconds) or has
+     * stopped (on send or blur). Without another call, typing ends on its own after a few seconds.
+     */
+    typing(on: boolean): void;
+    /** Close the record: the others stop seeing this person on it. */
+    leave(): void;
+}
 export interface LiveHandlers<R> {
     /** Called with the whole list, in the query's order, at first and after every change. */
     onRows: (rows: R[], change: LiveChange<R> | null) => void;
@@ -516,6 +582,15 @@ export declare class AwesomateAppClient {
      * a fresh snapshot when it does. Returns stop().
      */
     live<K extends KindName, S extends keyof RowOf<K> = keyof RowOf<K>>(kind: K, options: Omit<QueryOptions<RowOf<K>, S>, 'after'>, handlers: LiveHandlers<Pick<RowOf<K>, S>> | ((rows: Array<Pick<RowOf<K>, S>>, change: LiveChange<Pick<RowOf<K>, S>> | null) => void)): () => void;
+    /** The one live connection behind live() and here(), made on first use. */
+    private liveSocket;
+    /**
+     * Open a record (a job's conversation) for who-is-here: onPeople gets everyone else who has it
+     * open with their tab in front, and who is typing, at first and on every change; the app's
+     * assistant appears while it writes a reply. The hub checks this person may read the record, and
+     * keeps checking; onError hears a refusal. Shares the one live connection. Returns typing() and leave().
+     */
+    here(recordId: string, onPeople: (people: HerePerson[]) => void, onError?: (err: AwesomateError) => void): HereHandle;
 }
 export declare function createAppClient(options: AppClientOptions): AwesomateAppClient;
 export declare function createClient(options: ClientOptions): AwesomateClient;

package/dist/index.js

@@ -215,6 +215,19 @@ export class AwesomateClient {
     async call(recipe, args = {}) {
         return (await this.request('POST', '/api/my-crm/v1/call', { fn: recipe, args }, false)).result;
     }
+    /**
+     * The business itself: the details Awesomate keeps about it (name, what it does, voice, colours,
+     * how customers reach it), grouped, each with where it came from. `confirmed` details are the
+     * ones agents and automations use; `suggestion` ones wait for the owner. Needs the account's
+     * token (hosting:read, every plan), never an app key.
+     */
+    business() {
+        return this.request('GET', '/api/my-business/v1/identity?format=json');
+    }
+    /** Details waiting for the owner's yes on Your business: from the website, the account, a team member or a file. */
+    async businessSuggestions() {
+        return (await this.request('GET', '/api/my-business/v1/proposals')).proposals;
+    }
     /** Grouped numbers (counts, sums) in the Business Data API's shape. */
     aggregate(request) {
         return this.request('POST', '/api/my-crm/v1/data/query', request);
@@ -539,15 +552,29 @@ export class AwesomateAppClient {
      */
     live(kind, options, handlers) {
         const h = typeof handlers === 'function' ? { onRows: handlers } : handlers;
-        this.socket ??= new LiveSocket({
+        return this.liveSocket().add({ kind, ...options }, h);
+    }
+    /** The one live connection behind live() and here(), made on first use. */
+    liveSocket() {
+        return this.socket ??= new LiveSocket({
             url: `${this.base.replace(/^http/, 'ws')}/api/sdk/v1/socket`,
             WebSocket: this.opts.WebSocket ?? globalThis.WebSocket,
             session: () => this.current(),
             refresh: async () => { const s = await this.load(); return s ? this.refresh(s) : null; },
         });
-        return this.socket.add({ kind, ...options }, h);
+    }
+    /**
+     * Open a record (a job's conversation) for who-is-here: onPeople gets everyone else who has it
+     * open with their tab in front, and who is typing, at first and on every change; the app's
+     * assistant appears while it writes a reply. The hub checks this person may read the record, and
+     * keeps checking; onError hears a refusal. Shares the one live connection. Returns typing() and leave().
+     */
+    here(recordId, onPeople, onError) {
+        return this.liveSocket().join(recordId, onPeople, onError);
     }
 }
+/** A page saying "still typing" more often than this is not sent: the hub keeps it for six seconds. */
+const TYPING_RESEND_MS = 2_500;
 /** Timers must never keep a Node process (a test, a server-side render) alive; browsers have no unref. */
 function unref(t) {
     t.unref?.();
@@ -583,6 +610,41 @@ class LiveSocket {
         if (this.ready && typeof d?.visibilityState === 'string')
             this.send({ type: 'presence', visible: d.visibilityState === 'visible' });
     }
+    /** Records open with here(): who else is on them goes to onPeople. */
+    rooms = new Map();
+    get wanted() {
+        return this.entries.size > 0 || this.rooms.size > 0;
+    }
+    join(id, onPeople, onError) {
+        const room = { onPeople, onError, typingSentAt: 0 };
+        this.rooms.set(id, room);
+        if (this.ready)
+            this.send({ type: 'here', id, on: true });
+        else if (!this.ws && !this.connecting)
+            void this.connect();
+        return {
+            typing: (on) => {
+                if (this.rooms.get(id) !== room || !this.ready)
+                    return;
+                const now = Date.now();
+                if (on && now - room.typingSentAt < TYPING_RESEND_MS)
+                    return;
+                if (!on && !room.typingSentAt)
+                    return;
+                room.typingSentAt = on ? now : 0;
+                this.send({ type: 'typing', id, on });
+            },
+            leave: () => {
+                if (this.rooms.get(id) !== room)
+                    return;
+                this.rooms.delete(id);
+                if (this.ready)
+                    this.send({ type: 'here', id, on: false });
+                if (!this.wanted)
+                    this.shut();
+            },
+        };
+    }
     add(spec, handlers) {
         const id = `l${++this.seq}`;
         this.entries.set(id, { spec, handlers, rows: new Map(), order: [] });
@@ -595,7 +657,7 @@ class LiveSocket {
                 return;
             if (this.ready)
                 this.send({ type: 'unsub', id });
-            if (!this.entries.size)
+            if (!this.wanted)
                 this.shut();
         };
     }
@@ -604,7 +666,7 @@ class LiveSocket {
             this.ws.send(JSON.stringify(f));
     }
     async connect() {
-        if (this.stopped || this.ws || this.connecting || !this.entries.size)
+        if (this.stopped || this.ws || this.connecting || !this.wanted)
             return;
         if (!this.o.WebSocket) {
             this.failAll(new AwesomateError('unavailable', 'No WebSocket here: pass createAppClient({ WebSocket }).', 0));
@@ -622,7 +684,7 @@ class LiveSocket {
             this.failAll(new AwesomateError('unauthenticated', 'Sign in first.', 401));
             return;
         }
-        if (this.stopped || this.ws || !this.entries.size)
+        if (this.stopped || this.ws || !this.wanted)
             return;
         this.scheduleRefresh(session);
         const ws = new this.o.WebSocket(this.o.url);
@@ -646,9 +708,29 @@ class LiveSocket {
             for (const [id, e] of this.entries)
                 this.send({ type: 'sub', id, spec: e.spec });
             this.sendPresence();
+            for (const [id, room] of this.rooms) {
+                room.typingSentAt = 0;
+                this.send({ type: 'here', id, on: true });
+            }
             this.pinger = unref(setInterval(() => this.send({ type: 'ping' }), 25_000));
             return;
         }
+        if (f.type === 'people' && typeof f.id === 'string') {
+            this.rooms.get(f.id)?.onPeople(Array.isArray(f.people) ? f.people : []);
+            return;
+        }
+        if (f.type === 'error' && typeof f.id === 'string' && f.id.startsWith('here:')) {
+            const id = f.id.slice(5);
+            const room = this.rooms.get(id);
+            if (!room)
+                return;
+            this.rooms.delete(id);
+            const code = ERROR_CODES.includes(String(f.code)) ? f.code : 'unavailable';
+            room.onError?.(new AwesomateError(code, String(f.message ?? 'Refused.'), 0, undefined, String(f.code)));
+            if (!this.wanted)
+                this.shut();
+            return;
+        }
         const e = typeof f.id === 'string' ? this.entries.get(f.id) : undefined;
         if (f.type === 'error') {
             const code = ERROR_CODES.includes(String(f.code)) ? f.code : 'unavailable';
@@ -713,7 +795,8 @@ class LiveSocket {
         if (this.refresher)
             clearTimeout(this.refresher);
         const ms = Math.max(5_000, s.expires_at - Date.now() - 60_000);
-        this.refresher = unref(setTimeout(() => { if (this.entries.size)
+        // A socket kept open only by here() needs a fresh token too, or the hub closes it at expiry.
+        this.refresher = unref(setTimeout(() => { if (this.wanted)
             void this.o.refresh(); }, ms));
     }
     async closed(ws, code) {
@@ -724,7 +807,7 @@ class LiveSocket {
         if (this.pinger)
             clearInterval(this.pinger);
         this.pinger = null;
-        if (this.stopped || !this.entries.size)
+        if (this.stopped || !this.wanted)
             return;
         if (code === 4401) {
             // Refused as unauthenticated: one refresh; if that is refused too, the person is signed out.
@@ -739,9 +822,13 @@ class LiveSocket {
     }
     failAll(err) {
         const all = [...this.entries.values()];
+        const rooms = [...this.rooms.values()];
         this.entries.clear();
+        this.rooms.clear();
         for (const e of all)
             e.handlers.onError?.(err);
+        for (const r of rooms)
+            r.onError?.(err);
         this.shut();
     }
     shut() {

package/package.json

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