ab-ecosystem-cpass 1.0.7 → 1.0.9

package/docs/audience/canned-replies.md

@@ -0,0 +1,302 @@
+# Canned replies
+
+`crm.cannedReplies` — `/v1/audience/canned-replies`
+
+Message payloads an agent sends into a chat without retyping them. The panel
+offers them when an agent types `/` followed by the reply's name.
+
+Two kinds, and the difference is who gets the last word:
+
+- **`CANNED`** — every message the reply holds is sent exactly as stored, in
+  order, the moment it is picked. A three-message reply puts three messages on
+  the contact's phone from one keystroke.
+- **`QUICK`** — the reply's text lands in the agent's composer to edit before
+  sending. Exactly one message, of type `text`: there is one composer, and
+  nowhere in it to put a second message or an image.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`list`](#list) | `GET /v1/audience/canned-replies` | `canned_replies:read` |
+| [`get`](#get) | `GET /v1/audience/canned-replies/:reply` | `canned_replies:read` |
+| [`create`](#create) | `POST /v1/audience/canned-replies` | `canned_replies:write` |
+| [`update`](#update) | `PATCH /v1/audience/canned-replies/:reply` | `canned_replies:write` |
+| [`delete`](#delete) | `DELETE /v1/audience/canned-replies/:reply` | `canned_replies:write` |
+
+## Addressing a reply: `:reply` is an id **or** a name
+
+A 24-hex-character path segment is read as an **id**; anything else as a
+**name**. Names are unique per account, which is what makes addressing by the
+name an agent typed safe — and it is the only identifier the panel has at the
+moment of picking one.
+
+There is no fallback between the two. A 24-hex id that no longer exists is a
+`404`, never a name lookup, so a request for a deleted reply cannot quietly match
+a different one that happened to be named after its id. The one real ambiguity is
+a reply *named* 24 hex characters: it would be read as an id and 404. Rename it.
+
+## The reply object
+
+```ts
+interface CannedReply {
+  id: string;
+  name: string;                      // unique per account; what the agent types after `/`
+  type: 'CANNED' | 'QUICK';
+  channel: 'whatsapp' | 'sms' | 'email' | 'rcs' | 'webchat';
+  messages: CannedReplyMessage[];
+  createdAt: string;                 // ISO
+  updatedAt: string;                 // ISO
+}
+```
+
+`channel` is a channel **type**, never a channel id, so one reply works across
+every number on the account. `whatsapp` is the only value the panel offers today,
+and the reason is `whatsapp_api` below: a stored message is a literal WhatsApp
+Cloud API message object, so a reply is only sendable on a channel that speaks
+that shape.
+
+`messages` comes back in full from **every** endpoint, `list` included. It is the
+entire point of the record, and a picker that had to fetch each reply before it
+could show what the reply says would make one request per keystroke.
+
+## The message object
+
+```ts
+interface CannedReplyMessageV2 {
+  version: '2';
+  whatsapp_api: MessageContent;      // the payload as the provider takes it
+  internal?: Record<string, unknown>; // the editor's working copy; never read by the server
+}
+```
+
+`whatsapp_api` is the same object `crm.inbox.messages.send()` accepts as
+`content`. That is the point: picking a reply *is* sending its payloads, with no
+translation step in between.
+
+```json
+{ "version": "2",
+  "whatsapp_api": { "type": "text", "text": { "body": "Hi!", "preview_url": false } } }
+```
+
+```json
+{ "version": "2",
+  "whatsapp_api": { "type": "image", "image": { "link": "https://...", "caption": "Our menu" } } }
+```
+
+```json
+{ "version": "2",
+  "whatsapp_api": { "type": "interactive", "interactive": {
+      "type": "button",
+      "body": { "text": "Pick one" },
+      "action": { "buttons": [ { "type": "reply", "reply": { "id": "btn_0", "title": "Yes" } } ] } } } }
+```
+
+`internal` is the form state a composer needs to **reopen** the message for
+editing — which media type was chosen, whether the upload was still local, the
+button rows before they were flattened into an action. Stored and returned
+verbatim, never read by the server. It is optional: a reply created through the
+API without one is valid, and an editor just opens it in whatever state it can
+infer from `whatsapp_api`.
+
+### Variables are not substituted here
+
+`{{first_name}}` and friends are stored **literally**. Substitution happens at
+the moment of sending, against the contact in front of the agent — there is no
+contact when a reply is written, so there is nothing here to substitute against.
+
+### Reading older rows
+
+Rows written by the previous editor are still in the collection and carry a
+different shape entirely: a flat `type` plus a `components` array in template
+form. They come back exactly as stored, because synthesising a `whatsapp_api` for
+them would mean inventing a payload nobody approved.
+
+Narrow before you read:
+
+```ts
+for (const message of reply.messages) {
+  if (message.version === '2') {
+    send(message.whatsapp_api);
+  } else {
+    // A v1 row. Render it read-only, or ask the user to re-save the reply.
+  }
+}
+```
+
+New writes are v2 only — there is no way to create a v1 row through this API.
+
+---
+
+## list
+
+```ts
+crm.cannedReplies.list(query?: Partial<ListCannedRepliesQuery>): Promise<Paginated<CannedReply>>
+```
+
+`GET /v1/audience/canned-replies` · `canned_replies:read` · **200**
+
+Offset paginated, newest first.
+
+### Query
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+| `search` | string | — | 1–120 chars. Matches the **name**, case-insensitively, anywhere in it. The term is escaped, so `(` and `.` are searched for rather than compiled. |
+| `type` | `'CANNED' \| 'QUICK'` | — | — |
+| `channel` | channel **type** | — | e.g. `whatsapp`. Not a channel id. |
+
+```ts
+// What the chat panel asks for: the replies usable on the open chat's channel.
+const { data } = await crm.cannedReplies.list({ channel: 'whatsapp', rows: 100 });
+```
+
+To count without fetching, ask for one row and read the total:
+
+```ts
+const { pagination } = await crm.cannedReplies.list({ rows: 1 });
+pagination.total; // how many replies the account has
+```
+
+> There is no `isListing` flag. Legacy had one, and all it dropped from the
+> response was `createdAt` and `updatedAt` — it kept `messages`, the only field
+> in the record with any weight.
+
+---
+
+## get
+
+```ts
+crm.cannedReplies.get(ref: string): Promise<CannedReply>
+```
+
+`GET /v1/audience/canned-replies/:reply` · `canned_replies:read` · **200**
+
+`ref` is an id or a name — see [addressing](#addressing-a-reply-reply-is-an-id-or-a-name).
+
+`404 not_found` if the reply is not the caller's.
+
+```ts
+const reply = await crm.cannedReplies.get('price list');
+```
+
+---
+
+## create
+
+```ts
+crm.cannedReplies.create(input: CreateCannedReplyInput): Promise<CannedReply>
+```
+
+`POST /v1/audience/canned-replies` · `canned_replies:write` · **201**
+
+### Body
+
+| Field | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `name` | string | yes | — | Trimmed, 1–120 chars. Unique per account. |
+| `type` | `'CANNED' \| 'QUICK'` | yes | — | — |
+| `channel` | channel type | no | `'whatsapp'` | — |
+| `messages` | `CannedReplyMessageInput[]` | yes | — | 1–10 entries. See [the message object](#the-message-object). |
+
+`messages[].version` defaults to `'2'` and is the only accepted value;
+`messages[].whatsapp_api` is required; `messages[].internal` is optional.
+
+```ts
+const reply = await crm.cannedReplies.create({
+  name: 'price list',
+  type: 'CANNED',
+  channel: 'whatsapp',
+  messages: [
+    { version: '2', whatsapp_api: { type: 'text', text: { body: 'Here you go' } } },
+    { version: '2', whatsapp_api: {
+        type: 'document',
+        document: { link: 'https://.../prices.pdf', filename: 'prices.pdf' } } },
+  ],
+});
+```
+
+### Errors
+
+| Status | Code | When |
+| --- | --- | --- |
+| 409 | `conflict` | The name is already used on this account. |
+| 422 | `invalid_canned_reply` | A `QUICK` reply holds more than one message, or one that is not `text`. |
+| 422 | `validation_failed` | `messages` is empty or longer than 10; a message has no `whatsapp_api.type`; `name` is blank. |
+
+The `QUICK` rule is enforced here because legacy did not: it stored a `QUICK`
+reply holding an image happily, and the panel then refused to use it forever —
+the only explanation being a toast at the moment an agent reached for it.
+
+---
+
+## update
+
+```ts
+crm.cannedReplies.update(ref: string, input: UpdateCannedReplyInput): Promise<CannedReply>
+```
+
+`PATCH /v1/audience/canned-replies/:reply` · `canned_replies:write` · **200**
+
+`ref` is an id or a name. The body is any subset of `create`'s.
+
+`messages` is replaced **whole**, never merged: a reply is an ordered sequence,
+and there is no sensible way to patch element two of a list whose length is also
+changing. Send the array you want stored.
+
+Renaming works. It silently did not in legacy, whose update built its `$set` from
+`messages` alone and discarded every other field — while still *requiring* `type`
+and `channel` in the request it then ignored.
+
+An empty body is a no-op and returns the reply as it stands.
+
+### Errors
+
+| Status | Code | When |
+| --- | --- | --- |
+| 404 | `not_found` | No such reply on this account. |
+| 409 | `conflict` | A rename into a name that is already used. |
+| 422 | `invalid_canned_reply` | The **merged** result breaks the `QUICK` rule. |
+
+That last one is checked against the merge, so flipping a three-message reply to
+`QUICK` is refused — while renaming one that *already* breaks the rule is not.
+The check runs only when the patch touches `type` or `messages`: a rename alone
+leaves a reply exactly as valid as it already was, and running the rule
+regardless would make a v1 row unrenameable, punishing existing data for a rule
+introduced after it was written.
+
+```ts
+await crm.cannedReplies.update('price list', {
+  messages: [{ version: '2', whatsapp_api: { type: 'text', text: { body: 'Updated prices attached' } } }],
+});
+```
+
+---
+
+## delete
+
+```ts
+crm.cannedReplies.delete(ref: string): Promise<void>
+```
+
+`DELETE /v1/audience/canned-replies/:reply` · `canned_replies:write` · **204**, no body.
+
+`ref` is an id or a name. `404 not_found` if the reply is not the caller's.
+
+Nothing else holds a reference to a canned reply — a sent message is a message
+row, with its own copy of the content — so a delete leaves nothing dangling.
+
+---
+
+## Events
+
+Each write publishes one, for panels that cache the list:
+
+| Event | Payload |
+| --- | --- |
+| `canned_reply.created` | the full `CannedReply` |
+| `canned_reply.updated` | the full `CannedReply` |
+| `canned_reply.deleted` | `{ id, name }` |
+
+The delete carries the **name** as well as the id, because a panel caching
+replies by name — which is how an agent picks them — has no id to evict by.

package/docs/audience/notifications.md

@@ -261,3 +261,113 @@ if (Notification.permission === 'granted') {
 
 That also repairs the two cases a stored flag gets wrong: a rotated token, and a
 row pruned for staleness.
+
+---
+
+## What a device actually receives
+
+Subscribing is only half the story. This is what arrives, so a frontend can
+render it and an app can deep-link from it.
+
+Today one thing notifies: **a message on a chat the device's owner is
+responsible for.** The payload is FCM's, with the application's own keys under
+`data`:
+
+```json
+{
+  "notification": { "title": "Priya", "body": "Is this still available?" },
+  "data": {
+    "chat": "68f1c2a39b4e5d6f70812345",
+    "action_title": "View In Chat Panel",
+    "link": "https://app.acme.com/products/crmv2/chat/68f1c2a39b4e5d6f70812345",
+    "click_action": "https://app.acme.com/products/crmv2/chat/68f1c2a39b4e5d6f70812345",
+    "icon": "https://cdn.acme.com/push-192.png",
+    "badge": "https://cdn.acme.com/push-192.png"
+  },
+  "webpush": {
+    "notification": { "icon": "https://cdn.acme.com/push-192.png" },
+    "fcmOptions": { "link": "https://app.acme.com/products/crmv2/chat/68f1c2a39b4e5d6f70812345" }
+  }
+}
+```
+
+| Key | What it is |
+| --- | --- |
+| `notification.title` | Who wrote — the contact's first name, or `New User`. Not the agency's sender name, which is what every other notification would use. |
+| `notification.body` | The message text, cut to 180 characters. A non-text message is named by its type instead: `Image Message`, `Location Message`. |
+| `data.chat` | The chat id. The same id the inbox endpoints take. |
+| `data.click_action` | **Web:** the absolute panel URL. **Android/iOS:** the bare chat id, because an app resolves a record rather than opening a URL. |
+| `data.link` | Always the absolute URL, on every platform, so a native client can open the panel if it would rather. |
+| `data.image` | An image message's media URL, for a preview. Absent otherwise. |
+| `data.icon`, `data.badge` | The agency's notification icon, for a client drawing the notification itself. |
+| `webpush.fcmOptions.link` | What a **browser** opens on click. This is the mechanism, not `click_action`. |
+
+The host in every URL is the one configured for that device's surface, so the
+same notification deep-links to `app.acme.com` for one reseller's user and
+`portal.other.com` for another's.
+
+### Which messages notify
+
+| The message | Notifies |
+| --- | --- |
+| A contact wrote in | yes |
+| Somebody replied from the WhatsApp Business app | yes |
+| An agent replied from the panel | no |
+| A bot replied | no |
+| A campaign sent | no |
+| An API send | no |
+| A delivery receipt moved to delivered or read | no |
+
+A tick changing on a screen is not worth interrupting anyone for, and nobody
+needs telling about a message they just sent themselves.
+
+### Who it reaches
+
+The chat's **assigned agent**, or the **account owner** while it is unassigned
+— one person, not the team. An unassigned chat belongs to whoever is minding
+the queue.
+
+There is no presence check: an agent with the conversation open on screen still
+gets the push on their phone. That is the behaviour the panel has always had, and
+changing it is a product decision rather than a detail of delivery.
+
+A person is matched under **either of their two ids**. A request carries the
+ecosystem's `psuid`, which is what `subscribe()` files a device under; the inbox
+trigger reads its recipient off a chat row the legacy stack wrote, so the id it
+holds is a legacy one. Registration records both, and the lookup matches the one
+id it is given against either field — so it resolves one person under two
+names, and never returns a colleague's devices.
+
+The practical consequence: a device registered before this existed is still
+reachable by `psuid` exactly as before, and the next `subscribe()` call — which
+the frontend makes on every app load — fills in the second id.
+
+### Rendering it in a browser
+
+If the payload carries a `notification` block, FCM displays it and opens
+`webpush.fcmOptions.link` on click with no code from you — which is the
+default worth keeping. A service worker that wants to draw its own instead
+should read the `data` keys above:
+
+```js
+messaging.onBackgroundMessage((payload) => {
+  self.registration.showNotification(payload.notification.title, {
+    body: payload.notification.body,
+    icon: payload.data.icon,
+    image: payload.data.image,
+    data: { url: payload.data.link },
+  });
+});
+
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close();
+  event.waitUntil(clients.openWindow(event.notification.data.url));
+});
+```
+
+Two things to know if you are porting the existing worker. A notification FCM
+displayed itself nests the payload under `notification.data.FCM_MSG`, so reading
+`event.notification.data.click_action` off it finds nothing — take the link
+from your own `showNotification` call, as above. And `localStorage` does not
+exist in a service worker: a gate written against it throws, and the handler
+around it never runs.

package/docs/campaign/campaign-messages.md

@@ -1,16 +1,28 @@
 # Campaign messages (reporting)
 
-`crm.campaignMessages` — `/v1/campaign-messages`
+`crm.campaignMessages` — `/v1/campaigns/:id/report`
 
 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` |
+| [`stats`](#stats) | `GET /v1/campaigns/:id/report` | `campaigns:read` |
+| [`list`](#list) | `GET /v1/campaigns/:id/report/messages` | `campaigns:read` |
 | [`iterate`](#iterate) | the same, paged for you | `campaigns:read` |
-| [`replies`](#replies) | `GET /v1/campaign-messages/replies` | `campaigns:read` |
+| [`replies`](#replies) | `GET /v1/campaigns/:id/report/replies` | `campaigns:read` |
+
+## The campaign is the path
+
+A report has no meaning without a campaign, so it is addressed as the campaign's
+own sub-resource rather than as a collection of rows that a campaign filters.
+Every method takes the id first, and the options object holds only what
+*narrows* a report that already exists — a message index, a status, a page.
+
+```ts
+await crm.campaignMessages.stats(campaignId);
+await crm.campaignMessages.list(campaignId, { status: 'failed' });
+```
 
 ## Where these numbers come from
 
@@ -96,23 +108,22 @@ those having gone to one person, and there is one per recipient per message.
 ## stats
 
 ```ts
-crm.campaignMessages.stats(query: CampaignMessageStatsQuery): Promise<CampaignMessageStats>
+crm.campaignMessages.stats(campaign: string, query?: CampaignMessageStatsQuery): Promise<CampaignMessageStats>
 ```
 
-`GET /v1/campaign-messages/stats` · `campaigns:read` · **200**
+`GET /v1/campaigns/:id/report` · `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. |
+| `message` | number | no | One message of a multi-message campaign, zero-based. Omit for the whole campaign. |
 
 ```ts
-const overall = await crm.campaignMessages.stats({ campaign });
+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 });
+const second = await crm.campaignMessages.stats(campaign, { message: 1 });
 ```
 
 **No date window**, deliberately. A campaign is a single send — its rows are
@@ -134,16 +145,15 @@ someone else's id is real.
 ## list
 
 ```ts
-crm.campaignMessages.list(query: ListCampaignMessagesQuery): Promise<Paginated<CampaignMessageRecord>>
+crm.campaignMessages.list(campaign: string, query?: ListCampaignMessagesQuery): Promise<Paginated<CampaignMessageRecord>>
 ```
 
-`GET /v1/campaign-messages` · `campaigns:read` · **200**
+`GET /v1/campaigns/:id/report/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. |
@@ -155,10 +165,10 @@ crm.campaignMessages.list(query: ListCampaignMessagesQuery): Promise<Paginated<C
 
 ```ts
 // the two queries a report screen actually makes
-const failures = await crm.campaignMessages.list({ campaign, status: 'failed', rows: 100 });
+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 });
+const unread = await crm.campaignMessages.list(campaign, { status: 'delivered', exact: true });
 unread.pagination.total; // equals stats.delivered - stats.read
 ```
 
@@ -175,7 +185,7 @@ beyond it.
 ### Reply filters
 
 `reply_type` and `replied_within_hours` are **refused** with
-`400 validation_failed` unless `status` is `replied`. They cannot match anything
+`422 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.
 
@@ -194,7 +204,7 @@ paging over a list that reorders itself skips and repeats rows.
 ## iterate
 
 ```ts
-crm.campaignMessages.iterate(query: ListCampaignMessagesQuery): AsyncGenerator<CampaignMessageRecord>
+crm.campaignMessages.iterate(campaign: string, query?: ListCampaignMessagesQuery): AsyncGenerator<CampaignMessageRecord>
 ```
 
 Every matching row, paged through for you. **This is what an export is** — there
@@ -202,7 +212,7 @@ 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 })) {
+for await (const row of crm.campaignMessages.iterate(campaign)) {
   csv.write([row.identifier, row.name, row.status, row.error ?? '']);
 }
 ```
@@ -221,21 +231,20 @@ repeat or miss a row. For a stable snapshot, export after the campaign completes
 ## replies
 
 ```ts
-crm.campaignMessages.replies(query: CampaignRepliesQuery): Promise<CampaignReplyBreakdown>
+crm.campaignMessages.replies(campaign: string, query?: CampaignRepliesQuery): Promise<CampaignReplyBreakdown>
 ```
 
-`GET /v1/campaign-messages/replies` · `campaigns:read` · **200**
+`GET /v1/campaigns/:id/report/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 });
+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