@fantastic.dev/better-stripe 0.10.2 → 0.12.0

package/src/component/costRecovery/claims.ts

@@ -0,0 +1,109 @@
+import { v } from "convex/values";
+import { type MutationCtx } from "../_generated/server.js";
+import { observationFields, rollbackArgs } from "./schema.js";
+import {
+  adjustTotals,
+  getGroup,
+  integer,
+  sign,
+  validateScope,
+} from "./helpers.js";
+import type { Infer } from "convex/values";
+const _observation = v.object(observationFields);
+export async function recordClaim(
+  ctx: MutationCtx,
+  args: Infer<typeof _observation>,
+) {
+  validateScope(args);
+  [
+    args.amountDue,
+    args.sourceGross,
+    args.sourceProcessingFee,
+    args.revision,
+  ].forEach(integer);
+  if (
+    !args.claimKey ||
+    !args.sourceChargeId ||
+    args.sourceGross <= 0 ||
+    args.sourceProcessingFee < 0 ||
+    args.revision < 0
+  )
+    throw new Error("Invalid recovery claim observation.");
+  const existing = await ctx.db
+    .query("recoveryClaims")
+    .withIndex("by_key", (q) => q.eq("claimKey", args.claimKey))
+    .unique();
+  if (existing) {
+    for (const key of [
+      "accountId",
+      "scopeKey",
+      "currency",
+      "sourceChargeId",
+      "sourceGross",
+      "sourceProcessingFee",
+    ] as const)
+      if (existing[key] !== args[key])
+        throw new Error("Recovery claim source identity cannot change.");
+    if (args.revision < existing.revision) return existing;
+    if (args.revision === existing.revision) {
+      if (args.amountDue !== existing.amountDue)
+        throw new Error(
+          "Recovery revision cannot be reused with a different amount.",
+        );
+      return existing;
+    }
+  }
+  const delta = integer(args.amountDue - (existing?.amountDue ?? 0));
+  const collectedAmount = existing?.collectedAmount ?? 0,
+    reservedAmount = existing?.reservedAmount ?? 0;
+  const outstanding = integer(
+    args.amountDue - collectedAmount - reservedAmount,
+  );
+  const fields = {
+    ...args,
+    collectedAmount,
+    reservedAmount,
+    outstanding,
+    sign: sign(outstanding),
+  };
+  let id = existing?._id;
+  if (id) await ctx.db.patch("recoveryClaims", id, fields);
+  else id = await ctx.db.insert("recoveryClaims", fields);
+  await adjustTotals(ctx, args, { amountDue: delta, outstanding: delta });
+  return (await ctx.db.get("recoveryClaims", id))!;
+}
+
+const _rollbackArgs = v.object(rollbackArgs);
+export async function rollbackClaim(
+  ctx: MutationCtx,
+  args: Infer<typeof _rollbackArgs>,
+) {
+  integer(args.returnedPrincipal);
+  integer(args.revision);
+  const group = await getGroup(ctx, args.groupKey);
+  if (
+    group.status !== "collected" ||
+    group.sourceKind !== "settlement" ||
+    !group.sourceGross
+  )
+    throw new Error(
+      "Rollback requires a collected settlement group with original funding economics.",
+    );
+  if (args.returnedPrincipal < 0 || args.returnedPrincipal > group.sourceGross)
+    throw new Error("Returned principal exceeds the original funding sale.");
+  const abs = BigInt(Math.abs(group.amount)),
+    gross = BigInt(group.sourceGross),
+    principal = BigInt(args.returnedPrincipal);
+  const rounded = Number((abs * principal + gross / 2n) / gross);
+  return recordClaim(ctx, {
+    accountId: group.accountId,
+    scopeKey: group.scopeKey,
+    currency: group.currency,
+    claimKey: `rollback:${group.groupKey}`,
+    sourceChargeId: group.sourceId,
+    sourceGross: group.sourceGross,
+    sourceProcessingFee: group.sourceProcessingFee!,
+    amountDue: group.amount < 0 ? -rounded : rounded,
+    revision: args.revision,
+  });
+}

package/src/component/costRecovery/completion.ts

