@awesomate/sdk 0.63.0 → 0.65.0

package/dist/index.d.ts

@@ -26,7 +26,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.63.0";
+export declare const VERSION = "0.65.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -1111,16 +1111,13 @@ export declare class AwesomateClient {
          * Null when there is none (an id that is not one never reaches the hub).
          */
         get: (id: string) => Promise<EmailDetail | null>;
-        /** A new draft to list `topic` (a key from `lists()`). `checks.blockers` must be empty before a person can approve it. */
-        draft: (input: {
-            topic: string;
-            doc: EmailDoc;
-        }) => Promise<EmailDraft>;
+        /**
+         * A new draft to list `topic` (a key from `lists()`). `checks.blockers` must be empty before a
+         * person can approve it. `send_at` proposes when it goes (see `EmailDraftInput`).
+         */
+        draft: (input: EmailDraftInput) => Promise<EmailDraft>;
         /** Replace a draft. Once someone approved it, it is refused: a person changes it in the hub. */
-        update: (id: string, input: {
-            topic: string;
-            doc: EmailDoc;
-        }) => Promise<EmailDraft>;
+        update: (id: string, input: EmailDraftInput) => Promise<EmailDraft>;
         /**
          * Throw a draft away. A draft only: an approved, sending or sent email throws `unavailable`
          * (server code `not_a_draft`, the case in `reason`). Nothing is deleted: the draft is stopped
@@ -1640,6 +1637,52 @@ export declare class AwesomateClient {
      * await db.archiveLink('vehicle', 'serviced_at');
      */
     archiveLink(kind: string, key: string): Promise<KindDescription>;
+    /**
+     * Set this up for me: the hub's suggestion for one sentence about what the owner keeps track of
+     * ("a job management system"), as a whole setup in the owner's words (fields, stages, lists,
+     * links, small related things, the brief). Nothing is saved. Pass `kind` to ask about one of
+     * their things: the suggestion then only adds to it, and `matched` says what it has already.
+     * Edit it if you like, then checkSetup(). The account's token, crm:write, Support Plus and above,
+     * with Set this up for me on the account; a few a person in ten minutes.
+     *
+     * @example
+     * const proposal = await db.proposeSetup('property bookings');
+     * console.log(proposal.sentence);
+     */
+    proposeSetup(sentence: string, options?: {
+        kind?: string;
+    }): Promise<SetupProposal>;
+    /**
+     * Check a setup exactly as a click would, and read the sentence the owner should agree to before
+     * applySetup(). Nothing is saved. On one of their things it is additions only, and answers
+     * `base`, which applySetup() needs. A setup that does not fit throws `validation` naming the
+     * item (`at`, like `fields.2`). The account's token, crm:write.
+     *
+     * @example
+     * const proposal = await db.proposeSetup('a quote pipeline');
+     * const check = await db.checkSetup(proposal.setup);
+     * if (check.can_apply) console.log(check.sentence);
+     */
+    checkSetup(setup: SetupSpec, options?: {
+        replaceBrief?: boolean;
+    }): Promise<SetupCheck>;
+    /**
+     * Set it up, all in one go or not at all: the thing, its fields, sections, stages, links, small
+     * related things, lists and the brief. On one of their things it only adds (nothing is removed,
+     * renamed or retyped) and needs `base` from checkSetup() (without it, `validation`, server code
+     * `base_required`); if the thing changed since, it throws
+     * `conflict` (server code `changed`): check again. Only an Owner's key may apply (anyone else's
+     * throws `forbidden`, server code `owner_only`). Apply only what the owner agreed to.
+     *
+     * @example
+     * const { setup } = await db.proposeSetup('property bookings');
+     * const made = await db.applySetup(setup); // once the owner has agreed to checkSetup()'s sentence
+     * console.log(made.kind.key, made.land);
+     */
+    applySetup(setup: SetupSpec, options?: {
+        base?: SetupBase;
+        replaceBrief?: boolean;
+    }): Promise<SetupApplied>;
     /**
      * Create a record (returns its id), or change one with options.id. Every value is checked
      * against the kind. crm:write, Support Plus and above: the account's token, or an app key made
@@ -2666,6 +2709,132 @@ export interface LinkSpec {
     /** Every record must set it. Only when added to a kind with no records yet; a link is never made required later. */
     required?: boolean;
 }
