@whooshbang/contracts 3.1.0 → 3.3.0

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

@@ -2,7 +2,7 @@
   "openapi": "3.1.1",
   "info": {
     "title": "WhooshBang API",
-    "version": "3.1.0",
+    "version": "3.3.0",
     "description": "The V1 contract for human organization/project administration, project-scoped\nsubscription links, and asynchronous text messages. A Clerk session selects\none organization for administration. A project credential selects one organization,\nproject, and `test` or `live` environment for product operations; request\nbodies cannot override either authenticated scope.\n\nA person's OAuth grant selects one organization 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": {
@@ -52,6 +52,10 @@
       "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."
@@ -94,6 +98,218 @@
     }
   ],
   "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",
@@ -6692,6 +6908,8 @@
                         "accent_color": "#4F46E5",
                         "color_scheme": "system"
                       },
+                      "show_service_category_switches": true,
+                      "show_marketing_category_switches": true,
                       "row_version": 2,
                       "updated_at": "2026-08-22T18:00:00Z",
                       "diagnostic_id": "diag_n17_project_experience"
@@ -7276,6 +7494,75 @@
         }
       }
     },
+    "/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": [
         {
@@ -8663,7 +8950,7 @@
       "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": [] },
@@ -8697,6 +8984,13 @@
             "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",
@@ -8715,6 +9009,20 @@
             "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",
@@ -11692,6 +12000,133 @@
       }
     },
     "schemas": {
+      "MessageCategoryKey": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+        "minLength": 1,
+        "maxLength": 63
+      },
+      "MessageCategory": {
+        "type": "object",
+        "description": "One project-owned category. Its key stays stable when settings change.",
+        "required": [
+          "key",
+          "name",
+          "description",
+          "purpose",
+          "level",
+          "can_turn_off",
+          "is_default"
+        ],
+        "properties": {
+          "key": { "$ref": "#/components/schemas/MessageCategoryKey" },
+          "name": { "type": "string", "minLength": 1, "maxLength": 100 },
+          "description": { "type": "string", "minLength": 1, "maxLength": 160 },
+          "purpose": { "enum": ["service", "marketing"] },
+          "level": { "enum": ["low", "normal", "high", "critical"] },
+          "can_turn_off": { "type": "boolean" },
+          "is_default": { "type": "boolean" },
+          "opted_out_subscriber_count": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Number of subscribers in this project who currently have this category switched off. Returned when listing a project's categories."
+          },
+          "archived_at": {
+            "$ref": "#/components/schemas/Timestamp",
+            "description": "Present only when this category has been archived. Historical messages retain their acceptance-time category snapshot."
+          }
+        },
+        "additionalProperties": false
+      },
+      "MessageCategoryCollection": {
+        "type": "object",
+        "required": ["items", "total"],
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": { "$ref": "#/components/schemas/MessageCategory" }
+          },
+          "total": { "$ref": "#/components/schemas/ListTotal" }
+        },
+        "additionalProperties": false
+      },
+      "CreateMessageCategoryRequest": {
+        "type": "object",
+        "required": [
+          "key",
+          "name",
+          "description",
+          "purpose",
+          "level",
+          "can_turn_off"
+        ],
+        "properties": {
+          "key": { "$ref": "#/components/schemas/MessageCategoryKey" },
+          "name": { "type": "string", "minLength": 1, "maxLength": 100 },
+          "description": { "type": "string", "minLength": 1, "maxLength": 160 },
+          "purpose": { "enum": ["service", "marketing"] },
+          "level": { "enum": ["low", "normal", "high", "critical"] },
+          "can_turn_off": { "type": "boolean" }
+        },
+        "additionalProperties": false
+      },
+      "UpdateMessageCategoryRequest": {
+        "type": "object",
+        "minProperties": 1,
+        "properties": {
+          "name": { "type": "string", "minLength": 1, "maxLength": 100 },
+          "description": { "type": "string", "minLength": 1, "maxLength": 160 },
+          "purpose": { "enum": ["service", "marketing"] },
+          "level": { "enum": ["low", "normal", "high", "critical"] },
+          "can_turn_off": { "type": "boolean" }
+        },
+        "additionalProperties": false
+      },
+      "SubscriberCategoryPreference": {
+        "type": "object",
+        "required": [
+          "key",
+          "name",
+          "description",
+          "purpose",
+          "level",
+          "can_turn_off",
+          "is_default",
+          "enabled"
+        ],
+        "properties": {
+          "key": { "$ref": "#/components/schemas/MessageCategoryKey" },
+          "name": { "type": "string", "minLength": 1, "maxLength": 100 },
+          "description": { "type": "string", "minLength": 1, "maxLength": 160 },
+          "purpose": { "enum": ["service", "marketing"] },
+          "level": { "enum": ["low", "normal", "high", "critical"] },
+          "can_turn_off": { "type": "boolean" },
+          "is_default": { "type": "boolean" },
+          "enabled": { "type": "boolean" }
+        },
+        "additionalProperties": false
+      },
+      "SubscriberCategoryPreferenceCollection": {
+        "type": "object",
+        "required": ["items", "total"],
+        "properties": {
+          "items": {
+            "type": "array",
+            "maxItems": 100,
+            "items": {
+              "$ref": "#/components/schemas/SubscriberCategoryPreference"
+            }
+          },
+          "total": { "$ref": "#/components/schemas/ListTotal" }
+        },
+        "additionalProperties": false
+      },
+      "SetSubscriberCategoryPreferenceRequest": {
+        "type": "object",
+        "required": ["enabled"],
+        "properties": { "enabled": { "type": "boolean" } },
+        "additionalProperties": false
+      },
       "WhoAmI": {
         "type": "object",
         "description": "Current principal, authorized context, safe channel readiness and deterministic personal me identity. Contains no email or provider destination.",
@@ -11848,6 +12283,10 @@
             "enum": ["service", "marketing"],
             "default": "service",
             "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
+          },
+          "category_key": {
+            "$ref": "#/components/schemas/MessageCategoryKey",
+            "description": "Optional project category. Omitted service sends use Updates; omitted marketing sends use Marketing."
           }
         },
         "additionalProperties": false,
