@whooshbang/contract-mock 2.3.1 → 2.5.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ recorded here.
 
 ## Unreleased
 
+## 2.5.0
+
+- Accept the published project configuration scopes while retaining organization and tenant boundaries (FXO-3028).
+- Accept developer-friendly message and question shorthands, optional idempotency keys, inferred types and setup defaults from contracts 2.6.0.
+- Create active webhook endpoints without the retired echo handshake, and expose credential-scoped flat endpoint routes.
+- Preserve explicit request forms, replay semantics, consent evidence and optimistic group updates.
+
+## 2.4.0
+
+- Use contracts 2.5.0 and serve the billing promotion routes, including the approved-price refusal for credit packs (FXO-2994).
+
 ## 2.3.1
 
 - Use contracts 2.4.0 and align scenario metadata with that contract (FXO-2828).

package/README.md

@@ -1,10 +1,10 @@
 # `@whooshbang/contract-mock`
 
 Deterministic, in-memory WhooshBang V1 mock for local contract tests.
-It implements the WhooshBang-owned release candidate without a cloud
+It implements the published WhooshBang contract without a cloud
 organization, network service, database, or production provider.
 
-Run the current release candidate directly from the public npm registry:
+Run the current release directly from the public npm registry:
 
 ```sh
 npx @whooshbang/contract-mock --port 8787
@@ -31,7 +31,7 @@ const response = await mock.fetch(
 );
 ```
 
-Install contracts, SDK and mock from the same published candidate batch.
+Install compatible published contracts, SDK and mock versions.
 The tenant rename has no old-route or old-field aliases.
 
 The mock also executes the organization-scoped administration contract. Use
@@ -42,50 +42,33 @@ The mock also executes the organization-scoped administration contract. Use
 
 ## Billing consumer tests
 
-The mock executes the public wallet, recurring Checkout, billing portal,
-automatic top-up settings/card setup, project slot and attribution routes. Organization administrators may use a
-human session; OAuth grants also need explicit `billing:read` or
-`billing:write`. Project, organization API and machine credentials cannot
-perform financial operations. Attribution uses the organization-level
-`projects:read` and `projects:write` scopes, with administrator membership for
-changes. The MCP tools retain their own scope and action-confirmation checks.
-
-Each account starts with the once-only $2 starter credit and one project slot.
-The fixture project already occupies that slot. Multi-project consumer tests
-must purchase extra slots through recurring Checkout or release the old slot
-with `assignBillingProjectSlots` before creating its replacement. Old projects
-retain their data and recorded test access; new live sends require an active
-slot. The default recurring catalog contains the $5 attribution and project
-add-ons. Team/Agency prices and allowances are not invented: pass synthetic
-offers through `billing.offers` when a consumer test needs a base plan.
-
-Wallet purchases use the approved $5/$10/$25/$50/$100 packs and
-$5/$10/$30/$65/$150 total core credit. Purchased and bonus funds remain
-separate. One accepted live notification debits $0.003 for core delivery;
-shared email adds $0.001 from purchased or starter credit. Paid allowances are
-used first. Tests, provider retries, later failures and answers do not create
-extra charges. Payment replay cannot fund the same Checkout twice.
-
-These are synthetic payments. Creating Checkout returns a local fixture URL;
-reconciliation applies the fixture's payment outcome, not a query parameter
-or caller-supplied `paid` flag. No Stripe request, card charge or webhook proof
-occurs. Set `billing.checkoutOutcome` to a callback returning `paid`, `unpaid`
-or `expired` to exercise recovery. `billing.accounts` may seed exact decimal
-balances for boundary tests. State resets with `control.reset()`.
-
-Automatic top-up starts disabled and requires a confirmed pack, threshold and
-gross monthly cap covering that pack. The mock's card setup is synthetic:
-`billing.autoTopUpSetupOutcome` returns `ready`, `unpaid` or `expired`. It models
-owned setup recovery and rejects stale completion after settings change; it
-does not run a bank charge or a scheduled automatic-purchase engine. Saving a
-card does not grant delivery credit. Actual automatic payment capture, pending
-reservations and gross monthly cap enforcement are tested against the owned
-storage and Stripe SDK boundaries.
+The mock implements saved-card setup, credit purchases, subscription changes,
+automatic top-up settings, project slots and attribution. Use a synthetic human
+session for organization administration; OAuth grants also need `billing:read`
+or `billing:write`. Project and machine credentials cannot perform financial
+operations.
+
+Each organization starts with $2 of welcome credit and one project slot. The fixture
+project already occupies that slot. Assign slots with `assignBillingProjectSlots`
+when testing multiple projects. Test access remains available without a live slot.
+The default recurring catalog contains the $5 attribution and project add-ons.
+Pass synthetic `billing.offers` when a test needs Team or Agency allowances.
+
+Wallet purchases use the $5/$10/$25/$50/$100 packs, granting
+$5/$10/$30/$65/$150 total credit. Purchased and bonus funds stay separate. One
+accepted live message costs $0.003 for core delivery; shared email adds $0.001
+from purchased or welcome credit. Paid allowances are used first. Test sends,
+provider retries, later delivery failures and answers add no charges.
+
+These are synthetic payments. `billing.cardOutcome` returns `ready`, `open` or
+`expired`; `billing.chargeOutcome` returns `paid`, `declined` or `requires_action`.
+No Stripe request or real card charge occurs. Seed decimal balances with
+`billing.accounts` for boundary tests. `control.reset()` clears state.
 
 ```ts
 const mock = createWhooshBangContractMock({
   billing: {
-    checkoutOutcome: () => "unpaid",
+    chargeOutcome: () => "declined",
     accounts: [{
       organizationId: "organization_synthetic",
       starterCreditUsd: "0.003000",
@@ -94,15 +77,18 @@ const mock = createWhooshBangContractMock({
 });
 ```
 
