@whooshbang/contracts 2.3.0 → 2.5.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.3.0
+x-contract-version: 2.5.0
 info:
   title: WhooshBang API
-  version: 2.3.0
+  version: 2.5.0
   description: |
     The V1 contract for human organization/project administration, project-scoped
     subscription links, and asynchronous text messages. A Clerk session selects
@@ -75,6 +75,7 @@ paths:
   /v1/projects/{project_id}/environments/{environment_id}/whoami:
     get:
       operationId: whoAmI
+      x-notification-scopes: [notifications:self, notifications:team]
       summary: Identify the authenticated caller
       description: Personal login identifies me without a recipient question. Shared or service credentials report their actual principal and require an explicit recipient. No account owner or credential creator is inferred.
       tags: [Operators]
@@ -83,6 +84,8 @@ paths:
         - bearerCredential: []
         - bearerOrganizationCredential: []
         - bearerGrant: [messages:read]
+        - bearerGrant: [notifications:self]
+        - bearerGrant: [notifications:team]
         - machineCredential: []
       x-required-scopes: [messages:read]
       parameters:
@@ -102,6 +105,7 @@ paths:
   /v1/projects/{project_id}/environments/{environment_id}/operators:
     get:
       operationId: listOperators
+      x-notification-scopes: [notifications:team]
       summary: listOperators
       description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
       tags: [Operators]
@@ -109,6 +113,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: [messages:read]
+        - bearerGrant: [notifications:team]
       x-required-scopes: [messages:read]
       parameters:
         - $ref: "#/components/parameters/ProjectId"
@@ -130,6 +135,7 @@ paths:
   /v1/projects/{project_id}/environments/{environment_id}/operators/resolve:
     get:
       operationId: resolveOperator
+      x-notification-scopes: [notifications:team]
       summary: resolveOperator
       description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
       tags: [Operators]
@@ -137,6 +143,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: [messages:read]
+        - bearerGrant: [notifications:team]
       x-required-scopes: [messages:read]
       parameters:
         - $ref: "#/components/parameters/ProjectId"
@@ -159,6 +166,7 @@ paths:
   /v1/projects/{project_id}/environments/{environment_id}/operator-messages:
     post:
       operationId: sendOperatorMessage
+      x-notification-scopes: [notifications:self, notifications:team]
       summary: sendOperatorMessage
       description: Message a current teammate by name or operator ID. Personal callers may omit recipient or use me. Shared credentials must name a recipient. Runtime machine credentials report recipient_required for omitted or me; named operator sends are forbidden because runtime authority remains subscriber-bound.
       tags: [Operators]
@@ -168,6 +176,8 @@ paths:
         - bearerOrganizationCredential: []
         - machineCredential: []
         - bearerGrant: [messages:write]
+        - bearerGrant: [notifications:self]
+        - bearerGrant: [notifications:team]
       x-required-scopes: [messages:write]
       parameters:
         - $ref: "#/components/parameters/ProjectId"
@@ -193,6 +203,7 @@ paths:
   /v1/projects/{project_id}/environments/{environment_id}/operators/broadcasts:
     post:
       operationId: broadcastOperators
+      x-notification-scopes: [notifications:team]
       summary: broadcastOperators
       description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
       tags: [Operators]
@@ -200,6 +211,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: [messages:write]
+        - bearerGrant: [notifications:team]
       x-required-scopes: [messages:write]
       parameters:
         - $ref: "#/components/parameters/ProjectId"
@@ -225,6 +237,7 @@ paths:
   /v1/projects/{project_id}/environments/{environment_id}/operators/broadcasts/{broadcast_id}:
     get:
       operationId: getOperatorBroadcast
+      x-notification-scopes: [notifications:team]
       summary: getOperatorBroadcast
       description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
       tags: [Operators]
@@ -232,6 +245,7 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: [messages:read]
+        - bearerGrant: [notifications:team]
       x-required-scopes: [messages:read]
       parameters:
         - $ref: "#/components/parameters/ProjectId"
@@ -254,6 +268,7 @@ paths:
   /v1/projects/{project_id}/environments/{environment_id}/notification-preferences:
     get:
       operationId: getOperatorPreferences
+      x-notification-scopes: [notifications:self, notifications:team]
       summary: getOperatorPreferences
       description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
       tags: [Operators]
@@ -261,6 +276,8 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: [messages:read]
+        - bearerGrant: [notifications:self]
+        - bearerGrant: [notifications:team]
       x-required-scopes: [messages:read]
       parameters:
         - $ref: "#/components/parameters/ProjectId"
@@ -279,6 +296,7 @@ paths:
   /v1/projects/{project_id}/environments/{environment_id}/notification-preferences/preferred-binding:
     put:
       operationId: setOperatorPreferredBinding
+      x-notification-scopes: [notifications:self, notifications:team]
       summary: setOperatorPreferredBinding
       description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
       tags: [Operators]
