@whooshbang/contracts 2.0.0-rc.7 → 2.0.0

package/schemas/whooshbang-v1.schema.json

@@ -1,13 +1,25 @@
 {
   "$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-rc.7",
+  "x-contract-version": "2.0.0",
   "title": "WhooshBangV1ContractDocument",
   "description": "Public request, resource, summary, and Problem Details models for the WhooshBang V1 REST API.",
   "anyOf": [
     {
       "$ref": "#/$defs/OrganizationProjection"
     },
+    {
+      "$ref": "#/$defs/Teammate"
+    },
+    {
+      "$ref": "#/$defs/TeammateCollection"
+    },
+    {
+      "$ref": "#/$defs/TeammateAccessRequest"
+    },
+    {
+      "$ref": "#/$defs/InviteTeammateRequest"
+    },
     {
       "$ref": "#/$defs/CloseOrganizationRequest"
     },
@@ -469,8 +481,8 @@
     },
     "OrganizationRole": {
       "type": "string",
-      "enum": ["admin", "member"],
-      "description": "The stable WhooshBang authorization role projected from the current Clerk organization membership."
+      "enum": ["admin", "member", "messenger"],
+      "description": "The person's WhooshBang role in the organization. `admin` does everything, including billing, API keys and teammates. `member` runs the projects they were given: channels, subscribers, messages and project settings. `messenger` sends messages and reads replies in the projects they were given. Clients must tolerate roles added later."
     },
     "OrganizationMembershipSummary": {
       "type": "object",
@@ -482,6 +494,217 @@
       },
       "additionalProperties": false
     },
