@fantastic.dev/better-stripe 0.7.0 → 0.8.0

package/src/react/workflows/Onboarding.tsx

@@ -0,0 +1,171 @@
+"use client";
+import { useId, useState, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { Connect, type ConnectProps } from "./Connect.js";
+import { AccountOnboardingCard } from "../components/AccountOnboardingCard.js";
+export const DEFAULT_CONNECT_COUNTRIES = [
+  { code: "US", name: "United States" },
+  { code: "GB", name: "United Kingdom" },
+  { code: "AU", name: "Australia" },
+  { code: "CA", name: "Canada" },
+  { code: "DE", name: "Germany" },
+  { code: "FR", name: "France" },
+  { code: "JP", name: "Japan" },
+  { code: "SG", name: "Singapore" },
+];
+export type OnboardingActions = {
+  scopeKey: string;
+  initialCountry?: string;
+  createAccount: (country: string) => Promise<{ onboardingUrl?: string }>;
+  continueOnboarding: () => Promise<{ url?: string }>;
+  closeAccount?: () => Promise<unknown>;
+  onNavigate?: (url: string) => void;
+};
+export function useOnboarding(props: OnboardingActions) {
+  const [fields, setFields] = useState({
+    scope: props.scopeKey,
+    country: props.initialCountry ?? "US",
+  });
+  if (fields.scope !== props.scopeKey)
+    setFields({ scope: props.scopeKey, country: props.initialCountry ?? "US" });
+  const [operation, setOperation] = useState<"create" | "link" | "close">(
+    "create",
+  );
+  const action = useWorkflowAction(
+    async (type: "create" | "link" | "close") => {
+      setOperation(type);
+      if (type === "close") {
+        if (!props.closeAccount)
+          throw new Error("Account closing is not configured.");
+        await props.closeAccount();
+        return true;
+      }
+      const result =
+        type === "create"
+          ? await props.createAccount(fields.country)
+          : await props.continueOnboarding();
+      const url =
+        "onboardingUrl" in result
+          ? result.onboardingUrl
+          : "url" in result
+            ? result.url
+            : undefined;
+      if (!url) throw new Error("Stripe did not return an onboarding URL.");
+      (props.onNavigate ?? ((url) => window.location.assign(url)))(url);
+      return true;
+    },
+    props.scopeKey,
+  );
+  const run = action.run;
+  return {
+    selectedCountry: fields.country,
+    setSelectedCountry: (country: string) =>
+      setFields((previous) => ({ ...previous, country })),
+    isPending: action.isPending,
+    isCreating: action.isPending && operation === "create",
+    isLinking: action.isPending && operation === "link",
+    isRestarting: action.isPending && operation === "close",
+    error: action.error,
+    createError: operation === "create" ? action.error : null,
+    linkError: operation === "link" ? action.error : null,
+    restartError: operation === "close" ? action.error : null,
+    create: () => run("create"),
+    continue: () => run("link"),
+    close: () => run("close"),
+  };
+}
+export type OnboardingAccount = {
+  stripeAccountId: string;
+  onboardingStatus?: string;
+  missingRequirements?: string[];
+  email?: string;
+  country?: string;
+};
+export type OnboardingRenderProps = ReturnType<typeof useOnboarding> & {
+  account: OnboardingAccount | null | undefined;
+};
+export type OnboardingProps =
+  | (OnboardingActions & {
+      presentation?: "headless";
+      account: OnboardingAccount | null | undefined;
+      countries?: { code: string; name: string }[];
+      children?: (state: OnboardingRenderProps) => ReactNode;
+    })
+  | (Omit<ConnectProps, "component"> & { presentation: "embedded" });
+export function Onboarding(props: OnboardingProps) {
+  return props.presentation === "embedded" ? (
+    <Connect {...props} component="onboarding" />
+  ) : (
+    <OnboardingBody key={props.scopeKey} {...props} />
+  );
+}
+function OnboardingBody(props: Extract<OnboardingProps, { account: unknown }>) {
+  const state = useOnboarding(props);
+  const id = useId();
+  if (props.children)
+    return <>{props.children({ ...state, account: props.account })}</>;
+  if (props.account === undefined) return <p role="status">Loading account…</p>;
+  const status = props.account?.onboardingStatus;
+  const normalized =
+    status === "complete" || status === "in_progress" || status === "restricted"
+      ? status
+      : "pending";
+  return (
+    <section data-better-stripe="onboarding" aria-busy={state.isPending}>
+      <h2>Account setup</h2>
+      {state.error && <p role="alert">{state.error}</p>}
+      {!props.account ? (
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            void state.create();
+          }}
+        >
+          <label htmlFor={id}>Country</label>
+          <select
+            id={id}
+            required
+            value={state.selectedCountry}
+            onChange={(event) => state.setSelectedCountry(event.target.value)}
+          >
+            {(props.countries ?? DEFAULT_CONNECT_COUNTRIES).map((country) => (
+              <option key={country.code} value={country.code}>
+                {country.name}
+              </option>
+            ))}
+          </select>
+          <button type="submit" disabled={state.isPending}>
+            {state.isCreating ? "Creating account…" : "Create account"}
+          </button>
+        </form>
+      ) : (
+        <>
+          <p>{props.account.stripeAccountId}</p>
+          <AccountOnboardingCard
+            status={normalized}
+            missingRequirements={props.account.missingRequirements}
+            onContinue={() => {
+              void state.continue();
+            }}
+            isLoading={state.isPending}
+          />
+          {props.closeAccount && (
+            <details>
+              <summary>Close account</summary>
+              <p>Closing a Stripe account is irreversible.</p>
+              <button
+                type="button"
+                disabled={state.isPending}
+                onClick={() => {
+                  void state.close();
+                }}
+              >
+                {state.isRestarting ? "Closing…" : "Close account"}
+              </button>
+            </details>
+          )}
+        </>
+      )}
+    </section>
+  );
+}

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

