@fantastic.dev/better-stripe 0.6.1 → 0.8.0

package/src/react/workflows/Billing.tsx

@@ -0,0 +1,213 @@
+"use client";
+import { useId, useState, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { formatPrice } from "../lib/price-helpers.js";
+export type EstimatedInvoice = {
+  currency: string;
+  total: number;
+  nextBillingAt: number;
+  lines: {
+    id: string;
+    description: string;
+    amount: number;
+    sourceType?: string;
+  }[];
+};
+export function useInvoiceEstimate(
+  load: () => Promise<EstimatedInvoice>,
+  scopeKey: string,
+) {
+  const action = useWorkflowAction(load, scopeKey);
+  return {
+    invoice: action.result,
+    isPending: action.isPending,
+    error: action.error,
+    refresh: action.run,
+  };
+}
+export type InvoiceEstimateProps = {
+  scopeKey: string;
+  load: () => Promise<EstimatedInvoice>;
+  children?: (state: ReturnType<typeof useInvoiceEstimate>) => ReactNode;
+};
+export function InvoiceEstimate({
+  scopeKey,
+  load,
+  children,
+}: InvoiceEstimateProps) {
+  const state = useInvoiceEstimate(load, scopeKey);
+  if (children) return <>{children(state)}</>;
+  return (
+    <section data-better-stripe="invoice-estimate">
+      <h2>Estimated next invoice</h2>
+      <button
+        type="button"
+        disabled={state.isPending}
+        onClick={() => {
+          void state.refresh();
+        }}
+      >
+        {state.isPending
+          ? "Loading…"
+          : state.invoice
+            ? "Refresh estimate"
+            : "View estimate"}
+      </button>
+      {state.error && <p role="alert">{state.error}</p>}
+      {state.invoice && (
+        <>
+          <p>
+            Next billing date:{" "}
+            {new Date(state.invoice.nextBillingAt).toLocaleDateString()}
+          </p>
+          <ul>
+            {state.invoice.lines.map((line) => (
+              <li key={line.id}>
+                {line.description}{" "}
+                <span>{formatPrice(line.amount, state.invoice!.currency)}</span>
+              </li>
+            ))}
+          </ul>
+          <p>
+            Estimated total:{" "}
+            <span>
+              {formatPrice(state.invoice.total, state.invoice.currency)}
+            </span>
+          </p>
+        </>
+      )}
+    </section>
+  );
+}
+export type BalanceFundingActions = {
+  scopeKey: string;
+  change: (args: { enabled: boolean; consent?: true }) => Promise<unknown>;
+};
+export function useBalanceFunding({ scopeKey, change }: BalanceFundingActions) {
+  const [state, setState] = useState({ scope: scopeKey, consent: false });
+  if (state.scope !== scopeKey) setState({ scope: scopeKey, consent: false });
+  const action = useWorkflowAction(async (enabled: boolean) => {
+    if (enabled && !state.consent)
+      throw new Error(
+        "Explicit consent is required to debit a Stripe balance.",
+      );
+    await change({ enabled, consent: enabled ? true : undefined });
+    return true;
+  }, scopeKey);
+  return {
+    consent: state.consent,
+    setConsent: (consent: boolean) =>
+      setState((previous) => ({ ...previous, consent })),
+    error: action.error,
+    isPending: action.isPending,
+    confirm: async (enabled: boolean) => {
+      if (await action.run(enabled))
+        setState((previous) => ({ ...previous, consent: false }));
+    },
+  };
+}
+export type BalancePaymentSourceProps = BalanceFundingActions & {
+  enabled: boolean | undefined;
+  consentLabel?: string;
+  children?: (
+    state: ReturnType<typeof useBalanceFunding> & {
+      enabled: boolean | undefined;
+    },
+  ) => ReactNode;
+};
+export function BalancePaymentSource(props: BalancePaymentSourceProps) {
+  const state = useBalanceFunding(props);
+  const id = useId();
+  if (props.children)
+    return <>{props.children({ ...state, enabled: props.enabled })}</>;
+  return (
+    <section data-better-stripe="balance-payment-source">
+      <h2>Payment source</h2>
+      <p role="status">
+        {props.enabled === undefined
+          ? "Loading…"
+          : props.enabled
+            ? "Pay from Stripe balance"
+            : "Pay with saved payment method"}
+      </p>
+      <p>
+        If your Stripe balance is insufficient, payment can fail. Switch to a
+        saved payment method to pay instead.
+      </p>
+      {state.error && <p role="alert">{state.error}</p>}
+      {props.enabled === false && (
+        <>
+          <label htmlFor={id}>
+            <input
+              id={id}
+              type="checkbox"
+              checked={state.consent}
+              onChange={(event) => state.setConsent(event.target.checked)}
+            />
+            {props.consentLabel ??
+              "I authorize recurring platform charges from my Stripe balance."}
+          </label>
+          <button
+            type="button"
+            disabled={!state.consent || state.isPending}
+            onClick={() => {
+              void state.confirm(true);
+            }}
+          >
+            {state.isPending ? "Saving…" : "Confirm balance payments"}
+          </button>
+        </>
+      )}
+      {props.enabled && (
+        <button
+          type="button"
+          disabled={state.isPending}
+          onClick={() => {
+            void state.confirm(false);
+          }}
+        >
+          Use saved payment method
+        </button>
+      )}
+    </section>
+  );
+}
+export type BillingPortalProps = {
+  scopeKey?: string;
+  createSession: () => Promise<string | { url: string }>;
+  onNavigate?: (url: string) => void;
+  children?: (state: {
+    open: () => Promise<true | undefined>;
+    isPending: boolean;
+    error: string | null;
+  }) => ReactNode;
+};
+export function BillingPortal(props: BillingPortalProps) {
+  const action = useWorkflowAction(async () => {
+    const result = await props.createSession();
+    const url = typeof result === "string" ? result : result.url;
+    if (!url) throw new Error("Stripe did not return a portal URL.");
+    (props.onNavigate ?? ((url) => window.location.assign(url)))(url);
+    return true as const;
+  }, props.scopeKey);
+  const state = {
+    open: action.run,
+    isPending: action.isPending,
+    error: action.error,
+  };
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <div data-better-stripe="billing-portal">
+      {action.error && <p role="alert">{action.error}</p>}
+      <button
+        type="button"
+        disabled={action.isPending}
+        onClick={() => {
+          void action.run();
+        }}
+      >
+        {action.isPending ? "Opening portal…" : "Open Stripe Billing Portal"}
+      </button>
+    </div>
+  );
+}

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

