@awesomate/sdk 0.18.0 → 0.19.0

package/dist/index.d.ts

@@ -24,7 +24,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export declare const VERSION = "0.18.0";
+export declare const VERSION = "0.19.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -157,6 +157,87 @@ export interface Page<R> {
     /** When the hub read the rows. */
     asAt: string;
 }
+/** Someone on the account, as Tasks names them. */
+export interface TaskPerson {
+    email: string;
+    name: string | null;
+}
+/**
+ * One card on the account's Tasks board: something waiting on a person (a quote to accept, an
+ * email to approve) or a task someone gave. The card's main action happens on its own page
+ * (`openPath` in the hub); Tasks only moves the card (not now, pass on) and finishes given tasks.
+ */
+export interface TaskCard {
+    /** Stable id of the card; pass it to notNow() and passOn(). */
+    key: string;
+    kind: string;
+    /** Where it came from, in the owner's words ("Build requests", "Contacts"). */
+    from: string;
+    title: string;
+    /** What is being asked, as a question. */
+    question: string;
+    context: string | null;
+    /** 1 routine to 5 urgent. */
+    priority: number;
+    createdAt: string;
+    dueAt: string | null;
+    /** The hub page that shows it in full. */
+    openPath: string;
+    /** Who has it, when it was passed on; null means anyone on the account. */
+    holder: TaskPerson | null;
+    /** When it comes back, if put off with Not now. */
+    snoozedUntil: string | null;
+    canAct: boolean;
+    /** Who it can be passed to. */
+    passTo: TaskPerson[];
+    /** Set for a task someone gave (give()); null for everything else. */
+    task: {
+        /** Pass it to update(), done() and drop(). */
+        id: number;
+        detail: string | null;
+        linkPath: string | null;
+        author: TaskPerson;
+        canFinish: boolean;
+        canDrop: boolean;
+        canEdit: boolean;
+    } | null;
+}
+/** The Tasks board, as the account's token sees it (the owner, so `scope: 'all'` works). */
+export interface TaskBoard {
+    scope: 'mine' | 'all';
+    me: TaskPerson & {
+        role: string;
+    };
+    /** Who a task can be given to. */
+    people: Array<TaskPerson & {
+        me: boolean;
+    }>;
+    /** Waiting for a decision now. */
+    toDecide: TaskCard[];
+    /** Put off with Not now; back when the time comes. */
+    later: TaskCard[];
+    /** With someone else. */
+    waiting: TaskCard[];
+    /** Recently decided, for the record. */
+    decided: Array<{
+        key: string;
+        kind: string;
+        from: string;
+        text: string;
+        by: TaskPerson | null;
+        at: string;
+    }>;
+}
+/** A task to give: to someone on the account by email, or to the owner when `forEmail` is left out. */
+export interface GiveTask {
+    title: string;
+    detail?: string;
+    forEmail?: string;
+    /** ISO time it is due. */
+    dueAt?: string;
+    /** A hub path the task points at, e.g. /contacts/people/... */
+    linkPath?: string;
+}
 /** A file or folder in the account's Files (the folders on its automation account: public/, private/, temp/). */
 export interface FileEntry {
     /** Relative to the files folder, starting with its top folder: public/images/logo.png. */
@@ -297,6 +378,44 @@ export declare class AwesomateClient {
             trashPath: string;
         }>;
     };
