@fantastic.dev/better-stripe 0.15.0 → 0.17.0

package/src/component/connect/queries.ts

@@ -1,3 +1,8 @@
+import {
+  getAccountEarnings as getAccountEarningsLegacy,
+  getAccountPayouts as getAccountPayoutsLegacy,
+} from "../earnings/legacyReads.js";
+import { currencyTotals, previewSize } from "../earnings/reads.js";
 import { v } from "convex/values";
 import { paginator } from "convex-helpers/server/pagination";
 import schema from "../schema.js";
@@ -21,9 +26,7 @@ import {
   wedgedReversalClaimValidator,
 } from "./validators";
 
-// =============================================================================
 // PAYMENT QUERIES
-// =============================================================================
 
 export const getPaymentByStripeId = query({
   args: { stripePaymentIntentId: v.string() },
@@ -38,9 +41,7 @@ export const getPaymentByStripeId = query({
   },
 });
 
-// =============================================================================
 // PAYOUT QUERIES
-// =============================================================================
 
 export const getPayout = query({
   args: { payoutId: v.id("payouts") },
@@ -111,9 +112,7 @@ export const listPayouts = query({
   },
 });
 
-// =============================================================================
 // REFUND QUERIES
-// =============================================================================
 
 export const getRefundByStripeId = query({
   args: { stripeRefundId: v.string() },
@@ -196,9 +195,7 @@ export const listRefunds = query({
   },
 });
 
-// =============================================================================
 // DISPUTE QUERIES
-// =============================================================================
 
 export const getDisputeByStripeId = query({
   args: { stripeDisputeId: v.string() },
@@ -279,9 +276,7 @@ export const listDisputes = query({
   },
 });
 
-// =============================================================================
 // TRANSFER QUERIES (ledger — BTS-12)
-// =============================================================================
 
 export const getTransferByStripeId = query({
   args: { stripeTransferId: v.string() },
@@ -366,9 +361,7 @@ export const paginateTransfersByAccount = query({
       .paginate(args.paginationOpts),
 });
 
-// =============================================================================
 // REVERSAL-CLAIM RECLAIM (BTS-74) — ops diagnostics for wedged legs
-// =============================================================================
 
 /**
  * Fetch one reversal operation's claim record (BTS-63/74) by its id, or null.
@@ -447,9 +440,7 @@ export const listWedgedReversalClaims = query({
   },
 });
 
-// =============================================================================
 // EARNINGS AGGREGATES (BTS-64)
-// =============================================================================
 //
 // The row-list queries above `.take(50)`, so summing their rows client-side
 // (as the earnings hooks did) silently understated totals for accounts with
@@ -479,27 +470,7 @@ export const getAccountEarnings = query({
     transferCount: v.number(),
     transfers: v.array(transferDocValidator),
   }),
-  handler: async (ctx, args) => {
-    const previewLimit = args.previewLimit ?? 50;
-    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")) {
-      gross += tr.amount;
-      reversed += tr.reversedAmount ?? 0;
-      transferCount += 1;
-      if (transfers.length < previewLimit) transfers.push(tr);
-    }
-
-    return { gross, reversed, transferCount, transfers };
-  },
+  handler: getAccountEarningsLegacy,
 });
 
 /**
@@ -515,20 +486,111 @@ export const getAccountPayouts = query({
     payoutCount: v.number(),
     payouts: v.array(payoutDocValidator),
   }),
-  handler: async (ctx, args) => {
-    const previewLimit = args.previewLimit ?? 50;
-    let paidOut = 0;
-    let payoutCount = 0;
-    const payouts: Doc<"payouts">[] = [];
+  handler: getAccountPayoutsLegacy,
+});
 
-    for await (const p of ctx.db
-      .query("payouts")
-      .withIndex("by_account_id", (q) => q.eq("accountId", args.accountId))) {
-      payoutCount += 1;
-      if (p.status === "paid") paidOut += p.amount;
-      if (payouts.length < previewLimit) payouts.push(p);
-    }
+/** Reactive, account-scoped history. A page is never a financial total. */
+export const paginatePayouts = query({
+  args: {
+    accountId: v.string(),
+    status: v.optional(payoutStatusValidator),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(payoutDocValidator),
+  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 rows = paginator(ctx.db, schema).query("payouts");
+    const scoped =
+      args.status === undefined
+        ? rows.withIndex("by_account_id", (q) =>
+            q.eq("accountId", args.accountId),
+          )
+        : rows.withIndex("by_account_status", (q) =>
+            q.eq("accountId", args.accountId).eq("status", args.status!),
+          );
+    return scoped.order("desc").paginate({
+      ...args.paginationOpts,
+      maximumRowsRead: 200,
+      maximumBytesRead: 1_000_000,
+    });
+  },
+});
 
-    return { paidOut, payoutCount, payouts };
+export const getAccountEarningsByCurrency = query({
+  args: {
+    destinationAccountId: v.string(),
+    previewLimit: v.optional(v.number()),
+  },
+  returns: v.object({
+    totals: v.array(
+      v.object({
+        currency: v.string(),
+        gross: v.number(),
+        reversed: v.number(),
+        net: v.number(),
+        transferCount: v.number(),
+      }),
+    ),
+    transfers: v.array(transferDocValidator),
+  }),
+  handler: async (ctx, args) => {
+    const limit = previewSize(args.previewLimit);
+    const rows = await currencyTotals(
+      ctx,
+      args.destinationAccountId,
+      "earnings",
+    );
+    const transfers = await ctx.db
+      .query("transfers")
+      .withIndex("by_destination_account_id", (q) =>
+        q.eq("destinationAccountId", args.destinationAccountId),
+      )
+      .order("desc")
+      .take(limit);
+    return {
+      totals: rows.map((r) => ({
+        currency: r.currency,
+        gross: r.gross,
+        reversed: r.reversed,
+        net: r.gross - r.reversed,
+        transferCount: r.count,
+      })),
+      transfers,
+    };
+  },
+});
+export const getAccountPayoutsByCurrency = query({
+  args: { accountId: v.string(), previewLimit: v.optional(v.number()) },
+  returns: v.object({
+    totals: v.array(
+      v.object({
+        currency: v.string(),
+        paidOut: v.number(),
+        payoutCount: v.number(),
+      }),
+    ),
+    payouts: v.array(payoutDocValidator),
+  }),
+  handler: async (ctx, args) => {
+    const limit = previewSize(args.previewLimit);
+    const rows = await currencyTotals(ctx, args.accountId, "payouts");
+    const payouts = await ctx.db
+      .query("payouts")
+      .withIndex("by_account_id", (q) => q.eq("accountId", args.accountId))
+      .order("desc")
+      .take(limit);
+    return {
+      totals: rows.map((r) => ({
+        currency: r.currency,
+        paidOut: r.paidOut,
+        payoutCount: r.count,
+      })),
+      payouts,
+    };
   },
 });

package/src/component/connect/schema.ts

@@ -1,3 +1,4 @@
+import { v } from "convex/values";
 import { defineTable } from "convex/server";
 
 import {
@@ -22,10 +23,14 @@ export const paymentsTable = defineTable(paymentFields)
 /**
  * Payouts to V2 accounts (marketplace).
  */
-export const payoutsTable = defineTable(payoutFields)
+export const payoutsTable = defineTable({
+  ...payoutFields,
+  totalsRecorded: v.optional(v.literal(true)),
+})
   .index("by_stripe_payout_id", ["stripePayoutId"])
   .index("by_account_id", ["accountId"])
   .index("by_status", ["status"])
+  .index("by_account_totals_recorded", ["accountId", "totalsRecorded"])
   .index("by_account_status", ["accountId", "status"]);
 
 /**
@@ -49,6 +54,15 @@ export const refundsTable = defineTable(refundFields)
   .index("by_account_id", ["accountId"])
   .index("by_status", ["status"])
   .index("by_account_id_and_status", ["accountId", "status"])
+  .index("by_account_id_and_stripe_payment_intent_id", [
+    "accountId",
+    "stripePaymentIntentId",
+  ])
+  .index("by_account_id_and_stripe_payment_intent_id_and_status", [
+    "accountId",
+    "stripePaymentIntentId",
+    "status",
+  ])
   .index("by_payment_intent_id_and_status", [
     "stripePaymentIntentId",
     "status",
@@ -63,6 +77,10 @@ export const transfersTable = defineTable({
   ...transferPersistedFields,
 })
   .index("by_stripe_transfer_id", ["stripeTransferId"])
+  .index("by_account_totals_recorded", [
+    "destinationAccountId",
+    "totalsRecorded",
+  ])
   .index("by_destination_account_id", ["destinationAccountId"])
   .index("by_source_charge_id", ["sourceChargeId"]);
 

package/src/component/connect/validators.ts

@@ -72,6 +72,8 @@ export const payoutFields = {
   status: payoutStatusValidator,
   arrivalDate: v.optional(v.string()),
   method: v.optional(v.string()),
+  failureCode: v.optional(v.string()),
+  failureMessage: v.optional(v.string()),
   metadata: v.optional(v.any()),
 };
 
@@ -80,6 +82,7 @@ export const payoutDocValidator = v.object({
   _id: v.id("payouts"),
   _creationTime: v.number(),
   ...payoutFields,
+  totalsRecorded: v.optional(v.literal(true)),
 });
 
 // =============================================================================
@@ -266,6 +269,7 @@ export const transferFields = {
  * redelivered base payload must not clobber an in-flight reversal claim.
  */
 export const transferPersistedFields = {
+  totalsRecorded: v.optional(v.literal(true)),
   /**
    * Reversal claim frontier (BTS-63): the highest cumulative reversal amount
    * reserved by `claimReversalSlices` before money moves. Always ≥

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"]);