@@ -0,0 +1,31 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { usePlanBilling } from "./BillingPlans.js";
+afterEach(cleanup);
+it("confirms a return session once and creates plan checkout only on explicit selection", async () => {
+  const confirm = vi.fn().mockResolvedValue(null);
+  const createCheckout = vi.fn().mockResolvedValue({
+    stripeSessionId: "cs_plan",
+    clientSecret: "cs_plan_secret",
+  });
+  const { result, rerender } = renderHook(
+    ({ scope }) =>
+      usePlanBilling({
+        scopeKey: scope,
+        sessionId: "cs_return",
+        confirm,
+        createCheckout,
+        createPortal: async () => "https://billing.stripe.com/session",
+      }),
+    { initialProps: { scope: "seller_one" } },
+  );
+  await waitFor(() => expect(confirm).toHaveBeenCalledWith("cs_return"));
+  expect(createCheckout).not.toHaveBeenCalled();
+  await act(async () => {
+    await result.current.choose("growth");
+  });
+  expect(result.current.clientSecret).toBe("cs_plan_secret");
+  rerender({ scope: "seller_two" });
+  expect(result.current.clientSecret).toBeUndefined();
+});

package/src/react/workflows/BillingPlans.tsx

@@ -0,0 +1,130 @@
+"use client";
+import type { ReactNode } from "react";
+import { EmbeddedCheckout } from "../components/EmbeddedCheckout.js";
+import { formatPrice } from "../lib/price-helpers.js";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { useWorkflowResource } from "./useWorkflowResource.js";
+import type { CheckoutSessionResult } from "./Checkout.js";
+export type PlanBillingOptions<PlanId extends string = string> = {
+  scopeKey: string;
+  sessionId?: string | null;
+  confirm?: (sessionId: string) => Promise<unknown>;
+  createCheckout: (planId: PlanId) => Promise<CheckoutSessionResult>;
+  createPortal: () => Promise<string | { url: string }>;
+  onNavigate?: (url: string) => void;
+};
+export function usePlanBilling<PlanId extends string = string>(
+  props: PlanBillingOptions<PlanId>,
+) {
+  const confirmation = useWorkflowResource(
+    () =>
+      props.sessionId && props.confirm
+        ? props.confirm(props.sessionId)
+        : Promise.resolve(null),
+    `${props.scopeKey}:${props.sessionId ?? ""}`,
+  );
+  const action = useWorkflowAction(
+    async (
+      operation: { type: "checkout"; planId: PlanId } | { type: "portal" },
+    ) => {
+      if (operation.type === "checkout") {
+        const session = await props.createCheckout(operation.planId);
+        if (!session.clientSecret)
+          throw new Error("Stripe did not return a checkout form.");
+        return {
+          type: "checkout" as const,
+          clientSecret: session.clientSecret,
+        };
+      }
+      const result = await props.createPortal();
+      const url = typeof result === "string" ? result : result.url;
+      if (!url) throw new Error("Stripe did not return a billing portal URL.");
+      return { type: "portal" as const, url };
+    },
+    props.scopeKey,
+  );
+  return {
+    clientSecret:
+      action.result?.type === "checkout"
+        ? action.result.clientSecret
+        : undefined,
+    isPending: action.isPending,
+    error: action.error ?? confirmation.error,
+    choose: (planId: PlanId) => action.run({ type: "checkout", planId }),
+    openPortal: async () => {
+      const result = await action.run({ type: "portal" });
+      if (result?.type === "portal")
+        (props.onNavigate ?? ((url) => window.location.assign(url)))(
+          result.url,
+        );
+    },
+  };
+}
+export type BillingPlan<PlanId extends string = string> = {
+  id: PlanId;
+  name: string;
+  monthlyAmount: number;
+  currency: string;
+  description?: string;
+  feeDescription?: string;
+};
+export type BillingPlansProps<PlanId extends string = string> =
+  PlanBillingOptions<PlanId> & {
+    plans: BillingPlan<PlanId>[];
+    publishableKey: string;
+    currentPlanId?: PlanId;
+    children?: (
+      state: ReturnType<typeof usePlanBilling<PlanId>> & {
+        plans: BillingPlan<PlanId>[];
+      },
+    ) => ReactNode;
+  };
+export function BillingPlans<PlanId extends string = string>(
+  props: BillingPlansProps<PlanId>,
+) {
+  const state = usePlanBilling(props);
+  if (props.children)
+    return <>{props.children({ ...state, plans: props.plans })}</>;
+  return (
+    <section data-better-stripe="billing-plans" aria-busy={state.isPending}>
+      <h2>Billing</h2>
+      {state.error && <p role="alert">{state.error}</p>}
+      <button
+        type="button"
+        disabled={state.isPending}
+        onClick={() => {
+          void state.openPortal();
+        }}
+      >
+        {state.isPending ? "Loading…" : "Manage billing"}
+      </button>
+      {props.plans.length ? (
+        props.plans.map((plan) => (
+          <article key={plan.id}>
+            <h3>{plan.name}</h3>
+            <p>{formatPrice(plan.monthlyAmount, plan.currency)}/month</p>
+            {plan.description && <p>{plan.description}</p>}
+            {plan.feeDescription && <p>{plan.feeDescription}</p>}
+            <button
+              type="button"
+              disabled={state.isPending || plan.id === props.currentPlanId}
+              onClick={() => {
+                void state.choose(plan.id);
+              }}
+            >
+              {plan.id === props.currentPlanId ? "Current plan" : "Choose plan"}
+            </button>
+          </article>
+        ))
+      ) : (
+        <p>No billing plans configured.</p>
+      )}
+      {state.clientSecret && (
+        <EmbeddedCheckout
+          publishableKey={props.publishableKey}
+          clientSecret={state.clientSecret}
+        />
+      )}
+    </section>
+  );
+}

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