@fantastic.dev/better-stripe 0.20.1 → 0.21.0

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

@@ -0,0 +1,385 @@
+// @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 type { Component, RunCtx } from "../helpers.js";
+import schema from "../../component/schema.js";
+import { transferFingerprint } from "../../component/payoutRelease/helpers.js";
+import { reconcileRecipientPayout } from "./payoutReconciliation.js";
+const modules = import.meta.glob("../../component/**/*.*s");
+const scope = {
+  accountId: "acct_recipient",
+  ownerKey: "user_1",
+  operationKey: "release-one",
+};
+const symbol = Symbol.for("toReferencePath");
+const component = {
+  payoutPolicy: {
+    queries: { get: { [symbol]: "betterStripe/payoutPolicy/queries/get" } },
+  },
+} as unknown as Component;
+const m = (name: string) =>
+  makeFunctionReference<"mutation">(`payoutRelease/mutations:${name}`);
+async function setup(attempt = true) {
+  const t = convexTest(schema, modules);
+  const identity = { accountId: scope.accountId, ownerKey: scope.ownerKey };
+  await t.mutation(
+    makeFunctionReference<"mutation">("payoutPolicy/mutations:prepare"),
+    {
+      ...identity,
+      operationKey: "enable",
+      expectedRevision: -1,
+      mode: "custom",
+      thresholds: [{ currency: "usd", amount: 1000 }],
+      country: "US",
+      observedSchedule: { interval: "daily" },
+    },
+  );
+  await t.mutation(
+    makeFunctionReference<"mutation">("payoutPolicy/mutations:confirm"),
+    {
+      ...identity,
+      operationKey: "enable",
+      observedSchedule: { interval: "manual" },
+    },
+  );
+  await t.mutation(
+    makeFunctionReference<"mutation">("connect/mutations:upsertTransfer"),
+    {
+      stripeTransferId: "tr_one",
+      destinationAccountId: scope.accountId,
+      currency: "usd",
+      amount: 1500,
+      role: "affiliate",
+      status: "paid",
+    },
+  );
+  const row = (await t.run((ctx) => ctx.db.query("transfers").take(1)))[0];
+  const args = {
+    ...scope,
+    expectedRevision: 0,
+    currency: "usd",
+    providerAvailable: 1000,
+    independentLiabilities: 0,
+    observations: [
+      {
+        stripeTransferId: "tr_one",
+        currency: "usd",
+        matureNet: 1500,
+        pendingCredits: 0,
+        ledgerFingerprint: transferFingerprint(row),
+        observedAt: Date.now(),
+        transactionIds: ["txn_funding"],
+      },
+    ],
+  };
+  await t.mutation(m("claim"), args);
+  if (attempt) await t.mutation(m("beginAttempt"), scope);
+  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;
+  const now = Math.floor(Date.now() / 1000);
+  let payout = {
+    id: "po_one",
+    amount: 1000,
+    currency: "usd",
+    status: "paid",
+    automatic: false,
+    method: "standard",
+    type: "bank_account",
+    source_type: "card",
+    destination: "ba_one",
+    created: now,
+    arrival_date: now + 86400,
+    balance_transaction: "txn_debit",
+    failure_balance_transaction: null as string | null,
+    reversed_by: null,
+    metadata: { bsPayoutClaim: scope.operationKey },
+  };
+  const provider = {
+    payouts: {
+      create: vi.fn(),
+      retrieve: vi.fn(async () => payout),
+      list: vi.fn(async () => ({ data: [payout], has_more: false })),
+    },
+    balanceTransactions: {
+      retrieve: vi.fn(async (id: string) => ({
+        id,
+        source: "po_one",
+        amount: id === "txn_debit" ? -1000 : 1000,
+        fee: id === "txn_debit" ? 30 : -10,
+        net: id === "txn_debit" ? -1030 : 1010,
+        currency: "usd",
+        status: "available",
+        created: now,
+        available_on: now,
+        type: id === "txn_debit" ? "payout" : "payout_failure",
+      })),
+    },
+  };
+  const reconcile = (options = {}) =>
+    reconcileRecipientPayout(provider as unknown as Stripe, component, ctx, {
+      ...scope,
+      ...options,
+    });
+  return {
+    t,
+    ctx,
+    args,
+    provider,
+    reconcile,
+    setPayout: (changed: Partial<typeof payout>) => {
+      payout = { ...payout, ...changed };
+    },
+  };
+}
+it("discovers an exact attempted payout after a timeout and records actual principal and fees once", async () => {
+  const { t, provider, reconcile } = await setup();
+  expect(await reconcile()).toMatchObject({
+    status: "updated",
+    claim: { status: "paid", stripePayoutId: "po_one", providerFee: 30 },
+  });
+  expect(await reconcile()).toMatchObject({
+    status: "updated",
+    claim: { status: "paid", providerFee: 30 },
+  });
+  expect(provider.payouts.create).not.toHaveBeenCalled();
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSourceAllocations").take(1)),
+  ).toMatchObject([{ paidAmount: 1000, reservedAmount: 0 }]);
+});
+it("keeps unknown attempts held when no payout can be identified, including after idempotency expiry", async () => {
+  const { t, provider, reconcile } = await setup();
+  provider.payouts.list.mockResolvedValue({ data: [], has_more: false });
+  await t.run(async (ctx) => {
+    const row = (await ctx.db.query("payoutReleaseClaims").take(1))[0];
+    await ctx.db.patch("payoutReleaseClaims", row._id, {
+      attemptedAt: Date.now() - 2 * 86400000,
+    });
+  });
+  expect(await reconcile()).toMatchObject({
+    status: "held",
+    reason: "payout_unidentified",
+  });
+  expect(provider.payouts.create).not.toHaveBeenCalled();
+});
+it("does not adopt a partial scan, duplicate matches, or a changing provider history", async () => {
+  const { provider, reconcile } = await setup();
+  const first = await provider.payouts.retrieve();
+  provider.payouts.list.mockResolvedValue({ data: [first], has_more: true });
+  expect(await reconcile({ maxPages: 1 })).toMatchObject({
+    status: "held",
+    reason: "history_incomplete",
+  });
+  provider.payouts.list.mockResolvedValue({
+    data: [first, { ...first, id: "po_other" }],
+    has_more: false,
+  });
+  expect(await reconcile()).toMatchObject({
+    status: "held",
+    reason: "multiple_matches",
+  });
+  provider.payouts.list
+    .mockResolvedValueOnce({ data: [first], has_more: false })
+    .mockResolvedValueOnce({
+      data: [{ ...first, id: "po_new" }],
+      has_more: false,
+    });
+  expect(await reconcile()).toMatchObject({
+    status: "held",
+    reason: "provider_changed",
+  });
+});
+it("follows provider cursors before adopting the only matching payout", async () => {
+  const { provider, reconcile } = await setup();
+  const first = await provider.payouts.retrieve();
+  const unrelated = {
+    ...first,
+    id: "po_unrelated",
+    metadata: { bsPayoutClaim: "different" },
+  };
+  provider.payouts.list
+    .mockResolvedValueOnce({ data: [unrelated], has_more: true })
+    .mockResolvedValueOnce({ data: [first], has_more: false })
+    .mockResolvedValueOnce({ data: [unrelated], has_more: false });
+  expect(await reconcile()).toMatchObject({
+    status: "updated",
+    claim: { status: "paid" },
+  });
+  expect(provider.payouts.list.mock.calls[1]).toEqual([
+    { limit: 100, created: expect.any(Object), starting_after: "po_unrelated" },
+    { stripeAccount: scope.accountId },
+  ]);
+});
+it("keeps failed payouts reserved without a mature return receipt", async () => {
+  const { reconcile, setPayout } = await setup();
+  setPayout({ status: "failed" });
+  expect(await reconcile({ stripePayoutId: "po_one" })).toMatchObject({
+    status: "held",
+    reason: "return_unavailable",
+  });
+});
+it("reconciles a paid payout that later fails and returns, preserving non-refundable fees", async () => {
+  const { t, args, reconcile, setPayout } = await setup();
+  await reconcile({ stripePayoutId: "po_one" });
+  setPayout({ status: "failed", failure_balance_transaction: "txn_return" });
+  expect(await reconcile()).toMatchObject({
+    status: "updated",
+    claim: { status: "returned", providerFee: 20 },
+  });
+  expect(await reconcile()).toMatchObject({
+    status: "updated",
+    claim: { status: "returned", providerFee: 20 },
+  });
+  expect(
+    await t.mutation(m("claim"), {
+      ...args,
+      operationKey: "next",
+      providerAvailable: 1500,
+    }),
+  ).toMatchObject({ status: "reserved", amount: 1480 });
+});
+it("rejects foreign owner, changed payout identity, money mismatch, missing markers, and old historical payouts", async () => {
+  for (const change of [
+    { amount: 999 },
+    { currency: "eur" },
+    { metadata: { bsPayoutClaim: "wrong" } },
+    { created: 1 },
+  ]) {
+    const { provider, reconcile, setPayout } = await setup();
+    setPayout(change);
+    if ("currency" in change || "amount" in change) {
+      const original =
+        provider.balanceTransactions.retrieve.getMockImplementation()!;
+      provider.balanceTransactions.retrieve.mockImplementation(async (id) => {
+        const transaction = await original(id);
+        const amount =
+          "amount" in change ? -change.amount! : transaction.amount;
+        return {
+          ...transaction,
+          amount,
+          net: amount - transaction.fee,
+          currency:
+            "currency" in change ? change.currency! : transaction.currency,
+        };
+      });
+    }
+    await expect(reconcile({ stripePayoutId: "po_one" })).rejects.toThrow(
+      /claim|receipt|attempt/,
+    );
+  }
+  const { reconcile } = await setup();
+  await reconcile({ stripePayoutId: "po_one" });
+  await expect(reconcile({ stripePayoutId: "po_other" })).rejects.toThrow(
+    /identity/,
+  );
+  await expect(reconcile({ ownerKey: "other" })).rejects.toThrow(
+    /owner|identity/,
+  );
+});
+it("keeps over-refunded fees explicitly unallocated", async () => {
+  const { provider, reconcile, setPayout } = await setup();
+  setPayout({ status: "failed", failure_balance_transaction: "txn_return" });
+  provider.balanceTransactions.retrieve.mockImplementation(async (id) => ({
+    id,
+    source: "po_one",
+    amount: id === "txn_debit" ? -1000 : 1000,
+    fee: id === "txn_debit" ? 30 : -31,
+    net: id === "txn_debit" ? -1030 : 1031,
+    currency: "usd",
+    status: "available",
+    created: 1,
+    available_on: 1,
+    type: id === "txn_debit" ? "payout" : "payout_failure",
+  }));
+  expect(await reconcile({ stripePayoutId: "po_one" })).toMatchObject({
+    status: "held",
+    reason: "fee_allocation_required",
+  });
+});
+it("never creates another payout after a persistence outage", async () => {
+  const { provider, reconcile, ctx } = await setup();
+  const real = ctx.runMutation!;
+  ctx.runMutation = vi
+    .fn()
+    .mockRejectedValueOnce(new Error("persistence unavailable")) as never;
+  await expect(reconcile()).rejects.toThrow("persistence unavailable");
+  ctx.runMutation = real;
+  expect(await reconcile()).toMatchObject({
+    status: "updated",
+    claim: { status: "paid" },
+  });
+  expect(provider.payouts.create).not.toHaveBeenCalled();
+});
+it("is available through the public payout policy client", async () => {
+  const { PayoutPolicyClient } = await import("../payoutPolicy.js");
+  const { ctx, provider } = await setup();
+  const client = new PayoutPolicyClient(
+    component,
+    () => provider as unknown as Stripe,
+  );
+  expect(client.reconcilePayout).toBeTypeOf("function");
+  expect(await client.reconcilePayout(ctx, scope)).toMatchObject({
+    status: "updated",
+  });
+});
+it.each([0, 0.5, 101, NaN])(
+  "rejects an invalid discovery budget %s before provider I/O",
+  async (maxPages) => {
+    const { provider, reconcile } = await setup();
+    await expect(reconcile({ maxPages })).rejects.toThrow(/budget/);
+    expect(provider.payouts.list).not.toHaveBeenCalled();
+  },
+);
+it("does not read Stripe for missing, unattempted, or terminal claims", async () => {
+  const { t, provider, reconcile } = await setup();
+  expect(await reconcile({ operationKey: "unknown" })).toMatchObject({
+    status: "held",
+    reason: "not_found",
+  });
+  await t.mutation(m("recordRejection"), {
+    ...scope,
+    requestId: "req_rejected",
+    code: "balance_insufficient",
+  });
+  expect(await reconcile()).toMatchObject({
+    status: "terminal",
+    claim: { status: "rejected" },
+  });
+  expect(provider.payouts.list).not.toHaveBeenCalled();
+  const unattempted = await setup(false);
+  expect(await unattempted.reconcile()).toMatchObject({
+    status: "held",
+    reason: "not_attempted",
+  });
+  expect(unattempted.provider.payouts.list).not.toHaveBeenCalled();
+});
+it("does not silently adopt a different source balance rail", async () => {
+  const { reconcile, setPayout } = await setup();
+  setPayout({ source_type: "bank_account" });
+  expect(await reconcile({ stripePayoutId: "po_one" })).toMatchObject({
+    status: "held",
+    reason: "source_allocation_required",
+  });
+});
+it("serializes concurrent outcome reconciliation without duplicate fees or principal", async () => {
+  const { t, reconcile, provider } = await setup();
+  const results = await Promise.all([reconcile(), reconcile()]);
+  expect(results.map((result) => result.status)).toEqual([
+    "updated",
+    "updated",
+  ]);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSourceAllocations").take(1)),
+  ).toMatchObject([{ paidAmount: 1000, reservedAmount: 0 }]);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutFeeBalances").take(1)),
+  ).toMatchObject([{ amount: 30, revision: 1 }]);
+  expect(provider.payouts.create).not.toHaveBeenCalled();
+});

