@tribe-nest/forge 1.13.0

package/src/ui/headless/agent/useAiAgent.ts

@@ -0,0 +1,106 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import { useForge } from "../../../provider/ForgeProvider";
+import {
+  createAgentConversation,
+  streamAgentMessage,
+  useWebsiteAgentConfig,
+} from "../../../data/queries/useWebsiteAgent";
+
+export interface AiAgentMessage {
+  role: "user" | "assistant";
+  text: string;
+}
+
+const VISITOR_KEY = "forge_agent_visitor_id";
+
+function getVisitorId(): string {
+  if (typeof window === "undefined") return "ssr";
+  try {
+    let id = window.localStorage.getItem(VISITOR_KEY);
+    if (!id) {
+      id = (window.crypto?.randomUUID?.() ?? `v_${Date.now()}_${Math.random().toString(36).slice(2)}`);
+      window.localStorage.setItem(VISITOR_KEY, id);
+    }
+    return id;
+  } catch {
+    return `v_${Date.now()}`;
+  }
+}
+
+/**
+ * Headless controller for the website AI agent widget. Owns visitor identity,
+ * the conversation (created lazily on first send), the message list, and the
+ * streaming turn. A site can build any UI on top of this.
+ */
+export function useAiAgent() {
+  const { apiUrl, profileId, token } = useForge();
+  const config = useWebsiteAgentConfig();
+
+  const [messages, setMessages] = useState<AiAgentMessage[]>([]);
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const conversationIdRef = useRef<string | null>(null);
+  const visitorId = useMemo(getVisitorId, []);
+
+  const ensureConversation = useCallback(async (): Promise<string | null> => {
+    if (conversationIdRef.current) return conversationIdRef.current;
+    if (!apiUrl || !profileId) return null;
+    const res = await createAgentConversation({ apiUrl, token, profileId, visitorId });
+    conversationIdRef.current = res.id;
+    return res.id;
+  }, [apiUrl, profileId, token, visitorId]);
+
+  const send = useCallback(
+    async (text: string) => {
+      const trimmed = text.trim();
+      if (!trimmed || sending || !apiUrl || !profileId) return;
+      setError(null);
+      setSending(true);
+      setMessages((prev) => [...prev, { role: "user", text: trimmed }, { role: "assistant", text: "" }]);
+
+      try {
+        const conversationId = await ensureConversation();
+        if (!conversationId) {
+          setError("The assistant is unavailable.");
+          setSending(false);
+          return;
+        }
+        await streamAgentMessage({
+          apiUrl,
+          token,
+          profileId,
+          visitorId,
+          conversationId,
+          message: trimmed,
+          onEvent: (ev) => {
+            if (ev.type === "text_delta") {
+              setMessages((prev) => {
+                const next = [...prev];
+                const last = next[next.length - 1];
+                if (last && last.role === "assistant") next[next.length - 1] = { ...last, text: last.text + ev.delta };
+                return next;
+              });
+            } else if (ev.type === "error") {
+              setError(ev.message);
+            }
+          },
+        });
+      } catch {
+        setError("Sorry, something went wrong. Please try again.");
+      } finally {
+        setSending(false);
+      }
+    },
+    [apiUrl, profileId, token, visitorId, sending, ensureConversation],
+  );
+
+  return {
+    config: config.data,
+    isEnabled: !!config.data?.enabled,
+    loading: config.isLoading,
+    messages,
+    sending,
+    error,
+    send,
+  };
+}

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

