@whooshbang/contracts 3.2.0 → 4.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": "3.2.0",
+  "x-contract-version": "4.0.0",
   "title": "WhooshBangV1ContractDocument",
   "description": "Public request, resource, summary, and Problem Details models for the WhooshBang V1 REST API.",
   "anyOf": [
@@ -2988,11 +2988,13 @@
     },
     "ProjectRecipientExperience": {
       "type": "object",
-      "description": "The project-owned recipient identity, fallback locale, and email answer behavior. Email answers use one click when no setting has been saved.",
+      "description": "The project-owned recipient identity, fallback locale, email answer behavior, and category switch visibility. Email answers use one click when no setting has been saved.",
       "required": [
         "project_id",
         "default_locale",
         "brand",
+        "show_service_category_switches",
+        "show_marketing_category_switches",
         "row_version",
         "updated_at",
         "diagnostic_id"
@@ -3012,6 +3014,14 @@
           "enum": ["one_click", "confirm"],
           "description": "How an email confirm or select button records its bound answer. Defaults to one_click for existing and new projects; free-text answers always use a form."
         },
+        "show_service_category_switches": {
+          "type": "boolean",
+          "description": "Whether subscriber settings show service category switches. A subscriber who already turned a category off still sees its switch. Defaults to true."
+        },
+        "show_marketing_category_switches": {
+          "type": "boolean",
+          "description": "Whether subscriber settings show marketing category switches. A subscriber who already turned a category off still sees its switch. Defaults to true."
+        },
         "row_version": {
           "type": "integer",
           "minimum": 1
@@ -3027,8 +3037,8 @@
     },
     "UpdateProjectRecipientExperienceRequest": {
       "type": "object",
-      "description": "Replaces the project-owned recipient brand and fallback locale under the last observed row version. Omission of email_answer_confirmation preserves its current value, or one_click for an unwritten project.",
-      "required": ["default_locale", "brand", "row_version"],
+      "description": "Updates supplied project recipient settings under the last observed row version. Omitted fields keep their current values or project defaults.",
+      "required": ["row_version"],
       "properties": {
         "default_locale": {
           "$ref": "#/$defs/RecipientLanguage"
@@ -3041,6 +3051,14 @@
           "enum": ["one_click", "confirm"],
           "description": "Optional project-wide email answer behavior. Omission preserves the current value."
         },
+        "show_service_category_switches": {
+          "type": "boolean",
+          "description": "Show service category switches in subscriber settings. A subscriber who already turned a category off still sees its switch. Omit to keep the current value."
+        },
+        "show_marketing_category_switches": {
+          "type": "boolean",
+          "description": "Show marketing category switches in subscriber settings. A subscriber who already turned a category off still sees its switch. Omit to keep the current value."
+        },
         "row_version": {
           "type": "integer",
           "minimum": 1
@@ -5478,7 +5496,16 @@
         "purpose": { "enum": ["service", "marketing"] },
         "level": { "enum": ["low", "normal", "high", "critical"] },
         "can_turn_off": { "type": "boolean" },
-        "is_default": { "type": "boolean" }
+        "is_default": { "type": "boolean" },
+        "opted_out_subscriber_count": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of subscribers in this project who currently have this category switched off. Returned when listing a project's categories."
+        },
+        "archived_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "Present only when this category has been archived. Historical messages retain their acceptance-time category snapshot."
+        }
       },
       "additionalProperties": false
     },
