@whooshbang/contracts 2.4.0 → 2.6.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.4.0",
+  "x-contract-version": "2.6.0",
   "title": "WhooshBangV1ContractDocument",
   "description": "Public request, resource, summary, and Problem Details models for the WhooshBang V1 REST API.",
   "anyOf": [
@@ -394,6 +394,24 @@
     },
     {
       "$ref": "#/$defs/WhoAmI"
+    },
+    {
+      "$ref": "#/$defs/BillingPromotions"
+    },
+    {
+      "$ref": "#/$defs/BillingPromotion"
+    },
+    {
+      "$ref": "#/$defs/RedeemBillingPromotionRequest"
+    },
+    {
+      "$ref": "#/$defs/CanonicalCreateMessageRequest"
+    },
+    {
+      "$ref": "#/$defs/CanonicalCreateGroupBroadcastRequest"
+    },
+    {
+      "$ref": "#/$defs/CanonicalCreateOperatorMessageRequest"
     }
   ],
   "$defs": {
@@ -3715,7 +3733,7 @@
           "maxItems": 50,
           "uniqueItems": true,
           "items": {
-            "$ref": "#/$defs/DeveloperKey"
+            "$ref": "#/$defs/GroupKey"
           }
         }
       },
@@ -3806,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": {
@@ -4040,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",
@@ -4060,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",
@@ -4077,7 +4095,21 @@
           "maxLength": 500
         }
       },
-      "additionalProperties": false
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": ["display_name"],
+          "properties": {
+            "display_name": {}
+          }
+        },
+        {
+          "required": ["description"],
+          "properties": {
+            "description": {}
+          }
+        }
+      ]
     },
     "SubscriberGroup": {
       "type": "object",
@@ -4111,7 +4143,7 @@
           "$ref": "#/$defs/Environment"
         },
         "key": {
-          "$ref": "#/$defs/DeveloperKey"
+          "$ref": "#/$defs/GroupKey"
         },
         "display_name": {
           "type": "string",
@@ -4220,7 +4252,7 @@
           "$ref": "#/$defs/OpaqueIdentifier"
         },
         "group_key": {
-          "$ref": "#/$defs/DeveloperKey"
+          "$ref": "#/$defs/GroupKey"
         },
         "subscriber_id": {
           "$ref": "#/$defs/OpaqueIdentifier"
@@ -4297,7 +4329,7 @@
       "required": ["group_key", "membership_revision", "items"],
       "properties": {
         "group_key": {
-          "$ref": "#/$defs/DeveloperKey"
+          "$ref": "#/$defs/GroupKey"
         },
         "membership_revision": {
           "type": "integer",
@@ -4331,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": [
@@ -4342,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",
@@ -4364,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",
@@ -4455,7 +4512,7 @@
           "$ref": "#/$defs/OpaqueIdentifier"
         },
         "group_key": {
-          "$ref": "#/$defs/DeveloperKey"
+          "$ref": "#/$defs/GroupKey"
         },
         "audience_revision": {
           "type": "integer",
@@ -4490,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"
@@ -4514,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",
@@ -4563,22 +4620,6 @@
               }
             }
           }
-        },
-        {
-          "if": {
-            "properties": {
-              "channels": {
-                "const": ["slack"]
-              }
-            },
-            "required": ["channels"]
-          },
-          "then": {
-            "required": ["connection_id"],
-            "properties": {
-              "connection_id": {}
-            }
-          }
         }
       ],
       "additionalProperties": false
@@ -5069,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",
@@ -5097,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
@@ -5361,10 +5403,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": [
@@ -5387,11 +5436,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",
@@ -5425,6 +5474,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
@@ -6502,7 +6573,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
@@ -9597,21 +9668,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"
@@ -9644,9 +9708,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",
@@ -9657,7 +9718,8 @@
               "$ref": "#/$defs/OpaqueIdentifier"
             },
             "notifier_id": {
-              "$ref": "#/$defs/OpaqueIdentifier"
+              "$ref": "#/$defs/OpaqueIdentifier",
+              "default": "default"
             },
             "connection_id": {
               "$ref": "#/$defs/OpaqueIdentifier"
@@ -9821,9 +9883,7 @@
       "required": ["key", "count"],
       "properties": {
         "key": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 128
+          "$ref": "#/$defs/GroupKey"
         },
         "count": {
           "type": "integer",
@@ -10782,6 +10842,12 @@
         "purchase_cents": {
           "type": "integer",
           "enum": [500, 1000, 2500, 5000, 10000]
+        },
+        "approved_charge_usd": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+          "maxLength": 40,
+          "description": "Optional. The card charge the customer approved: the pack price less any promotion shown to them. When it differs from what would be charged, the purchase is refused with credit_purchase_price_changed and nothing is charged."
         }
       },
       "description": "Buy one credit pack now with the default card. The amount is the explicit approval of the charge."