package/src/client/connect/payoutReconciliation.ts

@@ -0,0 +1,174 @@
+import type Stripe from "stripe";
+import type { Infer } from "convex/values";
+import type { claimDoc } from "../../component/payoutRelease/schema.js";
+import { validateIdentity } from "../../component/payoutRelease/helpers.js";
+import { addSummaryAmounts } from "../../component/earnings/arithmetic.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import {
+  getRecipientPayoutReceipt,
+  type RecipientPayoutReceipt,
+} from "./payoutReceipt.js";
+export type PayoutReconciliationOptions = {
+  accountId: string;
+  ownerKey: string;
+  operationKey: string;
+  stripePayoutId?: string;
+  /** Complete discovery only. Exhausting this budget never adopts a partial match. */
+  maxPages?: number;
+};
+type Claim = Infer<typeof claimDoc>;
+export type PayoutReconciliation =
+  | { status: "terminal"; claim: Claim }
+  | {
+      status: "updated";
+      claim: Claim;
+      receipt: Extract<RecipientPayoutReceipt, { status: "ready" }>;
+    }
+  | {
+      status: "held";
+      reason:
+        | "not_found"
+        | "not_attempted"
+        | "payout_unidentified"
+        | "multiple_matches"
+        | "history_incomplete"
+        | "provider_changed"
+        | "fee_allocation_required"
+        | "source_allocation_required"
+        | Extract<RecipientPayoutReceipt, { status: "not_ready" }>["reason"];
+    };
+async function discover(
+  stripe: Stripe,
+  opts: PayoutReconciliationOptions,
+  claim: Claim,
+  maxPages: number,
+): Promise<
+  | { status: "found"; stripePayoutId: string }
+  | Extract<PayoutReconciliation, { status: "held" }>
+> {
+  const request = { stripeAccount: opts.accountId };
+  const created = {
+    gte: Math.max(0, Math.floor(claim.attemptedAt! / 1000) - 60),
+  };
+  const matches = new Set<string>();
+  let cursor: string | undefined;
+  let firstId: string | undefined;
+  for (let page = 0; page < maxPages; page++) {
+    const result = await stripe.payouts.list(
+      { limit: 100, created, ...(cursor ? { starting_after: cursor } : {}) },
+      request,
+    );
+    if (page === 0) firstId = result.data[0]?.id;
+    for (const payout of result.data)
+      if (payout.metadata?.bsPayoutClaim === opts.operationKey)
+        matches.add(payout.id);
+    if (!result.has_more) {
+      const head = await stripe.payouts.list({ limit: 1, created }, request);
+      if (head.data[0]?.id !== firstId)
+        return { status: "held", reason: "provider_changed" };
+      if (matches.size > 1)
+        return { status: "held", reason: "multiple_matches" };
+      if (!matches.size)
+        return { status: "held", reason: "payout_unidentified" };
+      return { status: "found", stripePayoutId: [...matches][0] };
+    }
+    const next = result.data[result.data.length - 1]?.id;
+    if (!next || next === cursor)
+      return { status: "held", reason: "history_incomplete" };
+    cursor = next;
+  }
+  return { status: "held", reason: "history_incomplete" };
+}
+/**
+ * Recover provider outcomes without creating or retrying a payout. Host must
+ * authorize account/owner/operation. A complete metadata match plus scoped
+ * receipts is required for adoption; no match never proves money did not move.
+ * Fees and principal are persisted together in the component transaction.
+ */
+export async function reconcileRecipientPayout(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  options: PayoutReconciliationOptions,
+): Promise<PayoutReconciliation> {
+  validateIdentity(options);
+  const maxPages = options.maxPages ?? 10;
+  if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 100)
+    throw new Error("Payout discovery page budget must be between 1 and 100.");
+  if (!ctx.runMutation)
+    throw new Error(
+      "Payout reconciliation requires a Convex ctx with runMutation.",
+    );
+  const identity = {
+    accountId: options.accountId,
+    ownerKey: options.ownerKey,
+    operationKey: options.operationKey,
+  };
+  const claim = (await ctx.runQuery(
+    componentRef(component, "payoutRelease/queries/get"),
+    identity,
+  )) as Claim | null;
+  if (!claim) return { status: "held", reason: "not_found" };
+  if (claim.status === "rejected" || claim.status === "canceled")
+    return { status: "terminal", claim };
+  if (claim.attemptedAt === undefined)
+    return { status: "held", reason: "not_attempted" };
+  if (
+    claim.stripePayoutId &&
+    options.stripePayoutId &&
+    claim.stripePayoutId !== options.stripePayoutId
+  )
+    throw new Error(
+      "Payout receipt identity conflicts with the durable claim.",
+    );
+  let payoutId = claim.stripePayoutId ?? options.stripePayoutId;
+  if (!payoutId) {
+    const result = await discover(stripe, options, claim, maxPages);
+    if (result.status === "held") return result;
+    payoutId = result.stripePayoutId;
+  }
+  const receipt = await getRecipientPayoutReceipt(stripe, {
+    accountId: options.accountId,
+    stripePayoutId: payoutId,
+    operationKey: options.operationKey,
+  });
+  if (receipt.status !== "ready")
+    return { status: "held", reason: receipt.reason };
+  if (receipt.amount !== claim.amount || receipt.currency !== claim.currency)
+    throw new Error("Payout receipt money does not match the durable claim.");
+  if (
+    receipt.created * 1000 < claim.attemptedAt - 60000 ||
+    receipt.created * 1000 > Date.now() + 60000
+  )
+    throw new Error(
+      "Payout receipt predates its durable attempt or has an invalid creation time.",
+    );
+  // 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")
+    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" };
+  const saved = (await runMutationOrThrow(
+    ctx,
+    componentRef(component, "payoutRelease/mutations/recordOutcome"),
+    {
+      ...identity,
+      stripePayoutId: receipt.stripePayoutId,
+      amount: receipt.amount,
+      currency: receipt.currency,
+      providerStatus: receipt.providerStatus,
+      debitTransactionId: receipt.debit.id,
+      debitFee: receipt.debit.fee,
+      ...(receipt.credit
+        ? {
+            returnTransactionId: receipt.credit.id,
+            returnFee: receipt.credit.fee,
+          }
+        : {}),
+    },
+  )) as Claim;
+  return { status: "updated", claim: saved, receipt };
+}

