ab-ecosystem-cpass 1.0.10 → 1.0.12

package/dist/types/channels.d.ts

@@ -381,3 +381,82 @@ export interface ListActivityLogsQuery extends ListQuery {
     /** Restrict to a period. */
     range?: UnixRange;
 }
+/** Channel families the onboarding endpoints can connect today. */
+export type OnboardingChannelType = 'whatsapp';
+/** Every family the picker shows, implemented or not. */
+export type OfferableChannelType = 'whatsapp' | 'facebook' | 'instagram';
+/** Why a family cannot be connected right now. */
+export type OnboardingUnavailableReason = 'not_included' | 'quota_exceeded' | 'not_supported' | 'provider_not_configured' | 'not_permitted';
+/** One row of the "add a channel" picker. */
+export interface ChannelOnboardingOption {
+    type: OfferableChannelType;
+    label: string;
+    available: boolean;
+    /** The inclusion a channel would be created against. Pass back to `url()`. */
+    slug?: string;
+    limit?: number;
+    used?: number;
+    remaining?: number;
+    /** Set only when `available` is false. */
+    reason?: OnboardingUnavailableReason;
+}
+export interface OnboardingUrlInput {
+    type?: OnboardingChannelType;
+    /** Only needed when the plan carries more than one channel inclusion. */
+    slug?: string;
+    /** Must be one of the service's configured redirects. Omit for the default. */
+    redirectUri?: string;
+}
+export interface OnboardingUrlResult {
+    /** Open in a popup. Meta refuses to render the dialog in an iframe. */
+    url: string;
+    /** Opaque; hand back to `exchange()` unchanged. */
+    state: string;
+    redirectUri: string;
+    expiresAt: IsoDate;
+    provider: string;
+    remaining?: number;
+}
+/** What Meta reports about the number, for the confirmation card. */
+export interface OnboardingPhoneNumber {
+    id: string;
+    wabaId: string;
+    /** Formatted, e.g. `+91 93116 36081`. */
+    displayPhoneNumber: string;
+    verifiedName: string;
+    status?: string;
+    codeVerificationStatus?: string;
+    qualityRating?: string;
+}
+export interface OnboardingExchangeInput {
+    state: string;
+    code: string;
+    wabaId: string;
+    phoneNumberId: string;
+}
+export interface OnboardingExchangeResult {
+    /** The pending record's id. Pass to `complete()` as `token`. */
+    id: string;
+    expiresAt: IsoDate;
+    phoneNumber: OnboardingPhoneNumber;
+    /** Prefill for the final form. */
+    defaults: {
+        name: string;
+        color: string;
+        currency: ChannelCurrency;
+    };
+}
+export interface CompleteOnboardingInput {
+    /** The `id` from `exchange()`. */
+    token: string;
+    name: string;
+    color?: string;
+    currency?: ChannelCurrency;
+}
+/** What the Meta dialog hands back, once both halves of it have arrived. */
+export interface SignupCredentials {
+    code: string;
+    state: string;
+    wabaId: string;
+    phoneNumberId: string;
+}

package/docs/audience/canned-replies.md