@@ -0,0 +1,92 @@
+import { v } from "convex/values";
+import type { MutationCtx } from "../_generated/server.js";
+import { finishArgs } from "./schema.js";
+import {
+  adjustTotals,
+  balance,
+  batchLimit,
+  getGroup,
+  integer,
+  sign,
+} from "./helpers.js";
+
+import type { Infer } from "convex/values";
+const _finishArgs = v.object(finishArgs);
+export async function finishGroup(
+  ctx: MutationCtx,
+  args: Infer<typeof _finishArgs>,
+) {
+  const limit = args.limit ?? 10;
+  batchLimit(limit, 10);
+  const group = await getGroup(ctx, args.groupKey);
+  const collect = args.outcome === "collect",
+    terminal = collect ? "collected" : "released",
+    progress = collect ? "collecting" : "releasing";
+  if (group.status === terminal) return { group, isDone: true };
+  if (
+    (collect && ["released", "releasing"].includes(group.status)) ||
+    (!collect && ["collected", "collecting"].includes(group.status))
+  )
+    throw new Error("Recovery outcome cannot change.");
+  if (collect && group.status === "open")
+    throw new Error("Seal recovery before confirming provider collection.");
+  const operations = await ctx.db
+    .query("recoveryReservations")
+    .withIndex("by_group_status", (q) =>
+      q.eq("groupKey", group.groupKey).eq("status", "reserved"),
+    )
+    .take(limit);
+  let amount = 0;
+  for (const operation of operations) {
+    for (const allocation of operation.allocations) {
+      const claim = await ctx.db.get("recoveryClaims", allocation.claimId);
+      if (
+        !claim ||
+        claim.accountId !== group.accountId ||
+        claim.scopeKey !== group.scopeKey ||
+        claim.currency !== group.currency
+      )
+        throw new Error("Recovery allocation identity does not match.");
+      const reservedAmount = integer(claim.reservedAmount - allocation.amount);
+      const collectedAmount = integer(
+        claim.collectedAmount + (collect ? allocation.amount : 0),
+      );
+      const outstanding = integer(
+        claim.amountDue - collectedAmount - reservedAmount,
+      );
+      await ctx.db.patch("recoveryClaims", claim._id, {
+        reservedAmount,
+        collectedAmount,
+        outstanding,
+        sign: sign(outstanding),
+      });
+    }
+    await ctx.db.patch("recoveryReservations", operation._id, {
+      status: terminal,
+    });
+    amount = integer(amount + operation.amount);
+  }
+  await adjustTotals(ctx, group, {
+    reservedAmount: -amount,
+    collectedAmount: collect ? amount : 0,
+    outstanding: collect ? 0 : amount,
+  });
+  const pendingOperations = group.pendingOperations - operations.length;
+  if (pendingOperations < 0)
+    throw new Error("Recovery operation count does not reconcile.");
+  await ctx.db.patch("recoveryGroups", group._id, {
+    pendingOperations,
+    status: pendingOperations ? progress : terminal,
+  });
+  if (!pendingOperations) {
+    const ledger = await balance(ctx, group);
+    if (ledger.activeGroupKey === group.groupKey)
+      await ctx.db.patch("recoveryBalances", ledger._id, {
+        activeGroupKey: undefined,
+      });
+  }
+  return {
+    group: (await ctx.db.get("recoveryGroups", group._id))!,
+    isDone: pendingOperations === 0,
+  };
+}

package/src/component/costRecovery/helpers.ts

