@fantastic.dev/better-stripe 0.7.0 → 0.8.0

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

package/src/react/workflows/SubscriptionOverview.tsx

@@ -0,0 +1,48 @@
+"use client";
+import type { ReactNode } from "react";
+import type { SubscriptionRow } from "./Subscriptions.js";
+import { currentSubscriptionFrom } from "./current-subscription.js";
+import { SubscriptionCard } from "../components/SubscriptionCard.js";
+export type SubscriptionOverviewState<Row> = {
+  subscription: Row | null;
+  isLoading: boolean;
+  isEmpty: boolean;
+};
+export type SubscriptionOverviewProps<
+  Row extends SubscriptionRow = SubscriptionRow,
+> = {
+  subscriptions: Row[] | undefined;
+  children?: (state: SubscriptionOverviewState<Row>) => ReactNode;
+};
+export function SubscriptionOverview<Row extends SubscriptionRow>({
+  subscriptions,
+  children,
+}: SubscriptionOverviewProps<Row>) {
+  const subscription = currentSubscriptionFrom(
+    (subscriptions ?? []).map((row) => ({
+      ...row,
+      cancelAtPeriodEnd: row.cancelAtPeriodEnd ?? false,
+    })),
+  );
+  const state = {
+    subscription,
+    isLoading: subscriptions === undefined,
+    isEmpty: subscriptions !== undefined && !subscription,
+  };
+  if (children) return <>{children(state)}</>;
+  if (state.isLoading) return <p role="status">Loading subscription…</p>;
+  if (!subscription) return <p>No subscription yet.</p>;
+  return (
+    <section data-better-stripe="subscription-overview">
+      <h2>Your subscription</h2>
+      <p>{subscription.stripeSubscriptionId}</p>
+      <SubscriptionCard
+        subscription={{
+          ...subscription,
+          isTrialing:
+            subscription.isTrialing ?? subscription.status === "trialing",
+        }}
+      />
+    </section>
+  );
+}

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

@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { useSubscriptionManager } from "./Subscriptions.js";
+afterEach(cleanup);
+it("validates quantity changes and exposes server confirmation as pending webhook synchronization", async () => {
+  const onAction = vi.fn().mockResolvedValue(null);
+  const { result } = renderHook(() =>
+    useSubscriptionManager({
+      scopeKey: "buyer",
+      subscription: { stripeSubscriptionId: "sub_one", status: "active" },
+      onAction,
+    }),
+  );
+  act(() => result.current.setQuantity("1.5"));
+  await act(async () => {
+    await result.current.run("quantity");
+  });
+  expect(onAction).not.toHaveBeenCalled();
+  expect(result.current.message).toContain("integer");
+  act(() => result.current.setQuantity("3"));
+  await act(async () => {
+    await result.current.run("quantity");
+  });
+  expect(onAction).toHaveBeenCalledWith({
+    type: "quantity",
+    stripeSubscriptionId: "sub_one",
+    quantity: 3,
+  });
+  expect(result.current.message).toContain("Waiting for Stripe webhook sync");
+});
+
+it("retains the pending subscription action when a second action is attempted", async () => {
+  let finish!: () => void;
+  const onAction = vi.fn(
+    () =>
+      new Promise<void>((resolve) => {
+        finish = resolve;
+      }),
+  );
+  const { result } = renderHook(() =>
+    useSubscriptionManager({
+      scopeKey: "buyer",
+      subscription: { stripeSubscriptionId: "sub_one", status: "active" },
+      onAction,
+    }),
+  );
+  let pending!: Promise<unknown>;
+  act(() => {
+    pending = result.current.run("pause");
+  });
+  await act(async () => {
+    await result.current.run("cancel");
+  });
+  expect(result.current.pendingAction).toBe("pause subscription");
+  expect(onAction).toHaveBeenCalledTimes(1);
+  await act(async () => {
+    finish();
+    await pending;
+  });
+});

package/src/react/workflows/Subscriptions.tsx

