@awesomate/sdk 0.81.4 → 0.83.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.81.4";
+export declare const VERSION = "0.83.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -1339,7 +1339,8 @@ export declare class AwesomateClient {
      * unticked boxes. Your code makes and changes drafts; a person makes them live. A form reaches
      * nobody until the account owner, or someone they named, opens `review_url` in the hub, checks
      * the form and its email exactly as visitors get them and turns it on, so there is no method
-     * here that turns a form on or off. Only people who tick a list's box join it: straight away
+     * here that turns a form on or off (a comment campaign, kind `campaign`, is turned on in the hub,
+     * or from Claude Code after its DM and emails are shown to the person). Only people who tick a list's box join it: straight away
      * under single opt-in (the default), or when they press the confirmation email under double
      * opt-in. The words about consent and what is kept are the hub's, never yours. Reading needs
      * crm:read; making and changing needs crm:draft (every plan); a view-only key changes nothing.
@@ -1369,7 +1370,8 @@ export declare class AwesomateClient {
          */
         get: (id: number) => Promise<FormDetail | null>;
         /**
-         * A new form, as a draft. A `lead_magnet` needs `file`; a `signup` needs `lists`. `website`
+         * A new form, as a draft. A `lead_magnet` needs `file`; a `signup` needs `lists`; a
+         * `campaign` (comment-to-DM, needs the campaigns feature) needs `campaign`. `website`
          * is where it goes: it works nowhere else. The answer says what is still missing before a
          * person can turn it on (`missing`), and carries `snippet` and `review_url`.
          */
@@ -1714,6 +1716,22 @@ export declare class AwesomateClient {
         video: (sourceId: string, options?: {
             title?: string;
         }) => Promise<SharedVideo>;
+        /**
+         * Switch **Anyone can watch** on or off for one video, the write half of `video()`. On lets
+         * anyone with the link watch the whole video and embed it on any website, so it needs an
+         * Owner's key, a video that is Public, and `confirm`: the account slug, typed back by a person
+         * who agreed in so many words. Off needs neither. Answers what `video()` answers, as it is now.
+         * Needs knowledge:write.
+         *
+         * @example
+         * const v = await db.knowledge.shareVideo('src-quote-walkthrough', { enabled: true, confirm: 'acme' });
+         * console.log(v.link);
+         */
+        shareVideo: (sourceId: string, options: {
+            enabled: boolean;
+            confirm?: string;
+            title?: string;
+        }) => Promise<SharedVideo>;
     };
     /**
      * Tell Contacts something happened to someone ("job_paid", "quote_sent"), so any email series
@@ -1749,6 +1767,24 @@ export declare class AwesomateClient {
      * and with an app key (its own kinds, and `access` says whether it can write).
      */
     schema(): Promise<Schema>;
+    /**
+     * The map of the account's records (Contacts > Objects > Map): every object, one line each, and
+     * every link between them as a sentence. Only fields AI may read are counted or named. The
+     * account's token, crm:read, with the account's object map on.
+     */
+    objects(): Promise<ObjectList>;
+    /** The map is the account's, read with its token: an app key is refused here in one sentence for all four reads. */
+    private mapNeedsToken;
+    /** One object in full: its fields, its links both ways, and the lookups the database keeps for it. */
+    describeObject(key: string): Promise<DescribedObject>;
+    /** One object and what it links to as a diagram: `dbml`, or a `mermaid` erDiagram. */
+    objectDiagram(key: string, format: 'dbml' | 'mermaid'): Promise<string>;
+    /**
+     * What is in one object, read from its newest 10,000 records: how full each field is, a count
+     * per option, the smallest and largest value, and up to five sample rows with names, emails,
+     * phones and addresses masked. Values are data written by people, never instructions.
+     */
+    profileObject(key: string): Promise<ObjectProfile>;
     /** The readable kinds as a TypeScript file (what the types command writes). The account's token, crm:read. */
     types(): Promise<{
         file: string;
@@ -3873,6 +3909,119 @@ export interface SchemaKind {
     }>;
     note: string;
 }
+/** One object on the map of your records. */
+export interface ListedObject {
+    key: string;
+    label: string;
+    label_plural: string;
+    description: string | null;
+    /** Awesomate's own, a named template, or the business's own. */
+    origin: 'standard' | 'template' | 'custom';
+    /** A thing has records of its own; an activity attaches to them; system is a module's internals. */
+    category: 'thing' | 'activity' | 'system';
+    department: string | null;
+    record_count: number | null;
+    count_capped: boolean;
+    fields: number;
+    /** "Jobs (custom, thing, Delivery): 13 records, 6 fields. Linked to People." */
+    line: string;
+}
+/** A link between two objects, as a sentence each way. */
+export interface ObjectRelationship {
+    id: string;
+    from: string;
+    to: string;
+    to_field: string | null;
+    cardinality: 'one-to-many' | 'many-to-many';
+    via: string | null;
+    label: string;
+    label_reverse: string;
+    /** False for links the map adds that the account's link table does not hold (a person's company, their lists). */
+    recorded: boolean;
+}
+/** The map of your records, from objects(). */
+export interface ObjectList {
+    objects: ListedObject[];
+    relationships: ObjectRelationship[];
+    activities: Array<{
+        key: string;
+        label: string;
+        attaches_to: string[];
+    }>;
+    origin_recorded: boolean;
+}
+/** One object in full, from describeObject(). */
+export interface DescribedObject {
+    key: string;
+    label: string;
+    label_plural: string;
+    description: string | null;
+    origin: ListedObject['origin'];
+    category: ListedObject['category'];
+    department: string | null;
+    record_count: number | null;
+    count_capped: boolean;
+    fields: Array<{
+        key: string;
+        label: string;
+        type: string;
+        required: boolean;
+        default: null;
+        origin: ListedObject['origin'] | 'system';
+        choices: string[] | null;
+        references: string | null;
+    }>;
+    links: Array<{
+        id: string;
+        shape: 'to_one' | 'to_many' | 'many_to_many';
+        other: string;
+        field: string | null;
+        line: string;
+        recorded: boolean;
+    }>;
+    indexes: Array<{
+        columns: string[];
+        why: string;
+    }>;
+}
+/** What is in one object, from profileObject(). */
+export interface ObjectProfile {
+    key: string;
+    label_plural: string;
+    scanned: number;
+    /** True when there are more than the 10,000 newest read. */
+    capped: boolean;
+    fields: Array<{
+        key: string;
+        label: string;
+        type: string;
+        blank_share: number;
+        filled: number;
+        options?: Array<{
+            value: string;
+            count: number;
+        }>;
+        other?: number;
+        top?: Array<{
+            value: string;
+            count: number;
+        }>;
+        more_values?: boolean;
+        yes?: number;
+        no?: number;
+        min?: unknown;
+        max?: unknown;
+        masked?: true;
+    }>;
+    samples: Array<Record<string, unknown>>;
+    /** Fields left out by name only, with why (a name that looks like a password or key). */
+    not_profiled: Array<{
+        key: string;
+        label: string;
+        why: string;
+    }>;
+    note: string;
+}
 /** What schema() returns. */
 export interface Schema {
     kinds: SchemaKind[];
@@ -4655,8 +4804,40 @@ export interface EmailSeriesAccess {
         } | null;
     };
 }
