@whooshbang/contracts 3.1.0 → 3.2.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.2.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"
     },
@@ -4400,6 +4421,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 +5440,136 @@
       "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" }
+      },
+      "additionalProperties": false
+    },
+    "MessageCategoryCollection": {
+      "type": "object",
+      "required": ["items", "total"],
+      "properties": {
+        "items": {
+          "type": "array",
+          "maxItems": 100,
+          "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 +5627,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 +5823,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 +6162,6 @@
                     "type": "object",
                     "required": ["classified_error"],
                     "properties": {
-                      "attempt_count": {
-                        "type": "integer",
-                        "minimum": 1
-                      },
                       "classified_error": {
                         "allOf": [
                           {
@@ -6014,7 +6173,8 @@
                               "code": {
                                 "enum": [
                                   "provider_terminal",
-                                  "not_consented_for_marketing"
+                                  "not_consented_for_marketing",
+                                  "category_turned_off"
                                 ]
                               },
                               "retryable": {
@@ -6024,7 +6184,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 +6305,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 +7289,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 +10265,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 +12087,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 +12676,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 +12734,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 +12773,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