@fantastic.dev/better-stripe 0.7.0 → 0.8.1

package/src/react/workflows/Refunds.tsx

@@ -0,0 +1,223 @@
+"use client";
+import { useState, useId, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { Connect, type ConnectProps } from "./Connect.js";
+export type RefundRequest = {
+  stripePaymentIntentId: string;
+  amountCents?: number;
+  reason: "requested_by_customer";
+};
+export type ReversalRequest = { sourceChargeId: string; amountCents?: number };
+export type RefundResult = { stripeRefundId: string };
+export type ReversalResult = {
+  reversals: { stripeTransferId: string; amount: number }[];
+  summary: { reversalCount: number; totalReversed: number };
+};
+export type RefundActionsProps = {
+  scopeKey: string;
+  paymentIntentId?: string;
+  sourceChargeId?: string;
+  issueRefund: (args: RefundRequest) => Promise<RefundResult>;
+  reverseTransfers?: (args: ReversalRequest) => Promise<ReversalResult>;
+};
+/** Currency input expressed in two decimal minor units. Rejects rounding and scientific notation. */
+export function parseAmountCents(value: string): number | null {
+  if (!/^\d+(?:\.\d{1,2})?$/.test(value.trim())) return null;
+  const [whole, fraction = ""] = value.trim().split(".");
+  const amount = Number(whole) * 100 + Number(fraction.padEnd(2, "0"));
+  return Number.isSafeInteger(amount) && amount > 0 ? amount : null;
+}
+export function useRefunds(props: RefundActionsProps) {
+  const initial = {
+    scope: props.scopeKey,
+    paymentIntentId: props.paymentIntentId ?? "",
+    sourceChargeId: props.sourceChargeId ?? "",
+    refundAmount: "",
+    reversalAmount: "",
+  };
+  const [fields, setFields] = useState(initial);
+  if (fields.scope !== props.scopeKey) setFields(initial);
+  const [operationType, setOperationType] = useState<"refund" | "reversal">(
+    "refund",
+  );
+  const action = useWorkflowAction(
+    async (operation: {
+      type: "refund" | "reversal";
+      kind: "full" | "partial";
+    }) => {
+      setOperationType(operation.type);
+      const id = (
+        operation.type === "refund"
+          ? fields.paymentIntentId
+          : fields.sourceChargeId
+      ).trim();
+      if (!id)
+        throw new Error(
+          operation.type === "refund"
+            ? "Enter a PaymentIntent id before issuing a refund."
+            : "Enter a source charge id before reversing transfers.",
+        );
+      const amount =
+        operation.kind === "partial"
+          ? parseAmountCents(
+              operation.type === "refund"
+                ? fields.refundAmount
+                : fields.reversalAmount,
+            )
+          : undefined;
+      if (amount === null)
+        throw new Error(
+          `Enter a positive partial ${operation.type === "refund" ? "refund" : "reversal"} amount with at most two decimal places.`,
+        );
+      if (operation.type === "refund")
+        return {
+          type: "refund" as const,
+          value: await props.issueRefund({
+            stripePaymentIntentId: id,
+            amountCents: amount,
+            reason: "requested_by_customer",
+          }),
+        };
+      if (!props.reverseTransfers)
+        throw new Error("Transfer reversals are not configured.");
+      return {
+        type: "reversal" as const,
+        value: await props.reverseTransfers({
+          sourceChargeId: id,
+          amountCents: amount,
+        }),
+      };
+    },
+    props.scopeKey,
+  );
+  const set = (
+    name:
+      "paymentIntentId" | "sourceChargeId" | "refundAmount" | "reversalAmount",
+    value: string,
+  ) => setFields((previous) => ({ ...previous, [name]: value }));
+  return {
+    ...fields,
+    setPaymentIntentId: (value: string) => set("paymentIntentId", value),
+    setSourceChargeId: (value: string) => set("sourceChargeId", value),
+    setRefundAmount: (value: string) => set("refundAmount", value),
+    setReversalAmount: (value: string) => set("reversalAmount", value),
+    error: action.error,
+    isPending: action.isPending,
+    busy: action.isPending ? operationType : null,
+    refundResult: action.result?.type === "refund" ? action.result.value : null,
+    reversalResult:
+      action.result?.type === "reversal" ? action.result.value : null,
+    submitRefund: (kind: "full" | "partial") =>
+      action.run({ type: "refund", kind }),
+    submitReversal: (kind: "full" | "partial") =>
+      action.run({ type: "reversal", kind }),
+  };
+}
+export type RefundsRenderProps = ReturnType<typeof useRefunds>;
+export type RefundsProps =
+  | (RefundActionsProps & {
+      presentation?: "headless";
+      children?: (state: RefundsRenderProps) => ReactNode;
+    })
+  | (Omit<ConnectProps, "component"> & { presentation: "embedded" });
+export function Refunds(props: RefundsProps) {
+  return props.presentation === "embedded" ? (
+    <Connect {...props} component="refunds" />
+  ) : (
+    <RefundsBody key={props.scopeKey} {...props} />
+  );
+}
+function RefundsBody(
+  props: RefundActionsProps & {
+    children?: (state: RefundsRenderProps) => ReactNode;
+  },
+) {
+  const state = useRefunds(props);
+  const id = useId();
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <section data-better-stripe="refunds" aria-busy={state.isPending}>
+      <h2>Refunds</h2>
+      {state.error && <p role="alert">{state.error}</p>}
+      <label htmlFor={`${id}-payment`}>PaymentIntent ID</label>
+      <input
+        id={`${id}-payment`}
+        value={state.paymentIntentId}
+        onChange={(event) => state.setPaymentIntentId(event.target.value)}
+      />
+      <label htmlFor={`${id}-amount`}>Partial refund amount</label>
+      <input
+        id={`${id}-amount`}
+        type="number"
+        min="0.01"
+        step="0.01"
+        value={state.refundAmount}
+        onChange={(event) => state.setRefundAmount(event.target.value)}
+      />
+      <button
+        type="button"
+        disabled={state.isPending}
+        onClick={() => {
+          void state.submitRefund("full");
+        }}
+      >
+        {state.isPending ? "Processing…" : "Full refund"}
+      </button>
+      <button
+        type="button"
+        disabled={state.isPending}
+        onClick={() => {
+          void state.submitRefund("partial");
+        }}
+      >
+        Partial refund
+      </button>
+      {state.refundResult && (
+        <p role="status">Refund created: {state.refundResult.stripeRefundId}</p>
+      )}
+      {props.reverseTransfers && (
+        <>
+          <h3>Transfer reversals</h3>
+          <label htmlFor={`${id}-charge`}>Source charge ID</label>
+          <input
+            id={`${id}-charge`}
+            value={state.sourceChargeId}
+            onChange={(event) => state.setSourceChargeId(event.target.value)}
+          />
+          <label htmlFor={`${id}-reversal`}>Partial reversal amount</label>
+          <input
+            id={`${id}-reversal`}
+            type="number"
+            min="0.01"
+            step="0.01"
+            value={state.reversalAmount}
+            onChange={(event) => state.setReversalAmount(event.target.value)}
+          />
+          <button
+            type="button"
+            disabled={state.isPending}
+            onClick={() => {
+              void state.submitReversal("full");
+            }}
+          >
+            Reverse all transfers
+          </button>
+          <button
+            type="button"
+            disabled={state.isPending}
+            onClick={() => {
+              void state.submitReversal("partial");
+            }}
+          >
+            Partial reversal
+          </button>
+          {state.reversalResult && (
+            <p role="status">
+              Reversed {state.reversalResult.summary.reversalCount} transfers.
+            </p>
+          )}
+        </>
+      )}
+    </section>
+  );
+}

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

