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

package/openapi/generated/whooshbang-v1.bundle.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.1",
   "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\nsubscription links, and asynchronous text messages. A Clerk session selects\none account for administration. A project credential selects one account,\nproject, and `test` or `live` environment for product operations; request\nbodies cannot override either authenticated scope.\n\nA person's OAuth grant selects one account and carries scopes, but no\nproject. It names the project and environment it acts in through the URL\npath, on the environment-scoped form of each operation; the service checks\nthat path against the granting person's membership on every call. The flat\nforms remain credential-only and are unchanged.\n\nResource identifiers are opaque and are not authorization. Reads outside the\ncredential scope return the same `404` shape as absent resources. Provider\ncredentials, raw Telegram identity, and protected provider responses are\nnever part of this API.\n",
     "termsOfService": "https://flowxo.com/terms",
     "contact": {
@@ -123,6 +123,51 @@
         }
       }
     },
+    "/v1/account/close": {
+      "post": {
+        "operationId": "closeAccount",
+        "summary": "Close the current customer account",
+        "description": "Terminally closes the account selected by the verified Clerk\norganization session. Only an administrator may close it. OAuth grants\nand API credentials are deliberately excluded: delegated authority must\nnot be able to erase the account that granted it.\n\nThe request requires the exact confirmation `close-account`. Repeating a\ncompleted closure is safe and returns the original `closed_at`. The\nresult names provider-owned resources the administrator must still retire\noutside WhooshBang, such as revoking a customer-managed Telegram bot token\nin BotFather; no provider credential is returned.\n",
+        "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",
@@ -475,7 +520,8 @@
                           ],
                           "created_at": "2026-07-28T12:05:00Z",
                           "updated_at": "2026-07-28T12:05:00Z",
-                          "diagnostic_id": "diag_project_synthetic_001"
+                          "diagnostic_id": "diag_project_synthetic_001",
+                          "privacy_mode": "minimal"
                         }
                       ],
                       "page": 1,
@@ -576,7 +622,8 @@
                       ],
                       "created_at": "2026-07-28T12:05:00Z",
                       "updated_at": "2026-07-28T12:05:00Z",
-                      "diagnostic_id": "diag_project_synthetic_001"
+                      "diagnostic_id": "diag_project_synthetic_001",
+                      "privacy_mode": "minimal"
                     }
                   }
                 }
@@ -655,7 +702,8 @@
                       ],
                       "created_at": "2026-07-28T12:05:00Z",
                       "updated_at": "2026-07-28T12:05:00Z",
-                      "diagnostic_id": "diag_project_synthetic_001"
+                      "diagnostic_id": "diag_project_synthetic_001",
+                      "privacy_mode": "minimal"
                     }
                   }
                 }
@@ -667,6 +715,51 @@
           "404": { "$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\ndefault for new and existing projects. standard permits messenger profiles;\nminimal keeps recipient language only; private keeps delivery routing and\nthe customer-supplied subscriber identifier, with no profile data.\nMoving standard to minimal erases existing identifying profile fields.\nMoving to private also erases recipient language. Increasing collection\ndoes not restore erased data. The operation is naturally idempotent.\nAn absent project and one outside the account return the same 404.\n",
+        "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": { "value": { "privacy_mode": "private" } }
+              }
+            }
+          }
+        },
+        "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": {
@@ -1469,7 +1562,7 @@
       "post": {
         "operationId": "createMessage",
         "summary": "Create an asynchronous message",
-        "description": "Durably accepts one logical text message for one subscriber and one\nresolved channel binding. `202` proves API acceptance only; it does not\nclaim provider acceptance or end-device delivery.\n",
+        "description": "Durably accepts one logical text message for one subscriber and one\nresolved channel binding. `202` proves API acceptance only; it does not\nclaim provider acceptance or end-device delivery.\nThe reserved `test:` subscriber prefix and `delivery_target: simulator`\nare test-environment-only. Live sends are refused before acceptance or\nidempotent replay with `400 request_invalid`; reserved subscriber IDs\ncarry a field error at `/to/subscriber_id`.\n",
         "tags": ["Messages"],
         "security": [{ "bearerCredential": [] }, { "machineCredential": [] }],
         "x-required-scopes": ["messages:write"],
@@ -2010,7 +2103,7 @@
       "post": {
         "operationId": "createMachineClient",
         "summary": "Create a destination-bound machine client",
-        "description": "Creates one machine client in the project/environment selected by the\nproject credential. The notifier, subscriber, and active binding become\nimmutable authorization bounds. The response never contains a readable\nsecret or digest.\n",
+        "description": "Creates one machine client in the project/environment selected by the\nproject credential. The notifier, subscriber, and active binding become\nimmutable authorization bounds. The response never contains a readable\nsecret or digest.\nLive environments reject the reserved `test:` subscriber prefix with\n`400 request_invalid` and a field error at `/subscriber_id` before creation.\n",
         "tags": ["Machine clients"],
         "security": [{ "bearerCredential": [] }],
         "x-required-scopes": ["machine-clients:write"],
@@ -6692,6 +6785,97 @@
         }
       }
     },
