@tribe-nest/forge 3.59.0 → 3.61.0

package/src/ui/headless/_tests/siteAppBar.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { APP_BAR_HREFS, buildAppBar, isAppBarItemActive, normaliseBarItems } from "../siteApp/appBar";
+import { SITE_APP_BAR_KEYS } from "../../../data/queries/useSiteApp";
+
+/**
+ * The site app's bottom bar model: Home first, the creator's items (at most
+ * three) after it, More last, and every other destination behind More.
+ */
+
+const keys = (items: Array<{ key: string }>) => items.map((item) => item.key);
+
+describe("buildAppBar", () => {
+  it("puts Home first, then the configured items in their order, and the rest behind More", () => {
+    const model = buildAppBar({ barItems: ["shop", "events"], homeHref: "/i/app" });
+    expect(keys(model.bar)).toEqual(["home", "shop", "events"]);
+    // The sheet keeps the canonical order, not the configured one.
+    expect(keys(model.more)).toEqual(["communities", "portal", "inbox", "courses"]);
+  });
+
+  it("uses the contract's default bar when nothing is configured", () => {
+    for (const barItems of [undefined, null, []]) {
+      const model = buildAppBar({ barItems, homeHref: "/i/app" });
+      expect(keys(model.bar)).toEqual(["home", "communities", "portal", "inbox"]);
+      expect(keys(model.more)).toEqual(["events", "courses", "shop"]);
+    }
+  });
+
+  it("drops unknown keys and repeats and holds at most three items", () => {
+    const model = buildAppBar({
+      barItems: ["inbox", "nope", "inbox", "courses", "home", "shop", "events"],
+      homeHref: "/i/app",
+    });
+    expect(keys(model.bar)).toEqual(["home", "inbox", "courses", "shop"]);
+    expect(normaliseBarItems(["events", "events", "bogus"])).toEqual(["events"]);
+  });
+
+  it("lists every destination exactly once, in the bar or in More", () => {
+    for (const barItems of [["communities"], ["portal", "inbox", "events"], ["shop", "courses", "communities"]]) {
+      const model = buildAppBar({ barItems, homeHref: "/i/app" });
+      const all = [...keys(model.bar), ...keys(model.more)];
+      expect(all.sort()).toEqual(["home", ...SITE_APP_BAR_KEYS].sort());
+    }
+  });
+
+  it("links each destination to its page, and Home to the Home it is given", () => {
+    const model = buildAppBar({ barItems: ["inbox"], homeHref: "/members" });
+    expect(model.bar[0]).toMatchObject({ key: "home", href: "/members" });
+    expect(model.bar[1]).toMatchObject({ key: "inbox", href: "/i/account/notifications" });
+    expect(APP_BAR_HREFS).toEqual({
+      communities: "/i/communities",
+      portal: "/i/account",
+      inbox: "/i/account/notifications",
+      events: "/i/events",
+      courses: "/i/courses",
+      shop: "/i/store",
+    });
+  });
+
+  it("highlights the page being shown, and More when that page lives in the sheet", () => {
+    const onEvents = buildAppBar({ barItems: ["events"], homeHref: "/i/app", currentPath: "/i/events/summit" });
+    expect(onEvents.bar.find((item) => item.key === "events")?.active).toBe(true);
+    expect(onEvents.moreActive).toBe(false);
+
+    const inSheet = buildAppBar({ barItems: ["communities"], homeHref: "/i/app", currentPath: "/i/store/tee?x=1" });
+    expect(inSheet.more.find((item) => item.key === "shop")?.active).toBe(true);
+    expect(inSheet.moreActive).toBe(true);
+
+    const home = buildAppBar({ barItems: [], homeHref: "/i/app", currentPath: "/i/app/" });
+    expect(home.bar[0]!.active).toBe(true);
+  });
+
+  it("does not let the portal claim the inbox, which lives under it", () => {
+    expect(isAppBarItemActive("portal", "/i/account", "/i/account/notifications")).toBe(false);
+    expect(isAppBarItemActive("inbox", "/i/account/notifications", "/i/account/notifications")).toBe(true);
+    expect(isAppBarItemActive("portal", "/i/account", "/i/account/invoices")).toBe(true);
+  });
+
+  it("matches Home exactly, so a custom Home at the root does not light up on every page", () => {
+    expect(isAppBarItemActive("home", "/", "/i/events")).toBe(false);
+    expect(isAppBarItemActive("home", "/", "/")).toBe(true);
+    expect(isAppBarItemActive("events", "/i/events", "/i/eventsx")).toBe(false);
+  });
+});

