@fantastic.dev/better-stripe 0.23.1 → 0.24.0

package/src/component/affiliateEarnings/mutations.ts

@@ -0,0 +1,196 @@
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import { earningFields } from "../affiliateRecovery/schema.js";
+import {
+  balance,
+  changeBalance,
+  due,
+  updateObligation,
+} from "../affiliateRecovery/accounting.js";
+const earningDoc = v.object({
+  ...earningFields,
+  _id: v.id("affiliateEarnings"),
+  _creationTime: v.number(),
+});
+export const reserveEarning = mutation({
+  args: { sourceChargeId: v.string(), affiliateAccountId: v.string() },
+  returns: earningDoc,
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("affiliateEarnings")
+      .withIndex("by_charge_affiliate", (q) =>
+        q
+          .eq("sourceChargeId", args.sourceChargeId)
+          .eq("affiliateAccountId", args.affiliateAccountId),
+      )
+      .unique();
+    if (existing) return existing;
+    const allocation = await ctx.db
+      .query("settlementAllocations")
+      .withIndex("by_source_charge", (q) =>
+        q.eq("sourceChargeId", args.sourceChargeId),
+      )
+      .unique();
+    const leg = allocation?.transfers.find(
+      (t) =>
+        t.role === "affiliate" &&
+        t.destinationAccountId === args.affiliateAccountId,
+    );
+    if (!allocation || !leg)
+      throw new Error(
+        "Affiliate earning requires an immutable settlement allocation.",
+      );
+    const totals = await balance(
+      ctx,
+      args.affiliateAccountId,
+      allocation.currency,
+    );
+    if (totals?.activePayoutKey)
+      throw new Error("Affiliate payout is pending reconciliation.");
+    if (
+      (totals?.reservedRecovery ?? 0) > 0 ||
+      (totals?.reservedRestoration ?? 0) > 0
+    )
+      throw new Error(
+        "Affiliate provider recovery is pending reconciliation; retry settlement.",
+      );
+    const debts = await ctx.db
+      .query("affiliateObligations")
+      .withIndex("by_affiliate_currency_debt", (q) =>
+        q
+          .eq("affiliateAccountId", args.affiliateAccountId)
+          .eq("currency", allocation.currency)
+          .eq("debtStatus", "open"),
+      )
+      .take(1001);
+    if (debts.length > 1000)
+      throw new Error(
+        "Affiliate debt batch limit exceeded; reconcile before releasing funds.",
+      );
+    let remaining = leg.amount;
+    const offsets = [];
+    for (const debt of debts) {
+      if (
+        debt.sourceChargeId === args.sourceChargeId ||
+        debt.needsReconciliation
+      )
+        continue;
+      if (debt.activeOperationId)
+        throw new Error("Affiliate debt has an unresolved provider operation.");
+      const amount = Math.min(remaining, due(debt));
+      if (amount > 0) {
+        offsets.push({ debt, amount });
+        remaining -= amount;
+      }
+      if (!remaining) break;
+    }
+    const earningId = await ctx.db.insert("affiliateEarnings", {
+      ...args,
+      currency: allocation.currency,
+      originalCommission: leg.amount,
+      withheldAmount: leg.amount - remaining,
+      releaseAmount: remaining,
+      status: "reserved",
+      sourceInvoiceId: allocation.sourceInvoiceId,
+      paymentIntentId: allocation.paymentIntentId,
+    });
+    for (const { debt, amount } of offsets) {
+      await ctx.db.insert("affiliateOffsets", {
+        earningId,
+        obligationId: debt._id,
+        amount,
+      });
+      await updateObligation(ctx, debt, {
+        offsetAmount: (debt.offsetAmount ?? 0) + amount,
+        lastState: "offset",
+      });
+    }
+    const obligationId = await ctx.db.insert("affiliateObligations", {
+      sourceChargeId: allocation.sourceChargeId,
+      sourceInvoiceId: allocation.sourceInvoiceId,
+      paymentIntentId: allocation.paymentIntentId,
+      paymentId: allocation.paymentId,
+      storeAccountId: allocation.transfers.find((leg) => leg.role === "store")
+        ?.destinationAccountId,
+      affiliateAccountId: args.affiliateAccountId,
+      currency: allocation.currency,
+      chargeAmount: allocation.gross,
+      originalCommission: leg.amount,
+      releasedCommission: remaining,
+      earningId,
+      refundedPrincipal: 0,
+      disputedPrincipal: 0,
+      lostPrincipal: 0,
+      finalizedAmount: 0,
+      provisionalAmount: 0,
+      recoveredAmount: 0,
+      needsReconciliation: false,
+    });
+    await updateObligation(
+      ctx,
+      (await ctx.db.get("affiliateObligations", obligationId))!,
+      {},
+    );
+    await changeBalance(ctx, args.affiliateAccountId, allocation.currency, {
+      withheldAmount: leg.amount - remaining,
+      netPayable: remaining,
+    });
+    return (await ctx.db.get("affiliateEarnings", earningId))!;
+  },
+});
+export const confirmEarning = mutation({
+  args: {
+    earningId: v.id("affiliateEarnings"),
+    stripeTransferId: v.optional(v.string()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const earning = await ctx.db.get("affiliateEarnings", args.earningId);
+    if (!earning) throw new Error("Affiliate earning not found.");
+    if (earning.status === "paid") {
+      if (earning.stripeTransferId !== args.stripeTransferId)
+        throw new Error("Affiliate earning receipt cannot change.");
+      return null;
+    }
+    if (earning.releaseAmount > 0 !== !!args.stripeTransferId)
+      throw new Error("Affiliate release requires an exact transfer receipt.");
+    if (args.stripeTransferId) {
+      const transfer = await ctx.db
+        .query("transfers")
+        .withIndex("by_stripe_transfer_id", (q) =>
+          q.eq("stripeTransferId", args.stripeTransferId!),
+        )
+        .unique();
+      if (
+        !transfer ||
+        transfer.amount !== earning.releaseAmount ||
+        transfer.currency !== earning.currency ||
+        transfer.destinationAccountId !== earning.affiliateAccountId ||
+        transfer.sourceChargeId !== earning.sourceChargeId
+      )
+        throw new Error(
+          "Affiliate release receipt does not match its earning.",
+        );
+    }
+    const obligation = await ctx.db
+      .query("affiliateObligations")
+      .withIndex("by_charge", (q) =>
+        q.eq("sourceChargeId", earning.sourceChargeId),
+      )
+      .take(1001);
+    const own = obligation.find((row) => row.earningId === earning._id);
+    if (!own || obligation.length > 1000)
+      throw new Error("Affiliate earning obligation requires reconciliation.");
+    await ctx.db.patch("affiliateObligations", own._id, {
+      stripeTransferId: args.stripeTransferId,
+    });
+    await ctx.db.patch("affiliateEarnings", earning._id, {
+      status: "paid",
+      stripeTransferId: args.stripeTransferId,
+    });
+    await changeBalance(ctx, earning.affiliateAccountId, earning.currency, {
+      netPayable: -earning.releaseAmount,
+    });
+    return null;
+  },
+});

package/src/component/affiliatePayouts/mutations.ts

@@ -0,0 +1,121 @@
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import { balance } from "../affiliateRecovery/accounting.js";
+import { payoutReleaseFields } from "../affiliateRecovery/schema.js";
+const doc = v.object({
+  ...payoutReleaseFields,
+  _id: v.id("affiliatePayoutReleases"),
+  _creationTime: v.number(),
+});
+export const reservePayout = mutation({
+  args: {
+    affiliateAccountId: v.string(),
+    currency: v.string(),
+    amount: v.number(),
+    minimumAmount: v.number(),
+    operationKey: v.optional(v.string()),
+    now: v.number(),
+  },
+  returns: v.union(doc, v.null()),
+  handler: async (ctx, args) => {
+    const totals = await balance(ctx, args.affiliateAccountId, args.currency);
+    if (!totals) return null;
+    if (!args.operationKey?.trim())
+      throw new Error("Affiliate payouts require a stable idempotency key.");
+    const existing = await ctx.db
+      .query("affiliatePayoutReleases")
+      .withIndex("by_key", (q) => q.eq("operationKey", args.operationKey!))
+      .unique();
+    if (existing) {
+      if (
+        existing.amount !== args.amount ||
+        existing.affiliateAccountId !== args.affiliateAccountId ||
+        existing.currency !== args.currency ||
+        existing.minimumAmount !== args.minimumAmount
+      )
+        throw new Error("Affiliate payout operation identity cannot change.");
+      if (existing.state === "pending" || existing.state === "unknown") {
+        if (
+          totals.outstandingDebt > 0 ||
+          totals.reservedRecovery > 0 ||
+          totals.reservedRestoration > 0 ||
+          totals.activePayoutKey !== existing.operationKey
+        )
+          throw new Error(
+            "Affiliate recovery must be reconciled before payout release.",
+          );
+      }
+      return existing;
+    }
+    if (
+      ![args.amount, args.minimumAmount].every(
+        (n) => Number.isSafeInteger(n) && n > 0,
+      ) ||
+      args.amount < args.minimumAmount
+    )
+      throw new Error("Affiliate payout does not meet its currency minimum.");
+    if (
+      totals.outstandingDebt > 0 ||
+      totals.reservedRecovery > 0 ||
+      totals.reservedRestoration > 0 ||
+      totals.activePayoutKey
+    )
+      throw new Error(
+        "Affiliate recovery must be reconciled before payout release.",
+      );
+    const id = await ctx.db.insert("affiliatePayoutReleases", {
+      affiliateAccountId: args.affiliateAccountId,
+      currency: args.currency,
+      amount: args.amount,
+      minimumAmount: args.minimumAmount,
+      operationKey: args.operationKey,
+      createdAt: args.now,
+      state: "pending",
+    });
+    await ctx.db.patch("affiliateRecoveryBalances", totals._id, {
+      activePayoutKey: args.operationKey,
+      pendingPayoutAmount: args.amount,
+    });
+    return (await ctx.db.get("affiliatePayoutReleases", id))!;
+  },
+});
+export const finishPayout = mutation({
+  args: {
+    operationKey: v.string(),
+    state: v.union(
+      v.literal("unknown"),
+      v.literal("submitted"),
+      v.literal("failed"),
+    ),
+    stripePayoutId: v.optional(v.string()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const row = await ctx.db
+      .query("affiliatePayoutReleases")
+      .withIndex("by_key", (q) => q.eq("operationKey", args.operationKey))
+      .unique();
+    if (!row) throw new Error("Affiliate payout operation not found.");
+    if (row.state === "submitted") {
+      if (
+        args.state === "submitted" &&
+        args.stripePayoutId !== row.stripePayoutId
+      )
+        throw new Error("Affiliate payout receipt cannot change.");
+      return null;
+    }
+    if (args.state === "submitted" && !args.stripePayoutId)
+      throw new Error("Affiliate payout requires a provider receipt.");
+    const totals = (await balance(ctx, row.affiliateAccountId, row.currency))!;
+    if (args.state !== "unknown" && totals.activePayoutKey === row.operationKey)
+      await ctx.db.patch("affiliateRecoveryBalances", totals._id, {
+        activePayoutKey: undefined,
+        pendingPayoutAmount: 0,
+      });
+    await ctx.db.patch("affiliatePayoutReleases", row._id, {
+      state: args.state,
+      stripePayoutId: args.stripePayoutId,
+    });
+    return null;
+  },
+});

package/src/component/affiliatePayouts/queries.ts

@@ -0,0 +1,28 @@
+import {
+  paginationOptsValidator,
+  paginationResultValidator,
+} from "convex/server";
+import { v } from "convex/values";
+import { query } from "../_generated/server.js";
+import { payoutReleaseFields } from "../affiliateRecovery/schema.js";
+export const pendingPayouts = query({
+  args: {
+    state: v.union(v.literal("pending"), v.literal("unknown")),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(
+    v.object({
+      ...payoutReleaseFields,
+      _id: v.id("affiliatePayoutReleases"),
+      _creationTime: v.number(),
+    }),
+  ),
+  handler: (ctx, args) =>
+    ctx.db
+      .query("affiliatePayoutReleases")
+      .withIndex("by_state", (q) => q.eq("state", args.state))
+      .paginate({
+        ...args.paginationOpts,
+        numItems: Math.min(10, args.paginationOpts.numItems),
+      }),
+});

package/src/component/affiliatePayouts/recipientGuard.ts

@@ -0,0 +1,42 @@
+import type { MutationCtx } from "../_generated/server.js";
+import { balance, changeBalance } from "../affiliateRecovery/accounting.js";
+
+type Identity = { accountId: string; currency: string; operationKey: string };
+const key = (identity: Identity) =>
+  `bs:recipient-payout:${identity.operationKey}`;
+
+/** Share the recovery lock with combined seller/affiliate payout claims. */
+export async function reserveRecoveryGuard(
+  ctx: MutationCtx,
+  identity: Identity,
+  amount: number,
+) {
+  await changeBalance(ctx, identity.accountId, identity.currency, {});
+  const totals = (await balance(ctx, identity.accountId, identity.currency))!;
+  if (
+    totals.outstandingDebt > 0 ||
+    totals.reservedRecovery > 0 ||
+    totals.reservedRestoration > 0 ||
+    (totals.activePayoutKey && totals.activePayoutKey !== key(identity))
+  )
+    throw new Error(
+      "Affiliate recovery must be reconciled before payout release.",
+    );
+  await ctx.db.patch("affiliateRecoveryBalances", totals._id, {
+    activePayoutKey: key(identity),
+    pendingPayoutAmount: amount,
+  });
+}
+
+/** Only a verified outcome or a never-attempted cancellation releases the lock. */
+export async function releaseRecoveryGuard(
+  ctx: MutationCtx,
+  identity: Identity,
+) {
+  const totals = await balance(ctx, identity.accountId, identity.currency);
+  if (totals?.activePayoutKey === key(identity))
+    await ctx.db.patch("affiliateRecoveryBalances", totals._id, {
+      activePayoutKey: undefined,
+      pendingPayoutAmount: 0,
+    });
+}

package/src/component/affiliateRecovery/accounting.ts

@@ -0,0 +1,111 @@
+import type { Doc } from "../_generated/dataModel.js";
+import type { MutationCtx } from "../_generated/server.js";
+export type Obligation = Omit<
+  Doc<"affiliateObligations">,
+  "_id" | "_creationTime"
+>;
+export const target = (row: Obligation) =>
+  row.finalizedAmount + row.provisionalAmount;
+export const netRecovery = (row: Obligation) =>
+  row.recoveredAmount + (row.offsetAmount ?? 0) - (row.restoredAmount ?? 0);
+export const due = (row: Obligation) =>
+  Math.max(0, target(row) - netRecovery(row));
+export const credit = (row: Obligation) =>
+  row.needsReconciliation ? 0 : Math.max(0, netRecovery(row) - target(row));
+export async function balance(
+  ctx: MutationCtx,
+  account: string,
+  currency: string,
+) {
+  return ctx.db
+    .query("affiliateRecoveryBalances")
+    .withIndex("by_affiliate_currency", (q) =>
+      q.eq("affiliateAccountId", account).eq("currency", currency),
+    )
+    .unique();
+}
+export async function changeBalance(
+  ctx: MutationCtx,
+  account: string,
+  currency: string,
+  changes: Partial<
+    Record<
+      | "originalCommission"
+      | "recoveredAmount"
+      | "offsetAmount"
+      | "restoredAmount"
+      | "outstandingDebt"
+      | "reservedRecovery"
+      | "reservedRestoration"
+      | "restorationDue"
+      | "withheldAmount"
+      | "netPayable",
+      number
+    >
+  >,
+) {
+  const existing = await balance(ctx, account, currency);
+  const base = existing ?? {
+    affiliateAccountId: account,
+    currency,
+    originalCommission: 0,
+    recoveredAmount: 0,
+    offsetAmount: 0,
+    restoredAmount: 0,
+    outstandingDebt: 0,
+    reservedRecovery: 0,
+    reservedRestoration: 0,
+    restorationDue: 0,
+    withheldAmount: 0,
+    netPayable: 0,
+  };
+  const patch: Record<string, number> = {};
+  for (const key of Object.keys(changes) as (keyof typeof changes)[]) {
+    const next = base[key] + (changes[key] ?? 0);
+    if (!Number.isSafeInteger(next) || next < 0)
+      throw new Error(`Invalid affiliate balance ${key}.`);
+    patch[key] = next;
+  }
+  if (existing)
+    await ctx.db.patch("affiliateRecoveryBalances", existing._id, patch);
+  else await ctx.db.insert("affiliateRecoveryBalances", { ...base, ...patch });
+}
+export async function updateObligation(
+  ctx: MutationCtx,
+  previous: Doc<"affiliateObligations">,
+  patch: Partial<Obligation>,
+) {
+  if (!previous.accounted) {
+    await changeBalance(ctx, previous.affiliateAccountId, previous.currency, {
+      originalCommission: previous.originalCommission,
+      recoveredAmount: previous.recoveredAmount,
+      offsetAmount: previous.offsetAmount ?? 0,
+      restoredAmount: previous.restoredAmount ?? 0,
+      outstandingDebt: due(previous),
+      restorationDue: credit(previous),
+      reservedRecovery: previous.reservedRecovery ?? 0,
+      reservedRestoration: previous.reservedRestoration ?? 0,
+    });
+  }
+  const next = { ...previous, ...patch };
+  const debtAmount = due(next),
+    creditAmount = credit(next);
+  await changeBalance(ctx, next.affiliateAccountId, next.currency, {
+    outstandingDebt: debtAmount - (previous.debtAmount ?? due(previous)),
+    restorationDue: creditAmount - (previous.creditAmount ?? credit(previous)),
+    recoveredAmount: next.recoveredAmount - previous.recoveredAmount,
+    offsetAmount: (next.offsetAmount ?? 0) - (previous.offsetAmount ?? 0),
+    restoredAmount: (next.restoredAmount ?? 0) - (previous.restoredAmount ?? 0),
+    reservedRecovery:
+      (next.reservedRecovery ?? 0) - (previous.reservedRecovery ?? 0),
+    reservedRestoration:
+      (next.reservedRestoration ?? 0) - (previous.reservedRestoration ?? 0),
+  });
+  await ctx.db.patch("affiliateObligations", previous._id, {
+    ...patch,
+    accounted: true,
+    debtAmount,
+    creditAmount,
+    debtStatus: debtAmount > 0 ? "open" : "settled",
+  });
+}