ab-ecosystem-cpass 1.0.12 → 1.0.13

package/docs/channels/onboarding.md

@@ -8,67 +8,93 @@ 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.
+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` |
-| [`exchange`](#exchange) | `POST /v1/channels/onboarding/exchange` | `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` |
-| [`connect`](#connect) | the three above, plus the popup | `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`, `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
+**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, and `types` reports them
-as `not_supported` so a picker can render the whole list it already renders.
+coming back; they are still created by the legacy stack, so `types` leaves them
+out entirely.
 
 ---
 
 ## 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                           │
-  └───────────────────────────────────────────────────────────────────────────┘
+  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
 ```
 
-Two things about the middle of that are easy to get wrong, and both cost an
-afternoon:
+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 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.
+- **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.
 
 ---
 
@@ -78,24 +104,26 @@ drive `FB.login`, or if your onboarding spans two page loads.
 const { data } = await crm.channelOnboarding.types();
 
 // [
-//   { type: 'whatsapp',  label: 'WhatsApp', available: true,
+//   { type: 'whatsapp', label: 'WhatsApp',
 //     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`:
+**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:
 
-| `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 |
+| 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
@@ -106,80 +134,164 @@ means *included, unmetered*. Absent is not zero.
 ## `url`
 
 ```ts
-const { data } = await crm.channelOnboarding.url();
-// { url, state, redirectUri, expiresAt, provider, remaining }
+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 |
-| `redirectUri` | Must be one of the service's configured redirects. Omit for the default |
+| `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, 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.
+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".
 
 ---
 
-## `exchange`
+## 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.exchange({
-  state,            // from url()
-  code,             // from the dialog
-  wabaId,           // from the WA_EMBEDDED_SIGNUP message
-  phoneNumberId,
-});
+const { data } = await crm.channelOnboarding.pending(token);
 
 // {
-//   id: '6721f0...',            // pass to complete() as `token`
+//   id: '6721f0...',
 //   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' },
+//   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' },
 // }
 ```
 
-**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.
+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.
 
-`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.
+`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.
 
-`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.
+`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.
 
-| 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.
+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.
 
 ---
 
@@ -188,6 +300,7 @@ would quietly take over the first one's message traffic.
 ```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',
@@ -199,6 +312,11 @@ Creates the channel and returns it in the same shape `channels.get()` does.
 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:
 
@@ -215,10 +333,17 @@ 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.
@@ -231,15 +356,26 @@ Only a create that succeeds spends the token.
 ```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),
+  redirectUri: 'https://console.example.com/settings/channels',
+  onProgress: ({ phase }) => setStatus(phase),
 });
 
-// Then show the card and the form, and call complete().
+// 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 → `exchange()`, resolving with exactly what `exchange()` returns.
-It creates nothing, so the person still confirms the number before it becomes a
-channel.
+`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,
@@ -248,8 +384,9 @@ 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` |
+| `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 |
 
@@ -259,57 +396,126 @@ Rejects with `EmbeddedSignupError`, whose `code` is one of:
 | --- | --- |
 | `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 |
+| `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 three calls yourself |
+| `unsupported_environment` | Not a browser — drive the calls yourself |
 
-Everything the service refused arrives as the usual `ApiError`, so handle both:
+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 === 'cancelled') return;           // not an error worth showing
+    if (err.code === 'popup_closed') return;         // not an error worth showing
     return showNotice(err.message);
   }
-  throw err;                                         // a 402, a 409, ...
+  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:
+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>
-  const params = new URLSearchParams(location.search);
-  window.opener?.postMessage(
-    { type: 'CRM_CHANNEL_ONBOARDING', code: params.get('code'), state: params.get('state') },
-    window.origin,
-  );
+  window.opener?.postMessage(location.search, window.origin);
+  window.close();
 </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.
+### 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
 
-Four checks that nothing downstream repeats:
+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.
+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.
-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.
+   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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ab-ecosystem-cpass",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "JavaScript/TypeScript SDK for the CPaaS CRM gateway: audience and channels",
   "license": "MIT",
   "main": "dist/index.js",