@fantastic.dev/better-stripe 0.16.0 → 0.17.1

package/src/component/refund-history.test.ts

@@ -0,0 +1,198 @@
+import { convexTest } from "convex-test";
+import { afterEach, expect, it, vi } from "vitest";
+
+import { api } from "./_generated/api.js";
+import schema from "./schema.js";
+
+const modules = import.meta.glob("./**/*.*s");
+const paginate = api.refundHistory.queries.paginateRefunds;
+afterEach(() => vi.useRealTimers());
+const rows = [
+  {
+    stripeRefundId: "re_a1",
+    accountId: "acct_a",
+    stripePaymentIntentId: "pi_a",
+    status: "succeeded",
+    currency: "jpy",
+    amount: 500,
+  },
+  {
+    stripeRefundId: "re_a2",
+    accountId: "acct_a",
+    stripePaymentIntentId: "pi_a",
+    status: "pending",
+    currency: "isk",
+    amount: 500,
+  },
+  {
+    stripeRefundId: "re_a3",
+    accountId: "acct_a",
+    stripePaymentIntentId: "pi_b",
+    status: "succeeded",
+    currency: "usd",
+    amount: 100,
+  },
+  {
+    stripeRefundId: "re_b1",
+    accountId: "acct_b",
+    stripePaymentIntentId: "pi_a",
+    status: "succeeded",
+    currency: "eur",
+    amount: 200,
+  },
+  {
+    stripeRefundId: "re_b2",
+    accountId: "acct_b",
+    stripePaymentIntentId: "pi_only_b",
+    status: "failed",
+    currency: "usd",
+    amount: 300,
+  },
+] as const;
+
+async function fixture() {
+  const t = convexTest(schema, modules);
+  vi.useFakeTimers();
+  for (const [index, row] of rows.entries()) {
+    vi.setSystemTime(1800000000000 + index * 1000);
+    await t.mutation(api.connect.mutations.upsertRefund, {
+      ...row,
+      stripeChargeId: `ch_${index}`,
+    });
+  }
+  return t;
+}
+
+it("walks every original refund over bounded newest-first pages and replays a cursor", async () => {
+  const t = await fixture();
+  const first = await t.query(paginate, {
+    paginationOpts: { numItems: 2, cursor: null },
+  });
+  expect(
+    first.page.map((row: { stripeRefundId: string }) => row.stripeRefundId),
+  ).toEqual(["re_b2", "re_b1"]);
+  expect(first.isDone).toBe(false);
+  const args = {
+    paginationOpts: { numItems: 2, cursor: first.continueCursor },
+  };
+  const second = await t.query(paginate, args);
+  expect(await t.query(paginate, args)).toEqual(second);
+  const last = await t.query(paginate, {
+    paginationOpts: { numItems: 2, cursor: second.continueCursor },
+  });
+  expect(last.isDone).toBe(true);
+  expect(
+    [...first.page, ...second.page, ...last.page].map((row) => ({
+      stripeRefundId: row.stripeRefundId,
+      accountId: row.accountId,
+      stripePaymentIntentId: row.stripePaymentIntentId,
+      status: row.status,
+      currency: row.currency,
+      amount: row.amount,
+    })),
+  ).toEqual([...rows].reverse());
+  expect(last.page[0].stripeChargeId).toBe("ch_0");
+});
+
+it.each([
+  [{ accountId: "acct_a" }, ["re_a3", "re_a2", "re_a1"]],
+  [{ stripePaymentIntentId: "pi_a" }, ["re_b1", "re_a2", "re_a1"]],
+  [{ status: "succeeded" }, ["re_b1", "re_a3", "re_a1"]],
+  [{ accountId: "acct_a", status: "succeeded" }, ["re_a3", "re_a1"]],
+  [{ stripePaymentIntentId: "pi_a", status: "succeeded" }, ["re_b1", "re_a1"]],
+  [{ accountId: "acct_a", stripePaymentIntentId: "pi_a" }, ["re_a2", "re_a1"]],
+  [
+    { accountId: "acct_a", stripePaymentIntentId: "pi_a", status: "succeeded" },
+    ["re_a1"],
+  ],
+  [{ accountId: "acct_a", stripePaymentIntentId: "pi_only_b" }, []],
+  [
+    {
+      accountId: "acct_a",
+      stripePaymentIntentId: "pi_only_b",
+      status: "failed",
+    },
+    [],
+  ],
+] as const)(
+  "applies every supplied scope conjunctively: %j",
+  async (scope, expected) => {
+    const t = await fixture();
+    const result = await t.query(paginate, {
+      ...scope,
+      paginationOpts: { numItems: 100, cursor: null },
+    });
+    expect(
+      result.page.map((row: { stripeRefundId: string }) => row.stripeRefundId),
+    ).toEqual(expected);
+    expect(result.isDone).toBe(true);
+  },
+);
+
+it.each([0, -1, 1.5, 101, Number.NaN, Number.POSITIVE_INFINITY])(
+  "rejects invalid page size %s",
+  async (numItems) => {
+    const t = convexTest(schema, modules);
+    await expect(
+      t.query(paginate, { paginationOpts: { numItems, cursor: null } }),
+    ).rejects.toThrow(/page size/i);
+  },
+);
+
+it("returns a completed empty page on empty history", async () => {
+  const t = convexTest(schema, modules);
+  expect(
+    await t.query(paginate, { paginationOpts: { numItems: 1, cursor: null } }),
+  ).toMatchObject({
+    page: [],
+    isDone: true,
+    continueCursor: expect.any(String),
+  });
+});
+
+it("pins reactive refund ranges and splits growth before bounded read limits", async () => {
+  const t = await fixture();
+  const scope = { accountId: "acct_a" };
+  const first = await t.query(paginate, {
+    ...scope,
+    paginationOpts: { numItems: 2, cursor: null },
+  });
+  const second = await t.query(paginate, {
+    ...scope,
+    paginationOpts: { numItems: 2, cursor: first.continueCursor },
+  });
+  vi.setSystemTime(1800000010000);
+  await t.mutation(api.connect.mutations.upsertRefund, {
+    stripeRefundId: "re_new",
+    ...scope,
+    amount: 500,
+    currency: "jpy",
+    status: "pending",
+  });
+  const paginationOpts = {
+    numItems: 2,
+    cursor: null,
+    endCursor: first.continueCursor,
+  };
+  const pinned = await t.query(paginate, { ...scope, paginationOpts });
+  expect(pinned.page).toHaveLength(3);
+  expect(
+    new Set([...pinned.page, ...second.page].map((row) => row.stripeRefundId))
+      .size,
+  ).toBe(4);
+  for (let index = 0; index < 205; index++) {
+    vi.setSystemTime(1800000020000 + index * 1000);
+    await t.mutation(api.connect.mutations.upsertRefund, {
+      stripeRefundId: `re_growth_${index}`,
+      ...scope,
+      amount: 500,
+      currency: "jpy",
+      status: "succeeded",
+    });
+  }
+  const grown = await t.query(paginate, { ...scope, paginationOpts });
+  expect(grown.page).toHaveLength(200);
+  expect(grown.pageStatus).toBe("SplitRequired");
+  expect(grown.splitCursor).toBeTruthy();
+  expect(grown.page.every((row) => row.accountId === "acct_a")).toBe(true);
+});

