@fantastic.dev/better-stripe 0.24.0 → 0.25.0

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({

package/src/client/connect/payoutExecutionTestHelpers.ts

@@ -0,0 +1,213 @@
+// @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";
+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]) {
+  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,
+  };
+}

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

@@ -0,0 +1,145 @@
+// @vitest-environment edge-runtime
+import { afterEach, expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import { setup, scope, component } from "./payoutExecutionTestHelpers.js";
+import { reconcileRecipientPayout } from "./payoutReconciliation.js";
+import { PayoutWorkerClient } from "./payoutWorker.js";
+import { changeBalance } from "../../component/affiliateRecovery/accounting.js";
+afterEach(() => vi.useRealTimers());
+async function worker(amounts?: number[]) {
+  const s = await setup(amounts);
+  const client = new PayoutWorkerClient(
+    component,
+    (_ctx, opts) => s.run(opts),
+    (_ctx, opts) =>
+      reconcileRecipientPayout(
+        s.provider as unknown as Stripe,
+        component,
+        s.ctx,
+        opts,
+      ),
+  );
+  const run = () => client.run(s.ctx, scope);
+  return { ...s, client, run };
+}
+it("the recurring worker releases combined money once, records its result and waits for the next attempt", async () => {
+  const s = await worker();
+  expect(await s.run()).toMatchObject({
+    status: "completed",
+    job: { lastReason: "paid", hasOperation: false },
+    payout: { claim: { amount: 1000, status: "paid" } },
+  });
+  expect(await s.run()).toMatchObject({ status: "held", reason: "not_due" });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+  const state = await s.client.get(s.ctx, scope);
+  expect(state?.nextAttemptAt).toBeGreaterThan(Date.now());
+});
+it("the next recurring attempt carries below-minimum balances and pays when new funding qualifies", async () => {
+  vi.useFakeTimers();
+  const amounts = [599, 400];
+  const s = await worker(amounts);
+  expect(await s.run()).toMatchObject({
+    payout: { status: "held", reason: "below_threshold", matureUnpaid: 999 },
+  });
+  vi.advanceTimersByTime(300000);
+  expect(await s.run()).toMatchObject({
+    payout: { reason: "below_threshold" },
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+  amounts.push(1);
+  await s.t.run((ctx) =>
+    ctx.db.insert("transfers", {
+      stripeTransferId: "tr_2",
+      destinationAccountId: scope.accountId,
+      sourceChargeId: "ch_2",
+      amount: 1,
+      currency: "usd",
+      status: "paid",
+      role: "affiliate",
+    }),
+  );
+  s.setTransactions([
+    ...s.transactions(),
+    {
+      ...s.transactions()[0],
+      id: "txn_2",
+      source: "py_2",
+      amount: 1,
+      net: 1,
+    },
+  ]);
+  vi.advanceTimersByTime(300000);
+  expect(await s.run()).toMatchObject({
+    payout: { claim: { status: "paid", amount: 1000 } },
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});
+it("unknown provider outcomes keep the same durable attempt and never blindly recreate", async () => {
+  vi.useFakeTimers();
+  const s = await worker();
+  s.provider.payouts.create.mockRejectedValueOnce(
+    new Error("network outcome unknown"),
+  );
+  await expect(s.run()).rejects.toThrow("network outcome unknown");
+  const first = await s.client.get(s.ctx, scope);
+  expect(first).toMatchObject({
+    hasOperation: true,
+    lastReason: "worker_error",
+  });
+  vi.advanceTimersByTime(300000);
+  expect(await s.run()).toMatchObject({
+    payout: { status: "held", reason: "payout_unidentified" },
+  });
+  expect((await s.client.get(s.ctx, scope))?.operationKey).toBe(
+    first?.operationKey,
+  );
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});
+it("concurrent recurring workers share the lease instead of canceling each other's unattempted claim", async () => {
+  const s = await worker();
+  const results = await Promise.all([s.run(), s.run()]);
+  expect(results.map((r) => r.status).sort()).toEqual(["completed", "held"]);
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});
+it("a successful payout with a lost response is recovered after opting out without another create", async () => {
+  vi.useFakeTimers();
+  const s = await worker();
+  const create = s.provider.payouts.create.getMockImplementation()!;
+  s.provider.payouts.create.mockImplementationOnce(async (params) => {
+    await create(params);
+    throw new Error("response lost after provider accepted");
+  });
+  await expect(s.run()).rejects.toThrow(/response lost/);
+  await s.t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "usd", { outstandingDebt: 100 }),
+  );
+  await s.t.run(async (ctx) => {
+    const policy = await ctx.db.query("payoutPolicies").first();
+    await ctx.db.patch("payoutPolicies", policy!._id, {
+      mode: "stripe_managed",
+      thresholds: [],
+      revision: 1,
+    });
+  });
+  vi.advanceTimersByTime(300000);
+  expect(await s.run()).toMatchObject({
+    payout: { claim: { status: "paid", amount: 1000 } },
+    job: { hasOperation: false },
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});
+it("reports affiliate recovery holds before a fresh attempt without creating a payout", async () => {
+  const s = await worker();
+  await s.t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "usd", { outstandingDebt: 100 }),
+  );
+  expect(await s.run()).toMatchObject({
+    status: "held",
+    reason: "affiliate_recovery_pending",
+  });
+  expect(await s.client.get(s.ctx, scope)).toMatchObject({
+    lastReason: "affiliate_recovery_pending",
+    hasOperation: false,
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});