@@ -0,0 +1,83 @@
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import type { Doc } from "../_generated/dataModel.js";
+export type Scope = { accountId: string; scopeKey: string; currency: string };
+export function integer(value: number) {
+  if (!Number.isSafeInteger(value))
+    throw new Error("Recovery amounts must be safe integers.");
+  return value;
+}
+export function validateScope(scope: Scope) {
+  if (!scope.accountId || !scope.scopeKey || !/^[a-z]{3}$/.test(scope.currency))
+    throw new Error("Recovery account, scope and currency are required.");
+}
+export const sign = (value: number) =>
+  value > 0
+    ? ("positive" as const)
+    : value < 0
+      ? ("negative" as const)
+      : ("zero" as const);
+export const scopeOnly = (scope: Scope): Scope => ({
+  accountId: scope.accountId,
+  scopeKey: scope.scopeKey,
+  currency: scope.currency,
+});
+export const zeroTotals = {
+  amountDue: 0,
+  collectedAmount: 0,
+  reservedAmount: 0,
+  outstanding: 0,
+};
+export function readBalance(ctx: QueryCtx | MutationCtx, scope: Scope) {
+  return ctx.db
+    .query("recoveryBalances")
+    .withIndex("by_scope", (q) =>
+      q
+        .eq("accountId", scope.accountId)
+        .eq("scopeKey", scope.scopeKey)
+        .eq("currency", scope.currency),
+    )
+    .unique();
+}
+export async function balance(ctx: MutationCtx, scope: Scope) {
+  const found = await readBalance(ctx, scope);
+  if (found) return found;
+  const id = await ctx.db.insert("recoveryBalances", {
+    ...scopeOnly(scope),
+    ...zeroTotals,
+  });
+  return (await ctx.db.get("recoveryBalances", id))!;
+}
+export async function adjustTotals(
+  ctx: MutationCtx,
+  scope: Scope,
+  delta: Partial<typeof zeroTotals>,
+) {
+  const stored = await balance(ctx, scope);
+  const next = { ...zeroTotals };
+  for (const key of Object.keys(zeroTotals) as (keyof typeof zeroTotals)[])
+    next[key] = integer(stored[key] + (delta[key] ?? 0));
+  if (
+    next.outstanding !==
+    integer(next.amountDue - next.collectedAmount - next.reservedAmount)
+  )
+    throw new Error("Recovery totals do not reconcile.");
+  await ctx.db.patch("recoveryBalances", stored._id, next);
+}
+export function groupTarget(group: Doc<"recoveryGroups">, outstanding: number) {
+  return Math.max(
+    -group.maxCredit,
+    Math.min(group.maxDebit, integer(outstanding + group.amount)),
+  );
+}
+export async function getGroup(ctx: MutationCtx, key: string) {
+  const group = await ctx.db
+    .query("recoveryGroups")
+    .withIndex("by_key", (q) => q.eq("groupKey", key))
+    .unique();
+  if (!group) throw new Error("Recovery group is missing.");
+  return group;
+}
+export function batchLimit(limit: number, max = 100) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > max)
+    throw new Error(`Recovery batch limit must be between 1 and ${max}.`);
+}

package/src/component/costRecovery/mutations.ts

@@ -0,0 +1,43 @@
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import { recordClaim, rollbackClaim } from "./claims.js";
+import { reserveGroup, sealGroup } from "./reservations.js";
+import { finishGroup } from "./completion.js";
+import {
+  observationFields,
+  claimDoc,
+  groupDoc,
+  reservationDoc,
+  reserveArgs,
+  rollbackArgs,
+  finishArgs,
+} from "./schema.js";
+export const record = mutation({
+  args: observationFields,
+  returns: claimDoc,
+  handler: async (ctx, args) => {
+    if (args.claimKey.startsWith("rollback:"))
+      throw new Error("Rollback claim keys are reserved.");
+    return recordClaim(ctx, args);
+  },
+});
+export const rollback = mutation({
+  args: rollbackArgs,
+  returns: claimDoc,
+  handler: rollbackClaim,
+});
+export const reserve = mutation({
+  args: reserveArgs,
+  returns: v.object({ reservation: reservationDoc, group: groupDoc }),
+  handler: reserveGroup,
+});
+export const seal = mutation({
+  args: { groupKey: v.string() },
+  returns: groupDoc,
+  handler: sealGroup,
+});
+export const finish = mutation({
+  args: finishArgs,
+  returns: v.object({ group: groupDoc, isDone: v.boolean() }),
+  handler: finishGroup,
+});

package/src/component/costRecovery/queries.ts

