@fantastic.dev/better-stripe 0.15.0 → 0.17.0

package/src/component/earnings/triggers.ts

@@ -0,0 +1,91 @@
+import { Triggers } from "convex-helpers/server/triggers";
+import {
+  customCtx,
+  customMutation,
+} from "convex-helpers/server/customFunctions";
+import type { DataModel } from "../_generated/dataModel.js";
+import {
+  mutation as rawMutation,
+  type MutationCtx,
+} from "../_generated/server.js";
+
+type Contribution = {
+  accountId: string;
+  currency: string;
+  gross: number;
+  reversed: number;
+  paidOut: number;
+  count: number;
+};
+async function adjust(
+  ctx: MutationCtx,
+  kind: "earnings" | "payouts",
+  value: Contribution,
+  sign: number,
+) {
+  const row = await ctx.db
+    .query("currencyTotals")
+    .withIndex("by_account_kind_currency", (q) =>
+      q
+        .eq("accountId", value.accountId)
+        .eq("kind", kind)
+        .eq("currency", value.currency),
+    )
+    .unique();
+  const totals = {
+    gross: (row?.gross ?? 0) + sign * value.gross,
+    reversed: (row?.reversed ?? 0) + sign * value.reversed,
+    paidOut: (row?.paidOut ?? 0) + sign * value.paidOut,
+    count: (row?.count ?? 0) + sign * value.count,
+  };
+  if (row) {
+    if (totals.count === 0) await ctx.db.delete("currencyTotals", row._id);
+    else await ctx.db.patch("currencyTotals", row._id, totals);
+  } else
+    await ctx.db.insert("currencyTotals", {
+      accountId: value.accountId,
+      currency: value.currency,
+      kind,
+      ...totals,
+    });
+}
+const triggers = new Triggers<DataModel>();
+triggers.register("transfers", async (ctx, change) => {
+  const contribution = (
+    row: NonNullable<typeof change.newDoc>,
+  ): Contribution => ({
+    accountId: row.destinationAccountId,
+    currency: row.currency,
+    gross: row.amount,
+    reversed: row.reversedAmount ?? 0,
+    paidOut: 0,
+    count: 1,
+  });
+  if (change.oldDoc?.totalsRecorded)
+    await adjust(ctx, "earnings", contribution(change.oldDoc), -1);
+  if (change.newDoc) {
+    await adjust(ctx, "earnings", contribution(change.newDoc), 1);
+    if (!change.newDoc.totalsRecorded)
+      await ctx.innerDb.patch("transfers", change.id, { totalsRecorded: true });
+  }
+});
+triggers.register("payouts", async (ctx, change) => {
+  const contribution = (
+    row: NonNullable<typeof change.newDoc>,
+  ): Contribution => ({
+    accountId: row.accountId,
+    currency: row.currency,
+    gross: 0,
+    reversed: 0,
+    paidOut: row.status === "paid" ? row.amount : 0,
+    count: 1,
+  });
+  if (change.oldDoc?.totalsRecorded)
+    await adjust(ctx, "payouts", contribution(change.oldDoc), -1);
+  if (change.newDoc) {
+    await adjust(ctx, "payouts", contribution(change.newDoc), 1);
+    if (!change.newDoc.totalsRecorded)
+      await ctx.innerDb.patch("payouts", change.id, { totalsRecorded: true });
+  }
+});
+export const mutation = customMutation(rawMutation, customCtx(triggers.wrapDB));

package/src/component/products/queries.ts

@@ -1,3 +1,9 @@
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
+import {
+  paginationOptsValidator,
+  paginationResultValidator,
+} from "convex/server";
 import { v } from "convex/values";
 
 import { query } from "../_generated/server";
@@ -147,3 +153,71 @@ export const listPricesByProduct = query({
       .collect();
   },
 });
