@fantastic.dev/better-stripe 0.22.0 → 0.23.0

package/src/client/connect/payoutAdoption.ts

@@ -0,0 +1,330 @@
+import { oldestUnpaidFunding } from "./payoutAdoptionAge.js";
+import { addSummaryAmounts as add } from "../../component/earnings/arithmetic.js";
+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 { validateScope } from "../../component/payoutPolicy/helpers.js";
+import {
+  transferFingerprint,
+  payoutClaimFingerprint,
+} from "../../component/payoutRelease/helpers.js";
+import type {
+  claimDoc,
+  observation,
+} from "../../component/payoutRelease/schema.js";
+import type { policyDoc } from "../../component/payoutPolicy/schema.js";
+import type { transferDocValidator } from "../../component/connect/validators.js";
+import {
+  getTransferFundingReceipt,
+  type TransferReceiptTransaction,
+} from "./transferReceipt.js";
+import { getRecipientPayoutReceipt } from "./payoutReceipt.js";
+import { verifyPayoutHistory } from "./payoutHistory.js";
+import {
+  validateHistoricalFunding,
+  type HistoricalFundingSource,
+  type HistoricalFundingPayout,
+} from "./payoutAdoptionAllocation.js";
+import { reconcileRecipientPayout } from "./payoutReconciliation.js";
+type Claim = Infer<typeof claimDoc>;
+export type PayoutAdoptionOptions = {
+  accountId: string;
+  ownerKey: string;
+  currency: string;
+  expectedRevision: number;
+  maxPages?: number;
+  /** Explicit authorized source accounting for historical payouts not already recorded by BetterStripe. */
+  payouts: {
+    stripePayoutId: string;
+    allocations: { stripeTransferId: string; amount: number }[];
+  }[];
+};
+export type PayoutAdoptionResult =
+  | {
+      status: "adopted";
+      claims: Claim[];
+      observedAt: number;
+      observations: Infer<typeof observation>[];
+      oldestHeldAt?: number;
+      historyCurrencies: string[];
+    }
+  | { status: "held"; reason: string };
+/** Import verified terminal historical payouts. Does not change payout schedules or authorize activation. */
+export async function adoptRecipientPayouts(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: PayoutAdoptionOptions,
+  verifyOnly = false,
+): Promise<PayoutAdoptionResult> {
+  validateScope(opts);
+  const max = opts.maxPages ?? 10;
+  if (
+    !/^[a-z]{3}$/.test(opts.currency) ||
+    !Number.isSafeInteger(opts.expectedRevision) ||
+    opts.expectedRevision < 0 ||
+    !Number.isInteger(max) ||
+    max < 1 ||
+    max > 100
+  )
+    throw new Error("Invalid historical adoption scope or budget.");
+  if (!ctx.runMutation)
+    throw new Error("Historical adoption requires runMutation.");
+  const mappings = new Map<
+    string,
+    PayoutAdoptionOptions["payouts"][number]["allocations"]
+  >();
+  for (const p of opts.payouts) {
+    if (mappings.has(p.stripePayoutId))
+      throw new Error("Duplicate historical payout mapping.");
+    mappings.set(p.stripePayoutId, p.allocations);
+  }
+  const scope = { accountId: opts.accountId, ownerKey: opts.ownerKey };
+  const policy = (await ctx.runQuery(
+    componentRef(component, "payoutPolicy/queries/get"),
+    scope,
+  )) as Infer<typeof policyDoc> | null;
+  if (
+    !policy ||
+    policy.revision !== opts.expectedRevision ||
+    policy.mode !== "stripe_managed" ||
+    (policy.status !== "ready" && !(verifyOnly && policy.status === "changing"))
+  )
+    throw new Error(
+      "Historical adoption requires an owned automatic policy at this revision.",
+    );
+  const snapshot = (await ctx.runQuery(
+    componentRef(component, "payoutRelease/queries/snapshot"),
+    scope,
+  )) as
+    | {
+        status: "ready";
+        transfers: Infer<typeof transferDocValidator>[];
+        claims: Claim[];
+      }
+    | { status: "held"; reason: string };
+  if (snapshot.status !== "ready") return snapshot;
+  const known = new Map(
+    snapshot.claims
+      .filter((c) => c.stripePayoutId)
+      .map((c) => [c.stripePayoutId!, c]),
+  );
+  const historyCurrencies = new Set<string>();
+  const payouts: Stripe.Payout[] = [];
+  let cursor: string | undefined,
+    head: string | undefined,
+    complete = false;
+  for (let page = 0; page < max; page++) {
+    const batch = await stripe.payouts.list(
+      { limit: 100, ...(cursor ? { starting_after: cursor } : {}) },
+      { stripeAccount: opts.accountId },
+    );
+    if (page === 0) head = batch.data[0]?.id;
+    for (const p of batch.data) historyCurrencies.add(p.currency);
+    payouts.push(...batch.data.filter((p) => p.currency === opts.currency));
+    if (!batch.has_more) {
+      complete = true;
+      break;
+    }
+    const next = batch.data[batch.data.length - 1]?.id;
+    if (!next || next === cursor)
+      return { status: "held", reason: "history_incomplete" };
+    cursor = next;
+  }
+  if (!complete) return { status: "held", reason: "history_incomplete" };
+  if (new Set(payouts.map((p) => p.id)).size !== payouts.length)
+    return { status: "held", reason: "history_incomplete" };
+  if ([...mappings.keys()].some((id) => !payouts.some((p) => p.id === id)))
+    return { status: "held", reason: "historical_history_changed" };
+  const proofPayouts: HistoricalFundingPayout[] = [];
+  const transactions: TransferReceiptTransaction[] = [];
+  const imports = [];
+  for (const p of payouts) {
+    const old = known.get(p.id),
+      supplied = mappings.get(p.id);
+    const allocations = old?.allocations ?? supplied;
+    if (!allocations)
+      return { status: "held", reason: "historical_allocation_required" };
+    const canonical = (a: typeof allocations) =>
+      JSON.stringify(
+        a
+          .map((x) => [x.stripeTransferId, x.amount])
+          .sort((a, b) => String(a[0]).localeCompare(String(b[0]))),
+      );
+    if (old && supplied && canonical(old.allocations) !== canonical(supplied))
+      throw new Error(
+        "Historical payout source allocations cannot be changed.",
+      );
+    const receipt = await getRecipientPayoutReceipt(stripe, {
+      accountId: opts.accountId,
+      stripePayoutId: p.id,
+    });
+    if (receipt.status !== "ready")
+      return { status: "held", reason: receipt.reason };
+    if (
+      receipt.sourceType !== "card" ||
+      receipt.method !== "standard" ||
+      receipt.type !== "bank_account"
+    )
+      return { status: "held", reason: "source_allocation_required" };
+    if (!["paid", "failed", "canceled"].includes(receipt.providerStatus))
+      return { status: "held", reason: "historical_payout_pending" };
+    const returned = receipt.providerStatus !== "paid";
+    if (returned && !receipt.credit)
+      return { status: "held", reason: "return_unavailable" };
+    if (receipt.debit.fee + (receipt.credit?.fee ?? 0) < 0)
+      return { status: "held", reason: "fee_allocation_required" };
+    proofPayouts.push({
+      stripePayoutId: p.id,
+      currency: receipt.currency,
+      amount: receipt.amount,
+      created: receipt.created,
+      allocations,
+      ...(returned
+        ? {
+            returnedAt: Math.max(
+              receipt.credit!.created,
+              receipt.credit!.availableOn,
+            ),
+          }
+        : {}),
+    });
+    transactions.push({ ...receipt.debit, sourceId: p.id });
+    if (receipt.credit)
+      transactions.push({ ...receipt.credit, sourceId: p.id });
+    imports.push({
+      old,
+      allocations,
+      payout: {
+        stripePayoutId: p.id,
+        amount: receipt.amount,
+        currency: receipt.currency,
+        created: receipt.created,
+        destinationId: receipt.destinationId,
+        status: returned ? ("returned" as const) : ("paid" as const),
+        debitTransactionId: receipt.debit.id,
+        debitFee: receipt.debit.fee,
+        ...(returned
+          ? {
+              returnTransactionId: receipt.credit!.id,
+              returnFee: receipt.credit!.fee,
+            }
+          : {}),
+      },
+    });
+  }
+  const observations: Infer<typeof observation>[] = [];
+  const sources: HistoricalFundingSource[] = [];
+  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 };
+    historyCurrencies.add(receipt.settlementCurrency);
+    sources.push({
+      stripeTransferId: row.stripeTransferId,
+      currency: receipt.settlementCurrency,
+      transactions: receipt.transactions,
+    });
+    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);
+  }
+  validateHistoricalFunding(sources, proofPayouts);
+  const history = await verifyPayoutHistory(stripe, {
+    accountId: opts.accountId,
+    currency: opts.currency,
+    transactions,
+    maxPages: max,
+  });
+  if (history.status !== "verified") return history;
+  const latest = await stripe.payouts.list(
+    { limit: 1 },
+    { stripeAccount: opts.accountId },
+  );
+  if (latest.data[0]?.id !== head)
+    return { status: "held", reason: "provider_changed" };
+  const claims: Claim[] = [];
+  for (const item of imports.filter((i) => i.old)) {
+    const result = await reconcileRecipientPayout(stripe, component, ctx, {
+      ...scope,
+      operationKey: item.old!.operationKey,
+      stripePayoutId: item.payout.stripePayoutId,
+      maxPages: max,
+    });
+    if (result.status !== "updated")
+      return {
+        status: "held",
+        reason:
+          result.status === "held"
+            ? result.reason
+            : "historical_claim_terminal",
+      };
+    claims.push(result.claim);
+  }
+  const unknown = imports.filter((i) => !i.old);
+  if (unknown.length && verifyOnly)
+    return { status: "held", reason: "historical_allocation_required" };
+  if (unknown.length) {
+    const fresh = (await ctx.runQuery(
+      componentRef(component, "payoutRelease/queries/snapshot"),
+      scope,
+    )) as
+      { status: "ready"; claims: Claim[] } | { status: "held"; reason: string };
+    if (fresh.status !== "ready") return fresh;
+    const result = (await runMutationOrThrow(
+      ctx,
+      componentRef(component, "payoutRelease/mutations/adoptHistoricalBatch"),
+      {
+        ...scope,
+        expectedRevision: opts.expectedRevision,
+        observations,
+        expectedClaims: fresh.claims.map((c) => ({
+          operationKey: c.operationKey,
+          fingerprint: payoutClaimFingerprint(c),
+        })),
+        payouts: unknown.map((i) => ({
+          payout: i.payout,
+          allocations: i.allocations,
+        })),
+      },
+    )) as { claims: Claim[] };
+    claims.push(...result.claims);
+  }
+  const paid = claims
+    .filter((c) => c.status === "paid")
+    .flatMap((c) => c.allocations);
+  const fees = claims.reduce((total, c) => add(total, c.providerFee ?? 0), 0);
+  const returned = proofPayouts
+    .filter((p) => p.returnedAt !== undefined)
+    .flatMap((p) =>
+      p.allocations.map((a) => ({ ...a, created: p.returnedAt! })),
+    );
+  const oldestHeldAt = oldestUnpaidFunding(
+    opts.currency,
+    sources,
+    paid,
+    fees,
+    returned,
+  );
+  return {
+    status: "adopted",
+    claims,
+    observations,
+    historyCurrencies: [...historyCurrencies],
+    ...(oldestHeldAt !== undefined ? { oldestHeldAt } : {}),
+    observedAt: Date.now(),
+  };
+}

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

