@fantastic.dev/better-stripe 0.23.2 → 0.24.0

package/src/client/affiliateRecovery.ts

@@ -0,0 +1,173 @@
+import {
+  reconcileAffiliatePayout,
+  completeAffiliatePayout,
+} from "./affiliateRecovery/payoutGate.js";
+import { verifiedLegacyReview } from "./affiliateRecovery/review.js";
+import { runMutationOrThrow } from "./helpers.js";
+import { createPayout } from "./connect/payouts.js";
+import type Stripe from "stripe";
+import type { PaginationOptions } from "convex/server";
+import type { Component, RunCtx } from "./helpers.js";
+import { componentRef } from "./webhooks/helpers.js";
+import { reconcileObligation } from "./affiliateRecovery/engine.js";
+import type {
+  RecoveryObligation,
+  RecoveryOperation,
+} from "./affiliateRecovery/provider.js";
+import type { Doc } from "../component/_generated/dataModel.js";
+export type AffiliateRecoveryObligation = RecoveryObligation;
+export type AffiliateRecoveryOperation = RecoveryOperation;
+export type AffiliateRecoveryBalance = Doc<"affiliateRecoveryBalances">;
+export type AffiliateRecoverySnapshot = {
+  balance: AffiliateRecoveryBalance | null;
+  obligations: {
+    page: RecoveryObligation[];
+    continueCursor: string;
+    isDone: boolean;
+  };
+};
+/** Server API. Host must authorize account ownership and operator retries. */
+export class AffiliateRecoveryClient {
+  constructor(
+    private readonly component: Component,
+    private readonly provider: () => Stripe,
+  ) {}
+  async snapshot(
+    ctx: RunCtx,
+    opts: {
+      affiliateAccountId: string;
+      currency: string;
+      paginationOpts: PaginationOptions;
+    },
+  ): Promise<AffiliateRecoverySnapshot> {
+    return ctx.runQuery(
+      componentRef(
+        this.component,
+        "affiliateRecovery/queries/recoverySnapshot",
+      ),
+      opts,
+    ) as Promise<AffiliateRecoverySnapshot>;
+  }
+  async obligation(
+    ctx: RunCtx,
+    opts: { obligationId: string },
+  ): Promise<RecoveryObligation | null> {
+    return ctx.runQuery(
+      componentRef(this.component, "affiliateRecovery/queries/getObligation"),
+      opts,
+    ) as Promise<RecoveryObligation | null>;
+  }
+  async history(
+    ctx: RunCtx,
+    opts: { obligationId: string; paginationOpts: PaginationOptions },
+  ) {
+    return ctx.runQuery(
+      componentRef(
+        this.component,
+        "affiliateRecovery/queries/operationHistory",
+      ),
+      opts,
+    ) as Promise<{
+      page: RecoveryOperation[];
+      continueCursor: string;
+      isDone: boolean;
+    }>;
+  }
+  async reviewLegacy(
+    ctx: RunCtx,
+    opts: {
+      obligationId: string;
+      reversalIds: string[];
+      restorationTransferIds?: string[];
+      note: string;
+    },
+  ) {
+    const row = await this.obligation(ctx, opts);
+    if (!row) throw new Error("Affiliate obligation not found.");
+    const review = await verifiedLegacyReview(this.provider(), row, opts);
+    await runMutationOrThrow(
+      ctx,
+      componentRef(this.component, "affiliateRecovery/mutations/reviewLegacy"),
+      review,
+    );
+    return this.obligation(ctx, opts);
+  }
+  async retry(ctx: RunCtx, opts: { obligationId: string }) {
+    return reconcileObligation(
+      this.provider(),
+      this.component,
+      ctx,
+      opts.obligationId,
+    );
+  }
+  async reconcilePayouts(
+    ctx: RunCtx,
+    opts: { paginationOpts: PaginationOptions; state: "pending" | "unknown" },
+  ) {
+    const page = (await ctx.runQuery(
+      componentRef(this.component, "affiliatePayouts/queries/pendingPayouts"),
+      opts,
+    )) as {
+      page: Doc<"affiliatePayoutReleases">[];
+      continueCursor: string;
+      isDone: boolean;
+    };
+    for (const row of page.page) {
+      try {
+        // Confirm money already moved even when new debt blocks another attempt.
+        const receipt = await reconcileAffiliatePayout(this.provider(), row);
+        if (receipt) {
+          await completeAffiliatePayout(
+            this.component,
+            ctx,
+            row.operationKey,
+            "submitted",
+            receipt,
+          );
+          continue;
+        }
+        await createPayout(
+          this.provider(),
+          ctx,
+          {
+            stripeAccountId: row.affiliateAccountId,
+            currency: row.currency,
+            amount: row.amount,
+            minimumAmount: row.minimumAmount,
+            idempotencyKey: row.operationKey,
+          },
+          this.component,
+        );
+      } catch {
+        /* The payout gate retains the durable failure/unknown outcome. */
+      }
+    }
+    return page;
+  }
+  /** Run from a host cron for both pending and unknown outcomes. */
+  async reconcilePending(
+    ctx: RunCtx,
+    opts: { paginationOpts: PaginationOptions; state: "pending" | "unknown" },
+  ) {
+    const page = (await ctx.runQuery(
+      componentRef(
+        this.component,
+        "affiliateRecovery/queries/pendingOperations",
+      ),
+      opts,
+    )) as {
+      page: RecoveryOperation[];
+      continueCursor: string;
+      isDone: boolean;
+    };
+    const results = [];
+    for (const op of page.page)
+      results.push(await this.retry(ctx, { obligationId: op.obligationId }));
+    return { ...page, results };
+  }
+}
+export {
+  affiliateSnapshotValidator,
+  affiliateObligationValidator,
+  affiliateOperationValidator,
+} from "./affiliateRecovery/validators.js";

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