@@ -12052,6 +12491,10 @@
           "environment": { "$ref": "#/components/schemas/Environment" },
           "id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
           "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
+          "category": {
+            "$ref": "#/components/schemas/MessageCategorySnapshot",
+            "description": "Category as accepted. Absent on messages accepted before categories existed."
+          },
           "state": { "$ref": "#/components/schemas/MessageState" },
           "subscriber_id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
           "updated_at": { "$ref": "#/components/schemas/Timestamp" },
@@ -16507,6 +16950,10 @@
             "enum": ["service", "marketing"],
             "default": "service",
             "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
+          },
+          "category_key": {
+            "$ref": "#/components/schemas/MessageCategoryKey",
+            "description": "Optional project category. Omitted service sends use Updates; omitted marketing sends use Marketing."
           }
         },
         "allOf": [
@@ -16620,6 +17067,10 @@
             "description": "What to call the subscriber, resolved as on the subscriber's `name`: your display name, otherwise the channel's own name where the privacy setting keeps it. Absent when there is neither."
           },
           "notifier_id": { "$ref": "#/components/schemas/OpaqueIdentifier" },
+          "category": {
+            "$ref": "#/components/schemas/MessageCategorySnapshot",
+            "description": "Category as accepted. Absent on messages accepted before categories existed."
+          },
           "binding": { "$ref": "#/components/schemas/BindingSummary" },
           "binding_resolution": {
             "type": "string",
@@ -16862,7 +17313,6 @@
                       "type": "object",
                       "required": ["classified_error"],
                       "properties": {
-                        "attempt_count": { "type": "integer", "minimum": 1 },
                         "classified_error": {
                           "allOf": [
                             { "$ref": "#/components/schemas/ClassifiedError" },
@@ -16872,7 +17322,8 @@
                                 "code": {
                                   "enum": [
                                     "provider_terminal",
-                                    "not_consented_for_marketing"
+                                    "not_consented_for_marketing",
+                                    "category_turned_off"
                                   ]
                                 },
                                 "retryable": { "const": false }
@@ -16880,7 +17331,32 @@
                             }
                           ]
                         }
-                      }
+                      },
+                      "allOf": [
+                        {
+                          "if": {
+                            "type": "object",
+                            "properties": {
+                              "classified_error": {
+                                "type": "object",
+                                "properties": {
+                                  "code": { "const": "provider_terminal" }
+                                },
+                                "required": ["code"]
+                              }
+                            },
+                            "required": ["classified_error"]
+                          },
+                          "then": {
+                            "properties": {
+                              "attempt_count": {
+                                "type": "integer",
+                                "minimum": 1
+                              }
+                            }
+                          }
+                        }
+                      ]
                     }
                   ]
                 }