@@ -0,0 +1,57 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, expect, it } from "vitest";
+import { Overview, getPayoutTotals } from "./Overview.js";
+afterEach(cleanup);
+it("does not claim live totals until both datasets have loaded", () => {
+  const { rerender } = render(
+    <Overview products={undefined} subscriptions={[]} />,
+  );
+  expect(screen.getAllByText("Loading…").length).toBeGreaterThan(0);
+  rerender(
+    <Overview
+      products={[{}]}
+      subscriptions={[{ status: "active" }, { status: "canceled" }]}
+    />,
+  );
+  expect(screen.getByText("Total Subscriptions")).toBeTruthy();
+  expect(screen.getByText("2")).toBeTruthy();
+});
+it("does not combine payouts in different currencies", () => {
+  const result = getPayoutTotals(
+    [
+      { amount: 100, status: "paid", currency: "usd" },
+      { amount: 900, status: "paid", currency: "eur" },
+      { amount: 200, status: "in_transit", currency: "usd" },
+    ],
+    "usd",
+  );
+  expect(result.totalPayouts).toBe(100);
+  expect(result.pendingBalance).toBe(200);
+  expect(result.totalEarned).toBe(300);
+});
+it("renders payout activity separately from Stripe account balances", async () => {
+  const { PayoutOverview } = await import("./Overview.js");
+  render(
+    <PayoutOverview
+      currency="usd"
+      payouts={[
+        {
+          stripePayoutId: "po_one",
+          amount: 1000,
+          status: "paid",
+          currency: "usd",
+        },
+        {
+          stripePayoutId: "po_two",
+          amount: 200,
+          status: "pending",
+          currency: "usd",
+        },
+      ]}
+    />,
+  );
+  expect(screen.getByText("Upcoming payouts")).toBeTruthy();
+  expect(screen.getByText("$2.00")).toBeTruthy();
+  expect(screen.queryByText("Pending Balance")).toBeNull();
+});

package/src/react/workflows/Overview.tsx

