ab-ecosystem-cpass 1.0.0 → 1.0.6

package/docs/audience/contacts.md

@@ -142,6 +142,7 @@ blank contact.
 | Field | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `name` | `Partial<ContactName>` | — | `salutation` ≤ 20 chars, `first_name` and `last_name` ≤ 120. |
+| `whatsapp` | string | — | The contact's WhatsApp number, in any shape. Creates the channel identity. Create-only. |
 | `order` | string | — | Free-form external reference. |
 | `tags` | ObjectId[] | `[]` | Contact tag ids. |
 | `agent` | ObjectId \| null | — | Assigned agent. |
@@ -152,17 +153,41 @@ blank contact.
 | `custom_field_hash` | object | — | Values keyed by custom field **slug**. |
 | `chat_metadata` | partial | — | Including `blocked`, itself partial. |
 
-Channel identities cannot be set here; they are written when a conversation
-starts on a channel.
-
 ```ts
 const contact = await crm.contacts.create({
   name: { first_name: 'Ada', last_name: 'Lovelace' },
+  whatsapp: '+91 98765 43210',
   tags: [vipTagId],
   custom_field_hash: { city: 'Pune', lead_score: 80 },
 });
+
+contact.profile.whatsapp.identifier; // '919876543210'
 ```
 
+### The `whatsapp` field
+
+Pass it unless the contact is genuinely a placeholder. A contact with no channel
+identity cannot be messaged, will not be matched to an inbound message, is
+invisible to a number search, and drops out of every segment whose filter reaches
+into channel identities.
+
+**Any shape is accepted and stored as digits only.** `+91 98765 43210`,
+`+919876543210` and `919876543210` all store `919876543210`, which is the form an
+inbound message carries — the comparison that matches a reply to this contact is
+made against that string, so the punctuation has to go.
+
+| Response | When |
+| --- | --- |
+| `409 conflict` | The account already holds that number, on another contact or on this one. Nothing is created; the existing contact is untouched. |
+| `422` | The value contains no digits at all. An empty identifier would be a channel identity that can never be messaged or matched. |
+
+A number identifies **one contact per account**, and `profile` holds **one
+identity per channel** — so a contact cannot carry two WhatsApp numbers, and two
+contacts cannot share one.
+
+Identities for the other channels are still written by the conversation that
+starts on them.
+
 ---
 
 ## update
@@ -173,11 +198,16 @@ crm.contacts.update(id: string, input: UpdateContactInput): Promise<Contact>
 
 `PATCH /v1/audience/contacts/:id` · `contacts:write` · **200**
 
-Takes the same body as `create`, all optional. Anything left out is untouched.
+Takes the same body as `create` minus `whatsapp`, all optional. Anything left out
+is untouched.
 
 `tags` and `custom_field_hash` **replace** their stored value rather than merging
 into it — read the contact first if you mean to add one tag to the existing set.
 
+`whatsapp` is **not** accepted. A channel identity lives in its own collection, so
+changing a number is a write there plus a delete of the identity it replaces —
+not something a patch of the contact can express. It is create-only for now.
+
 ```ts
 await crm.contacts.update(id, { agent: agentId, chat_metadata: { closed: true } });
 ```

package/docs/audience/notifications.md

