@whooshbang/contracts 3.1.0 → 3.3.0

package/schemas/whooshbang-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/whooshbang-v1.schema.json",
-  "x-contract-version": "3.1.0",
+  "x-contract-version": "3.3.0",
   "title": "WhooshBangV1ContractDocument",
   "description": "Public request, resource, summary, and Problem Details models for the WhooshBang V1 REST API.",
   "anyOf": [
@@ -110,6 +110,27 @@
     {
       "$ref": "#/$defs/CreateMessageRequest"
     },
+    {
+      "$ref": "#/$defs/MessageCategory"
+    },
+    {
+      "$ref": "#/$defs/MessageCategoryCollection"
+    },
+    {
+      "$ref": "#/$defs/CreateMessageCategoryRequest"
+    },
+    {
+      "$ref": "#/$defs/UpdateMessageCategoryRequest"
+    },
+    {
+      "$ref": "#/$defs/SubscriberCategoryPreference"
+    },
+    {
+      "$ref": "#/$defs/SubscriberCategoryPreferenceCollection"
+    },
+    {
+      "$ref": "#/$defs/SetSubscriberCategoryPreferenceRequest"
+    },
     {
       "$ref": "#/$defs/Message"
     },
@@ -2967,11 +2988,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"
@@ -2991,6 +3014,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
@@ -3006,8 +3037,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": "#/$defs/RecipientLanguage"
@@ -3020,6 +3051,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
@@ -4400,6 +4439,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": "#/$defs/MessageCategoryKey",
+          "description": "Optional project category. Omitted service sends use Updates; omitted marketing sends use Marketing."
         }
       },
       "additionalProperties": false,
@@ -5415,6 +5458,144 @@
       "additionalProperties": false,
       "description": "Exact signed request bytes. A verifier echoes these exact bytes with valid webhook headers to prove it possesses the endpoint secret."
     },
+    "MessageCategoryKey": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+      "minLength": 1,
+      "maxLength": 63
+    },
+    "MessageCategorySnapshot": {
+      "type": "object",
+      "description": "The category settings recorded when the message was accepted.",
+      "required": ["key", "name", "purpose", "level", "can_turn_off"],
+      "properties": {
+        "key": { "$ref": "#/$defs/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
+    },
+    "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": "#/$defs/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": "#/$defs/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": "#/$defs/MessageCategory" }
+        },
+        "total": { "$ref": "#/$defs/ListTotal" }
+      },
+      "additionalProperties": false
+    },
+    "CreateMessageCategoryRequest": {
+      "type": "object",
+      "required": [
+        "key",
+        "name",
+        "description",
+        "purpose",
+        "level",
+        "can_turn_off"
+      ],
+      "properties": {
+        "key": { "$ref": "#/$defs/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": "#/$defs/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": "#/$defs/SubscriberCategoryPreference" }
+        },
+        "total": { "$ref": "#/$defs/ListTotal" }
+      },
+      "additionalProperties": false
+    },
+    "SetSubscriberCategoryPreferenceRequest": {
+      "type": "object",
+      "required": ["enabled"],
+      "properties": { "enabled": { "type": "boolean" } },
+      "additionalProperties": false
+    },
     "CreateMessageRequest": {
       "type": "object",
       "description": "Creates one logical message for one subscriber and one resolved channel binding.",
@@ -5472,6 +5653,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": "#/$defs/MessageCategoryKey",
+          "description": "Optional project category. Omitted service sends use Updates; omitted marketing sends use Marketing."
         }
       },
       "allOf": [
@@ -5664,6 +5849,10 @@
         "notifier_id": {
           "$ref": "#/$defs/OpaqueIdentifier"
         },
+        "category": {
+          "$ref": "#/$defs/MessageCategorySnapshot",
+          "description": "Category as accepted. Absent on messages accepted before categories existed."
+        },
         "binding": {
           "$ref": "#/$defs/BindingSummary"
         },
@@ -5999,10 +6188,6 @@
                     "type": "object",
                     "required": ["classified_error"],
                     "properties": {
-                      "attempt_count": {
-                        "type": "integer",
-                        "minimum": 1
-                      },
                       "classified_error": {
                         "allOf": [
                           {
@@ -6014,7 +6199,8 @@
                               "code": {
                                 "enum": [
                                   "provider_terminal",
-                                  "not_consented_for_marketing"
+                                  "not_consented_for_marketing",
+                                  "category_turned_off"
                                 ]
                               },
                               "retryable": {
@@ -6024,7 +6210,29 @@
                           }
                         ]
                       }
-                    }
+                    },
+                    "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 }
+                          }
+                        }
+                      }
+                    ]
                   }
                 ]
               }
@@ -6123,7 +6331,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": {
@@ -7103,6 +7315,54 @@
               "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
@@ -10031,6 +10291,10 @@
         "notifier_id": {
           "$ref": "#/$defs/OpaqueIdentifier"
         },
+        "category": {
+          "$ref": "#/$defs/MessageCategorySnapshot",
+          "description": "Category as accepted. Absent on messages accepted before categories existed."
+        },
         "state": {
           "$ref": "#/$defs/MessageState"
         },
@@ -11849,6 +12113,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": "#/$defs/MessageCategoryKey",
+          "description": "Optional project category. Omitted service sends use Updates; omitted marketing sends use Marketing."
         }
       },
       "additionalProperties": false,
@@ -12434,6 +12702,9 @@
           "enum": ["service", "marketing"],
           "default": "service",
           "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
+        },
+        "category_key": {
+          "$ref": "#/$defs/MessageCategoryKey"
         }
       },
       "allOf": [
@@ -12489,6 +12760,9 @@
           "enum": ["service", "marketing"],
           "default": "service",
           "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
+        },
+        "category_key": {
+          "$ref": "#/$defs/MessageCategoryKey"
         }
       },
       "additionalProperties": false
@@ -12525,6 +12799,9 @@
           "enum": ["service", "marketing"],
           "default": "service",
           "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
+        },
+        "category_key": {
+          "$ref": "#/$defs/MessageCategoryKey"
         }
       },
       "additionalProperties": false