@fantastic.dev/better-stripe 0.7.0 → 0.8.0

package/src/react/workflows/Disputes.tsx

@@ -0,0 +1,164 @@
+"use client";
+import { useState, type ReactNode } from "react";
+import {
+  DisputesList,
+  type DisputesListRow,
+} from "../components/DisputesList.js";
+import { DisputeDetail } from "../components/DisputeDetail.js";
+import {
+  EvidenceForm,
+  type EvidenceFormUpdateArgs,
+} from "../components/EvidenceForm.js";
+import type { DisputeWithCountdown } from "../hooks/useDisputeWithCountdown.js";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { Connect, type ConnectProps } from "./Connect.js";
+export type DisputeResponseOptions = {
+  scopeKey: string;
+  acceptDispute?: (stripeDisputeId: string) => Promise<unknown>;
+  onSelectionChange?: (id: string | undefined) => void;
+};
+export function useDisputeResponse(props: DisputeResponseOptions) {
+  const initial = {
+    scope: props.scopeKey,
+    selectedId: undefined as string | undefined,
+    confirming: false,
+  };
+  const [state, setState] = useState(initial);
+  if (state.scope !== props.scopeKey) setState(initial);
+  const action = useWorkflowAction(
+    async () => {
+      if (!state.selectedId || !state.confirming)
+        throw new Error("Confirm accepting this dispute first.");
+      if (!props.acceptDispute)
+        throw new Error("Dispute acceptance is not configured.");
+      await props.acceptDispute(state.selectedId);
+      return true;
+    },
+    `${props.scopeKey}:${state.selectedId ?? ""}`,
+  );
+  return {
+    selectedId: state.selectedId,
+    setSelectedId: (selectedId: string | undefined) => {
+      setState((previous) => ({ ...previous, selectedId, confirming: false }));
+      props.onSelectionChange?.(selectedId);
+      action.reset();
+    },
+    acceptStatus: action.isPending
+      ? ("submitting" as const)
+      : action.result
+        ? ("accepted" as const)
+        : action.error
+          ? ("error" as const)
+          : state.confirming
+            ? ("confirming" as const)
+            : ("idle" as const),
+    acceptError: action.error,
+    isPending: action.isPending,
+    requestAccept: () => {
+      action.reset();
+      setState((previous) => ({ ...previous, confirming: true }));
+    },
+    cancelAccept: () => {
+      action.reset();
+      setState((previous) => ({ ...previous, confirming: false }));
+    },
+    accept: action.run,
+  };
+}
+export type DisputesRenderProps = ReturnType<typeof useDisputeResponse> & {
+  disputes: DisputesListRow[] | undefined;
+  detail: DisputeWithCountdown | null | undefined;
+};
+export type HeadlessDisputesProps = DisputeResponseOptions & {
+  presentation?: "headless";
+  disputes: DisputesListRow[] | undefined;
+  detail?: DisputeWithCountdown | null;
+  onUpdateEvidence: (args: EvidenceFormUpdateArgs) => Promise<unknown>;
+  children?: (state: DisputesRenderProps) => ReactNode;
+};
+export type DisputesProps =
+  | HeadlessDisputesProps
+  | (Omit<ConnectProps, "component"> & { presentation: "embedded" });
+export function Disputes(props: DisputesProps) {
+  return props.presentation === "embedded" ? (
+    <Connect {...props} component="disputes" />
+  ) : (
+    <DisputesBody key={props.scopeKey} {...props} />
+  );
+}
+function DisputesBody(props: HeadlessDisputesProps) {
+  const state = useDisputeResponse(props);
+  const detail =
+    props.detail?.stripeDisputeId === state.selectedId
+      ? props.detail
+      : undefined;
+  if (props.children)
+    return (
+      <>{props.children({ ...state, disputes: props.disputes, detail })}</>
+    );
+  return (
+    <section data-better-stripe="disputes">
+      <h2>Disputes</h2>
+      <DisputesList
+        disputes={props.disputes}
+        isLoading={props.disputes === undefined}
+        renderRow={(row) => (
+          <button
+            key={row.dispute.stripeDisputeId}
+            type="button"
+            aria-pressed={state.selectedId === row.dispute.stripeDisputeId}
+            onClick={() => state.setSelectedId(row.dispute.stripeDisputeId)}
+          >
+            {row.dispute.stripeDisputeId} · {row.dispute.status} {row.badgeText}
+          </button>
+        )}
+      />
+      {!state.selectedId ? (
+        <p>Select a dispute to respond.</p>
+      ) : (
+        <>
+          <DisputeDetail dispute={detail} isLoading={!detail} />
+          {props.acceptDispute &&
+            (state.acceptStatus === "confirming" ? (
+              <div>
+                <p>
+                  Accepting permanently closes this dispute. This cannot be
+                  undone.
+                </p>
+                <button
+                  type="button"
+                  disabled={state.isPending}
+                  onClick={() => {
+                    void state.accept();
+                  }}
+                >
+                  Yes, accept dispute
+                </button>
+                <button type="button" onClick={state.cancelAccept}>
+                  Cancel
+                </button>
+              </div>
+            ) : (
+              <button
+                type="button"
+                disabled={state.isPending || state.acceptStatus === "accepted"}
+                onClick={state.requestAccept}
+              >
+                {state.isPending
+                  ? "Accepting…"
+                  : state.acceptStatus === "accepted"
+                    ? "Dispute accepted"
+                    : "Accept dispute"}
+              </button>
+            ))}
+          {state.acceptError && <p role="alert">{state.acceptError}</p>}
+          <EvidenceForm
+            key={state.selectedId}
+            stripeDisputeId={state.selectedId}
+            onUpdateDispute={props.onUpdateEvidence}
+          />
+        </>
+      )}
+    </section>
+  );
+}

