@fantastic.dev/better-stripe 0.22.0 → 0.23.1

package/src/client/connect/payoutAdoptionAllocation.ts

@@ -0,0 +1,106 @@
+import { addSummaryAmounts as add } from "../../component/earnings/arithmetic.js";
+export type HistoricalFundingSource = {
+  stripeTransferId: string;
+  currency: string;
+  transactions: {
+    net: number;
+    created: number;
+    availableOn: number;
+    status: string;
+  }[];
+};
+export type HistoricalFundingPayout = {
+  stripePayoutId: string;
+  currency: string;
+  amount: number;
+  created: number;
+  returnedAt?: number;
+  allocations: { stripeTransferId: string; amount: number }[];
+};
+function integer(n: number) {
+  if (!Number.isSafeInteger(n))
+    throw new Error("Invalid historical funding arithmetic.");
+  return n;
+}
+function timestamp(n: number) {
+  if (integer(n) < 0) throw new Error("Invalid historical funding timestamp.");
+}
+/** Validate explicit historical cash provenance, not today's still-unpaid entitlement. */
+export function validateHistoricalFunding(
+  sources: HistoricalFundingSource[],
+  payouts: HistoricalFundingPayout[],
+): void {
+  const byId = new Map<string, HistoricalFundingSource>();
+  for (const s of sources) {
+    if (byId.has(s.stripeTransferId))
+      throw new Error("Duplicate historical funding source.");
+    if (!/^tr_\w+$/.test(s.stripeTransferId) || !/^[a-z]{3}$/.test(s.currency))
+      throw new Error("Invalid historical funding source.");
+    for (const t of s.transactions) {
+      integer(t.net);
+      timestamp(t.created);
+      timestamp(t.availableOn);
+      if (!["available", "pending"].includes(t.status))
+        throw new Error("Invalid historical funding status.");
+    }
+    byId.set(s.stripeTransferId, s);
+  }
+  const ids = new Set<string>();
+  for (const p of payouts) {
+    if (ids.has(p.stripePayoutId))
+      throw new Error("Duplicate historical payout.");
+    ids.add(p.stripePayoutId);
+    if (
+      !/^po_\w+$/.test(p.stripePayoutId) ||
+      !/^[a-z]{3}$/.test(p.currency) ||
+      integer(p.amount) <= 0
+    )
+      throw new Error("Invalid historical payout principal.");
+    timestamp(p.created);
+    if (p.returnedAt !== undefined) {
+      timestamp(p.returnedAt);
+      if (p.returnedAt < p.created)
+        throw new Error("Historical payout return predates the payout.");
+    }
+  }
+  const prior: HistoricalFundingPayout[] = [];
+  for (const p of [...payouts].sort(
+    (a, b) =>
+      a.created - b.created || a.stripePayoutId.localeCompare(b.stripePayoutId),
+  )) {
+    const seen = new Set<string>();
+    let principal = 0;
+    for (const a of p.allocations) {
+      if (seen.has(a.stripeTransferId))
+        throw new Error("Duplicate historical source allocation.");
+      seen.add(a.stripeTransferId);
+      if (integer(a.amount) <= 0)
+        throw new Error("Invalid historical principal allocation.");
+      principal = add(principal, a.amount);
+      const s = byId.get(a.stripeTransferId);
+      if (!s)
+        throw new Error("Historical payout funding source is unavailable.");
+      if (s.currency !== p.currency)
+        throw new Error("Historical payout currency allocation mismatch.");
+      let capacity = 0;
+      for (const t of s.transactions)
+        if (
+          t.status === "available" &&
+          Math.max(t.created, t.availableOn) <= p.created
+        )
+          capacity = add(capacity, t.net);
+      for (const old of prior)
+        if (old.returnedAt === undefined || old.returnedAt > p.created)
+          for (const allocation of old.allocations)
+            if (allocation.stripeTransferId === s.stripeTransferId)
+              capacity = add(capacity, -allocation.amount);
+      if (a.amount > capacity)
+        throw new Error(
+          "Historical payout exceeds verified mature source funding.",
+        );
+    }
+    if (principal !== p.amount)
+      throw new Error("Historical allocations do not equal payout principal.");
+    prior.push(p);
+  }
+}

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 };
+}

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

