ab-ecosystem-cpass 1.0.5 → 1.0.7

package/dist/resources/campaign-messages.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CampaignMessages = void 0;
+const BASE = '/v1/campaign-messages';
+/**
+ * Campaign reporting: what actually happened to each message.
+ *
+ * ```ts
+ * const stats = await crm.campaignMessages.stats({ campaign });
+ * // { total: 12480, sent: 12410, delivered: 11980, read: 7420, replied: 310, failed: 70 }
+ *
+ * const { data } = await crm.campaignMessages.list({ campaign, status: 'failed' });
+ * data[0].error; // why that one did not go
+ * ```
+ *
+ * ## Where these numbers come from
+ *
+ * One row per attempted send, written by the campaign manager as it hands each
+ * message to a channel, with its `status` moved forward by the channel's
+ * delivery webhooks -- which are processed outside the CRM entirely. The report
+ * is **counted off those rows when you ask for it**, not rolled up on a
+ * schedule, so there is no "generated at" to reason about and no staleness
+ * window: the numbers are as current as the webhooks that have arrived.
+ *
+ * The flip side is that a campaign still going out has moving numbers. Reading
+ * `stats` seconds after launching under-counts everything, and that is correct
+ * rather than a lag.
+ *
+ * ## The funnel
+ *
+ * `status` is a single field holding the furthest stage reached, so the counts
+ * are cumulative and nest: `replied ⊆ read ⊆ delivered ⊆ sent`. For a stage's
+ * exclusive count, subtract the next one -- `delivered - read` is "delivered but
+ * unread". `failed` is outside the funnel and never inside `sent`.
+ *
+ * ## There is no export endpoint
+ *
+ * An export is {@link list} written to a file, so {@link iterate} does the
+ * paging and the caller formats the rows. Nothing is queued, nothing has to be
+ * polled, and no generated file expires before someone downloads it.
+ */
+class CampaignMessages {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * The campaign's funnel counts.
+     *
+     * `GET /v1/campaign-messages/stats?campaign=<id>` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Required | Notes |
+     * | --- | --- | --- | --- |
+     * | `campaign` | string | yes | The campaign id. |
+     * | `message` | number | no | One message of a multi-message campaign, zero-based. |
+     *
+     * ```ts
+     * const overall = await crm.campaignMessages.stats({ campaign });
+     * const second = await crm.campaignMessages.stats({ campaign, message: 1 });
+     * ```
+     *
+     * No date window: a campaign is one send, so its whole life is the only
+     * meaningful window. A repeating campaign's runs are separate campaigns with
+     * their own ids.
+     *
+     * `404 not_found` if the campaign is not the caller's -- the same answer as a
+     * campaign that does not exist, so the error cannot be used to probe ids.
+     */
+    stats(query) {
+        return this.http.request('GET', `${BASE}/stats`, { query });
+    }
+    /**
+     * The rows behind the funnel. This is the report table.
+     *
+     * `GET /v1/campaign-messages?campaign=<id>` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Default | Notes |
+     * | --- | --- | --- | --- |
+     * | `campaign` | string | — | Required. |
+     * | `message` | number | — | Zero-based index of one campaign message. |
+     * | `status` | `sent \| delivered \| read \| replied \| failed` | — | Cumulative; see below. Omit for every row. |
+     * | `exact` | boolean | `false` | Only rows sitting at `status` right now. |
+     * | `identifier` | string | — | Exact match on one recipient. Not a search. |
+     * | `reply_type` | string | — | Replied rows only; refused otherwise. |
+     * | `replied_within_hours` | number | — | Replied rows only; refused otherwise. |
+     * | `page` | number | `1` | 1-based. |
+     * | `rows` | number | `25` | 1–100. |
+     *
+     * Newest attempt first, ordered by when the row was written -- not by a stage
+     * timestamp, which would reorder the list as webhooks arrive and make paging
+     * skip and repeat rows.
+     *
+     * ```ts
+     * // the two queries a report screen actually makes
+     * const failures = await crm.campaignMessages.list({ campaign, status: 'failed', rows: 100 });
+     * const unread = await crm.campaignMessages.list({ campaign, status: 'delivered', exact: true });
+     * ```
+     *
+     * `reply_type` and `replied_within_hours` are **refused** with
+     * `400 validation_failed` unless `status` is `replied`, rather than quietly
+     * matching nothing.
+     */
+    list(query) {
+        return this.http.request('GET', BASE, { query });
+    }
+    /**
+     * Every matching row, paged through for you. What an export is.
+     *
+     * ```ts
+     * for await (const row of crm.campaignMessages.iterate({ campaign })) {
+     *   csv.write([row.identifier, row.name, row.status, row.error ?? '']);
+     * }
+     * ```
+     *
+     * Pages at 100 rows unless told otherwise -- the server's maximum, and the
+     * fewest round trips. A campaign of a million recipients is ten thousand
+     * requests, so for exports that size prefer running it where the latency is
+     * low rather than from a browser.
+     *
+     * The collection is live: rows are written while a campaign is going out, and
+     * statuses change under an export that takes minutes. Offset paging over
+     * moving data can repeat or skip a row -- for a stable snapshot, export after
+     * the campaign completes.
+     */
+    async *iterate(query) {
+        const rows = query.rows ?? 100;
+        let page = query.page ?? 1;
+        for (;;) {
+            const result = await this.list({ ...query, page, rows });
+            for (const record of result.data)
+                yield record;
+            if (result.data.length === 0 || page >= result.pagination.pages)
+                return;
+            page += 1;
+        }
+    }
+    /**
+     * What people replied, grouped by the reply itself.
+     *
+     * `GET /v1/campaign-messages/replies?campaign=<id>` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Default | Notes |
+     * | --- | --- | --- | --- |
+     * | `campaign` | string | — | Required. |
+     * | `message` | number | — | Zero-based index of one campaign message. |
+     * | `limit` | number | `50` | Distinct replies to return, 1–200. |
+     *
+     * ```ts
+     * const { groups, replied, distinct } = await crm.campaignMessages.replies({ campaign });
+     * groups; // [{ reply: 'Yes', replyType: 'button', count: 182 }, …]
+     * ```
+     *
+     * This is what a poll or a button message is sent to find out. Grouped on the
+     * reply **and** its type, so a tapped `Yes` and a typed `Yes` stay apart --
+     * they say different things about how engaged the recipient was.
+     *
+     * `distinct` against `groups.length` tells you whether the breakdown is
+     * complete. A campaign that asked an open question has as many groups as it
+     * has repliers, so a truncated answer there is normal rather than a problem.
+     */
+    replies(query) {
+        return this.http.request('GET', `${BASE}/replies`, { query });
+    }
+}
+exports.CampaignMessages = CampaignMessages;
+//# sourceMappingURL=campaign-messages.js.map

