@whooshbang/contracts 2.0.0 → 2.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": "2.0.0",
+  "x-contract-version": "2.2.0",
   "title": "WhooshBangV1ContractDocument",
   "description": "Public request, resource, summary, and Problem Details models for the WhooshBang V1 REST API.",
   "anyOf": [
@@ -364,6 +364,36 @@
     },
     {
       "$ref": "#/$defs/ConfirmSubscriptionChangeRequest"
+    },
+    {
+      "$ref": "#/$defs/Operator"
+    },
+    {
+      "$ref": "#/$defs/OperatorCollection"
+    },
+    {
+      "$ref": "#/$defs/OperatorResolution"
+    },
+    {
+      "$ref": "#/$defs/CreateOperatorMessageRequest"
+    },
+    {
+      "$ref": "#/$defs/OperatorMessageResult"
+    },
+    {
+      "$ref": "#/$defs/OperatorBroadcastRecipient"
+    },
+    {
+      "$ref": "#/$defs/OperatorBroadcast"
+    },
+    {
+      "$ref": "#/$defs/OperatorPreferences"
+    },
+    {
+      "$ref": "#/$defs/OperatorConnectRequest"
+    },
+    {
+      "$ref": "#/$defs/WhoAmI"
     }
   ],
   "$defs": {
@@ -11499,6 +11529,366 @@
         }
       },
       "additionalProperties": false
