@fantastic.dev/better-stripe 0.23.2 → 0.25.0

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

@@ -0,0 +1,157 @@
+import { reclaimReversalClaim } from "./transfers.js";
+import type Stripe from "stripe";
+import { describe, expect, it, vi } from "vitest";
+import { findCommissionReversal } from "./commissionReceipts.js";
+import { executeClaimedSlices } from "./reversalExecution.js";
+import type { Component, RunCtx } from "../helpers.js";
+
+const component = new Proxy(
+  {},
+  {
+    get: (_t, p) =>
+      p === Symbol.for("toReferencePath") ? "betterStripe" : component,
+  },
+) as Component;
+const claim = {
+  replay: false,
+  slices: [
+    {
+      stripeTransferId: "tr_1",
+      from: 0,
+      to: 501,
+      confirmed: 0,
+      commissionTracked: true,
+    },
+  ],
+};
+const fixture = () => {
+  const receipts: {
+    id: string;
+    amount: number;
+    metadata: Record<string, string>;
+  }[] = [];
+  const stripe = {
+    transfers: {
+      createReversal: vi.fn(
+        async (
+          _id: string,
+          params: { amount: number; metadata: Record<string, string> },
+        ) => {
+          const receipt = { id: "trr_1", ...params };
+          receipts.push(receipt);
+          return receipt;
+        },
+      ),
+      listReversals: vi.fn(() =>
+        (async function* () {
+          yield* receipts;
+        })(),
+      ),
+      retrieve: vi.fn(),
+    },
+  };
+  const ctx = { runMutation: vi.fn().mockResolvedValue(null) };
+  const run = (replay = false, confirmed = 0) =>
+    executeClaimedSlices(
+      stripe as unknown as Stripe,
+      component,
+      ctx as unknown as RunCtx,
+      "re_1",
+      { ...claim, replay, slices: [{ ...claim.slices[0], confirmed }] },
+    );
+  return { stripe, ctx, receipts, run };
+};
+
+describe("commission reversal receipt reconciliation", () => {
+  it("recovers a provider success after the ledger confirmation crashed, even beyond the idempotency window", async () => {
+    const f = fixture();
+    f.ctx.runMutation.mockRejectedValueOnce(new Error("ledger offline"));
+    await expect(f.run()).rejects.toThrow("ledger offline");
+    expect(f.receipts).toHaveLength(1);
+    await f.run(true);
+    await f.run(true, 501);
+    expect(f.stripe.transfers.createReversal).toHaveBeenCalledTimes(1);
+    expect(f.ctx.runMutation).toHaveBeenLastCalledWith(expect.anything(), {
+      stripeTransferId: "tr_1",
+      reversedAmount: 501,
+      receipt: { stripeReversalId: "trr_1", operationId: "re_1", amount: 501 },
+    });
+  });
+
+  it("does not mistake another operation's aggregate reversal for this receipt", async () => {
+    const f = fixture();
+    f.receipts.push({
+      id: "trr_other",
+      amount: 501,
+      metadata: { bsReversalOperation: "re_other" },
+    });
+    await expect(f.run(true, 501)).rejects.toThrow(
+      "requires receipt reconciliation",
+    );
+    expect(f.stripe.transfers.retrieve).not.toHaveBeenCalled();
+    expect(f.stripe.transfers.createReversal).not.toHaveBeenCalled();
+    expect(f.ctx.runMutation).not.toHaveBeenCalled();
+  });
+
+  it("retries a failed provider attempt with byte-identical parameters and operation identity", async () => {
+    const f = fixture();
+    f.stripe.transfers.createReversal.mockRejectedValueOnce(
+      new Error("network offline"),
+    );
+    await expect(f.run()).rejects.toThrow("network offline");
+    await f.run(true);
+    expect(f.stripe.transfers.createReversal.mock.calls[0]).toEqual(
+      f.stripe.transfers.createReversal.mock.calls[1],
+    );
+    expect(f.receipts).toHaveLength(1);
+  });
+
+  it("rejects a mismatching receipt amount without confirming money", async () => {
+    const f = fixture();
+    f.receipts.push({
+      id: "trr_bad",
+      amount: 500,
+      metadata: { bsReversalOperation: "re_1" },
+    });
+    await expect(f.run(true)).rejects.toThrow("amount mismatch");
+    expect(f.ctx.runMutation).not.toHaveBeenCalled();
+  });
+
+  it("fails explicitly when the bounded receipt search cannot establish success", async () => {
+    const f = fixture();
+    for (let i = 0; i < 1001; i++)
+      f.receipts.push({ id: `trr_${i}`, amount: 1, metadata: {} });
+    await expect(
+      findCommissionReversal(
+        f.stripe as unknown as Stripe,
+        "tr_1",
+        "re_1",
+        501,
+      ),
+    ).rejects.toThrow("lookup limit exceeded");
+  });
+});
+
+it("operator re-execution delegates tracked commissions to the durable recovery engine", async () => {
+  const f = fixture();
+  const runQuery = vi
+    .fn()
+    .mockResolvedValueOnce({
+      operationId: "re_1",
+      sourceChargeId: "ch_1",
+      _creationTime: 0,
+      slices: [{ stripeTransferId: "tr_1", from: 0, to: 501 }],
+      commissionExposure: { kind: "refund" },
+    })
+    .mockResolvedValueOnce({ role: "affiliate", reversedAmount: 0 });
+  await reclaimReversalClaim(
+    f.stripe as unknown as Stripe,
+    component,
+    { ...f.ctx, runQuery } as unknown as RunCtx,
+    { operationId: "re_1" },
+  );
+  expect(f.stripe.transfers.createReversal).not.toHaveBeenCalled();
+  expect(runQuery).toHaveBeenLastCalledWith(expect.anything(), {
+    sourceChargeId: "ch_1",
+  });
+});

