@fantastic.dev/better-stripe 0.8.1 → 0.10.0

package/src/react/workflows/Pagination.tsx

@@ -0,0 +1,93 @@
+"use client";
+import { useState, type ReactNode } from "react";
+
+/** Cursor history for bounded server pages. Changing scope resets navigation. */
+export function useCursorPagination(scopeKey: string) {
+  const initial = { scopeKey, cursors: [null] as (string | null)[], index: 0 };
+  const [state, setState] = useState(initial);
+  const current = state.scopeKey === scopeKey ? state : initial;
+  if (state.scopeKey !== scopeKey) setState(initial);
+  return {
+    cursor: current.cursors[current.index],
+    page: current.index + 1,
+    canPrevious: current.index > 0,
+    previous: () =>
+      setState((previous) => ({
+        ...previous,
+        index: Math.max(0, previous.index - 1),
+      })),
+    next: (cursor: string) =>
+      setState((previous) => ({
+        ...previous,
+        cursors: [...previous.cursors.slice(0, previous.index + 1), cursor],
+        index: previous.index + 1,
+      })),
+  };
+}
+export type PaginationProps = {
+  page: number;
+  canPrevious: boolean;
+  canNext: boolean;
+  isLoading?: boolean;
+  onPrevious: () => void;
+  onNext: () => void;
+  previousLabel?: string;
+  nextLabel?: string;
+  pageLabel?: string;
+  children?: (state: {
+    pageLabel: string;
+    previousLabel: string;
+    nextLabel: string;
+    previousDisabled: boolean;
+    nextDisabled: boolean;
+    previous: () => void;
+    next: () => void;
+  }) => ReactNode;
+};
+/** Unstyled navigation with render props for application design systems. */
+export function Pagination({
+  page,
+  canPrevious,
+  canNext,
+  isLoading = false,
+  onPrevious,
+  onNext,
+  previousLabel = "Previous",
+  nextLabel = "Next",
+  pageLabel = `Page ${page}`,
+  children,
+}: PaginationProps) {
+  const previousDisabled = isLoading || !canPrevious;
+  const nextDisabled = isLoading || !canNext;
+  const state = {
+    pageLabel,
+    previousLabel,
+    nextLabel,
+    previousDisabled,
+    nextDisabled,
+    previous: () => {
+      if (!previousDisabled) onPrevious();
+    },
+    next: () => {
+      if (!nextDisabled) onNext();
+    },
+  };
+  if (children) return <>{children(state)}</>;
+  return (
+    <nav aria-label="Pagination">
+      <button
+        type="button"
+        disabled={previousDisabled}
+        onClick={state.previous}
+      >
+        {previousLabel}
+      </button>
+      <span role="status" aria-live="polite">
+        {pageLabel}
+      </span>
+      <button type="button" disabled={nextDisabled} onClick={state.next}>
+        {nextLabel}
+      </button>
+    </nav>
+  );
+}

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

@@ -110,3 +110,36 @@ it("keeps completed payouts out of upcoming and sorts the remaining arrivals", a
   );
   expect(screen.getAllByText("po_paid")).toHaveLength(1);
 });
+it("distinguishes an unavailable account from an empty balance and labels upcoming previews", async () => {
+  const load = vi.fn().mockResolvedValue({
+    status: "not_ready",
+    reason: "account_unavailable",
+    balances: [],
+    upcoming: [],
+    payouts: [],
+    nextCursor: null,
+    upcomingComplete: true,
+  });
+  const { unmount } = render(<Payouts scopeKey="unavailable" load={load} />);
+  expect((await screen.findByRole("alert")).textContent).toContain(
+    "not available",
+  );
+  expect(screen.queryByText("Not scheduled")).toBeNull();
+  unmount();
+  render(
+    <Payouts
+      scopeKey="preview"
+      load={async () => ({
+        status: "ready",
+        balances: [],
+        upcoming: [],
+        payouts: [],
+        nextCursor: null,
+        upcomingComplete: false,
+      })}
+    />,
+  );
+  expect(
+    await screen.findByText(/Upcoming payouts are a bounded preview/),
+  ).toBeTruthy();
+});

