@useatlas/create 0.0.5 → 0.0.7

package/templates/nextjs-standalone/src/ui/hooks/use-admin-fetch.ts

@@ -1,31 +1,28 @@
 "use client";
 
 import { useEffect, useState, useCallback, useRef } from "react";
+import type { z } from "zod";
 import { useAtlasConfig } from "@/ui/context";
+import { extractFetchError, type FetchError } from "@/ui/lib/fetch-error";
 
-export interface FetchError {
-  message: string;
-  status?: number;
-}
-
-/** Map HTTP status codes to user-friendly messages for admin pages. */
-export function friendlyError(err: FetchError): string {
-  if (err.status === 401) return "Not authenticated. Please sign in.";
-  if (err.status === 403)
-    return "Access denied. Admin role required to view this page.";
-  if (err.status === 404) return "This feature is not enabled on this server.";
-  return err.message;
-}
+// Re-export from @/ui/lib/fetch-error (canonical location) for backward
+// compatibility. New code should import directly from @/ui/lib/fetch-error.
+export { type FetchError, friendlyError } from "@/ui/lib/fetch-error";
 
 /**
  * Shared fetch hook for admin pages.
- * Handles loading/error state, cancellation on unmount, and credentials.
+ * Handles loading/error state, structured error body extraction (message + requestId),
+ * cancellation on unmount, and credentials.
+ *
+ * Prefer `schema` (Zod) for runtime validation over `transform`.
+ * `schema` and `transform` are mutually exclusive — if both provided, `schema` wins.
  */
 export function useAdminFetch<T>(
   path: string,
   opts?: {
     deps?: unknown[];
     transform?: (json: unknown) => T;
+    schema?: z.ZodType<T>;
   },
 ) {
   const { apiUrl, isCrossOrigin } = useAtlasConfig();
@@ -45,19 +42,39 @@ export function useAdminFetch<T>(
         signal,
       });
       if (!res.ok) {
-        const e: FetchError = { message: `HTTP ${res.status}`, status: res.status };
-        if (!signal?.aborted) setError(e);
+        const e = await extractFetchError(res);
+        if (!signal?.aborted) {
+          setData(null);
+          setError(e);
+        }
         return;
       }
-      const json = await res.json();
-      const result = opts?.transform ? opts.transform(json) : (json as T);
+      const json: unknown = await res.json();
+      let result: T;
+      if (opts?.schema) {
+        const parsed = opts.schema.safeParse(json);
+        if (!parsed.success) {
+          if (!signal?.aborted) {
+            console.warn(`useAdminFetch schema validation failed for ${path}:`, parsed.error.issues);
+            setData(null);
+            setError({ message: `Unexpected response format from ${path}. Try refreshing the page.` });
+          }
+          return;
+        }
+        result = parsed.data;
+      } else if (opts?.transform) {
+        result = opts.transform(json);
+      } else {
+        result = json as T;
+      }
       if (!signal?.aborted) setData(result);
     } catch (err) {
       if (err instanceof DOMException && err.name === "AbortError") return;
       if (!signal?.aborted) {
-        setError({
-          message: err instanceof Error ? err.message : "Request failed",
-        });
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`useAdminFetch ${path}:`, msg);
+        setData(null);
+        setError({ message: msg || "Request failed" });
       }
     } finally {
       if (!signal?.aborted) setLoading(false);
@@ -93,12 +110,3 @@ export function useInProgressSet() {
       }),
   };
 }
-
-/**
- * Returns fetch options with correct credentials for admin API calls.
- */
-export function useAdminFetchOpts() {
-  const { apiUrl, isCrossOrigin } = useAtlasConfig();
-  const credentials: RequestCredentials = isCrossOrigin ? "include" : "same-origin";
-  return { apiUrl, fetchOpts: { credentials } as RequestInit };
-}

package/templates/nextjs-standalone/src/ui/hooks/use-admin-mutation.ts

