@fantastic.dev/better-stripe 0.23.2 → 0.25.0

package/src/client/connect/reversalExecution.ts

@@ -0,0 +1,130 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { findCommissionReversal } from "./commissionReceipts.js";
+
+export type ClaimedSlice = {
+  stripeTransferId: string;
+  /** Cumulative reversed amount this slice starts from. */
+  from: number;
+  /** Cumulative reversed amount this slice raises the leg to. */
+  to: number;
+  /** The leg's confirmed `reversedAmount` at claim time. */
+  confirmed: number;
+  commissionTracked?: boolean;
+};
+
+export type ReversalClaim = { replay: boolean; slices: ClaimedSlice[] };
+
+/**
+ * Execute the slices an operation claimed via `claimReversalSlices` (BTS-63).
+ * The claim already reserved this money atomically, so all that's left is
+ * moving it: one `bs_rev_<operationId>_<transferId>` reversal per slice, then
+ * confirming the new cumulative total in the ledger. A replayed claim always
+ * re-sends byte-identical params under the same key, which Stripe answers
+ * from its idempotency cache without moving money twice.
+ *
+ * Because Stripe prunes idempotency keys after ~24h (and a crash can land
+ * between the Stripe call and the ledger confirm), a replay first checks the
+ * transfer's live `amount_reversed`: if the slice's money already moved, it
+ * just confirms the ledger instead of re-sending the reversal.
+ *
+ * A slice only executes once every predecessor slice on its leg is confirmed
+ * (`confirmed ≥ from`). Without that gate, a sibling operation landing behind
+ * a transiently-failed claim would execute and confirm PAST the hole; the
+ * failed operation's retry would then see `confirmed ≥ to` and silently skip
+ * — its money would never move while the ledger says it did. Throwing instead
+ * fails this operation's webhook event, and at-least-once delivery retries
+ * both operations until the predecessor fills its hole and each claimed slice
+ * has actually moved. The ledger's `reversedAmount` therefore always covers a
+ * solid, hole-free prefix of the reversed axis — which is exactly what makes
+ * the `confirmed`/`amount_reversed` checks above sound.
+ */
+export async function executeClaimedSlices(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  operationId: string,
+  claim: ReversalClaim,
+): Promise<{ reversals: { stripeTransferId: string; amount: number }[] }> {
+  const reversals: { stripeTransferId: string; amount: number }[] = [];
+  for (const slice of claim.slices) {
+    const receiptAmount = slice.to - slice.from;
+    if (slice.commissionTracked && claim.replay) {
+      const receipt = await findCommissionReversal(
+        stripe,
+        slice.stripeTransferId,
+        operationId,
+        receiptAmount,
+      );
+      if (receipt) {
+        await runMutationOrThrow(
+          ctx,
+          componentRef(component, "connect/mutations/recordTransferReversal"),
+          {
+            stripeTransferId: slice.stripeTransferId,
+            reversedAmount: slice.to,
+            receipt: {
+              stripeReversalId: receipt.id,
+              operationId,
+              amount: receiptAmount,
+            },
+          },
+        );
+        continue;
+      }
+      if (slice.confirmed >= slice.to)
+        throw new Error("Commission reversal requires receipt reconciliation.");
+    }
+    if (slice.confirmed >= slice.to) continue; // executed and recorded already
+
+    if (slice.confirmed < slice.from) {
+      throw new Error(
+        `reversal slice [${slice.from},${slice.to}) on ${slice.stripeTransferId} ` +
+          `blocked: predecessor claim unexecuted (confirmed=${slice.confirmed})`,
+      );
+    }
+
+    if (claim.replay && !slice.commissionTracked) {
+      const transfer = await stripe.transfers.retrieve(slice.stripeTransferId);
+      if ((transfer.amount_reversed ?? 0) >= slice.to) {
+        // The money moved on a previous attempt that died before confirming.
+        await runMutationOrThrow(
+          ctx,
+          componentRef(component, "connect/mutations/recordTransferReversal"),
+          {
+            stripeTransferId: slice.stripeTransferId,
+            reversedAmount: slice.to,
+          },
+        );
+        continue;
+      }
+    }
+
+    const amount = slice.to - slice.from;
+    const receipt = await stripe.transfers.createReversal(
+      slice.stripeTransferId,
+      {
+        amount,
+        ...(slice.commissionTracked
+          ? { metadata: { bsReversalOperation: operationId } }
+          : {}),
+      },
+      { idempotencyKey: `bs_rev_${operationId}_${slice.stripeTransferId}` },
+    );
+    await runMutationOrThrow(
+      ctx,
+      componentRef(component, "connect/mutations/recordTransferReversal"),
+      {
+        stripeTransferId: slice.stripeTransferId,
+        reversedAmount: slice.to,
+        ...(slice.commissionTracked
+          ? { receipt: { stripeReversalId: receipt.id, operationId, amount } }
+          : {}),
+      },
+    );
+    reversals.push({ stripeTransferId: slice.stripeTransferId, amount });
+  }
+  return { reversals };
+}

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

