@salesforce/afv-skills 1.42.0 → 1.44.0

package/skills/service-de-channel-consent-configure/references/worked-examples.md

@@ -0,0 +1,134 @@
+# Worked examples: `service-de-channel-consent-configure`
+
+Reference runs for the three ConsentType paths. The ExplicitOptIn channel-side write, the read model, and the WhatsApp restriction below were verified live on `messaging_sdb6c` 2026-08-13.
+
+---
+
+## Worked example: ImplicitOptIn (opt-out only)
+
+Input:
+- `{CHANNEL_ID}` = `0MjSG00000030wL0AQ` (Enhanced WhatsApp channel `DummyChannelForTesting`)
+- `{LANGUAGE}` = `en_US`
+
+**Stage 1** read shows `PlatformType=Enhanced`, `ConsentType=ImplicitOptIn`, and one existing `MsgChannelLanguageKeyword` (`3OrSG0000002kUz0AI`, `MasterLanguage=en_US`) with:
+```text
+OptOutKeywords    = unsubscribe_en_US,stopall_en_US,cancel_en_US,quit_en_US,stop_en_US,end_en_US
+OptOutConfirmation = You've opted out of receiving messages from us, so we won't contact you again.
+```
+That record already satisfies the ImplicitOptIn readiness rule (`OptOutKeywords` + `OptOutConfirmation` both non-null), so the skill takes the **no-op path**:
+
+```json
+{"ok": true, "noop": true, "consentType": "ImplicitOptIn",
+ "languageKeywordIds": ["3OrSG0000002kUz0AI"],
+ "message": "Consent already configured and activation-ready"}
+```
+
+If instead there were **no** keyword record, the skill would create one:
+
+```bash
+sf data create record --sobject MsgChannelLanguageKeyword \
+  --values "MessagingChannelId=0MjSG00000030wL0AQ MasterLanguage=en_US \
+OptOutKeywords=stop,unsubscribe,cancel OptOutConfirmation='You have been unsubscribed.'"
+```
+
+and report `Success — Consent configured — channel 0MjSG00000030wL0AQ is now ImplicitOptIn with an en_US keyword record. Activation-ready.`
+
+---
+
+## Worked example: ExplicitOptIn (channel-side write verified live)
+
+Input:
+- `{CHANNEL_ID}` = `0MjSG0000000D9V0AU` (Enhanced Facebook channel `FACEBOOK_null_101192609043587`)
+- `{CONSENT_TYPE}` = `ExplicitOptIn`
+- `{LANGUAGE}` = `en_US`
+
+**Stage 1**: `PlatformType=Enhanced`, `ConsentType=ImplicitOptIn`, `OptInPrompt=null`. Continue.
+
+**Stage 2**: ExplicitOptIn chosen. Facebook accepts it (unlike WhatsApp rich content — see below).
+
+**Stage 3**: collect `OptInPrompt` = `Reply YES to receive messages`.
+
+**Stage 5 (channel PATCH)** — verified live, note the single-quoting of the multi-word prompt:
+
+```bash
+$ sf data update record --sobject MessagingChannel --record-id 0MjSG0000000D9V0AU \
+    --values "ConsentType=ExplicitOptIn OptInPrompt='Reply YES to receive messages'"
+# → {"id":"0MjSG0000000D9V0AU","success":true,"errors":[]}
+```
+
+Re-read confirmed `ConsentType=ExplicitOptIn`, `OptInPrompt=Reply YES to receive messages`.
+
+**Stage 5 (keyword record)** — the record must also carry `OptInKeywords` (plus the ImplicitOptIn opt-out fields). Create or update the `en_US` record:
+
+```bash
+sf data update record --sobject MsgChannelLanguageKeyword --record-id <3Or...> \
+  --values "OptInKeywords='yes,start,subscribe' OptInConfirmation='You are subscribed'"
+```
+
+(Live keyword shape confirmed on sdb6c: e.g. Facebook channel `0MjSG0000000Beb0AE` carries `OptInKeywords=yes,sure` — multiple opt-in keywords as a comma-separated string.)
+
+**Stage 6**: re-read channel + keyword record; `OptInPrompt` non-null on the channel and `OptInKeywords`+`OptOutKeywords`+`OptOutConfirmation` non-null on the keyword record → activation-ready.
+
+**Stage 7**:
+```json
+{"ok": true, "consentType": "ExplicitOptIn", "channelFieldsSet": ["ConsentType","OptInPrompt"],
+ "languageKeywordId": "3Or...", "language": "en_US", "created": false, "activationReady": true}
+```
+
+*(The test channel was restored afterward to `ConsentType=ImplicitOptIn, OptInPrompt=null` — passing `OptInPrompt=''` nulls the field.)*
+
+---
+
+## Worked example: DoubleOptIn
+
+Input:
+- `{CHANNEL_ID}` = an Enhanced Text (SMS) channel
+- `{CONSENT_TYPE}` = `DoubleOptIn`
+
+**Stage 3** collects both `OptInPrompt` and `DoubleOptInPrompt`.
+
+**Stage 5 (channel PATCH)** — all three fields in one write:
+
+```bash
+sf data update record --sobject MessagingChannel --record-id '{CHANNEL_ID}' \
+  --values "ConsentType=DoubleOptIn OptInPrompt='Reply YES to subscribe' \
+DoubleOptInPrompt='Reply CONFIRM to confirm your subscription' IsRequireDoubleOptIn=true"
+```
+
+**Stage 5 (keyword record)** — needs `OptInKeywords`, `DoubleOptInKeywords`, `OptOutKeywords`, `OptOutConfirmation`:
+
+```bash
+sf data update record --sobject MsgChannelLanguageKeyword --record-id <3Or...> \
+  --values "OptInKeywords=yes,start DoubleOptInKeywords=confirm \
+OptOutKeywords=stop,unsubscribe OptOutConfirmation='You have been unsubscribed.'"
+```
+
+(Live example on sdb6c: keyword record `3OrSG00000002rR0AQ` has both `OptInKeywords=yes` and `DoubleOptInKeywords=yes`, confirming DoubleOptIn uses both keyword fields.)
+
+**Stage 6** verifies `OptInPrompt` + `DoubleOptInPrompt` non-null on the channel and `OptInKeywords` + `DoubleOptInKeywords` + opt-out fields non-null on the keyword record.
+
+---
+
+## Worked example: WhatsApp rich-content rejects ExplicitOptIn (verified live)
+
+Input:
+- `{CHANNEL_ID}` = `0MjSG00000030wL0AQ` (Enhanced WhatsApp channel with rich content)
+- User asks for `ExplicitOptIn`
+
+**Stage 5** PATCH is rejected server-side:
+
+```bash
+$ sf data update record --sobject MessagingChannel --record-id 0MjSG00000030wL0AQ \
+    --values "ConsentType=ExplicitOptIn OptInPrompt='Reply YES to receive messages'"
+# → INVALID_INPUT: Consent Type for WhatsApp Messaging Channel with rich content
+#    cannot be set to EXPLICIT_OPT_IN(db=1,api=ExplicitOptIn).
+```
+
+The skill surfaces this rather than retrying:
+
+```json
+{"ok": false, "kind": "channel-patch-failed",
+ "message": "Consent Type for WhatsApp Messaging Channel with rich content cannot be set to EXPLICIT_OPT_IN. WhatsApp rich-content channels support ImplicitOptIn only."}
+```
+
+User-facing: `Error: This WhatsApp channel has rich content and only supports ImplicitOptIn — the server rejected ExplicitOptIn. Configure opt-out keywords under ImplicitOptIn instead.`

