@fantastic.dev/better-stripe 0.28.6 → 0.29.0

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

@@ -0,0 +1,222 @@
+import type Stripe from "stripe";
+import { PayoutWorkerClient } from "./payoutWorker.js";
+import { reconcileRecipientPayout } from "./payoutReconciliation.js";
+// @vitest-environment edge-runtime
+import { expect, it, vi } from "vitest";
+import { makeFunctionReference } from "convex/server";
+import { setup, scope, component } from "./payoutExecutionTestHelpers.js";
+async function largeHistory(amount = 5) {
+  const s = await setup(Array.from({ length: 205 }, () => amount));
+  await s.t.run(async (ctx) => {
+    for (let i = 0; i < 101; i++)
+      await ctx.db.insert("payoutReleaseClaims", {
+        accountId: "acct_recipient",
+        ownerKey: "owner",
+        operationKey: `old-${i}`,
+        expectedRevision: 0,
+        currency: "usd",
+        amount: 1,
+        allocations: [{ stripeTransferId: "tr_0", amount: 1, role: "store" }],
+        observations: [],
+        status: "canceled",
+      });
+  });
+  s.provider.balanceTransactions.list.mockImplementation(async (params) => {
+    const p = params as typeof params & {
+      starting_after?: string;
+      currency?: string;
+    };
+    const all = s
+      .transactions()
+      .filter(
+        (t) =>
+          (!p.source || t.source === p.source) &&
+          (!p.currency || t.currency === p.currency),
+      );
+    const start = p.starting_after
+      ? all.findIndex((t) => t.id === p.starting_after) + 1
+      : 0;
+    const data = all.slice(start, start + (p.limit ?? 100));
+    return { data, has_more: start + data.length < all.length };
+  });
+  return s;
+}
+it("releases all 205 verified sources despite 101 terminal historical claims", async () => {
+  const s = await largeHistory();
+  expect(await s.run()).toMatchObject({
+    status: "updated",
+    claim: { status: "paid", amount: 1025 },
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toHaveLength(205);
+  await s.run();
+  expect(await s.run({ operationKey: "release-2" })).toMatchObject({
+    status: "held",
+    reason: "below_threshold",
+    matureUnpaid: 0,
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+  // Two complete 205-source passes exercise allocation rollups under coverage.
+}, 15_000);
+
+it("preserves a financially bound collection across a crash before attempt, then cancels exactly", async () => {
+  const s = await largeHistory();
+  const mutation = s.ctx.runMutation!;
+  const fault = vi
+    .spyOn(s.ctx, "runMutation")
+    .mockImplementation(async (...args) => {
+      const [ref] = args;
+      const path = (ref as unknown as Record<symbol, string>)[
+        Symbol.for("toReferencePath")
+      ];
+      if (path.endsWith("payoutRelease/mutations/beginAttempt"))
+        throw new Error("before-attempt outage");
+      return mutation(args[0], args[1] ?? {});
+    });
+  await expect(s.run()).rejects.toThrow("before-attempt outage");
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutSnapshots").first()),
+  ).toMatchObject({ readOnly: false, boundOperationKey: "release-1" });
+  fault.mockRestore();
+  expect(await s.run()).toMatchObject({
+    status: "terminal",
+    claim: { status: "canceled" },
+  });
+  const sources = await s.t.run((ctx) =>
+    ctx.db.query("payoutSourceAllocations").collect(),
+  );
+  expect(sources).toHaveLength(205);
+  expect(
+    sources.every((s) => s.reservedAmount === 0 && s.paidAmount === 0),
+  ).toBe(true);
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutSnapshots").collect()),
+  ).toEqual([]);
+});
+it("does not replace an unknown large-history payout outcome", async () => {
+  const s = await largeHistory();
+  s.provider.payouts.create.mockRejectedValueOnce(
+    new Error("provider outcome unknown"),
+  );
+  await expect(s.run()).rejects.toThrow("provider outcome unknown");
+  expect(await s.run()).toMatchObject({
+    status: "held",
+    reason: "payout_unidentified",
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+  const sources = await s.t.run((ctx) =>
+    ctx.db.query("payoutSourceAllocations").collect(),
+  );
+  expect(
+    sources.every((s) => s.reservedAmount === 5 && s.paidAmount === 0),
+  ).toBe(true);
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutSnapshots").collect()),
+  ).toEqual([]);
+});
+it("a source reversal after reservation invalidates the financial binding before Stripe", async () => {
+  const s = await largeHistory();
+  const verified = await s.verify();
+  s.verify.mockResolvedValueOnce(verified).mockImplementationOnce(async () => {
+    await s.t.mutation(
+      makeFunctionReference<"mutation">("connect/mutations:upsertTransfer"),
+      {
+        stripeTransferId: "tr_0",
+        destinationAccountId: "acct_recipient",
+        sourceChargeId: "ch_0",
+        amount: 5,
+        currency: "usd",
+        status: "reversed",
+        reversedAmount: 1,
+        role: "store",
+      },
+    );
+    return verified;
+  });
+  await expect(s.run()).rejects.toThrow(/collection changed/);
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+  expect(await s.run()).toMatchObject({
+    status: "terminal",
+    claim: { status: "canceled" },
+  });
+  const sources = await s.t.run((ctx) =>
+    ctx.db.query("payoutSourceAllocations").collect(),
+  );
+  expect(sources.every((s) => s.reservedAmount === 0)).toBe(true);
+});
+
+it("resumes a bounded collection under the same recurring worker operation", async () => {
+  const s = await largeHistory();
+  const worker = new PayoutWorkerClient(
+    component,
+    (_ctx, opts) => s.run(opts),
+    (_ctx, opts) =>
+      reconcileRecipientPayout(
+        s.provider as unknown as Stripe,
+        component,
+        s.ctx,
+        opts,
+      ),
+  );
+  const first = await worker.run(s.ctx, { ...scope, maxPages: 1 });
+  expect(first).toMatchObject({
+    status: "completed",
+    payout: { status: "held", reason: "collection_pending" },
+    job: { hasOperation: true },
+  });
+  if (first.status !== "completed")
+    throw new Error("Expected collection progress");
+  const clock = vi.spyOn(Date, "now").mockReturnValue(Date.now() + 300000);
+  try {
+    const next = await worker.run(s.ctx, { ...scope, maxPages: 10 });
+    expect(next).toMatchObject({
+      status: "completed",
+      payout: { claim: { amount: 1025, status: "paid" } },
+      job: { sequence: first.job.sequence, hasOperation: false },
+    });
+    expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+  } finally {
+    clock.mockRestore();
+  }
+});
+
+it("carries a complete larger history forward below the combined minimum", async () => {
+  const s = await largeHistory(4);
+  expect(await s.run()).toMatchObject({
+    status: "held",
+    reason: "below_threshold",
+    matureUnpaid: 820,
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toEqual([]);
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutSnapshots").collect()),
+  ).toEqual([]);
+});
+it("deducts known refund/dispute liabilities before qualifying a larger history", async () => {
+  const s = await largeHistory();
+  expect(await s.run({ independentLiabilities: 30 })).toMatchObject({
+    status: "held",
+    reason: "below_threshold",
+    matureUnpaid: 995,
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});
+it("does not verify provider data from another owner's historical claim", async () => {
+  const s = await largeHistory();
+  await s.t.run(async (ctx) => {
+    const claim = await ctx.db.query("payoutReleaseClaims").first();
+    await ctx.db.patch(claim!._id, { ownerKey: "other-owner" });
+  });
+  expect(await s.run()).toMatchObject({
+    status: "held",
+    reason: "collection_invalidated",
+  });
+  expect(s.provider.accounts.listExternalAccounts).not.toHaveBeenCalled();
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});

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

@@ -0,0 +1,221 @@
+// @vitest-environment edge-runtime
+import { expect, it } from "vitest";
+import { makeFunctionReference } from "convex/server";
+import { setup } from "./payoutExecutionTestHelpers.js";
+it("invalidates a liability version when refund costs increase before the attempt", async () => {
+  const s = await setup([600, 401]);
+  const cost = {
+    accountId: "acct_recipient",
+    scopeKey: "store:owner",
+    currency: "usd",
+    claimKey: "refund:new",
+    sourceChargeId: "ch_refunded",
+    sourceGross: 1001,
+    sourceProcessingFee: 2,
+    amountDue: 1,
+    revision: 1,
+  };
+  await s.t.mutation(
+    makeFunctionReference<"mutation">("costRecovery/mutations:record"),
+    cost,
+  );
+  const version = await s.t.run(
+    async (ctx) =>
+      (await ctx.db.query("payoutRiskRevisions").first())?.riskRevision ?? 0,
+  );
+  const verified = await s.verify();
+  s.verify.mockResolvedValueOnce(verified).mockImplementationOnce(async () => {
+    await s.t.mutation(
+      makeFunctionReference<"mutation">("costRecovery/mutations:record"),
+      { ...cost, amountDue: 2, revision: 2 },
+    );
+    return verified;
+  });
+  await expect(
+    s.run({ independentLiabilities: 1, liabilityRevision: version }),
+  ).rejects.toThrow(/liabilit|collection changed/);
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});
+
+it.each(["new", "increase", "decrease"])(
+  "rejects %s recovery costs before attempt and pays only after a fresh quote",
+  async (kind) => {
+    const { CostRecoveryClient } = await import("../costRecovery.js");
+    const { component } = await import("./payoutExecutionTestHelpers.js");
+    const s = await setup([600, 405]);
+    const client = new CostRecoveryClient(component);
+    const cost = {
+      accountId: "acct_recipient",
+      scopeKey: "store:owner",
+      currency: "usd",
+      claimKey: "refund:new",
+      sourceChargeId: "ch_refunded",
+      sourceGross: 1005,
+      sourceProcessingFee: 2,
+      amountDue: kind === "new" ? 0 : kind === "increase" ? 1 : 2,
+      revision: 1,
+    };
+    await s.t.mutation(
+      makeFunctionReference<"mutation">("costRecovery/mutations:record"),
+      cost,
+    );
+    const quote = await client.payoutQuote(s.ctx, cost);
+    const changed = kind === "increase" ? 2 : 1;
+    const verified = await s.verify();
+    s.verify
+      .mockResolvedValueOnce(verified)
+      .mockImplementationOnce(async () => {
+        await s.t.mutation(
+          makeFunctionReference<"mutation">("costRecovery/mutations:record"),
+          { ...cost, amountDue: changed, revision: 2 },
+        );
+        return verified;
+      });
+    await expect(s.run(quote)).rejects.toThrow(/collection changed/);
+    expect(s.provider.payouts.create).not.toHaveBeenCalled();
+    expect(await s.run(quote)).toMatchObject({
+      status: "terminal",
+      claim: { status: "canceled" },
+    });
+    const fresh = await client.payoutQuote(s.ctx, cost);
+    expect(fresh.independentLiabilities).toBe(changed);
+    expect(fresh.liabilityRevision).toBeGreaterThan(quote.liabilityRevision);
+    expect(
+      await s.run({ ...fresh, operationKey: "fresh-payout" }),
+    ).toMatchObject({
+      status: "updated",
+      claim: {
+        status: "paid",
+        amount: 1005 - changed,
+        liabilityRevision: fresh.liabilityRevision,
+      },
+    });
+    expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+  },
+);
+it("accepts unchanged atomic quotes and excludes costs from another currency", async () => {
+  const { CostRecoveryClient } = await import("../costRecovery.js");
+  const { component } = await import("./payoutExecutionTestHelpers.js");
+  const s = await setup([600, 405]);
+  const client = new CostRecoveryClient(component);
+  const cost = {
+    accountId: "acct_recipient",
+    scopeKey: "store:owner",
+    currency: "eur",
+    claimKey: "refund:eur",
+    sourceChargeId: "ch_refunded",
+    sourceGross: 1005,
+    sourceProcessingFee: 2,
+    amountDue: 2,
+    revision: 1,
+  };
+  await s.t.mutation(
+    makeFunctionReference<"mutation">("costRecovery/mutations:record"),
+    cost,
+  );
+  const quote = await client.payoutQuote(s.ctx, { ...cost, currency: "usd" });
+  expect(quote.independentLiabilities).toBe(0);
+  await s.t.mutation(
+    makeFunctionReference<"mutation">("costRecovery/mutations:record"),
+    cost,
+  );
+  expect(await client.payoutQuote(s.ctx, { ...cost, currency: "usd" })).toEqual(
+    quote,
+  );
+  expect(await s.run(quote)).toMatchObject({
+    status: "updated",
+    claim: { status: "paid", amount: 1005, currency: "usd" },
+  });
+});
+it("rejects a quote that is already stale before qualification", async () => {
+  const { CostRecoveryClient } = await import("../costRecovery.js");
+  const { component } = await import("./payoutExecutionTestHelpers.js");
+  const s = await setup([600, 405]);
+  const client = new CostRecoveryClient(component);
+  const cost = {
+    accountId: "acct_recipient",
+    scopeKey: "store:owner",
+    currency: "usd",
+    claimKey: "refund:new",
+    sourceChargeId: "ch_refunded",
+    sourceGross: 1005,
+    sourceProcessingFee: 2,
+    amountDue: 1,
+    revision: 1,
+  };
+  await s.t.mutation(
+    makeFunctionReference<"mutation">("costRecovery/mutations:record"),
+    cost,
+  );
+  const quote = await client.payoutQuote(s.ctx, cost);
+  await s.t.mutation(
+    makeFunctionReference<"mutation">("costRecovery/mutations:record"),
+    { ...cost, amountDue: 2, revision: 2 },
+  );
+  await expect(s.run(quote)).rejects.toThrow(/liability version changed/);
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});
+it("fails safely when a legacy unversioned caller gains recovery debt before attempt", async () => {
+  const s = await setup();
+  const verified = await s.verify();
+  s.verify.mockResolvedValueOnce(verified).mockImplementationOnce(async () => {
+    await s.t.mutation(
+      makeFunctionReference<"mutation">("costRecovery/mutations:record"),
+      {
+        accountId: "acct_recipient",
+        scopeKey: "store:owner",
+        currency: "usd",
+        claimKey: "refund:new",
+        sourceChargeId: "ch_refunded",
+        sourceGross: 1000,
+        sourceProcessingFee: 1,
+        amountDue: 1,
+        revision: 1,
+      },
+    );
+    return verified;
+  });
+  await expect(s.run()).rejects.toThrow(/versioned recovery liability quote/);
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});
+
+it("protects a versioned quote across a larger paginated collection", async () => {
+  const { CostRecoveryClient } = await import("../costRecovery.js");
+  const { component } = await import("./payoutExecutionTestHelpers.js");
+  const s = await setup(Array.from({ length: 205 }, () => 5));
+  const client = new CostRecoveryClient(component);
+  const cost = {
+    accountId: "acct_recipient",
+    scopeKey: "store:owner",
+    currency: "usd",
+    claimKey: "refund:new",
+    sourceChargeId: "ch_refunded",
+    sourceGross: 1025,
+    sourceProcessingFee: 2,
+    amountDue: 1,
+    revision: 1,
+  };
+  await s.t.mutation(
+    makeFunctionReference<"mutation">("costRecovery/mutations:record"),
+    cost,
+  );
+  const quote = await client.payoutQuote(s.ctx, cost);
+  const verified = await s.verify();
+  s.verify.mockResolvedValueOnce(verified).mockImplementationOnce(async () => {
+    await s.t.mutation(
+      makeFunctionReference<"mutation">("costRecovery/mutations:record"),
+      { ...cost, amountDue: 2, revision: 2 },
+    );
+    return verified;
+  });
+  await expect(s.run(quote)).rejects.toThrow(/collection changed/);
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+  await s.run(quote);
+  const fresh = await client.payoutQuote(s.ctx, cost);
+  expect(await s.run({ ...fresh, operationKey: "fresh-large" })).toMatchObject({
+    status: "updated",
+    claim: { status: "paid", amount: 1023, independentLiabilities: 2 },
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+  // This new integration case qualifies the full ledger twice, with a cancellation between.
+}, 15_000);

package/src/client/connect/payoutPreview.ts

@@ -1,3 +1,4 @@
+import { discardQualificationInput } from "./payoutCollectedInput.js";
 import type Stripe from "stripe";
 import type { Infer } from "convex/values";
 import type { Component, RunCtx } from "../helpers.js";
@@ -13,6 +14,7 @@ export type PayoutPreviewOptions = {
   ownerKey: string;
   currency: string;
   independentLiabilities: number;
+  liabilityRevision?: number;
   maxPages?: number;
 };
 export type PayoutPreview =
@@ -51,29 +53,45 @@ export async function previewRecipientPayout(
     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.currency === opts.currency && o.observedAt < Date.now() - 30000,
+  try {
+    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.currency === opts.currency && 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,
-    },
-  );
+      return held("observations_stale");
+    return await ctx.runQuery(
+      componentRef(component, "payoutRelease/queries/preview"),
+      {
+        accountId: opts.accountId,
+        ownerKey: opts.ownerKey,
+        currency: opts.currency,
+        expectedRevision: controls.policy.revision,
+        observations: proof.observations,
+        ...(opts.liabilityRevision === undefined
+          ? {}
+          : { liabilityRevision: opts.liabilityRevision }),
+        ...(proof.collection
+          ? { snapshotId: proof.collection.snapshotId }
+          : {}),
+        providerAvailable: proof.providerAvailable,
+        independentLiabilities: opts.independentLiabilities,
+      },
+    );
+  } finally {
+    await discardQualificationInput(
+      component,
+      ctx,
+      proof.collection,
+      proof.status === "held" && proof.reason === "collection_pending",
+    );
+  }
 }

package/src/client/connect/payoutQualification.ts

@@ -1,3 +1,8 @@
+import {
+  collectLargePayoutInput,
+  type CollectionRef,
+  type PayoutInput,
+} from "./payoutCollectedInput.js";
 import type Stripe from "stripe";
 import type { Infer } from "convex/values";
 import type { Component, RunCtx } from "../helpers.js";
@@ -30,6 +35,8 @@ export type PayoutProofScope = {
   accountId: string;
   ownerKey: string;
   currency: string;
+  operationKey?: string;
+  liabilityRevision?: number;
 };
 /** Shared provider qualification. It can reconcile existing receipts, but never creates a bank payout. */
 export async function collectPayoutQualification(
@@ -39,20 +46,45 @@ export async function collectPayoutQualification(
   opts: PayoutProofScope,
   maxPages: number,
 ): Promise<
-  | Held
+  | (Held & { collection?: CollectionRef })
   | {
       status: "verified";
+      collection?: CollectionRef;
       observations: Infer<typeof observation>[];
       destinationId: string;
       providerAvailable: number;
       observedAt: number;
     }
 > {
-  const snapshot = (await ctx.runQuery(
+  let snapshot = (await ctx.runQuery(
     componentRef(component, "payoutRelease/queries/snapshot"),
     { accountId: opts.accountId, ownerKey: opts.ownerKey },
   )) as Snapshot;
-  if (snapshot.status !== "ready") return snapshot;
+  let collection: CollectionRef | undefined;
+  if (snapshot.status !== "ready" || opts.liabilityRevision !== undefined) {
+    const large = await collectLargePayoutInput(component, ctx, opts, maxPages);
+    if (large.status !== "ready") return large;
+    collection = large.collection;
+    snapshot = large;
+  }
+  const result = await qualifyInput(
+    stripe,
+    component,
+    ctx,
+    opts,
+    maxPages,
+    snapshot,
+  );
+  return { ...result, ...(collection ? { collection } : {}) };
+}
+async function qualifyInput(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: PayoutProofScope,
+  maxPages: number,
+  snapshot: PayoutInput,
+): Promise<Awaited<ReturnType<typeof collectPayoutQualification>>> {
   const banks: string[] = [];
   let bankCursor: string | undefined;
   for (let page = 0; ; page++) {
@@ -109,24 +141,33 @@ export async function collectPayoutQualification(
         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);
+  for (let i = 0; i < snapshot.transfers.length; i += 5) {
+    const batch = snapshot.transfers.slice(i, i + 5);
+    const receipts = await Promise.all(
+      batch.map((row) =>
+        getTransferFundingReceipt(stripe, component, ctx, {
+          accountId: opts.accountId,
+          stripeTransferId: row.stripeTransferId,
+        }),
+      ),
+    );
+    for (let j = 0; j < batch.length; j++) {
+      const row = batch[j],
+        receipt = receipts[j];
+      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,

package/src/client/connect/payoutWorker.ts

@@ -127,6 +127,9 @@ export class PayoutWorkerClient {
             ...scope,
             operationKey,
             independentLiabilities: opts.independentLiabilities,
+            ...(opts.liabilityRevision === undefined
+              ? {}
+              : { liabilityRevision: opts.liabilityRevision }),
             maxPages: opts.maxPages,
           });
     } catch (error) {
@@ -163,7 +166,7 @@ export function payoutAttemptStatus(
       : (job.lastReason ?? "pending_claim");
   const status = running
     ? "running"
-    : job.hasOperation
+    : job.hasOperation && reason !== "collection_pending"
       ? "reconciling"
       : ["balance_insufficient", "amount_too_small", "rejected"].includes(
             reason,

package/src/client/costRecovery.ts

@@ -241,6 +241,14 @@ export class CostRecoveryClient {
   ) {
     return this.mutate<RecoveryClaim>(ctx, "mutations/rollback", opts);
   }
+  /** Host authorizes the recovery scope; pass this atomic quote unchanged to payout qualification. */
+  payoutQuote(ctx: RunCtx, opts: RecoveryScope) {
+    const { accountId, scopeKey, currency } = opts;
+    return this.query<{
+      independentLiabilities: number;
+      liabilityRevision: number;
+    }>(ctx, "payoutQuote", { accountId, scopeKey, currency });
+  }
   balance(ctx: RunCtx, opts: RecoveryScope) {
     return this.query<RecoveryBalance>(ctx, "balance", opts);
   }