@fantastic.dev/better-stripe 0.23.2 → 0.25.0

package/src/component/schema.ts

@@ -1,4 +1,25 @@
+import { jobsTable as payoutWorkerJobsTable } from "./payoutWorker/schema.js";
+import {
+  financialRevisionsTable,
+  riskEventsTable,
+  riskRevisionsTable,
+  snapshotsTable,
+  snapshotSourcesTable,
+  snapshotClaimsTable,
+  snapshotFeesTable,
+} from "./payoutSnapshots/schema.js";
 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 +59,21 @@ import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 
 export default defineSchema({
+  payoutWorkerJobs: payoutWorkerJobsTable,
+  payoutFinancialRevisions: financialRevisionsTable,
+  payoutRiskEvents: riskEventsTable,
+  payoutRiskRevisions: riskRevisionsTable,
+  payoutSnapshots: snapshotsTable,
+  payoutSnapshotSources: snapshotSourcesTable,
+  payoutSnapshotClaims: snapshotClaimsTable,
+  payoutSnapshotFees: snapshotFeesTable,
+  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),
+      }),
+});

package/src/component/summary-arithmetic.test.ts

@@ -103,15 +103,20 @@ it("rolls back subtract/reapply updates that would overflow", async () => {
   ).toMatchObject({ totals: [{ gross: max, transferCount: 2 }] });
 });
 
-it("rolls back a reversal whose cumulative summary would overflow", async () => {
+it("rolls back a reversal when a legacy cumulative summary would overflow", async () => {
   const t = convexTest(schema, modules);
   await t.mutation(api.connect.mutations.upsertTransfer, {
     ...transfer("tr_a", 1),
-    reversedAmount: max - 1,
+    reversedAmount: 0,
   });
   await t.mutation(api.connect.mutations.upsertTransfer, {
     ...transfer("tr_b", 1),
-    reversedAmount: 1,
+    reversedAmount: 0,
+  });
+  // Imported legacy totals can be inconsistent even when the new receipt is valid.
+  await t.run(async (ctx) => {
+    const totals = (await ctx.db.query("currencyTotals").first())!;
+    await ctx.db.patch("currencyTotals", totals._id, { reversed: max });
   });
   const before = await t.query(
     api.connect.queries.getAccountEarningsByCurrency,
@@ -120,7 +125,7 @@ it("rolls back a reversal whose cumulative summary would overflow", async () =>
   await expect(
     t.mutation(api.connect.mutations.recordTransferReversal, {
       stripeTransferId: "tr_b",
-      reversedAmount: 2,
+      reversedAmount: 1,
     }),
   ).rejects.toThrow(/safe integer/i);
   expect(

package/src/react/workflows/AffiliateRecovery.test.tsx

@@ -0,0 +1,106 @@
+// @vitest-environment jsdom
+import {
+  cleanup,
+  render,
+  screen,
+  fireEvent,
+  waitFor,
+} from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import {
+  AffiliateRecovery,
+  AffiliateRecoveryHistory,
+} from "./AffiliateRecovery.js";
+import { affiliateRecoveryScenarios } from "../../testing/affiliate-recovery.js";
+import type { AffiliateRecoveryOperation } from "../../client/affiliateRecovery.js";
+afterEach(cleanup);
+it("shows exact recovered, debt and withheld amounts and labels simulated data separately", () => {
+  const fixture = affiliateRecoveryScenarios().find(
+    (r) => r.id === "paid-out",
+  )!;
+  expect(fixture.evidence).toBe("simulated");
+  render(<AffiliateRecovery snapshot={fixture.snapshot} currency="usd" />);
+  expect(screen.getAllByText("$10.01").length).toBeGreaterThan(1);
+  expect(screen.getByText("insufficient_balance")).toBeDefined();
+  expect(screen.getByText("Outstanding debt")).toBeDefined();
+  expect(screen.getByText("Withheld earnings")).toBeDefined();
+});
+it("exposes identical formatted metrics through the headless render API", () => {
+  const fixture = affiliateRecoveryScenarios().find((r) => r.id === "overlap")!;
+  let metrics: { key: string; formattedValue: string }[] = [];
+  render(
+    <AffiliateRecovery snapshot={fixture.snapshot} currency="usd">
+      {(state) => {
+        metrics = state.metrics;
+        return <p>{state.rows[0].sourceChargeId}</p>;
+      }}
+    </AffiliateRecovery>,
+  );
+  expect(metrics.find((r) => r.key === "recoveredAmount")!.formattedValue).toBe(
+    "$10.01",
+  );
+  expect(metrics.find((r) => r.key === "restoredAmount")!.formattedValue).toBe(
+    "$5.00",
+  );
+  expect(metrics.find((r) => r.key === "outstandingDebt")!.formattedValue).toBe(
+    "$0.00",
+  );
+});
+it("provides an operator reconcile action and visible provider errors without claiming success", async () => {
+  const fixture = affiliateRecoveryScenarios().find((r) => r.id === "unknown")!;
+  const retry = vi
+    .fn()
+    .mockRejectedValue(new Error("Provider outcome is unknown"));
+  render(
+    <AffiliateRecovery
+      snapshot={fixture.snapshot}
+      currency="usd"
+      onRetry={retry}
+    />,
+  );
+  fireEvent.click(screen.getByRole("button", { name: "Reconcile" }));
+  await waitFor(() =>
+    expect(screen.getByRole("alert").textContent).toBe(
+      "Provider outcome is unknown",
+    ),
+  );
+  expect(retry).toHaveBeenCalledWith(fixture.snapshot.obligations.page[0]._id);
+});
+it("shows authentication, pagination and unconfirmed receipt states", () => {
+  const { rerender } = render(
+    <AffiliateRecovery snapshot={null} currency="usd" />,
+  );
+  expect(
+    screen.getByText("Sign in to view your commission recovery."),
+  ).toBeDefined();
+  const fixture = affiliateRecoveryScenarios()[0];
+  rerender(
+    <AffiliateRecovery
+      snapshot={{
+        ...fixture.snapshot,
+        obligations: { ...fixture.snapshot.obligations, isDone: false },
+      }}
+      currency="usd"
+    />,
+  );
+  expect(screen.getByText(/More adjustments are available/)).toBeDefined();
+  rerender(
+    <AffiliateRecoveryHistory
+      currency="usd"
+      operations={[
+        {
+          _id: "fixture_op",
+          kind: "restoration",
+          amount: 501,
+          state: "unknown",
+          attempted: true,
+          createdAt: 0,
+          _creationTime: 0,
+          obligationId: "fixture_debt",
+        } as AffiliateRecoveryOperation,
+      ]}
+    />,
+  );
+  expect(screen.getByText("Unconfirmed")).toBeDefined();
+  expect(screen.getByText("unknown")).toBeDefined();
+});