ab-ecosystem-cpass 1.0.6 → 1.0.7

package/README.md

@@ -275,8 +275,7 @@ to show a user.
 | Resource | Page | Actions |
 | --- | --- | --- |
 | `crm.campaigns` | [campaigns](https://github.com/udghatan-dev/crm-sdk/blob/main/packages/sdk-js/docs/campaign/campaigns.md) | `list` `get` `create` `createBulk` `createGroup` `uploadReceivers` `update` `schedule` `cancel` `delete` |
-| `crm.campaignReports` | [campaigns](https://github.com/udghatan-dev/crm-sdk/blob/main/packages/sdk-js/docs/campaign/campaigns.md#campaign-reports) | `list` `getByCampaign` |
-| `crm.campaignReportExports` | [campaigns](https://github.com/udghatan-dev/crm-sdk/blob/main/packages/sdk-js/docs/campaign/campaigns.md#campaign-reports) | `list` `get` `create` |
+| `crm.campaignMessages` | [campaign messages](https://github.com/udghatan-dev/crm-sdk/blob/main/packages/sdk-js/docs/campaign/campaign-messages.md) | `stats` `list` `iterate` `replies` — reporting, counted off the per-recipient rows |
 
 The audience helpers are exported too, so a UI can show "12,480 recipients, 3
 duplicates dropped" before anything is uploaded:

package/dist/client.d.ts

@@ -18,8 +18,7 @@ import { Billing } from './resources/channels/billing';
 import { Wallet } from './resources/channels/wallet';
 import { Activity } from './resources/channels/activity';
 import { Campaigns } from './resources/campaigns';
-import { CampaignReports } from './resources/campaign-reports';
-import { CampaignReportExports } from './resources/campaign-report-exports';
+import { CampaignMessages } from './resources/campaign-messages';
 /**
  * One client for the whole gateway. Construct it once and share it: it holds no
  * per-request state, and every resource below runs over the same HTTP client,
@@ -91,9 +90,11 @@ export declare class CrmClient {
      * has to get exactly right.
      */
     readonly campaigns: Campaigns;
-    /** Per-campaign delivery metrics. */
-    readonly campaignReports: CampaignReports;
-    /** Report extracts as CSV or XLSX, generated asynchronously. */
-    readonly campaignReportExports: CampaignReportExports;
+    /**
+     * Campaign reporting: the funnel, the per-recipient rows behind it, and what
+     * people replied -- all counted off the message rows when asked for, so there
+     * is no roll-up to wait for and no export job to poll.
+     */
+    readonly campaignMessages: CampaignMessages;
     constructor(options: ClientOptions);
 }

package/dist/client.js

@@ -24,8 +24,7 @@ const wallet_1 = require("./resources/channels/wallet");
 const activity_1 = require("./resources/channels/activity");
 // Campaign
 const campaigns_1 = require("./resources/campaigns");
-const campaign_reports_1 = require("./resources/campaign-reports");
-const campaign_report_exports_1 = require("./resources/campaign-report-exports");
+const campaign_messages_1 = require("./resources/campaign-messages");
 /**
  * One client for the whole gateway. Construct it once and share it: it holds no
  * per-request state, and every resource below runs over the same HTTP client,
@@ -100,10 +99,12 @@ class CrmClient {
      * has to get exactly right.
      */
     campaigns;
-    /** Per-campaign delivery metrics. */
-    campaignReports;
-    /** Report extracts as CSV or XLSX, generated asynchronously. */
-    campaignReportExports;
+    /**
+     * Campaign reporting: the funnel, the per-recipient rows behind it, and what
+     * people replied -- all counted off the message rows when asked for, so there
+     * is no roll-up to wait for and no export job to poll.
+     */
+    campaignMessages;
     constructor(options) {
         const http = new http_1.HttpClient(options);
         this.contacts = new contacts_1.Contacts(http);
@@ -128,8 +129,7 @@ class CrmClient {
         // audience is uploaded through the media endpoint before the campaign is
         // created.
         this.campaigns = new campaigns_1.Campaigns(http);
-        this.campaignReports = new campaign_reports_1.CampaignReports(http);
-        this.campaignReportExports = new campaign_report_exports_1.CampaignReportExports(http);
+        this.campaignMessages = new campaign_messages_1.CampaignMessages(http);
     }
 }
 exports.CrmClient = CrmClient;

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -15,8 +15,7 @@ export { Webhooks } from './resources/audience/webhooks';
 export { Notifications } from './resources/audience/notifications';
 export { InboxMedia, type UploadMediaOptions, type UploadMediaSource, } from './resources/audience/inbox-media';
 export { Campaigns, type CreateBulkCampaignInput, type BulkCampaignResult, type CreateGroupCampaignInput, type GroupBucket, type GroupBucketResult, type GroupCampaignResult, type ReceiverUploader, } from './resources/campaigns';
-export { CampaignReports } from './resources/campaign-reports';
-export { CampaignReportExports } from './resources/campaign-report-exports';
+export { CampaignMessages } from './resources/campaign-messages';
 /**
  * The audience helpers, exported because they are useful before a campaign
  * exists: a UI can parse a CSV, show "12,480 recipients, 3 duplicates dropped",

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Activity = exports.Wallet = exports.Billing = exports.ChannelWebhooks = exports.Templates = exports.Channels = exports.resolveAudience = exports.parseDelimited = exports.normaliseNumbers = exports.normaliseColumn = exports.buildReceivers = exports.MAX_BULK_RECEIVERS = exports.CampaignReportExports = exports.CampaignReports = exports.Campaigns = exports.InboxMedia = exports.Notifications = exports.Webhooks = exports.Exports = exports.Imports = exports.CrmTriggers = exports.Segments = exports.CustomFields = exports.ContactNotes = exports.ContactTags = exports.Contacts = exports.CHANNELS = exports.AUDIENCE = void 0;
+exports.Activity = exports.Wallet = exports.Billing = exports.ChannelWebhooks = exports.Templates = exports.Channels = exports.resolveAudience = exports.parseDelimited = exports.normaliseNumbers = exports.normaliseColumn = exports.buildReceivers = exports.MAX_BULK_RECEIVERS = exports.CampaignMessages = exports.Campaigns = exports.InboxMedia = exports.Notifications = exports.Webhooks = exports.Exports = exports.Imports = exports.CrmTriggers = exports.Segments = exports.CustomFields = exports.ContactNotes = exports.ContactTags = exports.Contacts = exports.CHANNELS = exports.AUDIENCE = void 0;
 __exportStar(require("./client"), exports);
 __exportStar(require("./http"), exports);
 __exportStar(require("./errors"), exports);
@@ -48,10 +48,8 @@ Object.defineProperty(exports, "InboxMedia", { enumerable: true, get: function (
 // Campaign
 var campaigns_1 = require("./resources/campaigns");
 Object.defineProperty(exports, "Campaigns", { enumerable: true, get: function () { return campaigns_1.Campaigns; } });
-var campaign_reports_1 = require("./resources/campaign-reports");
-Object.defineProperty(exports, "CampaignReports", { enumerable: true, get: function () { return campaign_reports_1.CampaignReports; } });
-var campaign_report_exports_1 = require("./resources/campaign-report-exports");
-Object.defineProperty(exports, "CampaignReportExports", { enumerable: true, get: function () { return campaign_report_exports_1.CampaignReportExports; } });
+var campaign_messages_1 = require("./resources/campaign-messages");
+Object.defineProperty(exports, "CampaignMessages", { enumerable: true, get: function () { return campaign_messages_1.CampaignMessages; } });
 /**
  * The audience helpers, exported because they are useful before a campaign
  * exists: a UI can parse a CSV, show "12,480 recipients, 3 duplicates dropped",

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,yCAAuB;AACvB,2CAAyB;AACzB,0CAAwB;AAExB,2CAAuD;AAA9C,iGAAA,QAAQ,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAE3B,WAAW;AACX,0DAAyD;AAAhD,oGAAA,QAAQ,OAAA;AACjB,kEAAgE;AAAvD,2GAAA,WAAW,OAAA;AACpB,oEAAkE;AAAzD,6GAAA,YAAY,OAAA;AACrB,oEAAkE;AAAzD,6GAAA,YAAY,OAAA;AACrB,0DAAyD;AAAhD,oGAAA,QAAQ,OAAA;AACjB,kEAAgE;AAAvD,2GAAA,WAAW,OAAA;AACpB,sEAA8D;AAArD,yGAAA,OAAO,OAAA;AAChB,sEAA8D;AAArD,yGAAA,OAAO,OAAA;AAChB,0DAAyD;AAAhD,oGAAA,QAAQ,OAAA;AACjB,oEAAmE;AAA1D,8GAAA,aAAa,OAAA;AACtB,gEAI0C;AAHxC,yGAAA,UAAU,OAAA;AAKZ,WAAW;AACX,mDAS+B;AAR7B,sGAAA,SAAS,OAAA;AASX,iEAA+D;AAAtD,mHAAA,eAAe,OAAA;AACxB,+EAA4E;AAAnE,gIAAA,qBAAqB,OAAA;AAC9B;;;;GAIG;AACH,mEAUuC;AATrC,uHAAA,kBAAkB,OAAA;AAClB,mHAAA,cAAc,OAAA;AACd,oHAAA,eAAe,OAAA;AACf,qHAAA,gBAAgB,OAAA;AAChB,mHAAA,cAAc,OAAA;AACd,oHAAA,eAAe,OAAA;AAMjB,WAAW;AACX,0DAA8E;AAArE,oGAAA,QAAQ,OAAA;AACjB,4DAA2D;AAAlD,sGAAA,SAAS,OAAA;AAClB,0DAAgE;AAAvD,2GAAA,eAAe,OAAA;AACxB,wDAAuD;AAA9C,kGAAA,OAAO,OAAA;AAChB,sDAAqD;AAA5C,gGAAA,MAAM,OAAA;AACf,0DAAyD;AAAhD,oGAAA,QAAQ,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,yCAAuB;AACvB,2CAAyB;AACzB,0CAAwB;AAExB,2CAAuD;AAA9C,iGAAA,QAAQ,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAE3B,WAAW;AACX,0DAAyD;AAAhD,oGAAA,QAAQ,OAAA;AACjB,kEAAgE;AAAvD,2GAAA,WAAW,OAAA;AACpB,oEAAkE;AAAzD,6GAAA,YAAY,OAAA;AACrB,oEAAkE;AAAzD,6GAAA,YAAY,OAAA;AACrB,0DAAyD;AAAhD,oGAAA,QAAQ,OAAA;AACjB,kEAAgE;AAAvD,2GAAA,WAAW,OAAA;AACpB,sEAA8D;AAArD,yGAAA,OAAO,OAAA;AAChB,sEAA8D;AAArD,yGAAA,OAAO,OAAA;AAChB,0DAAyD;AAAhD,oGAAA,QAAQ,OAAA;AACjB,oEAAmE;AAA1D,8GAAA,aAAa,OAAA;AACtB,gEAI0C;AAHxC,yGAAA,UAAU,OAAA;AAKZ,WAAW;AACX,mDAS+B;AAR7B,sGAAA,SAAS,OAAA;AASX,mEAAiE;AAAxD,qHAAA,gBAAgB,OAAA;AACzB;;;;GAIG;AACH,mEAUuC;AATrC,uHAAA,kBAAkB,OAAA;AAClB,mHAAA,cAAc,OAAA;AACd,oHAAA,eAAe,OAAA;AACf,qHAAA,gBAAgB,OAAA;AAChB,mHAAA,cAAc,OAAA;AACd,oHAAA,eAAe,OAAA;AAMjB,WAAW;AACX,0DAA8E;AAArE,oGAAA,QAAQ,OAAA;AACjB,4DAA2D;AAAlD,sGAAA,SAAS,OAAA;AAClB,0DAAgE;AAAvD,2GAAA,eAAe,OAAA;AACxB,wDAAuD;AAA9C,kGAAA,OAAO,OAAA;AAChB,sDAAqD;AAA5C,gGAAA,MAAM,OAAA;AACf,0DAAyD;AAAhD,oGAAA,QAAQ,OAAA"}

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

@@ -0,0 +1,150 @@
+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
+ * ```
+ *
+ * ## 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/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: CampaignMessageStatsQuery): Promise<CampaignMessageStats>;
+    /**
+     * 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: 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(query: ListCampaignMessagesQuery): AsyncGenerator<CampaignMessageRecord>;
+    /**
+     * 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: CampaignRepliesQuery): Promise<CampaignReplyBreakdown>;
+}

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/types/campaign.d.ts

@@ -77,8 +77,8 @@ export interface CampaignRetargetSelectionFilter {
  * rejects a mixture rather than guessing.
  */
 export type CampaignFilter = CampaignNumbersFilter | CampaignRetargetStatusFilter | CampaignRetargetSelectionFilter | ContactFilterEntry;
-/** Which of the four modes a `filters` array expresses. */
-export type CampaignAudienceKind = 'all' | 'segment' | 'numbers' | 'retarget';
+/** Which of the five modes a `filters` array expresses. */
+export type CampaignAudienceKind = 'all' | 'segment' | 'numbers' | 'group' | 'retarget';
 export interface CampaignMessage {
     id?: string | number;
     channel: {
@@ -180,50 +180,140 @@ export type ListCampaignsQuery = {
     type?: string;
     hidden?: boolean;
 };
-/** Delivery counts for one campaign. Every field is a running total. */
-export interface CampaignMetrics {
-    queued: number;
-    sent: number;
-    delivered: number;
-    failed: number;
-    opened: number;
-    clicked: number;
-    unsubscribed: number;
-}
-export interface CampaignReport {
+/**
+ * How far one message got.
+ *
+ * A funnel held in **one field**, not a set of flags: a row carries the furthest
+ * state it has reached, so `read` also means delivered and sent. There is no
+ * `queued` -- a row only exists once the send has been attempted.
+ *
+ * `failed` sits off the funnel rather than at the end of it. A failed message
+ * was never delivered, so it is counted on its own and never inside `sent`.
+ */
+export type CampaignMessageStatus = 'sent' | 'delivered' | 'read' | 'replied' | 'failed';
+/**
+ * One attempted send: one campaign message, to one recipient.
+ *
+ * **Not a {@link CampaignMessage}**, which is the confusingly similar
+ * thing: that is one of the messages a campaign is *defined* to send. This is a
+ * record of such a message having gone to one person, and there is one per
+ * recipient per message.
+ *
+ * Written by the campaign manager at send time; its `status` is moved forward by
+ * the channel's webhooks, which are processed outside the CRM. So a row is
+ * append-only from this SDK's side -- there is nothing here that writes one.
+ */
+export interface CampaignMessageRecord {
+    /**
+     * The row's own id.
+     *
+     * This is the handle a `selection` retarget takes: hand a list of these back
+     * and the campaign manager resolves them to recipients, which is how
+     * "re-send to everyone who did not read it" is built.
+     */
     id: string;
     campaignId: string;
-    metrics: CampaignMetrics;
-    /** When the metrics were last rolled up, which may lag the campaign. */
-    generatedAt: IsoDate;
+    /** Which message of the campaign this was, zero-based. */
+    messageIndex: number;
+    /** The provider's id for the message. `''` when the send failed. */
+    providerMessageId: string;
+    channelId: string;
+    /** The recipient's contact id. */
+    contactId: string;
+    /** The destination itself -- a WhatsApp number, a Telegram id, and so on. */
+    identifier: string;
+    /** The recipient's name at send time; `''` when the contact had none. */
+    name: string;
+    status: CampaignMessageStatus;
+    /** Set for each stage the row has reached, absent for the ones it has not. */
+    sentAt?: IsoDate;
+    deliveredAt?: IsoDate;
+    readAt?: IsoDate;
+    repliedAt?: IsoDate;
+    failedAt?: IsoDate;
+    /** What the recipient replied; `''` unless `status` is `replied`. */
+    reply: string;
+    /** The reply's kind -- `text`, `button`, … `''` unless replied. */
+    replyType: string;
+    /** Seconds between the send and the reply. `0` unless replied. */
+    repliedIn: number;
+    /** The provider's error, on failed rows only. */
+    error?: string;
+    /** When the send was attempted. */
     createdAt: IsoDate;
-    updatedAt: IsoDate;
 }
-/** A report export shares the job lifecycle used across the platform. */
-export type CampaignReportExportStatus = 'queued' | 'processing' | 'completed' | 'failed';
-export interface CampaignReportExport {
-    id: string;
-    campaignId: string;
-    format: 'csv' | 'xlsx';
-    status: CampaignReportExportStatus;
-    rowCount: number;
-    /** Present once `status` is `completed`. Expires; see `expiresAt`. */
-    fileUrl?: string;
-    expiresAt?: IsoDate;
-    errorMessage?: string;
-    createdAt: IsoDate;
-    updatedAt: IsoDate;
+/**
+ * The campaign report: the numbers behind the tiles.
+ *
+ * Every stage is **cumulative** -- `delivered` counts everything that got at
+ * least that far -- so `read` is a subset of `delivered`. Subtract for a stage's
+ * exclusive count: `delivered - read` is "delivered but unread".
+ *
+ * `total` is the only number that counts every row, failures included, and it is
+ * the number of attempted sends.
+ */
+export interface CampaignMessageStats {
+    total: number;
+    /** Reached the provider: sent, delivered, read or replied. */
+    sent: number;
+    /** Delivered, read or replied. */
+    delivered: number;
+    /** Read or replied. */
+    read: number;
+    replied: number;
+    /** Never part of `sent`. */
+    failed: number;
 }
-export interface CreateCampaignReportExportInput {
-    campaignId: string;
-    /** Defaults to `csv`. */
-    format?: 'csv' | 'xlsx';
-    /** Narrows the rows by the period they fall in. */
-    from?: IsoDate;
-    to?: IsoDate;
+/** A type alias, for the same reason as {@link ListCampaignsQuery}. */
+export type CampaignMessageStatsQuery = {
+    /** The campaign id. Required. */
+    campaign: string;
+    /** One message of a multi-message campaign, by zero-based index. */
+    message?: number;
+};
+/**
+ * `crm.campaignMessages.list()` -- offset paginated.
+ *
+ * `status` filters **cumulatively** by default, so it agrees with the stats:
+ * `status: 'delivered'` returns the same rows the `delivered` number counted.
+ * `exact: true` instead returns only rows sitting at that stage -- "delivered
+ * but never read" -- which is the drill-down for `delivered - read`.
+ */
+export type ListCampaignMessagesQuery = {
+    campaign: string;
+    message?: number;
+    status?: CampaignMessageStatus;
+    /** Only rows at `status` right now. No effect without `status`, or on `failed`. */
+    exact?: boolean;
+    /** Exact match on one recipient, e.g. a single WhatsApp number. Not a search. */
+    identifier?: string;
+    /** Replied rows only; the API refuses it otherwise. */
+    reply_type?: string;
+    /** Replied rows only; the API refuses it otherwise. */
+    replied_within_hours?: number;
+    page?: number;
+    /** 1..100, default 25. */
+    rows?: number;
+};
+/** One distinct reply, and how many people sent it. */
+export interface CampaignReplyGroup {
+    reply: string;
+    replyType: string;
+    count: number;
+}
+/** What a poll or button message was answered with. */
+export interface CampaignReplyBreakdown {
+    /** Most common first, capped by the query's `limit`. */
+    groups: CampaignReplyGroup[];
+    /** Replied rows in total, whether or not their group is listed. */
+    replied: number;
+    /** Distinct replies in total -- compare with `groups.length` to detect truncation. */
+    distinct: number;
 }
 /** A type alias, for the same reason as {@link ListCampaignsQuery}. */
-export type GetCampaignReportQuery = {
-    from?: IsoDate;
-    to?: IsoDate;
+export type CampaignRepliesQuery = {
+    campaign: string;
+    message?: number;
+    /** Distinct replies to return, 1..200, default 50. */
+    limit?: number;
 };

package/docs/campaign/campaign-messages.md

@@ -0,0 +1,273 @@
+# Campaign messages (reporting)
+
+`crm.campaignMessages` — `/v1/campaign-messages`
+
+What actually happened to each message a campaign sent. One row per attempted
+send: who it went to, how far it got, what came back, and why it failed.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`stats`](#stats) | `GET /v1/campaign-messages/stats` | `campaigns:read` |
+| [`list`](#list) | `GET /v1/campaign-messages` | `campaigns:read` |
+| [`iterate`](#iterate) | the same, paged for you | `campaigns:read` |
+| [`replies`](#replies) | `GET /v1/campaign-messages/replies` | `campaigns:read` |
+
+## Where these numbers come from
+
+The campaign manager writes one row as it hands each message to a channel. The
+channel's delivery webhooks — processed **outside the CRM** — then move that
+row's `status` forward as the message is delivered, read and replied to.
+
+So reporting is a **read of those rows, counted when you ask**. There is no
+report collection, no roll-up job, and nothing to regenerate: no `generatedAt` to
+reason about, and no window in which a stored number is quietly wrong because a
+webhook has arrived but the roll-up has not run.
+
+The flip side is that a campaign still going out has moving numbers. Reading
+`stats` seconds after launch under-counts everything, and that is the truth
+rather than a lag.
+
+Nothing in this module writes. There is no endpoint to correct a status: the
+service that owns the lifecycle is the one receiving the webhooks.
+
+## The funnel
+
+`status` is a **single field holding the furthest stage reached** — not a set of
+flags. A row at `read` is also delivered and sent; a row at `replied` is all
+three. So the counts nest:
+
+```
+replied  ⊆  read  ⊆  delivered  ⊆  sent        failed ∥ (outside the funnel)
+```
+
+Which means:
+
+- **Cumulative by default.** `delivered` is everything that got at least as far
+  as delivered — the number a "delivered" tile shows.
+- **Subtract for a stage's own count.** `delivered - read` is "delivered but
+  unread"; `read - replied` is "read but silent".
+- **`failed` is never inside `sent`.** A failed message was never sent anywhere;
+  it is counted on its own.
+- **There is no `queued`.** A row exists only once a send has been attempted, so
+  "waiting to go out" is not a state this collection can have. The campaign's own
+  `status` is where that lives.
+
+`total` counts every row, failures included, and is the number of attempted
+sends.
+
+## The row
+
+```ts
+interface CampaignMessageRecord {
+  id: string;             // the row's own id — what a `selection` retarget takes
+  campaignId: string;
+  messageIndex: number;   // which message of the campaign, zero-based
+  providerMessageId: string; // '' when the send failed
+  channelId: string;
+  contactId: string;      // the recipient's contact id
+  identifier: string;     // the destination: a WhatsApp number, a Telegram id…
+  name: string;           // '' when the contact had no name
+  status: 'sent' | 'delivered' | 'read' | 'replied' | 'failed';
+  sentAt?: string;        // set per stage reached, absent for stages not reached
+  deliveredAt?: string;
+  readAt?: string;
+  repliedAt?: string;
+  failedAt?: string;
+  reply: string;          // '' unless replied
+  replyType: string;      // 'text', 'button', … '' unless replied
+  repliedIn: number;      // seconds between the send and the reply; 0 unless replied
+  error?: string;         // failed rows only
+  createdAt: string;      // when the send was attempted
+}
+```
+
+`id` is worth singling out: it is the handle a **`selection` retarget** campaign
+takes. Collect the ids of the rows you want and the campaign manager resolves
+them back to recipients, which is how "re-send to everyone who did not read it"
+is built.
+
+`CampaignMessageRecord` is not `CampaignMessage`, despite the names. A
+`CampaignMessage` is one of the messages a campaign is *defined* to send — a
+channel, a payload, its polls. A `CampaignMessageRecord` is a record of one of
+those having gone to one person, and there is one per recipient per message.
+
+---
+
+## stats
+
+```ts
+crm.campaignMessages.stats(query: CampaignMessageStatsQuery): Promise<CampaignMessageStats>
+```
+
+`GET /v1/campaign-messages/stats` · `campaigns:read` · **200**
+
+### Query
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `campaign` | string | yes | The campaign id, as a 24-character ObjectId. |
+| `message` | number | no | One message of a multi-message campaign, zero-based. |
+
+```ts
+const overall = await crm.campaignMessages.stats({ campaign });
+// { total: 12480, sent: 12410, delivered: 11980, read: 7420, replied: 310, failed: 70 }
+
+const second = await crm.campaignMessages.stats({ campaign, message: 1 });
+```
+
+**No date window**, deliberately. A campaign is a single send — its rows are
+written over the minutes it takes to go out and then only change state — so "the
+campaign's whole life" is the only window that means anything. A repeating
+campaign's runs are separate campaigns, each with its own id.
+
+One aggregation, not five counts. Legacy issued a `countDocuments` per stage,
+which is five passes for numbers that all come from one grouping, and could
+return a `read` higher than its own `delivered` when a webhook landed between
+two of the passes.
+
+`404 not_found` when 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 whether
+someone else's id is real.
+
+---
+
+## list
+
+```ts
+crm.campaignMessages.list(query: ListCampaignMessagesQuery): Promise<Paginated<CampaignMessageRecord>>
+```
+
+`GET /v1/campaign-messages` · `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. |
+
+```ts
+// the two queries a report screen actually makes
+const failures = await crm.campaignMessages.list({ campaign, status: 'failed', rows: 100 });
+failures.data[0].error; // why that one did not go
+
+const unread = await crm.campaignMessages.list({ campaign, status: 'delivered', exact: true });
+unread.pagination.total; // equals stats.delivered - stats.read
+```
+
+### `status` and `exact`
+
+`status` filters **cumulatively**, so a drill-down returns exactly the rows the
+matching stat counted: `status: 'delivered'` gives you the `delivered` number's
+rows. `exact: true` switches to the single stage — "delivered but never read" —
+which is the drill-down for `delivered - read`.
+
+`exact` has no effect without `status`, and none on `failed`, which has nothing
+beyond it.
+
+### Reply filters
+
+`reply_type` and `replied_within_hours` are **refused** with
+`400 validation_failed` unless `status` is `replied`. They cannot match anything
+on a non-replied row, and a filter that cannot match is a caller mistake worth
+reporting rather than an empty page.
+
+`replied_within_hours: 2` means the reply arrived within two hours of the send —
+useful for separating people who answered immediately from people who came back
+the next day.
+
+### Ordering
+
+Newest attempt first, by when the row was **written**, not by a stage timestamp.
+Sorting on `deliveredAt` would reorder the list as webhooks arrive, and offset
+paging over a list that reorders itself skips and repeats rows.
+
+---
+
+## iterate
+
+```ts
+crm.campaignMessages.iterate(query: ListCampaignMessagesQuery): AsyncGenerator<CampaignMessageRecord>
+```
+
+Every matching row, paged through for you. **This is what an export is** — there
+is no export endpoint, nothing to queue, nothing to poll, and no generated file
+that expires before someone downloads it.
+
+```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 you pass `rows` — the server's maximum, and so the
+fewest round trips. A million recipients is ten thousand requests, so run an
+export that size somewhere with low latency to the gateway rather than from a
+browser tab.
+
+The collection is live. Rows are written while a campaign goes out and statuses
+change under an export that takes minutes, and offset paging over moving data can
+repeat or miss a row. For a stable snapshot, export after the campaign completes.
+
+---
+
+## replies
+
+```ts
+crm.campaignMessages.replies(query: CampaignRepliesQuery): Promise<CampaignReplyBreakdown>
+```
+
+`GET /v1/campaign-messages/replies` · `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 }, { reply: 'No', … }]
+replied;  // 310 — every replied row, whether or not its group is listed
+distinct; // 4   — distinct replies in total
+```
+
+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. Most common first, ties broken by the
+reply text so the order is stable between reads.
+
+`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 — raise `limit`, or
+treat the tail as "other".
+
+---
+
+## Operational note: the index this needs
+
+Every read here matches on the campaign first, and the collection — which belongs
+to the campaign manager — declares no index on it. Without one, each report is a
+scan of every campaign message ever sent:
+
+```js
+db.newcampaignmessages.createIndex(
+  { cid: 1, cmid: 1, status: 1 },
+  { name: 'Campaign Report', background: true },
+);
+```
+
+One compound index serves all three reads. This service deliberately does **not**
+create it: building an index on a multi-million row collection owned by another
+service, as a side effect of a process starting, is not something that should
+happen by accident.

package/docs/campaign/campaigns.md

@@ -434,56 +434,16 @@ await crm.campaigns.delete(id);
 
 ---
 
-# Campaign reports
+# Reporting
 
-`crm.campaignReports` — `/v1/campaign-reports`
+Campaign reporting lives on its own page: **[campaign messages](campaign-messages.md)**
+— `crm.campaignMessages`.
 
-Delivery metrics for a campaign, rolled up by the platform.
+There is no report collection and no export job. One row is written per attempted
+send, its status is advanced by the channel's delivery webhooks, and every number
+is counted off those rows when you ask for it:
 
 ```ts
-const report = await crm.campaignReports.getByCampaign(campaignId);
-report.metrics;  // { queued, sent, delivered, failed, opened, clicked, unsubscribed }
+const stats = await crm.campaignMessages.stats({ campaign: id });
+// { total, sent, delivered, read, replied, failed }
 ```
-
-| Action | Route |
-| --- | --- |
-| `list` | `GET /v1/campaign-reports` — cursor-paged, `campaignId` optional |
-| `getByCampaign` | `GET /v1/campaign-reports/:campaignId` |
-
-`getByCampaign` takes an optional window; without it the report covers the
-campaign's whole life:
-
-```ts
-await crm.campaignReports.getByCampaign(campaignId, {
-  from: '2026-10-01T00:00:00.000Z',
-  to: '2026-10-31T23:59:59.000Z',
-});
-```
-
-`generatedAt` is when the metrics were last rolled up, which may lag the
-campaign — a report read seconds after a send will under-count.
-
-## Report exports
-
-`crm.campaignReportExports` — `/v1/campaign-report-exports`
-
-A per-recipient extract, generated asynchronously because it is a file rather
-than a few counters.
-
-```ts
-const job = await crm.campaignReportExports.create({ campaignId, format: 'xlsx' });
-
-// Poll until it finishes, then download.
-const done = await crm.campaignReportExports.get(job.id);
-if (done.status === 'completed') window.location.href = done.fileUrl!;
-```
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `campaignId` | `string` | required |
-| `format` | `csv` `xlsx` | default `csv` |
-| `from` / `to` | ISO datetime | narrows the rows by period |
-
-`status` moves `queued` → `processing` → `completed` or `failed`; `rowCount` is
-filled in as it goes, and `errorMessage` explains a failure. **`fileUrl` expires**
-— download it rather than storing the link.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ab-ecosystem-cpass",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "JavaScript/TypeScript SDK for the CPaaS CRM gateway: audience and channels",
   "license": "MIT",
   "main": "dist/index.js",

package/dist/resources/campaign-report-exports.d.ts

@@ -1,14 +0,0 @@
-import type { CampaignReportExport, CreateCampaignReportExportInput } from '../types/campaign';
-import type { Page, PageQuery } from '../types/common';
-import type { HttpClient } from '../http';
-export declare class CampaignReportExports {
-    private readonly http;
-    constructor(http: HttpClient);
-    list(query?: Partial<PageQuery>): Promise<Page<CampaignReportExport>>;
-    /**
-     * One export. Poll this until `status` is `completed`, then read `fileUrl` --
-     * which expires, so download rather than storing the link.
-     */
-    get(id: string): Promise<CampaignReportExport>;
-    create(input: CreateCampaignReportExportInput): Promise<CampaignReportExport>;
-}

package/dist/resources/campaign-report-exports.js

@@ -1,28 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CampaignReportExports = void 0;
-class CampaignReportExports {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    list(query = {}) {
-        return this.http.request('GET', '/v1/campaign-report-exports', {
-            query,
-        });
-    }
-    /**
-     * One export. Poll this until `status` is `completed`, then read `fileUrl` --
-     * which expires, so download rather than storing the link.
-     */
-    get(id) {
-        return this.http.request('GET', `/v1/campaign-report-exports/${encodeURIComponent(id)}`);
-    }
-    create(input) {
-        return this.http.request('POST', '/v1/campaign-report-exports', {
-            body: input,
-        });
-    }
-}
-exports.CampaignReportExports = CampaignReportExports;
-//# sourceMappingURL=campaign-report-exports.js.map

package/dist/resources/campaign-report-exports.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"campaign-report-exports.js","sourceRoot":"","sources":["../../src/resources/campaign-report-exports.ts"],"names":[],"mappings":";;;AAIA,MAAa,qBAAqB;IACH;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD,IAAI,CAAC,QAA4B,EAAE;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAA6B,KAAK,EAAE,6BAA6B,EAAE;YACzF,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CACtB,KAAK,EACL,+BAA+B,kBAAkB,CAAC,EAAE,CAAC,EAAE,CACxD,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,KAAsC;QAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAuB,MAAM,EAAE,6BAA6B,EAAE;YACpF,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;IACL,CAAC;CACF;AAzBD,sDAyBC"}

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

@@ -1,15 +0,0 @@
-import type { CampaignReport, GetCampaignReportQuery } from '../types/campaign';
-import type { Page, PageQuery } from '../types/common';
-import type { HttpClient } from '../http';
-export declare class CampaignReports {
-    private readonly http;
-    constructor(http: HttpClient);
-    list(query?: Partial<PageQuery>): Promise<Page<CampaignReport>>;
-    /**
-     * The report for one campaign.
-     *
-     * `from`/`to` narrow the window the metrics are rolled up over; without them
-     * the report covers the campaign's whole life.
-     */
-    getByCampaign(campaignId: string, query?: GetCampaignReportQuery): Promise<CampaignReport>;
-}

package/dist/resources/campaign-reports.js

@@ -1,25 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CampaignReports = void 0;
-class CampaignReports {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    list(query = {}) {
-        return this.http.request('GET', '/v1/campaign-reports', { query });
-    }
-    /**
-     * The report for one campaign.
-     *
-     * `from`/`to` narrow the window the metrics are rolled up over; without them
-     * the report covers the campaign's whole life.
-     */
-    getByCampaign(campaignId, query = {}) {
-        return this.http.request('GET', `/v1/campaign-reports/${encodeURIComponent(campaignId)}`, {
-            query,
-        });
-    }
-}
-exports.CampaignReports = CampaignReports;
-//# sourceMappingURL=campaign-reports.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"campaign-reports.js","sourceRoot":"","sources":["../../src/resources/campaign-reports.ts"],"names":[],"mappings":";;;AAIA,MAAa,eAAe;IACG;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD,IAAI,CAAC,QAA4B,EAAE;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAuB,KAAK,EAAE,sBAAsB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,UAAkB,EAAE,QAAgC,EAAE;QAClE,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAiB,KAAK,EAAE,wBAAwB,kBAAkB,CAAC,UAAU,CAAC,EAAE,EAAE;YACxG,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAlBD,0CAkBC"}