@whooshbang/contracts 2.5.0 → 3.0.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": "2.5.0",
+  "x-contract-version": "3.0.0",
   "title": "WhooshBangV1ContractDocument",
   "description": "Public request, resource, summary, and Problem Details models for the WhooshBang V1 REST API.",
   "anyOf": [
@@ -403,6 +403,15 @@
     },
     {
       "$ref": "#/$defs/RedeemBillingPromotionRequest"
+    },
+    {
+      "$ref": "#/$defs/CanonicalCreateMessageRequest"
+    },
+    {
+      "$ref": "#/$defs/CanonicalCreateGroupBroadcastRequest"
+    },
+    {
+      "$ref": "#/$defs/CanonicalCreateOperatorMessageRequest"
     }
   ],
   "$defs": {
@@ -3724,7 +3733,7 @@
           "maxItems": 50,
           "uniqueItems": true,
           "items": {
-            "$ref": "#/$defs/DeveloperKey"
+            "$ref": "#/$defs/GroupKey"
           }
         }
       },
@@ -3815,7 +3824,7 @@
           "uniqueItems": true,
           "description": "The keys of the static groups this subscriber belongs to in the environment asked about. Present when one subscriber is read.",
           "items": {
-            "$ref": "#/$defs/DeveloperKey"
+            "$ref": "#/$defs/GroupKey"
           }
         },
         "last_activity_at": {
@@ -4049,10 +4058,10 @@
     "CreateSubscriberGroupRequest": {
       "type": "object",
       "description": "Creates one static, developer-managed subscriber group.",
-      "required": ["key", "display_name"],
+      "required": ["key"],
       "properties": {
         "key": {
-          "$ref": "#/$defs/DeveloperKey"
+          "$ref": "#/$defs/GroupKey"
         },
         "display_name": {
           "type": "string",
@@ -4069,8 +4078,8 @@
     "UpdateSubscriberGroupRequest": {
       "type": "object",
       "description": "Renames or redescribes an active group. Its key and static membership model cannot change.",
-      "required": ["row_version"],
-      "minProperties": 2,
+      "required": [],
+      "minProperties": 1,
       "properties": {
         "row_version": {
           "type": "integer",
@@ -4086,7 +4095,21 @@
           "maxLength": 500
         }
       },
-      "additionalProperties": false
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": ["display_name"],
+          "properties": {
+            "display_name": {}
+          }
+        },
+        {
+          "required": ["description"],
+          "properties": {
+            "description": {}
+          }
+        }
+      ]
     },
     "SubscriberGroup": {
       "type": "object",
@@ -4120,7 +4143,7 @@
           "$ref": "#/$defs/Environment"
         },
         "key": {
-          "$ref": "#/$defs/DeveloperKey"
+          "$ref": "#/$defs/GroupKey"
         },
         "display_name": {
           "type": "string",
@@ -4229,7 +4252,7 @@
           "$ref": "#/$defs/OpaqueIdentifier"
         },
         "group_key": {
-          "$ref": "#/$defs/DeveloperKey"
+          "$ref": "#/$defs/GroupKey"
         },
         "subscriber_id": {
           "$ref": "#/$defs/OpaqueIdentifier"
@@ -4306,7 +4329,7 @@
       "required": ["group_key", "membership_revision", "items"],
       "properties": {
         "group_key": {
-          "$ref": "#/$defs/DeveloperKey"
+          "$ref": "#/$defs/GroupKey"
         },
         "membership_revision": {
           "type": "integer",
@@ -4340,7 +4363,7 @@
     "CreateGroupBroadcastRequest": {
       "type": "object",
       "description": "Creates one group broadcast using the existing ordinary message envelope. The group target comes only from the path.",
-      "required": ["content"],
+      "required": [],
       "properties": {
         "notifier_id": {
           "allOf": [
@@ -4351,10 +4374,11 @@
           "default": "default"
         },
         "content": {
-          "$ref": "#/$defs/MessageContent"
+          "$ref": "#/$defs/MessageContentInput"
         },
         "expires_at": {
-          "$ref": "#/$defs/Timestamp"
+          "$ref": "#/$defs/Timestamp",
+          "description": "Optional server-authoritative expiry after acceptance, through year 9999. Omit for 24 hours."
         },
         "correlation_id": {
           "type": "string",
@@ -4373,7 +4397,31 @@
           "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
         }
       },
-      "additionalProperties": false
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "anyOf": [
+            {
+              "required": ["content"],
+              "properties": {
+                "content": {
+                  "$ref": "#/$defs/MessageContentInput"
+                }
+              },
+              "additionalProperties": true
+            },
+            {
+              "required": ["interaction"],
+              "properties": {
+                "interaction": {
+                  "$ref": "interaction-v1.schema.json#/$defs/InteractionSendRequest"
+                }
+              },
+              "additionalProperties": true
+            }
+          ]
+        }
+      ]
     },
     "BroadcastAggregate": {
       "type": "object",
@@ -4464,7 +4512,7 @@
           "$ref": "#/$defs/OpaqueIdentifier"
         },
         "group_key": {
-          "$ref": "#/$defs/DeveloperKey"
+          "$ref": "#/$defs/GroupKey"
         },
         "audience_revision": {
           "type": "integer",
@@ -4499,7 +4547,7 @@
     "CreateSubscriptionLinkRequest": {
       "type": "object",
       "description": "Creates one project- and environment-scoped, single-use authorization link.",
-      "required": ["subscriber_id", "channels"],
+      "required": ["subscriber_id"],
       "properties": {
         "subscriber_id": {
           "$ref": "#/$defs/OpaqueIdentifier"
@@ -4523,7 +4571,7 @@
         },
         "connection_id": {
           "$ref": "#/$defs/OpaqueIdentifier",
-          "description": "The exact channel connection to authorize. Required for Slack. For Telegram or email, omission resolves an unambiguous default or sole compatible connection; it never selects an arbitrary fallback."
+          "description": "Optional exact connection. Otherwise the default or only compatible connection is used."
         },
         "address": {
           "$ref": "#/$defs/EmailAddress",
@@ -4572,22 +4620,6 @@
               }
             }
           }
-        },
-        {
-          "if": {
-            "properties": {
-              "channels": {
-                "const": ["slack"]
-              }
-            },
-            "required": ["channels"]
-          },
-          "then": {
-            "required": ["connection_id"],
-            "properties": {
-              "connection_id": {}
-            }
-          }
         }
       ],
       "additionalProperties": false
@@ -5078,7 +5110,7 @@
     "CreateCustomerEndpointRequest": {
       "type": "object",
       "description": "Creates one project/environment endpoint. The service validates the final normalized destination and never returns it from health or diagnostic reads.",
-      "required": ["url", "event_types"],
+      "required": ["url"],
       "properties": {
         "url": {
           "type": "string",
@@ -5106,12 +5138,13 @@
     },
     "RotateCustomerEndpointRequest": {
       "type": "object",
-      "required": ["overlap_seconds"],
+      "required": [],
       "properties": {
         "overlap_seconds": {
           "type": "integer",
           "minimum": 60,
-          "maximum": 86400
+          "maximum": 86400,
+          "default": 86400
         }
       },
       "additionalProperties": false
@@ -5215,6 +5248,16 @@
         },
         "diagnostic_id": {
           "$ref": "#/$defs/DiagnosticId"
+        },
+        "pause_reason": {
+          "type": "string",
+          "enum": ["customer", "sustained_failure", "probe_failed"]
+        },
+        "next_probe_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "recovery_pending": {
+          "type": "boolean"
         }
       },
       "additionalProperties": false
@@ -5370,10 +5413,17 @@
     "CreateMessageRequest": {
       "type": "object",
       "description": "Creates one logical message for one subscriber and one resolved channel binding.",
-      "required": ["to", "content"],
+      "required": ["to"],
       "properties": {
         "to": {
-          "$ref": "#/$defs/MessageTarget"
+          "oneOf": [
+            {
+              "$ref": "#/$defs/MessageTarget"
+            },
+            {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            }
+          ]
         },
         "notifier_id": {
           "allOf": [
@@ -5396,11 +5446,11 @@
           "description": "Optional channel connection to send through, from the environment's connections. The subscriber must be connected through it; the service never substitutes another connection or provider. A connection the subscriber has not connected through is refused as `subscriber_not_connected` when they are connected through another, and as an unchosen send would be (`subscriber_unbound` or `preferred_binding_unavailable`) when no connected channel can take the message. Omitted, the service chooses: the subscriber's preferred channel when they set one, otherwise the default connection when they are connected there, otherwise the connection they connected through most recently. The accepted message's `binding.connection_id` records the connection used. Implies `delivery_target: connection`."
         },
         "content": {
-          "$ref": "#/$defs/MessageContent"
+          "$ref": "#/$defs/MessageContentInput"
         },
         "expires_at": {
           "$ref": "#/$defs/Timestamp",
-          "description": "Optional server-authoritative expiry no more than 24 hours after acceptance."
+          "description": "Optional server-authoritative expiry after acceptance, through year 9999. Omit for 24 hours."
         },
         "correlation_id": {
           "type": "string",
@@ -5434,6 +5484,28 @@
               }
             }
           }
+        },
+        {
+          "anyOf": [
+            {
+              "required": ["content"],
+              "properties": {
+                "content": {
+                  "$ref": "#/$defs/MessageContentInput"
+                }
+              },
+              "additionalProperties": true
+            },
+            {
+              "required": ["interaction"],
+              "properties": {
+                "interaction": {
+                  "$ref": "interaction-v1.schema.json#/$defs/InteractionSendRequest"
+                }
+              },
+              "additionalProperties": true
+            }
+          ]
         }
       ],
       "additionalProperties": false
@@ -6511,7 +6583,7 @@
               "const": "https://whooshbang.flowxo.com/problems/idempotency_key_required"
             },
             "title": {
-              "const": "Idempotency key required"
+              "enum": ["Invalid idempotency key", "Idempotency key required"]
             },
             "status": {
               "const": 400
@@ -9606,21 +9678,14 @@
         {
           "type": "object",
           "description": "Atomically create or resolve one subscriber and assert existing consent for an exact customer-owned email connection and domain. No verification message is sent. Revocation, suppression, recipient pause, holds and unhealthy authority take precedence. An omitted source is recorded as customer.",
-          "required": [
-            "subscriber_id",
-            "notifier_id",
-            "connection_id",
-            "domain_id",
-            "address",
-            "consented",
-            "consented_at"
-          ],
+          "required": ["subscriber_id", "address", "consented", "consented_at"],
           "properties": {
             "subscriber_id": {
               "$ref": "#/$defs/OpaqueIdentifier"
             },
             "notifier_id": {
-              "$ref": "#/$defs/OpaqueIdentifier"
+              "$ref": "#/$defs/OpaqueIdentifier",
+              "default": "default"
             },
             "connection_id": {
               "$ref": "#/$defs/OpaqueIdentifier"
@@ -9653,9 +9718,6 @@
           "description": "Enroll an application-verified user for service email. This is relationship evidence, never consent or WhooshBang mailbox verification. An existing prior-consent binding with the same subscriber, address, notifier, connection and domain is reused with its original evidence and status.",
           "required": [
             "subscriber_id",
-            "notifier_id",
-            "connection_id",
-            "domain_id",
             "address",
             "basis",
             "source",
@@ -9666,7 +9728,8 @@
               "$ref": "#/$defs/OpaqueIdentifier"
             },
             "notifier_id": {
-              "$ref": "#/$defs/OpaqueIdentifier"
+              "$ref": "#/$defs/OpaqueIdentifier",
+              "default": "default"
             },
             "connection_id": {
               "$ref": "#/$defs/OpaqueIdentifier"
@@ -9830,9 +9893,7 @@
       "required": ["key", "count"],
       "properties": {
         "key": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 128
+          "$ref": "#/$defs/GroupKey"
         },
         "count": {
           "type": "integer",
@@ -11744,7 +11805,7 @@
     "CreateOperatorMessageRequest": {
       "type": "object",
       "description": "Send to a teammate by exact name or operator ID, or use me. Omitted recipient means the verified authenticated human only. Shared and service credentials must name a recipient. Preferred channel, service-email billing and marketing restrictions still apply.",
-      "required": ["content"],
+      "required": [],
       "properties": {
         "recipient": {
           "type": "string",
@@ -11752,11 +11813,11 @@
           "maxLength": 128
         },
         "content": {
-          "$ref": "#/$defs/MessageContent"
+          "$ref": "#/$defs/MessageContentInput"
         },
         "expires_at": {
           "$ref": "#/$defs/Timestamp",
-          "description": "Optional server-authoritative expiry no more than 24 hours after acceptance."
+          "description": "Optional server-authoritative expiry after acceptance, through year 9999. Omit for 24 hours."
         },
         "correlation_id": {
           "type": "string",
@@ -11775,7 +11836,31 @@
           "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
         }
       },
-      "additionalProperties": false
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "anyOf": [
+            {
+              "required": ["content"],
+              "properties": {
+                "content": {
+                  "$ref": "#/$defs/MessageContentInput"
+                }
+              },
+              "additionalProperties": true
+            },
+            {
+              "required": ["interaction"],
+              "properties": {
+                "interaction": {
+                  "$ref": "interaction-v1.schema.json#/$defs/InteractionSendRequest"
+                }
+              },
+              "additionalProperties": true
+            }
+          ]
+        }
+      ]
     },
     "OperatorMessageResult": {
       "type": "object",
@@ -12264,6 +12349,268 @@
         }
       },
       "additionalProperties": false
+    },
+    "CanonicalCreateMessageRequest": {
+      "type": "object",
+      "description": "Creates one logical message for one subscriber and one resolved channel binding.",
+      "required": ["to", "content"],
+      "properties": {
+        "to": {
+          "$ref": "#/$defs/MessageTarget"
+        },
+        "notifier_id": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            }
+          ],
+          "default": "default"
+        },
+        "delivery_target": {
+          "$ref": "#/$defs/MessageDeliveryTarget",
+          "description": "Optional routing override. Simulator delivery and the reserved test: subscriber prefix are test-environment-only; live requests are refused with 400 request_invalid. Omit for connection delivery, or for the reserved test-environment simulator default."
+        },
+        "connection_id": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            }
+          ],
+          "description": "Optional channel connection to send through, from the environment's connections. The subscriber must be connected through it; the service never substitutes another connection or provider. A connection the subscriber has not connected through is refused as `subscriber_not_connected` when they are connected through another, and as an unchosen send would be (`subscriber_unbound` or `preferred_binding_unavailable`) when no connected channel can take the message. Omitted, the service chooses: the subscriber's preferred channel when they set one, otherwise the default connection when they are connected there, otherwise the connection they connected through most recently. The accepted message's `binding.connection_id` records the connection used. Implies `delivery_target: connection`."
+        },
+        "content": {
+          "$ref": "#/$defs/MessageContent"
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "Optional server-authoritative expiry within the representable range through year 9999 after acceptance."
+        },
+        "correlation_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "metadata": {
+          "$ref": "#/$defs/Metadata"
+        },
+        "interaction": {
+          "$ref": "interaction-v1.schema.json#/$defs/CanonicalInteractionSendRequest"
+        },
+        "purpose": {
+          "enum": ["service", "marketing"],
+          "default": "service",
+          "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "required": ["connection_id"],
+            "properties": {
+              "connection_id": true
+            }
+          },
+          "then": {
+            "properties": {
+              "delivery_target": {
+                "const": "connection"
+              }
+            }
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "CanonicalCreateGroupBroadcastRequest": {
+      "type": "object",
+      "description": "Creates one group broadcast using the existing ordinary message envelope. The group target comes only from the path.",
+      "required": ["content"],
+      "properties": {
+        "notifier_id": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            }
+          ],
+          "default": "default"
+        },
+        "content": {
+          "$ref": "#/$defs/MessageContent"
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "correlation_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "metadata": {
+          "$ref": "#/$defs/Metadata"
+        },
+        "interaction": {
+          "$ref": "interaction-v1.schema.json#/$defs/CanonicalInteractionSendRequest"
+        },
+        "purpose": {
+          "enum": ["service", "marketing"],
+          "default": "service",
+          "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
+        }
+      },
+      "additionalProperties": false
+    },
+    "CanonicalCreateOperatorMessageRequest": {
+      "type": "object",
+      "description": "Send to a teammate by exact name or operator ID, or use me. Omitted recipient means the verified authenticated human only. Shared and service credentials must name a recipient. Preferred channel, service-email billing and marketing restrictions still apply.",
+      "required": ["content"],
+      "properties": {
+        "recipient": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "content": {
+          "$ref": "#/$defs/MessageContent"
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "Optional server-authoritative expiry within the representable range through year 9999 after acceptance."
+        },
+        "correlation_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "metadata": {
+          "$ref": "#/$defs/Metadata"
+        },
+        "interaction": {
+          "$ref": "interaction-v1.schema.json#/$defs/CanonicalInteractionSendRequest"
+        },
+        "purpose": {
+          "enum": ["service", "marketing"],
+          "default": "service",
+          "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
+        }
+      },
+      "additionalProperties": false
+    },
+    "MessageContentInput": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 8192,
+          "x-max-utf8-bytes": 8192
+        },
+        {
+          "$ref": "#/$defs/TextContentInput"
+        },
+        {
+          "$ref": "#/$defs/DocumentContentInput"
+        }
+      ]
+    },
+    "TextContentInput": {
+      "type": "object",
+      "required": ["text"],
+      "properties": {
+        "type": {
+          "const": "text"
+        },
+        "format": {
+          "type": "string",
+          "enum": ["plain", "markdown"],
+          "description": "Text format. Omitted means plain text. Markdown supports headings, paragraphs, emphasis, strong emphasis, code, lists, quotes and safe HTTP(S) links; raw HTML and remote images are never executed or fetched."
+        },
+        "text": {
+          "description": "The complete notification content. This remains authoritative and sufficient when an adapter cannot render optional structure.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 8192,
+          "x-max-utf8-bytes": 8192
+        },
+        "title": {
+          "description": "An optional semantic title. The adapter chooses its native presentation.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "x-max-utf8-bytes": 800
+        },
+        "sections": {
+          "description": "Optional ordered semantic sections that enhance, but never replace, the complete text.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 12,
+          "items": {
+            "$ref": "#/$defs/StructuredTextSection"
+          }
+        },
+        "image": {
+          "$ref": "#/$defs/NotificationImageInput"
+        }
+      },
+      "additionalProperties": false
+    },
+    "DocumentContentInput": {
+      "description": "An authoritative ordered portable notification document that every delivery adapter renders faithfully.",
+      "type": "object",
+      "required": ["blocks"],
+      "properties": {
+        "type": {
+          "const": "document"
+        },
+        "title": {
+          "description": "An optional semantic document title. The adapter chooses its native presentation.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "x-max-utf8-bytes": 800
+        },
+        "blocks": {
+          "description": "The complete portable document in exact authored order.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 24,
+          "items": {
+            "$ref": "#/$defs/DocumentBlock"
+          }
+        },
+        "image": {
+          "$ref": "#/$defs/NotificationImageInput"
+        }
+      },
+      "additionalProperties": false
+    },
+    "NotificationImageInput": {
+      "type": "object",
+      "description": "One optional provider-neutral illustrative image. The notification content remains complete without the pixels.",
+      "required": ["asset_id"],
+      "properties": {
+        "asset_id": {
+          "$ref": "#/$defs/NotificationImageAssetId"
+        },
+        "purpose": {
+          "const": "illustration",
+          "default": "illustration"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1000,
+          "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F]+$",
+          "x-max-utf8-bytes": 4000,
+          "description": "Optional accessible description preserved by every adapter. Omit it for a decorative illustration; notification text must remain complete without the image."
+        }
+      },
+      "additionalProperties": false
+    },
+    "GroupKey": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63,
+      "pattern": "^[A-Za-z0-9]+(?:[-_][A-Za-z0-9]+)*$",
+      "description": "A stable, case-sensitive subscriber group key. Existing keys are preserved exactly."
     }
   }
 }