package/src/ui/headless/_tests/siteAppHarness.ts

@@ -0,0 +1,19 @@
+import type { SiteApp } from "../../../data/queries/useSiteApp";
+
+/** The public site app settings (`GET /public/websites/app`), as the contract shapes them. */
+export const siteApp = (patch: Partial<SiteApp> = {}): SiteApp => ({
+  websiteId: "website-1",
+  profileId: "profile-1",
+  appName: "Northlight",
+  shortName: "Northlight",
+  iconUrl: null,
+  themeColor: null,
+  backgroundColor: null,
+  startUrl: "/i/app",
+  homeSections: [{ type: "builtin", key: "portal", visible: true }],
+  barItems: ["communities", "portal", "inbox"],
+  installPrompt: true,
+  pushPrompt: true,
+  activeVersionId: null,
+  ...patch,
+});

package/src/ui/headless/_tests/siteAppHome.spec.ts

@@ -0,0 +1,226 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildAppHomeSections,
+  buildPortalTiles,
+  courseProgress,
+  pickLearningCourse,
+  pickNextCall,
+  pickNextTicket,
+  upcomingEvents,
+  type AppHomeData,
+} from "../siteApp/appHome";
+import type { SiteAppHomeSection } from "../../../data/queries/useSiteApp";
+import type { PortalSummary } from "../portal/usePortal";
+import type { MyBooking } from "../../../data/queries/useMyBookings";
+import type { MyTicket } from "../../../data/queries/useMyTickets";
+import type { MyMembershipCall } from "../../../data/queries/useMembershipCalls";
+import type { CourseAccessData, IEvent } from "../../../types/models";
+
+/**
+ * The app home's sections: the configured order, hidden entries skipped,
+ * empty sections skipped, and the portal drawn whatever it holds.
+ */
+
+const builtin = (key: string, visible = true) => ({ type: "builtin", key, visible }) as SiteAppHomeSection;
+const link = (id: string, label: string, href: string, visible = true) =>
+  ({ type: "link", id, label, href, visible }) as SiteAppHomeSection;
+
+const community = (id: string) => ({
+  id,
+  name: `Community ${id}`,
+  slug: `c-${id}`,
+  logoUrl: null,
+  coverUrl: null,
+  tierName: null,
+  memberCount: 3,
+  href: `/i/communities/c-${id}`,
+});
+
+const full: AppHomeData = {
+  attention: [
+    {
+      kind: "invoice_due",
+      id: "inv-1",
+      invoiceNumber: "1042",
+      total: "450",
+      currency: "USD",
+      dueDate: null,
+      projectId: null,
+      projectName: null,
+    },
+  ],
+  communities: [community("a")],
+  nextCall: { id: "call:1", title: "Group call", startsAt: "2026-10-02T18:00:00Z", joinable: false, href: "/x", context: null },
+  nextTicket: null,
+  learning: { accessId: "acc-1", title: "Pricing", href: "/i/course-access/acc-1", progress: null },
+  explore: [community("b"), community("c"), community("d"), community("e")],
+  events: [{ id: "e-1" } as IEvent],
+  courses: [],
+  products: [],
+};
+
+const kinds = (config: SiteAppHomeSection[], data: AppHomeData) => buildAppHomeSections(config, data).map((s) => s.kind);
+
+describe("buildAppHomeSections", () => {
+  it("draws the sections in the configured order", () => {
+    const config = [builtin("learning"), builtin("portal"), builtin("needs_you"), builtin("communities"), builtin("coming_up")];
+    expect(kinds(config, full)).toEqual(["learning", "portal", "needs_you", "communities", "coming_up"]);
+  });
+
+  it("skips hidden sections", () => {
+    const config = [builtin("needs_you", false), builtin("portal"), builtin("events", false), builtin("communities")];
+    expect(kinds(config, full)).toEqual(["portal", "communities"]);
+  });
+
+  it("skips a section with nothing to show, except the portal", () => {
+    const config = [
+      builtin("needs_you"),
+      builtin("portal"),
+      builtin("communities"),
+      builtin("coming_up"),
+      builtin("learning"),
+      builtin("explore_communities"),
+      builtin("events"),
+      builtin("courses"),
+      builtin("shop"),
+    ];
+    expect(kinds(config, {})).toEqual(["portal"]);
+    // The portal with no summary still has its Settings tile.
+    const [portal] = buildAppHomeSections([builtin("portal")], {});
+    expect(portal).toMatchObject({ kind: "portal", tiles: [{ key: "settings" }] });
+    // Courses and shop configured but empty are left out while the rest draw.
+    expect(kinds(config, full)).toEqual([
+      "needs_you",
+      "portal",
+      "communities",
+      "coming_up",
+      "learning",
+      "explore_communities",
+      "events",
+    ]);
+  });
+
+  it("draws link sections where they are placed, and only with a safe address", () => {
+    const config = [
+      link("l1", "Book a call", "/book"),
+      builtin("portal"),
+      link("l2", "Our podcast", "https://example.com/pod"),
+      link("l3", "Bad", "javascript:alert(1)"),
+      link("l4", "Off-site trick", "//evil.example"),
+      link("l5", "  ", "/blank"),
+      link("l6", "Hidden", "/hidden", false),
+    ];
+    const sections = buildAppHomeSections(config, {});
+    expect(sections.map((s) => s.key)).toEqual(["l1", "portal", "l2"]);
+    expect(sections[0]).toEqual({ kind: "link", key: "l1", label: "Book a call", href: "/book" });
+  });
+
+  it("ignores unknown keys and repeats", () => {
+    const config = [builtin("portal"), builtin("mystery"), builtin("portal"), link("x", "A", "/a"), link("x", "B", "/b")];
+    expect(buildAppHomeSections(config, {}).map((s) => s.key)).toEqual(["portal", "x"]);
+  });
+
+  it("caps the explore list and turns attention into one-tap actions", () => {
+    const sections = buildAppHomeSections([builtin("needs_you"), builtin("explore_communities")], full);
+    expect(sections[0]).toMatchObject({ kind: "needs_you", actions: [{ action: "pay", href: "/i/invoice/inv-1" }] });
+    expect(sections[1]!.kind === "explore_communities" && sections[1]!.communities.length).toBe(3);
+  });
+
+  it("draws nothing until the settings arrive", () => {
+    expect(buildAppHomeSections(undefined, full)).toEqual([]);
+  });
+});
+
+describe("buildPortalTiles", () => {
+  const summary = (sections: Partial<PortalSummary["sections"]>, attention: PortalSummary["attention"] = []): PortalSummary =>
+    ({ sections, attention, lastActivity: { work: null, library: null } }) as PortalSummary;
+
+  it("draws a tile per section the person has anything in, with what needs them as the badge", () => {
+    const tiles = buildPortalTiles(
+      summary({ projects: 1, invoices: 2, documents: 1, orders: 0 }, [
+        { kind: "invoice_overdue", id: "i", invoiceNumber: "1", total: "1", currency: "USD", dueDate: null, projectId: null, projectName: null },
+        { kind: "document_to_sign", id: "d", title: "Agreement", token: "t", sentAt: "2026-01-01", expiresAt: null },
+      ]),
+    );
+    expect(tiles).toEqual([
+      { key: "projects", href: "/i/account/projects", attention: 0 },
+      { key: "invoices", href: "/i/account/invoices", attention: 1 },
+      { key: "documents", href: "/i/account/documents", attention: 1 },
+      { key: "settings", href: "/i/account/settings", attention: 0 },
+    ]);
+  });
+
+  it("is exactly the eight sections when the person has all of them", () => {
+    const tiles = buildPortalTiles(
+      summary({ projects: 1, bookings: 1, invoices: 1, documents: 1, courses: 1, orders: 1, tickets: 1, saved: 1 }),
+    );
+    expect(tiles.map((t) => t.key)).toEqual(["projects", "bookings", "invoices", "documents", "courses", "orders", "tickets", "saved"]);
+  });
+});
+
+describe("the section pickers", () => {
+  const now = new Date("2026-10-01T12:00:00Z");
+
+  it("picks the soonest call that has not ended, joinable when its room is open", () => {
+    const calls = [
+      { id: "c1", title: "Later call", startsAt: "2026-10-03T10:00:00Z", endsAt: "2026-10-03T11:00:00Z", isOpen: false, callPublicId: "room-1", audiences: [{ label: "Gold" }] },
+      { id: "c0", title: "Ended", startsAt: "2026-09-30T10:00:00Z", endsAt: "2026-09-30T11:00:00Z", isOpen: false, callPublicId: "room-0", audiences: [] },
+    ] as unknown as MyMembershipCall[];
+    const bookings = [
+      { id: "b1", status: "confirmed", sessionStartTime: "2026-10-01T12:05:00Z", sessionEndTime: "2026-10-01T13:00:00Z", videoCallId: "vc-1", coachingProductTitle: "1:1 session", location: { type: "video" } },
+      { id: "b2", status: "canceled", sessionStartTime: "2026-10-01T12:01:00Z", sessionEndTime: "2026-10-01T13:00:00Z", videoCallId: "vc-2", coachingProductTitle: "Cancelled" },
+    ] as unknown as MyBooking[];
+    expect(pickNextCall(calls, bookings, now)).toEqual({
+      id: "booking:b1",
+      title: "1:1 session",
+      startsAt: "2026-10-01T12:05:00Z",
+      joinable: true,
+      href: "/i/video-calls/vc-1",
+      context: null,
+    });
+    expect(pickNextCall(calls, [], now)).toMatchObject({ id: "call:c1", joinable: false, context: "Gold", href: "/i/video-calls/room-1" });
+    expect(pickNextCall([], [], now)).toBeNull();
+  });
+
+  it("picks the next ticket, counting its passes and skipping cancelled orders", () => {
+    const tickets = [
+      { id: "t2", status: "paid", selfCancelledAt: null, eventTitle: "Summit", eventDateTime: "2026-11-14T09:00:00Z", eventEndDateTime: null, items: [{ quantity: 2 }] },
+      { id: "t1", status: "refunded", selfCancelledAt: null, eventTitle: "Refunded", eventDateTime: "2026-10-05T09:00:00Z", eventEndDateTime: null, items: [] },
+    ] as unknown as MyTicket[];
+    expect(pickNextTicket(tickets, now)).toEqual({
+      id: "t2",
+      title: "Summit",
+      startsAt: "2026-11-14T09:00:00Z",
+      count: 2,
+      href: "/i/account/tickets",
+    });
+  });
+
+  it("carries on with a started course, and measures it in lessons", () => {
+    const course = (accessId: string, patch: object) => ({ accessId, courseId: accessId, title: accessId, completedAt: null, currentLessonId: null, ...patch });
+    expect(pickLearningCourse([course("done", { completedAt: "2026-01-01" }), course("new", {}), course("started", { currentLessonId: "l2" })] as never)?.accessId).toBe("started");
+    expect(pickLearningCourse([course("done", { completedAt: "2026-01-01" })] as never)).toBeNull();
+
+    const access = {
+      access: {},
+      course: { modules: [{ lessons: [{ id: "l1" }, { id: "l2" }] }, { lessons: [{ id: "l3" }, { id: "l4" }] }] },
+      progress: [
+        { lessonId: "l1", isCompleted: true },
+        { lessonId: "l2", isCompleted: false },
+        { lessonId: "l3", isCompleted: true },
+      ],
+    } as unknown as CourseAccessData;
+    expect(courseProgress(access)).toEqual({ done: 2, total: 4, ratio: 0.5 });
+    expect(courseProgress(null)).toBeNull();
+  });
+
+  it("lists only events still to come, soonest first", () => {
+    const events = [
+      { id: "late", status: "on_sale", dateTime: "2026-12-01T00:00:00Z", endDateTime: null, cancelledAt: null },
+      { id: "past", status: "on_sale", dateTime: "2026-09-01T00:00:00Z", endDateTime: null, cancelledAt: null },
+      { id: "soon", status: "scheduled", dateTime: "2026-10-10T00:00:00Z", endDateTime: null, cancelledAt: null },
+      { id: "off", status: "cancelled", dateTime: "2026-10-11T00:00:00Z", endDateTime: null, cancelledAt: "2026-09-01" },
+    ] as unknown as IEvent[];
+    expect(upcomingEvents(events, now).map((e) => e.id)).toEqual(["soon", "late"]);
+  });
+});

