@whooshbang/contracts 3.0.0 → 3.2.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: 3.0.0
+x-contract-version: 3.2.0
 info:
   title: WhooshBang API
-  version: 3.0.0
+  version: 3.2.0
   description: |
     The V1 contract for human organization/project administration, project-scoped
     subscription links, and asynchronous text messages. A Clerk session selects
@@ -51,6 +51,8 @@ tags:
     description: Single-use, expiring Telegram authorization links.
   - name: Messages
     description: Asynchronous logical messages and their highest proven outcomes.
+  - name: Message categories
+    description: Project categories and subscriber choices for those categories.
   - name: Machine clients
     description: Project-administered, destination-bound local-client identities and one-way credential metadata.
   - name: Machine events
@@ -72,6 +74,183 @@ tags:
   - name: Group broadcasts
     description: Durable group acceptance and aggregate projection over ordinary child messages.
 paths:
+  /v1/projects/{project_id}/message-categories:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+    get:
+      operationId: listMessageCategories
+      summary: List project message categories
+      tags: [Message categories]
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+        - bearerCredential: []
+      x-required-scopes: [projects:read]
+      responses:
+        "200":
+          description: Categories in this project.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageCategoryCollection"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    post:
+      operationId: createMessageCategory
+      summary: Add a project message category
+      tags: [Message categories]
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+        - bearerCredential: []
+      x-required-scopes: [projects:write]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateMessageCategoryRequest"
+      responses:
+        "201":
+          description: Category added.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageCategory"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "409":
+          $ref: "#/components/responses/Conflict"
+  /v1/projects/{project_id}/message-categories/{category_key}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - name: category_key
+        in: path
+        required: true
+        schema:
+          $ref: "#/components/schemas/MessageCategoryKey"
+    put:
+      operationId: updateMessageCategory
+      summary: Change a project's message category
+      tags: [Message categories]
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+        - bearerCredential: []
+      x-required-scopes: [projects:write]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateMessageCategoryRequest"
+      responses:
+        "200":
+          description: Category updated.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageCategory"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+    delete:
+      operationId: deleteMessageCategory
+      summary: Remove an unused message category
+      tags: [Message categories]
+      description: The default category and a category still used by queued messages cannot be removed.
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+        - bearerCredential: []
+      x-required-scopes: [projects:write]
+      responses:
+        "204":
+          description: Category removed.
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
+  /v1/projects/{project_id}/environments/{environment_id}/notification-preferences/categories:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+    get:
+      operationId: getOwnCategoryPreferences
+      summary: Read my message category switches
+      tags: [Message categories]
+      security:
+        - clerkSession: []
+      x-required-scopes: [messages:read]
+      responses:
+        "200":
+          description: Category choices for the signed-in person.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriberCategoryPreferenceCollection"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/projects/{project_id}/environments/{environment_id}/notification-preferences/categories/{category_key}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - $ref: "#/components/parameters/EnvironmentId"
+      - name: category_key
+        in: path
+        required: true
+        schema:
+          $ref: "#/components/schemas/MessageCategoryKey"
+    put:
+      operationId: setOwnCategoryPreference
+      summary: Switch one of my message categories on or off
+      tags: [Message categories]
+      security:
+        - clerkSession: []
+      x-required-scopes: [messages:write]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SetSubscriberCategoryPreferenceRequest"
+      responses:
+        "200":
+          description: Updated category choice.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriberCategoryPreference"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
   /v1/projects/{project_id}/environments/{environment_id}/whoami:
     get:
       operationId: whoAmI
@@ -327,6 +506,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
@@ -5623,6 +5837,60 @@ paths:
           $ref: "#/components/responses/RecipientCapabilityInvalid"
         "403":
           $ref: "#/components/responses/RecipientOriginForbidden"
+  /v1/recipient-session/category-preferences:
+    get:
+      operationId: getCategoryPreferences
+      summary: Read this subscriber's message categories and switches
+      tags: [Message categories]
+      security:
+        - recipientSessionCapability: []
+      responses:
+        "200":
+          description: Category choices for this exact subscriber.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriberCategoryPreferenceCollection"
+        "401":
+          $ref: "#/components/responses/RecipientCapabilityInvalid"
+        "403":
+          $ref: "#/components/responses/RecipientOriginForbidden"
+  /v1/recipient-session/category-preferences/{category_key}:
+    parameters:
+      - name: category_key
+        in: path
+        required: true
+        schema:
+          $ref: "#/components/schemas/MessageCategoryKey"
+    put:
+      operationId: setCategoryPreference
+      summary: Switch one of this subscriber's message categories on or off
+      tags: [Message categories]
+      security:
+        - recipientSessionCapability: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SetSubscriberCategoryPreferenceRequest"
+      responses:
+        "200":
+          description: Updated category choice.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriberCategoryPreference"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/RecipientCapabilityInvalid"
+        "403":
+          $ref: "#/components/responses/RecipientOriginForbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          $ref: "#/components/responses/Conflict"
   /v1/recipient-session/logo/{asset_id}:
     parameters:
       - name: Origin
