@awesomate/sdk 0.18.1 → 0.20.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.1";
+export declare const VERSION = "0.20.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. */
@@ -179,6 +260,22 @@ export interface FilesUsage {
     partial: boolean;
     measured_at: string;
 }
+/** An answer from the app's agent to a typed question (app.ask()). */
+export interface AgentAnswer {
+    /** answered: from the business's content, with sources; none: the content has no answer (or not for this person). */
+    status: 'answered' | 'none';
+    answer: string;
+    /** Where the answer came from: show them with it. */
+    sources: Array<{
+        title: string;
+        url: string | null;
+    }>;
+    /**
+     * The platform's sentence about keeping questions it could not answer. It comes with a person's
+     * first answer only: show it with that answer.
+     */
+    questionNotice: string | null;
+}
 /** A file uploaded from an app. Keep `handle` in a record (a kind's file attribute); it opens the file again. */
 export interface AppFile {
     handle: string;
@@ -297,6 +394,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<{
@@ -981,6 +1116,21 @@ export declare class AwesomateAppClient {
         /** The file a handle names, for someone signed in to this app. */
         download: (handle: string) => Promise<Blob>;
     };
+    /**
+     * Ask the app's agent a typed question, as this signed-in person: a help box that answers from
+     * the business's content, with sources. The agent is the one the account picked for the app (the
+     * same one Talk uses). Show `questionNotice` with the answer when it comes (a person's first).
+     * The agent answers only from content this person may see; the voice persona does not apply.
+     * A refusal's serverCode says why: no_agent, channel_off, person_daily (30 a day per person),
+     * agent_daily, answers_used_up; personMessage is the sentence to show.
+     *
+     * @example
+     * const a = await app.ask('What time do you open on Saturday?');
+     * render(a.answer, a.sources, a.questionNotice);
+     */
+    ask(question: string, options?: {
+        session?: string;
+    }): Promise<AgentAnswer>;
     /**
      * The agent this app talks with by voice, or null when the account has not picked one. Pass it
      * to AwesomateAgent.mount as agentId; the hub decides which agent answers, never the page.

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.1';
+export const VERSION = '0.20.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')
@@ -759,6 +809,22 @@ export class AwesomateAppClient {
         /** The file a handle names, for someone signed in to this app. */
         download: async (handle) => this.authed(async (token) => (await this.rawData('GET', `/files/${encodeURIComponent(handle)}`, token)).blob()),
     };
+    /**
+     * Ask the app's agent a typed question, as this signed-in person: a help box that answers from
+     * the business's content, with sources. The agent is the one the account picked for the app (the
+     * same one Talk uses). Show `questionNotice` with the answer when it comes (a person's first).
+     * The agent answers only from content this person may see; the voice persona does not apply.
+     * A refusal's serverCode says why: no_agent, channel_off, person_daily (30 a day per person),
+     * agent_daily, answers_used_up; personMessage is the sentence to show.
+     *
+     * @example
+     * const a = await app.ask('What time do you open on Saturday?');
+     * render(a.answer, a.sources, a.questionNotice);
+     */
+    async ask(question, options = {}) {
+        const r = await this.data('POST', '/agents/ask', { question, ...(options.session ? { session: options.session } : {}) });
+        return { status: r.status, answer: r.answer, sources: r.sources ?? [], questionNotice: r.question_notice ?? null };
+    }
     /**
      * The agent this app talks with by voice, or null when the account has not picked one. Pass it
      * to AwesomateAgent.mount as agentId; the hub decides which agent answers, never the page.

package/package.json

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