@fantastic.dev/better-stripe 0.7.0 → 0.8.0

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

@@ -0,0 +1,118 @@
+// @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";
+vi.mock("../components/EmbeddedCheckout.js", () => ({
+  EmbeddedCheckout: () => <div>Stripe iframe</div>,
+}));
+vi.mock("./CheckoutForms.js", () => ({
+  CheckoutElementsForm: () => <div>Elements form</div>,
+  PaymentIntentForm: () => <div>Intent form</div>,
+  CheckoutForm: () => <div>Compact form</div>,
+}));
+import { Checkout } from "./Checkout.js";
+afterEach(cleanup);
+it("opens hosted Checkout only on explicit interaction", async () => {
+  const createSession = vi.fn().mockResolvedValue({
+    stripeSessionId: "cs_test",
+    url: "https://checkout.stripe.com/test",
+  });
+  const navigate = vi.fn();
+  render(
+    <Checkout
+      mode="redirect"
+      orderKey="order_one"
+      publishableKey="pk_test_example"
+      returnUrl="https://app.test/receipt"
+      createSession={createSession}
+      onNavigate={navigate}
+    />,
+  );
+  await screen.findByRole("button", { name: "Continue to Stripe Checkout" });
+  expect(navigate).not.toHaveBeenCalled();
+  await userEvent.click(
+    screen.getByRole("button", { name: "Continue to Stripe Checkout" }),
+  );
+  expect(navigate).toHaveBeenCalledWith("https://checkout.stripe.com/test");
+  expect(createSession).toHaveBeenCalledWith(
+    expect.objectContaining({
+      mode: "redirect",
+      requestId: expect.any(String),
+    }),
+  );
+});
+it.each([
+  ["embedded", "Stripe iframe"],
+  ["custom", "Elements form"],
+  ["form", "Compact form"],
+] as const)("dispatches %s to the correct integration", async (mode, title) => {
+  render(
+    <Checkout
+      mode={mode}
+      orderKey="order_one"
+      publishableKey="pk_test_example"
+      returnUrl="https://app.test/receipt"
+      createSession={async () => ({
+        stripeSessionId: "cs_test",
+        clientSecret: "cs_test_secret",
+      })}
+    />,
+  );
+  expect(await screen.findByText(title)).toBeTruthy();
+});
+it("exposes creation errors and retries without losing the selected integration", async () => {
+  const createSession = vi
+    .fn()
+    .mockRejectedValueOnce(new Error("Seller plan expired"))
+    .mockResolvedValueOnce({
+      stripeSessionId: "cs_test",
+      clientSecret: "cs_test_secret",
+    });
+  render(
+    <Checkout
+      mode="embedded"
+      orderKey="order_one"
+      publishableKey="pk_test_example"
+      returnUrl="https://app.test/receipt"
+      createSession={createSession}
+    />,
+  );
+  expect((await screen.findByRole("alert")).textContent).toContain(
+    "Seller plan expired",
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Retry" }));
+  await screen.findByText("Stripe iframe");
+  await waitFor(() => expect(createSession).toHaveBeenCalledTimes(2));
+});
+it("rejects missing session secrets and initializes Payment Intents through their own callback", async () => {
+  const { unmount } = render(
+    <Checkout
+      mode="embedded"
+      orderKey="order_one"
+      publishableKey="pk_test_example"
+      returnUrl="https://app.test/receipt"
+      createSession={async () => ({ stripeSessionId: "cs_test" })}
+    />,
+  );
+  expect((await screen.findByRole("alert")).textContent).toContain(
+    "client secret",
+  );
+  unmount();
+  const createPaymentIntent = vi.fn().mockResolvedValue({
+    paymentIntentId: "pi_test",
+    clientSecret: "pi_test_secret",
+  });
+  render(
+    <Checkout
+      mode="payment-intent"
+      orderKey="order_one"
+      publishableKey="pk_test_example"
+      returnUrl="https://app.test/receipt"
+      createPaymentIntent={createPaymentIntent}
+    />,
+  );
+  await screen.findByText("Intent form");
+  expect(createPaymentIntent).toHaveBeenCalledWith({
+    requestId: expect.any(String),
+  });
+});

package/src/react/workflows/Checkout.tsx

@@ -0,0 +1,135 @@
+"use client";
+import type { ReactNode } from "react";
+import { EmbeddedCheckout } from "../components/EmbeddedCheckout.js";
+import { useWorkflowResource } from "./useWorkflowResource.js";
+import {
+  CheckoutElementsForm,
+  PaymentIntentForm,
+  CheckoutForm,
+  type CheckoutFormOptions,
+} from "./CheckoutForms.js";
+export type CheckoutMode =
+  "redirect" | "embedded" | "custom" | "form" | "payment-intent";
+export type CheckoutSessionResult = {
+  stripeSessionId: string;
+  clientSecret?: string;
+  url?: string;
+};
+export type CheckoutIntentResult = {
+  paymentIntentId: string;
+  clientSecret: string;
+};
+export type CheckoutRequest = {
+  mode: Exclude<CheckoutMode, "payment-intent">;
+  requestId: string;
+};
+export type CheckoutRenderProps = {
+  content: ReactNode;
+  isLoading: boolean;
+  error: string | null;
+  retry: () => void;
+  mode: CheckoutMode;
+  hostedUrl?: string;
+  continueToCheckout?: () => void;
+};
+type Common = CheckoutFormOptions & {
+  publishableKey: string;
+  /** Changes when the price, signed-in customer, or referral attribution changes. */
+  orderKey: string;
+  returnUrl: string;
+  onNavigate?: (url: string) => void;
+  children?: (state: CheckoutRenderProps) => ReactNode;
+};
+export type CheckoutProps = Common &
+  (
+    | {
+        mode: Exclude<CheckoutMode, "payment-intent">;
+        createSession: (
+          request: CheckoutRequest,
+        ) => Promise<CheckoutSessionResult>;
+      }
+    | {
+        mode: "payment-intent";
+        createPaymentIntent: (request: {
+          requestId: string;
+        }) => Promise<CheckoutIntentResult>;
+      }
+  );
+/** All checkout integrations share one unstyled lifecycle. Callbacks must authenticate and validate prices on the server. */
+export function Checkout(props: CheckoutProps) {
+  return <CheckoutBody key={`${props.orderKey}:${props.mode}`} {...props} />;
+}
+function CheckoutBody(props: CheckoutProps) {
+  const state = useWorkflowResource(async () => {
+    const requestId = crypto.randomUUID();
+    const result =
+      props.mode === "payment-intent"
+        ? await props.createPaymentIntent({ requestId })
+        : await props.createSession({ mode: props.mode, requestId });
+    if (props.mode === "redirect") {
+      if (!("url" in result) || !result.url)
+        throw new Error("Stripe did not return a checkout URL.");
+    } else if (!result.clientSecret)
+      throw new Error("Stripe did not return a checkout client secret.");
+    return result;
+  });
+  const navigate =
+    props.onNavigate ?? ((url: string) => window.location.assign(url));
+  let content: ReactNode;
+  if (state.error)
+    content = (
+      <div role="alert">
+        <p>{state.error}</p>
+        <button type="button" onClick={state.refresh}>
+          Retry
+        </button>
+      </div>
+    );
+  else if (!state.data || state.isLoading)
+    content = <p role="status">Creating checkout…</p>;
+  else if (props.mode === "redirect" && "url" in state.data) {
+    const url = state.data.url!;
+    content = (
+      <button type="button" onClick={() => navigate(url)}>
+        Continue to Stripe Checkout
+      </button>
+    );
+  } else {
+    const form = {
+      publishableKey: props.publishableKey,
+      clientSecret: state.data.clientSecret!,
+      returnUrl: props.returnUrl,
+      email: props.email,
+      appearance: props.appearance,
+      renderForm: props.renderForm,
+      onNavigate: navigate,
+    };
+    content =
+      props.mode === "embedded" ? (
+        <EmbeddedCheckout
+          publishableKey={form.publishableKey}
+          clientSecret={form.clientSecret}
+        />
+      ) : props.mode === "custom" ? (
+        <CheckoutElementsForm {...form} />
+      ) : props.mode === "form" ? (
+        <CheckoutForm {...form} />
+      ) : (
+        <PaymentIntentForm {...form} />
+      );
+  }
+  const hostedUrl =
+    props.mode === "redirect" && state.data && "url" in state.data
+      ? state.data.url
+      : undefined;
+  const result: CheckoutRenderProps = {
+    content,
+    isLoading: state.isLoading,
+    error: state.error,
+    retry: state.refresh,
+    mode: props.mode,
+    hostedUrl,
+    continueToCheckout: hostedUrl ? () => navigate(hostedUrl) : undefined,
+  };
+  return <>{props.children ? props.children(result) : content}</>;
+}

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

@@ -0,0 +1,44 @@
+// @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 { CheckoutChooser } from "./CheckoutChooser.js";
+afterEach(cleanup);
+it("offers five checkout types, explains tradeoffs, and reports the selected mode", async () => {
+  const change = vi.fn();
+  render(<CheckoutChooser onValueChange={change} />);
+  expect(screen.getAllByRole("button")).toHaveLength(5);
+  expect(
+    screen
+      .getByRole("button", { name: "Embedded Checkout" })
+      .getAttribute("aria-pressed"),
+  ).toBe("true");
+  await userEvent.click(
+    screen.getByRole("button", { name: "Hosted Checkout" }),
+  );
+  expect(change).toHaveBeenCalledWith("redirect");
+  expect(screen.getByText(/Redirects away from your app/)).toBeTruthy();
+  expect(
+    screen
+      .getByRole("link", { name: "Stripe documentation" })
+      .getAttribute("href"),
+  ).toBe("https://docs.stripe.com/payments/checkout");
+});
+it("preserves a controlled selection and marks Payment Intents unsupported for recurring products", async () => {
+  const change = vi.fn();
+  render(
+    <CheckoutChooser value="payment-intent" recurring onValueChange={change}>
+      {(state) => (
+        <>
+          <span>{state.selected.id}</span>
+          <span>{String(state.unsupported)}</span>
+          <button onClick={() => state.select("custom")}>Switch</button>
+        </>
+      )}
+    </CheckoutChooser>,
+  );
+  expect(screen.getByText("true")).toBeTruthy();
+  await userEvent.click(screen.getByRole("button", { name: "Switch" }));
+  expect(change).toHaveBeenCalledWith("custom");
+  expect(screen.getByText("payment-intent")).toBeTruthy();
+});

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",
+  );
+});