@@ -0,0 +1,263 @@
+# Push notifications
+
+`crm.notifications` — `/v1/audience/devices`
+
+Which browsers and apps a user wants notifications delivered to. A subscription
+is one device — one browser profile, one app installation — held against the
+acting user, and the only party who can see or revoke it is that user.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`subscribe`](#subscribe) | `POST /v1/audience/devices` | `devices:write` |
+| [`unsubscribe`](#unsubscribe) | `POST /v1/audience/devices/unregister` | `devices:write` |
+| [`devices`](#devices) | `GET /v1/audience/devices` | `devices:read` |
+
+## What the SDK does, and what you do
+
+A push subscription has two halves and only one of them is an API call.
+
+**In the browser**, which this SDK deliberately does not wrap:
+
+```js
+const permission = await Notification.requestPermission(); // 'granted' | 'denied' | 'default'
+const token = await getToken(messaging, { vapidKey });     // firebase/messaging
+```
+
+Wrapping those two would mean a hard dependency on `firebase/*` — in a package
+that also runs on Node — to pass arguments that come from your own Firebase
+project.
+
+**Here**, which is the part that is an API call:
+
+```ts
+if (permission === 'granted') {
+  await crm.notifications.subscribe({ token });
+}
+```
+
+## Where the subscription lives
+
+On the platform, against the acting user, **in this product** — not in the core
+platform. Core owns identity and the agency's Firebase credentials; messages
+arrive here, so the tokens and the sending live here too, and core is never on
+the delivery path.
+
+Nothing you send names a Firebase project. The platform resolves it from the
+client the call arrives on and stamps it onto the row, because a registration
+token is only sendable through the project that minted it and nothing in the
+token itself says which. That resolution is a cached read, so it costs nothing in
+steady state — but it is why `subscribe` is the one method here that can answer
+`503`.
+
+## The device object
+
+```ts
+interface Device {
+  id: string;
+  platform: 'web' | 'android' | 'ios';
+  label: string;          // what you sent as device_label; '' when you sent none
+  clientId: string | null; // the reseller frontend it registered from
+  lastSeenAt: string;     // ISO; last successful send, or last subscribe
+  createdAt: string;
+}
+```
+
+The **registration token is never returned**. It is a send credential: anything
+holding one can push to that browser through the agency's Firebase project. The
+list exists so a user can recognise and revoke their own devices, which needs the
+label and the last-seen time and nothing more.
+
+---
+
+## subscribe
+
+```ts
+crm.notifications.subscribe(input: SubscribeNotificationsInput): Promise<Device>
+```
+
+`POST /v1/audience/devices` · `devices:write` · **201**
+
+### Payload
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `token` | string | yes | The FCM registration token for this instance, from `getToken()`. 20–4096 characters — a sanity check, not a format; Google publishes no shape for these. Trimmed. |
+| `platform` | `'web' \| 'android' \| 'ios'` | defaulted | `'web'` when the SDK can see a DOM. Required otherwise — see below. |
+| `device_label` | string | no | Up to 200 characters; longer is trimmed, not refused. Defaults to something like `Chrome on Windows`, derived from the user agent. Cosmetic, never matched on. |
+| `tpc_id` | string | no | The reseller client (`tpc_…`) this frontend belongs to. Rarely needed. |
+
+What goes on the wire, with everything defaulted:
+
+```http
+POST /v1/audience/devices
+authorization: Bearer <ecosystem token>
+client-id: tpc_8Kd3mXp7qR2wL9zB
+content-type: application/json
+
+{
+  "token": "fNx8…:APA91bH…",
+  "platform": "web",
+  "device_label": "Chrome on Windows"
+}
+```
+
+```ts
+const device = await crm.notifications.subscribe({ token });
+// → { id: '…', platform: 'web', label: 'Chrome on Windows', clientId: 'tpc_…', … }
+```
+
+There is **no user field**, and that is deliberate: the acting user comes from
+the verified token the client was constructed with. A body that could name its
+own user would let any caller point someone else's notifications at their own
+browser.
+
+### Call it on every app load, not once
+
+It is an idempotent upsert keyed on the token, so re-sending one the platform
+already holds costs a single indexed update. That is the intended usage, because
+two things change underneath you:
+
+- FCM rotates registration tokens on its own schedule, and the old one stops
+  being delivered to without anyone being told.
+- A device unseen for **60 days** is pruned, and "seen" means a successful send
+  or a call to this method. Someone who receives no notifications for two months
+  would otherwise quietly fall off the list.
+
+Re-subscribing a token already on file against **another** user moves it rather
+than duplicating it. One browser has one person signed in, and the previous
+owner's notifications have to stop reaching it the moment someone else logs in
+there.
+
+### `platform` off-browser
+
+The SDK defaults it from `document`, not from `navigator` — which is the
+distinction that matters. React Native defines a `navigator` and no `document`,
+so a navigator-based guess would register every phone as a browser, and the send
+path would fill in the `webpush` block instead of `android`/`apns`: a
+notification FCM accepts and the device never shows. Outside a browser the SDK
+asks instead of guessing:
+
+```ts
+await crm.notifications.subscribe({ token, platform: 'android' });
+```
+
+### `tpc_id`
+
+Only ever a confirmation. The `clientId` the `CrmClient` already sends is
+verified by the gateway and wins; this field says which reseller frontend is
+registering, which decides whose Firebase project and which deep-link host apply.
+A value that contradicts the verified client is refused with `403` rather than
+ignored — the two disagreeing means either a frontend bug or an attempt to file a
+device under another tenant, and silently preferring one would hide the first and
+partially succeed at the second. The white-label frontend has no client and sends
+nothing.
+
+### Errors
+
+| Status | Code | Meaning |
+| --- | --- | --- |
+| 400 | `validation_failed` | Token missing or implausible, or `platform` could not be defaulted. Thrown by the SDK before a request is made. |
+| 403 | `forbidden` | `tpc_id` names a different client than the token was issued for. |
+| 503 | `push_not_configured` | The agency has no Firebase notification resource. Nothing the caller can fix; push is simply off for this account. |
+| 503 | `push_unavailable` | The platform could not read the configuration from core. Transient. |
+
+Both `503`s want the same handling as success: try again on the next app load,
+which the advice above means you are doing anyway.
+
+---
+
+## unsubscribe
+
+```ts
+crm.notifications.unsubscribe(token: string): Promise<void>
+```
+
+`POST /v1/audience/devices/unregister` · `devices:write` · **204**
+
+```ts
+await crm.notifications.unsubscribe(token);
+```
+
+### Payload
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `token` | string | yes | The same registration token. Trimmed. |
+
+`204` with no body **whether or not a row went** — you are asking for a
+guarantee about the future, and a token that is already gone provides it. So this
+is safe to call unconditionally on logout without first checking whether the
+device was ever subscribed.
+
+Scoped to the caller's own devices. A token identifies a browser rather than a
+person, so by the time one user logs out the row may already belong to whoever
+logged in after them; an unscoped delete would cut off the person now holding it.
+
+A `POST` with the token in the body rather than `DELETE /devices/:token`: a
+registration token is hundreds of characters and may contain `:` and `/`, and
+putting one in a path invites proxy length limits and writes a live send
+credential into every access log along the way.
+
+### Also delete it on the device
+
+This withdraws the platform's permission to send to that token. If the user is
+turning notifications **off** — rather than logging out — also drop the token in
+the browser, or the next `getToken()` hands back the same one and the
+subscription can come back by accident:
+
+```ts
+await crm.notifications.unsubscribe(token);
+await deleteToken(messaging); // firebase/messaging
+```
+
+---
+
+## devices
+
+```ts
+crm.notifications.devices(query?: Partial<ListDevicesQuery>): Promise<Paginated<Device>>
+```
+
+`GET /v1/audience/devices` · `devices:read` · **200**
+
+### Query
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `page` | number | `1` | 1-based. |
+| `rows` | number | `25` | 1–100. |
+
+Sorted by `lastSeenAt` descending. This is what a "notification settings" screen
+lists.
+
+```ts
+const { data } = await crm.notifications.devices();
+data.map((d) => `${d.label || 'This device'} · last seen ${d.lastSeenAt}`);
+```
+
+No `search`: the endpoint shares the common list query so the server would accept
+one, but the service does not apply it — a device list is one person's handful of
+rows. It is left out of the SDK type rather than accepted and silently dropped.
+
+Only ever the acting user's own devices. There is no account-wide view and no
+device id in the path: a device is one person's browser.
+
+Worth knowing: a notification is sent to the **20 most recently seen** devices
+of a user. A longer list is itself the answer to "why did my old laptop stop
+buzzing".
+
+### Telling whether *this* browser is subscribed
+
+You can't, from here — tokens are not returned, by design. Decide it locally
+instead. The browser knows its own `Notification.permission` and its own token,
+and because `subscribe` is an idempotent upsert, the cheap and correct answer to
+"am I still subscribed?" is to subscribe again:
+
+```ts
+if (Notification.permission === 'granted') {
+  await crm.notifications.subscribe({ token: await getToken(messaging, { vapidKey }) });
+}
+```
+
+That also repairs the two cases a stored flag gets wrong: a rotated token, and a
+row pruned for staleness.