@@ -0,0 +1,157 @@
+import { reclaimReversalClaim } from "./transfers.js";
+import type Stripe from "stripe";
+import { describe, expect, it, vi } from "vitest";
+import { findCommissionReversal } from "./commissionReceipts.js";
+import { executeClaimedSlices } from "./reversalExecution.js";
+import type { Component, RunCtx } from "../helpers.js";
+
+const component = new Proxy(
+  {},
+  {
+    get: (_t, p) =>
+      p === Symbol.for("toReferencePath") ? "betterStripe" : component,
+  },
+) as Component;
+const claim = {
+  replay: false,
+  slices: [
+    {
+      stripeTransferId: "tr_1",
+      from: 0,
+      to: 501,
+      confirmed: 0,
+      commissionTracked: true,
+    },
+  ],
+};
+const fixture = () => {
+  const receipts: {
+    id: string;
+    amount: number;
+    metadata: Record<string, string>;
+  }[] = [];
+  const stripe = {
+    transfers: {
+      createReversal: vi.fn(
+        async (
+          _id: string,
+          params: { amount: number; metadata: Record<string, string> },
+        ) => {
+          const receipt = { id: "trr_1", ...params };
+          receipts.push(receipt);
+          return receipt;
+        },
+      ),
+      listReversals: vi.fn(() =>
+        (async function* () {
+          yield* receipts;
+        })(),
+      ),
+      retrieve: vi.fn(),
+    },
+  };
+  const ctx = { runMutation: vi.fn().mockResolvedValue(null) };
+  const run = (replay = false, confirmed = 0) =>
+    executeClaimedSlices(
+      stripe as unknown as Stripe,
+      component,
+      ctx as unknown as RunCtx,
+      "re_1",
+      { ...claim, replay, slices: [{ ...claim.slices[0], confirmed }] },
+    );
+  return { stripe, ctx, receipts, run };
+};
+
+describe("commission reversal receipt reconciliation", () => {
+  it("recovers a provider success after the ledger confirmation crashed, even beyond the idempotency window", async () => {
+    const f = fixture();
+    f.ctx.runMutation.mockRejectedValueOnce(new Error("ledger offline"));
+    await expect(f.run()).rejects.toThrow("ledger offline");
+    expect(f.receipts).toHaveLength(1);
+    await f.run(true);
+    await f.run(true, 501);
+    expect(f.stripe.transfers.createReversal).toHaveBeenCalledTimes(1);
+    expect(f.ctx.runMutation).toHaveBeenLastCalledWith(expect.anything(), {
+      stripeTransferId: "tr_1",
+      reversedAmount: 501,
+      receipt: { stripeReversalId: "trr_1", operationId: "re_1", amount: 501 },
+    });
+  });
+
+  it("does not mistake another operation's aggregate reversal for this receipt", async () => {
+    const f = fixture();
+    f.receipts.push({
+      id: "trr_other",
+      amount: 501,
+      metadata: { bsReversalOperation: "re_other" },
+    });
+    await expect(f.run(true, 501)).rejects.toThrow(
+      "requires receipt reconciliation",
+    );
+    expect(f.stripe.transfers.retrieve).not.toHaveBeenCalled();
+    expect(f.stripe.transfers.createReversal).not.toHaveBeenCalled();
+    expect(f.ctx.runMutation).not.toHaveBeenCalled();
+  });
+
+  it("retries a failed provider attempt with byte-identical parameters and operation identity", async () => {
+    const f = fixture();
+    f.stripe.transfers.createReversal.mockRejectedValueOnce(
+      new Error("network offline"),
+    );
+    await expect(f.run()).rejects.toThrow("network offline");
+    await f.run(true);
+    expect(f.stripe.transfers.createReversal.mock.calls[0]).toEqual(
+      f.stripe.transfers.createReversal.mock.calls[1],
+    );
+    expect(f.receipts).toHaveLength(1);
+  });
+
+  it("rejects a mismatching receipt amount without confirming money", async () => {
+    const f = fixture();
+    f.receipts.push({
+      id: "trr_bad",
+      amount: 500,
+      metadata: { bsReversalOperation: "re_1" },
+    });
+    await expect(f.run(true)).rejects.toThrow("amount mismatch");
+    expect(f.ctx.runMutation).not.toHaveBeenCalled();
+  });
+
+  it("fails explicitly when the bounded receipt search cannot establish success", async () => {
+    const f = fixture();
+    for (let i = 0; i < 1001; i++)
+      f.receipts.push({ id: `trr_${i}`, amount: 1, metadata: {} });
+    await expect(
+      findCommissionReversal(
+        f.stripe as unknown as Stripe,
+        "tr_1",
+        "re_1",
+        501,
+      ),
+    ).rejects.toThrow("lookup limit exceeded");
+  });
+});
+
+it("operator re-execution delegates tracked commissions to the durable recovery engine", async () => {
+  const f = fixture();
+  const runQuery = vi
+    .fn()
+    .mockResolvedValueOnce({
+      operationId: "re_1",
+      sourceChargeId: "ch_1",
+      _creationTime: 0,
+      slices: [{ stripeTransferId: "tr_1", from: 0, to: 501 }],
+      commissionExposure: { kind: "refund" },
+    })
+    .mockResolvedValueOnce({ role: "affiliate", reversedAmount: 0 });
+  await reclaimReversalClaim(
+    f.stripe as unknown as Stripe,
+    component,
+    { ...f.ctx, runQuery } as unknown as RunCtx,
+    { operationId: "re_1" },
+  );
+  expect(f.stripe.transfers.createReversal).not.toHaveBeenCalled();
+  expect(runQuery).toHaveBeenLastCalledWith(expect.anything(), {
+    sourceChargeId: "ch_1",
+  });
+});