@@ -0,0 +1,123 @@
+"use client";
+import { formatPrice } from "../lib/price-helpers.js";
+import type { ReactNode } from "react";
+export type OverviewState = {
+  isLoading: boolean;
+  totalProducts: number;
+  totalSubscriptions: number;
+  activeSubscriptions: number;
+  metrics: { label: string; value: number | string }[];
+};
+export type OverviewProps = {
+  products: unknown[] | undefined;
+  subscriptions: { status: string }[] | undefined;
+  children?: (state: OverviewState) => ReactNode;
+};
+export function Overview({ products, subscriptions, children }: OverviewProps) {
+  const isLoading = products === undefined || subscriptions === undefined;
+  const totalProducts = products?.length ?? 0;
+  const totalSubscriptions = subscriptions?.length ?? 0;
+  const activeSubscriptions =
+    subscriptions?.filter((row) => row.status === "active").length ?? 0;
+  const state = {
+    isLoading,
+    totalProducts,
+    totalSubscriptions,
+    activeSubscriptions,
+    metrics: [
+      { label: "Total Subscriptions", value: totalSubscriptions },
+      { label: "Active Subscriptions", value: activeSubscriptions },
+      { label: "Total Products", value: totalProducts },
+      { label: "Data Status", value: isLoading ? "Loading…" : "Live" },
+    ],
+  };
+  if (children) return <>{children(state)}</>;
+  return (
+    <section data-better-stripe="overview">
+      <h2>Overview</h2>
+      <dl>
+        {state.metrics.map((metric) => (
+          <div key={metric.label}>
+            <dt>{metric.label}</dt>
+            <dd>{isLoading ? "Loading…" : metric.value}</dd>
+          </div>
+        ))}
+      </dl>
+    </section>
+  );
+}
+/** Totals for one currency only. Upcoming payout amounts are not an account's available/pending Stripe balance. */
+export function getPayoutTotals<
+  T extends { amount?: number; status: string; currency: string },
+>(payouts: T[] | undefined, currency: string) {
+  const rows = payouts?.filter((row) => row.currency === currency) ?? [];
+  const totalPayouts = rows
+    .filter((row) => row.status === "paid")
+    .reduce((sum, row) => sum + (row.amount ?? 0), 0);
+  const pendingBalance = rows
+    .filter((row) => row.status === "pending" || row.status === "in_transit")
+    .reduce((sum, row) => sum + (row.amount ?? 0), 0);
+  return {
+    totalPayouts,
+    pendingBalance,
+    totalEarned: totalPayouts + pendingBalance,
+    recentPayouts: rows.slice(0, 3),
+  };
+}
+
+export type PayoutOverviewRow = {
+  stripePayoutId: string;
+  amount?: number;
+  currency: string;
+  status: string;
+  arrivalDate?: string | null;
+};
+export type PayoutOverviewProps<
+  Row extends PayoutOverviewRow = PayoutOverviewRow,
+> = {
+  payouts: Row[] | undefined;
+  currency: string;
+  children?: (
+    state: ReturnType<typeof getPayoutTotals<Row>> & {
+      isLoading: boolean;
+      metrics: { label: string; value: string }[];
+    },
+  ) => ReactNode;
+};
+/** Payout activity totals. These amounts are not the available or pending account balance. */
+export function PayoutOverview<Row extends PayoutOverviewRow>({
+  payouts,
+  currency,
+  children,
+}: PayoutOverviewProps<Row>) {
+  const totals = getPayoutTotals(payouts, currency);
+  const state = {
+    ...totals,
+    isLoading: payouts === undefined,
+    metrics: [
+      {
+        label: "Total payouts tracked",
+        value: formatPrice(totals.totalEarned, currency),
+      },
+      {
+        label: "Upcoming payouts",
+        value: formatPrice(totals.pendingBalance, currency),
+      },
+      { label: "Paid out", value: formatPrice(totals.totalPayouts, currency) },
+    ],
+  };
+  if (children) return <>{children(state)}</>;
+  return (
+    <section data-better-stripe="payout-overview">
+      <h2>Payout activity</h2>
+      <dl>
+        {state.metrics.map((metric) => (
+          <div key={metric.label}>
+            <dt>{metric.label}</dt>
+            <dd>{state.isLoading ? "Loading…" : metric.value}</dd>
+          </div>
+        ))}
+      </dl>
+    </section>
+  );
+}

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

