@fantastic.dev/better-stripe 0.4.0 → 0.6.0

package/src/client/webhooks/retry.integration.test.ts

@@ -0,0 +1,196 @@
+// @vitest-environment edge-runtime
+import { getFunctionAddress } from "convex/server";
+import Stripe from "stripe";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import schema from "../../component/schema.js";
+import { components, initConvexTest } from "../setup.test.js";
+import type { RegisterRoutesConfig } from "../types.js";
+import { handleWebhookRequest } from "./handler.js";
+
+const signingSecret = "whsec_retry_regression";
+const modules = import.meta.glob("../../component/**/*.{ts,js,tsx,jsx}");
+
+function fixture() {
+  const t = initConvexTest();
+  t.registerComponent("betterStripe", schema, modules);
+  let attempts = 0;
+  let unavailable = "";
+  const event = {
+    id: "evt_checkout_retry",
+    object: "event",
+    api_version: "2026-09-30.endive",
+    type: "checkout.session.completed",
+    livemode: false,
+    data: {
+      object: {
+        id: "cs_retry",
+        mode: "payment",
+        status: "complete",
+        payment_status: "paid",
+        metadata: { userId: "buyer", purchaseType: "communityMembership" },
+      },
+    },
+  };
+  const fulfill = async () => {
+    attempts++;
+    if (attempts === 1) throw new Error("Transient fulfillment failure");
+  };
+  const config: RegisterRoutesConfig = {
+    stripeSecretKey: "sk_test_local_signature_only",
+    webhookSecret: signingSecret,
+    retryOnHookError: (verified) => verified.type === event.type,
+    events: { [event.type]: fulfill },
+  };
+  const deliver = async (tamper = false) => {
+    const body = JSON.stringify(event);
+    const signature = await Stripe.webhooks.generateTestHeaderStringAsync({
+      payload: body,
+      secret: signingSecret,
+    });
+    return t.action(async (ctx) => {
+      const runMutation: typeof ctx.runMutation = async (ref, args) => {
+        if (
+          unavailable &&
+          getFunctionAddress(ref).reference?.endsWith(`/${unavailable}`)
+        ) {
+          throw new Error("Ledger unavailable");
+        }
+        return ctx.runMutation(ref, args);
+      };
+      const response = await handleWebhookRequest(
+        { ...ctx, runMutation },
+        new Request("https://example.test/stripe/webhook", {
+          method: "POST",
+          body: tamper ? body.replace("cs_retry", "cs_tampered") : body,
+          headers: { "stripe-signature": signature },
+        }),
+        components.betterStripe,
+        config,
+      );
+      return { status: response.status, body: await response.json() };
+    });
+  };
+  const ledger = () =>
+    t.query(components.betterStripe.webhooks.queries.getWebhookEvent, {
+      stripeEventId: event.id,
+    });
+  return {
+    t,
+    event,
+    config,
+    fulfill,
+    deliver,
+    ledger,
+    attempts: () => attempts,
+    fail: (operation: string) => {
+      unavailable = operation;
+    },
+  };
+}
+
+afterEach(() => vi.useRealTimers());
+
+describe("required V1 hooks with the real SDK signature verifier and component ledger", () => {
+  it("persists checkout before fulfillment, retries a failed hook, then deduplicates", async () => {
+    const f = fixture();
+    expect((await f.deliver()).status).toBe(500);
+    expect(await f.ledger()).toMatchObject({
+      status: "failed",
+      lastError: "Transient fulfillment failure",
+    });
+    expect(
+      await f.t.query(
+        components.betterStripe.billing.queries.getCheckoutSessionByStripeId,
+        { stripeSessionId: "cs_retry" },
+      ),
+    ).toMatchObject({ status: "complete" });
+    expect((await f.deliver()).status).toBe(200);
+    expect(await f.ledger()).toMatchObject({ status: "processed" });
+    expect(await f.deliver()).toMatchObject({
+      status: 200,
+      body: { deduplicated: true },
+    });
+    expect(f.attempts()).toBe(2);
+  });
+
+  it("requires onEvent success as well as the event-specific hook", async () => {
+    const f = fixture();
+    f.config.onEvent = f.fulfill;
+    f.config.events = { [f.event.type]: vi.fn().mockResolvedValue(undefined) };
+    expect((await f.deliver()).status).toBe(500);
+    expect(f.config.events[f.event.type]).not.toHaveBeenCalled();
+    expect((await f.deliver()).status).toBe(200);
+    expect(f.config.events[f.event.type]).toHaveBeenCalledTimes(1);
+  });
+
+  it("verifies the signature before running the selector or touching the ledger", async () => {
+    const f = fixture();
+    f.config.retryOnHookError = vi.fn(() => true);
+    expect((await f.deliver(true)).status).toBe(400);
+    expect(f.config.retryOnHookError).not.toHaveBeenCalled();
+    expect(f.attempts()).toBe(0);
+    expect(await f.ledger()).toBeNull();
+  });
+
+  it.each([undefined, () => false])(
+    "preserves best-effort hooks when the selector is %s",
+    async (selector) => {
+      const f = fixture();
+      f.config.retryOnHookError = selector;
+      expect((await f.deliver()).status).toBe(200);
+      expect(await f.ledger()).toMatchObject({ status: "processed" });
+      await f.deliver();
+      expect(f.attempts()).toBe(1);
+    },
+  );
+
+  it("returns 503 for an in-flight delivery without concurrent fulfillment", async () => {
+    const f = fixture();
+    await f.t.mutation(
+      components.betterStripe.webhooks.mutations.insertWebhookEvent,
+      {
+        stripeEventId: f.event.id,
+        eventType: f.event.type,
+        livemode: false,
+      },
+    );
+    expect((await f.deliver()).status).toBe(503);
+    expect(f.attempts()).toBe(0);
+  });
+
+  it("fails closed if reservation is unavailable", async () => {
+    const f = fixture();
+    f.fail("insertWebhookEvent");
+    expect((await f.deliver()).status).toBe(500);
+    expect(await f.ledger()).toBeNull();
+    expect(f.attempts()).toBe(0);
+  });
+
+  it.each(["markWebhookEventProcessed", "markWebhookEventFailed"])(
+    "recovers a stale reservation after %s fails",
+    async (operation) => {
+      const f = fixture();
+      if (operation === "markWebhookEventProcessed") await f.deliver();
+      f.fail(operation);
+      expect((await f.deliver()).status).toBe(500);
+      expect(await f.ledger()).toMatchObject({ status: "processing" });
+      f.fail("");
+      expect((await f.deliver()).status).toBe(503);
+      vi.useFakeTimers({ toFake: ["Date"] });
+      vi.setSystemTime(Date.now() + 11 * 60 * 1000);
+      expect((await f.deliver()).status).toBe(200);
+      expect(await f.ledger()).toMatchObject({ status: "processed" });
+    },
+  );
+
+  it("returns a retryable response when the selection policy throws", async () => {
+    const f = fixture();
+    f.config.retryOnHookError = () => {
+      throw new Error("Policy unavailable");
+    };
+    expect((await f.deliver()).status).toBe(500);
+    expect(await f.ledger()).toBeNull();
+    expect(f.attempts()).toBe(0);
+  });
+});

