@tribe-nest/forge 3.60.0 → 3.63.0

package/src/data/queries/useCommunity.ts

@@ -1,6 +1,15 @@
-import { useInfiniteQuery, useMutation, useQuery, useQueryClient, type QueryClient } from "@tanstack/react-query";
+import { useEffect, useState } from "react";
+import {
+  keepPreviousData,
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type QueryClient,
+} from "@tanstack/react-query";
 import { useCommunityScope } from "../../contexts/CommunityContext";
 import { useChatSocket } from "./useChat";
+import type { CommunityAgentAuthor } from "./useCommunityAgent";
 
 // ── Types (mirror apps/backend/src/routes/public/community + models) ─────────
 
@@ -25,6 +34,14 @@ export interface CommunitySpace {
   memberCount?: number | null;
   /** Whether the current member has joined this space (new-post notifications). */
   isJoined?: boolean;
+  /** The level a member needs to read this space (1 = no level needed). */
+  minLevel?: number;
+  /**
+   * On the member list: the space is above the member's level. It is listed so
+   * they can see what their next level opens, but its feed stays closed (the
+   * server refuses it too).
+   */
+  levelLocked?: boolean;
 }
 
 /** One roster row (GET /public/community/spaces/:id/members). */
@@ -80,7 +97,8 @@ export interface CommunityPost {
   id: string;
   profileId: string;
   spaceId: string;
-  authorAccountId: string;
+  /** Null when the community AI wrote it (`agentAuthor` is then set). */
+  authorAccountId: string | null;
   title: string | null;
   /** Lexical editor state (JSON). Render with <CommunityRichText/>. */
   body: unknown;
@@ -92,22 +110,119 @@ export interface CommunityPost {
   lastActivityAt: string | null;
   createdAt: string;
   author: CommunityAuthor | null;
+  /** The community AI, when it wrote this post. `author` is then null. Absent on older servers. */
+  agentAuthor?: CommunityAgentAuthor | null;
   media: CommunityMediaItem[];
   reactions?: ReactionSummary[];
+  /**
+   * Moderation state. Only an author sees their own pending post; everyone else
+   * sees published posts only. Absent on rows from older servers: treat as published.
+   */
+  status?: CommunityContentStatus;
+  /** Why a post was held (`approval_new_member`, `approval_all`, `keyword:<word>`), or why it was rejected. */
+  moderationReason?: string | null;
+  /** Set in the cache when a moderator removes the post in this session, so the undo stays in place. */
+  archivedAt?: string | null;
+  /**
+   * The post's poll, as this viewer sees it, or null when it has none. Absent
+   * on a post that arrived over the realtime socket (see `CommunityPollView`).
+   */
+  poll?: CommunityPollView | null;
+  /**
+   * A card for the first link in the post, or null. Filled in the background
+   * shortly after the post is published, so a new post has none at first.
+   * Absent on rows from older servers.
+   */
+  linkPreview?: CommunityLinkPreview | null;
+}
+
+/** A link card on a post (community parity §6.2). */
+export interface CommunityLinkPreview {
+  url: string;
+  kind: "link" | "video";
+  provider: "youtube" | "vimeo" | "loom" | null;
+  siteName: string | null;
+  title: string | null;
+  description: string | null;
+  imageUrl: string | null;
+  /** The player address, for a video. Render only through `safeEmbedUrl`. */
+  embedUrl: string | null;
+}
+
+// ── Polls (community parity §6.1) ────────────────────────────────────────────
+
+/** When a poll's counts are shown: at once, once the member voted, or once it closed. */
+export type CommunityPollResultsVisibility = "always" | "after_vote" | "after_close";
+
+export const COMMUNITY_POLL_RESULTS_VISIBILITY: readonly CommunityPollResultsVisibility[] = [
+  "always",
+  "after_vote",
+  "after_close",
+];
+
+export interface CommunityPollOption {
+  id: string;
+  label: string;
+  position: number;
+  /** Null while this viewer may not see results yet. */
+  votes: number | null;
+}
+
+/** A post's poll as the viewer sees it. The post title is its question. */
+export interface CommunityPollView {
+  id: string;
+  multipleChoice: boolean;
+  closesAt: string | null;
+  closed: boolean;
+  resultsVisibility: CommunityPollResultsVisibility;
+  /** Whether this viewer may see the counts now. */
+  resultsVisible: boolean;
+  /** Distinct members who voted. Null while results are hidden. */
+  totalVoters: number | null;
+  /** The option ids this viewer chose. Empty when they have not voted. */
+  myVotes: string[];
+  options: CommunityPollOption[];
+}
+
+/** The poll part of the create-post body. The question travels as the post `title`. */
+export interface CommunityPollInput {
+  options: string[];
+  multipleChoice?: boolean;
+  /** ISO date, in the future. */
+  closesAt?: string | null;
+  resultsVisibility?: CommunityPollResultsVisibility;
+}
+
+/** Where a post or reply stands in moderation. */
+export type CommunityContentStatus = "published" | "pending" | "rejected";
+
+/** True when a post or reply is waiting for a moderator (only its author ever sees it). */
+export function isCommunityContentPending(
+  item: { status?: CommunityContentStatus | string | null } | null | undefined,
+): boolean {
+  return item?.status === "pending";
 }
 
 export interface CommunityReply {
   id: string;
   postId: string;
   parentReplyId: string | null;
-  authorAccountId: string;
+  /** Null when the community AI wrote it (`agentAuthor` is then set). */
+  authorAccountId: string | null;
   body: unknown;
   bodyText: string | null;
   reactionCount: number;
   createdAt: string;
   author: CommunityAuthor | null;
+  /** The community AI, when this reply is its answer. `author` is then null. */
+  agentAuthor?: CommunityAgentAuthor | null;
   media: CommunityMediaItem[];
   reactions?: ReactionSummary[];
+  /** See `CommunityPost.status`. */
+  status?: CommunityContentStatus;
+  moderationReason?: string | null;
+  /** Set in the cache when a moderator removes the reply in this session. */
+  archivedAt?: string | null;
 }
 
 /** Attachment input shape the community create endpoints accept. */
@@ -136,6 +251,20 @@ export interface CommunityMemberProfile {
   createdAt: string;
   firstName: string | null;
   lastName: string | null;
+  /**
+   * Only on `/me`: whether this member moderates THIS community (the moderator
+   * role here, or an owner/admin of the profile). Display only; the server
+   * checks again on every moderation call.
+   */
+  canModerate?: boolean;
+  /** Listed in the member directory (default true). */
+  showInDirectory?: boolean;
+  /** Counted on the member map, by country only (default false). */
+  showOnMap?: boolean;
+  /** Free text, display only. */
+  city?: string | null;
+  /** ISO 3166-1 alpha-2, or null. */
+  countryCode?: string | null;
   recentPosts?: {
     id: string;
     spaceId: string;
@@ -158,17 +287,30 @@ export interface CommunityMemberProfile {
 
 export type CommunityDigestCadence = "off" | "inapp_only" | "hourly" | "daily";
 
-export type CommunityNotificationType = "mention" | "reply" | "reaction" | "new_post" | "mod";
+export type CommunityNotificationType = "mention" | "reply" | "reaction" | "new_post" | "mod" | "level_up";
 
 export interface CommunityNotificationItem {
   id: string;
   profileId: string;
   accountId: string;
   type: CommunityNotificationType | string;
-  entityType: "community_post" | "community_reply" | string | null;
+  entityType: "community_post" | "community_reply" | "community" | string | null;
   entityId: string | null;
   readAt: string | null;
   createdAt: string;
+  /**
+   * Extra detail for some types. A `mod` notice about a post or reply carries
+   * the moderation outcome; a `mod` notice about the community (a mute) has none.
+   */
+  data?: CommunityNotificationData | null;
+}
+
+export interface CommunityNotificationData {
+  outcome?: "approved" | "rejected";
+  reason?: string | null;
+  /** On a `level_up`: the level the member reached. */
+  level?: number;
+  [key: string]: unknown;
 }
 
 export interface CommunityLeaderboardEntry {
@@ -251,6 +393,9 @@ export const communityKeys = {
   leaderboard: (communityId?: string, period?: string) => ["public-community-leaderboard", communityId, period] as const,
   search: (communityId?: string, q?: string, spaceId?: string) =>
     ["public-community-search", communityId, q, spaceId ?? null] as const,
+  moderationQueue: (communityId?: string) => ["public-community-moderation-queue", communityId] as const,
+  moderationLog: (communityId?: string, page?: number) =>
+    ["public-community-moderation-log", communityId, page] as const,
 };
 
 // ── Data hooks ───────────────────────────────────────────────────────────────
@@ -401,6 +546,8 @@ export interface CreateCommunityPostInput {
   body: unknown;
   attachments?: CommunityAttachmentInput[];
   mentionedAccountIds?: string[];
+  /** Attach a poll. `title` is then its question, and required. */
+  poll?: CommunityPollInput;
 }
 
 /** Create a post in a space (POST /public/community/spaces/:id/posts). */
@@ -419,6 +566,41 @@ export function useCreateCommunityPost(spaceId?: string) {
   });
 }
 
+export interface VoteCommunityPollInput {
+  postId: string;
+  /**
+   * The member's WHOLE answer: it replaces any earlier vote. An empty list
+   * withdraws the vote.
+   */
+  optionIds: string[];
+  /** Cache hint: the feed the post sits in. Omitted, every loaded feed is patched. */
+  spaceId?: string;
+}
+
+/**
+ * Vote on a post's poll (POST /public/community/posts/:id/poll/vote). Answers
+ * the updated poll, which lands in the feed and post caches. The server answers
+ * 409 once the poll has closed, 400 for an option that is not on it (or several
+ * on a single-choice poll), and 403 to a muted member or one without access.
+ */
+export function useVoteCommunityPoll() {
+  const { client, profileId, communityId } = useCommunityScope("useVoteCommunityPoll()");
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: VoteCommunityPollInput) => {
+      const res = await client.post(`/public/community/posts/${input.postId}/poll/vote`, {
+        profileId,
+        communityId,
+        optionIds: input.optionIds,
+      });
+      return { poll: res.data as CommunityPollView, input };
+    },
+    onSuccess: ({ poll, input }) => {
+      setPostPoll(queryClient, { postId: input.postId, spaceId: input.spaceId }, poll);
+    },
+  });
+}
+
 export interface CreateCommunityReplyInput {
   body: unknown;
   parentReplyId?: string;
@@ -513,6 +695,17 @@ export function useMyCommunityProfile(enabled = true) {
   });
 }
 
