@fantastic.dev/better-stripe 0.7.0 → 0.8.1

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

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