@tribe-nest/forge 3.60.0 → 3.63.0

package/src/ui/headless/_tests/useSiteApp.spec.tsx

@@ -0,0 +1,52 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { resolveAppHomeHref, useAppHomeHref, useSiteApp } from "../../../data/queries/useSiteApp";
+import { calls, get, installAdapter, restoreAdapter, wrapper } from "./communityHarness";
+import { siteApp } from "./siteAppHarness";
+
+/**
+ * The site app's public settings, read for the host the visitor is on, and the
+ * Home rule built on them.
+ */
+
+afterEach(restoreAdapter);
+
+describe("useSiteApp", () => {
+  it("asks for the settings of the host the visitor is on", async () => {
+    installAdapter([get("/public/websites/app", () => siteApp())]);
+    const { result } = renderHook(() => useSiteApp(), { wrapper: wrapper({ community: null }) });
+    await waitFor(() => expect(result.current.data).toBeDefined());
+    const sent = calls("get", "/public/websites/app");
+    expect(sent).toHaveLength(1);
+    expect(sent[0]!.params).toEqual({ host: window.location.host });
+  });
+});
+
+describe("useAppHomeHref", () => {
+  it("is the creator's start page when they chose one", async () => {
+    installAdapter([get("/public/websites/app", () => siteApp({ startUrl: "/members" }))]);
+    const { result } = renderHook(() => useAppHomeHref(), { wrapper: wrapper({ community: null }) });
+    await waitFor(() => expect(result.current).toBe("/members"));
+  });
+
+  it("falls back to /i/app before the settings arrive and when the host is unknown", async () => {
+    installAdapter([
+      get("/public/websites/app", () => {
+        throw { status: 404 };
+      }),
+    ]);
+    const { result } = renderHook(() => useAppHomeHref(), { wrapper: wrapper({ community: null }) });
+    expect(result.current).toBe("/i/app");
+    await waitFor(() => expect(calls("get", "/public/websites/app")).toHaveLength(1));
+    expect(result.current).toBe("/i/app");
+  });
+
+  it("never sends Home off-site", () => {
+    expect(resolveAppHomeHref({ startUrl: "//evil.example" })).toBe("/i/app");
+    expect(resolveAppHomeHref({ startUrl: "https://evil.example" })).toBe("/i/app");
+    expect(resolveAppHomeHref({ startUrl: "" })).toBe("/i/app");
+    expect(resolveAppHomeHref(null)).toBe("/i/app");
+    expect(resolveAppHomeHref({ startUrl: "/start" })).toBe("/start");
+  });
+});

package/src/ui/headless/_tests/wikiMediaImage.spec.tsx