@@ -10793,6 +10859,8 @@
         "id",
         "purchase_cents",
         "credit_usd",
+        "charged_usd",
+        "discount_usd",
         "status",
         "failure",
         "client_secret",
@@ -10813,6 +10881,18 @@
           "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
           "maxLength": 40
         },
+        "charged_usd": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+          "maxLength": 40,
+          "description": "What the card is charged: the pack price less any promotional discount. The pack's credit is unchanged."
+        },
+        "discount_usd": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+          "maxLength": 40,
+          "description": "The promotional discount taken off the pack price, or 0.000000."
+        },
         "status": {
           "type": "string",
           "enum": ["processing", "requires_action", "paid", "failed"]
@@ -11406,6 +11486,8 @@
         "monthly_price_usd",
         "charge_now_usd",
         "unused_time_credit_usd",
+        "promotion",
+        "renewal_promotion",
         "effective_at",
         "expires_at",
         "client_secret",
@@ -11467,6 +11549,95 @@
           ],
           "description": "Compatibility field: new upgrades return 0.000000; starts and boundary changes return null. Historical quotes can retain their recorded unused-time credit. No new automatic unused-time refunds or offsets."
         },
+        "promotion": {
+          "anyOf": [
+            {
+              "type": "object",
+              "required": ["percent_off", "duration", "months", "discount_usd"],
+              "properties": {
+                "percent_off": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 90
+                },
+                "duration": {
+                  "type": "string",
+                  "enum": ["once", "repeating"]
+                },
+                "months": {
+                  "anyOf": [
+                    {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 12
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "discount_usd": {
+                  "type": "string",
+                  "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                  "maxLength": 40,
+                  "description": "What the promotion takes off charge_now_usd."
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "A promotion code's plan discount applied to this first plan or add-on purchase: charge_now_usd is already reduced by it, and the monthly charges keep it for its months. Null when no plan discount applies."
+        },
+        "renewal_promotion": {
+          "anyOf": [
+            {
+              "type": "object",
+              "required": [
+                "percent_off",
+                "duration",
+                "renewal_price_usd",
+                "ends_at"
+              ],
+              "properties": {
+                "percent_off": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 90
+                },
+                "duration": {
+                  "type": "string",
+                  "enum": ["once", "repeating"]
+                },
+                "renewal_price_usd": {
+                  "type": "string",
+                  "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                  "maxLength": 40,
+                  "description": "What the next monthly charge for this selection comes to with the promotion: monthly_price_usd less its percentage."
+                },
+                "ends_at": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "When a repeating promotion stops applying. Null for a once promotion, which applies to the next monthly charge only."
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "A plan discount already running on the subscription, which keeps lowering the monthly charges after this change. It never reduces charge_now_usd. Null when none applies to the next monthly charge, and once a change is no longer a quote."
+        },
         "effective_at": {
           "anyOf": [
             {
@@ -11624,7 +11795,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",
@@ -11632,11 +11803,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",
@@ -11655,7 +11826,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",
@@ -11895,6 +12090,517 @@
         }
       },
       "additionalProperties": false
+    },
+    "BillingPromotion": {
+      "type": "object",
+      "required": [
+        "id",
+        "source",
+        "name",
+        "status",
+        "starts_at",
+        "ends_at",
+        "ended_at",
+        "benefit"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^grn_[0-9a-z]{26}$"
+        },
+        "source": {
+          "type": "string",
+          "enum": ["whooshbang", "code"],
+          "description": "`whooshbang` for a reward WhooshBang gave the organization directly; `code` for a promotion code the organization redeemed."
+        },
+        "name": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The promotion's name for a redeemed code. Null for a direct reward."
+        },
+        "status": {
+          "type": "string",
+          "enum": ["active", "pending", "expired", "used", "revoked"],
+          "description": "`pending` is a credit pack discount carried by a payment still waiting for the customer's bank; it is not available to another purchase. `used` applies only to a discount that has been applied to a purchase or put on a plan. `revoked` means WhooshBang withdrew what remained."
+        },
+        "starts_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "ends_at": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "date-time"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When the benefit stops. Null for a discount, which ends when it is used or, for a plan discount, after its months."
+        },
+        "ended_at": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "date-time"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When the promotion was used or withdrawn, if it was."
+        },
+        "benefit": {
+          "oneOf": [
+            {
+              "type": "object",
+              "required": ["kind", "credit_usd", "remaining_usd"],
+              "properties": {
+                "kind": {
+                  "const": "message_credit"
+                },
+                "credit_usd": {
+                  "type": "string",
+                  "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                  "maxLength": 40
+                },
+                "remaining_usd": {
+                  "type": "string",
+                  "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                  "maxLength": 40
+                }
+              },
+              "additionalProperties": false,
+              "description": "Promotional credit for messages. Spent before purchased, bonus and welcome credit; it never pays the shared-email charge."
+            },
+            {
+              "type": "object",
+              "required": ["kind", "shared_emails", "remaining"],
+              "properties": {
+                "kind": {
+                  "const": "shared_emails"
+                },
+                "shared_emails": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 1000000
+                },
+                "remaining": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 1000000
+                }
+              },
+              "additionalProperties": false,
+              "description": "Emails through WhooshBang's shared email service with no shared-email charge. The message itself is still paid for."
+            },
+            {
+              "type": "object",
+              "required": ["kind"],
+              "properties": {
+                "kind": {
+                  "const": "branding"
+                }
+              },
+              "additionalProperties": false,
+              "description": "WhooshBang branding can be removed from recipient messages until ends_at."
+            },
+            {
+              "type": "object",
+              "required": [
+                "kind",
+                "applies_to",
+                "percent_off",
+                "amount_off_usd",
+                "duration",
+                "months"
+              ],
+              "properties": {
+                "kind": {
+                  "const": "discount"
+                },
+                "applies_to": {
+                  "type": "string",
+                  "enum": ["credit_packs", "subscriptions"]
+                },
+                "percent_off": {
+                  "anyOf": [
+                    {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 90
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "amount_off_usd": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                      "maxLength": 40
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "duration": {
+                  "type": "string",
+                  "enum": ["once", "repeating"]
+                },
+                "months": {
+                  "anyOf": [
+                    {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 12
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                }
+              },
+              "additionalProperties": false,
+              "description": "Money off the next credit pack, or off plan and add-on charges for one charge or a number of months."
+            }
+          ]
+        }
+      },
+      "additionalProperties": false,
+      "description": "One promotion an organization holds. Promotional value has no cash value, is never refunded and cannot move to another organization."
+    },
+    "BillingPromotions": {
+      "type": "object",
+      "required": [
+        "promotional_credit_usd",
+        "free_shared_emails",
+        "branding_removed_until",
+        "promotions"
+      ],
+      "properties": {
+        "promotional_credit_usd": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+          "maxLength": 40,
+          "description": "Unexpired promotional message credit available now."
+        },
+        "free_shared_emails": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "description": "Unexpired free shared emails available now."
+        },
+        "branding_removed_until": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "date-time"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When the latest active branding promotion ends, if one is active."
+        },
+        "promotions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/BillingPromotion"
+          },
+          "maxItems": 200
+        }
+      },
+      "additionalProperties": false,
+      "description": "An organization's promotions: rewards WhooshBang gave it and promotion codes it redeemed, newest first."
+    },
+    "RedeemBillingPromotionRequest": {
+      "type": "object",
+      "required": ["code"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "minLength": 4,
+          "maxLength": 64,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9 _-]*$",
+          "description": "The promotion code. Case, spaces, hyphens and underscores are ignored."
+        }
+      },
+      "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."
     }
   }
 }