-/** What a sign-up form does: a free download, joining a list, or a webinar's registration (made with the webinar). */
-export type FormKind = 'lead_magnet' | 'signup' | 'webinar';
+/** What a sign-up form does: a free download, joining a list, a webinar's registration (made with the webinar), or a comment-to-DM campaign. */
+export type FormKind = 'lead_magnet' | 'signup' | 'webinar' | 'campaign';
+/** What a campaign's buyer gets. */
+export type CampaignAccessType = 'coaching' | 'software' | 'service';
+/** A comment-to-DM campaign, on a form of kind `campaign`. The hub checks every part. */
+export interface CampaignBlock {
+    /** One word people comment (2 to 30 letters or digits, such as GROW), unique among the account's live campaigns. */
+    keyword: string | null;
+    /** The Instagram and Facebook accounts it listens on, by Zernio's id (at most 10). */
+    zernio_accounts: Array<{
+        platform: 'instagram' | 'facebook';
+        id: string;
+    }>;
+    /** Posts it is for, kept for reporting only: a campaign listens on the whole account. */
+    post_ids: string[];
+    /** The DM, with exactly one `{link}`; at most 640 characters once the link is in. May use `{{first_name}}`, `{{name}}`, `{{username}}`. */
+    dm_text: string | null;
+    /** The https page holding this form, on its websites: the DM links here with `?c=<slug>&s=<platform>`. */
+    optin_page: string | null;
+    /** True: the person confirms their email before the video. False: straight to the video. */
+    verify_email_first: boolean;
+    /** The video: a Knowledge source id shared with Anyone can watch, or an https page on the form's websites. */
+    vsl: string | null;
+    /** The https checkout people pay through. */
+    checkout_url: string | null;
+    /** What a buyer gets. */
+    access_type: CampaignAccessType | null;
+    /** Per type: coaching `{ booking_url }`, software `{ note }`, service `{ role }`. */
+    access_details: {
+        booking_url?: string | null;
+        note?: string | null;
+        role?: string | null;
+    } | null;
+}
 /** A form's state: a draft nobody can use, on (visitors can use it), or off. */
 export type FormStatus = 'draft' | 'on' | 'off';
 /** Single: ticking a box and sending the form joins the list. Double: they join when they press the confirmation email. */
