ab-ecosystem-cpass 1.0.11 → 1.0.13

package/dist/resources/channels/onboarding.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChannelOnboarding = void 0;
+const paths_1 = require("../paths");
+const embedded_signup_1 = require("../../internal/embedded-signup");
+const ONBOARDING = `${paths_1.CHANNELS}/onboarding`;
+/**
+ * Connecting a channel. The browser only runs Meta's dialog: Meta returns to
+ * the service's callback, which redeems the code and sends the browser back to
+ * `redirectUri` with a `status` and a `token` -- no credential reaches this
+ * page. `connect()` drives all of it; or call `url()`, open the dialog
+ * yourself, and read the return off your own landing page.
+ *
+ * ```ts
+ * // In the click handler for "Connect WhatsApp" -- not after an await.
+ * const candidate = await crm.channelOnboarding.connect({
+ *   redirectUri: 'https://console.example.com/channels/connected',
+ * });
+ * // One number, or several to choose between: candidate.numbers
+ * const { data: channel } = await crm.channelOnboarding.complete({
+ *   token: candidate.id,
+ *   phoneNumberId: chosen.id,
+ *   name: form.name,
+ * });
+ * ```
+ */
+class ChannelOnboarding {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * `GET /v1/channels/onboarding/types` -- the families this caller can connect
+     * right now. Anything the plan, the provider record or their role rules out is
+     * left out, so an empty list means "nothing to offer". Scope: `channels:read`.
+     */
+    types() {
+        return this.http.request('GET', `${ONBOARDING}/types`);
+    }
+    /**
+     * `POST /v1/channels/onboarding/url` -- the page to open. **Meta refuses to
+     * be framed**: use a popup, or navigate. 402 if the plan has no room.
+     *
+     * `url` is a launcher on the app's own domain that forwards to the dialog
+     * (`dialogUrl`); `redirectUri` is where *we* return the browser, not what
+     * Meta is given -- that is `callbackUri`.
+     */
+    url(input) {
+        return this.http.request('POST', `${ONBOARDING}/url`, { body: input });
+    }
+    /**
+     * `GET /v1/channels/onboarding/pending/:token` -- what the return URL's
+     * `token` refers to: the numbers it covers, and the form's prefill.
+     */
+    pending(token) {
+        return this.http.request('GET', `${ONBOARDING}/pending/${encodeURIComponent(token)}`);
+    }
+    /**
+     * `POST /v1/channels/onboarding/exchange` -- redeems a code you hold yourself,
+     * for a BSP app whose registered redirect is a page of yours rather than the
+     * service's callback. **Creates nothing**: show `phoneNumber` and confirm.
+     */
+    exchange(input) {
+        return this.http.request('POST', `${ONBOARDING}/exchange`, {
+            body: input,
+        });
+    }
+    /**
+     * `POST /v1/channels/onboarding/complete` -- creates the channel, **inactive**:
+     * `setProp(id, 'wa_pin_update')` brings it up, or `wa_biz_update` for a WA Biz number.
+     */
+    complete(input) {
+        return this.http.request('POST', `${ONBOARDING}/complete`, { body: input });
+    }
+    /**
+     * The URL, the dialog, and the record the callback leaves behind, in one call.
+     * **Call it straight from the click handler**, or the popup is blocked.
+     * Rejects with `EmbeddedSignupError`; `reason` carries the service's own code.
+     *
+     * What comes back is a *candidate* -- nothing exists until `complete()`, and
+     * if it holds several numbers the person picks one.
+     */
+    async connect(options) {
+        const { type, slug, provider, redirectUri, ...popup } = options;
+        const { data: session } = await this.url({ type, slug, provider, redirectUri });
+        const returned = await (0, embedded_signup_1.awaitSignupReturn)(session.url, popup);
+        if (!returned.token) {
+            throw new embedded_signup_1.EmbeddedSignupError('signup_error', 'The signup came back without an onboarding token');
+        }
+        // The query string carries a summary; this is the whole record.
+        const { data } = await this.pending(returned.token);
+        return data;
+    }
+}
+exports.ChannelOnboarding = ChannelOnboarding;
+//# sourceMappingURL=onboarding.js.map

