@tribe-nest/forge 3.59.0 → 3.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.59.0",
+  "version": "3.60.0",
   "publishConfig": {
     "access": "public"
   },

package/src/_tests/testCommunity.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import { CommunityProvider } from "../contexts/CommunityContext";
+import type { PublicCommunity } from "../data/queries/useCommunities";
+
+/**
+ * A community for specs. Member-content hooks throw outside a
+ * `<CommunityProvider>`, so a spec that renders one wraps it in `InCommunity`.
+ * `initialData` makes the id known on the first render, with no request.
+ */
+export const TEST_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 function InCommunity({ children, community = TEST_COMMUNITY }: { children: ReactNode; community?: PublicCommunity }) {
+  return (
+    <CommunityProvider community={community.slug} initialData={community}>
+      {children}
+    </CommunityProvider>
+  );
+}

package/src/contexts/CommunityContext.tsx

@@ -0,0 +1,192 @@
+"use client";
+import { useContext, useEffect, useMemo, type ReactNode } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { createSharedContext } from "../runtime/registry";
+import { useForge } from "../provider/ForgeProvider";
+import {
+  communitiesKeys,
+  usePublicCommunity,
+  useViewerAccountId,
+  type CommunityDetail,
+  type PublicCommunity,
+} from "../data/queries/useCommunities";
+
+/**
+ * Which community the surrounding UI is about.
+ *
+ * A profile can run several communities, each fully isolated (members, tiers,
+ * feed, spaces, collections, chat, calls, identity). So every member-content
+ * hook has to be told WHICH one, and it is told by this provider rather than by
+ * an argument threaded through every component: the hosted pages fill it from
+ * the `$slug` in the URL, and a creator's own page wraps a section in it.
+ *
+ *     <CommunityProvider community="fan-club">
+ *       <CommunityHome />
+ *     </CommunityProvider>
+ *
+ * A member-content hook used outside it THROWS. That is deliberate: guessing
+ * ("the first community", "any membership on the profile") is exactly the
+ * cross-community leak this model exists to prevent, and a developer error at
+ * build time is far cheaper than a fan reading the wrong community's feed.
+ *
+ * The context is shared across bundles (`createSharedContext`), so a provider a
+ * site mounts is the one the hosted pages bundle reads, and vice versa.
+ */
+
+export interface CommunityContextValue {
+  /** The community, once loaded. */
+  community: PublicCommunity | undefined;
+  /** Its id. Known before the community loads when the provider was given an id. */
+  communityId: string | undefined;
+  /** Its slug. Known before the community loads when the provider was given a slug. */
+  slug: string | undefined;
+  isLoading: boolean;
+  /** True when the server answered that no such live community exists. */
+  notFound: boolean;
+  /** What the provider was given: a slug or an id. */
+  ref: string;
+}
+
+const CommunityContext = createSharedContext<CommunityContextValue | null>("community", null);
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** True when a community reference is an id rather than a slug. */
+export function isCommunityId(ref: string): boolean {
+  return UUID_RE.test(ref);
+}
+
+export interface CommunityProviderProps {
+  /** The community's slug (as in `/i/communities/<slug>`) or its id. */
+  community: string;
+  /**
+   * The community when the host already has it (SSR, a list it came from).
+   * Seeds the cache so nothing below waits on a request. Optional.
+   */
+  initialData?: PublicCommunity;
+  children: ReactNode;
+}
+
+/**
+ * Supplies one community to every hook and component below it. See the file
+ * docblock for why a member-content hook refuses to run without one.
+ */
+export function CommunityProvider({ community: ref, initialData, children }: CommunityProviderProps) {
+  const { profileId } = useForge();
+  const queryClient = useQueryClient();
+  const accountId = useViewerAccountId();
+
+  // Seed the detail cache from `initialData` so `community` is there on the
+  // first render. The seed carries no tiers or viewer, so the real read still
+  // runs and replaces it.
+  useEffect(() => {
+    if (!initialData || !profileId) return;
+    const key = communitiesKeys.detail(profileId, ref, {}, accountId);
+    if (!queryClient.getQueryData(key)) {
+      queryClient.setQueryData<CommunityDetail>(
+        key,
+        { community: initialData, tiers: [], viewer: EMPTY_VIEWER, invite: null },
+        { updatedAt: 0 },
+      );
+    }
+  }, [initialData, profileId, ref, accountId, queryClient]);
+
+  const detail = usePublicCommunity(ref);
+  const community = detail.data?.community ?? initialData;
+  const byId = isCommunityId(ref);
+
+  const value = useMemo<CommunityContextValue>(
+    () => ({
+      community,
+      communityId: community?.id ?? (byId ? ref : undefined),
+      slug: community?.slug ?? (byId ? undefined : ref),
+      isLoading: !community && detail.isLoading,
+      notFound: !community && (detail.error as { response?: { status?: number } } | null)?.response?.status === 404,
+      ref,
+    }),
+    [community, byId, ref, detail.isLoading, detail.error],
+  );
+
+  return <CommunityContext.Provider value={value}>{children}</CommunityContext.Provider>;
+}
+
+const EMPTY_VIEWER = {
+  state: "none" as const,
+  membership: null,
+  application: null,
+  upgradeTiers: [],
+  canInteract: false,
+};
+
+/** Thrown by any member-content hook used outside `<CommunityProvider>`. */
+export class MissingCommunityProviderError extends Error {
+  constructor(hookName: string) {
+    super(
+      `${hookName} must be used inside <CommunityProvider community="<slug or id>">. ` +
+        "A creator can run several communities, so Forge will not guess which one this is. " +
+        "Wrap the page (or section) in <CommunityProvider>, or pass `community` to the component that accepts it.",
+    );
+    this.name = "MissingCommunityProviderError";
+  }
+}
+
+/**
+ * The surrounding community. Throws outside `<CommunityProvider>`.
+ *
+ * `communityId` can be undefined for a moment while a slug resolves, so data
+ * hooks gate on it rather than on the provider alone.
+ */
+export function useCommunityContext(): CommunityContextValue {
+  const ctx = useContext(CommunityContext);
+  if (!ctx) throw new MissingCommunityProviderError("useCommunityContext()");
+  return ctx;
+}
+
+/** The surrounding community, or null outside a provider. For components that work either way. */
+export function useOptionalCommunityContext(): CommunityContextValue | null {
+  return useContext(CommunityContext);
+}
+
+/**
+ * What a member-content data hook needs: the API client, the profile and the
+ * community. Throws `MissingCommunityProviderError` naming the calling hook.
+ */
+export function useCommunityScope(hookName: string) {
+  const ctx = useContext(CommunityContext);
+  if (!ctx) throw new MissingCommunityProviderError(hookName);
+  const { client, profileId } = useForge();
+  return { client, profileId, communityId: ctx.communityId, slug: ctx.slug };
+}
+
+// ---- The upgrade sheet opener ----------------------------------------------------
+
+/**
+ * Lets any locked item inside a community ("Unlock with {tier}") open the
+ * community's ONE upgrade sheet, wherever it is drawn. `CommunityHome` provides
+ * it; a custom member area can provide its own. Absent, locked items fall back
+ * to a link to the community's About page with the tier preselected.
+ */
+export interface CommunityUpgradeOpener {
+  /** Open the upgrade sheet, optionally preselecting the tier that unlocks the item. */
+  openUpgrade: (tierId?: string | null) => void;
+}
+
+const CommunityUpgradeOpenerContext = createSharedContext<CommunityUpgradeOpener | null>(
+  "communityUpgradeOpener",
+  null,
+);
+
+export function CommunityUpgradeOpenerProvider({
+  value,
+  children,
+}: {
+  value: CommunityUpgradeOpener;
+  children: ReactNode;
+}) {
+  return <CommunityUpgradeOpenerContext.Provider value={value}>{children}</CommunityUpgradeOpenerContext.Provider>;
+}
+
+/** The surrounding upgrade opener, or null when no community home provides one. */
+export function useCommunityUpgradeOpener(): CommunityUpgradeOpener | null {
+  return useContext(CommunityUpgradeOpenerContext);
+}

