@tribe-nest/forge 1.13.0

package/src/ui/headless/forms/useSectionedForm.ts

@@ -0,0 +1,256 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { usePublicForm, useSubmitPublicForm } from "../../../data/queries/useForms";
+import type { FormData, FormField, FormFieldEdge } from "../../../types/models";
+
+const emailRe = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// --- Seeded per-attempt option shuffle (quiz mode) ---------------------------
+// Stable for the lifetime of the mount so the review screen matches the answered
+// order. Mirrors the flat renderer's shuffle helper.
+function hashSeed(str: string): number {
+  let h = 1779033703 ^ str.length;
+  for (let i = 0; i < str.length; i++) {
+    h = Math.imul(h ^ str.charCodeAt(i), 3432918353);
+    h = (h << 13) | (h >>> 19);
+  }
+  h = Math.imul(h ^ (h >>> 16), 2246822507);
+  h = Math.imul(h ^ (h >>> 13), 3266489909);
+  return (h ^= h >>> 16) >>> 0;
+}
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+function seededShuffle<T>(items: T[], rand: () => number): T[] {
+  const out = items.slice();
+  for (let i = out.length - 1; i > 0; i--) {
+    const j = Math.floor(rand() * (i + 1));
+    [out[i], out[j]] = [out[j], out[i]];
+  }
+  return out;
+}
+function shuffleFormOptions(form: FormData | undefined, seed: string): FormData | undefined {
+  if (!form) return form;
+  const settings = typeof form.settings === "string" ? safeParseSettings(form.settings) : form.settings || {};
+  if (!settings?.quiz?.enabled || !settings?.quiz?.shuffleOptions) return form;
+  const fields = form.fields.map((f) => {
+    if (!f.options || f.options.length < 2) return f;
+    return { ...f, options: seededShuffle(f.options, mulberry32(hashSeed(`${seed}:${f.id}`))) };
+  });
+  return { ...form, fields };
+}
+function safeParseSettings(s: string): any {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return {};
+  }
+}
+
+type Condition = { operator: string; value: string | string[] | null } | null;
+
+function evaluateCondition(raw: unknown, answer: string | undefined | null): boolean {
+  const condition = (typeof raw === "string" ? JSON.parse(raw) : raw) as Condition;
+  if (!condition || !condition.operator) return false;
+  const { operator, value } = condition;
+  switch (operator) {
+    case "equals":
+      return answer === value;
+    case "not_equals":
+      return answer !== value;
+    case "contains":
+      return typeof answer === "string" && typeof value === "string" && answer.includes(value);
+    case "is_empty":
+      return !answer || answer === "";
+    case "is_not_empty":
+      return !!answer && answer !== "";
+    default:
+      return false;
+  }
+}
+
+function buildModel(form?: FormData) {
+  const sections = [...(form?.sections ?? [])].sort((a, b) => a.order - b.order);
+  const byId = new Map(sections.map((s) => [s.id, s]));
+  const order = sections.map((s) => s.id);
+
+  const fieldsBySection = new Map<string, FormField[]>();
+  for (const f of form?.fields ?? []) {
+    if (!f.sectionId) continue;
+    const arr = fieldsBySection.get(f.sectionId) ?? [];
+    arr.push(f);
+    fieldsBySection.set(f.sectionId, arr);
+  }
+  for (const arr of fieldsBySection.values()) arr.sort((a, b) => a.order - b.order);
+
+  const visByTarget = new Map<string, FormFieldEdge[]>();
+  const sectionEdges = new Map<string, FormFieldEdge[]>();
+  for (const e of form?.edges ?? []) {
+    if (e.scope === "section" && e.sourceSectionId) {
+      const a = sectionEdges.get(e.sourceSectionId) ?? [];
+      a.push(e);
+      sectionEdges.set(e.sourceSectionId, a);
+    } else if (e.sourceFieldId && e.targetFieldId && e.condition) {
+      // A field→field edge with a CONDITION is an in-page visibility rule ("show
+      // target when source matches") — treat scope "field"/"visibility" alike
+      // since jumps don't apply to paged forms. A field→field edge WITHOUT a
+      // condition is not a visibility rule and must NOT hide its target.
+      const a = visByTarget.get(e.targetFieldId) ?? [];
+      a.push(e);
+      visByTarget.set(e.targetFieldId, a);
+    }
+  }
+  return { sections, byId, order, fieldsBySection, visByTarget, sectionEdges };
+}
+
+/**
+ * Headless multi-section form flow: a paginated wizard over `usePublicForm` that
+ * mirrors the server walk (docs/forms-sections.md). Handles current-section
+ * state, in-page field visibility (show/hide), per-section required validation,
+ * section→section branching (incl. submit), Back navigation, and submit. Bring
+ * your own markup (or use the styled `<SectionedFormRenderer>`).
+ *
+ * For forms with no sections, prefer the flat `<FormRenderer>` — this hook has
+ * nothing to page through.
+ */
+export function useSectionedForm(formId?: string) {
+  const { data: rawForm, isLoading } = usePublicForm(formId);
+  const submitMutation = useSubmitPublicForm(formId);
+
+  // Seeded per-mount option shuffle for quiz-mode forms (no-op otherwise).
+  const seedRef = useRef<string>(Math.random().toString(36).slice(2, 12));
+  const form = useMemo(() => shuffleFormOptions(rawForm, seedRef.current), [rawForm]);
+
+  const model = useMemo(() => buildModel(form), [form]);
+  const { sections, order, byId, fieldsBySection, visByTarget, sectionEdges } = model;
+
+  const [answers, setAnswers] = useState<Record<string, string>>({});
+  const [stack, setStack] = useState<string[]>([]); // visited section ids; current = last
+  const [error, setError] = useState("");
+  const [isCompleted, setIsCompleted] = useState(false);
+  // Graded quiz result (null until submit + only for quiz-mode forms). Shaped by
+  // the server's reveal policy — see docs/quizzes-certification-initiative.md.
+  const [quizResult, setQuizResult] = useState<Record<string, unknown> | null>(null);
+
+  // Start at the first section once the form loads.
+  useEffect(() => {
+    if (form && sections.length && stack.length === 0) setStack([sections[0].id]);
+  }, [form, sections, stack.length]);
+
+  const currentId = stack.length ? stack[stack.length - 1] : null;
+  const currentSection = currentId ? byId.get(currentId) ?? null : null;
+
+  const setAnswer = (id: string, value: string) => setAnswers((p) => ({ ...p, [id]: value }));
+
+  const isActive = (field: FormField): boolean => {
+    const incoming = visByTarget.get(field.id);
+    if (!incoming || incoming.length === 0) return true;
+    return incoming.some((e) => evaluateCondition(e.condition, answers[e.sourceFieldId ?? ""]));
+  };
+
+  const visibleFields = currentId ? (fieldsBySection.get(currentId) ?? []).filter(isActive) : [];
+
+  const computeNext = (): { submit: boolean; sectionId: string | null } => {
+    if (!currentSection) return { submit: true, sectionId: null };
+    const outs = (sectionEdges.get(currentSection.id) ?? []).slice().sort((a, b) => a.sortOrder - b.sortOrder);
+    const branchAnswer = currentSection.branchFieldId ? answers[currentSection.branchFieldId] : undefined;
+    for (const e of outs) {
+      if (!e.condition) continue;
+      if (evaluateCondition(e.condition, branchAnswer)) {
+        return e.targetKind === "submit" ? { submit: true, sectionId: null } : { submit: false, sectionId: e.targetSectionId ?? null };
+      }
+    }
+    const def = outs.find((e) => !e.condition);
+    if (def) {
+      return def.targetKind === "submit" ? { submit: true, sectionId: null } : { submit: false, sectionId: def.targetSectionId ?? null };
+    }
+    const idx = order.indexOf(currentSection.id);
+    const nextId = idx >= 0 && idx + 1 < order.length ? order[idx + 1] : null;
+    return { submit: nextId === null, sectionId: nextId };
+  };
+
+  const validateCurrent = (): boolean => {
+    for (const f of visibleFields) {
+      if (f.isRequired && !answers[f.id]) {
+        setError(`"${f.label}" is required`);
+        return false;
+      }
+      if (f.type === "email" && answers[f.id] && !emailRe.test(answers[f.id])) {
+        setError("Please enter a valid email address");
+        return false;
+      }
+    }
+    setError("");
+    return true;
+  };
+
+  const submit = async () => {
+    // Send answers only for active fields in the sections actually visited.
+    const visited = stack.length ? stack : sections[0] ? [sections[0].id] : [];
+    const entries: { fieldId: string; value: string | null }[] = [];
+    for (const sid of visited) {
+      for (const f of fieldsBySection.get(sid) ?? []) {
+        if (isActive(f)) entries.push({ fieldId: f.id, value: answers[f.id] || null });
+      }
+    }
+    try {
+      const res = (await submitMutation.mutateAsync(entries)) as { result?: Record<string, unknown> | null };
+      if (res?.result) setQuizResult(res.result);
+      setIsCompleted(true);
+    } catch {
+      setError("Failed to submit. Please try again.");
+    }
+  };
+
+  const next = async () => {
+    if (!validateCurrent()) return;
+    const { submit: doSubmit, sectionId } = computeNext();
+    if (doSubmit || !sectionId) {
+      await submit();
+      return;
+    }
+    setError("");
+    setStack((s) => [...s, sectionId]);
+  };
+
+  const back = () => {
+    setError("");
+    setStack((s) => (s.length > 1 ? s.slice(0, -1) : s));
+  };
+
+  const nextAction = computeNext();
+
+  return {
+    form,
+    isLoading,
+    /** The section currently on screen. */
+    currentSection,
+    /** Fields of the current section that pass their visibility conditions. */
+    visibleFields,
+    answers,
+    setAnswer,
+    error,
+    /** Validate the page, then branch to the next section or submit. */
+    next,
+    /** Return to the previous visited section. */
+    back,
+    canGoBack: stack.length > 1,
+    /** True when Next will submit the form (terminal section / branch). */
+    isSubmitStep: nextAction.submit,
+    isSubmitting: submitMutation.isPending,
+    isCompleted,
+    /** Graded quiz result (null for non-quiz forms). Present after submit. */
+    quizResult,
+    /** 1-based index of the current page in the visited path. */
+    step: stack.length,
+    totalSections: sections.length,
+    /** Estimated 0..1 progress (branching can skip sections). */
+    progress: sections.length ? Math.min(1, stack.length / sections.length) : 0,
+  };
+}