+/**
+ * Whether the signed-in member moderates THIS community (`canModerate` on
+ * `/me`), for showing the moderation tools. Display only: every moderation
+ * call is checked again by the server. Reads the same cache entry as
+ * `useMyCommunityProfile`, and stays false (with no request) until `enabled`.
+ */
+export function useCommunityCanModerate(enabled = true): boolean {
+  const { data } = useMyCommunityProfile(enabled);
+  return enabled && !!data?.canModerate;
+}
+
 /** Update display name / bio / avatar / digest cadence (PUT /public/community/me). */
 export function useUpdateMyCommunityProfile() {
   const { client, profileId, communityId } = useCommunityScope("useUpdateMyCommunityProfile()");
@@ -523,13 +716,24 @@ export function useUpdateMyCommunityProfile() {
       bio?: string | null;
       avatarUrl?: string | null;
       digestCadence?: CommunityDigestCadence;
+      showInDirectory?: boolean;
+      showOnMap?: boolean;
+      city?: string | null;
+      countryCode?: string | null;
     }) => {
       const res = await client.put("/public/community/me", { profileId, communityId, ...input });
       return res.data as CommunityMemberProfile;
     },
     onSuccess: (profile) => {
-      queryClient.setQueryData(communityKeys.myProfile(communityId), profile);
+      // Merged, not replaced: `/me` carries fields the PUT answer may not
+      // (`canModerate`), and dropping them would hide the moderator's tools.
+      queryClient.setQueryData(communityKeys.myProfile(communityId), (old: CommunityMemberProfile | undefined) =>
+        old ? { ...old, ...profile } : profile,
+      );
       queryClient.invalidateQueries({ queryKey: communityKeys.member(communityId, profile?.accountId) });
+      // Directory and map visibility may have changed.
+      queryClient.invalidateQueries({ queryKey: ["public-community-directory", communityId] });
+      queryClient.invalidateQueries({ queryKey: ["public-community-member-map", communityId] });
     },
   });
 }
