@whooshbang/contracts 1.0.0-rc.13 → 1.0.0-rc.17

package/CHANGELOG.md

@@ -2,6 +2,240 @@
 
 All notable contract changes are recorded here.
 
+## 1.0.0-rc.16
+
+- Notifier routing becomes a public contract. `NotifierConnectionRoute`,
+  `NotifierConnectionCollection`, and `AttachNotifierConnectionRequest` publish
+  which connection a notifier sends and authorizes through, with `GET`, `POST`,
+  and `DELETE` on
+  `/v1/projects/{project_id}/environments/{environment_id}/notifier-connections`.
+  A connection nothing routes to is inert — it delivers nothing and a
+  subscriber cannot authorize against it — so this is the surface that decides
+  whether a connection does anything at all. Additive: existing notifier-first
+  sends are unchanged.
+- `connection-archived.problem` documents the refusal a caller receives for
+  routing a notifier through an archived connection: `request_invalid` with a
+  `connection_archived` field error on `/connection_id`. It is a 400 rather
+  than a 404 because the caller can see the connection and is entitled to know
+  its retirement is the reason.
+
+- `CreateMessageRequest.delivery_target` makes transport explicit: `connection`
+  delivers through the subscriber's selected environment connection and
+  `simulator` keeps deterministic fixture delivery independent of environment.
+  Omitting it preserves reserved simulator destinations while ordinary
+  subscribers default to connection delivery. `Message.delivery_target`
+  records the effective choice on every accepted and terminal response.
+- `CreateSubscriptionLinkRequest` may select an exact Telegram
+  `connection_id`. The chosen connection is fixed on the link and returned as
+  a safe summary containing its mode, display name, and public bot username;
+  idempotent replay therefore cannot silently move consent to a new default.
+- A pending Telegram link now opens the selected bot directly with an opaque
+  `start` capability. Activated bindings carry the same `connection_id`, so a
+  subscriber's consent stays attached to the bot they actually saw and can be
+  routed through that bot in the subsequent delivery story.
+- The change is additive. Callers may omit `connection_id` and let the service
+  choose an unambiguous compatible connection, while existing links and
+  bindings remain readable without the new fields.
+- Published authorization examples use deliberately non-secret start values
+  while preserving Telegram's exact 43-character capability shape. A semantic
+  fixture also pins that the direct link reveals neither the link id nor the
+  selected connection id.
+- A signed callback is still scoped to the selected connection. Presenting a
+  valid capability to another authenticated bot is ignored without sending a
+  consent card, creating a binding, or consuming the pending link.
+
+- `CreateChannelConnectionRequest` gains its third arm. `customer_managed` has
+  Telegram create a brand new bot on the administrator's own Telegram account,
+  which is what an application needs when it wants its own sender and has no
+  bot yet — the gap between `whooshbang_shared`, which lends ours, and
+  `customer_byok`, which adopts one they already built. Neither customer mode
+  supersedes the other: a bot that already exists can never be moved into
+  managed mode, because the manager permitted to act for a bot is fixed when
+  the bot is created.
+- The arm carries **no credential field at all**, and that absence is the whole
+  point of the mode. Telegram hands the new bot's token to WhooshBang server to
+  server, so it never passes through a browser, a clipboard, this request, or
+  any response. There is nothing here for a caller to paste and therefore
+  nothing for a caller to leak — which is a stronger promise than `writeOnly`
+  makes for `customer_byok`, where the customer necessarily holds the secret
+  already.
+- `suggested_bot_username` is required and comes from the caller rather than
+  from us. It is the handle every subscriber sees forever and Telegram will not
+  let it be changed once the bot exists, so a WhooshBang-generated handle would
+  permanently brand a customer's own bot with our naming — the one thing the
+  customer-owned modes exist to prevent. It is bounded to Telegram's own rule
+  (5–32 characters, a letter first, ending in `bot`) so a caller learns the
+  shape is wrong before an administrator is standing in front of the dialog. It
+  is a suggestion and not a reservation: the administrator can type something
+  else, and Telegram refuses a handle somebody already holds. Optional
+  `suggested_bot_name` prefills the display name in the same dialog and can be
+  changed afterwards, which is why it is a convenience rather than a
+  commitment.
+- `ChannelConnection` gains optional `setup`: the unfinished half of a
+  customer-managed connection, present only while one is unfinished. Its
+  absence is how a caller knows nothing further is expected of anyone — a
+  connection that never used guided setup never has it, and one that finished a
+  setup loses it, because from then on what the setup produced is described by
+  `identity` and `status` and the record of the attempt is not part of the
+  identity a subscriber consents to. The object is structurally incapable of
+  carrying a secret, which is what makes it safe to poll, render in a
+  dashboard, or forward to whoever is actually doing the setup.
+- `ChannelConnectionSetupStatus` is the only thing a caller can act on while a
+  connection is still `pending`, which `ChannelConnectionStatus` alone cannot
+  express. `awaiting_handoff` waits for the administrator to open the link on
+  the account that will own the bot; `awaiting_creation` means that account is
+  bound and the bot does not exist yet; `provisioning` means the bot exists and
+  delivery is being installed. `failed` and `expired` end an attempt without
+  ending the connection, and neither withdraws a bot Telegram already created,
+  because no provider API can delete one — the product says so rather than
+  implying a cleanup it cannot perform.
+- `handoff_url` is a capability for exactly one setup session. It names no
+  account, no project, and no environment, it stops working at `expires_at`,
+  and only the first Telegram account to open it is bound. It is not credential
+  material, so displaying it costs nothing beyond letting whoever sees it first
+  own the bot this setup creates. `failure_reason` is absent whenever there is
+  nothing both safe and useful to say: an attempt refused because that Telegram
+  account already holds a live setup says only that, because naming the
+  account, project, or environment holding the other one would disclose another
+  customer.
+- Add `restartChannelConnectionSetup`, `connections:write`, no body, returning
+  `ChannelConnection`. An abandoned or lapsed setup must always be able to end,
+  or one administrator's forgotten attempt would hold their Telegram account's
+  only managed-setup slot across the whole deployment, permanently. The
+  connection is reused rather than replaced because it is still `pending`:
+  nothing was provisioned under it, no identity was claimed, and no subscriber
+  consented to anything through it. It takes no body so that resuming cannot
+  rename a bot an administrator is already looking at — a different suggestion
+  is a different connection. Repeating it is safe: a session still usable comes
+  back as it stands, so two dashboard tabs converge on one link instead of
+  racing to strand each other's.
+- `RotateChannelConnectionCredentialRequest` becomes a union discriminated by
+  where a replacement can come from at all, not by caller preference. A
+  customer-owned bot has one only its owner can produce, so that arm sends
+  `credential` and is unchanged. A managed bot has one only Telegram can issue:
+  asked to rotate, it revokes the current token and returns the successor to
+  the manager that created the bot, so that arm sends a `source` of
+  `provider_managed` and nothing else. It is stated rather than
+  inferred from an empty body so that a request which lost its credential in
+  transit is refused as malformed instead of being read as a request to have
+  the provider mint a new token. Either way the identity is untouched: the same
+  bot keeps the same `@username` and the same subscribers, and only the secret
+  behind it is new.
+- A provider-managed rotation is one-shot, which changes what
+  `provider_outcome_unknown` means on that operation. Once the replace call may
+  have reached Telegram, the outcome is resolved by asking Telegram for the
+  bot's current token, never by replacing again — a second replace would revoke
+  the token the first one issued. On this operation the code is an instruction
+  to read the connection, not a hint to repeat the call.
+- No new `ProblemCode` members. The enum is closed and widening it would be
+  breaking, so every new refusal reuses a published code and is distinguished
+  by `field_errors[].code`: a rotation arm that does not match how the
+  connection holds its secret is `request_invalid` with
+  `rotation_source_mismatch` at `/credential` or `/source`; a restart on a
+  connection that never used guided setup is `idempotency_conflict` with
+  `setup_not_managed`; a restart on one that already finished, or is archived,
+  is `idempotency_conflict` with `invalid_connection_transition`.
+- Everything that can go wrong in a managed setup after the create returns is
+  reported on `setup` rather than as a refusal, because by then the connection
+  exists and the failing party is a person the request has already answered.
+  Both `failed` and `expired` are recoverable through
+  `restartChannelConnectionSetup` on the same connection.
+- The change is additive. `setup` is optional, both new arms are new members of
+  existing unions, and no existing field moved, so a client written against
+  `1.0.0-rc.16` keeps working unchanged.
+
+- Document that an occupied provider identity is a **warning, not a
+  prohibition**. Repeating the request with `confirm_webhook_takeover` connects
+  it whoever owns the endpoint it currently delivers to. WhooshBang is not the
+  caretaker of a customer's bot, and a developer comparing frameworks routinely
+  points one at us that already feeds something else.
+- Document `whooshbang_connection_takeover_required` on
+  `createChannelConnection`, for the case where the webhook being displaced
+  belongs to another WhooshBang connection. Separate from
+  `webhook_takeover_required` because the consequence is separate: confirming
+  this one **disables** the other connection, which would otherwise go on
+  reporting itself healthy while receiving nothing.
+- Document `provider_identity_unverifiable` on
+  `rotateChannelConnectionCredential`, for a connection whose own identity
+  cannot be established and whose replacement therefore cannot be proved to
+  belong to it.
+
+No schema changed. These are refusals the closed Problem vocabulary already
+carries, distinguished by `field_errors[].code`, and they are written down here
+because an integrator branching on those codes has no other way to learn them.
+
+## 1.0.0-rc.15
+
+- `CreateChannelConnectionRequest` becomes a union discriminated on `mode`.
+  The existing `whooshbang_shared` arm is unchanged; a new `customer_byok` arm
+  connects a provider identity the customer already owns by supplying its
+  credential, with an optional `confirm_webhook_takeover`. `customer_managed`
+  stays in the mode vocabulary and is still not creatable.
+- The `customer_byok` arm carries **no** identity field, and the absence is
+  load-bearing. `provider_identity_digest` is unique across every tenant, so an
+  endpoint that digested a client-supplied identity would answer "already
+  claimed" for a bot the caller does not own — an oracle for whether any given
+  bot is connected to WhooshBang by anyone. The identity is derived
+  server-side from a provider-validated `getMe` on the submitted credential,
+  which no caller can forge without holding the credential itself.
+- `credential` is bounded at 1–512 characters and marked `writeOnly`. It is
+  sealed on arrival and is echoed by no response; no reference to it appears in
+  `ChannelConnection`, exactly as for the shared identities WhooshBang
+  operates.
+- Add `repairChannelConnection`, `rotateChannelConnectionCredential`,
+  `checkChannelConnectionHealth`, and `purgeChannelConnection` on one
+  connection, each `connections:write` and each returning `ChannelConnection`.
+  Rotation carries the new `RotateChannelConnectionCredentialRequest`; the
+  other three carry no body. Purge is repeat-safe: destroying something already
+  destroyed reports the same archived connection, because a caller that lost
+  the first response has to be able to confirm the outcome.
+- `checkChannelConnectionHealth` is `connections:write` rather than
+  `connections:read` deliberately. It makes a live provider call and advances
+  the connection's recorded health, so it is not a safe read.
+- No new `ProblemCode` members. The enum is closed and widening it would be
+  breaking, so every new refusal reuses a published code and is distinguished
+  by `field_errors[].code`, as `AlphaAccessRequiredError` established: a
+  rejected credential is `request_invalid` with `provider_credential_invalid`,
+  an occupied webhook is `request_invalid` with `webhook_takeover_required`, a
+  replacement for another bot is `request_invalid` with
+  `provider_identity_mismatch`, a bot any account already connected is
+  `idempotency_conflict` with `provider_identity_claimed`, and rotating a
+  WhooshBang-operated credential is `idempotency_conflict` with
+  `credential_not_customer_owned`. An unreachable provider is
+  `provider_outcome_unknown` and a rate-limited one is `provider_retryable`
+  with `retry_at`.
+- `ChannelConnection` is unchanged. `status` already separates `pending` from
+  `active`, so a client can already tell a provisioned connection from a
+  half-provisioned one, which keeps this bump purely additive.
+- Coordinate with SDK `1.0.0-rc.16` and deterministic mock `1.0.0-rc.19`.
+  `1.0.0-rc.14` remains immutable.
+
+## 1.0.0-rc.14
+
+- Add Channel Connections: an environment's explicit selection of the provider
+  identity its recipients will see. `listConnectionProviders` reports the
+  supported providers, their setup modes, and the WhooshBang-owned identities an
+  environment may select; `listChannelConnections`, `createChannelConnection`,
+  `getChannelConnection`, `updateChannelConnection`, and
+  `archiveChannelConnection` manage one environment's own connections.
+- Credential material and every reference to one are structurally absent from
+  the `ChannelConnection` shape, including for shared identities WhooshBang
+  operates. Selecting a shared identity never conveys the ability to read,
+  rotate, or retire it.
+- `updateChannelConnection` requires the `row_version` that was read, so a
+  rename and a disable issued at the same time cannot silently undo each other.
+  Archiving is terminal: reconnecting later is a new connection, so consent a
+  subscriber gave to the archived identity is never revived under it.
+- Add the `connections:read` and `connections:write` credential scopes. Choosing
+  which identity an environment sends through is neither a messaging power nor
+  project administration, so it does not ride on either. Existing scopes and
+  operations are unchanged.
+- Only `whooshbang_shared` is accepted on create today. The customer-owned modes
+  are published in the vocabulary because they are the accepted model, and they
+  become creatable with the provider setup journeys that can supply an identity.
+- Coordinate with SDK `1.0.0-rc.15` and deterministic mock `1.0.0-rc.17`.
+  `1.0.0-rc.13` remains immutable.
+
 ## 1.0.0-rc.13
 
 - Publish the unchanged contract schemas and fixtures as the first public npm