package/src/ui/headless/index.ts

@@ -0,0 +1,60 @@
+// Tier-1 headless primitives: behavior + a11y, zero styling (compound + asChild,
+// plus behavior hooks for leaf flows like forms).
+export * from "./dialog";
+export * from "./donation";
+export * from "./offer";
+export { MembershipGate, type MembershipGateProps, type MembershipGateState } from "./membership/MembershipGate";
+export { useEmailListForm, type UseEmailListFormOptions, type FormStatus } from "./forms/useEmailListForm";
+export { useContactForm } from "./forms/useContactForm";
+export { useSectionedForm } from "./forms/useSectionedForm";
+export { usePostEngagement, type UsePostEngagementOptions } from "./engagement/usePostEngagement";
+export {
+  useCheckout,
+  CHECKOUT_STAGE_ORDER,
+  type UseCheckoutOptions,
+  type CheckoutStage,
+  type GuestUserData,
+  type CheckoutShippingData,
+  type SelectedShippingRate,
+} from "./checkout/useCheckout";
+export { useLoginFlow, type LoginStep } from "./auth/useLoginFlow";
+export { useSignupForm, type UseSignupFormOptions } from "./auth/useSignupForm";
+
+// Flow primitives (Part A2) — multi-step purchase/booking/subscribe/chat flows,
+// each composed from the data hooks so a creator can rebuild any page.
+export { useEventCheckout, type UseEventCheckoutOptions, type EventCheckoutStep } from "./event/useEventCheckout";
+export { useCourseCheckout, type UseCourseCheckoutOptions, type CourseCheckoutStep } from "./course/useCourseCheckout";
+export {
+  useCoachingBooking,
+  type UseCoachingBookingOptions,
+  type CoachingBookingStep,
+} from "./coaching/useCoachingBooking";
+export {
+  useMembershipCheckout,
+  type UseMembershipCheckoutOptions,
+  type MembershipCheckoutStep,
+  type BillingCycle,
+} from "./membership/useMembershipCheckout";
+export { useInvoicePayment, type UseInvoicePaymentOptions } from "./invoice/useInvoicePayment";
+export { usePaymentLinkPayment, type UsePaymentLinkPaymentOptions } from "./paymentLink/usePaymentLinkPayment";
+export { useBroadcastWatch } from "./broadcast/useBroadcastWatch";
+export { useChatRoom } from "./chat/useChatRoom";
+export { useMessageThread, type UseMessageThreadResult } from "./chat/useMessageThread";
+export { useChatAttachmentUpload, type PendingAttachment } from "./chat/useChatAttachmentUpload";
+export { attachmentKind, formatBytes, type AttachmentKind } from "./chat/attachmentKind";
+export { useCookieConsent, type UseCookieConsentResult } from "./consent/useCookieConsent";
+
+export { usePodcastPlayer, type UsePodcastPlayerOptions, type PodcastPlayerState } from "./podcast/usePodcastPlayer";
+
+// Community (forum) headless primitives.
+export * from "./community";
+// Member posts pillar (member home) headless primitives.
+export * from "./posts";
+// Unified member home nav model.
+export * from "./memberHome";
+// Reviews (social proof) headless primitives.
+export * from "./reviews";
+// Document signing (contracts / e-signature) headless primitives.
+export * from "./document";
+// Work (project management) client-portal headless primitives.
+export * from "./work";

