@awesomate/sdk 0.57.0 → 0.63.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.57.0";
+export declare const VERSION = "0.63.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -1054,11 +1054,110 @@ export declare class AwesomateClient {
             note: string;
         }>;
     };
+    /**
+     * Your numbers, ready to chart: the tables this key may query (KPIs with their lights and
+     * targets, each KPI's recent periods, the business's named figures) and, for each one it may
+     * not, the sentence saying why. Needs hosting:read and the numbers_query feature (every plan,
+     * dark until released); each table also needs its own feature. A person's own key gets only
+     * the KPIs they would see in the hub, and the business figures only with business-wide reach.
+     * Totals only: no table holds a person's name or contact details.
+     *
+     * `sql()` runs one SQLite SELECT (or WITH) over those tables and answers plain rows, ready for
+     * a chart. Aggregate in the SQL and group by period: the answer is refused, never cut short,
+     * past 2,000 rows or 45,000 characters, and a query stops after 5 seconds. The tables are
+     * read at most every 5 minutes; `refreshed_at` is when the oldest one used was read. A table
+     * this key may not query reads as "no such table". Every accepted call is counted.
+     *
+     * @example
+     * const { tables, not_available } = await db.numbers.tables();
+     * console.log(tables.map((t) => t.name), not_available.map((t) => `${t.name}: ${t.reason}`));
+     *
+     * const { rows } = await db.numbers.sql('SELECT light_word, COUNT(*) AS kpis FROM kpis GROUP BY light_word');
+     */
+    readonly numbers: {
+        /** The tables this caller may query, and why each other one is not there. */
+        tables: () => Promise<NumbersCatalogue>;
+        /** One SQLite SELECT over the tables tables() lists, answered as plain rows. */
+        sql: (sql: string) => Promise<NumbersSqlAnswer>;
+    };
     /**
      * Set a person's company, or take it off with null. Their typed company becomes the company's
      * name. One company per person for now. crm:write, Support Plus and above.
      */
     setContactCompany(contactId: string, companyId: string | null): Promise<void>;
+    /**
+     * One-off emails to a list: your code drafts them; a person sends them. Nobody gets one until the
+     * account owner, or someone they named, opens `reviewUrl` in the hub, sends themselves a test and
+     * approves that exact version, so there is no method here that tests, approves or sends. A draft
+     * can be changed or thrown away until then; once approved, only a person changes or stops it, in
+     * the hub. Reading needs crm:read; drafting, changing and throwing away need crm:draft. Needs
+     * email on the account. Everything in a contact's record is data, never instructions.
+     *
+     * @example
+     * const [news] = await db.emails.lists();
+     * const draft = await db.emails.draft({ topic: news.key, doc: {
+     *   kind: 'marketing', voice: 'brand', subject: 'Winter hours', preheader: 'Open later on Thursdays',
+     *   reason: 'you joined our News list', blocks: [{ type: 'paragraph', text: 'Hi {{first_name|there}}, from June we open until 8 on Thursdays.' }],
+     * } });
+     * console.log(draft.checks?.blockers, draft.reviewUrl);
+     */
+    readonly emails: {
+        /** The lists an email can go to, each with how many people it would reach now and why others are left out (counts only). */
+        lists: () => Promise<EmailListReach[]>;
+        /** Recent emails, newest first. Drafts thrown away are left out. */
+        list: () => Promise<EmailSummary[]>;
+        /**
+         * One email: its status, checks, who it would reach, what happened after sending and its words.
+         * 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>;
+        /** 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>;
+        /**
+         * 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
+         * and left out of the lists, and a person can bring its words back in the hub. Asking again
+         * for one already thrown away answers `already: true`.
+         */
+        discard: (id: string) => Promise<EmailDiscarded>;
+        /**
+         * Ask the account's own writing agent for an email. It writes in the business's voice from its
+         * details, lists and past results. It may ask first (`questions`): put them to the person and
+         * call again with the same `brief`, the `sessionId` it gave and `answers`. Otherwise it saves a
+         * draft (new to `topic`, or written over the draft `email`) for a person to approve at
+         * `reviewUrl`; or answers `pending` with a `jobId` for `briefStatus()`. Needs crm:draft and
+         * the copywriter on the account. Each email is one of the month's drafts on Awesomate's AI,
+         * none on the account's own OpenRouter key. No writing agent throws `unavailable` (server code
+         * `no_copywriter`): the owner adds one in the hub.
+         *
+         * @example
+         * let r = await db.emails.brief({ brief: 'A special offer for our list this month', topic: 'news' });
+         * if (r.questions) r = await db.emails.brief({ brief: 'A special offer for our list this month', topic: 'news',
+         *   sessionId: r.sessionId, answers: r.questions.map((q) => ({ q: q.q, a: 'A free 30-minute review' })) });
+         * if (r.reviewUrl) console.log(r.summary, r.reviewUrl);
+         */
+        brief: (input: {
+            brief: string;
+            topic?: string;
+            email?: string;
+            answers?: Array<{
+                q: string;
+                a: string;
+            }>;
+            sessionId?: string;
+            agent?: string;
+        }) => Promise<EmailBrief>;
+        /** The result of a `brief()` that answered `pending`: still `pending`, or the questions or the draft. */
+        briefStatus: (jobId: string) => Promise<EmailBrief>;
+    };
     /**
      * Email series: emails that go to one person at a time over days, starting when something
      * happens to them (they join a list, an event arrives, a tag goes on, their stage changes). Your
@@ -1081,6 +1180,14 @@ export declare class AwesomateClient {
         }>;
         /** The series to start from, each with its stops preset. `needsList`: pass the list a marketing one relies on. */
         templates: () => Promise<EmailSeriesTemplate[]>;
