@whooshbang/contracts 2.3.0 → 2.5.0

package/openapi/generated/whooshbang-v1.bundle.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.1",
   "info": {
     "title": "WhooshBang API",
-    "version": "2.3.0",
+    "version": "2.5.0",
     "description": "The V1 contract for human organization/project administration, project-scoped\nsubscription links, and asynchronous text messages. A Clerk session selects\none organization for administration. A project credential selects one organization,\nproject, and `test` or `live` environment for product operations; request\nbodies cannot override either authenticated scope.\n\nA person's OAuth grant selects one organization and carries scopes, but no\nproject. It names the project and environment it acts in through the URL\npath, on the environment-scoped form of each operation; the service checks\nthat path against the granting person's membership on every call. The flat\nforms remain credential-only and are unchanged.\n\nResource identifiers are opaque and are not authorization. Reads outside the\ncredential scope return the same `404` shape as absent resources. Provider\ncredentials, raw Telegram identity, and protected provider responses are\nnever part of this API.\n",
     "termsOfService": "https://flowxo.com/terms",
     "contact": {
@@ -97,6 +97,7 @@
     "/v1/projects/{project_id}/environments/{environment_id}/whoami": {
       "get": {
         "operationId": "whoAmI",
+        "x-notification-scopes": ["notifications:self", "notifications:team"],
         "summary": "Identify the authenticated caller",
         "description": "Personal login identifies me without a recipient question. Shared or service credentials report their actual principal and require an explicit recipient. No account owner or credential creator is inferred.",
         "tags": ["Operators"],
@@ -105,6 +106,8 @@
           { "bearerCredential": [] },
           { "bearerOrganizationCredential": [] },
           { "bearerGrant": ["messages:read"] },
+          { "bearerGrant": ["notifications:self"] },
+          { "bearerGrant": ["notifications:team"] },
           { "machineCredential": [] }
         ],
         "x-required-scopes": ["messages:read"],
@@ -129,13 +132,15 @@
     "/v1/projects/{project_id}/environments/{environment_id}/operators": {
       "get": {
         "operationId": "listOperators",
+        "x-notification-scopes": ["notifications:team"],
         "summary": "listOperators",
         "description": "Membership-derived operator messaging. Only the authenticated human can manage personal preferences.",
         "tags": ["Operators"],
         "security": [
           { "clerkSession": [] },
           { "bearerCredential": [] },
-          { "bearerGrant": ["messages:read"] }
+          { "bearerGrant": ["messages:read"] },
+          { "bearerGrant": ["notifications:team"] }
         ],
         "x-required-scopes": ["messages:read"],
         "parameters": [
@@ -162,13 +167,15 @@
     "/v1/projects/{project_id}/environments/{environment_id}/operators/resolve": {
       "get": {
         "operationId": "resolveOperator",
+        "x-notification-scopes": ["notifications:team"],
         "summary": "resolveOperator",
         "description": "Membership-derived operator messaging. Only the authenticated human can manage personal preferences.",
         "tags": ["Operators"],
         "security": [
           { "clerkSession": [] },
           { "bearerCredential": [] },
-          { "bearerGrant": ["messages:read"] }
+          { "bearerGrant": ["messages:read"] },
+          { "bearerGrant": ["notifications:team"] }
         ],
         "x-required-scopes": ["messages:read"],
         "parameters": [
@@ -198,6 +205,7 @@
     "/v1/projects/{project_id}/environments/{environment_id}/operator-messages": {
       "post": {
         "operationId": "sendOperatorMessage",
+        "x-notification-scopes": ["notifications:self", "notifications:team"],
         "summary": "sendOperatorMessage",
         "description": "Message a current teammate by name or operator ID. Personal callers may omit recipient or use me. Shared credentials must name a recipient. Runtime machine credentials report recipient_required for omitted or me; named operator sends are forbidden because runtime authority remains subscriber-bound.",
         "tags": ["Operators"],
@@ -206,7 +214,9 @@
           { "bearerCredential": [] },
           { "bearerOrganizationCredential": [] },
           { "machineCredential": [] },
-          { "bearerGrant": ["messages:write"] }
+          { "bearerGrant": ["messages:write"] },
+          { "bearerGrant": ["notifications:self"] },
+          { "bearerGrant": ["notifications:team"] }
         ],
         "x-required-scopes": ["messages:write"],
         "parameters": [
@@ -243,13 +253,15 @@
     "/v1/projects/{project_id}/environments/{environment_id}/operators/broadcasts": {
       "post": {
         "operationId": "broadcastOperators",
+        "x-notification-scopes": ["notifications:team"],
         "summary": "broadcastOperators",
         "description": "Membership-derived operator messaging. Only the authenticated human can manage personal preferences.",
         "tags": ["Operators"],
         "security": [
           { "clerkSession": [] },
           { "bearerCredential": [] },
-          { "bearerGrant": ["messages:write"] }
+          { "bearerGrant": ["messages:write"] },
+          { "bearerGrant": ["notifications:team"] }
         ],
         "x-required-scopes": ["messages:write"],
         "parameters": [
@@ -284,13 +296,15 @@
     "/v1/projects/{project_id}/environments/{environment_id}/operators/broadcasts/{broadcast_id}": {
       "get": {
         "operationId": "getOperatorBroadcast",
+        "x-notification-scopes": ["notifications:team"],
         "summary": "getOperatorBroadcast",
         "description": "Membership-derived operator messaging. Only the authenticated human can manage personal preferences.",
         "tags": ["Operators"],
         "security": [
           { "clerkSession": [] },
           { "bearerCredential": [] },
-          { "bearerGrant": ["messages:read"] }
+          { "bearerGrant": ["messages:read"] },
+          { "bearerGrant": ["notifications:team"] }
         ],
         "x-required-scopes": ["messages:read"],
         "parameters": [
@@ -320,13 +334,16 @@
     "/v1/projects/{project_id}/environments/{environment_id}/notification-preferences": {
       "get": {
         "operationId": "getOperatorPreferences",
+        "x-notification-scopes": ["notifications:self", "notifications:team"],
         "summary": "getOperatorPreferences",
         "description": "Membership-derived operator messaging. Only the authenticated human can manage personal preferences.",
         "tags": ["Operators"],
         "security": [
           { "clerkSession": [] },
           { "bearerCredential": [] },
-          { "bearerGrant": ["messages:read"] }
+          { "bearerGrant": ["messages:read"] },
+          { "bearerGrant": ["notifications:self"] },
+          { "bearerGrant": ["notifications:team"] }
         ],
         "x-required-scopes": ["messages:read"],
         "parameters": [
@@ -350,13 +367,16 @@
     "/v1/projects/{project_id}/environments/{environment_id}/notification-preferences/preferred-binding": {
       "put": {
         "operationId": "setOperatorPreferredBinding",
+        "x-notification-scopes": ["notifications:self", "notifications:team"],
         "summary": "setOperatorPreferredBinding",
         "description": "Membership-derived operator messaging. Only the authenticated human can manage personal preferences.",
         "tags": ["Operators"],
         "security": [
           { "clerkSession": [] },
           { "bearerCredential": [] },
-          { "bearerGrant": ["messages:write"] }
+          { "bearerGrant": ["messages:write"] },
+          { "bearerGrant": ["notifications:self"] },
+          { "bearerGrant": ["notifications:team"] }
         ],
         "x-required-scopes": ["messages:write"],
         "parameters": [
@@ -390,13 +410,16 @@
     "/v1/projects/{project_id}/environments/{environment_id}/notification-preferences/connect": {
       "post": {
         "operationId": "connectOperatorChannel",
+        "x-notification-scopes": ["notifications:self", "notifications:team"],
         "summary": "connectOperatorChannel",
         "description": "Membership-derived operator messaging. Only the authenticated human can manage personal preferences.",
         "tags": ["Operators"],
         "security": [
           { "clerkSession": [] },
           { "bearerCredential": [] },
-          { "bearerGrant": ["messages:write"] }
+          { "bearerGrant": ["messages:write"] },
+          { "bearerGrant": ["notifications:self"] },
+          { "bearerGrant": ["notifications:team"] }
         ],
         "x-required-scopes": ["messages:write"],
         "parameters": [
@@ -501,6 +524,92 @@
         }
       }
     },
+    "/v1/billing/promotions": {
+      "get": {
+        "operationId": "getBillingPromotions",
+        "summary": "Read the organization's promotions",
+        "description": "Organization administrators can read every promotion the organization holds: rewards WhooshBang gave it\nand promotion codes it redeemed, with what remains and when each ends. Promotional value has no cash\nvalue, is never refunded and cannot move to another organization.\n",
+        "tags": ["Organization"],
+        "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
+        "x-required-scopes": ["billing:read"],
+        "x-organization-membership": "required",
+        "responses": {
+          "200": {
+            "description": "The organization's promotions, newest first.",
+            "headers": {
+              "WhooshBang-Diagnostic-Id": {
+                "$ref": "#/components/headers/DiagnosticId"
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/BillingPromotions" }
+              }
+            }
+          },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "403": { "$ref": "#/components/responses/Forbidden" },
+          "404": { "$ref": "#/components/responses/NotFound" },
+          "429": { "$ref": "#/components/responses/RateLimited" }
+        }
+      }
+    },
+    "/v1/billing/promotions/redeem": {
+      "post": {
+        "operationId": "redeemBillingPromotion",
+        "summary": "Redeem a promotion code",
+        "description": "Organization administrators can redeem a promotion code for their own organization. Nothing is charged.\nEvery code that cannot be redeemed (mistyped, ended, fully used, not offered to this organization, or not\ncombinable with a promotion it already holds) receives the same `resource_not_found` answer. Repeated\nrefusals are rate limited per organization; wait for `Retry-After`. Reuse the same idempotency key after\nan uncertain response: it can never redeem twice.\n",
+        "tags": ["Organization"],
+        "security": [{ "clerkSession": [] }, { "bearerGrant": [] }],
+        "x-required-scopes": ["billing:write"],
+        "x-organization-membership": "required",
+        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RedeemBillingPromotionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The same promotion, replayed for a repeated idempotency key.",
+            "headers": {
+              "WhooshBang-Diagnostic-Id": {
+                "$ref": "#/components/headers/DiagnosticId"
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/BillingPromotion" }
+              }
+            }
+          },
+          "201": {
+            "description": "The promotion the code gave the organization.",
+            "headers": {
+              "WhooshBang-Diagnostic-Id": {
+                "$ref": "#/components/headers/DiagnosticId"
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/BillingPromotion" }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/BadRequest" },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "403": { "$ref": "#/components/responses/Forbidden" },
+          "404": { "$ref": "#/components/responses/NotFound" },
+          "409": { "$ref": "#/components/responses/Conflict" },
+          "429": { "$ref": "#/components/responses/RateLimited" }
+        }
+      }
+    },
     "/v1/billing/auto-top-up": {
       "get": {
         "operationId": "getAutoTopUpSettings",
@@ -2190,12 +2299,15 @@
     "/v1/projects": {
       "get": {
         "operationId": "listProjects",
+        "x-notification-scopes": ["notifications:self", "notifications:team"],
         "summary": "List projects in the current organization",
         "description": "Returns only projects owned by the organization selected by the verified\nClerk organization session. Every project includes its complete test/live\nenvironment and default-notifier bootstrap.\n",
         "tags": ["Projects"],
         "security": [
           { "clerkSession": [] },
           { "bearerGrant": [] },
+          { "bearerGrant": ["notifications:self"] },
+          { "bearerGrant": ["notifications:team"] },
           { "bearerOrganizationCredential": [] }
         ],
         "x-required-scopes": ["projects:read"],
@@ -2379,12 +2491,15 @@
       "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
       "get": {
         "operationId": "getProject",
+        "x-notification-scopes": ["notifications:self", "notifications:team"],
         "summary": "Read one project in the current organization",
         "description": "Returns the complete project bootstrap. An absent project and a project\noutside the authenticated organization use the same non-enumerating `404`.\n",
         "tags": ["Projects"],
         "security": [
           { "clerkSession": [] },
           { "bearerGrant": [] },
+          { "bearerGrant": ["notifications:self"] },
+          { "bearerGrant": ["notifications:team"] },
           { "bearerOrganizationCredential": [] }
         ],
         "x-required-scopes": ["projects:read"],
@@ -12836,6 +12951,202 @@
         "additionalProperties": false,
         "description": "Replace the requested active project selection with owned, active projects within current paid capacity. An empty selection releases all slots."
       },
+      "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": "#/components/schemas/BillingPromotion" },
+            "maxItems": 200
+          }
+        },
+        "additionalProperties": false,
+        "description": "An organization's promotions: rewards WhooshBang gave it and promotion codes it redeemed, newest first."
+      },
+      "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."
+      },
+      "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
+      },
       "BillingEntitlements": {
         "type": "object",
         "required": [
@@ -13000,6 +13311,8 @@
           "monthly_price_usd",
           "charge_now_usd",
           "unused_time_credit_usd",
+          "promotion",
+          "renewal_promotion",
           "effective_at",
           "expires_at",
           "client_secret",
@@ -13055,6 +13368,85 @@
             ],
             "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": [
               { "type": "string", "format": "date-time" },
@@ -13387,6 +13779,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."
@@ -13398,6 +13796,8 @@
           "id",
           "purchase_cents",
           "credit_usd",
+          "charged_usd",
+          "discount_usd",
           "status",
           "failure",
           "client_secret",
@@ -13418,6 +13818,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"]
@@ -20387,7 +20799,7 @@
       "provider-capabilities-v1.schema": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "$id": "https://whooshbang.flowxo.com/schemas/provider-capabilities-v1.schema.json",
-        "x-contract-version": "2.3.0",
+        "x-contract-version": "2.5.0",
         "title": "ProviderCapabilitiesV1",
         "description": "Provider-neutral, renderer-facing delivery and interaction capabilities with explicit degradation.",
         "type": "object",
@@ -21168,5 +21580,5 @@
       }
     }
   },
-  "x-contract-version": "2.3.0"
+  "x-contract-version": "2.5.0"
 }