@@ -0,0 +1,188 @@
+"use client";
+
+import { useState, useCallback, useRef } from "react";
+import { useAtlasConfig } from "@/ui/context";
+import { extractFetchError } from "@/ui/lib/fetch-error";
+
+/** HTTP methods supported by admin mutations. */
+type MutationMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+
+/**
+ * Discriminated result returned by `mutate()`.
+ * Discriminates on `ok`: true means the request succeeded (data is
+ * undefined for 204 No Content or non-JSON responses), false means
+ * an error occurred.
+ */
+export type MutateResult<T> =
+  | { ok: true; data: T | undefined }
+  | { ok: false; error: string };
+
+/** Options for a single mutate() call. */
+interface MutateOptions<TResponse = unknown> {
+  /** Override the path from the hook-level default. */
+  path?: string;
+  /** HTTP method. Defaults to hook-level method or "POST". */
+  method?: MutationMethod;
+  /** JSON request body. */
+  body?: Record<string, unknown>;
+  /** Track this mutation under an ID for per-item loading state. */
+  itemId?: string;
+  /** Called on success when the server returns a JSON body. Not called for 204 No Content. */
+  onSuccess?: (data: TResponse) => void;
+}
+
+/** Hook-level configuration. */
+interface UseAdminMutationOptions {
+  /** Default API path (e.g. "/api/v1/admin/branding"). Can be overridden per-call. */
+  path?: string;
+  /** Default HTTP method. Defaults to "POST". */
+  method?: MutationMethod;
+  /** Refetch functions to call after a successful mutation. */
+  invalidates?: (() => void) | (() => void)[];
+}
+
+/** Return value of useAdminMutation. */
+interface UseAdminMutationReturn<TResponse> {
+  /** Execute a mutation. Resolves with a discriminated `{ ok, data }` or `{ ok, error }` result. */
+  mutate: (options?: MutateOptions<TResponse>) => Promise<MutateResult<TResponse>>;
+  /** True while any non-item-scoped mutation is in flight. */
+  saving: boolean;
+  /** Last mutation error message, or null. Cleared on next mutate() call. */
+  error: string | null;
+  /** Clear the error manually. */
+  clearError: () => void;
+  /** Reset both error and saving state (e.g. when a dialog reopens). */
+  reset: () => void;
+  /** Check whether a per-item mutation is in flight. */
+  isMutating: (itemId: string) => boolean;
+}
+
+/**
+ * Hook for admin page mutations (POST, PUT, PATCH, DELETE).
+ *
+ * Handles saving/error state, credentials, JSON serialization,
+ * structured error extraction from response bodies, and per-item
+ * loading tracking. Reads apiUrl and credentials from AtlasUIContext.
+ */
+export function useAdminMutation<TResponse = unknown>(
+  options?: UseAdminMutationOptions,
+): UseAdminMutationReturn<TResponse> {
+  const { apiUrl, isCrossOrigin } = useAtlasConfig();
+  const credentials: RequestCredentials = isCrossOrigin ? "include" : "same-origin";
+
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [inFlight, setInFlight] = useState<Set<string>>(new Set());
+
+  // Stable refs for options that shouldn't trigger re-renders
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  // useCallback for stable references — hook API contract, not performance
+  const clearError = useCallback(() => setError(null), []);
+
+  const reset = useCallback(() => {
+    setError(null);
+    setSaving(false);
+    setInFlight(new Set());
+  }, []);
+
+  const isMutating = useCallback(
+    (itemId: string) => inFlight.has(itemId),
+    [inFlight],
+  );
+
+  const mutate = useCallback(
+    async (callOpts?: MutateOptions<TResponse>): Promise<MutateResult<TResponse>> => {
+      const opts = optionsRef.current;
+      const path = callOpts?.path ?? opts?.path;
+      const method = callOpts?.method ?? opts?.method ?? "POST";
+      const itemId = callOpts?.itemId;
+
+      if (!path) {
+        const msg = "useAdminMutation: no path provided";
+        setError(msg);
+        return { ok: false, error: msg };
+      }
+
+      // Track loading state
+      if (itemId) {
+        setInFlight((prev) => new Set(prev).add(itemId));
+      } else {
+        setSaving(true);
+      }
+      setError(null);
+
+      let data: TResponse | undefined;
+      try {
+        const headers: Record<string, string> = {};
+        let body: string | undefined;
+        if (callOpts?.body) {
+          headers["Content-Type"] = "application/json";
+          body = JSON.stringify(callOpts.body);
+        }
+
+        const res = await fetch(`${apiUrl}${path}`, {
+          method,
+          credentials,
+          headers,
+          body,
+        });
+
+        if (!res.ok) {
+          const fetchError = await extractFetchError(res);
+          const msg = fetchError.requestId
+            ? `${fetchError.message} (Request ID: ${fetchError.requestId})`
+            : fetchError.message;
+          setError(msg);
+          return { ok: false, error: msg };
+        }
+
+        // Parse response (handle 204 No Content)
+        const contentType = res.headers.get("content-type");
+        if (res.status === 204 || !contentType?.includes("application/json")) {
+          data = undefined;
+        } else {
+          data = (await res.json()) as TResponse;
+        }
+
+        // Call invalidates (refetch functions)
+        const invalidates = opts?.invalidates;
+        if (invalidates) {
+          if (Array.isArray(invalidates)) {
+            for (const fn of invalidates) fn();
+          } else {
+            invalidates();
+          }
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const errorMessage = msg || "Request failed";
+        setError(errorMessage);
+        return { ok: false, error: errorMessage };
+      } finally {
+        if (itemId) {
+          setInFlight((prev) => {
+            const next = new Set(prev);
+            next.delete(itemId);
+            return next;
+          });
+        } else {
+          setSaving(false);
+        }
+      }
+
+      // Call onSuccess outside try/catch so callback bugs don't
+      // get misreported as mutation failures.
+      // Only called when data is present — 204/non-JSON callers use result.ok instead.
+      if (data !== undefined) {
+        callOpts?.onSuccess?.(data);
+      }
+
+      return { ok: true, data };
+    },
+    [apiUrl, credentials],
+  );
+
+  return { mutate, saving, error, clearError, reset, isMutating };
+}

package/templates/nextjs-standalone/src/ui/hooks/use-atlas-transport.ts

@@ -0,0 +1,225 @@
+"use client";
+
+import { useState, useEffect, useCallback, useMemo, useRef } from "react";
+import { DefaultChatTransport, type UIMessage } from "ai";
+import { AUTH_MODES, type AuthMode } from "../lib/types";
+import { applyBrandColor, OKLCH_RE } from "./use-dark-mode";
+
+const API_KEY_STORAGE_KEY = "atlas-api-key";
+
+export interface UseAtlasTransportOptions {
+  apiUrl: string;
+  isCrossOrigin: boolean;
+  /** Returns current conversation ID. Called by transport at fetch time. */
+  getConversationId: () => string | null;
+  /** Called when a new conversation ID is captured from x-conversation-id response header */
+  onNewConversationId: (id: string) => void;
+}
+
+export interface UseAtlasTransportReturn {
+  transport: DefaultChatTransport<UIMessage>;
+  authMode: AuthMode | null;
+  authResolved: boolean;
+  apiKey: string;
+  setApiKey: (key: string) => void;
+  getHeaders: () => Record<string, string>;
+  getCredentials: () => RequestCredentials;
+  healthWarning: string;
+}
+
+export function useAtlasTransport(
+  opts: UseAtlasTransportOptions,
+): UseAtlasTransportReturn {
+  const { apiUrl, isCrossOrigin } = opts;
+
+  // --- Callback refs (stable across renders, never in useMemo deps) ---
+  const getConversationIdRef = useRef(opts.getConversationId);
+  getConversationIdRef.current = opts.getConversationId;
+
+  const onNewConversationIdRef = useRef(opts.onNewConversationId);
+  onNewConversationIdRef.current = opts.onNewConversationId;
+
+  // Internal ref — synced from getter every render, eagerly written on capture
+  const conversationIdRef = useRef<string | null>(null);
+  conversationIdRef.current = getConversationIdRef.current();
+
+  // --- Auth state ---
+  const [authMode, setAuthMode] = useState<AuthMode | null>(null);
+  const [healthWarning, setHealthWarning] = useState("");
+  const [apiKey, setApiKeyState] = useState("");
+
+  // Load API key from sessionStorage on mount
+  useEffect(() => {
+    try {
+      const stored = sessionStorage.getItem(API_KEY_STORAGE_KEY);
+      if (stored) setApiKeyState(stored);
+    } catch (err: unknown) {
+      console.warn(
+        "Cannot read API key from sessionStorage:",
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }, []);
+
+  // Combined setter: state + sessionStorage
+  const setApiKey = useCallback((key: string) => {
+    setApiKeyState(key);
+    try {
+      sessionStorage.setItem(API_KEY_STORAGE_KEY, key);
+    } catch (err: unknown) {
+      console.warn(
+        "Could not persist API key to sessionStorage:",
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }, []);
+
+  // --- Auth helpers ---
+  const getHeaders = useCallback(() => {
+    const headers: Record<string, string> = {};
+    if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+    return headers;
+  }, [apiKey]);
+
+  const getCredentials = useCallback(
+    (): RequestCredentials => (isCrossOrigin ? "include" : "same-origin"),
+    [isCrossOrigin],
+  );
+
+  // --- Health check with retry ---
+  useEffect(() => {
+    let cancelled = false;
+
+    async function fetchHealth(attempt: number): Promise<void> {
+      try {
+        const res = await fetch(`${apiUrl}/api/health`, {
+          credentials: isCrossOrigin ? "include" : "same-origin",
+        });
+        if (!res.ok) {
+          console.warn(`Health check returned ${res.status}`);
+          if (attempt < 2) {
+            await new Promise((r) => setTimeout(r, 2000));
+            return fetchHealth(attempt + 1);
+          }
+          if (!cancelled) {
+            setHealthWarning(
+              "Health check failed — check server logs. Try refreshing the page.",
+            );
+            setAuthMode("none");
+          }
+          return;
+        }
+        let data: Record<string, unknown>;
+        try {
+          data = await res.json();
+        } catch (parseErr: unknown) {
+          console.warn(
+            "Health check returned invalid JSON:",
+            parseErr instanceof Error ? parseErr.message : String(parseErr),
+          );
+          if (!cancelled) {
+            setHealthWarning(
+              "Health check returned an unreadable response. Check that no reverse proxy is modifying API responses.",
+            );
+            setAuthMode("none");
+          }
+          return;
+        }
+        const checks = data?.checks as Record<string, Record<string, unknown>> | undefined;
+        const mode = checks?.auth?.mode;
+        if (!cancelled) {
+          if (
+            typeof mode === "string" &&
+            AUTH_MODES.includes(mode as AuthMode)
+          ) {
+            setAuthMode(mode as AuthMode);
+          } else {
+            console.warn(
+              "Health check succeeded but returned no valid auth mode:",
+              data,
+            );
+            setHealthWarning(
+              "Server returned an unexpected authentication configuration.",
+            );
+            setAuthMode("none");
+          }
+          // Apply admin-configured brand color (with validation)
+          if (
+            typeof data?.brandColor === "string" &&
+            OKLCH_RE.test(data.brandColor.trim())
+          ) {
+            applyBrandColor(data.brandColor);
+          }
+        }
+      } catch (err: unknown) {
+        console.warn("Health endpoint unavailable:", err);
+        if (attempt < 2) {
+          await new Promise((r) => setTimeout(r, 2000));
+          return fetchHealth(attempt + 1);
+        }
+        if (!cancelled) {
+          const detail = err instanceof Error ? err.message : String(err);
+          setHealthWarning(
+            `Unable to reach the API server (${detail}). Try refreshing the page.`,
+          );
+          setAuthMode("none");
+        }
+      }
+    }
+
+    fetchHealth(1);
+    return () => {
+      cancelled = true;
+    };
+  }, [apiUrl, isCrossOrigin]);
+
+  // --- Transport ---
+  // conversationId is accessed via ref (not state) to avoid recreating the
+  // transport mid-stream, which triggers an infinite re-render loop in useChat.
+  // Callback refs (getConversationId, onNewConversationId) follow the same pattern.
+  // authMode: not read directly, but forces transport re-creation after auth resolves.
+  const transport = useMemo(() => {
+    const headers: Record<string, string> = {};
+    if (apiKey) {
+      headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+    return new DefaultChatTransport({
+      api: `${apiUrl}/api/v1/chat`,
+      headers,
+      credentials: isCrossOrigin ? "include" : undefined,
+      body: () =>
+        conversationIdRef.current
+          ? { conversationId: conversationIdRef.current }
+          : {},
+      fetch: (async (input: RequestInfo | URL, init?: RequestInit) => {
+        let response: Response;
+        try {
+          response = await globalThis.fetch(input, init);
+        } catch (err: unknown) {
+          console.error(
+            "Chat transport fetch failed:",
+            err instanceof Error ? err.message : String(err),
+          );
+          throw err;
+        }
+        const convId = response.headers.get("x-conversation-id");
+        if (convId && convId !== conversationIdRef.current) {
+          conversationIdRef.current = convId; // Write immediately so the next request in this stream uses the new ID (before React re-renders)
+          onNewConversationIdRef.current(convId);
+        }
+        return response;
+      }) as typeof fetch,
+    });
+  }, [apiKey, authMode, apiUrl, isCrossOrigin]);
+
+  return {
+    transport,
+    authMode,
+    authResolved: authMode !== null,
+    apiKey,
+    setApiKey,
+    getHeaders,
+    getCredentials,
+    healthWarning,
+  };
+}

package/templates/nextjs-standalone/src/ui/hooks/use-branding.ts

@@ -0,0 +1,68 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useAtlasConfig } from "@/ui/context";
+import type { WorkspaceBrandingPublic } from "@/ui/lib/types";
+
+export type { WorkspaceBrandingPublic } from "@/ui/lib/types";
+
+/**
+ * Fetch workspace branding from the public endpoint.
+ * Each component instance fetches independently on mount.
+ * Returns null while loading or if no custom branding is set.
+ */
+export function useBranding() {
+  const { apiUrl, isCrossOrigin } = useAtlasConfig();
+  const [branding, setBranding] = useState<WorkspaceBrandingPublic | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const credentials: RequestCredentials = isCrossOrigin ? "include" : "same-origin";
+
+  useEffect(() => {
+    const controller = new AbortController();
+
+    async function fetchBranding() {
+      try {
+        const res = await fetch(`${apiUrl}/api/v1/branding`, {
+          credentials,
+          signal: controller.signal,
+        });
+        if (!res.ok) {
+          console.warn(`useBranding: branding endpoint returned ${res.status} — falling back to defaults`);
+          if (!controller.signal.aborted) {
+            setError(`HTTP ${res.status}`);
+          }
+          return;
+        }
+        const json: unknown = await res.json();
+        if (
+          typeof json === "object" &&
+          json !== null &&
+          "branding" in json
+        ) {
+          const data = (json as { branding: WorkspaceBrandingPublic | null }).branding;
+          if (!controller.signal.aborted) {
+            setBranding(data);
+          }
+        }
+      } catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") return;
+        // intentionally ignored: branding fetch failure is non-critical — use defaults
+        const msg = err instanceof Error ? err.message : String(err);
+        console.debug("useBranding: fetch failed", msg);
+        if (!controller.signal.aborted) {
+          setError(msg);
+        }
+      } finally {
+        if (!controller.signal.aborted) {
+          setLoading(false);
+        }
+      }
+    }
+
+    fetchBranding();
+    return () => controller.abort();
+  }, [apiUrl, credentials]);
+
+  return { branding, loading, error };
+}