ab-ecosystem-cpass 1.0.11 → 1.0.13

package/docs/channels/onboarding.md

@@ -0,0 +1,530 @@
+# 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. What it can do is keep the
+browser out of the credential business entirely: **Meta returns to us, not to
+you.** The dialog is opened with our own `oauth-callback` as its redirect, so the
+authorization code goes straight to this service, which redeems it, reads which
+numbers the authorisation covers, and hands the browser back to a URL of yours
+with nothing on it but an outcome and a token to finish from.
+
+| Action | Route | Scope |
+| --- | --- | --- |
+| [`types`](#types) | `GET /v1/channels/onboarding/types` | `channels:read` |
+| [`url`](#url) | `POST /v1/channels/onboarding/url` | `channels:write` |
+| [the callback](#the-callback) | `GET /v1/channels/onboarding/oauth-callback` | **public** |
+| [`pending`](#pending) | `GET /v1/channels/onboarding/pending/:token` | `channels:read` |
+| [`complete`](#complete) | `POST /v1/channels/onboarding/complete` | `channels:write` |
+| [`exchange`](#exchange) | `POST /v1/channels/onboarding/exchange` | `channels:write` |
+| [`connect`](#connect) | `url` + the popup + `pending` | `channels:write` |
+
+**Permissions** — `CRM.CHANNEL.WHATSAPP.CREATE`, checked on `url`, `pending`,
+`exchange` **and** `complete`. Several 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 gets a list without it rather than losing the
+page.
+
+The callback is the exception, and necessarily so: a browser arriving on a
+redirect carries no token of ours, so there is no role there to check. What it
+trusts instead is the signed `state` Meta round-trips to it — this service
+issued it, to that account, with that permission already checked, within the
+hour. It never widens anything: the plan, the quota and the number are all
+re-checked, and `complete` runs the role check again with a real caller behind
+it.
+
+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, so `types` leaves them
+out entirely.
+
+---
+
+## The shape of it
+
+```
+  your console                     Meta                      our backend
+  ────────────                     ────                       ───────────
+
+  types()      ────────────────────────────────────────────▶  the picker
+  url()        ────────────────────────────────────────────▶  { url, state }
+      │
+      └─ popup ─▶  oauth.automationsbuilder.com/whatsapp_channel_signup
+                           │
+                           └─ ▶ facebook.com/.../dialog/oauth
+                                they pick or create a number
+                           │
+                           └─ code + state ──────────────▶   oauth-callback
+                                                             · redeem the code
+                                                             · long-lived token
+                                                             · read the numbers
+                                                             · write a record
+                           ┌──────── 302 ─────────────────────────┘
+                           ▼
+  ?status=ready&token=…
+  pending(token) ──────────────────────────────────────────▶  numbers + prefill
+  complete()     ──────────────────────────────────────────▶  the channel
+```
+
+Three things about the middle of that are worth knowing before you build it:
+
+- **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 you open is a launcher, not the dialog.** `url` answers a page on the
+  BSP app's own domain carrying the dialog as its `?redirect=`, because Meta ties
+  an app's login dialog to that domain and your console is not on it. The page
+  forwards and is otherwise not involved. `dialogUrl` is the dialog itself, if
+  you want to see what the app was asked for.
+- **One redirect is registered with Meta, and it is ours.** Your `redirectUri`
+  is where *we* send the browser afterwards; Meta never sees it. So a new
+  console, a new environment or a new path needs no change at Meta — only an
+  entry on our return allowlist.
+- **The number is not known until the token is read.** The dialog tells its
+  *opener* which WABA and number were set up, by `postMessage`; a server-side
+  callback has no opener. So the service asks Meta what the token was granted,
+  and what numbers those WABAs hold. Usually that is exactly one number and the
+  record is bound to it — but an authorisation can cover several, and then
+  somebody has to pick. That is `status=select`.
+
+`connect()` drives the whole browser half for you.
+
+---
+
+## `types`
+
+```ts
+const { data } = await crm.channelOnboarding.types();
+
+// [
+//   { type: 'whatsapp', label: 'WhatsApp',
+//     slug: 'whatsapp_channels_28335', limit: 3, used: 1, remaining: 2 },
+// ]
+```
+
+**Every row returned is connectable.** Render them as they come: there is no
+`available` flag to branch on and no row to grey out. A family is left out when:
+
+| Left out because | What to say |
+| --- | --- |
+| The plan carries none of the inclusion | Offer an upgrade |
+| Every unit of it is spent | "You have used all 3 of your WhatsApp channels" |
+| The caller's role cannot create one | "Ask the account owner" |
+| No BSP is configured for the family | Our problem, not theirs — contact support |
+| The family is not onboarded here yet | Facebook and Instagram, today |
+
+An empty list therefore means there is nothing to offer this caller at all, and
+the "add a channel" button is what to hide. The reason is not returned; if you
+need to explain one, `url()` answers with the specific refusal — `402` for the
+plan, `403` for the role, `provider_not_configured` for the BSP.
+
+`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({
+  redirectUri: 'https://console.example.com/settings/channels?from=wizard',
+});
+// { url, dialogUrl, state, redirectUri, callbackUri, 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 |
+| `provider` | The BSP to connect through, by provider code. Omit for whichever is active for the family |
+| `redirectUri` | **Required.** Where **we** hand the browser back when the dialog is done |
+
+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, 409
+`onboarding_callback_not_configured` when this deployment has no callback URL,
+400 `redirect_uri_required` when the call names no return at all, 400
+`redirect_uri_not_allowed` for a return we are not configured for.
+
+**`redirectUri` is required**, and nothing is defaulted in its place: the
+callback is a redirect with no caller and no session, so this is the only thing
+that says where the browser goes when the dialog is done. A signup with nowhere
+to return to would strand somebody on a URL registered at Meta.
+
+It is matched **by origin**, not exactly, so you are free to carry your own path
+and query on it — `?from=wizard` above comes back alongside our `status`, which
+is how one page can start several flows and tell them apart. Only the origin has
+to be on the service's list, because that is what decides who receives a
+connected number's details.
+
+> **The origin check is currently commented out** in `url()` — any absolute URL
+> a caller sends is taken as given, so `CHANNEL_ONBOARDING_REDIRECT_URIS` has no
+> live effect at all now that there is no default to supply. That makes this an
+> open redirect with a signup outcome attached: a `token` and a number's details
+> land wherever the request asked. Fine behind a trusted console while a tunnel
+> is in play; restore `resolveReturnUri` before this is reachable by anyone else.
+
+`url` is the launcher —
+`https://oauth.automationsbuilder.com/whatsapp_channel_signup?redirect=<the dialog>`
+— and it is what you open. The dialog rides on it percent-encoded, so read it
+back with `URLSearchParams` rather than by splitting on `redirect=`: the dialog
+carries a query of its own, and the first `&` in it comes before the state.
+`dialogUrl` is that inner URL, answered for inspection; opening it directly
+skips the launcher, which works only if the Meta app is registered against
+whatever origin you opened it from.
+
+`provider` pins which BSP the channel is created against. Leave it out and the
+service uses the row that is `active` for the family, which is the right answer
+almost always; name a code when it is not — a second BSP, a per-currency app, an
+app still being tested. A named code does **not** have to be the active one, but
+it has to be configured for this family (400 `provider_type_mismatch`), it has
+to exist (404 `provider_not_found`) and it has to carry `app_id`, `app_secret`
+and `config_id` (409 `provider_not_configured`, which names the missing ones).
+Whatever is resolved comes back as `provider` and is signed into the state, so
+the callback redeems the code with that same app's secret — which matters,
+because the BSP a channel is created against is permanent.
+
+Note this is deliberately independent of `types`: that lists what the *active*
+provider offers, so a family can be absent there and still connectable by
+naming a code.
+
+`callbackUri` is what Meta was given. It is the same for every call, and it is
+the one URL that has to appear in each BSP app's *Valid OAuth Redirect URIs* —
+answered here so an operator can read it off a live response rather than off a
+deployment variable.
+
+`state` is ours, not Meta's: signed, bound to this account, and carrying the
+inclusion, the BSP and your `redirectUri`. **You do not need to keep it.** The
+callback is the only thing that reads it, which is the point — there is nothing
+for a browser to hold on to, lose, or have taken off it. 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".
+
+---
+
+## The callback
+
+```
+GET /v1/channels/onboarding/oauth-callback?code=…&state=…
+```
+
+Meta's redirect, and not a call you make. It is public — a redirect cannot carry
+a token — and it **always answers with a 302**, because there is a person in a
+browser on the other end of it and a JSON error would strand them on a URL with
+no way back. Everything it has to say it says on your own page:
+
+```
+https://console.example.com/settings/channels
+  ?from=wizard               ← yours, untouched
+  &status=ready
+  &token=6721f0…             ← pass to pending() and complete()
+  &numbers=1
+  &wabaId=…&phoneNumberId=…
+  &displayPhoneNumber=%2B91+93116+36081&verifiedName=Acme+Support
+  &expiresAt=2026-10-26T09:12:00.000Z
+```
+
+| `status` | What it means |
+| --- | --- |
+| `ready` | One number, already bound to the record. `complete()` needs nothing but a name |
+| `select` | The authorisation covered several. Read them with `pending()` and let the person pick |
+| `error` | `code` is the service's own code and `message` is a sentence you can show as it is |
+
+`status=error` is how every refusal after the dialog arrives — `quota_exceeded`
+if the last unit went in another tab, `phone_number_in_use` if somebody
+connected the number meanwhile, `onboarding_code_rejected` if Meta would not
+redeem the code, `onboarding_no_numbers` if the WABA has nothing connectable on
+it. None of them is a status code you can catch; branch on `code`.
+
+The one thing that does not redirect is a `state` we cannot read — expired,
+tampered with, or missing. That field is the one naming the page to go back to,
+so there is nowhere safe to send the browser, and it answers 400
+`invalid_onboarding_state` / `onboarding_state_expired` instead.
+
+**Nothing is created yet.** The record the `token` points at holds the
+long-lived token, encrypted, belongs to this account, can be used once, and
+expires in an hour.
+
+---
+
+## `pending`
+
+```ts
+const { data } = await crm.channelOnboarding.pending(token);
+
+// {
+//   id: '6721f0...',
+//   expiresAt: '...',
+//   type: 'whatsapp',
+//   numbers: [
+//     { id: '...', wabaId: '...', displayPhoneNumber: '+91 93116 36081',
+//       verifiedName: 'Acme Support', status: 'CONNECTED',
+//       codeVerificationStatus: 'VERIFIED', qualityRating: 'GREEN' },
+//   ],
+//   phoneNumber: { ... },   // set when there was exactly one
+//   defaults: { name: 'Acme Support', color: '#075E54', currency: 'USD' },
+// }
+```
+
+What the `token` on the return URL refers to, in full: Meta's own description of
+each number the authorisation covers, and the prefill for the confirmation form.
+The query string carries a summary of the same thing, so for `status=ready` you
+can skip this call and show the form from the URL alone.
+
+`numbers` is what to render as a picker when `status=select`. A number another
+channel already holds is not in it — the service drops those rather than
+offering a choice that cannot be taken.
+
+`phoneNumber` is Meta's description, not an echo of anything you sent: the
+service read the WABA's numbers with the token it had just minted, which is what
+proves the token covers that WABA and the number is really on it.
+
+404 `not_found` for a record that has expired, been completed, or belongs to
+another account — one answer for all three, because whose it is is not something
+to disclose.
+
+---
+
+## `complete`
+
+```ts
+const { data: channel } = await crm.channelOnboarding.complete({
+  token: candidate.id,
+  phoneNumberId: chosen.id,   // required only for status=select
+  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.
+
+`phoneNumberId` names which number to connect, and is needed exactly when the
+record covers more than one. It has to be one of them: a number the
+authorisation did not cover is refused rather than attempted, or a caller could
+connect a WABA nobody granted us.
+
+**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 | |
+| --- | --- | --- |
+| 400 | `onboarding_number_required` | The record covers several numbers and none was named |
+| 400 | `onboarding_number_not_authorised` | `phoneNumberId` is not one the authorisation covered |
+| 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 |
+| 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.
+
+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({
+  redirectUri: 'https://console.example.com/settings/channels',
+  onProgress: ({ phase }) => setStatus(phase),
+});
+
+// candidate.numbers — one, or several to choose between
+const { data: channel } = await crm.channelOnboarding.complete({
+  token: candidate.id,
+  phoneNumberId: candidate.phoneNumber?.id ?? chosen.id,
+  name: form.name,
+});
+```
+
+`url()` → popup → wait for the popup to come back to your `redirectUri` →
+`pending()`, resolving with exactly what `pending()` returns. It creates
+nothing, so the person still confirms the number before it becomes a channel.
+
+**`redirectUri` is required, and has to be a page on this page's own origin**,
+since reading the outcome off the popup is what ends the wait. A landing page on
+another origin cannot be read at all, and the wait ends with `popup_closed` when
+the person shuts the window.
+
+**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 | |
+| --- | --- |
+| `redirectUri` | **Required**, and on this page's own origin. Passed through to `url()` |
+| `type`, `slug`, `provider` | Passed through to `url()` |
+| `onProgress` | `opened` → `returned` |
+| `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 |
+| `signup_error` | The flow came back refused. `message` is the sentence to show, and `reason` is the service's own code — `quota_exceeded`, `phone_number_in_use`, ... |
+| `timeout` | Still open after `timeoutMs` |
+| `unsupported_environment` | Not a browser — drive the calls yourself |
+
+Everything the service refused *before* the dialog opened 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 === 'popup_closed') return;         // not an error worth showing
+    return showNotice(err.message);
+  }
+  throw err;                                          // a 402, a 409, ...
+}
+```
+
+### Driving the dialog yourself
+
+Without the helper: call `url()`, open `data.url` yourself (or navigate to it),
+and read `status` and `token` off the query string when the browser lands back
+on your `redirectUri`. The flow survives a full page load, which is the reason
+to do it this way — the state lives in the signed `state` and in the pending
+record, not in your tab.
+
+If your landing page runs inside a popup and wants to close itself, post the
+query back to the opener and `awaitSignupReturn` will take it from there:
+
+```html
+<!-- At your redirectUri -->
+<script>
+  window.opener?.postMessage(location.search, window.origin);
+  window.close();
+</script>
+```
+
+### The dialog shape
+
+`url()` builds `extras` from the provider row, defaulting to what the panel runs
+today: `sessionInfoVersion: '2'` and `featureType:
+'whatsapp_business_app_onboarding'`, the variant that also onboards a number
+sitting on the WhatsApp Business app. A BSP whose app is configured differently
+overrides either on its `crmchannelproviders` row -- `provider.feature_type`,
+`provider.session_info_version` -- without a deploy. `only_waba_sharing` there
+is the migration flow.
+
+### Setting it up
+
+Three things, and none of them is in code:
+
+1. `CHANNEL_ONBOARDING_CALLBACK_URL` is this deployment's public
+   `/v1/channels/onboarding/oauth-callback`, and that exact string has to be in
+   *Valid OAuth Redirect URIs* on every BSP app you onboard through. Meta
+   compares it exactly, trailing slash included.
+2. `CHANNEL_ONBOARDING_REDIRECT_URIS` lists the origins we may hand the browser
+   back to, comma separated. This one is ours alone; Meta never sees it. With
+   the origin check commented out in `url()` and `redirectUri` now required,
+   **this variable currently does nothing** — set it anyway, so restoring
+   `resolveReturnUri` is a one-line change rather than a deployment.
+3. `CHANNEL_ONBOARDING_LAUNCH_URL` is the launcher page, and it already defaults
+   to the shared one. Change it only if a BSP app is registered against a
+   different domain; set it empty to hand the dialog URL back directly.
+
+With either of the first two unset, `url()` refuses rather than starting a
+dialog that has nowhere to come back to.
+
+---
+
+## `exchange`
+
+```ts
+const { data } = await crm.channelOnboarding.exchange({
+  state,            // from url()
+  code,             // from the dialog
+  wabaId,           // from the WA_EMBEDDED_SIGNUP message
+  phoneNumberId,
+});
+// { id, expiresAt, phoneNumber, defaults }
+```
+
+**The other path, for a code you hold yourself.** It only applies to a BSP app
+whose registered redirect is a page of *yours* rather than this service's
+callback — the `FB.login` flow, where the code comes back on your redirect and
+the `waba_id` / `phone_number_id` arrive separately as a `postMessage` from
+`facebook.com` carrying `WA_EMBEDDED_SIGNUP`. The SDK's `openSignup` waits for
+both halves and is kept for exactly this.
+
+Everything else is the same as the callback's: the code is redeemed, the token
+is traded for a long-lived one, the number is verified against the WABA, and a
+pending record comes back to `complete()`. The difference is that you name the
+number instead of the service discovering it.
+
+| 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 |
+
+---
+
+## What the service is doing for you
+
+Checks that nothing downstream repeats:
+
+1. **The plan has room** — at every step, 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. In the callback this filters as well as refuses: a
+   number that is taken is left out of the choice.
+3. **The token really covers the WABA** — the numbers are read back with the
+   minted token, which is the only thing that proves it.
+4. **The credential never reaches a browser.** The code goes to us, not to your
+   page; the long-lived token is encrypted at rest and swapped for a channel id;
+   what travels on the return URL is an outcome and a one-hour, single-use token
+   scoped to one account.
+
+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: