@fantastic.dev/better-stripe 0.14.0 → 0.16.0

package/src/component/currency-migration.test.ts

@@ -0,0 +1,119 @@
+// @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("backfills legacy rows in bounded pages, safely interleaved with updates and replay", async () => {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    for (let i = 0; i < 205; i++)
+      await ctx.db.insert("transfers", {
+        stripeTransferId: `legacy_${i}`,
+        destinationAccountId: "acct_old",
+        amount: 100,
+        currency: "usd",
+        status: "paid",
+      });
+  });
+  await expect(
+    t.query(api.connect.queries.getAccountEarningsByCurrency, {
+      destinationAccountId: "acct_old",
+    }),
+  ).rejects.toThrow("backfill");
+  let cursor: string | null = null;
+  for (let i = 0; i < 3; i++) {
+    const result: { isDone: boolean; continueCursor: string } =
+      await t.mutation(api.earnings.mutations.backfillCurrencyTotals, {
+        kind: "earnings",
+        cursor,
+      });
+    cursor = result.continueCursor;
+    if (i === 0) {
+      await t.mutation(api.connect.mutations.recordTransferReversal, {
+        stripeTransferId: "legacy_150",
+        reversedAmount: 50,
+      });
+      await expect(
+        t.query(api.connect.queries.getAccountEarningsByCurrency, {
+          destinationAccountId: "acct_old",
+        }),
+      ).rejects.toThrow("backfill");
+    }
+    expect(result.isDone).toBe(i === 2);
+  }
+  const read = () =>
+    t.query(api.connect.queries.getAccountEarningsByCurrency, {
+      destinationAccountId: "acct_old",
+      previewLimit: 0,
+    });
+  expect(await read()).toEqual({
+    totals: [
+      {
+        currency: "usd",
+        gross: 20500,
+        reversed: 50,
+        net: 20450,
+        transferCount: 205,
+      },
+    ],
+    transfers: [],
+  });
+  await t.mutation(api.earnings.mutations.backfillCurrencyTotals, {
+    kind: "earnings",
+    cursor: null,
+  });
+  expect((await read()).totals[0].gross).toBe(20500);
+});
+it("moves changed payout contributions between accounts and currencies, counting only paid rows", async () => {
+  const t = convexTest(schema, modules);
+  const args = {
+    stripePayoutId: "po_move",
+    accountId: "acct_old",
+    amount: 100,
+    currency: "usd",
+    status: "paid" as const,
+  };
+  await t.run((ctx) => ctx.db.insert("payouts", args));
+  await expect(
+    t.query(api.connect.queries.getAccountPayoutsByCurrency, {
+      accountId: "acct_old",
+    }),
+  ).rejects.toThrow("backfill");
+  await t.mutation(api.earnings.mutations.backfillCurrencyTotals, {
+    kind: "payouts",
+    cursor: null,
+  });
+  await t.mutation(api.connect.mutations.upsertPayout, {
+    ...args,
+    accountId: "acct_new",
+    currency: "jpy",
+    status: "failed",
+  });
+  expect(
+    (
+      await t.query(api.connect.queries.getAccountPayoutsByCurrency, {
+        accountId: "acct_old",
+      })
+    ).totals,
+  ).toEqual([]);
+  expect(
+    (
+      await t.query(api.connect.queries.getAccountPayoutsByCurrency, {
+        accountId: "acct_new",
+      })
+    ).totals,
+  ).toEqual([{ currency: "jpy", paidOut: 0, payoutCount: 1 }]);
+  await t.mutation(api.connect.mutations.upsertPayout, {
+    ...args,
+    accountId: "acct_new",
+    currency: "jpy",
+  });
+  expect(
+    (
+      await t.query(api.connect.queries.getAccountPayoutsByCurrency, {
+        accountId: "acct_new",
+      })
+    ).totals[0].paidOut,
+  ).toBe(100);
+});

package/src/component/currency-totals.test.ts

@@ -0,0 +1,95 @@
+// @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("keeps exact per-currency totals across previews, reversals, reinstatements and payout failures", async () => {
+  const t = convexTest(schema, modules);
+  for (let i = 0; i < 120; i++) {
+    const currency = ["usd", "eur", "jpy", "kwd"][i % 4];
+    await t.mutation(api.connect.mutations.upsertTransfer, {
+      stripeTransferId: `tr_${i}`,
+      destinationAccountId: "acct_a",
+      amount: 100,
+      currency,
+      status: "paid",
+    });
+    await t.mutation(api.connect.mutations.upsertPayout, {
+      stripePayoutId: `po_${i}`,
+      accountId: "acct_a",
+      amount: 10,
+      currency,
+      status: i < 60 ? "paid" : "failed",
+    });
+  }
+  await t.mutation(api.connect.mutations.recordTransferReversal, {
+    stripeTransferId: "tr_0",
+    reversedAmount: 40,
+  });
+  await t.mutation(api.connect.mutations.upsertTransfer, {
+    stripeTransferId: "tr_restored",
+    destinationAccountId: "acct_a",
+    amount: 40,
+    currency: "usd",
+    status: "paid",
+    reinstatement: true,
+  });
+  const earnings = await t.query(
+    api.connect.queries.getAccountEarningsByCurrency,
+    { destinationAccountId: "acct_a", previewLimit: 2 },
+  );
+  expect(earnings.transfers).toHaveLength(2);
+  expect(earnings.totals).toEqual([
+    { currency: "eur", gross: 3000, reversed: 0, net: 3000, transferCount: 30 },
+    { currency: "jpy", gross: 3000, reversed: 0, net: 3000, transferCount: 30 },
+    { currency: "kwd", gross: 3000, reversed: 0, net: 3000, transferCount: 30 },
+    {
+      currency: "usd",
+      gross: 3040,
+      reversed: 40,
+      net: 3000,
+      transferCount: 31,
+    },
+  ]);
+  const payouts = await t.query(
+    api.connect.queries.getAccountPayoutsByCurrency,
+    { accountId: "acct_a", previewLimit: 1 },
+  );
+  expect(payouts.payouts).toHaveLength(1);
+  expect(payouts.totals.map((row) => row.paidOut)).toEqual([
+    150, 150, 150, 150,
+  ]);
+  expect(
+    await t.query(api.connect.queries.getAccountEarningsByCurrency, {
+      destinationAccountId: "other",
+    }),
+  ).toEqual({ totals: [], transfers: [] });
+});
+it("refuses to add incompatible currencies in the legacy totals", async () => {
+  const t = convexTest(schema, modules);
+  for (const currency of ["usd", "eur"]) {
+    await t.mutation(api.connect.mutations.upsertTransfer, {
+      stripeTransferId: currency,
+      destinationAccountId: "acct_a",
+      amount: 1,
+      currency,
+      status: "paid",
+    });
+    await t.mutation(api.connect.mutations.upsertPayout, {
+      stripePayoutId: currency,
+      accountId: "acct_a",
+      amount: 1,
+      currency,
+      status: "paid",
+    });
+  }
+  await expect(
+    t.query(api.connect.queries.getAccountEarnings, {
+      destinationAccountId: "acct_a",
+    }),
+  ).rejects.toThrow("currency");
+  await expect(
+    t.query(api.connect.queries.getAccountPayouts, { accountId: "acct_a" }),
+  ).rejects.toThrow("currency");
+});

package/src/component/earnings/legacyReads.ts

