@fantastic.dev/better-stripe 0.7.0 → 0.8.0

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

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

@@ -0,0 +1,86 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, expect, it } from "vitest";
+import {
+  Sales,
+  Invoices,
+  RefundHistory,
+  ReferredSales,
+} from "./Collections.js";
+afterEach(cleanup);
+it("renders sale economics in minor units without recomputing the platform's fee policy", () => {
+  render(
+    <Sales
+      rows={[
+        {
+          paymentIntentId: "pi_sale",
+          planId: "custom",
+          gross: 10000,
+          processingFee: 320,
+          platformNet: 580,
+          affiliateNet: 1820,
+          costRecoveryAmount: 100,
+          sellerNet: 7180,
+          currency: "usd",
+          status: "settled",
+        },
+      ]}
+    />,
+  );
+  expect(screen.getByText("$100.00")).toBeTruthy();
+  expect(screen.getByText("$71.80")).toBeTruthy();
+  expect(screen.getByText("pi_sale")).toBeTruthy();
+});
+it("renders invoice links and explicit loading/empty states", () => {
+  const { rerender } = render(<Invoices rows={undefined} />);
+  expect(screen.getByRole("status").textContent).toContain("Loading");
+  rerender(<Invoices rows={[]} />);
+  expect(screen.getByText("No invoices yet.")).toBeTruthy();
+  rerender(
+    <Invoices
+      rows={[
+        {
+          stripeInvoiceId: "in_test",
+          status: "paid",
+          amountPaid: 1200,
+          currency: "usd",
+          hostedInvoiceUrl: "https://invoice.stripe.com/test",
+        },
+      ]}
+    />,
+  );
+  expect(
+    screen.getByRole("link", { name: "View invoice" }).getAttribute("href"),
+  ).toBe("https://invoice.stripe.com/test");
+});
+it("preserves store attribution in referred sales and refund statuses in history", () => {
+  const { unmount } = render(
+    <ReferredSales
+      rows={[
+        {
+          stripeTransferId: "tr_test",
+          storeName: "Independent Store",
+          amount: 900,
+          currency: "usd",
+        },
+      ]}
+    />,
+  );
+  expect(screen.getByText("Independent Store")).toBeTruthy();
+  unmount();
+  render(
+    <RefundHistory
+      rows={[
+        {
+          stripeRefundId: "re_test",
+          amount: 1000,
+          currency: "usd",
+          status: "failed",
+          _creationTime: Date.UTC(2026, 9, 13),
+        },
+      ]}
+    />,
+  );
+  expect(screen.getByText("failed")).toBeTruthy();
+  expect(screen.getByRole("columnheader", { name: "Created" })).toBeTruthy();
+});