@@ -0,0 +1,282 @@
+"use client";
+import { useId, useState, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import {
+  Collection,
+  type CollectionProps,
+  type WorkflowColumn,
+} from "./Collection.js";
+import { SubscriptionCard } from "../components/SubscriptionCard.js";
+export type SubscriptionRow = {
+  stripeSubscriptionId: string;
+  status: string;
+  isTrialing?: boolean;
+  cancelAtPeriodEnd?: boolean;
+  isCollectionPaused?: boolean;
+  currentPeriodEnd?: string | null;
+  trialEnd?: string | null;
+  quantity?: number;
+  userId?: string;
+};
+export type SubscriptionActionType =
+  | "pause"
+  | "resume"
+  | "reactivate"
+  | "cancel"
+  | "price"
+  | "quantity"
+  | "trial"
+  | "endTrial";
+export type SubscriptionCommand = {
+  type: SubscriptionActionType;
+  stripeSubscriptionId: string;
+  stripePriceId?: string;
+  quantity?: number;
+  trialEnd?: string;
+};
+export type SubscriptionManagerOptions = {
+  scopeKey: string;
+  subscription: SubscriptionRow | null | undefined;
+  onAction: (command: SubscriptionCommand) => Promise<unknown>;
+};
+const labels: Record<SubscriptionActionType, string> = {
+  pause: "pause subscription",
+  resume: "resume subscription",
+  reactivate: "reactivate subscription",
+  cancel: "cancel subscription",
+  price: "change plan",
+  quantity: "update quantity",
+  trial: "update trial end",
+  endTrial: "end trial now",
+};
+export function useSubscriptionManager(props: SubscriptionManagerOptions) {
+  const scope = `${props.scopeKey}:${props.subscription?.stripeSubscriptionId ?? ""}`;
+  const initial = { scope, quantity: "1", selectedPriceId: "", trialEnd: "" };
+  const [fields, setFields] = useState(initial);
+  if (fields.scope !== scope) setFields(initial);
+  const [operation, setOperation] = useState<SubscriptionActionType>("pause");
+  const action = useWorkflowAction(async (type: SubscriptionActionType) => {
+    setOperation(type);
+    if (!props.subscription) throw new Error("Select a subscription first.");
+    const request: SubscriptionCommand = {
+      type,
+      stripeSubscriptionId: props.subscription.stripeSubscriptionId,
+    };
+    if (type === "quantity") {
+      const quantity = Number(fields.quantity);
+      if (
+        !/^\d+$/.test(fields.quantity) ||
+        !Number.isSafeInteger(quantity) ||
+        quantity < 1
+      )
+        throw new Error("Enter a positive integer quantity.");
+      request.quantity = quantity;
+    }
+    if (type === "price") {
+      if (!fields.selectedPriceId) throw new Error("Choose a price first.");
+      request.stripePriceId = fields.selectedPriceId;
+    }
+    if (type === "trial") {
+      if (!fields.trialEnd || Number.isNaN(new Date(fields.trialEnd).getTime()))
+        throw new Error("Enter a valid trial end date.");
+      request.trialEnd = fields.trialEnd;
+    }
+    if (type === "endTrial") request.trialEnd = "now";
+    await props.onAction(request);
+    return `${labels[type]} requested. Waiting for Stripe webhook sync.`;
+  }, scope);
+  const active =
+    props.subscription?.status === "active" ||
+    props.subscription?.status === "trialing";
+  return {
+    ...fields,
+    setQuantity: (quantity: string) =>
+      setFields((previous) => ({ ...previous, quantity })),
+    setSelectedPriceId: (selectedPriceId: string) =>
+      setFields((previous) => ({ ...previous, selectedPriceId })),
+    setTrialEnd: (trialEnd: string) =>
+      setFields((previous) => ({ ...previous, trialEnd })),
+    pendingAction: action.isPending ? labels[operation] : null,
+    isPending: action.isPending,
+    message: action.error ?? action.result ?? null,
+    error: action.error,
+    canPause: active && !props.subscription?.isCollectionPaused,
+    canResume: !!props.subscription?.isCollectionPaused,
+    canReactivate: active && !!props.subscription?.cancelAtPeriodEnd,
+    run: action.run,
+  };
+}
+export type SubscriptionManagerProps = SubscriptionManagerOptions & {
+  children?: (state: ReturnType<typeof useSubscriptionManager>) => ReactNode;
+};
+export function SubscriptionManager(props: SubscriptionManagerProps) {
+  const state = useSubscriptionManager(props);
+  const id = useId();
+  if (props.children) return <>{props.children(state)}</>;
+  if (!props.subscription) return <p>No subscription selected.</p>;
+  return (
+    <section
+      data-better-stripe="subscription-manager"
+      aria-busy={state.isPending}
+    >
+      <SubscriptionCard
+        subscription={{
+          ...props.subscription,
+          isTrialing: props.subscription.isTrialing ?? false,
+          cancelAtPeriodEnd: props.subscription.cancelAtPeriodEnd ?? false,
+        }}
+      />
+      {state.message && (
+        <p role={state.error ? "alert" : "status"}>{state.message}</p>
+      )}
+      {(
+        [
+          ["pause", state.canPause],
+          ["resume", state.canResume],
+          ["reactivate", state.canReactivate],
+          [
+            "cancel",
+            !props.subscription.cancelAtPeriodEnd &&
+              props.subscription.status !== "canceled",
+          ],
+        ] as const
+      ).map(([type, enabled]) => (
+        <button
+          type="button"
+          key={type}
+          disabled={!enabled || state.isPending}
+          onClick={() => {
+            void state.run(type);
+          }}
+        >
+          {state.pendingAction === labels[type] ? "Processing…" : labels[type]}
+        </button>
+      ))}
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          void state.run("price");
+        }}
+      >
+        <label htmlFor={`${id}-price`}>Price ID</label>
+        <input
+          id={`${id}-price`}
+          required
+          value={state.selectedPriceId}
+          onChange={(event) => state.setSelectedPriceId(event.target.value)}
+        />
+        <button type="submit" disabled={state.isPending}>
+          Change plan
+        </button>
+      </form>
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          void state.run("quantity");
+        }}
+      >
+        <label htmlFor={`${id}-quantity`}>Quantity</label>
+        <input
+          id={`${id}-quantity`}
+          type="number"
+          min="1"
+          step="1"
+          required
+          value={state.quantity}
+          onChange={(event) => state.setQuantity(event.target.value)}
+        />
+        <button type="submit" disabled={state.isPending}>
+          Update quantity
+        </button>
+      </form>
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          void state.run("trial");
+        }}
+      >
+        <label htmlFor={`${id}-trial`}>Trial end</label>
+        <input
+          id={`${id}-trial`}
+          type="datetime-local"
+          required
+          value={state.trialEnd}
+          onChange={(event) => state.setTrialEnd(event.target.value)}
+        />
+        <button type="submit" disabled={state.isPending}>
+          Set trial end
+        </button>
+      </form>
+      <button
+        type="button"
+        disabled={state.isPending}
+        onClick={() => {
+          void state.run("endTrial");
+        }}
+      >
+        End trial now
+      </button>
+    </section>
+  );
+}
+export const SUBSCRIPTION_FILTERS = [
+  { label: "All", value: "all" },
+  { label: "Active", value: "active" },
+  { label: "Trialing", value: "trialing" },
+  { label: "Past Due", value: "past_due" },
+  { label: "Canceled", value: "canceled" },
+] as const;
+export function useSubscriptionFilter<T extends { status: string }>(
+  subscriptions: T[] | undefined,
+) {
+  const [filter, setFilter] = useState("all");
+  return {
+    filter,
+    setFilter,
+    filtered:
+      filter === "all"
+        ? (subscriptions ?? [])
+        : (subscriptions?.filter((row) => row.status === filter) ?? []),
+    countByStatus: (status: string) =>
+      subscriptions?.filter((row) => row.status === status).length ?? 0,
+    tabs: SUBSCRIPTION_FILTERS,
+  };
+}
+export type SubscriptionsProps<Row extends SubscriptionRow = SubscriptionRow> =
+  Omit<CollectionProps<Row>, "getKey" | "columns"> & {
+    columns?: WorkflowColumn<Row>[];
+  };
+export function Subscriptions<Row extends SubscriptionRow>(
+  props: SubscriptionsProps<Row>,
+) {
+  const columns: WorkflowColumn<Row>[] = [
+    {
+      id: "id",
+      label: "Subscription",
+      cell: (row) => row.stripeSubscriptionId,
+    },
+    { id: "status", label: "Status", cell: (row) => row.status },
+    {
+      id: "period",
+      label: "Current period end",
+      cell: (row) =>
+        row.currentPeriodEnd
+          ? new Date(row.currentPeriodEnd).toLocaleDateString()
+          : "Not supplied",
+    },
+    {
+      id: "trial",
+      label: "Trial end",
+      cell: (row) =>
+        row.trialEnd ? new Date(row.trialEnd).toLocaleDateString() : "None",
+    },
+  ];
+  return (
+    <Collection
+      emptyLabel="No subscriptions yet."
+      {...props}
+      columns={props.columns ?? columns}
+      getKey={(row) => row.stripeSubscriptionId}
+    />
+  );
+}

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

@@ -0,0 +1,23 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, expect, it } from "vitest";
+import { useTaskRunner } from "./Tasks.js";
+afterEach(cleanup);
+it("retains per-operation results and errors and keeps only a bounded activity log", async () => {
+  const { result } = renderHook(() => useTaskRunner({ maxEntries: 2 }));
+  await act(async () => {
+    await result.current.run("Products", async () => ({ count: 3 }));
+  });
+  expect(result.current.results.Products).toBe("Completed");
+  await act(async () => {
+    await result.current.run("Accounts", async () => {
+      throw new Error("Restricted");
+    });
+  });
+  expect(result.current.errors.Accounts).toBe("Restricted");
+  await act(async () => {
+    await result.current.run("Subscriptions", async () => null);
+  });
+  expect(result.current.log).toHaveLength(2);
+  expect(result.current.results.Products).toBe("Completed");
+});