@nextsparkjs/theme-default 0.1.0-beta.1

package/lib/langchain/tools/customers.ts

@@ -0,0 +1,176 @@
+import { z } from 'zod'
+import { ToolDefinition } from '@/plugins/langchain/lib/tools-builder'
+import { CustomersService } from '@/themes/default/entities/customers/customers.service'
+import type { DayOfWeek } from '@/themes/default/entities/customers/customers.types'
+
+/**
+ * Tool context for customer operations
+ */
+export interface CustomerToolContext {
+    userId: string
+    teamId: string
+}
+
+/**
+ * Create customer management tools for the AI agent
+ *
+ * @param context - User and team context for RLS
+ * @returns Array of customer-related tool definitions
+ */
+export function createCustomerTools(context: CustomerToolContext): ToolDefinition<any>[] {
+    const { userId, teamId } = context
+
+    return [
+        {
+            name: 'list_customers',
+            description: 'List all customers with optional pagination and sorting.',
+            schema: z.object({
+                limit: z.number().optional().default(20).describe('Max customers to return'),
+                offset: z.number().optional().default(0).describe('Offset for pagination'),
+                orderBy: z.enum(['name', 'account', 'office', 'salesRep', 'createdAt'])
+                    .optional()
+                    .describe('Field to order by'),
+                orderDir: z.enum(['asc', 'desc'])
+                    .optional()
+                    .describe('Order direction'),
+            }),
+            func: async (params) => {
+                try {
+                    const result = await CustomersService.list(userId, params)
+                    return JSON.stringify({
+                        customers: result.customers.map(c => ({
+                            id: c.id,
+                            name: c.name,
+                            account: c.account,
+                            office: c.office,
+                            salesRep: c.salesRep,
+                            phone: c.phone,
+                        })),
+                        total: result.total,
+                    }, null, 2)
+                } catch (error) {
+                    return `Error listing customers: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'search_customers',
+            description: 'Search customers by name, account number, office, or sales representative.',
+            schema: z.object({
+                query: z.string().describe('Search term to match against customer fields'),
+                limit: z.number().optional().default(10).describe('Max results to return'),
+            }),
+            func: async (params) => {
+                try {
+                    const results = await CustomersService.search(userId, params)
+                    return JSON.stringify(results.map(c => ({
+                        id: c.id,
+                        name: c.name,
+                        account: c.account,
+                        office: c.office,
+                        salesRep: c.salesRep,
+                        phone: c.phone,
+                    })), null, 2)
+                } catch (error) {
+                    return `Error searching customers: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'get_customer',
+            description: 'Get full details of a specific customer by ID.',
+            schema: z.object({
+                customerId: z.string().describe('The customer ID to retrieve'),
+            }),
+            func: async ({ customerId }) => {
+                try {
+                    const customer = await CustomersService.getById(customerId, userId)
+                    if (!customer) {
+                        return JSON.stringify({ error: 'Customer not found' })
+                    }
+                    return JSON.stringify(customer, null, 2)
+                } catch (error) {
+                    return `Error getting customer: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'create_customer',
+            description: 'Create a new customer. Name, account number, and office are required.',
+            schema: z.object({
+                name: z.string().describe('Customer or company name'),
+                account: z.number().describe('Unique account number'),
+                office: z.string().describe('Office location or branch'),
+                phone: z.string().optional().describe('Contact phone number'),
+                salesRep: z.string().optional().describe('Assigned sales representative'),
+                visitDays: z.array(z.enum(['lun', 'mar', 'mie', 'jue', 'vie']))
+                    .optional()
+                    .describe('Days for in-person visits'),
+                contactDays: z.array(z.enum(['lun', 'mar', 'mie', 'jue', 'vie']))
+                    .optional()
+                    .describe('Days for phone/email contact'),
+            }),
+            func: async (data) => {
+                try {
+                    const customer = await CustomersService.create(userId, {
+                        ...data,
+                        visitDays: data.visitDays as DayOfWeek[] | undefined,
+                        contactDays: data.contactDays as DayOfWeek[] | undefined,
+                        teamId,
+                    })
+                    return JSON.stringify(customer, null, 2)
+                } catch (error) {
+                    return `Error creating customer: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'update_customer',
+            description: 'Update an existing customer. Only specify fields you want to change.',
+            schema: z.object({
+                customerId: z.string().describe('The customer ID to update'),
+                name: z.string().optional().describe('New customer name'),
+                account: z.number().optional().describe('New account number'),
+                office: z.string().optional().describe('New office location'),
+                phone: z.string().optional().describe('New phone number'),
+                salesRep: z.string().optional().describe('New sales representative'),
+                visitDays: z.array(z.enum(['lun', 'mar', 'mie', 'jue', 'vie']))
+                    .optional()
+                    .describe('New visit days'),
+                contactDays: z.array(z.enum(['lun', 'mar', 'mie', 'jue', 'vie']))
+                    .optional()
+                    .describe('New contact days'),
+            }),
+            func: async ({ customerId, ...updates }) => {
+                try {
+                    const customer = await CustomersService.update(userId, customerId, {
+                        ...updates,
+                        visitDays: updates.visitDays as DayOfWeek[] | undefined,
+                        contactDays: updates.contactDays as DayOfWeek[] | undefined,
+                    })
+                    return JSON.stringify(customer, null, 2)
+                } catch (error) {
+                    return `Error updating customer: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'delete_customer',
+            description: 'Delete a customer permanently. This action cannot be undone.',
+            schema: z.object({
+                customerId: z.string().describe('The customer ID to delete'),
+            }),
+            func: async ({ customerId }) => {
+                try {
+                    const success = await CustomersService.delete(userId, customerId)
+                    return JSON.stringify({
+                        success,
+                        message: success ? 'Customer deleted successfully' : 'Failed to delete customer',
+                    })
+                } catch (error) {
+                    return `Error deleting customer: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+    ]
+}

package/lib/langchain/tools/index.ts

@@ -0,0 +1,10 @@
+/**
+ * LangChain Tools Index
+ *
+ * Central export point for all theme-specific AI agent tools.
+ */
+
+export { createTaskTools, type TaskToolContext } from './tasks'
+export { createCustomerTools, type CustomerToolContext } from './customers'
+export { createPageTools, type PageToolContext } from './pages'
+export { createOrchestratorTools, type AgentType, type RoutingResult, type ClarificationResult } from './orchestrator'

package/lib/langchain/tools/orchestrator.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod'
+import { ToolDefinition } from '@/plugins/langchain/lib/tools-builder'
+
+/**
+ * Agent types that can be routed to
+ */
+export type AgentType = 'task' | 'customer' | 'page'
+
+/**
+ * Routing result structure
+ */
+export interface RoutingResult {
+    agent: AgentType
+    message: string
+}
+
+/**
+ * Clarification result structure
+ */
+export interface ClarificationResult {
+    action: 'clarify'
+    question: string
+    options: Array<{ label: string; description: string }>
+}
+
+/**
+ * Create orchestrator routing tools
+ *
+ * These tools don't execute operations directly; they return routing decisions
+ * that the orchestrator handler uses to delegate to specialized agents.
+ */
+export function createOrchestratorTools(): ToolDefinition<any>[] {
+    return [
+        {
+            name: 'route_to_task',
+            description: 'Route the request to the task management agent. Use when the user wants to manage tasks, to-dos, work items, deadlines, or project-related items.',
+            schema: z.object({
+                message: z.string().describe('The user message to forward to the task agent'),
+            }),
+            func: async ({ message }) => {
+                return JSON.stringify({
+                    agent: 'task',
+                    message,
+                } as RoutingResult)
+            },
+        },
+        {
+            name: 'route_to_customer',
+            description: 'Route the request to the customer management agent. Use when the user wants to manage customers, clients, accounts, contacts, offices, sales representatives, or sales-related data.',
+            schema: z.object({
+                message: z.string().describe('The user message to forward to the customer agent'),
+            }),
+            func: async ({ message }) => {
+                return JSON.stringify({
+                    agent: 'customer',
+                    message,
+                } as RoutingResult)
+            },
+        },
+        {
+            name: 'route_to_page',
+            description: 'Route the request to the page/content management agent. Use when the user wants to manage pages, website content, blocks, landing pages, SEO, or publishing.',
+            schema: z.object({
+                message: z.string().describe('The user message to forward to the page agent'),
+            }),
+            func: async ({ message }) => {
+                return JSON.stringify({
+                    agent: 'page',
+                    message,
+                } as RoutingResult)
+            },
+        },
+        {
+            name: 'ask_clarification',
+            description: 'Ask the user for clarification when the request is ambiguous and you cannot determine which agent should handle it. Provide 2-3 specific options.',
+            schema: z.object({
+                question: z.string().describe('The clarification question to ask the user'),
+                options: z.array(z.object({
+                    label: z.string().describe('Short label for the option (e.g., "Tarea", "Cliente", "Página")'),
+                    description: z.string().describe('Brief description of what this option means'),
+                })).min(2).max(4).describe('Options to present to the user'),
+            }),
+            func: async ({ question, options }) => {
+                return JSON.stringify({
+                    action: 'clarify',
+                    question,
+                    options,
+                } as ClarificationResult)
+            },
+        },
+    ]
+}

package/lib/langchain/tools/pages.ts

@@ -0,0 +1,289 @@
+import { z } from 'zod'
+import { ToolDefinition } from '@/plugins/langchain/lib/tools-builder'
+import { PagesManagementService } from '@/themes/default/entities/pages/pages-management.service'
+import { BLOCK_REGISTRY } from '@nextsparkjs/registries/block-registry'
+
+/**
+ * Tool context for page operations
+ */
+export interface PageToolContext {
+    userId: string
+    teamId: string
+}
+
+/**
+ * Create page management tools for the AI agent
+ *
+ * @param context - User and team context for RLS
+ * @returns Array of page-related tool definitions
+ */
+export function createPageTools(context: PageToolContext): ToolDefinition<any>[] {
+    const { userId, teamId } = context
+
+    return [
+        // ============================================
+        // PAGE CRUD
+        // ============================================
+        {
+            name: 'list_pages',
+            description: 'List all pages with optional status filter.',
+            schema: z.object({
+                status: z.enum(['draft', 'published', 'all'])
+                    .optional()
+                    .default('all')
+                    .describe('Filter by page status'),
+                limit: z.number().optional().default(20).describe('Max pages to return'),
+                offset: z.number().optional().default(0).describe('Offset for pagination'),
+                locale: z.string().optional().describe('Filter by locale'),
+            }),
+            func: async (params) => {
+                try {
+                    const result = await PagesManagementService.list(userId, { ...params, teamId })
+                    return JSON.stringify({
+                        pages: result.pages.map(p => ({
+                            id: p.id,
+                            title: p.title,
+                            slug: p.slug,
+                            status: p.status,
+                            blockCount: p.blocks.length,
+                            locale: p.locale,
+                        })),
+                        total: result.total,
+                    }, null, 2)
+                } catch (error) {
+                    return `Error listing pages: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'get_page',
+            description: 'Get full page details including all blocks.',
+            schema: z.object({
+                pageId: z.string().describe('The page ID to retrieve'),
+            }),
+            func: async ({ pageId }) => {
+                try {
+                    const page = await PagesManagementService.getById(userId, pageId)
+                    if (!page) {
+                        return JSON.stringify({ error: 'Page not found' })
+                    }
+                    return JSON.stringify(page, null, 2)
+                } catch (error) {
+                    return `Error getting page: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'create_page',
+            description: 'Create a new page. Title and slug are required.',
+            schema: z.object({
+                title: z.string().describe('Page title'),
+                slug: z.string().describe('URL-friendly slug (lowercase, hyphens only)'),
+                locale: z.string().optional().default('en').describe('Page locale'),
+                status: z.enum(['draft', 'published'])
+                    .optional()
+                    .default('draft')
+                    .describe('Initial page status'),
+                seoTitle: z.string().optional().describe('SEO meta title'),
+                seoDescription: z.string().optional().describe('SEO meta description'),
+            }),
+            func: async (data) => {
+                try {
+                    const page = await PagesManagementService.create(userId, { ...data, teamId })
+                    return JSON.stringify(page, null, 2)
+                } catch (error) {
+                    return `Error creating page: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'update_page',
+            description: 'Update page metadata (title, slug, SEO). Does not modify blocks.',
+            schema: z.object({
+                pageId: z.string().describe('The page ID to update'),
+                title: z.string().optional().describe('New page title'),
+                slug: z.string().optional().describe('New URL slug'),
+                seoTitle: z.string().optional().describe('New SEO title'),
+                seoDescription: z.string().optional().describe('New SEO description'),
+            }),
+            func: async ({ pageId, ...updates }) => {
+                try {
+                    const page = await PagesManagementService.update(userId, pageId, updates)
+                    return JSON.stringify(page, null, 2)
+                } catch (error) {
+                    return `Error updating page: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'delete_page',
+            description: 'Delete a page permanently. This cannot be undone.',
+            schema: z.object({
+                pageId: z.string().describe('The page ID to delete'),
+            }),
+            func: async ({ pageId }) => {
+                try {
+                    const success = await PagesManagementService.delete(userId, pageId)
+                    return JSON.stringify({
+                        success,
+                        message: success ? 'Page deleted successfully' : 'Failed to delete page',
+                    })
+                } catch (error) {
+                    return `Error deleting page: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+
+        // ============================================
+        // BLOCK OPERATIONS
+        // ============================================
+        {
+            name: 'add_block',
+            description: 'Add a new block to a page. Use list_available_blocks to see available block types.',
+            schema: z.object({
+                pageId: z.string().describe('The page ID to add the block to'),
+                blockSlug: z.string().describe('Block type slug (e.g., hero, cta-section, features-grid)'),
+                props: z.record(z.string(), z.unknown())
+                    .optional()
+                    .default({})
+                    .describe('Block properties (title, content, etc.)'),
+                position: z.number()
+                    .optional()
+                    .describe('Position in the page (0 = first). Appends to end if not specified.'),
+            }),
+            func: async ({ pageId, blockSlug, props, position }) => {
+                try {
+                    const page = await PagesManagementService.addBlock(
+                        userId, pageId, blockSlug, props || {}, position
+                    )
+                    return JSON.stringify(page, null, 2)
+                } catch (error) {
+                    return `Error adding block: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'update_block',
+            description: 'Update a block properties. Only specify properties you want to change.',
+            schema: z.object({
+                pageId: z.string().describe('The page ID containing the block'),
+                blockId: z.string().describe('The block instance ID to update'),
+                props: z.record(z.string(), z.unknown()).describe('Properties to update (merged with existing)'),
+            }),
+            func: async ({ pageId, blockId, props }) => {
+                try {
+                    const page = await PagesManagementService.updateBlock(userId, pageId, blockId, props)
+                    return JSON.stringify(page, null, 2)
+                } catch (error) {
+                    return `Error updating block: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'remove_block',
+            description: 'Remove a block from a page.',
+            schema: z.object({
+                pageId: z.string().describe('The page ID containing the block'),
+                blockId: z.string().describe('The block instance ID to remove'),
+            }),
+            func: async ({ pageId, blockId }) => {
+                try {
+                    const page = await PagesManagementService.removeBlock(userId, pageId, blockId)
+                    return JSON.stringify(page, null, 2)
+                } catch (error) {
+                    return `Error removing block: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'reorder_blocks',
+            description: 'Reorder blocks in a page by providing the block IDs in the new order.',
+            schema: z.object({
+                pageId: z.string().describe('The page ID to reorder blocks in'),
+                blockIds: z.array(z.string()).describe('Block IDs in the desired order'),
+            }),
+            func: async ({ pageId, blockIds }) => {
+                try {
+                    const page = await PagesManagementService.reorderBlocks(userId, pageId, blockIds)
+                    return JSON.stringify(page, null, 2)
+                } catch (error) {
+                    return `Error reordering blocks: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+
+        // ============================================
+        // PUBLICATION
+        // ============================================
+        {
+            name: 'publish_page',
+            description: 'Publish a draft page to make it live and accessible.',
+            schema: z.object({
+                pageId: z.string().describe('The page ID to publish'),
+            }),
+            func: async ({ pageId }) => {
+                try {
+                    const page = await PagesManagementService.publish(userId, pageId)
+                    return JSON.stringify({
+                        ...page,
+                        message: `Page published successfully. View at: /p/${page.slug}`,
+                    }, null, 2)
+                } catch (error) {
+                    return `Error publishing page: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+        {
+            name: 'unpublish_page',
+            description: 'Unpublish a page (set to draft). It will no longer be publicly accessible.',
+            schema: z.object({
+                pageId: z.string().describe('The page ID to unpublish'),
+            }),
+            func: async ({ pageId }) => {
+                try {
+                    const page = await PagesManagementService.unpublish(userId, pageId)
+                    return JSON.stringify({
+                        ...page,
+                        message: 'Page unpublished successfully. It is now a draft.',
+                    }, null, 2)
+                } catch (error) {
+                    return `Error unpublishing page: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+
+        // ============================================
+        // DISCOVERY
+        // ============================================
+        {
+            name: 'list_available_blocks',
+            description: 'Get information about available block types that can be added to pages.',
+            schema: z.object({
+                category: z.string()
+                    .optional()
+                    .describe('Filter by category (hero, content, features, cta, testimonials, etc.)'),
+            }),
+            func: async ({ category }) => {
+                try {
+                    const allBlocks = Object.values(BLOCK_REGISTRY)
+                    const filteredBlocks = category
+                        ? allBlocks.filter(b => b.category === category)
+                        : allBlocks
+
+                    return JSON.stringify({
+                        blocks: filteredBlocks.map(b => ({
+                            slug: b.slug,
+                            name: b.name,
+                            description: b.description,
+                            category: b.category,
+                        })),
+                        total: filteredBlocks.length,
+                        categories: [...new Set(allBlocks.map(b => b.category))],
+                    }, null, 2)
+                } catch (error) {
+                    return `Error listing available blocks: ${error instanceof Error ? error.message : 'Unknown error'}`
+                }
+            },
+        },
+    ]
+}