+    "/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\nacross both project environments. Personal content, answers, identities,\nand identifiers are removed while non-identifying delivery and usage\nshells remain. Pending work and old capabilities cannot restore or send\ndata for the erased person.\n\nRepeating the operation is safe, including when the subscriber is already\nabsent. Project-environment credentials cannot call this project-wide\noperation. A provider action that has already begun returns\n`privacy_operation_in_progress` rather than claiming erasure won the race;\nretry after that operation finishes.\n",
+        "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\nin the project. `provided_by_subscriber` is the Article 20 portable subset;\nthe three provenance sections together provide the Article 15 access copy.\nWhooshBang-controller audit and service log data is identified as excluded\nand requires a separate recipient request. Project-environment credentials\ncannot call this project-wide operation.\n",
+        "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" },
@@ -8328,6 +8512,20 @@
         },
         "additionalProperties": false
       },
+      "UpdateProjectRequest": {
+        "type": "object",
+        "description": "Sets the project privacy policy. Moving from standard to minimal erases stored identifying profile data; moving to private also erases recipient language. Increasing collection does not restore erased data.",
+        "required": ["privacy_mode"],
+        "properties": {
+          "privacy_mode": { "$ref": "#/components/schemas/PrivacyMode" }
+        },
+        "additionalProperties": false
+      },
+      "PrivacyMode": {
+        "type": "string",
+        "enum": ["minimal", "standard", "private"],
+        "description": "Project profile collection policy. minimal (the default for new and existing projects) keeps recipient language only; standard permits messenger profile data; private retains delivery routing and the customer-supplied subscriber identifier, with no profile data. Lowering collection erases existing fields the new mode disallows."
+      },
       "CreateProjectRequest": {
         "type": "object",
         "description": "Creates one project inside the account selected by the authenticated human session.",
@@ -8344,6 +8542,10 @@
             "$ref": "#/components/schemas/RecipientLanguage",
             "default": "en",
             "description": "The application fallback locale for recipient-owned surfaces when no session, subscriber, or supported provider locale is available."
+          },
+          "privacy_mode": {
+            "$ref": "#/components/schemas/PrivacyMode",
+            "default": "minimal"
           }
         },
         "additionalProperties": false
@@ -8395,7 +8597,8 @@
           "environments",
           "created_at",
           "updated_at",
-          "diagnostic_id"
+          "diagnostic_id",
+          "privacy_mode"
         ],
         "properties": {
           "id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
@@ -8420,7 +8623,8 @@
           },
           "created_at": { "$ref": "#/components/schemas/Timestamp" },
           "updated_at": { "$ref": "#/components/schemas/Timestamp" },
-          "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" }
+          "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" },
+          "privacy_mode": { "$ref": "#/components/schemas/PrivacyMode" }
         },
         "additionalProperties": false
       },
@@ -9284,7 +9488,7 @@
           },
           "delivery_target": {
             "$ref": "#/components/schemas/MessageDeliveryTarget",
-            "description": "Optional routing override. Omit for notifier-default connection delivery, except reserved simulator destinations retained for compatibility."
+            "description": "Optional routing override. Simulator delivery and the reserved test: subscriber prefix are test-environment-only; live requests are refused with 400 request_invalid. Omit for notifier-default connection delivery or the reserved test-environment simulator default."
           },
           "connection_id": {
             "allOf": [{ "$ref": "#/components/schemas/OpaqueIdentifier" }],
@@ -9824,6 +10028,18 @@
               "retryable": { "const": false }
             }
           },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "const": "https://whooshbang.flowxo.com/problems/privacy_operation_in_progress"
+              },
+              "title": { "const": "Privacy operation in progress" },
+              "status": { "const": 409 },
+              "code": { "const": "privacy_operation_in_progress" },
+              "retryable": { "const": true }
+            }
+          },
           {
             "type": "object",
             "properties": {
@@ -10962,6 +11178,92 @@
         },
         "additionalProperties": false
       },