package/src/react/workflows/Earnings.test.ts

@@ -0,0 +1,19 @@
+import { expect, it } from "vitest";
+import { earningsFromBalance } from "./Earnings.js";
+it("keeps currencies separate and includes only completed payouts in recipient totals", () => {
+  const result = earningsFromBalance(
+    { available: 1200, pending: 300, currency: "usd" },
+    [
+      { amount: 500, status: "paid", currency: "usd" },
+      { amount: 9000, status: "paid", currency: "eur" },
+      { amount: 200, status: "pending", currency: "usd" },
+    ],
+  );
+  expect(result).toEqual({
+    gross: 2000,
+    net: 2000,
+    reversed: 0,
+    paidOut: 500,
+    currency: "usd",
+  });
+});

package/src/react/workflows/Earnings.tsx

@@ -0,0 +1,84 @@
+"use client";
+import type { ReactNode } from "react";
+import {
+  EarningsSummary,
+  type EarningsSummaryProps,
+} from "../components/EarningsSummary.js";
+import { formatPrice } from "../lib/price-helpers.js";
+import { Connect, type ConnectProps } from "./Connect.js";
+export type BalanceSnapshot = {
+  available: number;
+  pending: number;
+  currency: string;
+};
+export type StoreEarnings = {
+  gross: number;
+  reversed: number;
+  net: number;
+  paidOut: number;
+  currency: string;
+};
+/** Recipient funds held plus already paid out, not gross charge revenue. Destination-charge balance display only. */
+export function earningsFromBalance(
+  balance: BalanceSnapshot | null,
+  payouts: { amount: number; status: string; currency: string }[],
+): StoreEarnings {
+  const currency = balance?.currency ?? payouts[0]?.currency ?? "usd";
+  const paidOut = payouts
+    .filter((row) => row.currency === currency && row.status === "paid")
+    .reduce((sum, row) => sum + row.amount, 0);
+  const gross = (balance ? balance.available + balance.pending : 0) + paidOut;
+  return { gross, reversed: 0, net: gross, paidOut, currency };
+}
+export type EarningsMetric = {
+  key: "gross" | "reversed" | "net" | "paidOut";
+  label: string;
+  amount: number;
+  formattedValue: string;
+};
+export type EarningsRenderProps = {
+  metrics: EarningsMetric[];
+  isLoading: boolean;
+  currency: string;
+  payouts: EarningsSummaryProps["payouts"];
+};
+export type HeadlessEarningsProps = Omit<EarningsSummaryProps, "children"> & {
+  presentation?: "headless";
+  children?: (state: EarningsRenderProps) => ReactNode;
+};
+export type EarningsProps =
+  | HeadlessEarningsProps
+  | (Omit<ConnectProps, "component"> & { presentation: "embedded" });
+export function Earnings(props: EarningsProps) {
+  if (props.presentation === "embedded")
+    return <Connect {...props} component="balances" />;
+  const { children, ...summary } = props;
+  const currency = props.currency ?? "usd";
+  const metrics: EarningsMetric[] = (
+    [
+      ["gross", "Gross"],
+      ["reversed", "Reversals & adjustments"],
+      ["net", "Net"],
+      ["paidOut", "Paid out"],
+    ] as const
+  ).map(([key, label]) => ({
+    key,
+    label: props.labels?.[key] ?? label,
+    amount: props[key],
+    formattedValue: formatPrice(props[key], currency, props.locale),
+  }));
+  return (
+    <>
+      {children ? (
+        children({
+          metrics,
+          isLoading: props.isLoading ?? false,
+          currency,
+          payouts: props.payouts,
+        })
+      ) : (
+        <EarningsSummary {...summary} />
+      )}
+    </>
+  );
+}

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

