@fantastic.dev/better-stripe 0.23.0 → 0.23.2

package/dist/component/schema.d.ts

@@ -1,4 +1,25 @@
 declare const _default: import("convex/server").SchemaDefinition<{
+    payoutSyncClaims: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        acceptedAt?: number | undefined;
+        acceptedFingerprint?: string | undefined;
+        acceptedGeneration?: number | undefined;
+        accountId: string;
+        generation: number;
+        startedAt: number;
+        status: "accepted" | "pending" | "unknown";
+        stripePayoutId: string;
+    }, {
+        stripePayoutId: import("convex/values").VString<string, "required">;
+        accountId: import("convex/values").VString<string, "required">;
+        generation: import("convex/values").VFloat64<number, "required">;
+        status: import("convex/values").VUnion<"accepted" | "pending" | "unknown", [import("convex/values").VLiteral<"pending", "required">, import("convex/values").VLiteral<"accepted", "required">, import("convex/values").VLiteral<"unknown", "required">], "required", never>;
+        startedAt: import("convex/values").VFloat64<number, "required">;
+        acceptedGeneration: import("convex/values").VFloat64<number | undefined, "optional">;
+        acceptedAt: import("convex/values").VFloat64<number | undefined, "optional">;
+        acceptedFingerprint: import("convex/values").VString<string | undefined, "optional">;
+    }, "required", "acceptedAt" | "acceptedFingerprint" | "acceptedGeneration" | "accountId" | "generation" | "startedAt" | "status" | "stripePayoutId">, {
+        by_stripe_payout_id: ["stripePayoutId", "_creationTime"];
+    }, {}, {}>;
     payoutFeeBalances: import("convex/server").TableDefinition<import("convex/values").VObject<{
         accountId: string;
         amount: number;

package/dist/component/schema.js

@@ -1,3 +1,4 @@
+import { claimsTable as payoutSyncClaimsTable } from "./payoutSync/schema.js";
 import { feeBalancesTable as payoutFeeBalancesTable, claimsTable as payoutReleaseClaimsTable, sourcesTable as payoutSourceAllocationsTable, } from "./payoutRelease/schema.js";
 import { policiesTable, operationsTable } from "./payoutPolicy/schema.js";
 import { currencyTotalsTable } from "./earnings/schema.js";
@@ -10,6 +11,7 @@ import { accountsTable } from "./core/schema";
 import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 export default defineSchema({
+    payoutSyncClaims: payoutSyncClaimsTable,
     payoutFeeBalances: payoutFeeBalancesTable,
     payoutReleaseClaims: payoutReleaseClaimsTable,
     payoutSourceAllocations: payoutSourceAllocationsTable,

package/dist/component/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,IAAI,sBAAsB,EAC1C,WAAW,IAAI,wBAAwB,EACvC,YAAY,IAAI,4BAA4B,GAC7C,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,YAAY,EACZ,wBAAwB,EACxB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,eAAe,YAAY,CAAC;IAC1B,iBAAiB,EAAE,sBAAsB;IACzC,mBAAmB,EAAE,wBAAwB;IAC7C,uBAAuB,EAAE,4BAA4B;IACrD,cAAc,EAAE,aAAa;IAC7B,sBAAsB,EAAE,eAAe;IACvC,cAAc,EAAE,mBAAmB;IACnC,cAAc,EAAE,WAAW;IAC3B,gBAAgB,EAAE,aAAa;IAC/B,cAAc,EAAE,WAAW;IAC3B,oBAAoB,EAAE,iBAAiB;IACvC,qBAAqB,EAAE,gBAAgB;IACvC,eAAe,EAAE,oBAAoB;IACrC,mBAAmB,EAAE,wBAAwB;IAC7C,OAAO;IACP,QAAQ,EAAE,aAAa;IAEvB,WAAW;IACX,QAAQ,EAAE,aAAa;IACvB,MAAM,EAAE,WAAW;IAEnB,UAAU;IACV,aAAa,EAAE,kBAAkB;IACjC,gBAAgB,EAAE,qBAAqB;IACvC,QAAQ,EAAE,aAAa;IAEvB,UAAU;IACV,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,YAAY;IACrB,iBAAiB,EAAE,sBAAsB;IACzC,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE,aAAa;IACvB,SAAS,EAAE,cAAc;IACzB,mBAAmB,EAAE,wBAAwB;IAE7C,WAAW;IACX,aAAa,EAAE,kBAAkB;CAClC,CAAC,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,IAAI,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EACL,gBAAgB,IAAI,sBAAsB,EAC1C,WAAW,IAAI,wBAAwB,EACvC,YAAY,IAAI,4BAA4B,GAC7C,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,YAAY,EACZ,wBAAwB,EACxB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,eAAe,YAAY,CAAC;IAC1B,gBAAgB,EAAE,qBAAqB;IACvC,iBAAiB,EAAE,sBAAsB;IACzC,mBAAmB,EAAE,wBAAwB;IAC7C,uBAAuB,EAAE,4BAA4B;IACrD,cAAc,EAAE,aAAa;IAC7B,sBAAsB,EAAE,eAAe;IACvC,cAAc,EAAE,mBAAmB;IACnC,cAAc,EAAE,WAAW;IAC3B,gBAAgB,EAAE,aAAa;IAC/B,cAAc,EAAE,WAAW;IAC3B,oBAAoB,EAAE,iBAAiB;IACvC,qBAAqB,EAAE,gBAAgB;IACvC,eAAe,EAAE,oBAAoB;IACrC,mBAAmB,EAAE,wBAAwB;IAC7C,OAAO;IACP,QAAQ,EAAE,aAAa;IAEvB,WAAW;IACX,QAAQ,EAAE,aAAa;IACvB,MAAM,EAAE,WAAW;IAEnB,UAAU;IACV,aAAa,EAAE,kBAAkB;IACjC,gBAAgB,EAAE,qBAAqB;IACvC,QAAQ,EAAE,aAAa;IAEvB,UAAU;IACV,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,YAAY;IACrB,iBAAiB,EAAE,sBAAsB;IACzC,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE,aAAa;IACvB,SAAS,EAAE,cAAc;IACzB,mBAAmB,EAAE,wBAAwB;IAE7C,WAAW;IACX,aAAa,EAAE,kBAAkB;CAClC,CAAC,CAAC"}

package/docs/read-contracts.md

@@ -126,14 +126,49 @@ accounts and direct callers to the new methods. Their historical scans remain
 subject to Convex read limits; migrate busy accounts to the maintained summaries.
 Full referred-sale history uses `paginateTransfersByAccount`, not the preview.
 
+## Current payout observations
+
+Call `betterStripe.syncPayoutFromStripe(ctx, { stripePayoutId, scope })` from an
+authorized server action. Use `scope: { type: "connected", accountId }` for the
+recipient's connected account or explicitly use `scope: { type: "platform" }`
+for a platform payout. Resolve scope from trusted host configuration and recipient
+ownership. Never accept an arbitrary account or platform mode from the browser.
+The method reads Stripe and updates the existing component payout record; it
+never creates, cancels or releases a bank payout.
+
+The operation works for Stripe-managed automatic and manually triggered payouts.
+It retrieves the current payout under that account's Stripe request scope and
+validates the payout identity, original amount and currency, status, arrival date,
+method and failure details. It does not require a mature balance transaction or a
+manual execution claim. A current status observation does not establish funding
+maturity, payout eligibility or a policy minimum.
+
+A durable claim assigns each read a per-payout generation. Only the newest
+claimed generation can commit. A delayed older response returns `superseded`
+without changing the financial row. A successful result returns `accepted`, its
+generation, `changed` and the stored payout. Identical observations preserve the
+financial row and exact currency totals. Retrying the same committed generation
+also preserves its acceptance timestamp. A later current provider observation
+can legitimately change paid to failed; no terminal-status ranking is applied.
+
+Provider errors or invalid snapshots throw and leave the last accepted financial
+observation intact. The latest incomplete claim becomes unknown when that marker
+can be saved. A lost mutation response may leave a pending or already accepted
+claim. Retry the operation to obtain a new generation and read Stripe again.
+Never substitute the webhook event body when the current provider read fails.
+The claim table holds reconciliation metadata, not a second money ledger.
+
+This method does not yet replace the existing signed webhook dispatcher. The
+prepared generation must be integrated into the shared host callback transaction.
+Until that wiring is adopted, legacy webhook deliveries still apply
+event-body snapshots and can regress on distinct out-of-order events. Do not call
+this method and then blindly apply an old event-body upsert afterward.
+
 ## Payout failures
 
 Component payout rows and live `RecipientPayoutRow` snapshots expose optional
-`failureCode` and `failureMessage`. Signed payout events write the provider's
-current snapshot to the existing payout identity. A later snapshot with absent
-or null provider failure fields clears stored details. Legacy rows remain valid.
-Ordinary event replay is deduplicated. This is snapshot reconciliation and does
-not guarantee convergence for globally out-of-order events.
+`failureCode` and `failureMessage`. A later accepted snapshot with absent or null
+provider failure fields clears stored details. Legacy rows remain valid.
 
 Host apps should translate known codes into safe recovery instructions and a
 settings link. Do not log or blindly render raw provider messages. Authorize

package/docs/settlement.md

@@ -459,6 +459,12 @@ the currency. Existing package claims supply their immutable allocations on
 subsequent calls; use `payouts: []` to verify/reconcile already imported history.
 The same flow supports explicit accounting for automatic historical payouts.
 
+For a verified bank return, holding-age proof retains the original paid
+principal and adds the returned credit at its availability time. The returned
+claim contributes no currently paid source allocation. Net provider fees still
+reduce the combined unpaid balance. Replaying adoption preserves the same claim;
+a later release can include returned cash and new funding exactly once.
+
 The package retrieves actual recipient funding and payout receipts, verifies
 full history against live available/pending cash, and validates each allocation
 against source maturity at the historical payout date. Future credits and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.23.0",
+  "version": "0.23.2",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",

package/src/client/connect/payoutAdoption.test.ts

@@ -1,247 +1,12 @@
 // @vitest-environment edge-runtime
-import { convexTest } from "convex-test";
-import { makeFunctionReference } from "convex/server";
 import { expect, it, vi } from "vitest";
 import type Stripe from "stripe";
-import schema from "../../component/schema.js";
-import type { Component, RunCtx } from "../helpers.js";
-import { releaseRecipientPayout } from "./payoutExecution.js";
-import { adoptRecipientPayouts } from "./payoutAdoption.js";
-const modules = import.meta.glob("../../component/**/*.*s");
-const symbol = Symbol.for("toReferencePath");
-const component = {
-  payoutPolicy: {
-    queries: { get: { [symbol]: "betterStripe/payoutPolicy/queries/get" } },
-  },
-} as unknown as Component;
-const scope = {
-  accountId: "acct_recipient",
-  ownerKey: "owner",
-  operationKey: "release-1",
-  currency: "usd",
-  independentLiabilities: 0,
-};
-async function setup(amounts = [600, 400]) {
-  const t = convexTest(schema, modules);
-  await t.run(async (ctx) => {
-    await ctx.db.insert("payoutPolicies", {
-      accountId: scope.accountId,
-      ownerKey: scope.ownerKey,
-      mode: "stripe_managed",
-      status: "ready",
-      revision: 0,
-      operationKey: "enable",
-      country: "US",
-      thresholds: [],
-      holdDeadline: Date.now() + 86400000,
-    });
-    for (let i = 0; i < amounts.length; i++)
-      await ctx.db.insert("transfers", {
-        stripeTransferId: `tr_${i}`,
-        destinationAccountId: scope.accountId,
-        sourceChargeId: `ch_${i}`,
-        amount: amounts[i],
-        currency: "usd",
-        status: "paid",
-        role: i % 2 ? "affiliate" : "store",
-      });
-  });
-  const path = (ref: Record<symbol, string>) =>
-    ref[symbol].replace("betterStripe/", "").replace(/\/(\w+)$/, ":$1");
-  const ctx = {
-    runQuery: (ref: Record<symbol, string>, args: never) =>
-      t.query(makeFunctionReference<"query">(path(ref)), args),
-    runMutation: (ref: Record<symbol, string>, args: never) =>
-      t.mutation(makeFunctionReference<"mutation">(path(ref)), args),
-  } as unknown as RunCtx;
-  let transactions = amounts.map((amount, i) => ({
-    id: `txn_${i}`,
-    source: `py_${i}`,
-    amount,
-    fee: 0,
-    net: amount,
-    currency: "usd",
-    created: 100,
-    available_on: 200,
-    status: "available",
-    type: "payment",
-    exchange_rate: null,
-  }));
-  let payout: Record<string, unknown> | undefined;
-  const provider = {
-    accounts: {
-      listExternalAccounts: vi.fn(async () => ({
-        data: [
-          {
-            id: "ba_one",
-            object: "bank_account",
-            currency: "usd",
-            default_for_currency: true,
-          },
-        ],
-        has_more: false,
-      })),
-    },
-    transfers: {
-      retrieve: vi.fn(async (id: string) => {
-        const i = Number(id.slice(3));
-        return {
-          id,
-          destination: scope.accountId,
-          destination_payment: `py_${i}`,
-          source_transaction: `ch_${i}`,
-          amount: amounts[i],
-          currency: "usd",
-          amount_reversed: 0,
-        };
-      }),
-      listReversals: vi.fn(async () => ({ data: [], has_more: false })),
-    },
-    charges: {
-      retrieve: vi.fn(async (id: string) => {
-        const i = Number(id.slice(3));
-        return {
-          id,
-          source_transfer: `tr_${i}`,
-          amount: amounts[i],
-          currency: "usd",
-          paid: true,
-          status: "succeeded",
-          balance_transaction: `txn_${i}`,
-        };
-      }),
-    },
-    balanceTransactions: {
-      list: vi.fn(async (params: { source?: string; limit?: number }) => ({
-        data: params.source
-          ? transactions.filter((t) => t.source === params.source)
-          : transactions.slice(0, params.limit),
-        has_more: false,
-      })),
-      retrieve: vi.fn(async (id: string) =>
-        transactions.find((t) => t.id === id),
-      ),
-    },
-    balance: {
-      retrieve: vi.fn(async () => ({
-        available: [
-          {
-            currency: "usd",
-            amount: transactions
-              .filter((t) => t.status === "available")
-              .reduce((a, t) => a + t.net, 0),
-            source_types: {
-              card: transactions
-                .filter((t) => t.status === "available")
-                .reduce((a, t) => a + t.net, 0),
-            },
-          },
-        ],
-        pending: [],
-      })),
-    },
-    payouts: {
-      list: vi.fn(async () => ({
-        data: payout ? [payout] : [],
-        has_more: false,
-      })),
-      retrieve: vi.fn(async () => payout),
-      create: vi.fn(
-        async (params: {
-          amount: number;
-          currency: string;
-          metadata: object;
-        }) => {
-          payout = {
-            id: "po_one",
-            ...params,
-            status: "paid",
-            automatic: false,
-            method: "standard",
-            type: "bank_account",
-            source_type: "card",
-            destination: "ba_one",
-            created: Math.floor(Date.now() / 1000),
-            arrival_date: Math.floor(Date.now() / 1000),
-            balance_transaction: "txn_debit",
-            failure_balance_transaction: null,
-            reversed_by: null,
-          };
-          transactions = [
-            {
-              id: "txn_debit",
-              source: "po_one",
-              amount: -params.amount,
-              fee: 0,
-              net: -params.amount,
-              currency: "usd",
-              created: Math.floor(Date.now() / 1000),
-              available_on: Math.floor(Date.now() / 1000),
-              status: "available",
-              type: "payout",
-              exchange_rate: null,
-            },
-            ...transactions,
-          ];
-          return payout;
-        },
-      ),
-    },
-  };
-  const verify = vi.fn(async () => ({
-    status: "verified" as const,
-    policy: (await t.run((ctx) => ctx.db.query("payoutPolicies").first()))!,
-  }));
-  const run = (extra = {}) =>
-    releaseRecipientPayout(
-      provider as unknown as Stripe,
-      component,
-      ctx,
-      { ...scope, ...extra },
-      verify,
-    );
-  return {
-    t,
-    ctx,
-    provider,
-    verify,
-    run,
-    setTransactions: (rows: typeof transactions) => {
-      transactions = rows;
-    },
-    transactions: () => transactions,
-  };
-}
-async function historical() {
-  const s = await setup();
-  await s.provider.payouts.create({
-    amount: 1000,
-    currency: "usd",
-    metadata: {},
-  });
-  s.provider.payouts.create.mockClear();
-  const opts = {
-    accountId: scope.accountId,
-    ownerKey: scope.ownerKey,
-    currency: "usd",
-    expectedRevision: 0,
-    payouts: [
-      {
-        stripePayoutId: "po_one",
-        allocations: [
-          { stripeTransferId: "tr_0", amount: 600 },
-          { stripeTransferId: "tr_1", amount: 400 },
-        ],
-      },
-    ],
-  };
-  const adopt = (extra = {}) =>
-    adoptRecipientPayouts(s.provider as unknown as Stripe, component, s.ctx, {
-      ...opts,
-      ...extra,
-    });
-  return { ...s, adopt, opts };
-}
+import {
+  component,
+  scope,
+  setup,
+  historical,
+} from "./payoutAdoptionTestHelpers.js";
 it("imports a verified historical manual payout with exact source allocations", async () => {
   const s = await historical();
   expect(await s.adopt()).toMatchObject({

package/src/client/connect/payoutAdoption.ts

@@ -303,8 +303,9 @@ export async function adoptRecipientPayouts(
     )) as { claims: Claim[] };
     claims.push(...result.claims);
   }
-  const paid = claims
-    .filter((c) => c.status === "paid")
+  // Returned cash gets a fresh holding age after consuming its original principal.
+  const originalPaid = claims
+    .filter((c) => c.status === "paid" || c.status === "returned")
     .flatMap((c) => c.allocations);
   const fees = claims.reduce((total, c) => add(total, c.providerFee ?? 0), 0);
   const returned = proofPayouts
@@ -315,7 +316,7 @@ export async function adoptRecipientPayouts(
   const oldestHeldAt = oldestUnpaidFunding(
     opts.currency,
     sources,
-    paid,
+    originalPaid,
     fees,
     returned,
   );

package/src/client/connect/payoutAdoptionTestHelpers.ts

@@ -0,0 +1,253 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { vi } from "vitest";
+import type Stripe from "stripe";
+import schema from "../../component/schema.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { releaseRecipientPayout } from "./payoutExecution.js";
+import { adoptRecipientPayouts } from "./payoutAdoption.js";
+const modules = import.meta.glob("../../component/**/*.*s");
+const symbol = Symbol.for("toReferencePath");
+export const component = {
+  payoutPolicy: {
+    queries: { get: { [symbol]: "betterStripe/payoutPolicy/queries/get" } },
+  },
+} as unknown as Component;
+export const scope = {
+  accountId: "acct_recipient",
+  ownerKey: "owner",
+  operationKey: "release-1",
+  currency: "usd",
+  independentLiabilities: 0,
+};
+export async function setup(amounts = [600, 400], currency = "usd") {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    await ctx.db.insert("payoutPolicies", {
+      accountId: scope.accountId,
+      ownerKey: scope.ownerKey,
+      mode: "stripe_managed",
+      status: "ready",
+      revision: 0,
+      operationKey: "enable",
+      country: "US",
+      thresholds: [],
+      holdDeadline: Date.now() + 86400000,
+    });
+    for (let i = 0; i < amounts.length; i++)
+      await ctx.db.insert("transfers", {
+        stripeTransferId: `tr_${i}`,
+        destinationAccountId: scope.accountId,
+        sourceChargeId: `ch_${i}`,
+        amount: amounts[i],
+        currency,
+        status: "paid",
+        role: i % 2 ? "affiliate" : "store",
+      });
+  });
+  const path = (ref: Record<symbol, string>) =>
+    ref[symbol].replace("betterStripe/", "").replace(/\/(\w+)$/, ":$1");
+  const ctx = {
+    runQuery: (ref: Record<symbol, string>, args: never) =>
+      t.query(makeFunctionReference<"query">(path(ref)), args),
+    runMutation: (ref: Record<symbol, string>, args: never) =>
+      t.mutation(makeFunctionReference<"mutation">(path(ref)), args),
+  } as unknown as RunCtx;
+  let transactions = amounts.map((amount, i) => ({
+    id: `txn_${i}`,
+    source: `py_${i}`,
+    amount,
+    fee: 0,
+    net: amount,
+    currency,
+    created: 100,
+    available_on: 200,
+    status: "available",
+    type: "payment",
+    exchange_rate: null,
+  }));
+  let payout: Record<string, unknown> | undefined;
+  const history: Record<string, unknown>[] = [];
+  const provider = {
+    accounts: {
+      listExternalAccounts: vi.fn(async () => ({
+        data: [
+          {
+            id: "ba_one",
+            object: "bank_account",
+            currency,
+            default_for_currency: true,
+          },
+        ],
+        has_more: false,
+      })),
+    },
+    transfers: {
+      retrieve: vi.fn(async (id: string) => {
+        const i = Number(id.slice(3));
+        return {
+          id,
+          destination: scope.accountId,
+          destination_payment: `py_${i}`,
+          source_transaction: `ch_${i}`,
+          amount: amounts[i],
+          currency,
+          amount_reversed: 0,
+        };
+      }),
+      listReversals: vi.fn(async () => ({ data: [], has_more: false })),
+    },
+    charges: {
+      retrieve: vi.fn(async (id: string) => {
+        const i = Number(id.slice(3));
+        return {
+          id,
+          source_transfer: `tr_${i}`,
+          amount: amounts[i],
+          currency,
+          paid: true,
+          status: "succeeded",
+          balance_transaction: `txn_${i}`,
+        };
+      }),
+    },
+    balanceTransactions: {
+      list: vi.fn(async (params: { source?: string; limit?: number }) => ({
+        data: params.source
+          ? transactions.filter((t) => t.source === params.source)
+          : transactions.slice(0, params.limit),
+        has_more: false,
+      })),
+      retrieve: vi.fn(async (id: string) =>
+        transactions.find((t) => t.id === id),
+      ),
+    },
+    balance: {
+      retrieve: vi.fn(async () => ({
+        available: [
+          {
+            currency,
+            amount: transactions
+              .filter((t) => t.status === "available")
+              .reduce((a, t) => a + t.net, 0),
+            source_types: {
+              card: transactions
+                .filter((t) => t.status === "available")
+                .reduce((a, t) => a + t.net, 0),
+            },
+          },
+        ],
+        pending: [],
+      })),
+    },
+    payouts: {
+      list: vi.fn(async () => ({
+        data: [...history].reverse(),
+        has_more: false,
+      })),
+      retrieve: vi.fn(async (id?: string) =>
+        id ? history.find((p) => p.id === id) : payout,
+      ),
+      create: vi.fn(
+        async (params: {
+          amount: number;
+          currency: string;
+          metadata: object;
+        }) => {
+          const id = history.length ? `po_${history.length + 1}` : "po_one";
+          const debitId = history.length
+            ? `txn_debit_${history.length + 1}`
+            : "txn_debit";
+          payout = {
+            id,
+            ...params,
+            status: "paid",
+            automatic: false,
+            method: "standard",
+            type: "bank_account",
+            source_type: "card",
+            destination: "ba_one",
+            created: Math.floor(Date.now() / 1000),
+            arrival_date: Math.floor(Date.now() / 1000),
+            balance_transaction: debitId,
+            failure_balance_transaction: null,
+            reversed_by: null,
+          };
+          transactions = [
+            {
+              id: debitId,
+              source: id,
+              amount: -params.amount,
+              fee: 0,
+              net: -params.amount,
+              currency,
+              created: Math.floor(Date.now() / 1000),
+              available_on: Math.floor(Date.now() / 1000),
+              status: "available",
+              type: "payout",
+              exchange_rate: null,
+            },
+            ...transactions,
+          ];
+          history.push(payout);
+          return payout;
+        },
+      ),
+    },
+  };
+  const verify = vi.fn(async () => ({
+    status: "verified" as const,
+    policy: (await t.run((ctx) => ctx.db.query("payoutPolicies").first()))!,
+  }));
+  const run = (extra = {}) =>
+    releaseRecipientPayout(
+      provider as unknown as Stripe,
+      component,
+      ctx,
+      { ...scope, currency, ...extra },
+      verify,
+    );
+  return {
+    t,
+    ctx,
+    provider,
+    verify,
+    run,
+    setTransactions: (rows: typeof transactions) => {
+      transactions = rows;
+    },
+    transactions: () => transactions,
+  };
+}
+export async function historical(currency = "usd") {
+  const amounts = [600, 400];
+  const s = await setup(amounts, currency);
+  await s.provider.payouts.create({
+    amount: 1000,
+    currency,
+    metadata: {},
+  });
+  s.provider.payouts.create.mockClear();
+  const opts = {
+    accountId: scope.accountId,
+    ownerKey: scope.ownerKey,
+    currency,
+    expectedRevision: 0,
+    payouts: [
+      {
+        stripePayoutId: "po_one",
+        allocations: [
+          { stripeTransferId: "tr_0", amount: 600 },
+          { stripeTransferId: "tr_1", amount: 400 },
+        ],
+      },
+    ],
+  };
+  const adopt = (extra = {}) =>
+    adoptRecipientPayouts(s.provider as unknown as Stripe, component, s.ctx, {
+      ...opts,
+      ...extra,
+    });
+  return { ...s, adopt, opts, amounts };
+}