+    "TeammateStatus": {
+      "type": "string",
+      "enum": ["active", "invited"],
+      "description": "`active` has joined. `invited` has an invitation they have not accepted."
+    },
+    "TeammateProjectAccess": {
+      "type": "object",
+      "description": "Which projects the teammate can see. An admin sees every project, including ones created later.",
+      "required": ["all", "project_ids"],
+      "properties": {
+        "all": {
+          "type": "boolean"
+        },
+        "project_ids": {
+          "type": "array",
+          "maxItems": 1000,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/OpaqueIdentifier"
+          },
+          "description": "The projects given to this teammate. Empty when `all` is true."
+        }
+      },
+      "additionalProperties": false
+    },
+    "Teammate": {
+      "type": "object",
+      "description": "One person in the organization, or one invitation to it. Identity-provider identifiers are not public fields.",
+      "required": [
+        "id",
+        "status",
+        "role",
+        "name",
+        "email",
+        "projects",
+        "is_current_user",
+        "created_at"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "status": {
+          "$ref": "#/$defs/TeammateStatus"
+        },
+        "role": {
+          "$ref": "#/$defs/OrganizationRole"
+        },
+        "name": {
+          "anyOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 200
+            }
+          ],
+          "description": "The person's name, when they have given one. Null for an invitation."
+        },
+        "email": {
+          "anyOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 320
+            }
+          ],
+          "description": "The address the person signs in with, or the address invited."
+        },
+        "projects": {
+          "$ref": "#/$defs/TeammateProjectAccess"
+        },
+        "is_current_user": {
+          "type": "boolean",
+          "description": "Whether this is the person making the request."
+        },
+        "created_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "When they joined, or when the invitation was sent."
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "When an invitation stops working. Absent for an active teammate."
+        }
+      },
+      "additionalProperties": false
+    },
+    "TeammateCollection": {
+      "type": "object",
+      "description": "Everybody in the organization and every open invitation, people first.",
+      "required": ["items", "total"],
+      "properties": {
+        "items": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "$ref": "#/$defs/Teammate"
+          }
+        },
+        "next_cursor": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "^[A-Za-z0-9_-]+$"
+        },
+        "page": {
+          "$ref": "#/$defs/ListPageNumber"
+        },
+        "page_size": {
+          "$ref": "#/$defs/ListPageSize"
+        },
+        "total": {
+          "$ref": "#/$defs/ListTotal"
+        }
+      },
+      "additionalProperties": false
+    },
+    "TeammateAccessRequest": {
+      "type": "object",
+      "description": "A role and, except for an admin, at least one project. An admin sees every project and takes no list.",
+      "required": ["role"],
+      "properties": {
+        "role": {
+          "$ref": "#/$defs/OrganizationRole"
+        },
+        "project_ids": {
+          "type": "array",
+          "maxItems": 1000,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/OpaqueIdentifier"
+          }
+        }
+      },
+      "if": {
+        "properties": {
+          "role": {
+            "const": "admin"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "project_ids": {
+            "type": "array",
+            "maxItems": 0
+          }
+        }
+      },
+      "else": {
+        "required": ["project_ids"],
+        "properties": {
+          "project_ids": {
+            "type": "array",
+            "minItems": 1
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "InviteTeammateRequest": {
+      "type": "object",
+      "description": "Invites one person by email with their role and projects in one step.",
+      "required": ["email", "role"],
+      "properties": {
+        "email": {
+          "$ref": "#/$defs/EmailAddress"
+        },
+        "role": {
+          "$ref": "#/$defs/OrganizationRole"
+        },
+        "project_ids": {
+          "type": "array",
+          "maxItems": 1000,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/OpaqueIdentifier"
+          }
+        }
+      },
+      "if": {
+        "properties": {
+          "role": {
+            "const": "admin"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "project_ids": {
+            "type": "array",
+            "maxItems": 0
+          }
+        }
+      },
+      "else": {
+        "required": ["project_ids"],
+        "properties": {
+          "project_ids": {
+            "type": "array",
+            "minItems": 1
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "OrganizationProjection": {
       "type": "object",
       "description": "The current Clerk organization projected as a WhooshBang tenant. Clerk organization and user identifiers are not public fields.",
@@ -2316,6 +2539,185 @@
           },
           "additionalProperties": false,
           "description": "Address-free asserted consent captured on a message. The snapshot survives binding deletion; it never claims recipient verification."
+        },
+        {
+          "type": "object",
+          "required": [
+            "id",
+            "project_id",
+            "environment",
+            "subscriber_id",
+            "notifier_id",
+            "channel",
+            "connection_id",
+            "status",
+            "address",
+            "basis",
+            "service"
+          ],
+          "properties": {
+            "id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "project_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "environment": {
+              "$ref": "#/$defs/Environment"
+            },
+            "subscriber_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "notifier_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "channel": {
+              "const": "email"
+            },
+            "connection_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "status": {
+              "enum": ["active", "paused", "revoked"]
+            },
+            "address": {
+              "$ref": "#/$defs/EmailAddress",
+              "description": "The application-verified email destination enrolled for service notices."
+            },
+            "basis": {
+              "const": "service"
+            },
+            "service": {
+              "type": "object",
+              "required": [
+                "relationship_started_at",
+                "source",
+                "asserted_at",
+                "asserted_by",
+                "domain_id"
+              ],
+              "properties": {
+                "source": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 100,
+                  "pattern": "^[^\u0000-\u001f-Ÿ

]+$"
+                },
+                "asserted_at": {
+                  "$ref": "#/$defs/Timestamp"
+                },
+                "asserted_by": {
+                  "type": "object",
+                  "required": ["kind", "id"],
+                  "properties": {
+                    "kind": {
+                      "enum": ["credential", "grant", "session"]
+                    },
+                    "id": {
+                      "$ref": "#/$defs/OpaqueIdentifier"
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                "domain_id": {
+                  "$ref": "#/$defs/OpaqueIdentifier"
+                },
+                "relationship_started_at": {
+                  "$ref": "#/$defs/Timestamp"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false,
+          "description": "Service relationship evidence. No consent claim. Address-free snapshots survive binding deletion."
+        },
+        {
+          "type": "object",
+          "required": [
+            "id",
+            "project_id",
+            "environment",
+            "subscriber_id",
+            "notifier_id",
+            "channel",
+            "connection_id",
+            "status",
+            "basis",
+            "service"
+          ],
+          "properties": {
+            "id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "project_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "environment": {
+              "$ref": "#/$defs/Environment"
+            },
+            "subscriber_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "notifier_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "channel": {
+              "const": "email"
+            },
+            "connection_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "status": {
+              "enum": ["active", "paused", "revoked"]
+            },
+            "basis": {
+              "const": "service"
+            },
+            "service": {
+              "type": "object",
+              "required": [
+                "relationship_started_at",
+                "source",
+                "asserted_at",
+                "asserted_by",
+                "domain_id"
+              ],
+              "properties": {
+                "source": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 100,
+                  "pattern": "^[^\u0000-\u001f-Ÿ

]+$"
+                },
+                "asserted_at": {
+                  "$ref": "#/$defs/Timestamp"
+                },
+                "asserted_by": {
+                  "type": "object",
+                  "required": ["kind", "id"],
+                  "properties": {
+                    "kind": {
+                      "enum": ["credential", "grant", "session"]
+                    },
+                    "id": {
+                      "$ref": "#/$defs/OpaqueIdentifier"
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                "domain_id": {
+                  "$ref": "#/$defs/OpaqueIdentifier"
+                },
+                "relationship_started_at": {
+                  "$ref": "#/$defs/Timestamp"
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false,
+          "description": "Service relationship evidence. No consent claim. Address-free snapshots survive binding deletion."
         }
       ]
     },
@@ -3925,6 +4327,11 @@
         },
         "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
@@ -4962,6 +5369,11 @@
         },
         "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."
         }
       },
       "allOf": [
@@ -5186,6 +5598,11 @@
         "outcome_guidance": {
           "type": "string",
           "const": "Delivery may have been accepted by the provider. No automatic retry is scheduled; create a new message explicitly if another attempt is appropriate."
+        },
+        "purpose": {
+          "enum": ["service", "marketing"],
+          "default": "service",
+          "description": "Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch."
         }
       },
       "allOf": [
@@ -5475,7 +5892,10 @@
                             "type": "object",
                             "properties": {
                               "code": {
-                                "const": "provider_terminal"
+                                "enum": [
+                                  "provider_terminal",
+                                  "not_consented_for_marketing"
+                                ]
                               },
                               "retryable": {
                                 "const": false
@@ -5582,7 +6002,8 @@
         "provider_retryable",
         "provider_terminal",
         "provider_outcome_unknown",
-        "internal_error"
+        "internal_error",
+        "not_consented_for_marketing"
       ]
     },
     "ProblemFieldError": {
@@ -6542,6 +6963,26 @@
               "const": true
             }
           }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "const": "https://whooshbang.flowxo.com/problems/not_consented_for_marketing"
+            },
+            "title": {
+              "const": "Marketing consent required"
+            },
+            "status": {
+              "const": 422
+            },
+            "code": {
+              "const": "not_consented_for_marketing"
+            },
+            "retryable": {
+              "const": false
+            }
+          }
         }
       ],
       "additionalProperties": false
@@ -6552,9 +6993,11 @@
         "projects:write",
         "projects:read",
         "billing:write",
-        "billing:read"
+        "billing:read",
+        "teammates:write",
+        "teammates:read"
       ],
-      "description": "An organization-level capability carried by a human session or an OAuth grant. Billing scopes grant financial access separately from project configuration. Project and organization API credentials cannot administer billing."
+      "description": "An organization-level capability carried by a human session or an OAuth grant. Teammate scopes reach the organization's people: who is in it, their roles and their projects. Billing scopes grant financial access separately from project configuration. Project and organization API credentials cannot administer billing."
     },
     "OAuthScope": {
       "description": "A scope an OAuth grant may carry. Project-level scopes are the credential vocabulary unchanged; organization-level scopes exist only here and on a human session.",
@@ -9113,49 +9556,100 @@
       "additionalProperties": false
     },
     "AssertEmailConsentRequest": {
-      "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"
-      ],
-      "properties": {
-        "subscriber_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
-        },
-        "notifier_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
-        },
-        "connection_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
-        },
-        "domain_id": {
-          "$ref": "#/$defs/OpaqueIdentifier"
-        },
-        "address": {
-          "$ref": "#/$defs/EmailAddress"
-        },
-        "consented": {
-          "const": true
-        },
-        "consented_at": {
-          "$ref": "#/$defs/Timestamp",
-          "description": "When the application obtained consent; must not be in the future."
+      "description": "Assert prior consent or enroll an application-verified user for service email on an exact customer-owned connection. Revocation and sending restrictions always win.",
+      "oneOf": [
+        {
+          "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"
+          ],
+          "properties": {
+            "subscriber_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "notifier_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "connection_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "domain_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "address": {
+              "$ref": "#/$defs/EmailAddress"
+            },
+            "consented": {
+              "const": true
+            },
+            "consented_at": {
+              "$ref": "#/$defs/Timestamp",
+              "description": "When the application obtained consent; must not be in the future."
+            },
+            "source": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 100,
+              "pattern": "^[^\u0000-\u001f-Ÿ

]+$",
+              "description": "A bounded customer description of where consent was collected. The authenticated asserting actor is recorded by the service, never accepted from this object."
+            }
+          },
+          "additionalProperties": false
         },
