@fantastic.dev/better-stripe 0.6.1 → 0.8.0

package/src/react/workflows/CheckoutChooser.tsx

@@ -0,0 +1,77 @@
+"use client";
+import { useState, type ReactNode } from "react";
+import { CHECKOUT_OPTIONS } from "./checkout-options.js";
+import type { CheckoutMode } from "./Checkout.js";
+export type CheckoutOption = (typeof CHECKOUT_OPTIONS)[number];
+export type CheckoutChooserState = {
+  options: typeof CHECKOUT_OPTIONS;
+  selected: CheckoutOption;
+  unsupported: boolean;
+  select: (mode: CheckoutMode) => void;
+};
+export type CheckoutChooserProps = {
+  value?: CheckoutMode;
+  defaultValue?: CheckoutMode;
+  onValueChange?: (mode: CheckoutMode) => void;
+  recurring?: boolean;
+  children?: (state: CheckoutChooserState) => ReactNode;
+};
+/** Checkout tradeoffs and mode selection, independent of routing and session creation. */
+export function CheckoutChooser({
+  value,
+  defaultValue = "embedded",
+  onValueChange,
+  recurring = false,
+  children,
+}: CheckoutChooserProps) {
+  const [internal, setInternal] = useState(defaultValue);
+  const selected =
+    CHECKOUT_OPTIONS.find((option) => option.id === (value ?? internal)) ??
+    CHECKOUT_OPTIONS[1];
+  const select = (mode: CheckoutMode) => {
+    setInternal(mode);
+    onValueChange?.(mode);
+  };
+  const state = {
+    options: CHECKOUT_OPTIONS,
+    selected,
+    select,
+    unsupported: recurring && selected.id === "payment-intent",
+  };
+  if (children) return <>{children(state)}</>;
+  return (
+    <section data-better-stripe="checkout-chooser">
+      <h2>Choose your checkout type</h2>
+      <div role="group" aria-label="Checkout types">
+        {state.options.map((option) => (
+          <button
+            key={option.id}
+            type="button"
+            aria-pressed={selected.id === option.id}
+            onClick={() => select(option.id)}
+          >
+            {option.title}
+          </button>
+        ))}
+      </div>
+      <h3>{selected.title}</h3>
+      <p>{selected.api}</p>
+      <dl>
+        <dt>Pros</dt>
+        <dd>{selected.pros}</dd>
+        <dt>Cons</dt>
+        <dd>{selected.cons}</dd>
+      </dl>
+      <a href={selected.docs} target="_blank" rel="noreferrer">
+        Stripe documentation
+      </a>
+      {selected.id === "form" && <p>Preview</p>}
+      {state.unsupported && (
+        <p role="status">
+          Payment Intents alone do not create subscriptions. Choose a Checkout
+          Sessions integration for a recurring product.
+        </p>
+      )}
+    </section>
+  );
+}

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

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+import { act, cleanup, render, screen } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+const mocks = vi.hoisted(() => ({
+  confirm: vi.fn(),
+  onConfirm: undefined as undefined | ((event: object) => unknown),
+}));
+vi.mock("@stripe/stripe-js", () => ({
+  loadStripe: () => Promise.resolve(null),
+}));
+vi.mock("@stripe/react-stripe-js/checkout", () => ({
+  CheckoutFormProvider: ({ children }: { children: ReactNode }) => children,
+  CheckoutForm: ({ onConfirm }: { onConfirm: (event: object) => unknown }) => {
+    mocks.onConfirm = onConfirm;
+    return <p>Stripe form</p>;
+  },
+  useCheckoutForm: () => ({
+    type: "success",
+    checkout: { id: "cs_form", confirm: mocks.confirm },
+  }),
+}));
+import { CheckoutForm } from "./CheckoutForms.js";
+afterEach(cleanup);
+it("returns a promise for the Stripe form confirmation lifecycle and uses the actual session ID", async () => {
+  mocks.confirm.mockResolvedValue({ type: "success" });
+  const navigate = vi.fn();
+  render(
+    <CheckoutForm
+      publishableKey="pk_test_example"
+      clientSecret="cs_form_secret"
+      returnUrl="https://app.test/receipt?session_id={CHECKOUT_SESSION_ID}"
+      onNavigate={navigate}
+    />,
+  );
+  let pending: unknown;
+  await act(async () => {
+    pending = mocks.onConfirm!({ type: "confirm" });
+    await pending;
+  });
+  expect(pending).toBeInstanceOf(Promise);
+  expect(mocks.confirm).toHaveBeenCalledWith({
+    formConfirmEvent: { type: "confirm" },
+  });
+  expect(navigate).toHaveBeenCalledWith(
+    "https://app.test/receipt?session_id=cs_form",
+  );
+});
+it("reports Stripe form confirmation failures", async () => {
+  mocks.confirm.mockResolvedValue({
+    type: "error",
+    error: { message: "Card declined" },
+  });
+  render(
+    <CheckoutForm
+      publishableKey="pk_test_example"
+      clientSecret="cs_form_secret"
+      returnUrl="/receipt"
+      onNavigate={vi.fn()}
+    />,
+  );
+  await act(async () => {
+    await mocks.onConfirm!({ type: "confirm" });
+  });
+  expect(screen.getByRole("alert").textContent).toContain("Card declined");
+});

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

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+const mocks = vi.hoisted(() => ({
+  updateEmail: vi.fn(),
+  confirm: vi.fn(),
+  submit: vi.fn(),
+  confirmPayment: vi.fn(),
+}));
+vi.mock("../components/CheckoutSessionProvider.js", () => ({
+  CheckoutSessionProvider: ({ children }: { children: ReactNode }) => children,
+}));
+vi.mock("../components/StripeProvider.js", () => ({
+  StripeProvider: ({ children }: { children: ReactNode }) => children,
+}));
+vi.mock("@stripe/react-stripe-js/checkout", () => ({
+  PaymentElement: () => <p>Secure payment details</p>,
+  useCheckout: () => ({
+    type: "success",
+    checkout: {
+      id: "cs_test",
+      canConfirm: false,
+      updateEmail: mocks.updateEmail,
+      confirm: mocks.confirm,
+    },
+  }),
+}));
+vi.mock("@stripe/react-stripe-js", () => ({
+  PaymentElement: () => <p>Secure payment details</p>,
+  useStripe: () => ({ confirmPayment: mocks.confirmPayment }),
+  useElements: () => ({ submit: mocks.submit }),
+}));
+import { CheckoutElementsForm, PaymentIntentForm } from "./CheckoutForms.js";
+afterEach(cleanup);
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.updateEmail.mockResolvedValue({ type: "success" });
+  mocks.confirm.mockResolvedValue({
+    type: "error",
+    error: { message: "Card declined" },
+  });
+  mocks.submit.mockResolvedValue({});
+  mocks.confirmPayment.mockResolvedValue({
+    error: { message: "Card declined" },
+  });
+});
+const props = {
+  publishableKey: "pk_test_example",
+  clientSecret: "cs_test_secret",
+  returnUrl: "https://app.test/receipt?session_id={CHECKOUT_SESSION_ID}",
+  email: "buyer@example.com",
+  onNavigate: vi.fn(),
+};
+it("sends the email before confirming, including when canConfirm is initially false", async () => {
+  render(<CheckoutElementsForm {...props} />);
+  await userEvent.click(screen.getByRole("button", { name: "Pay" }));
+  expect(mocks.updateEmail).toHaveBeenCalledWith("buyer@example.com");
+  expect(mocks.confirm).toHaveBeenCalledOnce();
+  expect(screen.getByRole("alert").textContent).toContain("Card declined");
+});
+it("does not confirm after Stripe rejects the email", async () => {
+  mocks.updateEmail.mockResolvedValue({
+    type: "error",
+    error: { message: "Invalid email" },
+  });
+  render(<CheckoutElementsForm {...props} />);
+  await userEvent.click(screen.getByRole("button", { name: "Pay" }));
+  expect(screen.getByRole("alert").textContent).toContain("Invalid email");
+  expect(mocks.confirm).not.toHaveBeenCalled();
+});
+it("disables confirmation while Stripe is processing and supports a new attempt after failure", async () => {
+  let resolve!: (value: unknown) => void;
+  mocks.confirm.mockImplementationOnce(
+    () =>
+      new Promise((done) => {
+        resolve = done;
+      }),
+  );
+  render(<CheckoutElementsForm {...props} />);
+  await userEvent.click(screen.getByRole("button", { name: "Pay" }));
+  expect(
+    (screen.getByRole("button", { name: "Processing…" }) as HTMLButtonElement)
+      .disabled,
+  ).toBe(true);
+  resolve({ type: "error", error: { message: "Try another card" } });
+  await screen.findByText("Try another card");
+  expect(
+    (screen.getByRole("button", { name: "Pay" }) as HTMLButtonElement).disabled,
+  ).toBe(false);
+});
+it("validates Elements before confirming a Payment Intent", async () => {
+  mocks.submit.mockResolvedValue({ error: { message: "Enter a valid card" } });
+  render(<PaymentIntentForm {...props} returnUrl="https://app.test/receipt" />);
+  await userEvent.click(screen.getByRole("button", { name: "Pay" }));
+  expect(screen.getByRole("alert").textContent).toContain("Enter a valid card");
+  expect(mocks.confirmPayment).not.toHaveBeenCalled();
+});
+it("includes the contact email and redirects to a server-confirmed receipt", async () => {
+  mocks.confirmPayment.mockResolvedValue({ paymentIntent: { id: "pi_test" } });
+  const navigate = vi.fn();
+  render(
+    <PaymentIntentForm
+      {...props}
+      returnUrl="https://app.test/receipt?ref=avery"
+      onNavigate={navigate}
+    />,
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Pay" }));
+  expect(mocks.confirmPayment).toHaveBeenCalledWith(
+    expect.objectContaining({
+      confirmParams: expect.objectContaining({
+        payment_method_data: {
+          billing_details: { email: "buyer@example.com" },
+        },
+      }),
+    }),
+  );
+  expect(navigate).toHaveBeenCalledWith(
+    "https://app.test/receipt?ref=avery&payment_intent=pi_test",
+  );
+});

package/src/react/workflows/CheckoutForms.tsx

@@ -0,0 +1,247 @@
+"use client";
+import {
+  useId,
+  useMemo,
+  useState,
+  type FormEvent,
+  type ReactNode,
+} from "react";
+import { loadStripe, type Appearance } from "@stripe/stripe-js";
+import {
+  PaymentElement as IntentElement,
+  useElements,
+  useStripe,
+} from "@stripe/react-stripe-js";
+import {
+  PaymentElement,
+  useCheckout,
+  CheckoutFormProvider,
+  CheckoutForm as StripeCheckoutForm,
+  useCheckoutForm,
+} from "@stripe/react-stripe-js/checkout";
+import { CheckoutSessionProvider } from "../components/CheckoutSessionProvider.js";
+import { StripeProvider } from "../components/StripeProvider.js";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+export type CheckoutFormState = {
+  email: string;
+  setEmail: (email: string) => void;
+  emailInputId: string;
+  isPending: boolean;
+  error: string | null;
+  paymentElement: ReactNode;
+  submit: (event: FormEvent<HTMLFormElement>) => void;
+};
+export type CheckoutFormOptions = {
+  email?: string;
+  appearance?: Appearance;
+  renderForm?: (state: CheckoutFormState) => ReactNode;
+};
+export type CheckoutFormProps = CheckoutFormOptions & {
+  publishableKey: string;
+  clientSecret: string;
+  returnUrl: string;
+  onNavigate: (url: string) => void;
+};
+function NativeForm({
+  email,
+  setEmail,
+  emailInputId,
+  paymentElement,
+  submit,
+  isPending,
+  error,
+}: CheckoutFormState) {
+  return (
+    <form
+      onSubmit={submit}
+      data-better-stripe="checkout-form"
+      aria-busy={isPending}
+    >
+      <label htmlFor={emailInputId}>Email for your receipt</label>
+      <input
+        id={emailInputId}
+        type="email"
+        name="email"
+        required
+        autoComplete="email"
+        value={email}
+        onChange={(event) => setEmail(event.target.value)}
+      />
+      {paymentElement}
+      {error && <p role="alert">{error}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Processing…" : "Pay"}
+      </button>
+    </form>
+  );
+}
+export function CheckoutElementsForm(props: CheckoutFormProps) {
+  return (
+    <CheckoutSessionProvider
+      publishableKey={props.publishableKey}
+      clientSecret={props.clientSecret}
+      appearance={props.appearance}
+    >
+      <SessionForm {...props} />
+    </CheckoutSessionProvider>
+  );
+}
+function SessionForm({
+  email: initialEmail = "",
+  returnUrl,
+  onNavigate,
+  renderForm,
+}: CheckoutFormProps) {
+  const checkout = useCheckout();
+  const [email, setEmail] = useState(initialEmail);
+  const emailInputId = useId();
+  const action = useWorkflowAction(async () => {
+    if (checkout.type !== "success") throw new Error("Checkout is not ready.");
+    const updated = await checkout.checkout.updateEmail(email);
+    if (updated.type === "error") throw new Error(updated.error.message);
+    const confirmed = await checkout.checkout.confirm();
+    if (confirmed.type === "error") throw new Error(confirmed.error.message);
+    onNavigate(
+      returnUrl.replace("{CHECKOUT_SESSION_ID}", checkout.checkout.id),
+    );
+  });
+  if (checkout.type === "loading")
+    return <p role="status">Loading checkout…</p>;
+  if (checkout.type === "error")
+    return <p role="alert">{checkout.error.message}</p>;
+  const state: CheckoutFormState = {
+    email,
+    setEmail,
+    emailInputId,
+    paymentElement: <PaymentElement />,
+    error: action.error,
+    isPending: action.isPending,
+    submit: (event) => {
+      event.preventDefault();
+      void action.run();
+    },
+  };
+  return <>{renderForm ? renderForm(state) : <NativeForm {...state} />}</>;
+}
+export function PaymentIntentForm(props: CheckoutFormProps) {
+  return (
+    <StripeProvider
+      publishableKey={props.publishableKey}
+      elementsOptions={{
+        clientSecret: props.clientSecret,
+        ...(props.appearance ? { appearance: props.appearance } : {}),
+      }}
+    >
+      <IntentForm {...props} />
+    </StripeProvider>
+  );
+}
+function IntentForm({
+  email: initialEmail = "",
+  returnUrl,
+  onNavigate,
+  renderForm,
+}: CheckoutFormProps) {
+  const stripe = useStripe();
+  const elements = useElements();
+  const emailInputId = useId();
+  const [email, setEmail] = useState(initialEmail);
+  const action = useWorkflowAction(async () => {
+    if (!stripe || !elements)
+      throw new Error("Payment details are still loading.");
+    const validation = await elements.submit();
+    if (validation.error)
+      throw new Error(
+        validation.error.message ?? "Check your payment details.",
+      );
+    const result = await stripe.confirmPayment({
+      elements,
+      confirmParams: {
+        return_url: returnUrl,
+        payment_method_data: { billing_details: { email } },
+      },
+      redirect: "if_required",
+    });
+    if (result.error)
+      throw new Error(result.error.message ?? "Payment failed.");
+    if (result.paymentIntent) {
+      const url = new URL(returnUrl, window.location.origin);
+      url.searchParams.set("payment_intent", result.paymentIntent.id);
+      onNavigate(url.toString());
+    }
+  });
+  const state: CheckoutFormState = {
+    email,
+    setEmail,
+    emailInputId,
+    paymentElement: <IntentElement />,
+    error: action.error,
+    isPending: action.isPending || !stripe || !elements,
+    submit: (event) => {
+      event.preventDefault();
+      void action.run();
+    },
+  };
+  return <>{renderForm ? renderForm(state) : <NativeForm {...state} />}</>;
+}
+export function CheckoutForm(props: CheckoutFormProps) {
+  const stripe = useMemo(
+    () => loadStripe(props.publishableKey),
+    [props.publishableKey],
+  );
+  return (
+    <CheckoutFormProvider
+      stripe={stripe}
+      options={{
+        clientSecret: props.clientSecret,
+        ...(props.appearance
+          ? { elementsOptions: { appearance: props.appearance } }
+          : {}),
+      }}
+    >
+      <CompactForm {...props} />
+    </CheckoutFormProvider>
+  );
+}
+function CompactForm({ returnUrl, onNavigate }: CheckoutFormProps) {
+  const checkout = useCheckoutForm();
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const action = useWorkflowAction(
+    async (
+      event: Parameters<
+        NonNullable<
+          React.ComponentProps<typeof StripeCheckoutForm>["onConfirm"]
+        >
+      >[0],
+    ) => {
+      if (checkout.type !== "success")
+        throw new Error("Checkout is not ready.");
+      const result = await checkout.checkout.confirm({
+        formConfirmEvent: event,
+      });
+      if (result.type === "error") throw new Error(result.error.message);
+      onNavigate(
+        returnUrl.replace("{CHECKOUT_SESSION_ID}", checkout.checkout.id),
+      );
+    },
+  );
+  if (checkout.type === "loading")
+    return <p role="status">Loading embedded form…</p>;
+  if (checkout.type === "error")
+    return <p role="alert">{checkout.error.message}</p>;
+  return (
+    <div data-better-stripe="checkout-form" aria-busy={action.isPending}>
+      <StripeCheckoutForm
+        onLoadError={({ error }) =>
+          setLoadError(error.message ?? "Could not load checkout.")
+        }
+        onConfirm={async (event) => {
+          await action.run(event);
+        }}
+      />
+      {(loadError || action.error) && (
+        <p role="alert">{loadError || action.error}</p>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,34 @@
+// @vitest-environment jsdom
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+} from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { ClipboardButton } from "./ClipboardButton.js";
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+it("copies on demand, restores its label, and catches denied clipboard access", async () => {
+  vi.useFakeTimers();
+  const writeText = vi
+    .fn()
+    .mockResolvedValueOnce(undefined)
+    .mockRejectedValueOnce(new Error("Clipboard denied"));
+  render(<ClipboardButton text="pnpm check:all" writeText={writeText} />);
+  await act(async () => {
+    fireEvent.click(screen.getByRole("button", { name: "Copy" }));
+  });
+  expect(writeText).toHaveBeenCalledWith("pnpm check:all");
+  expect(screen.getByText("Copied!")).toBeTruthy();
+  act(() => {
+    vi.advanceTimersByTime(2000);
+  });
+  await act(async () => {
+    fireEvent.click(screen.getByRole("button", { name: "Copy" }));
+  });
+  expect(screen.getByRole("alert").textContent).toContain("Clipboard denied");
+});

package/src/react/workflows/ClipboardButton.tsx

@@ -0,0 +1,67 @@
+"use client";
+import { useEffect, useRef, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+export type ClipboardButtonProps = {
+  text: string;
+  label?: string;
+  copiedLabel?: string;
+  resetAfterMs?: number;
+  writeText?: (text: string) => Promise<void>;
+  children?: (state: {
+    copy: () => Promise<void>;
+    copied: boolean;
+    isPending: boolean;
+    error: string | null;
+    label: string;
+  }) => ReactNode;
+};
+export function ClipboardButton({
+  text,
+  label = "Copy",
+  copiedLabel = "Copied!",
+  resetAfterMs = 2000,
+  writeText = (text) => navigator.clipboard.writeText(text),
+  children,
+}: ClipboardButtonProps) {
+  const action = useWorkflowAction(async () => {
+    await writeText(text);
+    return text;
+  });
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  useEffect(
+    () => () => {
+      clearTimeout(timer.current);
+    },
+    [],
+  );
+  const copied = action.result === text;
+  const copy = async () => {
+    const result = await action.run();
+    if (result !== undefined) {
+      clearTimeout(timer.current);
+      timer.current = setTimeout(action.reset, resetAfterMs);
+    }
+  };
+  const state = {
+    copy,
+    copied,
+    isPending: action.isPending,
+    error: action.error,
+    label: copied ? copiedLabel : label,
+  };
+  if (children) return <>{children(state)}</>;
+  return (
+    <span data-better-stripe="clipboard">
+      <button
+        type="button"
+        disabled={state.isPending}
+        onClick={() => {
+          void copy();
+        }}
+      >
+        {state.label}
+      </button>
+      {state.error && <span role="alert">{state.error}</span>}
+    </span>
+  );
+}

package/src/react/workflows/Collection.tsx

@@ -0,0 +1,76 @@
+"use client";
+import type { Key, ReactNode } from "react";
+export type WorkflowColumn<Row> = {
+  id: string;
+  label: string;
+  align?: "start" | "end";
+  cell: (row: Row) => ReactNode;
+};
+export type CollectionRenderProps<Row> = {
+  rows: Row[];
+  columns: WorkflowColumn<Row>[];
+  getKey: (row: Row) => Key;
+  isLoading: boolean;
+  isEmpty: boolean;
+  error: string | null;
+  emptyLabel: string;
+  loadingLabel: string;
+};
+export type CollectionProps<Row> = {
+  rows: Row[] | null | undefined;
+  columns: WorkflowColumn<Row>[];
+  getKey: (row: Row) => Key;
+  isLoading?: boolean;
+  error?: string | null;
+  emptyLabel?: string;
+  loadingLabel?: string;
+  children?: (state: CollectionRenderProps<Row>) => ReactNode;
+};
+/** Accessible native table by default. Render props let the application supply its design-system elements. */
+export function Collection<Row>({
+  rows,
+  columns,
+  getKey,
+  isLoading = rows === undefined,
+  error = null,
+  emptyLabel = "No records yet.",
+  loadingLabel = "Loading…",
+  children,
+}: CollectionProps<Row>) {
+  const state: CollectionRenderProps<Row> = {
+    rows: rows ?? [],
+    columns,
+    getKey,
+    isLoading,
+    isEmpty: !isLoading && !rows?.length,
+    error,
+    emptyLabel,
+    loadingLabel,
+  };
+  if (children) return <>{children(state)}</>;
+  if (error) return <p role="alert">{error}</p>;
+  if (isLoading) return <p role="status">{loadingLabel}</p>;
+  if (state.isEmpty) return <p>{emptyLabel}</p>;
+  return (
+    <table data-better-stripe="collection">
+      <thead>
+        <tr>
+          {columns.map((column) => (
+            <th key={column.id} scope="col">
+              {column.label}
+            </th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {state.rows.map((row) => (
+          <tr key={getKey(row)}>
+            {columns.map((column) => (
+              <td key={column.id}>{column.cell(row)}</td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}