@tribe-nest/forge 3.60.0 → 3.63.0

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

@@ -0,0 +1,156 @@
+import { useMemo, useState } from "react";
+import { communityRequestStatus } from "../../../data/queries/useCommunityClassroom";
+import {
+  useCommunityCalendarItems,
+  useCommunityCallRsvp,
+  type CommunityCalendarCall,
+  type CommunityCalendarItem,
+  type CommunityRsvpResponse,
+} from "../../../data/queries/useCommunityCalendar";
+
+// ── Pure helpers (unit-tested; no React) ─────────────────────────────────────
+
+/** One day of the agenda, in the viewer's own time zone. */
+export interface CommunityCalendarDay {
+  /** `YYYY-MM-DD`, local. */
+  key: string;
+  /** Local midnight of the day. */
+  date: Date;
+  items: CommunityCalendarItem[];
+}
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+/** The local day an instant falls on, as `YYYY-MM-DD`. */
+export function calendarDayKey(value: Date | string): string {
+  const date = typeof value === "string" ? new Date(value) : value;
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+/** Local midnight on the first of the month `offset` months from `now`. */
+export function calendarMonthStart(now: Date, offset = 0): Date {
+  return new Date(now.getFullYear(), now.getMonth() + offset, 1);
+}
+
+/** The window one month reads: its first local midnight up to the next month's. */
+export function calendarMonthWindow(monthStart: Date): { from: Date; to: Date } {
+  return {
+    from: new Date(monthStart.getFullYear(), monthStart.getMonth(), 1),
+    to: new Date(monthStart.getFullYear(), monthStart.getMonth() + 1, 1),
+  };
+}
+
+/** When an item is over: its end, or its start when it has no end. */
+export function calendarItemIsOver(item: Pick<CommunityCalendarItem, "startsAt" | "endsAt">, now: Date): boolean {
+  return new Date(item.endsAt ?? item.startsAt).getTime() < now.getTime();
+}
+
+/**
+ * The agenda, grouped by the local day each item starts on and split in two:
+ * `upcoming` (anything not yet over, soonest first) and `past` (most recent
+ * day first), so what a member can still act on is always at the top. Items
+ * keep their time order inside a day.
+ */
+export function groupCalendarItems(
+  items: CommunityCalendarItem[] | undefined,
+  now: Date,
+): { upcoming: CommunityCalendarDay[]; past: CommunityCalendarDay[] } {
+  const sorted = [...(Array.isArray(items) ? items : [])].sort((a, b) => a.startsAt.localeCompare(b.startsAt));
+  const group = (list: CommunityCalendarItem[]) => {
+    const days = new Map<string, CommunityCalendarDay>();
+    for (const item of list) {
+      const key = calendarDayKey(item.startsAt);
+      let day = days.get(key);
+      if (!day) {
+        const start = new Date(item.startsAt);
+        day = { key, date: new Date(start.getFullYear(), start.getMonth(), start.getDate()), items: [] };
+        days.set(key, day);
+      }
+      day.items.push(item);
+    }
+    return [...days.values()];
+  };
+  const upcoming = group(sorted.filter((item) => !calendarItemIsOver(item, now)));
+  const past = group(sorted.filter((item) => calendarItemIsOver(item, now))).reverse();
+  return { upcoming, past };
+}
+
+/** What a failed going or not going means for the member. */
+export type CommunityRsvpErrorCode = "closed" | "not_found" | "failed";
+
+export function rsvpErrorCode(error: unknown): CommunityRsvpErrorCode {
+  const status = communityRequestStatus(error);
+  if (status === 409) return "closed";
+  if (status === 404) return "not_found";
+  return "failed";
+}
+
+/** Pressing the answer a member already gave clears it; any other answer replaces it. */
+export function nextRsvp(
+  current: CommunityRsvpResponse | null,
+  pressed: CommunityRsvpResponse,
+): CommunityRsvpResponse | null {
+  return current === pressed ? null : pressed;
+}
+
+/** Join is offered only while the server says the room is open and there is a room to join. */
+export function callJoinable(call: Pick<CommunityCalendarCall, "isOpen" | "callPublicId">): boolean {
+  return call.isOpen && !!call.callPublicId;
+}
+
+// ── Hook ─────────────────────────────────────────────────────────────────────
+
+export interface UseCommunityCalendarOptions {
+  /** The clock, for tests. Defaults to the time of the first render. */
+  now?: Date;
+}
+
+/**
+ * Headless community calendar: one month at a time (this month first, arrows
+ * either way), grouped by day with what is still ahead on top, and going or
+ * not going on a call. Answering the answer already given clears it. A refused
+ * answer (the call is over or was cancelled, 409) is kept per call for the
+ * row to show.
+ */
+export function useCommunityCalendar(opts: UseCommunityCalendarOptions = {}) {
+  const [initialNow] = useState(() => opts.now ?? new Date());
+  const now = opts.now ?? initialNow;
+  const [offset, setOffset] = useState(0);
+  const monthStart = useMemo(() => calendarMonthStart(now, offset), [now, offset]);
+  const range = useMemo(() => calendarMonthWindow(monthStart), [monthStart]);
+  const query = useCommunityCalendarItems(range);
+  const groups = useMemo(() => groupCalendarItems(query.data, now), [query.data, now]);
+  const rsvpMutation = useCommunityCallRsvp();
+  const [rsvpError, setRsvpError] = useState<{ callId: string; code: CommunityRsvpErrorCode } | null>(null);
+  const status = communityRequestStatus(query.error);
+
+  const answer = (call: CommunityCalendarCall, pressed: CommunityRsvpResponse) => {
+    setRsvpError(null);
+    rsvpMutation.mutate(
+      { callId: call.id, response: nextRsvp(call.rsvp.mine, pressed) },
+      { onError: (error) => setRsvpError({ callId: call.id, code: rsvpErrorCode(error) }) },
+    );
+  };
+
+  return {
+    monthStart,
+    isCurrentMonth: offset === 0,
+    goToPreviousMonth: () => setOffset((o) => o - 1),
+    goToNextMonth: () => setOffset((o) => o + 1),
+    goToToday: () => setOffset(0),
+    items: Array.isArray(query.data) ? query.data : [],
+    upcoming: groups.upcoming,
+    past: groups.past,
+    now,
+    isLoading: query.isLoading,
+    /** Signed out, or not a member of this community. */
+    forbidden: status === 401 || status === 403,
+    isError: query.isError && status !== 401 && status !== 403,
+    /** Answer going or not going; pressing the current answer clears it. */
+    answer,
+    /** The call whose answer is being saved. */
+    pendingCallId: rsvpMutation.isPending ? (rsvpMutation.variables?.callId ?? null) : null,
+    /** Why a call's last answer was refused. */
+    rsvpErrorFor: (callId: string) => (rsvpError?.callId === callId ? rsvpError.code : null),
+  };
+}

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

@@ -0,0 +1,84 @@
+import { useCommunityUpgradeOpener, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
+import {
+  communityRequestStatus,
+  useCommunityClassroomCourses,
+  type CommunityClassroomCourse,
+  type CommunityClassroomProgress,
+} from "../../../data/queries/useCommunityClassroom";
+import { internalPath } from "../../../runtime/pages";
+import { communityAboutPath } from "./paths";
+import { wikiUnlockParts } from "./useCommunityWiki";
+
+// ── Pure helpers (unit-tested; no React) ─────────────────────────────────────
+
+/** Where a member stands with one course card. */
+export type ClassroomCourseState = "locked" | "not_started" | "in_progress" | "completed";
+
+/** How far through a course the member is, 0 to 100. */
+export function classroomProgressPercent(progress: CommunityClassroomProgress | null | undefined): number {
+  if (!progress) return 0;
+  if (progress.completedAt) return 100;
+  const total = Number(progress.total) || 0;
+  if (total <= 0) return 0;
+  return Math.max(0, Math.min(100, Math.round(((Number(progress.completed) || 0) / total) * 100)));
+}
+
+export function classroomCourseState(course: Pick<CommunityClassroomCourse, "open" | "progress">): ClassroomCourseState {
+  if (!course.open) return "locked";
+  const progress = course.progress;
+  if (!progress) return "not_started";
+  if (progress.completedAt || (progress.total > 0 && progress.completed >= progress.total)) return "completed";
+  return progress.completed > 0 ? "in_progress" : "not_started";
+}
+
+/**
+ * What opens a locked course: the level the member has not reached (null when
+ * the level is not what is missing) and the names of the tiers that include
+ * it (empty when none are named). The same reading as a locked wiki page.
+ */
+export function classroomUnlockParts(course: Pick<CommunityClassroomCourse, "unlockLevel" | "unlockTiers">) {
+  return wikiUnlockParts(course);
+}
+
+/**
+ * Where an open card leads: the course player, addressed by the member's
+ * access id. Null without one. The course's own page is the sales page, a dead
+ * end for someone who already holds the course, so it is never the fallback.
+ */
+export function classroomCourseHref(course: Pick<CommunityClassroomCourse, "open" | "accessId">): string | null {
+  return course.open && course.accessId ? internalPath("course-access/$accessId", { accessId: course.accessId }) : null;
+}
+
+// ── Hook ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Headless classroom for the surrounding community: the course cards, open
+ * ones first as the server orders them, whether the viewer may see the tab at
+ * all (`forbidden` for a non-member), and how to unlock a locked card. `unlock`
+ * opens the community's upgrade sheet on the first tier that includes the
+ * course when a community home provides one; otherwise `unlockHref` is the
+ * About page with that tier chosen. A card only a level holds back has nothing
+ * to buy, so it offers no upgrade.
+ */
+export function useCommunityClassroom(opts: { enabled?: boolean } = {}) {
+  const community = useOptionalCommunityContext();
+  const opener = useCommunityUpgradeOpener();
+  const query = useCommunityClassroomCourses(opts);
+  const status = communityRequestStatus(query.error);
+  const courses = Array.isArray(query.data) ? query.data : [];
+
+  return {
+    courses,
+    isLoading: query.isLoading,
+    /** Signed out, or not a member of this community. */
+    forbidden: status === 401 || status === 403,
+    notFound: status === 404,
+    isError: query.isError && status !== 401 && status !== 403 && status !== 404,
+    refetch: query.refetch,
+    /** A locked card offers an upgrade only when a tier includes it. */
+    canUpgrade: (course: CommunityClassroomCourse) => !course.open && course.unlockTiers.length > 0,
+    unlock: opener ? (course: CommunityClassroomCourse) => opener.openUpgrade(course.unlockTiers[0]?.id ?? null) : null,
+    unlockHref: (course: CommunityClassroomCourse) =>
+      community?.slug ? communityAboutPath(community.slug, { tier: course.unlockTiers[0]?.id }) : null,
+  };
+}

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

@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
 import { useConfirmLatestSubscription } from "../../../data/queries/useSubscriptions";
+import { requestAppInstall } from "../siteApp/appPrompts";
 import { useInvalidateCommunities } from "../../../data/queries/useCommunities";
 import { useCommunity } from "./useCommunity";
 import { communityAboutPath } from "./paths";
@@ -46,6 +47,8 @@ export function useCommunityHome(opts: UseCommunityHomeOptions = {}) {
     setConfirming(true);
     confirmLatest
       .mutateAsync({ communityId })
+      // Back from paying to join: the same moment as a free join to offer the app.
+      .then(() => requestAppInstall("joined_community"))
       .catch(() => undefined)
       .finally(() => {
         setConfirming(false);

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

@@ -5,17 +5,23 @@ import { useInvalidateCommunities, type PublicTier } from "../../../data/queries
 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: sign up (name, email, password) or sign in.
- *               Skipped when signed in.
+ *   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.
@@ -26,12 +32,14 @@ import { communityHomePath } from "./paths";
  *   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";
+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;
@@ -51,7 +59,7 @@ export interface CommunityJoinStepInput {
 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.isAuthenticated) return input.needsProfile ? "profile" : input.awaitingCode ? "code" : "email";
   if (input.emailMismatch) return "email";
   if (input.isProcessing) return "submitting";
   if (input.hasPaymentStep) return "payment";
@@ -93,14 +101,18 @@ export interface UseCommunityJoinOptions {
 /**
  * Join a community from its About page, in place: Skool-simple.
  *
- *     email -> code -> tier -> questions -> payment -> inside
+ *     email -> code -> (profile) -> tier -> questions -> payment -> inside
  *
- * with every step that does not apply skipped. A free tier with nothing to
+ * 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-code sign-up (`useSignupForm`)
- * and sign-in (`useLoginFlow`), the membership checkout (`useMembershipCheckout`:
+ * 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`).
@@ -153,6 +165,8 @@ export function useCommunityJoin(opts: UseCommunityJoinOptions = {}) {
   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);
@@ -188,7 +202,13 @@ export function useCommunityJoin(opts: UseCommunityJoinOptions = {}) {
   }, [presetTierId, tiers]);
 
   // ---- Identity (email + code) -------------------------------------------------------
-  const [mode, setMode] = useState<"signup" | "signin">("signup");
+  /**
+   * `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,
@@ -199,9 +219,12 @@ export function useCommunityJoin(opts: UseCommunityJoinOptions = {}) {
     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]);
-  const awaitingCode = mode === "signup" ? signup.awaitingCode : login.step === "code";
+  }, [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);
@@ -230,6 +253,7 @@ export function useCommunityJoin(opts: UseCommunityJoinOptions = {}) {
   const step = communityJoinStep({
     isAuthenticated,
     awaitingCode,
+    needsProfile,
     emailMismatch: isAuthenticated && invite.emailMismatch,
     joined,
     pending,
@@ -287,20 +311,26 @@ export function useCommunityJoin(opts: UseCommunityJoinOptions = {}) {
     // 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;
+  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 === "signup") await signup.submit();
+        if (mode === "email") await emailFlow.submitEmail();
+        else if (mode === "signup") await signup.submit();
         else await login.submitCredentials();
         return;
       case "code":
-        if (mode === "signup") await signup.submitCode();
+        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);
@@ -323,7 +353,9 @@ export function useCommunityJoin(opts: UseCommunityJoinOptions = {}) {
   const back = () => {
     switch (step) {
       case "code":
-        if (mode === "signup") signup.editDetails();
+      case "profile":
+        if (mode === "email") emailFlow.changeEmail();
+        else if (mode === "signup") signup.editDetails();
         else login.back();
         return;
       case "questions":
@@ -351,9 +383,22 @@ export function useCommunityJoin(opts: UseCommunityJoinOptions = {}) {
     alreadyMember,
 
     // ---- email + code ----
-    /** `signup` (new fan) or `signin` (has an account). */
+    /** `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). */
@@ -362,9 +407,13 @@ export function useCommunityJoin(opts: UseCommunityJoinOptions = {}) {
     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()),
+    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,
@@ -372,10 +421,11 @@ export function useCommunityJoin(opts: UseCommunityJoinOptions = {}) {
     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. */
+    /** "Sign in as {email}": signs the current account out and starts email first with the invited address locked. */
     signInAsInvited: async () => {
       await auth?.logout();
-      setMode("signin");
+      emailFlow.changeEmail();
+      setMode("email");
     },
 
     // ---- tier ----
@@ -433,7 +483,7 @@ export function useCommunityJoin(opts: UseCommunityJoinOptions = {}) {
     applicationOutcome: checkout.applicationOutcome,
     /** Whether a join was attempted in this sheet. */
     attempted,
-    error: step === "email" || step === "code" ? identityError : checkout.error,
+    error: step === "email" || step === "code" || step === "profile" ? identityError : checkout.error,
     isSubmitting: identitySubmitting || checkout.isProcessing,
 
     next,

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

@@ -3,11 +3,12 @@ import { MissingCommunityProviderError, useOptionalCommunityContext } from "../.
 import {
   useCancelCommunityMembership,
   useDowngradeCommunityMembership,
+  useMyCommunityMemberships,
   useUndoCommunityDowngrade,
   type PublicTier,
 } from "../../../data/queries/useCommunities";
 import { useOpenBillingPortal } from "../../../data/queries/useSubscriptions";
-import { cycleFloor, defaultCycle } from "../../format/membershipPwyw";
+import { cycleFloor, cycleIsFree, defaultCycle, type BillingCycle } from "../../format/membershipPwyw";
 import { useCommunity } from "./useCommunity";
 
 const errMessage = (e: unknown) =>
@@ -37,6 +38,39 @@ export function communityDowngradeTiers(tiers: PublicTier[], currentTierId: stri
   );
 }
 
+/** What the member pays, as far as the client can tell. */
+export interface CommunityMembershipBilling {
+  /** True when the membership is paid for (a subscription with a price). */
+  isPaid: boolean;
+  /** Per period, in `currency`. Null on a free membership, or while unknown. */
+  amount: number | null;
+  currency: string | null;
+  cycle: BillingCycle | null;
+}
+
+/**
+ * Is this membership paid for, and what does it cost? Pure.
+ *
+ * The answer comes from the member's own row in `/public/memberships/mine`
+ * (`row`), which carries the subscription's real amount and cycle: a
+ * pay-what-you-want member pays what they chose, and a member on a tier sold
+ * both ways pays the cycle they picked. Until that row arrives, the tier's own
+ * price stands in, so a free tier never flashes "Update payment method".
+ */
+export function communityMembershipBilling(
+  row: { amount: number | null; currency: string | null; billingCycle: string | null } | null | undefined,
+  tier: PublicTier | null | undefined,
+): CommunityMembershipBilling {
+  if (row) {
+    const amount = typeof row.amount === "number" && row.amount > 0 ? row.amount : null;
+    const cycle = row.billingCycle === "year" ? "year" : row.billingCycle === "month" ? "month" : null;
+    return { isPaid: amount !== null, amount, currency: amount !== null ? row.currency : null, cycle: amount !== null ? cycle : null };
+  }
+  if (!tier) return { isPaid: false, amount: null, currency: null, cycle: null };
+  const cycle = defaultCycle(tier);
+  return { isPaid: !cycleIsFree(tier, cycle), amount: null, currency: null, cycle: null };
+}
+
 /**
  * The Membership menu inside a community: current tier, renewal date, a pending
  * downgrade, and the actions. Cancel keeps the paid period; a downgrade takes
@@ -55,6 +89,7 @@ export function useCommunityMembership() {
   const downgrade = useDowngradeCommunityMembership(ref);
   const undo = useUndoCommunityDowngrade(ref);
   const billingPortal = useOpenBillingPortal();
+  const mine = useMyCommunityMemberships({ enabled: !!community.membership });
 
   const [cancelRequested, setCancelRequested] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -73,11 +108,17 @@ export function useCommunityMembership() {
       })
     : null;
 
+  const mineRow = membership ? mine.data?.find((row) => row.id === membership.id) : undefined;
+  const billing = communityMembershipBilling(
+    mineRow ? { amount: mineRow.subscriptionAmount ?? null, currency: mineRow.subscriptionCurrency ?? null, billingCycle: mineRow.billingCycle ?? null } : null,
+    community.currentTier,
+  );
+
   const run = async (action: () => Promise<unknown>) => {
     setError(null);
     try {
       await action();
-      await community.refetch();
+      await Promise.all([community.refetch(), membership ? mine.refetch() : Promise.resolve()]);
       return true;
     } catch (e) {
       setError(errMessage(e));
@@ -97,6 +138,11 @@ export function useCommunityMembership() {
     pendingDowngradeTier,
     downgradeTiers,
     isPastDue: community.viewer?.state === "past_due",
+    /** Paid or free, and the price per period when the server has said. A free membership has no card to update. */
+    billing,
+    isPaid: billing.isPaid,
+    /** A higher tier exists, so the sheet offers Upgrade. */
+    hasUpgrade: community.hasUpgrade,
     error,
     isWorking: cancel.isPending || downgrade.isPending || undo.isPending || billingPortal.isPending,