package/skills/service-de-channel-create/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: service-de-channel-create
+description: "**INTERNAL USE ONLY — invoked by `service-de-headless-channel-configure` orchestrator.** Insert an Enhanced messaging `MessagingChannel` record (plus its child `MessagingChannelUsage` as a free server-side side-effect) of any supported type — WhatsApp, LINE, Apple Business Chat, Facebook, or SMS (Text). Given a `{MESSAGE_TYPE}` and the corresponding type-specific inputs, runs the shared preflight → Connect-insert → verify flow and branches only where a type genuinely differs (request body, prerequisites, error classes). Uses the sanctioned `POST /services/data/v{V}/connect/livemessage/channels` Connect REST endpoint — no Aura session, no token extracted into shell state. **Users should always invoke `service-de-headless-channel-configure` instead — it handles insert → route → activate in one flow.** Use this skill when inserting a messaging channel of any type; it replaces the four former per-type creation skills."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+  domains: ["Service"]
+  cliTools:
+    - tool: ["curl"]
+      semver: ">=7.0.0"
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "service-de-channel-activate"
+    - "service-de-channel-consent-configure"
+    - "service-de-channel-routing-configure"
+    - "service-de-headless-channel-configure"
+    - "service-de-waba-integrate"
+---
+
+# Inserting Messaging Channels
+
+## Reference File Index
+
+| Reference file | Load when |
+| --- | --- |
+| `references/whatsapp.md` | `MESSAGE_TYPE=WhatsApp` — WABA partnership (Stage 2) + SF-side manage-WABA (Stage 3) prereqs, request body, WhatsApp gotchas. |
+| `references/line.md` | `MESSAGE_TYPE=Line` — optional token verify, `authDetails` body shape, LINE gotchas. |
+| `references/apple.md` | `MESSAGE_TYPE=AppleBusinessChat` — empty-config body, Apple-precondition errors, Apple gotchas. |
+| `references/facebook.md` | `MESSAGE_TYPE=Facebook` — browser OAuth → page-selection flow, Facebook gotchas. |
+| `references/sms.md` | `MESSAGE_TYPE=Text` — phone-number platform key, present-but-unvalidated `smsProvider`, number-provisioning prerequisite (caller's), SMS gotchas. |
+| `references/connect-insert.md` | Shared authProviderId lookup + Connect POST + response-classification detail (Stage 4). |
+| `references/worked-examples.md` | End-to-end traces per type (fresh insert, preflight short-circuit, OAuth). |
+
+## What this skill does
+
+Given a `{MESSAGE_TYPE}` and its inputs, creates a `MessagingChannel` record with
+`PlatformType=Enhanced`, `IsActive=false`. The same server-side path
+(`LiveMessageSetupServiceImpl.addChannel` → `LiveMessageChannelsUtil.findOrCreateCsotMessagingChannel`)
+also inserts a `MessagingChannelUsage` row (`DeploymentType=Conversation`, `DeploymentStatus=New`
+on fresh insert — `Disabled` on a channel that was previously activated then deactivated) — we get
+it for free.
+
+**One primary path for every type: Connect REST API.**
+`POST /services/data/v{V}/connect/livemessage/channels` with an org OAuth session managed by
+`sf api request rest`. Public, sanctioned, live since API v66+. No Aura session, no token extracted
+into shell state.
+
+**Idempotent** on `(MessagingPlatformKey, MessageType)` — re-firing with the same platform key
+returns the existing channel's id. This matters because `MessagingChannel` records are not deletable
+via standard means, so the preflight (Stage 1) is the practical idempotency guard.
+
+All types return the **same envelope shape**, so callers don't branch on type after insert:
+`{ok, channelId, mcuId, developerName, isActive:false, messageType, messagingPlatformKey, path, created, durationMs}`.
+
+### Supported types (the only branch point)
+
+| `{MESSAGE_TYPE}` | Platform key (`messagingPlatformKey`) | Prerequisite (caller supplies) | Body extras | Ref |
+| --- | --- | --- | --- | --- |
+| `WhatsApp` | Phone Number ID | `service-de-waba-integrate` (run in Stage 2-3) | `externalAccountId`, `isoCountryCode` | `whatsapp.md` |
+| `Line` | LINE channel id | LINE id + secret + token (LINE Developers Console) | `authDetails.{client_secret,access_token}` | `line.md` |
+| `AppleBusinessChat` | Apple BC Account ID (GUID) | Apple BC Account ID (register.apple.com/business-chat) | *(none — empty config)* | `apple.md` |
+| `Facebook` | Facebook Page ID | *OAuth handled internally* | `authDetails: {}` (OAuth-derived) | `facebook.md` |
+| `Text` | Phone number / short code | number already provisioned (caller supplies) | `smsProvider` (key required, value may be `""`), `isoCountryCode` | `sms.md` |
+
+Unsupported (would need their own leaf logic, not yet built): `WeChat`, `MsCopilot`, `Alexa`.
+For these, emit the `unsupported-type` envelope (Stage 0).
+
+## When NOT to use this skill
+
+- **End-to-end setup.** If the user wants insert → route → activate, invoke
+  `service-de-headless-channel-configure` — it orchestrates this skill plus routing, consent, and
+  activation. This skill only handles the insertion step (see Stage 0).
+- **The channel already exists and you only want to re-route / activate it.** Skip insertion;
+  call `service-de-channel-routing-configure` / `service-de-channel-activate` with the existing
+  `channelId`.
+
+## Inputs (from caller)
+
+- `{MESSAGE_TYPE}` — one of `WhatsApp`, `Line`, `AppleBusinessChat`, `Facebook`, `Text`.
+  Case-sensitive (matches the SF picklist). `Text` is the enum value for SMS — there is no `SMS` type.
+- `{ORG_ALIAS}` — optional; `sf` CLI target-org alias. Default: `sf config get target-org`.
+- `{API_VERSION}` — optional; Connect API version. Default: the org's current API version
+  (`sf org display --json | jq -r '.result.apiVersion'`). Always use the org's native version to
+  avoid 404s.
+- `{CHANNEL_NAME}` — display name shown in Setup → Messaging Settings. Required for
+  `AppleBusinessChat` (no phone/screen-name fallback); prompted if omitted for others.
+
+Type-specific inputs:
+
+- **WhatsApp:** `{WABA_ID}` (sent as `externalAccountId`), `{PHONE_NUMBER_ID}` (the platform
+  key — **must differ from WABA_ID**), `{ISO_COUNTRY_CODE}` (optional, default `US`).
+- **Line:** `{LINE_CHANNEL_ID}` (platform key), `{LINE_CHANNEL_SECRET}`, `{LINE_ACCESS_TOKEN}`,
+  `{VERIFY_TOKEN_FIRST}` (optional, default `true`).
+- **AppleBusinessChat:** `{APPLE_BC_ID}` (platform key, GUID).
+- **Facebook:** `{PAGE_ID}` (optional — OAuth fetches/prompts if absent).
+- **Text (SMS):** `{SMS_NUMBER}` (the platform key — the phone number / short code string, already
+  provisioned to the org), `{SMS_PROVIDER}` (sent as `smsProvider` — the `smsProvider` **key must be
+  present** in the body or the insert 400s with "SMS provider is missing", but its **value is not
+  validated or stored**, so an empty string `""` works; default to `""` when the caller doesn't supply
+  a provider), `{ISO_COUNTRY_CODE}` (optional, default `US`). This skill does not provision the
+  number — the caller must already know their number.
+
+## Output (to caller)
+
+**Success:**
+```json
+{"ok": true, "channelId": "0Mj...", "mcuId": "0gL...", "developerName": "...",
+ "isActive": false, "messageType": "{MESSAGE_TYPE}", "messagingPlatformKey": "...",
+ "path": "connect" | "preflight", "created": true | false, "durationMs": 1234}
+```
+`created: false` + `path: "preflight"` means the row already existed and was returned idempotently.
+
+**Failure (shared):**
+```json
+{"ok": false, "kind": "wrong-skill", "correctSkill": "service-de-headless-channel-configure", "hint": "..."}
+{"ok": false, "kind": "unsupported-type", "supportedTypes": ["WhatsApp","Line","AppleBusinessChat","Facebook","Text"], "hint": "..."}
+{"ok": false, "kind": "missing-input", "missing": ["..."], "hint": "caller must provide all required inputs for this type"}
+{"ok": false, "kind": "auth",     "hint": "OAuth token invalid / expired — run 'sf org login web'"}
+{"ok": false, "kind": "business", "message": "...", "errorCode": "..."}
+{"ok": false, "kind": "transport","status": 500, "message": "..."}
+{"ok": false, "kind": "verify-failed", "hint": "Connect returned 201 but follow-up SOQL shows no matching channel"}
+```
+Type-specific failure kinds (`partnership-blocked`, `user-declined`, `waba-manage-failed`,
+`meta-precondition` for WhatsApp; `line-token-invalid` for LINE; `apple-precondition` for Apple;
+`oauth-not-complete`, `oauth-failed` for Facebook) are documented in the per-type reference files.
+
+---
+
+## Stage 0: Enforce orchestrator-only invocation
+
+**This skill is INTERNAL USE ONLY.** It should only be invoked by the
+`service-de-headless-channel-configure` orchestrator.
+
+If the user's original request was to "install", "set up", "create", or "activate" a messaging
+channel (or any phrasing that implies end-to-end setup), immediately return:
+
+```json
+{
+  "ok": false,
+  "kind": "wrong-skill",
+  "hint": "This is an internal insertion skill. For end-to-end channel setup (insert → route → activate), invoke 'service-de-headless-channel-configure' instead with the desired MESSAGE_TYPE.",
+  "correctSkill": "service-de-headless-channel-configure"
+}
+```
+
+And render to the user:
+```text
+Error: Wrong skill invoked.
+
+This skill (service-de-channel-create) only handles the insertion step.
+For complete channel setup, use: /service-de-headless-channel-configure
+
+That orchestrator runs: insert → configure routing → activate in one flow.
+```
+
+**Only proceed to Stage 0.1 if:**
+- This skill was invoked programmatically by `service-de-headless-channel-configure`
+- The user explicitly stated they ONLY want insertion (not routing or activation)
+- This is a retry/resume scenario where routing/activation already succeeded
+
+When in doubt, redirect to the orchestrator.
+
+### Stage 0.1: Validate type and required inputs
+
+Look up `{MESSAGE_TYPE}` in the supported-types table. If absent, emit the `unsupported-type`
+envelope and return.
+
+Validate the type's required inputs are present (**Facebook is the exception** — no required
+inputs; OAuth → page selection → prompts happen inside the Facebook flow). If any are missing,
+emit `missing-input` with the list and return.
+
+**WhatsApp only:** additionally assert `{WABA_ID} != {PHONE_NUMBER_ID}` — they are distinct Meta
+entities and reusing one value for both causes cryptic activation failures. If equal, emit
+`{ok:false, kind:"invalid-input", hint:"WABA_ID and PHONE_NUMBER_ID must differ — WABA_ID is the WhatsApp Business Account ID; PHONE_NUMBER_ID is a specific phone number within it. Find both in Meta Business Manager → WhatsApp Accounts."}`.
+
+Capture `{T0} = Date.now()` for `durationMs`.
+
+### Stage 0.2: Establish the scratch directory
+
+Every transient artifact this skill writes (preflight query results, request bodies, Connect
+responses) goes into a per-run scratch directory rooted inside the harness working area — never a
+bare absolute `/tmp` path, which is world-writable and non-portable. Establish it once:
+
+```bash
+SCRATCH_DIR="$(mktemp -d "${outputDir:-${TMPDIR:-/tmp}}/icc.XXXXXX")"
+```
+
+The base dir is the harness-provided `${outputDir}` when set, else the private user-scoped
+`${TMPDIR}`, else `/tmp` only as a last resort. All later stages (and the reference flows) write
+under `${SCRATCH_DIR}/`; the durable report stays under `${outputDir}`.
+
+---
+
+## Stage 1: Preflight — is the channel already here?
+
+SOQL-probe for an existing row **first**; a hit lets us skip all prerequisites and the insert.
+
+**For Facebook without a `{PAGE_ID}`, skip this stage** — the page id isn't known until OAuth →
+page selection completes (see `references/facebook.md`). Run the preflight after page selection.
+
+**Two queries, not a subquery.** The `(SELECT ... FROM MessagingChannelUsages)` child subquery
+fails with `INVALID_TYPE` on orgs where the child relationship is unnameable (verified on
+`wadtesting` / PRODDEBUG). The FK-keyed form works everywhere.
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, DeveloperName, MasterLabel, IsActive, MessagingPlatformKey FROM MessagingChannel WHERE MessagingPlatformKey = '{PLATFORM_KEY}' AND MessageType = '{MESSAGE_TYPE}'" \
+  --json > "${SCRATCH_DIR}/preflight.json"
+```
+
+If `records.length === 1`:
+- Record `{CHANNEL_ID}`, `{DEVELOPER_NAME}`, `{IS_ACTIVE}`.
+- Second query for the MCU by FK:
+  ```bash
+  sf data query --target-org '{ORG_ALIAS}' \
+    --query "SELECT Id, DeploymentStatus FROM MessagingChannelUsage WHERE MessagingChannelId = '{CHANNEL_ID}'" \
+    --json > "${SCRATCH_DIR}/preflight-mcu.json"
+  ```
+  Record `{MCU_ID}` (empty MCU: flag, don't fail — the activation skill handles it).
+- Emit the success envelope with `path: "preflight", created: false`. Return.
+
+If `records.length > 1`: ambiguous (uniqueness should prevent this) — proceed with the first,
+note a warning in the envelope.
+
+If `records.length === 0`: proceed to Stage 2.
+
+---
+
+## Stage 2-3: Type-specific prerequisites
+
+Most types have **no** prerequisite here — go straight to Stage 4.
+
+- **WhatsApp:** requires the Meta WABA↔Salesforce partnership (Stage 2, via
+  `service-de-waba-integrate`) and the SF-side webhook subscription + credit-line share
+  (Stage 3, `POST /connect/livemessage/whatsapp/business-account`). **Load `references/whatsapp.md`
+  and follow it** before inserting.
+- **Line:** optional token preflight against `https://api.line.me/v2/bot/info` if
+  `{VERIFY_TOKEN_FIRST}` is true. **See `references/line.md`.**
+- **Facebook:** browser-based OAuth authorization + page-list fetch + page selection happen here,
+  before the insert. **Load `references/facebook.md` and follow it.**
+- **Apple:** none. (Apple's certificate handshake is provisioned on Apple's side and is per-message
+  at runtime, not at channel insert — see `references/apple.md`.)
+- **Text (SMS):** none at insert. The number must already be provisioned to the org and the caller
+  must know its `smsProvider`, but this skill performs no provisioning step — it inserts the record for
+  a number the caller already has. (ESP registration runs at activation, not insert — see
+  `references/sms.md`.)
+
+---
+
+## Stage 4: Insert via Connect REST API
+
+Shared across all types. The only per-type difference is the **request body**; the authProviderId
+lookup, the POST invocation, and the response-classification table are identical.
+
+### Stage 4.1: authProviderId (org-global; required for every type except Text)
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id FROM AuthProvider WHERE DeveloperName = 'LiveMessageSetup'" \
+  --json > "${SCRATCH_DIR}/authprovider.json"
+```
+
+One row → `{AUTH_PROVIDER_ID}`. Zero rows → **branch on type:**
+- **`Text`** — non-fatal. Text's Connect signature doesn't take `authProviderId`, so leave
+  `{AUTH_PROVIDER_ID}` unset and continue to Stage 4.2; the POST omits the parameter entirely (see
+  below). Do **not** emit the business error for Text — an org that has never run LiveMessage setup
+  is exactly where the Text-only path matters, and blocking here would make the advertised SMS insert
+  unreachable on those orgs.
+- **every other type** (`WhatsApp`, `Line`, `AppleBusinessChat`, `Facebook`) — the org has never run
+  LiveMessage setup and the insert can't proceed; emit
+  `{ok:false, kind:"business", message:"No AuthProvider 'LiveMessageSetup' found — run the Messaging Setup wizard once on this org first"}`.
+
+The Connect endpoint rejects the POST with `400 ILLEGAL_QUERY_PARAMETER_VALUE "Missing argument
+authProviderId"` if this URL parameter is absent — verified for every type **except `Text`**, Apple
+included. (`Text` has its own Connect signature that doesn't require it.) When the lookup finds a row,
+send `authProviderId` for every type including Text (harmless there); when it finds none, only Text may
+proceed, and it proceeds **without** the parameter. `authProviderId` goes in the URL query string,
+never the body (body → `400 JSON_PARSER_ERROR "Unrecognized field 'authProviderId'"`).
+
+### Stage 4.2: Build the type-specific body and POST
+
+Resolve `{CHANNEL_NAME}` first (prompt if required and absent — see per-type ref). Then build the
+body from the supported-types table and POST. **Write the body to a file** (`--body @...`) — LINE
+tokens are long and can contain shell-hostile characters.
+
+Append the `authProviderId` query parameter only when Stage 4.1 resolved one — otherwise (the
+Text-with-no-AuthProvider case) POST to the bare endpoint, since an empty `?authProviderId=` would
+trip the same `ILLEGAL_QUERY_PARAMETER_VALUE`:
+
+```bash
+URL="/services/data/v{API_VERSION}/connect/livemessage/channels"
+[ -n "${AUTH_PROVIDER_ID:-}" ] && URL="${URL}?authProviderId=${AUTH_PROVIDER_ID}"
+
+sf api request rest "${URL}" \
+  --method POST --target-org '{ORG_ALIAS}' \
+  --header 'Content-Type: application/json' --header 'Accept: application/json' \
+  --body @"${SCRATCH_DIR}/body.json" --include > "${SCRATCH_DIR}/connect-response.txt" 2>&1
+```
+
+`--include` prints the HTTP status/header block before the body — read the status from there, not
+a trailing `-w` marker. `sf api request rest` manages OAuth internally.
+
+**For the exact per-type body shape and the full response-classification table (including the
+`DUPLICATE_VALUE` race back to Stage 1, the Facebook `AUTH_PROVIDER_NEEDS_AUTH` 401-vs-400
+disambiguation, and per-type precondition errors), load `references/connect-insert.md` plus the
+per-type ref.**
+
+---
+
+## Stage 5: Verify the insert
+
+Two queries (same no-subquery reason as Stage 1). Keep to the universal field set —
+`ExternalAccountId` and `MessagingPlatform` don't exist on all orgs.
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, DeveloperName, MasterLabel, MessageType, IsActive, MessagingPlatformKey FROM MessagingChannel WHERE Id = '{CHANNEL_ID}'" --json
+
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, DeploymentStatus, DeploymentType FROM MessagingChannelUsage WHERE MessagingChannelId = '{CHANNEL_ID}'" --json
+```
+
+Expected: channel `IsActive=false`; exactly one MCU, `DeploymentType=Conversation`,
+`DeploymentStatus` in `{New, Disabled}` (fresh inserts land in `New`; `Disabled` is a
+previously-activated-then-deactivated channel — both are valid starting states for activation).
+Empty MCU query → `{ok:false, kind:"verify-failed", hint:"Connect returned {CHANNEL_ID} but no
+child MessagingChannelUsage was created"}`.
+
+**Trust the DB, not the Connect response body**, for `MasterLabel` / `DeveloperName` — the 201 body
+carries stale input-rep projections (see per-type gotchas).
+
+---
+
+## Stage 6: Report to caller
+
+```json
+{"ok": true, "channelId": "{CHANNEL_ID}", "mcuId": "<from Stage 5>",
+ "developerName": "<authoritative, from Stage 5>", "isActive": false,
+ "messageType": "{MESSAGE_TYPE}", "messagingPlatformKey": "{PLATFORM_KEY}",
+ "path": "connect", "created": true, "durationMs": <Date.now() - T0>}
+```
+
+Rendered (when invoked directly rather than by the orchestrator):
+- `Success — MessagingChannel {CHANNEL_ID} ({developerName}) created via {path}. MCU {mcuId} auto-created. IsActive=false — run routing, then consent, then activate next.`
+- `Info: Channel already exists — {CHANNEL_ID} ({developerName}). Proceed to routing/activation.`
+- `Error: {kind}: {message or hint}`
+
+On success the caller can immediately invoke `service-de-channel-routing-configure` with the
+returned `channelId`, then `service-de-channel-consent-configure`, then
+`service-de-channel-activate`. Those three are message-type-agnostic (they operate on
+`MessagingChannel.Id` + `MessagingChannelUsage.Id`), so there's no downstream dispatch concern.
+
+---
+
+## Gotchas (shared)
+
+1. **Case-sensitive type names.** `"whatsapp"` ≠ `"WhatsApp"` — the SF picklist, SOQL filters,
+   and Connect enum all match exactly. Normalize upstream; don't make Stage 0.1 case-insensitive.
+2. **Preflight is the idempotency guard.** `MessagingChannel` rows aren't deletable via standard
+   means, so re-runs rely on Stage 1 finding the existing row.
+3. **Envelope shape is a tight coupling with callers.** If a field is renamed here, every caller
+   (especially `service-de-headless-channel-configure`) silently sees the change — break loudly
+   in tests rather than remap field names.
+4. **Per-type gotchas live in the reference files.** WABA/phone-id confusion, LINE long-lived vs
+   short-lived tokens, Apple's empty-config body + no-provisioning-callout, Facebook OAuth page
+   selection + 401 disambiguation — load the matching `references/<type>.md` when debugging that type.

package/skills/service-de-channel-create/references/apple.md

@@ -0,0 +1,59 @@
+# Apple Business Chat — empty config, precondition errors, gotchas
+
+`MESSAGE_TYPE=AppleBusinessChat`. Platform key is the **Apple Business Chat Account ID** (a GUID,
+`00000000-0000-0000-0000-000000000000`, from register.apple.com/business-chat).
+
+Apple BC has **no third-party credentials** (no client secret, no access token). Authentication with
+Apple's servers is certificate-based and provisioned when the Apple BC account is created on Apple's
+Register a Business side. That's why the Setup UI's `liveMessageAppleBusinessChatHelper.js` sends
+`messagingChannelProperties: {}` and never asks for any secret beyond the account id itself.
+
+## Inputs
+
+- `{APPLE_BC_ID}` — Apple Business Chat Account ID (GUID). Sent as `messagingPlatformKey`.
+- `{CHANNEL_NAME}` — **required**. Apple BC has no phone number / screen name to fall back on, so the
+  caller must supply a display name (`messagingChannelName`). Don't synthesize `APPLE_{id}` — the
+  user sees this name in the UI.
+
+## Stage 2-3: none
+
+Apple has no insert-time prerequisite. The certificate handshake with Apple's servers is per-message
+at runtime, separate from channel activation — there is no external provisioning callout at activation
+either (Apple hits the `default` branch in the observer's external-callout switch; activation is ~1s).
+
+## Stage 4.2: request body
+
+```json
+{"messageType":"AppleBusinessChat","platformType":"Enhanced",
+ "messagingPlatformKey":"{APPLE_BC_ID}",
+ "messagingChannelName":"{CHANNEL_NAME}"}
+```
+
+**No `authDetails` / `externalAccountId` / `isoCountryCode`.** Apple BC uses none of those; the
+Connect input rep treats unset fields as absent (not `null`). `authProviderId` still goes in the URL
+query string (Apple is NOT exempt — verified: omitting it yields `400 ILLEGAL_QUERY_PARAMETER_VALUE
+"Missing argument authProviderId"`).
+
+Response classification: same as the shared table (see `connect-insert.md`), plus — on `400` whose
+message mentions "Apple" / "account" / "not registered" — emit
+`{ok:false, kind:"apple-precondition", hint:"Apple BC Account ID not recognized — confirm the business is registered at register.apple.com/business-chat", message}`.
+
+## Gotchas
+
+1. **`messagingChannelProperties` / `authDetails` MUST be empty or omitted for Apple.** Populating
+   the map with placeholder values can make the server reject the insert with an unclear error.
+2. **`MessagingPlatformKey` is the GUID**, not a display string. Don't paste the URL-encoded or
+   capitalized form.
+3. **No external provisioning callout at activation** — Apple hits the `default` branch in
+   `ConversationChannelUsageDeploymentStatusService.runProvisioning`; the terminal
+   `DeploymentStatus=Active` write happens immediately (~1s, vs 15-21s for WhatsApp).
+4. **`CHANNEL_NAME` is required** — no display phone number to fall back on.
+5. **Apple BC onboarding is slow outside SF.** Registering at register.apple.com/business-chat can
+   take days for Apple to approve. A precondition error at insert most likely means the business
+   isn't live on Apple's side yet.
+6. **Connect response echoes are not authoritative.** The 201 body comes back with
+   `masterLabel = messagingPlatformKey` (the GUID) and a non-canonical short `developerName`
+   (`AppleBusinessChat_<guid>`). The DB row uses the supplied `messagingChannelName` and the
+   canonical `APPLEBUSINESSCHAT_US_<guid>`. Trust Stage 5's verify SOQL, not the POST body.
+7. **Fresh MCUs start in `DeploymentStatus=New`** (`Disabled` is the post-deactivation state). Both
+   are valid `→ Provisioning` sources — don't assert a specific starting status in Stage 5.

package/skills/service-de-channel-create/references/connect-insert.md

@@ -0,0 +1,84 @@
+---
+name: service-de-channel-create-connect-insert
+description: "Load when a channel's prerequisites are satisfied and CHANNEL_NAME is resolved, right before POSTing the channel-creation request to the Connect REST endpoint. Covers the shared Stage 4.1 (authProviderId lookup), Stage 4.2 (POST invocation), and Stage 4.3 (HTTP + business-error response classification, including the DUPLICATE_VALUE race). Per-type request-body shapes live in the per-type reference (whatsapp.md / line.md / apple.md / facebook.md). DO NOT load for type-specific prereqs (Stage 2-3) or for resolving CHANNEL_NAME."
+metadata:
+  version: "1.0"
+  related-skills: service-de-channel-create
+---
+
+# Connect insert: authProviderId, POST, response classification (shared)
+
+Full detail for Stage 4.1-4.3 of the channel insert, shared across all four types. The per-type
+**request body** shape is in the matching per-type reference file; everything else here is identical
+across types.
+
+## Stage 4.1: Get authProviderId
+
+`sf api request rest` manages the Salesforce OAuth session internally, so there's no
+`{ACCESS_TOKEN}`/`{INSTANCE_URL}` to carry in shell state.
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id FROM AuthProvider WHERE DeveloperName = 'LiveMessageSetup'" \
+  --json > "${SCRATCH_DIR}/authprovider.json"
+```
+
+- `records.length === 1` → record `{AUTH_PROVIDER_ID} = records[0].Id`.
+- `records.length === 0` → `{ok:false, kind:"business", message:"No AuthProvider 'LiveMessageSetup' found — run the Messaging Setup wizard once on this org first"}`.
+
+`authProviderId` is **org-global** — the same `LiveMessageSetup` `AuthProvider.Id` works for every
+message type on that org, so a caller inserting multiple channels can reuse it. The value differs on
+every org; always query, never hardcode.
+
+## Stage 4.2: POST to the Connect endpoint
+
+Build the type-specific body (see the per-type reference), **write it to a file** under
+`${SCRATCH_DIR}` (the per-run scratch dir established in SKILL.md Stage 0.2 — under
+`${outputDir}`/`${TMPDIR}`, never a bare `/tmp` path), then POST:
+
+```bash
+sf api request rest \
+  "/services/data/v{API_VERSION}/connect/livemessage/channels?authProviderId=${AUTH_PROVIDER_ID}" \
+  --method POST --target-org '{ORG_ALIAS}' \
+  --header 'Content-Type: application/json' --header 'Accept: application/json' \
+  --body @"${SCRATCH_DIR}/body.json" --include > "${SCRATCH_DIR}/connect-response.txt" 2>&1
+```
+
+**`authProviderId` is a URL query-string parameter, NOT a body field** — mandatory on every known org
+and every type (Apple included). Omitting it from the URL → `400 ILLEGAL_QUERY_PARAMETER_VALUE
+"Missing argument authProviderId"`. Putting it in the body → `400 JSON_PARSER_ERROR "Unrecognized
+field 'authProviderId'"`. The only working form is `?authProviderId=${AUTH_PROVIDER_ID}` in the URL.
+
+**`sf api request rest` manages the Salesforce OAuth session internally** — no bearer token is
+extracted into shell state. `--include` prints the HTTP status/headers block ahead of the body — read
+the status from that block, not a trailing `-w` marker.
+
+## Stage 4.3: Classify the Connect response
+
+**Classify by `errorCode` first, HTTP status second** — the endpoint is inconsistent about which
+status it pairs with some error codes (notably Facebook's `AUTH_PROVIDER_NEEDS_AUTH`). Inspect
+`response[0].errorCode` (or `.errorCode` if the body is an object, not an array) before falling back
+to the status table.
+
+| HTTP status | Body shape | Handling |
+| --- | --- | --- |
+| 201 | `{id, developerName, isActive:false, ...}` | Success. Record `{CHANNEL_ID}=id`, `{DEVELOPER_NAME}=developerName`. Continue to Stage 5. |
+| 200 | Same shape | Idempotent hit on some orgs. Treat same as 201. |
+| 400 | `[{errorCode, message}]` | Business-level rejection. See table below. |
+| 401 | empty / `INVALID_SESSION_ID` | SF bearer token invalid. `{ok:false, kind:"auth", hint:"OAuth token invalid — run 'sf org login web'"}`. |
+| 403 | `[{errorCode:"INSUFFICIENT_ACCESS"}]` | `{ok:false, kind:"business", errorCode:"INSUFFICIENT_ACCESS", message}`. |
+| 404 | usually HTML | Endpoint unavailable / API version unsupported. `{ok:false, kind:"transport", status:404, message:"Connect endpoint unavailable — is {API_VERSION} supported?"}`. |
+| 5xx | varies | `{ok:false, kind:"transport", status, message}`. |
+
+**Business errors (HTTP 400, or any status when classified by errorCode):**
+
+| `errorCode` | Meaning | Handling |
+| --- | --- | --- |
+| `DUPLICATE_VALUE` | Channel already exists (race — preflight missed it). | Re-run Stage 1 preflight; if a row now exists, emit success `created:false, path:"connect-duplicate"`. |
+| `INVALID_INPUT` / `MALFORMED_REQUEST` | Body shape issue — likely a skill bug. | `{ok:false, kind:"business", errorCode, message}`; report the request body for debugging. |
+| `AUTH_PROVIDER_NEEDS_AUTH` (Facebook) | OAuth not complete / token expired. | `{ok:false, kind:"oauth-not-complete", hint:"re-run Facebook OAuth to refresh the FB token"}`. |
+| `INVALID_STATUS` / `UNKNOWN_EXCEPTION` mentioning "WABA"/"Meta" | Meta-side precondition failed. | `{ok:false, kind:"meta-precondition", hint:"WABA may not be shared with SF's BSP app, or the phone may not be OTP-verified on Meta", message}`. |
+| any other | Unrecognized. | `{ok:false, kind:"business", errorCode, message}`. |
+
+Per-type message-substring refinements (LINE creds, Apple precondition) are in the per-type reference
+files. Return the classified envelope.