package/src/client/payoutPolicy.ts

@@ -1,3 +1,13 @@
+import {
+  reconcileRecipientPayout,
+  type PayoutReconciliationOptions,
+} from "./connect/payoutReconciliation.js";
+export type * from "./connect/payoutReconciliation.js";
+import {
+  getRecipientPayoutReceipt,
+  type RecipientPayoutReceiptOptions,
+} from "./connect/payoutReceipt.js";
+export type * from "./connect/payoutReceipt.js";
 import {
   getTransferFundingReceipt,
   type TransferReceiptOptions,
@@ -75,6 +85,12 @@ export class PayoutPolicyClient {
     private readonly component: Component,
     private readonly provider: () => Stripe,
   ) {}
+  reconcilePayout(ctx: RunCtx, opts: PayoutReconciliationOptions) {
+    return reconcileRecipientPayout(this.provider(), this.component, ctx, opts);
+  }
+  payoutReceipt(opts: RecipientPayoutReceiptOptions) {
+    return getRecipientPayoutReceipt(this.provider(), opts);
+  }
   transferReceipt(ctx: RunCtx, opts: TransferReceiptOptions) {
     return getTransferFundingReceipt(
       this.provider(),

package/src/component/_generated/api.ts

@@ -38,6 +38,7 @@ import type * as payoutPolicy_helpers from "../payoutPolicy/helpers.js";
 import type * as payoutPolicy_mutations from "../payoutPolicy/mutations.js";
 import type * as payoutPolicy_queries from "../payoutPolicy/queries.js";
 import type * as payoutRelease_allocation from "../payoutRelease/allocation.js";
+import type * as payoutRelease_fees from "../payoutRelease/fees.js";
 import type * as payoutRelease_helpers from "../payoutRelease/helpers.js";
 import type * as payoutRelease_mutations from "../payoutRelease/mutations.js";
 import type * as payoutRelease_queries from "../payoutRelease/queries.js";
@@ -89,6 +90,7 @@ const fullApi: ApiFromModules<{
   "payoutPolicy/mutations": typeof payoutPolicy_mutations;
   "payoutPolicy/queries": typeof payoutPolicy_queries;
   "payoutRelease/allocation": typeof payoutRelease_allocation;
+  "payoutRelease/fees": typeof payoutRelease_fees;
   "payoutRelease/helpers": typeof payoutRelease_helpers;
   "payoutRelease/mutations": typeof payoutRelease_mutations;
   "payoutRelease/queries": typeof payoutRelease_queries;