@fantastic.dev/better-stripe 0.23.1 → 0.24.0

package/src/client/webhooks/processors.test.ts

@@ -96,6 +96,13 @@ type MockReversal = {
 
 function makeStripe() {
   return {
+    refunds: {
+      list: vi.fn(() =>
+        (async function* () {
+          yield { amount: 5000, status: "succeeded" };
+        })(),
+      ),
+    },
     products: { retrieve: vi.fn() },
     subscriptions: {
       retrieve: vi.fn(),
@@ -1396,7 +1403,7 @@ describe("processEvent — split transfer engine (BTS-22)", () => {
     expect(data.statementDescriptor).toBe("ACME STORE");
   });
 
-  it("[BTS-26] still processes the dispute when the charge lookup fails (descriptor is best-effort)", async () => {
+  it("records the dispute but retries recovery when the charge basis is unavailable", async () => {
     const stripe = makeStripe();
     stripe.charges.retrieve.mockRejectedValue(new Error("stripe down"));
     const ctx = makeCtx({
@@ -1411,26 +1418,28 @@ describe("processEvent — split transfer engine (BTS-22)", () => {
     });
     const whCtx = makeWhCtx({ stripe, ctx });
 
-    await processEvent(
-      whCtx,
-      event("charge.dispute.created", {
-        id: "dp_bf",
-        charge: "ch_1",
-        amount: 9000,
-        currency: "usd",
-        status: "needs_response",
-        reason: "fraudulent",
-        is_charge_refundable: true,
-        evidence_details: { due_by: 1700000000 },
-        metadata: {},
-      }),
-    );
+    await expect(
+      processEvent(
+        whCtx,
+        event("charge.dispute.created", {
+          id: "dp_bf",
+          charge: "ch_1",
+          amount: 9000,
+          currency: "usd",
+          status: "needs_response",
+          reason: "fraudulent",
+          is_charge_refundable: true,
+          evidence_details: { due_by: 1700000000 },
+          metadata: {},
+        }),
+      ),
+    ).rejects.toThrow("stripe down");
 
-    // Dispute still recorded (without a descriptor) and clawback still ran.
+    // Record the dispute, but require an authoritative basis before recovery.
     const { path, data } = dispatchedPayload(whCtx.ctx);
     expect(path).toBe("betterStripe/connect/mutations/upsertDispute");
     expect(data.statementDescriptor).toBeUndefined();
-    expect(stripe.transfers.createReversal).toHaveBeenCalledTimes(1);
+    expect(stripe.transfers.createReversal).not.toHaveBeenCalled();
   });
 
   it("[BTS-27] claws back a single-recipient transfer on dispute", async () => {
@@ -2338,7 +2347,6 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
         : {}),
     },
   ];
-
   const refundEvent = (overrides: Record<string, unknown> = {}) =>
     event("refund.created", {
       id: "re_1",
@@ -2350,7 +2358,6 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
       metadata: {},
       ...overrides,
     });
-
   it("reverses split-sale transfers pro-rata on a succeeded partial refund", async () => {
     const ctx = makeCtx({ query: ledgerLegs() });
     const stripe = makeStripe();
@@ -2360,10 +2367,7 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
       amount_refunded: 5000,
     });
     const whCtx = makeWhCtx({ ctx, stripe });
-
     await processEvent(whCtx, refundEvent());
-
-    // 50% refunded → each leg reversed to 50% of its original amount.
     expect(stripe.transfers.createReversal).toHaveBeenCalledTimes(2);
     expect(stripe.transfers.createReversal).toHaveBeenCalledWith(
       "tr_s",
@@ -2376,19 +2380,21 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
       { idempotencyKey: "bs_rev_re_1_tr_a" },
     );
   });
-
   it("reverses the full transfer amounts on a full refund", async () => {
     const ctx = makeCtx({ query: ledgerLegs() });
     const stripe = makeStripe();
+    stripe.refunds.list.mockImplementation(() =>
+      (async function* () {
+        yield { amount: 10000, status: "succeeded" };
+      })(),
+    );
     stripe.charges.retrieve.mockResolvedValue({
       id: "ch_1",
       amount: 10000,
       amount_refunded: 10000,
     });
     const whCtx = makeWhCtx({ ctx, stripe });
-
     await processEvent(whCtx, refundEvent({ amount: 10000 }));
-
     expect(stripe.transfers.createReversal).toHaveBeenCalledWith(
       "tr_s",
       { amount: 7000 },
@@ -2400,23 +2406,23 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
       { idempotencyKey: "bs_rev_re_1_tr_a" },
     );
   });
-
   it("a second partial refund reverses only the delta up to the new cumulative target", async () => {
-    // First refund (5000) already clawed back 3500/500 and was recorded.
     const ctx = makeCtx({
       query: ledgerLegs({ reversedStore: 3500, reversedAff: 500 }),
     });
     const stripe = makeStripe();
+    stripe.refunds.list.mockImplementation(() =>
+      (async function* () {
+        yield { amount: 7000, status: "succeeded" };
+      })(),
+    );
     stripe.charges.retrieve.mockResolvedValue({
       id: "ch_1",
       amount: 10000,
       amount_refunded: 7000, // cumulative: 5000 + this refund's 2000
     });
     const whCtx = makeWhCtx({ ctx, stripe });
-
     await processEvent(whCtx, refundEvent({ id: "re_2", amount: 2000 }));
-
-    // Target 70% of each leg minus what's already reversed: 4900-3500, 700-500.
     expect(stripe.transfers.createReversal).toHaveBeenCalledWith(
       "tr_s",
       { amount: 1400 },
@@ -2428,7 +2434,6 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
       { idempotencyKey: "bs_rev_re_2_tr_a" },
     );
   });
-
   it("is idempotent — a redelivered refund event whose reversals are recorded reverses nothing", async () => {
     const ctx = makeCtx({
       query: ledgerLegs({ reversedStore: 3500, reversedAff: 500 }),
@@ -2440,36 +2445,24 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
       amount_refunded: 5000,
     });
     const whCtx = makeWhCtx({ ctx, stripe });
-
     await processEvent(whCtx, refundEvent());
-
-    // Cumulative target (50%) already met on both legs — no delta, no calls.
     expect(stripe.transfers.createReversal).not.toHaveBeenCalled();
   });
-
   it("skips clawback quietly for a refund on a non-split sale", async () => {
     const ctx = makeCtx({ query: [] });
     const stripe = makeStripe();
     const whCtx = makeWhCtx({ ctx, stripe });
-
     await processEvent(whCtx, refundEvent());
-
-    // No ledger legs → not a split sale (Stripe-native reverse_transfer covers
-    // destination charges). No charge lookup, no reversals, no throw.
     expect(stripe.charges.retrieve).not.toHaveBeenCalled();
     expect(stripe.transfers.createReversal).not.toHaveBeenCalled();
   });
-
   it("does not claw back for a pending refund", async () => {
     const ctx = makeCtx({ query: ledgerLegs() });
     const stripe = makeStripe();
     const whCtx = makeWhCtx({ ctx, stripe });
-
     await processEvent(whCtx, refundEvent({ status: "pending" }));
-
     expect(stripe.transfers.createReversal).not.toHaveBeenCalled();
   });
-
   it("propagates a reversal failure so the event is marked failed and Stripe retries", async () => {
     const ctx = makeCtx({ query: ledgerLegs() });
     const stripe = makeStripe();
@@ -2480,12 +2473,10 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
     });
     stripe.transfers.createReversal.mockRejectedValue(new Error("stripe down"));
     const whCtx = makeWhCtx({ ctx, stripe });
-
     await expect(processEvent(whCtx, refundEvent())).rejects.toThrow(
       "stripe down",
     );
   });
-
   it("application_fee.refunded sets absolute fee totals on the linked payment", async () => {
     const stripe = makeStripe();
     stripe.charges.retrieve.mockResolvedValue({
@@ -2493,7 +2484,6 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
       payment_intent: "pi_1",
     });
     const whCtx = makeWhCtx({ stripe });
-
     const feeEvent = event("application_fee.refunded", {
       id: "fee_1",
       charge: "ch_1",
@@ -2502,7 +2492,6 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
       currency: "usd",
     });
     await processEvent(whCtx, feeEvent);
-
     const calls = whCtx.ctx.runMutation.mock.calls;
     const feeCall = calls.find(
       (c) =>
@@ -2510,15 +2499,11 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
         "betterStripe/connect/mutations/recordPaymentFeeRefund",
     );
     expect(feeCall).toBeDefined();
-    // Absolute cumulative values straight from Stripe — never incremented, so
-    // a redelivery (or a createRefund-triggered duplicate) can't double-count.
     expect(feeCall![1]).toEqual({
       stripePaymentIntentId: "pi_1",
       feeCollectedAmount: 160,
       feeRefundedAmount: 160,
     });
-
-    // Redelivery writes the identical absolute state.
     await processEvent(whCtx, feeEvent);
     const feeCalls = whCtx.ctx.runMutation.mock.calls.filter(
       (c) =>
@@ -2528,7 +2513,6 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
     expect(feeCalls).toHaveLength(2);
     expect(feeCalls[1][1]).toEqual(feeCalls[0][1]);
   });
-
   it("application_fee.refunded skips quietly when the charge has no payment intent", async () => {
     const stripe = makeStripe();
     stripe.charges.retrieve.mockResolvedValue({
@@ -2536,7 +2520,6 @@ describe("processEvent — refunds: split clawback + fee-refund denormalization
       payment_intent: null,
     });
     const whCtx = makeWhCtx({ stripe });
-
     await expect(
       processEvent(
         whCtx,

package/src/client/webhooks/processors.ts

@@ -1,3 +1,5 @@
+import { reconcileDisputeMoney } from "./disputeRecovery.js";
+import { successfulRefundPrincipal } from "../connect/refundPrincipal.js";
 import { subscriptionRouting } from "../billing/subscriptionRouting.js";
 import { cancelsAtPeriodEnd } from "../billing/subscriptionCancellation.js";
 import type Stripe from "stripe";
@@ -5,8 +7,6 @@ import type Stripe from "stripe";
 import type { SplitRecipient } from "../../component/lib/fees.js";
 import {
   createSplitTransfers,
-  reinstateTransfers,
-  reverseTransfers,
   reverseTransfersForRefund,
 } from "../connect/transfers.js";
 import { validateStatementDescriptorSuffix } from "../core/descriptors.js";
@@ -989,15 +989,24 @@ async function handleRefundEvent(
     componentRef(whCtx.component, "connect/queries/listTransfersByCharge"),
     { sourceChargeId: chargeId },
   )) ?? []) as unknown[];
-  if (legs.length === 0) return; // not a split sale
+  if (legs.length === 0) {
+    const obligations = (await whCtx.ctx.runQuery(
+      componentRef(
+        whCtx.component,
+        "affiliateRecovery/queries/chargeObligations",
+      ),
+      { sourceChargeId: chargeId },
+    )) as unknown[] | null;
+    if (!obligations?.length) return;
+  }
 
-  // Fresh charge read for the authoritative cumulative amount_refunded.
+  // Fetch succeeded refunds: charge.amount_refunded can include pending funds.
   const charge = await whCtx.stripe.charges.retrieve(chargeId);
   await reverseTransfersForRefund(whCtx.stripe, whCtx.component, whCtx.ctx, {
     sourceChargeId: chargeId,
     refundId: refund.id,
     chargeAmount: charge.amount,
-    amountRefunded: charge.amount_refunded ?? refund.amount,
+    amountRefunded: await successfulRefundPrincipal(whCtx.stripe, chargeId),
   });
 }
 
@@ -1054,9 +1063,11 @@ async function handleDisputeEvent(
   // best-effort: this is optional metadata, so a transient charge-lookup failure
   // must never abort the critical dispute side effects (upsert, clawback, cancel).
   let statementDescriptor: string | undefined;
+  let originalCharge: Stripe.Charge | undefined;
   if (lastEvent === "created" && chargeId) {
     try {
-      const charge = await whCtx.stripe.charges.retrieve(chargeId);
+      const charge = (originalCharge =
+        await whCtx.stripe.charges.retrieve(chargeId));
       statementDescriptor =
         charge?.calculated_statement_descriptor ??
         charge?.statement_descriptor ??
@@ -1082,31 +1093,7 @@ async function handleDisputeEvent(
     metadata: dispute.metadata ?? undefined,
   });
 
-  // Clawback (BTS-27): when a dispute is first opened, reverse the transfers
-  // funded by the disputed charge pro-rata to the disputed amount, so recipients
-  // bear their share (losses_collector=application leaves the platform with the
-  // rest). Idempotent via the dispute id; reinstated by BTS-29 if the dispute is
-  // won. Only on `created` — other dispute events don't move funds here.
-  if (lastEvent === "created" && chargeId) {
-    await reverseTransfers(whCtx.stripe, whCtx.component, whCtx.ctx, {
-      sourceChargeId: chargeId,
-      amount: dispute.amount,
-      operationId: dispute.id,
-    });
-  }
-
-  // Reinstatement (BTS-29): when the dispute is won (or funds are explicitly
-  // reinstated), pay recipients back the amounts clawed back on `created`.
-  const isWon =
-    lastEvent === "funds_reinstated" ||
-    (lastEvent === "closed" && dispute.status === "won");
-  if (isWon && chargeId) {
-    await reinstateTransfers(whCtx.stripe, whCtx.component, whCtx.ctx, {
-      sourceChargeId: chargeId,
-      operationId: dispute.id,
-      currency: dispute.currency,
-    });
-  }
+  await reconcileDisputeMoney(whCtx, dispute, lastEvent, originalCharge);
 
   // Auto-cancel the disputed subscription (BTS-28, default on). Resolve the
   // subscription from the dispute's PaymentIntent (invoice payment → invoice →

package/src/component/_generated/api.ts

@@ -8,11 +8,22 @@
  * @module
  */
 
+import type * as affiliateEarnings_mutations from "../affiliateEarnings/mutations.js";
+import type * as affiliatePayouts_mutations from "../affiliatePayouts/mutations.js";
+import type * as affiliatePayouts_queries from "../affiliatePayouts/queries.js";
+import type * as affiliatePayouts_recipientGuard from "../affiliatePayouts/recipientGuard.js";
+import type * as affiliateRecovery_accounting from "../affiliateRecovery/accounting.js";
+import type * as affiliateRecovery_mutations from "../affiliateRecovery/mutations.js";
+import type * as affiliateRecovery_queries from "../affiliateRecovery/queries.js";
 import type * as billing_mutations from "../billing/mutations.js";
 import type * as billing_queries from "../billing/queries.js";
 import type * as billing_validators from "../billing/validators.js";
 import type * as connect_mutations from "../connect/mutations.js";
+import type * as connect_payoutWrites from "../connect/payoutWrites.js";
 import type * as connect_queries from "../connect/queries.js";
+import type * as connect_reversalClaims from "../connect/reversalClaims.js";
+import type * as connect_reversalDiagnostics from "../connect/reversalDiagnostics.js";
+import type * as connect_reversalReceipts from "../connect/reversalReceipts.js";
 import type * as connect_validators from "../connect/validators.js";
 import type * as core_mutations from "../core/mutations.js";
 import type * as core_queries from "../core/queries.js";
@@ -45,10 +56,16 @@ import type * as payoutRelease_helpers from "../payoutRelease/helpers.js";
 import type * as payoutRelease_mutations from "../payoutRelease/mutations.js";
 import type * as payoutRelease_observation from "../payoutRelease/observation.js";
 import type * as payoutRelease_queries from "../payoutRelease/queries.js";
+import type * as payoutSync_helpers from "../payoutSync/helpers.js";
+import type * as payoutSync_mutations from "../payoutSync/mutations.js";
+import type * as payoutSync_queries from "../payoutSync/queries.js";
+import type * as payoutSync_validators from "../payoutSync/validators.js";
 import type * as products_mutations from "../products/mutations.js";
 import type * as products_queries from "../products/queries.js";
 import type * as products_validators from "../products/validators.js";
 import type * as refundHistory_queries from "../refundHistory/queries.js";
+import type * as settlement_clawbackSchema from "../settlement/clawbackSchema.js";
+import type * as settlement_clawbacks from "../settlement/clawbacks.js";
 import type * as settlement_mutations from "../settlement/mutations.js";
 import type * as settlement_queries from "../settlement/queries.js";
 import type * as webhooks_mutations from "../webhooks/mutations.js";
@@ -63,11 +80,22 @@ import type {
 import { anyApi, componentsGeneric } from "convex/server";
 
 const fullApi: ApiFromModules<{
+  "affiliateEarnings/mutations": typeof affiliateEarnings_mutations;
+  "affiliatePayouts/mutations": typeof affiliatePayouts_mutations;
+  "affiliatePayouts/queries": typeof affiliatePayouts_queries;
+  "affiliatePayouts/recipientGuard": typeof affiliatePayouts_recipientGuard;
+  "affiliateRecovery/accounting": typeof affiliateRecovery_accounting;
+  "affiliateRecovery/mutations": typeof affiliateRecovery_mutations;
+  "affiliateRecovery/queries": typeof affiliateRecovery_queries;
   "billing/mutations": typeof billing_mutations;
   "billing/queries": typeof billing_queries;
   "billing/validators": typeof billing_validators;
   "connect/mutations": typeof connect_mutations;
+  "connect/payoutWrites": typeof connect_payoutWrites;
   "connect/queries": typeof connect_queries;
+  "connect/reversalClaims": typeof connect_reversalClaims;
+  "connect/reversalDiagnostics": typeof connect_reversalDiagnostics;
+  "connect/reversalReceipts": typeof connect_reversalReceipts;
   "connect/validators": typeof connect_validators;
   "core/mutations": typeof core_mutations;
   "core/queries": typeof core_queries;
@@ -100,10 +128,16 @@ const fullApi: ApiFromModules<{
   "payoutRelease/mutations": typeof payoutRelease_mutations;
   "payoutRelease/observation": typeof payoutRelease_observation;
   "payoutRelease/queries": typeof payoutRelease_queries;
+  "payoutSync/helpers": typeof payoutSync_helpers;
+  "payoutSync/mutations": typeof payoutSync_mutations;
+  "payoutSync/queries": typeof payoutSync_queries;
+  "payoutSync/validators": typeof payoutSync_validators;
   "products/mutations": typeof products_mutations;
   "products/queries": typeof products_queries;
   "products/validators": typeof products_validators;
   "refundHistory/queries": typeof refundHistory_queries;
+  "settlement/clawbackSchema": typeof settlement_clawbackSchema;
+  "settlement/clawbacks": typeof settlement_clawbacks;
   "settlement/mutations": typeof settlement_mutations;
   "settlement/queries": typeof settlement_queries;
   "webhooks/mutations": typeof webhooks_mutations;