@chaaskit/client 0.1.0

package/src/contexts/TeamContext.tsx

@@ -0,0 +1,255 @@
+import {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useCallback,
+  useRef,
+  type ReactNode,
+} from 'react';
+import { useSearchParams } from 'react-router';
+import type { TeamWithRole, TeamDetails, TeamInvite, TeamRole } from '@chaaskit/shared';
+import { api } from '../utils/api';
+import { useAuth } from './AuthContext';
+import { useConfig, useConfigLoaded } from './ConfigContext';
+
+interface TeamContextType {
+  teams: TeamWithRole[];
+  currentTeam: TeamDetails | null;
+  currentTeamId: string | null;
+  isLoadingTeams: boolean;
+  isLoadingTeamDetails: boolean;
+  loadTeams: () => Promise<void>;
+  loadTeamDetails: (teamId: string) => Promise<void>;
+  setCurrentTeamId: (teamId: string | null) => void;
+  createTeam: (name: string) => Promise<TeamDetails>;
+  updateTeam: (teamId: string, updates: { name?: string; context?: string | null }) => Promise<void>;
+  archiveTeam: (teamId: string) => Promise<void>;
+  inviteMember: (teamId: string, email: string, role: 'admin' | 'member' | 'viewer') => Promise<{ invite: TeamInvite; inviteUrl: string }>;
+  removeMember: (teamId: string, userId: string) => Promise<void>;
+  updateMemberRole: (teamId: string, userId: string, role: TeamRole) => Promise<void>;
+  leaveTeam: (teamId: string) => Promise<void>;
+  cancelInvite: (teamId: string, inviteId: string) => Promise<void>;
+  getCurrentTeamRole: () => TeamRole | null;
+}
+
+const TeamContext = createContext<TeamContextType | undefined>(undefined);
+
+export function TeamProvider({ children }: { children: ReactNode }) {
+  const { user } = useAuth();
+  const config = useConfig();
+  const configLoaded = useConfigLoaded();
+  const teamsEnabled = configLoaded ? (config.teams?.enabled ?? true) : false;
+  const [searchParams, setSearchParams] = useSearchParams();
+  const [teams, setTeams] = useState<TeamWithRole[]>([]);
+  const [currentTeam, setCurrentTeam] = useState<TeamDetails | null>(null);
+  const [currentTeamId, setCurrentTeamId] = useState<string | null>(() => {
+    // URL takes priority over localStorage
+    const urlTeam = searchParams.get('team');
+    if (urlTeam) return urlTeam;
+    return localStorage.getItem('currentTeamId');
+  });
+  const [isLoadingTeams, setIsLoadingTeams] = useState(false);
+  const [isLoadingTeamDetails, setIsLoadingTeamDetails] = useState(false);
+
+  const clearTeamSelection = useCallback(() => {
+    setCurrentTeamId(null);
+    setCurrentTeam(null);
+    localStorage.removeItem('currentTeamId');
+    setSearchParams((prev) => {
+      prev.delete('team');
+      return prev;
+    }, { replace: true });
+  }, [setSearchParams]);
+
+  const loadTeams = useCallback(async () => {
+    if (!user || !teamsEnabled) {
+      setTeams([]);
+      return;
+    }
+
+    setIsLoadingTeams(true);
+    try {
+      const response = await api.get<{ teams: TeamWithRole[] }>('/api/teams');
+      setTeams(response.teams);
+
+      // If current team is no longer available (invalid/archived or user not a member), clear it
+      if (currentTeamId && !response.teams.some((t) => t.id === currentTeamId)) {
+        clearTeamSelection();
+      }
+    } catch (error) {
+      console.error('Failed to load teams:', error);
+      setTeams([]);
+    } finally {
+      setIsLoadingTeams(false);
+    }
+  }, [user, teamsEnabled, currentTeamId, clearTeamSelection]);
+
+  const loadTeamDetails = useCallback(async (teamId: string) => {
+    if (!teamsEnabled) {
+      setCurrentTeam(null);
+      return;
+    }
+
+    setIsLoadingTeamDetails(true);
+    try {
+      const response = await api.get<{ team: TeamDetails }>(`/api/teams/${teamId}`);
+      setCurrentTeam(response.team);
+    } catch (error) {
+      console.error('Failed to load team details:', error);
+      setCurrentTeam(null);
+    } finally {
+      setIsLoadingTeamDetails(false);
+    }
+  }, [teamsEnabled]);
+
+  const handleSetCurrentTeamId = useCallback((teamId: string | null) => {
+    setCurrentTeamId(teamId);
+
+    // Update URL and localStorage
+    if (teamId) {
+      localStorage.setItem('currentTeamId', teamId);
+      setSearchParams((prev) => {
+        prev.set('team', teamId);
+        return prev;
+      }, { replace: true });
+    } else {
+      localStorage.removeItem('currentTeamId');
+      setCurrentTeam(null);
+      setSearchParams((prev) => {
+        prev.delete('team');
+        return prev;
+      }, { replace: true });
+    }
+  }, [setSearchParams]);
+
+  const createTeam = useCallback(async (name: string): Promise<TeamDetails> => {
+    const response = await api.post<{ team: TeamDetails }>('/api/teams', { name });
+    await loadTeams();
+    return response.team;
+  }, [loadTeams]);
+
+  const updateTeam = useCallback(async (teamId: string, updates: { name?: string; context?: string | null }) => {
+    await api.patch(`/api/teams/${teamId}`, updates);
+    await loadTeams();
+    if (currentTeamId === teamId) {
+      await loadTeamDetails(teamId);
+    }
+  }, [loadTeams, loadTeamDetails, currentTeamId]);
+
+  const archiveTeam = useCallback(async (teamId: string) => {
+    await api.post(`/api/teams/${teamId}/archive`, {});
+    if (currentTeamId === teamId) {
+      handleSetCurrentTeamId(null);
+    }
+    await loadTeams();
+  }, [loadTeams, currentTeamId, handleSetCurrentTeamId]);
+
+  const inviteMember = useCallback(async (
+    teamId: string,
+    email: string,
+    role: 'admin' | 'member' | 'viewer'
+  ): Promise<{ invite: TeamInvite; inviteUrl: string }> => {
+    const response = await api.post<{ invite: TeamInvite; inviteUrl: string }>(
+      `/api/teams/${teamId}/invite`,
+      { email, role }
+    );
+    if (currentTeamId === teamId) {
+      await loadTeamDetails(teamId);
+    }
+    return response;
+  }, [loadTeamDetails, currentTeamId]);
+
+  const removeMember = useCallback(async (teamId: string, userId: string) => {
+    await api.delete(`/api/teams/${teamId}/members/${userId}`);
+    await loadTeams();
+    if (currentTeamId === teamId) {
+      await loadTeamDetails(teamId);
+    }
+  }, [loadTeams, loadTeamDetails, currentTeamId]);
+
+  const updateMemberRole = useCallback(async (teamId: string, userId: string, role: TeamRole) => {
+    await api.patch(`/api/teams/${teamId}/members/${userId}`, { role });
+    if (currentTeamId === teamId) {
+      await loadTeamDetails(teamId);
+    }
+  }, [loadTeamDetails, currentTeamId]);
+
+  const leaveTeam = useCallback(async (teamId: string) => {
+    await api.post(`/api/teams/${teamId}/leave`, {});
+    if (currentTeamId === teamId) {
+      handleSetCurrentTeamId(null);
+    }
+    await loadTeams();
+  }, [loadTeams, currentTeamId, handleSetCurrentTeamId]);
+
+  const cancelInvite = useCallback(async (teamId: string, inviteId: string) => {
+    await api.delete(`/api/teams/${teamId}/invite/${inviteId}`);
+    if (currentTeamId === teamId) {
+      await loadTeamDetails(teamId);
+    }
+  }, [loadTeamDetails, currentTeamId]);
+
+  const getCurrentTeamRole = useCallback((): TeamRole | null => {
+    if (!currentTeamId) return null;
+    const team = teams.find((t) => t.id === currentTeamId);
+    return team?.role || null;
+  }, [teams, currentTeamId]);
+
+  // Track if user was ever logged in to distinguish logout from initial mount
+  const wasLoggedIn = useRef(false);
+
+  // Load teams when user changes and config is loaded
+  useEffect(() => {
+    if (user && configLoaded) {
+      wasLoggedIn.current = true;
+      loadTeams();
+    } else if (wasLoggedIn.current && !user) {
+      // Only clear on actual logout, not on initial mount
+      setTeams([]);
+      setCurrentTeam(null);
+      handleSetCurrentTeamId(null);
+    }
+  }, [user, configLoaded, loadTeams, handleSetCurrentTeamId]);
+
+  // Load team details when current team changes
+  useEffect(() => {
+    if (currentTeamId && configLoaded && teamsEnabled) {
+      loadTeamDetails(currentTeamId);
+    }
+  }, [currentTeamId, configLoaded, teamsEnabled, loadTeamDetails]);
+
+  return (
+    <TeamContext.Provider
+      value={{
+        teams,
+        currentTeam,
+        currentTeamId,
+        isLoadingTeams,
+        isLoadingTeamDetails,
+        loadTeams,
+        loadTeamDetails,
+        setCurrentTeamId: handleSetCurrentTeamId,
+        createTeam,
+        updateTeam,
+        archiveTeam,
+        inviteMember,
+        removeMember,
+        updateMemberRole,
+        leaveTeam,
+        cancelInvite,
+        getCurrentTeamRole,
+      }}
+    >
+      {children}
+    </TeamContext.Provider>
+  );
+}
+
+export function useTeam() {
+  const context = useContext(TeamContext);
+  if (context === undefined) {
+    throw new Error('useTeam must be used within a TeamProvider');
+  }
+  return context;
+}

