@tribe-nest/forge 3.59.0 → 3.61.0

package/src/ui/headless/community/richLexical.ts

@@ -1,7 +1,7 @@
 // DOM → Lexical-state serializer for the rich community composer. The
 // contentEditable div is the source of truth; here we walk its DOM and emit the
 // exact Lexical JSON shapes CommunityRichText renders and the create-post API
-// stores — WITHOUT pulling the Lexical runtime into forge. Mirrors the node
+// stores, WITHOUT pulling the Lexical runtime into forge. Mirrors the node
 // shapes in ./lexical.ts (buildLexicalState) so plain-text and rich content
 // round-trip through the same renderer.
 
@@ -41,6 +41,23 @@ const mentionNode = (accountId: string, name: string): LexicalNodeJson => ({
   style: "",
 });
 
+/**
+ * A mention of the community AI. It carries `agentId` and NO account field: the
+ * backend reads an account from `accountId | id | mentionId`, and the agent has
+ * no account, so it would otherwise be read as a member mention.
+ */
+const agentMentionNode = (agentId: string, name: string): LexicalNodeJson => ({
+  type: "mention",
+  version: 1,
+  agentId,
+  mentionName: name,
+  text: `@${name}`,
+  detail: 0,
+  format: 0,
+  mode: "segmented",
+  style: "",
+});
+
 const linebreakNode = (): LexicalNodeJson => ({ type: "linebreak", version: 1 });
 
 const linkNode = (url: string, children: LexicalNodeJson[]): LexicalNodeJson => ({
@@ -177,6 +194,14 @@ function serializeInline(nodes: NodeListOf<ChildNode> | ChildNode[], inherited:
       return;
     }
 
+    // The community AI's chip: a non-editable span carrying the agent id.
+    const agentId = node.getAttribute("data-agent-id");
+    if (agentId) {
+      const name = (node.getAttribute("data-mention-name") ?? node.textContent ?? "").replace(/^@/, "");
+      push(agentMentionNode(agentId, name));
+      return;
+    }
+
     // Mention chip: a non-editable span carrying the account id.
     const accountId = node.getAttribute("data-account-id");
     if (accountId) {
@@ -309,6 +334,6 @@ export function collectMentions(root: HTMLElement): MentionRef[] {
 
 /** Whether the editor holds any real content (text or a mention chip). */
 export function isRichEmpty(root: HTMLElement): boolean {
-  if (root.querySelector("[data-account-id]")) return false;
+  if (root.querySelector("[data-account-id], [data-agent-id]")) return false;
   return (root.textContent ?? "").trim().length === 0;
 }

package/src/ui/headless/community/useCommunityAgent.ts

@@ -0,0 +1,285 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { Socket } from "socket.io-client";
+import {
+  communityAgentSummaryError,
+  useCommunityAgentFeedback,
+  useCommunityAgentRatings,
+  useCommunityAgentSummary,
+  type CommunityAgentFeedbackEntity,
+  type CommunityAgentFeedbackValue,
+  type CommunityAgentSummary,
+  type CommunityAgentSummaryError,
+} from "../../../data/queries/useCommunityAgent";
+import type { CommunityReply } from "../../../data/queries/useCommunity";
+import type { ChatMessage } from "../../../data/queries/useChat";
+
+/**
+ * How long a "thinking" indicator may stand without its `done`. The answer job
+ * always sends `done`, but a dropped socket would otherwise leave the
+ * indicator up for ever.
+ */
+export const AGENT_THINKING_TIMEOUT_MS = 120_000;
+
+/** The reply count from which a thread offers "Catch me up". */
+export const CATCH_ME_UP_MIN_REPLIES = 10;
+
+// ── Linkified text ───────────────────────────────────────────────────────────
+
+export type LinkifiedSegment = { kind: "text"; text: string } | { kind: "link"; text: string; url: string };
+
+/**
+ * A titled link, `[Title](https://...)`, or a bare http(s) address. The titled
+ * form is how the agent writes its sources; bare addresses are kept for
+ * answers written before it, and for addresses inside the answer itself.
+ */
+const LINK_RE = /\[([^\]\n]+)\]\((https?:\/\/[^\s)]+)\)|https?:\/\/[^\s<>"')\]]+/g;
+/** Punctuation that ends a sentence rather than the address. */
+const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
+
+/**
+ * Split plain text into text and http(s) link segments. The agent writes its
+ * answers as plain text with a "Sources:" list of titled links; this is what
+ * makes them clickable without trusting any markup. Only http(s) addresses
+ * ever become links. Pure.
+ */
+export function linkifyText(text: string): LinkifiedSegment[] {
+  const out: LinkifiedSegment[] = [];
+  let last = 0;
+  for (const match of text.matchAll(LINK_RE)) {
+    const start = match.index ?? 0;
+    if (start > last) out.push({ kind: "text", text: text.slice(last, start) });
+    if (match[1] !== undefined && match[2] !== undefined) {
+      out.push({ kind: "link", text: match[1], url: match[2] });
+      last = start + match[0].length;
+      continue;
+    }
+    let url = match[0];
+    const trailing = TRAILING_PUNCTUATION.exec(url)?.[0] ?? "";
+    if (trailing) url = url.slice(0, -trailing.length);
+    out.push({ kind: "link", text: url, url });
+    last = start + url.length;
+  }
+  if (last < text.length) out.push({ kind: "text", text: text.slice(last) });
+  return out;
+}
+
+// ── Who asked ────────────────────────────────────────────────────────────────
+
+/**
+ * The viewer's ratings on the AI answers in one visible list, and with them
+ * who is offered thumbs at all: the read returns ONLY the answers this account
+ * asked for, so an answer is ratable exactly when its id came back. Pass the
+ * ids of the agent's answers in the list; nothing is asked for when there
+ * are none, when signed out, or when the AI is off.
+ */
+export function useCommunityAgentAnswerRatings(entityType: CommunityAgentFeedbackEntity, answerIds: string[]) {
+  const { data } = useCommunityAgentRatings(entityType, answerIds);
+  const byId = useMemo(() => new Map((data ?? []).map((row) => [row.entityId, row.feedback])), [data]);
+  return {
+    /** The viewer asked this question, so they may rate the answer. */
+    canRate: (entityId: string) => byId.has(entityId),
+    /** Their saved rating, or null. */
+    ratingOf: (entityId: string): 1 | -1 | null => byId.get(entityId) ?? null,
+  };
+}
+
+// ── Thinking ────────────────────────────────────────────────────────────────
+
+interface SocketEnvelope {
+  event?: string;
+  data?: Record<string, unknown> & {
+    postId?: string;
+    state?: string;
+    reply?: CommunityReply;
+    channelId?: string;
+    parentMessageId?: string | null;
+    message?: ChatMessage;
+  };
+}
+
+/** A set of keys that each clear themselves after `AGENT_THINKING_TIMEOUT_MS`. */
+function useExpiringSet() {
+  const [keys, setKeys] = useState<ReadonlySet<string>>(() => new Set());
+  const timers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+
+  const remove = useCallback((key: string) => {
+    const timer = timers.current.get(key);
+    if (timer) clearTimeout(timer);
+    timers.current.delete(key);
+    setKeys((prev) => {
+      if (!prev.has(key)) return prev;
+      const next = new Set(prev);
+      next.delete(key);
+      return next;
+    });
+  }, []);
+
+  const add = useCallback(
+    (key: string) => {
+      const timer = timers.current.get(key);
+      if (timer) clearTimeout(timer);
+      timers.current.set(
+        key,
+        setTimeout(() => remove(key), AGENT_THINKING_TIMEOUT_MS),
+      );
+      setKeys((prev) => (prev.has(key) ? prev : new Set(prev).add(key)));
+    },
+    [remove],
+  );
+
+  useEffect(() => {
+    const map = timers.current;
+    return () => {
+      map.forEach((timer) => clearTimeout(timer));
+      map.clear();
+    };
+  }, []);
+
+  return { keys, add, remove };
+}
+
+/**
+ * Which posts the community AI is answering right now, from the space room's
+ * `communityAgentThinking` events (the room is joined by the feed or thread
+ * hook). An entry clears on `done`, when the answer itself arrives as a
+ * `communityNewReply`, or after `AGENT_THINKING_TIMEOUT_MS`.
+ *
+ * `accepts` limits it to the posts the caller shows (one post in a thread).
+ */
+export function useCommunityAgentThinking(socket: Socket | null, accepts?: (postId: string) => boolean) {
+  const { keys, add, remove } = useExpiringSet();
+  const acceptsRef = useRef(accepts);
+  acceptsRef.current = accepts;
+
+  useEffect(() => {
+    if (!socket) return;
+    const onMessage = (envelope: SocketEnvelope) => {
+      const postId = envelope.data?.postId;
+      if (!postId || (acceptsRef.current && !acceptsRef.current(postId))) return;
+      if (envelope.event === "communityAgentThinking") {
+        if (envelope.data?.state === "thinking") add(postId);
+        else remove(postId);
+      }
+      if (envelope.event === "communityNewReply" && envelope.data?.reply?.agentAuthor) remove(postId);
+    };
+    socket.on("message", onMessage);
+    return () => {
+      socket.off("message", onMessage);
+    };
+  }, [socket, add, remove]);
+
+  return {
+    thinkingPostIds: keys,
+    isThinking: (postId: string) => keys.has(postId),
+  };
+}
+
+/** The key one chat thinking indicator lives under: the thread, or the channel itself. */
+export const chatThinkingKey = (channelId: string, parentMessageId: string | null | undefined) =>
+  `${channelId}:${parentMessageId ?? ""}`;
+
+/**
+ * Where the community AI is answering in chat, from `chatAgentThinking` on the
+ * channel rooms the chat joined. A channel answer goes in the tagging
+ * message's thread (`parentMessageId` set); a DM answer goes in the DM itself
+ * (`parentMessageId` null). Clears on `done`, on the agent's message arriving,
+ * or after `AGENT_THINKING_TIMEOUT_MS`.
+ */
+export function useChatAgentThinking(socket: Socket | null) {
+  const { keys, add, remove } = useExpiringSet();
+
+  useEffect(() => {
+    if (!socket) return;
+    const onMessage = (envelope: SocketEnvelope) => {
+      const channelId = envelope.data?.channelId;
+      if (!channelId) return;
+      if (envelope.event === "chatAgentThinking") {
+        const key = chatThinkingKey(channelId, envelope.data?.parentMessageId ?? null);
+        if (envelope.data?.state === "thinking") add(key);
+        else remove(key);
+      }
+      const message = envelope.data?.message;
+      if (envelope.event === "chatNewMessage" && message?.senderAgentId) {
+        remove(chatThinkingKey(channelId, message.parentMessageId ?? null));
+      }
+    };
+    socket.on("message", onMessage);
+    return () => {
+      socket.off("message", onMessage);
+    };
+  }, [socket, add, remove]);
+
+  return {
+    isThinking: (channelId: string | null | undefined, parentMessageId: string | null | undefined) =>
+      !!channelId && keys.has(chatThinkingKey(channelId, parentMessageId ?? null)),
+  };
+}
+
+// ── Feedback ─────────────────────────────────────────────────────────────────
+
+/**
+ * Thumbs up / down on one AI answer, optimistic. `saved` is the rating the
+ * ratings read hydrated, so the thumbs survive a reload; a press shows at once,
+ * and a success lands in the ratings cache. Choosing the active thumb again
+ * clears it. A failed rating rolls back; a 404 (not the member who asked, a
+ * safety net now the ratings read decides who sees the control) hides it.
+ */
+export function useCommunityAgentAnswerFeedback(
+  entityType: CommunityAgentFeedbackEntity,
+  entityId: string,
+  saved: 1 | -1 | null = null,
+) {
+  const mutation = useCommunityAgentFeedback();
+  // `undefined` = follow the saved rating; set while a press is in flight or failed back.
+  const [local, setLocal] = useState<1 | -1 | null | undefined>(undefined);
+  const [hidden, setHidden] = useState(false);
+  const value = local !== undefined ? local : saved;
+
+  const rate = useCallback(
+    (thumb: 1 | -1) => {
+      const previous = value;
+      const next: CommunityAgentFeedbackValue = previous === thumb ? 0 : thumb;
+      setLocal(next === 0 ? null : next);
+      mutation.mutate(
+        { entityType, entityId, value: next },
+        {
+          onError: (error) => {
+            setLocal(previous);
+            if ((error as { response?: { status?: number } })?.response?.status === 404) setHidden(true);
+          },
+        },
+      );
+    },
+    [value, mutation, entityType, entityId],
+  );
+
+  return { value, hidden, rate, isPending: mutation.isPending };
+}
+
+// ── Catch me up ──────────────────────────────────────────────────────────────
+
+/**
+ * "Catch me up" on a long thread: ask, then show the private summary until the
+ * member dismisses it. `error` is `daily_limit` (409), `unavailable` (400: too
+ * short, or the AI cannot answer now) or `failed`.
+ */
+export function useCommunityCatchUp(postId?: string) {
+  const mutation = useCommunityAgentSummary(postId);
+  const [summary, setSummary] = useState<CommunityAgentSummary | null>(null);
+  const [error, setError] = useState<CommunityAgentSummaryError | null>(null);
+
+  const ask = useCallback(() => {
+    setError(null);
+    mutation.mutate(undefined, {
+      onSuccess: (data) => setSummary(data),
+      onError: (e) => setError(communityAgentSummaryError(e)),
+    });
+  }, [mutation]);
+
+  const dismiss = useCallback(() => {
+    setSummary(null);
+    setError(null);
+  }, []);
+
+  return { summary, error, ask, dismiss, isPending: mutation.isPending };
+}

package/src/ui/headless/community/useCommunityAttachmentUpload.ts

@@ -1,6 +1,7 @@
 import axios from "axios";
 import { useCallback, useRef, useState } from "react";
 import { useForge } from "../../../provider/ForgeProvider";
+import { useOptionalCommunityContext } from "../../../contexts/CommunityContext";
 import { attachmentKind, type AttachmentKind } from "../chat/attachmentKind";
 import type { CommunityAttachmentInput } from "../../../data/queries/useCommunity";
 
@@ -31,11 +32,14 @@ const toApiType = (kind: AttachmentKind): CommunityAttachmentInput["type"] => {
 /**
  * Headless attachment composer for community posts/replies: stage local files
  * (with previews), upload to R2 via the member-scoped presigned endpoint
- * (POST /public/community/attachments/presigned-url — same flow as chat's
+ * (POST /public/community/attachments/presigned-url: same flow as chat's
  * useChatAttachmentUpload), and hand back `CommunityAttachmentInput[]`.
  */
 export function useCommunityAttachmentUpload() {
   const { client, profileId } = useForge();
+  // The community the attachment is posted into, when there is one. Soft: the
+  // composer also serves course spaces, which belong to no community.
+  const communityId = useOptionalCommunityContext()?.communityId;
   const [pending, setPending] = useState<PendingCommunityAttachment[]>([]);
   const [error, setError] = useState<string | null>(null);
   const pendingRef = useRef<PendingCommunityAttachment[]>([]);
@@ -96,7 +100,7 @@ export function useCommunityAttachmentUpload() {
       try {
         const { data } = await client.post<{ presignedUrl: string; remoteUrl: string }>(
           "/public/community/attachments/presigned-url",
-          { fileName: item.file.name, profileId },
+          { fileName: item.file.name, profileId, ...(communityId ? { communityId } : {}) },
         );
         await axios.put(data.presignedUrl, item.file, {
           headers: { "Content-Type": item.file.type || "application/octet-stream" },
@@ -121,7 +125,7 @@ export function useCommunityAttachmentUpload() {
     }
 
     return uploaded;
-  }, [client, profileId, patch]);
+  }, [client, profileId, communityId, patch]);
 
   return {
     pending,

package/src/ui/headless/community/useCommunityMembers.ts

@@ -0,0 +1,175 @@
+import { useEffect, useMemo, useState } from "react";
+import {
+  useCommunityDirectory,
+  useCommunityMemberMap,
+  type CommunityDirectoryMember,
+  type CommunityDirectoryRole,
+  type CommunityDirectorySort,
+  type CommunityMemberMapCountry,
+} from "../../../data/queries/useCommunityMembers";
+import { COUNTRY_CENTROIDS, countryName } from "./countries";
+
+// ── Pure helpers (unit-tested; no React) ─────────────────────────────────────
+
+export const DIRECTORY_SORTS: readonly CommunityDirectorySort[] = ["active", "points", "newest", "name"];
+export const DIRECTORY_LEVELS: readonly number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+
+/** One dot on the member globe: a country, where it is, and how many members. */
+export interface MemberGlobePoint {
+  countryCode: string;
+  latitude: number;
+  longitude: number;
+  members: number;
+}
+
+/** A dot as the globe library draws it. */
+export interface MemberGlobeMarker {
+  location: [number, number];
+  size: number;
+}
+
+/**
+ * The member map's countries, cleaned: codes upper-cased, repeats merged,
+ * empty and malformed rows dropped, biggest first. Every country is here,
+ * including one the globe has no centre for, so the list under the globe
+ * leaves nobody out.
+ */
+export function memberMapCountries(rows: CommunityMemberMapCountry[] | undefined): CommunityMemberMapCountry[] {
+  const merged = new Map<string, number>();
+  for (const row of Array.isArray(rows) ? rows : []) {
+    const code = typeof row.countryCode === "string" ? row.countryCode.trim().toUpperCase() : "";
+    const members = Number(row.members) || 0;
+    if (!/^[A-Z]{2}$/.test(code) || members <= 0) continue;
+    merged.set(code, (merged.get(code) ?? 0) + members);
+  }
+  return [...merged.entries()]
+    .map(([countryCode, members]) => ({ countryCode, members }))
+    .sort((a, b) => b.members - a.members || a.countryCode.localeCompare(b.countryCode));
+}
+
+/**
+ * The member map's countries as globe dots, placed at each country's centre.
+ * A country with no known centre has no dot (it still lists, through
+ * `memberMapCountries`). Biggest first.
+ */
+export function memberGlobePoints(rows: CommunityMemberMapCountry[] | undefined): MemberGlobePoint[] {
+  const points: MemberGlobePoint[] = [];
+  for (const { countryCode, members } of memberMapCountries(rows)) {
+    const centre = COUNTRY_CENTROIDS[countryCode];
+    if (centre) points.push({ countryCode, latitude: centre[0], longitude: centre[1], members });
+  }
+  return points;
+}
+
+/**
+ * Dot sizes by the square root of each country's share of the biggest, so one
+ * large country does not hide the rest: 0.03 for the smallest to 0.12 for the
+ * biggest.
+ */
+export function memberGlobeMarkers(points: MemberGlobePoint[]): MemberGlobeMarker[] {
+  const max = Math.max(1, ...points.map((p) => p.members));
+  return points.map((p) => ({ location: [p.latitude, p.longitude], size: 0.03 + 0.09 * Math.sqrt(p.members / max) }));
+}
+
+/** cobe's rotation that brings a place to the front. */
+export function globeAnglesFor(latitude: number, longitude: number): [number, number] {
+  return [Math.PI - ((longitude * Math.PI) / 180 - Math.PI / 2), (latitude * Math.PI) / 180];
+}
+
+/** "Berlin, Germany", "Germany", "Berlin", or null: where a member says they are. */
+export function memberLocationLabel(
+  member: Pick<CommunityDirectoryMember, "city" | "countryCode">,
+  locale = "en",
+): string | null {
+  const city = member.city?.trim() || null;
+  const country = countryName(member.countryCode, locale);
+  if (city && country) return `${city}, ${country}`;
+  return city ?? country;
+}
+
+// ── Hooks ────────────────────────────────────────────────────────────────────
+
+/** How long the search box settles before the directory is asked. */
+export const DIRECTORY_SEARCH_DEBOUNCE_MS = 300;
+
+export type CommunityMembersView = "list" | "map";
+
+export interface UseCommunityMemberDirectoryOptions {
+  /** Cards per page. Default 24. */
+  pageSize?: number;
+  initialView?: CommunityMembersView;
+}
+
+/**
+ * Headless member directory for the surrounding community: the search (sent
+ * once typing settles), role and level filters, sort, paging, and the list or
+ * map view. Changing any filter goes back to page 1. The map's data loads only
+ * once the map is shown.
+ */
+export function useCommunityMemberDirectory(opts: UseCommunityMemberDirectoryOptions = {}) {
+  const [search, setSearch] = useState("");
+  const [q, setQ] = useState("");
+  const [role, setRoleState] = useState<CommunityDirectoryRole | null>(null);
+  const [minLevel, setMinLevelState] = useState<number | null>(null);
+  const [sort, setSortState] = useState<CommunityDirectorySort>("active");
+  const [page, setPage] = useState(1);
+  const [view, setView] = useState<CommunityMembersView>(opts.initialView ?? "list");
+
+  useEffect(() => {
+    const id = setTimeout(() => {
+      setQ(search.trim());
+      setPage(1);
+    }, DIRECTORY_SEARCH_DEBOUNCE_MS);
+    return () => clearTimeout(id);
+  }, [search]);
+
+  const directory = useCommunityDirectory({ q, role, minLevel, sort, page, limit: opts.pageSize });
+  const map = useCommunityMemberMap({ enabled: view === "map" });
+  const countries = useMemo(() => memberMapCountries(map.data), [map.data]);
+  const points = useMemo(() => memberGlobePoints(map.data), [map.data]);
+
+  const resetting =
+    <T>(set: (value: T) => void) =>
+    (value: T) => {
+      set(value);
+      setPage(1);
+    };
+
+  return {
+    // Filters
+    search,
+    setSearch,
+    role,
+    setRole: resetting(setRoleState),
+    minLevel,
+    setMinLevel: resetting(setMinLevelState),
+    sort,
+    setSort: resetting(setSortState),
+    /** Any filter other than the default order is on. */
+    filtered: !!q || !!role || !!minLevel,
+    // Results
+    members: directory.data?.data ?? [],
+    total: directory.data?.total ?? 0,
+    page,
+    hasNextPage: !!directory.data?.hasNextPage,
+    hasPreviousPage: page > 1,
+    nextPage: () => setPage((p) => p + 1),
+    previousPage: () => setPage((p) => Math.max(1, p - 1)),
+    isLoading: directory.isLoading,
+    /** True while a new page or filter is loading behind the current results. */
+    isRefreshing: directory.isFetching && !directory.isLoading,
+    isError: directory.isError,
+    /** 403: the viewer is not a member of this community. */
+    forbidden: (directory.error as { response?: { status?: number } } | null)?.response?.status === 403,
+    // Map
+    view,
+    setView,
+    /** Globe dots: countries with a known centre. */
+    mapPoints: points,
+    /** Every country with members on the map, for the list. */
+    mapCountries: countries,
+    mapMembers: countries.reduce((n, c) => n + c.members, 0),
+    mapLoading: view === "map" && map.isLoading,
+    mapError: map.isError,
+  };
+}