@@ -0,0 +1,89 @@
+import { expect, it } from "vitest";
+import { oldestUnpaidFunding } from "./payoutAdoptionAge.js";
+const source = (stripeTransferId: string, net: number, created: number) => ({
+  stripeTransferId,
+  currency: "usd",
+  transactions: [{ net, created }],
+});
+it("ignores fully paid old funding and anchors a later unpaid credit", () => {
+  expect(
+    oldestUnpaidFunding(
+      "usd",
+      [source("tr_old", 1000, 10), source("tr_new", 300, 100)],
+      [{ stripeTransferId: "tr_old", amount: 1000 }],
+      0,
+    ),
+  ).toBe(100000);
+});
+it("old refund debt consumes new funding without reviving the old holding age", () => {
+  expect(
+    oldestUnpaidFunding(
+      "usd",
+      [source("tr_old", 900, 10), source("tr_new", 300, 100)],
+      [{ stripeTransferId: "tr_old", amount: 1000 }],
+      0,
+    ),
+  ).toBe(100000);
+});
+it("fees consume the oldest unpaid funds first", () => {
+  expect(
+    oldestUnpaidFunding(
+      "usd",
+      [source("tr_old", 30, 10), source("tr_new", 300, 100)],
+      [],
+      30,
+    ),
+  ).toBe(100000);
+});
+it("anchors a fee credit after the original source was fully paid", () => {
+  expect(
+    oldestUnpaidFunding(
+      "usd",
+      [
+        {
+          ...source("tr_old", 1000, 10),
+          transactions: [
+            { net: 1000, created: 10 },
+            { net: 100, created: 100 },
+          ],
+        },
+      ],
+      [{ stripeTransferId: "tr_old", amount: 1000 }],
+      0,
+    ),
+  ).toBe(100000);
+});
+it("returns no holding age when nothing is owed", () => {
+  expect(
+    oldestUnpaidFunding(
+      "usd",
+      [source("tr_old", 1000, 10)],
+      [{ stripeTransferId: "tr_old", amount: 1000 }],
+      0,
+    ),
+  ).toBeUndefined();
+});
+it("does not offset another currency", () => {
+  expect(
+    oldestUnpaidFunding(
+      "usd",
+      [
+        { ...source("tr_eur", -1000, 10), currency: "eur" },
+        source("tr_usd", 100, 20),
+      ],
+      [],
+      0,
+    ),
+  ).toBe(20000);
+});
+it("returned bank cash starts a new holding age after the original funds left Stripe", () => {
+  expect(
+    oldestUnpaidFunding(
+      "usd",
+      [source("tr_old", 1000, 10)],
+      [{ stripeTransferId: "tr_old", amount: 1000 }],
+      0,
+      [{ stripeTransferId: "tr_old", amount: 1000, created: 100 }],
+    ),
+  ).toBe(100000);
+});