package/dist/resources/channels/onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.js","sourceRoot":"","sources":["../../../src/resources/channels/onboarding.ts"],"names":[],"mappings":";;;AAYA,oCAAoC;AACpC,oEAAgH;AAEhH,MAAM,UAAU,GAAG,GAAG,gBAAQ,aAAa,CAAC;AAiB5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,iBAAiB;IACC;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD;;;;OAIG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAsC,KAAK,EAAE,GAAG,UAAU,QAAQ,CAAC,CAAC;IAC9F,CAAC;IAED;;;;;;;OAOG;IACH,GAAG,CAAC,KAAyB;QAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAgC,MAAM,EAAE,GAAG,UAAU,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACxG,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,KAAa;QACnB,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CACtB,KAAK,EACL,GAAG,UAAU,YAAY,kBAAkB,CAAC,KAAK,CAAC,EAAE,CACrD,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,KAA8B;QACrC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAqC,MAAM,EAAE,GAAG,UAAU,WAAW,EAAE;YAC7F,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,KAA8B;QACrC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAkB,MAAM,EAAE,GAAG,UAAU,WAAW,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/F,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,OAAuB;QACnC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;QAChE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;QAEhF,MAAM,QAAQ,GAAG,MAAM,IAAA,mCAAiB,EAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7D,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACpB,MAAM,IAAI,qCAAmB,CAAC,cAAc,EAAE,kDAAkD,CAAC,CAAC;QACpG,CAAC;QAED,gEAAgE;QAChE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAEpD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AA5ED,8CA4EC"}

package/dist/types/campaign.d.ts

