@fantastic.dev/better-stripe 0.23.2 → 0.25.0

package/src/component/affiliateRecovery/mutations.ts

@@ -0,0 +1,275 @@
+import { commissionExposureValidator } from "../settlement/clawbackSchema.js";
+import { applyObligationExposure } from "../settlement/clawbacks.js";
+import { v } from "convex/values";
+import { mutation } from "../earnings/triggers.js";
+import { balance, updateObligation, due, credit } from "./accounting.js";
+import { operationFields, recoveryState } from "./schema.js";
+import { deriveReversalState } from "../lib/reversals.js";
+const operationDoc = v.object({
+  ...operationFields,
+  _id: v.id("affiliateRecoveryOperations"),
+  _creationTime: v.number(),
+});
+export const reserveOperation = mutation({
+  args: {
+    obligationId: v.id("affiliateObligations"),
+    kind: v.union(v.literal("recovery"), v.literal("restoration")),
+    now: v.number(),
+  },
+  returns: v.union(operationDoc, v.null()),
+  handler: async (ctx, args) => {
+    const row = await ctx.db.get("affiliateObligations", args.obligationId);
+    if (!row) throw new Error("Affiliate obligation not found.");
+    if (row.needsReconciliation) return null;
+    if (
+      (await balance(ctx, row.affiliateAccountId, row.currency))
+        ?.activePayoutKey
+    )
+      throw new Error("Affiliate payout is pending reconciliation.");
+    if (row.activeOperationId)
+      return ctx.db.get("affiliateRecoveryOperations", row.activeOperationId);
+    const originalTransfer = row.stripeTransferId
+      ? await ctx.db
+          .query("transfers")
+          .withIndex("by_stripe_transfer_id", (q) =>
+            q.eq("stripeTransferId", row.stripeTransferId!),
+          )
+          .unique()
+      : null;
+    const reversible = originalTransfer
+      ? originalTransfer.amount - (originalTransfer.reversedAmount ?? 0)
+      : 0;
+    const amount =
+      args.kind === "recovery"
+        ? Math.min(due(row), Math.max(0, reversible))
+        : credit(row);
+    if (amount <= 0 || (args.kind === "recovery" && !row.stripeTransferId)) {
+      if (args.kind === "recovery" && due(row) > 0)
+        await updateObligation(ctx, row, {
+          lastState: "offset_required",
+          lastError:
+            "Original transfer has no reversible funds; recover from eligible future commissions.",
+        });
+      return null;
+    }
+    const id = await ctx.db.insert("affiliateRecoveryOperations", {
+      obligationId: row._id,
+      sourceEventId:
+        args.kind === "restoration"
+          ? row.disputeId
+          : (row.lastRefundId ?? row.disputeId),
+      kind: args.kind,
+      amount,
+      state: "pending",
+      attempted: false,
+      providerBaseline: originalTransfer?.reversedAmount ?? 0,
+      createdAt: args.now,
+    });
+    await updateObligation(ctx, row, {
+      activeOperationId: id,
+      [args.kind === "recovery" ? "reservedRecovery" : "reservedRestoration"]:
+        amount,
+      lastState: "pending",
+      lastError: undefined,
+    });
+    return (await ctx.db.get("affiliateRecoveryOperations", id))!;
+  },
+});
+/** Persist intent before contacting Stripe. Retries keep the exact operation ID. */
+export const beginOperation = mutation({
+  args: { operationId: v.id("affiliateRecoveryOperations") },
+  returns: operationDoc,
+  handler: async (ctx, { operationId }) => {
+    const op = await ctx.db.get("affiliateRecoveryOperations", operationId);
+    if (!op) throw new Error("Affiliate operation not found.");
+    const row = (await ctx.db.get("affiliateObligations", op.obligationId))!;
+    if (
+      !op.attempted &&
+      (op.kind === "recovery" ? due(row) : credit(row)) < op.amount
+    ) {
+      await ctx.db.patch("affiliateRecoveryOperations", op._id, {
+        state: "canceled",
+      });
+      await updateObligation(ctx, row, {
+        activeOperationId: undefined,
+        reservedRecovery: 0,
+        reservedRestoration: 0,
+        lastState: "canceled",
+      });
+      return { ...op, state: "canceled" as const };
+    }
+    if (op.state === "pending" && !op.attempted)
+      await ctx.db.patch("affiliateRecoveryOperations", op._id, {
+        attempted: true,
+      });
+    return { ...op, attempted: true };
+  },
+});
+export const completeOperation = mutation({
+  args: {
+    operationId: v.id("affiliateRecoveryOperations"),
+    state: recoveryState,
+    receiptId: v.optional(v.string()),
+    confirmedTransferReversed: v.optional(v.number()),
+    error: v.optional(v.string()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const op = await ctx.db.get(
+      "affiliateRecoveryOperations",
+      args.operationId,
+    );
+    if (!op) throw new Error("Affiliate operation not found.");
+    if (op.state === "succeeded") {
+      if (args.state === "succeeded" && op.receiptId !== args.receiptId)
+        throw new Error("Affiliate receipt identity cannot change.");
+      return null;
+    }
+    const row = (await ctx.db.get("affiliateObligations", op.obligationId))!;
+    if (args.state === "succeeded" && !args.receiptId)
+      throw new Error("Confirmed affiliate recovery requires a receipt.");
+    const pending = args.state === "pending" || args.state === "unknown";
+    const patch = {
+      lastState: args.state,
+      lastError: args.error,
+      activeOperationId: pending ? op._id : undefined,
+      reservedRecovery: op.kind === "recovery" && pending ? op.amount : 0,
+      reservedRestoration: op.kind === "restoration" && pending ? op.amount : 0,
+    };
+    if (args.state === "succeeded") {
+      if (op.kind === "recovery") {
+        if (!row.stripeTransferId)
+          throw new Error("Recovery has no original Connect transfer.");
+        const transfer = await ctx.db
+          .query("transfers")
+          .withIndex("by_stripe_transfer_id", (q) =>
+            q.eq("stripeTransferId", row.stripeTransferId!),
+          )
+          .unique();
+        if (!transfer) throw new Error("Original transfer not found.");
+        const total = row.recoveredAmount + op.amount;
+        if (total > transfer.amount)
+          throw new Error("Recovery exceeds original transfer.");
+        const aggregate = args.confirmedTransferReversed;
+        if (
+          aggregate === undefined ||
+          !Number.isSafeInteger(aggregate) ||
+          aggregate < total ||
+          aggregate > transfer.amount
+        )
+          throw new Error(
+            "A confirmed provider transfer aggregate is required.",
+          );
+        await ctx.db.patch(
+          "transfers",
+          transfer._id,
+          deriveReversalState(
+            transfer.amount,
+            Math.max(aggregate, transfer.reversedAmount ?? 0),
+            transfer.status,
+          ),
+        );
+        const duplicate = await ctx.db
+          .query("affiliateReversalReceipts")
+          .withIndex("by_receipt", (q) =>
+            q.eq("stripeReversalId", args.receiptId!),
+          )
+          .unique();
+        if (duplicate)
+          throw new Error(
+            "Affiliate reversal receipt has already been attributed.",
+          );
+        await ctx.db.insert("affiliateReversalReceipts", {
+          stripeReversalId: args.receiptId!,
+          stripeTransferId: row.stripeTransferId,
+          operationId: op._id,
+          amount: op.amount,
+        });
+        await updateObligation(ctx, row, { ...patch, recoveredAmount: total });
+      } else {
+        await ctx.db.insert("transfers", {
+          stripeTransferId: args.receiptId!,
+          sourceChargeId: row.sourceChargeId,
+          sourceInvoiceId: row.sourceInvoiceId,
+          destinationAccountId: row.affiliateAccountId,
+          currency: row.currency,
+          amount: op.amount,
+          role: "affiliate",
+          status: "paid",
+          reinstatement: true,
+          metadata: { bsRecoveryOperation: op._id },
+        });
+        await updateObligation(ctx, row, {
+          ...patch,
+          restoredAmount: (row.restoredAmount ?? 0) + op.amount,
+        });
+      }
+    } else await updateObligation(ctx, row, patch);
+    await ctx.db.patch("affiliateRecoveryOperations", op._id, {
+      state: args.state,
+      receiptId: args.receiptId,
+      error: args.error,
+    });
+    return null;
+  },
+});
+
+/** Trusted operator API; the client verifies provider facts before this write. */
+export const reviewLegacy = mutation({
+  args: {
+    obligationId: v.id("affiliateObligations"),
+    recoveredAmount: v.number(),
+    restoredAmount: v.number(),
+    receipts: v.array(v.object({ id: v.string(), amount: v.number() })),
+    restorationIds: v.array(v.string()),
+    note: v.string(),
+    exposure: commissionExposureValidator,
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const row = await ctx.db.get("affiliateObligations", args.obligationId);
+    if (!row || !row.needsReconciliation || row.activeOperationId)
+      throw new Error("Obligation is not eligible for legacy review.");
+    if (
+      !args.note.trim() ||
+      args.receipts.length > 100 ||
+      new Set(args.receipts.map((r) => r.id)).size !== args.receipts.length ||
+      ![
+        args.recoveredAmount,
+        args.restoredAmount,
+        ...args.receipts.map((r) => r.amount),
+      ].every((n) => Number.isSafeInteger(n) && n >= 0) ||
+      args.recoveredAmount > row.originalCommission ||
+      args.restoredAmount > args.recoveredAmount ||
+      args.receipts.reduce((n, r) => n + r.amount, 0) !== args.recoveredAmount
+    )
+      throw new Error("Legacy review does not reconcile.");
+    await applyObligationExposure(ctx, row, args.exposure);
+    const observed = (await ctx.db.get("affiliateObligations", row._id))!;
+    for (const receipt of args.receipts) {
+      const existing = await ctx.db
+        .query("affiliateReversalReceipts")
+        .withIndex("by_receipt", (q) => q.eq("stripeReversalId", receipt.id))
+        .unique();
+      if (existing && existing.stripeTransferId !== row.stripeTransferId)
+        throw new Error("Legacy receipt belongs to another original transfer.");
+      if (!existing)
+        await ctx.db.insert("affiliateReversalReceipts", {
+          stripeReversalId: receipt.id,
+          stripeTransferId: row.stripeTransferId!,
+          operationId: `review:${row._id}`,
+          amount: receipt.amount,
+        });
+    }
+    await updateObligation(ctx, observed, {
+      recoveredAmount: args.recoveredAmount,
+      restoredAmount: args.restoredAmount,
+      needsReconciliation: false,
+      legacyReceiptIds: args.receipts.map((r) => r.id),
+      legacyRestorationIds: args.restorationIds,
+      operatorNote: args.note,
+      lastState: "reviewed",
+    });
+    return null;
+  },
+});

package/src/component/affiliateRecovery/queries.ts

@@ -0,0 +1,138 @@
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
+import {
+  paginationOptsValidator,
+  paginationResultValidator,
+} from "convex/server";
+import { v } from "convex/values";
+import { query } from "../_generated/server.js";
+import { obligationFields } from "../settlement/clawbackSchema.js";
+import { balanceFields, operationFields, earningFields } from "./schema.js";
+export const obligationDoc = v.object({
+  ...obligationFields,
+  _id: v.id("affiliateObligations"),
+  _creationTime: v.number(),
+});
+export const getObligation = query({
+  args: { obligationId: v.id("affiliateObligations") },
+  returns: v.union(obligationDoc, v.null()),
+  handler: (ctx, args) => ctx.db.get("affiliateObligations", args.obligationId),
+});
+export const chargeObligations = query({
+  args: { sourceChargeId: v.string() },
+  returns: v.array(obligationDoc),
+  handler: async (ctx, args) => {
+    const rows = await ctx.db
+      .query("affiliateObligations")
+      .withIndex("by_charge", (q) =>
+        q.eq("sourceChargeId", args.sourceChargeId),
+      )
+      .take(1001);
+    if (rows.length > 1000)
+      throw new Error("Affiliate charge recovery limit exceeded.");
+    return rows;
+  },
+});
+export const getEarning = query({
+  args: { sourceChargeId: v.string(), affiliateAccountId: v.string() },
+  returns: v.union(
+    v.object({
+      ...earningFields,
+      _id: v.id("affiliateEarnings"),
+      _creationTime: v.number(),
+    }),
+    v.null(),
+  ),
+  handler: (ctx, args) =>
+    ctx.db
+      .query("affiliateEarnings")
+      .withIndex("by_charge_affiliate", (q) =>
+        q
+          .eq("sourceChargeId", args.sourceChargeId)
+          .eq("affiliateAccountId", args.affiliateAccountId),
+      )
+      .unique(),
+});
+export const recoverySnapshot = query({
+  args: {
+    affiliateAccountId: v.string(),
+    currency: v.string(),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: v.object({
+    balance: v.union(
+      v.object({
+        ...balanceFields,
+        _id: v.id("affiliateRecoveryBalances"),
+        _creationTime: v.number(),
+      }),
+      v.null(),
+    ),
+    obligations: paginationResultValidator(obligationDoc),
+  }),
+  handler: async (ctx, args) => ({
+    balance: await ctx.db
+      .query("affiliateRecoveryBalances")
+      .withIndex("by_affiliate_currency", (q) =>
+        q
+          .eq("affiliateAccountId", args.affiliateAccountId)
+          .eq("currency", args.currency),
+      )
+      .unique(),
+    obligations: await paginator(ctx.db, schema)
+      .query("affiliateObligations")
+      .withIndex("by_affiliate_currency", (q) =>
+        q
+          .eq("affiliateAccountId", args.affiliateAccountId)
+          .eq("currency", args.currency),
+      )
+      .paginate({
+        ...args.paginationOpts,
+        numItems: Math.min(100, args.paginationOpts.numItems),
+      }),
+  }),
+});
+export const operationHistory = query({
+  args: {
+    obligationId: v.id("affiliateObligations"),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(
+    v.object({
+      ...operationFields,
+      _id: v.id("affiliateRecoveryOperations"),
+      _creationTime: v.number(),
+    }),
+  ),
+  handler: (ctx, args) =>
+    paginator(ctx.db, schema)
+      .query("affiliateRecoveryOperations")
+      .withIndex("by_obligation", (q) =>
+        q.eq("obligationId", args.obligationId),
+      )
+      .paginate({
+        ...args.paginationOpts,
+        numItems: Math.min(100, args.paginationOpts.numItems),
+      }),
+});
+export const pendingOperations = query({
+  args: {
+    paginationOpts: paginationOptsValidator,
+    state: v.union(v.literal("pending"), v.literal("unknown")),
+  },
+  returns: paginationResultValidator(
+    v.object({
+      ...operationFields,
+      _id: v.id("affiliateRecoveryOperations"),
+      _creationTime: v.number(),
+    }),
+  ),
+  handler: (ctx, args) =>
+    paginator(ctx.db, schema)
+      .query("affiliateRecoveryOperations")
+      .withIndex("by_state", (q) => q.eq("state", args.state))
+      .paginate({
+        ...args.paginationOpts,
+        numItems: Math.min(50, args.paginationOpts.numItems),
+      }),
+});

package/src/component/affiliateRecovery/schema.ts

@@ -0,0 +1,86 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+export const recoveryState = v.union(
+  v.literal("pending"),
+  v.literal("unknown"),
+  v.literal("insufficient_balance"),
+  v.literal("unsupported"),
+  v.literal("failed"),
+  v.literal("succeeded"),
+  v.literal("canceled"),
+);
+export const operationFields = {
+  obligationId: v.id("affiliateObligations"),
+  sourceEventId: v.optional(v.string()),
+  kind: v.union(v.literal("recovery"), v.literal("restoration")),
+  amount: v.number(),
+  state: recoveryState,
+  receiptId: v.optional(v.string()),
+  error: v.optional(v.string()),
+  attempted: v.boolean(),
+  providerBaseline: v.optional(v.number()),
+  createdAt: v.number(),
+};
+export const operationsTable = defineTable(operationFields)
+  .index("by_obligation", ["obligationId"])
+  .index("by_state", ["state"]);
+export const earningFields = {
+  sourceChargeId: v.string(),
+  affiliateAccountId: v.string(),
+  currency: v.string(),
+  originalCommission: v.number(),
+  withheldAmount: v.number(),
+  releaseAmount: v.number(),
+  sourceInvoiceId: v.optional(v.string()),
+  paymentIntentId: v.optional(v.string()),
+  stripeTransferId: v.optional(v.string()),
+  status: v.union(v.literal("reserved"), v.literal("paid")),
+};
+export const earningsTable = defineTable(earningFields)
+  .index("by_charge_affiliate", ["sourceChargeId", "affiliateAccountId"])
+  .index("by_affiliate_currency", ["affiliateAccountId", "currency"]);
+export const offsetsTable = defineTable({
+  earningId: v.id("affiliateEarnings"),
+  obligationId: v.id("affiliateObligations"),
+  amount: v.number(),
+})
+  .index("by_earning", ["earningId"])
+  .index("by_obligation", ["obligationId"]);
+export const balanceFields = {
+  activePayoutKey: v.optional(v.string()),
+  pendingPayoutAmount: v.optional(v.number()),
+  affiliateAccountId: v.string(),
+  currency: v.string(),
+  originalCommission: v.number(),
+  recoveredAmount: v.number(),
+  offsetAmount: v.number(),
+  restoredAmount: v.number(),
+  outstandingDebt: v.number(),
+  reservedRecovery: v.number(),
+  reservedRestoration: v.number(),
+  restorationDue: v.number(),
+  withheldAmount: v.number(),
+  netPayable: v.number(),
+};
+export const balancesTable = defineTable(balanceFields).index(
+  "by_affiliate_currency",
+  ["affiliateAccountId", "currency"],
+);
+export const payoutReleaseFields = {
+  affiliateAccountId: v.string(),
+  currency: v.string(),
+  operationKey: v.string(),
+  amount: v.number(),
+  minimumAmount: v.number(),
+  state: v.union(
+    v.literal("pending"),
+    v.literal("unknown"),
+    v.literal("submitted"),
+    v.literal("failed"),
+  ),
+  stripePayoutId: v.optional(v.string()),
+  createdAt: v.number(),
+};
+export const payoutReleasesTable = defineTable(payoutReleaseFields)
+  .index("by_key", ["operationKey"])
+  .index("by_state", ["state"]);

package/src/component/connect/mutations.ts

@@ -1,10 +1,13 @@
+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,
@@ -312,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(
@@ -331,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