@@ -5488,7 +5515,6 @@
       "properties": {
         "items": {
           "type": "array",
-          "maxItems": 100,
           "items": { "$ref": "#/$defs/MessageCategory" }
         },
         "total": { "$ref": "#/$defs/ListTotal" }
@@ -5757,6 +5783,7 @@
         "dispatch_pending",
         "queued",
         "sending",
+        "intake_pending",
         "provider_accepted",
         "retry_wait",
         "terminal_failed",
@@ -5958,6 +5985,7 @@
                   "dispatch_pending",
                   "queued",
                   "sending",
+                  "intake_pending",
                   "provider_accepted",
                   "cancelled",
                   "expired"
@@ -6051,6 +6079,36 @@
             }
           }
         },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "state": {
+                "const": "intake_pending"
+              }
+            },
+            "required": ["state"]
+          },
+          "then": {
+            "type": "object",
+            "properties": {
+              "delivery": {
+                "allOf": [
+                  { "$ref": "#/$defs/DeliveryAttemptSummary" },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "attempt_count": { "type": "integer", "minimum": 1 },
+                      "highest_proven_provider_state": { "const": "none" },
+                      "retry_scheduled": { "const": false },
+                      "classified_error": false
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
         {
           "if": {
             "type": "object",
@@ -6250,7 +6308,12 @@
             "type": "object",
             "properties": {
               "state": {
-                "enum": ["sending", "provider_accepted", "outcome_unknown"]
+                "enum": [
+                  "sending",
+                  "intake_pending",
+                  "provider_accepted",
+                  "outcome_unknown"
+                ]
               },
               "cancellation_effective": {
                 "type": "boolean"
@@ -7990,7 +8053,7 @@
       "additionalProperties": false
     },
     "EmailDnsRecord": {
-      "description": "One exact neutral DNS record. `name` is preserved exactly as the provider returns it and is relative to the registrable domain (for example `send.notify`, not `send.notify.example.com`).",
+      "description": "One exact neutral DNS record. `name` and `value` are preserved exactly as supplied; a record name may be relative to the registrable domain or a full hostname. DNS consoles differ in whether they append the zone automatically.",
       "oneOf": [
         {
           "type": "object",
@@ -8278,6 +8341,10 @@
       "type": "object",
       "required": ["items", "total"],
       "properties": {
+        "managed_domain_available": {
+          "type": "boolean",
+          "description": "Whether this deployment is configured to offer service-managed custom-domain setup. False is a deployment capability, not a domain readiness verdict."
+        },
         "items": {
           "type": "array",
           "maxItems": 100,
@@ -8304,22 +8371,41 @@
       "additionalProperties": false
     },
     "CreateEmailDomainRequest": {
-      "type": "object",
-      "description": "Creates or safely adopts one dedicated domain inside an authorized account-owned installation. No provider team id, API key or OAuth credential can be supplied.",
-      "required": ["installation_id", "domain"],
-      "properties": {
-        "installation_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
-        },
-        "domain": {
-          "$ref": "#/$defs/EmailDomainName"
+      "description": "Creates or safely adopts an account-owned domain. Omit backend and installation_id for the default FlowXO Mail service. An existing legacy OAuth installation may still be selected by id.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["installation_id", "domain"],
+          "properties": {
+            "installation_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "domain": {
+              "$ref": "#/$defs/EmailDomainName"
+            },
+            "tls": {
+              "enum": ["opportunistic", "enforced"],
+              "default": "opportunistic"
+            }
+          },
+          "additionalProperties": false
         },
-        "tls": {
-          "enum": ["opportunistic", "enforced"],
-          "default": "opportunistic"
+        {
+          "type": "object",
+          "required": ["domain"],
+          "properties": {
+            "backend": { "const": "flowxo_mail" },
+            "domain": {
+              "$ref": "#/$defs/EmailDomainName"
+            },
+            "tls": {
+              "enum": ["opportunistic", "enforced"],
+              "default": "opportunistic"
+            }
+          },
+          "additionalProperties": false
         }
-      },
-      "additionalProperties": false
+      ]
     },
     "EmailBindingImportRow": {
       "type": "object",
@@ -10360,6 +10446,7 @@
             "accepted",
             "queued",
             "attempt_started",
+            "attempt_intake_pending",
             "attempt_sent",
             "attempt_retry_scheduled",
             "attempt_could_not_send",