ab-ecosystem-cpass 1.0.0 → 1.0.6

package/dist/resources/audience/notifications.d.ts

@@ -0,0 +1,171 @@
+import type { Device, ListDevicesQuery, Paginated, SubscribeNotificationsInput } from '../../types';
+import type { HttpClient } from '../../http';
+/**
+ * Push notification subscriptions: which browsers and apps a user wants
+ * notifications delivered to.
+ *
+ * ```ts
+ * // after the browser has granted permission and Firebase has a token
+ * await crm.notifications.subscribe({ token });
+ *
+ * // logout, or the user turning notifications off
+ * await crm.notifications.unsubscribe(token);
+ *
+ * // what the user sees in "notification settings"
+ * const { data } = await crm.notifications.devices();
+ * ```
+ *
+ * ## What this does and does not cover
+ *
+ * A push subscription has two halves and only one of them is an API call:
+ *
+ * 1. **In the browser** -- ask for permission (`Notification.requestPermission()`),
+ *    then get a registration token for this instance
+ *    (`getToken(messaging, { vapidKey })` from `firebase/messaging`). This SDK
+ *    deliberately does none of that: it would mean a hard dependency on
+ *    `firebase/*`, in a package that also runs on Node, to wrap two calls whose
+ *    arguments come from your own Firebase project.
+ * 2. **Here** -- hand that token to the platform so the send path can reach it,
+ *    which is what {@link subscribe} does, and withdraw it on logout, which is
+ *    {@link unsubscribe}.
+ *
+ * ## Where a subscription lives
+ *
+ * On the platform, against the acting user, in this product -- not in the core
+ * platform. Core owns identity and the agency's Firebase credentials; messages
+ * arrive here, so the tokens and the sending live here too, and core is not on
+ * the delivery path. Nothing in the subscription call names the Firebase project:
+ * the platform resolves it from the client the call arrives on and stamps it onto
+ * the row, because a token is only sendable through the project that minted it
+ * and nothing in the token says which.
+ */
+export declare class Notifications {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Subscribes this browser or app instance to notifications.
+     *
+     * ```http
+     * POST /v1/audience/devices
+     * authorization: Bearer <ecosystem token>
+     * client-id: tpc_8Kd3mXp7qR2wL9zB
+     * content-type: application/json
+     *
+     * {
+     *   "token": "fNx8...:APA91bH...",
+     *   "platform": "web",
+     *   "device_label": "Chrome on Windows",
+     *   "tpc_id": "tpc_8Kd3mXp7qR2wL9zB"
+     * }
+     * ```
+     *
+     * Answers `201` with the stored {@link Device}, token omitted. Of those four
+     * fields the SDK fills in two for you: `platform` defaults to `'web'` when it
+     * can see a DOM, and `device_label` to something like `Chrome on Windows` from
+     * the user agent.
+     *
+     * ## Call it on every app load, not once
+     *
+     * It is an idempotent upsert keyed on the token, so re-sending one the platform
+     * already holds costs a single indexed update. That is the intended usage,
+     * because two things change underneath you:
+     *
+     * - FCM rotates registration tokens on its own schedule, and the old one stops
+     *   being delivered to without anyone being told.
+     * - A device unseen for 60 days is pruned, and "seen" means a successful send
+     *   or a call to this method. A user who receives no notifications for two
+     *   months would otherwise fall off the list.
+     *
+     * Re-registering a token that is already on file against **another** user
+     * moves it rather than duplicating it: one browser has one person signed in,
+     * and the previous owner's notifications must stop reaching it the moment
+     * someone else logs in there.
+     *
+     * ## Identity
+     *
+     * The user comes from the verified token this client was built with, and there
+     * is no field that could say otherwise. `tpc_id` is the one tenant field
+     * accepted, because it is not an identity claim -- it says which reseller
+     * frontend is registering, which decides whose Firebase project and which deep
+     * link host apply. It is cross-checked against the verified `client-id`, so it
+     * can confirm the surface but never move the device to another tenant: a value
+     * that contradicts the token is refused with `403` rather than ignored.
+     *
+     * ## Failures worth handling
+     *
+     * - `400 validation_failed` -- the token is missing or implausible, or
+     *   `platform` could not be defaulted (see {@link SubscribeNotificationsInput}).
+     * - `403 forbidden` -- `tpc_id` names a different client than the token was
+     *   issued for.
+     * - `503 push_not_configured` -- the agency has no Firebase notification
+     *   resource set up. Nothing the caller can fix; notifications are simply off
+     *   for this account.
+     * - `503 push_unavailable` -- the platform could not reach core to read the
+     *   configuration. Transient.
+     *
+     * Both `503`s deserve the same handling as a successful call: try again on the
+     * next app load, which the advice above means you are doing anyway.
+     *
+     * Scope: `devices:write`.
+     */
+    subscribe(input: SubscribeNotificationsInput): Promise<Device>;
+    /**
+     * Stops notifications reaching one device. What logout calls.
+     *
+     * ```http
+     * POST /v1/audience/devices/unregister
+     * { "token": "fNx8...:APA91bH..." }
+     * ```
+     *
+     * `204`, no body, whether or not a row went -- the caller is asking for a
+     * guarantee about the future, and a token that is already gone provides it. So
+     * this is safe to call unconditionally on logout without first checking whether
+     * the device was ever subscribed.
+     *
+     * Scoped to the caller's own devices. A token identifies a browser rather than
+     * a person, so by the time one user logs out the row may already belong to
+     * whoever logged in after them; an unscoped delete would cut off the person now
+     * holding it.
+     *
+     * A `POST` with the token in the body, not `DELETE /devices/:token`: a
+     * registration token is hundreds of characters and may contain `:` and `/`, and
+     * putting one in a path would invite proxy length limits and write a live send
+     * credential into every access log on the way.
+     *
+     * ## Also delete it on the device
+     *
+     * This revokes the platform's permission to send to the token. If the user is
+     * turning notifications *off* -- rather than logging out -- also call
+     * `deleteToken(messaging)` in the browser, otherwise the next `getToken()`
+     * hands back the same token and the subscription can come back by accident.
+     *
+     * Scope: `devices:write`.
+     */
+    unsubscribe(token: string): Promise<void>;
+    /**
+     * The caller's own subscribed devices, newest contact first.
+     *
+     * ```http
+     * GET /v1/audience/devices?page=1&rows=25
+     * ```
+     *
+     * Offset paginated, `rows` 1..100 and default 25, sorted by `lastSeenAt`
+     * descending. This is what a "notification settings" screen lists, and the 20
+     * most recently seen devices are also the only ones a notification is sent to,
+     * so a longer list is itself the answer to "why did my old laptop stop
+     * buzzing".
+     *
+     * Only ever the acting user's own devices -- there is no account-wide view and
+     * no device id in the path. A device is one person's browser, and the only
+     * party with a reason to see or revoke it is that person.
+     *
+     * Tokens are not included, so this cannot tell you whether *this* browser is
+     * subscribed. Decide that locally: the browser knows its own
+     * `Notification.permission` and its own token, and {@link subscribe} being
+     * idempotent means the cheap answer to "am I still subscribed" is to subscribe
+     * again.
+     *
+     * Scope: `devices:read`.
+     */
+    devices(query?: Partial<ListDevicesQuery>): Promise<Paginated<Device>>;
+}