package/src/ui/headless/_tests/siteAppPrompts.spec.ts

@@ -0,0 +1,185 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  APP_INSTALL_REQUEST_TTL_MS,
+  APP_INSTALL_SNOOZE_MS,
+  clearPendingAppInstall,
+  decideAppInstall,
+  decideAppPush,
+  pushPreferencePatch,
+  readInstallDismissedAt,
+  readPendingAppInstall,
+  readPushAnswer,
+  rememberInstallDismissed,
+  rememberPushAnswer,
+  requestAppInstall,
+  subscribeAppInstallRequests,
+} from "../siteApp/appPrompts";
+
+/**
+ * The gating of the site app's two prompts, and the storage around them.
+ */
+
+const DAY = 24 * 60 * 60 * 1000;
+const NOW = Date.parse("2026-10-01T12:00:00Z");
+
+const install = (patch: Partial<Parameters<typeof decideAppInstall>[0]> = {}) =>
+  decideAppInstall({
+    installPrompt: true,
+    isStandalone: false,
+    isIOS: false,
+    hasNativePrompt: true,
+    dismissedAt: null,
+    now: NOW,
+    ...patch,
+  });
+
+beforeEach(() => {
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+  clearPendingAppInstall();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("decideAppInstall", () => {
+  it("uses the native prompt where the browser holds one", () => {
+    expect(install()).toBe("native");
+  });
+
+  it("gives an iPhone the two Safari steps, which has no native prompt", () => {
+    expect(install({ hasNativePrompt: false, isIOS: true })).toBe("ios");
+  });
+
+  it("never shows in the installed app", () => {
+    expect(install({ isStandalone: true })).toBeNull();
+    expect(install({ isStandalone: true, isIOS: true, hasNativePrompt: false })).toBeNull();
+  });
+
+  it("respects the website's setting, and treats an unknown setting as off", () => {
+    expect(install({ installPrompt: false })).toBeNull();
+    expect(install({ installPrompt: undefined })).toBeNull();
+    expect(install({ installPrompt: null })).toBeNull();
+  });
+
+  it("stays away for 14 days after Not now, and comes back after", () => {
+    expect(install({ dismissedAt: NOW - 1 * DAY })).toBeNull();
+    expect(install({ dismissedAt: NOW - 13 * DAY })).toBeNull();
+    expect(install({ dismissedAt: NOW - APP_INSTALL_SNOOZE_MS })).toBe("native");
+    expect(install({ dismissedAt: NOW - 15 * DAY })).toBe("native");
+  });
+
+  it("has nothing to show where there is neither a prompt nor Safari's steps", () => {
+    expect(install({ hasNativePrompt: false, isIOS: false })).toBeNull();
+  });
+});
+
+describe("Not now, remembered", () => {
+  it("round-trips through localStorage", () => {
+    expect(readInstallDismissedAt()).toBeNull();
+    rememberInstallDismissed(NOW);
+    expect(readInstallDismissedAt()).toBe(NOW);
+  });
+
+  it("never throws when storage is blocked", () => {
+    vi.spyOn(Storage.prototype, "getItem").mockImplementation(() => {
+      throw new Error("SecurityError");
+    });
+    vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+      throw new Error("SecurityError");
+    });
+    expect(() => rememberInstallDismissed(NOW)).not.toThrow();
+    expect(readInstallDismissedAt()).toBeNull();
+    expect(() => rememberPushAnswer("accepted")).not.toThrow();
+    expect(readPushAnswer()).toBeNull();
+  });
+});
+
+describe("requestAppInstall", () => {
+  it("holds the request for the page that can show it, and tells listeners", () => {
+    const heard = vi.fn();
+    const off = subscribeAppInstallRequests(heard);
+    requestAppInstall("purchase");
+    expect(heard).toHaveBeenCalledTimes(1);
+    expect(readPendingAppInstall()).toMatchObject({ context: "purchase" });
+    off();
+  });
+
+  it("survives a navigation through sessionStorage", () => {
+    requestAppInstall("joined_community");
+    const stored = window.sessionStorage.getItem("forge-app-install-pending");
+    clearPendingAppInstall();
+    expect(readPendingAppInstall()).toBeNull();
+    // A fresh page: the copy in memory is gone, the session copy is not.
+    window.sessionStorage.setItem("forge-app-install-pending", stored!);
+    expect(readPendingAppInstall()).toMatchObject({ context: "joined_community" });
+  });
+
+  it("lets a stale request lapse", () => {
+    requestAppInstall("booking");
+    const at = readPendingAppInstall()!.at;
+    expect(readPendingAppInstall(at + APP_INSTALL_REQUEST_TTL_MS + 1)).toBeNull();
+  });
+
+  it("ignores a context it does not know", () => {
+    requestAppInstall("nonsense" as never);
+    expect(readPendingAppInstall()).toBeNull();
+  });
+});
+
+describe("decideAppPush", () => {
+  const push = (patch: Partial<Parameters<typeof decideAppPush>[0]> = {}) =>
+    decideAppPush({
+      pushPrompt: true,
+      isStandalone: true,
+      isSignedIn: true,
+      isSupported: true,
+      permission: "default",
+      answer: null,
+      ...patch,
+    });
+
+  it("offers on the first launch of the installed app", () => {
+    expect(push()).toBe(true);
+  });
+
+  it("does not offer in a browser tab", () => {
+    expect(push({ isStandalone: false })).toBe(false);
+  });
+
+  it("respects the website's setting", () => {
+    expect(push({ pushPrompt: false })).toBe(false);
+    expect(push({ pushPrompt: undefined })).toBe(false);
+  });
+
+  it("needs someone signed in, and a browser that can push", () => {
+    expect(push({ isSignedIn: false })).toBe(false);
+    expect(push({ isSupported: false })).toBe(false);
+  });
+
+  it("asks only while the browser has not been asked", () => {
+    expect(push({ permission: "granted" })).toBe(false);
+    expect(push({ permission: "denied" })).toBe(false);
+  });
+
+  it("asks once: any earlier answer ends it", () => {
+    expect(push({ answer: "declined" })).toBe(false);
+    expect(push({ answer: "accepted" })).toBe(false);
+    rememberPushAnswer("declined");
+    expect(push({ answer: readPushAnswer() })).toBe(false);
+  });
+});
+
+describe("pushPreferencePatch", () => {
+  it("switches every known type of each category, and leaves unknown types alone", () => {
+    const known = new Set(["dm", "mention", "new_post", "event_reminder"]);
+    expect(pushPreferencePatch({ messages: true, community: false, events: true }, known)).toEqual({
+      "dm.push": true,
+      "mention.push": true,
+      "new_post.push": false,
+      "event_reminder.push": true,
+    });
+  });
+});