+/** A field in a setup, in the owner's words. */
+export interface SetupField {
+    label: string;
+    type: 'text' | 'long_text' | 'number' | 'money' | 'date' | 'datetime' | 'yes_no' | 'choice' | 'choices' | 'address' | 'phone' | 'email' | 'url';
+    /** For choice and choices. */
+    choices?: string[];
+    required?: boolean;
+    /** Whether AI may read it. Leave names, notes and contact details off unless the owner says so. */
+    ai_may_read?: boolean;
+    /** A section's label. */
+    section?: string;
+}
+/**
+ * A setup: what an owner keeps track of, in their own words, never keys. `thing` is a new thing
+ * (`{label, label_plural?}`) or one of theirs to add to (`{kind}`). Limits: 6 sections, 15
+ * fields, 2 to 8 stages, 4 links, 2 related things of up to 6 fields, 3 lists of up to 12
+ * columns, a brief focus of up to 200 characters and 6 pins.
+ */
+export interface SetupSpec {
+    thing: {
+        label: string;
+        label_plural?: string;
+    } | {
+        kind: string;
+    };
+    sections?: Array<{
+        label: string;
+        description?: string;
+    }>;
+    fields?: SetupField[];
+    /** The stage field and its stages in order; `role` is a role on the business map, whose turn it is. */
+    stages?: {
+        field_label?: string;
+        stages: Array<{
+            name: string;
+            colour?: 'grey' | 'blue' | 'green' | 'amber' | 'red' | 'purple';
+            closed?: boolean;
+            role?: string;
+        }>;
+    } | null;
+    /** `to` is 'People', 'Companies' or one of the owner's things. */
+    links?: Array<{
+        to: string;
+        label?: string;
+        required?: boolean;
+    }>;
+    /** Small new things, each belonging to the main thing. */
+    new_related?: Array<{
+        label: string;
+        label_plural?: string;
+        fields?: SetupField[];
+        link_label?: string;
+    }>;
+    lists?: Array<{
+        name: string;
+        display: 'table' | 'board' | 'calendar' | 'week' | 'timeline';
+        group_by?: string;
+        date_field?: string;
+        columns?: string[];
+    }>;
+    /** What the summary at the top of each record leads with, and the fields pinned under it. */
+    brief?: {
+        focus?: string;
+        pins?: string[];
+    } | null;
+}
+/** What one of the owner's things has already, by the owner's labels. */
+export interface SetupMatched {
+    fields: string[];
+    links: string[];
+    stages: string[];
+    lists: string[];
+}
+/** The versions checkSetup() read a thing at; pass it to applySetup() as it came. */
+export type SetupBase = Record<string, unknown>;
+/** proposeSetup()'s answer. */
+export interface SetupProposal {
+    setup: SetupSpec;
+    /** What it would do, in plain words: show this to the owner. */
+    sentence: string;
+    /** How many suggested parts did not fit and were left out. */
+    dropped: number;
+    /** How many parts the thing has already (adding to one of theirs). */
+    already: number;
+    matched?: SetupMatched;
+    notes?: string[];
+    /** Set when the sentence named one of their things: the setup adds to it. */
+    adds_to?: {
+        key: string;
+        label: string;
+        label_plural: string;
+    };
+}
+/** checkSetup()'s answer. */
+export interface SetupCheck {
+    /** Exactly what applySetup() would do: the owner agrees to this. */
+    sentence: string;
+    setup: SetupSpec;
+    /** Whether this key may apply it (an Owner's). */
+    can_apply: boolean;
+    makes: {
+        key: string;
+        related: string[];
+        lists: number;
+        stages: number;
+        fields?: number;
+        links?: number;
+    };
+    matched?: SetupMatched;
+    notes?: string[];
+    /** Adding to one of theirs: true when there is nothing to add. */
+    nothing?: boolean;
+    base?: SetupBase;
+}
+/** applySetup()'s answer: the thing set up, its related things, and the list to open first. */
+export interface SetupApplied {
+    kind: {
+        key: string;
+        label_plural: string;
+    };
+    related: string[];
+    land: {
+        kind: string;
+        list?: string;
+    };
+}
 /** A kind to define: a table an app keeps. */
 export interface KindSpec {
     key: string;
@@ -3465,6 +3634,19 @@ export interface EmailSeriesWrite {
     pending?: true;
     job_id?: string;
 }
+/** What `emails.draft()` and `emails.update()` take. */
+export interface EmailDraftInput {
+    /** The list's key, from `emails.lists()`. */
+    topic: string;
+    doc: EmailDoc;
+    /**
+     * A proposed time it goes: a date and time on the business's own clock (`'2026-10-21T09:00'`) or an
+     * instant with its offset, a few minutes to 60 days ahead; `null` clears it. Only a proposal: the
+     * person who approves it in the hub confirms or changes the time. Needs scheduled emails on the
+     * account (`unavailable`, server code `feature_unavailable`, otherwise). A bad time saves nothing.
+     */
+    send_at?: string | null;
+}
 /** A draft, from `emails.draft()` or `emails.update()`. */
 export interface EmailDraft {
     id: string;
@@ -3483,6 +3665,13 @@ export interface EmailDraft {
     reviewUrl: string;
     /** What happens next, to tell the owner. */
     next: string;
+    /** The proposed time, when one was given and kept. */
+    send_at?: string | null;
+    send_tz?: string | null;
+    /** "Wed 21 Oct, 9:00 am (Sydney time)". */
+    send_when?: string | null;
+    /** Set when the draft was saved but the time given with it was not: why, in a sentence to pass on. */
+    send_at_refused?: string;
 }
 /** One email, from `emails.get()`. */
 export interface EmailDetail {
@@ -3504,6 +3693,12 @@ export interface EmailDetail {
     reviewUrl: string;
     /** Opens, clicks, bounces and replies over time, once sent; null when it could not be read. */
     timeline: unknown;
+    /** When it goes: a draft's proposed time, or the approved one. Null to go when approved. */
+    send_at?: string | null;
+    /** The same time in words, in the zone it was chosen in. */
+    send_when?: string | null;
+    /** Approved and waiting for its time. */
+    scheduled?: boolean;
 }
 /** `emails.discard()`: the draft is stopped and left out of the lists. */
 export interface EmailDiscarded {

package/dist/index.js

@@ -26,7 +26,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export const VERSION = '0.63.0';
+export const VERSION = '0.65.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 /** The one check for a platform `watch_url` (mirrored in the hub's awesomate-knowledge.ts and its MCP). */
 const WATCH_URL = /^https:\/\/[^\s"'<>]+$/i;
@@ -130,7 +130,8 @@ function errorCode(status, server, body = {}) {
         return 'rate_limited';
     // stale: a form or webinar changed since it was read (update with version). not_draft: a webinar's
     // registration is open, so it is fixed in Zoom. not_run: a recording goes only on a webinar that has run.
-    if (server === 'conflict' || server === 'stale' || server === 'not_draft' || server === 'not_run')
+    // changed: a thing a setup adds to changed since checkSetup().
+    if (server === 'conflict' || server === 'stale' || server === 'not_draft' || server === 'not_run' || server === 'changed')
         return 'conflict';
     if (status === 404 && server !== 'not_live')
         return 'not_found';
@@ -800,7 +801,10 @@ export class AwesomateClient {
                 return null;
             return nullIfMissing(this.request('GET', `/api/my-crm/v1/emails/${encodeURIComponent(String(id))}`));
         },
-        /** A new draft to list `topic` (a key from `lists()`). `checks.blockers` must be empty before a person can approve it. */
+        /**
+         * A new draft to list `topic` (a key from `lists()`). `checks.blockers` must be empty before a
+         * person can approve it. `send_at` proposes when it goes (see `EmailDraftInput`).
+         */
         draft: (input) => this.request('POST', '/api/my-crm/v1/emails', input, false),
         /** Replace a draft. Once someone approved it, it is refused: a person changes it in the hub. */
         update: async (id, input) => this.request('PATCH', `/api/my-crm/v1/emails/${emailId(id)}`, input, false),
@@ -1476,6 +1480,53 @@ export class AwesomateClient {
     async archiveLink(kind, key) {
         return (await this.request('DELETE', `/api/my-crm/v1/kinds/${encodeURIComponent(kind)}/links/${encodeURIComponent(key)}`, undefined, false)).kind;
     }
+    /**
+     * Set this up for me: the hub's suggestion for one sentence about what the owner keeps track of
+     * ("a job management system"), as a whole setup in the owner's words (fields, stages, lists,
+     * links, small related things, the brief). Nothing is saved. Pass `kind` to ask about one of
+     * their things: the suggestion then only adds to it, and `matched` says what it has already.
+     * Edit it if you like, then checkSetup(). The account's token, crm:write, Support Plus and above,
+     * with Set this up for me on the account; a few a person in ten minutes.
+     *
+     * @example
+     * const proposal = await db.proposeSetup('property bookings');
+     * console.log(proposal.sentence);
+     */
+    async proposeSetup(sentence, options = {}) {
+        return this.request('POST', '/api/my-crm/v1/setup/propose', { sentence, ...(options.kind ? { kind: options.kind } : {}) }, false);
+    }
+    /**
+     * Check a setup exactly as a click would, and read the sentence the owner should agree to before
+     * applySetup(). Nothing is saved. On one of their things it is additions only, and answers
+     * `base`, which applySetup() needs. A setup that does not fit throws `validation` naming the
+     * item (`at`, like `fields.2`). The account's token, crm:write.
+     *
+     * @example
+     * const proposal = await db.proposeSetup('a quote pipeline');
+     * const check = await db.checkSetup(proposal.setup);
+     * if (check.can_apply) console.log(check.sentence);
+     */
+    async checkSetup(setup, options = {}) {
+        return this.request('POST', '/api/my-crm/v1/setup/check', { setup, ...(options.replaceBrief ? { replace_brief: true } : {}) }, false);
+    }
+    /**
+     * Set it up, all in one go or not at all: the thing, its fields, sections, stages, links, small
+     * related things, lists and the brief. On one of their things it only adds (nothing is removed,
+     * renamed or retyped) and needs `base` from checkSetup() (without it, `validation`, server code
+     * `base_required`); if the thing changed since, it throws
+     * `conflict` (server code `changed`): check again. Only an Owner's key may apply (anyone else's
+     * throws `forbidden`, server code `owner_only`). Apply only what the owner agreed to.
+     *
+     * @example
+     * const { setup } = await db.proposeSetup('property bookings');
+     * const made = await db.applySetup(setup); // once the owner has agreed to checkSetup()'s sentence
+     * console.log(made.kind.key, made.land);
+     */
+    async applySetup(setup, options = {}) {
+        return this.request('POST', '/api/my-crm/v1/setup/apply', {
+            setup, ...(options.base ? { base: options.base } : {}), ...(options.replaceBrief ? { replace_brief: true } : {}),
+        }, false);
+    }
     /**
      * Create a record (returns its id), or change one with options.id. Every value is checked
      * against the kind. crm:write, Support Plus and above: the account's token, or an app key made

package/package.json

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