@@ -0,0 +1,88 @@
+import { paginationOptsValidator } from "convex/server";
+import { v } from "convex/values";
+import { query } from "../_generated/server.js";
+import {
+  balanceFields,
+  claimDoc,
+  groupDoc,
+  scopeFields,
+  reservationDoc,
+} from "./schema.js";
+import {
+  readBalance,
+  scopeOnly,
+  validateScope,
+  batchLimit,
+} from "./helpers.js";
+export const balance = query({
+  args: scopeFields,
+  returns: v.object(balanceFields),
+  handler: async (ctx, args) => {
+    validateScope(args);
+    const stored = await readBalance(ctx, args);
+    return {
+      ...scopeOnly(args),
+      amountDue: stored?.amountDue ?? 0,
+      collectedAmount: stored?.collectedAmount ?? 0,
+      reservedAmount: stored?.reservedAmount ?? 0,
+      outstanding: stored?.outstanding ?? 0,
+      ...(stored?.activeGroupKey
+        ? { activeGroupKey: stored.activeGroupKey }
+        : {}),
+    };
+  },
+});
+export const listClaims = query({
+  args: { ...scopeFields, paginationOpts: paginationOptsValidator },
+  returns: v.object({
+    page: v.array(claimDoc),
+    continueCursor: v.string(),
+    isDone: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    validateScope(args);
+    batchLimit(args.paginationOpts.numItems);
+    const result = await ctx.db
+      .query("recoveryClaims")
+      .withIndex("by_scope", (q) =>
+        q
+          .eq("accountId", args.accountId)
+          .eq("scopeKey", args.scopeKey)
+          .eq("currency", args.currency),
+      )
+      .order("desc")
+      .paginate(args.paginationOpts);
+    return {
+      page: result.page,
+      continueCursor: result.continueCursor,
+      isDone: result.isDone,
+    };
+  },
+});
+export const group = query({
+  args: { groupKey: v.string() },
+  returns: v.union(groupDoc, v.null()),
+  handler: (ctx, args) =>
+    ctx.db
+      .query("recoveryGroups")
+      .withIndex("by_key", (q) => q.eq("groupKey", args.groupKey))
+      .unique(),
+});
+export const reservation = query({
+  args: { operationKey: v.string() },
+  returns: v.union(reservationDoc, v.null()),
+  handler: (ctx, args) =>
+    ctx.db
+      .query("recoveryReservations")
+      .withIndex("by_key", (q) => q.eq("operationKey", args.operationKey))
+      .unique(),
+});
+export const claim = query({
+  args: { claimKey: v.string() },
+  returns: v.union(claimDoc, v.null()),
+  handler: (ctx, args) =>
+    ctx.db
+      .query("recoveryClaims")
+      .withIndex("by_key", (q) => q.eq("claimKey", args.claimKey))
+      .unique(),
+});

package/src/component/costRecovery/reservations.ts

@@ -0,0 +1,164 @@
+import { v } from "convex/values";
+import type { MutationCtx } from "../_generated/server.js";
+import { reserveArgs } from "./schema.js";
+import {
+  balance,
+  batchLimit,
+  getGroup,
+  groupTarget,
+  integer,
+  sign,
+  validateScope,
+} from "./helpers.js";
+
+import type { Infer } from "convex/values";
+const _reserveArgs = v.object(reserveArgs);
+export async function reserveGroup(
+  ctx: MutationCtx,
+  args: Infer<typeof _reserveArgs>,
+) {
+  validateScope(args);
+  const limit = args.limit ?? 100;
+  batchLimit(limit);
+  [args.maxDebit, args.maxCredit].forEach(integer);
+  if (
+    !args.groupKey.trim() ||
+    !args.operationKey.trim() ||
+    !args.sourceId ||
+    args.maxDebit < 0 ||
+    args.maxCredit < 0
+  )
+    throw new Error("Invalid recovery operation identity or limits.");
+  if (args.sourceGross !== undefined && integer(args.sourceGross) <= 0)
+    throw new Error("Funding gross must be positive.");
+  if (
+    args.sourceProcessingFee !== undefined &&
+    integer(args.sourceProcessingFee) < 0
+  )
+    throw new Error("Funding processing fee must be nonnegative.");
+  if (
+    args.sourceKind === "settlement" &&
+    (!args.sourceGross || args.sourceProcessingFee === undefined)
+  )
+    throw new Error("Settlement recovery requires original funding gross.");
+  let group = await ctx.db
+    .query("recoveryGroups")
+    .withIndex("by_key", (q) => q.eq("groupKey", args.groupKey))
+    .unique();
+  const existing = await ctx.db
+    .query("recoveryReservations")
+    .withIndex("by_key", (q) => q.eq("operationKey", args.operationKey))
+    .unique();
+  if (group)
+    for (const key of [
+      "accountId",
+      "scopeKey",
+      "currency",
+      "sourceKind",
+      "sourceId",
+      "sourceGross",
+      "sourceProcessingFee",
+      "maxDebit",
+      "maxCredit",
+    ] as const)
+      if (group[key] !== args[key])
+        throw new Error("Recovery group identity and limits cannot change.");
+  if (existing) {
+    if (
+      existing.groupKey !== args.groupKey ||
+      existing.limit !== limit ||
+      !group
+    )
+      throw new Error("Recovery operation identity cannot change.");
+    return { reservation: existing, group };
+  }
+  const ledger = await balance(ctx, args);
+  if (ledger.activeGroupKey && ledger.activeGroupKey !== args.groupKey)
+    throw new Error("Another recovery boundary is pending.");
+  if (group && group.status !== "open")
+    throw new Error(
+      "Recovery group is sealed; replay its existing operations.",
+    );
+  if (!group) {
+    const { operationKey: _operationKey, limit: _limit, ...input } = args;
+    const id = await ctx.db.insert("recoveryGroups", {
+      ...input,
+      amount: 0,
+      pendingOperations: 0,
+      status: "open",
+    });
+    group = (await ctx.db.get("recoveryGroups", id))!;
+  }
+  const delta = integer(groupTarget(group, ledger.outstanding) - group.amount);
+  const direction = sign(delta);
+  let remaining = Math.abs(delta),
+    amount = 0;
+  const allocations: {
+    claimId: import("../_generated/dataModel.js").Id<"recoveryClaims">;
+    claimKey: string;
+    amount: number;
+  }[] = [];
+  if (direction !== "zero") {
+    const claims = await ctx.db
+      .query("recoveryClaims")
+      .withIndex("by_sign", (q) =>
+        q
+          .eq("accountId", args.accountId)
+          .eq("scopeKey", args.scopeKey)
+          .eq("currency", args.currency)
+          .eq("sign", direction),
+      )
+      .take(limit);
+    for (const claim of claims) {
+      if (!remaining) break;
+      const take =
+        Math.min(remaining, Math.abs(claim.outstanding)) * (delta < 0 ? -1 : 1);
+      const reservedAmount = integer(claim.reservedAmount + take),
+        outstanding = integer(claim.outstanding - take);
+      await ctx.db.patch("recoveryClaims", claim._id, {
+        reservedAmount,
+        outstanding,
+        sign: sign(outstanding),
+      });
+      allocations.push({
+        claimId: claim._id,
+        claimKey: claim.claimKey,
+        amount: take,
+      });
+      amount = integer(amount + take);
+      remaining -= Math.abs(take);
+    }
+  }
+  const reservationId = await ctx.db.insert("recoveryReservations", {
+    operationKey: args.operationKey,
+    groupKey: args.groupKey,
+    amount,
+    limit,
+    allocations,
+    status: allocations.length ? "reserved" : "empty",
+  });
+  if (allocations.length) {
+    await ctx.db.patch("recoveryBalances", ledger._id, {
+      reservedAmount: integer(ledger.reservedAmount + amount),
+      outstanding: integer(ledger.outstanding - amount),
+      activeGroupKey: group.groupKey,
+    });
+    await ctx.db.patch("recoveryGroups", group._id, {
+      amount: integer(group.amount + amount),
+      pendingOperations: group.pendingOperations + 1,
+    });
+  }
+  return {
+    reservation: (await ctx.db.get("recoveryReservations", reservationId))!,
+    group: (await ctx.db.get("recoveryGroups", group._id))!,
+  };
+}
+export async function sealGroup(ctx: MutationCtx, args: { groupKey: string }) {
+  const group = await getGroup(ctx, args.groupKey);
+  if (group.status !== "open") return group;
+  const ledger = await balance(ctx, group);
+  if (groupTarget(group, ledger.outstanding) !== group.amount)
+    throw new Error("Recovery needs another reservation batch before sealing.");
+  await ctx.db.patch("recoveryGroups", group._id, { status: "sealed" });
+  return (await ctx.db.get("recoveryGroups", group._id))!;
+}