package/src/ui/headless/_tests/useCommunityInvite.spec.tsx

@@ -0,0 +1,104 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { describeCommunityInvite, useCommunityInvite } from "../communities/useCommunityInvite";
+import type { CommunityInviteState } from "../../../data/queries/useCommunities";
+import { account, calls, get, installAdapter, restoreAdapter, tier, wrapper } from "./communityHarness";
+
+/**
+ * What an invite is worth to THIS viewer: every state the server can answer,
+ * the mismatch only the client can see (signed in on this page as someone
+ * else), and which token is forwarded (only a usable one).
+ */
+
+afterEach(restoreAdapter);
+
+const vip = tier({ id: "tier-vip", joinMode: "invite" });
+const answer = (patch: Partial<CommunityInviteState>): CommunityInviteState => ({
+  kind: "email",
+  state: "valid",
+  invitedEmail: "invited@example.com",
+  tier: vip,
+  ...patch,
+});
+
+describe("describeCommunityInvite", () => {
+  it("no token: nothing to say and nothing to forward", () => {
+    expect(describeCommunityInvite({ tokens: {}, answer: undefined })).toMatchObject({
+      kind: null,
+      state: null,
+      isValid: false,
+      problem: null,
+      forward: {},
+    });
+  });
+
+  it("a valid per-email invite forwards the invite token and names its tier and email", () => {
+    expect(describeCommunityInvite({ tokens: { invite: "tok" }, answer: answer({}), signedInEmail: null })).toMatchObject({
+      kind: "email",
+      state: "valid",
+      isValid: true,
+      emailMismatch: false,
+      problem: null,
+      invitedEmail: "invited@example.com",
+      tier: vip,
+      forward: { inviteToken: "tok" },
+    });
+  });
+
+  it("signed in as another address (case-insensitively) is a mismatch, still forwarded so signing in as the invitee works", () => {
+    const summary = describeCommunityInvite({ tokens: { invite: "tok" }, answer: answer({}), signedInEmail: "Other@Example.com" });
+    expect(summary).toMatchObject({ state: "email_mismatch", isValid: false, emailMismatch: true, forward: { inviteToken: "tok" } });
+    expect(describeCommunityInvite({ tokens: { invite: "tok" }, answer: answer({}), signedInEmail: "INVITED@example.com" }).isValid).toBe(true);
+  });
+
+  it("the server's own email_mismatch is kept", () => {
+    expect(describeCommunityInvite({ tokens: { invite: "tok" }, answer: answer({ state: "email_mismatch" }) }).emailMismatch).toBe(true);
+  });
+
+  it.each(["expired", "revoked", "used", "used_up", "not_found"] as const)("%s is a problem, with no tier and no token forwarded", (state) => {
+    expect(describeCommunityInvite({ tokens: { invite: "tok" }, answer: answer({ state, tier: vip }) })).toMatchObject({
+      state,
+      isValid: false,
+      problem: state,
+      tier: null,
+      forward: {},
+    });
+  });
+
+  it("a shareable link forwards the join token and never mismatches on email", () => {
+    const summary = describeCommunityInvite({
+      tokens: { join: "link" },
+      answer: answer({ kind: "link", invitedEmail: null }),
+      signedInEmail: "anyone@example.com",
+    });
+    expect(summary).toMatchObject({ kind: "link", isValid: true, emailMismatch: false, invitedEmail: null, forward: { joinToken: "link" } });
+  });
+});
+
+describe("useCommunityInvite", () => {
+  it("reads the invite state for the provider's community with the token", async () => {
+    installAdapter([get("/public/communities/fan-club/invite", () => answer({}))]);
+    const { result } = renderHook(() => useCommunityInvite({ invite: "tok" }), { wrapper: wrapper({ user: account("invited@example.com") }) });
+    await waitFor(() => expect(result.current.isValid).toBe(true));
+    expect(calls("get", "/public/communities/fan-club/invite")[0].params).toMatchObject({ profileId: "profile-1", invite: "tok" });
+  });
+
+  it("a token the server cannot resolve at all (404) reads as not found, never as valid", async () => {
+    installAdapter([
+      get("/public/communities/fan-club/invite", () => {
+        throw { status: 404 };
+      }),
+    ]);
+    const { result } = renderHook(() => useCommunityInvite({ join: "gone" }), { wrapper: wrapper() });
+    await waitFor(() => expect(result.current.problem).toBe("not_found"));
+    expect(result.current.forward).toEqual({});
+  });
+
+  it("sends nothing without a token", async () => {
+    installAdapter([]);
+    const { result } = renderHook(() => useCommunityInvite({}), { wrapper: wrapper() });
+    expect(result.current.kind).toBeNull();
+    expect(calls("get", /\/invite$/)).toHaveLength(0);
+  });
+});