package/dist/resources/audience/notifications.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Notifications = void 0;
+const errors_1 = require("../../errors");
+const device_1 = require("../../internal/device");
+const paths_1 = require("../paths");
+const BASE = `${paths_1.AUDIENCE}/devices`;
+/** The bounds the server applies, checked here so a bad token fails without a round trip. */
+const TOKEN_LENGTH = { min: 20, max: 4096 };
+/** What the server accepts as a label, so a long one is trimmed rather than refused. */
+const MAX_LABEL = 200;
+/**
+ * Push notification subscriptions: which browsers and apps a user wants
+ * notifications delivered to.
+ *
+ * ```ts
+ * // after the browser has granted permission and Firebase has a token
+ * await crm.notifications.subscribe({ token });
+ *
+ * // logout, or the user turning notifications off
+ * await crm.notifications.unsubscribe(token);
+ *
+ * // what the user sees in "notification settings"
+ * const { data } = await crm.notifications.devices();
+ * ```
+ *
+ * ## What this does and does not cover
+ *
+ * A push subscription has two halves and only one of them is an API call:
+ *
+ * 1. **In the browser** -- ask for permission (`Notification.requestPermission()`),
+ *    then get a registration token for this instance
+ *    (`getToken(messaging, { vapidKey })` from `firebase/messaging`). This SDK
+ *    deliberately does none of that: it would mean a hard dependency on
+ *    `firebase/*`, in a package that also runs on Node, to wrap two calls whose
+ *    arguments come from your own Firebase project.
+ * 2. **Here** -- hand that token to the platform so the send path can reach it,
+ *    which is what {@link subscribe} does, and withdraw it on logout, which is
+ *    {@link unsubscribe}.
+ *
+ * ## Where a subscription lives
+ *
+ * On the platform, against the acting user, in this product -- not in the core
+ * platform. Core owns identity and the agency's Firebase credentials; messages
+ * arrive here, so the tokens and the sending live here too, and core is not on
+ * the delivery path. Nothing in the subscription call names the Firebase project:
+ * the platform resolves it from the client the call arrives on and stamps it onto
+ * the row, because a token is only sendable through the project that minted it
+ * and nothing in the token says which.
+ */
+class Notifications {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Subscribes this browser or app instance to notifications.
+     *
+     * ```http
+     * POST /v1/audience/devices
+     * authorization: Bearer <ecosystem token>
+     * client-id: tpc_8Kd3mXp7qR2wL9zB
+     * content-type: application/json
+     *
+     * {
+     *   "token": "fNx8...:APA91bH...",
+     *   "platform": "web",
+     *   "device_label": "Chrome on Windows",
+     *   "tpc_id": "tpc_8Kd3mXp7qR2wL9zB"
+     * }
+     * ```
+     *
+     * Answers `201` with the stored {@link Device}, token omitted. Of those four
+     * fields the SDK fills in two for you: `platform` defaults to `'web'` when it
+     * can see a DOM, and `device_label` to something like `Chrome on Windows` from
+     * the user agent.
+     *
+     * ## Call it on every app load, not once
+     *
+     * It is an idempotent upsert keyed on the token, so re-sending one the platform
+     * already holds costs a single indexed update. That is the intended usage,
+     * because two things change underneath you:
+     *
+     * - FCM rotates registration tokens on its own schedule, and the old one stops
+     *   being delivered to without anyone being told.
+     * - A device unseen for 60 days is pruned, and "seen" means a successful send
+     *   or a call to this method. A user who receives no notifications for two
+     *   months would otherwise fall off the list.
+     *
+     * Re-registering a token that is already on file against **another** user
+     * moves it rather than duplicating it: one browser has one person signed in,
+     * and the previous owner's notifications must stop reaching it the moment
+     * someone else logs in there.
+     *
+     * ## Identity
+     *
+     * The user comes from the verified token this client was built with, and there
+     * is no field that could say otherwise. `tpc_id` is the one tenant field
+     * accepted, because it is not an identity claim -- it says which reseller
+     * frontend is registering, which decides whose Firebase project and which deep
+     * link host apply. It is cross-checked against the verified `client-id`, so it
+     * can confirm the surface but never move the device to another tenant: a value
+     * that contradicts the token is refused with `403` rather than ignored.
+     *
+     * ## Failures worth handling
+     *
+     * - `400 validation_failed` -- the token is missing or implausible, or
+     *   `platform` could not be defaulted (see {@link SubscribeNotificationsInput}).
+     * - `403 forbidden` -- `tpc_id` names a different client than the token was
+     *   issued for.
+     * - `503 push_not_configured` -- the agency has no Firebase notification
+     *   resource set up. Nothing the caller can fix; notifications are simply off
+     *   for this account.
+     * - `503 push_unavailable` -- the platform could not reach core to read the
+     *   configuration. Transient.
+     *
+     * Both `503`s deserve the same handling as a successful call: try again on the
+     * next app load, which the advice above means you are doing anyway.
+     *
+     * Scope: `devices:write`.
+     */
+    subscribe(input) {
+        const token = (input.token ?? '').trim();
+        if (token.length < TOKEN_LENGTH.min || token.length > TOKEN_LENGTH.max) {
+            throw new errors_1.CrmApiError(400, 'validation_failed', `token must be a Firebase registration token of ${TOKEN_LENGTH.min}..${TOKEN_LENGTH.max} characters`);
+        }
+        const platform = input.platform ?? (0, device_1.detectPlatform)();
+        if (!platform) {
+            // Not defaulted to 'web' outside a browser on purpose: a mobile runtime
+            // registered as web gets the webpush half of the payload, which FCM
+            // accepts and the device never displays.
+            throw new errors_1.CrmApiError(400, 'validation_failed', 'platform is required outside a browser: pass "android", "ios", or "web" explicitly');
+        }
+        const label = (input.device_label ?? (0, device_1.describeDevice)() ?? '').trim().slice(0, MAX_LABEL);
+        return this.http.request('POST', BASE, {
+            body: {
+                token,
+                platform,
+                // Both omitted when empty rather than sent as '': the server treats an
+                // absent optional and an empty one the same way, and a body carrying only
+                // what it means is easier to read in a log.
+                ...(label ? { device_label: label } : {}),
+                ...(input.tpc_id ? { tpc_id: input.tpc_id.trim() } : {}),
+            },
+        });
+    }
+    /**
+     * Stops notifications reaching one device. What logout calls.
+     *
+     * ```http
+     * POST /v1/audience/devices/unregister
+     * { "token": "fNx8...:APA91bH..." }
+     * ```
+     *
+     * `204`, no body, whether or not a row went -- the caller is asking for a
+     * guarantee about the future, and a token that is already gone provides it. So
+     * this is safe to call unconditionally on logout without first checking whether
+     * the device was ever subscribed.
+     *
+     * Scoped to the caller's own devices. A token identifies a browser rather than
+     * a person, so by the time one user logs out the row may already belong to
+     * whoever logged in after them; an unscoped delete would cut off the person now
+     * holding it.
+     *
+     * A `POST` with the token in the body, not `DELETE /devices/:token`: a
+     * registration token is hundreds of characters and may contain `:` and `/`, and
+     * putting one in a path would invite proxy length limits and write a live send
+     * credential into every access log on the way.
+     *
+     * ## Also delete it on the device
+     *
+     * This revokes the platform's permission to send to the token. If the user is
+     * turning notifications *off* -- rather than logging out -- also call
+     * `deleteToken(messaging)` in the browser, otherwise the next `getToken()`
+     * hands back the same token and the subscription can come back by accident.
+     *
+     * Scope: `devices:write`.
+     */
+    unsubscribe(token) {
+        const value = (token ?? '').trim();
+        if (!value)
+            throw new errors_1.CrmApiError(400, 'validation_failed', 'token is required');
+        return this.http.request('POST', `${BASE}/unregister`, { body: { token: value } });
+    }
+    /**
+     * The caller's own subscribed devices, newest contact first.
+     *
+     * ```http
+     * GET /v1/audience/devices?page=1&rows=25
+     * ```
+     *
+     * Offset paginated, `rows` 1..100 and default 25, sorted by `lastSeenAt`
+     * descending. This is what a "notification settings" screen lists, and the 20
+     * most recently seen devices are also the only ones a notification is sent to,
+     * so a longer list is itself the answer to "why did my old laptop stop
+     * buzzing".
+     *
+     * Only ever the acting user's own devices -- there is no account-wide view and
+     * no device id in the path. A device is one person's browser, and the only
+     * party with a reason to see or revoke it is that person.
+     *
+     * Tokens are not included, so this cannot tell you whether *this* browser is
+     * subscribed. Decide that locally: the browser knows its own
+     * `Notification.permission` and its own token, and {@link subscribe} being
+     * idempotent means the cheap answer to "am I still subscribed" is to subscribe
+     * again.
+     *
+     * Scope: `devices:read`.
+     */
+    devices(query = {}) {
+        return this.http.request('GET', BASE, { query });
+    }
+}
+exports.Notifications = Notifications;
+//# sourceMappingURL=notifications.js.map