package/dist/resources/campaign-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign-messages.js","sourceRoot":"","sources":["../../src/resources/campaign-messages.ts"],"names":[],"mappings":";;;AAWA,MAAM,IAAI,GAAG,uBAAuB,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAa,gBAAgB;IACE;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CAAC,KAAgC;QACpC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAuB,KAAK,EAAE,GAAG,IAAI,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACpF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,IAAI,CAAC,KAAgC;QACnC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAmC,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACrF,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,CAAC,OAAO,CAAC,KAAgC;QAC7C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC;QAC/B,IAAI,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;QAE3B,SAAS,CAAC;YACR,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACzD,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,IAAI;gBAAE,MAAM,MAAM,CAAC;YAE/C,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK;gBAAE,OAAO;YACxE,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,KAA2B;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAyB,KAAK,EAAE,GAAG,IAAI,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACxF,CAAC;CACF;AAjID,4CAiIC"}

package/dist/resources/campaigns.d.ts

@@ -0,0 +1,239 @@
+import type { HttpClient } from '../http';
+import { InboxMedia } from './audience/inbox-media';
+import { type CampaignReceiver, type ReceiverEncoding } from '../internal/receiver-file';
+import { type BulkAudienceInput, type ResolvedAudience } from './campaign-audience';
+import type { Campaign, CampaignNumbersFilter, CreateCampaignInput, ListCampaignsQuery, UpdateCampaignInput } from '../types/campaign';
+import type { Page } from '../types/common';
+/** Everything `createBulk` needs: a normal campaign, with an audience instead of `filters`. */
+export interface CreateBulkCampaignInput extends Omit<CreateCampaignInput, 'filters' | 'type'> {
+    /** The recipients. Numbers, CSV text, parsed rows, or receivers you built. */
+    audience: BulkAudienceInput;
+    /** Overrides the dispatch route. Defaults to `bulk_campaign`; rarely needed. */
+    type?: string;
+    /** Aborts the upload. The campaign is not created if the upload is cancelled. */
+    signal?: AbortSignal;
+}
+/**
+ * What `createBulk` did, beyond creating the campaign.
+ *
+ * `receivers` is a **count**, deliberately matching what the same field means on
+ * a {@link Campaign} rather than carrying the resolved list. Two reasons: the
+ * caller already holds the data they passed in, and a name that means a number in
+ * one place and an array in another is the kind of thing that reads fine and then
+ * renders `[object Object]` on someone's screen.
+ */
+export interface BulkCampaignResult extends Omit<ResolvedAudience, 'receivers'> {
+    campaign: Campaign;
+    /**
+     * Recipients actually written into the file.
+     *
+     * This -- not `campaign.receivers`, which is `0` until the campaign is sent --
+     * is the number to show a user now.
+     */
+    receivers: number;
+    /** Public URL of the encrypted receiver file, as stored on the campaign. */
+    fileUrl: string;
+}
+/** An uploader, so the receiver file's destination can be swapped or faked in tests. */
+export type ReceiverUploader = Pick<InboxMedia, 'upload'>;
+/**
+ * One bucket of a group campaign: a slice of the recipients, and what should
+ * send it.
+ *
+ * Which of `channel` and `pairIndex` applies depends on the campaign's
+ * `distributeBy`. Neither is validated here -- a bucket with the wrong one is a
+ * mistake the sending service will report, and guessing which the caller meant
+ * would be worse than passing it along.
+ */
+export interface GroupBucket {
+    /** This bucket's recipients. Any of the four audience shapes. */
+    audience: BulkAudienceInput;
+    /** `distributeBy: 'channel'` -- the channel id this bucket is sent through. */
+    channel?: string;
+    /** `distributeBy: 'template'` -- which message in `messages` renders this bucket. */
+    pairIndex?: number;
+    /**
+     * Extra keys carried onto the filter entry verbatim, beside `numbers` and
+     * `hash`. The campaign contract passes anything it does not recognise straight
+     * through to the sending service, so this is the seam for distribution metadata
+     * this SDK does not model.
+     */
+    extra?: Record<string, unknown>;
+}
+export interface CreateGroupCampaignInput extends Omit<CreateCampaignInput, 'filters' | 'type'> {
+    /**
+     * What the buckets are split by.
+     *
+     * `channel` sends each bucket through a different channel; `template` renders
+     * each with a different message. Every bucket is stamped with this, and the
+     * contract refuses a campaign whose buckets disagree.
+     */
+    distributeBy: 'channel' | 'template';
+    buckets: readonly GroupBucket[];
+    /** Overrides the stored type. Defaults to `group_campaign`; rarely needed. */
+    type?: string;
+    signal?: AbortSignal;
+}
+/** One bucket's outcome. Same order as the buckets given. */
+export interface GroupBucketResult {
+    receivers: number;
+    skipped: number;
+    duplicates: number;
+    /** Public URL of this bucket's encrypted file. */
+    fileUrl: string;
+    channel?: string;
+    pairIndex?: number;
+}
+export interface GroupCampaignResult {
+    campaign: Campaign;
+    /** Buckets that had recipients and were uploaded. Empty ones are not here. */
+    buckets: GroupBucketResult[];
+    /** Totals across every bucket. */
+    receivers: number;
+    skipped: number;
+    duplicates: number;
+}
+export declare class Campaigns {
+    private readonly http;
+    private readonly media;
+    constructor(http: HttpClient, media?: ReceiverUploader);
+    list(query?: Partial<ListCampaignsQuery>): Promise<Page<Campaign>>;
+    get(id: string): Promise<Campaign>;
+    /**
+     * Creates a campaign from a payload you have already assembled.
+     *
+     * For a bulk recipient list, prefer {@link createBulk} -- it does the
+     * encrypting and uploading that a file-backed audience requires, which is not
+     * something a caller should have to reproduce.
+     */
+    create(input: CreateCampaignInput): Promise<Campaign>;
+    /**
+     * Creates a campaign addressed to a list of numbers you supply directly.
+     *
+     * This is the "bulk campaign" path, and the SDK does the whole of it: the
+     * recipient list never travels as part of the campaign, because a million
+     * numbers is not a request body. Instead it is encrypted into a file, uploaded
+     * to storage, and the campaign stores a pointer to it -- which the sending
+     * service fetches and decrypts when the campaign runs.
+     *
+     * ```ts
+     * // Pasted numbers, no variables
+     * const { campaign, receivers } = await crm.campaigns.createBulk({
+     *   name: 'Diwali offer',
+     *   audience: { numbers: '919000000001, 919000000002\n919000000003' },
+     *   messages: [{ channel: { id: channelId }, message: template }],
+     * });
+     *
+     * // A CSV, with every column available as a template variable
+     * await crm.campaigns.createBulk({
+     *   name: 'Renewal reminder',
+     *   audience: { csv: await file.text(), recipientColumn: 'phone' },
+     *   messages: [{ channel: { id: channelId }, message: template }],
+     *   trigger: 'schedule',
+     *   scheduledAt: '2026-11-01T04:30:00.000Z',
+     * });
+     * ```
+     *
+     * ## What it does, in order
+     *
+     * 1. **Resolves the audience.** Numbers are reduced to digits; CSV or TSV text
+     *    is parsed with quoted fields honoured; every column becomes a per-recipient
+     *    variable. Rows with no usable number are skipped and duplicates dropped,
+     *    both counted in the result rather than passed over in silence.
+     * 2. **Encrypts the list.** AES-256-CBC under a secret generated fresh for this
+     *    one file. See `internal/receiver-file.ts` for the exact scheme.
+     * 3. **Uploads it** as a `document` through the media endpoint: a presigned URL
+     *    is issued and the bytes go straight to storage, so the file never passes
+     *    through the API.
+     * 4. **Creates the campaign** with `type: 'bulk_campaign'` and
+     *    `filters: [{numbers: <url>, hash: <secret>}]`.
+     *
+     * ## Two things worth knowing
+     *
+     * **The returned `campaign.receivers` is `0`, and that is correct.** The
+     * audience is resolved when the campaign is sent, not when it is created. Use
+     * the `receivers` on this result -- the number actually written into the file --
+     * for anything you show the user now.
+     *
+     * **The file is readable by anyone holding both the URL and the `hash`.** The
+     * URL is a public storage link, so the secret stored alongside it on the
+     * campaign is the only thing protecting the list. It is a credential: do not log
+     * it, and do not copy a `filters` entry from one campaign into another system.
+     *
+     * Throws `validation_failed` if the audience resolves to no recipients, or to
+     * more than a million.
+     */
+    createBulk(input: CreateBulkCampaignInput): Promise<BulkCampaignResult>;
+    /**
+     * Creates a campaign whose recipients are split into buckets, each sent through
+     * a different channel or rendered with a different message.
+     *
+     * ```ts
+     * const { campaign, buckets, receivers } = await crm.campaigns.createGroup({
+     *   name: 'Diwali offer',
+     *   distributeBy: 'channel',
+     *   buckets: [
+     *     { channel: channelA, audience: { rows: north, recipientColumn: 'phone' } },
+     *     { channel: channelB, audience: { rows: south, recipientColumn: 'phone' } },
+     *   ],
+     *   messages: [{ channel: { id: channelA }, message: template }],
+     * });
+     * ```
+     *
+     * ## How this differs from `createBulk`
+     *
+     * Three ways, and each of them is a thing that would be wrong if you built the
+     * payload by hand:
+     *
+     * - **One file per bucket, not one per campaign.** Each bucket is encrypted
+     *   under its own secret and uploaded separately, and `filters` carries one
+     *   entry per bucket. This is the only audience mode where `filters` has more
+     *   than one element.
+     * - **A different file format.** A bucket file is a `||`-delimited table with a
+     *   header row, not the JSON array a bulk file holds. The reading side chooses
+     *   by campaign type, so the wrong encoding decrypts cleanly and then parses to
+     *   nothing.
+     * - **Columns are fixed by the first recipient.** A table has one header, so
+     *   every row carries the same variables in the same order. A bucket whose rows
+     *   have differing columns will have the missing ones filled in as empty.
+     *
+     * Everything else is the same: numbers are reduced to digits, CSV is parsed
+     * with quoted fields honoured, duplicates and unusable rows are dropped and
+     * counted -- per bucket, and summed on the result.
+     *
+     * ## Empty buckets are dropped, not refused
+     *
+     * A bucket whose audience resolves to nobody is left out of `filters`
+     * altogether, matching the panel: distributing a list across six channels
+     * routinely leaves one or two with nothing in them, and that is not an error.
+     * The call fails only when **every** bucket is empty.
+     *
+     * De-duplication is per bucket. A number appearing in two buckets is sent to
+     * twice -- which is usually the intent, since the buckets are different
+     * channels, and is not something this can second-guess.
+     */
+    createGroup(input: CreateGroupCampaignInput): Promise<GroupCampaignResult>;
+    /**
+     * Encrypts and uploads a receiver list, answering with the audience filter it
+     * produced.
+     *
+     * The file half of {@link createBulk}, exposed because the two halves can fail
+     * for unrelated reasons. Holding the filter lets you retry a failed campaign
+     * creation -- or create several campaigns against one uploaded list -- without
+     * re-uploading, which matters when the list is large.
+     *
+     * The returned `hash` is the decryption secret. Keep it with the URL or the
+     * file becomes unreadable; there is no copy of it anywhere else.
+     */
+    uploadReceivers(receivers: readonly CampaignReceiver[], signal?: AbortSignal, 
+    /**
+     * How the list is encoded inside the file. `json` for a bulk campaign's
+     * single file, `table` for a group campaign's bucket. The reading side picks
+     * by campaign type, so this has to match the campaign it is for.
+     */
+    encoding?: ReceiverEncoding): Promise<CampaignNumbersFilter>;
+    update(id: string, input: UpdateCampaignInput): Promise<Campaign>;
+    schedule(id: string, scheduledAt: string): Promise<Campaign>;
+    cancel(id: string): Promise<Campaign>;
+    delete(id: string): Promise<void>;
+}