-        "source": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 100,
-          "pattern": "^[^\u0000-\u001f-Ÿ

]+$",
-          "description": "A bounded customer description of where consent was collected. The authenticated asserting actor is recorded by the service, never accepted from this object."
+        {
+          "type": "object",
+          "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": "^[^\u0000-\u001f-Ÿ

]+$",
+            "notifier_id",
+            "connection_id",
+            "domain_id",
+            "address",
+            "basis",
+            "source",
+            "relationship_started_at"
+          ],
+          "properties": {
+            "subscriber_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "notifier_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "connection_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "domain_id": {
+              "$ref": "#/$defs/OpaqueIdentifier"
+            },
+            "address": {
+              "$ref": "#/$defs/EmailAddress"
+            },
+            "source": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 100,
+              "pattern": "^[^\u0000-\u001f-Ÿ

]+$",
+              "description": "A bounded customer description of the service relationship. The authenticated asserting actor is recorded by the service, never accepted from this object."
+            },
+            "basis": {
+              "const": "service"
+            },
+            "relationship_started_at": {
+              "$ref": "#/$defs/Timestamp",
+              "description": "When the verified user relationship began; must not be in the future."
+            }
+          },
+          "additionalProperties": false
         }
-      },
-      "additionalProperties": false
+      ]
     },
     "SubscriberChannelSettings": {
       "type": "object",
@@ -10648,6 +11142,10 @@
             }
           ],
           "description": "A recurring charge the default card did not pay. Paid access continues until the paid boundary; another attempt follows at next_attempt_at, or none when null. Update the card to settle it."