+
+export const paginateProducts = query({
+  args: {
+    accountId: v.optional(v.string()),
+    active: v.optional(v.boolean()),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(productDocValidator),
+  handler: (ctx, args) => {
+    if (
+      !Number.isInteger(args.paginationOpts.numItems) ||
+      args.paginationOpts.numItems < 1 ||
+      args.paginationOpts.numItems > 100
+    )
+      throw new Error("Page size must be an integer from 1 to 100");
+    const { accountId, active } = args;
+    const rows = paginator(ctx.db, schema).query("products");
+    const scoped =
+      accountId !== undefined
+        ? active !== undefined
+          ? rows.withIndex("by_account_active", (q) =>
+              q.eq("accountId", accountId).eq("active", active),
+            )
+          : rows.withIndex("by_account_id", (q) => q.eq("accountId", accountId))
+        : active !== undefined
+          ? rows.withIndex("by_active", (q) => q.eq("active", active))
+          : rows;
+    return scoped.order("desc").paginate({
+      ...args.paginationOpts,
+      maximumRowsRead: 200,
+      maximumBytesRead: 1_000_000,
+    });
+  },
+});
+
+export const paginatePrices = query({
+  args: {
+    productId: v.optional(v.string()),
+    active: v.optional(v.boolean()),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(priceDocValidator),
+  handler: (ctx, args) => {
+    if (
+      !Number.isInteger(args.paginationOpts.numItems) ||
+      args.paginationOpts.numItems < 1 ||
+      args.paginationOpts.numItems > 100
+    )
+      throw new Error("Page size must be an integer from 1 to 100");
+    const { productId, active } = args;
+    const rows = paginator(ctx.db, schema).query("prices");
+    const scoped =
+      productId !== undefined
+        ? active !== undefined
+          ? rows.withIndex("by_product_active", (q) =>
+              q.eq("productId", productId).eq("active", active),
+            )
+          : rows.withIndex("by_product_id", (q) => q.eq("productId", productId))
+        : active !== undefined
+          ? rows.withIndex("by_active", (q) => q.eq("active", active))
+          : rows;
+    return scoped.order("desc").paginate({
+      ...args.paginationOpts,
+      maximumRowsRead: 200,
+      maximumBytesRead: 1_000_000,
+    });
+  },
+});

package/src/component/public.test.ts

@@ -471,7 +471,7 @@ describe("core — clearAllTables", () => {
     const result = await t.mutation(api.core.mutations.clearAllTables, {});
     const tableCount = Object.keys(schema.tables).length;
 
-    expect(result.cleared).toBe(13);
+    expect(result.cleared).toBe(15);
     expect(result.tables).toHaveLength(tableCount);
 
     for (const tableName of Object.keys(schema.tables) as TableNames[]) {

package/src/component/read-pagination.test.ts

@@ -0,0 +1,193 @@
+// @vitest-environment edge-runtime
+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");
+
+it("traverses account/status payout history beyond the cap without duplicates", async () => {
+  const t = convexTest(schema, modules);
+  for (let i = 0; i < 67; i++)
+    await t.mutation(api.connect.mutations.upsertPayout, {
+      stripePayoutId: `po_${i}`,
+      accountId: i < 57 ? "acct_a" : "acct_b",
+      status: "paid",
+      amount: i,
+      currency: "usd",
+    });
+  await t.mutation(api.connect.mutations.upsertPayout, {
+    stripePayoutId: "po_failed",
+    accountId: "acct_a",
+    status: "failed",
+    amount: 999,
+    currency: "usd",
+  });
+  const ids: string[] = [];
+  let cursor: string | null = null;
+  for (let i = 0; i < 10; i++) {
+    const result: {
+      page: { stripePayoutId: string }[];
+      isDone: boolean;
+      continueCursor: string;
+    } = await t.query(api.connect.queries.paginatePayouts, {
+      accountId: "acct_a",
+      status: "paid",
+      paginationOpts: { numItems: 10, cursor },
+    });
+    ids.push(...result.page.map((p) => p.stripePayoutId));
+    if (result.isDone) break;
+    cursor = result.continueCursor;
+  }
+  expect(ids).toEqual(Array.from({ length: 57 }, (_, i) => `po_${56 - i}`));
+  expect(new Set(ids).size).toBe(57);
+  expect(
+    await t.query(api.connect.queries.paginatePayouts, {
+      accountId: "empty",
+      paginationOpts: { numItems: 10, cursor: null },
+    }),
+  ).toMatchObject({ page: [], isDone: true });
+});
+
+it("traverses indexed product and price pages with account/product/active isolation", async () => {
+  const t = convexTest(schema, modules);
+  for (let i = 0; i < 67; i++) {
+    await t.mutation(api.products.mutations.upsertProduct, {
+      stripeProductId: `prod_${i}`,
+      accountId: i < 57 ? "acct_a" : "acct_b",
+      name: `Product ${i}`,
+      active: true,
+    });
+    await t.mutation(api.products.mutations.upsertPrice, {
+      stripePriceId: `price_${i}`,
+      productId: i < 57 ? "product_a" : "product_b",
+      stripeProductId: i < 57 ? "prod_a" : "prod_b",
+      unitAmount: i,
+      currency: "usd",
+      type: "one_time",
+      active: true,
+    });
+  }
+  for (const [ref, filters, key, prefix] of [
+    [
+      api.products.queries.paginateProducts,
+      { accountId: "acct_a", active: true },
+      "stripeProductId",
+      "prod_",
+    ],
+    [
+      api.products.queries.paginatePrices,
+      { productId: "product_a", active: true },
+      "stripePriceId",
+      "price_",
+    ],
+  ] as const) {
+    const ids: string[] = [];
+    let cursor: string | null = null;
+    for (let i = 0; i < 10; i++) {
+      const result: {
+        page: Record<string, unknown>[];
+        isDone: boolean;
+        continueCursor: string;
+      } = await t.query(ref, {
+        ...filters,
+        paginationOpts: { numItems: 10, cursor },
+      });
+      ids.push(
+        ...result.page.map((row: Record<string, unknown>) => String(row[key])),
+      );
+      if (result.isDone) break;
+      cursor = result.continueCursor;
+    }
+    expect(ids).toEqual(
+      Array.from({ length: 57 }, (_, i) => `${prefix}${56 - i}`),
+    );
+    expect(
+      await t.query(ref, {
+        ...filters,
+        active: false,
+        paginationOpts: { numItems: 10, cursor: null },
+      }),
+    ).toMatchObject({ page: [], isDone: true });
+  }
+});
+
+it("rejects invalid page bounds and preserves legacy capped readers", async () => {
+  const t = convexTest(schema, modules);
+  for (const numItems of [0, -1, 101, 1.5]) {
+    await expect(
+      t.query(api.products.queries.paginateProducts, {
+        paginationOpts: { numItems, cursor: null },
+      }),
+    ).rejects.toThrow("Page size");
+    await expect(
+      t.query(api.products.queries.paginatePrices, {
+        paginationOpts: { numItems, cursor: null },
+      }),
+    ).rejects.toThrow("Page size");
+    await expect(
+      t.query(api.connect.queries.paginatePayouts, {
+        accountId: "acct_a",
+        paginationOpts: { numItems, cursor: null },
+      }),
+    ).rejects.toThrow("Page size");
+  }
+  expect(await t.query(api.products.queries.listProducts, {})).toEqual([]);
+  expect(await t.query(api.products.queries.listPrices, {})).toEqual([]);
+  expect(await t.query(api.connect.queries.listPayouts, {})).toEqual([]);
+});
+
+it("pins reactive product boundaries and splits a grown page before read limits", async () => {
+  const t = convexTest(schema, modules);
+  for (let i = 0; i < 20; i++)
+    await t.mutation(api.products.mutations.upsertProduct, {
+      stripeProductId: `boundary_${i}`,
+      accountId: "acct_boundary",
+      name: "Boundary",
+      active: true,
+    });
+  const first = await t.query(api.products.queries.paginateProducts, {
+    accountId: "acct_boundary",
+    paginationOpts: { numItems: 10, cursor: null },
+  });
+  const second = await t.query(api.products.queries.paginateProducts, {
+    accountId: "acct_boundary",
+    paginationOpts: { numItems: 10, cursor: first.continueCursor },
+  });
+  await t.mutation(api.products.mutations.upsertProduct, {
+    stripeProductId: "new_boundary",
+    accountId: "acct_boundary",
+    name: "New",
+    active: true,
+  });
+  const pinned = await t.query(api.products.queries.paginateProducts, {
+    accountId: "acct_boundary",
+    paginationOpts: {
+      numItems: 10,
+      cursor: null,
+      endCursor: first.continueCursor,
+    },
+  });
+  expect(pinned.page).toHaveLength(11);
+  expect(
+    new Set([...pinned.page, ...second.page].map((p) => p.stripeProductId))
+      .size,
+  ).toBe(21);
+  for (let i = 0; i < 220; i++)
+    await t.mutation(api.products.mutations.upsertProduct, {
+      stripeProductId: `growth_${i}`,
+      accountId: "acct_boundary",
+      name: "Growth",
+      active: true,
+    });
+  const grown = await t.query(api.products.queries.paginateProducts, {
+    accountId: "acct_boundary",
+    paginationOpts: {
+      numItems: 10,
+      cursor: null,
+      endCursor: first.continueCursor,
+    },
+  });
+  expect(grown.page).toHaveLength(200);
+  expect(grown.pageStatus).toBe("SplitRequired");
+  expect(grown.splitCursor).toBeTruthy();
+});

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/schema.ts

@@ -1,3 +1,4 @@
+import { currencyTotalsTable } from "./earnings/schema.js";
 import {
   claimsTable,
   balancesTable,
@@ -30,6 +31,7 @@ import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 
 export default defineSchema({
+  currencyTotals: currencyTotalsTable,
   recoveryClaims: claimsTable,
   recoveryBalances: balancesTable,
   recoveryGroups: groupsTable,