package/dist/resources/audience/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../../src/resources/audience/notifications.ts"],"names":[],"mappings":";;;AAEA,yCAA2C;AAC3C,kDAAuE;AACvE,oCAAoC;AAEpC,MAAM,IAAI,GAAG,GAAG,gBAAQ,UAAU,CAAC;AAEnC,6FAA6F;AAC7F,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AAE5C,wFAAwF;AACxF,MAAM,SAAS,GAAG,GAAG,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAa,aAAa;IACK;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiEG;IACH,SAAS,CAAC,KAAkC;QAC1C,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAEzC,IAAI,KAAK,CAAC,MAAM,GAAG,YAAY,CAAC,GAAG,IAAI,KAAK,CAAC,MAAM,GAAG,YAAY,CAAC,GAAG,EAAE,CAAC;YACvE,MAAM,IAAI,oBAAW,CACnB,GAAG,EACH,mBAAmB,EACnB,kDAAkD,YAAY,CAAC,GAAG,KAAK,YAAY,CAAC,GAAG,aAAa,CACrG,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAA,uBAAc,GAAE,CAAC;QAEpD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,wEAAwE;YACxE,oEAAoE;YACpE,yCAAyC;YACzC,MAAM,IAAI,oBAAW,CACnB,GAAG,EACH,mBAAmB,EACnB,oFAAoF,CACrF,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,YAAY,IAAI,IAAA,uBAAc,GAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QAExF,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAS,MAAM,EAAE,IAAI,EAAE;YAC7C,IAAI,EAAE;gBACJ,KAAK;gBACL,QAAQ;gBACR,uEAAuE;gBACvE,0EAA0E;gBAC1E,4CAA4C;gBAC5C,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACzC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACzD;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,WAAW,CAAC,KAAa;QACvB,MAAM,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAEnC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,oBAAW,CAAC,GAAG,EAAE,mBAAmB,EAAE,mBAAmB,CAAC,CAAC;QAEjF,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAO,MAAM,EAAE,GAAG,IAAI,aAAa,EAAE,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,QAAmC,EAAE;QAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAoB,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACtE,CAAC;CACF;AAhLD,sCAgLC"}