-Paid add-on reconciliation enables the server-enforced attribution preference
-until its paid boundary. Restoring the preference restores visible attribution;
-expiry preserves the preference but removes its paid effect. Paid wallet
-purchases or current recurring periods select 90-day content retention;
-starter-only accounts select seven days. The mock projects that entitlement;
-it does not simulate the storage purge jobs or prove real recipient rendering.
+Automatic top-up starts disabled. Enabling it requires a confirmed pack,
+threshold, saved card and monthly cap. Saving a card alone grants no credit.
+The mock does not run an automatic-purchase scheduler or prove bank settlement.
 
-Each project has one webhook endpoint across its environments. Paused and
-unverified endpoints still occupy it; disabling one releases it. Only a
+Attribution preferences take effect while the paid entitlement is active.
+Expiry preserves the preference but restores branding. A paid wallet purchase
+or current recurring period selects 90-day content retention; welcome-credit-only
+accounts select seven days. The mock projects the entitlement without simulating
+storage purge jobs or proving recipient rendering.
+
+Each project has one webhook endpoint across its environments. Active and
+paused endpoints still occupy it; disabling one releases it. Only a
 terminal failed automatic cycle can receive the one included manual replay.
 `control.runPending()` executes that cycle using the same eight-attempt bound.
 The original cycle and manual recovery together cannot exceed 16 attempts.
@@ -118,7 +104,7 @@ values are local fixtures, not production credential material.
 It can also configure the project recipient experience, upload a bounded PNG
 logo, and manage sparse recipient-copy overrides. The mock normalizes the logo
 before storing it, atomically replaces the prior asset, projects its ID and the
-ten owner-voiced panel values into recipient sessions, and serves the PNG only
+ten customer-editable panel values into recipient sessions, and serves the PNG only
 to that session's exact configured origin. System-owned safety, refusal, pause,
 unavailable, and unsubscribe copy is rejected just as it is by the service.
 