@@ -0,0 +1,60 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { usePaymentMethodsManager } from "./PaymentMethods.js";
+afterEach(cleanup);
+it("refreshes saved methods after a successful attach and reports detach failures", async () => {
+  const load = vi
+    .fn()
+    .mockResolvedValueOnce([])
+    .mockResolvedValueOnce([{ id: "pm_one", type: "card" }]);
+  const attach = vi.fn().mockResolvedValue(null);
+  const detach = vi.fn().mockRejectedValue(new Error("Card is still in use"));
+  const { result } = renderHook(() =>
+    usePaymentMethodsManager({ scopeKey: "buyer", load, attach, detach }),
+  );
+  await waitFor(() => expect(result.current.isLoading).toBe(false));
+  await act(async () => {
+    await result.current.attach("pm_one");
+  });
+  await waitFor(() => expect(result.current.methods).toHaveLength(1));
+  expect(attach).toHaveBeenCalledWith("pm_one");
+  await act(async () => {
+    await result.current.detach("pm_one");
+  });
+  expect(result.current.deleteError).toBe("Card is still in use");
+  expect(result.current.methods).toHaveLength(1);
+});
+it("keeps a pending detach error associated with detach when another action is attempted", async () => {
+  let reject!: (error: Error) => void;
+  const detach = vi.fn(
+    () =>
+      new Promise<void>((_, fail) => {
+        reject = fail;
+      }),
+  );
+  const attach = vi.fn();
+  const { result } = renderHook(() =>
+    usePaymentMethodsManager({
+      scopeKey: "buyer",
+      load: async () => [],
+      attach,
+      detach,
+    }),
+  );
+  await waitFor(() => expect(result.current.isLoading).toBe(false));
+  let pending!: Promise<void>;
+  act(() => {
+    pending = result.current.detach("pm_one");
+  });
+  await act(async () => {
+    await result.current.attach("pm_two");
+  });
+  expect(attach).not.toHaveBeenCalled();
+  await act(async () => {
+    reject(new Error("Detach failed"));
+    await pending;
+  });
+  expect(result.current.deleteError).toBe("Detach failed");
+  expect(result.current.attachError).toBeNull();
+});

package/src/react/workflows/PaymentMethods.tsx

