@awesomate/sdk 0.82.0 → 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.82.0";
+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
@@ -4786,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. */
@@ -4828,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 {
@@ -4841,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 {
@@ -4964,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 {
@@ -4980,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). */
@@ -5013,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.82.0';
+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

package/package.json

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