@fantastic.dev/better-stripe 0.7.0 → 0.8.0

package/src/react/workflows/Payouts.tsx

@@ -0,0 +1,212 @@
+"use client";
+import { useState, type ReactNode } from "react";
+import { Connect, type ConnectProps } from "./Connect.js";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { useWorkflowResource } from "./useWorkflowResource.js";
+import {
+  Collection,
+  type CollectionProps,
+  type WorkflowColumn,
+} from "./Collection.js";
+import { formatPrice } from "../lib/price-helpers.js";
+export type PayoutRow = {
+  id: string;
+  amount: number;
+  currency: string;
+  status: string;
+  /** Unix milliseconds. */ arrivalDate: number | null;
+  created: number;
+};
+export type PayoutSnapshot = {
+  balances: { currency: string; available: number; pending: number }[];
+  payouts: PayoutRow[];
+  upcoming: PayoutRow[];
+  nextCursor: string | null;
+};
+export type PayoutsRenderProps = {
+  data: PayoutSnapshot | undefined;
+  error: string | null;
+  isLoading: boolean;
+  isPending: boolean;
+  nextPayout: PayoutRow | undefined;
+  previousPayouts: PayoutRow[];
+  refresh: () => void;
+  loadMore: () => Promise<void>;
+};
+export type HeadlessPayoutsProps = {
+  presentation?: "headless";
+  scopeKey: string;
+  load: (cursor?: string) => Promise<PayoutSnapshot>;
+  children?: (state: PayoutsRenderProps) => ReactNode;
+};
+export type PayoutsProps =
+  | HeadlessPayoutsProps
+  | (Omit<ConnectProps, "component"> & { presentation: "embedded" });
+const upcoming = (row: PayoutRow) =>
+  row.status === "pending" || row.status === "in_transit";
+export function Payouts(props: PayoutsProps) {
+  return props.presentation === "embedded" ? (
+    <Connect {...props} component="payouts" />
+  ) : (
+    <PayoutsBody key={props.scopeKey} {...props} />
+  );
+}
+function PayoutsBody({ load, scopeKey, children }: HeadlessPayoutsProps) {
+  const resource = useWorkflowResource(() => load(), scopeKey);
+  const more = useWorkflowAction(
+    (cursor: string) => load(cursor),
+    `${scopeKey}:${resource.revision}`,
+  );
+  const [pages, setPages] = useState<{
+    base: PayoutSnapshot | undefined;
+    rows: PayoutRow[];
+    cursor: string | null | undefined;
+  }>({ base: undefined, rows: [], cursor: undefined });
+  if (pages.base !== resource.data)
+    setPages({ base: resource.data, rows: [], cursor: undefined });
+  const base = resource.data;
+  const nextCursor =
+    pages.cursor === undefined ? (base?.nextCursor ?? null) : pages.cursor;
+  const data = base
+    ? {
+        ...base,
+        nextCursor,
+        payouts: [
+          ...new Map(
+            [...base.payouts, ...pages.rows].map((row) => [row.id, row]),
+          ).values(),
+        ],
+      }
+    : undefined;
+  const loadMore = async () => {
+    if (!nextCursor || resource.isLoading) return;
+    const next = await more.run(nextCursor);
+    if (next)
+      setPages((previous) => ({
+        ...previous,
+        rows: [...previous.rows, ...next.payouts],
+        cursor: next.nextCursor,
+      }));
+  };
+  const sortedUpcoming =
+    data?.upcoming
+      .filter(upcoming)
+      .slice()
+      .sort(
+        (a, b) => (a.arrivalDate ?? Infinity) - (b.arrivalDate ?? Infinity),
+      ) ?? [];
+  const state: PayoutsRenderProps = {
+    data,
+    isLoading: resource.isLoading,
+    isPending: resource.isLoading || more.isPending,
+    error: resource.error ?? more.error,
+    nextPayout: sortedUpcoming[0],
+    previousPayouts: data?.payouts.filter((row) => !upcoming(row)) ?? [],
+    refresh: resource.refresh,
+    loadMore,
+  };
+  return <>{children ? children(state) : <NativePayouts {...state} />}</>;
+}
+function date(value: number | null) {
+  return value === null
+    ? "Not supplied by Stripe"
+    : new Date(value).toLocaleDateString(undefined, { timeZone: "UTC" });
+}
+export type PayoutHistoryRow = Pick<
+  PayoutRow,
+  "id" | "amount" | "currency" | "status" | "arrivalDate"
+>;
+export type PayoutHistoryProps<
+  Row extends PayoutHistoryRow = PayoutHistoryRow,
+> = Omit<CollectionProps<Row>, "columns" | "getKey"> & {
+  columns?: WorkflowColumn<Row>[];
+};
+export function PayoutHistory<Row extends PayoutHistoryRow>(
+  props: PayoutHistoryProps<Row>,
+) {
+  const columns: WorkflowColumn<Row>[] = [
+    { id: "id", label: "Payout ID", cell: (row) => row.id },
+    {
+      id: "amount",
+      label: "Amount",
+      align: "end",
+      cell: (row) => formatPrice(row.amount, row.currency),
+    },
+    { id: "status", label: "Status", cell: (row) => row.status },
+    {
+      id: "arrival",
+      label: "Arrival date",
+      cell: (row) => date(row.arrivalDate),
+    },
+  ];
+  return (
+    <Collection
+      emptyLabel="No payouts yet."
+      {...props}
+      getKey={(row) => row.id}
+      columns={props.columns ?? columns}
+    />
+  );
+}
+function NativePayouts({
+  data,
+  isLoading,
+  isPending,
+  error,
+  nextPayout,
+  previousPayouts,
+  refresh,
+  loadMore,
+}: PayoutsRenderProps) {
+  return (
+    <section data-better-stripe="payouts" aria-busy={isPending}>
+      <h2>Payouts</h2>
+      <button type="button" disabled={isPending} onClick={refresh}>
+        {isPending ? "Refreshing…" : "Refresh"}
+      </button>
+      {error && <p role="alert">{error}</p>}
+      {isLoading && !data && <p role="status">Loading payouts…</p>}
+      {data && (
+        <>
+          <dl>
+            {data.balances.map((balance) => (
+              <div key={balance.currency}>
+                <dt>Available</dt>
+                <dd>{formatPrice(balance.available, balance.currency)}</dd>
+                <dt>Pending</dt>
+                <dd>{formatPrice(balance.pending, balance.currency)}</dd>
+              </div>
+            ))}
+            <dt>Next payout</dt>
+            <dd>
+              {nextPayout
+                ? `${formatPrice(nextPayout.amount, nextPayout.currency)} · ${date(nextPayout.arrivalDate)}`
+                : "Not scheduled"}
+            </dd>
+          </dl>
+          <h3>Upcoming payouts</h3>
+          <PayoutHistory
+            rows={data.upcoming}
+            emptyLabel="No upcoming payouts scheduled."
+          />
+          <h3>Previous payouts</h3>
+          <PayoutHistory
+            rows={previousPayouts}
+            emptyLabel="No previous payouts yet."
+          />
+          {data.nextCursor && (
+            <button
+              type="button"
+              disabled={isPending}
+              onClick={() => {
+                void loadMore();
+              }}
+            >
+              {isPending ? "Loading…" : "Load more payouts"}
+            </button>
+          )}
+        </>
+      )}
+    </section>
+  );
+}

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