@@ -0,0 +1,25 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { useWebhookSetup } from "./Setup.js";
+afterEach(cleanup);
+it("refreshes destination status after setup and keeps setup errors available for retry", async () => {
+  const load = vi
+    .fn()
+    .mockResolvedValueOnce({ configured: false })
+    .mockResolvedValueOnce({ configured: true });
+  const setup = vi.fn().mockResolvedValue({ id: "we_test" });
+  const { result } = renderHook(() =>
+    useWebhookSetup({ scopeKey: "site", load, setup }),
+  );
+  await waitFor(() =>
+    expect(result.current.status).toEqual({ configured: false }),
+  );
+  await act(async () => {
+    await result.current.configure();
+  });
+  await waitFor(() =>
+    expect(result.current.status).toEqual({ configured: true }),
+  );
+  expect(result.current.result).toEqual({ id: "we_test" });
+});

package/src/react/workflows/Setup.tsx

@@ -0,0 +1,166 @@
+"use client";
+import type { ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { useWorkflowResource } from "./useWorkflowResource.js";
+export type WebhookSetupOptions<Status, Result> = {
+  scopeKey: string;
+  load: () => Promise<Status>;
+  setup: () => Promise<Result>;
+};
+export function useWebhookSetup<Status, Result>(
+  props: WebhookSetupOptions<Status, Result>,
+) {
+  const status = useWorkflowResource(props.load, props.scopeKey);
+  const setup = useWorkflowAction(
+    async () => ({ value: await props.setup() }),
+    props.scopeKey,
+  );
+  return {
+    status: status.data,
+    isChecking: status.isLoading,
+    statusError: status.error,
+    checkStatus: status.refresh,
+    result: setup.result?.value,
+    isPending: setup.isPending,
+    error: setup.error,
+    configure: async () => {
+      if (await setup.run()) status.refresh();
+    },
+  };
+}
+export function WebhookSetup<Status, Result>(
+  props: WebhookSetupOptions<Status, Result> & {
+    renderStatus?: (status: Status) => ReactNode;
+    children?: (
+      state: ReturnType<typeof useWebhookSetup<Status, Result>>,
+    ) => ReactNode;
+  },
+) {
+  const state = useWebhookSetup(props);
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <section data-better-stripe="webhook-setup">
+      <h2>Webhook destinations</h2>
+      {(state.error || state.statusError) && (
+        <p role="alert">{state.error || state.statusError}</p>
+      )}
+      {state.isChecking ? (
+        <p role="status">Checking destinations…</p>
+      ) : state.status !== undefined && props.renderStatus ? (
+        props.renderStatus(state.status)
+      ) : (
+        <p>Destination status loaded.</p>
+      )}
+      <button
+        type="button"
+        disabled={state.isPending || state.isChecking}
+        onClick={() => {
+          void state.configure();
+        }}
+      >
+        {state.isPending ? "Configuring…" : "Configure webhooks"}
+      </button>
+      <button
+        type="button"
+        disabled={state.isChecking}
+        onClick={state.checkStatus}
+      >
+        Refresh status
+      </button>
+    </section>
+  );
+}
+export type EnvironmentCheck = {
+  id: string;
+  label: string;
+  configured: boolean;
+};
+export function EnvironmentStatus({
+  checks,
+  isLoading = checks === undefined,
+  error,
+  children,
+}: {
+  checks: EnvironmentCheck[] | undefined;
+  isLoading?: boolean;
+  error?: string | null;
+  children?: (state: {
+    checks: EnvironmentCheck[];
+    allConfigured: boolean;
+    isLoading: boolean;
+    error: string | null;
+  }) => ReactNode;
+}) {
+  const state = {
+    checks: checks ?? [],
+    allConfigured:
+      !!checks?.length && checks.every((check) => check.configured),
+    isLoading,
+    error: error ?? null,
+  };
+  if (children) return <>{children(state)}</>;
+  return (
+    <section data-better-stripe="environment-status">
+      <h2>Environment</h2>
+      {error ? (
+        <p role="alert">{error}</p>
+      ) : isLoading ? (
+        <p role="status">Checking configuration…</p>
+      ) : !checks?.length ? (
+        <p>No environment checks configured.</p>
+      ) : (
+        <ul>
+          {checks.map((check) => (
+            <li key={check.id}>
+              {check.label}: {check.configured ? "Set" : "Not set"}
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}
+export type FixtureProgressState = {
+  cursor: number;
+  total: number;
+  status: string;
+  error?: string;
+};
+export function FixtureProgress({
+  state,
+  children,
+}: {
+  state: FixtureProgressState | null | undefined;
+  children?: (
+    state: FixtureProgressState & { progress: number; message: string },
+  ) => ReactNode;
+}) {
+  if (!state) return <p>No fixture run yet.</p>;
+  const result = {
+    ...state,
+    progress:
+      state.total > 0
+        ? Math.max(0, Math.min(1, state.cursor / state.total))
+        : 0,
+    message:
+      state.status === "running"
+        ? "Fixtures are being created. Stripe events continue to update your data."
+        : state.status === "complete"
+          ? "Fixtures are populated. Stripe statuses can continue updating through webhooks."
+          : "Population stopped. Resume to retry this step.",
+  };
+  if (children) return <>{children(result)}</>;
+  return (
+    <div data-better-stripe="fixture-progress">
+      <progress
+        aria-label="Sandbox fixture progress"
+        value={result.progress}
+        max={1}
+      />
+      <p role="status">
+        {state.cursor} of {state.total} steps complete. {result.message}
+      </p>
+      {state.error && <p role="alert">{state.error}</p>}
+    </div>
+  );
+}

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

@@ -0,0 +1,82 @@
+// @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 { Storefront } from "./Storefront.js";
+afterEach(cleanup);
+it("preserves product, store, and referral attribution when selecting a price", async () => {
+  const onSelectPrice = vi.fn();
+  render(
+    <Storefront
+      stores={[
+        {
+          accountId: "acct_one",
+          name: "Independent Store",
+          products: [
+            {
+              stripeProductId: "prod_one",
+              name: "Tee",
+              prices: [
+                {
+                  stripePriceId: "price_one",
+                  unitAmount: 2900,
+                  currency: "usd",
+                  type: "one_time",
+                },
+              ],
+            },
+          ],
+        },
+      ]}
+      referralCode="avery"
+      onSelectPrice={onSelectPrice}
+    />,
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Buy Tee" }));
+  expect(onSelectPrice).toHaveBeenCalledWith(
+    expect.objectContaining({
+      store: expect.objectContaining({ accountId: "acct_one" }),
+      price: expect.objectContaining({ stripePriceId: "price_one" }),
+      referralCode: "avery",
+    }),
+  );
+});
+it("does not offer inactive prices or purchases when the application disables buying", () => {
+  render(
+    <Storefront
+      canPurchase={false}
+      stores={[
+        {
+          accountId: "acct_one",
+          name: "Store",
+          products: [
+            {
+              stripeProductId: "prod_one",
+              name: "Tee",
+              prices: [
+                {
+                  stripePriceId: "price_old",
+                  active: false,
+                  unitAmount: 100,
+                  currency: "usd",
+                  type: "one_time",
+                },
+                {
+                  stripePriceId: "price_one",
+                  unitAmount: 2900,
+                  currency: "usd",
+                  type: "one_time",
+                },
+              ],
+            },
+          ],
+        },
+      ]}
+    />,
+  );
+  expect(
+    (screen.getByRole("button", { name: "Buy Tee" }) as HTMLButtonElement)
+      .disabled,
+  ).toBe(true);
+  expect(screen.getAllByRole("button")).toHaveLength(1);
+});

package/src/react/workflows/Storefront.tsx

@@ -0,0 +1,138 @@
+"use client";
+import type { ReactNode } from "react";
+import { formatPriceWithInterval } from "../lib/price-helpers.js";
+export type StorefrontPrice = {
+  stripePriceId: string;
+  unitAmount: number;
+  currency: string;
+  type: string;
+  interval?: string | null;
+  intervalCount?: number | null;
+  active?: boolean;
+};
+export type StorefrontProduct = {
+  stripeProductId: string;
+  name: string;
+  description?: string | null;
+  active?: boolean;
+  prices: StorefrontPrice[];
+};
+export type StorefrontStore = {
+  accountId: string;
+  name: string;
+  products: StorefrontProduct[];
+};
+export type StorefrontSelection = {
+  store: StorefrontStore;
+  product: StorefrontProduct;
+  price: StorefrontPrice;
+  referralCode?: string;
+};
+export type StorefrontCard = StorefrontSelection & {
+  formattedPrice: string;
+  purchaseLabel: string;
+  accessibilityLabel: string;
+  checkoutUrl?: string;
+  purchase: () => void;
+};
+export type StorefrontRenderProps = {
+  stores: StorefrontStore[];
+  cards: StorefrontCard[];
+  isLoading: boolean;
+  isEmpty: boolean;
+  canPurchase: boolean;
+};
+export type StorefrontProps = {
+  stores: StorefrontStore[] | undefined;
+  storeId?: string;
+  referralCode?: string;
+  canPurchase?: boolean;
+  getCheckoutUrl?: (selection: StorefrontSelection) => string;
+  onSelectPrice?: (selection: StorefrontSelection) => void;
+  children?: (state: StorefrontRenderProps) => ReactNode;
+};
+export function Storefront({
+  stores,
+  storeId,
+  referralCode,
+  canPurchase = true,
+  getCheckoutUrl,
+  onSelectPrice,
+  children,
+}: StorefrontProps) {
+  const visible =
+    stores?.filter((store) => !storeId || store.accountId === storeId) ?? [];
+  const cards: StorefrontCard[] = visible.flatMap((store) =>
+    store.products
+      .filter((product) => product.active !== false)
+      .flatMap((product) =>
+        product.prices
+          .filter((price) => price.active !== false)
+          .map((price) => {
+            const selection = { store, product, price, referralCode };
+            return {
+              ...selection,
+              formattedPrice: formatPriceWithInterval({
+                ...price,
+                active: true,
+              }),
+              purchaseLabel:
+                price.type === "recurring" ? "Subscribe" : "Buy now",
+              accessibilityLabel: `${price.type === "recurring" ? "Subscribe to" : "Buy"} ${product.name}`,
+              checkoutUrl: getCheckoutUrl?.(selection),
+              purchase: () => {
+                if (canPurchase) onSelectPrice?.(selection);
+              },
+            };
+          }),
+      ),
+  );
+  const state = {
+    stores: visible,
+    cards,
+    isLoading: stores === undefined,
+    isEmpty: stores !== undefined && !visible.length,
+    canPurchase,
+  };
+  if (children) return <>{children(state)}</>;
+  if (state.isLoading) return <p role="status">Loading stores…</p>;
+  if (state.isEmpty) return <p>No stores available yet.</p>;
+  return (
+    <div data-better-stripe="storefront">
+      {visible.map((store) => (
+        <section key={store.accountId}>
+          <h2>{store.name}</h2>
+          {!cards.some((card) => card.store.accountId === store.accountId) && (
+            <p>No products available yet.</p>
+          )}
+          {cards
+            .filter((card) => card.store.accountId === store.accountId)
+            .map((card) => (
+              <article key={card.price.stripePriceId}>
+                <h3>{card.product.name}</h3>
+                <p>{card.product.description}</p>
+                <p>{card.formattedPrice}</p>
+                {card.checkoutUrl && canPurchase ? (
+                  <a
+                    href={card.checkoutUrl}
+                    aria-label={card.accessibilityLabel}
+                  >
+                    {card.purchaseLabel}
+                  </a>
+                ) : (
+                  <button
+                    type="button"
+                    disabled={!canPurchase || !onSelectPrice}
+                    aria-label={card.accessibilityLabel}
+                    onClick={card.purchase}
+                  >
+                    {card.purchaseLabel}
+                  </button>
+                )}
+              </article>
+            ))}
+        </section>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,27 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, expect, it } from "vitest";
+import { SubscriptionOverview } from "./SubscriptionOverview.js";
+afterEach(cleanup);
+it("renders loading, empty, and current subscription states without app providers", () => {
+  const { rerender } = render(
+    <SubscriptionOverview subscriptions={undefined} />,
+  );
+  expect(screen.getByRole("status").textContent).toContain("Loading");
+  rerender(<SubscriptionOverview subscriptions={[]} />);
+  expect(screen.getByText("No subscription yet.")).toBeTruthy();
+  rerender(
+    <SubscriptionOverview
+      subscriptions={[
+        {
+          stripeSubscriptionId: "sub_old",
+          status: "canceled",
+          cancelAtPeriodEnd: true,
+        },
+        { stripeSubscriptionId: "sub_new", status: "active" },
+      ]}
+    />,
+  );
+  expect(screen.getByText("sub_new")).toBeTruthy();
+  expect(screen.queryByText("sub_old")).toBeNull();
+});