@useatlas/react 0.0.1

package/src/hooks/__tests__/use-atlas-chat.test.tsx

@@ -0,0 +1,157 @@
+import { describe, it, expect, beforeEach, afterEach, mock } from "bun:test";
+import { renderHook, act } from "@testing-library/react";
+import { AtlasProvider } from "../provider";
+import { useAtlasChat } from "../use-atlas-chat";
+import type { ReactNode } from "react";
+
+// Mock @ai-sdk/react useChat
+const mockSendMessage = mock(() => Promise.resolve());
+const mockSetMessages = mock();
+
+mock.module("@ai-sdk/react", () => ({
+  useChat: () => ({
+    messages: [],
+    setMessages: mockSetMessages,
+    sendMessage: mockSendMessage,
+    status: "ready",
+    error: undefined,
+  }),
+}));
+
+mock.module("ai", () => ({
+  DefaultChatTransport: class {
+    constructor(public opts: Record<string, unknown>) {}
+  },
+  isToolUIPart: () => false,
+  getToolName: () => "unknown",
+  callCompletionApi: () => {},
+  callChatApi: () => {},
+}));
+
+const originalFetch = globalThis.fetch;
+const fetchMock = mock(() =>
+  Promise.resolve(
+    new Response("", { status: 200, headers: { "Content-Type": "application/json" } }),
+  ),
+);
+
+beforeEach(() => {
+  globalThis.fetch = fetchMock as unknown as typeof fetch;
+  fetchMock.mockClear();
+  mockSendMessage.mockClear();
+  mockSetMessages.mockClear();
+  mockSendMessage.mockImplementation(() => Promise.resolve());
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+function wrapper({ children }: { children: ReactNode }) {
+  return (
+    <AtlasProvider apiUrl="https://api.example.com" apiKey="test-key">
+      {children}
+    </AtlasProvider>
+  );
+}
+
+describe("useAtlasChat", () => {
+  it("returns initial state with empty messages", () => {
+    const { result } = renderHook(() => useAtlasChat(), { wrapper });
+
+    expect(result.current.messages).toEqual([]);
+    expect(result.current.input).toBe("");
+    expect(result.current.status).toBe("ready");
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(result.current.conversationId).toBeNull();
+  });
+
+  it("accepts initialConversationId option", () => {
+    const { result } = renderHook(
+      () => useAtlasChat({ initialConversationId: "conv-123" }),
+      { wrapper },
+    );
+
+    expect(result.current.conversationId).toBe("conv-123");
+  });
+
+  it("setInput updates the input value", () => {
+    const { result } = renderHook(() => useAtlasChat(), { wrapper });
+
+    act(() => {
+      result.current.setInput("hello");
+    });
+
+    expect(result.current.input).toBe("hello");
+  });
+
+  it("sendMessage clears input and delegates to useChat", async () => {
+    const { result } = renderHook(() => useAtlasChat(), { wrapper });
+
+    act(() => {
+      result.current.setInput("test query");
+    });
+
+    await act(async () => {
+      await result.current.sendMessage("test query");
+    });
+
+    expect(result.current.input).toBe("");
+    expect(mockSendMessage).toHaveBeenCalledWith({ text: "test query" });
+  });
+
+  it("sendMessage restores input on failure", async () => {
+    mockSendMessage.mockImplementation(() =>
+      Promise.reject(new Error("Stream failed")),
+    );
+
+    const { result } = renderHook(() => useAtlasChat(), { wrapper });
+
+    act(() => {
+      result.current.setInput("my query");
+    });
+
+    let caught: Error | null = null;
+    await act(async () => {
+      try {
+        await result.current.sendMessage("my query");
+      } catch (e) {
+        caught = e as Error;
+      }
+    });
+
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toBe("Stream failed");
+    expect(result.current.input).toBe("my query");
+  });
+
+  it("setConversationId updates conversation ID", () => {
+    const { result } = renderHook(() => useAtlasChat(), { wrapper });
+
+    act(() => {
+      result.current.setConversationId("new-conv");
+    });
+
+    expect(result.current.conversationId).toBe("new-conv");
+  });
+
+  it("setMessages is exposed from the hook", () => {
+    const { result } = renderHook(() => useAtlasChat(), { wrapper });
+
+    expect(result.current.setMessages).toBeDefined();
+    expect(typeof result.current.setMessages).toBe("function");
+  });
+
+  it("exposes isLoading derived from status", () => {
+    // With status "ready", isLoading should be false
+    const { result } = renderHook(() => useAtlasChat(), { wrapper });
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.status).toBe("ready");
+  });
+
+  it("returns null error when useChat has no error", () => {
+    const { result } = renderHook(() => useAtlasChat(), { wrapper });
+    expect(result.current.error).toBeNull();
+  });
+});

package/src/hooks/__tests__/use-atlas-conversations.test.tsx

@@ -0,0 +1,159 @@
+import { describe, it, expect, beforeEach, afterEach, mock } from "bun:test";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { AtlasProvider } from "../provider";
+import { useAtlasConversations } from "../use-atlas-conversations";
+import type { ReactNode } from "react";
+
+const mockConversations = [
+  {
+    id: "conv-1",
+    userId: "user-1",
+    title: "Test conversation",
+    surface: "web",
+    connectionId: null,
+    starred: false,
+    createdAt: "2026-03-12T00:00:00Z",
+    updatedAt: "2026-03-12T00:00:00Z",
+  },
+];
+
+const fetchMock = mock(() =>
+  Promise.resolve(
+    new Response(
+      JSON.stringify({ conversations: mockConversations, total: 1 }),
+      { status: 200, headers: { "Content-Type": "application/json" } },
+    ),
+  ),
+);
+
+const originalFetch = globalThis.fetch;
+
+beforeEach(() => {
+  // mockClear only clears call history, not implementation — restore the default
+  fetchMock.mockImplementation(() =>
+    Promise.resolve(
+      new Response(
+        JSON.stringify({ conversations: mockConversations, total: 1 }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      ),
+    ),
+  );
+  fetchMock.mockClear();
+  globalThis.fetch = fetchMock as unknown as typeof fetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+function wrapper({ children }: { children: ReactNode }) {
+  return (
+    <AtlasProvider apiUrl="https://api.example.com" apiKey="test-key">
+      {children}
+    </AtlasProvider>
+  );
+}
+
+describe("useAtlasConversations", () => {
+  it("initializes with empty state", () => {
+    const { result } = renderHook(
+      () => useAtlasConversations({ enabled: false }),
+      { wrapper },
+    );
+
+    expect(result.current.conversations).toEqual([]);
+    expect(result.current.total).toBe(0);
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.available).toBe(true);
+    expect(result.current.selectedId).toBeNull();
+  });
+
+  it("fetches conversations with correct auth headers", async () => {
+    const { result } = renderHook(
+      () => useAtlasConversations({ enabled: true }),
+      { wrapper },
+    );
+
+    await result.current.refresh();
+
+    await waitFor(() => {
+      expect(result.current.conversations).toHaveLength(1);
+    });
+
+    expect(result.current.conversations[0].id).toBe("conv-1");
+    expect(result.current.total).toBe(1);
+
+    // Verify fetch called with correct URL and auth header
+    const calls = fetchMock.mock.calls as unknown as [string, RequestInit][];
+    expect(calls[0][0]).toBe("https://api.example.com/api/v1/conversations?limit=50");
+    const headers = calls[0][1]?.headers as Record<string, string>;
+    expect(headers["Authorization"]).toBe("Bearer test-key");
+  });
+
+  it("disables on 404 response", async () => {
+    fetchMock.mockImplementation(() =>
+      Promise.resolve(new Response("", { status: 404 })),
+    );
+
+    const { result } = renderHook(
+      () => useAtlasConversations({ enabled: true }),
+      { wrapper },
+    );
+
+    await result.current.refresh();
+
+    await waitFor(() => {
+      expect(result.current.available).toBe(false);
+    });
+  });
+
+  it("deleteConversation removes from local state", async () => {
+    const { result } = renderHook(
+      () => useAtlasConversations({ enabled: true }),
+      { wrapper },
+    );
+
+    await act(async () => {
+      await result.current.refresh();
+    });
+    expect(result.current.conversations).toHaveLength(1);
+
+    // Mock DELETE response
+    fetchMock.mockImplementation(() =>
+      Promise.resolve(new Response("", { status: 200 })),
+    );
+
+    let deleted = false;
+    await act(async () => {
+      deleted = await result.current.deleteConversation("conv-1");
+    });
+    expect(deleted).toBe(true);
+    expect(result.current.conversations).toHaveLength(0);
+    expect(result.current.total).toBe(0);
+  });
+
+  it("starConversation does optimistic update and rolls back on failure", async () => {
+    const { result } = renderHook(
+      () => useAtlasConversations({ enabled: true }),
+      { wrapper },
+    );
+
+    await act(async () => {
+      await result.current.refresh();
+    });
+    expect(result.current.conversations).toHaveLength(1);
+
+    // Mock PATCH to fail
+    fetchMock.mockImplementation(() =>
+      Promise.resolve(new Response("", { status: 500 })),
+    );
+
+    let starred = true;
+    await act(async () => {
+      starred = await result.current.starConversation("conv-1", true);
+    });
+    expect(starred).toBe(false);
+    // Should roll back to unstarred
+    expect(result.current.conversations[0].starred).toBe(false);
+  });
+});

package/src/hooks/__tests__/use-atlas-theme.test.tsx

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { renderHook, act } from "@testing-library/react";
+import { useAtlasTheme } from "../use-atlas-theme";
+
+describe("useAtlasTheme", () => {
+  beforeEach(() => {
+    const { result } = renderHook(() => useAtlasTheme());
+    act(() => {
+      result.current.setTheme("system");
+    });
+  });
+
+  it("returns current theme mode", () => {
+    const { result } = renderHook(() => useAtlasTheme());
+    expect(["light", "dark", "system"]).toContain(result.current.theme);
+    expect(typeof result.current.isDark).toBe("boolean");
+  });
+
+  it("sets theme to dark", () => {
+    const { result } = renderHook(() => useAtlasTheme());
+
+    act(() => {
+      result.current.setTheme("dark");
+    });
+
+    expect(result.current.theme).toBe("dark");
+    expect(result.current.isDark).toBe(true);
+  });
+
+  it("toggles between light and dark", () => {
+    const { result } = renderHook(() => useAtlasTheme());
+
+    act(() => {
+      result.current.setTheme("light");
+    });
+    expect(result.current.theme).toBe("light");
+    expect(result.current.isDark).toBe(false);
+
+    act(() => {
+      result.current.setTheme("dark");
+    });
+    expect(result.current.theme).toBe("dark");
+    expect(result.current.isDark).toBe(true);
+  });
+
+  it("applyBrandColor sets CSS custom property", () => {
+    const { result } = renderHook(() => useAtlasTheme());
+
+    act(() => {
+      result.current.applyBrandColor("oklch(0.759 0.148 167.71)");
+    });
+
+    const value = document.documentElement.style.getPropertyValue("--atlas-brand");
+    expect(value).toBe("oklch(0.759 0.148 167.71)");
+  });
+});

package/src/hooks/index.ts

@@ -0,0 +1,47 @@
+// Provider
+export { AtlasProvider, useAtlasContext } from "./provider";
+export type {
+  AtlasProviderProps,
+  AtlasContextValue,
+  AtlasAuthClient,
+} from "./provider";
+
+// Hooks
+export { useAtlasChat } from "./use-atlas-chat";
+export type {
+  AtlasChatStatus,
+  UseAtlasChatOptions,
+  UseAtlasChatReturn,
+} from "./use-atlas-chat";
+
+export { useAtlasAuth } from "./use-atlas-auth";
+export type { UseAtlasAuthReturn } from "./use-atlas-auth";
+
+export { useAtlasTheme } from "./use-atlas-theme";
+export type { UseAtlasThemeReturn, ThemeMode } from "./use-atlas-theme";
+
+export { useAtlasConversations } from "./use-atlas-conversations";
+export type {
+  UseAtlasConversationsOptions,
+  UseAtlasConversationsReturn,
+} from "./use-atlas-conversations";
+
+// Types re-exported for consumers who only import from hooks
+export type {
+  AuthMode,
+  Conversation,
+  Message,
+  ConversationWithMessages,
+  ChatErrorCode,
+  ChatErrorInfo,
+} from "../lib/types";
+export { AUTH_MODES, parseChatError } from "../lib/types";
+
+// Tool renderer types
+export type {
+  ToolRendererProps,
+  ToolRenderers,
+  SQLToolResult,
+  ExploreToolResult,
+  PythonToolResult,
+} from "../lib/tool-renderer-types";

package/src/hooks/provider.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+import type { AtlasAuthClient } from "../context";
+
+export type { AtlasAuthClient };
+
+export interface AtlasProviderProps {
+  /** Atlas API server URL (e.g. "https://api.example.com" or "" for same-origin). */
+  apiUrl: string;
+  /** API key for simple-key auth mode. Sent as Bearer token. Accessible in context by all hooks. */
+  apiKey?: string;
+  /** Custom auth client for managed auth mode (better-auth compatible). */
+  authClient?: AtlasAuthClient;
+  children: ReactNode;
+}
+
+export interface AtlasContextValue {
+  apiUrl: string;
+  apiKey: string | undefined;
+  authClient: AtlasAuthClient;
+  isCrossOrigin: boolean;
+}
+
+/** No-op auth client for non-managed auth modes. Warns when auth operations are attempted. */
+const noopAuthClient: AtlasAuthClient = {
+  signIn: {
+    email: async () => {
+      console.warn("[Atlas] signIn called but no authClient was provided to AtlasProvider");
+      return { error: { message: "Auth client not configured" } };
+    },
+  },
+  signUp: {
+    email: async () => {
+      console.warn("[Atlas] signUp called but no authClient was provided to AtlasProvider");
+      return { error: { message: "Auth client not configured" } };
+    },
+  },
+  signOut: async () => {
+    console.warn("[Atlas] signOut called but no authClient was provided to AtlasProvider");
+  },
+  useSession: () => ({ data: null, isPending: false }),
+};
+
+const AtlasContext = createContext<AtlasContextValue | null>(null);
+
+/** Access the AtlasProvider context. Throws if used outside <AtlasProvider>. */
+export function useAtlasContext(): AtlasContextValue {
+  const ctx = useContext(AtlasContext);
+  if (!ctx) throw new Error("useAtlasContext must be used within <AtlasProvider>");
+  return ctx;
+}
+
+/**
+ * Lightweight provider for headless Atlas hooks.
+ *
+ * Wraps your app and supplies API URL, auth credentials, and an optional
+ * better-auth client to all Atlas hooks. Derives isCrossOrigin from apiUrl
+ * to configure credential handling for cross-origin requests.
+ */
+export function AtlasProvider({
+  apiUrl,
+  apiKey,
+  authClient = noopAuthClient,
+  children,
+}: AtlasProviderProps) {
+  const isCrossOrigin =
+    typeof window !== "undefined" &&
+    apiUrl !== "" &&
+    !apiUrl.startsWith(window.location.origin);
+
+  return (
+    <AtlasContext.Provider value={{ apiUrl, apiKey, authClient, isCrossOrigin }}>
+      {children}
+    </AtlasContext.Provider>
+  );
+}

package/src/hooks/theme-init-script.ts

@@ -0,0 +1,17 @@
+/**
+ * Blocking inline script for layout.tsx — prevents dark-mode flash on load.
+ *
+ * This file intentionally has NO "use client" directive so it can be imported
+ * by server components (layout.tsx). The storage key must stay in sync with
+ * use-dark-mode.ts.
+ */
+
+export const THEME_STORAGE_KEY = "atlas-theme";
+
+/**
+ * Returns the inline script string for the blocking `<script>` in layout.tsx.
+ * Reads atlas-theme from localStorage and sets the `dark` class before first paint.
+ */
+export function buildThemeInitScript(): string {
+  return `try{var t=localStorage.getItem("${THEME_STORAGE_KEY}");var d=t==="dark"||(t!=="light"&&window.matchMedia("(prefers-color-scheme:dark)").matches);if(d)document.documentElement.classList.add("dark")}catch(e){}`;
+}

package/src/hooks/use-atlas-auth.ts

@@ -0,0 +1,131 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { useAtlasContext } from "./provider";
+import { AUTH_MODES, type AuthMode } from "../lib/types";
+
+export interface UseAtlasAuthReturn {
+  /** Auth mode detected from the server's /api/health endpoint. `null` while the initial health check is in flight. */
+  authMode: AuthMode | null;
+  /** Whether the user is authenticated (based on auth mode, API key, or session). */
+  isAuthenticated: boolean;
+  /** Session data for managed auth mode. */
+  session: { user?: { email?: string } } | null;
+  /** Whether auth state is still being resolved (health check or managed session loading). */
+  isLoading: boolean;
+  /** Error from health check or auth operations. `null` when healthy. */
+  error: Error | null;
+  /** Sign in with email/password (managed auth). */
+  login: (email: string, password: string) => Promise<{ error?: string }>;
+  /** Sign up with email/password/name (managed auth). */
+  signup: (email: string, password: string, name: string) => Promise<{ error?: string }>;
+  /** Sign out (managed auth). */
+  logout: () => Promise<{ error?: string }>;
+}
+
+export function useAtlasAuth(): UseAtlasAuthReturn {
+  const { apiUrl, apiKey, authClient, isCrossOrigin } = useAtlasContext();
+  const [authMode, setAuthMode] = useState<AuthMode | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const managedSession = authClient.useSession();
+
+  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(`[Atlas] Health check returned HTTP ${res.status} (attempt ${attempt})`);
+          if (attempt < 2 && !cancelled) {
+            await new Promise((r) => setTimeout(r, 2000));
+            return fetchHealth(attempt + 1);
+          }
+          if (!cancelled) {
+            setError(new Error(`Health check failed with HTTP ${res.status}`));
+            setAuthMode("none");
+          }
+          return;
+        }
+        const data = await res.json();
+        const mode = data?.checks?.auth?.mode;
+        if (!cancelled) {
+          if (typeof mode === "string" && AUTH_MODES.includes(mode as AuthMode)) {
+            setAuthMode(mode as AuthMode);
+          } else {
+            console.warn("[Atlas] Health check returned no valid auth mode:", data);
+            setAuthMode("none");
+          }
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[Atlas] Health check failed (attempt ${attempt}):`, message);
+        if (attempt < 2 && !cancelled) {
+          await new Promise((r) => setTimeout(r, 2000));
+          return fetchHealth(attempt + 1);
+        }
+        if (!cancelled) {
+          setError(err instanceof Error ? err : new Error(message));
+          setAuthMode("none");
+        }
+      }
+    }
+
+    fetchHealth(1);
+    return () => { cancelled = true; };
+  }, [apiUrl, isCrossOrigin]);
+
+  const isAuthenticated = (() => {
+    if (authMode === null) return false;
+    if (authMode === "none") return true;
+    if (authMode === "simple-key" || authMode === "byot") return !!apiKey;
+    if (authMode === "managed") return !!managedSession.data?.user;
+    return false;
+  })();
+
+  const login = async (email: string, password: string) => {
+    try {
+      const result = await authClient.signIn.email({ email, password });
+      return { error: result.error?.message };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Login failed";
+      console.warn("[Atlas] login error:", message);
+      return { error: message };
+    }
+  };
+
+  const signup = async (email: string, password: string, name: string) => {
+    try {
+      const result = await authClient.signUp.email({ email, password, name });
+      return { error: result.error?.message };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Signup failed";
+      console.warn("[Atlas] signup error:", message);
+      return { error: message };
+    }
+  };
+
+  const logout = async () => {
+    try {
+      await authClient.signOut();
+      return {};
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Logout failed";
+      console.warn("[Atlas] logout error:", message);
+      return { error: message };
+    }
+  };
+
+  return {
+    authMode,
+    isAuthenticated,
+    session: managedSession.data ?? null,
+    isLoading: authMode === null || (authMode === "managed" && !!managedSession.isPending),
+    error,
+    login,
+    signup,
+    logout,
+  };
+}