@@ -0,0 +1,90 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { useProductManager } from "./Products.js";
+afterEach(cleanup);
+it("validates product names and price minor units before mutation", async () => {
+  const createProduct = vi.fn().mockResolvedValue("prod_test");
+  const createPrice = vi.fn().mockResolvedValue("price_test");
+  const { result } = renderHook(() =>
+    useProductManager({ scopeKey: "seller", createProduct, createPrice }),
+  );
+  await act(async () => {
+    await result.current.handleCreateProduct();
+  });
+  expect(createProduct).not.toHaveBeenCalled();
+  act(() =>
+    result.current.setNewProduct({
+      name: "  Classic Tee  ",
+      description: "Cotton",
+    }),
+  );
+  await act(async () => {
+    await result.current.handleCreateProduct();
+  });
+  expect(createProduct).toHaveBeenCalledWith({
+    name: "Classic Tee",
+    description: "Cotton",
+  });
+  act(() =>
+    result.current.setNewPrice({
+      amount: "12.50",
+      currency: "usd",
+      interval: "one_time",
+    }),
+  );
+  await act(async () => {
+    await result.current.handleAddPrice("prod_test");
+  });
+  expect(createPrice).not.toHaveBeenCalled();
+  act(() =>
+    result.current.setNewPrice({
+      amount: "2900",
+      currency: "usd",
+      interval: "one_time",
+    }),
+  );
+  await act(async () => {
+    await result.current.handleAddPrice("prod_test");
+  });
+  expect(createPrice).toHaveBeenCalledWith({
+    stripeProductId: "prod_test",
+    unitAmount: 2900,
+    currency: "usd",
+    type: "one_time",
+    interval: undefined,
+  });
+});
+
+it("keeps the active product operation when a second operation is attempted", async () => {
+  let finish!: () => void;
+  const deactivateProduct = vi.fn(
+    () =>
+      new Promise<void>((resolve) => {
+        finish = resolve;
+      }),
+  );
+  const deactivatePrice = vi.fn();
+  const { result } = renderHook(() =>
+    useProductManager({
+      scopeKey: "seller",
+      createProduct: async () => null,
+      createPrice: async () => null,
+      deactivateProduct,
+      deactivatePrice,
+    }),
+  );
+  let pending!: Promise<unknown>;
+  act(() => {
+    pending = result.current.handleDeactivate("prod_one");
+  });
+  await act(async () => {
+    await result.current.handleDeactivatePrice("price_one");
+  });
+  expect(result.current.deactivatingId).toBe("prod_one");
+  expect(deactivatePrice).not.toHaveBeenCalled();
+  await act(async () => {
+    finish();
+    await pending;
+  });
+});

