@whooshbang/contracts 3.1.0 → 3.3.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.1.0
+x-contract-version: 3.3.0
 info:
   title: WhooshBang API
-  version: 3.1.0
+  version: 3.3.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,191 @@ 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
+      description: By default, only current categories are listed. Include archived categories when offering a filter over historical messages.
+      tags: [Message categories]
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+        - bearerCredential: []
+      x-required-scopes: [projects:read]
+      parameters:
+        - in: query
+          name: include_archived
+          required: false
+          schema:
+            type: boolean
+            default: false
+      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
@@ -5658,6 +5845,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
@@ -6649,7 +6890,7 @@ paths:
     get:
       operationId: listMessagesInEnvironment
       summary: List accepted messages with filters
-      description: "Content-free message history. Filters combine. accepted_after is inclusive; accepted_before is exclusive. Supply after or page, never both. after accepts the opaque next_after continuation; history intentionally has no total."
+      description: "Message history with a retained-content snippet. q searches retained text or an exact message or subscriber ID. After content expires, its message ID still finds it. Filters combine before pagination. accepted_after is inclusive; accepted_before is exclusive. Supply after or page, never both. after accepts the opaque next_after continuation; history intentionally has no total."
       tags: [Administration]
       security:
         - clerkSession: []
@@ -6680,6 +6921,14 @@ paths:
           required: false
           schema:
             $ref: "#/components/schemas/OpaqueIdentifier"
+        - in: query
+          name: q
+          required: false
+          description: Search retained message text or an exact message or subscriber ID. Expired content is found by message ID only.
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 256
         - in: query
           name: accepted_after
           required: false
@@ -6695,6 +6944,19 @@ paths:
           required: false
           schema:
             $ref: "#/components/schemas/OpaqueIdentifier"
+        - in: query
+          name: category_key
+          required: false
+          description: Match the category key captured when the message was accepted.
+          schema:
+            $ref: "#/components/schemas/MessageCategoryKey"
+        - in: query
+          name: no_category
+          required: false
+          description: Match messages accepted before categories were recorded. Cannot be true with category_key.
+          schema:
+            type: boolean
+            default: false
         - in: query
           name: state
           required: false
@@ -9133,6 +9395,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.1.0",
+  "version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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.1.0",
+  "x-contract-version": "3.3.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",