+      "SubscriberDataExport": {
+        "type": "object",
+        "description": "A complete customer-controller access artifact for one subscriber across every environment in one project. provided_by_subscriber is the Article 20 portable subset; all three record groups together are the Article 15 access copy. WhooshBang-controller records are named but never mixed into the customer export.",
+        "required": [
+          "format",
+          "generated_at",
+          "controller_scope",
+          "project_id",
+          "environment_ids",
+          "subscriber_id",
+          "provided_by_subscriber",
+          "provided_by_customer",
+          "derived_by_service",
+          "excluded_controller_data"
+        ],
+        "properties": {
+          "format": {
+            "type": "string",
+            "const": "whooshbang.subscriber-data-export.v1"
+          },
+          "generated_at": { "$ref": "#/components/schemas/Timestamp" },
+          "controller_scope": { "type": "string", "const": "customer" },
+          "project_id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
+          "environment_ids": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "$ref": "#/components/schemas/OpaqueIdentifier" }
+          },
+          "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
+          "provided_by_subscriber": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SubscriberDataExportRecord"
+            }
+          },
+          "provided_by_customer": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SubscriberDataExportRecord"
+            }
+          },
+          "derived_by_service": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SubscriberDataExportRecord"
+            }
+          },
+          "excluded_controller_data": {
+            "type": "array",
+            "minItems": 2,
+            "maxItems": 2,
+            "uniqueItems": true,
+            "items": {
+              "$ref": "#/components/schemas/SubscriberDataExportExcludedControllerData"
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "CloseAccountRequest": {
+        "type": "object",
+        "description": "Exact, explicit confirmation that the current account administrator intends to close the whole account.",
+        "required": ["confirmation"],
+        "properties": {
+          "confirmation": { "type": "string", "const": "close-account" }
+        },
+        "additionalProperties": false
+      },
+      "AccountClosureResult": {
+        "type": "object",
+        "description": "Terminal account-closure result. Repeating closure returns the same closed_at and any provider-owned resources that still require manual retirement.",
+        "required": ["status", "closed_at", "provider_actions_required"],
+        "properties": {
+          "status": { "type": "string", "const": "closed" },
+          "closed_at": { "$ref": "#/components/schemas/Timestamp" },
+          "provider_actions_required": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "$ref": "#/components/schemas/AccountClosureProviderAction"
+            }
+          }
+        },
+        "additionalProperties": false
+      },
       "CreateRecipientGroupRequest": {
         "type": "object",
         "description": "Creates one static, developer-managed recipient group.",
@@ -11219,6 +11521,7 @@
           "environment_mismatch",
           "idempotency_key_required",
           "idempotency_conflict",
+          "privacy_operation_in_progress",
           "project_slug_conflict",
           "request_invalid",
           "replay_unavailable",
@@ -11355,6 +11658,20 @@
           }
         ]
       },
+      "AccountClosureProviderAction": {
+        "type": "object",
+        "description": "One provider-owned resource the customer must retire outside WhooshBang after account closure. It contains safe identifiers only, never provider credentials.",
+        "required": ["provider", "action", "connection_id"],
+        "properties": {
+          "provider": { "type": "string", "enum": ["telegram", "slack"] },
+          "action": {
+            "type": "string",
+            "enum": ["revoke_bot_token", "delete_provider_application"]
+          },
+          "connection_id": { "$ref": "#/components/schemas/OpaqueIdentifier" }
+        },
+        "additionalProperties": false
+      },
       "AccountCredentialPrefix": {
         "type": "string",
         "pattern": "^wb_ac1\\.acred_[A-Za-z0-9_-]{8}$",
@@ -12783,7 +13100,7 @@
       "provider-capabilities-v1.schema": {
         "$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",
@@ -12986,6 +13303,38 @@
           }
         },
         "additionalProperties": false
+      },
+      "SubscriberDataExportRecord": {
+        "type": "object",
+        "description": "One semantic record held about the subscriber. The source names the durable store or recovered semantic value; data contains plaintext business fields and excludes custody metadata and secrets.",
+        "required": ["source", "data"],
+        "properties": {
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 96,
+            "pattern": "^[a-z][a-z0-9_.-]*$"
+          },
+          "data": { "type": "object", "additionalProperties": true }
+        },
+        "additionalProperties": false
+      },
+      "SubscriberDataExportExcludedControllerData": {
+        "type": "object",
+        "description": "A category deliberately outside the customer-controller artifact because WhooshBang is controller for it.",
+        "required": ["category", "controller", "access"],
+        "properties": {
+          "category": {
+            "type": "string",
+            "enum": ["consent_lifecycle_audit", "service_logs"]
+          },
+          "controller": { "type": "string", "const": "whooshbang" },
+          "access": {
+            "type": "string",
+            "const": "separate_recipient_request_required"
+          }
+        },
+        "additionalProperties": false
       }
     },
     "responses": {
@@ -13435,5 +13784,5 @@
       }
     }
   },
-  "x-contract-version": "1.0.0-rc.21"
+  "x-contract-version": "1.0.0-rc.22"
 }