package/src/client/webhooks/v2.test.ts

@@ -155,6 +155,42 @@ describe("verifyV2Event", () => {
 });
 
 describe("handleV2Event — routing / early returns", () => {
+  it("resolves an account pointer without id from its URL", async () => {
+    const whCtx = makeWhCtx();
+    whCtx.stripe.v2.core.accounts.retrieve.mockResolvedValue(makeAccount());
+    expect(
+      await handleV2Event(
+        whCtx,
+        makeThinEvent({
+          related_object: {
+            type: "v2.core.account",
+            url: "/v2/core/accounts/acct_123",
+          },
+        }),
+      ),
+    ).toBe("acct_123");
+  });
+
+  it("preserves the verified notification context when refreshing account capabilities", async () => {
+    const whCtx = makeWhCtx();
+    whCtx.stripe.v2.core.accounts.retrieve.mockResolvedValue(
+      makeAccount({
+        configuration: {
+          merchant: {
+            applied: true,
+            capabilities: { card_payments: { status: "rejected" } },
+          },
+        },
+      }),
+    );
+    await handleV2Event(whCtx, makeThinEvent({ context: "org_123/acct_123" }));
+    expect(whCtx.stripe.v2.core.accounts.retrieve).toHaveBeenCalledWith(
+      "acct_123",
+      expect.objectContaining({ include: expect.any(Array) }),
+      { stripeContext: "org_123/acct_123" },
+    );
+    expect(dispatched(whCtx.ctx).data.onboardingStatus).toBe("restricted");
+  });
   it("skips and returns null for a non-account V2 event type", async () => {
     const info = vi.spyOn(console, "info").mockImplementation(() => {});
     const whCtx = makeWhCtx();

package/src/client/webhooks/v2.ts

@@ -58,7 +58,7 @@ export async function handleV2Event(
   // (type: 'v2.core.account') or a sub-resource (type: 'v2.core.account_person').
   // For sub-resources, parse the account ID from the URL (/v2/core/accounts/acct_xxx/...).
   let accountId: string;
-  if (relatedObject.type === "v2.core.account") {
+  if (relatedObject.type === "v2.core.account" && relatedObject.id) {
     accountId = relatedObject.id;
   } else if (relatedObject.url) {
     const match = relatedObject.url.match(/\/accounts\/(acct_[a-zA-Z0-9]+)/);
@@ -74,15 +74,25 @@ export async function handleV2Event(
     return null;
   }
 
-  const account = await stripe.v2.core.accounts.retrieve(accountId, {
+  const retrieveParams = {
     include: [
       "configuration.merchant",
       "configuration.recipient",
       "configuration.customer",
       "identity",
       "requirements",
-    ],
-  });
+    ] satisfies NonNullable<
+      Parameters<Stripe["v2"]["core"]["accounts"]["retrieve"]>[1]
+    >["include"],
+  };
+  // Preserve the verified notification's account/organization context when
+  // fetching the latest resource; otherwise organization keys can fetch from
+  // the wrong account. Keep the raw string in the public thin-event payload.
+  const account = thinEvent.context
+    ? await stripe.v2.core.accounts.retrieve(accountId, retrieveParams, {
+        stripeContext: thinEvent.context,
+      })
+    : await stripe.v2.core.accounts.retrieve(accountId, retrieveParams);
   const identity = account.identity;
   const metadata = (account.metadata ?? {}) as Record<string, string>;
   const { userId, orgId } = extractIdentifiers(metadata);

package/src/component/_generated/component.ts

@@ -108,6 +108,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationAccountId?: string;
             feeCollectedAmount?: number;
             feeRefundedAmount?: number;
+            isCollectionPaused?: boolean;
             isTrialing: boolean;
             metadata?: any;
             orgId?: string;
@@ -157,6 +158,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationAccountId?: string;
             feeCollectedAmount?: number;
             feeRefundedAmount?: number;
+            isCollectionPaused?: boolean;
             isTrialing: boolean;
             metadata?: any;
             orgId?: string;
@@ -307,6 +309,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationAccountId?: string;
             feeCollectedAmount?: number;
             feeRefundedAmount?: number;
+            isCollectionPaused?: boolean;
             isTrialing: boolean;
             metadata?: any;
             orgId?: string;
@@ -353,6 +356,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationAccountId?: string;
             feeCollectedAmount?: number;
             feeRefundedAmount?: number;
+            isCollectionPaused?: boolean;
             isTrialing: boolean;
             metadata?: any;
             orgId?: string;
@@ -513,6 +517,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationAccountId?: string;
             feeCollectedAmount?: number;
             feeRefundedAmount?: number;
+            isCollectionPaused?: boolean;
             isTrialing: boolean;
             metadata?: any;
             orgId?: string;
@@ -559,6 +564,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationAccountId?: string;
             feeCollectedAmount?: number;
             feeRefundedAmount?: number;
+            isCollectionPaused?: boolean;
             isTrialing: boolean;
             metadata?: any;
             orgId?: string;
@@ -605,6 +611,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationAccountId?: string;
             feeCollectedAmount?: number;
             feeRefundedAmount?: number;
+            isCollectionPaused?: boolean;
             isTrialing: boolean;
             metadata?: any;
             orgId?: string;
@@ -663,6 +670,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationAccountId?: string;
             feeCollectedAmount?: number;
             feeRefundedAmount?: number;
+            isCollectionPaused?: boolean;
             isTrialing: boolean;
             metadata?: any;
             orgId?: string;
@@ -1325,10 +1333,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             missingRequirements?: Array<string>;
             name?: string;
             onboardingStatus?:
-              | "pending"
-              | "in_progress"
-              | "complete"
-              | "restricted";
+              "pending" | "in_progress" | "complete" | "restricted";
             orgId?: string;
             requirements?: any;
             stripeAccountId: string;
@@ -1352,10 +1357,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             missingRequirements?: Array<string>;
             name?: string;
             onboardingStatus:
-              | "pending"
-              | "in_progress"
-              | "complete"
-              | "restricted";
+              "pending" | "in_progress" | "complete" | "restricted";
             orgId?: string;
             requirements?: any;
             stripeAccountId: string;
@@ -1384,10 +1386,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             missingRequirements?: Array<string>;
             name?: string;
             onboardingStatus:
-              | "pending"
-              | "in_progress"
-              | "complete"
-              | "restricted";
+              "pending" | "in_progress" | "complete" | "restricted";
             orgId?: string;
             requirements?: any;
             statementDescriptor?: string;
@@ -1414,10 +1413,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             missingRequirements?: Array<string>;
             name?: string;
             onboardingStatus:
-              | "pending"
-              | "in_progress"
-              | "complete"
-              | "restricted";
+              "pending" | "in_progress" | "complete" | "restricted";
             orgId?: string;
             requirements?: any;
             statementDescriptor?: string;
@@ -1444,10 +1440,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             missingRequirements?: Array<string>;
             name?: string;
             onboardingStatus:
-              | "pending"
-              | "in_progress"
-              | "complete"
-              | "restricted";
+              "pending" | "in_progress" | "complete" | "restricted";
             orgId?: string;
             requirements?: any;
             statementDescriptor?: string;
@@ -1474,10 +1467,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             missingRequirements?: Array<string>;
             name?: string;
             onboardingStatus:
-              | "pending"
-              | "in_progress"
-              | "complete"
-              | "restricted";
+              "pending" | "in_progress" | "complete" | "restricted";
             orgId?: string;
             requirements?: any;
             statementDescriptor?: string;
@@ -1495,10 +1485,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             isReady: boolean;
             missingRequirements: Array<string>;
             onboardingStatus:
-              | "pending"
-              | "in_progress"
-              | "complete"
-              | "restricted";
+              "pending" | "in_progress" | "complete" | "restricted";
           } | null,
           Name
         >;

package/src/component/_generated/server.ts

@@ -31,9 +31,15 @@ import {
 import type { DataModel } from "./dataModel.js";
 
 /**
- * Typesafe environment variables declared in `convex.config.ts`.
+ * Typesafe environment variables.
+ *
+ * This includes platform-provided env vars and any variables declared in
+ * `convex.config.ts`.
  */
 type Env = {
+  readonly CONVEX_CLOUD_URL: string;
+  readonly CONVEX_SITE_URL: string;
+  readonly STRIPE_PUBLISHABLE_KEY: string | undefined;
   readonly STRIPE_SECRET_KEY: string;
 };
 
@@ -113,7 +119,8 @@ export const internalAction: ActionBuilder<DataModel, "internal"> =
  * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
  */
 export const httpAction: HttpActionBuilder = httpActionGeneric;
-export const env: Env = process.env as unknown as Env;
+export const env: Env = (globalThis as unknown as { process: { env: Env } })
+  .process.env;
 
 /**
  * A set of services for use within Convex query functions.

package/src/component/billing/mutations.ts

@@ -25,6 +25,7 @@ export const upsertSubscription = mutation({
     currentPeriodStart: v.optional(v.string()),
     currentPeriodEnd: v.optional(v.string()),
     cancelAtPeriodEnd: v.boolean(),
+    isCollectionPaused: v.optional(v.boolean()),
     canceledAt: v.optional(v.string()),
     isTrialing: v.boolean(),
     trialStart: v.optional(v.string()),

package/src/component/billing/validators.ts

@@ -46,6 +46,7 @@ export const subscriptionFields = {
   currentPeriodStart: v.optional(v.string()),
   currentPeriodEnd: v.optional(v.string()),
   cancelAtPeriodEnd: v.boolean(),
+  isCollectionPaused: v.optional(v.boolean()),
   canceledAt: v.optional(v.string()),
   isTrialing: v.boolean(),
   trialStart: v.optional(v.string()),

package/src/component/config-queries.test.ts

@@ -7,10 +7,7 @@ import schema from "./schema.js";
 
 const modules = import.meta.glob("./**/*.*s");
 
-// These queries read the component's Stripe env vars. `STRIPE_SECRET_KEY` is
-// declared (required) in `convex.config.ts`; `STRIPE_PUBLISHABLE_KEY` is
-// intentionally NOT declared (it is a frontend-only value), so the component
-// never receives it and `getPublishableKey` always resolves to null.
+// Both keys are declared in the component environment and passed by the app.
 describe("core/queries — Stripe config from declared env", () => {
   const originalSecret = process.env.STRIPE_SECRET_KEY;
   const originalPublishable = process.env.STRIPE_PUBLISHABLE_KEY;
@@ -44,4 +41,11 @@ describe("core/queries — Stripe config from declared env", () => {
     const t = convexTest(schema, modules);
     expect(await t.query(api.core.queries.getPublishableKey, {})).toBeNull();
   });
+  it("getPublishableKey: returns the configured test publishable key", async () => {
+    process.env.STRIPE_PUBLISHABLE_KEY = "pk_test_abc123";
+    const t = convexTest(schema, modules);
+    expect(await t.query(api.core.queries.getPublishableKey, {})).toBe(
+      "pk_test_abc123",
+    );
+  });
 });

package/src/component/connect/queries.ts

@@ -339,9 +339,6 @@ export const listTransfersByAccount = query({
 // REVERSAL-CLAIM RECLAIM (BTS-74) — ops diagnostics for wedged legs
 // =============================================================================
 
-/** Page size for the wedged-claim scan. */
-const RECLAIM_PAGE_SIZE = 200;
-
 /**
  * Fetch one reversal operation's claim record (BTS-63/74) by its id, or null.
  * The `_creationTime` lets the reclaim path age-gate a release against Stripe's
@@ -367,7 +364,7 @@ export const getReversalOp = query({
  * successor. For each wedged leg, returns the recorded ops holding an
  * unexecuted slice on it (the blockers ops must reclaim).
  *
- * An admin/ops diagnostic, not a hot path. It paginates the `transfers` and
+ * An admin/ops diagnostic, not a hot path. It iterates the `transfers` and
  * `transferReversalOps` tables to completion, so it is exact up to Convex's
  * per-query document-read limit (16,384) — beyond which it throws (loud) rather
  * than silently truncating, matching the BTS-64 aggregate convention.
@@ -378,18 +375,10 @@ export const listWedgedReversalClaims = query({
   handler: async (ctx) => {
     // Collect the wedged legs first.
     const wedged: Doc<"transfers">[] = [];
-    let cursor: string | null = null;
-    for (;;) {
-      const page = await ctx.db
-        .query("transfers")
-        .paginate({ cursor, numItems: RECLAIM_PAGE_SIZE });
-      for (const tr of page.page) {
-        if ((tr.reversalClaimedAmount ?? 0) > (tr.reversedAmount ?? 0)) {
-          wedged.push(tr);
-        }
+    for await (const tr of ctx.db.query("transfers")) {
+      if ((tr.reversalClaimedAmount ?? 0) > (tr.reversedAmount ?? 0)) {
+        wedged.push(tr);
       }
-      if (page.isDone) break;
-      cursor = page.continueCursor;
     }
     if (wedged.length === 0) return [];
 
@@ -404,22 +393,14 @@ export const listWedgedReversalClaims = query({
       string,
       { operationId: string; from: number; to: number }[]
     >();
-    cursor = null;
-    for (;;) {
-      const page = await ctx.db
-        .query("transferReversalOps")
-        .paginate({ cursor, numItems: RECLAIM_PAGE_SIZE });
-      for (const op of page.page) {
-        for (const s of op.slices) {
-          if (!wedgedIds.has(s.stripeTransferId)) continue;
-          if (s.to <= (confirmedById.get(s.stripeTransferId) ?? 0)) continue;
-          const list = blockersByLeg.get(s.stripeTransferId) ?? [];
-          list.push({ operationId: op.operationId, from: s.from, to: s.to });
-          blockersByLeg.set(s.stripeTransferId, list);
-        }
+    for await (const op of ctx.db.query("transferReversalOps")) {
+      for (const s of op.slices) {
+        if (!wedgedIds.has(s.stripeTransferId)) continue;
+        if (s.to <= (confirmedById.get(s.stripeTransferId) ?? 0)) continue;
+        const list = blockersByLeg.get(s.stripeTransferId) ?? [];
+        list.push({ operationId: op.operationId, from: s.from, to: s.to });
+        blockersByLeg.set(s.stripeTransferId, list);
       }
-      if (page.isDone) break;
-      cursor = page.continueCursor;
     }
 
     return wedged.map((t) => ({
@@ -441,20 +422,18 @@ export const listWedgedReversalClaims = query({
 //
 // The row-list queries above `.take(50)`, so summing their rows client-side
 // (as the earnings hooks did) silently understated totals for accounts with
-// more than 50 transfers/payouts. These aggregates paginate the account's
+// more than 50 transfers/payouts. These aggregates iterate the account's
 // ledger to completion and return EXACT totals regardless of row count, plus a
 // bounded preview of rows for drill-down UIs. Exact up to Convex's per-query
-// document-read limit (a single query may scan at most 16,384 documents);
+// document/byte read limits (currently 32,000 documents or 16 MiB; see
+// https://docs.convex.dev/production/state/limits);
 // beyond that the query throws (loud) rather than silently truncating —
 // strictly safer than a fixed cap for financial figures.
 
-/** Page size for the internal pagination loops. */
-const EARNINGS_PAGE_SIZE = 200;
-
 /**
  * Exact earnings totals for one connected account (BTS-64): `gross` (sum of all
  * transfer amounts, incl. reinstatements — the earnings view) and `reversed`
- * (sum of all `reversedAmount`), paginated to completion so totals are never
+ * (sum of all `reversedAmount`), iterated to completion so totals are never
  * capped. `transfers` is a bounded preview (`previewLimit ?? 50` rows) for
  * drill-down; use `gross`/`reversed`/`transferCount` for the money figures.
  */
@@ -476,22 +455,15 @@ export const getAccountEarnings = query({
     let transferCount = 0;
     const transfers: Doc<"transfers">[] = [];
 
-    let cursor: string | null = null;
-    for (;;) {
-      const page = await ctx.db
-        .query("transfers")
-        .withIndex("by_destination_account_id", (q) =>
-          q.eq("destinationAccountId", args.destinationAccountId),
-        )
-        .paginate({ cursor, numItems: EARNINGS_PAGE_SIZE });
-      for (const tr of page.page) {
-        gross += tr.amount;
-        reversed += tr.reversedAmount ?? 0;
-        transferCount += 1;
-        if (transfers.length < previewLimit) transfers.push(tr);
-      }
-      if (page.isDone) break;
-      cursor = page.continueCursor;
+    for await (const tr of ctx.db
+      .query("transfers")
+      .withIndex("by_destination_account_id", (q) =>
+        q.eq("destinationAccountId", args.destinationAccountId),
+      )) {
+      gross += tr.amount;
+      reversed += tr.reversedAmount ?? 0;
+      transferCount += 1;
+      if (transfers.length < previewLimit) transfers.push(tr);
     }
 
     return { gross, reversed, transferCount, transfers };
@@ -500,7 +472,7 @@ export const getAccountEarnings = query({
 
 /**
  * Exact payout totals for one connected account (BTS-64): `paidOut` (sum of all
- * `paid` payout amounts), paginated to completion so it is never capped.
+ * `paid` payout amounts), iterated to completion so it is never capped.
  * `payouts` is a bounded preview (`previewLimit ?? 50` rows) for drill-down; use
  * `paidOut`/`payoutCount` for the money figures.
  */
@@ -517,19 +489,12 @@ export const getAccountPayouts = query({
     let payoutCount = 0;
     const payouts: Doc<"payouts">[] = [];
 
-    let cursor: string | null = null;
-    for (;;) {
-      const page = await ctx.db
-        .query("payouts")
-        .withIndex("by_account_id", (q) => q.eq("accountId", args.accountId))
-        .paginate({ cursor, numItems: EARNINGS_PAGE_SIZE });
-      for (const p of page.page) {
-        payoutCount += 1;
-        if (p.status === "paid") paidOut += p.amount;
-        if (payouts.length < previewLimit) payouts.push(p);
-      }
-      if (page.isDone) break;
-      cursor = page.continueCursor;
+    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);
     }
 
     return { paidOut, payoutCount, payouts };

package/src/component/convex.config.ts

@@ -3,7 +3,7 @@ import { v } from "convex/values";
 
 const component = defineComponent("betterStripe", {
   env: {
-    // The only env var the component itself reads (core/queries.ts: getStripeMode).
+    // Server-side credentials used by core/queries.ts: getStripeMode.
     // Declared as required so Convex validates its presence at push time; the
     // installing app wires it in via
     // `app.use(betterStripe, { env: { STRIPE_SECRET_KEY: app.env.STRIPE_SECRET_KEY } })`.
@@ -12,6 +12,7 @@ const component = defineComponent("betterStripe", {
     // here: they are read by the app layer (registerRoutes) directly from the
     // deployment env, never by the component.
     STRIPE_SECRET_KEY: v.string(),
+    STRIPE_PUBLISHABLE_KEY: v.optional(v.string()),
   },
 });
 export default component;