@fantastic.dev/better-stripe 0.23.1 → 0.24.0

package/src/component/payoutSync/mutations.ts

@@ -0,0 +1,102 @@
+import { v } from "convex/values";
+import { mutation } from "../earnings/triggers.js";
+import { writePayout } from "../connect/payoutWrites.js";
+import {
+  claimByPayout,
+  payoutById,
+  validateSnapshot,
+  fingerprint,
+} from "./helpers.js";
+import { identity, prepared, result } from "./validators.js";
+export const begin = mutation({
+  args: identity,
+  returns: v.number(),
+  handler: async (ctx, args) => {
+    const claim = await claimByPayout(ctx, args);
+    await payoutById(ctx, args);
+    const generation = (claim?.generation ?? 0) + 1;
+    if (!Number.isSafeInteger(generation))
+      throw new Error("Payout synchronization generation exhausted.");
+    if (claim)
+      await ctx.db.patch("payoutSyncClaims", claim._id, {
+        generation,
+        status: "pending",
+        startedAt: Date.now(),
+      });
+    else
+      await ctx.db.insert("payoutSyncClaims", {
+        ...args,
+        generation,
+        status: "pending",
+        startedAt: Date.now(),
+      });
+    return generation;
+  },
+});
+export const finish = mutation({
+  args: prepared,
+  returns: result,
+  handler: async (ctx, args) => {
+    const claim = await claimByPayout(ctx, args);
+    if (!claim) throw new Error("Payout synchronization claim is missing.");
+    if (claim.generation !== args.generation)
+      return { status: "superseded" as const, generation: args.generation };
+    validateSnapshot(args.payout);
+    if (
+      args.payout.accountId !== args.accountId ||
+      args.payout.stripePayoutId !== args.stripePayoutId
+    )
+      throw new Error(
+        "Payout synchronization snapshot identity does not match.",
+      );
+    const existing = await payoutById(ctx, args);
+    if (
+      existing &&
+      (existing.amount !== args.payout.amount ||
+        existing.currency !== args.payout.currency)
+    )
+      throw new Error("Existing payout original money does not match.");
+    const nextFingerprint = await fingerprint(args.payout);
+    if (
+      claim.status === "accepted" &&
+      claim.acceptedFingerprint !== nextFingerprint
+    )
+      throw new Error("An accepted payout observation cannot be replaced.");
+    const changed =
+      !existing || (await fingerprint(existing)) !== nextFingerprint;
+    if (claim.status === "accepted" && changed)
+      throw new Error(
+        "Accepted payout state changed outside its synchronization.",
+      );
+    if (claim.status === "accepted")
+      return {
+        status: "accepted" as const,
+        generation: args.generation,
+        changed: false,
+        payout: existing!,
+      };
+    const payout = changed ? await writePayout(ctx, args.payout) : existing!;
+    await ctx.db.patch("payoutSyncClaims", claim._id, {
+      status: "accepted",
+      acceptedGeneration: args.generation,
+      acceptedAt: Date.now(),
+      acceptedFingerprint: nextFingerprint,
+    });
+    return {
+      status: "accepted" as const,
+      generation: args.generation,
+      changed,
+      payout,
+    };
+  },
+});
+export const markUnknown = mutation({
+  args: { ...identity, generation: v.number() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const claim = await claimByPayout(ctx, args);
+    if (claim?.generation === args.generation && claim.status === "pending")
+      await ctx.db.patch("payoutSyncClaims", claim._id, { status: "unknown" });
+    return null;
+  },
+});

package/src/component/payoutSync/queries.ts

@@ -0,0 +1,10 @@
+import { v } from "convex/values";
+import { query } from "../_generated/server.js";
+import { claimByPayout } from "./helpers.js";
+import { claimDoc } from "./schema.js";
+import { identity } from "./validators.js";
+export const get = query({
+  args: identity,
+  returns: v.union(claimDoc, v.null()),
+  handler: claimByPayout,
+});

package/src/component/payoutSync/schema.ts

@@ -0,0 +1,25 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+import { identity } from "./validators.js";
+const fields = {
+  ...identity,
+  generation: v.number(),
+  status: v.union(
+    v.literal("pending"),
+    v.literal("accepted"),
+    v.literal("unknown"),
+  ),
+  startedAt: v.number(),
+  acceptedGeneration: v.optional(v.number()),
+  acceptedAt: v.optional(v.number()),
+  acceptedFingerprint: v.optional(v.string()),
+};
+export const claimDoc = v.object({
+  ...fields,
+  _id: v.id("payoutSyncClaims"),
+  _creationTime: v.number(),
+});
+/** Operational generations only. Financial facts remain in the existing payouts table. */
+export const claimsTable = defineTable(fields).index("by_stripe_payout_id", [
+  "stripePayoutId",
+]);

package/src/component/payoutSync/validators.ts

@@ -0,0 +1,21 @@
+import { v } from "convex/values";
+import { payoutFields, payoutDocValidator } from "../connect/validators.js";
+export const identity = { stripePayoutId: v.string(), accountId: v.string() };
+export const snapshot = v.object({
+  ...payoutFields,
+  metadata: v.optional(v.record(v.string(), v.string())),
+});
+export const prepared = {
+  ...identity,
+  generation: v.number(),
+  payout: snapshot,
+};
+export const result = v.union(
+  v.object({
+    status: v.literal("accepted"),
+    generation: v.number(),
+    changed: v.boolean(),
+    payout: payoutDocValidator,
+  }),
+  v.object({ status: v.literal("superseded"), generation: v.number() }),
+);

package/src/component/schema.ts

@@ -1,3 +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,
@@ -37,6 +49,14 @@ 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,
   payoutSourceAllocations: payoutSourceAllocationsTable,

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(