@whooshbang/contracts 2.6.0 → 3.1.0

package/fixtures/core-v1/scenarios/metadata-overrun.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "metadata-overrun",
   "category": "message_outcome",
   "given": {

package/fixtures/core-v1/scenarios/missing-scope.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "missing-scope",
   "category": "isolation",
   "given": {

package/fixtures/core-v1/scenarios/project-create-equivalent-replay.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "project-create-equivalent-replay",
   "category": "idempotency",
   "given": {

package/fixtures/core-v1/scenarios/project-slug-conflict.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "project-slug-conflict",
   "category": "idempotency",
   "given": {

package/fixtures/core-v1/scenarios/provider-outcome-unknown.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "provider-outcome-unknown",
   "category": "message_outcome",
   "given": {

package/fixtures/core-v1/scenarios/subscription-activation-replay.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "subscription-activation-replay",
   "category": "subscription_replay",
   "given": {

package/fixtures/core-v1/scenarios/subscription-authorization-capability-opacity.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "subscription-authorization-capability-opacity",
   "category": "isolation",
   "given": {

package/fixtures/core-v1/scenarios/subscription-cross-connection-callback-rejected.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "subscription-cross-connection-callback-rejected",
   "category": "isolation",
   "given": {

package/fixtures/core-v1/scenarios/subscription-expired-replay.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "subscription-expired-replay",
   "category": "subscription_replay",
   "given": {

package/fixtures/core-v1/scenarios/subscription-selected-connection-replay.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "subscription-selected-connection-replay",
   "category": "subscription_replay",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/ack-conflict.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "ack-conflict",
   "category": "machine_ack",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/ack-cross-machine.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "ack-cross-machine",
   "category": "machine_authorization",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/ack-out-of-order.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "ack-out-of-order",
   "category": "machine_ack",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/ack-replay.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "ack-replay",
   "category": "machine_ack",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/ambiguous-free-text.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "ambiguous-free-text",
   "category": "interaction_resolution",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/callback-token-opacity.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "callback-token-opacity",
   "category": "callback_token",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/credential-registration-conflict.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "credential-registration-conflict",
   "category": "machine_credential",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/credential-registration-replay.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "credential-registration-replay",
   "category": "machine_credential",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/credential-revocation-replay.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "credential-revocation-replay",
   "category": "machine_credential",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/credential-rotation.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "credential-rotation",
   "category": "machine_credential",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/first-credential-activates.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "first-credential-activates",
   "category": "machine_credential",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/interaction-duplicate.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "interaction-duplicate",
   "category": "interaction_resolution",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/interaction-expired.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "interaction-expired",
   "category": "interaction_resolution",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/interaction-mismatch.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "interaction-mismatch",
   "category": "interaction_resolution",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/interaction-retired.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "interaction-retired",
   "category": "interaction_resolution",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/interaction-stale.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "interaction-stale",
   "category": "interaction_resolution",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/machine-admin-denied.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "machine-admin-denied",
   "category": "machine_authorization",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/machine-bound-message-create.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "machine-bound-message-create",
   "category": "machine_authorization",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/machine-cancel-denied.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "machine-cancel-denied",
   "category": "machine_authorization",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/machine-crash-before-ack.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "machine-crash-before-ack",
   "category": "machine_poll",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/machine-notifier-mismatch.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "machine-notifier-mismatch",
   "category": "machine_authorization",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/machine-other-message-read.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "machine-other-message-read",
   "category": "machine_authorization",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/machine-owned-message-read.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "machine-owned-message-read",
   "category": "machine_authorization",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/machine-subscriber-mismatch.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "machine-subscriber-mismatch",
   "category": "machine_authorization",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/poll-uncommitted-cursor-rejected.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "poll-uncommitted-cursor-rejected",
   "category": "machine_poll",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/project-credential-machine-endpoint-denied.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "project-credential-machine-endpoint-denied",
   "category": "machine_authorization",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/quarantine-integrity-rejected.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "quarantine-integrity-rejected",
   "category": "quarantine",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/quarantine-signature-rejected.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "quarantine-signature-rejected",
   "category": "quarantine",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/quarantine-valid.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "quarantine-valid",
   "category": "quarantine",
   "given": {

package/fixtures/interaction-machine-v1/scenarios/revoked-machine-credential.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "revoked-machine-credential",
   "category": "machine_authorization",
   "given": {

package/fixtures/recipient-experience-v1/scenarios/membership-broadcast-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "membership-broadcast-snapshot",
   "category": "membership_broadcast",
   "given": {

package/fixtures/recipient-experience-v1/scenarios/preferred-binding-resolution.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "preferred-binding-resolution",
   "category": "preference_resolution",
   "given": {

package/fixtures/recipient-experience-v1/scenarios/recipient-session-security.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "recipient-session-security",
   "category": "recipient_security",
   "given": {

package/fixtures/recipient-experience-v1/scenarios/subscriber-initial-groups-transaction.json

@@ -1,5 +1,5 @@
 {
-  "contract_version": "2.6.0",
+  "contract_version": "3.1.0",
   "id": "subscriber-initial-groups-transaction",
   "category": "subscriber_groups",
   "given": {

package/openapi/generated/whooshbang-v1.bundle.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.1",
   "info": {
     "title": "WhooshBang API",
-    "version": "2.6.0",
+    "version": "3.1.0",
     "description": "The V1 contract for human organization/project administration, project-scoped\nsubscription links, and asynchronous text messages. A Clerk session selects\none organization for administration. A project credential selects one organization,\nproject, and `test` or `live` environment for product operations; request\nbodies cannot override either authenticated scope.\n\nA person's OAuth grant selects one organization and carries scopes, but no\nproject. It names the project and environment it acts in through the URL\npath, on the environment-scoped form of each operation; the service checks\nthat path against the granting person's membership on every call. The flat\nforms remain credential-only and are unchanged.\n\nResource identifiers are opaque and are not authorization. Reads outside the\ncredential scope return the same `404` shape as absent resources. Provider\ncredentials, raw Telegram identity, and protected provider responses are\nnever part of this API.\n",
     "termsOfService": "https://flowxo.com/terms",
     "contact": {
@@ -407,6 +407,46 @@
         }
       }
     },
+    "/v1/projects/{project_id}/environments/{environment_id}/notification-preferences/bindings/{binding_id}/resume": {
+      "post": {
+        "operationId": "resumeOperatorBinding",
+        "x-notification-scopes": ["notifications:self", "notifications:team"],
+        "summary": "resumeOperatorBinding",
+        "description": "Resumes one of the authenticated person's own paused channels. Only the authenticated human can manage personal preferences; this never establishes consent or revives a revoked binding.",
+        "tags": ["Operators"],
+        "security": [
+          { "clerkSession": [] },
+          { "bearerCredential": [] },
+          { "bearerGrant": ["messages:write"] },
+          { "bearerGrant": ["notifications:self"] },
+          { "bearerGrant": ["notifications:team"] }
+        ],
+        "x-required-scopes": ["messages:write"],
+        "parameters": [
+          { "$ref": "#/components/parameters/ProjectId" },
+          { "$ref": "#/components/parameters/EnvironmentId" },
+          {
+            "in": "path",
+            "name": "binding_id",
+            "required": true,
+            "schema": { "$ref": "#/components/schemas/OpaqueIdentifier" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Authorized result.",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/OperatorPreferences" }
+              }
+            }
+          },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "403": { "$ref": "#/components/responses/Forbidden" },
+          "404": { "$ref": "#/components/responses/NotFound" }
+        }
+      }
+    },
     "/v1/projects/{project_id}/environments/{environment_id}/notification-preferences/connect": {
       "post": {
         "operationId": "connectOperatorChannel",
@@ -11897,6 +11937,29 @@
           "settings": {
             "$ref": "#/components/schemas/SubscriberChannelSettings"
           },
+          "accounts": {
+            "type": "array",
+            "maxItems": 10,
+            "description": "Who each of your connected channels reaches, as the channel named you when you connected: a Telegram or Slack name and username, by binding. Kept only on the Standard privacy setting, so it is empty otherwise.",
+            "items": {
+              "type": "object",
+              "required": ["binding_id"],
+              "properties": {
+                "binding_id": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 128
+                },
+                "name": { "type": "string", "minLength": 1, "maxLength": 254 },
+                "username": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 80
+                }
+              },
+              "additionalProperties": false
+            }
+          },
           "connections": {
             "type": "array",
             "items": {
@@ -11957,7 +12020,7 @@
       },
       "MessageListEntry": {
         "type": "object",
-        "description": "Content-free accepted-message summary. Includes neither the notification nor an interaction answer.",
+        "description": "Accepted-message summary: a one-line snippet of what the message said, and no interaction answer.",
         "required": [
           "accepted_at",
           "diagnostic_id",
@@ -12005,6 +12068,16 @@
           "classified_error": {
             "$ref": "#/components/schemas/ClassifiedError"
           },
+          "content_snippet": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 121,
+            "description": "The start of what the message said, on one line: its text, or the title of block content, cut to 120 characters with an ellipsis. Absent when `content_retained` is false."
+          },
+          "content_retained": {
+            "type": "boolean",
+            "description": "False once the message's content has been deleted at the end of its retention period (7 days, or 90 on paid plans, after it finished). The rest of the entry is kept."
+          },
           "channel": { "$ref": "#/components/schemas/Channel" }
         },
         "additionalProperties": false
@@ -15777,7 +15850,13 @@
           "last_failure": {
             "$ref": "#/components/schemas/CustomerEndpointFailure"
           },
-          "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" }
+          "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" },
+          "pause_reason": {
+            "type": "string",
+            "enum": ["customer", "sustained_failure", "probe_failed"]
+          },
+          "next_probe_at": { "$ref": "#/components/schemas/Timestamp" },
+          "recovery_pending": { "type": "boolean" }
         },
         "additionalProperties": false
       },
@@ -18710,6 +18789,11 @@
             "maxLength": 254,
             "description": "What to call this subscriber: `display_name` when your application sent one, otherwise the name their channel gave when they connected (a Telegram username, a Slack display name, an email address), which is kept only on the standard privacy setting. Absent when there is neither; show `subscriber_id` then."
           },
+          "team_member": {
+            "type": "boolean",
+            "const": true,
+            "description": "Present when this subscriber is someone on your WhooshBang team, messaged through the operators group. `name` is then their WhooshBang account name. They manage their own channels in notification preferences, so the subscriber can be read but not renamed, paused or erased."
+          },
           "locale": { "$ref": "#/components/schemas/RecipientLanguage" },
           "time_zone": { "$ref": "#/components/schemas/TimeZone" },
           "channels": {
@@ -21479,7 +21563,7 @@
       "provider-capabilities-v1.schema": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "$id": "https://whooshbang.flowxo.com/schemas/provider-capabilities-v1.schema.json",
-        "x-contract-version": "2.6.0",
+        "x-contract-version": "3.1.0",
         "title": "ProviderCapabilitiesV1",
         "description": "Provider-neutral, renderer-facing delivery and interaction capabilities with explicit degradation.",
         "type": "object",
@@ -22035,15 +22119,15 @@
                   "type": "https://whooshbang.flowxo.com/problems/replay_unavailable",
                   "title": "Replay unavailable",
                   "status": 409,
-                  "detail": "Customer event replay is not enabled for this project environment.",
+                  "detail": "Replay is available only after the latest delivery sequence reaches terminal failure.",
                   "code": "replay_unavailable",
-                  "diagnostic_id": "diag_replay_unavailable_rollout_001",
+                  "diagnostic_id": "diag_replay_unavailable_not_terminal_001",
                   "retryable": false,
                   "field_errors": [
                     {
                       "field": "/",
-                      "code": "rollout_disabled",
-                      "detail": "Customer event replay is not enabled for this project environment."
+                      "code": "not_terminal",
+                      "detail": "Replay is available only after the latest delivery sequence reaches terminal failure."
                     }
                   ]
                 }
@@ -22281,5 +22365,5 @@
       }
     }
   },
-  "x-contract-version": "2.6.0"
+  "x-contract-version": "3.1.0"
 }

package/openapi/whooshbang-v1.yaml

@@ -1,10 +1,10 @@
 openapi: 3.1.1
 jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
 # whooshbang:public-origin production api https://api.whooshbang.com
-x-contract-version: 2.6.0
+x-contract-version: 3.1.0
 info:
   title: WhooshBang API
-  version: 2.6.0
+  version: 3.1.0
   description: |
     The V1 contract for human organization/project administration, project-scoped
     subscription links, and asynchronous text messages. A Clerk session selects
@@ -327,6 +327,41 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
+  /v1/projects/{project_id}/environments/{environment_id}/notification-preferences/bindings/{binding_id}/resume:
+    post:
+      operationId: resumeOperatorBinding
+      x-notification-scopes: [notifications:self, notifications:team]
+      summary: resumeOperatorBinding
+      description: Resumes one of the authenticated person's own paused channels. Only the authenticated human can manage personal preferences; this never establishes consent or revives a revoked binding.
+      tags: [Operators]
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: [messages:write]
+        - bearerGrant: [notifications:self]
+        - bearerGrant: [notifications:team]
+      x-required-scopes: [messages:write]
+      parameters:
+        - $ref: "#/components/parameters/ProjectId"
+        - $ref: "#/components/parameters/EnvironmentId"
+        - in: path
+          name: binding_id
+          required: true
+          schema:
+            $ref: "../schemas/whooshbang-v1.schema.json#/$defs/OpaqueIdentifier"
+      responses:
+        "200":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OperatorPreferences"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /v1/projects/{project_id}/environments/{environment_id}/notification-preferences/connect:
     post:
       operationId: connectOperatorChannel
@@ -9551,7 +9586,7 @@ components:
             projectSlugConflict:
               externalValue: ../fixtures/core-v1/problems/project-slug-conflict.json
             replayUnavailable:
-              externalValue: ../fixtures/core-v1/problems/replay-unavailable-rollout.json
+              externalValue: ../fixtures/core-v1/problems/replay-unavailable-not-terminal.json
     Unprocessable:
       description: The request is valid in shape but names no usable authorized binding or registered return destination.
       headers:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whooshbang/contracts",
-  "version": "2.6.0",
+  "version": "3.1.0",
   "description": "Versioned public contracts for WhooshBang",
   "private": false,
   "license": "MIT",

package/schemas/core-scenario.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/core-scenario.schema.json",
-  "x-contract-version": "2.6.0",
+  "x-contract-version": "3.1.0",
   "title": "CoreContractScenario",
   "description": "A deterministic C0-02 semantic, state, idempotency, or isolation scenario.",
   "type": "object",