@whooshbang/contracts 3.0.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.0.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"
     },
@@ -3764,6 +3785,11 @@
           "maxLength": 254,
           "description": "What to call this subscriber: `display_name` when your application sent one, otherwise the name their channel gave when they connected (a Telegram username, a Slack display name, an email address), which is kept only on the standard privacy setting. Absent when there is neither; show `subscriber_id` then."
         },
+        "team_member": {
+          "type": "boolean",
+          "const": true,
+          "description": "Present when this subscriber is someone on your WhooshBang team, messaged through the operators group. `name` is then their WhooshBang account name. They manage their own channels in notification preferences, so the subscriber can be read but not renamed, paused or erased."
+        },
         "locale": {
           "$ref": "#/$defs/RecipientLanguage"
         },
@@ -4395,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,
@@ -5410,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.",
@@ -5467,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": [
@@ -5659,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"
         },
@@ -5994,10 +6162,6 @@
                     "type": "object",
                     "required": ["classified_error"],
                     "properties": {
-                      "attempt_count": {
-                        "type": "integer",
-                        "minimum": 1
-                      },
                       "classified_error": {
                         "allOf": [
                           {
@@ -6009,7 +6173,8 @@
                               "code": {
                                 "enum": [
                                   "provider_terminal",
-                                  "not_consented_for_marketing"
+                                  "not_consented_for_marketing",
+                                  "category_turned_off"
                                 ]
                               },
                               "retryable": {
@@ -6019,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 }
+                          }
+                        }
+                      }
+                    ]
                   }
                 ]
               }
@@ -6118,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": {
@@ -7098,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
@@ -9984,7 +10223,7 @@
     },
     "MessageListEntry": {
       "type": "object",
-      "description": "Content-free accepted-message summary. Includes neither the notification nor an interaction answer.",
+      "description": "Accepted-message summary: a one-line snippet of what the message said, and no interaction answer.",
       "required": [
         "accepted_at",
         "diagnostic_id",
@@ -10026,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"
         },
@@ -10055,6 +10298,16 @@
         "classified_error": {
           "$ref": "#/$defs/ClassifiedError"
         },
+        "content_snippet": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 121,
+          "description": "The start of what the message said, on one line: its text, or the title of block content, cut to 120 characters with an ellipsis. Absent when `content_retained` is false."
+        },
+        "content_retained": {
+          "type": "boolean",
+          "description": "False once the message's content has been deleted at the end of its retention period (7 days, or 90 on paid plans, after it finished). The rest of the entry is kept."
+        },
         "channel": {
           "$ref": "#/$defs/Channel"
         }
@@ -11834,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,
@@ -11952,6 +12209,25 @@
         "settings": {
           "$ref": "#/$defs/SubscriberChannelSettings"
         },
+        "accounts": {
+          "type": "array",
+          "maxItems": 10,
+          "description": "Who each of your connected channels reaches, as the channel named you when you connected: a Telegram or Slack name and username, by binding. Kept only on the Standard privacy setting, so it is empty otherwise.",
+          "items": {
+            "type": "object",
+            "required": ["binding_id"],
+            "properties": {
+              "binding_id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "name": { "type": "string", "minLength": 1, "maxLength": 254 },
+              "username": { "type": "string", "minLength": 1, "maxLength": 80 }
+            },
+            "additionalProperties": false
+          }
+        },
         "connections": {
           "type": "array",
           "items": {
@@ -12400,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": [
@@ -12455,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
@@ -12491,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