@@ -0,0 +1,59 @@
+import type { Doc } from "../_generated/dataModel.js";
+import type { QueryCtx } from "../_generated/server.js";
+
+export async function getAccountEarnings(
+  ctx: QueryCtx,
+  args: { destinationAccountId: string; previewLimit?: number },
+) {
+  const previewLimit = args.previewLimit ?? 50;
+  let currency: string | undefined;
+  let gross = 0;
+  let reversed = 0;
+  let transferCount = 0;
+  const transfers: Doc<"transfers">[] = [];
+
+  for await (const tr of ctx.db
+    .query("transfers")
+    .withIndex("by_destination_account_id", (q) =>
+      q.eq("destinationAccountId", args.destinationAccountId),
+    )
+    .order("desc")) {
+    if (currency !== undefined && currency !== tr.currency)
+      throw new Error(
+        "Mixed currency account: use getAccountEarningsByCurrency",
+      );
+    currency = tr.currency;
+    gross += tr.amount;
+    reversed += tr.reversedAmount ?? 0;
+    transferCount += 1;
+    if (transfers.length < previewLimit) transfers.push(tr);
+  }
+
+  return { gross, reversed, transferCount, transfers };
+}
+
+export async function getAccountPayouts(
+  ctx: QueryCtx,
+  args: { accountId: string; previewLimit?: number },
+) {
+  const previewLimit = args.previewLimit ?? 50;
+  let currency: string | undefined;
+  let paidOut = 0;
+  let payoutCount = 0;
+  const payouts: Doc<"payouts">[] = [];
+
+  for await (const p of ctx.db
+    .query("payouts")
+    .withIndex("by_account_id", (q) => q.eq("accountId", args.accountId))) {
+    if (currency !== undefined && currency !== p.currency)
+      throw new Error(
+        "Mixed currency account: use getAccountPayoutsByCurrency",
+      );
+    currency = p.currency;
+    payoutCount += 1;
+    if (p.status === "paid") paidOut += p.amount;
+    if (payouts.length < previewLimit) payouts.push(p);
+  }
+
+  return { paidOut, payoutCount, payouts };
+}

package/src/component/earnings/mutations.ts

@@ -0,0 +1,21 @@
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
+import { v } from "convex/values";
+import { mutation } from "./triggers.js";
+/** Call repeatedly until isDone. Updates and backfill share one transaction. */
+export const backfillCurrencyTotals = mutation({
+  args: {
+    kind: v.union(v.literal("earnings"), v.literal("payouts")),
+    cursor: v.union(v.string(), v.null()),
+  },
+  returns: v.object({ isDone: v.boolean(), continueCursor: v.string() }),
+  handler: async (ctx, args) => {
+    const table = args.kind === "earnings" ? "transfers" : "payouts";
+    const result = await paginator(ctx.db, schema)
+      .query(table)
+      .paginate({ numItems: 100, cursor: args.cursor });
+    for (const row of result.page)
+      if (!row.totalsRecorded) await ctx.db.patch(table, row._id, {});
+    return { isDone: result.isDone, continueCursor: result.continueCursor };
+  },
+});

package/src/component/earnings/reads.ts

@@ -0,0 +1,41 @@
+import type { QueryCtx } from "../_generated/server.js";
+export function previewSize(value = 50) {
+  if (!Number.isInteger(value) || value < 0 || value > 100)
+    throw new Error("Preview size must be an integer from 0 to 100");
+  return value;
+}
+export async function currencyTotals(
+  ctx: QueryCtx,
+  accountId: string,
+  kind: "earnings" | "payouts",
+) {
+  const pending =
+    kind === "earnings"
+      ? await ctx.db
+          .query("transfers")
+          .withIndex("by_account_totals_recorded", (q) =>
+            q
+              .eq("destinationAccountId", accountId)
+              .eq("totalsRecorded", undefined),
+          )
+          .first()
+      : await ctx.db
+          .query("payouts")
+          .withIndex("by_account_totals_recorded", (q) =>
+            q.eq("accountId", accountId).eq("totalsRecorded", undefined),
+          )
+          .first();
+  if (pending)
+    throw new Error(
+      "Currency totals require backfillCurrencyTotals before reading this account",
+    );
+  const rows = await ctx.db
+    .query("currencyTotals")
+    .withIndex("by_account_kind_currency", (q) =>
+      q.eq("accountId", accountId).eq("kind", kind),
+    )
+    .take(501);
+  if (rows.length > 500)
+    throw new Error("Account exceeds supported currency count");
+  return rows;
+}

package/src/component/earnings/schema.ts

@@ -0,0 +1,11 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+export const currencyTotalsTable = defineTable({
+  accountId: v.string(),
+  currency: v.string(),
+  kind: v.union(v.literal("earnings"), v.literal("payouts")),
+  gross: v.number(),
+  reversed: v.number(),
+  paidOut: v.number(),
+  count: v.number(),
+}).index("by_account_kind_currency", ["accountId", "kind", "currency"]);

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[]) {