@@ -0,0 +1,72 @@
+import { useState } from "react";
+import { useForge } from "../../../provider/ForgeProvider";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+
+export type LoginStep = "credentials" | "code";
+
+const msg = (e: unknown) => (e as { response?: { data?: { message?: string } } })?.response?.data?.message;
+
+/**
+ * Headless 2FA login: credentials → emailed code → verify. Bring your own UI
+ * (or use the styled <LoginForm>).
+ */
+export function useLoginFlow(opts: { onSuccess?: (smartLinkPath?: string) => void } = {}) {
+  const profileId = useForge().profileId ?? "";
+  const { validateLoginCredentials, verifyLoginCode, resendLoginCode } = usePublicAuth();
+
+  const [step, setStep] = useState<LoginStep>("credentials");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [code, setCode] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const submitCredentials = async () => {
+    setError(null);
+    setIsSubmitting(true);
+    try {
+      await validateLoginCredentials({ email, password, profileId });
+      setStep("code");
+    } catch (e) {
+      setError(msg(e) || "Invalid email or password.");
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  const submitCode = async () => {
+    setError(null);
+    setIsSubmitting(true);
+    try {
+      const { smartLinkPath } = await verifyLoginCode(email, code, profileId);
+      opts.onSuccess?.(smartLinkPath);
+    } catch (e) {
+      setError(msg(e) || "Invalid or expired code.");
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  const resend = () => resendLoginCode(email).catch(() => {});
+  const back = () => {
+    setStep("credentials");
+    setCode("");
+    setError(null);
+  };
+
+  return {
+    step,
+    email,
+    setEmail,
+    password,
+    setPassword,
+    code,
+    setCode,
+    error,
+    isSubmitting,
+    submitCredentials,
+    submitCode,
+    resend,
+    back,
+  };
+}

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

@@ -0,0 +1,85 @@
+import { useState } from "react";
+import { useForge } from "../../../provider/ForgeProvider";
+import { usePublicAuth } from "../../../contexts/PublicAuthContext";
+
+const emailRe = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const msg = (e: unknown) => (e as { response?: { data?: { message?: string } } })?.response?.data?.message;
+
+export interface UseSignupFormOptions {
+  onSuccess?: (smartLinkPath?: string) => void;
+  membershipTierId?: string;
+  couponCode?: string;
+  /** Require the terms/privacy checkbox before submit (default true). */
+  requireAcceptance?: boolean;
+}
+
+/** Headless account signup. Bring your own UI (or use the styled <SignupForm>). */
+export function useSignupForm(opts: UseSignupFormOptions = {}) {
+  const profileId = useForge().profileId ?? "";
+  const { register } = usePublicAuth();
+
+  const [firstName, setFirstName] = useState("");
+  const [lastName, setLastName] = useState("");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [acceptedTerms, setAcceptedTerms] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const requireAcceptance = opts.requireAcceptance ?? true;
+
+  const submit = async () => {
+    setError(null);
+    if (!firstName.trim() || !lastName.trim()) {
+      setError("Please enter your name.");
+      return;
+    }
+    if (!emailRe.test(email)) {
+      setError("Please enter a valid email.");
+      return;
+    }
+    if (password.length < 8) {
+      setError("Password must be at least 8 characters.");
+      return;
+    }
+    if (requireAcceptance && !acceptedTerms) {
+      setError("You must accept the Terms and Privacy Policy.");
+      return;
+    }
+    setIsSubmitting(true);
+    try {
+      const { smartLinkPath } = await register({
+        email: email.trim(),
+        password,
+        firstName: firstName.trim(),
+        lastName: lastName.trim(),
+        profileId,
+        membershipTierId: opts.membershipTierId,
+        couponCode: opts.couponCode,
+        acceptedTerms: true,
+        acceptedPrivacy: true,
+      });
+      opts.onSuccess?.(smartLinkPath);
+    } catch (e) {
+      setError(msg(e) || "Could not create your account.");
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return {
+    firstName,
+    setFirstName,
+    lastName,
+    setLastName,
+    email,
+    setEmail,
+    password,
+    setPassword,
+    acceptedTerms,
+    setAcceptedTerms,
+    error,
+    isSubmitting,
+    submit,
+  };
+}

package/src/ui/headless/broadcast/useBroadcastWatch.ts

@@ -0,0 +1,59 @@
+import { useMemo, useState } from "react";
+import type { IBroadcastPass } from "../../../types/models";
+import { useLiveBroadcasts, useValidateBroadcastPass } from "../../../data/queries/useBroadcasts";
+
+const errMessage = (e: unknown) =>
+  (e as { response?: { data?: { message?: string } } })?.response?.data?.message || "Invalid pass.";
+
+/**
+ * Headless broadcast watch: resolves a broadcast from the live list and gates it
+ * behind pass validation. Composes `useLiveBroadcasts` + `useValidateBroadcastPass`.
+ * Once `pass` is set the caller can mount its player with the returned playback info.
+ */
+export function useBroadcastWatch(broadcastId?: string) {
+  const broadcasts = useLiveBroadcasts();
+  const validatePass = useValidateBroadcastPass();
+  const [pass, setPass] = useState<IBroadcastPass | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const broadcast = useMemo(
+    () => broadcasts.data?.find((b) => b.id === broadcastId),
+    [broadcasts.data, broadcastId],
+  );
+
+  // Derive lifecycle from the broadcast timestamps (no explicit status field).
+  const isEnded = !!broadcast?.endedAt;
+  const isLive = !!broadcast?.startedAt && !broadcast?.endedAt;
+  const status: "scheduled" | "live" | "ended" | undefined = !broadcast
+    ? undefined
+    : isEnded
+      ? "ended"
+      : isLive
+        ? "live"
+        : "scheduled";
+
+  const validate = async (eventPassId: string, sessionId?: string) => {
+    setError(null);
+    if (!broadcastId) return;
+    try {
+      const result = await validatePass.mutateAsync({ broadcastId, eventPassId, sessionId });
+      setPass(result);
+      return result;
+    } catch (e) {
+      setError(errMessage(e));
+      throw e;
+    }
+  };
+
+  return {
+    broadcast,
+    isLoading: broadcasts.isLoading,
+    status,
+    isLive,
+    isEnded,
+    pass,
+    validate,
+    isValidating: validatePass.isPending,
+    error,
+  };
+}

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

@@ -0,0 +1,27 @@
+import type { ChatAttachment } from "../../../data/queries/useChat";
+
+export type AttachmentKind = "image" | "video" | "audio" | "pdf" | "file";
+
+/**
+ * Classify a chat attachment so the renderer can pick the right preview.
+ * Pure + dependency-free so every surface (forge / client / admin) shares one
+ * source of truth and can't drift.
+ */
+export function attachmentKind(a: Pick<ChatAttachment, "fileType" | "fileName">): AttachmentKind {
+  const type = (a.fileType || "").toLowerCase();
+  const name = (a.fileName || "").toLowerCase();
+  if (type.startsWith("image/")) return "image";
+  if (type.startsWith("video/")) return "video";
+  if (type.startsWith("audio/")) return "audio";
+  if (type === "application/pdf" || name.endsWith(".pdf")) return "pdf";
+  return "file";
+}
+
+/** Human-readable byte size, e.g. 2.4 MB. */
+export function formatBytes(bytes: number): string {
+  if (!bytes || bytes < 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+  const value = bytes / Math.pow(1024, i);
+  return `${value >= 10 || i === 0 ? Math.round(value) : value.toFixed(1)} ${units[i]}`;
+}

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

@@ -0,0 +1,132 @@
+import axios from "axios";
+import { useCallback, useRef, useState } from "react";
+import { useForge } from "../../../provider/ForgeProvider";
+import type { ChatAttachment } from "../../../data/queries/useChat";
+import { attachmentKind, type AttachmentKind } from "./attachmentKind";
+
+export interface PendingAttachment {
+  id: string;
+  file: File;
+  kind: AttachmentKind;
+  /** objectURL for image/video/audio local preview, revoked on clear/remove. */
+  previewUrl?: string;
+  progress: number;
+  status: "pending" | "uploading" | "done" | "error";
+  uploaded?: ChatAttachment;
+}
+
+const MAX_ATTACHMENTS = 10;
+/** Max size for a single chat attachment (100MB). Mirrors the backend cap. */
+export const MAX_ATTACHMENT_BYTES = 100 * 1024 * 1024;
+let counter = 0;
+const nextId = () => `att-${Date.now()}-${counter++}`;
+
+/**
+ * Headless attachment composer for chat: stage local files (with previews),
+ * 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() {
+  const { client, profileId } = useForge();
+  const [pending, setPending] = useState<PendingAttachment[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const pendingRef = useRef<PendingAttachment[]>([]);
+  pendingRef.current = pending;
+
+  const patch = useCallback((id: string, updates: Partial<PendingAttachment>) => {
+    setPending((prev) => prev.map((p) => (p.id === id ? { ...p, ...updates } : p)));
+  }, []);
+
+  const addFiles = useCallback((files: FileList | File[]) => {
+    const incoming = Array.from(files);
+    const oversized = incoming.filter((f) => f.size > MAX_ATTACHMENT_BYTES);
+    const allowed = incoming.filter((f) => f.size <= MAX_ATTACHMENT_BYTES);
+    setError(
+      oversized.length
+        ? `${oversized.length === 1 ? `"${oversized[0].name}" exceeds` : `${oversized.length} files exceed`} the 100MB limit and ${oversized.length === 1 ? "was" : "were"} skipped.`
+        : null,
+    );
+    setPending((prev) => {
+      const room = MAX_ATTACHMENTS - prev.length;
+      const next = allowed.slice(0, Math.max(0, room)).map((file) => {
+        const kind = attachmentKind({ fileType: file.type, fileName: file.name });
+        const previewUrl =
+          typeof URL !== "undefined" && (kind === "image" || kind === "video" || kind === "audio")
+            ? URL.createObjectURL(file)
+            : undefined;
+        return { id: nextId(), file, kind, previewUrl, progress: 0, status: "pending" as const };
+      });
+      return [...prev, ...next];
+    });
+  }, []);
+
+  const removeFile = useCallback((id: string) => {
+    setPending((prev) => {
+      const target = prev.find((p) => p.id === id);
+      if (target?.previewUrl) URL.revokeObjectURL(target.previewUrl);
+      return prev.filter((p) => p.id !== id);
+    });
+  }, []);
+
+  const clear = useCallback(() => {
+    pendingRef.current.forEach((p) => p.previewUrl && URL.revokeObjectURL(p.previewUrl));
+    setPending([]);
+    setError(null);
+  }, []);
+
+  /** Upload every staged file and return the uploaded attachments (send-ready). */
+  const uploadAll = useCallback(async (): Promise<ChatAttachment[]> => {
+    const items = pendingRef.current;
+    const uploaded: ChatAttachment[] = [];
+
+    for (const item of items) {
+      if (item.status === "done" && item.uploaded) {
+        uploaded.push(item.uploaded);
+        continue;
+      }
+      patch(item.id, { status: "uploading", progress: 0 });
+      try {
+        // 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 },
+        );
+        await axios.put(data.presignedUrl, item.file, {
+          headers: { "Content-Type": item.file.type || "application/octet-stream" },
+          onUploadProgress: (e) => {
+            const total = e.total ?? item.file.size;
+            if (total) patch(item.id, { progress: Math.round((e.loaded / total) * 100) });
+          },
+        });
+        const attachment: ChatAttachment = {
+          url: data.remoteUrl,
+          fileName: item.file.name,
+          fileSize: item.file.size,
+          fileType: item.file.type,
+        };
+        patch(item.id, { status: "done", progress: 100, uploaded: attachment });
+        uploaded.push(attachment);
+      } catch (err) {
+        patch(item.id, { status: "error" });
+        setError(`Couldn't upload "${item.file.name}". Please try again.`);
+        throw err;
+      }
+    }
+
+    return uploaded;
+  }, [client, profileId, patch]);
+
+  return {
+    pending,
+    error,
+    addFiles,
+    removeFile,
+    uploadAll,
+    clear,
+    isUploading: pending.some((p) => p.status === "uploading"),
+    hasPending: pending.length > 0,
+    canAddMore: pending.length < MAX_ATTACHMENTS,
+  };
+}