package/src/client/connect/payoutAdoptionAge.ts

@@ -0,0 +1,74 @@
+import { addSummaryAmounts as add } from "../../component/earnings/arithmetic.js";
+type Source = {
+  stripeTransferId: string;
+  currency: string;
+  transactions: { net: number; created: number }[];
+};
+/** FIFO ownership age after historical paid principal, source debt and verified payout fees. */
+export function oldestUnpaidFunding(
+  currency: string,
+  sources: Source[],
+  paid: { stripeTransferId: string; amount: number }[],
+  fees: number,
+  returned: {
+    stripeTransferId: string;
+    amount: number;
+    created: number;
+  }[] = [],
+): number | undefined {
+  if (!Number.isSafeInteger(fees) || fees < 0)
+    throw new Error("Invalid payout fee amount.");
+  const bySource = new Map<string, number>();
+  for (const p of paid) {
+    if (!Number.isSafeInteger(p.amount) || p.amount < 0)
+      throw new Error("Invalid historical paid amount.");
+    bySource.set(
+      p.stripeTransferId,
+      add(bySource.get(p.stripeTransferId) ?? 0, p.amount),
+    );
+  }
+  sources = sources.map((s) => ({ ...s, transactions: [...s.transactions] }));
+  const returnedTotals = new Map<string, number>();
+  for (const r of returned) {
+    const source = sources.find(
+      (s) => s.stripeTransferId === r.stripeTransferId,
+    );
+    if (!source || !Number.isSafeInteger(r.amount) || r.amount <= 0)
+      throw new Error("Invalid returned funding allocation.");
+    const total = add(returnedTotals.get(r.stripeTransferId) ?? 0, r.amount);
+    if (total > (bySource.get(r.stripeTransferId) ?? 0))
+      throw new Error("Returned funding exceeds historical paid principal.");
+    returnedTotals.set(r.stripeTransferId, total);
+    source.transactions.push({ net: r.amount, created: r.created });
+  }
+  const chunks: { amount: number; created: number }[] = [];
+  let debt = fees;
+  for (const s of sources.filter((s) => s.currency === currency)) {
+    let consumed = bySource.get(s.stripeTransferId) ?? 0;
+    for (const t of s.transactions) {
+      if (
+        !Number.isSafeInteger(t.net) ||
+        !Number.isSafeInteger(t.created) ||
+        t.created < 0 ||
+        !Number.isSafeInteger(t.created * 1000)
+      )
+        throw new Error("Invalid source funding age.");
+      if (t.net < 0) consumed = add(consumed, -t.net);
+    }
+    for (const t of [...s.transactions]
+      .filter((t) => t.net > 0)
+      .sort((a, b) => a.created - b.created)) {
+      const used = Math.min(consumed, t.net);
+      consumed = add(consumed, -used);
+      const amount = add(t.net, -used);
+      if (amount) chunks.push({ amount, created: t.created });
+    }
+    debt = add(debt, consumed);
+  }
+  for (const c of chunks.sort((a, b) => a.created - b.created)) {
+    const used = Math.min(debt, c.amount);
+    debt = add(debt, -used);
+    if (c.amount > used) return c.created * 1000;
+  }
+  return undefined;
+}

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

