@fantastic.dev/better-stripe 0.14.0 → 0.16.0

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/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,

package/src/react/components/EarningsSummary.tsx

@@ -46,6 +46,8 @@ export type EarningsSummaryProps = {
     net?: string;
     paidOut?: string;
   };
+  /** Override formatting for observed currencies outside the charge formatter. */
+  formatAmount?: (amount: number, currency: string, locale?: string) => string;
   locale?: string;
   className?: string;
   children?: (props: EarningsSummaryRenderProps) => ReactNode;
@@ -70,6 +72,7 @@ export function EarningsSummary({
   noPayoutsLabel = "No payouts yet",
   labels,
   locale,
+  formatAmount = formatPrice,
   className,
   children,
 }: EarningsSummaryProps) {
@@ -93,12 +96,12 @@ export function EarningsSummary({
     ? latestPayoutLabel
         .replace(
           "{amount}",
-          formatPrice(latestPayout.amount, latestPayout.currency, locale),
+          formatAmount(latestPayout.amount, latestPayout.currency, locale),
         )
         .replace("{status}", latestPayout.status)
     : noPayoutsLabel;
 
-  const money = (amount: number) => formatPrice(amount, currency, locale);
+  const money = (amount: number) => formatAmount(amount, currency, locale);
   const renderProps: EarningsSummaryRenderProps = {
     grossLabel: money(gross),
     reversedLabel: money(reversed),

package/src/react/hooks/useConfirmPayment.test.tsx

@@ -0,0 +1,47 @@
+// @vitest-environment jsdom
+import { renderHook } from "@testing-library/react";
+import { expect, it, vi } from "vitest";
+const f = vi.hoisted(() => ({ confirmSetup: vi.fn(), submit: vi.fn() }));
+vi.mock("@stripe/react-stripe-js", () => ({
+  useStripe: () => ({ confirmSetup: f.confirmSetup }),
+  useElements: () => ({ submit: f.submit }),
+}));
+import { useConfirmPayment } from "./useConfirmPayment.js";
+it("submits Elements and confirms explicit redisplay permission only on succeeded setup", async () => {
+  f.submit.mockResolvedValue({});
+  f.confirmSetup.mockResolvedValue({ setupIntent: { status: "succeeded" } });
+  const { result } = renderHook(useConfirmPayment);
+  expect(
+    await result.current.confirmSetup("https://app.test", "always"),
+  ).toEqual({ success: true });
+  expect(f.submit).toHaveBeenCalled();
+  expect(f.confirmSetup).toHaveBeenCalledWith({
+    elements: expect.anything(),
+    confirmParams: {
+      return_url: "https://app.test",
+      payment_method_data: { allow_redisplay: "always" },
+    },
+    redirect: "if_required",
+  });
+});
+it("does not turn processing or incomplete authentication into saved-card success", async () => {
+  f.submit.mockResolvedValue({});
+  f.confirmSetup.mockResolvedValue({
+    setupIntent: { status: "requires_action" },
+  });
+  const { result } = renderHook(useConfirmPayment);
+  expect(await result.current.confirmSetup()).toEqual({
+    success: false,
+    error: "Card setup is not complete.",
+  });
+});
+it("reports validation errors before confirmation", async () => {
+  f.confirmSetup.mockClear();
+  f.submit.mockResolvedValue({ error: { message: "Invalid card" } });
+  const { result } = renderHook(useConfirmPayment);
+  expect(await result.current.confirmSetup()).toEqual({
+    success: false,
+    error: "Invalid card",
+  });
+  expect(f.confirmSetup).not.toHaveBeenCalled();
+});

package/src/react/hooks/useConfirmPayment.ts

@@ -77,15 +77,27 @@ export function useConfirmPayment() {
    * @param returnUrl - URL to redirect to after 3D Secure. Defaults to current page.
    */
   const confirmSetup = useCallback(
-    async (returnUrl?: string): Promise<StripeConfirmResult> => {
+    async (
+      returnUrl?: string,
+      allowRedisplay?: "always" | "limited" | "unspecified",
+    ): Promise<StripeConfirmResult> => {
       if (!stripe || !elements) {
         return { success: false, error: "Stripe not initialized" };
       }
 
-      const { error } = await stripe.confirmSetup({
+      const validation = await elements.submit();
+      if (validation.error)
+        return {
+          success: false,
+          error: validation.error.message ?? "Check your card details.",
+        };
+      const { error, setupIntent } = await stripe.confirmSetup({
         elements,
         confirmParams: {
           return_url: returnUrl ?? window.location.href,
+          ...(allowRedisplay
+            ? { payment_method_data: { allow_redisplay: allowRedisplay } }
+            : {}),
         },
         redirect: "if_required",
       });
@@ -96,6 +108,8 @@ export function useConfirmPayment() {
           error: error.message ?? "Failed to confirm setup",
         };
       }
+      if (setupIntent?.status !== "succeeded")
+        return { success: false, error: "Card setup is not complete." };
       return { success: true };
     },
     [stripe, elements],

package/src/react/hooks/useCurrencyEarnings.test.ts

@@ -0,0 +1,59 @@
+import { expect, it } from "vitest";
+import { createUseCurrencyEarnings } from "./useCurrencyEarnings.js";
+it("joins exact server totals by currency without summing preview rows", () => {
+  const earnings = {
+    totals: [
+      {
+        currency: "jpy",
+        gross: 1000,
+        reversed: 100,
+        net: 900,
+        transferCount: 99,
+      },
+    ],
+    transfers: [],
+  };
+  const payouts = {
+    totals: [{ currency: "usd", paidOut: 50, payoutCount: 20 }],
+    payouts: [],
+  };
+  const useEarnings = createUseCurrencyEarnings(
+    (ref) => (ref === "earnings" ? earnings : payouts),
+    "earnings",
+    "payouts",
+  );
+  expect(useEarnings("acct_a").totals).toEqual([
+    {
+      currency: "jpy",
+      gross: 1000,
+      reversed: 100,
+      net: 900,
+      transferCount: 99,
+      paidOut: 0,
+      payoutCount: 0,
+    },
+    {
+      currency: "usd",
+      gross: 0,
+      reversed: 0,
+      net: 0,
+      transferCount: 0,
+      paidOut: 50,
+      payoutCount: 20,
+    },
+  ]);
+});
+it("skips unresolved accounts and distinguishes loading from empty totals", () => {
+  const args: unknown[] = [];
+  const hook = createUseCurrencyEarnings(
+    (_ref, value) => {
+      args.push(value);
+      return undefined;
+    },
+    "earnings",
+    "payouts",
+  );
+  expect(hook(undefined)).toMatchObject({ totals: [], isLoading: false });
+  expect(args).toEqual(["skip", "skip"]);
+  expect(hook("acct_a").isLoading).toBe(true);
+});

package/src/react/hooks/useCurrencyEarnings.ts

@@ -0,0 +1,73 @@
+"use client";
+import type { EarningsTransfer } from "./useEarnings.js";
+import type { StripeComponentPayout } from "../types.js";
+export type CurrencyEarningsTotal = {
+  currency: string;
+  gross: number;
+  reversed: number;
+  net: number;
+  transferCount: number;
+};
+export type CurrencyPayoutTotal = {
+  currency: string;
+  paidOut: number;
+  payoutCount: number;
+};
+export type AccountCurrencyEarnings = {
+  totals: CurrencyEarningsTotal[];
+  transfers: EarningsTransfer[];
+};
+export type AccountCurrencyPayouts = {
+  totals: CurrencyPayoutTotal[];
+  payouts: StripeComponentPayout[];
+};
+export type UseCurrencyEarningsResult = {
+  totals: (CurrencyEarningsTotal & CurrencyPayoutTotal)[];
+  transfers: EarningsTransfer[];
+  payouts: StripeComponentPayout[];
+  isLoading: boolean;
+};
+/** Bind authorized host queries to the maintained component currency summaries. */
+export function createUseCurrencyEarnings(
+  useQuery: (ref: any, args: Record<string, unknown> | "skip") => any,
+  earningsRef: any,
+  payoutsRef: any,
+) {
+  return function useCurrencyEarnings(
+    accountId: string | undefined,
+  ): UseCurrencyEarningsResult {
+    const earnings = useQuery(
+      earningsRef,
+      accountId ? { destinationAccountId: accountId } : "skip",
+    ) as AccountCurrencyEarnings | undefined;
+    const payouts = useQuery(payoutsRef, accountId ? { accountId } : "skip") as
+      AccountCurrencyPayouts | undefined;
+    const byCurrency = new Map<
+      string,
+      CurrencyEarningsTotal & CurrencyPayoutTotal
+    >();
+    for (const row of earnings?.totals ?? [])
+      byCurrency.set(row.currency, { ...row, paidOut: 0, payoutCount: 0 });
+    for (const row of payouts?.totals ?? [])
+      byCurrency.set(row.currency, {
+        ...(byCurrency.get(row.currency) ?? {
+          currency: row.currency,
+          gross: 0,
+          reversed: 0,
+          net: 0,
+          transferCount: 0,
+        }),
+        ...row,
+      });
+    return {
+      totals: [...byCurrency.values()].sort((a, b) =>
+        a.currency.localeCompare(b.currency),
+      ),
+      transfers: earnings?.transfers ?? [],
+      payouts: payouts?.payouts ?? [],
+      isLoading:
+        accountId !== undefined &&
+        (earnings === undefined || payouts === undefined),
+    };
+  };
+}

package/src/react/index.ts

@@ -290,3 +290,18 @@ export {
   formatChargeAmount,
   type ChargeCurrencyMetadata,
 } from "../client/charge-currency.js";
+
+export { SaveCard } from "./workflows/SaveCard.js";
+export type { SaveCardProps, SaveCardFormState } from "./workflows/SaveCard.js";
+
+export { createUseCurrencyEarnings } from "./hooks/useCurrencyEarnings.js";
+export type {
+  CurrencyEarningsTotal,
+  CurrencyPayoutTotal,
+  AccountCurrencyEarnings,
+  AccountCurrencyPayouts,
+  UseCurrencyEarningsResult,
+} from "./hooks/useCurrencyEarnings.js";
+
+// Pins end cursors for the component paginator, including reactive page splits.
+export { usePaginatedQuery as useComponentPaginatedQuery } from "convex-helpers/react";

package/src/react/read-contracts.render.test.tsx

@@ -0,0 +1,20 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { expect, it } from "vitest";
+import { EarningsSummary } from "./components/EarningsSummary.js";
+it("lets currency-aware earnings consumers format three-decimal observed amounts", () => {
+  const html = renderToStaticMarkup(
+    createElement(EarningsSummary, {
+      gross: 1234,
+      reversed: 100,
+      net: 1134,
+      paidOut: 1000,
+      currency: "kwd",
+      payouts: [],
+      formatAmount: (amount: number, currency: string) =>
+        `${currency.toUpperCase()} ${(amount / 1000).toFixed(3)}`,
+    }),
+  );
+  expect(html).toContain("KWD 1.234");
+  expect(html).toContain("KWD 1.134");
+});

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

@@ -0,0 +1,127 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+const confirm = vi.hoisted(() => vi.fn());
+vi.mock("../components/StripeProvider.js", () => ({
+  StripeProvider: ({ children }: { children: React.ReactNode }) => children,
+}));
+vi.mock("@stripe/react-stripe-js", () => ({
+  PaymentElement: () => <div>Card details</div>,
+}));
+vi.mock("../hooks/useConfirmPayment.js", () => ({
+  useConfirmPayment: () => ({
+    confirmSetup: confirm,
+    isReady: true,
+    hasElements: true,
+  }),
+}));
+import { SaveCard } from "./SaveCard.js";
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+it("retries provisioning with the same logical request and requires explicit consent before confirmation", async () => {
+  const create = vi
+    .fn()
+    .mockRejectedValueOnce(new Error("offline"))
+    .mockResolvedValue({ setupIntentId: "seti_one", clientSecret: "secret" });
+  const success = vi.fn();
+  confirm.mockResolvedValue({ success: true });
+  render(
+    <SaveCard
+      publishableKey="pk_test"
+      scopeKey="buyer"
+      requestId="save-one"
+      returnUrl="https://app.test/cards"
+      createSetupIntent={create}
+      onSuccess={success}
+    />,
+  );
+  await screen.findByText("offline");
+  await userEvent.click(screen.getByRole("button", { name: "Retry" }));
+  await screen.findByText("Card details");
+  expect(create.mock.calls).toEqual([
+    [{ requestId: "save-one" }],
+    [{ requestId: "save-one" }],
+  ]);
+  await userEvent.click(screen.getByRole("button", { name: "Save card" }));
+  expect(confirm).not.toHaveBeenCalled();
+  await userEvent.click(screen.getByRole("checkbox"));
+  await userEvent.click(screen.getByRole("button", { name: "Save card" }));
+  await waitFor(() => expect(success).toHaveBeenCalledWith("seti_one"));
+  expect(confirm).toHaveBeenCalledWith("https://app.test/cards", "always");
+});
+it("keeps failed authentication retryable and does not report completion", async () => {
+  confirm
+    .mockResolvedValueOnce({ success: false, error: "Authentication failed" })
+    .mockResolvedValueOnce({ success: true });
+  const success = vi.fn();
+  render(
+    <SaveCard
+      publishableKey="pk_test"
+      scopeKey="buyer"
+      returnUrl="https://app.test/cards"
+      createSetupIntent={async () => ({
+        setupIntentId: "seti_one",
+        clientSecret: "secret",
+      })}
+      onSuccess={success}
+    />,
+  );
+  await screen.findByText("Card details");
+  await userEvent.click(screen.getByRole("checkbox"));
+  await userEvent.click(screen.getByRole("button", { name: "Save card" }));
+  await screen.findByRole("alert");
+  expect(success).not.toHaveBeenCalled();
+  await userEvent.click(screen.getByRole("button", { name: "Save card" }));
+  await waitFor(() => expect(success).toHaveBeenCalledOnce());
+});
+it("does not confirm the same completed setup twice", async () => {
+  confirm.mockResolvedValue({ success: true });
+  const success = vi.fn();
+  render(
+    <SaveCard
+      publishableKey="pk_test"
+      scopeKey="buyer"
+      returnUrl="https://app.test/cards"
+      createSetupIntent={async () => ({
+        setupIntentId: "seti_one",
+        clientSecret: "secret",
+      })}
+      onSuccess={success}
+    />,
+  );
+  await screen.findByText("Card details");
+  await userEvent.click(screen.getByRole("checkbox"));
+  await userEvent.click(screen.getByRole("button", { name: "Save card" }));
+  await waitFor(() => expect(success).toHaveBeenCalledOnce());
+  await userEvent.click(screen.getByRole("button", { name: "Save card" }));
+  expect(confirm).toHaveBeenCalledOnce();
+});
+it("blocks repeat confirmation through a custom render callback", async () => {
+  confirm.mockResolvedValue({ success: true });
+  const success = vi.fn();
+  let submit: (() => Promise<void>) | undefined;
+  render(
+    <SaveCard
+      publishableKey="pk_test"
+      scopeKey="buyer"
+      returnUrl="https://app.test/cards"
+      createSetupIntent={async () => ({
+        setupIntentId: "seti_one",
+        clientSecret: "secret",
+      })}
+      onSuccess={success}
+      renderForm={(state) => {
+        submit = state.submit;
+        return <button onClick={() => state.setConsent(true)}>Consent</button>;
+      }}
+    />,
+  );
+  await userEvent.click(await screen.findByRole("button", { name: "Consent" }));
+  await submit!();
+  await submit!();
+  expect(confirm).toHaveBeenCalledOnce();
+  expect(success).toHaveBeenCalledOnce();
+});