@fantastic.dev/better-stripe 0.11.0 → 0.13.0

package/src/component/cost-recovery.test.ts

@@ -0,0 +1,344 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, it } from "vitest";
+import schema from "./schema.js";
+const modules = import.meta.glob("./**/*.*s");
+const m = (name: string) =>
+  makeFunctionReference<"mutation">(`costRecovery/${name}`);
+const q = (name: string) =>
+  makeFunctionReference<"query">(`costRecovery/queries:${name}`);
+const scope = { accountId: "acct_store", scopeKey: "store", currency: "usd" };
+const observation = (claimKey: string, amountDue: number, revision = 1) => ({
+  ...scope,
+  claimKey,
+  sourceChargeId: `ch_${claimKey}`,
+  sourceGross: 10000,
+  sourceProcessingFee: 320,
+  amountDue,
+  revision,
+});
+const reserve = (operationKey: string, groupKey = "group", limit = 100) => ({
+  ...scope,
+  groupKey,
+  operationKey,
+  sourceKind: "settlement" as const,
+  sourceId: "ch_funding",
+  sourceGross: 10000,
+  sourceProcessingFee: 320,
+  maxDebit: 10000,
+  maxCredit: 10000,
+  limit,
+});
+it("preserves identity, ignores stale observations and rejects conflicting replays", async () => {
+  const t = convexTest(schema, modules);
+  const first = await t.mutation(
+    m("mutations:record"),
+    observation("a", 500, 2),
+  );
+  expect(
+    await t.mutation(m("mutations:record"), observation("a", 900, 1)),
+  ).toEqual(first);
+  expect(
+    await t.mutation(m("mutations:record"), observation("a", 500, 2)),
+  ).toEqual(first);
+  await expect(
+    t.mutation(m("mutations:record"), observation("a", 800, 2)),
+  ).rejects.toThrow(/revision/);
+  await expect(
+    t.mutation(m("mutations:record"), {
+      ...observation("a", 500, 3),
+      accountId: "acct_other",
+    }),
+  ).rejects.toThrow(/identity/);
+  await expect(
+    t.mutation(m("mutations:record"), {
+      ...observation("a", 500, 3),
+      sourceProcessingFee: 0,
+    }),
+  ).rejects.toThrow(/identity/);
+});
+it("nets unseen credits and isolates currencies/scopes beyond one history page", async () => {
+  const t = convexTest(schema, modules);
+  for (let i = 0; i < 125; i++)
+    await t.mutation(m("mutations:record"), observation(`a${i}`, 10));
+  await t.mutation(m("mutations:record"), observation("credit", -1200));
+  await t.mutation(m("mutations:record"), {
+    ...observation("eur", 9000),
+    currency: "eur",
+  });
+  await t.mutation(m("mutations:record"), {
+    ...observation("other", 9000),
+    scopeKey: "other",
+  });
+  const r = await t.mutation(m("mutations:reserve"), reserve("batch-1"));
+  expect(r.reservation.amount).toBe(50);
+  expect((await t.query(q("balance"), scope)).outstanding).toBe(0);
+  const claims: unknown[] = [];
+  let cursor: string | null = null;
+  do {
+    const page: { page: unknown[]; isDone: boolean; continueCursor: string } =
+      await t.query(q("listClaims"), {
+        ...scope,
+        paginationOpts: { numItems: 20, cursor },
+      });
+    claims.push(...page.page);
+    cursor = page.isDone ? null : page.continueCursor;
+  } while (cursor);
+  expect(claims).toHaveLength(126);
+});
+it("reserves in bounded batches and seals only a fully prepared group", async () => {
+  const t = convexTest(schema, modules);
+  for (let i = 0; i < 110; i++)
+    await t.mutation(m("mutations:record"), observation(`a${i}`, 10));
+  const first = await t.mutation(m("mutations:reserve"), reserve("batch-1"));
+  expect(first.reservation.amount).toBe(1000);
+  await expect(
+    t.mutation(m("mutations:seal"), { groupKey: "group" }),
+  ).rejects.toThrow(/batch/);
+  const second = await t.mutation(m("mutations:reserve"), reserve("batch-2"));
+  expect(second.reservation.amount).toBe(100);
+  expect(
+    (await t.mutation(m("mutations:seal"), { groupKey: "group" })).amount,
+  ).toBe(1100);
+  await expect(
+    t.mutation(m("mutations:reserve"), reserve("batch-3")),
+  ).rejects.toThrow(/sealed/);
+  const partial = await t.mutation(m("mutations:finish"), {
+    groupKey: "group",
+    outcome: "collect",
+    limit: 1,
+  });
+  expect(partial.isDone).toBe(false);
+  const done = await t.mutation(m("mutations:finish"), {
+    groupKey: "group",
+    outcome: "collect",
+    limit: 1,
+  });
+  expect(done.isDone).toBe(true);
+  expect(await t.query(q("balance"), scope)).toMatchObject({
+    collectedAmount: 1100,
+    reservedAmount: 0,
+    outstanding: 0,
+  });
+  expect(
+    (
+      await t.mutation(m("mutations:finish"), {
+        groupKey: "group",
+        outcome: "collect",
+        limit: 1,
+      })
+    ).isDone,
+  ).toBe(true);
+  await expect(
+    t.mutation(m("mutations:finish"), {
+      groupKey: "group",
+      outcome: "release",
+      limit: 1,
+    }),
+  ).rejects.toThrow(/outcome/);
+});
+it("serializes provider boundaries and recovers the same reservation after a worker dies", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(m("mutations:record"), observation("a", 500));
+  const first = await t.mutation(m("mutations:reserve"), reserve("same"));
+  expect(await t.mutation(m("mutations:reserve"), reserve("same"))).toEqual(
+    first,
+  );
+  await expect(
+    t.mutation(m("mutations:reserve"), reserve("other", "other-group")),
+  ).rejects.toThrow(/pending/);
+  await t.mutation(m("mutations:seal"), { groupKey: "group" });
+  await t.mutation(m("mutations:finish"), {
+    groupKey: "group",
+    outcome: "release",
+    limit: 10,
+  });
+  expect(await t.query(q("balance"), scope)).toMatchObject({
+    outstanding: 500,
+    collectedAmount: 0,
+    reservedAmount: 0,
+  });
+  expect(
+    (await t.mutation(m("mutations:reserve"), reserve("next", "next-group")))
+      .reservation.amount,
+  ).toBe(500);
+});
+it("handles source credits while reserved without making them spendable at a different boundary", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(m("mutations:record"), observation("a", 500));
+  await t.mutation(m("mutations:reserve"), reserve("debit"));
+  await t.mutation(m("mutations:record"), observation("a", 0, 2));
+  await expect(
+    t.mutation(m("mutations:reserve"), reserve("credit", "elsewhere")),
+  ).rejects.toThrow(/pending/);
+  const credit = await t.mutation(m("mutations:reserve"), reserve("offset"));
+  expect(credit.reservation.amount).toBe(-500);
+  expect(
+    (await t.mutation(m("mutations:seal"), { groupKey: "group" })).amount,
+  ).toBe(0);
+  await t.mutation(m("mutations:finish"), {
+    groupKey: "group",
+    outcome: "collect",
+    limit: 10,
+  });
+  expect(await t.query(q("balance"), scope)).toMatchObject({
+    amountDue: 0,
+    collectedAmount: 0,
+    reservedAmount: 0,
+    outstanding: 0,
+  });
+});
+it("restores signed recovered costs proportionally when the funding sale is returned", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(m("mutations:record"), observation("a", 501));
+  await t.mutation(m("mutations:reserve"), reserve("debit"));
+  await t.mutation(m("mutations:seal"), { groupKey: "group" });
+  await t.mutation(m("mutations:finish"), {
+    groupKey: "group",
+    outcome: "collect",
+    limit: 10,
+  });
+  const rollback = { groupKey: "group", returnedPrincipal: 5000, revision: 1 };
+  expect(await t.mutation(m("mutations:rollback"), rollback)).toMatchObject({
+    amountDue: 251,
+    sourceGross: 10000,
+    sourceProcessingFee: 320,
+  });
+  await t.mutation(m("mutations:rollback"), rollback);
+  expect((await t.query(q("balance"), scope)).outstanding).toBe(251);
+  await t.mutation(m("mutations:rollback"), {
+    ...rollback,
+    returnedPrincipal: 10000,
+    revision: 2,
+  });
+  expect((await t.query(q("balance"), scope)).outstanding).toBe(501);
+  await t.mutation(m("mutations:rollback"), {
+    ...rollback,
+    returnedPrincipal: 0,
+    revision: 3,
+  });
+  expect((await t.query(q("balance"), scope)).outstanding).toBe(0);
+});
+it("permits only one concurrent external recovery boundary", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(m("mutations:record"), observation("race", 500));
+  const results = await Promise.allSettled([
+    t.mutation(m("mutations:reserve"), reserve("one", "one")),
+    t.mutation(m("mutations:reserve"), reserve("two", "two")),
+  ]);
+  expect(results.filter((r) => r.status === "fulfilled")).toHaveLength(1);
+  expect(results.filter((r) => r.status === "rejected")).toHaveLength(1);
+  expect(await t.query(q("balance"), scope)).toMatchObject({
+    reservedAmount: 500,
+    outstanding: 0,
+    collectedAmount: 0,
+  });
+});
+it("holds a credit created after sealing until the original debit is resolved", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(m("mutations:record"), observation("a", 500));
+  await t.mutation(m("mutations:reserve"), reserve("debit"));
+  await t.mutation(m("mutations:seal"), { groupKey: "group" });
+  await t.mutation(m("mutations:record"), observation("a", 0, 2));
+  await expect(
+    t.mutation(m("mutations:reserve"), reserve("credit", "credit")),
+  ).rejects.toThrow(/pending/);
+  await t.mutation(m("mutations:finish"), {
+    groupKey: "group",
+    outcome: "collect",
+  });
+  expect(await t.query(q("balance"), scope)).toMatchObject({
+    collectedAmount: 500,
+    outstanding: -500,
+  });
+  expect(
+    (await t.mutation(m("mutations:reserve"), reserve("credit", "credit")))
+      .reservation.amount,
+  ).toBe(-500);
+  await t.mutation(m("mutations:seal"), { groupKey: "credit" });
+  await t.mutation(m("mutations:finish"), {
+    groupKey: "credit",
+    outcome: "collect",
+  });
+  expect(await t.query(q("balance"), scope)).toMatchObject({
+    amountDue: 0,
+    collectedAmount: 0,
+    outstanding: 0,
+  });
+});
+it("enforces a group-wide budget across batches and rounds signed credit rollback symmetrically", async () => {
+  const t = convexTest(schema, modules);
+  for (let i = 0; i < 3; i++)
+    await t.mutation(m("mutations:record"), observation(`a${i}`, 10));
+  const opts = { ...reserve("batch1", "limited", 1), maxDebit: 15 };
+  expect(
+    (await t.mutation(m("mutations:reserve"), opts)).reservation.amount,
+  ).toBe(10);
+  expect(
+    (
+      await t.mutation(m("mutations:reserve"), {
+        ...opts,
+        operationKey: "batch2",
+      })
+    ).reservation.amount,
+  ).toBe(5);
+  await expect(
+    t.mutation(m("mutations:reserve"), { ...opts, maxDebit: 100 }),
+  ).rejects.toThrow(/identity/);
+  await t.mutation(m("mutations:seal"), { groupKey: "limited" });
+  await t.mutation(m("mutations:finish"), {
+    groupKey: "limited",
+    outcome: "collect",
+  });
+  expect((await t.query(q("balance"), scope)).outstanding).toBe(15);
+  const creditScope = { ...scope, scopeKey: "credits" };
+  await t.mutation(m("mutations:record"), {
+    ...observation("credit", -501),
+    ...creditScope,
+  });
+  await t.mutation(m("mutations:reserve"), {
+    ...reserve("credit", "credit"),
+    ...creditScope,
+  });
+  await t.mutation(m("mutations:seal"), { groupKey: "credit" });
+  await t.mutation(m("mutations:finish"), {
+    groupKey: "credit",
+    outcome: "collect",
+  });
+  expect(
+    (
+      await t.mutation(m("mutations:rollback"), {
+        groupKey: "credit",
+        returnedPrincipal: 5000,
+        revision: 1,
+      })
+    ).amountDue,
+  ).toBe(-251);
+});
+it("does not let an empty old group clear another group's lock, and reset includes new tables", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(m("mutations:reserve"), {
+    ...reserve("empty", "empty"),
+    maxDebit: 0,
+    maxCredit: 0,
+  });
+  await t.mutation(m("mutations:record"), observation("a", 100));
+  await t.mutation(m("mutations:reserve"), reserve("active", "active"));
+  await t.mutation(m("mutations:seal"), { groupKey: "empty" });
+  await t.mutation(m("mutations:finish"), {
+    groupKey: "empty",
+    outcome: "collect",
+  });
+  expect((await t.query(q("balance"), scope)).activeGroupKey).toBe("active");
+  await t.mutation(
+    makeFunctionReference<"mutation">("core/mutations:clearAllTables"),
+    {},
+  );
+  expect(await t.query(q("balance"), scope)).toMatchObject({
+    amountDue: 0,
+    collectedAmount: 0,
+    reservedAmount: 0,
+    outstanding: 0,
+  });
+});

package/src/component/costRecovery/claims.ts

@@ -0,0 +1,119 @@
+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
+      : !group.invoiceFunding)
+  )
+    throw new Error(
+      "Rollback requires a collected group with original funding economics.",
+    );
+  const funding =
+    group.sourceKind === "settlement"
+      ? {
+          sourceChargeId: group.sourceId,
+          sourceGross: group.sourceGross!,
+          sourceProcessingFee: group.sourceProcessingFee!,
+        }
+      : group.invoiceFunding!;
+  if (
+    args.returnedPrincipal < 0 ||
+    args.returnedPrincipal > funding.sourceGross
+  )
+    throw new Error("Returned principal exceeds the original funding sale.");
+  const abs = BigInt(Math.abs(group.amount)),
+    gross = BigInt(funding.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}`,
+    ...funding,
+    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}.`);
+}