package/src/client/connect/commissionReceipts.ts

@@ -0,0 +1,23 @@
+import type Stripe from "stripe";
+
+/** Locate the exact receipt, never infer operation success from an aggregate. */
+export async function findCommissionReversal(
+  stripe: Stripe,
+  stripeTransferId: string,
+  operationId: string,
+  amount: number,
+) {
+  let count = 0;
+  for await (const receipt of stripe.transfers.listReversals(stripeTransferId, {
+    limit: 100,
+  })) {
+    if (++count > 1000)
+      throw new Error("Commission reversal receipt lookup limit exceeded.");
+    if (receipt.metadata?.bsReversalOperation === operationId) {
+      if (receipt.amount !== amount)
+        throw new Error("Commission reversal receipt amount mismatch.");
+      return receipt;
+    }
+  }
+  return null;
+}

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

@@ -0,0 +1,74 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, it, vi } from "vitest";
+import schema from "../../component/schema.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { PayoutPolicyClient } from "../payoutPolicy.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;
+it("collects, resumes and discards local account state through the public API without Stripe I/O", async () => {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    for (let i = 0; i < 205; i++)
+      await ctx.db.insert("transfers", {
+        stripeTransferId: `tr_${i}`,
+        destinationAccountId: "acct_one",
+        amount: 1000,
+        currency: "usd",
+        role: "store",
+        status: "paid",
+      });
+  });
+  const path = (r: Record<symbol, string>) =>
+    r[symbol].replace("betterStripe/", "").replace(/\/(\w+)$/, ":$1");
+  const ctx = {
+    runQuery: (r: Record<symbol, string>, args: never) =>
+      t.query(makeFunctionReference<"query">(path(r)), args),
+    runMutation: (r: Record<symbol, string>, args: never) =>
+      t.mutation(makeFunctionReference<"mutation">(path(r)), args),
+  } as unknown as RunCtx;
+  const provider = vi.fn(() => {
+    throw Error("Unexpected provider I/O");
+  });
+  const client = new PayoutPolicyClient(component, provider);
+  const opts = {
+    accountId: "acct_one",
+    ownerKey: "owner",
+    operationKey: "read-only",
+    expectedRevision: -1,
+    currency: "usd",
+  };
+  let state = await client.collectSnapshot(ctx, opts);
+  for (
+    let i = 0;
+    i < 100 && state.phase !== "local_ready" && state.phase !== "invalidated";
+    i++
+  )
+    state = await client.collectSnapshot(ctx, {
+      ...opts,
+      expectedStep: state.step,
+    });
+  expect(state).toMatchObject({
+    phase: "local_ready",
+    readOnly: true,
+    sourceCount: 205,
+  });
+  expect(state).not.toHaveProperty("amount");
+  let cleanup = await client.discardSnapshot(ctx, opts);
+  for (let i = 0; i < 100 && cleanup; i++)
+    cleanup = await client.discardSnapshot(ctx, opts);
+  expect(cleanup).toBeNull();
+  expect(provider).not.toHaveBeenCalled();
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSnapshotSources").collect()),
+  ).toEqual([]);
+  expect(
+    await t.run((ctx) => ctx.db.query("transfers").collect()),
+  ).toHaveLength(205);
+});