+    private tasksCall;
+    /**
+     * The account's Tasks: what is waiting on its people, and tasks they give each other. An app's
+     * server or an n8n workflow can give someone a task ("call this customer back") and finish it.
+     * Needs the account's token, and Tasks on the account (a feature_unavailable refusal says
+     * when it is not).
+     *
+     * @example
+     * await db.tasks.give({ title: 'Call Sam back about the leak', forEmail: 'jo@brightwater.example', dueAt: '2026-10-06T09:00:00+11:00' });
+     */
+    readonly tasks: {
+        /** The board: waiting now, put off, with someone else, recently decided. `all` shows everyone's, not only yours. */
+        board: (options?: {
+            scope?: "mine" | "all";
+        }) => Promise<TaskBoard>;
+        /** Give a task. The person gets it on their board, and an email when they are not the one giving it. */
+        give: (task: GiveTask) => Promise<{
+            key: string;
+            id: number;
+            holder: TaskPerson;
+            emailed: boolean;
+        }>;
+        /** Change a given task: whoever wrote it, or the owner. */
+        update: (id: number | string, patch: Partial<Omit<GiveTask, "forEmail">>) => Promise<void>;
+        /** Mark a given task done: the person who has it, whoever wrote it, or the owner. */
+        done: (id: number | string) => Promise<void>;
+        /** Take a given task off the board without doing it: whoever wrote it, or the owner. */
+        drop: (id: number | string) => Promise<void>;
+        /** Put a card off until a time (at most 90 days), for this person only. */
+        notNow: (key: string, until: Date | string) => Promise<{
+            until: string;
+        }>;
+        /** Hand a card to someone on the account who can act on it. */
+        passOn: (key: string, toEmail: string, reason?: string) => Promise<{
+            holder: TaskPerson;
+            emailed: boolean;
+        }>;
+    };
     /** The kinds this token can read, their columns, operators and examples. */
     schema(): Promise<{
         kinds: Array<{
@@ -830,7 +949,7 @@ export interface HereHandle {
      * 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. */
+    /** Close the record: the others stop seeing this person on it once every part of the page that opened it has left. */
     leave(): void;
 }
 /** What live() calls. */
@@ -1007,7 +1126,9 @@ export declare class AwesomateAppClient {
      * 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().
+     * keeps checking; onError hears a refusal. Shares the one live connection. Two parts of a page (a
+     * thread and a sidebar) can open the same record: each hears onPeople, and it stays open until both
+     * have left. Returns typing() and leave().
      */
     here(recordId: string, onPeople: (people: HerePerson[]) => void, onError?: (err: AwesomateError) => void): HereHandle;
 }

package/dist/index.js

@@ -24,7 +24,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export const VERSION = '0.18.0';
+export const VERSION = '0.19.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 const ERROR_CODES = ['unauthenticated', 'forbidden', 'not_found', 'validation', 'consent_blocked', 'rate_limited', 'conflict', 'unavailable'];
 /**
@@ -230,6 +230,56 @@ export class AwesomateClient {
         /** Move to the trash. Not erased, and no longer counted toward the Files space. */
         remove: async (path) => this.filesCall('DELETE', `/api/files?path=${encodeURIComponent(path)}`),
     };
+    tasksCall(method, path, body) {
+        if (this.appKey) {
+            return Promise.reject(new AwesomateError('forbidden', 'Tasks needs the account\'s token (amt_pat_...), not an app key.', 0));
+        }
+        return this.request(method, path, body, false);
+    }
+    /**
+     * The account's Tasks: what is waiting on its people, and tasks they give each other. An app's
+     * server or an n8n workflow can give someone a task ("call this customer back") and finish it.
+     * Needs the account's token, and Tasks on the account (a feature_unavailable refusal says
+     * when it is not).
+     *
+     * @example
+     * await db.tasks.give({ title: 'Call Sam back about the leak', forEmail: 'jo@brightwater.example', dueAt: '2026-10-06T09:00:00+11:00' });
+     */
+    tasks = {
+        /** The board: waiting now, put off, with someone else, recently decided. `all` shows everyone's, not only yours. */
+        board: (options = {}) => this.tasksCall('GET', `/api/my-tasks${options.scope === 'all' ? '?scope=all' : ''}`),
+        /** Give a task. The person gets it on their board, and an email when they are not the one giving it. */
+        give: async (task) => {
+            const r = await this.tasksCall('POST', '/api/my-tasks/tasks', task);
+            return { key: r.key, id: r.id, holder: r.holder, emailed: r.emailed };
+        },
+        /** Change a given task: whoever wrote it, or the owner. */
+        update: async (id, patch) => {
+            await this.tasksCall('PATCH', `/api/my-tasks/tasks/${encodeURIComponent(String(id))}`, patch);
+        },
+        /** Mark a given task done: the person who has it, whoever wrote it, or the owner. */
+        done: async (id) => {
+            await this.tasksCall('POST', `/api/my-tasks/tasks/${encodeURIComponent(String(id))}/done`);
+        },
+        /** Take a given task off the board without doing it: whoever wrote it, or the owner. */
+        drop: async (id) => {
+            await this.tasksCall('POST', `/api/my-tasks/tasks/${encodeURIComponent(String(id))}/drop`);
+        },
+        /** Put a card off until a time (at most 90 days), for this person only. */
+        notNow: async (key, until) => {
+            const r = await this.tasksCall('POST', `/api/my-tasks/items/${encodeURIComponent(key)}/not-now`, {
+                until: until instanceof Date ? until.toISOString() : until,
+            });
+            return { until: r.until };
+        },
+        /** Hand a card to someone on the account who can act on it. */
+        passOn: async (key, toEmail, reason) => {
+            const r = await this.tasksCall('POST', `/api/my-tasks/items/${encodeURIComponent(key)}/pass-on`, {
+                toEmail, ...(reason ? { reason } : {}),
+            });
+            return { holder: r.holder, emailed: r.emailed };
+        },
+    };
     /** The kinds this token can read, their columns, operators and examples. */
     schema() {
         return this.request('GET', '/api/my-crm/v1/rows/schema');
@@ -271,7 +321,7 @@ export class AwesomateClient {
     async get(kind, id, options = {}) {
         try {
             const qs = options.tz ? `?tz=${encodeURIComponent(options.tz)}` : '';
-            const r = await this.request('GET', `/api/my-crm/v1/rows/${encodeURIComponent(kind)}/${encodeURIComponent(id)}${qs}`);
+            const r = await this.request('GET', `/api/my-crm/v1/rows/${encodeURIComponent(kind)}/${encodeURIComponent(String(id))}${qs}`);
             return r.row;
         }
         catch (err) {
@@ -658,7 +708,7 @@ export class AwesomateAppClient {
     /** 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;
+            return (await this.data('GET', `/rows/${encodeURIComponent(kind)}/${encodeURIComponent(String(id))}`)).row;
         }
         catch (err) {
             if (err instanceof AwesomateError && err.code === 'not_found')
@@ -799,7 +849,9 @@ export class AwesomateAppClient {
      * 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().
+     * keeps checking; onError hears a refusal. Shares the one live connection. Two parts of a page (a
+     * thread and a sidebar) can open the same record: each hears onPeople, and it stays open until both
+     * have left. Returns typing() and leave().
      */
     here(recordId, onPeople, onError) {
         return this.liveSocket().join(recordId, onPeople, onError);
@@ -842,32 +894,57 @@ 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. */
+    /**
+     * Records open with here(), one per record id however many parts of the page opened it: the hub
+     * hears `here on` once and `here off` when the last of them leaves, and every one of them gets
+     * onPeople. Typing is the person's, so one resend clock per record, shared by them all.
+     */
     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();
+        const listener = { onPeople, onError };
+        let room = this.rooms.get(id);
+        if (room) {
+            room.listeners.add(listener);
+            // Already open: the hub sends nothing new for a second join, so hand over who it last said was there.
+            const people = room.people;
+            if (people)
+                queueMicrotask(() => { if (this.rooms.get(id)?.listeners.has(listener))
+                    onPeople(people); });
+        }
+        else {
+            room = { listeners: new Set([listener]), typingSentAt: 0, people: null };
+            this.rooms.set(id, room);
+            if (this.ready)
+                this.send({ type: 'here', id, on: true });
+            else if (!this.ws && !this.connecting)
+                void this.connect();
+        }
+        const open = () => {
+            const r = this.rooms.get(id);
+            return r?.listeners.has(listener) ? r : undefined;
+        };
         return {
             typing: (on) => {
-                if (this.rooms.get(id) !== room || !this.ready)
+                const r = open();
+                if (!r || !this.ready)
                     return;
                 const now = Date.now();
-                if (on && now - room.typingSentAt < TYPING_RESEND_MS)
+                if (on && now - r.typingSentAt < TYPING_RESEND_MS)
                     return;
-                if (!on && !room.typingSentAt)
+                if (!on && !r.typingSentAt)
                     return;
-                room.typingSentAt = on ? now : 0;
+                r.typingSentAt = on ? now : 0;
                 this.send({ type: 'typing', id, on });
             },
             leave: () => {
-                if (this.rooms.get(id) !== room)
+                const r = open();
+                if (!r)
+                    return;
+                r.listeners.delete(listener);
+                if (r.listeners.size)
                     return;
                 this.rooms.delete(id);
                 if (this.ready)
@@ -948,7 +1025,13 @@ class LiveSocket {
             return;
         }
         if (f.type === 'people' && typeof f.id === 'string') {
-            this.rooms.get(f.id)?.onPeople(Array.isArray(f.people) ? f.people : []);
+            const room = this.rooms.get(f.id);
+            if (!room)
+                return;
+            const people = Array.isArray(f.people) ? f.people : [];
+            room.people = people;
+            for (const l of [...room.listeners])
+                l.onPeople(people);
             return;
         }
         if (f.type === 'error' && typeof f.id === 'string' && f.id.startsWith('here:')) {
@@ -958,7 +1041,9 @@ class LiveSocket {
                 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)));
+            const err = new AwesomateError(code, String(f.message ?? 'Refused.'), 0, undefined, String(f.code));
+            for (const l of room.listeners)
+                l.onError?.(err);
             if (!this.wanted)
                 this.shut();
             return;
@@ -1013,6 +1098,8 @@ class LiveSocket {
         if (this.retry)
             clearTimeout(this.retry);
         this.pinger = this.retry = null;
+        for (const room of this.rooms.values())
+            room.people = null;
         if (ws && ws.readyState <= 1) {
             try {
                 ws.send(JSON.stringify({ type: 'bye' }));
@@ -1039,6 +1126,9 @@ class LiveSocket {
         if (this.pinger)
             clearInterval(this.pinger);
         this.pinger = null;
+        // Who was there is the old connection's word: a part opening a record now waits for the new one.
+        for (const room of this.rooms.values())
+            room.people = null;
         if (this.stopped || !this.wanted)
             return;
         if (code === 4401) {
@@ -1060,7 +1150,8 @@ class LiveSocket {
         for (const e of all)
             e.handlers.onError?.(err);
         for (const r of rooms)
-            r.onError?.(err);
+            for (const l of r.listeners)
+                l.onError?.(err);
         this.shut();
     }
     shut() {

package/package.json

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