@@ -0,0 +1,35 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, expect, it } from "vitest";
+import { ChargeSummary, PaymentDetails } from "./Financials.js";
+afterEach(cleanup);
+it("displays server-authoritative destination-charge amounts and reconciliation status", () => {
+  render(
+    <ChargeSummary
+      gross={10000}
+      fee={900}
+      net={9100}
+      currency="usd"
+      reconciles={false}
+    />,
+  );
+  expect(screen.getByText("$91.00")).toBeTruthy();
+  expect(screen.getByRole("alert").textContent).toContain("does not reconcile");
+});
+it("shows recorded payment refund state, including a failed refund", () => {
+  const { rerender } = render(<PaymentDetails payment={undefined} />);
+  expect(screen.getByRole("status")).toBeTruthy();
+  rerender(
+    <PaymentDetails
+      payment={{
+        amount: 1000,
+        currency: "usd",
+        status: "succeeded",
+        refundedAmount: 200,
+        refundStatus: "failed",
+      }}
+    />,
+  );
+  expect(screen.getByText("$2.00")).toBeTruthy();
+  expect(screen.getByText("failed")).toBeTruthy();
+});

package/src/react/workflows/Financials.tsx

@@ -0,0 +1,117 @@
+"use client";
+import type { ReactNode } from "react";
+import { formatPrice } from "../lib/price-helpers.js";
+export type ChargeSummaryProps = {
+  gross: number;
+  fee: number;
+  net: number;
+  currency: string;
+  reconciles: boolean;
+  feeLabel?: string;
+  children?: (state: {
+    metrics: {
+      key: "gross" | "fee" | "net";
+      label: string;
+      amount: number;
+      formattedAmount: string;
+    }[];
+    reconciles: boolean;
+  }) => ReactNode;
+};
+/** Displays a server-calculated charge allocation, without applying a platform fee policy. */
+export function ChargeSummary(props: ChargeSummaryProps) {
+  const metrics = (
+    [
+      ["gross", "Charged"],
+      ["fee", props.feeLabel ?? "Platform fee"],
+      ["net", "Seller payout"],
+    ] as const
+  ).map(([key, label]) => ({
+    key,
+    label,
+    amount: props[key],
+    formattedAmount: formatPrice(props[key], props.currency),
+  }));
+  if (props.children)
+    return <>{props.children({ metrics, reconciles: props.reconciles })}</>;
+  return (
+    <section data-better-stripe="charge-summary">
+      <h2>Charge breakdown</h2>
+      <dl>
+        {metrics.map((metric) => (
+          <div key={metric.key}>
+            <dt>{metric.label}</dt>
+            <dd>{metric.formattedAmount}</dd>
+          </div>
+        ))}
+      </dl>
+      <p role={props.reconciles ? "status" : "alert"}>
+        {props.reconciles
+          ? "Fee and seller payout reconcile to the charge amount."
+          : "Breakdown does not reconcile to the charge amount."}
+      </p>
+    </section>
+  );
+}
+export type PaymentDetailsPayment = {
+  amount: number;
+  currency: string;
+  status: string;
+  refundedAmount?: number;
+  refundStatus?: string;
+};
+export type PaymentDetailsState = {
+  payment: PaymentDetailsPayment | null | undefined;
+  isLoading: boolean;
+  isEmpty: boolean;
+  metrics: {
+    key: "charged" | "refunded" | "status" | "refundStatus";
+    label: string;
+    value: string;
+  }[];
+};
+export type PaymentDetailsProps = {
+  payment: PaymentDetailsPayment | null | undefined;
+  children?: (state: PaymentDetailsState) => ReactNode;
+};
+export function PaymentDetails({ payment, children }: PaymentDetailsProps) {
+  const metrics: PaymentDetailsState["metrics"] = payment
+    ? [
+        {
+          key: "charged",
+          label: "Charged",
+          value: formatPrice(payment.amount, payment.currency),
+        },
+        {
+          key: "refunded",
+          label: "Refunded",
+          value: formatPrice(payment.refundedAmount ?? 0, payment.currency),
+        },
+        { key: "status", label: "Status", value: payment.status },
+        {
+          key: "refundStatus",
+          label: "Refund state",
+          value: payment.refundStatus ?? "none",
+        },
+      ]
+    : [];
+  const state = {
+    payment,
+    metrics,
+    isLoading: payment === undefined,
+    isEmpty: payment === null,
+  };
+  if (children) return <>{children(state)}</>;
+  if (state.isLoading) return <p role="status">Loading payment…</p>;
+  if (state.isEmpty) return <p>No payment found.</p>;
+  return (
+    <dl data-better-stripe="payment-details">
+      {metrics.map((metric) => (
+        <div key={metric.key}>
+          <dt>{metric.label}</dt>
+          <dd>{metric.value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}

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

@@ -0,0 +1,36 @@
+// @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 { IntegrationSwitch } from "./IntegrationSwitch.js";
+afterEach(cleanup);
+it("mounts only the selected integration and falls back when a requested mode is unsupported", async () => {
+  const mount = vi.fn();
+  function Embedded() {
+    mount();
+    return <p>Stripe component</p>;
+  }
+  render(
+    <IntegrationSwitch
+      value="hosted"
+      views={{ headless: <p>API controls</p>, embedded: <Embedded /> }}
+    />,
+  );
+  expect(screen.getByText("API controls")).toBeTruthy();
+  expect(mount).not.toHaveBeenCalled();
+});
+it("allows an uncontrolled choice without requiring a router", async () => {
+  render(
+    <IntegrationSwitch
+      views={{
+        headless: <p>API controls</p>,
+        embedded: <p>Stripe component</p>,
+      }}
+    />,
+  );
+  await userEvent.click(
+    screen.getByRole("button", { name: "Stripe embedded" }),
+  );
+  expect(screen.getByText("Stripe component")).toBeTruthy();
+  expect(screen.queryByText("API controls")).toBeNull();
+});

package/src/react/workflows/IntegrationSwitch.tsx

@@ -0,0 +1,63 @@
+"use client";
+import { useState, type ReactNode } from "react";
+export type IntegrationMode = "headless" | "components" | "embedded" | "hosted";
+const labels: Record<IntegrationMode, string> = {
+  headless: "Headless",
+  components: "Components",
+  embedded: "Stripe embedded",
+  hosted: "Stripe hosted",
+};
+export type IntegrationSwitchState = {
+  value: IntegrationMode;
+  select: (mode: IntegrationMode) => void;
+  options: { value: IntegrationMode; label: string }[];
+  content: ReactNode;
+};
+export type IntegrationSwitchProps = {
+  views: Partial<Record<IntegrationMode, ReactNode>> & { headless: ReactNode };
+  value?: IntegrationMode;
+  defaultValue?: IntegrationMode;
+  onValueChange?: (mode: IntegrationMode) => void;
+  children?: (state: IntegrationSwitchState) => ReactNode;
+};
+/** Only the active integration is mounted. No router or styling dependencies. */
+export function IntegrationSwitch({
+  views,
+  value,
+  defaultValue = "headless",
+  onValueChange,
+  children,
+}: IntegrationSwitchProps) {
+  const [internal, setInternal] = useState(defaultValue);
+  const options = (Object.keys(labels) as IntegrationMode[])
+    .filter((mode) => views[mode] !== undefined && views[mode] !== null)
+    .map((value) => ({ value, label: labels[value] }));
+  const requested = value ?? internal;
+  const selected = options.some((option) => option.value === requested)
+    ? requested
+    : "headless";
+  const select = (mode: IntegrationMode) => {
+    if (!options.some((option) => option.value === mode)) return;
+    setInternal(mode);
+    onValueChange?.(mode);
+  };
+  const state = { value: selected, select, options, content: views[selected] };
+  if (children) return <>{children(state)}</>;
+  return (
+    <div data-better-stripe="integration-switch">
+      <div role="group" aria-label="Integration examples">
+        {options.map((option) => (
+          <button
+            key={option.value}
+            type="button"
+            aria-pressed={selected === option.value}
+            onClick={() => select(option.value)}
+          >
+            {option.label}
+          </button>
+        ))}
+      </div>
+      {state.content}
+    </div>
+  );
+}

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

@@ -0,0 +1,75 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { useOnboarding } from "./Onboarding.js";
+afterEach(cleanup);
+it("creates an account for the selected country and exposes a hosted link failure", async () => {
+  const createAccount = vi
+    .fn()
+    .mockResolvedValue({ onboardingUrl: "https://connect.stripe.com/setup" });
+  const continueOnboarding = vi
+    .fn()
+    .mockRejectedValue(new Error("Account restricted"));
+  const navigate = vi.fn();
+  const { result } = renderHook(() =>
+    useOnboarding({
+      scopeKey: "seller",
+      createAccount,
+      continueOnboarding,
+      onNavigate: navigate,
+    }),
+  );
+  act(() => result.current.setSelectedCountry("GB"));
+  await act(async () => {
+    await result.current.create();
+  });
+  expect(createAccount).toHaveBeenCalledWith("GB");
+  expect(navigate).toHaveBeenCalledWith("https://connect.stripe.com/setup");
+  await act(async () => {
+    await result.current.continue();
+  });
+  expect(result.current.linkError).toBe("Account restricted");
+});
+
+it("keeps onboarding link failures associated with the active operation", async () => {
+  let fail!: (error: Error) => void;
+  const createAccount = vi.fn();
+  const { result } = renderHook(() =>
+    useOnboarding({
+      scopeKey: "seller",
+      createAccount,
+      continueOnboarding: () =>
+        new Promise<{ url: string }>((_, reject) => {
+          fail = reject;
+        }),
+    }),
+  );
+  let pending!: Promise<unknown>;
+  act(() => {
+    pending = result.current.continue();
+  });
+  await act(async () => {
+    await result.current.create();
+  });
+  expect(result.current.isLinking).toBe(true);
+  expect(createAccount).not.toHaveBeenCalled();
+  await act(async () => {
+    fail(new Error("Link unavailable"));
+    await pending;
+  });
+  expect(result.current.linkError).toBe("Link unavailable");
+  expect(result.current.createError).toBeNull();
+});
+it("offers the shared example countries in the native onboarding UI", async () => {
+  const { render, screen } = await import("@testing-library/react");
+  const { Onboarding } = await import("./Onboarding.js");
+  render(
+    <Onboarding
+      scopeKey="store"
+      account={null}
+      createAccount={async () => ({})}
+      continueOnboarding={async () => ({})}
+    />,
+  );
+  expect(screen.getByRole("option", { name: "United Kingdom" })).toBeTruthy();
+});