package/src/data/queries/useChat.ts

@@ -2,6 +2,7 @@ import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tansta
 import { useEffect, useRef, useState } from "react";
 import { io, type Socket } from "socket.io-client";
 import { useForge } from "../../provider/ForgeProvider";
+import { useCommunityScope } from "../../contexts/CommunityContext";
 import { getForgeWebSocketUrl } from "../../client/createForgeClient";
 import { PUBLIC_ACCESS_TOKEN_KEY } from "../../contexts/PublicAuthContext";
 
@@ -67,83 +68,85 @@ export interface ChatMessagesPage {
 // Query keys are exported so the realtime layer (and creators) can patch the
 // same caches the data hooks populate.
 export const chatKeys = {
-  channels: (profileId?: string) => ["public-chat-channels", profileId] as const,
+  // Channel lists, unread counts, DMs and the directory are per COMMUNITY: a
+  // profile runs several, and each has its own channels and members.
+  channels: (communityId?: string) => ["public-chat-channels", communityId] as const,
   messages: (channelId?: string) => ["public-chat-messages", channelId] as const,
   pinned: (channelId?: string) => ["public-chat-pinned", channelId] as const,
-  unread: (profileId?: string) => ["public-chat-unread-counts", profileId] as const,
-  dm: (profileId?: string) => ["public-chat-dm", profileId] as const,
+  unread: (communityId?: string) => ["public-chat-unread-counts", communityId] as const,
+  dm: (communityId?: string) => ["public-chat-dm", communityId] as const,
   replies: (parentMessageId?: string) => ["public-chat-replies", parentMessageId] as const,
-  memberDirectory: (profileId?: string) => ["public-chat-member-directory", profileId] as const,
+  memberDirectory: (communityId?: string) => ["public-chat-member-directory", communityId] as const,
 };
 
 // ── Data hooks ───────────────────────────────────────────────────────────────
 
 /** Channels visible to the current member (GET /public/chat/channels). */
 export function useChatChannels() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatChannels()");
   return useQuery<ChatChannel[]>({
-    queryKey: chatKeys.channels(profileId),
+    queryKey: chatKeys.channels(communityId),
     queryFn: async () => {
-      const res = await client.get("/public/chat/channels", { params: { profileId } });
+      const res = await client.get("/public/chat/channels", { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
   });
 }
 
 /** Paginated messages for a channel, newest first (GET /public/chat/channels/:id/messages). */
 export function useChatMessages(channelId?: string, limit = 50) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatMessages()");
   return useInfiniteQuery<ChatMessagesPage>({
     queryKey: chatKeys.messages(channelId),
     queryFn: async ({ pageParam = 1 }) => {
       const res = await client.get(`/public/chat/channels/${channelId}/messages`, {
-        params: { profileId, page: pageParam, limit },
+        params: { profileId, communityId, page: pageParam, limit },
       });
       return res.data;
     },
     initialPageParam: 1,
     getNextPageParam: (lastPage) =>
       lastPage.page * lastPage.limit < lastPage.total ? lastPage.page + 1 : undefined,
-    enabled: !!channelId && !!client && !!profileId,
+    enabled: !!channelId && !!client && !!profileId && !!communityId,
   });
 }
 
 /** Pinned messages for a channel (GET /public/chat/channels/:id/pinned). */
 export function useChatPinnedMessages(channelId?: string) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatPinnedMessages()");
   return useQuery<ChatMessage[]>({
     queryKey: chatKeys.pinned(channelId),
     queryFn: async () => {
-      const res = await client.get(`/public/chat/channels/${channelId}/pinned`, { params: { profileId } });
+      const res = await client.get(`/public/chat/channels/${channelId}/pinned`, { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!channelId && !!client && !!profileId,
+    enabled: !!channelId && !!client && !!profileId && !!communityId,
   });
 }
 
 /** Per-channel unread counts, polled every 30s (GET /public/chat/unread-counts). */
 export function useChatUnreadCounts() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatUnreadCounts()");
   return useQuery<ChatUnreadCount[]>({
-    queryKey: chatKeys.unread(profileId),
+    queryKey: chatKeys.unread(communityId),
     queryFn: async () => {
-      const res = await client.get("/public/chat/unread-counts", { params: { profileId } });
+      const res = await client.get("/public/chat/unread-counts", { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
     refetchInterval: 30000,
   });
 }
 
 /** Mark messages as read (POST /public/chat/read-receipts); invalidates unread counts. */
 export function useMarkChatRead() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useMarkChatRead()");
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (messageIds: string[]) => {
       if (messageIds.length === 0) return;
-      await client.post("/public/chat/read-receipts", { profileId, messageIds });
+      await client.post("/public/chat/read-receipts", { profileId, communityId, messageIds });
     },
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ["public-chat-unread-counts"] });
@@ -153,7 +156,7 @@ export function useMarkChatRead() {
 
 /** Send a message over REST (POST /public/chat/messages). Realtime path uses the socket. */
 export function useSendChatMessage() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useSendChatMessage()");
   return useMutation({
     mutationFn: async (input: {
       channelId: string;
@@ -161,7 +164,7 @@ export function useSendChatMessage() {
       attachments?: ChatAttachment[];
       parentMessageId?: string;
     }) => {
-      const res = await client.post("/public/chat/messages", { profileId, ...input });
+      const res = await client.post("/public/chat/messages", { profileId, communityId, ...input });
       return res.data as ChatMessage;
     },
   });
@@ -169,69 +172,69 @@ export function useSendChatMessage() {
 
 /** Paginated replies for a thread parent (GET /public/chat/messages/:id/replies), oldest first. */
 export function useChatMessageReplies(parentMessageId?: string, limit = 50) {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatMessageReplies()");
   return useInfiniteQuery<ChatMessagesPage>({
     queryKey: chatKeys.replies(parentMessageId),
     queryFn: async ({ pageParam = 1 }) => {
       const res = await client.get(`/public/chat/messages/${parentMessageId}/replies`, {
-        params: { profileId, page: pageParam, limit },
+        params: { profileId, communityId, page: pageParam, limit },
       });
       return res.data;
     },
     initialPageParam: 1,
     getNextPageParam: (lastPage) =>
       lastPage.page * lastPage.limit < lastPage.total ? lastPage.page + 1 : undefined,
-    enabled: !!parentMessageId && !!client && !!profileId,
+    enabled: !!parentMessageId && !!client && !!profileId && !!communityId,
   });
 }
 
 /** Same-tier members the current member may start a DM with (GET /public/chat/dm/directory). */
 export function useChatMemberDirectory() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatMemberDirectory()");
   return useQuery<ChatDirectoryMember[]>({
-    queryKey: chatKeys.memberDirectory(profileId),
+    queryKey: chatKeys.memberDirectory(communityId),
     queryFn: async () => {
-      const res = await client.get("/public/chat/dm/directory", { params: { profileId } });
+      const res = await client.get("/public/chat/dm/directory", { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
   });
 }
 
 /** Open/create a DM with another member (POST /public/chat/dm/member). */
 export function useCreateMemberDm() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCreateMemberDm()");
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (targetAccountId: string) => {
-      const res = await client.post("/public/chat/dm/member", { profileId, targetAccountId });
+      const res = await client.post("/public/chat/dm/member", { profileId, communityId, targetAccountId });
       return res.data as ChatChannel;
     },
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: chatKeys.channels(profileId) });
+      queryClient.invalidateQueries({ queryKey: chatKeys.channels(communityId) });
     },
   });
 }
 
 /** The current member's DM channel, if any (GET /public/chat/dm). */
 export function useChatDm() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useChatDm()");
   return useQuery<ChatChannel | null>({
-    queryKey: chatKeys.dm(profileId),
+    queryKey: chatKeys.dm(communityId),
     queryFn: async () => {
-      const res = await client.get("/public/chat/dm", { params: { profileId } });
+      const res = await client.get("/public/chat/dm", { params: { profileId, communityId } });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!communityId && !!client,
   });
 }
 
 /** Open/create the member's DM channel (POST /public/chat/dm). */
 export function useCreateChatDm() {
-  const { client, profileId } = useForge();
+  const { client, profileId, communityId } = useCommunityScope("useCreateChatDm()");
   return useMutation({
     mutationFn: async () => {
-      const res = await client.post("/public/chat/dm", { profileId });
+      const res = await client.post("/public/chat/dm", { profileId, communityId });
       return res.data as ChatChannel;
     },
   });
@@ -259,7 +262,7 @@ export function useChatSocket(enabled: boolean) {
     const next = io(getForgeWebSocketUrl(apiUrl), { auth: { token }, transports: ["websocket"] });
     socketRef.current = next;
     setSocket(next);
-    // Intentionally not disconnecting on unmount — mirrors the client app, where the
+    // Intentionally not disconnecting on unmount: mirrors the client app, where the
     // chat socket persists across channel selection. Callers manage room join/leave.
   }, [enabled, apiUrl]);