@@ -0,0 +1,132 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { useWikiMediaImage, wikiImageSource, wikiMediaImageStatus } from "../communities/useCommunityWiki";
+import { wikiMediaRefreshMs } from "../../../data/queries/useCommunityWiki";
+import { PROFILE_ID, account, calls, get, installAdapter, restoreAdapter, wrapper } from "./communityHarness";
+
+/**
+ * Private wiki images. A page body names one as `kbmedia:<id>`, and the site
+ * exchanges it for a signed address that lives ten minutes, asked for with the
+ * page it sits on. These pin which `src` values render at all, what is sent,
+ * the refresh before expiry, the single re-request after a failed load, and
+ * the quiet unavailable state.
+ */
+
+afterEach(restoreAdapter);
+
+const MEDIA = "/public/communities/fan-club/wiki/start-here/media/m-1";
+
+describe("wikiImageSource", () => {
+  it("keeps plain http(s) images and site paths as they are", () => {
+    expect(wikiImageSource("https://cdn.example.com/a.png")).toEqual({
+      kind: "url",
+      url: "https://cdn.example.com/a.png",
+    });
+    expect(wikiImageSource("http://example.com/a.png")).toEqual({ kind: "url", url: "http://example.com/a.png" });
+    expect(wikiImageSource("/uploads/a.png")).toEqual({ kind: "url", url: "/uploads/a.png" });
+  });
+
+  it("reads a private reference as its media id", () => {
+    expect(wikiImageSource("kbmedia:abc-123_X")).toEqual({ kind: "private", mediaId: "abc-123_X" });
+  });
+
+  it("never renders anything else", () => {
+    for (const src of [
+      "javascript:alert(1)",
+      "data:image/png;base64,AAAA",
+      "//evil.example.com/a.png",
+      "kbmedia:",
+      "kbmedia:../../etc",
+      "kb-private:abc",
+      "",
+      42,
+      null,
+    ]) {
+      expect(wikiImageSource(src), String(src)).toBeNull();
+    }
+  });
+});
+
+describe("wikiMediaImageStatus", () => {
+  const base = {
+    isLoading: false,
+    isError: false,
+    url: "u1",
+    failedUrls: new Set<string>(),
+    retriedAfterFailure: false,
+  };
+
+  it("is loading until an address arrives, then ready", () => {
+    expect(wikiMediaImageStatus({ ...base, url: null, isLoading: true })).toBe("loading");
+    expect(wikiMediaImageStatus(base)).toBe("ready");
+  });
+
+  it("is unavailable on a refused or failed request", () => {
+    expect(wikiMediaImageStatus({ ...base, url: null, isError: true })).toBe("unavailable");
+    expect(wikiMediaImageStatus({ ...base, url: null })).toBe("unavailable");
+  });
+
+  it("waits for a fresh address after the first failed load, and gives up after the second", () => {
+    const failed = new Set(["u1"]);
+    expect(wikiMediaImageStatus({ ...base, failedUrls: failed })).toBe("loading");
+    expect(wikiMediaImageStatus({ ...base, failedUrls: failed, retriedAfterFailure: true })).toBe("unavailable");
+    expect(wikiMediaImageStatus({ ...base, url: "u2", failedUrls: failed, retriedAfterFailure: true })).toBe("ready");
+  });
+});
+
+describe("wikiMediaRefreshMs", () => {
+  it("refreshes a minute before expiry, never under 30 seconds", () => {
+    expect(wikiMediaRefreshMs(600)).toBe(540_000);
+    expect(wikiMediaRefreshMs(60)).toBe(30_000);
+    expect(wikiMediaRefreshMs(undefined)).toBe(540_000);
+  });
+});
+
+describe("useWikiMediaImage", () => {
+  it("asks for the signed address with the page it sits on", async () => {
+    installAdapter([get(MEDIA, () => ({ url: "https://signed.example.com/1", expiresInSeconds: 600 }))]);
+    const { result } = renderHook(() => useWikiMediaImage("start-here", "m-1"), {
+      wrapper: wrapper({ user: account() }),
+    });
+    expect(result.current.status).toBe("loading");
+    await waitFor(() => expect(result.current.status).toBe("ready"));
+    expect(result.current.url).toBe("https://signed.example.com/1");
+    expect(calls("get", MEDIA)[0].params).toEqual({ profileId: PROFILE_ID });
+  });
+
+  it("is unavailable when the server refuses, without retrying", async () => {
+    installAdapter([
+      get(MEDIA, () => {
+        throw { status: 404, message: "Not found" };
+      }),
+    ]);
+    const { result } = renderHook(() => useWikiMediaImage("start-here", "m-1"), { wrapper: wrapper() });
+    await waitFor(() => expect(result.current.status).toBe("unavailable"));
+    expect(calls("get", MEDIA)).toHaveLength(1);
+  });
+
+  it("replaces an address the browser could not load once, then gives up", async () => {
+    let n = 0;
+    installAdapter([get(MEDIA, () => ({ url: `https://signed.example.com/${++n}`, expiresInSeconds: 600 }))]);
+    const { result } = renderHook(() => useWikiMediaImage("start-here", "m-1"), {
+      wrapper: wrapper({ user: account() }),
+    });
+    await waitFor(() => expect(result.current.url).toBe("https://signed.example.com/1"));
+
+    act(() => result.current.onImageError());
+    await waitFor(() => expect(result.current.url).toBe("https://signed.example.com/2"));
+    expect(result.current.status).toBe("ready");
+
+    act(() => result.current.onImageError());
+    await waitFor(() => expect(result.current.status).toBe("unavailable"));
+    expect(calls("get", MEDIA)).toHaveLength(2);
+  });
+
+  it("asks for nothing without a media id", () => {
+    installAdapter([]);
+    const { result } = renderHook(() => useWikiMediaImage("start-here", undefined), { wrapper: wrapper() });
+    expect(result.current.status).toBe("unavailable");
+    expect(calls("get", /\/media\//)).toHaveLength(0);
+  });
+});

package/src/ui/headless/auth/useEmailCodeSignIn.ts

@@ -0,0 +1,186 @@
+import { useContext, useState } from "react";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import {
+  useCompleteEmailSignUp,
+  useStartEmailSignIn,
+  useVerifyEmailSignIn,
+  type EmailSignInSession,
+} from "../../../data/queries/useEmailSignIn";
+
+const emailRe = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const msg = (e: unknown) => (e as { response?: { data?: { message?: string } } })?.response?.data?.message;
+
+/**
+ * Where the email-first sign-in is:
+ *
+ *   email     the address, then Continue (emails a code).
+ *   code      the 6-digit code. Right for an address with an account: signed in.
+ *   profile   right, but the address has no account here yet: name and terms.
+ */
+export type EmailCodeSignInStep = "email" | "code" | "profile";
+
+export interface UseEmailCodeSignInOptions {
+  /** Called once signed in, by the code (`existing`) or after the name step (`new`). */
+  onSignedIn?: (result: { kind: "existing" | "new" }) => void;
+  /** Require the terms checkbox on the name step (default true). The server requires it regardless. */
+  requireAcceptance?: boolean;
+  /** Start with this email filled in. */
+  defaultEmail?: string;
+}
+
+/**
+ * Headless email-first sign-in: one email field, one code, and a name only for
+ * someone new. Nobody chooses between signing up and signing in.
+ *
+ *     email -> code -> (signed in) | profile -> (signed in)
+ *
+ * The session is stored through `PublicAuthContext.adoptSession`, the same
+ * storage every other sign-in uses. Must sit inside a `PublicAuthProvider`.
+ */
+export function useEmailCodeSignIn(opts: UseEmailCodeSignInOptions = {}) {
+  const auth = useContext(PublicAuthContext);
+  const start = useStartEmailSignIn();
+  const verify = useVerifyEmailSignIn();
+  const complete = useCompleteEmailSignUp();
+
+  const [step, setStep] = useState<EmailCodeSignInStep>("email");
+  const [email, setEmail] = useState(opts.defaultEmail ?? "");
+  const [code, setCode] = useState("");
+  const [ticket, setTicket] = useState<string | null>(null);
+  const [firstName, setFirstName] = useState("");
+  const [lastName, setLastName] = useState("");
+  const [acceptedTerms, setAcceptedTerms] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [resent, setResent] = useState(false);
+
+  const requireAcceptance = opts.requireAcceptance ?? true;
+  const trimmed = email.trim();
+
+  const signIn = (session: EmailSignInSession, kind: "existing" | "new") => {
+    auth?.adoptSession({ token: session.token, refreshToken: session.refreshToken, account: session.account });
+    opts.onSignedIn?.({ kind });
+  };
+
+  /** Step 1: email a code. */
+  const submitEmail = async () => {
+    setError(null);
+    if (!emailRe.test(trimmed)) {
+      setError("Please enter a valid email.");
+      return false;
+    }
+    try {
+      await start.mutateAsync({ email: trimmed });
+      setCode("");
+      setResent(false);
+      setStep("code");
+      return true;
+    } catch (e) {
+      setError(msg(e) || "Could not send the code.");
+      return false;
+    }
+  };
+
+  /** Step 2: redeem the code. Signs in an existing account, or opens the name step. */
+  const submitCode = async () => {
+    setError(null);
+    const value = code.trim();
+    if (!/^\d{6}$/.test(value)) {
+      setError("Enter the 6-digit code we emailed you.");
+      return false;
+    }
+    try {
+      const answer = await verify.mutateAsync({ email: trimmed, code: value });
+      if (answer.status === "needs_profile") {
+        setTicket(answer.ticket);
+        setStep("profile");
+        return true;
+      }
+      signIn(answer, "existing");
+      return true;
+    } catch (e) {
+      setError(msg(e) || "That code did not work.");
+      return false;
+    }
+  };
+
+  /** Step 3, for someone new: create the account and sign in. */
+  const submitProfile = async () => {
+    setError(null);
+    const first = firstName.trim();
+    const last = lastName.trim();
+    if (!first || !last) {
+      setError("Please enter your name.");
+      return false;
+    }
+    if (first.length > 100 || last.length > 100) {
+      setError("Please use a shorter name.");
+      return false;
+    }
+    if (requireAcceptance && !acceptedTerms) {
+      setError("You must accept the Terms and Privacy Policy.");
+      return false;
+    }
+    if (!ticket) {
+      setStep("email");
+      return false;
+    }
+    try {
+      const session = await complete.mutateAsync({
+        email: trimmed,
+        ticket,
+        firstName: first,
+        lastName: last,
+        acceptedPrivacy: true,
+      });
+      signIn(session, "new");
+      return true;
+    } catch (e) {
+      setError(msg(e) || "Could not create your account.");
+      return false;
+    }
+  };
+
+  /** Email another code (throttled to one per 60 seconds server-side). */
+  const resendCode = async () => {
+    setError(null);
+    setResent(false);
+    try {
+      await start.mutateAsync({ email: trimmed });
+      setResent(true);
+    } catch (e) {
+      setError(msg(e) || "Could not resend the code.");
+    }
+  };
+
+  /** Back to the email field, to correct a mistyped address. */
+  const changeEmail = () => {
+    setStep("email");
+    setCode("");
+    setTicket(null);
+    setResent(false);
+    setError(null);
+  };
+
+  return {
+    step,
+    email,
+    setEmail,
+    code,
+    setCode,
+    firstName,
+    setFirstName,
+    lastName,
+    setLastName,
+    acceptedTerms,
+    setAcceptedTerms,
+    error,
+    /** True right after a resend succeeded, until the next action. */
+    resent,
+    isSubmitting: start.isPending || verify.isPending || complete.isPending,
+    submitEmail,
+    submitCode,
+    submitProfile,
+    resendCode,
+    changeEmail,
+  };
+}

package/src/ui/headless/auth/useSignupForm.ts

@@ -11,8 +11,27 @@ export interface UseSignupFormOptions {
   couponCode?: string;
   /** Require the terms/privacy checkbox before submit (default true). */
   requireAcceptance?: boolean;
+  /**
+   * Start with this email filled in. When omitted, an address handed over by a
+   * client-portal invite in this tab (`rememberSignupEmail`) is used once.
+   */
+  defaultEmail?: string;
 }
 
+const SIGNUP_EMAIL_PREFILL_KEY = "forge:signup-email";
+
+/** The invite page's handed-over email, read and cleared in one go. */
+const takePrefilledEmail = (): string => {
+  if (typeof window === "undefined") return "";
+  try {
+    const value = window.sessionStorage.getItem(SIGNUP_EMAIL_PREFILL_KEY) ?? "";
+    if (value) window.sessionStorage.removeItem(SIGNUP_EMAIL_PREFILL_KEY);
+    return value;
+  } catch {
+    return "";
+  }
+};
+
 /**
  * Headless account signup. Bring your own UI (or use the styled <SignupForm>).
  *
@@ -27,7 +46,7 @@ export function useSignupForm(opts: UseSignupFormOptions = {}) {
 
   const [firstName, setFirstName] = useState("");
   const [lastName, setLastName] = useState("");
-  const [email, setEmail] = useState("");
+  const [email, setEmail] = useState(() => opts.defaultEmail ?? takePrefilledEmail());
   const [password, setPassword] = useState("");
   const [acceptedTerms, setAcceptedTerms] = useState(false);
   const [error, setError] = useState<string | null>(null);

package/src/ui/headless/chat/useChatAttachmentUpload.ts

@@ -26,8 +26,11 @@ const nextId = () => `att-${Date.now()}-${counter++}`;
  * upload them to R2 via presigned URLs, and hand back `ChatAttachment[]` to send.
  * Mirrors the admin `useUploadFiles` flow but Forge-native (uses the tenant client).
  */
-export function useChatAttachmentUpload() {
+export function useChatAttachmentUpload(options: { presignPath?: string } = {}) {
   const { client, profileId } = useForge();
+  // Community chat signs uploads at its own member-scoped endpoint. A surface
+  // with its own access rule (the client portal's Messages) names its own.
+  const presignPath = options.presignPath ?? "/public/chat/attachments/presigned-url";
   const [pending, setPending] = useState<PendingAttachment[]>([]);
   const [error, setError] = useState<string | null>(null);
   const pendingRef = useRef<PendingAttachment[]>([]);
@@ -89,10 +92,10 @@ export function useChatAttachmentUpload() {
         // Member-scoped presigned endpoint. The admin `/uploads/presigned-url`
         // route requires profile write permissions, which website members
         // don't have — using it made file-only messages fail silently.
-        const { data } = await client.post<{ presignedUrl: string; remoteUrl: string }>(
-          "/public/chat/attachments/presigned-url",
-          { fileName: item.file.name, profileId },
-        );
+        const { data } = await client.post<{ presignedUrl: string; remoteUrl: string }>(presignPath, {
+          fileName: item.file.name,
+          profileId,
+        });
         await axios.put(data.presignedUrl, item.file, {
           headers: { "Content-Type": item.file.type || "application/octet-stream" },
           onUploadProgress: (e) => {
@@ -116,7 +119,7 @@ export function useChatAttachmentUpload() {
     }
 
     return uploaded;
-  }, [client, profileId, patch]);
+  }, [client, profileId, patch, presignPath]);
 
   return {
     pending,

package/src/ui/headless/chat/useChatRoom.ts

@@ -15,6 +15,8 @@ import {
   type ChatChannel,
   type ChatMessage,
 } from "../../../data/queries/useChat";
+import { useOpenCommunityAgentDm, COMMUNITY_AGENT_DM_KEY_PREFIX } from "../../../data/queries/useCommunityAgent";
+import { useChatAgentThinking } from "../community/useCommunityAgent";
 
 /**
  * Headless community chat room: channel list + unread counts, paginated messages
@@ -23,7 +25,7 @@ import {
  * and same-tier member DMs.
  *
  * Composes the `useChat*` data hooks and `useChatSocket`. This is the single
- * primitive a creator needs to rebuild the chat page — render however you like.
+ * primitive a creator needs to rebuild the chat page. Render however you like.
  */
 export function useChatRoom() {
   const { user } = usePublicAuth();
@@ -33,6 +35,7 @@ export function useChatRoom() {
   const { data: unreadCounts = [] } = useChatUnreadCounts();
   const { data: memberDirectory = [] } = useChatMemberDirectory();
   const createMemberDm = useCreateMemberDm();
+  const openAgentDm = useOpenCommunityAgentDm();
   const markRead = useMarkChatRead();
 
   const [selectedChannel, setSelectedChannel] = useState<ChatChannel | null>(null);
@@ -138,6 +141,9 @@ export function useChatRoom() {
     };
   }, [socket, queryClient, user?.id]);
 
+  // The community AI writing an answer (in a thread, or in its DM).
+  const agentThinking = useChatAgentThinking(socket);
+
   // Join/leave the selected channel room.
   useEffect(() => {
     if (!selectedChannel?.id || !socket?.connected) return;
@@ -194,6 +200,28 @@ export function useChatRoom() {
     [createMemberDm],
   );
 
+  /**
+   * Open the member's DM with the community AI and select it. The DM is an
+   * ordinary chat channel; until the refreshed channel list carries it, a
+   * stand-in with the agent's name is selected so the panel opens at once.
+   */
+  const startAgentDm = useCallback(async () => {
+    const result = await openAgentDm.mutateAsync();
+    const listed = channels.find((c) => c.id === result.channelId);
+    const channel: ChatChannel = listed ?? {
+      id: result.channelId,
+      name: result.agent.enabled ? result.agent.name : null,
+      type: "dm",
+      description: null,
+      otherParticipant: null,
+      dmKey: `${COMMUNITY_AGENT_DM_KEY_PREFIX}${result.agent.enabled ? result.agent.id : ""}`,
+    };
+    setSelectedChannel(channel);
+    setActiveThreadParent(null);
+    setTypingUsers([]);
+    return channel;
+  }, [openAgentDm, channels]);
+
   return {
     channels,
     channelsLoading,
@@ -219,5 +247,11 @@ export function useChatRoom() {
     memberDirectory,
     startMemberDm,
     isStartingDm: createMemberDm.isPending,
+    // The community AI
+    startAgentDm,
+    isStartingAgentDm: openAgentDm.isPending,
+    agentDmError: openAgentDm.error,
+    /** Whether the community AI is answering in this channel (null thread = the channel itself, as in its DM). */
+    isAgentThinking: agentThinking.isThinking,
   };
 }

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

@@ -53,3 +53,44 @@ export { useCommunityHome, type UseCommunityHomeOptions } from "./useCommunityHo
 export { useMyMemberships, toMyMembershipEntry, type MyMembershipEntry } from "./useMyMemberships";
 export { CommunityGate, communityGateAllows, type CommunityGateProps, type CommunityGateState } from "./CommunityGate";
 export { communitiesListPath, communityAboutPath, communityHomePath } from "./paths";
+export {
+  useCommunityWiki,
+  useCommunityWikiPage,
+  shapeWikiList,
+  defaultWikiPageSlug,
+  parseWikiContent,
+  extractWikiToc,
+  wikiHeadingSlug,
+  lexicalNodeText,
+  wikiImageSource,
+  wikiMediaImageStatus,
+  wikiUnlockParts,
+  useWikiMediaImage,
+  type WikiImageSource,
+  type WikiMediaImageStatus,
+  WIKI_TOC_MIN_HEADINGS,
+  type CommunityWikiTocEntry,
+  type UseCommunityWikiOptions,
+} from "./useCommunityWiki";
+export {
+  useCommunityClassroom,
+  classroomProgressPercent,
+  classroomCourseState,
+  classroomUnlockParts,
+  classroomCourseHref,
+  type ClassroomCourseState,
+} from "./useCommunityClassroom";
+export {
+  useCommunityCalendar,
+  calendarDayKey,
+  calendarMonthStart,
+  calendarMonthWindow,
+  calendarItemIsOver,
+  groupCalendarItems,
+  rsvpErrorCode,
+  nextRsvp,
+  callJoinable,
+  type CommunityCalendarDay,
+  type CommunityRsvpErrorCode,
+  type UseCommunityCalendarOptions,
+} from "./useCommunityCalendar";