package/src/react/workflows/Products.tsx

@@ -0,0 +1,377 @@
+"use client";
+import { useId, useState, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+import { PriceCard, type PriceCardPrice } from "../components/PriceCard.js";
+export type ProductInput = { name: string; description?: string };
+export type PriceInput = {
+  stripeProductId: string;
+  unitAmount: number;
+  currency: string;
+  type: "one_time" | "recurring";
+  interval?: "month" | "year" | "week" | "day";
+};
+export type ProductActions = {
+  scopeKey: string;
+  createProduct: (args: ProductInput) => Promise<unknown>;
+  createPrice: (args: PriceInput) => Promise<unknown>;
+  updateProduct?: (
+    args: ProductInput & { stripeProductId: string },
+  ) => Promise<unknown>;
+  deactivateProduct?: (args: { stripeProductId: string }) => Promise<unknown>;
+  deactivatePrice?: (args: { stripePriceId: string }) => Promise<unknown>;
+};
+export type ProductEdit = {
+  stripeProductId: string;
+  name: string;
+  description: string;
+};
+export function useProductManager(props: ProductActions) {
+  const initial = {
+    scope: props.scopeKey,
+    expandedProduct: null as string | null,
+    showCreateDialog: false,
+    showAddPriceFor: null as string | null,
+    newProduct: { name: "", description: "" },
+    newPrice: { amount: "", currency: "usd", interval: "month" },
+    editingProduct: null as ProductEdit | null,
+  };
+  const [fields, setFields] = useState(initial);
+  if (fields.scope !== props.scopeKey) setFields(initial);
+  type Command = {
+    type: "create" | "price" | "edit" | "archiveProduct" | "archivePrice";
+    id?: string;
+  };
+  const [command, setCommand] = useState<Command | null>(null);
+  const action = useWorkflowAction(async (command: Command) => {
+    setCommand(command);
+    switch (command.type) {
+      case "create": {
+        if (!fields.newProduct.name.trim())
+          throw new Error("Enter a product name.");
+        await props.createProduct({
+          name: fields.newProduct.name.trim(),
+          description: fields.newProduct.description.trim() || undefined,
+        });
+        break;
+      }
+      case "price": {
+        const unitAmount = Number(fields.newPrice.amount);
+        if (
+          !/^\d+$/.test(fields.newPrice.amount) ||
+          !Number.isSafeInteger(unitAmount) ||
+          unitAmount <= 0
+        )
+          throw new Error("Enter a positive integer price in minor units.");
+        if (!/^[a-zA-Z]{3}$/.test(fields.newPrice.currency))
+          throw new Error("Enter a three-letter currency code.");
+        const interval = fields.newPrice.interval;
+        if (!["one_time", "month", "year", "week", "day"].includes(interval))
+          throw new Error("Choose a supported price interval.");
+        await props.createPrice({
+          stripeProductId: command.id!,
+          unitAmount,
+          currency: fields.newPrice.currency.toLowerCase(),
+          type: interval === "one_time" ? "one_time" : "recurring",
+          interval:
+            interval === "one_time"
+              ? undefined
+              : (interval as PriceInput["interval"]),
+        });
+        break;
+      }
+      case "edit": {
+        if (!props.updateProduct || !fields.editingProduct)
+          throw new Error("Product editing is not configured.");
+        if (!fields.editingProduct.name.trim())
+          throw new Error("Enter a product name.");
+        await props.updateProduct({
+          stripeProductId: fields.editingProduct.stripeProductId,
+          name: fields.editingProduct.name.trim(),
+          description: fields.editingProduct.description.trim() || undefined,
+        });
+        break;
+      }
+      case "archiveProduct":
+        if (!props.deactivateProduct)
+          throw new Error("Product archiving is not configured.");
+        else await props.deactivateProduct({ stripeProductId: command.id! });
+        break;
+      case "archivePrice":
+        if (!props.deactivatePrice)
+          throw new Error("Price archiving is not configured.");
+        else await props.deactivatePrice({ stripePriceId: command.id! });
+        break;
+    }
+    return true;
+  }, props.scopeKey);
+  const run = action.run;
+  const set = <K extends keyof typeof initial>(
+    key: K,
+    value: (typeof initial)[K],
+  ) => setFields((previous) => ({ ...previous, [key]: value }));
+  return {
+    ...fields,
+    error: action.error,
+    clearError: action.reset,
+    isPending: action.isPending,
+    isCreatingProduct: action.isPending && command?.type === "create",
+    isCreatingPrice: action.isPending && command?.type === "price",
+    isSavingEdit: action.isPending && command?.type === "edit",
+    deactivatingId:
+      action.isPending && command?.type === "archiveProduct"
+        ? command.id
+        : null,
+    deactivatingPriceId:
+      action.isPending && command?.type === "archivePrice" ? command.id : null,
+    setExpandedProduct: (value: string | null) => set("expandedProduct", value),
+    setShowCreateDialog: (value: boolean) => set("showCreateDialog", value),
+    setShowAddPriceFor: (value: string | null) => set("showAddPriceFor", value),
+    setNewProduct: (value: typeof initial.newProduct) =>
+      set("newProduct", value),
+    setNewPrice: (value: typeof initial.newPrice) => set("newPrice", value),
+    setEditingProduct: (value: ProductEdit | null) =>
+      set("editingProduct", value),
+    handleCreateProduct: async () => {
+      if (await run({ type: "create" }))
+        setFields((previous) => ({
+          ...previous,
+          newProduct: initial.newProduct,
+          showCreateDialog: false,
+        }));
+    },
+    handleAddPrice: async (id: string) => {
+      if (await run({ type: "price", id }))
+        setFields((previous) => ({
+          ...previous,
+          newPrice: initial.newPrice,
+          showAddPriceFor: null,
+        }));
+    },
+    handleSaveEdit: async () => {
+      if (await run({ type: "edit" })) set("editingProduct", null);
+    },
+    handleDeactivate: (id: string) => run({ type: "archiveProduct", id }),
+    handleDeactivatePrice: (id: string) => run({ type: "archivePrice", id }),
+  };
+}
+export type CatalogProduct = {
+  stripeProductId: string;
+  name: string;
+  description?: string;
+  active: boolean;
+  prices: PriceCardPrice[];
+};
+export type ProductsRenderProps = ReturnType<typeof useProductManager> & {
+  products: CatalogProduct[];
+  isLoading: boolean;
+};
+export type ProductsProps = ProductActions & {
+  products: CatalogProduct[] | undefined;
+  children?: (state: ProductsRenderProps) => ReactNode;
+};
+/** Complete catalog creation/editing/archiving controller, with optional custom rendering. Amount inputs use minor units. */
+export function Products(props: ProductsProps) {
+  return <ProductsBody key={props.scopeKey} {...props} />;
+}
+function ProductsBody(props: ProductsProps) {
+  const state = useProductManager(props);
+  const id = useId();
+  const result = {
+    ...state,
+    products: props.products ?? [],
+    isLoading: props.products === undefined,
+  };
+  if (props.children) return <>{props.children(result)}</>;
+  return (
+    <section data-better-stripe="products" aria-busy={state.isPending}>
+      <h2>Products</h2>
+      {state.error && <p role="alert">{state.error}</p>}
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          void state.handleCreateProduct();
+        }}
+      >
+        <label htmlFor={`${id}-name`}>Product name</label>
+        <input
+          id={`${id}-name`}
+          required
+          value={state.newProduct.name}
+          onChange={(event) =>
+            state.setNewProduct({
+              ...state.newProduct,
+              name: event.target.value,
+            })
+          }
+        />
+        <label htmlFor={`${id}-description`}>Description</label>
+        <input
+          id={`${id}-description`}
+          value={state.newProduct.description}
+          onChange={(event) =>
+            state.setNewProduct({
+              ...state.newProduct,
+              description: event.target.value,
+            })
+          }
+        />
+        <button type="submit" disabled={state.isPending}>
+          {state.isCreatingProduct ? "Creating…" : "Create product"}
+        </button>
+      </form>
+      {result.isLoading ? (
+        <p role="status">Loading products…</p>
+      ) : !result.products.length ? (
+        <p>No products yet.</p>
+      ) : (
+        result.products.map((product) => (
+          <article key={product.stripeProductId}>
+            <h3>{product.name}</h3>
+            <p>{product.description}</p>
+            {product.prices.map((price) => (
+              <div key={price.stripePriceId}>
+                <PriceCard price={price}>
+                  {({ formattedPrice }) => <p>{formattedPrice}</p>}
+                </PriceCard>
+                {props.deactivatePrice && price.active && (
+                  <button
+                    type="button"
+                    disabled={state.isPending}
+                    onClick={() => {
+                      void state.handleDeactivatePrice(price.stripePriceId);
+                    }}
+                  >
+                    Archive price
+                  </button>
+                )}
+              </div>
+            ))}
+            <button
+              type="button"
+              disabled={state.isPending}
+              onClick={() => state.setShowAddPriceFor(product.stripeProductId)}
+            >
+              Add price
+            </button>
+            {props.updateProduct && (
+              <button
+                type="button"
+                onClick={() =>
+                  state.setEditingProduct({
+                    stripeProductId: product.stripeProductId,
+                    name: product.name,
+                    description: product.description ?? "",
+                  })
+                }
+              >
+                Edit product
+              </button>
+            )}
+            {props.deactivateProduct && (
+              <button
+                type="button"
+                disabled={state.isPending}
+                onClick={() => {
+                  void state.handleDeactivate(product.stripeProductId);
+                }}
+              >
+                Archive product
+              </button>
+            )}
+          </article>
+        ))
+      )}
+      {state.showAddPriceFor && (
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            void state.handleAddPrice(state.showAddPriceFor!);
+          }}
+        >
+          <label htmlFor={`${id}-amount`}>Price in minor units</label>
+          <input
+            id={`${id}-amount`}
+            type="number"
+            required
+            min="1"
+            step="1"
+            value={state.newPrice.amount}
+            onChange={(event) =>
+              state.setNewPrice({
+                ...state.newPrice,
+                amount: event.target.value,
+              })
+            }
+          />
+          <label htmlFor={`${id}-currency`}>Currency</label>
+          <input
+            id={`${id}-currency`}
+            required
+            minLength={3}
+            maxLength={3}
+            value={state.newPrice.currency}
+            onChange={(event) =>
+              state.setNewPrice({
+                ...state.newPrice,
+                currency: event.target.value,
+              })
+            }
+          />
+          <label htmlFor={`${id}-interval`}>Interval</label>
+          <select
+            id={`${id}-interval`}
+            value={state.newPrice.interval}
+            onChange={(event) =>
+              state.setNewPrice({
+                ...state.newPrice,
+                interval: event.target.value,
+              })
+            }
+          >
+            {["one_time", "month", "year", "week", "day"].map((value) => (
+              <option key={value}>{value}</option>
+            ))}
+          </select>
+          <button type="submit" disabled={state.isPending}>
+            {state.isCreatingPrice ? "Creating…" : "Create price"}
+          </button>
+        </form>
+      )}
+      {state.editingProduct && (
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            void state.handleSaveEdit();
+          }}
+        >
+          <label htmlFor={`${id}-edit-name`}>Product name</label>
+          <input
+            id={`${id}-edit-name`}
+            required
+            value={state.editingProduct.name}
+            onChange={(event) =>
+              state.setEditingProduct({
+                ...state.editingProduct!,
+                name: event.target.value,
+              })
+            }
+          />
+          <label htmlFor={`${id}-edit-description`}>Description</label>
+          <input
+            id={`${id}-edit-description`}
+            value={state.editingProduct.description}
+            onChange={(event) =>
+              state.setEditingProduct({
+                ...state.editingProduct!,
+                description: event.target.value,
+              })
+            }
+          />
+          <button type="submit" disabled={state.isPending}>
+            {state.isSavingEdit ? "Saving…" : "Save product"}
+          </button>
+        </form>
+      )}
+    </section>
+  );
+}