@whooshbang/contracts 2.0.0-rc.8 → 2.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.0.0-rc.8
+x-contract-version: 2.1.0
 info:
   title: WhooshBang API
-  version: 2.0.0-rc.8
+  version: 2.1.0
   description: |
     The V1 contract for human organization/project administration, project-scoped
     subscription links, and asynchronous text messages. A Clerk session selects
@@ -67,9 +67,278 @@ tags:
     description: Application-owned subscriber identity and transactional initial static-group membership.
   - name: Subscriber groups
     description: Environment-scoped static groups and monotonic membership generations.
+  - name: Operators
+    description: Current teammates, personal notification preferences and membership-derived service email.
   - name: Group broadcasts
     description: Durable group acceptance and aggregate projection over ordinary child messages.
 paths:
+  /v1/projects/{project_id}/environments/{environment_id}/whoami:
+    get:
+      operationId: whoAmI
+      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]
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerOrganizationCredential: []
+        - bearerGrant: [messages:read]
+        - machineCredential: []
+      x-required-scopes: [messages:read]
+      parameters:
+        - $ref: "#/components/parameters/ProjectId"
+        - $ref: "#/components/parameters/EnvironmentId"
+      responses:
+        "200":
+          description: Actual principal and safe authorized messaging context.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WhoAmI"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/projects/{project_id}/environments/{environment_id}/operators:
+    get:
+      operationId: listOperators
+      summary: listOperators
+      description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
+      tags: [Operators]
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: [messages:read]
+      x-required-scopes: [messages:read]
+      parameters:
+        - $ref: "#/components/parameters/ProjectId"
+        - $ref: "#/components/parameters/EnvironmentId"
+        - $ref: "#/components/parameters/ListAfterCursor"
+        - $ref: "#/components/parameters/ListPageLimit"
+        - $ref: "#/components/parameters/PageNumber"
+      responses:
+        "200":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OperatorCollection"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/projects/{project_id}/environments/{environment_id}/operators/resolve:
+    get:
+      operationId: resolveOperator
+      summary: resolveOperator
+      description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
+      tags: [Operators]
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: [messages:read]
+      x-required-scopes: [messages:read]
+      parameters:
+        - $ref: "#/components/parameters/ProjectId"
+        - $ref: "#/components/parameters/EnvironmentId"
+        - name: recipient
+          in: query
+          required: true
+          schema: { type: string, minLength: 1, maxLength: 128 }
+      responses:
+        "200":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OperatorResolution"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/projects/{project_id}/environments/{environment_id}/operator-messages:
+    post:
+      operationId: sendOperatorMessage
+      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]
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerOrganizationCredential: []
+        - machineCredential: []
+        - bearerGrant: [messages:write]
+      x-required-scopes: [messages:write]
+      parameters:
+        - $ref: "#/components/parameters/ProjectId"
+        - $ref: "#/components/parameters/EnvironmentId"
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateOperatorMessageRequest"
+      responses:
+        "200":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OperatorMessageResult"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/projects/{project_id}/environments/{environment_id}/operators/broadcasts:
+    post:
+      operationId: broadcastOperators
+      summary: broadcastOperators
+      description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
+      tags: [Operators]
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: [messages:write]
+      x-required-scopes: [messages:write]
+      parameters:
+        - $ref: "#/components/parameters/ProjectId"
+        - $ref: "#/components/parameters/EnvironmentId"
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateGroupBroadcastRequest"
+      responses:
+        "200":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OperatorBroadcast"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/projects/{project_id}/environments/{environment_id}/operators/broadcasts/{broadcast_id}:
+    get:
+      operationId: getOperatorBroadcast
+      summary: getOperatorBroadcast
+      description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
+      tags: [Operators]
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: [messages:read]
+      x-required-scopes: [messages:read]
+      parameters:
+        - $ref: "#/components/parameters/ProjectId"
+        - $ref: "#/components/parameters/EnvironmentId"
+        - name: broadcast_id
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OperatorBroadcast"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/projects/{project_id}/environments/{environment_id}/notification-preferences:
+    get:
+      operationId: getOperatorPreferences
+      summary: getOperatorPreferences
+      description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
+      tags: [Operators]
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: [messages:read]
+      x-required-scopes: [messages:read]
+      parameters:
+        - $ref: "#/components/parameters/ProjectId"
+        - $ref: "#/components/parameters/EnvironmentId"
+      responses:
+        "200":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OperatorPreferences"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/projects/{project_id}/environments/{environment_id}/notification-preferences/preferred-binding:
+    put:
+      operationId: setOperatorPreferredBinding
+      summary: setOperatorPreferredBinding
+      description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
+      tags: [Operators]
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: [messages:write]
+      x-required-scopes: [messages:write]
+      parameters:
+        - $ref: "#/components/parameters/ProjectId"
+        - $ref: "#/components/parameters/EnvironmentId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SetPreferredBindingRequest"
+      responses:
+        "200":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OperatorPreferences"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+  /v1/projects/{project_id}/environments/{environment_id}/notification-preferences/connect:
+    post:
+      operationId: connectOperatorChannel
+      summary: connectOperatorChannel
+      description: Membership-derived operator messaging. Only the authenticated human can manage personal preferences.
+      tags: [Operators]
+      security:
+        - clerkSession: []
+        - bearerCredential: []
+        - bearerGrant: [messages:write]
+      x-required-scopes: [messages:write]
+      parameters:
+        - $ref: "#/components/parameters/ProjectId"
+        - $ref: "#/components/parameters/EnvironmentId"
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OperatorConnectRequest"
+      responses:
+        "201":
+          description: Authorized result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriptionLink"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /v1/billing/project-slots:
     get:
       operationId: getBillingProjectSlots
@@ -8332,6 +8601,26 @@ components:
       schema:
         $ref: "#/components/schemas/DiagnosticId"
   schemas:
+    WhoAmI:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/WhoAmI
+    Operator:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/Operator
+    OperatorCollection:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/OperatorCollection
+    OperatorResolution:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/OperatorResolution
+    CreateOperatorMessageRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateOperatorMessageRequest
+    OperatorMessageResult:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/OperatorMessageResult
+    OperatorBroadcastRecipient:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/OperatorBroadcastRecipient
+    OperatorBroadcast:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/OperatorBroadcast
+    OperatorPreferences:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/OperatorPreferences
+    OperatorConnectRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/OperatorConnectRequest
     ListPageSize:
       $ref: "../schemas/whooshbang-v1.schema.json#/$defs/ListPageSize"
     MessageState:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whooshbang/contracts",
-  "version": "2.0.0-rc.8",
+  "version": "2.1.0",
   "description": "Versioned public contracts for WhooshBang",
   "private": false,
   "license": "MIT",
@@ -20,7 +20,7 @@
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "next"
+    "tag": "latest"
   },
   "files": [
     "CHANGELOG.md",
@@ -53,7 +53,6 @@
     "check": "npm run build && tsx scripts/check.ts",
     "generate": "tsx scripts/generate.ts",
     "lint": "eslint src scripts test --max-warnings=0",
-    "pack:verified": "npm run check && tsx scripts/pack.ts",
     "test": "vitest run --no-file-parallelism",
     "type-check": "tsc --noEmit -p tsconfig.json"
   },

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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.0",
   "title": "InteractionV1ContractDocument",
   "description": "Provider-neutral confirm, single-select, input, lifecycle, callback-token, and authenticated answer-event contracts.",
   "oneOf": [

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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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.0.0-rc.8",
+  "x-contract-version": "2.1.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",