package/src/contexts/ThemeContext.tsx

@@ -0,0 +1,113 @@
+import {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  type ReactNode,
+} from 'react';
+import { useConfig } from './ConfigContext';
+
+interface ThemeContextType {
+  theme: string;
+  setTheme: (theme: string) => void;
+  availableThemes: string[];
+}
+
+const ThemeContext = createContext<ThemeContextType | undefined>(undefined);
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const config = useConfig();
+  const [theme, setThemeState] = useState(() => {
+    // Check localStorage first, then config default
+    const stored = localStorage.getItem('theme');
+    if (stored && config.theming.themes[stored]) {
+      return stored;
+    }
+    return config.theming.defaultTheme;
+  });
+
+  const availableThemes = Object.keys(config.theming.themes);
+
+  useEffect(() => {
+    // Apply theme to document
+    document.documentElement.setAttribute('data-theme', theme);
+    localStorage.setItem('theme', theme);
+    // Set cookie for SSR to read
+    document.cookie = `theme=${theme};path=/;max-age=31536000;SameSite=Lax`;
+
+    // Apply theme colors as CSS variables
+    const themeConfig = config.theming.themes[theme];
+    if (themeConfig) {
+      const root = document.documentElement;
+      const colors = themeConfig.colors;
+
+      // Convert hex colors to RGB values
+      Object.entries(colors).forEach(([key, value]) => {
+        const cssKey = `--color-${key.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
+        const rgb = hexToRgb(value);
+        if (rgb) {
+          root.style.setProperty(cssKey, `${rgb.r} ${rgb.g} ${rgb.b}`);
+        }
+      });
+    }
+
+    // Apply fonts
+    document.documentElement.style.setProperty(
+      '--font-sans',
+      config.theming.fonts.sans
+    );
+    document.documentElement.style.setProperty(
+      '--font-mono',
+      config.theming.fonts.mono
+    );
+
+    // Apply border radius
+    document.documentElement.style.setProperty(
+      '--radius-sm',
+      config.theming.borderRadius.sm
+    );
+    document.documentElement.style.setProperty(
+      '--radius-md',
+      config.theming.borderRadius.md
+    );
+    document.documentElement.style.setProperty(
+      '--radius-lg',
+      config.theming.borderRadius.lg
+    );
+    document.documentElement.style.setProperty(
+      '--radius-full',
+      config.theming.borderRadius.full
+    );
+  }, [theme, config.theming]);
+
+  function setTheme(newTheme: string) {
+    if (config.theming.themes[newTheme]) {
+      setThemeState(newTheme);
+    }
+  }
+
+  return (
+    <ThemeContext.Provider value={{ theme, setTheme, availableThemes }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (context === undefined) {
+    throw new Error('useTheme must be used within a ThemeProvider');
+  }
+  return context;
+}
+
+function hexToRgb(hex: string): { r: number; g: number; b: number } | null {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result
+    ? {
+        r: parseInt(result[1]!, 16),
+        g: parseInt(result[2]!, 16),
+        b: parseInt(result[3]!, 16),
+      }
+    : null;
+}

package/src/extensions/index.ts

@@ -0,0 +1,15 @@
+// Client extension system for @chaaskit/client
+export {
+  clientRegistry,
+  type PageExtension,
+  type ToolExtension,
+  type ComponentOverride,
+} from './registry';
+
+export {
+  useExtensionPages,
+  useSidebarPages,
+  useExtensionTools,
+  useToolRenderer,
+  useComponentOverride,
+} from './useExtensions';

package/src/extensions/registry.ts

@@ -0,0 +1,187 @@
+import type { ComponentType } from 'react';
+
+/**
+ * Page extension configuration
+ */
+export interface PageExtension {
+  /** Unique identifier for the page */
+  id: string;
+  /** URL path for the page (e.g., "/analytics") */
+  path: string;
+  /** Display label for navigation */
+  label: string;
+  /** Optional icon name from lucide-react */
+  icon?: string;
+  /** React component to render for this page */
+  component: ComponentType;
+  /** Whether to show in the sidebar navigation */
+  showInSidebar?: boolean;
+  /** Whether this page requires authentication */
+  requiresAuth?: boolean;
+  /** Whether this page requires admin access */
+  requiresAdmin?: boolean;
+}
+
+/**
+ * Tool result renderer extension
+ */
+export interface ToolExtension {
+  /** Tool name to match */
+  name: string;
+  /** Description of the tool */
+  description: string;
+  /** Custom renderer for tool results */
+  resultRenderer?: ComponentType<{ result: unknown }>;
+}
+
+/**
+ * Component override extension
+ */
+export interface ComponentOverride {
+  /** Component slot to override */
+  slot: 'header' | 'footer' | 'sidebar-header' | 'sidebar-footer' | 'message-actions';
+  /** Component to render in the slot */
+  component: ComponentType<Record<string, unknown>>;
+}
+
+/**
+ * Client-side extension registry for customizing the ChaasKit UI
+ *
+ * Note: getPages(), getSidebarPages(), and getTools() cache their results
+ * to support React's useSyncExternalStore which requires stable references.
+ */
+class ClientExtensionRegistry {
+  private pages: Map<string, PageExtension> = new Map();
+  private tools: Map<string, ToolExtension> = new Map();
+  private overrides: Map<string, ComponentOverride> = new Map();
+  private listeners: Set<() => void> = new Set();
+
+  // Cached arrays for useSyncExternalStore compatibility
+  // These are only updated when the underlying data changes
+  private cachedPages: PageExtension[] = [];
+  private cachedSidebarPages: PageExtension[] = [];
+  private cachedTools: ToolExtension[] = [];
+
+  /**
+   * Register a custom page
+   */
+  registerPage(page: PageExtension): void {
+    this.pages.set(page.id, page);
+    this.invalidateCaches();
+    this.notifyListeners();
+  }
+
+  /**
+   * Unregister a custom page
+   */
+  unregisterPage(id: string): boolean {
+    const result = this.pages.delete(id);
+    if (result) {
+      this.invalidateCaches();
+      this.notifyListeners();
+    }
+    return result;
+  }
+
+  /**
+   * Get all registered pages
+   * Returns a cached array for useSyncExternalStore compatibility
+   */
+  getPages(): PageExtension[] {
+    return this.cachedPages;
+  }
+
+  /**
+   * Get pages that should appear in the sidebar
+   * Returns a cached array for useSyncExternalStore compatibility
+   */
+  getSidebarPages(): PageExtension[] {
+    return this.cachedSidebarPages;
+  }
+
+  /**
+   * Register a custom tool renderer
+   */
+  registerTool(tool: ToolExtension): void {
+    this.tools.set(tool.name, tool);
+    this.invalidateCaches();
+    this.notifyListeners();
+  }
+
+  /**
+   * Unregister a tool renderer
+   */
+  unregisterTool(name: string): boolean {
+    const result = this.tools.delete(name);
+    if (result) {
+      this.invalidateCaches();
+      this.notifyListeners();
+    }
+    return result;
+  }
+
+  /**
+   * Get all registered tools
+   * Returns a cached array for useSyncExternalStore compatibility
+   */
+  getTools(): ToolExtension[] {
+    return this.cachedTools;
+  }
+
+  /**
+   * Get a specific tool by name
+   */
+  getTool(name: string): ToolExtension | undefined {
+    return this.tools.get(name);
+  }
+
+  /**
+   * Register a component override
+   */
+  registerOverride(override: ComponentOverride): void {
+    this.overrides.set(override.slot, override);
+    this.notifyListeners();
+  }
+
+  /**
+   * Get a component override for a slot
+   */
+  getOverride(slot: string): ComponentOverride | undefined {
+    return this.overrides.get(slot);
+  }
+
+  /**
+   * Subscribe to registry changes
+   */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private invalidateCaches(): void {
+    this.cachedPages = Array.from(this.pages.values());
+    this.cachedSidebarPages = this.cachedPages.filter(p => p.showInSidebar);
+    this.cachedTools = Array.from(this.tools.values());
+  }
+
+  private notifyListeners(): void {
+    this.listeners.forEach(listener => listener());
+  }
+
+  /**
+   * Clear all registered extensions
+   */
+  clear(): void {
+    this.pages.clear();
+    this.tools.clear();
+    this.overrides.clear();
+    this.invalidateCaches();
+    this.notifyListeners();
+  }
+}
+
+// Singleton instance
+export const clientRegistry = new ClientExtensionRegistry();
+
+// Export for use in user extensions
+export default clientRegistry;

package/src/extensions/useExtensions.ts

@@ -0,0 +1,52 @@
+import { useSyncExternalStore, useCallback } from 'react';
+import { clientRegistry, type PageExtension, type ToolExtension, type ComponentOverride } from './registry';
+
+/**
+ * Hook to access extension pages with automatic updates
+ */
+export function useExtensionPages(): PageExtension[] {
+  const getSnapshot = useCallback(() => clientRegistry.getPages(), []);
+  const subscribe = useCallback((callback: () => void) => clientRegistry.subscribe(callback), []);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * Hook to access sidebar pages with automatic updates
+ */
+export function useSidebarPages(): PageExtension[] {
+  const getSnapshot = useCallback(() => clientRegistry.getSidebarPages(), []);
+  const subscribe = useCallback((callback: () => void) => clientRegistry.subscribe(callback), []);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * Hook to access extension tools with automatic updates
+ */
+export function useExtensionTools(): ToolExtension[] {
+  const getSnapshot = useCallback(() => clientRegistry.getTools(), []);
+  const subscribe = useCallback((callback: () => void) => clientRegistry.subscribe(callback), []);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * Hook to get a specific tool renderer
+ */
+export function useToolRenderer(toolName: string): ToolExtension | undefined {
+  const getSnapshot = useCallback(() => clientRegistry.getTool(toolName), [toolName]);
+  const subscribe = useCallback((callback: () => void) => clientRegistry.subscribe(callback), []);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * Hook to get a component override
+ */
+export function useComponentOverride(slot: string): ComponentOverride | undefined {
+  const getSnapshot = useCallback(() => clientRegistry.getOverride(slot), [slot]);
+  const subscribe = useCallback((callback: () => void) => clientRegistry.subscribe(callback), []);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/src/hooks/useAppPath.ts

@@ -0,0 +1,34 @@
+import { useCallback } from 'react';
+import { useConfig } from '../contexts/ConfigContext';
+
+/**
+ * Returns a memoized function to build paths with the configured basePath.
+ * Use this for all internal navigation within the authenticated app.
+ *
+ * @example
+ * const appPath = useAppPath();
+ * navigate(appPath('/'));  // Goes to /chat (or whatever basePath is configured)
+ * navigate(appPath('/thread/123'));  // Goes to /chat/thread/123
+ */
+export function useAppPath(): (path: string) => string {
+  const config = useConfig();
+  // Default to /chat if basePath is undefined, null, or empty string
+  const configBasePath = config?.app?.basePath;
+  const basePath = configBasePath && configBasePath.trim() !== '' ? configBasePath : '/chat';
+
+  return useCallback(
+    (path: string) => {
+      // Remove leading slash from path if basePath already ends with one
+      const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
+      const normalizedBase = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+
+      // Handle root path
+      if (!normalizedPath || normalizedPath === '') {
+        return normalizedBase;
+      }
+
+      return `${normalizedBase}/${normalizedPath}`;
+    },
+    [basePath]
+  );
+}

package/src/hooks/useBasePath.ts

@@ -0,0 +1,13 @@
+import { useConfig } from '../contexts/ConfigContext';
+
+/**
+ * Returns the configured basePath for the application.
+ * Useful for building absolute URLs or for components that need
+ * to know the base path for external navigation.
+ */
+export function useBasePath(): string {
+  const config = useConfig();
+  // Return basePath if configured and non-empty, otherwise default to /chat
+  const configBasePath = config?.app?.basePath;
+  return configBasePath && configBasePath.trim() !== '' ? configBasePath : '/chat';
+}