@tribe-nest/forge 3.59.0 → 3.61.0

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

@@ -0,0 +1,116 @@
+import { useContext, useMemo } from "react";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import {
+  useCommunityInviteState,
+  type CommunityInviteKind,
+  type CommunityInviteState,
+  type CommunityInviteStateName,
+  type PublicTier,
+} from "../../../data/queries/useCommunities";
+
+/** Why an invite cannot be used. The About page says so and falls back to the normal Join. */
+export type CommunityInviteProblem = "expired" | "revoked" | "used" | "used_up" | "not_found";
+
+export interface CommunityInviteSummary {
+  /** `email` for a per-email invite (`?invite=`), `link` for a shareable one (`?join=`). Null with no token. */
+  kind: CommunityInviteKind | null;
+  /** The server's answer, adjusted for who is signed in right now. Null with no token or while loading. */
+  state: CommunityInviteStateName | null;
+  /** The invite can be accepted by this viewer as they are. */
+  isValid: boolean;
+  /** A per-email invite for a different address than the signed-in one. */
+  emailMismatch: boolean;
+  /** Set when the token is dead, and why. */
+  problem: CommunityInviteProblem | null;
+  /** The address a per-email invite was sent to: prefilled and locked in the join sheet. */
+  invitedEmail: string | null;
+  /** The tier the invite opens. Null for a dead token. */
+  tier: PublicTier | null;
+  /**
+   * The tokens to forward with the join. Only a usable token is forwarded: a
+   * dead one would turn the fallback Join into a refusal.
+   */
+  forward: { inviteToken?: string; joinToken?: string };
+}
+
+const DEAD: ReadonlyArray<CommunityInviteStateName> = ["expired", "revoked", "used", "used_up", "not_found"];
+
+/**
+ * What an invite is worth to this viewer. Pure, so the same rules drive the
+ * hosted sheet and a custom one.
+ *
+ * The server decides validity; this only adds what the server cannot know at
+ * read time: a fan who signed in on this page with a different address than
+ * the invite's is a mismatch now, even if the page loaded anonymous. A shareable
+ * link has no email lock, so it never mismatches.
+ */
+export function describeCommunityInvite(input: {
+  tokens: { invite?: string | null; join?: string | null };
+  answer: CommunityInviteState | null | undefined;
+  signedInEmail?: string | null;
+}): CommunityInviteSummary {
+  const { tokens, answer } = input;
+  const kind: CommunityInviteKind | null = tokens.invite ? "email" : tokens.join ? "link" : null;
+  if (!kind || !answer) {
+    return { kind, state: null, isValid: false, emailMismatch: false, problem: null, invitedEmail: null, tier: null, forward: {} };
+  }
+  let state = answer.state;
+  const invitedEmail = answer.invitedEmail;
+  if (
+    state === "valid" &&
+    answer.kind === "email" &&
+    invitedEmail &&
+    input.signedInEmail &&
+    input.signedInEmail.trim().toLowerCase() !== invitedEmail.trim().toLowerCase()
+  ) {
+    state = "email_mismatch";
+  }
+  const problem = DEAD.includes(state) ? (state as CommunityInviteProblem) : null;
+  // A mismatched invite is still forwarded: signing in as the invited address
+  // is the way through, and that sign-in happens in the same sheet.
+  const usable = state === "valid" || state === "email_mismatch";
+  return {
+    kind: answer.kind ?? kind,
+    state,
+    isValid: state === "valid",
+    emailMismatch: state === "email_mismatch",
+    problem,
+    invitedEmail: answer.kind === "email" ? invitedEmail : null,
+    tier: usable ? answer.tier : null,
+    forward: usable
+      ? kind === "email"
+        ? { inviteToken: tokens.invite! }
+        : { joinToken: tokens.join! }
+      : {},
+  };
+}
+
+/**
+ * The invite state for the surrounding community (`valid`, `expired`,
+ * `revoked`, `used`, `used_up`, `email_mismatch`, `not_found`), the invited
+ * email and the tier it opens. Pass `slug` to read a community other than the
+ * provider's.
+ */
+export function useCommunityInvite(opts: { invite?: string | null; join?: string | null; slug?: string } = {}) {
+  const context = useOptionalCommunityContext();
+  const ref = opts.slug ?? context?.ref;
+  if (!ref) throw new MissingCommunityProviderError("useCommunityInvite()");
+  const tokens = { invite: opts.invite ?? null, join: opts.invite ? null : (opts.join ?? null) };
+  const signedInEmail = useContext(PublicAuthContext)?.user?.email ?? null;
+  const query = useCommunityInviteState(ref, tokens);
+  const summary = useMemo(
+    () => describeCommunityInvite({ tokens, answer: query.data ?? (query.error ? NOT_FOUND(tokens) : undefined), signedInEmail }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [tokens.invite, tokens.join, query.data, query.error, signedInEmail],
+  );
+  return { ...summary, isLoading: !!(tokens.invite || tokens.join) && query.isLoading };
+}
+
+/** A token the server could not resolve at all (a 404 or a failed read) reads as not found, never as valid. */
+const NOT_FOUND = (tokens: { invite?: string | null; join?: string | null }): CommunityInviteState => ({
+  kind: tokens.invite ? "email" : "link",
+  state: "not_found",
+  invitedEmail: null,
+  tier: null,
+});

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

@@ -0,0 +1,494 @@
+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 { useEmailCodeSignIn } from "../auth/useEmailCodeSignIn";
+import { offeredCycles } from "../../format/membershipPwyw";
+import { useCommunity } from "./useCommunity";
+import { useCommunityInvite } from "./useCommunityInvite";
+import { communityHomePath } from "./paths";
+import { requestAppInstall } from "../siteApp/appPrompts";
+
+/**
+ * Where the join sheet is. Steps that do not apply are skipped, never shown:
+ *
+ *   email       who the fan is: their email address, nothing else. Skipped
+ *               when signed in. (`switchToPassword()` swaps in the email and
+ *               password sign-in for someone who prefers it.)
+ *   code        the 6-digit code emailed to them. Skipped when signed in.
+ *               Right for an address with an account here: signed in.
+ *   profile     right, but nobody has that address here yet: first name, last
+ *               name and the terms. Only for someone new.
+ *   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" | "profile" | "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;
+  /** The code was right and the address is new here: the name step. */
+  needsProfile?: 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.needsProfile ? "profile" : 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 -> (profile) -> tier -> questions -> payment -> inside
+ *
+ * with every step that does not apply skipped. Identity is email first: the
+ * code decides whether the fan already has an account (signed in) or is new
+ * (asked their name), so nobody picks between "Create account" and "Sign in". 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-first sign-in
+ * (`useEmailCodeSignIn`), the password sign-in (`useLoginFlow`) and the
+ * password sign-up (`useSignupForm`, kept for a custom sheet that sets
+ * `mode` to `signup`), 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();
+      // In, with nothing left to pay: the moment the site app offers itself.
+      if (!result.pending && !result.requiresConfirmation) requestAppInstall("joined_community");
+      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) -------------------------------------------------------
+  /**
+   * `email` (the default): email first, the code decides. `signin`: the email
+   * and password sign-in, for someone who prefers their password. `signup`: the
+   * password sign-up, which the styled sheet no longer offers.
+   */
+  const [mode, setMode] = useState<"email" | "signup" | "signin">("email");
+  const emailFlow = useEmailCodeSignIn({ requireAcceptance: opts.requireAcceptance });
+  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);
+    if (emailFlow.email !== lockedEmail) emailFlow.setEmail(lockedEmail);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [lockedEmail, signup.email, login.email, emailFlow.email]);
+  const awaitingCode =
+    mode === "email" ? emailFlow.step === "code" : mode === "signup" ? signup.awaitingCode : login.step === "code";
+  const needsProfile = mode === "email" && emailFlow.step === "profile";
+
+  // ---- 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,
+    needsProfile,
+    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 === "email" ? emailFlow.error : mode === "signup" ? signup.error : login.error;
+  const identitySubmitting =
+    mode === "email" ? emailFlow.isSubmitting : mode === "signup" ? signup.isSubmitting : login.isSubmitting;
+
+  /** Advance from the current step. */
+  const next = async () => {
+    switch (step) {
+      case "email":
+        if (mode === "email") await emailFlow.submitEmail();
+        else if (mode === "signup") await signup.submit();
+        else await login.submitCredentials();
+        return;
+      case "code":
+        if (mode === "email") await emailFlow.submitCode();
+        else if (mode === "signup") await signup.submitCode();
+        else await login.submitCode();
+        return;
+      case "profile":
+        await emailFlow.submitProfile();
+        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":
+      case "profile":
+        if (mode === "email") emailFlow.changeEmail();
+        else 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 ----
+    /** `email` (email first, the default), `signin` (email and password) or `signup` (password sign-up). */
+    mode,
+    setMode,
+    /** The email-first fields and steps (email, code, then a name for someone new). */
+    emailFlow,
+    /** "Use your password instead": the email and password sign-in, carrying the typed address over. */
+    switchToPassword: () => {
+      if (!lockedEmail && emailFlow.email && !login.email) login.setEmail(emailFlow.email);
+      setMode("signin");
+    },
+    /** Back from the password sign-in to email first. */
+    switchToEmailCode: () => {
+      if (!lockedEmail && login.email && !emailFlow.email) emailFlow.setEmail(login.email);
+      login.back();
+      setMode("email");
+    },
+    /** 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 === "email" ? emailFlow.code : mode === "signup" ? signup.code : login.code,
+    setCode: (value: string) =>
+      mode === "email" ? emailFlow.setCode(value) : mode === "signup" ? signup.setCode(value) : login.setCode(value),
+    resendCode: () =>
+      mode === "email" ? emailFlow.resendCode() : mode === "signup" ? signup.resendCode() : login.resend(),
+    /** The address the code went to, whichever mode. */
+    codeEmail: mode === "email" ? emailFlow.email : mode === "signup" ? signup.email : login.email,
+
+    // ---- 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 starts email first with the invited address locked. */
+    signInAsInvited: async () => {
+      await auth?.logout();
+      emailFlow.changeEmail();
+      setMode("email");
+    },
+
+    // ---- 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" || step === "profile" ? identityError : checkout.error,
+    isSubmitting: identitySubmitting || checkout.isProcessing,
+
+    next,
+    back,
+    /** Submit the join now (the tier and questions as they stand). */
+    submit,
+  };
+}