@fantastic.dev/better-stripe 0.23.1 → 0.24.0

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,10 @@
+import { AffiliateRecoveryClient } from "./affiliateRecovery.js";
+export * from "./affiliateRecovery.js";
+import * as payoutSyncImpl from "./connect/payoutSync.js";
+export type {
+  PayoutSyncOptions,
+  PayoutSyncResult,
+} from "./connect/payoutSync.js";
 import { PayoutPolicyClient } from "./payoutPolicy.js";
 export * from "./payoutPolicy.js";
 import type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
@@ -76,12 +83,8 @@ 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,
-  PayoutStatus,
-} from "../component/connect/validators.js";
+import type { DisputeStatus } from "../component/connect/validators.js";
 import type { SplitRecipient } from "../component/lib/fees.js";
 import * as checkoutImpl from "./billing/checkout.js";
 import * as invoicesImpl from "./billing/invoices.js";
@@ -143,7 +146,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 {
@@ -152,13 +154,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,
@@ -169,7 +169,6 @@ export type {
   BetterStripeV2WebhookEvent,
   BetterStripeWebhookEvent,
 } from "./utils/webhookEndpoints.js";
-
 // Re-export types for consumers
 export type {
   BetterStripeOptions,
@@ -208,7 +207,6 @@ export type {
   V2ThinEvent,
   WebhookActionCtx,
 } from "./types.js";
-
 export type BetterStripeComponent = ComponentApi;
 
 // BETTER STRIPE CLIENT
@@ -1149,7 +1147,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);
   }
 
   /**
@@ -1255,6 +1253,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());
   }
@@ -1300,15 +1301,16 @@ export class BetterStripe extends ReadContractClient {
     return payoutsImpl.getAccountBalance(this.stripe(), opts);
   }
 
-  async getPayout(ctx: RunCtx, opts: { payoutId: string }) {
-    return payoutsImpl.getPayout(this.component, ctx, opts);
-  }
-
-  async listPayouts(
+  async syncPayoutFromStripe(
     ctx: RunCtx,
-    opts?: { stripeAccountId?: string; status?: PayoutStatus; limit?: number },
+    opts: payoutSyncImpl.PayoutSyncOptions,
   ) {
-    return payoutsImpl.listPayouts(this.component, ctx, opts);
+    return payoutSyncImpl.syncPayoutFromStripe(
+      this.stripe(),
+      this.component,
+      ctx,
+      opts,
+    );
   }
 
   // REFUND METHODS

package/src/client/readContracts.ts

@@ -1,3 +1,4 @@
+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";
@@ -51,6 +52,17 @@ export class ReadContractClient {
     );
   }
 
+  async getPayout(ctx: RunCtx, opts: { payoutId: string }) {
+    return payoutsImpl.getPayout(this.component, ctx, opts);
+  }
+
+  async listPayouts(
+    ctx: RunCtx,
+    opts?: { stripeAccountId?: string; status?: PayoutStatus; limit?: number },
+  ) {
+    return payoutsImpl.listPayouts(this.component, ctx, opts);
+  }
+
   async getAccountEarningsByCurrency(
     ctx: RunCtx,
     opts: { destinationAccountId: string; previewLimit?: number },

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");

package/src/client/settlement/execution.ts

@@ -1,3 +1,4 @@
+import { reconcileAffiliateCharge } from "../affiliateRecovery/engine.js";
 import {
   sourceTransfers,
   matchingTransfer,
@@ -60,13 +61,34 @@ export async function executeResolvedTransfers(
     transfers: saved.transfers,
     paymentId: saved.paymentId,
   };
+  const earnings = new Map<string, { _id: string; releaseAmount: number }>();
+  for (const leg of claim.transfers)
+    if (leg.role === "affiliate" && leg.amount > 0) {
+      const earning = (await runMutationOrThrow(
+        ctx,
+        componentRef(component, "affiliateEarnings/mutations/reserveEarning"),
+        {
+          sourceChargeId: claim.sourceChargeId,
+          affiliateAccountId: leg.destinationAccountId,
+        },
+      )) as { _id: string; releaseAmount: number } | undefined;
+      if (earning?._id) earnings.set(leg.destinationAccountId, earning);
+    }
+  const effective = claim.transfers.map((leg) =>
+    leg.role === "affiliate" && earnings.has(leg.destinationAccountId)
+      ? {
+          ...leg,
+          amount: earnings.get(leg.destinationAccountId)!.releaseAmount,
+        }
+      : leg,
+  );
   const existing = ((await ctx.runQuery(
     componentRef(component, "connect/queries/listTransfersByCharge"),
     { sourceChargeId: claim.sourceChargeId },
   )) ?? []) as Ledger[];
   let provider = await sourceTransfers(stripe, claim.sourceChargeId);
   if (
-    claim.transfers.some(
+    effective.some(
       (leg) =>
         leg.amount > 0 &&
         !existing.some(
@@ -87,8 +109,20 @@ export async function executeResolvedTransfers(
     ];
   }
   const executedTransfers: SettlementResult["executedTransfers"] = [];
-  for (const leg of claim.transfers) {
-    if (leg.amount === 0) continue;
+  for (const leg of effective) {
+    const earning =
+      leg.role === "affiliate"
+        ? earnings.get(leg.destinationAccountId)
+        : undefined;
+    if (leg.amount === 0) {
+      if (earning)
+        await runMutationOrThrow(
+          ctx,
+          componentRef(component, "affiliateEarnings/mutations/confirmEarning"),
+          { earningId: earning._id },
+        );
+      continue;
+    }
     const recorded = existing.find(
       (t) =>
         t.destinationAccountId === leg.destinationAccountId &&
@@ -123,6 +157,12 @@ export async function executeResolvedTransfers(
       transferId = transfer.id;
       await recordSettlementTransfer(component, ctx, claim, leg, transfer);
     }
+    if (earning)
+      await runMutationOrThrow(
+        ctx,
+        componentRef(component, "affiliateEarnings/mutations/confirmEarning"),
+        { earningId: earning._id, stripeTransferId: transferId },
+      );
     executedTransfers.push({
       stripeTransferId: transferId,
       destinationAccountId: leg.destinationAccountId,
@@ -130,5 +170,12 @@ export async function executeResolvedTransfers(
       amount: leg.amount,
     });
   }
+  if (earnings.size)
+    await reconcileAffiliateCharge(
+      stripe,
+      component,
+      ctx,
+      claim.sourceChargeId,
+    );
   return { ...claim, status: "settled", executedTransfers };
 }

package/src/client/settlement/reconciliation.ts

@@ -97,9 +97,26 @@ export async function recoverSettlementTransfers(
     { sourceChargeId },
   )) as ResolvedSettlement | null;
   if (!claim || typeof claim.sourceChargeId !== "string") return;
+  const effective = [];
+  for (const leg of claim.transfers) {
+    const earning =
+      leg.role === "affiliate"
+        ? ((await ctx.runQuery(
+            componentRef(component, "affiliateRecovery/queries/getEarning"),
+            { sourceChargeId, affiliateAccountId: leg.destinationAccountId },
+          )) as { releaseAmount?: number } | null)
+        : null;
+    effective.push({
+      ...leg,
+      amount:
+        typeof earning?.releaseAmount === "number"
+          ? earning.releaseAmount
+          : leg.amount,
+    });
+  }
   let provider = await sourceTransfers(stripe, sourceChargeId);
   if (
-    claim.transfers.some(
+    effective.some(
       (leg) => leg.amount > 0 && !matchingTransfer(provider, claim, leg),
     )
   )
@@ -111,7 +128,8 @@ export async function recoverSettlementTransfers(
         ].map((t) => [t.id, t]),
       ).values(),
     ];
-  for (const leg of claim.transfers) {
+  for (const leg of effective) {
+    if (leg.amount === 0) continue;
     const transfer = matchingTransfer(provider, claim, leg);
     if (transfer)
       await recordSettlementTransfer(component, ctx, claim, leg, transfer);

package/src/client/webhooks/disputeRecovery.ts

@@ -0,0 +1,74 @@
+import { recoverSettlementTransfers } from "../settlement/reconciliation.js";
+import { componentRef } from "./helpers.js";
+import type Stripe from "stripe";
+import type { WebhookContext } from "./helpers.js";
+import {
+  reinstateTransfers,
+  reverseTransfersForDispute,
+} from "../connect/transfers.js";
+import { successfulRefundPrincipal } from "../connect/refundPrincipal.js";
+export async function reconcileDisputeMoney(
+  whCtx: WebhookContext,
+  dispute: Stripe.Dispute,
+  event: string,
+  originalCharge?: Stripe.Charge,
+) {
+  if (dispute.status.startsWith("warning_") || dispute.status === "prevented")
+    return;
+  const chargeId =
+    typeof dispute.charge === "string" ? dispute.charge : dispute.charge?.id;
+  if (
+    !chargeId ||
+    !["created", "funds_withdrawn", "closed", "funds_reinstated"].includes(
+      event,
+    )
+  )
+    return;
+  await recoverSettlementTransfers(
+    whCtx.stripe,
+    whCtx.component,
+    whCtx.ctx,
+    chargeId,
+  );
+  const legs = await whCtx.ctx.runQuery(
+    componentRef(whCtx.component, "connect/queries/listTransfersByCharge"),
+    { sourceChargeId: chargeId },
+  );
+  const obligations = await whCtx.ctx.runQuery(
+    componentRef(
+      whCtx.component,
+      "affiliateRecovery/queries/chargeObligations",
+    ),
+    { sourceChargeId: chargeId },
+  );
+  if (
+    (!Array.isArray(legs) || !legs.length) &&
+    (!Array.isArray(obligations) || !obligations.length)
+  )
+    return;
+  const won = event === "funds_reinstated" || dispute.status === "won";
+  const charge =
+    originalCharge ?? (await whCtx.stripe.charges.retrieve(chargeId));
+  const refundedPrincipal = await successfulRefundPrincipal(
+    whCtx.stripe,
+    chargeId,
+  );
+  await reverseTransfersForDispute(whCtx.stripe, whCtx.component, whCtx.ctx, {
+    sourceChargeId: chargeId,
+    operationId: dispute.id,
+    chargeAmount: charge.amount,
+    amount: dispute.amount,
+    finalized: dispute.status === "lost",
+    disputeState: won ? "won" : dispute.status === "lost" ? "lost" : "open",
+    refundedPrincipal,
+  });
+  if (won)
+    await reinstateTransfers(whCtx.stripe, whCtx.component, whCtx.ctx, {
+      sourceChargeId: chargeId,
+      operationId: dispute.id,
+      currency: dispute.currency,
+      excludeAffiliates: true,
+      chargeAmount: charge.amount,
+      refundedPrincipal,
+    });
+}