@whooshbang/contracts 1.0.0-rc.21 → 1.0.0-rc.22

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: 1.0.0-rc.21
+x-contract-version: 1.0.0-rc.22
 info:
   title: WhooshBang API
-  version: 1.0.0-rc.21
+  version: 1.0.0-rc.22
   description: |
     The V1 contract for human account/project administration, project-scoped
     subscription links, and asynchronous text messages. A Clerk session selects
@@ -99,6 +99,56 @@ paths:
           $ref: "#/components/responses/Forbidden"
         "429":
           $ref: "#/components/responses/RateLimited"
+  /v1/account/close:
+    post:
+      operationId: closeAccount
+      summary: Close the current customer account
+      description: |
+        Terminally closes the account selected by the verified Clerk
+        organization session. Only an administrator may close it. OAuth grants
+        and API credentials are deliberately excluded: delegated authority must
+        not be able to erase the account that granted it.
+
+        The request requires the exact confirmation `close-account`. Repeating a
+        completed closure is safe and returns the original `closed_at`. The
+        result names provider-owned resources the administrator must still retire
+        outside WhooshBang, such as revoking a customer-managed Telegram bot token
+        in BotFather; no provider credential is returned.
+      tags:
+        - Account
+      security:
+        - clerkSession: []
+      x-account-membership: required
+      x-required-membership-role: admin
+      x-repeat-semantics:
+        same_target: idempotent
+        secret_returned: false
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CloseAccountRequest"
+      responses:
+        "200":
+          description: The account is closed, with any manual provider retirement still required.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccountClosureResult"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "409":
+          $ref: "#/components/responses/Conflict"
+        "429":
+          $ref: "#/components/responses/RateLimited"
   /v1/account/credentials:
     get:
       operationId: listAccountCredentials
@@ -426,6 +476,57 @@ paths:
           $ref: "#/components/responses/NotFound"
         "429":
           $ref: "#/components/responses/RateLimited"
+    patch:
+      operationId: updateProject
+      summary: Set a project's privacy policy
+      description: |
+        Changes profile collection for both project environments. minimal is the
+        default for new and existing projects. standard permits messenger profiles;
+        minimal keeps recipient language only; private keeps delivery routing and
+        the customer-supplied subscriber identifier, with no profile data.
+        Moving standard to minimal erases existing identifying profile fields.
+        Moving to private also erases recipient language. Increasing collection
+        does not restore erased data. The operation is naturally idempotent.
+        An absent project and one outside the account return the same 404.
+      tags:
+        - Projects
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+        - bearerCredential: []
+        - bearerAccountCredential: []
+      x-required-scopes:
+        - projects:write
+      x-account-membership: required
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateProjectRequest"
+            examples:
+              updateProject:
+                externalValue: ../fixtures/core-v1/requests/update-project.json
+      responses:
+        "200":
+          description: The project after changing its privacy policy and clearing disallowed profile fields.
+          headers:
+            WhooshBang-Diagnostic-Id:
+              $ref: "#/components/headers/DiagnosticId"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Project"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "429":
+          $ref: "#/components/responses/RateLimited"
   /v1/projects/{project_id}/recipient-copy-overrides:
     parameters:
       - $ref: "#/components/parameters/ProjectId"
@@ -1021,6 +1122,10 @@ paths:
         Durably accepts one logical text message for one subscriber and one
         resolved channel binding. `202` proves API acceptance only; it does not
         claim provider acceptance or end-device delivery.
+        The reserved `test:` subscriber prefix and `delivery_target: simulator`
+        are test-environment-only. Live sends are refused before acceptance or
+        idempotent replay with `400 request_invalid`; reserved subscriber IDs
+        carry a field error at `/to/subscriber_id`.
       tags:
         - Messages
       security:
@@ -1276,6 +1381,8 @@ paths:
         project credential. The notifier, subscriber, and active binding become
         immutable authorization bounds. The response never contains a readable
         secret or digest.