package/src/component/refundHistory/queries.ts

@@ -0,0 +1,99 @@
+import {
+  paginationOptsValidator,
+  paginationResultValidator,
+} from "convex/server";
+import { v } from "convex/values";
+import { paginator } from "convex-helpers/server/pagination";
+
+import { query, type QueryCtx } from "../_generated/server.js";
+import schema from "../schema.js";
+import {
+  refundDocValidator,
+  refundStatusValidator,
+  type RefundStatus,
+} from "../connect/validators.js";
+
+/** Host-authorized scopes are conjunctive; use the package React pagination binding. */
+export const paginateRefunds = query({
+  args: {
+    accountId: v.optional(v.string()),
+    stripePaymentIntentId: v.optional(v.string()),
+    status: v.optional(refundStatusValidator),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(refundDocValidator),
+  handler: (ctx, args) => {
+    const { paginationOpts } = args;
+    if (
+      !Number.isSafeInteger(paginationOpts.numItems) ||
+      paginationOpts.numItems < 1 ||
+      paginationOpts.numItems > 100
+    )
+      throw new Error(
+        "Refund history page size must be an integer from 1 to 100",
+      );
+    return scopedRefunds(ctx, args)
+      .order("desc")
+      .paginate({
+        ...paginationOpts,
+        maximumRowsRead: 200,
+        maximumBytesRead: 1_000_000,
+      });
+  },
+});
+
+function scopedRefunds(
+  ctx: QueryCtx,
+  args: {
+    accountId?: string;
+    stripePaymentIntentId?: string;
+    status?: RefundStatus;
+  },
+) {
+  const { accountId, stripePaymentIntentId, status } = args;
+  const refunds = paginator(ctx.db, schema).query("refunds");
+  if (
+    accountId !== undefined &&
+    stripePaymentIntentId !== undefined &&
+    status === undefined
+  )
+    return refunds.withIndex(
+      "by_account_id_and_stripe_payment_intent_id",
+      (q) =>
+        q
+          .eq("accountId", accountId)
+          .eq("stripePaymentIntentId", stripePaymentIntentId),
+    );
+  if (
+    accountId !== undefined &&
+    stripePaymentIntentId !== undefined &&
+    status !== undefined
+  )
+    return refunds.withIndex(
+      "by_account_id_and_stripe_payment_intent_id_and_status",
+      (q) =>
+        q
+          .eq("accountId", accountId)
+          .eq("stripePaymentIntentId", stripePaymentIntentId)
+          .eq("status", status),
+    );
+  if (accountId !== undefined && status !== undefined)
+    return refunds.withIndex("by_account_id_and_status", (q) =>
+      q.eq("accountId", accountId).eq("status", status),
+    );
+  if (stripePaymentIntentId !== undefined && status !== undefined)
+    return refunds.withIndex("by_payment_intent_id_and_status", (q) =>
+      q.eq("stripePaymentIntentId", stripePaymentIntentId).eq("status", status),
+    );
+  if (accountId !== undefined)
+    return refunds.withIndex("by_account_id", (q) =>
+      q.eq("accountId", accountId),
+    );
+  if (stripePaymentIntentId !== undefined)
+    return refunds.withIndex("by_stripe_payment_intent_id", (q) =>
+      q.eq("stripePaymentIntentId", stripePaymentIntentId),
+    );
+  if (status !== undefined)
+    return refunds.withIndex("by_status", (q) => q.eq("status", status));
+  return refunds;
+}

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

@@ -0,0 +1,246 @@
+import { convexTest } from "convex-test";
+import { expect, it } from "vitest";
+
+import { api } from "./_generated/api.js";
+import schema from "./schema.js";
+
+const modules = import.meta.glob("./**/*.*s");
+const max = Number.MAX_SAFE_INTEGER;
+const transfer = (stripeTransferId: string, amount: number) => ({
+  stripeTransferId,
+  amount,
+  destinationAccountId: "acct_a",
+  currency: "usd",
+  status: "paid" as const,
+});
+const payout = (stripePayoutId: string, amount: number) => ({
+  stripePayoutId,
+  amount,
+  accountId: "acct_a",
+  currency: "usd",
+  status: "paid" as const,
+});
+const earnings = { destinationAccountId: "acct_a", previewLimit: 0 };
+
+it("rejects the public artifact overflow before rounding and rolls back each rejected transfer", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(
+    api.connect.mutations.upsertTransfer,
+    transfer("tr_max", max),
+  );
+  const original = await t.query(
+    api.connect.queries.getAccountEarningsByCurrency,
+    earnings,
+  );
+  for (const id of ["tr_overflow_1", "tr_overflow_2"])
+    await expect(
+      t.mutation(api.connect.mutations.upsertTransfer, transfer(id, 1)),
+    ).rejects.toThrow(/safe integer/i);
+  expect(
+    await t.query(api.connect.queries.getAccountEarningsByCurrency, earnings),
+  ).toEqual(original);
+  expect(await t.run((ctx) => ctx.db.query("transfers").take(3))).toHaveLength(
+    1,
+  );
+});
+
+it("rejects paid payout overflow without persisting the payout or changing its summary", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(api.connect.mutations.upsertPayout, payout("po_max", max));
+  await expect(
+    t.mutation(api.connect.mutations.upsertPayout, payout("po_overflow", 1)),
+  ).rejects.toThrow(/safe integer/i);
+  expect(
+    await t.query(api.connect.queries.getAccountPayoutsByCurrency, {
+      accountId: "acct_a",
+      previewLimit: 0,
+    }),
+  ).toMatchObject({ totals: [{ paidOut: max, payoutCount: 1 }] });
+  expect(await t.run((ctx) => ctx.db.query("payouts").take(2))).toHaveLength(1);
+});
+
+it.each([0.5, Number.NaN, Number.POSITIVE_INFINITY, max + 1])(
+  "rejects invalid source amounts %s, including unpaid payouts",
+  async (amount) => {
+    const t = convexTest(schema, modules);
+    await expect(
+      t.mutation(
+        api.connect.mutations.upsertTransfer,
+        transfer("tr_invalid", amount),
+      ),
+    ).rejects.toThrow(/safe integer/i);
+    await expect(
+      t.mutation(api.connect.mutations.upsertPayout, {
+        ...payout("po_invalid", amount),
+        status: "pending",
+      }),
+    ).rejects.toThrow(/safe integer/i);
+    expect(
+      await t.run((ctx) => ctx.db.query("currencyTotals").take(1)),
+    ).toEqual([]);
+  },
+);
+
+it("rolls back subtract/reapply updates that would overflow", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(
+    api.connect.mutations.upsertTransfer,
+    transfer("tr_max", max),
+  );
+  await t.mutation(
+    api.connect.mutations.upsertTransfer,
+    transfer("tr_update", 0),
+  );
+  const before = await t.run((ctx) => ctx.db.query("transfers").take(3));
+  await expect(
+    t.mutation(api.connect.mutations.upsertTransfer, transfer("tr_update", 1)),
+  ).rejects.toThrow(/safe integer/i);
+  expect(await t.run((ctx) => ctx.db.query("transfers").take(3))).toEqual(
+    before,
+  );
+  expect(
+    await t.query(api.connect.queries.getAccountEarningsByCurrency, earnings),
+  ).toMatchObject({ totals: [{ gross: max, transferCount: 2 }] });
+});
+
+it("rolls back a reversal whose cumulative summary would overflow", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(api.connect.mutations.upsertTransfer, {
+    ...transfer("tr_a", 1),
+    reversedAmount: max - 1,
+  });
+  await t.mutation(api.connect.mutations.upsertTransfer, {
+    ...transfer("tr_b", 1),
+    reversedAmount: 1,
+  });
+  const before = await t.query(
+    api.connect.queries.getAccountEarningsByCurrency,
+    earnings,
+  );
+  await expect(
+    t.mutation(api.connect.mutations.recordTransferReversal, {
+      stripeTransferId: "tr_b",
+      reversedAmount: 2,
+    }),
+  ).rejects.toThrow(/safe integer/i);
+  expect(
+    await t.query(api.connect.queries.getAccountEarningsByCurrency, earnings),
+  ).toEqual(before);
+});
+
+it.each(["earnings", "payouts"] as const)(
+  "rolls back an entire %s backfill page and source markers on unsafe totals",
+  async (kind) => {
+    const t = convexTest(schema, modules);
+    await t.run(async (ctx) => {
+      if (kind === "earnings") {
+        await ctx.db.insert("transfers", transfer("tr_legacy_max", max));
+        await ctx.db.insert("transfers", transfer("tr_legacy_overflow", 1));
+      } else {
+        await ctx.db.insert("payouts", payout("po_legacy_max", max));
+        await ctx.db.insert("payouts", payout("po_legacy_overflow", 1));
+      }
+    });
+    await expect(
+      t.mutation(api.earnings.mutations.backfillCurrencyTotals, {
+        kind,
+        cursor: null,
+      }),
+    ).rejects.toThrow(/safe integer/i);
+    expect(
+      await t.run((ctx) => ctx.db.query("currencyTotals").take(1)),
+    ).toEqual([]);
+    expect(
+      (
+        await t.run((ctx) =>
+          ctx.db.query(kind === "earnings" ? "transfers" : "payouts").take(2),
+        )
+      ).every((row) => row.totalsRecorded === undefined),
+    ).toBe(true);
+  },
+);
+
+it.each([
+  ["gross", max + 1],
+  ["reversed", 0.5],
+  ["paidOut", Number.POSITIVE_INFINITY],
+  ["count", Number.NaN],
+] as const)(
+  "rejects unsafe stored summary field %s before exposing totals",
+  async (field, value) => {
+    const t = convexTest(schema, modules);
+    await t.run((ctx) =>
+      ctx.db.insert("currencyTotals", {
+        accountId: "acct_a",
+        currency: "usd",
+        kind: "earnings",
+        gross: 100,
+        reversed: 0,
+        paidOut: 0,
+        count: 1,
+        [field]: value,
+      }),
+    );
+    await expect(
+      t.query(api.connect.queries.getAccountEarningsByCurrency, earnings),
+    ).rejects.toThrow(/safe integer/i);
+  },
+);
+
+it("checks summary counts before persisting a new source record", async () => {
+  const t = convexTest(schema, modules);
+  await t.run((ctx) =>
+    ctx.db.insert("currencyTotals", {
+      accountId: "acct_a",
+      currency: "usd",
+      kind: "earnings",
+      gross: 0,
+      reversed: 0,
+      paidOut: 0,
+      count: max,
+    }),
+  );
+  await expect(
+    t.mutation(api.connect.mutations.upsertTransfer, transfer("tr_count", 0)),
+  ).rejects.toThrow(/safe integer/i);
+  expect(await t.run((ctx) => ctx.db.query("transfers").take(1))).toEqual([]);
+});
+
+it("rejects an unsafe derived net even when both stored operands are safe integers", async () => {
+  const t = convexTest(schema, modules);
+  await t.run((ctx) =>
+    ctx.db.insert("currencyTotals", {
+      accountId: "acct_a",
+      currency: "usd",
+      kind: "earnings",
+      gross: max,
+      reversed: -1,
+      paidOut: 0,
+      count: 1,
+    }),
+  );
+  await expect(
+    t.query(api.connect.queries.getAccountEarningsByCurrency, earnings),
+  ).rejects.toThrow(/safe integer/i);
+});
+
+it("preserves supported boundary amounts through reversal and reinstatement", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(
+    api.connect.mutations.upsertTransfer,
+    transfer("tr_boundary", max - 2),
+  );
+  await t.mutation(api.connect.mutations.recordTransferReversal, {
+    stripeTransferId: "tr_boundary",
+    reversedAmount: 1,
+  });
+  await t.mutation(api.connect.mutations.upsertTransfer, {
+    ...transfer("tr_restore", 1),
+    reinstatement: true,
+  });
+  expect(
+    await t.query(api.connect.queries.getAccountEarningsByCurrency, earnings),
+  ).toMatchObject({
+    totals: [{ gross: max - 1, reversed: 1, net: max - 2, transferCount: 2 }],
+  });
+});

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