@@ -606,24 +810,59 @@ export function useCommunityLeaderboard(period: CommunityLeaderboardPeriod = "al
   });
 }
 
+/** How long the typed @query settles before the member search runs. */
+export const MENTION_SEARCH_DEBOUNCE_MS = 150;
+
 /**
- * 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.
+ * The member search behind @mention: the typed text as `q` (left out when
+ * blank, so a bare "@" lists the most active members), ten results, most
+ * recently active first.
  */
-export function useCommunityMentionDirectory() {
+export function mentionDirectoryParams(q: string | null | undefined): Record<string, string | number> {
+  const trimmed = (q ?? "").trim().slice(0, 80);
+  return { ...(trimmed ? { q: trimmed } : {}), limit: 10, sort: "active" };
+}
+
+/**
+ * Members for @mention autocomplete, searched on the server as the member
+ * types (GET /public/community/members), so every current member can be
+ * mentioned, not just the hundred with the most points. Pass the text after
+ * the "@"; pass `undefined` while no @token is active and nothing is asked
+ * for. Rows come back in the leaderboard entry shape the composers read.
+ */
+export function useCommunityMentionDirectory(query?: string | null) {
   const { client, profileId, communityId } = useCommunityScope("useCommunityMentionDirectory()");
+  const active = query !== undefined && query !== null;
+  // null while no @token is open. The first text after "@" is searched at
+  // once; typing after that settles first, so a request goes per pause.
+  const [settled, setSettled] = useState<string | null>(null);
+  useEffect(() => {
+    if (!active) {
+      setSettled(null);
+      return;
+    }
+    const id = setTimeout(() => setSettled(query ?? ""), MENTION_SEARCH_DEBOUNCE_MS);
+    return () => clearTimeout(id);
+  }, [query, active]);
+  const params = mentionDirectoryParams(settled ?? query);
   return useQuery<CommunityLeaderboardEntry[]>({
-    queryKey: communityKeys.leaderboard(communityId, "mention-directory"),
+    queryKey: ["public-community-mention-search", communityId, params] as const,
     queryFn: async () => {
-      const res = await client.get("/public/community/leaderboard", {
-        params: { profileId, communityId, period: "all", limit: 100 },
-      });
-      return res.data;
+      const res = await client.get("/public/community/members", { params: { profileId, communityId, ...params } });
+      const rows = (res.data?.data ?? []) as Array<CommunityLeaderboardEntry & { points?: number }>;
+      return rows.map((m) => ({
+        accountId: m.accountId,
+        displayName: m.displayName,
+        avatarUrl: m.avatarUrl,
+        points: m.points ?? 0,
+        level: m.level,
+        firstName: m.firstName,
+        lastName: m.lastName,
+      }));
     },
-    enabled: !!profileId && !!communityId && !!client,
-    staleTime: 60_000,
+    placeholderData: keepPreviousData,
+    enabled: active && !!profileId && !!communityId && !!client,
+    staleTime: 30_000,
   });
 }
 
@@ -718,6 +957,32 @@ export function bumpFeedReplyCount(queryClient: QueryClient, spaceId: string | u
   });
 }
 
