@whooshbang/contracts 3.1.0 → 3.2.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.2.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,209 @@
     }
   ],
   "paths": {
+    "/v1/projects/{project_id}/message-categories": {
+      "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
+      "get": {
+        "operationId": "listMessageCategories",
+        "summary": "List project message categories",
+        "tags": ["Message categories"],
+        "security": [
+          { "clerkSession": [] },
+          { "bearerGrant": [] },
+          { "bearerCredential": [] }
+        ],
+        "x-required-scopes": ["projects:read"],
+        "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",
@@ -7276,6 +7483,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": [
         {
@@ -11692,6 +11968,125 @@
       }
     },
     "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" }
+        },
+        "additionalProperties": false
+      },
+      "MessageCategoryCollection": {
+        "type": "object",
+        "required": ["items", "total"],
+        "properties": {
+          "items": {
+            "type": "array",
+            "maxItems": 100,
+            "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 +12243,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 +12451,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 +16910,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 +17027,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 +17273,6 @@
                       "type": "object",
                       "required": ["classified_error"],
                       "properties": {
-                        "attempt_count": { "type": "integer", "minimum": 1 },
                         "classified_error": {
                           "allOf": [
                             { "$ref": "#/components/schemas/ClassifiedError" },
@@ -16872,7 +17282,8 @@
                                 "code": {
                                   "enum": [
                                     "provider_terminal",
-                                    "not_consented_for_marketing"
+                                    "not_consented_for_marketing",
+                                    "category_turned_off"
                                   ]
                                 },
                                 "retryable": { "const": false }
@@ -16880,7 +17291,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 +17819,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
@@ -19236,6 +19720,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 +19796,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 +19836,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 +20012,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 +20453,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 +22068,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.2.0",
         "title": "ProviderCapabilitiesV1",
         "description": "Provider-neutral, renderer-facing delivery and interaction capabilities with explicit degradation.",
         "type": "object",
@@ -22365,5 +22870,5 @@
       }
     }
   },
-  "x-contract-version": "3.1.0"
+  "x-contract-version": "3.2.0"
 }