@nextsparkjs/theme-default 0.1.0-beta.1

package/lib/hooks/usePersistentChat.ts

@@ -0,0 +1,315 @@
+'use client'
+
+import { useState, useCallback, useEffect, useRef } from 'react'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { useTeamContext } from '@nextsparkjs/core/contexts/TeamContext'
+import { authClient } from '@nextsparkjs/core/lib/auth-client'
+
+export interface Message {
+    id: string
+    role: 'user' | 'assistant'
+    content: string
+    timestamp: number
+}
+
+interface ChatResponse {
+    success: boolean
+    data?: {
+        message: string
+        sessionId: string
+        isNewSession?: boolean
+    }
+    error?: string
+}
+
+interface HistoryResponse {
+    success: boolean
+    data?: {
+        sessionId: string
+        name: string | null
+        messageCount: number
+        isPinned: boolean
+        messages: Message[]
+    }
+    error?: string
+}
+
+interface ClearResponse {
+    success: boolean
+    message?: string
+    error?: string
+}
+
+const STORAGE_KEY = 'persistent-chat-messages'
+const CONVERSATIONS_QUERY_KEY = 'conversations'
+
+/**
+ * Persistent Chat Hook
+ *
+ * Manages chat messages for a specific conversation session.
+ * If sessionId is provided, uses that session.
+ * If not provided, creates a new session on first message.
+ *
+ * Features:
+ * - Loads message history from server when switching sessions
+ * - Caches messages in localStorage for quick UI
+ * - Supports multiple conversations
+ */
+export function usePersistentChat(externalSessionId?: string | null) {
+    const [messages, setMessages] = useState<Message[]>([])
+    const [input, setInput] = useState('')
+    const [error, setError] = useState<string | null>(null)
+    const [isInitialized, setIsInitialized] = useState(false)
+    const [isLoadingHistory, setIsLoadingHistory] = useState(false)
+    const lastLoadedSessionRef = useRef<string | null>(null)
+    const { currentTeam } = useTeamContext()
+    const queryClient = useQueryClient()
+
+    // Get current user session
+    const { data: session } = useQuery({
+        queryKey: ['session'],
+        queryFn: async () => {
+            const { data } = await authClient.getSession()
+            return data
+        },
+        staleTime: 1000 * 60 * 5, // 5 minutes
+    })
+
+    const userId = session?.user?.id
+    const teamId = currentTeam?.id
+
+    // Use external session ID if provided
+    const sessionId = externalSessionId || undefined
+
+    // Storage key is specific to the session
+    const storageKey = sessionId ? `${STORAGE_KEY}-${sessionId}` : null
+
+    // Load messages from localStorage when session changes
+    useEffect(() => {
+        if (!userId || !sessionId) {
+            setMessages([])
+            setIsInitialized(true)
+            return
+        }
+
+        // Already loaded this session
+        if (lastLoadedSessionRef.current === sessionId) {
+            return
+        }
+
+        // Try to load from localStorage first for instant UI
+        if (storageKey) {
+            try {
+                const stored = localStorage.getItem(storageKey)
+                if (stored) {
+                    const parsed = JSON.parse(stored) as Message[]
+                    setMessages(parsed)
+                } else {
+                    setMessages([])
+                }
+            } catch {
+                setMessages([])
+            }
+        }
+
+        setIsInitialized(true)
+        lastLoadedSessionRef.current = sessionId
+
+        // Then fetch from server to get the authoritative history
+        if (teamId) {
+            fetchHistory(sessionId)
+        }
+    }, [userId, sessionId, storageKey, teamId])
+
+    // Fetch message history from server
+    const fetchHistory = async (sid: string) => {
+        if (!teamId) return
+
+        setIsLoadingHistory(true)
+        try {
+            const headers: Record<string, string> = {
+                'Content-Type': 'application/json',
+                'x-team-id': teamId,
+            }
+
+            const response = await fetch(
+                `/api/v1/theme/default/ai/single-agent?sessionId=${encodeURIComponent(sid)}`,
+                { method: 'GET', headers }
+            )
+
+            if (response.ok) {
+                const data: HistoryResponse = await response.json()
+                if (data.success && data.data?.messages) {
+                    setMessages(data.data.messages)
+                    // Update localStorage
+                    if (storageKey) {
+                        try {
+                            localStorage.setItem(storageKey, JSON.stringify(data.data.messages))
+                        } catch {
+                            // Ignore
+                        }
+                    }
+                }
+            }
+        } catch {
+            // Ignore fetch errors, we have localStorage data
+        } finally {
+            setIsLoadingHistory(false)
+        }
+    }
+
+    // Save messages to localStorage when they change
+    useEffect(() => {
+        if (!storageKey || !isInitialized) return
+
+        try {
+            localStorage.setItem(storageKey, JSON.stringify(messages))
+        } catch {
+            // Ignore storage errors (quota exceeded, etc.)
+        }
+    }, [messages, storageKey, isInitialized])
+
+    const sendMutation = useMutation({
+        mutationFn: async (message: string): Promise<ChatResponse> => {
+            const headers: Record<string, string> = {
+                'Content-Type': 'application/json',
+            }
+
+            if (teamId) {
+                headers['x-team-id'] = teamId
+            }
+
+            const response = await fetch('/api/v1/theme/default/ai/single-agent', {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ message, sessionId }),
+            })
+
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({}))
+                throw new Error(errorData.error || 'Failed to send message')
+            }
+
+            return response.json()
+        },
+        onMutate: (message) => {
+            setError(null)
+            // Optimistic update - add user message immediately
+            const userMessage: Message = {
+                id: crypto.randomUUID(),
+                role: 'user',
+                content: message,
+                timestamp: Date.now(),
+            }
+            setMessages((prev) => [...prev, userMessage])
+            setInput('')
+        },
+        onSuccess: (data) => {
+            if (data.success && data.data) {
+                const aiMessage: Message = {
+                    id: crypto.randomUUID(),
+                    role: 'assistant',
+                    content: data.data.message,
+                    timestamp: Date.now(),
+                }
+                setMessages((prev) => [...prev, aiMessage])
+
+                // If a new session was created, invalidate conversations list
+                if (data.data.isNewSession) {
+                    queryClient.invalidateQueries({ queryKey: [CONVERSATIONS_QUERY_KEY] })
+                }
+            } else if (data.error) {
+                setError(data.error)
+            }
+        },
+        onError: (err: Error) => {
+            setError(err.message)
+            // Remove the optimistic user message on error
+            setMessages((prev) => prev.slice(0, -1))
+        },
+    })
+
+    const clearMutation = useMutation({
+        mutationFn: async (): Promise<ClearResponse> => {
+            if (!sessionId) {
+                throw new Error('No session to clear')
+            }
+
+            const headers: Record<string, string> = {
+                'Content-Type': 'application/json',
+            }
+
+            if (teamId) {
+                headers['x-team-id'] = teamId
+            }
+
+            const response = await fetch('/api/v1/theme/default/ai/single-agent', {
+                method: 'DELETE',
+                headers,
+                body: JSON.stringify({ sessionId }),
+            })
+
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({}))
+                throw new Error(errorData.error || 'Failed to clear session')
+            }
+
+            return response.json()
+        },
+        onSuccess: () => {
+            // Clear local messages
+            setMessages([])
+            setError(null)
+            setInput('')
+
+            // Clear localStorage for this session
+            if (storageKey) {
+                try {
+                    localStorage.removeItem(storageKey)
+                } catch {
+                    // Ignore
+                }
+            }
+
+            // Invalidate related queries
+            queryClient.invalidateQueries({ queryKey: ['chat-history'] })
+            queryClient.invalidateQueries({ queryKey: [CONVERSATIONS_QUERY_KEY] })
+        },
+        onError: (err: Error) => {
+            setError(`Failed to clear conversation: ${err.message}`)
+        },
+    })
+
+    const sendMessage = useCallback(() => {
+        if (!input.trim() || sendMutation.isPending) return
+        sendMutation.mutate(input)
+    }, [input, sendMutation])
+
+    const clearConversation = useCallback(() => {
+        if (clearMutation.isPending) return
+        clearMutation.mutate()
+    }, [clearMutation])
+
+    // Reload history from server
+    const reloadHistory = useCallback(() => {
+        if (sessionId && teamId) {
+            fetchHistory(sessionId)
+        }
+    }, [sessionId, teamId])
+
+    return {
+        messages,
+        input,
+        setInput,
+        error,
+        isLoading: sendMutation.isPending,
+        isClearing: clearMutation.isPending,
+        isLoadingHistory,
+        sendMessage,
+        clearConversation,
+        reloadHistory,
+        sessionId,
+        isReady: isInitialized && !!userId,
+        hasSession: !!sessionId,
+    }
+}