@@ -0,0 +1,117 @@
+"use client";
+import { useState, type ReactNode } from "react";
+import {
+  PaymentMethodsList,
+  type PaymentMethodItem,
+} from "../components/PaymentMethodsList.js";
+import { AddCardForm } from "../components/AddCardForm.js";
+import { StripeProvider } from "../components/StripeProvider.js";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { useWorkflowResource } from "./useWorkflowResource.js";
+export type PaymentMethodsActions = {
+  scopeKey: string;
+  load: () => Promise<PaymentMethodItem[]>;
+  attach: (paymentMethodId: string) => Promise<unknown>;
+  detach: (paymentMethodId: string) => Promise<unknown>;
+};
+export function usePaymentMethodsManager(props: PaymentMethodsActions) {
+  const resource = useWorkflowResource(props.load, props.scopeKey);
+  const [kind, setKind] = useState<"attach" | "detach">("attach");
+  const action = useWorkflowAction(
+    async (kind: "attach" | "detach", id: string) => {
+      setKind(kind);
+      if (!id.trim()) throw new Error("A payment method ID is required.");
+      await props[kind](id);
+      return true;
+    },
+    props.scopeKey,
+  );
+  const run = async (kind: "attach" | "detach", id: string) => {
+    if (await action.run(kind, id)) resource.refresh();
+  };
+  return {
+    methods: resource.data ?? [],
+    isLoading: resource.isLoading,
+    isPending: action.isPending,
+    loadError: resource.error,
+    attachError: kind === "attach" ? action.error : null,
+    deleteError: kind === "detach" ? action.error : null,
+    reload: resource.refresh,
+    attach: (id: string) => run("attach", id),
+    detach: (id: string) => run("detach", id),
+  };
+}
+export function toPaymentMethodItem(
+  method: {
+    id: string;
+    type: string;
+    card?: {
+      brand: string;
+      last4: string;
+      exp_month: number;
+      exp_year: number;
+    } | null;
+  },
+  defaultId?: string,
+): PaymentMethodItem {
+  return {
+    id: method.id,
+    type: method.type,
+    card: method.card
+      ? {
+          brand: method.card.brand,
+          last4: method.card.last4,
+          expMonth: method.card.exp_month,
+          expYear: method.card.exp_year,
+        }
+      : undefined,
+    isDefault: method.id === defaultId,
+  };
+}
+export type PaymentMethodsProps = PaymentMethodsActions & {
+  publishableKey: string;
+  children?: (state: ReturnType<typeof usePaymentMethodsManager>) => ReactNode;
+};
+export function PaymentMethods(props: PaymentMethodsProps) {
+  return <PaymentMethodsBody key={props.scopeKey} {...props} />;
+}
+function PaymentMethodsBody(props: PaymentMethodsProps) {
+  const state = usePaymentMethodsManager(props);
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <section
+      data-better-stripe="payment-methods"
+      aria-busy={state.isPending || state.isLoading}
+    >
+      <h2>Payment methods</h2>
+      <StripeProvider publishableKey={props.publishableKey}>
+        <fieldset disabled={state.isPending}>
+          <legend>Add a card</legend>
+          <AddCardForm
+            onSuccess={(id) => {
+              void state.attach(id);
+            }}
+          />
+        </fieldset>
+      </StripeProvider>
+      {(state.loadError || state.attachError || state.deleteError) && (
+        <p role="alert">
+          {state.loadError || state.attachError || state.deleteError}
+        </p>
+      )}
+      <button type="button" disabled={state.isLoading} onClick={state.reload}>
+        {state.isLoading ? "Loading…" : "Refresh"}
+      </button>
+      {state.isLoading ? (
+        <p role="status">Loading payment methods…</p>
+      ) : (
+        <PaymentMethodsList
+          methods={state.methods}
+          onDelete={(id) => {
+            void state.detach(id);
+          }}
+        />
+      )}
+    </section>
+  );
+}

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

@@ -0,0 +1,24 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, expect, it } from "vitest";
+import { PaymentReceipt } from "./PaymentReceipt.js";
+afterEach(cleanup);
+it("shows success only after the application supplies a confirmed server payment", () => {
+  const { rerender } = render(<PaymentReceipt payment={undefined} />);
+  expect(screen.getByRole("status").textContent).toContain(
+    "Waiting for Stripe",
+  );
+  rerender(
+    <PaymentReceipt
+      payment={{ status: "processing", amount: 2900, currency: "usd" }}
+    />,
+  );
+  expect(screen.queryByText("Payment successful!")).toBeNull();
+  rerender(
+    <PaymentReceipt
+      payment={{ status: "succeeded", amount: 2900, currency: "usd" }}
+    />,
+  );
+  expect(screen.getByText("Payment successful!")).toBeTruthy();
+  expect(screen.getByText("$29.00")).toBeTruthy();
+});

package/src/react/workflows/PaymentReceipt.tsx

