@tribe-nest/forge 3.59.0 → 3.60.0

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

@@ -0,0 +1,80 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import { CommunityGate, communityGateAllows } from "../communities/CommunityGate";
+import { account, detailRoute, installAdapter, meRoute, restoreAdapter, viewer, wrapper } from "./communityHarness";
+
+/**
+ * `CommunityGate` replaces `MembershipGate`. With no tiers it means "an active
+ * member of THIS community": a membership in another community of the same
+ * creator unlocks nothing here.
+ */
+
+afterEach(restoreAdapter);
+
+const memberOn = (tierId: string, state: "member" | "past_due" | "cancelled" = "member") =>
+  viewer({
+    state,
+    membership: { id: "m-1", tierId, tierName: tierId, status: "active", cancelAtPeriodEnd: false, currentPeriodEnd: null, pendingDowngradeTierId: null },
+  });
+
+describe("communityGateAllows", () => {
+  it("any active member of this community, when no tiers are named", () => {
+    expect(communityGateAllows(memberOn("tier-a"))).toBe(true);
+    expect(communityGateAllows(memberOn("tier-a", "past_due"))).toBe(true);
+  });
+  it("nobody else: none, pending, cancelled, anonymous, or no viewer at all", () => {
+    for (const state of ["none", "pending", "cancelled", "anonymous"] as const) {
+      expect(communityGateAllows(viewer({ state }))).toBe(false);
+    }
+    expect(communityGateAllows(undefined)).toBe(false);
+  });
+  it("only the named tiers when tiers are named", () => {
+    expect(communityGateAllows(memberOn("tier-a"), ["tier-a", "tier-b"])).toBe(true);
+    expect(communityGateAllows(memberOn("tier-c"), ["tier-a", "tier-b"])).toBe(false);
+  });
+});
+
+function renderGate(me: () => ReturnType<typeof viewer>, tiers?: string[]) {
+  installAdapter([meRoute(me), detailRoute(() => ({ viewer: me() }))]);
+  const Wrapper = wrapper({ user: account() });
+  render(
+    <Wrapper>
+      <CommunityGate tiers={tiers} fallback={(state) => <p data-testid="locked">{state.viewerState}</p>}>
+        <p data-testid="unlocked">secret</p>
+      </CommunityGate>
+    </Wrapper>,
+  );
+}
+
+describe("<CommunityGate>", () => {
+  it("shows the content to a member of this community", async () => {
+    renderGate(() => memberOn("tier-a"));
+    expect(await screen.findByTestId("unlocked")).toBeTruthy();
+  });
+
+  it("locks out a fan whose membership is in ANOTHER community (the server answers none here)", async () => {
+    renderGate(() => viewer({ state: "none" }));
+    expect((await screen.findByTestId("locked")).textContent).toBe("none");
+    expect(screen.queryByTestId("unlocked")).toBeNull();
+  });
+
+  it("locks out a member on a tier the gate does not name", async () => {
+    renderGate(() => memberOn("tier-c"), ["tier-a"]);
+    await waitFor(() => expect(screen.getByTestId("locked").textContent).toBe("member"));
+  });
+
+  it("refuses to render outside a provider", () => {
+    installAdapter([]);
+    const Wrapper = wrapper({ community: null });
+    expect(() =>
+      render(
+        <Wrapper>
+          <CommunityGate>
+            <p>secret</p>
+          </CommunityGate>
+        </Wrapper>,
+      ),
+    ).toThrow(/CommunityProvider/);
+  });
+});

package/src/ui/headless/_tests/communityHarness.tsx

