@tribe-nest/forge 1.13.0

package/src/data/queries/useCommunity.ts

@@ -0,0 +1,794 @@
+import { useInfiniteQuery, useMutation, useQuery, useQueryClient, type QueryClient } from "@tanstack/react-query";
+import { useForge } from "../../provider/ForgeProvider";
+import { useChatSocket } from "./useChat";
+
+// ── Types (mirror apps/backend/src/routes/public/community + models) ─────────
+
+export type CommunitySpaceType = "feed" | "forum";
+
+export interface CommunitySpace {
+  id: string;
+  profileId: string;
+  name: string;
+  slug: string | null;
+  description: string | null;
+  type: CommunitySpaceType;
+  courseId: string | null;
+  order: number;
+  archivedAt: string | null;
+  createdAt: string;
+  /** Gating tiers — empty array = open to every member. */
+  tiers: { id: string; name: string }[];
+  /** Only present on the member list query. */
+  postCount?: number | null;
+  /** Joined members (roster) count. Tiers govern access; join governs belonging. */
+  memberCount?: number | null;
+  /** Whether the current member has joined this space (new-post notifications). */
+  isJoined?: boolean;
+}
+
+/** One roster row (GET /public/community/spaces/:id/members). */
+export interface CommunitySpaceMemberEntry {
+  accountId: string;
+  joinedAt: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+  level: number | null;
+  role: string | null;
+  firstName: string | null;
+  lastName: string | null;
+}
+
+export interface CommunitySpaceMembersPage {
+  data: CommunitySpaceMemberEntry[];
+  total: number;
+  page: number;
+  pageSize: number;
+  hasNextPage: boolean;
+}
+
+export interface CommunityAuthor {
+  accountId: string;
+  firstName: string | null;
+  lastName: string | null;
+  displayName: string | null;
+  avatarUrl: string | null;
+  level: number | null;
+  role: string | null;
+}
+
+export interface CommunityMediaItem {
+  id: string;
+  url: string;
+  type: string;
+  size: number | null;
+  name: string | null;
+  width: number | null;
+  height: number | null;
+  order: number;
+}
+
+/** Per-emoji summary row for one entity (reactions are toggled per emoji). */
+export interface ReactionSummary {
+  entityId: string;
+  emoji: string;
+  count: number;
+  reactedByMe: boolean;
+}
+
+export interface CommunityPost {
+  id: string;
+  profileId: string;
+  spaceId: string;
+  authorAccountId: string;
+  title: string | null;
+  /** Lexical editor state (JSON). Render with <CommunityRichText/>. */
+  body: unknown;
+  bodyText: string | null;
+  isPinned: boolean;
+  isLocked: boolean;
+  replyCount: number;
+  reactionCount: number;
+  lastActivityAt: string | null;
+  createdAt: string;
+  author: CommunityAuthor | null;
+  media: CommunityMediaItem[];
+  reactions?: ReactionSummary[];
+}
+
+export interface CommunityReply {
+  id: string;
+  postId: string;
+  parentReplyId: string | null;
+  authorAccountId: string;
+  body: unknown;
+  bodyText: string | null;
+  reactionCount: number;
+  createdAt: string;
+  author: CommunityAuthor | null;
+  media: CommunityMediaItem[];
+  reactions?: ReactionSummary[];
+}
+
+/** Attachment input shape the community create endpoints accept. */
+export interface CommunityAttachmentInput {
+  url: string;
+  type: "image" | "video" | "audio" | "document" | "other";
+  size: number;
+  name?: string;
+  width?: number;
+  height?: number;
+}
+
+export interface CommunityMemberProfile {
+  id: string;
+  profileId: string;
+  accountId: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+  bio: string | null;
+  points: number;
+  level: number;
+  role: string;
+  digestCadence: CommunityDigestCadence;
+  lastActiveAt: string | null;
+  mutedUntil: string | null;
+  createdAt: string;
+  firstName: string | null;
+  lastName: string | null;
+  recentPosts?: {
+    id: string;
+    spaceId: string;
+    title: string | null;
+    bodyText: string | null;
+    replyCount: number;
+    reactionCount: number;
+    createdAt: string;
+  }[];
+  recentReplies?: {
+    id: string;
+    postId: string;
+    spaceId: string;
+    bodyText: string | null;
+    reactionCount: number;
+    createdAt: string;
+    postTitle: string | null;
+  }[];
+}
+
+export type CommunityDigestCadence = "off" | "inapp_only" | "hourly" | "daily";
+
+export type CommunityNotificationType = "mention" | "reply" | "reaction" | "new_post" | "mod";
+
+export interface CommunityNotificationItem {
+  id: string;
+  profileId: string;
+  accountId: string;
+  type: CommunityNotificationType | string;
+  entityType: "community_post" | "community_reply" | string | null;
+  entityId: string | null;
+  readAt: string | null;
+  createdAt: string;
+}
+
+export interface CommunityLeaderboardEntry {
+  accountId: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+  points: number;
+  level: number;
+  firstName: string | null;
+  lastName: string | null;
+}
+
+export interface CommunityPostsPage {
+  data: CommunityPost[];
+  total: number;
+  page: number;
+  pageSize: number;
+  hasNextPage: boolean;
+  nextPage: number | null;
+}
+
+export interface CommunityRepliesPage {
+  data: CommunityReply[];
+  total: number;
+  page: number;
+  pageSize: number;
+  hasNextPage: boolean;
+}
+
+export interface CommunitySearchResults {
+  posts: {
+    id: string;
+    spaceId: string;
+    title: string | null;
+    bodyText: string | null;
+    authorAccountId: string;
+    replyCount: number;
+    reactionCount: number;
+    createdAt: string;
+    rank: number;
+  }[];
+  replies: {
+    id: string;
+    postId: string;
+    spaceId: string;
+    postTitle: string | null;
+    bodyText: string | null;
+    authorAccountId: string;
+    reactionCount: number;
+    createdAt: string;
+    rank: number;
+  }[];
+}
+
+export type CommunityLeaderboardPeriod = "all" | "7" | "30";
+
+/** Display name resolution used everywhere a member is rendered. */
+export function communityMemberName(
+  m: { displayName?: string | null; firstName?: string | null; lastName?: string | null } | null | undefined,
+): string {
+  if (!m) return "Member";
+  return m.displayName || `${m.firstName ?? ""} ${m.lastName ?? ""}`.trim() || "Member";
+}
+
+// Query keys are exported so the realtime layer (and creators) can patch the
+// same caches the data hooks populate — mirrors chatKeys in useChat.ts.
+export const communityKeys = {
+  spaces: (profileId?: string) => ["public-community-spaces", profileId] as const,
+  spaceMembers: (spaceId?: string) => ["public-community-space-members", spaceId] as const,
+  posts: (spaceId?: string) => ["public-community-posts", spaceId] as const,
+  post: (postId?: string) => ["public-community-post", postId] as const,
+  replies: (postId?: string) => ["public-community-replies", postId] as const,
+  myProfile: (profileId?: string) => ["public-community-my-profile", profileId] as const,
+  member: (profileId?: string, accountId?: string) => ["public-community-member", profileId, accountId] as const,
+  notifications: (profileId?: string, unreadOnly?: boolean) =>
+    ["public-community-notifications", profileId, unreadOnly] as const,
+  unread: (profileId?: string) => ["public-community-unread", profileId] as const,
+  leaderboard: (profileId?: string, period?: string) => ["public-community-leaderboard", profileId, period] as const,
+  search: (profileId?: string, q?: string, spaceId?: string) =>
+    ["public-community-search", profileId, q, spaceId ?? null] as const,
+};
+
+// ── Data hooks ───────────────────────────────────────────────────────────────
+
+/** Spaces the current member can access (GET /public/community/spaces). */
+export function useCommunitySpaces() {
+  const { client, profileId } = useForge();
+  return useQuery<CommunitySpace[]>({
+    queryKey: communityKeys.spaces(profileId),
+    queryFn: async () => {
+      const res = await client.get("/public/community/spaces", { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+export interface SpaceMembershipResult {
+  isJoined: boolean;
+  memberCount: number;
+}
+
+/** Patch one space's isJoined/memberCount inside the spaces list cache. */
+export function setSpaceMembership(
+  queryClient: QueryClient,
+  profileId: string | undefined,
+  spaceId: string,
+  membership: SpaceMembershipResult,
+) {
+  queryClient.setQueryData(communityKeys.spaces(profileId), (old: CommunitySpace[] | undefined) =>
+    old?.map((s) => (s.id === spaceId ? { ...s, ...membership } : s)),
+  );
+}
+
+/**
+ * Join a space (POST /public/community/spaces/:id/join). Tiers still govern
+ * who can access a space — joining opts into new-post notifications/digests
+ * and the roster. Interacting (post/reply/react) auto-joins server-side.
+ */
+export function useJoinCommunitySpace() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (spaceId: string) => {
+      const res = await client.post(`/public/community/spaces/${spaceId}/join`, { profileId });
+      return { ...(res.data as SpaceMembershipResult), spaceId };
+    },
+    onSuccess: ({ spaceId, ...membership }) => {
+      setSpaceMembership(queryClient, profileId, spaceId, membership);
+      queryClient.invalidateQueries({ queryKey: communityKeys.spaceMembers(spaceId) });
+    },
+  });
+}
+
+/** Leave a space (POST /public/community/spaces/:id/leave). Always explicit. */
+export function useLeaveCommunitySpace() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (spaceId: string) => {
+      const res = await client.post(`/public/community/spaces/${spaceId}/leave`, { profileId });
+      return { ...(res.data as SpaceMembershipResult), spaceId };
+    },
+    onSuccess: ({ spaceId, ...membership }) => {
+      setSpaceMembership(queryClient, profileId, spaceId, membership);
+      queryClient.invalidateQueries({ queryKey: communityKeys.spaceMembers(spaceId) });
+    },
+  });
+}
+
+/** Paginated joined-member roster for a space. */
+export function useCommunitySpaceMembers(spaceId?: string, limit = 50) {
+  const { client, profileId } = useForge();
+  return useInfiniteQuery<CommunitySpaceMembersPage>({
+    queryKey: communityKeys.spaceMembers(spaceId),
+    queryFn: async ({ pageParam = 1 }) => {
+      const res = await client.get(`/public/community/spaces/${spaceId}/members`, {
+        params: { profileId, page: pageParam, limit },
+      });
+      return res.data;
+    },
+    initialPageParam: 1,
+    getNextPageParam: (lastPage) => (lastPage.hasNextPage ? lastPage.page + 1 : undefined),
+    enabled: !!spaceId && !!client && !!profileId,
+  });
+}
+
+/** Paginated posts for a space, pinned first then most recent activity. */
+export function useCommunitySpacePosts(spaceId?: string, limit = 20) {
+  const { client, profileId } = useForge();
+  return useInfiniteQuery<CommunityPostsPage>({
+    queryKey: communityKeys.posts(spaceId),
+    queryFn: async ({ pageParam = 1 }) => {
+      const res = await client.get(`/public/community/spaces/${spaceId}/posts`, {
+        params: { profileId, page: pageParam, limit },
+      });
+      return res.data;
+    },
+    initialPageParam: 1,
+    getNextPageParam: (lastPage) => (lastPage.hasNextPage ? lastPage.page + 1 : undefined),
+    enabled: !!spaceId && !!client && !!profileId,
+  });
+}
+
+/**
+ * A single post (GET /public/community/posts/:id). The endpoint also returns a
+ * replies page — we request the minimum (limit=1) and let the dedicated
+ * replies hook own pagination, so both caches stay simple.
+ */
+export function useCommunityPost(postId?: string) {
+  const { client, profileId } = useForge();
+  return useQuery<CommunityPost>({
+    queryKey: communityKeys.post(postId),
+    queryFn: async () => {
+      const res = await client.get(`/public/community/posts/${postId}`, {
+        params: { profileId, page: 1, limit: 1 },
+      });
+      return res.data.post;
+    },
+    enabled: !!postId && !!client && !!profileId,
+  });
+}
+
+/**
+ * Flat, chronological reply pages for a post (GET /public/community/posts/:id/replies).
+ * `parentReplyId` is included on every row — assemble the tree with
+ * `buildReplyTree` (data nesting is unlimited; the 3-level display cap is a UI concern).
+ */
+export function useCommunityReplies(postId?: string, limit = 100) {
+  const { client, profileId } = useForge();
+  return useInfiniteQuery<CommunityRepliesPage>({
+    queryKey: communityKeys.replies(postId),
+    queryFn: async ({ pageParam = 1 }) => {
+      const res = await client.get(`/public/community/posts/${postId}/replies`, {
+        params: { profileId, page: pageParam, limit },
+      });
+      return res.data;
+    },
+    initialPageParam: 1,
+    getNextPageParam: (lastPage) => (lastPage.hasNextPage ? lastPage.page + 1 : undefined),
+    enabled: !!postId && !!client && !!profileId,
+  });
+}
+
+export interface CreateCommunityPostInput {
+  title?: string;
+  /** Lexical editor state — build one from plain text with `buildLexicalState`. */
+  body: unknown;
+  attachments?: CommunityAttachmentInput[];
+  mentionedAccountIds?: string[];
+}
+
+/** Create a post in a space (POST /public/community/spaces/:id/posts). */
+export function useCreateCommunityPost(spaceId?: string) {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: CreateCommunityPostInput) => {
+      const res = await client.post(`/public/community/spaces/${spaceId}/posts`, { profileId, ...input });
+      return res.data as CommunityPost;
+    },
+    onSuccess: (post) => {
+      prependPostToFeed(queryClient, spaceId, post);
+      queryClient.invalidateQueries({ queryKey: communityKeys.spaces(profileId) });
+    },
+  });
+}
+
+export interface CreateCommunityReplyInput {
+  body: unknown;
+  parentReplyId?: string;
+  attachments?: CommunityAttachmentInput[];
+  mentionedAccountIds?: string[];
+}
+
+/** Reply to a post — optionally nested under another reply. */
+export function useCreateCommunityReply(postId?: string) {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: CreateCommunityReplyInput) => {
+      const res = await client.post(`/public/community/posts/${postId}/replies`, { profileId, ...input });
+      return res.data as CommunityReply;
+    },
+    onSuccess: (reply) => {
+      appendReplyToThread(queryClient, postId, reply);
+      // Replying implicitly joins the post's space server-side.
+      queryClient.invalidateQueries({ queryKey: communityKeys.spaces(profileId) });
+    },
+  });
+}
+
+export type ReactableEntityType = "community_post" | "community_reply" | "chat_message";
+
+export interface ToggleReactionResult {
+  reacted: boolean;
+  emoji: string;
+  /** Authoritative per-emoji summary for the entity after the toggle. */
+  reactions: ReactionSummary[];
+}
+
+/** Toggle an emoji reaction (POST /public/community/:entityType/:id/react). */
+export function useToggleCommunityReaction() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: {
+      entityType: ReactableEntityType;
+      entityId: string;
+      emoji: string;
+      /** Cache hints so the summary lands in the right query data. */
+      spaceId?: string;
+      postId?: string;
+    }) => {
+      const res = await client.post(`/public/community/${input.entityType}/${input.entityId}/react`, {
+        profileId,
+        emoji: input.emoji,
+      });
+      return { ...(res.data as ToggleReactionResult), input };
+    },
+    onSuccess: ({ reactions, input }) => {
+      setReactionSummary(queryClient, input, reactions);
+      // Adding a reaction implicitly joins the space server-side.
+      queryClient.invalidateQueries({ queryKey: communityKeys.spaces(profileId) });
+    },
+  });
+}
+
+/** Report a post or reply to the moderators. */
+export function useReportCommunityContent() {
+  const { client, profileId } = useForge();
+  return useMutation({
+    mutationFn: async (input: {
+      entityId: string;
+      entityType: "community_post" | "community_reply";
+      reason?: string;
+    }) => {
+      const res = await client.post(`/public/community/posts/${input.entityId}/report`, {
+        profileId,
+        entityType: input.entityType,
+        reason: input.reason,
+      });
+      return res.data;
+    },
+  });
+}
+
+/** The member's own community profile — created on first read (GET /public/community/me). */
+export function useMyCommunityProfile(enabled = true) {
+  const { client, profileId } = useForge();
+  return useQuery<CommunityMemberProfile>({
+    queryKey: communityKeys.myProfile(profileId),
+    queryFn: async () => {
+      const res = await client.get("/public/community/me", { params: { profileId } });
+      return res.data;
+    },
+    enabled: enabled && !!profileId && !!client,
+  });
+}
+
+/** Update display name / bio / avatar / digest cadence (PUT /public/community/me). */
+export function useUpdateMyCommunityProfile() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: {
+      displayName?: string | null;
+      bio?: string | null;
+      avatarUrl?: string | null;
+      digestCadence?: CommunityDigestCadence;
+    }) => {
+      const res = await client.put("/public/community/me", { profileId, ...input });
+      return res.data as CommunityMemberProfile;
+    },
+    onSuccess: (profile) => {
+      queryClient.setQueryData(communityKeys.myProfile(profileId), profile);
+      queryClient.invalidateQueries({ queryKey: communityKeys.member(profileId, profile?.accountId) });
+    },
+  });
+}
+
+/** Another member's profile + recent activity (filtered to spaces you can read). */
+export function useCommunityMemberProfile(accountId?: string) {
+  const { client, profileId } = useForge();
+  return useQuery<CommunityMemberProfile>({
+    queryKey: communityKeys.member(profileId, accountId),
+    queryFn: async () => {
+      const res = await client.get(`/public/community/profile/${accountId}`, { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!accountId && !!profileId && !!client,
+  });
+}
+
+/** In-app inbox (GET /public/community/notifications). Returns { data, unreadCount }. */
+export function useCommunityNotifications({ unreadOnly = false, limit = 50 } = {}) {
+  const { client, profileId } = useForge();
+  return useQuery<{ data: CommunityNotificationItem[]; unreadCount: number }>({
+    queryKey: communityKeys.notifications(profileId, unreadOnly),
+    queryFn: async () => {
+      const res = await client.get("/public/community/notifications", {
+        params: { profileId, page: 1, limit, unreadOnly },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/** Unread count for the bell, polled every 30s (same cadence as chat unread counts). */
+export function useCommunityUnreadCount(enabled = true) {
+  const { client, profileId } = useForge();
+  return useQuery<number>({
+    queryKey: communityKeys.unread(profileId),
+    queryFn: async () => {
+      const res = await client.get("/public/community/notifications", {
+        params: { profileId, page: 1, limit: 1, unreadOnly: true },
+      });
+      return res.data.unreadCount as number;
+    },
+    enabled: enabled && !!profileId && !!client,
+    refetchInterval: 30000,
+  });
+}
+
+/** Mark notifications read — omit ids to mark ALL unread as read. */
+export function useMarkCommunityNotificationsRead() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (ids?: string[]) => {
+      await client.post("/public/community/notifications/mark-read", { profileId, ids });
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["public-community-notifications"] });
+      queryClient.invalidateQueries({ queryKey: communityKeys.unread(profileId) });
+    },
+  });
+}
+
+/** Points leaderboard (GET /public/community/leaderboard?period=all|7|30). */
+export function useCommunityLeaderboard(period: CommunityLeaderboardPeriod = "all", limit = 20) {
+  const { client, profileId } = useForge();
+  return useQuery<CommunityLeaderboardEntry[]>({
+    queryKey: communityKeys.leaderboard(profileId, period),
+    queryFn: async () => {
+      const res = await client.get("/public/community/leaderboard", { params: { profileId, period, limit } });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+  });
+}
+
+/**
+ * Member directory for @mention autocomplete. There is no dedicated public
+ * member-search endpoint yet, so this reads the all-time leaderboard at its max
+ * page size (100) — every community_profiles row ranked by points — and filters
+ * client-side.
+ */
+export function useCommunityMentionDirectory() {
+  const { client, profileId } = useForge();
+  return useQuery<CommunityLeaderboardEntry[]>({
+    queryKey: communityKeys.leaderboard(profileId, "mention-directory"),
+    queryFn: async () => {
+      const res = await client.get("/public/community/leaderboard", {
+        params: { profileId, period: "all", limit: 100 },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client,
+    staleTime: 60_000,
+  });
+}
+
+/**
+ * FTS over posts + replies (min 2 chars). Scopes to spaces the member can read;
+ * pass `spaceId` (a space uuid OR its per-profile slug) to scope to one space —
+ * scoping can only narrow, never widen, access. Backward-compatible: called with
+ * just a query it searches every accessible space (prior behavior).
+ */
+export function useCommunitySearch(q: string, spaceId?: string) {
+  const { client, profileId } = useForge();
+  const trimmed = q.trim();
+  return useQuery<CommunitySearchResults>({
+    queryKey: communityKeys.search(profileId, trimmed, spaceId),
+    queryFn: async () => {
+      const res = await client.get("/public/community/search", {
+        params: { profileId, q: trimmed, page: 1, limit: 20, ...(spaceId ? { spaceId } : {}) },
+      });
+      return res.data;
+    },
+    enabled: trimmed.length >= 2 && !!profileId && !!client,
+  });
+}
+
+// ── Realtime primitive ───────────────────────────────────────────────────────
+
+/**
+ * Community realtime rides the same Socket.io gateway as chat (one connection
+ * per site). Emits `communityJoinSpace` / `communityLeaveSpace`; receives a
+ * `message` envelope with `event` in {communityNewPost, communityNewReply,
+ * communityReaction}.
+ */
+export const useCommunitySocket = useChatSocket;
+
+export interface CommunityReactionEvent {
+  profileId: string;
+  spaceId: string | null;
+  entityType: ReactableEntityType;
+  entityId: string;
+  accountId: string;
+  emoji: string;
+  action: "added" | "removed";
+}
+
+// ── Cache patch helpers (shared by mutations + the realtime layer) ───────────
+
+/** Prepend a post to the first page of a space feed cache (dedupes by id). */
+export function prependPostToFeed(queryClient: QueryClient, spaceId: string | undefined, post: CommunityPost) {
+  if (!spaceId) return;
+  queryClient.setQueryData(communityKeys.posts(spaceId), (old: any) => {
+    if (!old?.pages?.length) return old;
+    const [first, ...rest] = old.pages;
+    if (first.data.some((p: CommunityPost) => p.id === post.id)) return old;
+    return {
+      ...old,
+      pages: [{ ...first, data: [{ reactions: [], ...post }, ...first.data], total: first.total + 1 }, ...rest],
+    };
+  });
+}
+
+/** Append a reply to the last page of a post's replies cache + bump counts. */
+export function appendReplyToThread(queryClient: QueryClient, postId: string | undefined, reply: CommunityReply) {
+  if (!postId) return;
+  queryClient.setQueryData(communityKeys.replies(postId), (old: any) => {
+    if (!old?.pages?.length) return old;
+    const pages = [...old.pages];
+    const lastIdx = pages.length - 1;
+    const last = pages[lastIdx];
+    if (pages.some((p: any) => p.data.some((r: CommunityReply) => r.id === reply.id))) return old;
+    pages[lastIdx] = { ...last, data: [...last.data, { reactions: [], ...reply }], total: last.total + 1 };
+    return { ...old, pages };
+  });
+  queryClient.setQueryData(communityKeys.post(postId), (old: CommunityPost | undefined) =>
+    old ? { ...old, replyCount: (old.replyCount ?? 0) + 1, lastActivityAt: reply.createdAt } : old,
+  );
+}
+
+/** Bump a post's replyCount inside a space feed cache (realtime new-reply event). */
+export function bumpFeedReplyCount(queryClient: QueryClient, spaceId: string | undefined, postId: string) {
+  if (!spaceId) return;
+  queryClient.setQueryData(communityKeys.posts(spaceId), (old: any) => {
+    if (!old?.pages?.length) return old;
+    return {
+      ...old,
+      pages: old.pages.map((page: any) => ({
+        ...page,
+        data: page.data.map((p: CommunityPost) =>
+          p.id === postId ? { ...p, replyCount: (p.replyCount ?? 0) + 1 } : p,
+        ),
+      })),
+    };
+  });
+}
+
+/** Replace an entity's reaction summary in every cache that renders it. */
+export function setReactionSummary(
+  queryClient: QueryClient,
+  target: { entityType: ReactableEntityType; entityId: string; spaceId?: string; postId?: string },
+  reactions: ReactionSummary[],
+) {
+  const patch = <T extends { id: string; reactions?: ReactionSummary[]; reactionCount?: number }>(item: T): T =>
+    item.id === target.entityId
+      ? { ...item, reactions, reactionCount: reactions.reduce((n, r) => n + r.count, 0) }
+      : item;
+
+  if (target.entityType === "community_post") {
+    if (target.spaceId) {
+      queryClient.setQueryData(communityKeys.posts(target.spaceId), (old: any) => {
+        if (!old?.pages?.length) return old;
+        return { ...old, pages: old.pages.map((page: any) => ({ ...page, data: page.data.map(patch) })) };
+      });
+    }
+    queryClient.setQueryData(communityKeys.post(target.entityId), (old: CommunityPost | undefined) =>
+      old ? patch(old) : old,
+    );
+  }
+
+  if (target.entityType === "community_reply" && target.postId) {
+    queryClient.setQueryData(communityKeys.replies(target.postId), (old: any) => {
+      if (!old?.pages?.length) return old;
+      return { ...old, pages: old.pages.map((page: any) => ({ ...page, data: page.data.map(patch) })) };
+    });
+  }
+}
+
+/**
+ * Apply a realtime reaction delta from another member. Our own toggles are
+ * already covered by the authoritative summary in the mutation response.
+ */
+export function applyReactionDelta(
+  queryClient: QueryClient,
+  event: CommunityReactionEvent,
+  { postId }: { postId?: string } = {},
+) {
+  const delta = event.action === "added" ? 1 : -1;
+
+  const patch = <T extends { id: string; reactions?: ReactionSummary[]; reactionCount?: number }>(item: T): T => {
+    if (item.id !== event.entityId) return item;
+    const existing = item.reactions ?? [];
+    const row = existing.find((r) => r.emoji === event.emoji);
+    let next: ReactionSummary[];
+    if (row) {
+      next = existing
+        .map((r) => (r.emoji === event.emoji ? { ...r, count: Math.max(0, r.count + delta) } : r))
+        .filter((r) => r.count > 0);
+    } else if (delta > 0) {
+      next = [...existing, { entityId: event.entityId, emoji: event.emoji, count: 1, reactedByMe: false }];
+    } else {
+      next = existing;
+    }
+    return { ...item, reactions: next, reactionCount: Math.max(0, (item.reactionCount ?? 0) + delta) };
+  };
+
+  if (event.entityType === "community_post") {
+    if (event.spaceId) {
+      queryClient.setQueryData(communityKeys.posts(event.spaceId), (old: any) => {
+        if (!old?.pages?.length) return old;
+        return { ...old, pages: old.pages.map((page: any) => ({ ...page, data: page.data.map(patch) })) };
+      });
+    }
+    queryClient.setQueryData(communityKeys.post(event.entityId), (old: CommunityPost | undefined) =>
+      old ? patch(old) : old,
+    );
+  }
+
+  if (event.entityType === "community_reply" && postId) {
+    queryClient.setQueryData(communityKeys.replies(postId), (old: any) => {
+      if (!old?.pages?.length) return old;
+      return { ...old, pages: old.pages.map((page: any) => ({ ...page, data: page.data.map(patch) })) };
+    });
+  }
+}