ab-ecosystem-cpass 1.0.11 → 1.0.12

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

package/docs/channels/onboarding.md

@@ -0,0 +1,324 @@
+# Connecting a channel
+
+`crm.channelOnboarding` — `/v1/channels/onboarding`
+
+Creating a channel is the one channel operation that is not a request and a
+response. The credentials belong to Meta, and the only way to get them is to
+walk the account holder through Meta's own **Embedded Signup** — a wizard on
+`facebook.com` where they pick or create a WhatsApp Business Account, add a
+number, and grant our app access to it.
+
+So the backend cannot create a channel on its own. It hands out the URL that
+starts the wizard, and redeems what the browser comes back with.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`types`](#types) | `GET /v1/channels/onboarding/types` | `channels:read` |
+| [`url`](#url) | `POST /v1/channels/onboarding/url` | `channels:write` |
+| [`exchange`](#exchange) | `POST /v1/channels/onboarding/exchange` | `channels:write` |
+| [`complete`](#complete) | `POST /v1/channels/onboarding/complete` | `channels:write` |
+| [`connect`](#connect) | the three above, plus the popup | `channels:write` |
+
+**Permissions** — `CRM.CHANNEL.WHATSAPP.CREATE`, checked on `url`, `exchange`
+**and** `complete`. Three checks rather than one because each call is a step
+towards a channel existing, and a role can be edited between them. `types`
+filters instead of refusing, like `GET /v1/channels`: a member who cannot create
+a WhatsApp channel sees the row marked `not_permitted` rather than losing the
+page.
+
+Only WhatsApp is onboarded here. Facebook and Instagram come through the same
+Meta dialog with a different signup configuration and a different set of ids
+coming back; they are still created by the legacy stack, and `types` reports them
+as `not_supported` so a picker can render the whole list it already renders.
+
+---
+
+## The shape of it
+
+```
+  ┌─────────────────────────────── your console ──────────────────────────────┐
+  │                                                                           │
+  │  1. types()        "WhatsApp — 2 of 3 left"                               │
+  │                                                                           │
+  │  2. url()          ──────────────▶  { url, state }                        │
+  │        │                                                                  │
+  │        └── open a POPUP on that url ───▶  Meta's wizard                   │
+  │                                               │                           │
+  │              code (on the redirect)  ◀────────┤                           │
+  │              waba_id + phone_number_id        │                           │
+  │              (postMessage)           ◀────────┘                           │
+  │                                                                           │
+  │  3. exchange()     ──────────────▶  { id, phoneNumber, defaults }         │
+  │                    show the number on a card; let them confirm            │
+  │                                                                           │
+  │  4. complete()     ──────────────▶  the channel                           │
+  └───────────────────────────────────────────────────────────────────────────┘
+```
+
+Two things about the middle of that are easy to get wrong, and both cost an
+afternoon:
+
+- **The dialog cannot be put in an iframe.** Meta sends `X-Frame-Options` on it.
+  A "modal" has to be your own chrome around a popup window, not an embedded
+  page. An iframe renders blank, which looks like our bug.
+- **What comes back arrives in two halves.** The authorization `code` comes back
+  the OAuth way, on the redirect. The `waba_id` and `phone_number_id` never
+  appear in that URL — they arrive as a `postMessage` from `facebook.com`
+  carrying `WA_EMBEDDED_SIGNUP`. A code with no ids cannot be verified and ids
+  with no code cannot be redeemed, so both are needed.
+
+`connect()` handles both halves for you. Use the long way only if you already
+drive `FB.login`, or if your onboarding spans two page loads.
+
+---
+
+## `types`
+
+```ts
+const { data } = await crm.channelOnboarding.types();
+
+// [
+//   { type: 'whatsapp',  label: 'WhatsApp', available: true,
+//     slug: 'whatsapp_channels_28335', limit: 3, used: 1, remaining: 2 },
+//   { type: 'facebook',  label: 'Facebook Messenger', available: false,
+//     reason: 'not_supported' },
+//   { type: 'instagram', label: 'Instagram', available: false,
+//     reason: 'not_supported' },
+// ]
+```
+
+Branch on `available`, and say something different for each `reason`:
+
+| `reason` | What happened | What to say |
+| --- | --- | --- |
+| `not_included` | The plan has none of this inclusion | Offer an upgrade |
+| `quota_exceeded` | Every unit is spent | "You have used all 3 of your WhatsApp channels" |
+| `not_permitted` | The account can, this person cannot | "Ask the account owner" |
+| `provider_not_configured` | No BSP is set up for the family | Our problem, not theirs — contact support |
+| `not_supported` | Not onboarded by this service yet | Hide the row, or point at the old panel |
+
+`limit` and `remaining` are absent when the inclusion is granted without a count
+— some plans grant a channel family as a flag rather than a quantity, which
+means *included, unmetered*. Absent is not zero.
+
+---
+
+## `url`
+
+```ts
+const { data } = await crm.channelOnboarding.url();
+// { url, state, redirectUri, expiresAt, provider, remaining }
+```
+
+| Field | |
+| --- | --- |
+| `type` | `whatsapp`, and the default |
+| `slug` | The inclusion to spend. Only needed when the plan carries more than one — each can sit behind a different BSP |
+| `redirectUri` | Must be one of the service's configured redirects. Omit for the default |
+
+Checks the plan **before** the account holder is sent anywhere: finding out
+afterwards means telling somebody who has just completed a business verification
+that they cannot have the channel. 402 `not_included` / `quota_exceeded` when
+the plan has no room, 409 `provider_not_configured` when no BSP is set up, 400
+`redirect_uri_not_allowed` for a redirect the service does not know.
+
+`state` is ours, not Meta's: signed, and bound to this account, this channel
+family and this provider. **Hand it back to `exchange()` unchanged.** It travels
+through Meta as the OAuth `state` parameter, so a browser that follows `url` gets
+it back for nothing — but `FB.login` will not round-trip it, so keep your copy.
+Good for an hour.
+
+`remaining` is what is left *after* this one, which is the number to put next to
+"you can connect 2 more".
+
+---
+
+## `exchange`
+
+```ts
+const { data } = await crm.channelOnboarding.exchange({
+  state,            // from url()
+  code,             // from the dialog
+  wabaId,           // from the WA_EMBEDDED_SIGNUP message
+  phoneNumberId,
+});
+
+// {
+//   id: '6721f0...',            // pass to complete() as `token`
+//   expiresAt: '...',
+//   phoneNumber: {
+//     id: '...', wabaId: '...', displayPhoneNumber: '+91 93116 36081',
+//     verifiedName: 'Acme Support', status: 'CONNECTED',
+//     codeVerificationStatus: 'VERIFIED', qualityRating: 'GREEN',
+//   },
+//   defaults: { name: 'Acme Support', color: '#075E54', currency: 'INR' },
+// }
+```
+
+**Nothing is created yet.** The number is a candidate: show
+`data.phoneNumber` on a card and let the person confirm it before it becomes a
+channel. That is why this is a separate call from `complete` — creating the
+channel the moment the code is redeemed leaves a half-configured channel behind
+every time somebody closes the tab on the confirmation screen.
+
+`phoneNumber` is Meta's own description of the number, not an echo of what you
+sent: the service reads the WABA's numbers with the token it just minted, which
+is what proves the token covers that WABA and the number is really on it.
+
+`id` stands for the long-lived token, which never leaves the service. The record
+it points at belongs to this account, can be used once, and expires in an hour.
+
+| Status | Code | |
+| --- | --- | --- |
+| 400 | `onboarding_code_rejected` | Meta refused the code. It is single use, so the dialog has to be run again |
+| 400 | `onboarding_number_rejected` | The number is not on that WABA, or Meta has banned it |
+| 400 | `onboarding_state_expired` | More than an hour since `url()` |
+| 403 | `onboarding_state_mismatch` | The state was issued to another account |
+| 409 | `phone_number_in_use` | Already connected to a channel |
+| 409 | `phone_number_pending` | **This account's own** unfinished channel — `details.channel` is its id. Resume it rather than making a second one |
+
+`phone_number_in_use` is checked across every account, not just this one: a
+number carries one WABA webhook subscription at a time, so a second channel on it
+would quietly take over the first one's message traffic.
+
+---
+
+## `complete`
+
+```ts
+const { data: channel } = await crm.channelOnboarding.complete({
+  token: candidate.id,
+  name: 'Acme Support',
+  color: '#075E54',
+  currency: 'INR',
+});
+```
+
+Creates the channel and returns it in the same shape `channels.get()` does.
+`name` is required; `color` defaults to WhatsApp's green and `currency` to the
+inclusion's, except that an INR plan falls back to USD for a number outside the
+Indian dial codes — Meta prices those in dollars however the plan is denominated.
+
+**The channel is created inactive.** Registering the number with Meta is what
+brings it up, and that is the next step in the console:
+
+```ts
+// A number new to the Cloud API: set its PIN.
+await crm.channels.setProp(channel.id, 'wa_pin_update', { body: { pin: '123456' } });
+
+// A number coming off the WhatsApp Business app: already registered with Meta.
+await crm.channels.setProp(channel.id, 'wa_biz_update');
+```
+
+`channel.cloud.wa_biz_registration` says which — `pending` until the BSP
+handshake has run. `channel.cloud.is_on_biz_app` is true for the second case.
+
+| Status | Code | |
+| --- | --- | --- |
+| 404 | `not_found` | No such session, or it belongs to another account |
+| 409 | `onboarding_already_completed` | A second call with the same token |
+| 410 | `onboarding_expired` | The confirmation screen sat for more than an hour |
+| 409 | `phone_number_in_use` | Somebody connected the number while the confirmation screen was open |
+
+A refusal here **releases the session rather than consuming it**, so pressing the
+button again is enough — the Meta dialog does not have to be run a second time.
+Only a create that succeeds spends the token.
+
+---
+
+## `connect`
+
+```ts
+// In the click handler for "Connect WhatsApp" — see the note below.
+const candidate = await crm.channelOnboarding.connect({
+  onProgress: ({ phase, step }) => setStatus(phase === 'step' ? step : phase),
+});
+
+// Then show the card and the form, and call complete().
+```
+
+`url()` → popup → `exchange()`, resolving with exactly what `exchange()` returns.
+It creates nothing, so the person still confirms the number before it becomes a
+channel.
+
+**Call it straight from the click handler**, not after an `await` of your own. It
+opens the popup before awaiting anything that would detach it from the gesture,
+because a `window.open` the browser does not attribute to a click is blocked —
+and the block is indistinguishable from the user having a popup blocker.
+
+| Option | |
+| --- | --- |
+| `type`, `slug`, `redirectUri` | Passed through to `url()` |
+| `onProgress` | `opened` → `step` (Meta's own step name) → `ids` / `code` |
+| `timeoutMs` | Default 15 minutes. The wizard can include a business verification |
+| `width`, `height`, `name` | The popup window |
+
+Rejects with `EmbeddedSignupError`, whose `code` is one of:
+
+| `code` | |
+| --- | --- |
+| `popup_blocked` | Allow popups and try again |
+| `popup_closed` | They closed the window |
+| `cancelled` | They backed out inside the wizard; `message` names the step |
+| `signup_error` | Meta reported a problem; `message` is Meta's own text |
+| `timeout` | Still open after `timeoutMs` |
+| `unsupported_environment` | Not a browser — drive the three calls yourself |
+
+Everything the service refused arrives as the usual `ApiError`, so handle both:
+
+```ts
+try {
+  const candidate = await crm.channelOnboarding.connect();
+} catch (err) {
+  if (err instanceof EmbeddedSignupError) {
+    if (err.code === 'cancelled') return;           // not an error worth showing
+    return showNotice(err.message);
+  }
+  throw err;                                         // a 402, a 409, ...
+}
+```
+
+### Driving the dialog yourself
+
+If you serve a page at the redirect, post the code back to the opener and
+`openSignup` will use it instead of reading the popup's URL:
+
+```html
+<!-- At your redirectUri -->
+<script>
+  const params = new URLSearchParams(location.search);
+  window.opener?.postMessage(
+    { type: 'CRM_CHANNEL_ONBOARDING', code: params.get('code'), state: params.get('state') },
+    window.origin,
+  );
+</script>
+```
+
+Or skip the popup helper entirely: call `url()`, run `FB.login` with the
+`config_id` from your own app configuration, and call `exchange()` with the
+`state` you kept and the ids from Meta's callback.
+
+---
+
+## What the service is doing for you
+
+Four checks that nothing downstream repeats:
+
+1. **The plan has room** — at all three steps, because the last unit can be spent
+   in another tab while somebody is in the wizard.
+2. **The number is not already connected** — across every account, for the
+   webhook reason above.
+3. **The token really covers the WABA** — both ids arrive in a request body, so
+   they are claims until the WABA's numbers are read with the minted token.
+
+And two things it deliberately leaves alone:
+
+- **The webhook subscription.** Meta is pointed at our listener at another level,
+  so onboarding neither registers it nor refuses a channel over it. Check it with
+  `channels.getProp(id, 'webhook_status')` and re-point it with
+  `channels.setProp(id, 'webhook_listener_update')` if it is ever not in place —
+  a channel whose WABA is not subscribed sends perfectly well and reports nothing
+  back, which is invisible until somebody replies.
+- **The credit-line handshake** with the BSP. That runs on the first
+  `wa_pin_update` or `wa_biz_update`, where it was already implemented and where
+  it is idempotent.

package/docs/channels/templates.md

@@ -21,6 +21,28 @@ channel is a `404` rather than a match.
 | [`delete`](#delete) | `DELETE /v1/channels/:channelId/templates/:id` | `channels:write` |
 | [`sync`](#sync) | `POST /v1/channels/:channelId/templates/sync` | `channels:write` |
 
+**Permissions** — the feature is `CRM.TEMPLATE`, flat and with no plan option of
+its own. A team member needs the key; an owner does not.
+
+| Action | Key |
+| --- | --- |
+| `list` | `CRM.TEMPLATE.LIST` |
+| `get` | `CRM.TEMPLATE.READ` |
+| `create` | `CRM.TEMPLATE.CREATE` |
+| `update`, `sync` | `CRM.TEMPLATE.UPDATE` |
+| `delete` | `CRM.TEMPLATE.DELETE` |
+
+`sync` pulls the provider's templates over the stored ones, which is a write to
+every template on the channel — hence `UPDATE`.
+
+The **channel** these hang off is gated separately, per type
+(`CRM.CHANNEL.WHATSAPP`, `CRM.CHANNEL.SMS`, `CRM.CHANNEL.RCS`), and that gate is
+not yet applied: the type is only knowable from the channel row, and on
+`/channels/:id/:prop` the verb depends on which prop is named — so both need the
+handler rather than the route. Until it lands, a member holding
+`CRM.TEMPLATE.LIST` can read templates on any channel the account owns.
+
+
 ## The template object
 
 ```ts

package/docs/channels/wallet.md

@@ -13,6 +13,8 @@ through this API. To send a user to the top-up page, read
 | --- | --- | --- |
 | [`list`](#list) | `GET /v1/channels/:channelId/wallet` | `channels:read` |
 
+**Permissions** — `CRM.CHANNEL.USAGE.READ`, shared with the conversation counts.
+
 ## The wallet log object
 
 ```ts

package/docs/channels/webhooks.md

@@ -20,6 +20,12 @@ changes from the audience module.
 | [`update`](#update) | `PATCH /v1/channels/:channelId/webhooks/:id` | `channels:write` |
 | [`delete`](#delete) | `DELETE /v1/channels/:channelId/webhooks/:id` | `channels:write` |
 
+**Permissions** — `CRM.CHANNEL.WEBHOOK`: `LIST`, `READ`, `CREATE`, `UPDATE`,
+`DELETE`. The two channel props that read and re-point the provider-side
+callback (`webhook_status`, `webhook_listener_update`) belong to this feature
+too, not to the channel: re-pointing a listener diverts every inbound message on
+that channel.
+
 ## The webhook object
 
 ```ts

package/docs/data-store.md

@@ -26,6 +26,24 @@ connections it holds to customer clusters cannot crowd out anything but itself.
 | [`dataStoreCollections`](#collections) | `…/:store/collections` | `datastores:read` / `datastores:write` |
 | [`dataStoreRecords`](#records) | `…/:store/collections/:collection/records` | `datastore-records:read` / `datastore-records:write` |
 
+**Permissions** — three features, one per level:
+
+| | Keys |
+| --- | --- |
+| stores | `CRM.DATASTORE`: `LIST`, `READ`, `CREATE`, `UPDATE`, `DELETE`, **`TEST`** |
+| collections | `CRM.DATASTORE.COLLECTION`: `LIST`, `READ`, `CREATE`, `UPDATE`, `DELETE` |
+| records | `CRM.DATASTORE.RECORD`: `LIST`, `READ`, `CREATE`, `UPDATE`, `DELETE` |
+
+`TEST` is a verb of its own because testing a connection opens an outbound
+connection to the customer's database, which is more than reading the row that
+describes it. `READ` on a store exposes the connection target; the credential is
+never returned.
+
+On records, `search` is `LIST` (a read with a body), and the bulk endpoints are
+the verb they perform — `bulk-update` is `UPDATE`, `bulk-delete` is `DELETE`.
+`CRM.DATASTORE.RECORD` is the most consequential key here: it reads and writes
+rows in the customer's own database.
+
 ## The model
 
 Three things, nested: