@tribe-nest/forge 3.60.0 → 3.63.0

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

@@ -4,6 +4,7 @@ import {
   useCommunityMentionDirectory,
   type CommunityLeaderboardEntry,
 } from "../../../data/queries/useCommunity";
+import { useCommunityAgent } from "../../../data/queries/useCommunityAgent";
 import type { MentionSuggestion } from "./useMentionComposer";
 import { collectMentions, isRichEmpty, serializeRichToLexical } from "./richLexical";
 
@@ -35,7 +36,10 @@ export function useRichMentionComposer() {
   const [tick, setTick] = useState(0);
   const bump = useCallback(() => setTick((n) => n + 1), []);
 
-  const { data: directory = [] } = useCommunityMentionDirectory();
+  // Searched on the server as the member types; nothing is asked for without an @token.
+  const { data: directory = [] } = useCommunityMentionDirectory(activeToken?.query);
+  // The community AI, listed first when it is on (community parity §8.2).
+  const { agent } = useCommunityAgent();
 
   const members: MentionSuggestion[] = useMemo(
     () =>
@@ -51,8 +55,17 @@ export function useRichMentionComposer() {
   const suggestions: MentionSuggestion[] = useMemo(() => {
     if (!activeToken) return [];
     const q = activeToken.query.toLowerCase();
-    return members.filter((m) => m.name.toLowerCase().includes(q)).slice(0, 6);
-  }, [activeToken, members]);
+    const matched = members.filter((m) => m.name.toLowerCase().includes(q)).slice(0, 6);
+    if (!agent || !agent.name.toLowerCase().includes(q)) return matched;
+    const agentSuggestion: MentionSuggestion = {
+      accountId: "",
+      agentId: agent.id,
+      name: agent.name,
+      avatarUrl: agent.avatarUrl,
+      level: 0,
+    };
+    return [agentSuggestion, ...matched];
+  }, [activeToken, members, agent]);
 
   /** Recompute the active @query token from the current selection. */
   const detectToken = useCallback(() => {
@@ -74,7 +87,7 @@ export function useRichMentionComposer() {
     setActiveToken({ query, textNode, atOffset: caretOffset - query.length - 1, caretOffset });
   }, []);
 
-  /** Fired on input/keyup/click/select — refresh emptiness + token. */
+  /** Fired on input/keyup/click/select: refresh emptiness + token. */
   const onEditorChange = useCallback(() => {
     bump();
     detectToken();
@@ -124,7 +137,8 @@ export function useRichMentionComposer() {
       range.deleteContents();
 
       const chip = doc.createElement("span");
-      chip.setAttribute("data-account-id", member.accountId);
+      if (member.agentId) chip.setAttribute("data-agent-id", member.agentId);
+      else chip.setAttribute("data-account-id", member.accountId);
       chip.setAttribute("data-mention-name", member.name);
       chip.setAttribute("contenteditable", "false");
       chip.textContent = `@${member.name}`;
@@ -184,6 +198,8 @@ export function useRichMentionComposer() {
     isSuggesting: !!activeToken && suggestions.length > 0,
     insertMention,
     dismissSuggestions: () => setActiveToken(null),
+    /** The community AI when it is on and can be mentioned, else null. */
+    agent,
     // Submission / state
     isEmpty,
     getBody,

package/src/ui/headless/downloads/index.ts

@@ -0,0 +1,8 @@
+// The download page behind a digital delivery email (`/i/downloads/$token`).
+export {
+  useDownloadPage,
+  type DownloadItem,
+  type DownloadFile,
+  type DownloadFileInfo,
+  type DownloadPageInfo,
+} from "./useDownloadPage";

package/src/ui/headless/downloads/useDownloadPage.ts

@@ -0,0 +1,134 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { useForge } from "../../../provider/ForgeProvider";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+import { apiErrorMessage } from "../coupon/useCouponField";
+
+/**
+ * The download page behind a delivery email (`/i/downloads/$token`).
+ *
+ * The token in the link finds the order and opens nothing. The files come out
+ * to a signed-in owner straight away, or to whoever types the code we email to
+ * the recipient. A right code also returns a GRANT, a signed one-hour pass for
+ * this delivery, held here in memory so a second click does not need a second
+ * email. Every file address is a ten-minute signed read, so they are fetched
+ * again (with the grant or the session) once they are close to expiring.
+ */
+
+export interface DownloadItem {
+  title: string;
+  quantity: number;
+  coverImage: string | null;
+}
+
+export interface DownloadFileInfo {
+  id: string;
+  filename: string;
+  size: number | null;
+}
+
+export interface DownloadPageInfo {
+  items: DownloadItem[];
+  files: DownloadFileInfo[];
+  /** The recipient's address, masked: `b***@example.com`. */
+  sentTo: string;
+  isGift: boolean;
+  signedInAsOwner: boolean;
+}
+
+export interface DownloadFile extends DownloadFileInfo {
+  /** A signed read, valid for ten minutes from when it was fetched. */
+  url: string;
+}
+
+type FilesResponse = { files: DownloadFile[]; grant?: string };
+
+/** Fetch again a minute before the ten-minute signature runs out. */
+const URL_REFRESH_AFTER_MS = 9 * 60 * 1000;
+
+export function useDownloadPage(token: string) {
+  const { client, profileId } = useForge();
+  const { user } = usePublicAuth();
+  const grant = useRef<string | null>(null);
+  const [files, setFiles] = useState<DownloadFile[] | null>(null);
+  const [fetchedAt, setFetchedAt] = useState(0);
+  const [codeSentTo, setCodeSentTo] = useState<string | null>(null);
+
+  const page = useQuery({
+    queryKey: ["download-page", profileId, token, user?.id ?? null],
+    queryFn: async () => {
+      const res = await client.get<DownloadPageInfo>(`/public/downloads/${encodeURIComponent(token)}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    retry: false,
+    enabled: !!token && !!profileId,
+  });
+
+  const unlock = useMutation({
+    mutationFn: async (input: { code?: string }) => {
+      const res = await client.post<FilesResponse>(`/public/downloads/${encodeURIComponent(token)}/files`, {
+        profileId,
+        ...(input.code ? { code: input.code } : {}),
+        ...(!input.code && grant.current ? { grant: grant.current } : {}),
+      });
+      return res.data;
+    },
+    onSuccess: (data) => {
+      if (data.grant) grant.current = data.grant;
+      setFiles(data.files);
+      setFetchedAt(Date.now());
+    },
+  });
+
+  const requestCode = useMutation({
+    mutationFn: async () => {
+      const res = await client.post<{ sentTo: string }>(`/public/downloads/${encodeURIComponent(token)}/code`, {
+        profileId,
+      });
+      return res.data;
+    },
+    onSuccess: (data) => setCodeSentTo(data.sentTo),
+  });
+
+  // A signed-in owner has nothing to prove: fetch the files on arrival.
+  const signedInAsOwner = !!page.data?.signedInAsOwner;
+  const { mutate: unlockMutate } = unlock;
+  useEffect(() => {
+    if (signedInAsOwner && !files) unlockMutate({});
+  }, [signedInAsOwner, files, unlockMutate]);
+
+  /**
+   * The address to send the browser to for one file, re-fetching the set first
+   * when the signatures are about to lapse.
+   */
+  const urlFor = useCallback(
+    async (fileId: string): Promise<string | null> => {
+      let current = files;
+      if (!current || Date.now() - fetchedAt > URL_REFRESH_AFTER_MS) {
+        current = (await unlock.mutateAsync({})).files;
+      }
+      return current.find((f) => f.id === fileId)?.url ?? null;
+    },
+    [files, fetchedAt, unlock],
+  );
+
+  const status: "loading" | "missing" | "locked" | "unlocked" =
+    page.isLoading ? "loading" : page.isError || !page.data ? "missing" : files ? "unlocked" : "locked";
+
+  return {
+    status,
+    info: page.data ?? null,
+    files,
+    codeSentTo,
+    requestCode: () => requestCode.mutate(),
+    isSendingCode: requestCode.isPending,
+    sendCodeError: requestCode.error ? (apiErrorMessage(requestCode.error) ?? null) : null,
+    submitCode: (code: string) => unlock.mutate({ code }),
+    isUnlocking: unlock.isPending,
+    unlockError: unlock.error ? (apiErrorMessage(unlock.error) ?? null) : null,
+    urlFor,
+  };
+}

package/src/ui/headless/index.ts

@@ -61,6 +61,12 @@ export {
 } from "./checkout/inventoryHold";
 export { useLoginFlow, type LoginStep } from "./auth/useLoginFlow";
 export { useSignupForm, type UseSignupFormOptions } from "./auth/useSignupForm";
+// Email-first sign-in: one email field and a code; a name only for someone new.
+export {
+  useEmailCodeSignIn,
+  type EmailCodeSignInStep,
+  type UseEmailCodeSignInOptions,
+} from "./auth/useEmailCodeSignIn";
 
 // Flow primitives (Part A2): multi-step purchase/booking/subscribe/chat flows,
 // each composed from the data hooks so a creator can rebuild any page.
@@ -200,6 +206,13 @@ export * from "./document";
 export * from "./film";
 // Work (project management) client-portal headless primitives.
 export * from "./work";
+// The client portal (`/i/account/*`): summary, invoices, documents, activity, approvals.
+export * from "./portal";
+// The download page behind a digital delivery email (`/i/downloads/$token`).
+export * from "./downloads";
+// The site app: its bottom bar model, its home sections, and its install and
+// notification prompts (`requestAppInstall`).
+export * from "./siteApp";
 // Funnel instrumentation: wrap a multi-step flow to record step-through and
 // drop-off on the first-party analytics feed.
 export * from "./funnel";

package/src/ui/headless/memberHome/index.ts

@@ -5,6 +5,16 @@ export {
   type MemberHomeNavKey,
   type UseMemberHomeNavOptions,
 } from "./useMemberHomeNav";
+// The phone's bottom bar and its "More" sheet, decided from the nav model.
+export {
+  buildMemberHomeBar,
+  MEMBER_HOME_BAR_PRIORITY,
+  MEMBER_HOME_BAR_SLOTS,
+  MEMBER_HOME_MORE_GROUPS,
+  type MemberHomeBarInput,
+  type MemberHomeBarModel,
+  type MemberHomeMoreGroup,
+} from "./memberHomeBar";
 
 // The member call calendar's model. Grouping lives here so the two rendering
 // surfaces cannot disagree about which calls are "today".

package/src/ui/headless/memberHome/memberHomeBar.ts

@@ -0,0 +1,91 @@
+import type { MemberHomeNavKey } from "./useMemberHomeNav";
+
+/**
+ * The phone layout of a community's member home: a bottom bar of four slots,
+ * then "More", which opens a sheet with everything else. Kept apart from how it
+ * is drawn so the bar, the sheet and a spec can never disagree about what goes
+ * where.
+ */
+
+/** How many items the bar holds before "More". */
+export const MEMBER_HOME_BAR_SLOTS = 4;
+
+/**
+ * Who gets a slot, in order. The first four are the ones a member opens daily;
+ * when one of them is not shown for this community, the next shown item in this
+ * list moves up into its slot.
+ */
+export const MEMBER_HOME_BAR_PRIORITY: readonly MemberHomeNavKey[] = [
+  "posts",
+  "spaces",
+  "chat",
+  "notifications",
+  "calendar",
+  "classroom",
+  "members",
+  "wiki",
+  "collections",
+  "leaderboard",
+  "moderation",
+];
+
+/** The "More" sheet's groups and the order inside each. */
+export const MEMBER_HOME_MORE_GROUPS: Readonly<Record<MemberHomeMoreGroup, readonly MemberHomeNavKey[]>> = {
+  community: ["collections", "calendar", "classroom", "wiki", "members", "leaderboard"],
+  you: ["moderation"],
+};
+
+export type MemberHomeMoreGroup = "community" | "you";
+
+/** The least a nav item needs for the bar model: its key, whether it is shown, and whether it is the page. */
+export interface MemberHomeBarInput<T extends { key: MemberHomeNavKey }> {
+  /** The items shown for this community (`useMemberHomeNav().visibleItems`). */
+  visibleItems: readonly T[];
+  /** The page being shown, or null. */
+  activeKey: MemberHomeNavKey | null;
+}
+
+export interface MemberHomeBarModel<T extends { key: MemberHomeNavKey }> {
+  /** Up to four items for the bar, in slot order. */
+  bar: T[];
+  /** Everything else that is shown, grouped for the sheet. Empty groups are left out. */
+  more: Array<{ group: MemberHomeMoreGroup; items: T[] }>;
+  /** The page being shown lives in the sheet, so "More" is the highlighted button. */
+  moreActive: boolean;
+}
+
+/**
+ * Decide what sits in the bar and what goes behind "More". Pure.
+ *
+ * An item is never in both places, and every shown item is in one of them: a
+ * key no group names (none today) lands at the end of "Community" rather than
+ * disappearing.
+ */
+export function buildMemberHomeBar<T extends { key: MemberHomeNavKey }>({
+  visibleItems,
+  activeKey,
+}: MemberHomeBarInput<T>): MemberHomeBarModel<T> {
+  const byKey = new Map(visibleItems.map((item) => [item.key, item] as const));
+  const bar = MEMBER_HOME_BAR_PRIORITY.filter((key) => byKey.has(key))
+    .slice(0, MEMBER_HOME_BAR_SLOTS)
+    .map((key) => byKey.get(key)!);
+  const inBar = new Set(bar.map((item) => item.key));
+  const rest = visibleItems.filter((item) => !inBar.has(item.key));
+
+  const placed = new Set<MemberHomeNavKey>();
+  const more = (Object.keys(MEMBER_HOME_MORE_GROUPS) as MemberHomeMoreGroup[]).map((group) => {
+    const items = MEMBER_HOME_MORE_GROUPS[group]
+      .map((key) => rest.find((item) => item.key === key))
+      .filter((item): item is T => !!item);
+    items.forEach((item) => placed.add(item.key));
+    return { group, items };
+  });
+  const unplaced = rest.filter((item) => !placed.has(item.key));
+  if (unplaced.length) more[0]!.items.push(...unplaced);
+
+  return {
+    bar,
+    more: more.filter((g) => g.items.length > 0),
+    moreActive: !!activeKey && !inBar.has(activeKey) && rest.some((item) => item.key === activeKey),
+  };
+}

package/src/ui/headless/memberHome/useMemberHomeNav.ts

@@ -1,19 +1,38 @@
-import { useMemo } from "react";
+import { useContext, useMemo } from "react";
 import { useGetPostCollections } from "../../../data/queries/usePostCollections";
-import { useCommunitySpaces } from "../../../data/queries/useCommunity";
+import { useCommunityCanModerate, useCommunitySpaces } from "../../../data/queries/useCommunity";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { useCommunityWikiPages } from "../../../data/queries/useCommunityWiki";
+import { useCommunityViewerState } from "../../../data/queries/useCommunities";
+import { viewerHasAccess } from "../communities/useCommunity";
 import { useChatChannels } from "../../../data/queries/useChat";
-import { useMyMembershipCalls } from "../../../data/queries/useMembershipCalls";
 import { MissingCommunityProviderError, useOptionalCommunityContext } from "../../../contexts/CommunityContext";
 import { internalPath } from "../../../runtime/pages";
 
-export type MemberHomeNavKey = "posts" | "collections" | "spaces" | "calendar" | "chat" | "leaderboard" | "notifications";
+export type MemberHomeNavKey =
+  | "posts"
+  | "collections"
+  | "spaces"
+  | "calendar"
+  | "classroom"
+  | "chat"
+  | "leaderboard"
+  | "notifications"
+  | "members"
+  | "wiki"
+  | "moderation";
 
 export interface MemberHomeNavItem {
   key: MemberHomeNavKey;
   label: string;
   /** Absolute in-site href (already run through `buildHref` when supplied). */
   href: string;
-  /** Conditional tabs (Collections/Spaces/Calendar/Chat/Leaderboard/Notifications) hide until the community has content for them. */
+  /**
+   * Conditional tabs (Collections/Spaces/Calendar/Chat/Wiki/Leaderboard/Notifications)
+   * hide until the community has content for them. Members, Calendar and
+   * Classroom show to members (the server answers them only). Moderation shows only to
+   * the community's moderators (and the profile's owners and admins).
+   */
   visible: boolean;
   /** Whether `currentPath` (or `activeKey`) falls on this tab. */
   active: boolean;
@@ -46,8 +65,8 @@ const normalize = (p: string) => {
  * queries the pages already need (cache shared via React Query), all scoped to
  * the surrounding `<CommunityProvider>`: Posts is always visible; Collections
  * when the community has any; Spaces (with its Leaderboard and Notifications)
- * when any space is accessible; Chat when any channel is; Calendar when any
- * call is. Billing, cancel and downgrade live in the community header's
+ * when any space is accessible; Chat when any channel is. Calendar, Classroom
+ * and Members show to members, whose reads they are. Billing, cancel and downgrade live in the community header's
  * Membership menu, not here, and nothing links to the account page. Hosts own
  * routing: pair with any layout via `href`/`active`.
  */
@@ -63,19 +82,29 @@ export function useMemberHomeNav(opts: UseMemberHomeNavOptions = {}) {
   const spacesQ = useCommunitySpaces();
   const channelsQ = useChatChannels();
   /**
-   * ANY call this viewer may see in this community, ever - not just an
-   * upcoming one. The Calendar is a month you can page backwards through, so
-   * it has something to show from the moment the creator has ever run a call.
-   * Keying the tab on upcoming calls alone hid the whole history the hour the
-   * last one ended, which is precisely when somebody goes looking for the
-   * recording. `limit: 1` because this is an existence check.
+   * The Moderation tab is for this community's moderators only. Display only:
+   * every moderation call is checked again by the server. Signed-out viewers
+   * never ask (read without `usePublicAuth()`, which throws outside a provider).
+   */
+  const signedIn = !!useContext(PublicAuthContext)?.user;
+  const canModerate = useCommunityCanModerate(signedIn);
+  /** The wiki, once the community has any page this viewer may see listed. */
+  const wikiQ = useCommunityWikiPages();
+  const hasWiki = Array.isArray(wikiQ.data) && wikiQ.data.length > 0;
+  /**
+   * The member directory, the calendar and the classroom are for members (the
+   * server answers 403 to anyone else). The calendar lists calls AND the events
+   * promoted into the community, and is a month you can page through, so it is
+   * a member's tab from the start rather than one that waits for a call. The
+   * viewer state is the same read the community header makes, so this adds no
+   * request there.
    */
-  const callsQ = useMyMembershipCalls({ from: new Date(0), limit: 1 });
+  const viewerQ = useCommunityViewerState(community.ref, { enabled: signedIn });
+  const isMember = signedIn && (viewerHasAccess(viewerQ.data) || canModerate);
 
   const hasCollections = (collectionsQ.data?.data?.length ?? 0) > 0;
   const hasSpaces = (spacesQ.data?.length ?? 0) > 0;
   const hasChannels = (channelsQ.data?.length ?? 0) > 0;
-  const hasCalls = (callsQ.data?.length ?? 0) > 0;
 
   const items: MemberHomeNavItem[] = useMemo(() => {
     const isUnder = (segment: string) =>
@@ -88,14 +117,18 @@ export function useMemberHomeNav(opts: UseMemberHomeNavOptions = {}) {
       { key: "spaces", label: "Spaces", path: `${basePath}/spaces`, visible: hasSpaces, external: false, active: onKey("spaces", isUnder("spaces") || isUnder("profile")) },
       // Scheduled calls. Sits above Chat because a call has a TIME on it: it is
       // the one tab whose content stops being useful if it is found late.
-      { key: "calendar", label: "Calendar", path: `${basePath}/calendar`, visible: hasCalls, external: false, active: onKey("calendar", isUnder("calendar")) },
+      { key: "calendar", label: "Calendar", path: `${basePath}/calendar`, visible: isMember, external: false, active: onKey("calendar", isUnder("calendar")) },
+      { key: "classroom", label: "Classroom", path: `${basePath}/classroom`, visible: isMember, external: false, active: onKey("classroom", isUnder("classroom")) },
       { key: "chat", label: "Chat", path: `${basePath}/chat`, visible: hasChannels, external: false, active: onKey("chat", isUnder("chat")) },
       { key: "leaderboard", label: "Leaderboard", path: `${basePath}/leaderboard`, visible: hasSpaces, external: false, active: onKey("leaderboard", isUnder("leaderboard")) },
       { key: "notifications", label: "Notifications", path: `${basePath}/notifications`, visible: hasSpaces, external: false, active: onKey("notifications", isUnder("notifications")) },
+      { key: "members", label: "Members", path: `${basePath}/members`, visible: isMember, external: false, active: onKey("members", isUnder("members")) },
+      { key: "wiki", label: "Wiki", path: `${basePath}/wiki`, visible: hasWiki, external: false, active: onKey("wiki", isUnder("wiki")) },
+      { key: "moderation", label: "Moderation", path: `${basePath}/moderation`, visible: canModerate, external: false, active: onKey("moderation", isUnder("moderation")) },
     ];
     return defs.map(({ path, ...d }) => ({ ...d, href: buildHref(path) }));
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [basePath, currentPath, opts.activeKey, hasCollections, hasSpaces, hasCalls, hasChannels]);
+  }, [basePath, currentPath, opts.activeKey, hasCollections, hasSpaces, hasChannels, hasWiki, isMember, canModerate]);
 
   return {
     items,
@@ -103,6 +136,11 @@ export function useMemberHomeNav(opts: UseMemberHomeNavOptions = {}) {
     visibleItems: items.filter((i) => i.visible),
     activeKey: items.find((i) => i.active)?.key ?? null,
     /** True once every visibility query has settled (avoids tab flash). */
-    isReady: !!basePath && !collectionsQ.isLoading && !spacesQ.isLoading && !callsQ.isLoading && !channelsQ.isLoading,
+    isReady:
+      !!basePath &&
+      !collectionsQ.isLoading &&
+      !spacesQ.isLoading &&
+      !channelsQ.isLoading &&
+      !wikiQ.isLoading,
   };
 }

package/src/ui/headless/portal/index.ts

@@ -0,0 +1,57 @@
+// Client portal (`/i/account/*`) headless primitives.
+export {
+  usePortalSummary,
+  usePortalInvoices,
+  usePortalDocuments,
+  usePortalActivity,
+  useWorkApprovalRequests,
+  useDecideApproval,
+  type PortalSectionKey,
+  type PortalAttentionItem,
+  type PortalSummary,
+  type PortalInvoice,
+  type PortalDocument,
+  type PortalActivityKind,
+  type PortalActivityItem,
+  type PortalActivityPage,
+  type ApprovalStatus,
+  type WorkApprovalRequest,
+  type WorkApprovalRequests,
+  type ApprovalDecision,
+} from "./usePortal";
+export {
+  usePortalFiles,
+  portalFilesKey,
+  type PortalFile,
+  type PortalFileOpen,
+  type PortalFilesPage,
+  type PortalFileSource,
+  type PortalFileSourceFilter,
+} from "./usePortalFiles";
+// Preview as client: redeem the one-time code, and read whether this is a preview.
+export {
+  usePortalPreview,
+  usePortalPreviewRedeem,
+  isPortalPreviewPending,
+  type PortalPreview,
+  type PortalPreviewRedeemState,
+} from "./usePortalPreview";
+// Messages: the one conversation with the creator.
+export {
+  usePortalThread,
+  usePortalMessages,
+  useSendPortalMessage,
+  useMarkPortalMessagesRead,
+  usePortalMessageAttachments,
+  usePortalMessagesLive,
+  portalMessagesInOrder,
+  portalThreadKey,
+  portalMessagesKey,
+  PORTAL_MESSAGES_POLL_MS,
+  PORTAL_MESSAGES_PRESIGN_PATH,
+  type PortalMessage,
+  type PortalMessageAttachment,
+  type PortalMessagesPage,
+  type PortalThreadState,
+  type PortalThreadSummary,
+} from "./usePortalMessages";