@whooshbang/contracts 2.4.0 → 2.5.0

package/schemas/events/subscription-activated-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/subscription-activated-v1.schema.json",
-  "x-contract-version": "2.4.0",
+  "x-contract-version": "2.5.0",
   "title": "SubscriptionActivatedEventV1",
   "description": "A subscription became active with a safe public channel binding.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/SubscriptionActivatedEvent"

package/schemas/events/subscription-revoked-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/subscription-revoked-v1.schema.json",
-  "x-contract-version": "2.4.0",
+  "x-contract-version": "2.5.0",
   "title": "SubscriptionRevokedEventV1",
   "description": "A subscription and its safe public channel binding were revoked.",
   "$ref": "whooshbang-event-v1.schema.json#/$defs/SubscriptionRevokedEvent"

package/schemas/events/whooshbang-event-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/events/whooshbang-event-v1.schema.json",
-  "x-contract-version": "2.4.0",
+  "x-contract-version": "2.5.0",
   "title": "WhooshBangEventV1ContractDocument",
   "description": "Strict public customer-event envelope and initial WhooshBang event union.",
   "oneOf": [

package/schemas/fixture-index.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/fixture-index.schema.json",
-  "x-contract-version": "2.4.0",
+  "x-contract-version": "2.5.0",
   "title": "CoreFixtureIndex",
   "description": "The machine-readable index of deterministic C0-02 through C0-04 golden fixtures.",
   "type": "object",

package/schemas/interaction-machine-scenario.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/interaction-machine-scenario.schema.json",
-  "x-contract-version": "2.4.0",
+  "x-contract-version": "2.5.0",
   "title": "InteractionMachineScenario",
   "description": "A deterministic C0-03 interaction, credential, authorization, polling, acknowledgement, or quarantine scenario.",
   "type": "object",

package/schemas/interaction-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/interaction-v1.schema.json",
-  "x-contract-version": "2.4.0",
+  "x-contract-version": "2.5.0",
   "title": "InteractionV1ContractDocument",
   "description": "Provider-neutral confirm, single-select, input, lifecycle, callback-token, and authenticated answer-event contracts.",
   "$defs": {

package/schemas/machine-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/machine-v1.schema.json",
-  "x-contract-version": "2.4.0",
+  "x-contract-version": "2.5.0",
   "title": "MachineV1ContractDocument",
   "description": "Machine-client administration, locally generated credential metadata, durable long-poll, and contiguous acknowledgement contracts.",
   "oneOf": [

package/schemas/provider-capabilities-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/provider-capabilities-v1.schema.json",
-  "x-contract-version": "2.4.0",
+  "x-contract-version": "2.5.0",
   "title": "ProviderCapabilitiesV1",
   "description": "Provider-neutral, renderer-facing delivery and interaction capabilities with explicit degradation.",
   "type": "object",

package/schemas/webhooks/webhook-delivery-case-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/webhooks/webhook-delivery-case-v1.schema.json",
-  "x-contract-version": "2.4.0",
+  "x-contract-version": "2.5.0",
   "title": "WebhookDeliveryCaseSetV1",
   "description": "Deterministic customer webhook response classification, Retry-After, and delivery-bound cases.",
   "type": "object",

package/schemas/webhooks/webhook-signing-vector-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/webhooks/webhook-signing-vector-v1.schema.json",
-  "x-contract-version": "2.4.0",
+  "x-contract-version": "2.5.0",
   "title": "WebhookSigningVectorSetV1",
   "description": "Language-neutral deterministic Standard Webhooks V1 verification vectors. All key material is public synthetic test data and must never be used outside fixtures.",
   "type": "object",

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.5.0",
   "title": "WhooshBangV1ContractDocument",
   "description": "Public request, resource, summary, and Problem Details models for the WhooshBang V1 REST API.",
   "anyOf": [
@@ -394,6 +394,15 @@
     },
     {
       "$ref": "#/$defs/WhoAmI"
+    },
+    {
+      "$ref": "#/$defs/BillingPromotions"
+    },
+    {
+      "$ref": "#/$defs/BillingPromotion"
+    },
+    {
+      "$ref": "#/$defs/RedeemBillingPromotionRequest"
     }
   ],
   "$defs": {
@@ -10782,6 +10791,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 +10808,8 @@
         "id",
         "purchase_cents",
         "credit_usd",
+        "charged_usd",
+        "discount_usd",
         "status",
         "failure",
         "client_secret",
@@ -10813,6 +10830,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 +11435,8 @@
         "monthly_price_usd",
         "charge_now_usd",
         "unused_time_credit_usd",
+        "promotion",
+        "renewal_promotion",
         "effective_at",
         "expires_at",
         "client_secret",
@@ -11467,6 +11498,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": [
             {
@@ -11895,6 +12015,255 @@
         }
       },
       "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
     }
   }
 }