ab-ecosystem-cpass 1.0.5 → 1.0.7

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.