package/src/ui/headless/invoice/useInvoicePayment.ts

@@ -0,0 +1,48 @@
+import { useInvoice, useDownloadInvoicePdf } from "../../../data/queries/useInvoice";
+import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+
+export interface UseInvoicePaymentOptions {
+  /** Return path after payment. Default `/i/invoice/:id/finalise`. */
+  returnPath?: string;
+  /** Start payment as soon as the invoice loads (default true). */
+  autoStart?: boolean;
+}
+
+/**
+ * Headless invoice payment: loads the invoice, starts its payment, and exposes
+ * the PDF download. Composes `useInvoice`, `useDownloadInvoicePdf`,
+ * `usePaymentFlow`. Stripe UI renders from `clientSecret`; finalize on the
+ * return page with `useInvoiceFinalize`.
+ */
+export function useInvoicePayment(invoiceId?: string, opts: UseInvoicePaymentOptions = {}) {
+  const invoice = useInvoice(invoiceId);
+  const downloadPdf = useDownloadInvoicePdf(invoiceId);
+
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const returnUrl = invoiceId ? `${origin}${opts.returnPath ?? `/i/invoice/${invoiceId}/finalise`}` : "";
+
+  const flow = usePaymentFlow({
+    path: `/public/invoices/${invoiceId}/start-payment`,
+    returnUrl,
+    autoStart: opts.autoStart ?? true,
+    enabled: !!invoiceId && !!invoice.data,
+  });
+
+  return {
+    invoice,
+    downloadPdf,
+    returnUrl,
+    clientSecret: flow.clientSecret,
+    paymentId: flow.paymentId,
+    provider: flow.provider,
+    /** Sales-tax quote (built from the invoice's own tax columns — no re-quote). */
+    taxQuote: flow.result?.taxQuote ?? null,
+    isStarting: flow.isStarting,
+    error: flow.error
+      ? ((flow.error as { response?: { data?: { message?: string } } })?.response?.data?.message ??
+        "Payment could not be started.")
+      : null,
+    /** Re-start payment (e.g. retry after failure). */
+    pay: flow.start,
+  };
+}