+        Live environments reject the reserved `test:` subscriber prefix with
+        `400 request_invalid` and a field error at `/subscriber_id` before creation.
       tags:
         - Machine clients
       security:
@@ -4740,6 +4847,103 @@ paths:
           $ref: "#/components/responses/Forbidden"
         "404":
           $ref: "#/components/responses/NotFound"
+  /v1/projects/{project_id}/subscribers/{subscriber_id}:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - name: subscriber_id
+        in: path
+        required: true
+        schema:
+          $ref: "#/components/schemas/OpaqueIdentifier"
+    delete:
+      operationId: eraseSubscriber
+      summary: Erase one subscriber across the project
+      description: |
+        Erases the person represented by this customer-supplied subscriber id
+        across both project environments. Personal content, answers, identities,
+        and identifiers are removed while non-identifying delivery and usage
+        shells remain. Pending work and old capabilities cannot restore or send
+        data for the erased person.
+
+        Repeating the operation is safe, including when the subscriber is already
+        absent. Project-environment credentials cannot call this project-wide
+        operation. A provider action that has already begun returns
+        `privacy_operation_in_progress` rather than claiming erasure won the race;
+        retry after that operation finishes.
+      tags:
+        - Subscribers
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+        - bearerAccountCredential: []
+      x-required-scopes:
+        - subscriptions:write
+        - messages:write
+        - machine-clients:write
+      x-account-membership: required
+      x-repeat-semantics:
+        same_target: idempotent
+        secret_returned: false
+      responses:
+        "204":
+          description: The subscriber's personal data is erased or was already absent.
+        "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/projects/{project_id}/subscribers/{subscriber_id}/data-export:
+    parameters:
+      - $ref: "#/components/parameters/ProjectId"
+      - name: subscriber_id
+        in: path
+        required: true
+        schema:
+          $ref: "#/components/schemas/OpaqueIdentifier"
+    get:
+      operationId: getSubscriberDataExport
+      summary: Export all customer-controlled data held for one subscriber
+      description: |
+        Returns one complete, machine-readable artifact across every environment
+        in the project. `provided_by_subscriber` is the Article 20 portable subset;
+        the three provenance sections together provide the Article 15 access copy.
+        WhooshBang-controller audit and service log data is identified as excluded
+        and requires a separate recipient request. Project-environment credentials
+        cannot call this project-wide operation.
+      tags:
+        - Subscribers
+      security:
+        - clerkSession: []
+        - bearerGrant: []
+        - bearerAccountCredential: []
+      x-required-scopes:
+        - subscriptions:read
+        - messages:read
+        - machine-clients:read
+      x-account-membership: required
+      responses:
+        "200":
+          description: Complete project-wide customer-controller subscriber data export.
+          headers:
+            Content-Disposition:
+              schema:
+                type: string
+              description: Fixed safe attachment filename.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriberDataExport"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /v1/projects/{project_id}/environments/{environment_id}/recipient-groups:
     parameters:
       - $ref: "#/components/parameters/ProjectId"
@@ -5577,6 +5781,10 @@ components:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/IdempotencyKey
     AccountProjection:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/AccountProjection
+    UpdateProjectRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/UpdateProjectRequest
+    PrivacyMode:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/PrivacyMode
     CreateProjectRequest:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateProjectRequest
     DefaultNotifierSummary:
@@ -5725,6 +5933,12 @@ components:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateSubscriberRequest
     Subscriber:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/Subscriber
+    SubscriberDataExport:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/SubscriberDataExport
+    CloseAccountRequest:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CloseAccountRequest
+    AccountClosureResult:
+      $ref: ../schemas/whooshbang-v1.schema.json#/$defs/AccountClosureResult
     CreateRecipientGroupRequest:
       $ref: ../schemas/whooshbang-v1.schema.json#/$defs/CreateRecipientGroupRequest
     UpdateRecipientGroupRequest:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whooshbang/contracts",
-  "version": "1.0.0-rc.21",
+  "version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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": "1.0.0-rc.21",
+  "x-contract-version": "1.0.0-rc.22",
   "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",