@whooshbang/sdk 5.0.0 → 6.0.0

package/README.md

@@ -42,17 +42,15 @@ const whooshBang = new WhooshBangClient({
   fetch,
 });
 
-const sent = await whooshBang.createMessage(
-  {
-    to: "customer_123",
-    interaction: {
-      prompt: "Approve the synthetic deployment?",
-      confirm_label: "Approve",
-      deny_label: "Deny",
-      expires_in_seconds: 900,
-    },
+const sent = await whooshBang.createMessage({
+  to: "customer_123",
+  interaction: {
+    prompt: "Approve the synthetic deployment?",
+    confirm_label: "Approve",
+    deny_label: "Deny",
+    expires_in_seconds: 900,
   },
-);
+});
 switch (sent.outcome) {
   case "accepted":
     console.log(sent.message.id);
@@ -108,7 +106,10 @@ are recognized for at least seven days, and longer when the answer window is lon
 same contract (`expires_in_seconds` / `expires_at` on the interaction).
 
 ```ts
-const question = confirmInteraction({ prompt: "Approve this week's plan?", expiresInSeconds: 604800 });
+const question = confirmInteraction({
+  prompt: "Approve this week's plan?",
+  expiresInSeconds: 604800,
+});
 ```
 
 The message's outer `expires_at` is its separate delivery deadline (default 24 hours, extendable through year 9999), not the answer deadline. Delivery acceptance does not end answerability.
@@ -142,6 +143,127 @@ a correct caller cancels and learns which side won. `cancelled` carries the
 cancelled resource; `cancellation_too_late` carries the message's current
 state, or the link's Problem Details, and never claims provider-side deletion.
 
+## Escalation
+
+A send that carries `escalation` keeps trying the person across their channel
+order, then any further stages, until a genuine human response, your
+cancellation, its expiry, or nobody is left to try. The accepted message is the
+first attempt and carries `message.escalation.id`. Read the whole ladder with
+`getEscalation(escalationId, { wait })`; `wait` holds the read until the
+escalation closes, up to 30 seconds. Its `timeline` says what happened in plain
+sentences, such as "Skipped Slack (step 2): this person hasn't connected Slack."
+or "Acknowledged by email, using the link in the email.", so you can show a
+person why the escalation did what it did. The `escalation.closed` event carries
+the same timeline.
+
+```ts
+const sent = await whooshBang.createMessage(request, {
+  idempotencyKey: "incident-2041-page",
+});
+// Later, when the matter is resolved some other way:
+const stop = await whooshBang.cancelEscalationByKey({
+  idempotency_key: "incident-2041-page",
+  reason: "resolved",
+});
+```
+
+Wait on the escalation, not on that first message. A person may answer on any
+attempt, including an earlier one, so `awaitInteraction` on the first message
+can miss the response that closed the escalation. `escalation.response` says
+which attempt was answered and how: `acknowledged`, `answered`, `declined`
+(a "no" is a reached person refusing, not approval) or `replied`.
+
+When nothing can be tried at all, because the person has no connected channel,
+the send is refused with `subscriber_unbound` and no escalation exists. When
+channels exist but every attempt is skipped at acceptance, for example because
+consent was withdrawn, the escalation is created and closes as
+`no_eligible_target`; its first message was never sent and carries
+`escalation.skip_reason`.
+
+`cancelEscalation(escalationId, { reason })` stops every future attempt.
+`cancelEscalationByKey` does the same for a caller that kept only the send's
+`Idempotency-Key`; name `send_operation: "sendOperatorMessage"` when the key
+was used on an operator send. Both resolve with `cancelled` when this call
+closed the escalation, or `already_closed` when it had already ended, so
+cancelling after someone answered is safe and keeps their answer.
+
+### Escalation defaults
+
+Each environment has a default channel order for every urgency tier (`low`,
+`normal`, `high`, `critical`, the message category's level). A person without
+an order of their own gets the tier's default. Until you save one, a tier uses
+the built-in suggested order: the environment's connected channels in the
+order Telegram, Slack, email, 5 minutes each.
+
+```ts
+await whooshBang.updateEscalationPolicy(projectId, environmentId, "critical", {
+  steps: [
+    { channel: "telegram", wait_minutes: 5 },
+    { channel: "email", wait_minutes: 15 },
+  ],
+});
+const preview = await whooshBang.previewEscalationPath(
+  projectId,
+  environmentId,
+  "critical",
+  "customer-123",
+);
+```
+
+Every step's channel must be connected in that environment, or the save fails
+with `escalation_policy_channel_unconnected`. Each save is a new version;
+running escalations keep the order they started with. `listEscalationPolicies`
+reads all four tiers, and `resetEscalationPolicy` returns a tier to the
+suggested order. The preview shows which of the person's channels each step
+reaches; a step without `binding_id` would be skipped.
+
+### A subscriber's own escalation order
+
+A subscriber can set their own order for each urgency, naming their exact
+bindings with whole-minute waits. Their order always wins over the project's;
+an empty order means nothing is tried, and an escalation to them closes as
+`no_eligible_target`. Only the subscriber can change it, through their
+recipient session:
+
+```ts
+const orders = await recipientSession.getEscalationOrders();
+await recipientSession.saveEscalationOrder("critical", {
+  steps: [{ binding_id: bindingId, wait_minutes: 2 }],
+  version: orders.items[3]?.version,
+});
+await recipientSession.resetEscalationOrder("critical");
+```
+
+Your application can read it with `getSubscriberEscalationOrders`, but cannot
+change it. That differs on purpose from the preferred binding, which your
+application can set.
+
+### Quiet hours
+
+A subscriber can set quiet hours: the times they would rather not be
+interrupted, and what each channel does then. A channel can deliver as usual,
+deliver silently (Telegram only) or withhold the message. A withheld message
+waits until quiet hours end, or goes straight to one channel they choose, such
+as their email. Critical messages still arrive unless they turn that off. Only
+the subscriber can change their quiet hours, through their recipient session:
+
+```ts
+const quiet = await recipientSession.getQuietHours();
+await recipientSession.saveQuietHours({
+  windows: [{ days: [1, 2, 3, 4, 5], start: "22:00", end: "07:00" }],
+  channels: { telegram: "silent", slack: "withhold", email: "deliver" },
+  critical_breakthrough: true,
+  when_withheld: "quiet_channel",
+  quiet_channel_binding_id: quiet.quiet_channel_options[0]?.binding_id,
+  time_zone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+});
+await recipientSession.resetQuietHours();
+```
+
+`channel_options` lists the choices each channel offers. Your application can
+read a subscriber's quiet hours with `getSubscriberQuietHours`, but cannot
+change them.
+
 ## Awaiting an answer
 
 Use your configured customer-events webhook to receive answers without keeping
@@ -248,6 +370,11 @@ both the previous and the current secret so a rotation overlap has no gap. Use
 `verifyWhooshBangWebhook` (or `verifyWebhookSignature`) for signature-only
 verification of any signed body.
 
+Events newer than the SDK still verify. A known type carrying a new field or
+enum value keeps its type; an unknown type returns `recognized: false` with
+only the shared envelope checked. Answer those with a 2xx: a 4xx stops the
+event and holds the endpoint's later deliveries behind it.
+
 ## Channel connections
 
 `listConnectionProviders` reports what a project can connect to, the setup
@@ -384,7 +511,8 @@ function onReady(event) {
     event.source !== popup ||
     event.origin !== hostedOrigin ||
     event.data?.type !== "whooshbang.recipient-settings.ready"
-  ) return;
+  )
+    return;
   window.removeEventListener("message", onReady);
   popup.postMessage(
     { type: "whooshbang.recipient-settings.session", session },
@@ -432,25 +560,27 @@ result type and no global outcome enum. An exhaustive `switch` over `outcome`
 compiles with no `default`, and a member added later is a compile error at
 every call site rather than a silent fallthrough.
 
-| Method                                        | `outcome`                                             | Carries                           | Means                                                                                                                                                                       |
-| --------------------------------------------- | ----------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `interactionAnswer`                           | `answered`                                            | `answer`, `summary`               | A person answered and the answer is retained.                                                                                                                         |
-|                                               | `answer_not_retained`                                 | `summary`                         | Answered; the answer is no longer in message history. `answered_at` survives.                                                                                           |
-|                                               | `open`                                                | `summary`                         | Nobody has answered yet.                                                                                                                                                    |
-|                                               | `expired`                                             | `summary`                         | The interaction reached its server-side expiry unanswered.                                                                                                                  |
-|                                               | `cancelled`                                           | `summary`                         | Cancelled before an answer.                                                                                                                                                 |
-|                                               | `retired`                                             | `summary`                         | The question was retired; later answers are ignored.                                                                                                                            |
-| `createMessage`, `createMessageInEnvironment` | `accepted`                                            | `message`                         | The service accepted the send; `message` is its current state.                                                                                                              |
-|                                               | `subscriber_unbound`                                  | `problem`                         | No active binding reaches the subscriber on this notifier. Nothing was sent; usually they have to subscribe again, sometimes your routing changed.                          |
-|                                               | `preferred_binding_unavailable`                       | `problem`                         | The channel the subscriber chose as preferred is paused or revoked, and the service never picks a fallback. Nothing was sent; they have to choose again or subscribe again. |
-| | `funding_required` | `reason`, `problem` | Add credit or wait for a paid allowance to renew, then retry the refused request. |
-| `awaitInteraction`                            | as `interactionAnswer`                                | `summary`, `answer` on `answered` | The same members; `open` means the patience bound elapsed and the interaction can be awaited again.                                                                         |
-| `ask`                                         | as `awaitInteraction`                                 | plus `message`                    | Every interaction member also carries the accepted message.                                                                                                                 |
-|                                               | `subscriber_unbound`, `preferred_binding_unavailable`, `funding_required` | `problem`                         | The send's own refusals, exactly as `createMessage` returns them. Nothing was sent, so there is no message.                                                                 |
-| `cancelMessage`                               | `cancelled`                                           | `message`                         | Cancellation took effect before a worker owned the provider call.                                                                                                           |
-|                                               | `cancellation_too_late`                               | `message`                         | A worker already owned the provider call. `message` is the current state; no provider-side deletion is claimed.                                                             |
-| `cancelSubscriptionLink`                      | `cancelled`                                           | `link`                            | The pending link is cancelled and can no longer create a binding.                                                                                                           |
-|                                               | `cancellation_too_late`                               | `problem`                         | The link had already left `pending` — activated, expired, failed, or revoked. Read the link to learn which.                                                                 |
+| Method                                                                       | `outcome`                                                                 | Carries                           | Means                                                                                                                                                                       |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `interactionAnswer`                                                          | `answered`                                                                | `answer`, `summary`               | A person answered and the answer is retained.                                                                                                                               |
+|                                                                              | `answer_not_retained`                                                     | `summary`                         | Answered; the answer is no longer in message history. `answered_at` survives.                                                                                               |
+|                                                                              | `open`                                                                    | `summary`                         | Nobody has answered yet.                                                                                                                                                    |
+|                                                                              | `expired`                                                                 | `summary`                         | The interaction reached its server-side expiry unanswered.                                                                                                                  |
+|                                                                              | `cancelled`                                                               | `summary`                         | Cancelled before an answer.                                                                                                                                                 |
+|                                                                              | `retired`                                                                 | `summary`                         | The question was retired; later answers are ignored.                                                                                                                        |
+| `createMessage`, `createMessageInEnvironment`                                | `accepted`                                                                | `message`                         | The service accepted the send; `message` is its current state.                                                                                                              |
+|                                                                              | `subscriber_unbound`                                                      | `problem`                         | No active binding reaches the subscriber on this notifier. Nothing was sent; usually they have to subscribe again, sometimes your routing changed.                          |
+|                                                                              | `preferred_binding_unavailable`                                           | `problem`                         | The channel the subscriber chose as preferred is paused or revoked, and the service never picks a fallback. Nothing was sent; they have to choose again or subscribe again. |
+|                                                                              | `funding_required`                                                        | `reason`, `problem`               | Add credit or wait for a paid allowance to renew, then retry the refused request.                                                                                           |
+| `awaitInteraction`                                                           | as `interactionAnswer`                                                    | `summary`, `answer` on `answered` | The same members; `open` means the patience bound elapsed and the interaction can be awaited again.                                                                         |
+| `ask`                                                                        | as `awaitInteraction`                                                     | plus `message`                    | Every interaction member also carries the accepted message.                                                                                                                 |
+|                                                                              | `subscriber_unbound`, `preferred_binding_unavailable`, `funding_required` | `problem`                         | The send's own refusals, exactly as `createMessage` returns them. Nothing was sent, so there is no message.                                                                 |
+| `cancelMessage`                                                              | `cancelled`                                                               | `message`                         | Cancellation took effect before a worker owned the provider call.                                                                                                           |
+|                                                                              | `cancellation_too_late`                                                   | `message`                         | A worker already owned the provider call. `message` is the current state; no provider-side deletion is claimed.                                                             |
+| `cancelSubscriptionLink`                                                     | `cancelled`                                                               | `link`                            | The pending link is cancelled and can no longer create a binding.                                                                                                           |
+|                                                                              | `cancellation_too_late`                                                   | `problem`                         | The link had already left `pending` — activated, expired, failed, or revoked. Read the link to learn which.                                                                 |
+| `cancelEscalation`, `cancelEscalationByKey` and their `…InEnvironment` forms | `cancelled`                                                               | `escalation`                      | This call closed the escalation; no later attempt is sent. An attempt already handed to the provider is recorded, never claimed deleted.                                    |
+|                                                                              | `already_closed`                                                          | `escalation`                      | The escalation had already ended — answered, expired, exhausted or cancelled earlier — and is returned unchanged; its `outcome` says which. Cancelling twice is safe.       |
 
 Two outcomes the rule names are already values and need no union. An
 equivalent idempotent replay returns the original resource with the original
@@ -478,45 +608,52 @@ for a paid allowance to renew, then explicitly retry the same refused request.
 Bonus credit funds core sends only; shared email needs purchased or welcome
 credit. These ceilings do not schedule an automatic SDK retry.
 
-| Code                               | Side      | Why                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| ---------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cancellation_too_late`            | Outcome   | The race is inherent: a correct caller cancels and learns it was too late. `cancelSubscriptionLink` receives it as a problem and returns it; `cancelMessage` receives the same fact as `cancellation_effective: false` on a success, as the contract documents, so the problem code arriving there is outside the documented response and throws.                                                                           |
-| `authentication_required`          | Exception | No credential reached the service. The integration's configuration is wrong.                                                                                                                                                                                                                                                                                                                                                |
-| `credential_invalid`               | Exception | The credential is malformed, revoked, or past its rotation overlap. Only a replacement credential fixes it.                                                                                                                                                                                                                                                                                                                 |
-| `scope_forbidden`                  | Exception | The credential lacks a scope, or the organization is not yet invited (`pendingInvitation`). No branch at the call site grants either.                                                                                                                                                                                                                                                                                       |
-| `environment_mismatch`             | Exception | A credential reached across the test/live boundary.                                                                                                                                                                                                                                                                                                                                                                         |
-| `idempotency_key_required`         | Exception | A supplied key was invalid. Omit it or use 8 to 255 visible ASCII characters.                                                                                                                                                                                                                                                                                            |
-| `idempotency_conflict`             | Exception | Same key, different body — including the stale row-version, claimed-identity, revoked-client, and acknowledgement cursor or disposition refusals that reuse the code. The fix is a new request, never a retry.                                                                                                                                                                                                              |
-| `project_slug_conflict`            | Exception | The slug is already taken in this organization. Refused input, handled as `request_invalid` is: choose another.                                                                                                                                                                                                                                                                                                             |
-| `request_invalid`                  | Exception | The request broke a documented bound. `fieldErrors` names each field.                                                                                                                                                                                                                                                                                                                                                       |
-| `replay_unavailable`               | Exception | A customer-event replay was refused by the attempt's state. The caller waits for a terminal attempt or accepts that an aged-out payload is gone; there is nothing to branch on.                                                                                                                                                                                                                                             |
-| `subscriber_unbound`               | Outcome   | On a send, the person's channel state: they revoked their channel or never finished subscribing, so the branch is to invite them again. It is also the answer when a send names a `connection_id` and the subscriber has no connected channel at all. `createMessage` and `createMessageInEnvironment` return it. `createMachineClient` still throws it: a machine client for an unbound subscriber is setup that is wrong. |
-| `subscriber_not_connected`         | Exception | A send or a connection test named a connection the subscriber has not connected through, while they are connected through another. `problem.subscriber_id` and `problem.channel` say who and where; nothing was sent. Naming the connection was the caller's choice: omit `connection_id` to let the service choose one of their channels, pick a connection they connected through, or invite them through this one.       |
-| `not_consented_for_marketing`      | Exception | A `marketing` send or broadcast reached an email recipient enrolled only on a service basis. Nothing was sent to that recipient and nothing was charged. Send it as `service`, or obtain marketing consent first.                                                                                                                                                                                                           |
-| `category_not_found`               | Exception | The named category is not active in this project. Check its key before sending. |
-| `category_purpose_mismatch`        | Exception | The stated purpose disagrees with the category's purpose. Nothing was sent or charged. |
-| `category_turned_off`              | Exception | The subscriber switched this category off. Nothing was sent or charged. |
-| `category_conflict`                | Exception | A category key is taken, the category is in use, or its settings prevent the requested change. |
-| `recipient_configuration_invalid`  | Exception | The owner's recipient-experience configuration is not usable as submitted or as stored.                                                                                                                                                                                                                                                                                                                                     |
-| `recipient_origin_forbidden`       | Exception | The presenting browser origin is not registered for the session.                                                                                                                                                                                                                                                                                                                                                            |
-| `return_destination_not_found`     | Exception | The return-destination key is not configured.                                                                                                                                                                                                                                                                                                                                                                               |
-| `recipient_capability_invalid`     | Exception | The session's capability is not live. Only the host backend can mint another; this is the browser surface's `credential_invalid`.                                                                                                                                                                                                                                                                                           |
-| `recipient_handoff_invalid`        | Exception | The provider handoff is unavailable or belongs to another session.                                                                                                                                                                                                                                                                                                                                                          |
-| `preferred_binding_conflict`       | Exception | A stale row version. Re-read the session and send a new request.                                                                                                                                                                                                                                                                                                                                                            |
-| `preferred_binding_unavailable`    | Outcome   | On a send, the subscriber's own channel state: the channel they chose as preferred is paused or revoked, and the service never picks a fallback. The same user event as `subscriber_unbound`, so `createMessage` and `createMessageInEnvironment` return it. The recipient-session client's `setPreferredBinding` still throws it: there it is a choice the service refused, and the panel offers the choice again.         |
-| `subscriber_conflict`              | Exception | A create for a subscriber that exists. Use the update and membership operations.                                                                                                                                                                                                                                                                                                                                            |
-| `subscriber_group_conflict`        | Exception | The group's state, revision, or a ceiling refused the operation.                                                                                                                                                                                                                                                                                                                                                            |
-| `subscriber_group_archived`        | Exception | Deletion is terminal. The caller needs a different group.                                                                                                                                                                                                                                                                                                                                                                   |
-| `resource_not_found`               | Exception | The identifier is wrong or outside the credential's reach; absent and out-of-scope look identical on purpose.                                                                                                                                                                                                                                                                                                               |
-| `resource_expired`                 | Exception | Published but not produced by the service today: a resource's expiry reaches the caller as its own `status` or `state`, which is already a value. The recipient-session element treats it, with `recipient_capability_invalid`, as a session that has ended.                                                                                                                                                                |
-| `credential_organization_mismatch` | Exception | An organization credential reached a project outside its organization.                                                                                                                                                                                                                                                                                                                                                      |
-| `endpoint_rotation_conflict`       | Exception | A prior overlap is still active. The caller waits for `retryAt`, as for rate limiting.                                                                                                                                                                                                                                                                                                                                      |
-| `rate_limited`                     | Exception | Wait until `retryAt`. The caller's response is to wait, not to branch.                                                                                                                                                                                                                                                                                                                                                      |
-| `privacy_operation_in_progress`    | Exception | Export, erasure, or organization closure still has in-flight work to drain or a provider cleanup to retry. Wait until `retryAt`, then repeat the same operation.                                                                                                                                                                                                                                                            |
-| `provider_retryable`               | Exception | The provider failed before acceptance. The service retries where a retry is scheduled; the caller waits.                                                                                                                                                                                                                                                                                                                    |
-| `provider_terminal`                | Exception | The provider refused permanently. Fix the binding or the content and send a new message.                                                                                                                                                                                                                                                                                                                                    |
-| `provider_outcome_unknown`         | Exception | The provider may already have acted. Read the resource state before deciding anything.                                                                                                                                                                                                                                                                                                                                      |
-| `internal_error`                   | Exception | WhooshBang failed on its own side; no provider or customer system was involved. Retried like any retryable problem. If it persists, report `diagnosticId` to support.                                                                                                                                                                                                                                                       |
+| Code                                    | Side      | Why                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cancellation_too_late`                 | Outcome   | The race is inherent: a correct caller cancels and learns it was too late. `cancelSubscriptionLink` receives it as a problem and returns it; `cancelMessage` receives the same fact as `cancellation_effective: false` on a success, as the contract documents, so the problem code arriving there is outside the documented response and throws.                                                                           |
+| `authentication_required`               | Exception | No credential reached the service. The integration's configuration is wrong.                                                                                                                                                                                                                                                                                                                                                |
+| `credential_invalid`                    | Exception | The credential is malformed, revoked, or past its rotation overlap. Only a replacement credential fixes it.                                                                                                                                                                                                                                                                                                                 |
+| `scope_forbidden`                       | Exception | The credential lacks a scope, or the organization is not yet invited (`pendingInvitation`). No branch at the call site grants either.                                                                                                                                                                                                                                                                                       |
+| `environment_mismatch`                  | Exception | A credential reached across the test/live boundary.                                                                                                                                                                                                                                                                                                                                                                         |
+| `idempotency_key_required`              | Exception | A supplied key was invalid. Omit it or use 8 to 255 visible ASCII characters.                                                                                                                                                                                                                                                                                                                                               |
+| `idempotency_conflict`                  | Exception | Same key, different body — including the stale row-version, claimed-identity, revoked-client, and acknowledgement cursor or disposition refusals that reuse the code. The fix is a new request, never a retry.                                                                                                                                                                                                              |
+| `project_slug_conflict`                 | Exception | The slug is already taken in this organization. Refused input, handled as `request_invalid` is: choose another.                                                                                                                                                                                                                                                                                                             |
+| `request_invalid`                       | Exception | The request broke a documented bound. `fieldErrors` names each field.                                                                                                                                                                                                                                                                                                                                                       |
+| `replay_unavailable`                    | Exception | A customer-event replay was refused by the attempt's state. The caller waits for a terminal attempt or accepts that an aged-out payload is gone; there is nothing to branch on.                                                                                                                                                                                                                                             |
+| `subscriber_unbound`                    | Outcome   | On a send, the person's channel state: they revoked their channel or never finished subscribing, so the branch is to invite them again. It is also the answer when a send names a `connection_id` and the subscriber has no connected channel at all. `createMessage` and `createMessageInEnvironment` return it. `createMachineClient` still throws it: a machine client for an unbound subscriber is setup that is wrong. |
+| `subscriber_not_connected`              | Exception | A send or a connection test named a connection the subscriber has not connected through, while they are connected through another. `problem.subscriber_id` and `problem.channel` say who and where; nothing was sent. Naming the connection was the caller's choice: omit `connection_id` to let the service choose one of their channels, pick a connection they connected through, or invite them through this one.       |
+| `not_consented_for_marketing`           | Exception | A `marketing` send or broadcast reached an email recipient enrolled only on a service basis. Nothing was sent to that recipient and nothing was charged. Send it as `service`, or obtain marketing consent first.                                                                                                                                                                                                           |
+| `category_not_found`                    | Exception | The named category is not active in this project. Check its key before sending.                                                                                                                                                                                                                                                                                                                                             |
+| `category_purpose_mismatch`             | Exception | The stated purpose disagrees with the category's purpose. Nothing was sent or charged.                                                                                                                                                                                                                                                                                                                                      |
+| `category_turned_off`                   | Exception | The subscriber switched this category off. Nothing was sent or charged.                                                                                                                                                                                                                                                                                                                                                     |
+| `category_conflict`                     | Exception | A category key is taken, the category is in use, or its settings prevent the requested change.                                                                                                                                                                                                                                                                                                                              |
+| `escalation_unavailable`                | Exception | Escalation is not available in this environment yet. Nothing was sent or charged. Send without `escalation`, or retry once escalation is enabled.                                                                                                                                                                                                                                                                           |
+| `escalation_shape_unsupported`          | Exception | A stage names more than one person. Parallel escalation is reserved and not yet supported; give each person a stage of their own. Nothing was sent.                                                                                                                                                                                                                                                                         |
+| `escalation_capacity_reached`           | Exception | The environment has its maximum number of open escalations. Nothing was sent. Wait until `retryAt`, or for one to close, as for rate limiting.                                                                                                                                                                                                                                                                              |
+| `escalation_policy_channel_unconnected` | Exception | An escalation default names a channel with no active connection in this environment; `fieldErrors` names each step. Nothing was saved. Connect the channel first or remove the step.                                                                                                                                                                                                                                        |
+| `escalation_order_step_ineligible`      | Exception | A subscriber's escalation order names a binding that is not theirs, is paused or revoked, or is on a channel the project turned off; `fieldErrors` names each step. Nothing was saved.                                                                                                                                                                                                                                      |
+| `escalation_limits_conflict`            | Exception | The project's escalation limits changed since they were read. Read them again before saving.                                                                                                                                                                                                                                                                                                                                |
+| `escalation_order_conflict`             | Exception | The subscriber's escalation order changed since it was read. Read it again before saving.                                                                                                                                                                                                                                                                                                                                   |
+| `recipient_configuration_invalid`       | Exception | The owner's recipient-experience configuration is not usable as submitted or as stored.                                                                                                                                                                                                                                                                                                                                     |
+| `recipient_origin_forbidden`            | Exception | The presenting browser origin is not registered for the session.                                                                                                                                                                                                                                                                                                                                                            |
+| `return_destination_not_found`          | Exception | The return-destination key is not configured.                                                                                                                                                                                                                                                                                                                                                                               |
+| `recipient_capability_invalid`          | Exception | The session's capability is not live. Only the host backend can mint another; this is the browser surface's `credential_invalid`.                                                                                                                                                                                                                                                                                           |
+| `recipient_handoff_invalid`             | Exception | The provider handoff is unavailable or belongs to another session.                                                                                                                                                                                                                                                                                                                                                          |
+| `preferred_binding_conflict`            | Exception | A stale row version. Re-read the session and send a new request.                                                                                                                                                                                                                                                                                                                                                            |
+| `preferred_binding_unavailable`         | Outcome   | On a send, the subscriber's own channel state: the channel they chose as preferred is paused or revoked, and the service never picks a fallback. The same user event as `subscriber_unbound`, so `createMessage` and `createMessageInEnvironment` return it. The recipient-session client's `setPreferredBinding` still throws it: there it is a choice the service refused, and the panel offers the choice again.         |
+| `subscriber_conflict`                   | Exception | A create for a subscriber that exists. Use the update and membership operations.                                                                                                                                                                                                                                                                                                                                            |
+| `subscriber_group_conflict`             | Exception | The group's state, revision, or a ceiling refused the operation.                                                                                                                                                                                                                                                                                                                                                            |
+| `subscriber_group_archived`             | Exception | Deletion is terminal. The caller needs a different group.                                                                                                                                                                                                                                                                                                                                                                   |
+| `resource_not_found`                    | Exception | The identifier is wrong or outside the credential's reach; absent and out-of-scope look identical on purpose.                                                                                                                                                                                                                                                                                                               |
+| `resource_expired`                      | Exception | Published but not produced by the service today: a resource's expiry reaches the caller as its own `status` or `state`, which is already a value. The recipient-session element treats it, with `recipient_capability_invalid`, as a session that has ended.                                                                                                                                                                |
+| `credential_organization_mismatch`      | Exception | An organization credential reached a project outside its organization.                                                                                                                                                                                                                                                                                                                                                      |
+| `endpoint_rotation_conflict`            | Exception | A prior overlap is still active. The caller waits for `retryAt`, as for rate limiting.                                                                                                                                                                                                                                                                                                                                      |
+| `rate_limited`                          | Exception | Wait until `retryAt`. The caller's response is to wait, not to branch.                                                                                                                                                                                                                                                                                                                                                      |
+| `privacy_operation_in_progress`         | Exception | Export, erasure, or organization closure still has in-flight work to drain or a provider cleanup to retry. Wait until `retryAt`, then repeat the same operation.                                                                                                                                                                                                                                                            |
+| `provider_retryable`                    | Exception | The provider failed before acceptance. The service retries where a retry is scheduled; the caller waits.                                                                                                                                                                                                                                                                                                                    |
+| `provider_terminal`                     | Exception | The provider refused permanently. Fix the binding or the content and send a new message.                                                                                                                                                                                                                                                                                                                                    |
+| `provider_outcome_unknown`              | Exception | The provider may already have acted. Read the resource state before deciding anything.                                                                                                                                                                                                                                                                                                                                      |
+| `internal_error`                        | Exception | WhooshBang failed on its own side; no provider or customer system was involved. Retried like any retryable problem. If it persists, report `diagnosticId` to support.                                                                                                                                                                                                                                                       |
 
 ## Errors
 
@@ -603,14 +740,12 @@ sole customer-owned email connection supplies its domain; specify `connection_id
 when more than one exists. No verification message is sent.
 
 ```ts
-const binding = await client.assertEmailConsent(
-  {
-    subscriber_id: "customer_123",
-    address: "Case.Sensitive+tag@example.com",
-    consented: true,
-    consented_at: "2026-09-10T12:00:00Z",
-  },
-);
+const binding = await client.assertEmailConsent({
+  subscriber_id: "customer_123",
+  address: "Case.Sensitive+tag@example.com",
+  consented: true,
+  consented_at: "2026-09-10T12:00:00Z",
+});
 ```
 
 Use a canonical mailbox: preserve the unquoted ASCII local part exactly,
@@ -660,11 +795,25 @@ Interaction builders now return send-time inputs. Relative durations start when
 The production API URL is the default. Override `baseUrl` for a local mock or proxy.
 
 ```ts
-const wb = new WhooshBangClient({ credential: process.env.WHOOSHBANG_CREDENTIAL! });
-await wb.createMessage({ to: "customer_123", content: "Order 4821 has shipped." });
-await wb.ask({ to: "customer_123", interaction: { prompt: "Ship it?" } }, { patienceMs: 60_000 });
-await wb.ask({ to: "customer_123", interaction: { prompt: "Choose", options: ["A", "B"] } });
-await wb.ask({ to: "customer_123", interaction: { type: "input", prompt: "What should change?" } });
+const wb = new WhooshBangClient({
+  credential: process.env.WHOOSHBANG_CREDENTIAL!,
+});
+await wb.createMessage({
+  to: "customer_123",
+  content: "Order 4821 has shipped.",
+});
+await wb.ask(
+  { to: "customer_123", interaction: { prompt: "Ship it?" } },
+  { patienceMs: 60_000 },
+);
+await wb.ask({
+  to: "customer_123",
+  interaction: { prompt: "Choose", options: ["A", "B"] },
+});
+await wb.ask({
+  to: "customer_123",
+  interaction: { type: "input", prompt: "What should change?" },
+});
 ```
 
 `{ text }` and `{ blocks }` infer their content type. An image needs only its

package/dist/cli/commands.js

@@ -289,6 +289,8 @@ function answerText(summary) {
     if (read.outcome !== "answered")
         return undefined;
     const { answer } = read;
+    if (answer.type === "acknowledge")
+        return "acknowledged";
     return answer.type === "confirm"
         ? answer.value
             ? "yes"