@@ -17383,6 +17859,54 @@
               "code": { "const": "not_consented_for_marketing" },
               "retryable": { "const": false }
             }
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "const": "https://whooshbang.flowxo.com/problems/category_not_found"
+              },
+              "title": { "const": "Message category not found" },
+              "status": { "const": 404 },
+              "code": { "const": "category_not_found" },
+              "retryable": { "const": false }
+            }
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "const": "https://whooshbang.flowxo.com/problems/category_purpose_mismatch"
+              },
+              "title": { "const": "Purpose and category do not match" },
+              "status": { "const": 422 },
+              "code": { "const": "category_purpose_mismatch" },
+              "retryable": { "const": false }
+            }
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "const": "https://whooshbang.flowxo.com/problems/category_turned_off"
+              },
+              "title": { "const": "Message category turned off" },
+              "status": { "const": 422 },
+              "code": { "const": "category_turned_off" },
+              "retryable": { "const": false }
+            }
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "const": "https://whooshbang.flowxo.com/problems/category_conflict"
+              },
+              "title": { "const": "Message category conflict" },
+              "status": { "const": 409 },
+              "code": { "const": "category_conflict" },
+              "retryable": { "const": false }
+            }
           }
         ],
         "additionalProperties": false
@@ -18066,11 +18590,13 @@
       },
       "ProjectRecipientExperience": {
         "type": "object",
-        "description": "The project-owned recipient identity, fallback locale, and email answer behavior. Email answers use one click when no setting has been saved.",
+        "description": "The project-owned recipient identity, fallback locale, email answer behavior, and category switch visibility. Email answers use one click when no setting has been saved.",
         "required": [
           "project_id",
           "default_locale",
           "brand",
+          "show_service_category_switches",
+          "show_marketing_category_switches",
           "row_version",
           "updated_at",
           "diagnostic_id"
@@ -18086,6 +18612,14 @@
             "enum": ["one_click", "confirm"],
             "description": "How an email confirm or select button records its bound answer. Defaults to one_click for existing and new projects; free-text answers always use a form."
           },
+          "show_service_category_switches": {
+            "type": "boolean",
+            "description": "Whether subscriber settings show service category switches. A subscriber who already turned a category off still sees its switch. Defaults to true."
+          },
+          "show_marketing_category_switches": {
+            "type": "boolean",
+            "description": "Whether subscriber settings show marketing category switches. A subscriber who already turned a category off still sees its switch. Defaults to true."
+          },
           "row_version": { "type": "integer", "minimum": 1 },
           "updated_at": { "$ref": "#/components/schemas/Timestamp" },
           "diagnostic_id": { "$ref": "#/components/schemas/DiagnosticId" }
@@ -18220,8 +18754,8 @@
       },
       "UpdateProjectRecipientExperienceRequest": {
         "type": "object",
-        "description": "Replaces the project-owned recipient brand and fallback locale under the last observed row version. Omission of email_answer_confirmation preserves its current value, or one_click for an unwritten project.",
-        "required": ["default_locale", "brand", "row_version"],
+        "description": "Updates supplied project recipient settings under the last observed row version. Omitted fields keep their current values or project defaults.",
+        "required": ["row_version"],
         "properties": {
           "default_locale": {
             "$ref": "#/components/schemas/RecipientLanguage"
@@ -18232,6 +18766,14 @@
             "enum": ["one_click", "confirm"],
             "description": "Optional project-wide email answer behavior. Omission preserves the current value."
           },
+          "show_service_category_switches": {
+            "type": "boolean",
+            "description": "Show service category switches in subscriber settings. A subscriber who already turned a category off still sees its switch. Omit to keep the current value."
+          },
+          "show_marketing_category_switches": {
+            "type": "boolean",
+            "description": "Show marketing category switches in subscriber settings. A subscriber who already turned a category off still sees its switch. Omit to keep the current value."
+          },
           "row_version": { "type": "integer", "minimum": 1 }
         },
         "additionalProperties": false
@@ -19236,6 +19778,10 @@
             "enum": ["service", "marketing"],
             "default": "service",
             "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
+          },
+          "category_key": {
+            "$ref": "#/components/schemas/MessageCategoryKey",
+            "description": "Optional project category. Omitted service sends use Updates; omitted marketing sends use Marketing."
           }
         },
         "additionalProperties": false,