+    },
+    "Operator": {
+      "type": "object",
+      "description": "A safe, membership-derived operator in the authorized project. No email, provider identifiers or credentials are exposed.",
+      "required": ["id", "name", "role", "readiness", "preferences_url"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "role": {
+          "enum": ["admin", "member", "messenger"]
+        },
+        "readiness": {
+          "enum": ["ready", "channel_unavailable"]
+        },
+        "preferred_channel": {
+          "$ref": "#/$defs/Channel"
+        },
+        "preferences_url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "setup_reason": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "description": "An actionable platform setup reason when the default shared email setup is missing, ambiguous or unavailable."
+        }
+      },
+      "additionalProperties": false
+    },
+    "OperatorCollection": {
+      "type": "object",
+      "description": "Read-only predefined operators audience, filtered to current account and project membership.",
+      "required": ["group", "items", "total"],
+      "properties": {
+        "group": {
+          "const": "operators"
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Operator"
+          }
+        },
+        "total": {
+          "$ref": "#/$defs/ListTotal"
+        },
+        "next_cursor": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "page": {
+          "$ref": "#/$defs/ListPageNumber"
+        },
+        "page_size": {
+          "$ref": "#/$defs/ListPageSize"
+        }
+      },
+      "additionalProperties": false
+    },
+    "OperatorResolution": {
+      "type": "object",
+      "description": "Exact normalized name or stable operator identity. Duplicate names are never guessed.",
+      "required": ["outcome", "choices"],
+      "properties": {
+        "outcome": {
+          "enum": ["resolved", "ambiguous", "not_found"]
+        },
+        "choices": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Operator"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "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"],
+      "properties": {
+        "recipient": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "content": {
+          "$ref": "#/$defs/MessageContent"
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "Optional server-authoritative expiry no more than 24 hours after acceptance."
+        },
+        "correlation_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "metadata": {
+          "$ref": "#/$defs/Metadata"
+        },
+        "interaction": {
+          "$ref": "interaction-v1.schema.json#/$defs/InteractionRequest"
+        },
+        "purpose": {
+          "enum": ["service", "marketing"],
+          "default": "service",
+          "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
+        }
+      },
+      "additionalProperties": false
+    },
+    "OperatorMessageResult": {
+      "type": "object",
+      "description": "Readable acceptance or refusal. Accepted means queued, never proof of provider delivery.",
+      "required": ["outcome", "choices", "detail"],
+      "properties": {
+        "outcome": {
+          "enum": [
+            "accepted",
+            "ambiguous",
+            "not_found",
+            "recipient_required",
+            "channel_unavailable"
+          ]
+        },
+        "choices": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Operator"
+          }
+        },
+        "detail": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "message": {
+          "$ref": "#/$defs/Message"
+        },
+        "preferences_url": {
+          "type": "string",
+          "format": "uri"
+        }
+      },
+      "additionalProperties": false
+    },
+    "OperatorBroadcastRecipient": {
+      "type": "object",
+      "description": "Per-person broadcast result. Sent requires provider acceptance; skipped includes removed membership or an unavailable destination.",
+      "required": ["operator_id", "outcome"],
+      "properties": {
+        "operator_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "name": {
+          "type": "string"
+        },
+        "outcome": {
+          "enum": ["pending", "sent", "skipped", "failed"]
+        },
+        "message_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "reason": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "OperatorBroadcast": {
+      "type": "object",
+      "description": "Durable operators broadcast using ordinary child messages and charging. Read again for provider outcomes.",
+      "required": ["broadcast", "recipients"],
+      "properties": {
+        "broadcast": {
+          "$ref": "#/$defs/GroupBroadcast"
+        },
+        "recipients": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/OperatorBroadcastRecipient"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "OperatorPreferences": {
+      "type": "object",
+      "description": "The authenticated person’s own destinations and preferred channel in this project. Shared credentials cannot manage a human’s preferences.",
+      "required": ["operator", "settings", "connections"],
+      "properties": {
+        "operator": {
+          "$ref": "#/$defs/Operator"
+        },
+        "settings": {
+          "$ref": "#/$defs/SubscriberChannelSettings"
+        },
+        "connections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "description": "An available personal connection route.",
+            "required": ["id", "channel", "name"],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "channel": {
+                "$ref": "#/$defs/Channel"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "OperatorConnectRequest": {
+      "type": "object",
+      "description": "Connect the signed-in person’s own destination through a configured channel. This never changes another person’s channels.",
+      "required": ["connection_id", "channel"],
+      "properties": {
+        "connection_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "channel": {
+          "enum": ["telegram", "slack"]
+        }
+      },
+      "additionalProperties": false
+    },
+    "WhoAmI": {
+      "type": "object",
+      "description": "Current principal, authorized context, safe channel readiness and deterministic personal me identity. Contains no email or provider destination.",
+      "required": ["principal", "context", "capabilities", "detail"],
+      "properties": {
+        "principal": {
+          "type": "object",
+          "description": "The credential actually authenticated for this request; service identity never implies its creator is the recipient.",
+          "required": ["type", "id"],
+          "properties": {
+            "type": {
+              "enum": [
+                "personal_session",
+                "personal_mcp",
+                "project_credential",
+                "organization_credential",
+                "machine_client"
+              ]
+            },
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128
+            }
+          },
+          "additionalProperties": false
+        },
+        "context": {
+          "type": "object",
+          "description": "Explicit authorized account and project context. No context is guessed across tenants.",
+          "required": [
+            "organization_id",
+            "project_id",
+            "environment_id",
+            "environment"
+          ],
+          "properties": {
+            "organization_id": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128
+            },
+            "project_id": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128
+            },
+            "environment_id": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128
+            },
+            "environment": {
+              "enum": ["test", "live"]
+            }
+          },
+          "additionalProperties": false
+        },
+        "capabilities": {
+          "type": "object",
+          "description": "Current messaging permissions; quota, binding readiness and provider gates still apply per send.",
+          "required": [
+            "can_message_self",
+            "can_message_teammates",
+            "can_broadcast_operators"
+          ],
+          "properties": {
+            "can_message_self": {
+              "type": "boolean"
+            },
+            "can_message_teammates": {
+              "type": "boolean"
+            },
+            "can_broadcast_operators": {
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": false
+        },
+        "user": {
+          "type": "object",
+          "description": "Verified authenticated human identity. Absent for shared/service credentials.",
+          "required": ["id", "name"],
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128
+            },
+            "name": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 256
+            }
+          },
+          "additionalProperties": false
+        },
+        "me": {
+          "$ref": "#/$defs/Operator"
+        },
+        "detail": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        }
+      },
+      "additionalProperties": false
     }
   }
 }