@fantastic.dev/better-stripe 0.7.0 → 0.8.0

package/src/react/workflows/Tasks.tsx

@@ -0,0 +1,199 @@
+"use client";
+import { useId, useState, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+export type WorkflowLogEntry = {
+  id: number;
+  timestamp: string;
+  action: string;
+  result: string;
+  status: "success" | "error";
+};
+export type TaskRunnerOptions = {
+  scopeKey?: string;
+  maxEntries?: number;
+  /** Explicitly select safe fields for display. Default never serializes returned secrets. */ formatResult?: (
+    value: unknown,
+  ) => string;
+};
+export function useTaskRunner({
+  scopeKey = "tasks",
+  maxEntries = 100,
+  formatResult = () => "Completed",
+}: TaskRunnerOptions = {}) {
+  const initial = {
+    scope: scopeKey,
+    log: [] as WorkflowLogEntry[],
+    results: {} as Record<string, string>,
+    errors: {} as Record<string, string>,
+  };
+  const [state, setState] = useState(initial);
+  if (state.scope !== scopeKey) setState(initial);
+  const [pendingOperation, setPendingOperation] = useState<string | null>(null);
+  const operation = useWorkflowAction(
+    async (name: string, task: () => Promise<unknown>) => {
+      setPendingOperation(name);
+      try {
+        return {
+          name,
+          status: "success" as const,
+          value: await task(),
+          error: null,
+        };
+      } catch (error) {
+        return {
+          name,
+          status: "error" as const,
+          value: undefined,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    },
+    scopeKey,
+  );
+  const run = async <T,>(
+    name: string,
+    task: () => Promise<T>,
+  ): Promise<T | undefined> => {
+    const result = await operation.run(name, task);
+    if (!result) return undefined;
+    let message: string;
+    try {
+      message =
+        result.status === "error" ? result.error! : formatResult(result.value);
+    } catch {
+      message = "Completed";
+    }
+    setState((previous) => ({
+      ...previous,
+      log: [
+        {
+          id: (previous.log[0]?.id ?? 0) + 1,
+          timestamp: new Date().toLocaleTimeString(),
+          action: name,
+          result: message,
+          status: result.status,
+        },
+        ...previous.log,
+      ].slice(0, Math.max(1, maxEntries)),
+      results:
+        result.status === "success"
+          ? { ...previous.results, [name]: message }
+          : previous.results,
+      errors: {
+        ...previous.errors,
+        [name]: result.status === "error" ? message : "",
+      },
+    }));
+    return result.status === "success" ? (result.value as T) : undefined;
+  };
+  return {
+    log: state.log,
+    results: state.results,
+    errors: state.errors,
+    isPending: operation.isPending,
+    pendingOperation: operation.isPending ? pendingOperation : null,
+    run,
+    appendLog: (
+      action: string,
+      result: string,
+      status: "success" | "error" = "success",
+    ) =>
+      setState((previous) => ({
+        ...previous,
+        log: [
+          {
+            id: (previous.log[0]?.id ?? 0) + 1,
+            timestamp: new Date().toLocaleTimeString(),
+            action,
+            result,
+            status,
+          },
+          ...previous.log,
+        ].slice(0, Math.max(1, maxEntries)),
+      })),
+    clearLog: () => setState((previous) => ({ ...previous, log: [] })),
+  };
+}
+export type WorkflowTask = {
+  id: string;
+  label: string;
+  description?: string;
+  run: () => Promise<unknown>;
+  requiresConfirmation?: boolean;
+};
+export type WorkflowTasksProps = TaskRunnerOptions & {
+  title?: string;
+  tasks: WorkflowTask[];
+  children?: (state: ReturnType<typeof useTaskRunner>) => ReactNode;
+};
+/** Unstyled administration/sandbox operations. Authorization and test-mode enforcement belong to the server callbacks. */
+export function WorkflowTasks(props: WorkflowTasksProps) {
+  const state = useTaskRunner(props);
+  const [confirmed, setConfirmed] = useState<Record<string, boolean>>({});
+  const id = useId();
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <section data-better-stripe="workflow-tasks" aria-busy={state.isPending}>
+      <h2>{props.title ?? "Stripe operations"}</h2>
+      {props.tasks.map((task) => (
+        <div key={task.id}>
+          <h3>{task.label}</h3>
+          {task.description && <p>{task.description}</p>}
+          {task.requiresConfirmation && (
+            <label htmlFor={`${id}-${task.id}`}>
+              <input
+                id={`${id}-${task.id}`}
+                type="checkbox"
+                checked={!!confirmed[task.id]}
+                onChange={(event) =>
+                  setConfirmed((previous) => ({
+                    ...previous,
+                    [task.id]: event.target.checked,
+                  }))
+                }
+              />
+              I understand and confirm this action.
+            </label>
+          )}
+          <button
+            type="button"
+            disabled={
+              state.isPending ||
+              (task.requiresConfirmation && !confirmed[task.id])
+            }
+            onClick={() => {
+              void state.run(task.id, task.run);
+            }}
+          >
+            {state.pendingOperation === task.id ? "Processing…" : task.label}
+          </button>
+          {state.errors[task.id] ? (
+            <p role="alert">{state.errors[task.id]}</p>
+          ) : (
+            state.results[task.id] && (
+              <p role="status">{state.results[task.id]}</p>
+            )
+          )}
+        </div>
+      ))}
+      <h3>Activity</h3>
+      {!state.log.length ? (
+        <p>No operations yet.</p>
+      ) : (
+        <ol>
+          {state.log.map((entry) => (
+            <li key={entry.id}>
+              {entry.timestamp} · {entry.action} · {entry.result}
+            </li>
+          ))}
+        </ol>
+      )}
+    </section>
+  );
+}
+export function StripeSetup(props: Omit<WorkflowTasksProps, "title">) {
+  return <WorkflowTasks {...props} title="Stripe setup" />;
+}
+export function SandboxTesting(props: Omit<WorkflowTasksProps, "title">) {
+  return <WorkflowTasks {...props} title="Sandbox testing" />;
+}

package/src/react/workflows/checkout-options.ts

@@ -0,0 +1,42 @@
+export const CHECKOUT_OPTIONS = [
+  {
+    id: "redirect",
+    title: "Hosted Checkout",
+    api: "Checkout Sessions",
+    pros: "Fastest setup. Stripe owns the payment page, order summary, subscriptions, and payment-method UI.",
+    cons: "Redirects away from your app. Layout customization is limited.",
+    docs: "https://docs.stripe.com/payments/checkout",
+  },
+  {
+    id: "embedded",
+    title: "Embedded Checkout",
+    api: "Checkout Sessions · embedded_page",
+    pros: "Stripe's complete checkout stays inside your app. Less custom checkout code to maintain.",
+    cons: "Stripe controls the form layout. The page embeds a Stripe iframe.",
+    docs: "https://docs.stripe.com/payments/checkout",
+  },
+  {
+    id: "custom",
+    title: "Payment Element + Checkout Sessions",
+    api: "Checkout Sessions · elements",
+    pros: "Custom page layout with Stripe handling the checkout session and payment state. Recommended for most custom checkouts.",
+    cons: "You build the order summary, form controls, and confirmation UI.",
+    docs: "https://docs.stripe.com/payments/payment-element",
+  },
+  {
+    id: "payment-intent",
+    title: "Payment Element + Payment Intents",
+    api: "Payment Intents · Stripe.js",
+    pros: "Low-level control over the payment lifecycle, capture, and your own checkout state.",
+    cons: "You build pricing, tax, shipping, discounts, and subscription orchestration. This example supports one-time purchases.",
+    docs: "https://docs.stripe.com/payments/payment-intents",
+  },
+  {
+    id: "form",
+    title: "Embedded Checkout Form",
+    api: "Checkout Sessions · form · public preview",
+    pros: "Stripe's compact prebuilt checkout form with Appearance API customization.",
+    cons: "Preview availability can vary by sandbox. Less layout control than individual Elements.",
+    docs: "https://docs.stripe.com/payments/checkout/how-checkout-works?payment-ui=checkout-form",
+  },
+] as const;

package/src/react/workflows/current-subscription.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Tests for the BTS-84 `currentSubscriptionFrom` fix — a re-subscribed buyer
+ * has one canceled-at-period-end sub from their old subscription plus a new
+ * active one, and the page must display the active sub rather than the stale
+ * canceled one.
+ */
+import { describe, expect, it } from "vitest";
+
+import { currentSubscriptionFrom } from "./current-subscription.js";
+
+describe("currentSubscriptionFrom", () => {
+  it("prefers a new active subscription over an old canceled-at-period-end one", () => {
+    const subscriptions = [
+      { status: "canceled", cancelAtPeriodEnd: true, id: "old" },
+      { status: "active", cancelAtPeriodEnd: false, id: "new" },
+    ];
+
+    expect(currentSubscriptionFrom(subscriptions)?.id).toBe("new");
+  });
+
+  it("still prefers a cancel-scheduled subscription while it is active", () => {
+    const subscriptions = [
+      { status: "active", cancelAtPeriodEnd: true, id: "canceling" },
+      { status: "past_due", cancelAtPeriodEnd: false, id: "other" },
+    ];
+
+    expect(currentSubscriptionFrom(subscriptions)?.id).toBe("canceling");
+  });
+});

package/src/react/workflows/current-subscription.ts

@@ -0,0 +1,25 @@
+/**
+ * Picks the subscription that best represents a buyer's "current plan" for
+ * display (`billing.tsx`). A `cancelAtPeriodEnd` sub is only preferred while
+ * it's still active/trialing, so a re-subscribed buyer's new subscription
+ * wins over a stale canceled one.
+ */
+export function currentSubscriptionFrom<
+  T extends {
+    status: string;
+    cancelAtPeriodEnd: boolean;
+  },
+>(subscriptions: T[]) {
+  return (
+    subscriptions.find(
+      (s) =>
+        s.cancelAtPeriodEnd &&
+        (s.status === "active" || s.status === "trialing"),
+    ) ??
+    subscriptions.find((s) =>
+      ["trialing", "active", "paused", "past_due", "unpaid"].includes(s.status),
+    ) ??
+    subscriptions[0] ??
+    null
+  );
+}

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

@@ -0,0 +1,12 @@
+import { expect, it } from "vitest";
+import { webhookQueryArgs } from "./filters.js";
+it("omits all sentinels from server filters", () => {
+  expect(webhookQueryArgs("all", "all")).toEqual({
+    eventType: undefined,
+    status: undefined,
+  });
+  expect(webhookQueryArgs("invoice.paid", "failed")).toEqual({
+    eventType: "invoice.paid",
+    status: "failed",
+  });
+});

package/src/react/workflows/filters.ts

@@ -0,0 +1,22 @@
+"use client";
+import { useState } from "react";
+export function webhookQueryArgs(eventType: string, status: string) {
+  return {
+    eventType: eventType === "all" ? undefined : eventType,
+    status: status === "all" ? undefined : status,
+  };
+}
+export function useWebhookFilters() {
+  const [typeFilter, setTypeFilter] = useState("all");
+  const [statusFilter, setStatusFilter] = useState("all");
+  const [expandedEvent, setExpandedEvent] = useState<string | null>(null);
+  return {
+    typeFilter,
+    setTypeFilter,
+    statusFilter,
+    setStatusFilter,
+    expandedEvent,
+    setExpandedEvent,
+    queryArgs: webhookQueryArgs(typeFilter, statusFilter),
+  };
+}

package/src/react/workflows/index.ts

@@ -0,0 +1,238 @@
+export { useWorkflowAction } from "./useWorkflowAction.js";
+export type { WorkflowActionState } from "./useWorkflowAction.js";
+export { useWorkflowResource } from "./useWorkflowResource.js";
+export { Checkout } from "./Checkout.js";
+export type {
+  CheckoutProps,
+  CheckoutMode,
+  CheckoutRequest,
+  CheckoutSessionResult,
+  CheckoutIntentResult,
+  CheckoutRenderProps,
+} from "./Checkout.js";
+export {
+  CheckoutElementsForm,
+  PaymentIntentForm,
+  CheckoutForm,
+} from "./CheckoutForms.js";
+export type {
+  CheckoutFormState,
+  CheckoutFormOptions,
+  CheckoutFormProps,
+} from "./CheckoutForms.js";
+export { Connect } from "./Connect.js";
+export type {
+  ConnectProps,
+  ConnectComponent,
+  ConnectRenderProps,
+} from "./Connect.js";
+export { Payouts } from "./Payouts.js";
+export type {
+  PayoutsProps,
+  HeadlessPayoutsProps,
+  PayoutsRenderProps,
+  PayoutSnapshot,
+  PayoutRow,
+} from "./Payouts.js";
+export { Refunds, useRefunds, parseAmountCents } from "./Refunds.js";
+export type {
+  RefundsProps,
+  RefundsRenderProps,
+  RefundActionsProps,
+  RefundRequest,
+  ReversalRequest,
+  RefundResult,
+  ReversalResult,
+} from "./Refunds.js";
+export { Collection } from "./Collection.js";
+export type {
+  CollectionProps,
+  CollectionRenderProps,
+  WorkflowColumn,
+} from "./Collection.js";
+export {
+  Sales,
+  Invoices,
+  RefundHistory,
+  ReferredSales,
+  WebhookEvents,
+} from "./Collections.js";
+export type {
+  ResourceCollectionProps,
+  SaleRow,
+  InvoiceRow,
+  RefundRow,
+  ReferredSaleRow,
+  WebhookEventRow,
+} from "./Collections.js";
+export { Products, useProductManager } from "./Products.js";
+export type {
+  ProductsProps,
+  ProductsRenderProps,
+  ProductActions,
+  CatalogProduct,
+  ProductInput,
+  PriceInput,
+  ProductEdit,
+} from "./Products.js";
+export { Onboarding, useOnboarding } from "./Onboarding.js";
+export type {
+  OnboardingProps,
+  OnboardingActions,
+  OnboardingAccount,
+  OnboardingRenderProps,
+} from "./Onboarding.js";
+export { Disputes, useDisputeResponse } from "./Disputes.js";
+export type {
+  DisputesProps,
+  HeadlessDisputesProps,
+  DisputesRenderProps,
+  DisputeResponseOptions,
+} from "./Disputes.js";
+export {
+  InvoiceEstimate,
+  useInvoiceEstimate,
+  BalancePaymentSource,
+  useBalanceFunding,
+  BillingPortal,
+} from "./Billing.js";
+export type {
+  InvoiceEstimateProps,
+  EstimatedInvoice,
+  BalanceFundingActions,
+  BalancePaymentSourceProps,
+  BillingPortalProps,
+} from "./Billing.js";
+export {
+  SubscriptionManager,
+  useSubscriptionManager,
+  Subscriptions,
+  useSubscriptionFilter,
+  SUBSCRIPTION_FILTERS,
+} from "./Subscriptions.js";
+export type {
+  SubscriptionManagerProps,
+  SubscriptionManagerOptions,
+  SubscriptionActionType,
+  SubscriptionCommand,
+  SubscriptionRow,
+  SubscriptionsProps,
+} from "./Subscriptions.js";
+export {
+  PaymentMethods,
+  usePaymentMethodsManager,
+  toPaymentMethodItem,
+} from "./PaymentMethods.js";
+export type {
+  PaymentMethodsProps,
+  PaymentMethodsActions,
+} from "./PaymentMethods.js";
+export { ReferralLinks, useReferralLinks } from "./ReferralLinks.js";
+export type { ReferralLink, ReferralLinksProps } from "./ReferralLinks.js";
+export { IntegrationSwitch } from "./IntegrationSwitch.js";
+export type {
+  IntegrationSwitchProps,
+  IntegrationSwitchState,
+  IntegrationMode,
+} from "./IntegrationSwitch.js";
+export { CHECKOUT_OPTIONS } from "./checkout-options.js";
+export { Account, useAccountManager } from "./Account.js";
+export type {
+  AccountProps,
+  HeadlessAccountProps,
+  AccountSummary,
+  AccountConfiguration,
+  AccountManagerOptions,
+} from "./Account.js";
+export {
+  WorkflowTasks,
+  StripeSetup,
+  SandboxTesting,
+  useTaskRunner,
+} from "./Tasks.js";
+export type {
+  WorkflowTasksProps,
+  WorkflowTask,
+  WorkflowLogEntry,
+  TaskRunnerOptions,
+} from "./Tasks.js";
+export {
+  WebhookSetup,
+  useWebhookSetup,
+  EnvironmentStatus,
+  FixtureProgress,
+} from "./Setup.js";
+export type {
+  WebhookSetupOptions,
+  EnvironmentCheck,
+  FixtureProgressState,
+} from "./Setup.js";
+export { BillingPlans, usePlanBilling } from "./BillingPlans.js";
+export type {
+  BillingPlansProps,
+  BillingPlan,
+  PlanBillingOptions,
+} from "./BillingPlans.js";
+export { CostRecovery, ChargebackLedger } from "./Costs.js";
+export type {
+  CostRecoveryRow,
+  ChargebackSummary,
+  ChargebackTransfer,
+  ChargebackLedgerRenderProps,
+} from "./Costs.js";
+export { Storefront } from "./Storefront.js";
+export type {
+  StorefrontProps,
+  StorefrontRenderProps,
+  StorefrontCard,
+  StorefrontSelection,
+  StorefrontPrice,
+  StorefrontProduct,
+  StorefrontStore,
+} from "./Storefront.js";
+export { PaymentReceipt } from "./PaymentReceipt.js";
+export type {
+  PaymentReceiptProps,
+  PaymentReceiptState,
+  ReceiptPayment,
+} from "./PaymentReceipt.js";
+export { Earnings, earningsFromBalance } from "./Earnings.js";
+export type {
+  EarningsProps,
+  HeadlessEarningsProps,
+  EarningsRenderProps,
+  EarningsMetric,
+  BalanceSnapshot,
+  StoreEarnings,
+} from "./Earnings.js";
+export { ClipboardButton } from "./ClipboardButton.js";
+export type { ClipboardButtonProps } from "./ClipboardButton.js";
+export { useWebhookFilters, webhookQueryArgs } from "./filters.js";
+export { AccountConfigurations } from "./Account.js";
+export type { AccountConfigurationsProps } from "./Account.js";
+export { Overview, getPayoutTotals } from "./Overview.js";
+export type { OverviewProps, OverviewState } from "./Overview.js";
+export { currentSubscriptionFrom } from "./current-subscription.js";
+export { CheckoutChooser } from "./CheckoutChooser.js";
+export type {
+  CheckoutChooserProps,
+  CheckoutChooserState,
+  CheckoutOption,
+} from "./CheckoutChooser.js";
+export { SubscriptionOverview } from "./SubscriptionOverview.js";
+export type {
+  SubscriptionOverviewProps,
+  SubscriptionOverviewState,
+} from "./SubscriptionOverview.js";
+export { DEFAULT_CONNECT_COUNTRIES } from "./Onboarding.js";
+export { PayoutHistory } from "./Payouts.js";
+export type { PayoutHistoryProps, PayoutHistoryRow } from "./Payouts.js";
+export { PayoutOverview } from "./Overview.js";
+export type { PayoutOverviewProps, PayoutOverviewRow } from "./Overview.js";
+export { ChargeSummary, PaymentDetails } from "./Financials.js";
+export type {
+  ChargeSummaryProps,
+  PaymentDetailsProps,
+  PaymentDetailsPayment,
+  PaymentDetailsState,
+} from "./Financials.js";

package/src/react/workflows/native-interactions.test.tsx

@@ -0,0 +1,73 @@
+// @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";
+import { Products, Refunds, BalancePaymentSource } from "../index.js";
+
+afterEach(cleanup);
+it("lets a package consumer create a recurring product price without example providers", async () => {
+  const createPrice = vi.fn(async () => null);
+  render(
+    <Products
+      scopeKey="store"
+      products={[
+        {
+          stripeProductId: "prod_tee",
+          name: "Tee club",
+          active: true,
+          prices: [],
+        },
+      ]}
+      createProduct={async () => null}
+      createPrice={createPrice}
+    />,
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Add price" }));
+  await userEvent.type(screen.getByLabelText("Price in minor units"), "2900");
+  await userEvent.selectOptions(screen.getByLabelText("Interval"), "month");
+  await userEvent.click(screen.getByRole("button", { name: "Create price" }));
+  await waitFor(() =>
+    expect(createPrice).toHaveBeenCalledWith({
+      stripeProductId: "prod_tee",
+      unitAmount: 2900,
+      currency: "usd",
+      type: "recurring",
+      interval: "month",
+    }),
+  );
+  await waitFor(() =>
+    expect(screen.queryByLabelText("Price in minor units")).toBeNull(),
+  );
+});
+it("submits a partial refund through the native UI and renders its receipt", async () => {
+  const issueRefund = vi.fn(async () => ({ stripeRefundId: "re_partial" }));
+  render(<Refunds scopeKey="store" issueRefund={issueRefund} />);
+  await userEvent.type(screen.getByLabelText("PaymentIntent ID"), "pi_one");
+  await userEvent.type(screen.getByLabelText("Partial refund amount"), "12.34");
+  await userEvent.click(screen.getByRole("button", { name: "Partial refund" }));
+  await waitFor(() =>
+    expect(issueRefund).toHaveBeenCalledWith({
+      stripePaymentIntentId: "pi_one",
+      amountCents: 1234,
+      reason: "requested_by_customer",
+    }),
+  );
+  expect((await screen.findByRole("status")).textContent).toContain(
+    "Refund created: re_partial",
+  );
+});
+it("requires explicit consent before the native balance-funding UI can submit", async () => {
+  const change = vi.fn(async () => null);
+  render(
+    <BalancePaymentSource scopeKey="store" enabled={false} change={change} />,
+  );
+  const confirm = screen.getByRole("button", {
+    name: "Confirm balance payments",
+  });
+  expect((confirm as HTMLButtonElement).disabled).toBe(true);
+  await userEvent.click(screen.getByRole("checkbox"));
+  await userEvent.click(confirm);
+  await waitFor(() =>
+    expect(change).toHaveBeenCalledWith({ enabled: true, consent: true }),
+  );
+});