package/src/react/workflows/Payouts.tsx

@@ -1,4 +1,8 @@
 "use client";
+import type {
+  RecipientPayoutSnapshot,
+  RecipientPayoutRow,
+} from "../../client/connect/payoutSnapshot.js";
 import { useState, type ReactNode } from "react";
 import { Connect, type ConnectProps } from "./Connect.js";
 import { useWorkflowAction } from "./useWorkflowAction.js";
@@ -9,20 +13,14 @@ import {
   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 PayoutRow = RecipientPayoutRow;
+export type PayoutSnapshot = Pick<
+  RecipientPayoutSnapshot,
+  "balances" | "payouts" | "upcoming" | "nextCursor"
+> &
+  Partial<
+    Pick<RecipientPayoutSnapshot, "status" | "reason" | "upcomingComplete">
+  >;
 export type PayoutsRenderProps = {
   data: PayoutSnapshot | undefined;
   error: string | null;
@@ -169,7 +167,10 @@ function NativePayouts({
       </button>
       {error && <p role="alert">{error}</p>}
       {isLoading && !data && <p role="status">Loading payouts…</p>}
-      {data && (
+      {data?.status === "not_ready" && (
+        <p role="alert">Stripe account data is not available yet.</p>
+      )}
+      {data && data.status !== "not_ready" && (
         <>
           <dl>
             {data.balances.map((balance) => (
@@ -188,6 +189,11 @@ function NativePayouts({
             </dd>
           </dl>
           <h3>Upcoming payouts</h3>
+          {data.upcomingComplete === false && (
+            <p>
+              Upcoming payouts are a bounded preview. More may be scheduled.
+            </p>
+          )}
           <PayoutHistory
             rows={upcomingPayouts}
             emptyLabel="No upcoming payouts scheduled."

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

@@ -0,0 +1,79 @@
+// @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 { PlanPricingEditor } from "./PlanPricingEditor.js";
+afterEach(cleanup);
+it("validates money and percentages before saving minor units", async () => {
+  const save = vi.fn().mockResolvedValue(undefined);
+  render(
+    <PlanPricingEditor
+      plan={{
+        id: "starter",
+        name: "Starter",
+        monthlyAmount: 900,
+        feeBasisPoints: 900,
+        version: 0,
+      }}
+      onSave={save}
+    />,
+  );
+  const monthly = screen.getByLabelText("Monthly price (USD)");
+  await userEvent.clear(monthly);
+  await userEvent.type(monthly, "12.34");
+  const fee = screen.getByLabelText("Sale fee (%)");
+  await userEvent.clear(fee);
+  await userEvent.type(fee, "7.5");
+  await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+  expect(save).toHaveBeenCalledWith({
+    monthlyAmount: 1234,
+    feeBasisPoints: 750,
+    affiliateBasisPoints: 0,
+    expectedVersion: 0,
+  });
+  expect(screen.getByRole("status").textContent).toContain("saved");
+  await userEvent.clear(fee);
+  await userEvent.type(fee, "101");
+  await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+  expect(save).toHaveBeenCalledTimes(1);
+  expect(screen.getByRole("alert").textContent).toMatch(/fee/i);
+  await userEvent.clear(fee);
+  await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+  expect(save).toHaveBeenLastCalledWith({
+    monthlyAmount: 1234,
+    feeBasisPoints: null,
+    affiliateBasisPoints: 0,
+    expectedVersion: 0,
+  });
+});
+it("validates affiliate payout percentages and saves basis points", async () => {
+  const save = vi.fn().mockResolvedValue(undefined);
+  render(
+    <PlanPricingEditor
+      plan={{
+        id: "growth",
+        name: "Growth",
+        monthlyAmount: 4900,
+        feeBasisPoints: 490,
+        affiliateBasisPoints: 2000,
+        version: 1,
+      }}
+      onSave={save}
+    />,
+  );
+  const share = screen.getByLabelText("Affiliate payout (%)");
+  await userEvent.clear(share);
+  await userEvent.type(share, "12.5");
+  await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+  expect(save).toHaveBeenLastCalledWith({
+    monthlyAmount: 4900,
+    feeBasisPoints: 490,
+    affiliateBasisPoints: 1250,
+    expectedVersion: 1,
+  });
+  await userEvent.clear(share);
+  await userEvent.type(share, "100.001");
+  await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+  expect(save).toHaveBeenCalledTimes(1);
+  expect(screen.getByRole("alert").textContent).toMatch(/affiliate/i);
+});

package/src/react/workflows/PlanPricingEditor.tsx

@@ -0,0 +1,156 @@
+"use client";
+import { useId, useState, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+export type PlanPricing = {
+  id: string;
+  name: string;
+  monthlyAmount: number;
+  feeBasisPoints: number | null;
+  affiliateBasisPoints?: number | null;
+  version: number;
+};
+export type PlanPricingUpdate = {
+  monthlyAmount: number;
+  feeBasisPoints: number | null;
+  affiliateBasisPoints?: number | null;
+  expectedVersion: number;
+};
+export type PlanPricingEditorState = {
+  monthlyPrice: string;
+  saleFee: string;
+  affiliateShare: string;
+  setMonthlyPrice: (value: string) => void;
+  setSaleFee: (value: string) => void;
+  setAffiliateShare: (value: string) => void;
+  save: () => Promise<unknown>;
+  isPending: boolean;
+  error: string | null;
+  message: string | undefined;
+};
+export type PlanPricingEditorProps = {
+  plan: PlanPricing;
+  onSave: (update: PlanPricingUpdate) => Promise<unknown>;
+  children?: (state: PlanPricingEditorState) => ReactNode;
+};
+/** Unstyled store-plan pricing editor. Authorization and Stripe price creation belong on the server. */
+export function PlanPricingEditor({
+  plan,
+  onSave,
+  children,
+}: PlanPricingEditorProps) {
+  const id = useId();
+  const scope = `${plan.id}:${plan.version}`;
+  const initial = {
+    scope,
+    affiliateShare: String((plan.affiliateBasisPoints ?? 0) / 100),
+    monthlyPrice: (plan.monthlyAmount / 100).toFixed(2),
+    saleFee:
+      plan.feeBasisPoints === null ? "" : String(plan.feeBasisPoints / 100),
+  };
+  const [fields, setFields] = useState(initial);
+  if (fields.scope !== scope) setFields(initial);
+  const action = useWorkflowAction(async () => {
+    if (!/^\d+(\.\d{1,2})?$/.test(fields.monthlyPrice.trim()))
+      throw new Error(
+        "Enter a positive monthly price with at most two decimal places.",
+      );
+    const monthlyAmount = Math.round(Number(fields.monthlyPrice) * 100);
+    if (!Number.isSafeInteger(monthlyAmount) || monthlyAmount <= 0)
+      throw new Error("Enter a positive monthly price.");
+    const feeBasisPoints =
+      fields.saleFee.trim() === ""
+        ? null
+        : Math.round(Number(fields.saleFee) * 100);
+    if (
+      feeBasisPoints !== null &&
+      (!/^\d+(\.\d{1,2})?$/.test(fields.saleFee.trim()) ||
+        !Number.isSafeInteger(feeBasisPoints) ||
+        feeBasisPoints < 0 ||
+        feeBasisPoints > 10000)
+    )
+      throw new Error(
+        "Enter a sale fee from 0 to 100%, with at most two decimal places, or leave it blank for Stripe processing only.",
+      );
+    const affiliateBasisPoints = Math.round(
+      Number(fields.affiliateShare) * 100,
+    );
+    if (
+      !/^\d+(\.\d{1,2})?$/.test(fields.affiliateShare.trim()) ||
+      !Number.isSafeInteger(affiliateBasisPoints) ||
+      affiliateBasisPoints < 0 ||
+      affiliateBasisPoints > 10000
+    )
+      throw new Error(
+        "Enter an affiliate payout from 0 to 100%, with at most two decimal places.",
+      );
+    await onSave({
+      monthlyAmount,
+      feeBasisPoints,
+      affiliateBasisPoints,
+      expectedVersion: plan.version,
+    });
+    return "Pricing saved. Existing subscriptions keep their monthly price.";
+  }, plan.id);
+  const state: PlanPricingEditorState = {
+    ...fields,
+    setMonthlyPrice: (monthlyPrice) =>
+      setFields((previous) => ({ ...previous, monthlyPrice })),
+    setSaleFee: (saleFee) =>
+      setFields((previous) => ({ ...previous, saleFee })),
+    setAffiliateShare: (affiliateShare) =>
+      setFields((previous) => ({ ...previous, affiliateShare })),
+    save: action.run,
+    isPending: action.isPending,
+    error: action.error,
+    message: action.result,
+  };
+  if (children) return <>{children(state)}</>;
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        void state.save();
+      }}
+      aria-label={`${plan.name} pricing`}
+    >
+      <h3>{plan.name}</h3>
+      <label htmlFor={`${id}-monthly`}>Monthly price (USD)</label>
+      <input
+        id={`${id}-monthly`}
+        inputMode="decimal"
+        value={state.monthlyPrice}
+        disabled={state.isPending}
+        onChange={(event) => state.setMonthlyPrice(event.target.value)}
+      />
+      <label htmlFor={`${id}-fee`}>Sale fee (%)</label>
+      <input
+        id={`${id}-fee`}
+        inputMode="decimal"
+        value={state.saleFee}
+        disabled={state.isPending}
+        onChange={(event) => state.setSaleFee(event.target.value)}
+      />
+      <p>
+        Leave the sale fee blank for Stripe processing only. The seller always
+        covers actual Stripe processing costs.
+      </p>
+      <label htmlFor={`${id}-affiliate`}>Affiliate payout (%)</label>
+      <input
+        id={`${id}-affiliate`}
+        inputMode="decimal"
+        value={state.affiliateShare}
+        disabled={state.isPending}
+        onChange={(event) => state.setAffiliateShare(event.target.value)}
+      />
+      <p>
+        Percentage of a referred sale after the sale fee. The seller receives
+        the remainder.
+      </p>
+      {state.error && <p role="alert">{state.error}</p>}
+      {state.message && <p role="status">{state.message}</p>}
+      <button type="submit" disabled={state.isPending}>
+        {state.isPending ? "Saving…" : "Save pricing"}
+      </button>
+    </form>
+  );
+}

package/src/react/workflows/index.ts

@@ -236,3 +236,25 @@ export type {
   PaymentDetailsPayment,
   PaymentDetailsState,
 } from "./Financials.js";
+export { Pagination, useCursorPagination } from "./Pagination.js";
+export type { PaginationProps } from "./Pagination.js";
+export { PlanPricingEditor } from "./PlanPricingEditor.js";
+export type {
+  PlanPricing,
+  PlanPricingUpdate,
+  PlanPricingEditorState,
+  PlanPricingEditorProps,
+} from "./PlanPricingEditor.js";
+export { AffiliateRateEditor } from "./AffiliateRateEditor.js";
+export type {
+  AffiliateRateUpdate,
+  AffiliateRateEditorProps,
+  AffiliateRateEditorState,
+} from "./AffiliateRateEditor.js";
+export { AffiliatePayoutEditor } from "./AffiliatePayoutEditor.js";
+export type {
+  AffiliateCommissionTerm,
+  AffiliatePayoutEditorProps,
+  AffiliatePayoutEditorState,
+  AffiliatePayoutUpdate,
+} from "./AffiliatePayoutEditor.js";