@@ -142,8 +128,9 @@ customer-managed provider resource that still needs manual retirement.
 
 Project credentials also execute the customer-endpoint lifecycle under
 `/v1/projects/{project_id}/environments/{environment_id}/customer-endpoints`:
-create with a one-time secret reveal, verify, bounded-overlap rotation, pause,
-resume, disable, and attempt inspection. Environment-scoped paths need an
+create with a one-time secret reveal, signed diagnostic ping, bounded-overlap rotation, pause,
+resume, disable, and attempt inspection. Endpoints are active immediately; no challenge echo is needed.
+Flat `/v1/customer-endpoints` routes derive scope from a project credential. Environment-scoped paths need an
 environment identifier the bearer does not carry, so
 `CONTRACT_MOCK_FIXTURE_ENVIRONMENTS` publishes the synthetic project and
 environment identifiers the fixture credentials authenticate against. A path
@@ -151,7 +138,7 @@ naming another project or environment is refused as `resource_not_found`.
 
 The same credentials execute the Channel Connections surface under
 `/v1/projects/{project_id}/environments/{environment_id}/connection-providers`
-and `.../channel-connections`: read the catalogue of providers and the
+and `.../channel-connections`: read the catalog of providers and the
 WhooshBang-owned identities an environment may select, then create a
 connection in `pending`, read it, list it, rename or disable it under the
 `row_version` that was read, and archive it. Archiving is terminal, so a
@@ -159,7 +146,7 @@ second archive or an edit to an archived connection is refused. Credential
 material and every reference to one are absent from these responses, including
 for the shared identity WhooshBang operates.
 
-The catalogue presents hosted Slack first as
+The catalog presents hosted Slack first as
 `WhooshBang for Slack — Recommended`. Creating that arm returns a durable
 `authorization_setup`; fetching its mock authorization URL completes the
 provider browser round trip and returns to the Dashboard with the same
@@ -169,7 +156,7 @@ verification/delivery timestamps. `.../{connection_id}/reauthorize` repeats
 the flow on the exact connection, health verifies it, archive is repeat-safe,
 and purge is refused because the tenant does not own the platform installation.
 
-When the owner enables Slack in N17 and exactly one eligible Slack connection
+When Slack is enabled and exactly one eligible Slack connection
 is attached to the notifier, a recipient session offers Slack. Its provider
 handoff binds that exact connection; ambiguity or a lifecycle change fails
 closed. Environment-scoped agent sends may include `connection_id`, and the

package/dist/billing.d.ts

