@fantastic.dev/better-stripe 0.7.0 → 0.8.1

package/src/react/index.ts

@@ -163,7 +163,10 @@ export type {
   DisputesListRow,
   DisputesListRowContext,
 } from "./components/DisputesList.js";
-export { DisputeDetail } from "./components/DisputeDetail.js";
+export {
+  DisputeDetail,
+  canRespondToDispute,
+} from "./components/DisputeDetail.js";
 export type {
   DisputeDetailProps,
   DisputeDetailRenderProps,
@@ -277,3 +280,6 @@ export {
   getRequirementKey,
   getRequirementLabel,
 } from "./lib/connect-requirement-keys.js";
+
+// Complete unstyled workflows
+export * from "./workflows/index.js";

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

@@ -0,0 +1,31 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { useAccountManager } from "./Account.js";
+afterEach(cleanup);
+it("opens an authorized dashboard link and exposes configuration failures", async () => {
+  const navigate = vi.fn();
+  const configure = vi
+    .fn()
+    .mockRejectedValue(new Error("Capability unavailable"));
+  const { result } = renderHook(() =>
+    useAccountManager({
+      scopeKey: "acct_one",
+      createDashboardLink: async () => ({
+        url: "https://connect.stripe.com/dashboard",
+      }),
+      configure,
+      onNavigate: navigate,
+    }),
+  );
+  await act(async () => {
+    await result.current.openDashboard();
+  });
+  expect(navigate).toHaveBeenCalledWith("https://connect.stripe.com/dashboard");
+  await act(async () => {
+    await result.current.configure("merchant");
+  });
+  expect(configure).toHaveBeenCalledWith("merchant");
+  expect(result.current.error).toBe("Capability unavailable");
+  expect(result.current.lastConfiguration).toBe("merchant");
+});

package/src/react/workflows/Account.tsx

@@ -0,0 +1,183 @@
+"use client";
+import { useState, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { Connect, type ConnectProps } from "./Connect.js";
+export type AccountConfiguration = "customer" | "recipient" | "merchant";
+export type AccountManagerOptions = {
+  scopeKey: string;
+  createDashboardLink?: () => Promise<{ url: string }>;
+  configure?: (configuration: AccountConfiguration) => Promise<unknown>;
+  onNavigate?: (url: string) => void;
+};
+export function useAccountManager(props: AccountManagerOptions) {
+  const [configuration, setConfiguration] =
+    useState<AccountConfiguration | null>(null);
+  const action = useWorkflowAction(
+    async (
+      command:
+        | { type: "login" }
+        | { type: "configure"; configuration: AccountConfiguration },
+    ) => {
+      if (command.type === "login") {
+        if (!props.createDashboardLink)
+          throw new Error("Dashboard access is not configured.");
+        const result = await props.createDashboardLink();
+        if (!result.url)
+          throw new Error("Stripe did not return a dashboard URL.");
+        return { type: "login" as const, url: result.url };
+      }
+      setConfiguration(command.configuration);
+      if (!props.configure)
+        throw new Error("Account configuration is not supported.");
+      await props.configure(command.configuration);
+      return {
+        type: "configure" as const,
+        configuration: command.configuration,
+      };
+    },
+    props.scopeKey,
+  );
+  return {
+    pendingConfiguration: action.isPending ? configuration : null,
+    lastConfiguration: configuration,
+    isPending: action.isPending,
+    error: action.error,
+    result: action.result,
+    openDashboard: async () => {
+      const result = await action.run({ type: "login" });
+      if (result?.type === "login")
+        (props.onNavigate ?? ((url) => window.location.assign(url)))(
+          result.url,
+        );
+    },
+    configure: (configuration: AccountConfiguration) =>
+      action.run({ type: "configure", configuration }),
+  };
+}
+export type AccountSummary = {
+  stripeAccountId: string;
+  email?: string;
+  country?: string;
+  onboardingStatus?: string;
+  configurations?: string[];
+  missingRequirements?: string[];
+};
+export type HeadlessAccountProps = AccountManagerOptions & {
+  presentation?: "headless";
+  account: AccountSummary | null | undefined;
+  children?: (
+    state: ReturnType<typeof useAccountManager> & {
+      account: AccountSummary | null | undefined;
+    },
+  ) => ReactNode;
+};
+export type AccountProps =
+  | HeadlessAccountProps
+  | (Omit<ConnectProps, "component"> & { presentation: "embedded" });
+export function Account(props: AccountProps) {
+  return props.presentation === "embedded" ? (
+    <Connect {...props} component="account" />
+  ) : (
+    <AccountBody key={props.scopeKey} {...props} />
+  );
+}
+function AccountBody(props: HeadlessAccountProps) {
+  const state = useAccountManager(props);
+  if (props.children)
+    return <>{props.children({ ...state, account: props.account })}</>;
+  if (props.account === undefined) return <p role="status">Loading account…</p>;
+  if (!props.account) return <p>No Stripe account has been set up.</p>;
+  return (
+    <section data-better-stripe="account" aria-busy={state.isPending}>
+      <h2>Account</h2>
+      <dl>
+        <dt>Account ID</dt>
+        <dd>{props.account.stripeAccountId}</dd>
+        <dt>Email</dt>
+        <dd>{props.account.email ?? "Not supplied"}</dd>
+        <dt>Country</dt>
+        <dd>{props.account.country ?? "Not supplied"}</dd>
+        <dt>Status</dt>
+        <dd>{props.account.onboardingStatus ?? "pending"}</dd>
+      </dl>
+      {state.error && <p role="alert">{state.error}</p>}
+      {props.createDashboardLink && (
+        <button
+          type="button"
+          disabled={state.isPending}
+          onClick={() => {
+            void state.openDashboard();
+          }}
+        >
+          {state.isPending ? "Opening…" : "Open Stripe dashboard"}
+        </button>
+      )}
+      <h3>Configurations</h3>
+      {props.account.configurations?.length ? (
+        <ul>
+          {props.account.configurations.map((value) => (
+            <li key={value}>{value}</li>
+          ))}
+        </ul>
+      ) : (
+        <p>No configurations yet.</p>
+      )}
+      {props.configure &&
+        (["customer", "recipient", "merchant"] as const)
+          .filter((value) => !props.account!.configurations?.includes(value))
+          .map((value) => (
+            <button
+              key={value}
+              type="button"
+              disabled={state.isPending}
+              onClick={() => {
+                void state.configure(value);
+              }}
+            >
+              Add {value} configuration
+            </button>
+          ))}
+      {!!props.account.missingRequirements?.length && (
+        <>
+          <h3>Requirements</h3>
+          <ul>
+            {props.account.missingRequirements.map((value) => (
+              <li key={value}>{value}</li>
+            ))}
+          </ul>
+        </>
+      )}
+    </section>
+  );
+}
+export type AccountConfigurationsProps = {
+  configurations: string[];
+  children?: (state: {
+    items: { key: string; label: string }[];
+    isEmpty: boolean;
+  }) => ReactNode;
+};
+export function AccountConfigurations({
+  configurations,
+  children,
+}: AccountConfigurationsProps) {
+  const labels: Record<string, string> = {
+    recipient: "Recipient (payouts)",
+    customer: "Customer (billable)",
+    merchant: "Merchant (card payments)",
+  };
+  const items = configurations.map((key) => ({
+    key,
+    label: labels[key] ?? key,
+  }));
+  if (children) return <>{children({ items, isEmpty: !items.length })}</>;
+  return items.length ? (
+    <ul data-better-stripe="account-configurations">
+      {items.map((item) => (
+        <li key={item.key}>{item.label}</li>
+      ))}
+    </ul>
+  ) : (
+    <p>No configurations yet.</p>
+  );
+}

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

@@ -0,0 +1,45 @@
+// @vitest-environment jsdom
+import {
+  act,
+  cleanup,
+  renderHook,
+  render,
+  screen,
+} from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import { useBalanceFunding, InvoiceEstimate } from "./Billing.js";
+afterEach(cleanup);
+it("requires explicit consent before enabling balance payments", async () => {
+  const change = vi.fn().mockResolvedValue(null);
+  const { result } = renderHook(() =>
+    useBalanceFunding({ scopeKey: "seller", change }),
+  );
+  await act(async () => {
+    await result.current.confirm(true);
+  });
+  expect(change).not.toHaveBeenCalled();
+  expect(result.current.error).toContain("consent");
+  act(() => result.current.setConsent(true));
+  await act(async () => {
+    await result.current.confirm(true);
+  });
+  expect(change).toHaveBeenCalledWith({ enabled: true, consent: true });
+  expect(result.current.consent).toBe(false);
+});
+it("loads an itemized estimate only when requested and displays the server total", async () => {
+  const load = vi.fn().mockResolvedValue({
+    currency: "usd",
+    total: 3700,
+    nextBillingAt: 1800000000000,
+    lines: [
+      { id: "plan", description: "Store plan", amount: 2900 },
+      { id: "cost", description: "Refund costs", amount: 800 },
+    ],
+  });
+  render(<InvoiceEstimate scopeKey="seller" load={load} />);
+  expect(load).not.toHaveBeenCalled();
+  await userEvent.click(screen.getByRole("button", { name: "View estimate" }));
+  await screen.findByText("$37.00");
+  expect(screen.getByText("Refund costs")).toBeTruthy();
+});

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