@@ -22,6 +22,9 @@ Two kinds, and the difference is who gets the last word:
 | [`update`](#update) | `PATCH /v1/audience/canned-replies/:reply` | `canned_replies:write` |
 | [`delete`](#delete) | `DELETE /v1/audience/canned-replies/:reply` | `canned_replies:write` |
 
+**Permissions** — `CRM.CHAT.CANNED_REPLY`: `LIST`, `READ`, `CREATE`, `UPDATE`,
+`DELETE`. Account-level, so `data_scope` does not narrow it.
+
 ## 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

package/docs/audience/contact-tags.md

@@ -14,6 +14,10 @@ tag **ids** on a write, and hands back the full tag documents resolved into
 | [`update`](#update) | `PATCH /v1/audience/contact-tags/:id` | `contact_tags:write` |
 | [`delete`](#delete) | `DELETE /v1/audience/contact-tags/:id` | `contact_tags:write` |
 
+**Permissions** — `CRM.CONTACT.TAG`: `LIST` to list, `READ` to read one,
+`CREATE`, `UPDATE`, `DELETE`. A tag is account-level, so a role's `data_scope`
+does not narrow this list — a member who holds `LIST` sees the account's tags.
+
 ## The tag object
 
 ```ts

package/docs/audience/contacts.md

@@ -19,6 +19,29 @@ land on the caller's own.
 | [`delete`](#delete) | `DELETE /v1/audience/contacts/:id` | `contacts:write` |
 | [`iterate`](#iterate) | — (walks `list`) | `contacts:read` |
 
+**Permissions** — each route also names a permission key, and a team member
+needs it. An owner does not.
+
+| Action | Key |
+| --- | --- |
+| `list` | `CRM.CONTACT.LIST` |
+| `get` | `CRM.CONTACT.READ` |
+| `create` | `CRM.CONTACT.CREATE` |
+| `update` | `CRM.CONTACT.UPDATE` |
+| `delete` | `CRM.CONTACT.DELETE` |
+
+A refusal is `403` with code `A403` (the role does not hold the key) or `E403`
+(the account's plan does not cover contacts — `details.feature` names it). An
+owner can meet `E403` but never `A403`.
+
+Separately from that, how many contacts a member can see is their role's
+`data_scope`: `own` — the default — returns the contacts assigned to them as
+`agent`, and `all` returns the account's. A contact assigned to nobody is the
+account's and not visible to an `own`-scoped member. Reading, updating or
+deleting a contact outside that scope is `404`, never `403`: a `403` would
+confirm the contact exists, which is what the scope is hiding.
+
+
 ## The contact object
 
 ```ts

package/docs/audience/crm-triggers.md

@@ -25,6 +25,9 @@ mean on the list.
 | [`delete`](#delete) | `DELETE /v1/audience/crm-triggers/:id` | `crm_triggers:write` |
 | [`logs`](#logs) | `GET /v1/audience/crm-triggers/logs` | `crm_triggers:read` |
 
+**Permissions** — `CRM.TRIGGER`: `LIST`, `READ` (one trigger, and the log
+endpoint), `CREATE`, `UPDATE`, `DELETE`.
+
 ## The trigger object
 
 ```ts

package/docs/audience/custom-fields.md

@@ -18,6 +18,29 @@ is looked up as one; anything else is read as a slug.
 | [`update`](#update) | `PATCH /v1/audience/custom-fields/:ref` | `custom_fields:write` |
 | [`delete`](#delete) | `DELETE /v1/audience/custom-fields/:ref` | `custom_fields:write` |
 
+**Permissions** — the feature is `CRM.CONTACT.FIELD`, which is its own feature
+and not a verb of `CRM.CONTACT`. A team member needs the key; an owner does not.
+
+| Action | Key |
+| --- | --- |
+| `list`, `get` | `CRM.CONTACT.FIELD.LIST` |
+| `create` | `CRM.CONTACT.FIELD.CREATE` |
+| `update` | `CRM.CONTACT.FIELD.UPDATE` |
+| `delete` | `CRM.CONTACT.FIELD.DELETE` |
+
+Reading one field uses `LIST`: the feature publishes no `READ` verb.
+
+The schema is account-level, so there is nothing for a role's `data_scope` to
+narrow — a field definition is not assigned to anybody, and a member seeing half
+a schema would see half of every contact. A member either reaches custom fields
+or does not.
+
+`teamAccess` on a field (`restricted` / `open_to_all`) is **stored and
+filterable, not enforced**: passing `?teamAccess=restricted` filters the list,
+and nothing restricts a member to `open_to_all` fields. If per-field visibility
+is meant to be real, that is a separate change from the key above.
+
+
 ## The field object
 
 ```ts

package/docs/audience/exports.md

@@ -23,11 +23,17 @@ The route is `/exports`, not `/contact-exports`: a row's `module` is `contact`
 | [`create`](#create) | `POST /v1/audience/exports` | `contacts:read` |
 | [`delete`](#delete) | `DELETE /v1/audience/exports/:id` | `contacts:write` |
 
+**Permissions** — every route here needs `CRM.CONTACT.EXPORT`, reads included:
+an export history row *is* the export, so a member who may not export has no
+business reading what one produced. The catalogue notes `EXPORT` implies
+`CRM.CONTACT.LIST`.
+
 There is no `update`: a row is moved by the worker, not by a caller.
 
 Note the scope on `create` — reading contacts out is a **read**, so an export
 can be started with read-only access.
 
+
 ## The export object
 
 ```ts

package/docs/audience/imports.md

@@ -23,8 +23,15 @@ The route is `/imports`, not `/contact-imports`: a row's `module` is `contact`
 | [`create`](#create) | `POST /v1/audience/imports` | `contacts:write` |
 | [`delete`](#delete) | `DELETE /v1/audience/imports/:id` | `contacts:write` |
 
+**Permissions** — the catalogue publishes `CRM.CONTACT.EXPORT` but **no
+`IMPORT`**, so these map to what an import does: `create` and `delete` need
+`CRM.CONTACT.CREATE` (an import is bulk contact creation) and the reads need
+`CRM.CONTACT.LIST`. If importing should be grantable separately from creating
+one contact at a time, the catalogue needs an `IMPORT` verb.
+
 There is no `update`: a row is moved by the worker, not by a caller.
 
+
 ## The import object
 
 ```ts

package/docs/audience/notifications.md

@@ -12,6 +12,10 @@ acting user, and the only party who can see or revoke it is that user.
 | [`unsubscribe`](#unsubscribe) | `POST /v1/audience/devices/unregister` | `devices:write` |
 | [`devices`](#devices) | `GET /v1/audience/devices` | `devices:read` |
 
+**Permissions** — `CRM.DEVICE`: `LIST`, `CREATE` to register, `DELETE` to
+unregister. Every device row belongs to the acting person rather than the
+account, so a caller only ever sees and changes their own whatever the key says.
+
 ## What the SDK does, and what you do
 
 A push subscription has two halves and only one of them is an API call.
@@ -342,6 +346,13 @@ 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.
 
+A **team member's** device records only their `psuid`. The legacy id on a member
+token belongs to the account holder, not to the member, so filling it in would
+make the member's phone answer notifications addressed to the owner — and the
+owner's answer theirs. The consequence is narrow and worth knowing: a member is
+reachable by `psuid`, and a chat assigned to them notifies them because the chat
+row names them.
+
 ### Rendering it in a browser
 
 If the payload carries a `notification` block, FCM displays it and opens

package/docs/audience/scheduled-messages.md

@@ -17,6 +17,11 @@ goes out.
 | [`cancelSeries`](#cancelseries) | `DELETE /v1/audience/scheduled-messages/series/:series` | `messages:write` |
 | [`sendNow`](#sendnow) | `POST /v1/audience/scheduled-messages/:id/send-now` | `messages:write` |
 
+**Permissions** — `CRM.CHAT.SCHEDULED_MESSAGE`: `LIST`, `READ`, `CREATE`
+(a single schedule or a series), `UPDATE` to reschedule, `DELETE` to cancel
+either, and **`SEND` for send-now**, which bypasses the schedule. The rows carry
+the account and no per-member creator, so `data_scope` does not narrow them.
+
 ---
 
 ## Why conditions exist

package/docs/audience/segments.md

@@ -17,6 +17,10 @@ campaign. Two runs a day apart can return different people, by design.
 | [`update`](#update) | `PATCH /v1/audience/segments/:id` | `segments:write` |
 | [`delete`](#delete) | `DELETE /v1/audience/segments/:id` | `segments:write` |
 
+**Permissions** — `CRM.CONTACT.SEGMENT`: `LIST`, `READ`, `CREATE`, `UPDATE`,
+`DELETE`. Reading a segment reveals its filter, not the contacts behind it;
+those still pass `CRM.CONTACT.LIST`.
+
 ## The segment object
 
 ```ts

package/docs/audience/webhooks.md

@@ -12,6 +12,12 @@ Three things in this SDK are called a webhook; they are not the same thing:
 | [`crm.crmTriggers`](crm-triggers.md) | One configured request per rule, when a contact matches | no |
 | [`crm.channelWebhooks`](../channels/webhooks.md) | A channel's message traffic | n/a |
 
+**Permissions** — `CRM.WEBHOOK`: `LIST`, `READ`, `CREATE`, `UPDATE`, `DELETE`.
+`READ` is a grant rather than a side effect of `LIST` because reading one
+reveals the endpoint URL and its secret header.
+
+Distinct from `CRM.CHANNEL.WEBHOOK`, which is where a *provider* delivers
+inbound traffic for one channel.
 **Scoping** — unlike the rest of the audience module, these rows are scoped by
 **tenant** rather than by the calling user.
 
@@ -23,6 +29,7 @@ Three things in this SDK are called a webhook; they are not the same thing:
 | [`update`](#update) | `PATCH /v1/audience/webhooks/:id` | `webhooks:write` |
 | [`delete`](#delete) | `DELETE /v1/audience/webhooks/:id` | `webhooks:write` |
 
+
 ## The webhook object
 
 ```ts

package/docs/campaign/campaigns.md

@@ -18,6 +18,26 @@ One message sent to many people.
 | [`cancel`](#cancel) | `POST /v1/campaigns/:id/cancel` | |
 | [`delete`](#delete) | `DELETE /v1/campaigns/:id` | |
 
+**Permissions** — the feature is `CRM.CAMPAIGN`. A team member needs the key; an
+owner does not.
+
+| Action | Key |
+| --- | --- |
+| `list` | `CRM.CAMPAIGN.LIST` |
+| `get`, the report endpoints | `CRM.CAMPAIGN.READ` |
+| `create`, `createBulk`, `createGroup`, `uploadReceivers` | `CRM.CAMPAIGN.CREATE` |
+| `update` | `CRM.CAMPAIGN.UPDATE` |
+| `trigger`, `schedule`, `cancel` | `CRM.CAMPAIGN.SEND` |
+| `delete` | `CRM.CAMPAIGN.DELETE` |
+
+`cancel` is under `SEND` rather than `UPDATE` on purpose: it is control of a
+dispatch, and somebody who may not launch a campaign should not be able to stop
+one that is going out.
+
+A campaign is not assigned to anybody, so a role's `data_scope` does not narrow
+this list — a member who holds `CRM.CAMPAIGN.LIST` sees the account's campaigns.
+
+
 ---
 
 ## Creating a campaign does not send it

package/docs/channels/activity.md

@@ -14,6 +14,9 @@ the [wallet ledger](wallet.md) instead.
 | --- | --- | --- |
 | [`list`](#list) | `GET /v1/channels/:channelId/logs` | `channels:read` |
 
+**Permissions** — `CRM.CHANNEL.LOG.LIST`. Its own feature rather than part of
+reading the channel, because the log exposes message traffic.
+
 ## The activity log object
 
 ```ts

package/docs/channels/billing.md

@@ -17,8 +17,10 @@ message category on a single one.
 | [`list`](#list) | `GET /v1/channels/:channelId/conversations` | `channels:read` |
 | [`stats`](#stats) | `GET /v1/channels/:channelId/conversations?stat=…` | `channels:read` |
 
+**Permissions** — `CRM.CHANNEL.USAGE.READ`, shared with the channel wallet.
 Read-only: charges are written by the platform as conversations happen.
 
+
 ## The billing log object
 
 ```ts

package/docs/channels/channel-props.md

@@ -1,5 +1,24 @@
 # Channel properties
 
+
+**Permissions** — a prop is not one capability, so the key depends on which prop
+is named. The path carries neither the feature (that is the channel's type) nor
+the verb (that is the prop), so this is checked in the handler.
+
+| Prop | Key |
+| --- | --- |
+| `token` | **`CREDENTIAL`** — it returns the provider access token |
+| `wa_pin_update`, `wa_request_otp`, `wa_submit_otp`, `migrate_number`, `wa_deregister`, `whatsapp_business_encryption` | **`REGISTER`** |
+| `message_analytics`, `conversation_analytics` | `ANALYTICS` |
+| `test_message`, `upload_media`, `resumable_upload` | `SEND` |
+| `webhook_status`, `webhook_listener_update` | `CRM.CHANNEL.WEBHOOK.READ` / `.UPDATE` |
+| every other read | `READ` |
+| every other write | `UPDATE` |
+
+The first two rows are the reason the split exists. `token` behind `READ` would
+let anybody who can view a channel take its credential, and the number
+lifecycle — retiring a number, moving it to another account, re-keying Flows
+encryption — is not a profile edit.
 `crm.channels.getProp` / `crm.channels.setProp` — `/v1/channels/:id/:prop`
 
 Everything about a channel that lives with the **provider** rather than on the

package/docs/channels/channels.md

@@ -6,8 +6,10 @@ The connections an account sends and receives on: a WhatsApp number, an RCS
 agent, a webchat widget.
 
 A channel is **provisioned by onboarding, not by this API**. There is no
-`create` and no `delete`: `disable` retires one for good, keeping the row its
-billing, wallet and activity history hang off.
+`create` and no `delete` here: `disable` retires one for good, keeping the row
+its billing, wallet and activity history hang off. Connecting a new one is
+`crm.channelOnboarding`, which walks the account holder through Meta's signup
+dialog -- **[connecting a channel](onboarding.md)**.
 
 Anything that lives with the provider rather than on the channel document — the
 business profile, the QR code, media uploads, number registration — moves
@@ -24,6 +26,36 @@ through `getProp` and `setProp`, documented on their own page:
 | [`getProp`](channel-props.md) | `GET /v1/channels/:id/:prop` | `channels:read` |
 | [`setProp`](channel-props.md) | `POST /v1/channels/:id/:prop` | `channels:write` |
 
+**Permissions** — there is no single `CRM.CHANNEL` key. The catalogue has one
+feature per channel type, because each sits behind its own plan option:
+`CRM.CHANNEL.WHATSAPP`, `CRM.CHANNEL.SMS`, `CRM.CHANNEL.RCS`. So the key for a
+request depends on the **type of the channel being addressed**, which is a field
+on the row — the check runs in the handler, not as route middleware.
+
+| Action | Verb |
+| --- | --- |
+| `list` | `LIST` — see below |
+| `get` | `READ` |
+| `updateDetails` | `UPDATE` |
+| `disable` | `DELETE` (a channel is never deleted; disabling retires it) |
+| `rotateToken` | **`CREDENTIAL`** |
+| `getProp` / `setProp` | depends on the prop — see [channel properties](channel-props.md) |
+
+`rotateToken` is `CREDENTIAL` rather than `UPDATE` because it replaces the same
+provider access token the `token` prop reads. Three verbs exist for that reason:
+`CREDENTIAL` for the token, `REGISTER` for the number lifecycle, and `ANALYTICS`
+for the analytics reads — none of which belong beside a business-profile edit.
+
+`list` spans every type the account owns, so it cannot be one key: it is
+**filtered** rather than refused. A member holding only
+`CRM.CHANNEL.WHATSAPP.LIST` sees the WhatsApp channels and no others, and asking
+for `?type=sms` without `CRM.CHANNEL.SMS.LIST` returns an empty page rather than
+somebody else's channels.
+
+Not every verb exists on every type: SMS reaches no properties at all, so it has
+no `CREDENTIAL`, `REGISTER` or `ANALYTICS`, and asking for one is refused rather
+than ignored.
+
 ## The channel object
 
 Credentials and the private auth block are stripped from every response; what