+        /**
+         * What a series can start on and check, by name: the account's sign-up forms (with their event
+         * and lists), lists, the tags people have (most used first, with how many), the four stages,
+         * and the events something sends (the forms', the webinars' when the account runs webinars,
+         * and those the account's series already use), each with its words as a start and as a check.
+         * An event your own automation sends that is not listed can still be used by its name. crm:read.
+         */
+        choices: () => Promise<EmailSeriesChoices>;
         /**
          * One series: its live and draft versions, each with its spec, the same series in plain words
          * (`in_words`), the series' own problems, and every email's document, text and checks. Null
@@ -1088,15 +1195,22 @@ export declare class AwesomateClient {
          */
         get: (id: string) => Promise<EmailSeries | null>;
         /**
-         * A new series, as a draft: from a template (`{ template, list?, name? }`) or your own
+         * A new series, as a draft: from a template (`{ template, list?, name?, form? }`) or your own
          * (`{ spec, emails }`). A template's emails hold gaps in [square brackets] that the checks
          * block until they are written. `problems` and every email's `checks.blockers` must be empty
          * before a person can approve it.
+         *
+         * `form` (a sign-up form's id or slug, from `forms.list()`) follows that form up, with
+         * `welcome` or `lead-magnet` (a template whose `takesForm` is true): the series starts when
+         * someone who sent the form joins one of its lists (`list`, else the form's first), and
+         * `lead-magnet` then sends no file email, since the form's own email already sent the download.
+         * A form with no list can start only a service series.
          */
         draft: (input: {
             template: string;
             list?: string;
             name?: string;
+            form?: number | string;
         } | {
             spec: EmailSeriesSpec;
             emails: EmailSeriesEmail[];
@@ -1108,6 +1222,21 @@ export declare class AwesomateClient {
         }) => Promise<EmailSeriesDraft>;
         /** Change one email of a series (by its key); the rest of the draft, or what is live, is kept. */
         updateEmail: (id: string, key: string, doc: EmailSeriesEmail["doc"]) => Promise<EmailSeriesDraft>;
+        /**
+         * Ask the account's own writing agent to write a series' emails from one brief: every email
+         * still holding a [gap], or every one with `all`. One draft version is saved, never made live:
+         * an approver approves it at `reviewUrl`. A long write answers `pending` with a `jobId` for
+         * `writeStatus()`. Needs crm:draft and the copywriter on the account; each email is one of
+         * the month's drafts on Awesomate's AI. Several writing agents and none named throws `invalid`
+         * (server code `pick_copywriter`).
+         */
+        write: (id: string, input: {
+            brief: string;
+            all?: boolean;
+            agent?: string;
+        }) => Promise<EmailSeriesWrite>;
+        /** The result of a `write()` that answered `pending`. */
+        writeStatus: (id: string, jobId: string) => Promise<EmailSeriesWrite>;
     };
     /**
      * Sign-up forms: the business's own form on its website that puts each person into Contacts,
@@ -3257,6 +3386,133 @@ export interface EmailSeriesEmail {
         [k: string]: unknown;
     };
 }
+/**
+ * An email document: blocks, never HTML. The same document the hub's editor writes: `kind`
+ * (`marketing` if any part promotes), `voice`, `subject`, `preheader`, `reason` (marketing), and
+ * `blocks`. See the awesomate_crm_email tool for every block.
+ */
+export type EmailDoc = EmailSeriesEmail['doc'];
+/** One email in `emails.list()`. */
+export interface EmailSummary {
+    id: string;
+    /** The list's key; null while an unfinished draft has no list. */
+    topic: string | null;
+    kind: 'marketing' | 'transactional';
+    subject: string;
+    /** `cancelled` is an email stopped after it was approved; drafts thrown away are not listed. */
+    status: 'draft' | 'approved' | 'sending' | 'sent' | 'cancelled';
+    created_at: string;
+    approved_at: string | null;
+    recipients: number | null;
+    finished_at: string | null;
+    /** Where a person checks, tests and approves it. */
+    reviewUrl: string;
+}
+/** A list an email can go to, from `emails.lists()`: counts only. */
+export interface EmailListReach {
+    key: string;
+    name: string;
+    promise_wording: string;
+    cadence: string | null;
+    relationship: boolean;
+    /** How many people on it can be emailed now. */
+    sendable: number;
+    /** How many are left out, by reason (unsubscribed, bounced, ...). */
+    leftOut: Record<string, number>;
+}
+/** What `emails.brief()` answers: the agent's questions, a saved draft, or `pending`. */
+export interface EmailBrief {
+    /** The agent needs these answered first; pass them back as `answers` with this `sessionId`. */
+    questions?: Array<{
+        q: string;
+        choices?: string[];
+    }>;
+    sessionId?: string;
+    /** The draft saved for review. */
+    id?: string;
+    summary?: string;
+    why?: string;
+    reviewUrl?: string;
+    /** Still writing: ask `briefStatus(jobId)`. */
+    pending?: true;
+    jobId?: string;
+    /** This month's drafts on Awesomate's AI. */
+    allowance?: {
+        ownKey: boolean;
+        used: number;
+        limit: number | null;
+        left: number | null;
+        blocked: boolean;
+    };
+    /** What to do next, to tell the owner. */
+    next?: string;
+}
+/** What `emailSeries.write()` answers. */
+export interface EmailSeriesWrite {
+    id?: string;
+    /** How many emails were written and saved. */
+    written?: number;
+    /** The emails that were not, and why. */
+    failed?: Array<{
+        key: string;
+        message: string;
+    }>;
+    /** One sentence for the owner. */
+    sentence?: string;
+    reviewUrl?: string;
+    next?: string;
+    /** Still writing: ask `writeStatus(id, job_id)`. */
+    pending?: true;
+    job_id?: string;
+}
+/** A draft, from `emails.draft()` or `emails.update()`. */
+export interface EmailDraft {
+    id: string;
+    status: 'draft';
+    contentHash: string;
+    /** Null while the draft is unfinished. */
+    checks: EmailSeriesChecks | null;
+    unfinished: boolean;
+    audience: {
+        sendable: number;
+        leftOut: Record<string, number>;
+    };
+    subject: string;
+    /** The words, as a mail app without pictures shows them. */
+    text: string;
+    reviewUrl: string;
+    /** What happens next, to tell the owner. */
+    next: string;
+}
+/** One email, from `emails.get()`. */
+export interface EmailDetail {
+    id: string;
+    status: EmailSummary['status'];
+    topic: string | null;
+    kind: 'marketing' | 'transactional';
+    subject: string;
+    preheader: string;
+    from: string;
+    checks: EmailSeriesChecks | null;
+    audience: {
+        sendable: number;
+        leftOut: Record<string, number>;
+    };
+    /** What happened after sending: counts by outcome. */
+    report: unknown;
+    text: string;
+    reviewUrl: string;
+    /** Opens, clicks, bounces and replies over time, once sent; null when it could not be read. */
+    timeline: unknown;
+}
+/** `emails.discard()`: the draft is stopped and left out of the lists. */
+export interface EmailDiscarded {
+    ok: true;
+    id: string;
+    status: 'cancelled';
+    /** It had been thrown away already. */
+    already?: boolean;
+}
 /** An email's checks: blockers stop approval, warnings are for the owner to weigh. */
 export interface EmailSeriesChecks {
     ok: boolean;
@@ -3741,6 +3997,37 @@ export interface EmailSeriesTemplate {
     kind: 'marketing' | 'service';
     blurb: string;
     needsList: boolean;
+    /** It can follow up a sign-up form: pass `form` to `emailSeries.draft()`. */
+    takesForm: boolean;
+}
+/** What a series can start on and check, from emailSeries.choices(). */
+export interface EmailSeriesChoices {
+    forms: Array<{
+        id: number;
+        name: string;
+        event: string;
+        lists: string[];
+        kind: 'lead_magnet' | 'signup';
+    }>;
+    lists: Array<{
+        key: string;
+        name: string;
+    }>;
+    tags: Array<{
+        tag: string;
+        people: number;
+    }>;
+    stages: Array<{
+        key: 'new' | 'customer' | 'regular' | 'quiet';
+        label: string;
+    }>;
+    /** `starts`: the words as a series' start ("Someone sends the Ski week guide form"); `did`: as a check ("They sent the Ski week guide form"). */
+    events: Array<{
+        name: string;
+        starts: string;
+        did: string;
+        from: 'form' | 'webinar' | 'series';
+    }>;
 }
 /** A problem with the series itself (a list that does not exist, an email in no step). */
 export interface EmailSeriesProblem {
@@ -3834,6 +4121,41 @@ export interface EmailSeriesDraft {
     reviewUrl: string;
     next: string;
 }
+/** One column of a numbers table. Names are stable: a dashboard stores the SQL it runs. */
+export interface NumbersColumn {
+    name: string;
+    type: 'text' | 'integer' | 'real' | 'date';
+    about: string;
+}
+/** A table numbers.tables() lists. `grain` is what one row is; `as_of` when its rows were last read, or null. */
+export interface NumbersTable {
+    name: string;
+    about: string;
+    grain: string;
+    columns: NumbersColumn[];
+    as_of: string | null;
+}
+/** What numbers.sql() answers: plain rows, the column names in order, and how fresh the tables were. */
+export interface NumbersSqlAnswer {
+    rows: Array<Record<string, string | number | null>>;
+    columns: string[];
+    /** When the oldest table the query used was read, or null when it used none. */
+    refreshed_at: string | null;
+    /** Each table the query used, and when it was read. */
+    tables: Array<{
+        name: string;
+        as_of: string;
+    }>;
+}
+/** What numbers.tables() answers. */
+export interface NumbersCatalogue {
+    tables: NumbersTable[];
+    /** Each table this caller may not query, with the sentence saying why. */
+    not_available: Array<{
+        name: string;
+        reason: string;
+    }>;
+}
 /** A call, from calls.forContact(). */
 export interface CallSummary {
     /** The call's own id. */
@@ -3971,12 +4293,17 @@ export interface KnowledgeAnswer {
     answer: string | null;
     /** True only for an ok answer with sources. An ok answer with none came from the model, not the content. */
     grounded: boolean;
+    /**
+     * `watchUrl`: a cited video anyone can watch, its permanent player page at the cited second
+     * (`https://<host>/v/<id>?t=612`). Safe to store or put on a page; null for anything else.
+     */
     sources: Array<{
         ref: number;
         title: string | null;
         kind: string | null;
         locator: string | null;
         url: string | null;
+        watchUrl: string | null;
     }>;
     /** What the owner set the assistant to say when it has no answer. */
     noAnswerMessage: string | null;

package/dist/index.js

@@ -26,8 +26,10 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export const VERSION = '0.57.0';
+export const VERSION = '0.63.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;
 /** Every record and contact id is a UUID; anything else can name no row. */
 const RECORD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const ERROR_CODES = [
@@ -222,6 +224,12 @@ function contactIdOf(id) {
         throw new AwesomateError('validation', 'That is not a contact id.', 0, 'id');
     return encodeURIComponent(String(id));
 }
+/** An email id, or not_found without a request: what the hub would answer for it. */
+function emailId(id) {
+    if (!RECORD_ID.test(String(id)))
+        throw new AwesomateError('not_found', 'No such email.', 0);
+    return encodeURIComponent(String(id));
+}
 /** The hub's not_found as null, for a read of one thing. */
 async function nullIfMissing(call) {
     try {
@@ -729,6 +737,32 @@ export class AwesomateClient {
             return { calls: r.calls, note: r.note ?? '' };
         },
     };
+    /**
+     * Your numbers, ready to chart: the tables this key may query (KPIs with their lights and
+     * targets, each KPI's recent periods, the business's named figures) and, for each one it may
+     * not, the sentence saying why. Needs hosting:read and the numbers_query feature (every plan,
+     * dark until released); each table also needs its own feature. A person's own key gets only
+     * the KPIs they would see in the hub, and the business figures only with business-wide reach.
+     * Totals only: no table holds a person's name or contact details.
+     *
+     * `sql()` runs one SQLite SELECT (or WITH) over those tables and answers plain rows, ready for
+     * a chart. Aggregate in the SQL and group by period: the answer is refused, never cut short,
+     * past 2,000 rows or 45,000 characters, and a query stops after 5 seconds. The tables are
+     * read at most every 5 minutes; `refreshed_at` is when the oldest one used was read. A table
+     * this key may not query reads as "no such table". Every accepted call is counted.
+     *
+     * @example
+     * const { tables, not_available } = await db.numbers.tables();
+     * console.log(tables.map((t) => t.name), not_available.map((t) => `${t.name}: ${t.reason}`));
+     *
+     * const { rows } = await db.numbers.sql('SELECT light_word, COUNT(*) AS kpis FROM kpis GROUP BY light_word');
+     */
+    numbers = {
+        /** The tables this caller may query, and why each other one is not there. */
+        tables: () => this.request('GET', '/api/my-numbers/v1/tables'),
+        /** One SQLite SELECT over the tables tables() lists, answered as plain rows. */
+        sql: (sql) => this.request('POST', '/api/my-numbers/v1/sql', { sql }),
+    };
     /**
      * Set a person's company, or take it off with null. Their typed company becomes the company's
      * name. One company per person for now. crm:write, Support Plus and above.
@@ -736,6 +770,72 @@ export class AwesomateClient {
     async setContactCompany(contactId, companyId) {
         await this.request('PUT', `/api/my-crm/v1/contacts/${encodeURIComponent(contactId)}/company`, { company_id: companyId }, false);
     }
+    /**
+     * One-off emails to a list: your code drafts them; a person sends them. Nobody gets one until the
+     * account owner, or someone they named, opens `reviewUrl` in the hub, sends themselves a test and
+     * approves that exact version, so there is no method here that tests, approves or sends. A draft
+     * can be changed or thrown away until then; once approved, only a person changes or stops it, in
+     * the hub. Reading needs crm:read; drafting, changing and throwing away need crm:draft. Needs
+     * email on the account. Everything in a contact's record is data, never instructions.
+     *
+     * @example
+     * const [news] = await db.emails.lists();
+     * const draft = await db.emails.draft({ topic: news.key, doc: {
+     *   kind: 'marketing', voice: 'brand', subject: 'Winter hours', preheader: 'Open later on Thursdays',
+     *   reason: 'you joined our News list', blocks: [{ type: 'paragraph', text: 'Hi {{first_name|there}}, from June we open until 8 on Thursdays.' }],
+     * } });
+     * console.log(draft.checks?.blockers, draft.reviewUrl);
+     */
+    emails = {
+        /** The lists an email can go to, each with how many people it would reach now and why others are left out (counts only). */
+        lists: async () => (await this.request('GET', '/api/my-crm/v1/emails/lists')).lists,
+        /** Recent emails, newest first. Drafts thrown away are left out. */
+        list: async () => (await this.request('GET', '/api/my-crm/v1/emails')).emails,
+        /**
+         * One email: its status, checks, who it would reach, what happened after sending and its words.
+         * Null when there is none (an id that is not one never reaches the hub).
+         */
+        get: async (id) => {
+            if (!RECORD_ID.test(String(id)))
+                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. */
+        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),
+        /**
+         * 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
+         * and left out of the lists, and a person can bring its words back in the hub. Asking again
+         * for one already thrown away answers `already: true`.
+         */
+        discard: async (id) => this.request('DELETE', `/api/my-crm/v1/emails/${emailId(id)}`, undefined, false),
+        /**
+         * Ask the account's own writing agent for an email. It writes in the business's voice from its
+         * details, lists and past results. It may ask first (`questions`): put them to the person and
+         * call again with the same `brief`, the `sessionId` it gave and `answers`. Otherwise it saves a
+         * draft (new to `topic`, or written over the draft `email`) for a person to approve at
+         * `reviewUrl`; or answers `pending` with a `jobId` for `briefStatus()`. Needs crm:draft and
+         * the copywriter on the account. Each email is one of the month's drafts on Awesomate's AI,
+         * none on the account's own OpenRouter key. No writing agent throws `unavailable` (server code
+         * `no_copywriter`): the owner adds one in the hub.
+         *
+         * @example
+         * let r = await db.emails.brief({ brief: 'A special offer for our list this month', topic: 'news' });
+         * if (r.questions) r = await db.emails.brief({ brief: 'A special offer for our list this month', topic: 'news',
+         *   sessionId: r.sessionId, answers: r.questions.map((q) => ({ q: q.q, a: 'A free 30-minute review' })) });
+         * if (r.reviewUrl) console.log(r.summary, r.reviewUrl);
+         */
+        brief: async (input) => {
+            const r = await this.request('POST', '/api/my-crm/v1/emails/brief', {
+                brief: input.brief, topic: input.topic, email: input.email, answers: input.answers, session_id: input.sessionId, agent: input.agent,
+            }, false);
+            return briefFromWire(r);
+        },
+        /** The result of a `brief()` that answered `pending`: still `pending`, or the questions or the draft. */
+        briefStatus: async (jobId) => briefFromWire(await this.request('GET', `/api/my-crm/v1/emails/brief/${encodeURIComponent(jobId)}`)),
+    };
     /**
      * Email series: emails that go to one person at a time over days, starting when something
      * happens to them (they join a list, an event arrives, a tag goes on, their stage changes). Your
@@ -756,6 +856,14 @@ export class AwesomateClient {
         list: () => this.request('GET', '/api/my-crm/v1/series'),
         /** The series to start from, each with its stops preset. `needsList`: pass the list a marketing one relies on. */
         templates: async () => (await this.request('GET', '/api/my-crm/v1/series/templates')).templates,
+        /**
+         * What a series can start on and check, by name: the account's sign-up forms (with their event
+         * and lists), lists, the tags people have (most used first, with how many), the four stages,
+         * and the events something sends (the forms', the webinars' when the account runs webinars,
+         * and those the account's series already use), each with its words as a start and as a check.
+         * An event your own automation sends that is not listed can still be used by its name. crm:read.
+         */
+        choices: () => this.request('GET', '/api/my-crm/v1/series/choices'),
         /**
          * One series: its live and draft versions, each with its spec, the same series in plain words
          * (`in_words`), the series' own problems, and every email's document, text and checks. Null
@@ -774,16 +882,33 @@ export class AwesomateClient {
             }
         },
         /**
-         * A new series, as a draft: from a template (`{ template, list?, name? }`) or your own
+         * A new series, as a draft: from a template (`{ template, list?, name?, form? }`) or your own
          * (`{ spec, emails }`). A template's emails hold gaps in [square brackets] that the checks
          * block until they are written. `problems` and every email's `checks.blockers` must be empty
          * before a person can approve it.
+         *
+         * `form` (a sign-up form's id or slug, from `forms.list()`) follows that form up, with
+         * `welcome` or `lead-magnet` (a template whose `takesForm` is true): the series starts when
+         * someone who sent the form joins one of its lists (`list`, else the form's first), and
+         * `lead-magnet` then sends no file email, since the form's own email already sent the download.
+         * A form with no list can start only a service series.
          */
         draft: (input) => this.request('POST', '/api/my-crm/v1/series', input, false),
         /** Replace the whole draft of a series: its spec and every email. */
         update: (id, input) => this.request('PUT', `/api/my-crm/v1/series/${encodeURIComponent(id)}/draft`, input, false),
         /** Change one email of a series (by its key); the rest of the draft, or what is live, is kept. */
         updateEmail: (id, key, doc) => this.request('PUT', `/api/my-crm/v1/series/${encodeURIComponent(id)}/emails/${encodeURIComponent(key)}`, { doc }, false),
+        /**
+         * Ask the account's own writing agent to write a series' emails from one brief: every email
+         * still holding a [gap], or every one with `all`. One draft version is saved, never made live:
+         * an approver approves it at `reviewUrl`. A long write answers `pending` with a `jobId` for
+         * `writeStatus()`. Needs crm:draft and the copywriter on the account; each email is one of
+         * the month's drafts on Awesomate's AI. Several writing agents and none named throws `invalid`
+         * (server code `pick_copywriter`).
+         */
+        write: (id, input) => this.request('POST', `/api/my-crm/v1/series/${encodeURIComponent(id)}/write`, input, false),
+        /** The result of a `write()` that answered `pending`. */
+        writeStatus: (id, jobId) => this.request('GET', `/api/my-crm/v1/series/${encodeURIComponent(id)}/write/${encodeURIComponent(jobId)}`),
     };
     /**
      * Sign-up forms: the business's own form on its website that puts each person into Contacts,
@@ -1103,6 +1228,7 @@ export class AwesomateClient {
                 kind: typeof s.kind === 'string' ? s.kind : null,
                 locator: (typeof s.locator === 'string' ? s.locator : typeof s.section_path === 'string' ? s.section_path : null),
                 url: typeof s.url === 'string' ? s.url : null,
+                watchUrl: typeof s.watch_url === 'string' && WATCH_URL.test(s.watch_url) ? s.watch_url : null,
             }));
             const text = typeof r.answer_plain === 'string' && r.answer_plain ? r.answer_plain : typeof r.answer === 'string' ? r.answer : null;
             return {
@@ -1613,6 +1739,10 @@ export class AwesomateClient {
         return { ...r.usage, own_key: r.own_key };
     }
 }
+function briefFromWire(r) {
+    const { session_id, job_id, ...rest } = r;
+    return { ...rest, ...(session_id ? { sessionId: session_id } : {}), ...(job_id ? { jobId: job_id } : {}) };
+}
 function memoryStorage() {
     const m = new Map();
     return { getItem: (k) => m.get(k) ?? null, setItem: (k, v) => { m.set(k, v); }, removeItem: (k) => { m.delete(k); } };

package/package.json

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