@@ -19308,10 +19854,10 @@
         },
         "additionalProperties": false
       },
-      "Channel": {
-        "type": "string",
-        "enum": ["telegram", "slack", "email"],
-        "description": "A provider-neutral delivery channel. Adding a member makes it representable; it does not claim that every deployment has registered an executable adapter."
+      "ListTotal": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "How many records the list holds in total, not only on this page. Counted while the page was read, so a write landing between the count and the page can leave it a record or two out of step with `items`. That is noise on an inspection surface; it never changes which records a page addresses."
       },
       "ProblemCode": {
         "type": "string",
@@ -19348,7 +19894,11 @@
           "provider_terminal",
           "provider_outcome_unknown",
           "internal_error",
-          "not_consented_for_marketing"
+          "not_consented_for_marketing",
+          "category_purpose_mismatch",
+          "category_turned_off",
+          "category_conflict",
+          "category_not_found"
         ]
       },
       "ProblemFieldError": {
@@ -19520,10 +20070,10 @@
           }
         ]
       },
-      "ListTotal": {
-        "type": "integer",
-        "minimum": 0,
-        "description": "How many records the list holds in total, not only on this page. Counted while the page was read, so a write landing between the count and the page can leave it a record or two out of step with `items`. That is noise on an inspection surface; it never changes which records a page addresses."
+      "Channel": {
+        "type": "string",
+        "enum": ["telegram", "slack", "email"],
+        "description": "A provider-neutral delivery channel. Adding a member makes it representable; it does not claim that every deployment has registered an executable adapter."
       },
       "StructuredTextSection": {
         "type": "object",
@@ -19961,6 +20511,19 @@
         "enum": ["test", "live"],
         "description": "The single environment selected by the authenticated credential."
       },
+      "MessageCategorySnapshot": {
+        "type": "object",
+        "description": "The category settings recorded when the message was accepted.",
+        "required": ["key", "name", "purpose", "level", "can_turn_off"],
+        "properties": {
+          "key": { "$ref": "#/components/schemas/MessageCategoryKey" },
+          "name": { "type": "string", "minLength": 1, "maxLength": 100 },
+          "purpose": { "enum": ["service", "marketing"] },
+          "level": { "enum": ["low", "normal", "high", "critical"] },
+          "can_turn_off": { "type": "boolean" }
+        },
+        "additionalProperties": false
+      },
       "EmailAddress": {
         "type": "string",
         "minLength": 3,
@@ -21563,7 +22126,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": "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",
@@ -22365,5 +22928,5 @@
       }
     }
   },
-  "x-contract-version": "3.1.0"
+  "x-contract-version": "3.3.0"
 }