@nextsparkjs/plugin-ai 0.1.0-beta.1

package/lib/ai-history-service.ts

@@ -0,0 +1,391 @@
+/**
+ * AI History Service
+ *
+ * Manages audit trail for all AI operations across plugins.
+ * Provides consistent logging interface with status tracking.
+ *
+ * Lifecycle:
+ * 1. startOperation() → status='pending'
+ * 2. updateToProcessing() → status='processing' (optional)
+ * 3. completeOperation() → status='completed' + metrics
+ * 4. failOperation() → status='failed' + error
+ */
+
+import { query, queryOne } from '@nextsparkjs/core/lib/db'
+import { AIHistoryMetaService } from './ai-history-meta-service'
+
+export type AIOperation = 'generate' | 'refine' | 'analyze' | 'chat' | 'completion' | 'other'
+export type AIProvider = 'anthropic' | 'openai' | 'google' | 'azure' | 'other'
+export type AIStatus = 'pending' | 'processing' | 'completed' | 'failed'
+
+export interface StartOperationParams {
+  userId: string
+  operation: AIOperation
+  model: string
+  provider?: AIProvider
+  relatedEntityType?: string
+  relatedEntityId?: string
+  // NOTE: Metadata should be stored in ai_history_metas table via completeOperation(metas)
+  // NOT in startOperation() - ai_history table has no metadata column
+}
+
+export interface CompleteOperationParams {
+  historyId: string
+  tokensUsed: number
+  tokensInput?: number // Input tokens (prompt) - for precise cost calculation
+  tokensOutput?: number // Output tokens (completion) - for precise cost calculation
+  creditsUsed: number
+  estimatedCost: number
+  balanceAfter: number
+  userId: string // ✅ NEW: Required for metadata operations
+  metas?: Record<string, unknown> // ✅ NEW: Flexible metadata (sourceOperationId, userInstruction, etc.)
+}
+
+export interface FailOperationParams {
+  historyId: string
+  errorMessage: string
+  tokensUsed?: number
+}
+
+export interface AIHistoryRecord {
+  id: string
+  userId: string
+  relatedEntityType: string | null
+  relatedEntityId: string | null
+  operation: AIOperation
+  model: string
+  provider: AIProvider
+  status: AIStatus
+  tokensUsed: number | null
+  creditsUsed: number | null
+  estimatedCost: number | null
+  balanceAfter: number | null
+  errorMessage: string | null
+  createdAt: Date
+  completedAt: Date | null
+}
+
+export class AIHistoryService {
+  /**
+   * Start tracking an AI operation
+   * Creates initial record with status='pending'
+   *
+   * @returns History ID for subsequent updates
+   */
+  static async startOperation(params: StartOperationParams): Promise<string> {
+    const {
+      userId,
+      operation,
+      model,
+      provider = 'anthropic',
+      relatedEntityType,
+      relatedEntityId,
+    } = params
+
+    try {
+      const result = await queryOne<{ id: string }>(
+        `INSERT INTO "ai_history" (
+          "userId",
+          operation,
+          model,
+          provider,
+          "relatedEntityType",
+          "relatedEntityId",
+          status,
+          "createdAt"
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, now())
+        RETURNING id`,
+        [userId, operation, model, provider, relatedEntityType || null, relatedEntityId || null, 'pending']
+      )
+
+      if (!result) {
+        throw new Error('Failed to create AI history record')
+      }
+
+      return result.id
+    } catch (error) {
+      console.error('Error starting AI operation tracking:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Update operation to 'processing' status (optional)
+   * Useful for long-running operations
+   */
+  static async updateToProcessing(historyId: string): Promise<void> {
+    try {
+      await query(
+        `UPDATE "ai_history"
+         SET status = 'processing'
+         WHERE id = $1`,
+        [historyId]
+      )
+    } catch (error) {
+      console.error('Error updating AI history to processing:', error)
+      // Non-critical, don't throw
+    }
+  }
+
+  /**
+   * Complete operation successfully
+   * Updates status='completed', adds metrics, and saves metadata
+   */
+  static async completeOperation(params: CompleteOperationParams): Promise<void> {
+    const { historyId, tokensUsed, tokensInput, tokensOutput, creditsUsed, estimatedCost, balanceAfter, userId, metas } = params
+
+    try {
+      // Update main ai_history record
+      await query(
+        `UPDATE "ai_history"
+         SET status = 'completed',
+             "tokensUsed" = $2,
+             "tokensInput" = $3,
+             "tokensOutput" = $4,
+             "creditsUsed" = $5,
+             "estimatedCost" = $6,
+             "balanceAfter" = $7,
+             "completedAt" = now()
+         WHERE id = $1`,
+        [historyId, tokensUsed, tokensInput || null, tokensOutput || null, creditsUsed, estimatedCost, balanceAfter]
+      )
+
+      // Save metadata to ai_history_metas table
+      if (metas && Object.keys(metas).length > 0) {
+        await AIHistoryMetaService.setBulkMetas(
+          historyId,
+          metas,
+          userId,
+          { isPublic: false, isSearchable: true }
+        )
+      }
+    } catch (error) {
+      console.error('Error completing AI operation:', error)
+      // Log but don't throw - operation succeeded even if history update failed
+    }
+  }
+
+  /**
+   * Mark operation as failed
+   * Updates status='failed' and adds error message
+   */
+  static async failOperation(params: FailOperationParams): Promise<void> {
+    const { historyId, errorMessage, tokensUsed } = params
+
+    try {
+      await query(
+        `UPDATE "ai_history"
+         SET status = 'failed',
+             "errorMessage" = $2,
+             "tokensUsed" = $3,
+             "completedAt" = now()
+         WHERE id = $1`,
+        [historyId, errorMessage, tokensUsed || null]
+      )
+    } catch (error) {
+      console.error('Error marking AI operation as failed:', error)
+      // Log but don't throw - we're already in error handling
+    }
+  }
+
+  /**
+   * Update related entity information for an existing operation
+   * Useful when entity is created AFTER AI operation starts (e.g., analyze-brief)
+   *
+   * Use case: analyze-brief runs before client exists, then client is created,
+   * and we need to link the AI history record to the newly created client.
+   *
+   * @param historyId - AI history record ID to update
+   * @param relatedEntityType - Entity type (e.g., 'clients', 'products')
+   * @param relatedEntityId - Entity ID (UUID)
+   */
+  static async updateRelatedEntity(
+    historyId: string,
+    relatedEntityType: string,
+    relatedEntityId: string
+  ): Promise<void> {
+    try {
+      await query(
+        `UPDATE "ai_history"
+         SET "relatedEntityType" = $2,
+             "relatedEntityId" = $3
+         WHERE id = $1`,
+        [historyId, relatedEntityType, relatedEntityId]
+      )
+    } catch (error) {
+      console.error('Error updating AI history related entity:', error)
+      // Log but don't throw - non-critical update
+    }
+  }
+
+  /**
+   * Get operation history for a user
+   * Useful for displaying usage analytics
+   */
+  static async getUserHistory(
+    userId: string,
+    options?: {
+      limit?: number
+      offset?: number
+      operation?: AIOperation
+      status?: AIStatus
+    }
+  ): Promise<AIHistoryRecord[]> {
+    const { limit = 50, offset = 0, operation, status } = options || {}
+
+    try {
+      let sql = `
+        SELECT * FROM "ai_history"
+        WHERE "userId" = $1
+      `
+      const params: any[] = [userId]
+      let paramIndex = 2
+
+      if (operation) {
+        sql += ` AND operation = $${paramIndex}`
+        params.push(operation)
+        paramIndex++
+      }
+
+      if (status) {
+        sql += ` AND status = $${paramIndex}`
+        params.push(status)
+        paramIndex++
+      }
+
+      sql += ` ORDER BY "createdAt" DESC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`
+      params.push(limit, offset)
+
+      const result = await query<AIHistoryRecord>(sql, params)
+      return result.rows
+    } catch (error) {
+      console.error('Error getting user AI history:', error)
+      return []
+    }
+  }
+
+  /**
+   * Get history for a specific related entity
+   * Useful for showing AI operations on a content/product/etc
+   */
+  static async getEntityHistory(
+    entityType: string,
+    entityId: string,
+    options?: {
+      limit?: number
+      operation?: AIOperation
+    }
+  ): Promise<AIHistoryRecord[]> {
+    const { limit = 20, operation } = options || {}
+
+    try {
+      let sql = `
+        SELECT * FROM "ai_history"
+        WHERE "relatedEntityType" = $1 AND "relatedEntityId" = $2
+      `
+      const params: any[] = [entityType, entityId]
+      let paramIndex = 3
+
+      if (operation) {
+        sql += ` AND operation = $${paramIndex}`
+        params.push(operation)
+        paramIndex++
+      }
+
+      sql += ` ORDER BY "createdAt" DESC LIMIT $${paramIndex}`
+      params.push(limit)
+
+      const result = await query<AIHistoryRecord>(sql, params)
+      return result.rows
+    } catch (error) {
+      console.error('Error getting entity AI history:', error)
+      return []
+    }
+  }
+
+  /**
+   * Get operation by ID
+   */
+  static async getOperation(historyId: string): Promise<AIHistoryRecord | null> {
+    try {
+      return await queryOne<AIHistoryRecord>(
+        'SELECT * FROM "ai_history" WHERE id = $1',
+        [historyId]
+      )
+    } catch (error) {
+      console.error('Error getting AI operation:', error)
+      return null
+    }
+  }
+
+  /**
+   * Get usage statistics for a user
+   * Useful for analytics dashboards
+   */
+  static async getUserStats(userId: string, fromDate?: Date): Promise<{
+    totalOperations: number
+    totalTokens: number
+    totalCredits: number
+    totalCost: number
+    successRate: number
+    operationBreakdown: Record<AIOperation, number>
+  }> {
+    try {
+      let sql = `
+        SELECT
+          COUNT(*) as total_operations,
+          COALESCE(SUM("tokensUsed"), 0) as total_tokens,
+          COALESCE(SUM("creditsUsed"), 0) as total_credits,
+          COALESCE(SUM("estimatedCost"), 0) as total_cost,
+          COUNT(*) FILTER (WHERE status = 'completed') as completed,
+          operation
+        FROM "ai_history"
+        WHERE "userId" = $1
+      `
+      const params: any[] = [userId]
+
+      if (fromDate) {
+        sql += ` AND "createdAt" >= $2`
+        params.push(fromDate)
+      }
+
+      sql += ` GROUP BY operation`
+
+      const result = await query<{
+        total_operations: string
+        total_tokens: string
+        total_credits: string
+        total_cost: string
+        completed: string
+        operation: AIOperation
+      }>(sql, params)
+
+      const totalOps = result.rows.reduce((sum, r) => sum + parseInt(r.total_operations), 0)
+      const totalCompleted = result.rows.reduce((sum, r) => sum + parseInt(r.completed), 0)
+
+      const operationBreakdown: Record<string, number> = {}
+      result.rows.forEach(row => {
+        operationBreakdown[row.operation] = parseInt(row.total_operations)
+      })
+
+      return {
+        totalOperations: totalOps,
+        totalTokens: result.rows.reduce((sum, r) => sum + parseInt(r.total_tokens || '0'), 0),
+        totalCredits: result.rows.reduce((sum, r) => sum + parseInt(r.total_credits || '0'), 0),
+        totalCost: result.rows.reduce((sum, r) => sum + parseFloat(r.total_cost || '0'), 0),
+        successRate: totalOps > 0 ? (totalCompleted / totalOps) * 100 : 0,
+        operationBreakdown: operationBreakdown as Record<AIOperation, number>,
+      }
+    } catch (error) {
+      console.error('Error getting user AI stats:', error)
+      return {
+        totalOperations: 0,
+        totalTokens: 0,
+        totalCredits: 0,
+        totalCost: 0,
+        successRate: 0,
+        operationBreakdown: {} as Record<AIOperation, number>,
+      }
+    }
+  }
+}

package/lib/ai-sdk.ts

@@ -0,0 +1,7 @@
+/**
+ * Re-exports from Vercel AI SDK for use in themes and other plugins
+ * This allows the 'ai' package to be isolated to the AI plugin workspace
+ */
+
+export { generateObject, generateText, streamText, streamObject } from 'ai'
+export type { CoreMessage, LanguageModel } from 'ai'

package/lib/core-utils.ts

@@ -0,0 +1,217 @@
+/**
+ * AI Plugin Core Utilities
+ *
+ * Simple, direct functions for building AI endpoints
+ * No dynamic imports, no complex abstractions
+ */
+
+import { createOpenAI } from '@ai-sdk/openai'
+import { createAnthropic } from '@ai-sdk/anthropic'
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible'
+import type { AIProvider, ModelSelection, AIResult } from '../types/ai.types'
+import {
+  getServerPluginConfig,
+  isServerPluginEnabled,
+  validateServerPluginEnvironment
+} from './server-env'
+
+// Cost per 1K tokens (USD)
+export const COST_CONFIG = {
+  // OpenAI models
+  'gpt-4o': { input: 0.0025, output: 0.01 },
+  'gpt-4o-mini': { input: 0.00015, output: 0.0006 },
+  'gpt-4-turbo': { input: 0.01, output: 0.03 },
+  'gpt-3.5-turbo': { input: 0.0005, output: 0.0015 },
+
+  // Anthropic models
+  'claude-sonnet-4-5-20250929': { input: 0.003, output: 0.015 }, // Current (Sept 2025)
+  'claude-3-5-sonnet-20241022': { input: 0.003, output: 0.015 }, // Deprecated Oct 28, 2025
+  'claude-3-5-haiku-20241022': { input: 0.00025, output: 0.00125 },
+  'claude-3-opus-20240229': { input: 0.015, output: 0.075 },
+
+  // Ollama models (local, no cost)
+  'llama3.2:3b': { input: 0, output: 0 },
+  'llama3.2': { input: 0, output: 0 },
+  'llama3.1': { input: 0, output: 0 },
+  'qwen2.5': { input: 0, output: 0 },
+  'mistral': { input: 0, output: 0 },
+  'gemma2': { input: 0, output: 0 },
+  'phi3.5': { input: 0, output: 0 },
+  'codellama': { input: 0, output: 0 }
+}
+
+/**
+ * Select AI model and provider
+ */
+export async function selectModel(modelName: string, provider?: AIProvider): Promise<ModelSelection> {
+  // Auto-detect provider if not specified
+  if (!provider) {
+    if (modelName.startsWith('gpt-')) {
+      provider = 'openai'
+    } else if (modelName.startsWith('claude-')) {
+      provider = 'anthropic'
+    } else {
+      provider = 'ollama'
+    }
+  }
+
+  console.log(`🎯 [selectModel] Selected provider: ${provider}, model: ${modelName}`)
+
+  const costConfig = COST_CONFIG[modelName as keyof typeof COST_CONFIG] || { input: 0, output: 0 }
+  const config = await getServerPluginConfig()
+
+  switch (provider) {
+    case 'openai':
+      if (!config.openaiApiKey) {
+        throw new Error('OpenAI API key not configured. Set OPENAI_API_KEY in contents/plugins/ai/.env')
+      }
+      const openaiProvider = createOpenAI({
+        apiKey: config.openaiApiKey
+      })
+      return {
+        provider: 'openai',
+        model: openaiProvider(modelName),
+        modelName,
+        isLocal: false,
+        costConfig
+      }
+
+    case 'anthropic':
+      if (!config.anthropicApiKey) {
+        throw new Error('Anthropic API key not configured. Set ANTHROPIC_API_KEY in contents/plugins/ai/.env')
+      }
+      const anthropicProvider = createAnthropic({
+        apiKey: config.anthropicApiKey
+      })
+      return {
+        provider: 'anthropic',
+        model: anthropicProvider(modelName),
+        modelName,
+        isLocal: false,
+        costConfig
+      }
+
+    case 'ollama':
+    default:
+      const ollamaBaseUrl = config.ollamaBaseUrl || 'http://localhost:11434'
+      console.log(`🔥 [selectModel] Creating Ollama provider with baseURL: ${ollamaBaseUrl}, model: ${modelName}`)
+      const ollamaProvider = createOpenAICompatible({
+        baseURL: `${ollamaBaseUrl}/v1`,
+        name: 'ollama'
+      })
+      return {
+        provider: 'ollama',
+        model: ollamaProvider(modelName),
+        modelName,
+        isLocal: true,
+        costConfig
+      }
+  }
+}
+
+/**
+ * Calculate AI generation cost
+ */
+export function calculateCost(
+  tokens: { input: number; output: number },
+  costConfig: { input: number; output: number }
+): number {
+  const inputCost = (tokens.input / 1000) * costConfig.input
+  const outputCost = (tokens.output / 1000) * costConfig.output
+  return Math.round((inputCost + outputCost) * 100000) / 100000
+}
+
+/**
+ * Validate plugin is ready to use
+ */
+export async function validatePlugin(): Promise<{ valid: boolean; error?: string }> {
+  try {
+    if (!(await isServerPluginEnabled())) {
+      return {
+        valid: false,
+        error: 'AI plugin disabled. Set AI_PLUGIN_ENABLED=true in contents/plugins/ai/.env'
+      }
+    }
+
+    const envValidation = await validateServerPluginEnvironment()
+    if (!envValidation.valid) {
+      return {
+        valid: false,
+        error: `Plugin configuration invalid: ${envValidation.errors.join(', ')}`
+      }
+    }
+
+    return { valid: true }
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : 'Unknown validation error'
+    }
+  }
+}
+
+/**
+ * Extract token usage from AI SDK result
+ */
+export function extractTokens(result: AIResult): { input: number; output: number; total: number } {
+  return {
+    input: result.usage?.inputTokens || 0,
+    output: result.usage?.outputTokens || 0,
+    total: result.usage?.totalTokens || 0
+  }
+}
+
+/**
+ * Common error handler for AI endpoints
+ */
+export function handleAIError(error: Error): { error: string; message: string; status: number } {
+  const errorMessage = error.message.toLowerCase()
+
+  // Provider-specific errors
+  if (errorMessage.includes('openai') || errorMessage.includes('api key')) {
+    return {
+      error: 'OpenAI authentication failed',
+      message: 'Check your OPENAI_API_KEY in contents/plugins/ai/.env',
+      status: 401
+    }
+  }
+
+  if (errorMessage.includes('anthropic') || errorMessage.includes('claude')) {
+    return {
+      error: 'Anthropic authentication failed',
+      message: 'Check your ANTHROPIC_API_KEY in contents/plugins/ai/.env',
+      status: 401
+    }
+  }
+
+  if (errorMessage.includes('econnrefused') || errorMessage.includes('connect')) {
+    return {
+      error: 'Ollama connection failed',
+      message: 'Make sure Ollama is running (ollama serve)',
+      status: 503
+    }
+  }
+
+  if (errorMessage.includes('rate limit') || errorMessage.includes('quota')) {
+    return {
+      error: 'Rate limit exceeded',
+      message: 'API rate limit reached. Try again later.',
+      status: 429
+    }
+  }
+
+  if (errorMessage.includes('model') && errorMessage.includes('not found')) {
+    return {
+      error: 'Model not found',
+      message: 'The specified model is not available or not installed',
+      status: 404
+    }
+  }
+
+  // Generic error
+  return {
+    error: 'AI generation failed',
+    message: error.message,
+    status: 500
+  }
+}