+/**
+ * Put a post's updated poll into every cache that renders the post: its feed
+ * (the one named, or every loaded feed when none is) and the single-post read.
+ */
+export function setPostPoll(
+  queryClient: QueryClient,
+  target: { postId: string; spaceId?: string },
+  poll: CommunityPollView | null,
+) {
+  const patchFeed = (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 === target.postId ? { ...p, poll } : p)),
+      })),
+    };
+  };
+  if (target.spaceId) queryClient.setQueryData(communityKeys.posts(target.spaceId), patchFeed);
+  else queryClient.setQueriesData({ queryKey: ["public-community-posts"] }, patchFeed);
+  queryClient.setQueryData(communityKeys.post(target.postId), (old: CommunityPost | undefined) =>
+    old ? { ...old, poll } : old,
+  );
+}
+
 /** Replace an entity's reaction summary in every cache that renders it. */
 export function setReactionSummary(
   queryClient: QueryClient,
@@ -796,3 +1061,82 @@ export function applyReactionDelta(
     });
   }
 }
+
+/** The `communityContentHeld` socket payload: auto-moderation sent it back to the approval queue. */
+export interface CommunityContentHeldEvent {
+  spaceId: string;
+  entityType: "community_post" | "community_reply";
+  postId: string | null;
+  replyId: string | null;
+}
+
+/**
+ * Take a post or reply that was just held for approval out of the open feeds
+ * and threads. Everyone else loses it at once; its author keeps it, marked as
+ * waiting for approval, exactly as the server shows them their own held work.
+ * An open post that is held for a reader who is not its author becomes `null`,
+ * which the thread renders as unavailable.
+ */
+export function applyCommunityContentHeld(
+  queryClient: QueryClient,
+  event: CommunityContentHeldEvent,
+  viewerAccountId: string | null | undefined,
+) {
+  const mine = (authorAccountId: string | null | undefined) => !!viewerAccountId && authorAccountId === viewerAccountId;
+  const asPending = <T extends { status?: CommunityContentStatus }>(item: T): T => ({ ...item, status: "pending" });
+
+  if (event.entityType === "community_post" && event.postId) {
+    const postId = event.postId;
+    queryClient.setQueryData(communityKeys.posts(event.spaceId), (old: any) => {
+      if (!old?.pages?.length) return old;
+      return {
+        ...old,
+        pages: old.pages.map((page: any) => {
+          const had = page.data.some((p: CommunityPost) => p.id === postId);
+          if (!had) return page;
+          const data = page.data.flatMap((p: CommunityPost) =>
+            p.id !== postId ? [p] : mine(p.authorAccountId) ? [asPending(p)] : [],
+          );
+          return { ...page, data, total: Math.max(0, page.total - (page.data.length - data.length)) };
+        }),
+      };
+    });
+    queryClient.setQueryData(communityKeys.post(postId), (old: CommunityPost | null | undefined) =>
+      old ? (mine(old.authorAccountId) ? asPending(old) : null) : old,
+    );
+    return;
+  }
+
+  if (event.entityType === "community_reply" && event.postId && event.replyId) {
+    const { postId, replyId } = event;
+    let removed = false;
+    queryClient.setQueryData(communityKeys.replies(postId), (old: any) => {
+      if (!old?.pages?.length) return old;
+      return {
+        ...old,
+        pages: old.pages.map((page: any) => {
+          if (!page.data.some((r: CommunityReply) => r.id === replyId)) return page;
+          const data = page.data.flatMap((r: CommunityReply) =>
+            r.id !== replyId ? [r] : mine(r.authorAccountId) ? [asPending(r)] : [],
+          );
+          if (data.length < page.data.length) removed = true;
+          return { ...page, data, total: Math.max(0, page.total - (page.data.length - data.length)) };
+        }),
+      };
+    });
+    if (removed) {
+      const drop = (p: CommunityPost) => ({ ...p, replyCount: Math.max(0, (p.replyCount ?? 0) - 1) });
+      queryClient.setQueryData(communityKeys.post(postId), (old: CommunityPost | null | undefined) => (old ? drop(old) : old));
+      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((p: CommunityPost) => (p.id === postId ? drop(p) : p)),
+          })),
+        };
+      });
+    }
+  }
+}