@@ -39,3 +39,24 @@ it("renders chargeback economics and explicitly handles missing charge links", (
   expect(screen.getByText("$80.00")).toBeTruthy();
   expect(screen.getByText("No transfer rows found.")).toBeTruthy();
 });
+it("distinguishes reserved recovery from money already collected", () => {
+  render(
+    <CostRecovery
+      rows={[
+        {
+          paymentIntentId: "pi_reserved",
+          amountDue: 1000,
+          collectedAmount: 400,
+          invoicedAmount: 999,
+          reservedAmount: 300,
+          outstanding: 300,
+          currency: "usd",
+        },
+      ]}
+    />,
+  );
+  expect(screen.getByText("Collected")).toBeTruthy();
+  expect(screen.getByText("Reserved")).toBeTruthy();
+  expect(screen.queryByText("$9.99")).toBeNull();
+  expect(screen.getAllByText("$3.00")).toHaveLength(2);
+});

package/src/react/workflows/Costs.tsx

@@ -10,24 +10,30 @@ export type CostRecoveryRow = {
   amountDue: number;
   collectedAmount: number;
   invoicedAmount: number;
+  reservedAmount?: number;
   outstanding: number;
   currency: string;
 };
 export function CostRecovery(props: ResourceCollectionProps<CostRecoveryRow>) {
+  const reserved = props.rows?.some((row) => row.reservedAmount !== undefined);
   const columns: WorkflowColumn<CostRecoveryRow>[] = [
     { id: "payment", label: "Payment", cell: (row) => row.paymentIntentId },
     ...(
       [
         ["amountDue", "Total cost"],
-        ["collectedAmount", "Deducted from earnings"],
-        ["invoicedAmount", "Added to invoice"],
+        ["collectedAmount", reserved ? "Collected" : "Deducted from earnings"],
+        [
+          reserved ? "reservedAmount" : "invoicedAmount",
+          reserved ? "Reserved" : "Added to invoice",
+        ],
         ["outstanding", "Outstanding"],
       ] as const
     ).map(([field, label]) => ({
       id: field,
       label,
       align: "end" as const,
-      cell: (row: CostRecoveryRow) => formatPrice(row[field], row.currency),
+      cell: (row: CostRecoveryRow) =>
+        formatPrice(row[field] ?? row.invoicedAmount, row.currency),
     })),
   ];
   return (