@@ -350,8 +350,8 @@ describe("createSplitTransfers engine (BTS-22)", () => {
       destination: "acct_aff",
     });
     // ledger rows
-    expect(ctx.runMutation).toHaveBeenCalledTimes(3);
-    expect(ctx.runMutation.mock.calls[1][1]).toMatchObject({
+    expect(ctx.runMutation).toHaveBeenCalledTimes(4);
+    expect(ctx.runMutation.mock.calls[2][1]).toMatchObject({
       sourceChargeId: "ch_1",
       destinationAccountId: "acct_store",
       amount: 8000,
@@ -380,7 +380,7 @@ describe("createSplitTransfers engine (BTS-22)", () => {
     });
 
     expect(stripe.transfers.create).toHaveBeenCalledTimes(3);
-    expect(ctx.runMutation).toHaveBeenCalledTimes(4);
+    expect(ctx.runMutation).toHaveBeenCalledTimes(5);
   });
 
   it("skips zero-amount transfers", async () => {

package/src/client/connect/transfers.ts

@@ -1,3 +1,9 @@
+import { reconcileAffiliateCharge } from "../affiliateRecovery/engine.js";
+import {
+  executeClaimedSlices,
+  type ClaimedSlice,
+  type ReversalClaim,
+} from "./reversalExecution.js";
 import { recoverSettlementTransfers } from "../settlement/reconciliation.js";
 import { executeResolvedTransfers } from "../settlement/execution.js";
 import type Stripe from "stripe";
@@ -19,90 +25,22 @@ type LedgerTransfer = {
   currency?: string;
 };
 
-type ClaimedSlice = {
-  stripeTransferId: string;
-  /** Cumulative reversed amount this slice starts from. */
-  from: number;
-  /** Cumulative reversed amount this slice raises the leg to. */
-  to: number;
-  /** The leg's confirmed `reversedAmount` at claim time. */
-  confirmed: number;
-};
-
-type ReversalClaim = { replay: boolean; slices: ClaimedSlice[] };
-
-/**
- * Execute the slices an operation claimed via `claimReversalSlices` (BTS-63).
- * The claim already reserved this money atomically, so all that's left is
- * moving it: one `bs_rev_<operationId>_<transferId>` reversal per slice, then
- * confirming the new cumulative total in the ledger. A replayed claim always
- * re-sends byte-identical params under the same key, which Stripe answers
- * from its idempotency cache without moving money twice.
- *
- * Because Stripe prunes idempotency keys after ~24h (and a crash can land
- * between the Stripe call and the ledger confirm), a replay first checks the
- * transfer's live `amount_reversed`: if the slice's money already moved, it
- * just confirms the ledger instead of re-sending the reversal.
- *
- * A slice only executes once every predecessor slice on its leg is confirmed
- * (`confirmed ≥ from`). Without that gate, a sibling operation landing behind
- * a transiently-failed claim would execute and confirm PAST the hole; the
- * failed operation's retry would then see `confirmed ≥ to` and silently skip
- * — its money would never move while the ledger says it did. Throwing instead
- * fails this operation's webhook event, and at-least-once delivery retries
- * both operations until the predecessor fills its hole and each claimed slice
- * has actually moved. The ledger's `reversedAmount` therefore always covers a
- * solid, hole-free prefix of the reversed axis — which is exactly what makes
- * the `confirmed`/`amount_reversed` checks above sound.
- */
-async function executeClaimedSlices(
-  stripe: Stripe,
+async function trackedAffiliateTransfers(
   component: Component,
   ctx: RunCtx,
-  operationId: string,
-  claim: ReversalClaim,
-): Promise<{ reversals: { stripeTransferId: string; amount: number }[] }> {
-  const reversals: { stripeTransferId: string; amount: number }[] = [];
-  for (const slice of claim.slices) {
-    if (slice.confirmed >= slice.to) continue; // executed and recorded already
-
-    if (slice.confirmed < slice.from) {
-      throw new Error(
-        `reversal slice [${slice.from},${slice.to}) on ${slice.stripeTransferId} ` +
-          `blocked: predecessor claim unexecuted (confirmed=${slice.confirmed})`,
-      );
-    }
-
-    if (claim.replay) {
-      const transfer = await stripe.transfers.retrieve(slice.stripeTransferId);
-      if ((transfer.amount_reversed ?? 0) >= slice.to) {
-        // The money moved on a previous attempt that died before confirming.
-        await runMutationOrThrow(
-          ctx,
-          componentRef(component, "connect/mutations/recordTransferReversal"),
-          {
-            stripeTransferId: slice.stripeTransferId,
-            reversedAmount: slice.to,
-          },
-        );
-        continue;
-      }
-    }
-
-    const amount = slice.to - slice.from;
-    await stripe.transfers.createReversal(
-      slice.stripeTransferId,
-      { amount },
-      { idempotencyKey: `bs_rev_${operationId}_${slice.stripeTransferId}` },
-    );
-    await runMutationOrThrow(
-      ctx,
-      componentRef(component, "connect/mutations/recordTransferReversal"),
-      { stripeTransferId: slice.stripeTransferId, reversedAmount: slice.to },
-    );
-    reversals.push({ stripeTransferId: slice.stripeTransferId, amount });
-  }
-  return { reversals };
+  sourceChargeId: string,
+) {
+  const rows = (await ctx.runQuery(
+    componentRef(component, "affiliateRecovery/queries/chargeObligations"),
+    { sourceChargeId },
+  )) as { accounted?: boolean; stripeTransferId?: string }[] | null;
+  return new Set(
+    Array.isArray(rows)
+      ? rows
+          .filter((row) => row.accounted && row.stripeTransferId)
+          .map((row) => row.stripeTransferId!)
+      : [],
+  );
 }
 
 /** A wedged reversal claim surfaced by {@link listWedgedReversalClaims}. */
@@ -120,6 +58,7 @@ type ReversalOpRecord = {
   sourceChargeId: string;
   slices: { stripeTransferId: string; from: number; to: number }[];
   _creationTime: number;
+  commissionExposure?: { kind: "refund" | "dispute" };
 };
 
 /** Stripe prunes idempotency keys after ~24h; a release must wait past this. */
@@ -212,19 +151,43 @@ export async function reclaimReversalClaim(
       const leg = (await ctx.runQuery(
         componentRef(component, "connect/queries/getTransferByStripeId"),
         { stripeTransferId: s.stripeTransferId },
-      )) as { reversedAmount?: number } | null;
-      slices.push({ ...s, confirmed: leg?.reversedAmount ?? 0 });
+      )) as { reversedAmount?: number; role?: string } | null;
+      slices.push({
+        ...s,
+        confirmed: leg?.reversedAmount ?? 0,
+        ...(op.commissionExposure
+          ? { commissionTracked: leg?.role === "affiliate" }
+          : {}),
+      });
     }
+    const tracked = op.commissionExposure
+      ? null
+      : await trackedAffiliateTransfers(component, ctx, op.sourceChargeId);
+    const usesRecoveryLedger = !!op.commissionExposure || !!tracked?.size;
     const { reversals } = await executeClaimedSlices(
       stripe,
       component,
       ctx,
       op.operationId,
-      { replay: true, slices },
+      {
+        replay: true,
+        slices: slices.filter(
+          (s) => !s.commissionTracked && !tracked?.has(s.stripeTransferId),
+        ),
+      },
     );
+    if (usesRecoveryLedger)
+      await reconcileAffiliateCharge(stripe, component, ctx, op.sourceChargeId);
     return { mode: "reexecute", reversals };
   }
 
+  if (
+    op.commissionExposure ||
+    (await trackedAffiliateTransfers(component, ctx, op.sourceChargeId)).size
+  )
+    throw new Error(
+      "Affiliate exposure audit claims cannot be released; use affiliateRecovery.retry or reviewLegacy.",
+    );
   // release: age-gate against the idempotency window, then verify live Stripe.
   const minAgeMs = opts.minAgeMs ?? REVERSAL_IDEMPOTENCY_WINDOW_MS;
   const now = opts.now ?? Date.now();
@@ -306,6 +269,13 @@ export async function reverseTransfers(
   }
 
   await recoverSettlementTransfers(stripe, component, ctx, opts.sourceChargeId);
+  if (
+    (await trackedAffiliateTransfers(component, ctx, opts.sourceChargeId)).size
+  )
+    throw new Error(
+      "Use affiliateRecovery.retry for tracked affiliate commission recovery.",
+    );
+
   if (opts.operationId) {
     const claim = (await runMutationOrThrow(
       ctx,
@@ -389,9 +359,9 @@ export async function reverseTransfers(
 }
 
 /**
- * Reverse a split sale's transfers pro-rata to the cumulatively refunded
- * amount (BTS-34) — the refund counterpart of the dispute clawback. Every leg
- * converges on a cumulative reversal TARGET, `round(leg × amountRefunded /
+ * Reverse a split sale's transfers pro-rata to cumulative succeeded refunds.
+ * Affiliate legs retain the larger refund/dispute commission exposure. Other
+ * legs converge on a cumulative reversal TARGET, `round(leg × amountRefunded /
  * chargeAmount)`, and only the delta above the ledger's recorded
  * `reversedAmount` is reversed. Delta-to-target (rather than percent-of-
  * original like {@link reverseTransfers}) is what makes at-least-once webhook
@@ -416,7 +386,7 @@ export async function reverseTransfersForRefund(
     refundId: string;
     /** The original charge amount (minor units). */
     chargeAmount: number;
-    /** Stripe's cumulative `charge.amount_refunded`, including this refund. */
+    /** Cumulative principal of succeeded refunds; exclude pending/failed refunds. */
     amountRefunded: number;
   },
 ): Promise<{ reversals: { stripeTransferId: string; amount: number }[] }> {
@@ -431,6 +401,13 @@ export async function reverseTransfersForRefund(
     {
       operationId: opts.refundId,
       sourceChargeId: opts.sourceChargeId,
+      commissionExposure: {
+        kind: "refund",
+        refundId: opts.refundId,
+        chargeAmount: opts.chargeAmount,
+        principal: opts.amountRefunded,
+        finalized: true,
+      },
       mode: {
         kind: "fraction" as const,
         chargeAmount: opts.chargeAmount,
@@ -438,9 +415,19 @@ export async function reverseTransfersForRefund(
       },
     },
   )) as ReversalClaim;
-  return executeClaimedSlices(stripe, component, ctx, opts.refundId, claim);
+  const result = await executeClaimedSlices(
+    stripe,
+    component,
+    ctx,
+    opts.refundId,
+    { ...claim, slices: claim.slices.filter((s) => !s.commissionTracked) },
+  );
+  await reconcileAffiliateCharge(stripe, component, ctx, opts.sourceChargeId);
+  return result;
 }
 
+export { reverseTransfersForDispute } from "../affiliateRecovery/disputes.js";
+
 /**
  * Webhook-driven split transfer engine (BTS-22). After a charge succeeds for a
  * separate-charges sale, fan funds out to each split recipient: compute the
@@ -489,7 +476,14 @@ export async function reinstateTransfers(
   stripe: Stripe,
   component: Component,
   ctx: RunCtx,
-  opts: { sourceChargeId: string; operationId: string; currency: string },
+  opts: {
+    sourceChargeId: string;
+    operationId: string;
+    currency: string;
+    excludeAffiliates?: boolean;
+    chargeAmount?: number;
+    refundedPrincipal?: number;
+  },
 ): Promise<{ reinstated: { destinationAccountId: string; amount: number }[] }> {
   const transfers = ((await ctx.runQuery(
     componentRef(component, "connect/queries/listTransfersByCharge"),
@@ -498,7 +492,14 @@ export async function reinstateTransfers(
 
   const reinstated: { destinationAccountId: string; amount: number }[] = [];
   for (const t of transfers) {
-    const amount = t.reversedAmount ?? 0;
+    if (opts.excludeAffiliates && t.role === "affiliate") continue;
+    const independentRefund = opts.chargeAmount
+      ? Math.round(
+          t.amount *
+            Math.min(1, (opts.refundedPrincipal ?? 0) / opts.chargeAmount),
+        )
+      : 0;
+    const amount = Math.max(0, (t.reversedAmount ?? 0) - independentRefund);
     if (amount <= 0) continue; // nothing was clawed back from this leg
     // Use the original leg's currency; fall back to the dispute currency for
     // legacy rows that predate the stored currency — never assume USD.

package/src/client/index.ts

@@ -1,3 +1,7 @@
+import { AffiliateRecoveryClient } from "./affiliateRecovery.js";
+export * from "./affiliateRecovery.js";
+import { CheckoutRequestClient } from "./checkoutRequests.js";
+export type { PreparedCheckoutSession } from "./billing/preparedCheckout.js";
 import * as payoutSyncImpl from "./connect/payoutSync.js";
 export type {
   PayoutSyncOptions,
@@ -81,7 +85,6 @@ export type {
 import { internalActionGeneric, internalMutationGeneric } from "convex/server";
 import { v } from "convex/values";
 import Stripe from "stripe";
-
 import type { ComponentApi } from "../component/_generated/component.js";
 import type { DisputeStatus } from "../component/connect/validators.js";
 import type { SplitRecipient } from "../component/lib/fees.js";
@@ -145,7 +148,6 @@ import type { AsyncHookName, TriggerDispatcherName } from "./types/triggers.js";
 import * as dataImpl from "./utils/data.js";
 import type { StripeMode } from "./utils/stripeDashboardUrl.js";
 import * as webhookEndpointsImpl from "./utils/webhookEndpoints.js";
-
 // Re-export standalone webhook registration
 export { registerRoutes } from "./webhooks.js";
 export {
@@ -154,13 +156,11 @@ export {
   STRIPE_DASHBOARD_BASE_URL,
   StripeDashboardResourcePath,
 } from "./utils/stripeDashboardUrl.js";
-
 // Re-export payment method utilities
 export {
   getPaymentMethodCard,
   getPaymentMethodOwner,
 } from "./connect/paymentMethodUtils.js";
-
 // Re-export webhook event constants and types
 export {
   ALL_BETTER_STRIPE_EVENTS,
@@ -171,7 +171,6 @@ export type {
   BetterStripeV2WebhookEvent,
   BetterStripeWebhookEvent,
 } from "./utils/webhookEndpoints.js";
-
 // Re-export types for consumers
 export type {
   BetterStripeOptions,
@@ -210,7 +209,6 @@ export type {
   V2ThinEvent,
   WebhookActionCtx,
 } from "./types.js";
-
 export type BetterStripeComponent = ComponentApi;
 
 // BETTER STRIPE CLIENT
@@ -684,6 +682,14 @@ export class BetterStripe extends ReadContractClient {
   }
 
   // CHECKOUT METHODS
+  get checkoutRequests() {
+    return new CheckoutRequestClient(
+      this.component,
+      () => this.stripe(),
+      (fee) => this.resolveFee(fee),
+      this._statementDescriptorSuffix,
+    );
+  }
 
   async createCheckoutSession(ctx: RunCtx, opts: CreateCheckoutSessionOptions) {
     const { fee, ...rest } = opts;
@@ -703,27 +709,6 @@ export class BetterStripe extends ReadContractClient {
     );
   }
 
-  async getCheckoutSession(
-    ctx: RunCtx,
-    opts: { sessionId: string },
-  ): Promise<StripeComponentCheckoutSession | null> {
-    return checkoutImpl.getCheckoutSession(this.component, ctx, opts);
-  }
-
-  async getCheckoutSessionByStripeId(
-    ctx: RunCtx,
-    opts: { stripeSessionId: string },
-  ): Promise<StripeComponentCheckoutSession | null> {
-    return checkoutImpl.getCheckoutSessionByStripeId(this.component, ctx, opts);
-  }
-
-  async listCheckoutSessionsByUser(
-    ctx: RunCtx,
-    opts: { userId: string; status?: string },
-  ): Promise<StripeComponentCheckoutSession[]> {
-    return checkoutImpl.listCheckoutSessionsByUser(this.component, ctx, opts);
-  }
-
   async upsertCheckoutSession(
     ctx: RunCtx,
     opts: {
@@ -1151,7 +1136,7 @@ export class BetterStripe extends ReadContractClient {
   // PAYOUT METHODS
 
   async createPayout(ctx: RunCtx, opts: payoutsImpl.CreatePayoutOptions) {
-    return payoutsImpl.createPayout(this.stripe(), ctx, opts);
+    return payoutsImpl.createPayout(this.stripe(), ctx, opts, this.component);
   }
 
   /**
@@ -1257,6 +1242,9 @@ export class BetterStripe extends ReadContractClient {
   ) {
     return providerReads.getCouponFromStripe(this.stripe(), opts);
   }
+  get affiliateRecovery() {
+    return new AffiliateRecoveryClient(this.component, () => this.stripe());
+  }
   get payoutPolicy() {
     return new PayoutPolicyClient(this.component, () => this.stripe());
   }

package/src/client/payoutPolicy.ts

@@ -1,3 +1,12 @@
+import { PayoutWorkerClient } from "./connect/payoutWorker.js";
+export type * from "./connect/payoutWorker.js";
+import {
+  collectPayoutSnapshot,
+  discardPayoutSnapshot,
+  type PayoutCollectionOptions,
+  type PayoutCollectionScope,
+} from "./connect/payoutCollection.js";
+export type * from "./connect/payoutCollection.js";
 import { collectAdoptionProof } from "./connect/payoutActivationProof.js";
 import {
   adoptRecipientPayouts,
@@ -97,10 +106,26 @@ const toProvider = (
 });
 /** Host authenticates owner/policy/consent. Provider I/O stays in this package. */
 export class PayoutPolicyClient {
+  readonly worker: PayoutWorkerClient;
   constructor(
     private readonly component: Component,
     private readonly provider: () => Stripe,
-  ) {}
+  ) {
+    this.worker = new PayoutWorkerClient(
+      component,
+      (ctx, opts) => this.release(ctx, opts),
+      (ctx, opts) => this.reconcilePayout(ctx, opts),
+    );
+  }
+  collectSnapshot(ctx: RunCtx, opts: PayoutCollectionOptions) {
+    return collectPayoutSnapshot(this.component, ctx, opts);
+  }
+  discardSnapshot(
+    ctx: RunCtx,
+    opts: PayoutCollectionScope & { batchSize?: number },
+  ) {
+    return discardPayoutSnapshot(this.component, ctx, opts);
+  }
   adoptPayouts(ctx: RunCtx, opts: PayoutAdoptionOptions) {
     return adoptRecipientPayouts(this.provider(), this.component, ctx, opts);
   }

package/src/client/readContracts.ts

@@ -1,9 +1,11 @@
+import * as checkoutImpl from "./billing/checkout.js";
 import * as payoutsImpl from "./connect/payouts.js";
 import type { ComponentApi } from "../component/_generated/component.js";
 import type { PaginationOptions, PaginationResult } from "convex/server";
 import type { Component, RunCtx } from "./helpers.js";
 import type { PayoutStatus } from "../component/connect/validators.js";
 import type {
+  StripeComponentCheckoutSession,
   StripeComponentPayout,
   StripeComponentProduct,
   StripeComponentPrice,
@@ -52,6 +54,27 @@ export class ReadContractClient {
     );
   }
 
+  async getCheckoutSession(
+    ctx: RunCtx,
+    opts: { sessionId: string },
+  ): Promise<StripeComponentCheckoutSession | null> {
+    return checkoutImpl.getCheckoutSession(this.component, ctx, opts);
+  }
+
+  async getCheckoutSessionByStripeId(
+    ctx: RunCtx,
+    opts: { stripeSessionId: string },
+  ): Promise<StripeComponentCheckoutSession | null> {
+    return checkoutImpl.getCheckoutSessionByStripeId(this.component, ctx, opts);
+  }
+
+  async listCheckoutSessionsByUser(
+    ctx: RunCtx,
+    opts: { userId: string; status?: string },
+  ): Promise<StripeComponentCheckoutSession[]> {
+    return checkoutImpl.listCheckoutSessionsByUser(this.component, ctx, opts);
+  }
+
   async getPayout(ctx: RunCtx, opts: { payoutId: string }) {
     return payoutsImpl.getPayout(this.component, ctx, opts);
   }

package/src/client/settlement/execution.test.ts

@@ -26,6 +26,11 @@ it("recovers provider success after a ledger failure even without an idempotency
     async (r: Record<symbol, string>, args: Record<string, unknown>) => {
       if (r[TO_REF].endsWith("/reserveSettlementAllocation"))
         return claimed ?? (claimed = { ...args });
+      if (
+        r[TO_REF].includes("affiliateRecovery/") ||
+        r[TO_REF].includes("affiliateEarnings/")
+      )
+        return undefined;
       if (fail) {
         fail = false;
         throw new Error("ledger unavailable");