package/lib/hooks/useStreamingChat.ts

@@ -0,0 +1,127 @@
+'use client'
+
+import { useState, useCallback, useRef } from 'react'
+import { useTeamContext } from '@nextsparkjs/core/contexts/TeamContext'
+
+interface StreamChunk {
+    type: 'token' | 'done' | 'error' | 'tool_start' | 'tool_end'
+    content?: string
+    fullContent?: string
+    agentUsed?: string
+    tokenUsage?: {
+        inputTokens: number
+        outputTokens: number
+        totalTokens: number
+    }
+    error?: string
+    toolName?: string
+    result?: unknown
+}
+
+interface UseStreamingChatOptions {
+    agentName: string
+    sessionId?: string
+    onToken?: (token: string) => void
+    onComplete?: (fullContent: string) => void
+    onError?: (error: string) => void
+}
+
+export function useStreamingChat(options: UseStreamingChatOptions) {
+    const { agentName, sessionId, onToken, onComplete, onError } = options
+    const { currentTeam } = useTeamContext()
+
+    const [isStreaming, setIsStreaming] = useState(false)
+    const [partialContent, setPartialContent] = useState('')
+    const [error, setError] = useState<string | null>(null)
+    const abortControllerRef = useRef<AbortController | null>(null)
+
+    const streamMessage = useCallback(async (message: string) => {
+        setIsStreaming(true)
+        setPartialContent('')
+        setError(null)
+
+        abortControllerRef.current = new AbortController()
+
+        try {
+            const headers: Record<string, string> = {
+                'Content-Type': 'application/json'
+            }
+
+            // Include team context
+            if (currentTeam?.id) {
+                headers['x-team-id'] = currentTeam.id
+            }
+
+            const response = await fetch('/api/ai/chat/stream', {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ message, agentName, sessionId }),
+                signal: abortControllerRef.current.signal,
+            })
+
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`)
+            }
+
+            const reader = response.body?.getReader()
+            if (!reader) throw new Error('No response body')
+
+            const decoder = new TextDecoder()
+            let fullContent = ''
+
+            while (true) {
+                const { done, value } = await reader.read()
+                if (done) break
+
+                const text = decoder.decode(value)
+                const lines = text.split('\n')
+
+                for (const line of lines) {
+                    if (line.startsWith('data: ')) {
+                        const data = line.slice(6)
+                        if (data === '[DONE]') continue
+
+                        try {
+                            const chunk: StreamChunk = JSON.parse(data)
+
+                            if (chunk.type === 'token' && chunk.content) {
+                                fullContent += chunk.content
+                                setPartialContent(fullContent)
+                                onToken?.(chunk.content)
+                            } else if (chunk.type === 'done' && chunk.fullContent) {
+                                onComplete?.(chunk.fullContent)
+                            } else if (chunk.type === 'error' && chunk.error) {
+                                setError(chunk.error)
+                                onError?.(chunk.error)
+                            }
+                        } catch {
+                            // Ignore parse errors
+                        }
+                    }
+                }
+            }
+        } catch (err) {
+            if (err instanceof Error && err.name !== 'AbortError') {
+                const message = err.message
+                setError(message)
+                onError?.(message)
+            }
+        } finally {
+            setIsStreaming(false)
+            abortControllerRef.current = null
+        }
+    }, [agentName, sessionId, currentTeam?.id, onToken, onComplete, onError])
+
+    const cancel = useCallback(() => {
+        abortControllerRef.current?.abort()
+        setIsStreaming(false)
+    }, [])
+
+    return {
+        streamMessage,
+        isStreaming,
+        partialContent,
+        error,
+        cancel,
+    }
+}

package/lib/hooks/useTokenUsage.ts

@@ -0,0 +1,63 @@
+'use client'
+
+import { useQuery } from '@tanstack/react-query'
+import { useTeamContext } from '@nextsparkjs/core/contexts/TeamContext'
+
+type Period = 'today' | '7d' | '30d' | 'all'
+
+interface UsageStats {
+    totalTokens: number
+    totalCost: number
+    inputTokens: number
+    outputTokens: number
+    requestCount: number
+    byModel: Record<string, { tokens: number; cost: number }>
+}
+
+interface DailyUsage {
+    date: string
+    tokens: number
+    cost: number
+    requests: number
+}
+
+interface UsageResponse {
+    success: boolean
+    data: {
+        stats: UsageStats
+        daily: DailyUsage[]
+        period: Period
+        type: 'user' | 'team'
+    }
+    error?: string
+}
+
+export function useTokenUsage(period: Period = '30d', type: 'user' | 'team' = 'user') {
+    const { currentTeam } = useTeamContext()
+
+    return useQuery<UsageResponse>({
+        queryKey: ['ai-usage', period, type],
+        queryFn: async () => {
+            const headers: Record<string, string> = {
+                'Content-Type': 'application/json'
+            }
+
+            // Include team context
+            if (currentTeam?.id) {
+                headers['x-team-id'] = currentTeam.id
+            }
+
+            const response = await fetch(`/api/v1/theme/default/ai/usage?period=${period}&type=${type}`, {
+                headers
+            })
+
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({}))
+                throw new Error(errorData.error || 'Failed to fetch usage')
+            }
+
+            return response.json()
+        },
+        enabled: !!currentTeam?.id,
+    })
+}

package/lib/langchain/agents/customer-assistant.md

@@ -0,0 +1,69 @@
+You are a customer management AI assistant for the Boilerplate application.
+
+## CRITICAL RULE - MUST FOLLOW
+
+**YOU MUST ALWAYS USE TOOLS TO GET DATA. NEVER FABRICATE OR IMAGINE CUSTOMER INFORMATION.**
+
+Before responding with ANY customer information, you MUST:
+1. Call the appropriate tool (list_customers, search_customers, get_customer)
+2. Wait for the tool result
+3. ONLY THEN respond based on the REAL data from the tool
+
+If a tool returns an error or empty results, tell the user honestly - NEVER make up fake customers.
+
+## Your Capabilities
+- List, search, and view customer details (using tools)
+- Create new customers with all their information
+- Update existing customer data
+- Delete customers (with confirmation)
+
+## Customer Fields
+- **name**: Company or customer name (required)
+- **account**: Account number (required, numeric, must be unique)
+- **office**: Office location/branch (required)
+- **phone**: Contact phone number (optional)
+- **salesRep**: Assigned sales representative name (optional)
+- **visitDays**: Days for in-person visits - lun, mar, mie, jue, vie (optional)
+- **contactDays**: Days for phone/email contact - lun, mar, mie, jue, vie (optional)
+
+## Available Tools - USE THEM
+
+| Tool | When to use |
+|------|-------------|
+| **list_customers** | User asks to see customers, all clients |
+| **search_customers** | User wants to find specific customers by name, office, account |
+| **get_customer** | User asks about a specific customer by ID |
+| **create_customer** | User wants to create a new customer |
+| **update_customer** | User wants to modify an existing customer |
+| **delete_customer** | User wants to remove a customer |
+
+## Handling Contextual Updates
+
+When the user says "modificalo", "cambialo", "actualízalo" (modify it, change it, update it) with new data:
+1. Look at the conversation history to identify which customer they're referring to
+2. Get the customer ID from your previous search/get results
+3. Call update_customer with that ID and the new values
+4. Confirm the update with a link
+
+**Example:**
+- Previous context: You showed StartupXYZ (id: customer-everpoint-002, phone: +1 512 555 0102)
+- User: "modificalo, su nuevo telefono es +1 457 45465245"
+- YOU: Call update_customer with customerId="customer-everpoint-002" and phone="+1 457 45465245"
+
+## Correct Workflow
+
+1. User: "Show me customers from office Central"
+2. YOU: Call search_customers tool with query "Central"
+3. Tool returns: [{id: "1", name: "TechStart", account: 1001, office: "Central"}, ...]
+4. YOU: Format and show the REAL customers from the tool result
+
+## Response Format
+- Use Spanish when the user writes in Spanish, English otherwise
+- After creating or updating a customer, provide a link: [Customer Name](/dashboard/customers/{id})
+- When listing customers, summarize key info: name, office, salesRep
+- Always confirm before deleting a customer
+
+## What NOT to do
+- NEVER respond with example/fake customer data
+- NEVER imagine what customers the user might have
+- NEVER skip calling tools before responding about customers

package/lib/langchain/agents/index.ts

@@ -0,0 +1,61 @@
+import fs from 'fs'
+import path from 'path'
+
+const AGENTS_DIR = path.join(process.cwd(), 'contents/themes/default/lib/langchain/agents')
+
+/**
+ * Agent names that have .md prompt files in the agents directory.
+ */
+export type AgentName = 'orchestrator' | 'task-assistant' | 'customer-assistant' | 'page-assistant' | 'single-agent'
+
+/**
+ * Load a system prompt from markdown file
+ *
+ * @param agentName - Name of the agent (without .md extension)
+ * @returns The system prompt content as a string
+ * @throws Error if the agent prompt file is not found
+ *
+ * @example
+ * ```typescript
+ * const systemPrompt = loadSystemPrompt('task-assistant')
+ * const agent = await createAgent({ systemPrompt, ... })
+ * ```
+ */
+export function loadSystemPrompt(agentName: AgentName): string {
+    const filePath = path.join(AGENTS_DIR, `${agentName}.md`)
+
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`Agent prompt not found: ${agentName}. Expected file: ${filePath}`)
+    }
+
+    return fs.readFileSync(filePath, 'utf-8')
+}
+
+/**
+ * Get list of available agent names
+ *
+ * Scans the agents directory for .md files and returns their names
+ *
+ * @returns Array of agent names (without .md extension)
+ */
+export function getAvailableAgents(): string[] {
+    if (!fs.existsSync(AGENTS_DIR)) {
+        return []
+    }
+
+    const files = fs.readdirSync(AGENTS_DIR)
+    return files
+        .filter(f => f.endsWith('.md'))
+        .map(f => f.replace('.md', ''))
+}
+
+/**
+ * Check if an agent exists
+ *
+ * @param agentName - Name of the agent to check
+ * @returns true if the agent prompt file exists
+ */
+export function agentExists(agentName: string): boolean {
+    const filePath = path.join(AGENTS_DIR, `${agentName}.md`)
+    return fs.existsSync(filePath)
+}

package/lib/langchain/agents/orchestrator.md

@@ -0,0 +1,59 @@
+You are an AI Orchestrator that routes user requests to specialized agents.
+
+## CRITICAL RULE
+
+**YOU CAN ONLY DO TWO THINGS:**
+1. Call a routing tool (route_to_task, route_to_customer, route_to_page)
+2. Respond to simple greetings
+
+**NEVER claim to perform actions like creating, updating, or deleting data.** You don't have those tools. Only the specialized agents do.
+
+## Your Job
+
+1. Analyze the user's message AND the conversation history
+2. Decide which agent should handle it
+3. Call the appropriate routing tool OR respond to greetings only
+
+## Routing Rules
+
+**route_to_customer** - Use when:
+- User mentions customers, clients, accounts (cliente, customer, cuenta)
+- User wants to modify, update, or change something about a previously discussed customer
+- User references a customer from earlier in the conversation (e.g., "modificalo", "cambialo", "actualiza su...")
+
+**route_to_task** - Use when:
+- User mentions tasks, to-dos, work items (tarea, task, pendiente)
+- User wants to create, update, or list tasks
+- User asks for suggestions to add to a task
+
+**route_to_page** - Use when:
+- User mentions pages, content, website (página, page, contenido)
+- User wants to create or modify landing pages, blocks
+
+## Context Awareness
+
+**IMPORTANT:** When the user says "modificalo", "cambialo", "actualízalo", "bórralo" (modify it, change it, update it, delete it):
+- Look at the conversation history to determine WHAT they're referring to
+- If you were just discussing a customer → route_to_customer
+- If you were just discussing a task → route_to_task
+- If you were just discussing a page → route_to_page
+
+## Direct Response (ONLY for greetings)
+
+Respond directly ONLY for:
+- "Hola" → "¡Hola! ¿En qué puedo ayudarte?"
+- "Hello" → "Hello! How can I help you?"
+- "¿Quién eres?" → "Soy tu asistente para tareas, clientes y páginas."
+
+For EVERYTHING else, use a routing tool.
+
+## Examples
+
+| User says | Action |
+|-----------|--------|
+| "Hola" | Respond: "¡Hola! ¿En qué puedo ayudarte?" |
+| "Muéstrame mis tareas" | route_to_task |
+| "Para la tarea X, sugiereme recetas" | route_to_task |
+| "Lista de clientes" | route_to_customer |
+| "modificalo, su nuevo telefono es..." | route_to_customer (context: talking about customer) |
+| "Crea una landing page" | route_to_page |