@fantastic.dev/better-stripe 0.23.1 → 0.24.0

package/src/component/connect/mutations.ts

@@ -1,14 +1,18 @@
+import { syncCommissionTransfer } from "../settlement/clawbacks.js";
+import { recordTransferReversalDefinition } from "./reversalReceipts.js";
+import { claimReversalSlicesDefinition } from "./reversalClaims.js";
+import { writePayout } from "./payoutWrites.js";
 import { v } from "convex/values";
 
-import type { Doc, Id } from "../_generated/dataModel";
+import type { Id } from "../_generated/dataModel";
 import { mutation } from "../earnings/triggers.js";
 import { feeRoutingFields } from "../lib/fees";
-import { computeReversalSlices, deriveReversalState } from "../lib/reversals";
+import { deriveReversalState } from "../lib/reversals";
 import { paymentSeller } from "../lib/paymentSeller";
 import {
   disputeFields,
   paymentStatusValidator,
-  payoutStatusValidator,
+  payoutFields,
   refundFields,
   transferFields,
 } from "./validators";
@@ -113,37 +117,10 @@ export const upsertPayment = mutation({
 // Payout mutations
 
 export const upsertPayout = mutation({
-  args: {
-    stripePayoutId: v.string(),
-    accountId: v.string(),
-    amount: v.number(),
-    currency: v.string(),
-    status: payoutStatusValidator,
-    arrivalDate: v.optional(v.string()),
-    method: v.optional(v.string()),
-    failureCode: v.optional(v.string()),
-    failureMessage: v.optional(v.string()),
-    metadata: v.optional(v.any()),
-  },
+  args: payoutFields,
   returns: v.null(),
   handler: async (ctx, args) => {
-    const existing = await ctx.db
-      .query("payouts")
-      .withIndex("by_stripe_payout_id", (q) =>
-        q.eq("stripePayoutId", args.stripePayoutId),
-      )
-      .first();
-
-    if (existing) {
-      await ctx.db.patch("payouts", existing._id, {
-        ...args,
-        failureCode: args.failureCode,
-        failureMessage: args.failureMessage,
-      });
-    } else {
-      await ctx.db.insert("payouts", args);
-    }
-
+    await writePayout(ctx, args);
     return null;
   },
 });
@@ -338,6 +315,7 @@ export const upsertTransfer = mutation({
         reversedAmount,
         args.status,
       );
+      await syncCommissionTransfer(ctx, { ...existing, ...args, ...derived });
       await ctx.db.patch("transfers", existing._id, { ...args, ...derived });
     } else {
       const derived = deriveReversalState(
@@ -357,166 +335,11 @@ export const upsertTransfer = mutation({
  * cumulative `reversedAmount` and a derived `reversalStatus`. `reversedAmount`
  * is the new cumulative total (matches Stripe's `Transfer.amount_reversed`).
  */
-export const recordTransferReversal = mutation({
-  args: {
-    stripeTransferId: v.string(),
-    reversedAmount: v.number(),
-  },
-  returns: v.null(),
-  handler: async (ctx, args) => {
-    const transfer = await ctx.db
-      .query("transfers")
-      .withIndex("by_stripe_transfer_id", (q) =>
-        q.eq("stripeTransferId", args.stripeTransferId),
-      )
-      .first();
-
-    if (!transfer) {
-      throw new Error(
-        `Cannot record reversal: no transfer found for ${args.stripeTransferId}`,
-      );
-    }
-
-    // `reversedAmount` is a cumulative total (matches Stripe's
-    // `Transfer.amount_reversed`). Keep it monotonic so a stale/out-of-order
-    // event can't shrink it or undo a full reversal.
-    const reversedAmount = Math.max(
-      transfer.reversedAmount ?? 0,
-      args.reversedAmount,
-    );
-    const derived = deriveReversalState(
-      transfer.amount,
-      reversedAmount,
-      transfer.status,
-    );
-
-    await ctx.db.patch("transfers", transfer._id, derived);
-
-    return null;
-  },
-});
-
-/** How `claimReversalSlices` sizes each leg's slice. */
-const reversalModeValidator = v.union(
-  v.object({ kind: v.literal("full") }),
-  v.object({ kind: v.literal("percent"), percent: v.number() }),
-  v.object({ kind: v.literal("amount"), amount: v.number() }),
-  v.object({
-    kind: v.literal("fraction"),
-    chargeAmount: v.number(),
-    amountRefunded: v.number(),
-  }),
+export const recordTransferReversal = mutation(
+  recordTransferReversalDefinition,
 );
 
-/**
- * Atomically claim reversal slices for one operation (a dispute or refund
- * clawback) BEFORE any money moves (BTS-63). Runs in a single transaction, so
- * concurrent operations serialize here instead of racing between the ledger
- * read and the Stripe call:
- *
- *  - First claim for an `operationId`: computes slices against each leg's
- *    claim frontier (`max(reversedAmount, reversalClaimedAmount)`), advances
- *    the frontier, and records the slices — atomically. A concurrent distinct
- *    operation claiming the same target gets an EMPTY claim, not a duplicate.
- *  - Any later call with the same `operationId` (webhook redelivery, retry
- *    after a partial failure) replays the recorded slices verbatim, so the
- *    caller re-sends byte-identical Stripe params under the same idempotency
- *    keys no matter how the ledger moved in between.
- *
- * Each returned slice carries the leg's current CONFIRMED `reversedAmount` so
- * the executor can skip slices whose money already moved and was recorded.
- */
-export const claimReversalSlices = mutation({
-  args: {
-    operationId: v.string(),
-    sourceChargeId: v.string(),
-    mode: reversalModeValidator,
-  },
-  returns: v.object({
-    replay: v.boolean(),
-    slices: v.array(
-      v.object({
-        stripeTransferId: v.string(),
-        from: v.number(),
-        to: v.number(),
-        confirmed: v.number(),
-      }),
-    ),
-  }),
-  handler: async (ctx, args) => {
-    const confirmedFor = async (stripeTransferId: string) => {
-      const row = await ctx.db
-        .query("transfers")
-        .withIndex("by_stripe_transfer_id", (q) =>
-          q.eq("stripeTransferId", stripeTransferId),
-        )
-        .first();
-      return row?.reversedAmount ?? 0;
-    };
-
-    const existingOp = await ctx.db
-      .query("transferReversalOps")
-      .withIndex("by_operation_id", (q) =>
-        q.eq("operationId", args.operationId),
-      )
-      .first();
-    if (existingOp) {
-      const slices = [];
-      for (const s of existingOp.slices) {
-        slices.push({
-          ...s,
-          confirmed: await confirmedFor(s.stripeTransferId),
-        });
-      }
-      return { replay: true, slices };
-    }
-
-    // Original split legs only — reinstatement payouts are audit rows and
-    // must never be re-reversed (mirrors listTransfersByCharge).
-    // Claim every original split leg, including those beyond the former
-    // 50-row preview. Read/write limits abort the transaction before a partial
-    // claim can commit; no Stripe call happens until this mutation succeeds.
-    const rows: Doc<"transfers">[] = [];
-    for await (const transfer of ctx.db
-      .query("transfers")
-      .withIndex("by_source_charge_id", (q) =>
-        q.eq("sourceChargeId", args.sourceChargeId),
-      )) {
-      if (!transfer.reinstatement) rows.push(transfer);
-    }
-
-    const byId = new Map(rows.map((r) => [r.stripeTransferId, r]));
-    const slices = computeReversalSlices(
-      rows.map((t) => ({
-        stripeTransferId: t.stripeTransferId,
-        amount: t.amount,
-        frontier: Math.max(t.reversedAmount ?? 0, t.reversalClaimedAmount ?? 0),
-      })),
-      args.mode,
-    );
-
-    for (const s of slices) {
-      await ctx.db.patch("transfers", byId.get(s.stripeTransferId)!._id, {
-        reversalClaimedAmount: s.to,
-      });
-    }
-    // Record the operation even when it claims nothing, so a redelivery is a
-    // deterministic no-op instead of a recomputation against newer state.
-    await ctx.db.insert("transferReversalOps", {
-      operationId: args.operationId,
-      sourceChargeId: args.sourceChargeId,
-      slices,
-    });
-
-    return {
-      replay: false,
-      slices: slices.map((s) => ({
-        ...s,
-        confirmed: byId.get(s.stripeTransferId)!.reversedAmount ?? 0,
-      })),
-    };
-  },
-});
+export const claimReversalSlices = mutation(claimReversalSlicesDefinition);
 
 /**
  * Release a permanently-dead reversal claim (BTS-74): rewind each of the

package/src/component/connect/payoutWrites.ts

@@ -0,0 +1,25 @@
+import type { MutationCtx } from "../_generated/server.js";
+import type { Doc } from "../_generated/dataModel.js";
+type PayoutData = Omit<
+  Doc<"payouts">,
+  "_id" | "_creationTime" | "totalsRecorded"
+>;
+/** The caller's triggered DB maintains the existing exact currency summaries. */
+export async function writePayout(ctx: MutationCtx, args: PayoutData) {
+  const existing = await ctx.db
+    .query("payouts")
+    .withIndex("by_stripe_payout_id", (q) =>
+      q.eq("stripePayoutId", args.stripePayoutId),
+    )
+    .first();
+  const id = existing?._id ?? (await ctx.db.insert("payouts", args));
+  if (existing)
+    await ctx.db.patch("payouts", id, {
+      ...args,
+      failureCode: args.failureCode,
+      failureMessage: args.failureMessage,
+    });
+  const saved = await ctx.db.get("payouts", id);
+  if (!saved) throw new Error("Payout was not found after synchronization.");
+  return saved;
+}

package/src/component/connect/queries.ts

@@ -1,3 +1,4 @@
+import { listWedgedReversalClaimsDefinition } from "./reversalDiagnostics.js";
 import {
   getAccountEarnings as getAccountEarningsLegacy,
   getAccountPayouts as getAccountPayoutsLegacy,
@@ -24,7 +25,6 @@ import {
   refundStatusValidator,
   transferDocValidator,
   transferReversalOpDocValidator,
-  wedgedReversalClaimValidator,
 } from "./validators";
 
 // PAYMENT QUERIES
@@ -394,52 +394,9 @@ export const getReversalOp = query({
  * per-query document-read limit (16,384) — beyond which it throws (loud) rather
  * than silently truncating, matching the BTS-64 aggregate convention.
  */
-export const listWedgedReversalClaims = query({
-  args: {},
-  returns: v.array(wedgedReversalClaimValidator),
-  handler: async (ctx) => {
-    // Collect the wedged legs first.
-    const wedged: Doc<"transfers">[] = [];
-    for await (const tr of ctx.db.query("transfers")) {
-      if ((tr.reversalClaimedAmount ?? 0) > (tr.reversedAmount ?? 0)) {
-        wedged.push(tr);
-      }
-    }
-    if (wedged.length === 0) return [];
-
-    const wedgedIds = new Set(wedged.map((t) => t.stripeTransferId));
-
-    // Index the ops that hold an unexecuted slice on a wedged leg. A slice is
-    // unexecuted when its `to` exceeds the leg's confirmed `reversedAmount`.
-    const confirmedById = new Map(
-      wedged.map((t) => [t.stripeTransferId, t.reversedAmount ?? 0]),
-    );
-    const blockersByLeg = new Map<
-      string,
-      { operationId: string; from: number; to: number }[]
-    >();
-    for await (const op of ctx.db.query("transferReversalOps")) {
-      for (const s of op.slices) {
-        if (!wedgedIds.has(s.stripeTransferId)) continue;
-        if (s.to <= (confirmedById.get(s.stripeTransferId) ?? 0)) continue;
-        const list = blockersByLeg.get(s.stripeTransferId) ?? [];
-        list.push({ operationId: op.operationId, from: s.from, to: s.to });
-        blockersByLeg.set(s.stripeTransferId, list);
-      }
-    }
-
-    return wedged.map((t) => ({
-      stripeTransferId: t.stripeTransferId,
-      sourceChargeId: t.sourceChargeId,
-      amount: t.amount,
-      reversedAmount: t.reversedAmount ?? 0,
-      reversalClaimedAmount: t.reversalClaimedAmount ?? 0,
-      blockingOps: (blockersByLeg.get(t.stripeTransferId) ?? []).sort(
-        (a, b) => a.from - b.from,
-      ),
-    }));
-  },
-});
+export const listWedgedReversalClaims = query(
+  listWedgedReversalClaimsDefinition,
+);
 
 // EARNINGS AGGREGATES (BTS-64)
 //

package/src/component/connect/reversalClaims.ts

@@ -0,0 +1,232 @@
+import { v } from "convex/values";
+import type { MutationCtx } from "../_generated/server.js";
+import { computeReversalSlices } from "../lib/reversals.js";
+import {
+  applyCommissionExposure,
+  applyObligationExposure,
+} from "../settlement/clawbacks.js";
+import { commissionExposureValidator } from "../settlement/clawbackSchema.js";
+import type { Infer } from "convex/values";
+/** How `claimReversalSlices` sizes each leg's slice. */
+const reversalModeValidator = v.union(
+  v.object({ kind: v.literal("full") }),
+  v.object({ kind: v.literal("percent"), percent: v.number() }),
+  v.object({ kind: v.literal("amount"), amount: v.number() }),
+  v.object({
+    kind: v.literal("fraction"),
+    chargeAmount: v.number(),
+    amountRefunded: v.number(),
+  }),
+);
+
+/**
+ * Atomically claim reversal slices for one operation (a dispute or refund
+ * clawback) BEFORE any money moves (BTS-63). Runs in a single transaction, so
+ * concurrent operations serialize here instead of racing between the ledger
+ * read and the Stripe call:
+ *
+ *  - First claim for an `operationId`: computes slices against each leg's
+ *    claim frontier (`max(reversedAmount, reversalClaimedAmount)`), advances
+ *    the frontier, and records the slices — atomically. A concurrent distinct
+ *    operation claiming the same target gets an EMPTY claim, not a duplicate.
+ *  - Any later call with the same `operationId` (webhook redelivery, retry
+ *    after a partial failure) replays the recorded slices verbatim, so the
+ *    caller re-sends byte-identical Stripe params under the same idempotency
+ *    keys no matter how the ledger moved in between.
+ *
+ * Each returned slice carries the leg's current CONFIRMED `reversedAmount` so
+ * the executor can skip slices whose money already moved and was recorded.
+ */
+export const claimReversalSlicesDefinition = {
+  args: {
+    operationId: v.string(),
+    sourceChargeId: v.string(),
+    mode: reversalModeValidator,
+    commissionExposure: v.optional(commissionExposureValidator),
+  },
+  returns: v.object({
+    replay: v.boolean(),
+    slices: v.array(
+      v.object({
+        stripeTransferId: v.string(),
+        from: v.number(),
+        to: v.number(),
+        confirmed: v.number(),
+        commissionTracked: v.optional(v.boolean()),
+      }),
+    ),
+  }),
+  handler: async (
+    ctx: MutationCtx,
+    args: {
+      operationId: string;
+      sourceChargeId: string;
+      mode: Infer<typeof reversalModeValidator>;
+      commissionExposure?: Infer<typeof commissionExposureValidator>;
+    },
+  ) => {
+    const confirmedFor = async (stripeTransferId: string) => {
+      const row = await ctx.db
+        .query("transfers")
+        .withIndex("by_stripe_transfer_id", (q) =>
+          q.eq("stripeTransferId", stripeTransferId),
+        )
+        .first();
+      return row?.reversedAmount ?? 0;
+    };
+
+    const isAffiliate = async (stripeTransferId: string) => {
+      const row = await ctx.db
+        .query("transfers")
+        .withIndex("by_stripe_transfer_id", (q) =>
+          q.eq("stripeTransferId", stripeTransferId),
+        )
+        .unique();
+      return row?.role === "affiliate";
+    };
+    // Fail atomically rather than commit a partial recovery beyond the bound.
+    const chargeRows = await ctx.db
+      .query("transfers")
+      .withIndex("by_source_charge_id", (q) =>
+        q.eq("sourceChargeId", args.sourceChargeId),
+      )
+      .take(1001);
+    if (chargeRows.length > 1000)
+      throw new Error("Charge transfer recovery limit exceeded.");
+    const rows = chargeRows.filter((t) => !t.reinstatement);
+
+    const existingOp = await ctx.db
+      .query("transferReversalOps")
+      .withIndex("by_operation_id", (q) =>
+        q.eq("operationId", args.operationId),
+      )
+      .first();
+    const exposure =
+      existingOp?.commissionExposure && args.commissionExposure
+        ? {
+            ...existingOp.commissionExposure,
+            finalized:
+              existingOp.commissionExposure.finalized ||
+              args.commissionExposure.finalized,
+            disputeState:
+              args.commissionExposure.disputeState ??
+              existingOp.commissionExposure.disputeState,
+            refundedPrincipal: args.commissionExposure.refundedPrincipal,
+          }
+        : existingOp
+          ? undefined
+          : args.commissionExposure;
+    const targets = new Map<string, number>();
+    if (exposure) {
+      for (const transfer of rows)
+        if (transfer.role === "affiliate")
+          targets.set(
+            transfer.stripeTransferId,
+            await applyCommissionExposure(ctx, transfer, exposure),
+          );
+      const untransferred = await ctx.db
+        .query("affiliateObligations")
+        .withIndex("by_charge", (q) =>
+          q.eq("sourceChargeId", args.sourceChargeId),
+        )
+        .take(1001);
+      if (untransferred.length > 1000)
+        throw new Error("Affiliate obligation limit exceeded.");
+      for (const row of untransferred)
+        if (!row.stripeTransferId)
+          await applyObligationExposure(ctx, row, exposure);
+    }
+    if (existingOp) {
+      if (existingOp.sourceChargeId !== args.sourceChargeId)
+        throw new Error("Reversal operation source identity cannot change.");
+      if (existingOp.commissionExposure && args.commissionExposure) {
+        if (
+          existingOp.commissionExposure.kind !== args.commissionExposure.kind ||
+          existingOp.commissionExposure.chargeAmount !==
+            args.commissionExposure.chargeAmount
+        )
+          throw new Error("Commission operation identity cannot change.");
+        if (exposure)
+          await ctx.db.patch("transferReversalOps", existingOp._id, {
+            commissionExposure: exposure,
+          });
+      }
+      const slices = [];
+      for (const s of existingOp.slices) {
+        slices.push({
+          ...s,
+          confirmed: await confirmedFor(s.stripeTransferId),
+          ...(existingOp.commissionExposure
+            ? { commissionTracked: await isAffiliate(s.stripeTransferId) }
+            : {}),
+        });
+      }
+      return { replay: true, slices };
+    }
+
+    const byId = new Map(rows.map((r) => [r.stripeTransferId, r]));
+    let slices = computeReversalSlices(
+      rows.map((t) => ({
+        stripeTransferId: t.stripeTransferId,
+        amount: t.amount,
+        frontier: Math.max(t.reversedAmount ?? 0, t.reversalClaimedAmount ?? 0),
+      })),
+      args.mode,
+    );
+
+    if (args.commissionExposure) {
+      // Keep the shipped seller/other paths; affiliates converge on original
+      // commission exposure rather than a second incremental dispute debit.
+      const affiliates = rows.filter((t) => t.role === "affiliate");
+      slices = slices.filter(
+        (s) => byId.get(s.stripeTransferId)!.role !== "affiliate",
+      );
+      for (const transfer of affiliates) {
+        const target = Math.min(
+          transfer.amount,
+          targets.get(transfer.stripeTransferId) ?? 0,
+        );
+        const from = Math.max(
+          transfer.reversedAmount ?? 0,
+          transfer.reversalClaimedAmount ?? 0,
+        );
+        if (target > from)
+          slices.push({
+            stripeTransferId: transfer.stripeTransferId,
+            from,
+            to: target,
+          });
+      }
+    }
+
+    for (const s of slices) {
+      await ctx.db.patch("transfers", byId.get(s.stripeTransferId)!._id, {
+        reversalClaimedAmount: s.to,
+      });
+    }
+    // Record the operation even when it claims nothing, so a redelivery is a
+    // deterministic no-op instead of a recomputation against newer state.
+    await ctx.db.insert("transferReversalOps", {
+      operationId: args.operationId,
+      sourceChargeId: args.sourceChargeId,
+      slices,
+      ...(args.commissionExposure
+        ? { commissionExposure: args.commissionExposure }
+        : {}),
+    });
+
+    return {
+      replay: false,
+      slices: slices.map((s) => ({
+        ...s,
+        confirmed: byId.get(s.stripeTransferId)!.reversedAmount ?? 0,
+        ...(args.commissionExposure
+          ? {
+              commissionTracked:
+                byId.get(s.stripeTransferId)!.role === "affiliate",
+            }
+          : {}),
+      })),
+    };
+  },
+};

package/src/component/connect/reversalDiagnostics.ts

@@ -0,0 +1,61 @@
+import { v } from "convex/values";
+import type { QueryCtx } from "../_generated/server.js";
+import type { Doc } from "../_generated/dataModel.js";
+import { wedgedReversalClaimValidator } from "./validators.js";
+
+export const listWedgedReversalClaimsDefinition = {
+  args: {},
+  returns: v.array(wedgedReversalClaimValidator),
+  handler: async (ctx: QueryCtx) => {
+    // Collect the wedged legs first.
+    const wedged: Doc<"transfers">[] = [];
+    for await (const tr of ctx.db.query("transfers")) {
+      const tracked =
+        tr.role === "affiliate"
+          ? await ctx.db
+              .query("affiliateObligations")
+              .withIndex("by_transfer", (q) =>
+                q.eq("stripeTransferId", tr.stripeTransferId),
+              )
+              .unique()
+          : null;
+      if (tracked?.accounted) continue;
+      if ((tr.reversalClaimedAmount ?? 0) > (tr.reversedAmount ?? 0)) {
+        wedged.push(tr);
+      }
+    }
+    if (wedged.length === 0) return [];
+
+    const wedgedIds = new Set(wedged.map((t) => t.stripeTransferId));
+
+    // Index the ops that hold an unexecuted slice on a wedged leg. A slice is
+    // unexecuted when its `to` exceeds the leg's confirmed `reversedAmount`.
+    const confirmedById = new Map(
+      wedged.map((t) => [t.stripeTransferId, t.reversedAmount ?? 0]),
+    );
+    const blockersByLeg = new Map<
+      string,
+      { operationId: string; from: number; to: number }[]
+    >();
+    for await (const op of ctx.db.query("transferReversalOps")) {
+      for (const s of op.slices) {
+        if (!wedgedIds.has(s.stripeTransferId)) continue;
+        if (s.to <= (confirmedById.get(s.stripeTransferId) ?? 0)) continue;
+        const list = blockersByLeg.get(s.stripeTransferId) ?? [];
+        list.push({ operationId: op.operationId, from: s.from, to: s.to });
+        blockersByLeg.set(s.stripeTransferId, list);
+      }
+    }
+
+    return wedged.map((t) => ({
+      stripeTransferId: t.stripeTransferId,
+      sourceChargeId: t.sourceChargeId,
+      amount: t.amount,
+      reversedAmount: t.reversedAmount ?? 0,
+      reversalClaimedAmount: t.reversalClaimedAmount ?? 0,
+      blockingOps: (blockersByLeg.get(t.stripeTransferId) ?? []).sort(
+        (a, b) => a.from - b.from,
+      ),
+    }));
+  },
+};