@fantastic.dev/better-stripe 0.23.2 → 0.24.0

package/src/component/payout-recovery-integration.test.ts

@@ -0,0 +1,172 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, it } from "vitest";
+import schema from "./schema.js";
+import { changeBalance } from "./affiliateRecovery/accounting.js";
+import { transferFingerprint } from "./payoutRelease/helpers.js";
+const modules = import.meta.glob("./**/*.*s");
+const m = (name: string) =>
+  makeFunctionReference<"mutation">(`payoutRelease/mutations:${name}`);
+const pm = (name: string) =>
+  makeFunctionReference<"mutation">(`payoutPolicy/mutations:${name}`);
+const scope = { accountId: "acct_recipient", ownerKey: "user_1" };
+const transfer = (
+  stripeTransferId: string,
+  amount: number,
+  role = "store",
+) => ({
+  stripeTransferId,
+  destinationAccountId: scope.accountId,
+  amount,
+  currency: "usd",
+  status: "paid",
+  role,
+});
+async function setup() {
+  const t = convexTest(schema, modules);
+  await t.mutation(pm("prepare"), {
+    ...scope,
+    operationKey: "enable",
+    expectedRevision: -1,
+    mode: "custom",
+    thresholds: [{ currency: "usd", amount: 1000 }],
+    country: "US",
+    observedSchedule: { interval: "daily" },
+  });
+  await t.mutation(pm("confirm"), {
+    ...scope,
+    operationKey: "enable",
+    observedSchedule: { interval: "manual" },
+  });
+  for (const row of [
+    transfer("tr_creator", 600),
+    transfer("tr_affiliate", 400, "affiliate"),
+  ])
+    await t.mutation(
+      makeFunctionReference<"mutation">("connect/mutations:upsertTransfer"),
+      row,
+    );
+  const rows = await t.run(async (ctx) => ctx.db.query("transfers").take(10));
+  const args = {
+    ...scope,
+    operationKey: "release-1",
+    expectedRevision: 0,
+    currency: "usd",
+    providerAvailable: 1000,
+    independentLiabilities: 0,
+    observations: rows.map((row) => ({
+      stripeTransferId: row.stripeTransferId,
+      matureNet: row.amount,
+      pendingCredits: 0,
+      currency: row.currency,
+      ledgerFingerprint: transferFingerprint(row),
+      observedAt: Date.now(),
+      transactionIds: [`txn_${row.stripeTransferId}`],
+    })),
+  };
+  return { t, args };
+}
+it("blocks combined payouts on affiliate debt in the payout currency", async () => {
+  const { t, args } = await setup();
+  await t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "usd", { outstandingDebt: 100 }),
+  );
+  await expect(t.mutation(m("claim"), args)).rejects.toThrow(/recovery/);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+  ).toEqual([]);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toEqual([]);
+});
+
+it("keeps independent currency debts out of a verified payout", async () => {
+  const { t, args } = await setup();
+  await t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "eur", { outstandingDebt: 100 }),
+  );
+  expect(await t.mutation(m("claim"), args)).toMatchObject({
+    status: "reserved",
+    amount: 1000,
+  });
+});
+
+it("shares one reservation between direct and combined payout paths", async () => {
+  const { t, args } = await setup();
+  await t.run((ctx) => changeBalance(ctx, scope.accountId, "usd", {}));
+  const direct = () =>
+    t.mutation(
+      makeFunctionReference<"mutation">(
+        "affiliatePayouts/mutations:reservePayout",
+      ),
+      {
+        affiliateAccountId: scope.accountId,
+        currency: "usd",
+        amount: 1000,
+        minimumAmount: 1,
+        operationKey: "direct",
+        now: Date.now(),
+      },
+    );
+  const outcomes = await Promise.allSettled([
+    t.mutation(m("claim"), args),
+    direct(),
+  ]);
+  expect(
+    outcomes.filter((result) => result.status === "fulfilled"),
+  ).toHaveLength(1);
+  expect(
+    outcomes.filter((result) => result.status === "rejected"),
+  ).toHaveLength(1);
+});
+
+it("rechecks new debt immediately before the provider attempt and permits safe cancellation", async () => {
+  const { t, args } = await setup();
+  await t.mutation(m("claim"), args);
+  await t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "usd", { outstandingDebt: 100 }),
+  );
+  const identity = { ...scope, operationKey: args.operationKey };
+  await expect(t.mutation(m("beginAttempt"), identity)).rejects.toThrow(
+    /recovery/,
+  );
+  await t.mutation(m("cancelUnattempted"), identity);
+  expect(
+    await t.run((ctx) => ctx.db.query("affiliateRecoveryBalances").first()),
+  ).toMatchObject({
+    outstandingDebt: 100,
+    pendingPayoutAmount: 0,
+  });
+});
+
+it("holds unknown payout attempts until a verified receipt, without erasing later debt", async () => {
+  const { t, args } = await setup();
+  await t.mutation(m("claim"), args);
+  const identity = { ...scope, operationKey: args.operationKey };
+  await t.mutation(m("beginAttempt"), identity);
+  await t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "usd", { outstandingDebt: 100 }),
+  );
+  const before = await t.run((ctx) =>
+    ctx.db.query("affiliateRecoveryBalances").first(),
+  );
+  expect(before?.activePayoutKey).toBe(
+    `bs:recipient-payout:${args.operationKey}`,
+  );
+  await expect(t.mutation(m("cancelUnattempted"), identity)).rejects.toThrow(
+    /attempt/,
+  );
+  await t.mutation(m("recordOutcome"), {
+    ...identity,
+    stripePayoutId: "po_verified",
+    amount: 1000,
+    currency: "usd",
+    providerStatus: "pending",
+  });
+  const after = await t.run((ctx) =>
+    ctx.db.query("affiliateRecoveryBalances").first(),
+  );
+  expect(after?.activePayoutKey).toBeUndefined();
+  expect(after?.outstandingDebt).toBe(100);
+});

