@fantastic.dev/better-stripe 0.23.2 → 0.24.0

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,
+      ),
+    }));
+  },
+};

package/src/component/connect/reversalReceipts.ts

@@ -0,0 +1,147 @@
+import { updateObligation } from "../affiliateRecovery/accounting.js";
+import { v } from "convex/values";
+import type { Doc } from "../_generated/dataModel.js";
+import type { MutationCtx } from "../_generated/server.js";
+import { deriveReversalState } from "../lib/reversals.js";
+
+async function recordCommissionReceipt(
+  ctx: MutationCtx,
+  transfer: Doc<"transfers">,
+  reversedAmount: number,
+  receipt: { stripeReversalId: string; operationId: string; amount: number },
+) {
+  const op = await ctx.db
+    .query("transferReversalOps")
+    .withIndex("by_operation_id", (q) =>
+      q.eq("operationId", receipt.operationId),
+    )
+    .unique();
+  const slice = op?.slices.find(
+    (s) => s.stripeTransferId === transfer.stripeTransferId,
+  );
+  if (
+    transfer.role !== "affiliate" ||
+    !op?.commissionExposure ||
+    !slice ||
+    receipt.amount !== slice.to - slice.from ||
+    reversedAmount !== slice.to ||
+    !receipt.stripeReversalId
+  )
+    throw new Error(
+      "Commission reversal receipt does not match its reserved operation.",
+    );
+  const priorOperationReceipt = await ctx.db
+    .query("affiliateReversalReceipts")
+    .withIndex("by_transfer_operation", (q) =>
+      q
+        .eq("stripeTransferId", transfer.stripeTransferId)
+        .eq("operationId", receipt.operationId),
+    )
+    .unique();
+  if (
+    priorOperationReceipt &&
+    priorOperationReceipt.stripeReversalId !== receipt.stripeReversalId
+  )
+    throw new Error(
+      "Commission operation already has a different reversal receipt.",
+    );
+  const existing = await ctx.db
+    .query("affiliateReversalReceipts")
+    .withIndex("by_receipt", (q) =>
+      q.eq("stripeReversalId", receipt.stripeReversalId),
+    )
+    .unique();
+  if (existing) {
+    if (
+      existing.stripeTransferId !== transfer.stripeTransferId ||
+      existing.operationId !== receipt.operationId ||
+      existing.amount !== receipt.amount
+    )
+      throw new Error("Commission reversal receipt identity cannot change.");
+  } else {
+    await ctx.db.insert("affiliateReversalReceipts", {
+      ...receipt,
+      stripeTransferId: transfer.stripeTransferId,
+    });
+  }
+}
+
+export const recordTransferReversalDefinition = {
+  args: {
+    stripeTransferId: v.string(),
+    reversedAmount: v.number(),
+    receipt: v.optional(
+      v.object({
+        stripeReversalId: v.string(),
+        operationId: v.string(),
+        amount: v.number(),
+      }),
+    ),
+  },
+  returns: v.null(),
+  handler: async (
+    ctx: MutationCtx,
+    args: {
+      stripeTransferId: string;
+      reversedAmount: number;
+      receipt?: {
+        stripeReversalId: string;
+        operationId: string;
+        amount: number;
+      };
+    },
+  ) => {
+    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,
+    );
+
+    if (
+      !Number.isSafeInteger(reversedAmount) ||
+      reversedAmount < 0 ||
+      reversedAmount > transfer.amount
+    )
+      throw new Error("Invalid confirmed transfer reversal amount.");
+    if (args.receipt)
+      await recordCommissionReceipt(
+        ctx,
+        transfer,
+        args.reversedAmount,
+        args.receipt,
+      );
+    await ctx.db.patch("transfers", transfer._id, derived);
+    const obligation = await ctx.db
+      .query("affiliateObligations")
+      .withIndex("by_transfer", (q) =>
+        q.eq("stripeTransferId", args.stripeTransferId),
+      )
+      .unique();
+    if (obligation)
+      await updateObligation(ctx, obligation, {
+        recoveredAmount: reversedAmount,
+      });
+
+    return null;
+  },
+};

package/src/component/connect/schema.ts

@@ -90,9 +90,9 @@ export const transfersTable = defineTable({
  * delivery replays byte-identical Stripe requests instead of recomputing
  * amounts from mutable ledger state.
  */
-export const transferReversalOpsTable = defineTable(
-  transferReversalOpFields,
-).index("by_operation_id", ["operationId"]);
+export const transferReversalOpsTable = defineTable(transferReversalOpFields)
+  .index("by_operation_id", ["operationId"])
+  .index("by_source_charge", ["sourceChargeId"]);
 
 /**
  * Disputes (chargebacks). Same indexing strategy as refunds.

package/src/component/connect/validators.ts

@@ -1,3 +1,4 @@
+import { commissionExposureValidator } from "../settlement/clawbackSchema.js";
 import { type Infer, v } from "convex/values";
 
 import { feeRoutingFields, splitRecipientRoleValidator } from "../lib/fees";
@@ -305,6 +306,7 @@ export const transferReversalOpFields = {
   operationId: v.string(),
   sourceChargeId: v.string(),
   slices: v.array(reversalSliceValidator),
+  commissionExposure: v.optional(commissionExposureValidator),
 };
 
 /** Full `transferReversalOps` document, including system fields. */