@@ -0,0 +1,205 @@
+import { useState, type ReactNode } from "react";
+import axios, { type AxiosAdapter, type InternalAxiosRequestConfig } from "axios";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ForgeClientProvider } from "../../../provider/ForgeProvider";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { CommunityProvider } from "../../../contexts/CommunityContext";
+import type {
+  CommunityDetail,
+  CommunityViewerState,
+  PublicCommunity,
+  PublicTier,
+} from "../../../data/queries/useCommunities";
+
+/**
+ * A real provider tree for the community hook specs: the real data hooks over
+ * a stub axios adapter, so a spec asserts what is SENT, and an auth context
+ * whose sign-up, code and sign-in steps really sign the fan in (the join sheet
+ * reacts to that exactly as it does on a site).
+ */
+
+export const PROFILE_ID = "profile-1";
+
+export const COMMUNITY: PublicCommunity = {
+  id: "11111111-1111-4111-8111-111111111111",
+  name: "Fan Club",
+  slug: "fan-club",
+  description: "Where the fans are.",
+  coverUrl: null,
+  logoUrl: null,
+  category: "Music",
+  tags: [],
+  memberCount: 42,
+};
+
+export const OTHER_COMMUNITY: PublicCommunity = {
+  ...COMMUNITY,
+  id: "22222222-2222-4222-8222-222222222222",
+  name: "Producers Circle",
+  slug: "producers",
+};
+
+export const tier = (overrides: Partial<PublicTier> = {}): PublicTier => ({
+  id: "tier-free",
+  name: "Free",
+  description: "",
+  payWhatYouWant: false,
+  benefits: [],
+  communityId: COMMUNITY.id,
+  ...overrides,
+});
+
+export const viewer = (overrides: Partial<CommunityViewerState> = {}): CommunityViewerState => ({
+  state: "none",
+  membership: null,
+  application: null,
+  upgradeTiers: [],
+  canInteract: false,
+  ...overrides,
+});
+
+export const account = (email = "fan@example.com") => ({
+  id: "account-1",
+  email,
+  firstName: "Fan",
+  lastName: "Person",
+  kind: "fan",
+  status: "active",
+  createdAt: "2026-01-01T00:00:00.000Z",
+  updatedAt: "2026-01-01T00:00:00.000Z",
+});
+
+export interface Sent {
+  method: string;
+  url: string;
+  params: Record<string, unknown> | undefined;
+  body: Record<string, unknown> | null;
+}
+
+export type Route = (req: Sent) => unknown | undefined;
+
+let realAdapter: AxiosAdapter | undefined;
+export let sent: Sent[] = [];
+
+/**
+ * Answer requests from `routes` in order; the first that returns something
+ * other than `undefined` wins. A thrown `{ status }` becomes that HTTP error.
+ */
+export function installAdapter(routes: Route[]) {
+  sent = [];
+  realAdapter ??= axios.defaults.adapter as AxiosAdapter | undefined;
+  axios.defaults.adapter = (async (config: InternalAxiosRequestConfig) => {
+    const req: Sent = {
+      method: (config.method ?? "get").toLowerCase(),
+      url: config.url ?? "",
+      params: config.params as Record<string, unknown> | undefined,
+      body: config.data ? (JSON.parse(config.data as string) as Record<string, unknown>) : null,
+    };
+    sent.push(req);
+    for (const route of routes) {
+      let data: unknown;
+      try {
+        data = route(req);
+      } catch (e) {
+        const status = (e as { status?: number }).status ?? 500;
+        const error = Object.assign(new Error(`HTTP ${status}`), {
+          response: { status, data: { message: (e as { message?: string }).message } },
+          config,
+          isAxiosError: true,
+        });
+        throw error;
+      }
+      if (data !== undefined) return { data, status: 200, statusText: "OK", headers: {}, config } as never;
+    }
+    return { data: {}, status: 200, statusText: "OK", headers: {}, config } as never;
+  }) as AxiosAdapter;
+}
+
+export function restoreAdapter() {
+  if (realAdapter) axios.defaults.adapter = realAdapter;
+}
+
+/** The community read, answered for `/public/communities/:slug` (with or without a token). */
+export const detailRoute =
+  (detail: (req: Sent) => Partial<CommunityDetail>): Route =>
+  (req) => {
+    if (req.method !== "get") return undefined;
+    const match = /^\/public\/communities\/([^/]+)$/.exec(req.url);
+    if (!match) return undefined;
+    return { community: COMMUNITY, tiers: [], viewer: viewer(), invite: null, ...detail(req) };
+  };
+
+export const meRoute =
+  (state: () => CommunityViewerState): Route =>
+  (req) =>
+    req.method === "get" && /^\/public\/communities\/[^/]+\/me$/.test(req.url) ? state() : undefined;
+
+export const post = (path: string, answer: (req: Sent) => unknown): Route => (req) =>
+  req.method === "post" && req.url === path ? answer(req) : undefined;
+
+export const get = (path: string | RegExp, answer: (req: Sent) => unknown): Route => (req) =>
+  req.method === "get" && (typeof path === "string" ? req.url === path : path.test(req.url)) ? answer(req) : undefined;
+
+export interface AuthControls {
+  logout: () => void;
+}
+
+/**
+ * A stateful auth context: `register` succeeds and asks for a code,
+ * `verifyRegistration` signs the fan in, `validateLoginCredentials` +
+ * `verifyLoginCode` do the same for sign-in, `logout` signs out.
+ */
+function TestAuth({ initialUser, children, controls }: { initialUser: unknown; children: ReactNode; controls?: AuthControls }) {
+  const [user, setUser] = useState<ReturnType<typeof account> | null>(initialUser as ReturnType<typeof account> | null);
+  const value = {
+    user,
+    isAuthenticated: !!user,
+    isInitialized: true,
+    currencies: null,
+    userSelectedCurrency: "USD",
+    register: async () => ({}),
+    verifyRegistration: async (data: { email: string }) => {
+      setUser(account(data.email));
+      return {};
+    },
+    validateLoginCredentials: async () => ({}),
+    verifyLoginCode: async (email: string) => {
+      setUser(account(email));
+      return {};
+    },
+    resendLoginCode: async () => {},
+    logout: async () => {
+      controls?.logout();
+      setUser(null);
+    },
+    refetchUser: async () => {},
+  };
+  return <PublicAuthContext.Provider value={value as never}>{children}</PublicAuthContext.Provider>;
+}
+
+/** A `renderHook` wrapper: client, auth, and (unless `community: null`) a community provider. */
+export function wrapper(opts: { user?: unknown; community?: PublicCommunity | null; controls?: AuthControls } = {}) {
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } });
+  const community = opts.community === undefined ? COMMUNITY : opts.community;
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <QueryClientProvider client={client}>
+        <ForgeClientProvider apiUrl="http://api.test" profileId={PROFILE_ID}>
+          <TestAuth initialUser={opts.user ?? null} controls={opts.controls}>
+            {community ? (
+              <CommunityProvider community={community.slug} initialData={community}>
+                {children}
+              </CommunityProvider>
+            ) : (
+              children
+            )}
+          </TestAuth>
+        </ForgeClientProvider>
+      </QueryClientProvider>
+    );
+  };
+}
+
+/** Requests to `path` (exact) with `method`. */
+export const calls = (method: string, path: string | RegExp) =>
+  sent.filter((req) => req.method === method && (typeof path === "string" ? req.url === path : path.test(req.url)));

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

