@fantastic.dev/better-stripe 0.25.1 → 0.26.0

package/docs/settlement.md

@@ -607,6 +607,63 @@ These are server worker APIs, not manual withdrawal actions for a customer UI.
 for an authorized host to display. Bank availability, pending funds and bank
 arrival dates come from the recipient payout snapshot API.
 
+## Payout eligibility preview
+
+An authorized server action can assess a custom policy before displaying its
+progress. It uses the same provider receipt qualification and local allocation
+plan as release:
+
+```ts
+const preview = await stripe.payoutPolicy.preview(ctx, {
+  accountId,
+  ownerKey,
+  currency,
+  independentLiabilities,
+});
+const job = await stripe.payoutPolicy.worker.get(ctx, {
+  accountId,
+  ownerKey,
+  currency,
+});
+```
+
+Authorize the owner/account mapping and derive independent liabilities on the
+server, exactly as for the automatic worker. The preview reads Stripe and can
+reconcile existing payout receipts in the component. It never creates a bank
+payout, reserves funds, or invokes the worker. The caller needs an action context
+that permits component queries and reconciliation mutations.
+
+A detailed result includes `currency`, `threshold`, `matureUnpaid`,
+`pendingCredits`, `confirmedFees`, `independentLiabilities`, `providerAvailable`,
+`amount`, `observedAt` and `sources`. Each source category reports its signed
+mature unpaid entitlement and pending credits. Category amounts are before shared
+fees and independent liabilities. Those deductions reduce the combined
+`matureUnpaid` once. Negative entitlement after a refund survives the calculation;
+pending credits never qualify. `amount` is the amount currently qualified for the
+supported bank payout rail, or zero when held. `providerMinimum: null` means the
+numeric Stripe floor is unknown, not zero.
+
+Below-threshold funds remain owed. `insufficient_available` distinguishes enough
+qualifying earnings from insufficient provider funds on the supported rail. Some
+holds return only `{ status: "held", reason, amount: 0 }`, including incomplete
+history, unverified controls and unresolved affiliate recovery. Such a result
+does **not** establish a zero balance or zero debt. Render an unavailable
+assessment with its reason, rather than inventing amounts. Ledger changes during
+the final query reject the assessment and require a refresh.
+
+The preview verifies policy controls again after reading provider data. Source
+and balance observations older than 30 seconds do not qualify. Display
+`observedAt` as an assessment time; release independently repeats qualification
+and reserves funds atomically. A qualified preview is neither a promised payout
+nor authorization to call Stripe. `job.nextAttemptAt` is the next application
+attempt. Bank arrival dates remain separate provider data from
+`getPayoutSnapshot`.
+
+Stripe-managed recipients keep Stripe's default automatic schedule. This preview
+requires a ready custom policy and preserves the current source/history limits,
+region restrictions and supported payout rail. It does not remove the need for
+provider-history continuation on larger accounts.
+
 ## Resumable local collections
 
 An authorized host worker can collect the local recipient ledger in bounded

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",

package/src/client/connect/payoutExecution.ts

@@ -4,17 +4,9 @@ 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 { validateIdentity } from "../../component/payoutRelease/helpers.js";
+import { collectPayoutQualification } from "./payoutQualification.js";
 import {
   reconcileRecipientPayout,
   type PayoutReconciliation,
@@ -32,13 +24,6 @@ export type PayoutReleaseOptions = {
 };
 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
@@ -94,86 +79,14 @@ export async function releaseRecipientPayout(
   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,
+  const proof = await collectPayoutQualification(
+    stripe,
+    component,
+    ctx,
+    opts,
     maxPages,
-  });
-  if (history.status !== "verified") return history;
+  );
+  if (proof.status !== "verified") return proof;
   const claim = (await runMutationOrThrow(
     ctx,
     componentRef(component, "payoutRelease/mutations/claim"),
@@ -181,10 +94,10 @@ export async function releaseRecipientPayout(
       ...identity,
       expectedRevision: controls.policy.revision,
       currency: opts.currency,
-      destinationId,
-      providerAvailable: history.providerAvailable,
+      destinationId: proof.destinationId,
+      providerAvailable: proof.providerAvailable,
       independentLiabilities: opts.independentLiabilities,
-      observations,
+      observations: proof.observations,
     },
   )) as Claim | Held;
   if (claim.status === "held") return claim;

