@tribe-nest/forge 3.59.0 → 3.60.0

package/src/ui/headless/communities/useCommunityJoin.ts

@@ -0,0 +1,444 @@
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import { useInvalidateCommunities, type PublicTier } from "../../../data/queries/useCommunities";
+import { useMembershipCheckout } from "../membership/useMembershipCheckout";
+import { useSignupForm } from "../auth/useSignupForm";
+import { useLoginFlow } from "../auth/useLoginFlow";
+import { offeredCycles } from "../../format/membershipPwyw";
+import { useCommunity } from "./useCommunity";
+import { useCommunityInvite } from "./useCommunityInvite";
+import { communityHomePath } from "./paths";
+
+/**
+ * Where the join sheet is. Steps that do not apply are skipped, never shown:
+ *
+ *   email       who the fan is: sign up (name, email, password) or sign in.
+ *               Skipped when signed in.
+ *   code        the 6-digit code emailed to them. Skipped when signed in.
+ *   tier        which tier, and on a tier with a choice, the billing cycle or
+ *               the pay-what-you-want amount. Skipped when there is one tier
+ *               and nothing to choose.
+ *   questions   the tier's questions. Only when it has some.
+ *   payment     the card. Only on a paid tier (or a paid application, which
+ *               saves the card and charges on approval).
+ *   submitting  a join request is in flight.
+ *   joined      in. The sheet lands the fan on the community home.
+ *   pending     an application was lodged: the fan lands inside, pending.
+ */
+export type CommunityJoinStep = "email" | "code" | "tier" | "questions" | "payment" | "submitting" | "joined" | "pending";
+
+/** The facts the step is derived from. Exported so the order can be tested without a provider tree. */
+export interface CommunityJoinStepInput {
+  isAuthenticated: boolean;
+  awaitingCode: boolean;
+  /** A per-email invite for another address, while signed in: the sheet offers "Sign in as". */
+  emailMismatch: boolean;
+  joined: boolean;
+  pending: boolean;
+  /** Already a member here and not changing tier through this sheet. */
+  alreadyMember: boolean;
+  isProcessing: boolean;
+  hasPaymentStep: boolean;
+  hasSelectedTier: boolean;
+  /** The tier step still needs the fan (several tiers, or a choice on the one). */
+  tierStepOpen: boolean;
+  /** The tier's questions are waiting for answers. */
+  questionsOpen: boolean;
+}
+
+/** The join step, pure. The ORDER here is the flow: identity, then tier, questions, card. */
+export function communityJoinStep(input: CommunityJoinStepInput): CommunityJoinStep {
+  if (input.joined || (input.alreadyMember && input.isAuthenticated)) return "joined";
+  if (input.pending) return "pending";
+  if (!input.isAuthenticated) return input.awaitingCode ? "code" : "email";
+  if (input.emailMismatch) return "email";
+  if (input.isProcessing) return "submitting";
+  if (input.hasPaymentStep) return "payment";
+  if (!input.hasSelectedTier || input.tierStepOpen) return "tier";
+  if (input.questionsOpen) return "questions";
+  return "submitting";
+}
+
+/** Does this tier ask the fan to choose anything (a cycle, or an amount)? */
+export function tierHasChoice(tier: Pick<PublicTier, "payWhatYouWant" | "priceMonthly" | "priceYearly" | "payWhatYouWantMinimum" | "payWhatYouWantYearlyMinimum" | "payWhatYouWantMaximum" | "payWhatYouWantYearlyMaximum">): boolean {
+  if (tier.payWhatYouWant) return true;
+  const cycles = offeredCycles(tier);
+  return cycles.month && cycles.year;
+}
+
+export interface UseCommunityJoinOptions {
+  /** Preselect a tier (`?tier=` on the About page). An invite's tier wins over it. */
+  tierId?: string | null;
+  /** A per-email invite token (`?invite=`): its tier is preset and its email locked. */
+  invite?: string | null;
+  /** A shareable invite link token (`?join=`): its tier is preset, no email lock. */
+  join?: string | null;
+  /**
+   * Where Stripe returns after a paid join. Default: the community home with
+   * `confirmSubscription=1`, which reconciles the subscription there.
+   */
+  returnPath?: string;
+  /**
+   * Called when the join is complete or an application is lodged. Omitted, the
+   * fan is sent to the community home (with `welcome=1` after a join).
+   */
+  onJoined?: (result: { pending: boolean; requiresConfirmation: boolean; path: string }) => void;
+  /** The host's router, used for the default landing instead of a full-page visit. */
+  navigate?: (href: string) => void;
+  /** Require the terms checkbox on sign-up (default true). */
+  requireAcceptance?: boolean;
+}
+
+/**
+ * Join a community from its About page, in place: Skool-simple.
+ *
+ *     email -> code -> tier -> questions -> payment -> inside
+ *
+ * with every step that does not apply skipped. A free tier with nothing to
+ * choose is joined the moment the code is accepted. Every success lands INSIDE
+ * the community (`/i/communities/<slug>/home`), never on the account page.
+ *
+ * Composes, rather than re-implements: the email-code sign-up (`useSignupForm`)
+ * and sign-in (`useLoginFlow`), the membership checkout (`useMembershipCheckout`:
+ * pricing, pay-what-you-want, questions, trials, free and paid subscribe,
+ * applications, Stripe and Paystack), the community read (`useCommunity`) and
+ * the invite read (`useCommunityInvite`).
+ *
+ * Invites:
+ * - a per-email invite presets its tier and prefills and LOCKS the email. A fan
+ *   signed in as someone else gets `emailMismatch` and `signInAsInvited()`.
+ * - a shareable link presets its tier with no email lock.
+ * - a dead token (expired, revoked, used, used up, not found) is reported in
+ *   `inviteProblem` and NOT forwarded, so the normal Join still works.
+ *
+ * The card step exposes what `ForgePaymentProvider`'s renderer needs:
+ * `clientSecret`, `paymentKind`, `returnUrl`, `amount`, `trial`, and
+ * `onPaymentSucceeded`; on Paystack, `openPaystackCheckout`.
+ */
+export function useCommunityJoin(opts: UseCommunityJoinOptions = {}) {
+  const context = useOptionalCommunityContext();
+  if (!context) throw new MissingCommunityProviderError("useCommunityJoin()");
+  const auth = useContext(PublicAuthContext);
+  const user = auth?.user ?? null;
+  const isAuthenticated = !!user;
+
+  const inviteToken = opts.invite ?? null;
+  const joinToken = inviteToken ? null : (opts.join ?? null);
+  const invite = useCommunityInvite({ invite: inviteToken, join: joinToken });
+  // Only a usable token changes what is listed and what is sent.
+  const forwardInvite = invite.forward.inviteToken ?? null;
+  const forwardJoin = invite.forward.joinToken ?? null;
+  const community = useCommunity(undefined, { invite: forwardInvite, join: forwardJoin });
+  const invalidate = useInvalidateCommunities();
+
+  const slug = community.slug ?? context.slug;
+  const home = (query?: { welcome?: 1; confirmSubscription?: 1 }) => (slug ? communityHomePath(slug, query) : "");
+  const paidReturnPath = opts.returnPath ?? home({ confirmSubscription: 1 });
+
+  // ---- Tiers -------------------------------------------------------------------
+  const tiers = useMemo(() => {
+    const list = [...community.tiers];
+    // The invite's tier is joinable even when the public list hides it.
+    if (invite.tier && !list.some((tier) => tier.id === invite.tier!.id)) list.unshift(invite.tier);
+    return list;
+  }, [community.tiers, invite.tier]);
+  const presetTierId =
+    invite.tier?.id ?? (opts.tierId && tiers.some((tier) => tier.id === opts.tierId) ? opts.tierId : null) ??
+    (tiers.length === 1 ? tiers[0]!.id : null);
+
+  // ---- Landing -------------------------------------------------------------------
+  const [joined, setJoined] = useState(false);
+  const [landedPending, setLandedPending] = useState(false);
+  const land = useCallback(
+    (result: { pending: boolean; requiresConfirmation: boolean }) => {
+      void invalidate();
+      const path = result.pending ? home() : result.requiresConfirmation ? paidReturnPath : home({ welcome: 1 });
+      if (opts.onJoined) return opts.onJoined({ ...result, path });
+      if (opts.navigate) return opts.navigate(path);
+      if (typeof window !== "undefined" && path) window.location.assign(`${window.location.origin}${path}`);
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [slug, paidReturnPath, opts.onJoined, opts.navigate],
+  );
+
+  const checkout = useMembershipCheckout({
+    tiers,
+    initialTierId: presetTierId ?? undefined,
+    inviteToken: forwardInvite,
+    joinToken: forwardJoin,
+    current: community.membership ? { tierId: community.membership.tierId, status: community.membership.status } : null,
+    returnPath: paidReturnPath,
+    freeReturnPath: home({ welcome: 1 }),
+    applicationReturnPath: home(),
+    onComplete: ({ requiresConfirmation }) => {
+      setJoined(true);
+      land({ pending: false, requiresConfirmation });
+    },
+  });
+
+  // The tier list can arrive after the first render (and an invite's tier after
+  // that): select the preset once it exists.
+  useEffect(() => {
+    if (!checkout.selectedTierId && presetTierId && tiers.some((tier) => tier.id === presetTierId)) {
+      checkout.setSelectedTierId(presetTierId);
+      checkout.setStep("select");
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [presetTierId, tiers]);
+
+  // ---- Identity (email + code) -------------------------------------------------------
+  const [mode, setMode] = useState<"signup" | "signin">("signup");
+  const signup = useSignupForm({
+    membershipTierId: checkout.selectedTierId,
+    requireAcceptance: opts.requireAcceptance,
+  });
+  const login = useLoginFlow();
+  const lockedEmail = invite.kind === "email" && (invite.isValid || invite.emailMismatch) ? invite.invitedEmail : null;
+  useEffect(() => {
+    if (!lockedEmail) return;
+    if (signup.email !== lockedEmail) signup.setEmail(lockedEmail);
+    if (login.email !== lockedEmail) login.setEmail(lockedEmail);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [lockedEmail, signup.email, login.email]);
+  const awaitingCode = mode === "signup" ? signup.awaitingCode : login.step === "code";
+
+  // ---- Tier and question confirmation ------------------------------------------------
+  const [tierConfirmed, setTierConfirmed] = useState(false);
+  const [questionsConfirmed, setQuestionsConfirmed] = useState(false);
+  const [attempted, setAttempted] = useState(false);
+  const selectedTier = checkout.selectedTier as PublicTier | undefined;
+  // An invite names its tier, so the list is not offered; a choice ON the tier still is.
+  const offersTierList = tiers.length > 1 && !invite.tier;
+  const tierStepNeeded = offersTierList || (!!selectedTier && tierHasChoice(selectedTier));
+  // A join that was refused (the amount below the floor, a server error) comes
+  // back to the tier step, which owns the message and the retry.
+  const refused = attempted && !checkout.isProcessing && (!!checkout.error || !!checkout.amountRefusal);
+  const tierStepOpen = !selectedTier || (tierStepNeeded && !tierConfirmed) || refused;
+  const questionsOpen = checkout.questionnaire.length > 0 && !questionsConfirmed;
+
+  const isChangingTier = !!community.membership && !!selectedTier && selectedTier.id !== community.membership.tierId && (!!invite.tier || !!opts.tierId);
+  const alreadyMember = community.isMember && !isChangingTier;
+  const pending =
+    landedPending ||
+    checkout.applicationOutcome === "received" ||
+    checkout.applicationOutcome === "approved" ||
+    (community.isPending && !joined);
+
+  const hasPaymentStep = checkout.step === "payment" && (!!checkout.clientSecret || checkout.canOpenPaystack);
+
+  const step = communityJoinStep({
+    isAuthenticated,
+    awaitingCode,
+    emailMismatch: isAuthenticated && invite.emailMismatch,
+    joined,
+    pending,
+    alreadyMember,
+    isProcessing: checkout.isProcessing,
+    hasPaymentStep,
+    hasSelectedTier: !!selectedTier,
+    tierStepOpen,
+    questionsOpen,
+  });
+
+  // An application lodged: land inside, pending (decision 9).
+  useEffect(() => {
+    if (landedPending) return;
+    if (checkout.applicationOutcome === "received" || checkout.applicationOutcome === "approved") {
+      setLandedPending(true);
+      land({ pending: true, requiresConfirmation: false });
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [checkout.applicationOutcome]);
+
+  const submit = useCallback(async () => {
+    setAttempted(true);
+    if (selectedTier) autoSubmitted.current = selectedTier.id;
+    await checkout.subscribe();
+    // A refusal (an amount below the floor, a blank required answer, a server
+    // error) leaves nothing started: reopen the step that owns the message.
+    if (checkout.questionnaire.length > 0) setQuestionsConfirmed(false);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [checkout.subscribe, checkout.questionnaire.length]);
+
+  // Nothing left to ask: join straight away. Once per tier, so a refusal does
+  // not loop; the fan retries from the tier step, which then owns the error.
+  const autoSubmitted = useRef<string | null>(null);
+  const viewerSettled = !community.viewerLoading && !community.isLoading;
+  useEffect(() => {
+    if (step !== "submitting" || checkout.isProcessing || !selectedTier || !viewerSettled) return;
+    if (autoSubmitted.current === selectedTier.id) return;
+    autoSubmitted.current = selectedTier.id;
+    void submit();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [step, checkout.isProcessing, selectedTier?.id, viewerSettled]);
+
+  // The already-member case lands straight inside, once.
+  const landedMember = useRef(false);
+  useEffect(() => {
+    if (step === "joined" && alreadyMember && !joined && !landedMember.current) {
+      landedMember.current = true;
+      if (slug) {
+        const path = home();
+        if (opts.onJoined) opts.onJoined({ pending: false, requiresConfirmation: false, path });
+        else if (opts.navigate) opts.navigate(path);
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [step, alreadyMember, joined, slug]);
+
+  const identityError = mode === "signup" ? signup.error : login.error;
+  const identitySubmitting = mode === "signup" ? signup.isSubmitting : login.isSubmitting;
+
+  /** Advance from the current step. */
+  const next = async () => {
+    switch (step) {
+      case "email":
+        if (mode === "signup") await signup.submit();
+        else await login.submitCredentials();
+        return;
+      case "code":
+        if (mode === "signup") await signup.submitCode();
+        else await login.submitCode();
+        return;
+      case "tier":
+        if (!selectedTier) return;
+        setTierConfirmed(true);
+        // The auto-submit is spent on a retry: pressing the button is the retry.
+        autoSubmitted.current = selectedTier.id;
+        if (checkout.questionnaire.length > 0 && !questionsConfirmed) return;
+        await submit();
+        return;
+      case "questions":
+        if (selectedTier) autoSubmitted.current = selectedTier.id;
+        setQuestionsConfirmed(true);
+        await submit();
+        return;
+      default:
+        return;
+    }
+  };
+
+  /** Go back one step, where there is one to go back to. */
+  const back = () => {
+    switch (step) {
+      case "code":
+        if (mode === "signup") signup.editDetails();
+        else login.back();
+        return;
+      case "questions":
+        if (tierStepNeeded) setTierConfirmed(false);
+        return;
+      case "payment":
+        checkout.setStep("select");
+        if (checkout.questionnaire.length > 0) setQuestionsConfirmed(false);
+        else if (tierStepNeeded) setTierConfirmed(false);
+        autoSubmitted.current = selectedTier?.id ?? null;
+        return;
+      default:
+        return;
+    }
+  };
+
+  return {
+    step,
+    isLoading: community.isLoading || invite.isLoading,
+    community: community.community,
+    slug,
+    tiers,
+    viewer: community.viewer,
+    /** Already a member here: the sheet has nothing to do but go inside. */
+    alreadyMember,
+
+    // ---- email + code ----
+    /** `signup` (new fan) or `signin` (has an account). */
+    mode,
+    setMode,
+    /** The sign-up fields (name, email, password, terms). */
+    signup,
+    /** The sign-in fields (email, password, then code). */
+    login,
+    /** The email is set by a per-email invite and cannot be changed. */
+    emailLocked: !!lockedEmail,
+    lockedEmail,
+    /** The code the fan types on the `code` step, whichever mode. */
+    code: mode === "signup" ? signup.code : login.code,
+    setCode: (value: string) => (mode === "signup" ? signup.setCode(value) : login.setCode(value)),
+    resendCode: () => (mode === "signup" ? signup.resendCode() : login.resend()),
+
+    // ---- invites ----
+    invite,
+    /** Why the URL's invite cannot be used, if it cannot. The normal Join still works. */
+    inviteProblem: invite.problem,
+    /** Signed in as another address than a per-email invite's. */
+    emailMismatch: isAuthenticated && invite.emailMismatch ? { invitedEmail: invite.invitedEmail ?? "", signedInEmail: user?.email ?? "" } : null,
+    /** "Sign in as {email}": signs the current account out and opens sign-in with the invited address locked. */
+    signInAsInvited: async () => {
+      await auth?.logout();
+      setMode("signin");
+    },
+
+    // ---- tier ----
+    selectedTier,
+    selectTier: (tier: PublicTier) => {
+      checkout.selectTier(tier);
+      setTierConfirmed(false);
+      setQuestionsConfirmed(false);
+      autoSubmitted.current = null;
+    },
+    /** True when more than one tier is offered, so the step lists them. False on an invite, which names its tier. */
+    hasTierChoice: offersTierList,
+    billingCycle: checkout.billingCycle,
+    setBillingCycle: checkout.setBillingCycle,
+    cycles: checkout.cycles,
+    isFreeCycle: checkout.isFreeCycle,
+    customAmount: checkout.customAmount,
+    setCustomAmount: checkout.setCustomAmount,
+    minimumAmount: checkout.minimumAmount,
+    maximumAmount: checkout.maximumAmount,
+    amountRefusal: checkout.amountRefusal,
+    amount: checkout.amount,
+    trialDays: checkout.trialDays,
+    trialEndsAt: checkout.trialEndsAt,
+    isApplication: checkout.isApplication,
+    isChange: checkout.isChange,
+
+    // ---- questions ----
+    questionnaire: checkout.questionnaire,
+    questionnaireAnswers: checkout.questionnaireAnswers,
+    setQuestionnaireAnswer: checkout.setQuestionnaireAnswer,
+    questionnaireRefusal: checkout.questionnaireRefusal,
+
+    // ---- payment ----
+    clientSecret: checkout.clientSecret,
+    /** `setup` when the card is saved rather than charged (a trial, or an application). */
+    paymentKind: checkout.paymentKind,
+    setupPurpose: checkout.setupPurpose,
+    /** The renderer's `returnUrl`: the community home, reconciling the subscription there. */
+    returnUrl:
+      checkout.setupPurpose === "application" && checkout.applicationReturnUrl
+        ? checkout.applicationReturnUrl
+        : `${typeof window !== "undefined" ? window.location.origin : ""}${paidReturnPath}`,
+    trial:
+      checkout.setupPurpose === "trial" && checkout.trialEndsAt
+        ? { endsAt: checkout.trialEndsAt, billingCycle: checkout.billingCycle }
+        : null,
+    isPaystack: checkout.isPaystack,
+    canOpenPaystack: checkout.canOpenPaystack,
+    openPaystackCheckout: checkout.openPaystackCheckout,
+    onPaymentSucceeded: checkout.onPaymentSucceeded,
+
+    // ---- outcome ----
+    application: checkout.application,
+    applicationOutcome: checkout.applicationOutcome,
+    /** Whether a join was attempted in this sheet. */
+    attempted,
+    error: step === "email" || step === "code" ? identityError : checkout.error,
+    isSubmitting: identitySubmitting || checkout.isProcessing,
+
+    next,
+    back,
+    /** Submit the join now (the tier and questions as they stand). */
+    submit,
+  };
+}

package/src/ui/headless/communities/useCommunityMembership.ts

@@ -0,0 +1,136 @@
+import { useMemo, useState } from "react";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import {
+  useCancelCommunityMembership,
+  useDowngradeCommunityMembership,
+  useUndoCommunityDowngrade,
+  type PublicTier,
+} from "../../../data/queries/useCommunities";
+import { useOpenBillingPortal } from "../../../data/queries/useSubscriptions";
+import { cycleFloor, defaultCycle } from "../../format/membershipPwyw";
+import { useCommunity } from "./useCommunity";
+
+const errMessage = (e: unknown) =>
+  (e as { response?: { data?: { message?: string } } })?.response?.data?.message || "Something went wrong.";
+
+/** A monthly-equivalent price, so tiers sold on different cycles still order correctly. */
+const monthlyPrice = (tier: PublicTier) => {
+  const cycle = defaultCycle(tier);
+  const floor = cycleFloor(tier, cycle);
+  return cycle === "year" ? floor / 12 : floor;
+};
+
+/**
+ * The tiers a member can move DOWN to: this community's tiers priced below the
+ * current one, excluding anything the upgrade list offers. Pure.
+ */
+export function communityDowngradeTiers(tiers: PublicTier[], currentTierId: string | null | undefined, upgradeTierIds: string[]): PublicTier[] {
+  const current = tiers.find((tier) => tier.id === currentTierId);
+  if (!current) return [];
+  const currentPrice = monthlyPrice(current);
+  return tiers.filter(
+    (tier) =>
+      tier.id !== current.id &&
+      !upgradeTierIds.includes(tier.id) &&
+      tier.joinMode !== "application" &&
+      monthlyPrice(tier) < currentPrice,
+  );
+}
+
+/**
+ * The Membership menu inside a community: current tier, renewal date, a pending
+ * downgrade, and the actions. Cancel keeps the paid period; a downgrade takes
+ * effect at period end and can be withdrawn until then (decision 11).
+ *
+ * Cancel is two-step (`requestCancel()` then `confirmCancel()`), because a
+ * destructive action has to be confirmed and the confirmation's wording depends
+ * on state the hook owns.
+ */
+export function useCommunityMembership() {
+  const context = useOptionalCommunityContext();
+  if (!context) throw new MissingCommunityProviderError("useCommunityMembership()");
+  const community = useCommunity();
+  const ref = community.slug ?? context.slug ?? context.ref;
+  const cancel = useCancelCommunityMembership(ref);
+  const downgrade = useDowngradeCommunityMembership(ref);
+  const undo = useUndoCommunityDowngrade(ref);
+  const billingPortal = useOpenBillingPortal();
+
+  const [cancelRequested, setCancelRequested] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const membership = community.membership;
+  const upgradeIds = community.upgradeTiers.map((tier) => tier.id);
+  const downgradeTiers = useMemo(
+    () => communityDowngradeTiers(community.tiers, membership?.tierId, upgradeIds),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [community.tiers, membership?.tierId, upgradeIds.join(",")],
+  );
+  const pendingDowngradeTier = membership?.pendingDowngradeTierId
+    ? (community.tiers.find((tier) => tier.id === membership.pendingDowngradeTierId) ?? {
+        id: membership.pendingDowngradeTierId,
+        name: "",
+      })
+    : null;
+
+  const run = async (action: () => Promise<unknown>) => {
+    setError(null);
+    try {
+      await action();
+      await community.refetch();
+      return true;
+    } catch (e) {
+      setError(errMessage(e));
+      return false;
+    }
+  };
+
+  return {
+    isLoading: community.isLoading,
+    /** False for a viewer with nothing to manage here. */
+    hasMembership: !!membership,
+    membership,
+    currentTier: community.currentTier,
+    /** When the paid period ends: the renewal date, or the last day when cancelling. */
+    periodEnd: membership?.currentPeriodEnd ?? null,
+    isCancelling: !!membership?.cancelAtPeriodEnd,
+    pendingDowngradeTier,
+    downgradeTiers,
+    isPastDue: community.viewer?.state === "past_due",
+    error,
+    isWorking: cancel.isPending || downgrade.isPending || undo.isPending || billingPortal.isPending,
+
+    cancelRequested,
+    /** Ask to cancel: show the confirmation, which must say the paid period is kept. */
+    requestCancel: () => {
+      setError(null);
+      setCancelRequested(true);
+    },
+    abortCancel: () => setCancelRequested(false),
+    /** Cancel for real. Access runs to the end of the paid period. */
+    confirmCancel: async () => {
+      const ok = await run(() => cancel.mutateAsync());
+      if (ok) setCancelRequested(false);
+      return ok;
+    },
+    /** The same, without the confirmation step, for a host that confirms on its own. */
+    cancel: () => run(() => cancel.mutateAsync()),
+    /** Move down to `tierId` at the end of the paid period. */
+    downgrade: (tierId: string) => run(() => downgrade.mutateAsync({ membershipTierId: tierId })),
+    /** Withdraw a pending downgrade. */
+    undoDowngrade: () => run(() => undo.mutateAsync()),
+    /**
+     * Open the provider's billing page to change the card. The server derives
+     * the customer from the session; the fan comes back to this page.
+     */
+    updateCard: async () => {
+      setError(null);
+      try {
+        const { url } = await billingPortal.mutateAsync();
+        if (typeof window !== "undefined" && url) window.location.assign(url);
+      } catch (e) {
+        setError(errMessage(e));
+      }
+    },
+  };
+}