@fantastic.dev/better-stripe 0.21.0 → 0.23.0

package/src/client/connect/payoutExecution.ts

@@ -0,0 +1,265 @@
+import type Stripe from "stripe";
+import type { Infer } from "convex/values";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import type { claimDoc } from "../../component/payoutRelease/schema.js";
+import type { transferDocValidator } from "../../component/connect/validators.js";
+import type { policyDoc } from "../../component/payoutPolicy/schema.js";
+import {
+  transferFingerprint,
+  validateIdentity,
+} from "../../component/payoutRelease/helpers.js";
+import {
+  getTransferFundingReceipt,
+  type TransferReceiptTransaction,
+} from "./transferReceipt.js";
+import { verifyPayoutHistory } from "./payoutHistory.js";
+import {
+  reconcileRecipientPayout,
+  type PayoutReconciliation,
+} from "./payoutReconciliation.js";
+type Claim = Infer<typeof claimDoc>;
+type Policy = Infer<typeof policyDoc>;
+export type PayoutReleaseOptions = {
+  accountId: string;
+  ownerKey: string;
+  operationKey: string;
+  currency: string;
+  /** Host supplies all authorized off-provider debts/reserves, without double counting provider receipt debits. */
+  independentLiabilities: number;
+  maxPages?: number;
+};
+type Held = { status: "held"; reason: string };
+export type PayoutReleaseResult = PayoutReconciliation | Held;
+type Snapshot =
+  | {
+      status: "ready";
+      transfers: Infer<typeof transferDocValidator>[];
+      claims: Claim[];
+    }
+  | Held;
+/**
+ * Complete receipt qualification followed by an atomic claim and one immutable
+ * provider request. Host authorizes the recipient, policy, operation and known
+ * off-provider liabilities. Attempted operations only reconcile on subsequent
+ * calls; they are never blindly recreated after an unknown provider outcome.
+ */
+export async function releaseRecipientPayout(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: PayoutReleaseOptions,
+  verify: () => Promise<
+    { status: "verified"; policy: Policy } | { status: string }
+  >,
+): Promise<PayoutReleaseResult> {
+  validateIdentity(opts);
+  if (
+    !/^[a-z]{3}$/.test(opts.currency) ||
+    !Number.isSafeInteger(opts.independentLiabilities) ||
+    opts.independentLiabilities < 0
+  )
+    throw new Error("Invalid payout currency or independent liabilities.");
+  const maxPages = opts.maxPages ?? 10;
+  if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 100)
+    throw new Error("Payout page budget must be between 1 and 100.");
+  if (!ctx.runMutation) throw new Error("Payout release requires runMutation.");
+  const identity = {
+    accountId: opts.accountId,
+    ownerKey: opts.ownerKey,
+    operationKey: opts.operationKey,
+  };
+  const existing = (await ctx.runQuery(
+    componentRef(component, "payoutRelease/queries/get"),
+    identity,
+  )) as Claim | null;
+  if (existing) {
+    if (existing.currency !== opts.currency)
+      throw new Error("Payout claim currency cannot be changed.");
+    if (existing.attemptedAt !== undefined || existing.status !== "reserved")
+      return reconcileRecipientPayout(stripe, component, ctx, {
+        ...identity,
+        maxPages,
+      });
+    // A crash before the attempt has no provider side effect. Release its exact
+    // reservations; the next scheduled operation must collect fresh receipts.
+    const claim = (await runMutationOrThrow(
+      ctx,
+      componentRef(component, "payoutRelease/mutations/cancelUnattempted"),
+      identity,
+    )) as Claim;
+    return { status: "terminal", claim };
+  }
+  const controls = await verify();
+  if (controls.status !== "verified" || !("policy" in controls))
+    return { status: "held", reason: controls.status };
+  const snapshot = (await ctx.runQuery(
+    componentRef(component, "payoutRelease/queries/snapshot"),
+    { accountId: opts.accountId, ownerKey: opts.ownerKey },
+  )) as Snapshot;
+  if (snapshot.status !== "ready") return snapshot;
+  const banks: string[] = [];
+  let bankCursor: string | undefined;
+  for (let page = 0; ; page++) {
+    if (page >= maxPages)
+      return { status: "held", reason: "bank_history_incomplete" };
+    const batch = await stripe.accounts.listExternalAccounts(opts.accountId, {
+      object: "bank_account",
+      limit: 100,
+      ...(bankCursor ? { starting_after: bankCursor } : {}),
+    });
+    for (const bank of batch.data)
+      if (
+        bank.object === "bank_account" &&
+        bank.currency === opts.currency &&
+        bank.default_for_currency &&
+        bank.status !== "errored"
+      )
+        banks.push(bank.id);
+    if (!batch.has_more) break;
+    const next = batch.data[batch.data.length - 1]?.id;
+    if (!next || next === bankCursor)
+      return { status: "held", reason: "bank_history_incomplete" };
+    bankCursor = next;
+  }
+  if (banks.length !== 1 || !/^ba_\w+$/.test(banks[0]))
+    return { status: "held", reason: "bank_destination_unavailable" };
+  const destinationId = banks[0];
+  const transactions: TransferReceiptTransaction[] = [];
+  for (const claim of snapshot.claims) {
+    if (
+      claim.currency !== opts.currency ||
+      claim.status === "canceled" ||
+      claim.status === "rejected"
+    )
+      continue;
+    if (claim.attemptedAt === undefined)
+      return { status: "held", reason: "pending_claim" };
+    const result = await reconcileRecipientPayout(stripe, component, ctx, {
+      accountId: opts.accountId,
+      ownerKey: opts.ownerKey,
+      operationKey: claim.operationKey,
+      maxPages,
+    });
+    if (result.status !== "updated") return result;
+    for (const t of [result.receipt.debit, result.receipt.credit])
+      if (t)
+        transactions.push({ ...t, sourceId: result.receipt.stripePayoutId });
+  }
+  const observations = [];
+  for (const row of snapshot.transfers) {
+    const receipt = await getTransferFundingReceipt(stripe, component, ctx, {
+      accountId: opts.accountId,
+      stripeTransferId: row.stripeTransferId,
+    });
+    if (receipt.status !== "ready")
+      return { status: "held", reason: receipt.reason };
+    observations.push({
+      stripeTransferId: row.stripeTransferId,
+      currency: receipt.settlementCurrency,
+      matureNet: receipt.matureNet,
+      pendingCredits: receipt.pendingCredits,
+      ledgerFingerprint: transferFingerprint(row),
+      observedAt: receipt.observedAt,
+      transactionIds: receipt.transactions.map((t) => t.id),
+    });
+    if (receipt.settlementCurrency === opts.currency)
+      transactions.push(...receipt.transactions);
+  }
+  const history = await verifyPayoutHistory(stripe, {
+    accountId: opts.accountId,
+    currency: opts.currency,
+    transactions,
+    maxPages,
+  });
+  if (history.status !== "verified") return history;
+  const claim = (await runMutationOrThrow(
+    ctx,
+    componentRef(component, "payoutRelease/mutations/claim"),
+    {
+      ...identity,
+      expectedRevision: controls.policy.revision,
+      currency: opts.currency,
+      destinationId,
+      providerAvailable: history.providerAvailable,
+      independentLiabilities: opts.independentLiabilities,
+      observations,
+    },
+  )) as Claim | Held;
+  if (claim.status === "held") return claim;
+  // Another caller can win this operation while receipts were being collected.
+  if (claim.attemptedAt !== undefined || claim.status !== "reserved")
+    return reconcileRecipientPayout(stripe, component, ctx, {
+      ...identity,
+      maxPages,
+    });
+  const latest = await verify();
+  if (
+    latest.status !== "verified" ||
+    !("policy" in latest) ||
+    latest.policy.revision !== controls.policy.revision
+  ) {
+    await runMutationOrThrow(
+      ctx,
+      componentRef(component, "payoutRelease/mutations/cancelUnattempted"),
+      identity,
+    );
+    return {
+      status: "held",
+      reason: latest.status === "verified" ? "policy_changed" : latest.status,
+    };
+  }
+  await runMutationOrThrow(
+    ctx,
+    componentRef(component, "payoutRelease/mutations/beginAttempt"),
+    identity,
+  );
+  let payout: Stripe.Payout;
+  try {
+    payout = await stripe.payouts.create(
+      {
+        amount: claim.amount,
+        currency: claim.currency,
+        destination: claim.destinationId,
+        method: "standard",
+        source_type: "card",
+        metadata: { bsPayoutClaim: claim.operationKey },
+      },
+      {
+        stripeAccount: claim.accountId,
+        idempotencyKey: `bs:payout-release:${claim.operationKey}`,
+      },
+    );
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "type" in error &&
+      error.type === "StripeInvalidRequestError" &&
+      "code" in error &&
+      ["balance_insufficient", "amount_too_small"].includes(
+        String(error.code),
+      ) &&
+      "requestId" in error &&
+      typeof error.requestId === "string" &&
+      /^req_\w+$/.test(error.requestId)
+    ) {
+      const saved = (await runMutationOrThrow(
+        ctx,
+        componentRef(component, "payoutRelease/mutations/recordRejection"),
+        {
+          ...identity,
+          requestId: error.requestId,
+          code: error.code,
+        },
+      )) as Claim;
+      return { status: "terminal", claim: saved };
+    }
+    throw error;
+  }
+  return reconcileRecipientPayout(stripe, component, ctx, {
+    ...identity,
+    stripePayoutId: payout.id,
+    maxPages,
+  });
+}

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