+        },
+        "recurring_selection": {
+          "$ref": "#/$defs/SubscriptionSelection",
+          "description": "Selection that will renew; paid project capacity can also include dropped extras until their original expiry. Optional for compatibility with older servers."
         }
       },
       "additionalProperties": false
@@ -10694,7 +11192,7 @@
         "project_capacity": {
           "type": "integer",
           "minimum": 1,
-          "maximum": 10025
+          "maximum": 2147483647
         },
         "requested_project_ids": {
           "type": "array",
@@ -10702,7 +11200,7 @@
             "$ref": "#/$defs/OpaqueIdentifier"
           },
           "uniqueItems": true,
-          "maxItems": 10025
+          "maxItems": 2147483647
         },
         "active_project_ids": {
           "type": "array",
@@ -10710,11 +11208,11 @@
             "$ref": "#/$defs/OpaqueIdentifier"
           },
           "uniqueItems": true,
-          "maxItems": 10025
+          "maxItems": 2147483647
         }
       },
       "additionalProperties": false,
-      "description": "Reusable account project slots. After a downgrade the oldest requested projects retain active slots. Unassigned projects retain data, accepted delivery and answers; new live sends require an active slot."
+      "description": "Reusable account project slots. After a downgrade the oldest requested projects retain active slots. Unassigned projects retain data, accepted delivery and answers; new live sends require an active slot. Paid capacity includes all unexpired project purchases, so retained dropped extras can exceed the maximum renewing selection."
     },
     "AssignBillingProjectSlotsRequest": {
       "type": "object",
@@ -10930,7 +11428,8 @@
             {
               "type": "null"
             }
-          ]
+          ],
+          "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."
         },
         "effective_at": {
           "anyOf": [