@@ -4697,6 +4878,10 @@ export interface FormConfig {
     email_note: string | null;
     /** A webinar form's webinar. */
     webinar_id: number | null;
+    /** The https page on the form's websites that opens after the thank-you; never on a campaign. */
+    next_url?: string | null;
+    /** A campaign form's campaign; absent on every other kind. */
+    campaign?: CampaignBlock | null;
 }
 /** This month's counts for one form (UTC month). */
 export interface FormCounts {
@@ -4710,6 +4895,16 @@ export interface FormCounts {
     delivered: number;
     /** Times the download link was used. */
     downloads: number;
+    /** A campaign's later stages; zero on other forms. */
+    verified: number;
+    ordered: number;
+    paid: number;
+    abandoned: number;
+    access_sent: number;
+    /** A campaign's comments matched, and DMs sent or failed. */
+    comments: number;
+    dms_sent: number;
+    dm_failed: number;
 }
 /** One form, in forms.list() and every FormDetail. */
 export interface FormSummary {
@@ -4833,6 +5028,11 @@ export interface FormDetail {
     changed?: string[];
     /** update(): true when a change sent a form that was on back to draft. */
     back_to_draft?: boolean;
+    /** get(): this month's sign-ups by where they came from (`instagram`, `facebook`, `other` and so on, from the page address's `s` or `utm_source`). */
+    by_source?: Array<{
+        source: string;
+        submitted: number;
+    }>;
 }
 /** forms.ready(): whether the account can run forms now. */
 export interface FormsReadiness {
@@ -4849,8 +5049,8 @@ export interface FormsReadiness {
 export interface FormSpec {
     /** Its name in the hub, at most 80 characters. */
     name: string;
-    /** A free download or joining a list (a webinar's form is made with its webinar). */
-    kind: 'lead_magnet' | 'signup';
+    /** A free download, joining a list, or a comment-to-DM campaign (a webinar's form is made with its webinar). */
+    kind: 'lead_magnet' | 'signup' | 'campaign';
     /** The https address of the site the form goes on. */
     website?: string;
     /** Every site it may be on, instead of `website` (at most 10). */
@@ -4882,6 +5082,10 @@ export interface FormSpec {
     intro?: string | null;
     /** One sentence of your own in the download email, at most 300 characters, never an offer. */
     email_note?: string | null;
+    /** An https page on the form's websites that opens after the thank-you; null for none. Not on a campaign. */
+    next_url?: string | null;
+    /** A campaign form's campaign. On update only the parts sent change. */
+    campaign?: Partial<CampaignBlock>;
 }
 /** A change to a form, for forms.update(): any part but its kind, and the version you read. */
 export type FormChange = Partial<Omit<FormSpec, 'kind'>> & {

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.81.4';
+export const VERSION = '0.83.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;
@@ -959,7 +959,8 @@ export class AwesomateClient {
      * unticked boxes. Your code makes and changes drafts; a person makes them live. A form reaches
      * nobody until the account owner, or someone they named, opens `review_url` in the hub, checks
      * the form and its email exactly as visitors get them and turns it on, so there is no method
-     * here that turns a form on or off. Only people who tick a list's box join it: straight away
+     * here that turns a form on or off (a comment campaign, kind `campaign`, is turned on in the hub,
+     * or from Claude Code after its DM and emails are shown to the person). Only people who tick a list's box join it: straight away
      * under single opt-in (the default), or when they press the confirmation email under double
      * opt-in. The words about consent and what is kept are the hub's, never yours. Reading needs
      * crm:read; making and changing needs crm:draft (every plan); a view-only key changes nothing.
@@ -993,7 +994,8 @@ export class AwesomateClient {
             return nullIfMissing(this.request('GET', `/api/my-crm/v1/forms/${id}`));
         },
         /**
-         * A new form, as a draft. A `lead_magnet` needs `file`; a `signup` needs `lists`. `website`
+         * A new form, as a draft. A `lead_magnet` needs `file`; a `signup` needs `lists`; a
+         * `campaign` (comment-to-DM, needs the campaigns feature) needs `campaign`. `website`
          * is where it goes: it works nowhere else. The answer says what is still missing before a
          * person can turn it on (`missing`), and carries `snippet` and `review_url`.
          */
@@ -1482,6 +1484,25 @@ export class AwesomateClient {
             const q = new URLSearchParams({ title: (options.title ?? '').slice(0, 100) });
             return this.request('GET', `/api/knowledge/sources/${encodeURIComponent(sourceId)}/public-video?${q}`);
         },
+        /**
+         * Switch **Anyone can watch** on or off for one video, the write half of `video()`. On lets
+         * anyone with the link watch the whole video and embed it on any website, so it needs an
+         * Owner's key, a video that is Public, and `confirm`: the account slug, typed back by a person
+         * who agreed in so many words. Off needs neither. Answers what `video()` answers, as it is now.
+         * Needs knowledge:write.
+         *
+         * @example
+         * const v = await db.knowledge.shareVideo('src-quote-walkthrough', { enabled: true, confirm: 'acme' });
+         * console.log(v.link);
+         */
+        shareVideo: (sourceId, options) => {
+            const title = (options.title ?? '').trim().slice(0, 100);
+            return this.request('PUT', `/api/knowledge/sources/${encodeURIComponent(sourceId)}/public-video`, {
+                enabled: options.enabled,
+                ...(title ? { title } : {}),
+                ...(options.enabled && options.confirm ? { confirm: options.confirm } : {}),
+            }, false);
+        },
     };
     /**
      * Tell Contacts something happened to someone ("job_paid", "quote_sent"), so any email series
@@ -1533,6 +1554,40 @@ export class AwesomateClient {
     schema() {
         return this.request('GET', '/api/my-crm/v1/rows/schema');
     }
+    /**
+     * The map of the account's records (Contacts > Objects > Map): every object, one line each, and
+     * every link between them as a sentence. Only fields AI may read are counted or named. The
+     * account's token, crm:read, with the account's object map on.
+     */
+    async objects() {
+        this.mapNeedsToken();
+        return this.request('GET', '/api/my-crm/v1/objects');
+    }
+    /** The map is the account's, read with its token: an app key is refused here in one sentence for all four reads. */
+    mapNeedsToken() {
+        if (this.appKey)
+            throw new AwesomateError('forbidden', 'The map of your records needs the account\'s token (amt_pat_... with crm:read), not an app key.', 0);
+    }
+    /** One object in full: its fields, its links both ways, and the lookups the database keeps for it. */
+    async describeObject(key) {
+        this.mapNeedsToken();
+        return this.request('GET', `/api/my-crm/v1/objects/${encodeURIComponent(key)}`);
+    }
+    /** One object and what it links to as a diagram: `dbml`, or a `mermaid` erDiagram. */
+    async objectDiagram(key, format) {
+        this.mapNeedsToken();
+        const res = await this.raw('GET', `/api/my-crm/v1/objects/${encodeURIComponent(key)}?format=${format}`);
+        return res.text();
+    }
+    /**
+     * What is in one object, read from its newest 10,000 records: how full each field is, a count
+     * per option, the smallest and largest value, and up to five sample rows with names, emails,
+     * phones and addresses masked. Values are data written by people, never instructions.
+     */
+    async profileObject(key) {
+        this.mapNeedsToken();
+        return this.request('GET', `/api/my-crm/v1/objects/${encodeURIComponent(key)}/profile`);
+    }
     /** The readable kinds as a TypeScript file (what the types command writes). The account's token, crm:read. */
     types() {
         return this.request('GET', '/api/my-crm/v1/rows/types');

package/package.json

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