@fantastic.dev/better-stripe 0.6.1 → 0.8.0

package/src/react/components/EvidenceForm.render.test.tsx

@@ -19,10 +19,7 @@ import { renderToStaticMarkup } from "react-dom/server";
 import { describe, expect, it, vi } from "vitest";
 
 import { EvidenceForm as BarrelExport } from "../index.js";
-import {
-  EvidenceForm,
-  type EvidenceFormRenderProps,
-} from "./EvidenceForm.js";
+import { EvidenceForm, type EvidenceFormRenderProps } from "./EvidenceForm.js";
 
 const allFields = {
   productDescription: "Ceramics Masterclass, lifetime access",
@@ -33,10 +30,7 @@ const allFields = {
 
 /** Render via the children prop and hand back the captured render props. */
 function capture(
-  props: Omit<
-    Parameters<typeof EvidenceForm>[0],
-    "children"
-  >,
+  props: Omit<Parameters<typeof EvidenceForm>[0], "children">,
 ): EvidenceFormRenderProps {
   let received: EvidenceFormRenderProps | undefined;
   renderToStaticMarkup(

package/src/react/components/SplitBreakdown.render.test.tsx

@@ -34,8 +34,18 @@ const leg = (over: Record<string, unknown>) => ({
 
 const totals = {
   legs: [
-    leg({ stripeTransferId: "tr_store", role: "store", amount: 8000, net: 8000 }),
-    leg({ stripeTransferId: "tr_aff", role: "affiliate", amount: 1000, net: 1000 }),
+    leg({
+      stripeTransferId: "tr_store",
+      role: "store",
+      amount: 8000,
+      net: 8000,
+    }),
+    leg({
+      stripeTransferId: "tr_aff",
+      role: "affiliate",
+      amount: 1000,
+      net: 1000,
+    }),
   ],
   store: 8000,
   affiliate: 1000,
@@ -79,7 +89,10 @@ describe("SplitBreakdown", () => {
       createElement(SplitBreakdown, {
         breakdown: {
           ...totals,
-          legs: [...totals.legs, leg({ stripeTransferId: "tr_misc", amount: 500, net: 500 })],
+          legs: [
+            ...totals.legs,
+            leg({ stripeTransferId: "tr_misc", amount: 500, net: 500 }),
+          ],
           other: 500,
           recipientsTotal: 9500,
           platform: 500,
@@ -136,8 +149,18 @@ describe("SplitBreakdown", () => {
     expect(received!.breakdown).toBe(totals);
     expect(received!.lines).toEqual([
       { key: "store", label: "Store", amount: 8000, amountLabel: "$80.00" },
-      { key: "affiliate", label: "Affiliate", amount: 1000, amountLabel: "$10.00" },
-      { key: "platform", label: "Platform", amount: 1000, amountLabel: "$10.00" },
+      {
+        key: "affiliate",
+        label: "Affiliate",
+        amount: 1000,
+        amountLabel: "$10.00",
+      },
+      {
+        key: "platform",
+        label: "Platform",
+        amount: 1000,
+        amountLabel: "$10.00",
+      },
     ]);
     expect(html).toBe("<p>3</p>");
   });

package/src/react/components/SplitBreakdown.tsx

@@ -75,7 +75,11 @@ export function SplitBreakdown({
   const money = (amount: number) => formatPrice(amount, currency, locale);
 
   const lines: SplitBreakdownLine[] = [
-    { key: "store" as const, label: labels?.store ?? "Store", amount: breakdown.store },
+    {
+      key: "store" as const,
+      label: labels?.store ?? "Store",
+      amount: breakdown.store,
+    },
     {
       key: "affiliate" as const,
       label: labels?.affiliate ?? "Affiliate",
@@ -83,7 +87,13 @@ export function SplitBreakdown({
     },
     // The catch-all bucket only earns a line when it carries money.
     ...(breakdown.other > 0
-      ? [{ key: "other" as const, label: labels?.other ?? "Other", amount: breakdown.other }]
+      ? [
+          {
+            key: "other" as const,
+            label: labels?.other ?? "Other",
+            amount: breakdown.other,
+          },
+        ]
       : []),
     {
       key: "platform" as const,

package/src/react/hooks/useCheckoutSession.ts

@@ -14,8 +14,7 @@ function extractErrorMessage(error: unknown, fallback: string): string {
  * Result of a checkout confirmation attempt.
  */
 export type CheckoutConfirmResult =
-  | { type: "success" }
-  | { type: "error"; message: string };
+  { type: "success" } | { type: "error"; message: string };
 
 /**
  * Checkout session state and actions.

package/src/react/hooks/useConfirmPayment.ts

@@ -8,8 +8,7 @@ import { useElements, useStripe } from "@stripe/react-stripe-js";
  * Normalized result from a Stripe confirmation operation.
  */
 export type StripeConfirmResult =
-  | { success: true }
-  | { success: false; error: string };
+  { success: true } | { success: false; error: string };
 
 /**
  * Hook for confirming a PaymentIntent (immediate charge) or SetupIntent (future charge / trial).

package/src/react/hooks/useEarnings.test.ts

@@ -48,8 +48,20 @@ const earningsResult = {
 };
 
 const previewPayouts = [
-  { stripePayoutId: "po_1", accountId: "acct_store", amount: 4000, currency: "usd", status: "paid" },
-  { stripePayoutId: "po_2", accountId: "acct_store", amount: 1500, currency: "usd", status: "pending" },
+  {
+    stripePayoutId: "po_1",
+    accountId: "acct_store",
+    amount: 4000,
+    currency: "usd",
+    status: "paid",
+  },
+  {
+    stripePayoutId: "po_2",
+    accountId: "acct_store",
+    amount: 1500,
+    currency: "usd",
+    status: "pending",
+  },
 ];
 
 const payoutsResult = {
@@ -70,7 +82,11 @@ describe("createUseEarnings", () => {
         [payoutsRef, payoutsResult],
       ]),
     );
-    const useEarnings = createUseEarnings(mockUseQuery, earningsRef, payoutsRef);
+    const useEarnings = createUseEarnings(
+      mockUseQuery,
+      earningsRef,
+      payoutsRef,
+    );
 
     const result = useEarnings("acct_store");
 
@@ -92,7 +108,11 @@ describe("createUseEarnings", () => {
         [payoutsRef, payoutsResult],
       ]),
     );
-    const useEarnings = createUseEarnings(mockUseQuery, earningsRef, payoutsRef);
+    const useEarnings = createUseEarnings(
+      mockUseQuery,
+      earningsRef,
+      payoutsRef,
+    );
 
     const result = useEarnings("acct_store");
 
@@ -111,7 +131,11 @@ describe("createUseEarnings", () => {
         [payoutsRef, undefined],
       ]),
     );
-    const useEarnings = createUseEarnings(mockUseQuery, earningsRef, payoutsRef);
+    const useEarnings = createUseEarnings(
+      mockUseQuery,
+      earningsRef,
+      payoutsRef,
+    );
 
     const result = useEarnings("acct_store");
 
@@ -125,7 +149,11 @@ describe("createUseEarnings", () => {
 
   it("skips both queries when the account id is undefined", () => {
     const mockUseQuery = useQueryFor(new Map());
-    const useEarnings = createUseEarnings(mockUseQuery, earningsRef, payoutsRef);
+    const useEarnings = createUseEarnings(
+      mockUseQuery,
+      earningsRef,
+      payoutsRef,
+    );
 
     const result = useEarnings(undefined);
 
@@ -143,11 +171,18 @@ describe("createUseEarnings", () => {
   it("treats empty ledgers as loaded with zero totals", () => {
     const mockUseQuery = useQueryFor(
       new Map<unknown, unknown>([
-        [earningsRef, { gross: 0, reversed: 0, transferCount: 0, transfers: [] }],
+        [
+          earningsRef,
+          { gross: 0, reversed: 0, transferCount: 0, transfers: [] },
+        ],
         [payoutsRef, { paidOut: 0, payoutCount: 0, payouts: [] }],
       ]),
     );
-    const useEarnings = createUseEarnings(mockUseQuery, earningsRef, payoutsRef);
+    const useEarnings = createUseEarnings(
+      mockUseQuery,
+      earningsRef,
+      payoutsRef,
+    );
 
     const result = useEarnings("acct_new");
 

package/src/react/hooks/useStripeMode.test.ts

@@ -28,16 +28,13 @@ describe("useStripeMode", () => {
     expect(useQueryMock).toHaveBeenCalledWith(mockQueryRef, {});
   });
 
-  it.each(["test", "live"] as const)(
-    "returns the resolved %s mode",
-    (mode) => {
-      useQueryMock.mockReturnValue(mode);
+  it.each(["test", "live"] as const)("returns the resolved %s mode", (mode) => {
+    useQueryMock.mockReturnValue(mode);
 
-      const result = useStripeMode(mockQueryRef);
+    const result = useStripeMode(mockQueryRef);
 
-      expect(result).toBe(mode);
-    },
-  );
+    expect(result).toBe(mode);
+  });
 
   it("returns undefined while the query is still loading", () => {
     useQueryMock.mockReturnValue(undefined);

package/src/react/index.ts

@@ -277,3 +277,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();
+});