@@ -0,0 +1,151 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import { render, renderHook, waitFor } from "@testing-library/react";
+import { useCommunitySpaces, useCommunityLeaderboard } from "../../../data/queries/useCommunity";
+import { useChatChannels } from "../../../data/queries/useChat";
+import { useGetPosts, useGetSavedPosts } from "../../../data/queries/usePosts";
+import { useGetPostCollection, useGetPostCollections } from "../../../data/queries/usePostCollections";
+import { useMyMembershipCalls } from "../../../data/queries/useMembershipCalls";
+import type { ReactNode } from "react";
+import { CommunityProvider, useCommunityContext } from "../../../contexts/CommunityContext";
+import { useMemberHomeNav } from "../memberHome/useMemberHomeNav";
+import { useCommunityJoin } from "../communities/useCommunityJoin";
+import { COMMUNITY, OTHER_COMMUNITY, calls, detailRoute, get, installAdapter, restoreAdapter, wrapper } from "./communityHarness";
+
+/**
+ * `<CommunityProvider>` is how every member-content hook learns WHICH community
+ * it is reading. A profile runs several, each fully isolated, so a hook outside
+ * a provider must refuse (a developer error naming the provider) rather than
+ * fetch "the profile's" content, and inside one it must send the community and
+ * key its cache by it.
+ */
+
+afterEach(restoreAdapter);
+
+const PROVIDER_ERROR = /must be used inside <CommunityProvider/;
+
+describe("outside a provider, every member-content hook refuses", () => {
+  const cases: Array<[string, () => unknown]> = [
+    ["useCommunitySpaces", () => useCommunitySpaces()],
+    ["useCommunityLeaderboard", () => useCommunityLeaderboard()],
+    ["useChatChannels", () => useChatChannels()],
+    ["useGetPosts", () => useGetPosts()],
+    ["useGetSavedPosts", () => useGetSavedPosts()],
+    ["useGetPostCollections", () => useGetPostCollections()],
+    ["useMyMembershipCalls", () => useMyMembershipCalls()],
+    ["useMemberHomeNav", () => useMemberHomeNav()],
+    ["useCommunityJoin", () => useCommunityJoin()],
+    ["useCommunityContext", () => useCommunityContext()],
+  ];
+  for (const [name, hook] of cases) {
+    it(`${name} throws a developer error that names the provider and the hook`, () => {
+      installAdapter([]);
+      expect(() => renderHook(hook, { wrapper: wrapper({ community: null }) })).toThrow(PROVIDER_ERROR);
+      expect(() => renderHook(hook, { wrapper: wrapper({ community: null }) })).toThrow(name);
+      // Nothing was fetched on the way to the error.
+      expect(calls("get", /\/public\/(community|chat|posts|post-collections|scheduled-calls)/)).toHaveLength(0);
+    });
+  }
+
+  it("a course-scoped call read needs no provider: a course belongs to no community", async () => {
+    installAdapter([get("/public/scheduled-calls/mine", () => [])]);
+    const { result } = renderHook(() => useMyMembershipCalls({ courseId: "course-1" }), { wrapper: wrapper({ community: null }) });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    const [req] = calls("get", "/public/scheduled-calls/mine");
+    expect(req.params).toMatchObject({ courseId: "course-1" });
+    expect(req.params?.communityId).toBeUndefined();
+  });
+});
+
+describe("inside a provider, the community is sent and keys the cache", () => {
+  it("sends communityId with every member-content read", async () => {
+    installAdapter([
+      get("/public/community/spaces", () => []),
+      get("/public/chat/channels", () => []),
+      get("/public/posts", () => ({ data: [], total: 0, page: 1, pageSize: 10, hasNextPage: false })),
+      get("/public/post-collections", () => ({ data: [], total: 0, page: 1, pageSize: 10 })),
+      get("/public/scheduled-calls/mine", () => []),
+    ]);
+    const { result } = renderHook(
+      () => ({
+        spaces: useCommunitySpaces(),
+        channels: useChatChannels(),
+        posts: useGetPosts(),
+        collections: useGetPostCollections(),
+        calls: useMyMembershipCalls(),
+      }),
+      { wrapper: wrapper() },
+    );
+    await waitFor(() => expect(Object.values(result.current).every((q) => q.isSuccess)).toBe(true));
+    for (const path of ["/public/community/spaces", "/public/chat/channels", "/public/posts", "/public/post-collections", "/public/scheduled-calls/mine"]) {
+      const [req] = calls("get", path);
+      expect(req?.params, path).toMatchObject({ profileId: "profile-1", communityId: COMMUNITY.id });
+    }
+  });
+
+  it("two communities on one page (one query cache) never share a cache entry", async () => {
+    installAdapter([
+      get("/public/community/spaces", (req) => [
+        { id: `space-of-${String(req.params?.communityId)}`, name: "Space", tiers: [] },
+      ]),
+    ]);
+    const seen: Record<string, string | undefined> = {};
+    function Spaces({ label }: { label: string }) {
+      seen[label] = useCommunitySpaces().data?.[0]?.id;
+      return null;
+    }
+    const Wrapper = wrapper({ community: null });
+    render(
+      <Wrapper>
+        <CommunityProvider community={COMMUNITY.slug} initialData={COMMUNITY}>
+          <Spaces label="a" />
+        </CommunityProvider>
+        <CommunityProvider community={OTHER_COMMUNITY.slug} initialData={OTHER_COMMUNITY}>
+          <Spaces label="b" />
+        </CommunityProvider>
+      </Wrapper>,
+    );
+    await waitFor(() => expect(seen.a && seen.b).toBeTruthy());
+    expect(seen.a).toBe(`space-of-${COMMUNITY.id}`);
+    expect(seen.b).toBe(`space-of-${OTHER_COMMUNITY.id}`);
+    expect(calls("get", "/public/community/spaces")).toHaveLength(2);
+  });
+
+  it("resolves a slug to the community's id before any member read goes out", async () => {
+    installAdapter([detailRoute(() => ({})), get("/public/community/spaces", () => [])]);
+    const Wrapper = wrapper({ community: null });
+    const { result } = renderHook(
+      () => {
+        const context = useCommunityContext();
+        const spaces = useCommunitySpaces();
+        return { context, spaces };
+      },
+      {
+        wrapper: ({ children }) => (
+          <Wrapper>
+            <ProviderBySlug>{children}</ProviderBySlug>
+          </Wrapper>
+        ),
+      },
+    );
+    expect(result.current.context.slug).toBe("fan-club");
+    await waitFor(() => expect(result.current.context.communityId).toBe(COMMUNITY.id));
+    await waitFor(() => expect(result.current.spaces.isSuccess).toBe(true));
+    expect(calls("get", "/public/community/spaces")[0].params).toMatchObject({ communityId: COMMUNITY.id });
+  });
+
+  it("a collection that is not in this community reads as not found, not as a crash", async () => {
+    installAdapter([
+      get(/^\/public\/post-collections\//, () => {
+        throw { status: 404 };
+      }),
+    ]);
+    const { result } = renderHook(() => useGetPostCollection("col-elsewhere"), { wrapper: wrapper() });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.data).toBeNull();
+  });
+});
+
+function ProviderBySlug({ children }: { children: ReactNode }) {
+  return <CommunityProvider community="fan-club">{children}</CommunityProvider>;
+}

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);
+  });
+});