@@ -9098,6 +9366,22 @@ components:
       schema:
         $ref: "#/components/schemas/DiagnosticId"
   schemas:
+    MessageCategoryKey:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/MessageCategoryKey
+    MessageCategory:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/MessageCategory
+    MessageCategoryCollection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/MessageCategoryCollection
+    CreateMessageCategoryRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateMessageCategoryRequest
+    UpdateMessageCategoryRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/UpdateMessageCategoryRequest
+    SubscriberCategoryPreference:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/SubscriberCategoryPreference
+    SubscriberCategoryPreferenceCollection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/SubscriberCategoryPreferenceCollection
+    SetSubscriberCategoryPreferenceRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/SetSubscriberCategoryPreferenceRequest
     WhoAmI:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/WhoAmI
     Operator:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whooshbang/contracts",
-  "version": "3.0.0",
+  "version": "3.2.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": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "CoreContractScenario",
   "description": "A deterministic C0-02 semantic, state, idempotency, or isolation scenario.",
   "type": "object",

package/schemas/events/agent-binding-degraded-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/agent-binding-degraded-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "AgentBindingDegradedEventV1",
   "description": "An agent binding entered a provider-neutral degraded state.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/AgentBindingDegradedEvent"

package/schemas/events/interaction-expired-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/interaction-expired-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "InteractionExpiredEventV1",
   "description": "An interaction reached its terminal expiry without a valid answer.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/InteractionExpiredEvent"

package/schemas/events/interaction-received-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/interaction-received-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "InteractionReceivedEventV1",
   "description": "One authenticated, provider-neutral interaction answer was received.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/InteractionReceivedEvent"

package/schemas/events/message-delivered-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/message-delivered-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "MessageDeliveredEventV1",
   "description": "A provider supplied trustworthy evidence that a message was delivered.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/MessageDeliveredEvent"

package/schemas/events/message-expired-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/message-expired-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "MessageExpiredEventV1",
   "description": "A message expired before reaching a later delivery state.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/MessageExpiredEvent"

package/schemas/events/message-failed-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/message-failed-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "MessageFailedEventV1",
   "description": "A message reached a classified terminal failure.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/MessageFailedEvent"

package/schemas/events/message-provider-accepted-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/message-provider-accepted-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "MessageProviderAcceptedEventV1",
   "description": "The provider accepted a message without implying delivery.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/MessageProviderAcceptedEvent"

package/schemas/events/subscription-activated-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/subscription-activated-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "SubscriptionActivatedEventV1",
   "description": "A subscription became active with a safe public channel binding.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/SubscriptionActivatedEvent"

package/schemas/events/subscription-revoked-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/subscription-revoked-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "SubscriptionRevokedEventV1",
   "description": "A subscription and its safe public channel binding were revoked.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/SubscriptionRevokedEvent"

package/schemas/events/whooshbang-event-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/whooshbang-event-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "WhooshBangEventV1ContractDocument",
   "description": "Strict public customer-event envelope and initial WhooshBang event union.",
   "oneOf": [

package/schemas/fixture-index.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/fixture-index.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "CoreFixtureIndex",
   "description": "The machine-readable index of deterministic C0-02 through C0-04 golden fixtures.",
   "type": "object",

package/schemas/interaction-machine-scenario.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/interaction-machine-scenario.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "InteractionMachineScenario",
   "description": "A deterministic C0-03 interaction, credential, authorization, polling, acknowledgement, or quarantine scenario.",
   "type": "object",

package/schemas/interaction-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/interaction-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "InteractionV1ContractDocument",
   "description": "Provider-neutral confirm, single-select, input, lifecycle, callback-token, and authenticated answer-event contracts.",
   "$defs": {

package/schemas/machine-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/machine-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "MachineV1ContractDocument",
   "description": "Machine-client administration, locally generated credential metadata, durable long-poll, and contiguous acknowledgement contracts.",
   "oneOf": [

package/schemas/provider-capabilities-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/provider-capabilities-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "ProviderCapabilitiesV1",
   "description": "Provider-neutral, renderer-facing delivery and interaction capabilities with explicit degradation.",
   "type": "object",

package/schemas/webhooks/webhook-delivery-case-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/webhooks/webhook-delivery-case-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "WebhookDeliveryCaseSetV1",
   "description": "Deterministic customer webhook response classification, Retry-After, and delivery-bound cases.",
   "type": "object",

package/schemas/webhooks/webhook-signing-vector-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/webhooks/webhook-signing-vector-v1.schema.json",
-  "x-contract-version": "3.0.0",
+  "x-contract-version": "3.2.0",
   "title": "WebhookSigningVectorSetV1",
   "description": "Language-neutral deterministic Standard Webhooks V1 verification vectors. All key material is public synthetic test data and must never be used outside fixtures.",
   "type": "object",