package/src/client/connect/payoutCollection.ts

@@ -0,0 +1,82 @@
+import type { Infer } from "convex/values";
+import type { snapshotDoc } from "../../component/payoutSnapshots/schema.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { validateIdentity } from "../../component/payoutRelease/helpers.js";
+export type PayoutCollectionState = Infer<typeof snapshotDoc>;
+export type PayoutCollectionScope = {
+  accountId: string;
+  ownerKey: string;
+  operationKey: string;
+};
+export type PayoutCollectionOptions = PayoutCollectionScope & {
+  expectedRevision: number;
+  expectedStep?: number;
+  batchSize?: number;
+};
+/** Resume one bounded local-ledger step. local_ready does not authorize a payout. */
+export async function collectPayoutSnapshot(
+  component: Component,
+  ctx: RunCtx,
+  opts: PayoutCollectionOptions,
+): Promise<PayoutCollectionState> {
+  validateIdentity(opts);
+  if (
+    !Number.isSafeInteger(opts.expectedRevision) ||
+    opts.expectedRevision < -1 ||
+    (opts.expectedStep !== undefined &&
+      (!Number.isSafeInteger(opts.expectedStep) || opts.expectedStep < 0)) ||
+    (opts.batchSize !== undefined &&
+      (!Number.isInteger(opts.batchSize) ||
+        opts.batchSize < 1 ||
+        opts.batchSize > 25))
+  )
+    throw new Error("Invalid local collection revision, step or batch.");
+  const scope = {
+    accountId: opts.accountId,
+    ownerKey: opts.ownerKey,
+    operationKey: opts.operationKey,
+  };
+  const state = (await runMutationOrThrow(
+    ctx,
+    componentRef(component, "payoutSnapshots/mutations/begin"),
+    { ...scope, expectedRevision: opts.expectedRevision },
+  )) as PayoutCollectionState;
+  if (!state.readOnly) throw new Error("Collection is financially bound.");
+  if (opts.expectedStep === undefined) return state;
+  return (await runMutationOrThrow(
+    ctx,
+    componentRef(component, "payoutSnapshots/mutations/advance"),
+    {
+      ...scope,
+      expectedStep: opts.expectedStep,
+      ...(opts.batchSize !== undefined ? { batchSize: opts.batchSize } : {}),
+    },
+  )) as PayoutCollectionState;
+}
+/** Delete only read-only cache state in bounded batches; never financial records. */
+export async function discardPayoutSnapshot(
+  component: Component,
+  ctx: RunCtx,
+  opts: PayoutCollectionScope & { batchSize?: number },
+): Promise<PayoutCollectionState | null> {
+  validateIdentity(opts);
+  if (
+    opts.batchSize !== undefined &&
+    (!Number.isInteger(opts.batchSize) ||
+      opts.batchSize < 1 ||
+      opts.batchSize > 100)
+  )
+    throw new Error("Invalid collection cleanup batch.");
+  return (await runMutationOrThrow(
+    ctx,
+    componentRef(component, "payoutSnapshots/mutations/discard"),
+    {
+      accountId: opts.accountId,
+      ownerKey: opts.ownerKey,
+      operationKey: opts.operationKey,
+      ...(opts.batchSize !== undefined ? { batchSize: opts.batchSize } : {}),
+    },
+  )) as PayoutCollectionState | null;
+}

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

@@ -1,216 +1,6 @@
 // @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";
-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: "custom",
-      status: "ready",
-      revision: 0,
-      operationKey: "enable",
-      country: "US",
-      thresholds: [{ currency: "usd", amount: 1000 }],
-      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,
-  };
-}
+import { setup, scope } from "./payoutExecutionTestHelpers.js";
 it("automatically releases combined creator and affiliate funds exactly once", async () => {
   const s = await setup();
   expect(await s.run()).toMatchObject({