ab-ecosystem-cpass 1.0.6 → 1.0.8

package/dist/resources/campaign-messages.d.ts

@@ -0,0 +1,153 @@
+import type { CampaignMessageRecord, CampaignMessageStats, CampaignMessageStatsQuery, CampaignRepliesQuery, CampaignReplyBreakdown, ListCampaignMessagesQuery } from '../types/campaign';
+import type { Paginated } from '../types/common';
+import type { HttpClient } from '../http';
+/**
+ * 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
+ * ```
+ *
+ * Every method takes the campaign id first. A report has no meaning without one,
+ * so it is addressed as the campaign's own sub-resource --
+ * `/v1/campaigns/:id/report` -- rather than as a collection of rows that a
+ * campaign filters. The options object holds only what *narrows* a report that
+ * already exists: a message index, a status, a page.
+ *
+ * ## 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.
+ */
+export declare class CampaignMessages {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * The campaign's funnel counts.
+     *
+     * `GET /v1/campaigns/:id/report` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Notes |
+     * | --- | --- | --- |
+     * | `message` | number | One message of a multi-message campaign, zero-based. Omit for the whole campaign. |
+     *
+     * ```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(campaign: string, query?: CampaignMessageStatsQuery): Promise<CampaignMessageStats>;
+    /**
+     * The rows behind the funnel. This is the report table.
+     *
+     * `GET /v1/campaigns/:id/report/messages` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Default | Notes |
+     * | --- | --- | --- | --- |
+     * | `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
+     * `422 validation_failed` unless `status` is `replied`, rather than quietly
+     * matching nothing.
+     */
+    list(campaign: string, query?: ListCampaignMessagesQuery): Promise<Paginated<CampaignMessageRecord>>;
+    /**
+     * 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.
+     */
+    iterate(campaign: string, query?: ListCampaignMessagesQuery): AsyncGenerator<CampaignMessageRecord>;
+    /**
+     * What people replied, grouped by the reply itself.
+     *
+     * `GET /v1/campaigns/:id/report/replies` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Default | Notes |
+     * | --- | --- | --- | --- |
+     * | `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(campaign: string, query?: CampaignRepliesQuery): Promise<CampaignReplyBreakdown>;
+}

package/dist/resources/campaign-messages.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CampaignMessages = void 0;
+const paths_1 = require("./paths");
+/** `/v1/campaigns/:id/report` -- the report is the campaign's own sub-resource. */
+const report = (campaign) => `/v1/campaigns/${(0, paths_1.seg)(campaign)}/report`;
+/**
+ * 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
+ * ```
+ *
+ * Every method takes the campaign id first. A report has no meaning without one,
+ * so it is addressed as the campaign's own sub-resource --
+ * `/v1/campaigns/:id/report` -- rather than as a collection of rows that a
+ * campaign filters. The options object holds only what *narrows* a report that
+ * already exists: a message index, a status, a page.
+ *
+ * ## 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/campaigns/:id/report` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Notes |
+     * | --- | --- | --- |
+     * | `message` | number | One message of a multi-message campaign, zero-based. Omit for the whole campaign. |
+     *
+     * ```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(campaign, query = {}) {
+        return this.http.request('GET', report(campaign), { query });
+    }
+    /**
+     * The rows behind the funnel. This is the report table.
+     *
+     * `GET /v1/campaigns/:id/report/messages` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Default | Notes |
+     * | --- | --- | --- | --- |
+     * | `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
+     * `422 validation_failed` unless `status` is `replied`, rather than quietly
+     * matching nothing.
+     */
+    list(campaign, query = {}) {
+        return this.http.request('GET', `${report(campaign)}/messages`, { 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(campaign, query = {}) {
+        const rows = query.rows ?? 100;
+        let page = query.page ?? 1;
+        for (;;) {
+            const result = await this.list(campaign, { ...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/campaigns/:id/report/replies` · `campaigns:read` · **200**
+     *
+     * ### Query
+     *
+     * | Field | Type | Default | Notes |
+     * | --- | --- | --- | --- |
+     * | `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(campaign, query = {}) {
+        return this.http.request('GET', `${report(campaign)}/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":";;;AAUA,mCAA8B;AAE9B,mFAAmF;AACnF,MAAM,MAAM,GAAG,CAAC,QAAgB,EAAU,EAAE,CAAC,iBAAiB,IAAA,WAAG,EAAC,QAAQ,CAAC,SAAS,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAa,gBAAgB;IACE;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,QAAgB,EAAE,QAAmC,EAAE;QAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAuB,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACrF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,IAAI,CACF,QAAgB,EAChB,QAAmC,EAAE;QAErC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CACtB,KAAK,EACL,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,EAC9B,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,CAAC,OAAO,CACZ,QAAgB,EAChB,QAAmC,EAAE;QAErC,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,QAAQ,EAAE,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACnE,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;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,QAAgB,EAAE,QAA8B,EAAE;QACxD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAyB,KAAK,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE;YACrF,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AA1ID,4CA0IC"}