@@ -396,3 +396,19 @@ it("rejects a payout sent to a different bank than the immutable claim", async (
     await s.t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
   ).toMatchObject([{ paidAmount: 0, reservedAmount: 1000 }]);
 });
+it("reconciles an explicitly adopted automatic payout without a package claim marker", async () => {
+  const s = await setup();
+  await s.t.run(async (ctx) => {
+    const c = await ctx.db.query("payoutReleaseClaims").first();
+    await ctx.db.patch("payoutReleaseClaims", c!._id, {
+      historical: true,
+      stripePayoutId: "po_one",
+      destinationId: "ba_one",
+    });
+  });
+  s.setPayout({ automatic: true, metadata: {} as never });
+  expect(await s.reconcile()).toMatchObject({
+    status: "updated",
+    claim: { status: "paid", historical: true },
+  });
+});

package/src/client/connect/payoutReconciliation.ts

@@ -132,7 +132,7 @@ export async function reconcileRecipientPayout(
   const receipt = await getRecipientPayoutReceipt(stripe, {
     accountId: options.accountId,
     stripePayoutId: payoutId,
-    operationKey: options.operationKey,
+    ...(claim.historical ? {} : { operationKey: options.operationKey }),
   });
   if (receipt.status !== "ready")
     return { status: "held", reason: receipt.reason };
@@ -151,7 +151,11 @@ export async function reconcileRecipientPayout(
     );
   // Current claims use the default card source balance. Other rails need a
   // persisted allocation contract before a provider receipt can be adopted.
-  if (receipt.sourceType !== "card")
+  if (
+    receipt.sourceType !== "card" ||
+    (claim.historical &&
+      (receipt.method !== "standard" || receipt.type !== "bank_account"))
+  )
     return { status: "held", reason: "source_allocation_required" };
   const fee = addSummaryAmounts(receipt.debit.fee, receipt.credit?.fee ?? 0);
   if (fee < 0) return { status: "held", reason: "fee_allocation_required" };

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

@@ -0,0 +1,157 @@
+// @vitest-environment edge-runtime
+import { expect, it, vi } from "vitest";
+import { historical, scope } from "./payoutAdoptionTestHelpers.js";
+
+it.each([
+  ["usd", "failed", 0],
+  ["jpy", "canceled", 25],
+  ["kwd", "failed", 25],
+] as const)(
+  "adopts and replays returned %s principal with %s status and %i fee",
+  async (currency, status, fee) => {
+    const s = await historical(currency);
+    const payout = await s.provider.payouts.retrieve();
+    if (!payout) throw new Error("Missing fixture payout");
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(Date.now() + 2000);
+      const returnedAt = Math.floor(Date.now() / 1000);
+      payout.status = status;
+      payout.failure_balance_transaction = "txn_return";
+      s.setTransactions([
+        {
+          id: "txn_return",
+          source: "po_one",
+          amount: 1000,
+          fee,
+          net: 1000 - fee,
+          currency,
+          created: returnedAt,
+          available_on: returnedAt,
+          status: "available",
+          type: status === "failed" ? "payout_failure" : "payout_cancel",
+          exchange_rate: null,
+        },
+        ...s.transactions(),
+      ]);
+      const expected = {
+        status: "adopted",
+        oldestHeldAt: returnedAt * 1000,
+        claims: [
+          { status: "returned", amount: 1000, currency, providerFee: fee },
+        ],
+      };
+      expect(await s.adopt()).toMatchObject(expected);
+      expect(await s.adopt()).toMatchObject(expected);
+      expect(
+        await s.t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+      ).toHaveLength(1);
+      expect(
+        await s.t.run((ctx) =>
+          ctx.db.query("payoutSourceAllocations").collect(),
+        ),
+      ).toMatchObject([
+        { paidAmount: 0, reservedAmount: 0 },
+        { paidAmount: 0, reservedAmount: 0 },
+      ]);
+      expect(s.provider.payouts.create).not.toHaveBeenCalled();
+
+      // Add later source funding; the returned principal is payable once, net of its fee.
+      s.amounts.push(300);
+      vi.setSystemTime(Date.now() + 10000);
+      const created = Math.floor(Date.now() / 1000);
+      await s.t.run(async (ctx) => {
+        await ctx.db.insert("transfers", {
+          stripeTransferId: "tr_2",
+          destinationAccountId: scope.accountId,
+          sourceChargeId: "ch_2",
+          amount: 300,
+          currency,
+          status: "paid",
+          role: "store",
+        });
+        const policy = await ctx.db.query("payoutPolicies").first();
+        if (!policy) throw new Error("Missing fixture policy");
+        await ctx.db.patch("payoutPolicies", policy._id, {
+          mode: "custom",
+          thresholds: [{ currency, amount: 1 }],
+        });
+      });
+      s.setTransactions([
+        ...s.transactions(),
+        {
+          id: "txn_2",
+          source: "py_2",
+          amount: 300,
+          fee: 0,
+          net: 300,
+          currency,
+          created,
+          available_on: created,
+          status: "available",
+          type: "payment",
+          exchange_rate: null,
+        },
+      ]);
+      expect(await s.run()).toMatchObject({
+        status: "updated",
+        claim: { status: "paid", amount: 1300 - fee, currency },
+      });
+      expect(await s.run()).toMatchObject({
+        status: "updated",
+        claim: { status: "paid", amount: 1300 - fee, currency },
+      });
+      expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  },
+);
+
+it.each(["pending", "wrong_currency", "wrong_principal"] as const)(
+  "holds or rejects %s returns without importing partial history",
+  async (kind) => {
+    const s = await historical();
+    const payout = await s.provider.payouts.retrieve();
+    if (!payout) throw new Error("Missing fixture payout");
+    payout.status = "failed";
+    payout.failure_balance_transaction = "txn_return";
+    const now = Math.floor(Date.now() / 1000);
+    const amount = kind === "wrong_principal" ? 999 : 1000;
+    s.setTransactions([
+      {
+        id: "txn_return",
+        source: "po_one",
+        amount,
+        fee: 0,
+        net: amount,
+        currency: kind === "wrong_currency" ? "eur" : "usd",
+        created: now,
+        available_on: now,
+        status: kind === "pending" ? "pending" : "available",
+        type: "payout_failure",
+        exchange_rate: null,
+      },
+      ...s.transactions(),
+    ]);
+    if (kind === "wrong_principal")
+      await expect(s.adopt()).rejects.toThrow(
+        "Payout transaction receipt identity or principal does not match.",
+      );
+    else
+      expect(await s.adopt()).toMatchObject({
+        status: "held",
+        reason:
+          kind === "pending"
+            ? "return_pending"
+            : "currency_allocation_required",
+      });
+    expect(
+      await s.t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+    ).toEqual([]);
+    expect(
+      await s.t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+    ).toEqual([]);
+    expect(s.provider.payouts.create).not.toHaveBeenCalled();
+  },
+);

package/src/client/payoutPolicy.test.ts

@@ -318,3 +318,19 @@ it("rechecks delayed activation and cancels safely when funds arrive after prepa
     status: "ready",
   });
 });
+it("requires adoption for historical payouts even when today's balance is zero", async () => {
+  const { client, ctx, provider } = await setup();
+  provider.payouts.list.mockImplementation(
+    async (params?: { status?: string }) =>
+      ({
+        data: params?.status ? [] : [{ id: "po_old" }],
+        has_more: false,
+      }) as never,
+  );
+  expect(await client.prepare(ctx, options)).toMatchObject({
+    status: "migration_required",
+    reason: "existing_payout_history",
+  });
+  expect(provider.balanceSettings.update).not.toHaveBeenCalled();
+  expect(await client.get(ctx, scope)).toBeNull();
+});