package/src/client/connect/payoutExecutionTestHelpers.ts

@@ -122,22 +122,24 @@ export async function setup(amounts = [600, 400]) {
       ),
     },
     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
+      retrieve: vi.fn(
+        async (): Promise<Pick<Stripe.Balance, "available" | "pending">> => ({
+          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: [],
-      })),
+          ],
+          pending: [],
+        }),
+      ),
     },
     payouts: {
       list: vi.fn(async () => ({

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

@@ -0,0 +1,269 @@
+// @vitest-environment edge-runtime
+import { afterEach, expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import { setup, scope, component } from "./payoutExecutionTestHelpers.js";
+import { previewRecipientPayout } from "./payoutPreview.js";
+import { changeBalance } from "../../component/affiliateRecovery/accounting.js";
+afterEach(() => vi.restoreAllMocks());
+async function preview(amounts?: number[]) {
+  const s = await setup(amounts);
+  const run = (extra = {}) =>
+    previewRecipientPayout(
+      s.provider as unknown as Stripe,
+      component,
+      s.ctx,
+      { ...scope, ...extra },
+      s.verify,
+    );
+  return { ...s, preview: run };
+}
+it("previews combined eligibility and source categories without creating or reserving a payout", async () => {
+  const s = await preview();
+  expect(await s.preview()).toMatchObject({
+    status: "qualified",
+    amount: 1000,
+    matureUnpaid: 1000,
+    pendingCredits: 0,
+    threshold: 1000,
+    providerMinimum: null,
+    sources: [
+      { role: "store", matureUnpaid: 600, pendingCredits: 0 },
+      { role: "affiliate", matureUnpaid: 400, pendingCredits: 0 },
+      { role: "other", matureUnpaid: 0, pendingCredits: 0 },
+    ],
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+  ).toEqual([]);
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toEqual([]);
+});
+it("shows below-threshold carry forward and independent liabilities", async () => {
+  const s = await preview([599, 400]);
+  expect(await s.preview({ independentLiabilities: 100 })).toMatchObject({
+    status: "held",
+    reason: "below_threshold",
+    matureUnpaid: 899,
+    amount: 0,
+    independentLiabilities: 100,
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});
+it("reports the shared affiliate recovery hold without treating the debt as payable", async () => {
+  const s = await preview();
+  await s.t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "usd", { outstandingDebt: 100 }),
+  );
+  expect(await s.preview()).toMatchObject({
+    status: "held",
+    reason: "affiliate_recovery_pending",
+    amount: 0,
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});
+it("subtracts a previously paid claim while verifying its current provider receipt", async () => {
+  const s = await preview();
+  await s.run();
+  expect(await s.preview()).toMatchObject({
+    status: "held",
+    reason: "below_threshold",
+    matureUnpaid: 0,
+    amount: 0,
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});
+it("rejects an expired provider balance observation even when there are no transfer observations", async () => {
+  const s = await preview([]);
+  const policy = await s.verify();
+  const now = Date.now();
+  const clock = vi.spyOn(Date, "now").mockReturnValue(now);
+  s.verify.mockResolvedValueOnce(policy).mockImplementationOnce(async () => {
+    clock.mockReturnValue(now + 31000);
+    return policy;
+  });
+  expect(await s.preview()).toMatchObject({
+    status: "held",
+    reason: "observations_stale",
+    amount: 0,
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});
+it("keeps pending credits out of the qualifying combined balance", async () => {
+  const s = await preview();
+  s.setTransactions(
+    s.transactions().map((row, index) => ({
+      ...row,
+      status: index === 0 ? "pending" : "available",
+    })),
+  );
+  s.provider.balance.retrieve.mockResolvedValue({
+    available: [{ currency: "usd", amount: 400, source_types: { card: 400 } }],
+    pending: [{ currency: "usd", amount: 600 }],
+  });
+  expect(await s.preview()).toMatchObject({
+    status: "held",
+    reason: "below_threshold",
+    amount: 0,
+    matureUnpaid: 400,
+    pendingCredits: 600,
+    sources: [
+      { role: "store", matureUnpaid: 0, pendingCredits: 600 },
+      { role: "affiliate", matureUnpaid: 400, pendingCredits: 0 },
+      { role: "other", matureUnpaid: 0, pendingCredits: 0 },
+    ],
+  });
+});
+it("distinguishes qualified earnings from insufficient funds on the supported payout rail", async () => {
+  const s = await preview();
+  s.provider.balance.retrieve.mockResolvedValue({
+    available: [{ currency: "usd", amount: 1000, source_types: { card: 500 } }],
+    pending: [],
+  });
+  expect(await s.preview()).toMatchObject({
+    status: "held",
+    reason: "insufficient_available",
+    matureUnpaid: 1000,
+    providerAvailable: 500,
+    amount: 0,
+  });
+});
+it("deducts confirmed payout costs without attributing shared costs to a source category", async () => {
+  const s = await preview([700, 400]);
+  await s.t.run((ctx) =>
+    ctx.db.insert("payoutFeeBalances", {
+      accountId: scope.accountId,
+      ownerKey: scope.ownerKey,
+      currency: "usd",
+      amount: 150,
+      revision: 1,
+    }),
+  );
+  expect(await s.preview()).toMatchObject({
+    status: "held",
+    reason: "below_threshold",
+    matureUnpaid: 950,
+    confirmedFees: 150,
+    sources: [
+      { role: "store", matureUnpaid: 700 },
+      { role: "affiliate", matureUnpaid: 400 },
+      { role: "other", matureUnpaid: 0 },
+    ],
+  });
+});
+it("does not show unverifiable history as a zero balance", async () => {
+  const s = await preview();
+  s.setTransactions([
+    ...s.transactions(),
+    {
+      ...s.transactions()[0],
+      id: "txn_unknown",
+      source: "po_unknown",
+      type: "payout",
+      amount: -100,
+      net: -100,
+    },
+  ]);
+  expect(await s.preview()).toEqual({
+    status: "held",
+    reason: "unallocated_history",
+    amount: 0,
+  });
+});
+it("holds if controls change during provider qualification", async () => {
+  const s = await preview();
+  const controls = await s.verify();
+  s.verify.mockResolvedValueOnce(controls).mockResolvedValueOnce({
+    ...controls,
+    policy: { ...controls.policy, revision: controls.policy.revision + 1 },
+  });
+  expect(await s.preview()).toEqual({
+    status: "held",
+    reason: "policy_changed",
+    amount: 0,
+  });
+});
+it("rejects ledger changes between provider reads and the final plan", async () => {
+  const s = await preview();
+  const controls = await s.verify();
+  s.verify.mockResolvedValueOnce(controls).mockImplementationOnce(async () => {
+    await s.t.run(async (ctx) => {
+      const transfer = await ctx.db.query("transfers").first();
+      await ctx.db.patch("transfers", transfer!._id, { reversedAmount: 100 });
+    });
+    return controls;
+  });
+  await expect(s.preview()).rejects.toThrow("snapshot changed");
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});
+it("preserves negative affiliate entitlement when a paid commission is refunded", async () => {
+  const s = await preview();
+  await s.run();
+  await s.t.run(async (ctx) => {
+    const row = await ctx.db
+      .query("transfers")
+      .withIndex("by_stripe_transfer_id", (q) =>
+        q.eq("stripeTransferId", "tr_1"),
+      )
+      .unique();
+    await ctx.db.patch("transfers", row!._id, { reversedAmount: 100 });
+  });
+  const original = s.provider.transfers.retrieve.getMockImplementation()!;
+  s.provider.transfers.retrieve.mockImplementation(async (id) => ({
+    ...(await original(id)),
+    amount_reversed: id === "tr_1" ? 100 : 0,
+  }));
+  Object.assign(s.provider.transfers, {
+    listReversals: vi.fn(async (id: string) => ({
+      data:
+        id === "tr_1"
+          ? [
+              {
+                id: "trr_one",
+                transfer: id,
+                amount: 100,
+                currency: "usd",
+                destination_payment_refund: "pyr_one",
+              },
+            ]
+          : [],
+      has_more: false,
+    })),
+  });
+  Object.assign(s.provider, {
+    refunds: {
+      retrieve: vi.fn(async () => ({
+        id: "pyr_one",
+        charge: "py_1",
+        amount: 100,
+        currency: "usd",
+        status: "succeeded",
+        balance_transaction: "txn_refund",
+      })),
+    },
+  });
+  s.setTransactions([
+    ...s.transactions(),
+    {
+      ...s.transactions()[0],
+      id: "txn_refund",
+      source: "pyr_one",
+      amount: -100,
+      net: -100,
+      type: "payment_refund",
+    },
+  ]);
+  expect(await s.preview()).toMatchObject({
+    status: "held",
+    reason: "below_threshold",
+    amount: 0,
+    matureUnpaid: -100,
+    sources: [
+      { role: "store", matureUnpaid: 0 },
+      { role: "affiliate", matureUnpaid: -100 },
+      { role: "other", matureUnpaid: 0 },
+    ],
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});

package/src/client/connect/payoutPreview.ts

@@ -0,0 +1,77 @@
+import type Stripe from "stripe";
+import type { Infer } from "convex/values";
+import type { Component, RunCtx } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { validateScope } from "../../component/payoutPolicy/helpers.js";
+import type { previewResult } from "../../component/payoutRelease/preview.js";
+import {
+  collectPayoutQualification,
+  type PayoutControlVerification,
+} from "./payoutQualification.js";
+export type PayoutPreviewOptions = {
+  accountId: string;
+  ownerKey: string;
+  currency: string;
+  independentLiabilities: number;
+  maxPages?: number;
+};
+export type PayoutPreview =
+  Infer<typeof previewResult> | { status: "held"; reason: string; amount: 0 };
+/** Informational assessment only. Release always repeats qualification and atomically reserves funds. */
+export async function previewRecipientPayout(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: PayoutPreviewOptions,
+  verify: PayoutControlVerification,
+): Promise<PayoutPreview> {
+  validateScope(opts);
+  const maxPages = opts.maxPages ?? 10;
+  if (
+    !/^[a-z]{3}$/.test(opts.currency) ||
+    !Number.isSafeInteger(opts.independentLiabilities) ||
+    opts.independentLiabilities < 0 ||
+    !Number.isInteger(maxPages) ||
+    maxPages < 1 ||
+    maxPages > 100
+  )
+    throw new Error("Invalid payout preview scope or budget.");
+  const held = (reason: string) => ({
+    status: "held" as const,
+    reason,
+    amount: 0 as const,
+  });
+  const controls = await verify();
+  if (controls.status !== "verified" || !("policy" in controls))
+    return held(controls.status);
+  const proof = await collectPayoutQualification(
+    stripe,
+    component,
+    ctx,
+    opts,
+    maxPages,
+  );
+  if (proof.status !== "verified") return held(proof.reason);
+  const latest = await verify();
+  if (latest.status !== "verified" || !("policy" in latest))
+    return held(latest.status);
+  if (latest.policy.revision !== controls.policy.revision)
+    return held("policy_changed");
+  if (
+    proof.observedAt < Date.now() - 30000 ||
+    proof.observations.some((o) => o.observedAt < Date.now() - 30000)
+  )
+    return held("observations_stale");
+  return ctx.runQuery(
+    componentRef(component, "payoutRelease/queries/preview"),
+    {
+      accountId: opts.accountId,
+      ownerKey: opts.ownerKey,
+      currency: opts.currency,
+      expectedRevision: controls.policy.revision,
+      observations: proof.observations,
+      providerAvailable: proof.providerAvailable,
+      independentLiabilities: opts.independentLiabilities,
+    },
+  );
+}