package/src/ui/headless/memberHome/index.ts

@@ -0,0 +1,7 @@
+// Unified member home (`/i/members`) — headless nav model.
+export {
+  useMemberHomeNav,
+  type MemberHomeNavItem,
+  type MemberHomeNavKey,
+  type UseMemberHomeNavOptions,
+} from "./useMemberHomeNav";

package/src/ui/headless/memberHome/useMemberHomeNav.ts

@@ -0,0 +1,82 @@
+import { useMemo } from "react";
+import { useGetPostCollections } from "../../../data/queries/usePostCollections";
+import { useCommunitySpaces } from "../../../data/queries/useCommunity";
+import { useChatChannels } from "../../../data/queries/useChat";
+
+export type MemberHomeNavKey = "posts" | "collections" | "spaces" | "chat" | "membership";
+
+export interface MemberHomeNavItem {
+  key: MemberHomeNavKey;
+  label: string;
+  /** Absolute in-site href (already run through `buildHref` when supplied). */
+  href: string;
+  /** Conditional tabs (Collections/Spaces/Chat) are hidden until the profile has content for them. */
+  visible: boolean;
+  /** Whether `currentPath` falls inside this tab. */
+  active: boolean;
+  /** True for "My membership" — a deep link out of the member home (account membership tab). */
+  external: boolean;
+}
+
+export interface UseMemberHomeNavOptions {
+  /** Current location pathname, used to compute `active`. */
+  currentPath?: string;
+  /** Member home base path (default `/i/members` — identical in both renderers). */
+  basePath?: string;
+  /** "My membership" target. Client: `/account?tab=membership` (default). Site-starter: `/i/account?tab=membership`. */
+  membershipHref?: string;
+  /** Optional href transform (e.g. locale prefixes). Applied to every item. */
+  buildHref?: (href: string) => string;
+}
+
+const normalize = (p: string) => {
+  const path = (p.split("?")[0] ?? "").replace(/\/+$/, "");
+  return path === "" ? "/" : path;
+};
+
+/**
+ * Headless nav model for the unified member home (`/i/members`). Tab
+ * visibility derives client-side from queries the pages already need (cache
+ * shared via React Query): Posts is always visible; Collections appears when
+ * the profile has any post collections; Spaces when any community spaces are
+ * accessible; Chat when any chat channels are accessible; "My membership" is
+ * always visible and deep-links out to the account membership tab. Hosts own
+ * routing — pair with any layout via `href`/`active`.
+ */
+export function useMemberHomeNav(opts: UseMemberHomeNavOptions = {}) {
+  const basePath = opts.basePath ?? "/i/members";
+  const membershipHref = opts.membershipHref ?? "/account?tab=membership";
+  const buildHref = opts.buildHref ?? ((href: string) => href);
+  const currentPath = normalize(opts.currentPath ?? "");
+
+  const collectionsQ = useGetPostCollections({ page: 1 });
+  const spacesQ = useCommunitySpaces();
+  const channelsQ = useChatChannels();
+
+  const hasCollections = (collectionsQ.data?.data?.length ?? 0) > 0;
+  const hasSpaces = (spacesQ.data?.length ?? 0) > 0;
+  const hasChannels = (channelsQ.data?.length ?? 0) > 0;
+
+  const items: MemberHomeNavItem[] = useMemo(() => {
+    const isUnder = (segment: string) =>
+      currentPath === normalize(`${basePath}/${segment}`) || currentPath.startsWith(normalize(`${basePath}/${segment}`) + "/");
+    const defs: Array<Omit<MemberHomeNavItem, "href" | "active"> & { path: string; active: boolean }> = [
+      { key: "posts", label: "Posts", path: basePath, visible: true, external: false, active: currentPath === normalize(basePath) },
+      { key: "collections", label: "Collections", path: `${basePath}/collections`, visible: hasCollections, external: false, active: isUnder("collections") },
+      { key: "spaces", label: "Spaces", path: `${basePath}/spaces`, visible: hasSpaces, external: false, active: isUnder("spaces") },
+      { key: "chat", label: "Chat", path: `${basePath}/chat`, visible: hasChannels, external: false, active: isUnder("chat") },
+      { key: "membership", label: "My membership", path: membershipHref, visible: true, external: true, active: false },
+    ];
+    return defs.map(({ path, ...d }) => ({ ...d, href: buildHref(path) }));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [basePath, membershipHref, currentPath, hasCollections, hasSpaces, hasChannels]);
+
+  return {
+    items,
+    /** Visible items only — what a shell actually renders. */
+    visibleItems: items.filter((i) => i.visible),
+    activeKey: items.find((i) => i.active)?.key ?? null,
+    /** True once the three visibility queries have settled (avoids tab flash). */
+    isReady: !collectionsQ.isLoading && !spacesQ.isLoading && !channelsQ.isLoading,
+  };
+}

package/src/ui/headless/membership/MembershipGate.tsx

@@ -0,0 +1,39 @@
+import type { ReactNode } from "react";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+
+export interface MembershipGateState {
+  hasAccess: boolean;
+  isAuthenticated: boolean;
+}
+
+export interface MembershipGateProps {
+  /**
+   * Tier ids that unlock the content. Omitted/empty → any active membership
+   * unlocks. (For per-item gates where the server already returns `hasAccess`,
+   * pass it via `access`.)
+   */
+  tiers?: string[];
+  /** Override the access decision (e.g. server-provided `post.hasAccess`). */
+  access?: boolean;
+  children: ReactNode;
+  /** Rendered when locked — static node or a render-fn given the gate state. */
+  fallback?: ReactNode | ((state: MembershipGateState) => ReactNode);
+}
+
+/**
+ * Headless access gate. Renders children when the member has access, otherwise
+ * the fallback. Behavior (who has access) is fixed by the server/membership;
+ * the locked UI is entirely yours.
+ */
+export function MembershipGate({ tiers, access, children, fallback }: MembershipGateProps) {
+  const { user, isAuthenticated } = usePublicAuth();
+  const membership = user?.membership;
+  const activeMembership = !!membership && membership.status === "active";
+  const tierAllows = !tiers?.length || (membership ? tiers.includes(membership.membershipTierId) : false);
+
+  const hasAccess = access ?? (activeMembership && tierAllows);
+
+  if (hasAccess) return <>{children}</>;
+  if (typeof fallback === "function") return <>{fallback({ hasAccess, isAuthenticated })}</>;
+  return <>{fallback ?? null}</>;
+}

package/src/ui/headless/membership/useMembershipCheckout.ts

@@ -0,0 +1,121 @@
+import { useMemo, useState } from "react";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { useGetMembershipTiers } from "../../../data/queries/useMembership";
+import {
+  useCreateSubscription,
+  useCreateFreeSubscription,
+  useConfirmLatestSubscription,
+} from "../../../data/queries/useSubscriptions";
+import { readAttributionRef } from "../../../utils/attribution";
+import { readLanding } from "../../../utils/landing";
+
+export type MembershipCheckoutStep = "select" | "payment";
+export type BillingCycle = "month" | "year";
+
+export interface UseMembershipCheckoutOptions {
+  /** Pre-select a tier (e.g. from a `?membershipTierId=` param). */
+  initialTierId?: string;
+  /** Where Stripe returns the member after a paid subscription. Default `/i/account?tab=membership&confirmSubscription=true`. */
+  returnPath?: string;
+  /** Where free activations land. Default `/i/account?tab=membership`. */
+  freeReturnPath?: string;
+  /** Called when a FREE activation completes in-app — the host navigates however
+   * it wants, instead of Forge doing a `window.location` redirect. */
+  onComplete?: () => void;
+}
+
+const errMessage = (e: unknown) =>
+  (e as { response?: { data?: { message?: string } } })?.response?.data?.message || "Something went wrong.";
+
+const tierIsFree = (tier: { payWhatYouWant: boolean; priceMonthly?: number; priceYearly?: number }, cycle: BillingCycle) =>
+  !tier.payWhatYouWant && !(cycle === "month" ? tier.priceMonthly : tier.priceYearly);
+
+/**
+ * Headless membership subscribe: tier selection → free activation OR paid Stripe
+ * subscription. Composes `useGetMembershipTiers`, `useCreateFreeSubscription`,
+ * `useCreateSubscription`, and (for the return page) `useConfirmLatestSubscription`.
+ * Paid flow exposes `clientSecret` for `ForgePaymentProvider`.
+ */
+export function useMembershipCheckout(opts: UseMembershipCheckoutOptions = {}) {
+  const { user } = usePublicAuth();
+  const { data: tiers, isLoading } = useGetMembershipTiers();
+  const createPaid = useCreateSubscription();
+  const createFree = useCreateFreeSubscription();
+  const confirmLatest = useConfirmLatestSubscription();
+
+  const [step, setStep] = useState<MembershipCheckoutStep>("select");
+  const [selectedTierId, setSelectedTierId] = useState<string | undefined>(opts.initialTierId);
+  const [billingCycle, setBillingCycle] = useState<BillingCycle>("month");
+  const [customAmount, setCustomAmount] = useState<number>(0);
+  const [clientSecret, setClientSecret] = useState<string | undefined>();
+  const [error, setError] = useState<string | null>(null);
+
+  const selectedTier = useMemo(
+    () => tiers?.find((t) => t.id === selectedTierId),
+    [tiers, selectedTierId],
+  );
+
+  const amount = useMemo(() => {
+    if (!selectedTier) return 0;
+    if (selectedTier.payWhatYouWant) return customAmount;
+    return (billingCycle === "month" ? selectedTier.priceMonthly : selectedTier.priceYearly) ?? 0;
+  }, [selectedTier, billingCycle, customAmount]);
+
+  const subscribe = async () => {
+    setError(null);
+    if (!selectedTier) {
+      setError("Select a membership tier.");
+      return;
+    }
+    if (!user) {
+      setError("Please sign in to subscribe.");
+      return;
+    }
+    const origin = typeof window !== "undefined" ? window.location.origin : "";
+    const attributionRefId = readAttributionRef() ?? undefined;
+    const landing = readLanding() ?? {};
+    try {
+      if (tierIsFree(selectedTier, billingCycle)) {
+        await createFree.mutateAsync({ membershipTierId: selectedTier.id, attributionRefId, ...landing });
+        if (opts.onComplete) opts.onComplete();
+        else if (typeof window !== "undefined") {
+          window.location.href = `${origin}${opts.freeReturnPath ?? "/i/account?tab=membership"}`;
+        }
+        return;
+      }
+      const data = await createPaid.mutateAsync({
+        amount,
+        billingCycle,
+        membershipTierId: selectedTier.id,
+        returnUrl: `${origin}${opts.returnPath ?? "/i/account?tab=membership&confirmSubscription=true"}`,
+        attributionRefId,
+        ...landing,
+      });
+      setClientSecret(data.clientSecret);
+      setStep("payment");
+    } catch (e) {
+      setError(errMessage(e));
+    }
+  };
+
+  return {
+    tiers,
+    isLoading,
+    step,
+    setStep,
+    selectedTierId,
+    setSelectedTierId,
+    selectedTier,
+    billingCycle,
+    setBillingCycle,
+    customAmount,
+    setCustomAmount,
+    amount,
+    subscribe,
+    clientSecret,
+    isProcessing: createPaid.isPending || createFree.isPending,
+    error,
+    /** Call on the return page to reconcile the latest subscription. */
+    confirmLatest,
+  };
+}