package/src/component/payoutRelease/mutations.ts

@@ -1,3 +1,7 @@
+import {
+  reserveRecoveryGuard,
+  releaseRecoveryGuard,
+} from "../affiliatePayouts/recipientGuard.js";
 import {
   historicalBatchArgs,
   adoptHistoricalBatch as importHistoricalBatch,
@@ -110,6 +114,7 @@ export const claim = mutation({
       sources,
     });
     if (plan.status === "held") return plan;
+    await reserveRecoveryGuard(ctx, args, plan.amount);
     for (const allocation of plan.allocations) {
       const prior = await sourceById(ctx, allocation.stripeTransferId);
       if (prior)
@@ -155,6 +160,7 @@ export const beginAttempt = mutation({
     if (feeRevision !== (claim.feeRevision ?? 0))
       throw new Error("Payout fee revision changed after reservation.");
     await checkSnapshot(ctx, claim.accountId, claim.observations, true);
+    await reserveRecoveryGuard(ctx, claim, claim.amount);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       attemptedAt: Date.now(),
     });
@@ -174,6 +180,7 @@ export const cancelUnattempted = mutation({
       throw new Error("An attempted payout claim cannot be canceled.");
     if (claim.status === "canceled") return claim;
     await moveAllocations(ctx, claim, "release");
+    await releaseRecoveryGuard(ctx, claim);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       status: "canceled",
     });
@@ -257,6 +264,7 @@ export const recordOutcome = mutation({
     if (claim.status === "paid" && args.providerStatus !== "paid" && !returned)
       return claim;
     await recordFees(ctx, claim, args, returned);
+    await releaseRecoveryGuard(ctx, claim);
     if (returned) {
       await moveAllocations(
         ctx,
@@ -329,6 +337,7 @@ export const recordRejection = mutation({
     if (adoptedRejection && adoptedRejection._id !== claim._id)
       throw new Error("Payout rejection receipt is already allocated.");
     await moveAllocations(ctx, claim, "release");
+    await releaseRecoveryGuard(ctx, claim);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       status: "rejected",
       rejection: { requestId: args.requestId, code: args.code },

package/src/component/payoutRelease/queries.ts

@@ -1,3 +1,5 @@
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
 import { transferDocValidator } from "../connect/validators.js";
 import { readFees } from "./fees.js";
 import { paginationOptsValidator } from "convex/server";
@@ -43,7 +45,7 @@ export const pending = query({
       args.paginationOpts.numItems > 100
     )
       throw new Error("Invalid payout claim page.");
-    const result = await ctx.db
+    const result = await paginator(ctx.db, schema)
       .query("payoutReleaseClaims")
       .withIndex("by_account_status", (q) =>
         q.eq("accountId", args.accountId).eq("status", "reserved"),

package/src/component/schema.ts

@@ -1,4 +1,15 @@
 import { claimsTable as payoutSyncClaimsTable } from "./payoutSync/schema.js";
+import {
+  payoutReleasesTable as affiliatePayoutReleases,
+  operationsTable as affiliateOperations,
+  earningsTable as affiliateEarnings,
+  offsetsTable as affiliateOffsets,
+  balancesTable as affiliateBalances,
+} from "./affiliateRecovery/schema.js";
+import {
+  affiliateObligationsTable,
+  affiliateReversalReceiptsTable,
+} from "./settlement/clawbackSchema.js";
 import {
   feeBalancesTable as payoutFeeBalancesTable,
   claimsTable as payoutReleaseClaimsTable,
@@ -38,6 +49,13 @@ import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 
 export default defineSchema({
+  affiliateObligations: affiliateObligationsTable,
+  affiliateRecoveryOperations: affiliateOperations,
+  affiliatePayoutReleases,
+  affiliateEarnings,
+  affiliateOffsets,
+  affiliateRecoveryBalances: affiliateBalances,
+  affiliateReversalReceipts: affiliateReversalReceiptsTable,
   payoutSyncClaims: payoutSyncClaimsTable,
   payoutFeeBalances: payoutFeeBalancesTable,
   payoutReleaseClaims: payoutReleaseClaimsTable,

package/src/component/settlement/clawbackSchema.ts

@@ -0,0 +1,78 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+
+/** Principal snapshots on the original charge axis, never incremental debits. */
+export const commissionExposureValidator = v.object({
+  kind: v.union(v.literal("refund"), v.literal("dispute")),
+  chargeAmount: v.number(),
+  principal: v.number(),
+  finalized: v.boolean(),
+  disputeState: v.optional(
+    v.union(v.literal("open"), v.literal("lost"), v.literal("won")),
+  ),
+  disputeId: v.optional(v.string()),
+  refundedPrincipal: v.optional(v.number()),
+  refundId: v.optional(v.string()),
+});
+
+export const obligationFields = {
+  stripeTransferId: v.optional(v.string()),
+  sourceChargeId: v.string(),
+  sourceInvoiceId: v.optional(v.string()),
+  paymentIntentId: v.optional(v.string()),
+  paymentId: v.optional(v.string()),
+  storeAccountId: v.optional(v.string()),
+  lastRefundId: v.optional(v.string()),
+  affiliateAccountId: v.string(),
+  currency: v.string(),
+  chargeAmount: v.number(),
+  originalCommission: v.number(),
+  refundedPrincipal: v.number(),
+  disputedPrincipal: v.number(),
+  lostPrincipal: v.number(),
+  finalizedAmount: v.number(),
+  provisionalAmount: v.number(),
+  /** Confirmed transfer reversal total; reservations are not receipts. */
+  recoveredAmount: v.number(),
+  /** Existing reversals may have no attributable refund/dispute receipt. */
+  needsReconciliation: v.boolean(),
+  accounted: v.optional(v.boolean()),
+  legacyReceiptIds: v.optional(v.array(v.string())),
+  legacyRestorationIds: v.optional(v.array(v.string())),
+  operatorNote: v.optional(v.string()),
+  earningId: v.optional(v.id("affiliateEarnings")),
+  releasedCommission: v.optional(v.number()),
+  offsetAmount: v.optional(v.number()),
+  restoredAmount: v.optional(v.number()),
+  reservedRecovery: v.optional(v.number()),
+  reservedRestoration: v.optional(v.number()),
+  debtAmount: v.optional(v.number()),
+  creditAmount: v.optional(v.number()),
+  debtStatus: v.optional(v.union(v.literal("open"), v.literal("settled"))),
+  disputeState: v.optional(
+    v.union(v.literal("open"), v.literal("lost"), v.literal("won")),
+  ),
+  disputeId: v.optional(v.string()),
+  activeOperationId: v.optional(v.id("affiliateRecoveryOperations")),
+  lastState: v.optional(v.string()),
+  lastError: v.optional(v.string()),
+  operationSequence: v.optional(v.number()),
+};
+export const affiliateObligationsTable = defineTable(obligationFields)
+  .index("by_transfer", ["stripeTransferId"])
+  .index("by_charge", ["sourceChargeId"])
+  .index("by_affiliate_currency_debt", [
+    "affiliateAccountId",
+    "currency",
+    "debtStatus",
+  ])
+  .index("by_affiliate_currency", ["affiliateAccountId", "currency"]);
+export const affiliateReversalReceiptsTable = defineTable({
+  stripeReversalId: v.string(),
+  stripeTransferId: v.string(),
+  operationId: v.string(),
+  amount: v.number(),
+})
+  .index("by_receipt", ["stripeReversalId"])
+  .index("by_transfer_operation", ["stripeTransferId", "operationId"])
+  .index("by_transfer", ["stripeTransferId"]);

package/src/component/settlement/clawbacks.ts

@@ -0,0 +1,233 @@
+import { updateObligation } from "../affiliateRecovery/accounting.js";
+import type { Infer } from "convex/values";
+import type { Doc } from "../_generated/dataModel.js";
+import type { MutationCtx } from "../_generated/server.js";
+import { commissionExposureValidator } from "./clawbackSchema.js";
+
+export type CommissionExposure = Infer<typeof commissionExposureValidator>;
+
+/** Exact round-half-up proportional commission in integer currency units. */
+export function proportionalCommission(
+  commission: number,
+  principal: number,
+  charge: number,
+): number {
+  for (const n of [commission, principal, charge]) {
+    if (!Number.isSafeInteger(n) || n < 0)
+      throw new Error(
+        "Commission recovery requires non-negative integer units.",
+      );
+  }
+  if (charge === 0)
+    throw new Error("Commission recovery requires a positive charge.");
+  const numerator = BigInt(commission) * BigInt(Math.min(principal, charge));
+  return Number((2n * numerator + BigInt(charge)) / (2n * BigInt(charge)));
+}
+
+/** Lazily migrate one immutable original affiliate leg, also used by backfill. */
+export async function ensureCommissionObligation(
+  ctx: MutationCtx,
+  transfer: Doc<"transfers">,
+  chargeAmount: number,
+) {
+  if (
+    transfer.role !== "affiliate" ||
+    transfer.reinstatement ||
+    !transfer.sourceChargeId
+  )
+    throw new Error(
+      "Commission obligation requires an original affiliate transfer.",
+    );
+  const existing = await ctx.db
+    .query("affiliateObligations")
+    .withIndex("by_transfer", (q) =>
+      q.eq("stripeTransferId", transfer.stripeTransferId),
+    )
+    .unique();
+  if (existing) {
+    if (
+      existing.chargeAmount !== chargeAmount ||
+      (existing.releasedCommission ?? existing.originalCommission) !==
+        transfer.amount ||
+      existing.affiliateAccountId !== transfer.destinationAccountId ||
+      existing.currency !== transfer.currency ||
+      existing.sourceChargeId !== transfer.sourceChargeId ||
+      (transfer.sourceInvoiceId !== undefined &&
+        existing.sourceInvoiceId !== transfer.sourceInvoiceId)
+    )
+      throw new Error("Original affiliate commission identity cannot change.");
+    return existing;
+  }
+  proportionalCommission(transfer.amount, 0, chargeAmount);
+  const allocation = await ctx.db
+    .query("settlementAllocations")
+    .withIndex("by_source_charge", (q) =>
+      q.eq("sourceChargeId", transfer.sourceChargeId!),
+    )
+    .unique();
+  const earning = await ctx.db
+    .query("affiliateEarnings")
+    .withIndex("by_charge_affiliate", (q) =>
+      q
+        .eq("sourceChargeId", transfer.sourceChargeId!)
+        .eq("affiliateAccountId", transfer.destinationAccountId),
+    )
+    .unique();
+  if (
+    allocation &&
+    (allocation.gross !== chargeAmount ||
+      allocation.currency !== transfer.currency ||
+      !allocation.transfers.some(
+        (leg) =>
+          leg.role === "affiliate" &&
+          leg.destinationAccountId === transfer.destinationAccountId &&
+          leg.amount === (earning?.originalCommission ?? transfer.amount),
+      ))
+  )
+    throw new Error("Commission recovery conflicts with original settlement.");
+  const recoveredAmount = transfer.reversedAmount ?? 0;
+  if (
+    !Number.isSafeInteger(recoveredAmount) ||
+    recoveredAmount < 0 ||
+    recoveredAmount > transfer.amount
+  )
+    throw new Error("Invalid original affiliate reversal balance.");
+  const id = await ctx.db.insert("affiliateObligations", {
+    stripeTransferId: transfer.stripeTransferId,
+    sourceChargeId: transfer.sourceChargeId,
+    sourceInvoiceId: transfer.sourceInvoiceId ?? allocation?.sourceInvoiceId,
+    paymentIntentId: allocation?.paymentIntentId,
+    paymentId: transfer.paymentId ?? allocation?.paymentId,
+    storeAccountId: allocation?.transfers.find((leg) => leg.role === "store")
+      ?.destinationAccountId,
+    affiliateAccountId: transfer.destinationAccountId,
+    currency: transfer.currency,
+    chargeAmount,
+    originalCommission: earning?.originalCommission ?? transfer.amount,
+    releasedCommission: transfer.amount,
+    earningId: earning?._id,
+    refundedPrincipal: 0,
+    disputedPrincipal: 0,
+    lostPrincipal: 0,
+    finalizedAmount: 0,
+    provisionalAmount: 0,
+    recoveredAmount,
+    needsReconciliation:
+      recoveredAmount > 0 || (transfer.reversalClaimedAmount ?? 0) > 0,
+  });
+  return (await ctx.db.get("affiliateObligations", id))!;
+}
+
+/** Refunds and disputes share the same original-principal exposure axis. */
+export async function applyCommissionExposure(
+  ctx: MutationCtx,
+  transfer: Doc<"transfers">,
+  exposure: CommissionExposure,
+) {
+  proportionalCommission(
+    transfer.amount,
+    exposure.principal,
+    exposure.chargeAmount,
+  );
+  if (exposure.kind === "refund" && !exposure.finalized)
+    throw new Error("Pending refunds cannot create commission obligations.");
+  const row = await ensureCommissionObligation(
+    ctx,
+    transfer,
+    exposure.chargeAmount,
+  );
+  return applyObligationExposure(ctx, row, exposure);
+}
+export async function applyObligationExposure(
+  ctx: MutationCtx,
+  row: Doc<"affiliateObligations">,
+  exposure: CommissionExposure,
+) {
+  proportionalCommission(
+    row.originalCommission,
+    exposure.principal,
+    exposure.chargeAmount,
+  );
+  if (row.chargeAmount !== exposure.chargeAmount)
+    throw new Error("Original charge amount cannot change.");
+  const principal = Math.min(exposure.principal, exposure.chargeAmount);
+  const refundedPrincipal = Math.max(
+    row.refundedPrincipal,
+    exposure.refundedPrincipal ?? 0,
+    exposure.kind === "refund" ? principal : 0,
+  );
+  let disputedPrincipal = Math.max(
+    row.disputedPrincipal,
+    exposure.kind === "dispute" ? principal : 0,
+  );
+  let lostPrincipal = Math.max(
+    row.lostPrincipal,
+    exposure.kind === "dispute" && exposure.finalized ? principal : 0,
+  );
+  const incomingState =
+    exposure.disputeState ?? (exposure.finalized ? "lost" : "open");
+  const rank = { open: 0, lost: 1, won: 2 };
+  const disputeState =
+    exposure.kind === "dispute" &&
+    rank[incomingState] >= rank[row.disputeState ?? "open"]
+      ? incomingState
+      : row.disputeState;
+  if (disputeState === "won") {
+    disputedPrincipal = 0;
+    lostPrincipal = 0;
+  }
+  if (exposure.kind === "dispute" && disputeState === "lost")
+    lostPrincipal = Math.max(lostPrincipal, disputedPrincipal);
+  const finalizedAmount = proportionalCommission(
+    row.originalCommission,
+    Math.max(refundedPrincipal, lostPrincipal),
+    row.chargeAmount,
+  );
+  const target = proportionalCommission(
+    row.originalCommission,
+    Math.max(refundedPrincipal, disputedPrincipal),
+    row.chargeAmount,
+  );
+  await updateObligation(ctx, row, {
+    disputeState,
+    lastRefundId: exposure.refundId ?? row.lastRefundId,
+    disputeId: exposure.disputeId ?? row.disputeId,
+    refundedPrincipal,
+    disputedPrincipal,
+    lostPrincipal,
+    finalizedAmount,
+    provisionalAmount: target - finalizedAmount,
+  });
+  return target;
+}
+
+/** Webhook upserts cannot rewrite a frozen commission or its confirmed balance. */
+export async function syncCommissionTransfer(
+  ctx: MutationCtx,
+  transfer: Doc<"transfers">,
+) {
+  const row = await ctx.db
+    .query("affiliateObligations")
+    .withIndex("by_transfer", (q) =>
+      q.eq("stripeTransferId", transfer.stripeTransferId),
+    )
+    .unique();
+  if (!row) return;
+  await ensureCommissionObligation(ctx, transfer, row.chargeAmount);
+  const recoveredAmount = Math.max(
+    row.recoveredAmount,
+    transfer.reversedAmount ?? 0,
+  );
+  if (
+    !Number.isSafeInteger(recoveredAmount) ||
+    recoveredAmount > row.originalCommission
+  )
+    throw new Error("Invalid confirmed affiliate reversal balance.");
+  if (recoveredAmount > row.recoveredAmount && row.activeOperationId) return;
+  await updateObligation(ctx, row, {
+    recoveredAmount,
+    ...(recoveredAmount > row.recoveredAmount && row.accounted
+      ? { needsReconciliation: true }
+      : {}),
+  });
+}

package/src/component/settlement/mutations.ts

@@ -1,3 +1,8 @@
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
+import { updateObligation } from "../affiliateRecovery/accounting.js";
+import { paginationOptsValidator } from "convex/server";
+import { ensureCommissionObligation } from "./clawbacks.js";
 import { v } from "convex/values";
 import { mutation } from "../_generated/server.js";
 import { allocationFields, commissionFields, termValidator } from "./schema.js";
@@ -117,3 +122,52 @@ export const claimCommissionInvoice = mutation({
     };
   },
 });
+
+/** Explicit, resumable migration. Never fabricate legacy refund provenance. */
+export const migrateAffiliateObligations = mutation({
+  args: { paginationOpts: paginationOptsValidator },
+  returns: v.object({
+    migrated: v.number(),
+    skipped: v.number(),
+    isDone: v.boolean(),
+    continueCursor: v.string(),
+  }),
+  handler: async (ctx, args) => {
+    const page = await paginator(ctx.db, schema)
+      .query("transfers")
+      .paginate({
+        ...args.paginationOpts,
+        numItems: Math.min(100, args.paginationOpts.numItems),
+      });
+    let migrated = 0;
+    let skipped = 0;
+    for (const transfer of page.page) {
+      if (transfer.role !== "affiliate" || transfer.reinstatement) continue;
+      const allocation = transfer.sourceChargeId
+        ? await ctx.db
+            .query("settlementAllocations")
+            .withIndex("by_source_charge", (q) =>
+              q.eq("sourceChargeId", transfer.sourceChargeId!),
+            )
+            .unique()
+        : null;
+      if (!allocation) {
+        skipped++;
+        continue;
+      }
+      const obligation = await ensureCommissionObligation(
+        ctx,
+        transfer,
+        allocation.gross,
+      );
+      await updateObligation(ctx, obligation, {});
+      migrated++;
+    }
+    return {
+      migrated,
+      skipped,
+      isDone: page.isDone,
+      continueCursor: page.continueCursor,
+    };
+  },
+});

package/src/component/settlement/queries.ts

@@ -1,3 +1,10 @@
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
+import {
+  paginationOptsValidator,
+  paginationResultValidator,
+} from "convex/server";
+import { obligationFields } from "./clawbackSchema.js";
 import { v } from "convex/values";
 import { query } from "../_generated/server.js";
 import { allocationFields, commissionFields } from "./schema.js";
@@ -36,3 +43,31 @@ export const getCommissionTerm = query({
     };
   },
 });
+
+/** Trusted host API: authorize account ownership before forwarding arguments. */
+export const listAffiliateObligations = query({
+  args: {
+    affiliateAccountId: v.string(),
+    currency: v.string(),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(
+    v.object({
+      ...obligationFields,
+      _id: v.id("affiliateObligations"),
+      _creationTime: v.number(),
+    }),
+  ),
+  handler: (ctx, args) =>
+    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),
+      }),
+});