@tribe-nest/forge 3.59.0 → 3.61.0

package/src/data/queries/useCommunityAgent.ts

@@ -0,0 +1,247 @@
+import { useMemo } from "react";
+import { useMutation, useQuery, useQueryClient, type QueryClient } from "@tanstack/react-query";
+import { useCommunityContext, useCommunityScope } from "../../contexts/CommunityContext";
+import { useCommunityViewerState, useViewerAccountId } from "./useCommunities";
+import { chatKeys, type ChatChannel } from "./useChat";
+
+/** Viewer states that hold member access (`past_due` keeps it through the grace window). */
+const MEMBER_STATES = ["member", "past_due"];
+
+// ── Types (mirror apps/backend/src/routes/public/communityAgent) ─────────────
+
+/**
+ * The community AI as a member's page sees it (community parity §8.1). Each
+ * community has at most one. It is not a member: it earns no points, is never
+ * in the directory, and is always shown with an "AI" badge.
+ */
+export type CommunityAgentInfo =
+  | { enabled: false }
+  | {
+      enabled: true;
+      id: string;
+      name: string;
+      avatarUrl: string | null;
+      /** Whether members may open a 1:1 DM with it. */
+      dmEnabled: boolean;
+    };
+
+/** The agent as the author of a post, reply or chat message. */
+export interface CommunityAgentAuthor {
+  id: string;
+  name: string;
+  avatarUrl: string | null;
+}
+
+/** What opening the agent DM answers: the DM channel and the agent. */
+export interface CommunityAgentDm {
+  channelId: string;
+  agent: CommunityAgentInfo;
+}
+
+/** The entity a thumbs up / down rates. */
+export type CommunityAgentFeedbackEntity = "community_reply" | "chat_message";
+
+/** 1 up, -1 down, 0 clears the rating. */
+export type CommunityAgentFeedbackValue = 1 | -1 | 0;
+
+/** A private "catch me up" summary. Shown to the member who asked, never posted. */
+export interface CommunityAgentSummary {
+  summary: string;
+  agentName: string;
+}
+
+/** Why a "catch me up" failed, for the copy the panel shows. */
+export type CommunityAgentSummaryError = "daily_limit" | "unavailable" | "failed";
+
+export const communityAgentKeys = {
+  info: (profileId?: string, communityId?: string, accountId?: string | null) =>
+    ["public-community-agent", profileId, communityId, accountId ?? null] as const,
+  /** Every ratings read for one account and entity type: the prefix a new rating patches. */
+  ratingsFor: (profileId?: string, accountId?: string | null, entityType?: CommunityAgentFeedbackEntity) =>
+    ["public-community-agent-feedback", profileId, accountId ?? null, entityType] as const,
+  /** One visible list's ratings. `entityIds` must be sorted (see `useCommunityAgentRatings`). */
+  ratings: (
+    profileId: string | undefined,
+    accountId: string | null | undefined,
+    entityType: CommunityAgentFeedbackEntity,
+    entityIds: string[],
+  ) => ["public-community-agent-feedback", profileId, accountId ?? null, entityType, entityIds.join(",")] as const,
+};
+
+/** One row of the member's own ratings: an answer they asked for, and how they rated it. */
+export interface CommunityAgentRating {
+  entityId: string;
+  feedback: 1 | -1 | null;
+}
+
+/** The ratings read takes at most this many ids per request. */
+export const COMMUNITY_AGENT_RATINGS_BATCH = 100;
+
+/**
+ * Put a rating into every loaded ratings read for that account and type, so
+ * every list showing the answer agrees with what was just saved. Only rows
+ * already there are patched: a read that did not return the answer means the
+ * viewer did not ask it, and a rating never adds it.
+ */
+export function setCommunityAgentRating(
+  queryClient: QueryClient,
+  target: { profileId?: string; accountId?: string | null; entityType: CommunityAgentFeedbackEntity },
+  rating: CommunityAgentRating,
+) {
+  queryClient.setQueriesData<CommunityAgentRating[]>(
+    { queryKey: communityAgentKeys.ratingsFor(target.profileId, target.accountId, target.entityType) },
+    (old) =>
+      old?.some((row) => row.entityId === rating.entityId)
+        ? old.map((row) => (row.entityId === rating.entityId ? { ...row, feedback: rating.feedback } : row))
+        : old,
+  );
+}
+
+/** The prefix every agent DM's `dmKey` carries (`agent:<agentId>:<accountId>`). */
+export const COMMUNITY_AGENT_DM_KEY_PREFIX = "agent:";
+
+/** True for the member's DM with the community AI. */
+export function isCommunityAgentDm(channel: Pick<ChatChannel, "type" | "dmKey"> | null | undefined): boolean {
+  return !!channel && channel.type === "dm" && !!channel.dmKey && channel.dmKey.startsWith(COMMUNITY_AGENT_DM_KEY_PREFIX);
+}
+
+/** The agent when it is switched on, or null. Narrowing helper for callers. */
+export function enabledCommunityAgent(
+  info: CommunityAgentInfo | null | undefined,
+): Extract<CommunityAgentInfo, { enabled: true }> | null {
+  return info && info.enabled ? info : null;
+}
+
+/** The HTTP status of a failed request, if any. */
+const statusOf = (error: unknown): number | undefined =>
+  (error as { response?: { status?: number } } | null)?.response?.status;
+
+/** Map a failed "catch me up" to the copy the panel shows. */
+export function communityAgentSummaryError(error: unknown): CommunityAgentSummaryError {
+  const status = statusOf(error);
+  if (status === 409) return "daily_limit";
+  if (status === 400) return "unavailable";
+  return "failed";
+}
+
+// ── Data hooks ───────────────────────────────────────────────────────────────
+
+/**
+ * The surrounding community's AI (GET /public/community-agent). Asked for only
+ * when the viewer is signed in AND a member of this community: nobody else can
+ * reach it, so nothing is requested for them. `data` is `{ enabled: false }`
+ * when the creator has it off. Pass `enabled: false` to hold the request.
+ */
+export function useCommunityAgent(opts: { enabled?: boolean } = {}) {
+  const { client, profileId, communityId } = useCommunityScope("useCommunityAgent()");
+  const { ref } = useCommunityContext();
+  const accountId = useViewerAccountId();
+  const signedIn = !!accountId;
+  // Same cache entry `useCommunity()` reads, so inside a community home this
+  // costs no extra request.
+  const viewer = useCommunityViewerState(ref, { enabled: signedIn && opts.enabled !== false });
+  const isMember = signedIn && !!viewer.data && MEMBER_STATES.includes(viewer.data.state);
+  const query = useQuery<CommunityAgentInfo>({
+    queryKey: communityAgentKeys.info(profileId, communityId, accountId),
+    queryFn: async () => {
+      const res = await client.get("/public/community-agent", { params: { profileId, communityId } });
+      return res.data as CommunityAgentInfo;
+    },
+    enabled: opts.enabled !== false && isMember && !!profileId && !!communityId && !!client,
+    staleTime: 60_000,
+  });
+  return { ...query, agent: enabledCommunityAgent(query.data) };
+}
+
+/**
+ * Open (or reopen) the member's DM with the agent (POST /public/community-agent/dm).
+ * Answers `{ channelId, agent }`; the channel is an ordinary chat DM, so the
+ * channel list is refreshed to carry it. 404 when the agent or its DMs are off,
+ * 403 for a team member or a non-member.
+ */
+export function useOpenCommunityAgentDm() {
+  const { client, profileId, communityId } = useCommunityScope("useOpenCommunityAgentDm()");
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async () => {
+      const res = await client.post("/public/community-agent/dm", { profileId, communityId });
+      return res.data as CommunityAgentDm;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: chatKeys.channels(communityId) });
+    },
+  });
+}
+
+/**
+ * Thumbs up / down on an answer (POST /public/community-agent/feedback). Only
+ * the member who asked can rate it; anyone else gets a 404.
+ */
+export function useCommunityAgentFeedback() {
+  const { client, profileId } = useCommunityScope("useCommunityAgentFeedback()");
+  const accountId = useViewerAccountId();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: {
+      entityType: CommunityAgentFeedbackEntity;
+      entityId: string;
+      value: CommunityAgentFeedbackValue;
+    }) => {
+      const res = await client.post("/public/community-agent/feedback", { profileId, ...input });
+      return res.data as { id: string; feedback: 1 | -1 | null };
+    },
+    onSuccess: (saved, input) => {
+      setCommunityAgentRating(
+        queryClient,
+        { profileId, accountId, entityType: input.entityType },
+        { entityId: input.entityId, feedback: saved?.feedback ?? (input.value === 0 ? null : input.value) },
+      );
+    },
+  });
+}
+
+/**
+ * The viewer's own ratings on the AI answers a list shows
+ * (GET /public/community-agent/feedback). Only answers THIS account asked for
+ * come back; anyone else's are simply absent, which is what decides who is
+ * offered thumbs at all. One read per list and type, keyed by the sorted ids,
+ * batched by 100. Asked only when signed in, a member, and the AI is on.
+ */
+export function useCommunityAgentRatings(entityType: CommunityAgentFeedbackEntity, entityIds: string[]) {
+  const { client, profileId } = useCommunityScope("useCommunityAgentRatings()");
+  const accountId = useViewerAccountId();
+  const { agent } = useCommunityAgent();
+  const ids = useMemo(() => [...new Set(entityIds.filter(Boolean))].sort(), [entityIds]);
+  return useQuery<CommunityAgentRating[]>({
+    queryKey: communityAgentKeys.ratings(profileId, accountId, entityType, ids),
+    queryFn: async () => {
+      const rows: CommunityAgentRating[] = [];
+      for (let i = 0; i < ids.length; i += COMMUNITY_AGENT_RATINGS_BATCH) {
+        const batch = ids.slice(i, i + COMMUNITY_AGENT_RATINGS_BATCH);
+        const res = await client.get("/public/community-agent/feedback", {
+          params: { profileId, entityType, entityIds: batch.join(",") },
+        });
+        rows.push(...(((res.data as { data?: CommunityAgentRating[] })?.data ?? []) as CommunityAgentRating[]));
+      }
+      return rows;
+    },
+    enabled: !!agent && !!accountId && ids.length > 0 && !!profileId && !!client,
+    staleTime: 60_000,
+  });
+}
+
+/**
+ * "Catch me up" on a long thread (POST /public/community-agent/posts/:id/summary).
+ * The summary is for the member who asked and is never posted. 409 when they
+ * reached their daily limit, 400 when the thread is too short or the AI is
+ * unavailable: map either with `communityAgentSummaryError`.
+ */
+export function useCommunityAgentSummary(postId?: string) {
+  const { client, profileId, communityId } = useCommunityScope("useCommunityAgentSummary()");
+  return useMutation({
+    mutationFn: async () => {
+      const res = await client.post(`/public/community-agent/posts/${postId}/summary`, { profileId, communityId });
+      return res.data as CommunityAgentSummary;
+    },
+  });
+}

package/src/data/queries/useCommunityCalendar.ts

@@ -0,0 +1,150 @@
+import { useMutation, useQuery, useQueryClient, type QueryClient } from "@tanstack/react-query";
+import { useCommunityScope } from "../../contexts/CommunityContext";
+import { useViewerAccountId } from "./useCommunities";
+import { communityRequestStatus } from "./useCommunityClassroom";
+import type { MyMembershipCall } from "./useMembershipCalls";
+
+/**
+ * A community's calendar (community parity §6.5), from
+ * `GET /public/communities/:slug/calendar`: the calls this member can attend
+ * in the community and the events the creator promoted into it, on one
+ * time-ordered list. Members and the team only (401 signed out, 403 to a
+ * non-member, 404 for an unknown community). A window is at most 186 days;
+ * without one the server reads now to 62 days ahead.
+ *
+ * Going and not going on a call is
+ * `PUT /public/communities/:slug/calendar/calls/:callId/rsvp`, which answers
+ * the call's new counts. 409 once the call is cancelled or over.
+ */
+
+export type CommunityRsvpResponse = "going" | "not_going";
+
+export interface CommunityCallRsvp {
+  going: number;
+  notGoing: number;
+  mine: CommunityRsvpResponse | null;
+}
+
+/**
+ * A call on the community calendar: exactly the member's own call read (so the
+ * same details dialog renders it), plus the member's answer and a calendar file.
+ * `isOpen` is decided by the server from the same window the join enforces.
+ */
+export interface CommunityCalendarCall extends MyMembershipCall {
+  kind: "call";
+  rsvp: CommunityCallRsvp;
+  icsUrl: string;
+}
+
+export interface CommunityCalendarEventAddress {
+  name?: string;
+  street?: string;
+  city?: string;
+  state?: string;
+  country?: string;
+  zipCode?: string;
+}
+
+export interface CommunityCalendarEvent {
+  kind: "event";
+  id: string;
+  title: string;
+  description: string | null;
+  slug: string;
+  startsAt: string;
+  endsAt: string | null;
+  timezone: string | null;
+  type: string;
+  address: CommunityCalendarEventAddress | null;
+  cancelled: boolean;
+  icsUrl: string;
+}
+
+export type CommunityCalendarItem = CommunityCalendarCall | CommunityCalendarEvent;
+
+/** The longest window the server reads in one request. */
+export const COMMUNITY_CALENDAR_MAX_RANGE_DAYS = 186;
+
+export interface CommunityCalendarRange {
+  from?: Date | string;
+  to?: Date | string;
+}
+
+const iso = (value: Date | string | undefined) =>
+  value === undefined ? undefined : typeof value === "string" ? value : value.toISOString();
+
+export const communityCalendarKeys = {
+  /** Every window of this viewer's calendar in this community, for cache updates. */
+  all: (profileId: string | undefined, slug: string | undefined, accountId: string | null) =>
+    ["public-community-calendar", profileId, slug, accountId] as const,
+  window: (
+    profileId: string | undefined,
+    slug: string | undefined,
+    accountId: string | null,
+    from: string | undefined,
+    to: string | undefined,
+  ) => ["public-community-calendar", profileId, slug, accountId, from ?? null, to ?? null] as const,
+};
+
+const retryable = (count: number, error: unknown) => {
+  const status = communityRequestStatus(error);
+  return (status === null || status >= 500) && count < 2;
+};
+
+/** The calendar's items in one window, time-ordered. */
+export function useCommunityCalendarItems(range: CommunityCalendarRange = {}, opts: { enabled?: boolean } = {}) {
+  const { client, profileId, slug } = useCommunityScope("useCommunityCalendarItems()");
+  const accountId = useViewerAccountId();
+  const from = iso(range.from);
+  const to = iso(range.to);
+  return useQuery<CommunityCalendarItem[]>({
+    queryKey: communityCalendarKeys.window(profileId, slug, accountId, from, to),
+    queryFn: async () => {
+      const params: Record<string, string> = { profileId: profileId! };
+      if (from) params.from = from;
+      if (to) params.to = to;
+      return (await client.get(`/public/communities/${encodeURIComponent(slug!)}/calendar`, { params })).data;
+    },
+    enabled: opts.enabled !== false && !!accountId && !!slug && !!profileId && !!client,
+    retry: retryable,
+  });
+}
+
+/** Put a call's new counts into every cached window that lists it. */
+export function setCalendarCallRsvp(
+  queryClient: QueryClient,
+  key: readonly unknown[],
+  callId: string,
+  rsvp: CommunityCallRsvp,
+) {
+  queryClient.setQueriesData<CommunityCalendarItem[]>({ queryKey: key }, (old) =>
+    Array.isArray(old)
+      ? old.map((item) => (item.kind === "call" && item.id === callId ? { ...item, rsvp } : item))
+      : old,
+  );
+}
+
+export interface CommunityRsvpInput {
+  callId: string;
+  /** Null clears the member's answer. */
+  response: CommunityRsvpResponse | null;
+}
+
+/** Answer going, not going, or clear the answer. The new counts land in every cached window. */
+export function useCommunityCallRsvp() {
+  const { client, profileId, slug } = useCommunityScope("useCommunityCallRsvp()");
+  const accountId = useViewerAccountId();
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: CommunityRsvpInput) =>
+      (
+        await client.put(
+          `/public/communities/${encodeURIComponent(slug!)}/calendar/calls/${encodeURIComponent(input.callId)}/rsvp`,
+          { profileId, response: input.response },
+        )
+      ).data as CommunityCallRsvp,
+    onSuccess: (rsvp, input) => {
+      setCalendarCallRsvp(queryClient, communityCalendarKeys.all(profileId, slug, accountId), input.callId, rsvp);
+    },
+  });
+}

package/src/data/queries/useCommunityClassroom.ts

@@ -0,0 +1,75 @@
+import { useQuery } from "@tanstack/react-query";
+import { useCommunityScope } from "../../contexts/CommunityContext";
+import { useViewerAccountId } from "./useCommunities";
+
+/**
+ * A community's classroom (community parity §6.3): the courses its tiers
+ * include, from `GET /public/communities/:slug/classroom`. Members and the
+ * creator's team only: the server answers 401 signed out, 403 to a non-member
+ * and 404 for an unknown community.
+ */
+
+export interface CommunityClassroomTier {
+  id: string;
+  name: string;
+}
+
+/** The viewer's progress on a course they hold. */
+export interface CommunityClassroomProgress {
+  completed: number;
+  total: number;
+  completedAt: string | null;
+  currentLessonId: string | null;
+}
+
+/** One course card. */
+export interface CommunityClassroomCourse {
+  courseId: string;
+  title: string;
+  description: string;
+  slug: string;
+  coverUrl: string | null;
+  /** The viewer holds the course, so it opens. */
+  open: boolean;
+  /** Only for a course the viewer holds. */
+  progress: CommunityClassroomProgress | null;
+  /** The level that opens it, when the viewer's own tier grants it at a level they have not reached. */
+  unlockLevel: number | null;
+  /** Other tiers of this community that include it, when the viewer's tier does not. */
+  unlockTiers: CommunityClassroomTier[];
+  /**
+   * The viewer's live course access id, which addresses the course player
+   * (`course-access/$accessId`). Null for a course they do not hold.
+   */
+  accessId: string | null;
+}
+
+export const communityClassroomKeys = {
+  list: (profileId: string | undefined, slug: string | undefined, accountId: string | null) =>
+    ["public-community-classroom", profileId, slug, accountId] as const,
+};
+
+/** The status of a failed request, or null. */
+export function communityRequestStatus(error: unknown): number | null {
+  const status = (error as { response?: { status?: unknown } } | null)?.response?.status;
+  return typeof status === "number" ? status : null;
+}
+
+/** 401, 403 and 404 are answers, not outages: asking again changes nothing. */
+const retryable = (count: number, error: unknown) => {
+  const status = communityRequestStatus(error);
+  return (status === null || status >= 500) && count < 2;
+};
+
+/** The classroom's course cards, for the signed-in viewer. */
+export function useCommunityClassroomCourses(opts: { enabled?: boolean } = {}) {
+  const { client, profileId, slug } = useCommunityScope("useCommunityClassroomCourses()");
+  const accountId = useViewerAccountId();
+  return useQuery<CommunityClassroomCourse[]>({
+    queryKey: communityClassroomKeys.list(profileId, slug, accountId),
+    queryFn: async () =>
+      (await client.get(`/public/communities/${encodeURIComponent(slug!)}/classroom`, { params: { profileId } })).data,
+    enabled: opts.enabled !== false && !!accountId && !!slug && !!profileId && !!client,
+    retry: retryable,
+  });
+}