@@ -0,0 +1,132 @@
+import { expect, it } from "vitest";
+import { validateHistoricalFunding } from "./payoutAdoptionAllocation.js";
+const source = {
+  stripeTransferId: "tr_one",
+  currency: "usd",
+  transactions: [
+    {
+      amount: 1000,
+      fee: 0,
+      net: 1000,
+      created: 10,
+      availableOn: 20,
+      status: "available",
+    },
+  ],
+};
+const payout = {
+  stripePayoutId: "po_one",
+  currency: "usd",
+  amount: 1000,
+  created: 30,
+  allocations: [{ stripeTransferId: "tr_one", amount: 1000 }],
+};
+it("validates exact historical funding without requiring it to remain unpaid now", () => {
+  expect(() =>
+    validateHistoricalFunding(
+      [
+        {
+          ...source,
+          transactions: [
+            ...source.transactions,
+            {
+              amount: -500,
+              fee: 0,
+              net: -500,
+              created: 40,
+              availableOn: 50,
+              status: "available",
+            },
+          ],
+        },
+      ],
+      [payout],
+    ),
+  ).not.toThrow();
+});
+it("rejects funding from a transfer not mature at the payout date", () => {
+  expect(() =>
+    validateHistoricalFunding(
+      [
+        {
+          ...source,
+          transactions: [{ ...source.transactions[0], availableOn: 31 }],
+        },
+      ],
+      [payout],
+    ),
+  ).toThrow(/funding/i);
+});
+it("rejects paying the same historical source twice", () => {
+  expect(() =>
+    validateHistoricalFunding(
+      [source],
+      [payout, { ...payout, stripePayoutId: "po_two", created: 40 }],
+    ),
+  ).toThrow(/funding/i);
+});
+it("a returned payout restores source capacity only at actual return maturity", () => {
+  const first = { ...payout, returnedAt: 50 };
+  expect(() =>
+    validateHistoricalFunding(
+      [source],
+      [first, { ...payout, stripePayoutId: "po_two", created: 45 }],
+    ),
+  ).toThrow(/funding/i);
+  expect(() =>
+    validateHistoricalFunding(
+      [source],
+      [first, { ...payout, stripePayoutId: "po_two", created: 50 }],
+    ),
+  ).not.toThrow();
+});
+it("cannot use a future positive fee adjustment to fund an older payout", () => {
+  expect(() =>
+    validateHistoricalFunding(
+      [
+        {
+          ...source,
+          transactions: [
+            { ...source.transactions[0], net: 900 },
+            {
+              net: 100,
+              created: 40,
+              availableOn: 40,
+              status: "available",
+            },
+          ],
+        },
+      ],
+      [payout],
+    ),
+  ).toThrow(/funding/i);
+});
+it("does not net currencies", () => {
+  expect(() =>
+    validateHistoricalFunding([{ ...source, currency: "eur" }], [payout]),
+  ).toThrow(/currency/i);
+});
+it("requires exact principal allocations", () => {
+  expect(() =>
+    validateHistoricalFunding([source], [{ ...payout, amount: 999 }]),
+  ).toThrow(/principal/i);
+});
+it("rejects duplicate payouts or duplicate source allocations", () => {
+  expect(() => validateHistoricalFunding([source], [payout, payout])).toThrow(
+    /duplicate/i,
+  );
+  expect(() =>
+    validateHistoricalFunding(
+      [source],
+      [
+        {
+          ...payout,
+          allocations: [
+            { stripeTransferId: "tr_one", amount: 500 },
+            { stripeTransferId: "tr_one", amount: 500 },
+          ],
+        },
+      ],
+    ),
+  ).toThrow(/duplicate/i);
+});