@@ -286,6 +304,8 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: [messages:write]
+        - bearerGrant: [notifications:self]
+        - bearerGrant: [notifications:team]
       x-required-scopes: [messages:write]
       parameters:
         - $ref: "#/components/parameters/ProjectId"
@@ -310,6 +330,7 @@ paths:
   /v1/projects/{project_id}/environments/{environment_id}/notification-preferences/connect:
     post:
       operationId: connectOperatorChannel
+      x-notification-scopes: [notifications:self, notifications:team]
       summary: connectOperatorChannel
       description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
       tags: [Operators]
@@ -317,6 +338,8 @@ paths:
         - clerkSession: []
         - bearerCredential: []
         - bearerGrant: [messages:write]
+        - bearerGrant: [notifications:self]
+        - bearerGrant: [notifications:team]
       x-required-scopes: [messages:write]
       parameters:
         - $ref: "#/components/parameters/ProjectId"
@@ -412,6 +435,93 @@ paths:
           $ref: "#/components/responses/Conflict"
         "429":
           $ref: "#/components/responses/RateLimited"
+  /v1/billing/promotions:
+    get:
+      operationId: getBillingPromotions
+      summary: Read the organization's promotions
+      description: |
+        Organization administrators can read every promotion the organization holds: rewards WhooshBang gave it
+        and promotion codes it redeemed, with what remains and when each ends. Promotional value has no cash
+        value, is never refunded and cannot move to another organization.
+      tags: [Organization]
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+      x-required-scopes: [billing:read]
+      x-organization-membership: required
+      responses:
+        "200":
+          description: The organization's promotions, newest first.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingPromotions"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
+  /v1/billing/promotions/redeem:
+    post:
+      operationId: redeemBillingPromotion
+      summary: Redeem a promotion code
+      description: |
+        Organization administrators can redeem a promotion code for their own organization. Nothing is charged.
+        Every code that cannot be redeemed (mistyped, ended, fully used, not offered to this organization, or not
+        combinable with a promotion it already holds) receives the same `resource_not_found` answer. Repeated
+        refusals are rate limited per organization; wait for `Retry-After`. Reuse the same idempotency key after
+        an uncertain response: it can never redeem twice.
+      tags: [Organization]
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+      x-required-scopes: [billing:write]
+      x-organization-membership: required
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RedeemBillingPromotionRequest"
+      responses:
+        "200":
+          description: The same promotion, replayed for a repeated idempotency key.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingPromotion"
+        "201":
+          description: The promotion the code gave the organization.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BillingPromotion"
+        "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"
+        "429":
+          $ref: "#/components/responses/RateLimited"
   /v1/billing/auto-top-up:
     get:
       operationId: getAutoTopUpSettings
@@ -1961,6 +2071,7 @@ paths:
   /v1/projects:
     get:
       operationId: listProjects
+      x-notification-scopes: [notifications:self, notifications:team]
       summary: List projects in the current organization
       description: |
         Returns only projects owned by the organization selected by the verified
@@ -1971,6 +2082,8 @@ paths:
       security:
         - clerkSession: []
         - bearerGrant: []
+        - bearerGrant: [notifications:self]
+        - bearerGrant: [notifications:team]
         - bearerOrganizationCredential: []
       x-required-scopes:
         - projects:read
@@ -2064,6 +2177,7 @@ paths:
       - $ref: "#/components/parameters/ProjectId"
     get:
       operationId: getProject
+      x-notification-scopes: [notifications:self, notifications:team]
       summary: Read one project in the current organization
       description: |
         Returns the complete project bootstrap. An absent project and a project
@@ -2073,6 +2187,8 @@ paths:
       security:
         - clerkSession: []
         - bearerGrant: []
+        - bearerGrant: [notifications:self]
+        - bearerGrant: [notifications:team]
         - bearerOrganizationCredential: []
       x-required-scopes:
         - projects:read
@@ -8725,6 +8841,12 @@ components:
       $ref: "../schemas/whooshbang-v1.schema.json#/$defs/BillingProjectSlots"
     AssignBillingProjectSlotsRequest:
       $ref: "../schemas/whooshbang-v1.schema.json#/$defs/AssignBillingProjectSlotsRequest"
+    BillingPromotions:
+      $ref: "../schemas/whooshbang-v1.schema.json#/$defs/BillingPromotions"
+    BillingPromotion:
+      $ref: "../schemas/whooshbang-v1.schema.json#/$defs/BillingPromotion"
+    RedeemBillingPromotionRequest:
+      $ref: "../schemas/whooshbang-v1.schema.json#/$defs/RedeemBillingPromotionRequest"
     BillingEntitlements:
       $ref: "../schemas/whooshbang-v1.schema.json#/$defs/BillingEntitlements"
     SubscriptionSelection:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whooshbang/contracts",
-  "version": "2.3.0",
+  "version": "2.5.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.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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": "2.3.0",
+  "x-contract-version": "2.5.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",