package/src/data/queries/useCommunityMembers.ts

@@ -0,0 +1,108 @@
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import { useCommunityScope } from "../../contexts/CommunityContext";
+
+/**
+ * The community member directory and member map (community parity §6.6), on
+ * the member session. The server lists current members and the team only, and
+ * leaves out anyone who opted out, lapsed or was banned. It never returns an
+ * email. A non-member gets 403.
+ */
+
+export type CommunityDirectorySort = "active" | "points" | "newest" | "name";
+export type CommunityDirectoryRole = "member" | "moderator";
+
+/** One member card (GET /public/community/members). */
+export interface CommunityDirectoryMember {
+  accountId: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+  bio: string | null;
+  level: number;
+  points: number;
+  role: string;
+  /** Free text the member typed; display only. */
+  city: string | null;
+  /** ISO 3166-1 alpha-2. */
+  countryCode: string | null;
+  lastActiveAt: string | null;
+  joinedAt: string | null;
+  firstName: string | null;
+  lastName: string | null;
+}
+
+export interface CommunityDirectoryPage {
+  data: CommunityDirectoryMember[];
+  total: number;
+  page: number;
+  pageSize: number;
+  hasNextPage: boolean;
+}
+
+/** One country on the member map: how many opted-in members are there. */
+export interface CommunityMemberMapCountry {
+  countryCode: string;
+  members: number;
+}
+
+export interface CommunityDirectoryQuery {
+  q?: string;
+  role?: CommunityDirectoryRole | null;
+  minLevel?: number | null;
+  sort?: CommunityDirectorySort;
+  page?: number;
+  limit?: number;
+}
+
+export const COMMUNITY_DIRECTORY_PAGE_SIZE = 24;
+const MAX_LIMIT = 100;
+
+/**
+ * The directory's query string, cleaned to what the server accepts: a blank
+ * search is left out rather than sent empty, a level outside 1 to 9 is
+ * dropped, the page is at least 1 and the limit 1 to 100. Pure, so the same
+ * filters always make the same cache key.
+ */
+export function buildDirectoryParams(query: CommunityDirectoryQuery = {}): Record<string, string | number> {
+  const params: Record<string, string | number> = {};
+  const q = query.q?.trim().slice(0, 80);
+  if (q) params.q = q;
+  if (query.role === "member" || query.role === "moderator") params.role = query.role;
+  const level = Number(query.minLevel);
+  if (Number.isInteger(level) && level >= 1 && level <= 9) params.minLevel = level;
+  params.sort = query.sort ?? "active";
+  const page = Math.floor(Number(query.page));
+  params.page = Number.isFinite(page) && page >= 1 ? page : 1;
+  const limit = Math.floor(Number(query.limit ?? COMMUNITY_DIRECTORY_PAGE_SIZE));
+  params.limit = Number.isFinite(limit) ? Math.min(MAX_LIMIT, Math.max(1, limit)) : COMMUNITY_DIRECTORY_PAGE_SIZE;
+  return params;
+}
+
+export const communityMembersKeys = {
+  directory: (communityId: string | undefined, params: Record<string, string | number>) =>
+    ["public-community-directory", communityId, params] as const,
+  map: (communityId: string | undefined) => ["public-community-member-map", communityId] as const,
+};
+
+/** One page of the member directory. The previous page stays on screen while the next loads. */
+export function useCommunityDirectory(query: CommunityDirectoryQuery = {}, opts: { enabled?: boolean } = {}) {
+  const { client, profileId, communityId } = useCommunityScope("useCommunityDirectory()");
+  const params = buildDirectoryParams(query);
+  return useQuery<CommunityDirectoryPage>({
+    queryKey: communityMembersKeys.directory(communityId, params),
+    queryFn: async () =>
+      (await client.get("/public/community/members", { params: { profileId, communityId, ...params } })).data,
+    placeholderData: keepPreviousData,
+    enabled: opts.enabled !== false && !!profileId && !!communityId && !!client,
+  });
+}
+
+/** Opted-in members per country, for the member globe. */
+export function useCommunityMemberMap(opts: { enabled?: boolean } = {}) {
+  const { client, profileId, communityId } = useCommunityScope("useCommunityMemberMap()");
+  return useQuery<CommunityMemberMapCountry[]>({
+    queryKey: communityMembersKeys.map(communityId),
+    queryFn: async () =>
+      (await client.get("/public/community/members/map", { params: { profileId, communityId } })).data,
+    enabled: opts.enabled !== false && !!profileId && !!communityId && !!client,
+  });
+}