@awesomate/sdk 0.62.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.62.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 {
 }
@@ -1128,6 +1128,35 @@ export declare class AwesomateClient {
          * 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
@@ -1193,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,
@@ -3376,6 +3420,51 @@ export interface EmailListReach {
     /** 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;
@@ -4204,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.62.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 = [
@@ -809,6 +811,30 @@ export class AwesomateClient {
          * 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
@@ -872,6 +898,17 @@ export class AwesomateClient {
         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,
@@ -1191,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 {
@@ -1701,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.62.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",