@whooshbang/contract-mock 2.0.0-rc.5 → 2.0.0-rc.6

package/CHANGELOG.md

@@ -5,6 +5,12 @@ recorded here.
 
 ## Unreleased
 
+## 2.0.0-rc.6
+
+### Added
+
+- Deterministic prepaid billing, recurring entitlement and quoted subscription-change scenarios, including insufficient funding and paid attribution enforcement through the rc.6 contract (FXO-2275, FXO-2276, FXO-2814).
+
 ## 2.0.0-rc.5
 
 ### Changed

package/README.md

@@ -31,9 +31,8 @@ const response = await mock.fetch(
 );
 ```
 
-The organization contract batch pairs mock `1.0.0-rc.35` with contracts
-`1.0.0-rc.23` and SDK `1.0.0-rc.32`. Install that batch together after
-publication; the tenant rename has no old-route or old-field aliases.
+Install contracts, SDK and mock from the same published candidate batch.
+The tenant rename has no old-route or old-field aliases.
 
 The mock also executes the organization-scoped administration contract. Use
 `humanSession` (or `otherHumanSession` for isolation tests) with
@@ -41,6 +40,73 @@ The mock also executes the organization-scoped administration contract. Use
 `GET /v1/projects/{project_id}`. Project creation atomically returns synthetic
 `test` and `live` environments and one `Default` notifier for each.
 
+## 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.
+
+```ts
+const mock = createWhooshBangContractMock({
+  billing: {
+    checkoutOutcome: () => "unpaid",
+    accounts: [{
+      organizationId: "organization_synthetic",
+      starterCreditUsd: "0.003000",
+    }],
+  },
+});
+```
+
+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.
+
+Each project has one webhook endpoint across its environments. Paused and
+unverified 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.
+
 The same human session can execute the environment credential lifecycle:
 `GET/POST /v1/projects/{project_id}/environments/{environment_id}/credentials`
 and the nested `rotate` and `revoke` actions. The mock emits a deterministic

package/dist/billing.d.ts

@@ -0,0 +1,77 @@
+import type { AutoTopUpSettings, UpdateAutoTopUpSettingsRequest, AutoTopUpSetup, BillingAccount, BillingEntitlements, BillingProjectSlots, ContractValidator, CreateSubscriptionCheckoutRequest, Problem, ProblemCode, Project, ProjectAttribution, SubscriptionCheckout, SubscriptionChange, WalletCheckout } from "@whooshbang/contracts";
+import type { Hono } from "hono";
+import type { ContractMockBillingOptions, OrganizationScope } from "./types.js";
+interface CheckoutState {
+    readonly organizationId: string;
+    readonly resource: WalletCheckout | SubscriptionCheckout;
+    readonly purchaseCents?: number;
+    readonly selection?: CreateSubscriptionCheckoutRequest;
+    readonly selectedOffers?: BillingEntitlements["offers"];
+    applied: boolean;
+}
+/** Local, isolated financial fixtures. All state resets with the mock. The
+ * production service independently verifies Stripe objects and signatures. */
+export declare class MockBillingState {
+    private readonly options;
+    readonly cardSetups: Map<string, {
+        organizationId: string;
+        revision: number;
+        resource: AutoTopUpSetup;
+        applied: boolean;
+    }>;
+    private readonly automaticSettings;
+    private readonly accounts;
+    readonly checkouts: Map<string, CheckoutState>;
+    readonly changes: Map<string, {
+        organizationId: string;
+        resource: SubscriptionChange;
+        selectedOffers: BillingEntitlements["offers"];
+    }>;
+    readonly attribution: Map<string, boolean>;
+    readonly replays: Map<string, {
+        fingerprint: string;
+        status: number;
+        body: unknown;
+        diagnosticId: string;
+    }>;
+    readonly offers: BillingEntitlements["offers"];
+    private sequence;
+    readAutoTopUp(organizationId: string): AutoTopUpSettings;
+    autoTopUpRevision(organizationId: string): number;
+    updateAutoTopUp(organizationId: string, input: UpdateAutoTopUpSettingsRequest): AutoTopUpSettings;
+    createCardSetup(organizationId: string): AutoTopUpSetup | null;
+    reconcileCardSetup(organizationId: string, id: string): "applied" | "unpaid" | "ignored";
+    constructor(options?: ContractMockBillingOptions);
+    private account;
+    readAccount(organizationId: string): BillingAccount;
+    private changeOffers;
+    private selectionTotal;
+    createChange(organizationId: string, selection: CreateSubscriptionCheckoutRequest, now: string): SubscriptionChange | null;
+    settleChange(organizationId: string, id: string, now: string): SubscriptionChange | null;
+    confirmChange(organizationId: string, id: string, charge: string, now: string): SubscriptionChange | null;
+    readEntitlements(organizationId: string, now: string): BillingEntitlements;
+    readAttribution(organizationId: string, projectId: string, now: string): ProjectAttribution;
+    readSlots(organizationId: string, projects: readonly Project[], now: string): BillingProjectSlots;
+    assignSlots(organizationId: string, ids: readonly string[]): void;
+    addProject(organizationId: string, id: string): void;
+    /** Call once at acceptance, after validation/replay/routing. Provider work and
+     * answers never call this function, so retries and later failures do not debit. */
+    hasCoreFunding(organizationId: string, now: string): boolean;
+    fundLive(organizationId: string, sharedEmail: boolean, now: string): "wallet_insufficient" | "email_credit_insufficient" | null;
+    createCheckout(organizationId: string, selection: number | CreateSubscriptionCheckoutRequest): CheckoutState | null;
+    reconcile(checkout: CheckoutState, now: string): "applied" | "unpaid" | "ignored";
+}
+interface BillingHooks {
+    state(): MockBillingState;
+    now(): string;
+    projects(): readonly Project[];
+    fingerprint(value: unknown): string;
+    authorize(request: Request, scope: OrganizationScope, admin: boolean): string | Response;
+    fail(code: ProblemCode, status: Problem["status"], fieldCode?: string, detail?: string): Response;
+    reply<T>(body: T, validator: ContractValidator<T>, status?: number): Response;
+    read<T>(request: Request, validator: ContractValidator<T>): Promise<T | Response>;
+}
+/** Register only published public resources. Synthetic vendor completion is
+ * driven by a programmatic fixture, never a caller-supplied payment flag. */
+export declare function addMockBillingRoutes(app: Hono, hooks: BillingHooks): void;
+export {};