@@ -0,0 +1,46 @@
+"use client";
+import type { ReactNode } from "react";
+import { formatPrice } from "../lib/price-helpers.js";
+export type ReceiptPayment = {
+  status: string;
+  amount: number;
+  currency: string;
+};
+export type PaymentReceiptState = {
+  payment: ReceiptPayment | null | undefined;
+  isLoading: boolean;
+  isConfirmed: boolean;
+  title: string;
+  message: string;
+  amountLabel?: string;
+};
+export type PaymentReceiptProps = {
+  /** Supply authoritative server/webhook data, never a client-confirmation result. */ payment:
+    ReceiptPayment | null | undefined;
+  children?: (state: PaymentReceiptState) => ReactNode;
+};
+export function PaymentReceipt({ payment, children }: PaymentReceiptProps) {
+  const isConfirmed = payment?.status === "succeeded";
+  const state = {
+    payment,
+    isLoading: !payment,
+    isConfirmed,
+    title: isConfirmed ? "Payment successful!" : "Payment status",
+    message: !payment
+      ? "Waiting for Stripe payment confirmation…"
+      : isConfirmed
+        ? "Your purchase is confirmed by Stripe."
+        : `Stripe payment status: ${payment.status}`,
+    amountLabel: payment
+      ? formatPrice(payment.amount, payment.currency)
+      : undefined,
+  };
+  if (children) return <>{children(state)}</>;
+  return (
+    <section data-better-stripe="payment-receipt">
+      <h2>{state.title}</h2>
+      <p role="status">{state.message}</p>
+      {state.amountLabel && <p>{state.amountLabel}</p>}
+    </section>
+  );
+}

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

@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import { Payouts } from "./Payouts.js";
+afterEach(cleanup);
+const row = (id: string, status = "paid") => ({
+  id,
+  status,
+  amount: 5000,
+  currency: "usd",
+  arrivalDate: 1800000000000,
+  created: 1799990000000,
+});
+it("shows balances, the actual next payout/date, and merges paginated history without duplicates", async () => {
+  const first = row("po_first");
+  const next = row("po_next", "pending");
+  const load = vi
+    .fn()
+    .mockResolvedValueOnce({
+      balances: [{ currency: "usd", available: 12000, pending: 2000 }],
+      upcoming: [next],
+      payouts: [next, first],
+      nextCursor: "po_first",
+    })
+    .mockResolvedValueOnce({
+      balances: [],
+      upcoming: [next],
+      payouts: [first, row("po_older")],
+      nextCursor: null,
+    });
+  render(<Payouts scopeKey="acct_one" load={load} />);
+  await screen.findByText("$120.00");
+  expect(screen.getByText("$20.00")).toBeTruthy();
+  expect(screen.getByText("po_next")).toBeTruthy();
+  await userEvent.click(
+    screen.getByRole("button", { name: "Load more payouts" }),
+  );
+  await screen.findByText("po_older");
+  expect(screen.getAllByText("po_first")).toHaveLength(1);
+  expect(screen.getByText("$120.00")).toBeTruthy();
+  expect(load).toHaveBeenLastCalledWith("po_first");
+});
+it("shows a load error with a working retry", async () => {
+  const load = vi
+    .fn()
+    .mockRejectedValueOnce(new Error("No balance access"))
+    .mockResolvedValueOnce({
+      balances: [],
+      upcoming: [],
+      payouts: [],
+      nextCursor: null,
+    });
+  render(<Payouts scopeKey="acct_one" load={load} />);
+  expect((await screen.findByRole("alert")).textContent).toContain(
+    "No balance access",
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Refresh" }));
+  await screen.findByText("No previous payouts yet.");
+});
+it("exports payout history with explicit empty/loading states and date formatting", async () => {
+  const { PayoutHistory } = await import("./Payouts.js");
+  const { rerender } = render(<PayoutHistory rows={undefined} />);
+  expect(screen.getByRole("status")).toBeTruthy();
+  rerender(<PayoutHistory rows={[]} />);
+  expect(screen.getByText("No payouts yet.")).toBeTruthy();
+  rerender(
+    <PayoutHistory
+      rows={[
+        {
+          id: "po_history",
+          amount: 900,
+          currency: "usd",
+          status: "paid",
+          arrivalDate: null,
+        },
+      ]}
+    />,
+  );
+  expect(screen.getByText("po_history")).toBeTruthy();
+  expect(screen.getByText("Not supplied by Stripe")).toBeTruthy();
+});