package/contract-manifest.json

@@ -1,115 +1,115 @@
 {
   "schema": "flowxo.contract-manifest.v1",
   "artifact": "@whooshbang/contracts",
-  "version": "1.0.0-rc.13",
+  "version": "1.0.0-rc.17",
   "openapi": [
     {
       "id": "whooshbang-rest-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "openapi/whooshbang-v1.yaml"
     }
   ],
   "schemas": [
     {
       "id": "whooshbang-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/whooshbang-v1.schema.json"
     },
     {
       "id": "interaction-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/interaction-v1.schema.json"
     },
     {
       "id": "machine-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/machine-v1.schema.json"
     },
     {
       "id": "provider-capabilities-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/provider-capabilities-v1.schema.json"
     },
     {
       "id": "whooshbang-event-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/events/whooshbang-event-v1.schema.json"
     },
     {
       "id": "subscription-activated-event-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/events/subscription-activated-v1.schema.json"
     },
     {
       "id": "subscription-revoked-event-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/events/subscription-revoked-v1.schema.json"
     },
     {
       "id": "message-provider-accepted-event-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/events/message-provider-accepted-v1.schema.json"
     },
     {
       "id": "message-delivered-event-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/events/message-delivered-v1.schema.json"
     },
     {
       "id": "message-failed-event-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/events/message-failed-v1.schema.json"
     },
     {
       "id": "message-expired-event-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/events/message-expired-v1.schema.json"
     },
     {
       "id": "interaction-received-event-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/events/interaction-received-v1.schema.json"
     },
     {
       "id": "interaction-expired-event-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/events/interaction-expired-v1.schema.json"
     },
     {
       "id": "agent-binding-degraded-event-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/events/agent-binding-degraded-v1.schema.json"
     },
     {
       "id": "webhook-signing-vector-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/webhooks/webhook-signing-vector-v1.schema.json"
     },
     {
       "id": "webhook-delivery-case-v1",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/webhooks/webhook-delivery-case-v1.schema.json"
     },
     {
       "id": "interaction-machine-scenario",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/interaction-machine-scenario.schema.json"
     },
     {
       "id": "core-contract-scenario",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/core-scenario.schema.json"
     },
     {
       "id": "core-fixture-index",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "path": "schemas/fixture-index.schema.json"
     }
   ],
   "fixture_sets": [
     {
       "id": "core-api-bodies",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "schema": "schemas/whooshbang-v1.schema.json",
       "fixtures": [
         "fixtures/core-v1/requests/create-project.json",
@@ -131,6 +131,7 @@
         "fixtures/core-v1/success/customer-endpoint-attempts.json",
         "fixtures/core-v1/requests/create-subscription-link.json",
         "fixtures/core-v1/requests/create-message.json",
+        "fixtures/core-v1/requests/create-message-connection.json",
         "fixtures/core-v1/success/subscription-link-pending.json",
         "fixtures/core-v1/success/subscription-link-activated.json",
         "fixtures/core-v1/success/subscription-link-paused.json",
@@ -160,12 +161,33 @@
         "fixtures/core-v1/problems/rate-limited.json",
         "fixtures/core-v1/problems/provider-retryable.json",
         "fixtures/core-v1/problems/provider-terminal.json",
-        "fixtures/core-v1/problems/provider-outcome-unknown.json"
+        "fixtures/core-v1/problems/provider-outcome-unknown.json",
+        "fixtures/core-v1/requests/create-channel-connection.json",
+        "fixtures/core-v1/requests/create-channel-connection-byok.json",
+        "fixtures/core-v1/requests/create-channel-connection-managed.json",
+        "fixtures/core-v1/requests/update-channel-connection.json",
+        "fixtures/core-v1/requests/rotate-channel-connection-credential.json",
+        "fixtures/core-v1/requests/rotate-channel-connection-managed.json",
+        "fixtures/core-v1/requests/attach-notifier-connection.json",
+        "fixtures/core-v1/success/connection-provider-collection.json",
+        "fixtures/core-v1/success/channel-connection-collection.json",
+        "fixtures/core-v1/success/channel-connection-created.json",
+        "fixtures/core-v1/success/channel-connection-byok-created.json",
+        "fixtures/core-v1/success/channel-connection-managed-pending.json",
+        "fixtures/core-v1/success/channel-connection-managed-setup-failed.json",
+        "fixtures/core-v1/success/channel-connection-setup-restarted.json",
+        "fixtures/core-v1/success/channel-connection-repaired.json",
+        "fixtures/core-v1/success/channel-connection-credential-rotated.json",
+        "fixtures/core-v1/success/channel-connection-managed-rotated.json",
+        "fixtures/core-v1/success/channel-connection-health-checked.json",
+        "fixtures/core-v1/success/channel-connection-archived.json",
+        "fixtures/core-v1/success/channel-connection-purged.json",
+        "fixtures/core-v1/success/notifier-connection-collection.json"
       ]
     },
     {
       "id": "core-semantic-scenarios",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "schema": "schemas/core-scenario.schema.json",
       "fixtures": [
         "fixtures/core-v1/scenarios/project-create-equivalent-replay.json",
@@ -182,6 +204,9 @@
         "fixtures/core-v1/scenarios/missing-scope.json",
         "fixtures/core-v1/scenarios/malformed-bearer.json",
         "fixtures/core-v1/scenarios/subscription-activation-replay.json",
+        "fixtures/core-v1/scenarios/subscription-authorization-capability-opacity.json",
+        "fixtures/core-v1/scenarios/subscription-cross-connection-callback-rejected.json",
+        "fixtures/core-v1/scenarios/subscription-selected-connection-replay.json",
         "fixtures/core-v1/scenarios/subscription-expired-replay.json",
         "fixtures/core-v1/scenarios/provider-outcome-unknown.json",
         "fixtures/core-v1/scenarios/cancellation-too-late.json",
@@ -190,7 +215,7 @@
     },
     {
       "id": "interaction-message-api-bodies",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "schema": "schemas/whooshbang-v1.schema.json",
       "fixtures": [
         "fixtures/interaction-machine-v1/requests/create-message-confirm.json",
@@ -202,7 +227,7 @@
     },
     {
       "id": "interaction-contract-bodies",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "schema": "schemas/interaction-v1.schema.json",
       "fixtures": [
         "fixtures/interaction-machine-v1/success/interaction-open.json",
@@ -219,7 +244,7 @@
     },
     {
       "id": "machine-api-bodies",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "schema": "schemas/machine-v1.schema.json",
       "fixtures": [
         "fixtures/interaction-machine-v1/requests/create-machine-client.json",
@@ -240,13 +265,13 @@
     },
     {
       "id": "provider-capability-bodies",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "schema": "schemas/provider-capabilities-v1.schema.json",
       "fixtures": ["fixtures/interaction-machine-v1/capabilities/telegram.json"]
     },
     {
       "id": "interaction-machine-semantic-scenarios",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "schema": "schemas/interaction-machine-scenario.schema.json",
       "fixtures": [
         "fixtures/interaction-machine-v1/scenarios/interaction-duplicate.json",
@@ -283,7 +308,7 @@
     },
     {
       "id": "customer-event-bodies",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "schema": "schemas/events/whooshbang-event-v1.schema.json",
       "fixtures": [
         "fixtures/whooshbang-events-v1/events/subscription-activated.json",
@@ -299,19 +324,19 @@
     },
     {
       "id": "webhook-signing-vectors",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "schema": "schemas/webhooks/webhook-signing-vector-v1.schema.json",
       "fixtures": ["fixtures/whooshbang-events-v1/signing/vectors.json"]
     },
     {
       "id": "webhook-delivery-cases",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "schema": "schemas/webhooks/webhook-delivery-case-v1.schema.json",
       "fixtures": ["fixtures/whooshbang-events-v1/delivery/cases.json"]
     },
     {
       "id": "core-fixture-index",
-      "version": "1.0.0-rc.13",
+      "version": "1.0.0-rc.17",
       "schema": "schemas/fixture-index.schema.json",
       "fixtures": ["fixtures/core-v1/fixture-index.json"]
     }