@fantastic.dev/better-stripe 0.7.0 → 0.8.1

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

package/src/react/workflows/public-workflows.test.tsx

@@ -0,0 +1,216 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import {
+  CheckoutChooser,
+  SubscriptionOverview,
+  PayoutHistory,
+  PayoutOverview,
+  ChargeSummary,
+  PaymentDetails,
+  Account,
+  Onboarding,
+  Payouts,
+  Refunds,
+  Products,
+  Subscriptions,
+  SubscriptionManager,
+  BillingPlans,
+  InvoiceEstimate,
+  BalancePaymentSource,
+  BillingPortal,
+  ReferralLinks,
+  Sales,
+  Invoices,
+  RefundHistory,
+  ReferredSales,
+  WebhookEvents,
+  ChargebackLedger,
+  CostRecovery,
+  Overview,
+  EnvironmentStatus,
+  StripeSetup,
+  SandboxTesting,
+  PaymentReceipt,
+  Earnings,
+  Storefront,
+} from "../index.js";
+import type { ReactNode } from "react";
+const action = vi.fn(async () => null);
+const account = {
+  stripeAccountId: "acct_public",
+  email: "seller@example.com",
+  country: "US",
+  onboardingStatus: "complete",
+  configurations: ["recipient"],
+};
+const subscription = {
+  stripeSubscriptionId: "sub_public",
+  status: "active",
+  isTrialing: false,
+  cancelAtPeriodEnd: false,
+};
+describe("public workflows without example providers, a router, or CSS", () => {
+  const cases: [string, ReactNode][] = [
+    ["CheckoutChooser", <CheckoutChooser />],
+    ["SubscriptionOverview", <SubscriptionOverview subscriptions={[]} />],
+    ["PayoutHistory", <PayoutHistory rows={[]} />],
+    ["PayoutOverview", <PayoutOverview payouts={[]} currency="usd" />],
+    [
+      "ChargeSummary",
+      <ChargeSummary
+        gross={1000}
+        fee={90}
+        net={910}
+        currency="usd"
+        reconciles
+      />,
+    ],
+    ["PaymentDetails", <PaymentDetails payment={null} />],
+    ["Account", <Account scopeKey="seller" account={account} />],
+    [
+      "Onboarding",
+      <Onboarding
+        scopeKey="seller"
+        account={null}
+        createAccount={async () => ({
+          onboardingUrl: "https://connect.stripe.com",
+        })}
+        continueOnboarding={async () => ({ url: "https://connect.stripe.com" })}
+      />,
+    ],
+    [
+      "Payouts",
+      <Payouts
+        scopeKey="seller"
+        load={async () => ({
+          balances: [],
+          payouts: [],
+          upcoming: [],
+          nextCursor: null,
+        })}
+      />,
+    ],
+    [
+      "Refunds",
+      <Refunds
+        scopeKey="seller"
+        issueRefund={async () => ({ stripeRefundId: "re_public" })}
+      />,
+    ],
+    [
+      "Products",
+      <Products
+        scopeKey="seller"
+        products={[]}
+        createProduct={action}
+        createPrice={action}
+      />,
+    ],
+    ["Subscriptions", <Subscriptions rows={[subscription]} />],
+    [
+      "SubscriptionManager",
+      <SubscriptionManager
+        scopeKey="buyer"
+        subscription={subscription}
+        onAction={action}
+      />,
+    ],
+    [
+      "BillingPlans",
+      <BillingPlans
+        scopeKey="seller"
+        publishableKey="pk_test_public"
+        plans={[
+          {
+            id: "starter",
+            name: "Starter",
+            monthlyAmount: 900,
+            currency: "usd",
+          },
+        ]}
+        createCheckout={async () => ({
+          stripeSessionId: "cs_public",
+          clientSecret: "cs_public_secret",
+        })}
+        createPortal={async () => "https://billing.stripe.com"}
+      />,
+    ],
+    [
+      "InvoiceEstimate",
+      <InvoiceEstimate
+        scopeKey="seller"
+        load={async () => ({
+          total: 900,
+          currency: "usd",
+          nextBillingAt: 1800000000000,
+          lines: [],
+        })}
+      />,
+    ],
+    [
+      "BalancePaymentSource",
+      <BalancePaymentSource
+        scopeKey="seller"
+        enabled={false}
+        change={action}
+      />,
+    ],
+    [
+      "BillingPortal",
+      <BillingPortal
+        createSession={async () => "https://billing.stripe.com"}
+      />,
+    ],
+    ["ReferralLinks", <ReferralLinks links={[]} />],
+    ["Sales", <Sales rows={[]} />],
+    ["Invoices", <Invoices rows={[]} />],
+    ["RefundHistory", <RefundHistory rows={[]} />],
+    ["ReferredSales", <ReferredSales rows={[]} />],
+    ["WebhookEvents", <WebhookEvents rows={[]} />],
+    ["CostRecovery", <CostRecovery rows={[]} />],
+    ["ChargebackLedger", <ChargebackLedger chargeback={null} />],
+    ["Overview", <Overview products={[]} subscriptions={[]} />],
+    [
+      "EnvironmentStatus",
+      <EnvironmentStatus
+        checks={[{ id: "secret", label: "Stripe key", configured: true }]}
+      />,
+    ],
+    [
+      "StripeSetup",
+      <StripeSetup tasks={[{ id: "sync", label: "Sync", run: action }]} />,
+    ],
+    [
+      "SandboxTesting",
+      <SandboxTesting tasks={[{ id: "seed", label: "Seed", run: action }]} />,
+    ],
+    [
+      "PaymentReceipt",
+      <PaymentReceipt
+        payment={{ status: "succeeded", amount: 2900, currency: "usd" }}
+      />,
+    ],
+    [
+      "Earnings",
+      <Earnings
+        gross={2900}
+        reversed={0}
+        net={2900}
+        paidOut={0}
+        payouts={[]}
+      />,
+    ],
+    ["Storefront", <Storefront stores={[]} />],
+  ];
+  it.each(cases)(
+    "%s renders unstyled native HTML independently",
+    (_name, component) => {
+      const markup = renderToStaticMarkup(component);
+      expect(markup.length).toBeGreaterThan(0);
+      expect(markup).not.toContain("class=");
+      expect(markup).not.toContain("style=");
+      expect(markup).not.toContain("localhost");
+      expect(action).not.toHaveBeenCalled();
+    },
+  );
+});

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

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+import { act, renderHook, cleanup } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+afterEach(cleanup);
+it("prevents duplicate requests and exposes pending, errors, and retry", async () => {
+  let reject!: (error: Error) => void;
+  const callback = vi.fn(
+    () =>
+      new Promise<string>((_resolve, fail) => {
+        reject = fail;
+      }),
+  );
+  const { result } = renderHook(() => useWorkflowAction(callback));
+  let first!: Promise<string | undefined>;
+  act(() => {
+    first = result.current.run();
+  });
+  expect(result.current.isPending).toBe(true);
+  await act(async () => {
+    await result.current.run();
+  });
+  expect(callback).toHaveBeenCalledOnce();
+  await act(async () => {
+    reject(new Error("Stripe declined"));
+    await first;
+  });
+  expect(result.current.error).toBe("Stripe declined");
+  expect(result.current.isPending).toBe(false);
+});
+it("does not publish an old account's action result after a scope change", async () => {
+  let resolve!: (value: string) => void;
+  const callback = vi.fn(
+    () =>
+      new Promise<string>((done) => {
+        resolve = done;
+      }),
+  );
+  const { result, rerender } = renderHook(
+    ({ scope }) => useWorkflowAction(callback, scope),
+    { initialProps: { scope: "seller_one" } },
+  );
+  let request!: Promise<string | undefined>;
+  act(() => {
+    request = result.current.run();
+  });
+  rerender({ scope: "seller_two" });
+  await act(async () => {
+    resolve("seller_one_secret");
+    await request;
+  });
+  expect(result.current.result).toBeUndefined();
+  expect(result.current.isPending).toBe(false);
+});