@@ -1,4 +1,4 @@
-import type { AutoTopUpSettings, UpdateAutoTopUpSettingsRequest, BillingAccount, BillingEntitlements, BillingInvoiceCollection, BillingProjectSlots, CardSetup, ContractValidator, CreditPurchase, Problem, ProblemCode, Project, ProjectAttribution, SubscriptionChange, SubscriptionSelection } from "@whooshbang/contracts";
+import type { AutoTopUpSettings, UpdateAutoTopUpSettingsRequest, BillingAccount, BillingEntitlements, BillingInvoiceCollection, BillingProjectSlots, BillingPromotion, BillingPromotions, CardSetup, ContractValidator, CreditPurchase, Problem, ProblemCode, Project, ProjectAttribution, SubscriptionChange, SubscriptionSelection } from "@whooshbang/contracts";
 import type { Hono } from "hono";
 import type { ContractMockBillingOptions, OrganizationScope } from "./types.js";
 interface ChangeState {
@@ -36,6 +36,9 @@ export declare class MockBillingState {
         diagnosticId: string;
     }>;
     readonly offers: BillingEntitlements["offers"];
+    private readonly promotionCodes;
+    private readonly promotionGrants;
+    private readonly promotionRefusals;
     private sequence;
     constructor(options?: ContractMockBillingOptions);
     private id;
@@ -43,6 +46,9 @@ export declare class MockBillingState {
     private record;
     private outcome;
     readAccount(organizationId: string, now?: string): BillingAccount;
+    readPromotions(organizationId: string, now: string): BillingPromotions;
+    /** `refused` covers every unredeemable code identically, by design. */
+    redeemPromotion(organizationId: string, code: string, now: string): BillingPromotion | "refused" | "throttled";
     setReceiptEmail(organizationId: string, email: string | null): void;
     createCardSetup(organizationId: string): CardSetup;
     reconcileCardSetup(organizationId: string, id: string): CardSetup | null;

package/dist/billing.js

@@ -1,4 +1,4 @@
-import { validateAutoTopUpSettings, validateUpdateAutoTopUpSettingsRequest, validateAssignBillingProjectSlotsRequest, validateBillingAccount, validateBillingEntitlements, validateBillingInvoiceCollection, validateCardSetup, validateConfirmSubscriptionChangeRequest, validateCreateCreditPurchaseRequest, validateCreditPurchase, validateBillingProjectSlots, validateProjectAttribution, validateSubscriptionChange, validateSubscriptionSelection, validateUpdateBillingReceiptEmailRequest, validateUpdateProjectAttributionRequest, } from "@whooshbang/contracts";
+import { validateAutoTopUpSettings, validateUpdateAutoTopUpSettingsRequest, validateAssignBillingProjectSlotsRequest, validateBillingAccount, validateBillingEntitlements, validateBillingInvoiceCollection, validateCardSetup, validateConfirmSubscriptionChangeRequest, validateCreateCreditPurchaseRequest, validateCreditPurchase, validateBillingProjectSlots, validateBillingPromotion, validateBillingPromotions, validateProjectAttribution, validateRedeemBillingPromotionRequest, validateSubscriptionChange, validateSubscriptionSelection, validateUpdateBillingReceiptEmailRequest, validateUpdateProjectAttributionRequest, } from "@whooshbang/contracts";
 const packs = [
     { purchase_cents: 500, core_credit_usd: "5.000000" },
     { purchase_cents: 1000, core_credit_usd: "10.000000" },
@@ -24,6 +24,24 @@ const defaultOffers = [
         hide_attribution: false,
     },
 ];
+/** The documented synthetic code every mock offers unless `promotionCodes` is set. */
+const defaultPromotionCodes = [
+    {
+        code: "MOCK-CREDIT",
+        name: "Mock launch credit",
+        benefit: { kind: "message_credit", credit_usd: "10.000000" },
+        benefit_days: 30,
+    },
+];
+/** Refusals one organization may collect before the mock answers 429. */
+const promotionRefusalLimit = 5;
+/** Case, spaces, hyphens and underscores never distinguish two codes. */
+function normalizePromotionCode(code) {
+    return code
+        .trim()
+        .toUpperCase()
+        .replace(/[\s_-]/gu, "");
+}
 const mockCard = {
     brand: "visa",
     last_four: "4242",
@@ -69,6 +87,9 @@ export class MockBillingState {
     attribution = new Map();
     replays = new Map();
     offers;
+    promotionCodes = new Map();
+    promotionGrants = new Map();
+    promotionRefusals = new Map();
     sequence = 0;
     constructor(options = {}) {
         this.options = options;
@@ -95,6 +116,21 @@ export class MockBillingState {
                         offer.hide_attribution !== (offer.kind === "attribution"))))
                 throw new TypeError("Mock billing offers must preserve the approved catalog shape.");
         }
+        for (const seed of options.promotionCodes ?? defaultPromotionCodes) {
+            const normalized = normalizePromotionCode(seed.code);
+            if (normalized.length < 4 ||
+                this.promotionCodes.has(normalized) ||
+                !Number.isSafeInteger(seed.benefit_days) ||
+                seed.benefit_days < 1 ||
+                seed.name.length < 1 ||
+                (seed.benefit.kind === "message_credit" &&
+                    microUsd(seed.benefit.credit_usd) <= 0n) ||
+                (seed.benefit.kind === "shared_emails" &&
+                    (!Number.isSafeInteger(seed.benefit.shared_emails) ||
+                        seed.benefit.shared_emails < 1)))
+                throw new TypeError("Mock promotion codes must be unique, named, and grant a positive benefit.");
+            this.promotionCodes.set(normalized, structuredClone(seed));
+        }
         for (const seed of options.accounts ?? []) {
             if (this.accounts.has(seed.organizationId))
                 throw new TypeError("Duplicate mock billing account.");
@@ -160,6 +196,77 @@ export class MockBillingState {
             receipt_email: account.receiptEmail,
         };
     }
+    readPromotions(organizationId, now) {
+        const at = Date.parse(now);
+        let credit = 0n;
+        let emails = 0;
+        let branding = null;
+        const promotions = (this.promotionGrants.get(organizationId) ?? []).map(({ resource }) => {
+            const live = resource.status === "active" &&
+                resource.ends_at !== null &&
+                Date.parse(resource.ends_at) > at;
+            const current = structuredClone(resource);
+            if (resource.status === "active" && !live)
+                current.status = "expired";
+            if (live && resource.ends_at) {
+                const benefit = resource.benefit;
+                if (benefit.kind === "message_credit")
+                    credit += microUsd(benefit.remaining_usd);
+                else if (benefit.kind === "shared_emails")
+                    emails += benefit.remaining;
+                else if (benefit.kind === "branding" &&
+                    (branding === null || resource.ends_at > branding))
+                    branding = resource.ends_at;
+            }
+            return current;
+        });
+        return {
+            promotional_credit_usd: usd(credit),
+            free_shared_emails: emails,
+            branding_removed_until: branding,
+            promotions,
+        };
+    }
+    /** `refused` covers every unredeemable code identically, by design. */
+    redeemPromotion(organizationId, code, now) {
+        const refusals = this.promotionRefusals.get(organizationId) ?? 0;
+        if (refusals >= promotionRefusalLimit)
+            return "throttled";
+        const normalized = normalizePromotionCode(code);
+        const seed = this.promotionCodes.get(normalized);
+        const grants = this.promotionGrants.get(organizationId) ?? [];
+        if (!seed || grants.some((grant) => grant.code === normalized)) {
+            this.promotionRefusals.set(organizationId, refusals + 1);
+            return "refused";
+        }
+        this.promotionRefusals.delete(organizationId);
+        const benefit = seed.benefit.kind === "message_credit"
+            ? {
+                kind: "message_credit",
+                credit_usd: seed.benefit.credit_usd,
+                remaining_usd: seed.benefit.credit_usd,
+            }
+            : seed.benefit.kind === "shared_emails"
+                ? {
+                    kind: "shared_emails",
+                    shared_emails: seed.benefit.shared_emails,
+                    remaining: seed.benefit.shared_emails,
+                }
+                : { kind: "branding" };
+        const resource = {
+            id: `grn_${(++this.sequence).toString(36).padStart(26, "0")}`,
+            source: "code",
+            name: seed.name,
+            status: "active",
+            starts_at: now,
+            ends_at: new Date(Date.parse(now) + seed.benefit_days * 86_400_000).toISOString(),
+            ended_at: null,
+            benefit,
+        };
+        grants.unshift({ code: normalized, resource });
+        this.promotionGrants.set(organizationId, grants);
+        return structuredClone(resource);
+    }
     setReceiptEmail(organizationId, email) {
         this.account(organizationId).receiptEmail = email;
     }
@@ -215,6 +322,9 @@ export class MockBillingState {
             id,
             purchase_cents: pack.purchase_cents,
             credit_usd: pack.core_credit_usd,
+            // The mock models no pack discounts; the card pays the pack price.
+            charged_usd: `${String(pack.purchase_cents / 100)}.000000`,
+            discount_usd: "0.000000",
             status: "processing",
             failure: null,
             client_secret: null,
@@ -363,6 +473,8 @@ export class MockBillingState {
                 monthly_price_usd: usd(targetTotal),
                 charge_now_usd: usd(targetTotal),
                 unused_time_credit_usd: null,
+                promotion: null,
+                renewal_promotion: null,
                 effective_at: null,
                 expires_at: expires,
                 client_secret: null,
@@ -430,6 +542,8 @@ export class MockBillingState {
             monthly_price_usd: usd(targetTotal),
             charge_now_usd: upgrade ? usd(charge) : "0.000000",
             unused_time_credit_usd: upgrade ? "0.000000" : null,
+            promotion: null,
+            renewal_promotion: null,
             effective_at: upgrade ? null : paid.end,
             expires_at: expires,
             client_secret: null,
@@ -662,7 +776,7 @@ export function addMockBillingRoutes(app, hooks) {
         context.res.headers.set("cache-control", "no-store");
     });
     const responseBodies = new WeakMap();
-    const mutate = (request, organizationId, operation, body, status, action) => {
+    const mutate = (request, organizationId, operation, body, status, action, replayStatus) => {
         const key = request.headers.get("idempotency-key");
         if (!key || key.length < 8 || key.length > 255 || !/^[!-~]+$/u.test(key))
             return hooks.fail("idempotency_key_required", 400);
@@ -684,7 +798,7 @@ export function addMockBillingRoutes(app, hooks) {
                     state.changes.get(id)?.resource)
                 : undefined;
             return new Response(JSON.stringify(fresh ?? prior.body), {
-                status: prior.status,
+                status: replayStatus ?? prior.status,
                 headers: {
                     "content-type": "application/json",
                     "cache-control": "no-store",
@@ -793,6 +907,12 @@ export function addMockBillingRoutes(app, hooks) {
         if (body instanceof Response)
             return body;
         return mutate(context.req.raw, org, "createCreditPurchase", body, 201, () => {
+            // The mock has no pack promotions: the approved charge must be the
+            // pack price, as the real API refuses any other.
+            if (body.approved_charge_usd !== undefined &&
+                body.approved_charge_usd !==
+                    `${String(body.purchase_cents / 100)}.000000`)
+                return hooks.fail("request_invalid", 400, "credit_purchase_price_changed", "This pack's price changed before it was charged, so nothing was charged. Review the price and try again.");
             const purchase = hooks
                 .state()
                 .createCreditPurchase(org, body.purchase_cents, hooks.now());
@@ -897,6 +1017,35 @@ export function addMockBillingRoutes(app, hooks) {
             return replayable(hooks.state().readSlots(org, hooks.projects(), hooks.now()), validateBillingProjectSlots, 200);
         });
     });
+    app.get("/v1/billing/promotions", (context) => {
+        const org = hooks.authorize(context.req.raw, "billing:read", true);
+        return org instanceof Response
+            ? org
+            : hooks.reply(hooks.state().readPromotions(org, hooks.now()), validateBillingPromotions);
+    });
+    app.post("/v1/billing/promotions/redeem", async (context) => {
+        const org = hooks.authorize(context.req.raw, "billing:write", true);
+        if (org instanceof Response)
+            return org;
+        const body = await hooks.read(context.req.raw, validateRedeemBillingPromotionRequest);
+        if (body instanceof Response)
+            return body;
+        return mutate(context.req.raw, org, "redeemBillingPromotion", { code: normalizePromotionCode(body.code) }, 201, () => {
+            const result = hooks
+                .state()
+                .redeemPromotion(org, body.code, hooks.now());
+            if (result === "throttled") {
+                const refused = hooks.fail("rate_limited", 429);
+                const headers = new Headers(refused.headers);
+                headers.set("retry-after", "60");
+                return new Response(refused.body, { status: 429, headers });
+            }
+            // One answer for a wrong, spent, expired or already-redeemed code.
+            if (result === "refused")
+                return hooks.fail("resource_not_found", 404);
+            return replayable(result, validateBillingPromotion, 201);
+        }, 200);
+    });
     for (const method of ["get", "put"]) {
         app[method]("/v1/projects/:projectId/attribution", async (context) => {
             context.header("cache-control", "no-store");