package/src/client/connect/commissionReceipts.ts

@@ -0,0 +1,23 @@
+import type Stripe from "stripe";
+
+/** Locate the exact receipt, never infer operation success from an aggregate. */
+export async function findCommissionReversal(
+  stripe: Stripe,
+  stripeTransferId: string,
+  operationId: string,
+  amount: number,
+) {
+  let count = 0;
+  for await (const receipt of stripe.transfers.listReversals(stripeTransferId, {
+    limit: 100,
+  })) {
+    if (++count > 1000)
+      throw new Error("Commission reversal receipt lookup limit exceeded.");
+    if (receipt.metadata?.bsReversalOperation === operationId) {
+      if (receipt.amount !== amount)
+        throw new Error("Commission reversal receipt amount mismatch.");
+      return receipt;
+    }
+  }
+  return null;
+}

package/src/client/connect/payouts.ts

@@ -1,3 +1,9 @@
+import {
+  reserveAffiliatePayout,
+  completeAffiliatePayout,
+  reconcileAffiliatePayout,
+} from "../affiliateRecovery/payoutGate.js";
+import { classifyRecoveryError } from "../affiliateRecovery/provider.js";
 import type Stripe from "stripe";
 
 import type { PayoutStatus } from "../../component/connect/validators.js";
@@ -54,6 +60,8 @@ export async function getAccountBalance(
 }
 
 export type CreatePayoutOptions = {
+  /** Host-authorized minimum in the payout currency. */
+  minimumAmount?: number;
   stripeAccountId: string;
   amount: number;
   currency?: string;
@@ -64,23 +72,75 @@ export type CreatePayoutOptions = {
 
 export async function createPayout(
   stripe: Stripe,
-  _ctx: RunCtx,
+  ctx: RunCtx,
   opts: CreatePayoutOptions,
+  component?: Component,
 ) {
-  const payout = await stripe.payouts.create(
-    {
-      amount: opts.amount,
-      currency: opts.currency ?? "usd",
-      metadata: opts.metadata ?? undefined,
-    },
-    {
-      stripeAccount: opts.stripeAccountId,
-      ...(opts.idempotencyKey !== undefined
-        ? { idempotencyKey: opts.idempotencyKey }
-        : {}),
-    },
-  );
-  return { stripePayoutId: payout.id };
+  const release = component
+    ? await reserveAffiliatePayout(component, ctx, opts)
+    : null;
+  if (release?.state === "submitted")
+    return { stripePayoutId: release.stripePayoutId! };
+  if (release?.state === "failed")
+    throw new Error(
+      "Affiliate payout failed; use a new authorized operation key.",
+    );
+  try {
+    if (release) {
+      const receiptId = await reconcileAffiliatePayout(stripe, release);
+      if (receiptId) {
+        await completeAffiliatePayout(
+          component!,
+          ctx,
+          release.operationKey,
+          "submitted",
+          receiptId,
+        );
+        return { stripePayoutId: receiptId };
+      }
+    }
+    if (release) {
+      if (Date.now() - release.createdAt >= 23 * 60 * 60 * 1000)
+        throw new Error(
+          "Affiliate payout idempotency window expired; reconcile the provider receipt before retrying.",
+        );
+      // Receipt lookup may yield while a refund records new debt.
+      await reserveAffiliatePayout(component!, ctx, opts);
+    }
+    const payout = await stripe.payouts.create(
+      {
+        amount: opts.amount,
+        currency: opts.currency ?? "usd",
+        metadata: release
+          ? { ...opts.metadata, bsAffiliatePayout: release._id }
+          : (opts.metadata ?? undefined),
+      },
+      {
+        stripeAccount: opts.stripeAccountId,
+        ...(opts.idempotencyKey !== undefined
+          ? { idempotencyKey: opts.idempotencyKey }
+          : {}),
+      },
+    );
+    if (release)
+      await completeAffiliatePayout(
+        component!,
+        ctx,
+        release.operationKey,
+        "submitted",
+        payout.id,
+      );
+    return { stripePayoutId: payout.id };
+  } catch (error) {
+    if (release)
+      await completeAffiliatePayout(
+        component!,
+        ctx,
+        release.operationKey,
+        classifyRecoveryError(error).state === "unknown" ? "unknown" : "failed",
+      );
+    throw error;
+  }
 }
 
 export async function getPayout(

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

@@ -0,0 +1,46 @@
+import type Stripe from "stripe";
+import { expect, it } from "vitest";
+import { successfulRefundPrincipal } from "./refundPrincipal.js";
+const provider = (refunds: { amount: number; status: string }[]) =>
+  ({
+    refunds: {
+      list: () =>
+        (async function* () {
+          yield* refunds;
+        })(),
+    },
+  }) as unknown as Stripe;
+it("excludes pending, failed and canceled refunds from the finalized cumulative principal", async () => {
+  expect(
+    await successfulRefundPrincipal(
+      provider([
+        { amount: 100, status: "succeeded" },
+        { amount: 200, status: "pending" },
+        { amount: 300, status: "failed" },
+        { amount: 400, status: "canceled" },
+        { amount: 500, status: "succeeded" },
+        { amount: 600, status: "requires_action" },
+      ]),
+      "ch_1",
+    ),
+  ).toBe(600);
+});
+it("fails closed on invalid money and a refund history beyond the supported bound", async () => {
+  await expect(
+    successfulRefundPrincipal(
+      provider([{ amount: -1, status: "succeeded" }]),
+      "ch_1",
+    ),
+  ).rejects.toThrow("Invalid");
+  await expect(
+    successfulRefundPrincipal(
+      provider(
+        Array.from({ length: 1001 }, () => ({
+          amount: 1,
+          status: "succeeded",
+        })),
+      ),
+      "ch_1",
+    ),
+  ).rejects.toThrow("limit exceeded");
+});

package/src/client/connect/refundPrincipal.ts

@@ -0,0 +1,26 @@
+import type Stripe from "stripe";
+
+/** Charge.amount_refunded also includes pending refunds; only success is final. */
+export async function successfulRefundPrincipal(
+  stripe: Stripe,
+  chargeId: string,
+) {
+  let principal = 0;
+  let count = 0;
+  for await (const refund of stripe.refunds.list({
+    charge: chargeId,
+    limit: 100,
+  })) {
+    if (++count > 1000)
+      throw new Error("Successful refund lookup limit exceeded.");
+    if (refund.status !== "succeeded") continue;
+    if (
+      !Number.isSafeInteger(refund.amount) ||
+      refund.amount < 0 ||
+      !Number.isSafeInteger(principal + refund.amount)
+    )
+      throw new Error("Invalid successful refund principal.");
+    principal += refund.amount;
+  }
+  return principal;
+}

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 () => {