package/dist/resources/audience/scheduled-messages.d.ts

@@ -0,0 +1,234 @@
+import type { CancelSeriesResult, CreateRepeatingScheduleInput, CreateScheduledMessageInput, CreateScheduledSeriesInput, ListScheduledMessagesQuery, Paginated, RescheduleMessageInput, ScheduledMessage, ScheduledMessageSeries } from '../../types';
+import type { HttpClient } from '../../http';
+/**
+ * Scheduled messages: a send with a time, and optionally a condition checked
+ * immediately before it goes out.
+ *
+ * ### What the condition is for
+ *
+ * A drip is easy to start and awkward to stop. Schedule five messages over two
+ * weeks, your lead converts after the third, and the last two still go out --
+ * now addressed to a customer, as a pitch. Cancelling them means somebody
+ * noticing in time.
+ *
+ * So each occurrence re-reads the contact a moment before sending and stands
+ * down if they no longer match. Keep a `stage` custom field on your contacts,
+ * condition the series on `stage equal to Lead`, and set `stage` to `Customer`
+ * when they convert: the rest of the sequence cancels itself. No cancellation
+ * call, no scheduled-message ids to track.
+ *
+ * ```ts
+ * const nurture = await crm.scheduledMessages.createSeries({
+ *   title: 'Lead nurture',
+ *   channel: channelId,
+ *   contact: { id: contactId },
+ *   timezone: 'Asia/Kolkata',
+ *   starts_at: '2026-10-13T10:00:00',
+ *   conditions: {
+ *     conditions: [
+ *       { field_id: 'stage', field_type: 'dropdown', condition: 'equal to', value: 'Lead' },
+ *     ],
+ *   },
+ *   on_condition_fail: 'cancel_series',
+ *   steps: [
+ *     { after: { value: 0, unit: 'days' }, content: intro },
+ *     { after: { value: 3, unit: 'days' }, content: caseStudy },
+ *     { after: { value: 6, unit: 'days' }, content: pricing },
+ *   ],
+ * });
+ *
+ * // Later, when the lead converts -- this is the whole of "stop the drip":
+ * await crm.contacts.update(contactId, { custom_field_hash: { stage: 'Customer' } });
+ * ```
+ *
+ * ### Two things that will catch you out
+ *
+ * **Templates, not free text.** WhatsApp only allows free-form messages within
+ * 24 hours of the contact's last inbound message, and a drip is by construction
+ * outside that window from the second message onward. Every step but the first
+ * has to be an approved template or the provider refuses it; `create` rejects
+ * free text past the window rather than letting you discover it on day four.
+ *
+ * **A series is expanded, not recurring.** `createSeries` writes one row per
+ * message straight away, so you can list them, move one, or cancel one without
+ * touching the others. There is no rule being evaluated later and nothing to
+ * recompute -- which is also why `until` has to be a real end rather than
+ * "forever".
+ *
+ * Scoping: scheduled messages belong to an account the same way contacts do --
+ * reads match the caller or the account they act for, writes land on the
+ * caller's own.
+ */
+export declare class ScheduledMessages {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * `GET /v1/audience/scheduled-messages` -- offset paginated, soonest first
+     * among `pending`, newest first among the rest. `search` matches the title.
+     *
+     * Narrow it with `contact` for one person's queue, `series` for one drip's
+     * occurrences, or `status` to answer "what is still waiting" (`pending`)
+     * versus "what stood down and why" (`skipped`).
+     *
+     * Scope: `messages:read`.
+     */
+    list(query?: Partial<ListScheduledMessagesQuery>): Promise<Paginated<ScheduledMessage>>;
+    /**
+     * `GET /v1/audience/scheduled-messages/:id` -- one occurrence, with its
+     * `result` if it has reached a terminal status.
+     *
+     * Scope: `messages:read`.
+     */
+    get(id: string): Promise<ScheduledMessage>;
+    /**
+     * `POST /v1/audience/scheduled-messages` -- 201 with the created occurrence.
+     *
+     * One message, one time. `series` on the response is `null` and `occurrence`
+     * is `1`.
+     *
+     * ```ts
+     * await crm.scheduledMessages.create({
+     *   title: 'Pricing follow-up',
+     *   channel: channelId,
+     *   contact: { id: contactId },
+     *   timezone: 'Asia/Kolkata',
+     *   scheduled_at: '2026-10-15T10:00:00',   // 10:00 IST
+     *   content: { type: 'text', text: { body: 'Following up on the pricing.' } },
+     *   conditions: {
+     *     conditions: [
+     *       { field_id: 'stage', field_type: 'dropdown', condition: 'equal to', value: 'Lead' },
+     *     ],
+     *   },
+     * });
+     * ```
+     *
+     * `on_condition_fail` defaults to `skip` here, which for a single message is
+     * the only reading that means anything -- there is no series to cancel.
+     *
+     * 422 if `scheduled_at` is in the past, if `timezone` is not an IANA zone, if
+     * the condition names a field type the comparison cannot apply to, or if the
+     * message is free text and the send falls outside the channel's reply window.
+     *
+     * Scope: `messages:write`.
+     */
+    create(input: CreateScheduledMessageInput): Promise<ScheduledMessage>;
+    /**
+     * `POST /v1/audience/scheduled-messages/series` -- 201 with the series and
+     * every occurrence it expanded into.
+     *
+     * For a sequence whose steps carry different copy. `after` is measured from
+     * `starts_at`, not from the previous step, so changing one delay leaves the
+     * others where they were.
+     *
+     * ```ts
+     * const series = await crm.scheduledMessages.createSeries({
+     *   title: 'Lead nurture -- 2 weeks',
+     *   channel: channelId,
+     *   contact: { id: contactId },
+     *   timezone: 'Asia/Kolkata',
+     *   starts_at: '2026-10-13T10:00:00',
+     *   conditions: { conditions: [stillALead] },
+     *   steps: [
+     *     { after: { value: 0,  unit: 'days' }, content: intro },
+     *     { after: { value: 3,  unit: 'days' }, content: caseStudy },
+     *     { after: { value: 6,  unit: 'days' }, content: pricing },
+     *     { after: { value: 9,  unit: 'days' }, content: demo },
+     *     { after: { value: 12, unit: 'days' }, content: lastCall },
+     *   ],
+     * });
+     *
+     * series.occurrences.length; // 5
+     * ```
+     *
+     * A step may carry its own `conditions`, which are checked **in addition to**
+     * the series' -- both have to pass. Leave them out to inherit.
+     *
+     * `on_condition_fail` defaults to `cancel_series`.
+     *
+     * Scope: `messages:write`.
+     */
+    createSeries(input: CreateScheduledSeriesInput): Promise<ScheduledMessageSeries>;
+    /**
+     * `POST /v1/audience/scheduled-messages/series` -- the same route, for the
+     * case where every occurrence sends the same message.
+     *
+     * ```ts
+     * await crm.scheduledMessages.createRepeating({
+     *   title: 'Weekly check-in',
+     *   channel: channelId,
+     *   contact: { id: contactId },
+     *   timezone: 'Asia/Kolkata',
+     *   starts_at: '2026-10-13T10:00:00',
+     *   repeat: { every: 3, unit: 'days', until: '2026-10-27T10:00:00' },
+     *   content: nudgeTemplate,
+     *   conditions: { conditions: [stillALead] },
+     * });
+     * ```
+     *
+     * `until` is inclusive and has to be a real end: the expansion is written as
+     * rows, so an open-ended cadence has nothing to expand into. The result is the
+     * same `ScheduledMessageSeries` as `createSeries` -- once created, a repeating
+     * schedule and a stepped one are indistinguishable.
+     *
+     * 422 if the expansion would exceed 365 occurrences.
+     *
+     * Scope: `messages:write`.
+     */
+    createRepeating(input: CreateRepeatingScheduleInput): Promise<ScheduledMessageSeries>;
+    /**
+     * `PATCH /v1/audience/scheduled-messages/:id` -- moves one occurrence.
+     *
+     * Only a `pending` one. Rescheduling something already `sent`, `skipped` or
+     * `cancelled` is a 409 rather than a silent no-op -- legacy answered
+     * `{ success: true }` either way, which made a failed reschedule look like a
+     * successful one.
+     *
+     * Moving one occurrence does not move the rest of its series.
+     *
+     * ```ts
+     * await crm.scheduledMessages.reschedule(id, { scheduled_at: '2026-10-16T14:00:00' });
+     * ```
+     *
+     * Scope: `messages:write`.
+     */
+    reschedule(id: string, input: RescheduleMessageInput): Promise<ScheduledMessage>;
+    /**
+     * `DELETE /v1/audience/scheduled-messages/:id` -- 200 with the cancelled row.
+     *
+     * The row is kept rather than deleted, at `status: 'cancelled'`, so a schedule
+     * that did not send still shows why. Use `cancelSeries` to stop a whole drip;
+     * this stops one message and leaves the others queued.
+     *
+     * Scope: `messages:write`.
+     */
+    cancel(id: string): Promise<ScheduledMessage>;
+    /**
+     * `DELETE /v1/audience/scheduled-messages/series/:series` -- 200 with the
+     * number of occurrences stood down.
+     *
+     * Cancels every `pending` occurrence; anything already sent is untouched and
+     * not counted. Idempotent -- a second call cancels nothing and answers `0`.
+     *
+     * Usually you do not need this. If the series carries a condition, changing
+     * the contact so it no longer matches is the better way to stop a drip: it
+     * leaves the reason on the record, and it works for every contact in the same
+     * sequence rather than one series at a time.
+     *
+     * Scope: `messages:write`.
+     */
+    cancelSeries(series: string): Promise<CancelSeriesResult>;
+    /**
+     * `POST /v1/audience/scheduled-messages/:id/send-now` -- 200 with the row.
+     *
+     * Brings a `pending` occurrence forward to immediately. The condition is still
+     * checked, because the condition is the point -- a send-now on a contact who
+     * no longer matches comes back `skipped`, not `sent`.
+     *
+     * It does not duplicate: the occurrence is moved, not copied, so the original
+     * time no longer fires. Legacy's equivalent scheduled a second job without
+     * cancelling the first and delivered the message twice.
+     *
+     * Scope: `messages:write`.
+     */
+    sendNow(id: string): Promise<ScheduledMessage>;
+}