@@ -0,0 +1,145 @@
+import { expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import { verifyPayoutHistory } from "./payoutHistory.js";
+import type { TransferReceiptTransaction } from "./transferReceipt.js";
+const credit: TransferReceiptTransaction = {
+  id: "txn_credit",
+  sourceId: "py_credit",
+  amount: 1000,
+  fee: 0,
+  net: 1000,
+  currency: "usd",
+  created: 10,
+  availableOn: 20,
+  status: "available" as const,
+  type: "payment",
+};
+const raw = (t = credit) => ({
+  ...t,
+  source: t.sourceId,
+  available_on: t.availableOn,
+});
+function setup(rows: unknown[] = [raw()]) {
+  const list = vi.fn(async () => ({ data: rows, has_more: false }));
+  const balance = vi.fn(async () => ({
+    available: [
+      { currency: "usd", amount: 1000, source_types: { card: 1000 } },
+    ],
+    pending: [],
+  }));
+  const stripe = {
+    balanceTransactions: { list },
+    balance: { retrieve: balance },
+  } as unknown as Stripe;
+  const read = (transactions = [credit], maxPages = 10) =>
+    verifyPayoutHistory(stripe, {
+      accountId: "acct_one",
+      currency: "usd",
+      transactions,
+      maxPages,
+    });
+  return { list, balance, read };
+}
+it("verifies complete exact known history and card-specific available cash", async () => {
+  const s = setup();
+  expect(await s.read()).toMatchObject({
+    status: "verified",
+    providerAvailable: 1000,
+  });
+  expect(s.list).toHaveBeenCalledWith(
+    { currency: "usd", limit: 100 },
+    { stripeAccount: "acct_one" },
+  );
+});
+it.each(["payout", "stripe_fee", "payment_refund", "payment"])(
+  "holds an unallocated %s instead of treating received credits as unpaid",
+  async (type) => {
+    const s = setup([
+      raw(),
+      { ...raw(), id: "txn_unknown", type, amount: -100, net: -100 },
+    ]);
+    expect(await s.read()).toEqual({
+      status: "held",
+      reason: "unallocated_history",
+    });
+  },
+);
+it("rejects reused receipt identities", async () => {
+  await expect(setup().read([credit, credit])).rejects.toThrow(/duplicate/i);
+});
+it("holds missing expected history", async () => {
+  expect(await setup([]).read()).toEqual({
+    status: "held",
+    reason: "history_changed",
+  });
+});
+it.each(["amount", "fee", "net", "created", "available_on"])(
+  "holds changed receipt %s",
+  async (field) => {
+    expect(await setup([{ ...raw(), [field]: 99 }]).read()).toEqual({
+      status: "held",
+      reason: "history_changed",
+    });
+  },
+);
+it("holds partial pages", async () => {
+  const s = setup();
+  s.list.mockResolvedValue({ data: [raw()], has_more: true });
+  expect(await s.read([credit], 1)).toEqual({
+    status: "held",
+    reason: "history_incomplete",
+  });
+});
+it("holds nonadvancing or duplicated history", async () => {
+  const s = setup([raw(), raw()]);
+  expect(await s.read()).toEqual({
+    status: "held",
+    reason: "history_incomplete",
+  });
+});
+it("holds a changed provider head", async () => {
+  const s = setup();
+  s.list
+    .mockResolvedValueOnce({ data: [raw()], has_more: false })
+    .mockResolvedValue({ data: [], has_more: false });
+  expect(await s.read()).toEqual({ status: "held", reason: "history_changed" });
+});
+it("holds a balance that does not reconcile to complete history", async () => {
+  const s = setup();
+  s.balance.mockResolvedValue({
+    available: [{ currency: "usd", amount: 900, source_types: { card: 900 } }],
+    pending: [],
+  });
+  expect(await s.read()).toEqual({ status: "held", reason: "balance_changed" });
+});
+it("never counts pending source money as available even when available_on has passed", async () => {
+  const pending = { ...credit, status: "pending" as const };
+  const s = setup([raw(pending)]);
+  s.balance.mockResolvedValue({
+    available: [],
+    pending: [{ currency: "usd", amount: 1000 }],
+  } as never);
+  expect(await s.read([pending] as (typeof credit)[])).toMatchObject({
+    status: "verified",
+    providerAvailable: 0,
+  });
+});
+it("uses card source availability rather than unrelated rails", async () => {
+  const s = setup();
+  s.balance.mockResolvedValue({
+    available: [{ currency: "usd", amount: 1000, source_types: { card: 100 } }],
+    pending: [],
+  });
+  expect(await s.read()).toMatchObject({
+    status: "verified",
+    providerAvailable: 100,
+  });
+});
+it.each([0, 101, 1.5])(
+  "rejects invalid page budget %s before provider I/O",
+  async (max) => {
+    const s = setup();
+    await expect(s.read([credit], max)).rejects.toThrow(/budget/i);
+    expect(s.list).not.toHaveBeenCalled();
+  },
+);

package/src/client/connect/payoutHistory.ts

@@ -0,0 +1,149 @@
+import type Stripe from "stripe";
+import type { TransferReceiptTransaction } from "./transferReceipt.js";
+import { addSummaryAmounts as add } from "../../component/earnings/arithmetic.js";
+export type PayoutHistoryVerification =
+  | { status: "verified"; providerAvailable: number; observedAt: number }
+  | {
+      status: "held";
+      reason:
+        | "unallocated_history"
+        | "history_changed"
+        | "history_incomplete"
+        | "balance_changed";
+    };
+function fingerprint(t: TransferReceiptTransaction) {
+  return JSON.stringify([
+    t.id,
+    t.sourceId,
+    t.amount,
+    t.fee,
+    t.net,
+    t.currency,
+    t.created,
+    t.availableOn,
+    t.status,
+    t.type,
+  ]);
+}
+function normalize(t: Stripe.BalanceTransaction): TransferReceiptTransaction {
+  if (t.status !== "available" && t.status !== "pending")
+    throw new Error("Invalid provider receipt status.");
+  return {
+    id: t.id,
+    sourceId: typeof t.source === "string" ? t.source : (t.source?.id ?? ""),
+    amount: t.amount,
+    fee: t.fee,
+    net: t.net,
+    currency: t.currency,
+    created: t.created,
+    availableOn: t.available_on,
+    status: t.status,
+    type: t.type,
+  };
+}
+/**
+ * Verify a complete currency history against independently verified transfer and
+ * payout receipts. Unknown debits AND credits require explicit allocation. A
+ * current balance alone never establishes still-unpaid source ownership.
+ */
+export async function verifyPayoutHistory(
+  stripe: Stripe,
+  opts: {
+    accountId: string;
+    currency: string;
+    transactions: TransferReceiptTransaction[];
+    maxPages?: number;
+  },
+): Promise<PayoutHistoryVerification> {
+  const maxPages = opts.maxPages ?? 10;
+  if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 100)
+    throw new Error("History page budget must be between 1 and 100.");
+  if (!/^acct_\w+$/.test(opts.accountId) || !/^[a-z]{3}$/.test(opts.currency))
+    throw new Error("Invalid payout history scope.");
+  const expected = new Map<string, string>();
+  for (const t of opts.transactions) {
+    if (expected.has(t.id))
+      throw new Error("Duplicate payout history receipt.");
+    if (
+      t.currency !== opts.currency ||
+      !/^txn_\w+$/.test(t.id) ||
+      !t.sourceId ||
+      [t.amount, t.fee, t.net, t.created, t.availableOn].some(
+        (n) => !Number.isSafeInteger(n),
+      ) ||
+      t.net !== add(t.amount, -t.fee)
+    )
+      throw new Error("Invalid payout history receipt.");
+    expected.set(t.id, fingerprint(t));
+  }
+  const scope = { stripeAccount: opts.accountId };
+  const seen = new Set<string>();
+  let cursor: string | undefined, head: string | undefined;
+  let available = 0,
+    pending = 0,
+    complete = false;
+  const held = (
+    reason: Extract<PayoutHistoryVerification, { status: "held" }>["reason"],
+  ): PayoutHistoryVerification => ({ status: "held", reason });
+  for (let page = 0; page < maxPages; page++) {
+    const batch = await stripe.balanceTransactions.list(
+      {
+        currency: opts.currency,
+        limit: 100,
+        ...(cursor ? { starting_after: cursor } : {}),
+      },
+      scope,
+    );
+    if (page === 0 && batch.data[0])
+      head = fingerprint(normalize(batch.data[0]));
+    for (const raw of batch.data) {
+      const t = normalize(raw);
+      if (seen.has(t.id)) return held("history_incomplete");
+      seen.add(t.id);
+      if (!expected.has(t.id)) return held("unallocated_history");
+      if (fingerprint(t) !== expected.get(t.id)) return held("history_changed");
+      if (t.status === "available") available = add(available, t.net);
+      else if (t.status === "pending") pending = add(pending, t.net);
+      else return held("history_changed");
+    }
+    if (!batch.has_more) {
+      complete = true;
+      break;
+    }
+    const next = batch.data[batch.data.length - 1]?.id;
+    if (!next || next === cursor) return held("history_incomplete");
+    cursor = next;
+  }
+  if (!complete) return held("history_incomplete");
+  if (seen.size !== expected.size) return held("history_changed");
+  const balance = await stripe.balance.retrieve(undefined, scope);
+  const latest = await stripe.balanceTransactions.list(
+    { currency: opts.currency, limit: 1 },
+    scope,
+  );
+  const latestHead = latest.data[0]
+    ? fingerprint(normalize(latest.data[0]))
+    : undefined;
+  if (latestHead !== head) return held("history_changed");
+  const entries = (rows: Stripe.Balance.Available[]) =>
+    rows.filter((t) => t.currency === opts.currency);
+  const a = entries(balance.available),
+    p = entries(balance.pending);
+  if (
+    a.length > 1 ||
+    p.length > 1 ||
+    (a[0]?.amount ?? 0) !== available ||
+    (p[0]?.amount ?? 0) !== pending
+  )
+    return held("balance_changed");
+  // The durable payout request explicitly draws from card balance. Other rails
+  // cannot increase this cap even if they contribute to aggregate availability.
+  const card = a[0]?.source_types?.card ?? 0;
+  if (!Number.isSafeInteger(card))
+    throw new Error("Invalid provider card balance.");
+  return {
+    status: "verified",
+    providerAvailable: Math.min(available, card),
+    observedAt: Date.now(),
+  };
+}

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

@@ -383,3 +383,32 @@ it("serializes concurrent outcome reconciliation without duplicate fees or princ
   ).toMatchObject([{ amount: 30, revision: 1 }]);
   expect(provider.payouts.create).not.toHaveBeenCalled();
 });
+it("rejects a payout sent to a different bank than the immutable claim", async () => {
+  const s = await setup();
+  await s.t.run(async (ctx) => {
+    const claim = await ctx.db.query("payoutReleaseClaims").first();
+    await ctx.db.patch("payoutReleaseClaims", claim!._id, {
+      destinationId: "ba_expected",
+    });
+  });
+  await expect(s.reconcile()).rejects.toThrow(/bank destination/i);
+  expect(
+    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,10 +132,14 @@ 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 };
+  if (claim.destinationId && receipt.destinationId !== claim.destinationId)
+    throw new Error(
+      "Payout receipt bank destination does not match the durable claim.",
+    );
   if (receipt.amount !== claim.amount || receipt.currency !== claim.currency)
     throw new Error("Payout receipt money does not match the durable claim.");
   if (
@@ -147,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/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();
+});