@@ -108,6 +108,14 @@ export interface CampaignTriggerInfo {
 }
 export interface Campaign {
     id: string;
+    /**
+     * The team member who created the campaign, by psuid. Absent when the account
+     * holder created it, and on campaigns written before this was recorded.
+     *
+     * Who *wrote* it. Who armed it is `triggerInfo.psuid`, which can be someone
+     * else and is set a step later.
+     */
+    member?: string;
     version: string;
     crmVersion: string;
     name: string;

package/dist/types/channels.d.ts

@@ -49,6 +49,12 @@ export interface ChannelWallet {
  */
 export interface Channel {
     id: string;
+    /**
+     * The team member who connected the channel, by psuid. Absent when the
+     * account holder connected it, and on channels created before this was
+     * recorded.
+     */
+    member?: string;
     /** Enabled/disabled by the owner -- not the connection state. */
     active: boolean;
     ecom?: {
@@ -381,3 +387,126 @@ 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';
+/** One row of the "add a channel" picker. Only connectable families are listed. */
+export interface ChannelOnboardingOption {
+    type: OfferableChannelType;
+    label: string;
+    /** The inclusion a channel would be created against. Pass back to `url()`. */
+    slug?: string;
+    limit?: number;
+    used?: number;
+    remaining?: number;
+}
+export interface OnboardingUrlInput {
+    type?: OnboardingChannelType;
+    /** Only needed when the plan carries more than one channel inclusion. */
+    slug?: string;
+    /**
+     * Which BSP to connect through, by provider code. Omit for whichever is
+     * active for this family -- pin one only when there is a reason to.
+     */
+    provider?: string;
+    /**
+     * Where the browser is handed back, with the outcome on it. **Required**: the
+     * callback has no session, so nothing else says where. Meta never sees it.
+     */
+    redirectUri: string;
+}
+export interface OnboardingUrlResult {
+    /**
+     * Open in a popup, or navigate to it; it cannot be framed. A launcher on the
+     * app's own domain that forwards to `dialogUrl`, since Meta ties the dialog
+     * to that domain.
+     */
+    url: string;
+    /** Meta's dialog, which `url` forwards to. Open `url`, not this. */
+    dialogUrl: string;
+    /** Opaque, and already carrying `redirectUri`. Our callback is what reads it. */
+    state: string;
+    /** Where the browser will come back to. */
+    redirectUri: string;
+    /** What Meta was given: the service's own callback, registered on the BSP app. */
+    callbackUri: string;
+    expiresAt: IsoDate;
+    provider: string;
+    remaining?: number;
+}
+/** `ready`: one number, bound. `select`: several, so `complete()` names one. */
+export type OnboardingReturnStatus = 'ready' | 'select' | 'error';
+/** The query string the service appends to `redirectUri`. All values are strings. */
+export interface OnboardingReturn {
+    status: OnboardingReturnStatus;
+    /** Pass to `pending()`, and to `complete()` as `token`. */
+    token?: string;
+    /** How many numbers the authorisation covered; `"1"` for `ready`. */
+    numbers?: string;
+    wabaId?: string;
+    phoneNumberId?: string;
+    displayPhoneNumber?: string;
+    verifiedName?: string;
+    expiresAt?: string;
+    /** `status=error` only. */
+    code?: string;
+    message?: string;
+}
+/** 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;
+}
+/** Prefill for the final form. Every field is overridable in `complete()`. */
+export interface OnboardingDefaults {
+    name: string;
+    color: string;
+    currency: ChannelCurrency;
+}
+export interface OnboardingExchangeResult {
+    /** The pending record's id. Pass to `complete()` as `token`. */
+    id: string;
+    expiresAt: IsoDate;
+    phoneNumber: OnboardingPhoneNumber;
+    defaults: OnboardingDefaults;
+}
+/** A pending record, read back from the `token` on the return URL. */
+export interface OnboardingPendingResult {
+    id: string;
+    expiresAt: IsoDate;
+    type: OnboardingChannelType;
+    /** Every number the authorisation covers that is still free to connect. */
+    numbers: OnboardingPhoneNumber[];
+    /** Set when there was exactly one, and so already bound to the record. */
+    phoneNumber?: OnboardingPhoneNumber;
+    defaults: OnboardingDefaults;
+}
+export interface CompleteOnboardingInput {
+    /** The `id` from `exchange()`, or `token` off the return URL. */
+    token: string;
+    /** Which number, when the record covers several -- `status=select`. */
+    phoneNumberId?: 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/dist/types/channels.js.map

@@ -1 +1 @@
-{"version":3,"file":"channels.js","sourceRoot":"","sources":["../../src/types/channels.ts"],"names":[],"mappings":";;;AA8KA;;;;GAIG;AACU,QAAA,oBAAoB,GAAG,CAAC,aAAa,EAAE,kBAAkB,EAAE,cAAc,CAAU,CAAC;AAoIpF,QAAA,sBAAsB,GAAmC;IACpE,UAAU;IACV,MAAM;IACN,WAAW;IACX,MAAM;IACN,QAAQ;IACR,SAAS;IACT,UAAU;IACV,SAAS;IACT,cAAc;IACd,OAAO;CACR,CAAC"}
+{"version":3,"file":"channels.js","sourceRoot":"","sources":["../../src/types/channels.ts"],"names":[],"mappings":";;;AAoLA;;;;GAIG;AACU,QAAA,oBAAoB,GAAG,CAAC,aAAa,EAAE,kBAAkB,EAAE,cAAc,CAAU,CAAC;AAoIpF,QAAA,sBAAsB,GAAmC;IACpE,UAAU;IACV,MAAM;IACN,WAAW;IACX,MAAM;IACN,QAAQ;IACR,SAAS;IACT,UAAU;IACV,SAAS;IACT,cAAc;IACd,OAAO;CACR,CAAC"}

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,35 @@ 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.
+
+A contact a **team member** creates is assigned to that member as its `agent`,
+whatever their `data_scope` and whatever `agent` the body carried: they are the
+one working it. An account holder's create leaves `agent` as given — `null`
+unless they named someone — so a contact stays unassigned until it is handed
+over.
+
+
 ## The contact object
 
 ```ts
@@ -145,7 +174,7 @@ blank contact.
 | `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. |
+| `agent` | ObjectId \| null | — | Assigned agent. **Ignored for a team member**: the member creating the contact is assigned it. |
 | `team` | ObjectId \| null | — | Assigned team. |
 | `lead_source` | `{ type?, module?, id? }` | — | Where the contact came from. |
 | `status` | `'live' \| 'trashed'` | `'live'` | |

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
@@ -47,8 +67,15 @@ named against it.
 | --- | --- | --- |
 | `scheduledAt` in the body | **`422`** | that is the point |
 | writes `triggerInfo` | no | yes |
+| writes `member` | on `create`, by a team member | no |
 | campaign becomes sendable | no | yes |
 
+`member` is the other half of that record: the team member who **wrote** the
+campaign, stamped at `create` from their token. `triggerInfo.psuid` is who armed
+it, which is a later act and can be somebody else. Both are server-set and
+refused from a body; an account holder's campaign carries no `member`, because
+the campaign is already theirs.
+
 **"Now" is not instant.** `trigger` with no time arms the campaign about a minute
 out (`CAMPAIGN_IMMEDIATE_DELAY_SECONDS`), and [`cancel`](#cancel) still stops it
 in that window. A second `trigger` on a campaign that is armed but not yet picked

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
@@ -32,6 +64,7 @@ remains is safe to hand a console.
 ```ts
 interface Channel {
   id: string;
+  member?: string;                  // the team member who connected it; absent when the account holder did
   active: boolean;                  // enabled by the owner — NOT the connection state
   ecom?: { store_status: boolean; store?: string };
   basic_details: { name: string; color_code: string; channel_identity: string };