@nextsparkjs/plugin-ai 0.1.0-beta.1 → 0.1.0-beta.100

package/api/generate/route.ts

@@ -9,6 +9,7 @@ import { NextRequest, NextResponse } from 'next/server'
 import { selectModel, calculateCost, validatePlugin, extractTokens, handleAIError } from '../../lib/core-utils'
 import { getServerPluginConfig } from '../../lib/server-env'
 import { authenticateRequest } from '@nextsparkjs/core/lib/api/auth/dual-auth'
+import { withRateLimitTier } from '@nextsparkjs/core/lib/api/rate-limit'
 import { generateText } from 'ai'
 import { saveExampleSafely } from '../../lib/save-example'
 import { z } from 'zod'
@@ -25,7 +26,7 @@ const GenerateRequestSchema = z.object({
   saveExample: z.boolean().optional().default(false)
 })
 
-export async function POST(request: NextRequest) {
+const postHandler = async (request: NextRequest) => {
   try {
     // 1. Authentication
     const authResult = await authenticateRequest(request)
@@ -79,20 +80,25 @@ export async function POST(request: NextRequest) {
 
     // 8. Save example if requested (opt-in)
     if (saveExample) {
+      const teamId = request.headers.get('x-team-id') || ''
       await saveExampleSafely(
         {
           prompt,
           response: result.text,
           model: selectedModel.modelName,
           status: 'completed',
+          operation: 'generate',
+          provider: selectedModel.provider,
           metadata: {
             tokens: tokens.total,
+            tokensInput: tokens.input,
+            tokensOutput: tokens.output,
             cost,
-            provider: selectedModel.provider,
             isLocal: selectedModel.isLocal
           }
         },
-        authResult.user!.id
+        authResult.user!.id,
+        teamId
       )
     }
 
@@ -119,10 +125,12 @@ export async function POST(request: NextRequest) {
   }
 }
 
+export const POST = withRateLimitTier(postHandler, 'write')
+
 /**
  * Get endpoint info
  */
-export async function GET(): Promise<NextResponse> {
+const getHandler = async (): Promise<NextResponse> => {
   const config = await getServerPluginConfig()
 
   return NextResponse.json({
@@ -157,4 +165,6 @@ export async function GET(): Promise<NextResponse> {
       anthropic: 'Add ANTHROPIC_API_KEY to contents/plugins/ai/.env'
     }
   })
-}
+}
+
+export const GET = withRateLimitTier(getHandler, 'read')

package/docs/02-features/03-ai-history.md

@@ -81,6 +81,7 @@ import { AIHistoryService } from '@/contents/plugins/ai/lib/ai-history-service'
 ```typescript
 const historyId = await AIHistoryService.startOperation({
   userId: 'user-id',
+  teamId: 'team-id',
   operation: 'generate',
   model: 'gpt-4o-mini',
   provider: 'openai',
@@ -133,6 +134,7 @@ await AIHistoryService.failOperation({
 ```typescript
 {
   userId: string              // Required
+  teamId: string              // Required - team context for the operation
   operation: AIOperation      // 'generate' | 'refine' | 'analyze' | 'chat' | 'completion' | 'other'
   model: string               // Model name (e.g., 'gpt-4o-mini')
   provider?: AIProvider       // 'openai' | 'anthropic' | 'ollama'
@@ -147,6 +149,7 @@ await AIHistoryService.failOperation({
 ```typescript
 const historyId = await AIHistoryService.startOperation({
   userId: session.user.id,
+  teamId: session.user.activeTeamId,
   operation: 'generate',
   model: 'llama3.2:3b',
   provider: 'ollama'
@@ -225,6 +228,7 @@ try {
 ```typescript
 const historyId = await AIHistoryService.startOperation({
   userId: 'user-id',
+  teamId: 'team-id',
   operation: 'analyze',
   model: 'claude-3-5-haiku-20241022',
   relatedEntityType: 'clients',
@@ -249,6 +253,7 @@ PATCH /api/v1/plugin/ai/ai-history/:id
 // Generate product description
 const historyId = await AIHistoryService.startOperation({
   userId: session.user.id,
+  teamId: session.user.activeTeamId,
   operation: 'generate',
   model: 'gpt-4o-mini',
   relatedEntityType: 'products',
@@ -265,6 +270,7 @@ const historyId = await AIHistoryService.startOperation({
 // Analyze client data
 const historyId = await AIHistoryService.startOperation({
   userId: session.user.id,
+  teamId: session.user.activeTeamId,
   operation: 'analyze',
   model: 'claude-3-5-sonnet-20241022',
   relatedEntityType: 'clients',
@@ -279,6 +285,7 @@ const historyId = await AIHistoryService.startOperation({
 // Audit article content
 const historyId = await AIHistoryService.startOperation({
   userId: session.user.id,
+  teamId: session.user.activeTeamId,
   operation: 'analyze',
   model: 'gpt-4o',
   relatedEntityType: 'articles',
@@ -384,6 +391,7 @@ export async function generateProductDescription(productId: string) {
   // 1. Start operation tracking
   const historyId = await AIHistoryService.startOperation({
     userId: session.user.id,
+    teamId: session.user.activeTeamId,
     operation: 'generate',
     model: 'gpt-4o-mini',
     provider: 'openai',

package/docs/04-use-cases/01-content-generation.md

@@ -336,6 +336,7 @@ export async function generateAndSaveDescription(productId: string) {
   // Start operation tracking
   const historyId = await AIHistoryService.startOperation({
     userId: session.user.id,
+    teamId: session.user.activeTeamId,
     operation: 'generate',
     model: 'gpt-4o-mini',
     provider: 'openai',

package/entities/ai-history/ai-history.config.ts

@@ -17,7 +17,8 @@ export const aiHistoryEntityConfig: EntityConfig = {
   // ==========================================
   // 1. BASIC IDENTIFICATION
   // ==========================================
-  slug: 'ai-history',    // Single source of truth - derives tableName, apiPath, metaTableName, i18nNamespace
+  slug: 'ai-history',
+  tableName: 'ai_history',  // Explicit table name (underscores, not hyphens)
   enabled: true,
   names: {
     singular: 'AI History',
@@ -57,46 +58,7 @@ export const aiHistoryEntityConfig: EntityConfig = {
   },
 
   // ==========================================
-  // 4. PERMISSIONS SYSTEM
-  // ==========================================
-  permissions: {
-    actions: [
-      {
-        action: 'create',
-        label: 'Create AI history',
-        description: 'Can create AI history entries (typically via API)',
-        roles: ['owner', 'admin', 'member'],
-      },
-      {
-        action: 'read',
-        label: 'View AI history',
-        description: 'Can view AI history entries (users see their own via API filtering)',
-        roles: ['owner', 'admin', 'member'],
-      },
-      {
-        action: 'list',
-        label: 'List AI history',
-        description: 'Can list AI history entries',
-        roles: ['owner', 'admin', 'member'],
-      },
-      {
-        action: 'update',
-        label: 'Edit AI history',
-        description: 'Can modify AI history entries (immutable for most users)',
-        roles: ['owner', 'admin'],
-      },
-      {
-        action: 'delete',
-        label: 'Delete AI history',
-        description: 'Can delete AI history entries (users can delete their own)',
-        roles: ['owner', 'admin', 'member'],
-        dangerous: true,
-      },
-    ],
-  },
-
-  // ==========================================
-  // 5. INTERNATIONALIZATION
+  // 4. INTERNATIONALIZATION
   // ==========================================
   i18n: {
     fallbackLocale: 'en',

package/entities/ai-history/ai-history.fields.ts

@@ -308,6 +308,25 @@ export const aiHistoryFields: EntityField[] = [
       readOnly: true,
     },
   },
+  {
+    name: 'updatedAt',
+    type: 'datetime',
+    required: false,
+    display: {
+      label: 'Updated At',
+      description: 'When the record was last updated',
+      showInList: false,
+      showInDetail: true,
+      showInForm: false,
+      order: 98,
+      columnWidth: 6,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      readOnly: true,
+    },
+  },
   {
     name: 'completedAt',
     type: 'datetime',
@@ -318,7 +337,7 @@ export const aiHistoryFields: EntityField[] = [
       showInList: false,
       showInDetail: true,
       showInForm: false,
-      order: 98,
+      order: 99,
       columnWidth: 6,
     },
     api: {

package/entities/ai-history/migrations/001_ai_history_table.sql

@@ -1,7 +1,7 @@
 -- =============================================
 -- AI HISTORY ENTITY MIGRATION - PLUGIN ENTITY
 -- Plugin: AI
--- Entity: ai-history
+-- Entity: ai_history
 -- Generic AI interaction history for all plugins
 -- Date: 2025-10-03
 -- =============================================
@@ -15,6 +15,7 @@ DROP TABLE IF EXISTS "ai_history" CASCADE;
 CREATE TABLE "ai_history" (
   id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
   "userId" TEXT NOT NULL REFERENCES "users"(id) ON DELETE CASCADE,
+  "teamId" TEXT NOT NULL REFERENCES "teams"(id) ON DELETE CASCADE,
 
   -- Generic polymorphic relationship (flexible for any future use case)
   "relatedEntityType" TEXT,
@@ -41,6 +42,7 @@ CREATE TABLE "ai_history" (
 
   -- Timestamps
   "createdAt" TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt" TIMESTAMPTZ NOT NULL DEFAULT now(),
   "completedAt" TIMESTAMPTZ
 );
 
@@ -49,6 +51,8 @@ CREATE TABLE "ai_history" (
 -- =============================================
 
 CREATE INDEX IF NOT EXISTS idx_ai_history_user_id ON "ai_history"("userId");
+CREATE INDEX IF NOT EXISTS idx_ai_history_team_id ON "ai_history"("teamId");
+CREATE INDEX IF NOT EXISTS idx_ai_history_team_user ON "ai_history"("teamId", "userId");
 CREATE INDEX IF NOT EXISTS idx_ai_history_entity ON "ai_history"("relatedEntityType", "relatedEntityId") WHERE "relatedEntityType" IS NOT NULL;
 CREATE INDEX IF NOT EXISTS idx_ai_history_status ON "ai_history"(status);
 CREATE INDEX IF NOT EXISTS idx_ai_history_operation ON "ai_history"(operation);
@@ -103,6 +107,13 @@ CREATE POLICY "Admins can manage all ai history" ON "ai_history"
     )
   );
 
+-- =============================================
+-- TRIGGER: Auto-update updatedAt
+-- =============================================
+CREATE TRIGGER ai_history_set_updated_at
+  BEFORE UPDATE ON "ai_history"
+  FOR EACH ROW EXECUTE FUNCTION public.set_updated_at();
+
 -- =============================================
 -- TRIGGER: Auto-update completedAt
 -- =============================================
@@ -152,6 +163,7 @@ COMMENT ON COLUMN "ai_history"."estimatedCost" IS 'Cost in USD based on model pr
 COMMENT ON COLUMN "ai_history"."balanceAfter" IS 'User credit balance after this operation';
 COMMENT ON COLUMN "ai_history"."errorMessage" IS 'Error message if operation failed';
 COMMENT ON COLUMN "ai_history"."createdAt" IS 'When the AI operation was initiated';
+COMMENT ON COLUMN "ai_history"."updatedAt" IS 'When the record was last updated';
 COMMENT ON COLUMN "ai_history"."completedAt" IS 'When the AI operation finished (success or failure)';
 
 -- =============================================

package/entities/ai-history/migrations/002_ai_history_metas.sql

@@ -1,7 +1,7 @@
 -- =============================================
 -- AI HISTORY METADATA SYSTEM
 -- Plugin: AI
--- Entity: ai-history
+-- Entity: ai_history
 -- =============================================
 --
 -- This migration adds comprehensive metadata capabilities through ai_history_metas table

package/lib/ai-history-meta-service.ts

@@ -14,27 +14,6 @@ import { CreateMetaPayload } from '@nextsparkjs/core/types/meta.types';
  * METADATA BY ENDPOINT (Standardized)
  * ============================================
  *
- * analyze-brief (/api/v1/theme/content-buddy/analyze-brief):
- * - briefText: Original brief text (for auditing/debugging)
- * - briefLength: Length of brief text
- * - extractedFieldsCount: Number of fields extracted
- * - audiencesCount: Number of audience entities extracted
- * - objectivesCount: Number of objective entities extracted
- * - productsCount: Number of product entities extracted
- * - totalChildEntities: Total child entities extracted
- * - clientName: Extracted client name
- * - clientIndustry: Extracted client industry
- *
- * generate-content (/api/v1/theme/content-buddy/generate-content):
- * Core generation parameters (reproducibility):
- * - temperature: AI model temperature used
- * - tone: Content tone
- * - brandVoice: Brand voice style
- * - audience: Target audience description
- * - topic: Content topic
- * - postType: Type of post
- * - language: Content language code (e.g., "en", "es")
- *
  * Content specifications (analytics):
  * - wordCount: Target word count
  * - keywords: Comma-separated keywords (e.g., "innovation,tech,ai")
@@ -54,13 +33,6 @@ import { CreateMetaPayload } from '@nextsparkjs/core/types/meta.types';
  * - objectiveId: Marketing objective (if specified)
  * - targetAudienceId: Specific audience segment (if specified)
  *
- * refine-content (/api/v1/theme/content-buddy/refine-content):
- * - userInstruction: User's refinement instruction
- * - sourceOperationId: UUID linking to source operation (for workflow tracking)
- * - temperature: AI model temperature used
- * - tone: Desired tone (if specified)
- * - platform: Social media platform being refined for
- *
  * ============================================
  * DEPRECATED METADATA (Use ai_history columns instead)
  * ============================================

package/lib/ai-history-service.ts

@@ -20,6 +20,7 @@ export type AIStatus = 'pending' | 'processing' | 'completed' | 'failed'
 
 export interface StartOperationParams {
   userId: string
+  teamId: string // Required - team context for the operation
   operation: AIOperation
   model: string
   provider?: AIProvider
@@ -75,6 +76,7 @@ export class AIHistoryService {
   static async startOperation(params: StartOperationParams): Promise<string> {
     const {
       userId,
+      teamId,
       operation,
       model,
       provider = 'anthropic',
@@ -86,6 +88,7 @@ export class AIHistoryService {
       const result = await queryOne<{ id: string }>(
         `INSERT INTO "ai_history" (
           "userId",
+          "teamId",
           operation,
           model,
           provider,
@@ -93,9 +96,9 @@ export class AIHistoryService {
           "relatedEntityId",
           status,
           "createdAt"
-        ) VALUES ($1, $2, $3, $4, $5, $6, $7, now())
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, now())
         RETURNING id`,
-        [userId, operation, model, provider, relatedEntityType || null, relatedEntityId || null, 'pending']
+        [userId, teamId, operation, model, provider, relatedEntityType || null, relatedEntityId || null, 'pending']
       )
 
       if (!result) {

package/lib/save-example.ts

@@ -1,28 +1,31 @@
 /**
- * AI Example Saving - PostgreSQL Implementation
+ * AI History Saving - PostgreSQL Implementation
  *
  * Uses project's PostgreSQL connection with RLS support.
- * Self-contained plugin with direct DB access.
+ * Saves AI interactions to the ai_history table.
  */
 
 import { mutateWithRLS, queryWithRLS } from '@nextsparkjs/core/lib/db'
 import { sanitizePrompt, sanitizeResponse } from './sanitize'
 
 export interface AIExampleData {
-  title?: string
   prompt: string
   response: string
   model: string
   status: 'pending' | 'processing' | 'completed' | 'failed'
-  userId?: string
+  operation?: 'generate' | 'refine' | 'analyze' | 'chat' | 'completion' | 'other'
+  provider?: string
   metadata?: {
     tokens?: number
+    tokensInput?: number
+    tokensOutput?: number
     cost?: number
     duration?: number
-    provider?: string
     isLocal?: boolean
     platforms?: number
     imagesProcessed?: number
+    relatedEntityType?: string
+    relatedEntityId?: string
   }
 }
 
@@ -34,11 +37,12 @@ export interface SaveExampleResult {
 }
 
 /**
- * Save AI example to PostgreSQL database
+ * Save AI interaction to ai_history table
  */
 export async function saveAIExample(
   data: AIExampleData,
-  userId: string
+  userId: string,
+  teamId: string
 ): Promise<SaveExampleResult> {
   try {
     // 1. Sanitize sensitive data
@@ -49,25 +53,35 @@ export async function saveAIExample(
       sanitizedPrompt !== data.prompt ||
       sanitizedResponse !== data.response
 
-    // 2. Generate title if not provided
-    const title = data.title || generateTitle(sanitizedPrompt)
+    // 2. Extract token info
+    const tokensInput = data.metadata?.tokensInput || 0
+    const tokensOutput = data.metadata?.tokensOutput || 0
+    const tokensUsed = data.metadata?.tokens || (tokensInput + tokensOutput)
 
-    // 3. Insert into database with RLS
+    // 3. Insert into ai_history table with RLS
     const query = `
-      INSERT INTO ai_example (
-        title, prompt, response, model, status, "userId", metadata, "createdAt", "updatedAt"
-      ) VALUES ($1, $2, $3, $4, $5, $6, $7, NOW(), NOW())
+      INSERT INTO ai_history (
+        "userId", "teamId", operation, model, provider, status,
+        "tokensUsed", "tokensInput", "tokensOutput", "estimatedCost",
+        "relatedEntityType", "relatedEntityId",
+        "createdAt", "updatedAt"
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, NOW(), NOW())
       RETURNING id
     `
 
     const params = [
-      title,
-      sanitizedPrompt,
-      sanitizedResponse,
+      userId,
+      teamId,
+      data.operation || 'generate',
       data.model,
+      data.provider || 'ollama',
       data.status,
-      userId,
-      JSON.stringify(data.metadata || {})
+      tokensUsed || null,
+      tokensInput || null,
+      tokensOutput || null,
+      data.metadata?.cost || null,
+      data.metadata?.relatedEntityType || null,
+      data.metadata?.relatedEntityId || null
     ]
 
     const result = await mutateWithRLS<{ id: string }>(query, params, userId)
@@ -75,13 +89,14 @@ export async function saveAIExample(
     if (result.rowCount === 0 || !result.rows[0]) {
       return {
         success: false,
-        error: 'Failed to insert example'
+        error: 'Failed to insert ai_history record'
       }
     }
 
-    console.log('[AI Plugin] Example saved to database:', {
+    console.log('[AI Plugin] History saved to database:', {
       id: result.rows[0].id,
-      title,
+      operation: data.operation || 'generate',
+      model: data.model,
       sanitizationApplied
     })
 
@@ -92,7 +107,7 @@ export async function saveAIExample(
     }
 
   } catch (error) {
-    console.error('[AI Plugin] Save example failed:', error)
+    console.error('[AI Plugin] Save history failed:', error)
     return {
       success: false,
       error: error instanceof Error ? error.message : 'Unknown error'
@@ -101,29 +116,44 @@ export async function saveAIExample(
 }
 
 /**
- * Get AI examples from PostgreSQL
+ * Get AI history from PostgreSQL
  */
 export async function getAIExamples(params: {
   userId?: string
+  teamId?: string
   limit?: number
   offset?: number
   status?: string
+  operation?: string
 }) {
   try {
-    const { userId, limit = 50, offset = 0, status } = params
+    const { userId, teamId, limit = 50, offset = 0, status, operation } = params
 
     let query = `
-      SELECT id, title, prompt, response, model, status, "userId", metadata, "createdAt", "updatedAt"
-      FROM ai_example
+      SELECT id, "userId", "teamId", operation, model, provider, status,
+             "tokensUsed", "tokensInput", "tokensOutput", "estimatedCost",
+             "relatedEntityType", "relatedEntityId",
+             "createdAt", "updatedAt", "completedAt"
+      FROM ai_history
       WHERE 1=1
     `
     const queryParams: (string | number)[] = []
 
+    if (teamId) {
+      queryParams.push(teamId)
+      query += ` AND "teamId" = $${queryParams.length}`
+    }
+
     if (status) {
       queryParams.push(status)
       query += ` AND status = $${queryParams.length}`
     }
 
+    if (operation) {
+      queryParams.push(operation)
+      query += ` AND operation = $${queryParams.length}`
+    }
+
     query += ` ORDER BY "createdAt" DESC LIMIT $${queryParams.length + 1} OFFSET $${queryParams.length + 2}`
     queryParams.push(limit, offset)
 
@@ -134,7 +164,7 @@ export async function getAIExamples(params: {
       data: rows
     }
   } catch (error) {
-    console.error('[AI Plugin] Get examples failed:', error)
+    console.error('[AI Plugin] Get history failed:', error)
     return {
       success: false,
       error: error instanceof Error ? error.message : 'Unknown error',
@@ -144,13 +174,16 @@ export async function getAIExamples(params: {
 }
 
 /**
- * Get single AI example by ID from PostgreSQL
+ * Get single AI history record by ID
  */
 export async function getAIExampleById(id: string, userId?: string) {
   try {
     const query = `
-      SELECT id, title, prompt, response, model, status, "userId", metadata, "createdAt", "updatedAt"
-      FROM ai_example
+      SELECT id, "userId", "teamId", operation, model, provider, status,
+             "tokensUsed", "tokensInput", "tokensOutput", "estimatedCost",
+             "relatedEntityType", "relatedEntityId",
+             "createdAt", "updatedAt", "completedAt"
+      FROM ai_history
       WHERE id = $1
     `
 
@@ -159,7 +192,7 @@ export async function getAIExampleById(id: string, userId?: string) {
     if (rows.length === 0) {
       return {
         success: false,
-        error: 'Example not found'
+        error: 'History record not found'
       }
     }
 
@@ -168,7 +201,7 @@ export async function getAIExampleById(id: string, userId?: string) {
       data: rows[0]
     }
   } catch (error) {
-    console.error('[AI Plugin] Get example by ID failed:', error)
+    console.error('[AI Plugin] Get history by ID failed:', error)
     return {
       success: false,
       error: error instanceof Error ? error.message : 'Unknown error'
@@ -177,18 +210,18 @@ export async function getAIExampleById(id: string, userId?: string) {
 }
 
 /**
- * Delete AI example from PostgreSQL
+ * Delete AI history record
  */
 export async function deleteAIExample(id: string, userId: string) {
   try {
-    const query = `DELETE FROM ai_example WHERE id = $1 RETURNING id`
+    const query = `DELETE FROM ai_history WHERE id = $1 RETURNING id`
 
     const result = await mutateWithRLS<{ id: string }>(query, [id], userId)
 
     if (result.rowCount === 0) {
       return {
         success: false,
-        error: 'Example not found or unauthorized'
+        error: 'History record not found or unauthorized'
       }
     }
 
@@ -197,7 +230,7 @@ export async function deleteAIExample(id: string, userId: string) {
       id: result.rows[0].id
     }
   } catch (error) {
-    console.error('[AI Plugin] Delete example failed:', error)
+    console.error('[AI Plugin] Delete history failed:', error)
     return {
       success: false,
       error: error instanceof Error ? error.message : 'Unknown error'
@@ -206,32 +239,23 @@ export async function deleteAIExample(id: string, userId: string) {
 }
 
 /**
- * Generate title from prompt (helper)
- */
-function generateTitle(prompt: string): string {
-  const cleaned = prompt.replace(/\n/g, ' ').trim()
-  return cleaned.length > 50
-    ? cleaned.substring(0, 50) + '...'
-    : cleaned
-}
-
-/**
- * Save example with automatic error handling (fire-and-forget)
+ * Save history with automatic error handling (fire-and-forget)
  */
 export async function saveExampleSafely(
   data: AIExampleData,
-  userId: string
+  userId: string,
+  teamId: string
 ): Promise<void> {
   try {
-    const result = await saveAIExample(data, userId)
+    const result = await saveAIExample(data, userId, teamId)
 
     if (!result.success) {
-      console.error('[AI Plugin] Example save failed:', result.error)
+      console.error('[AI Plugin] History save failed:', result.error)
     } else if (result.sanitizationApplied) {
-      console.warn('[AI Plugin] Sanitization was applied to saved example')
+      console.warn('[AI Plugin] Sanitization was applied to saved history')
     }
   } catch (error) {
     // Silent fail - don't break the main request
-    console.error('[AI Plugin] Example save error:', error)
+    console.error('[AI Plugin] History save error:', error)
   }
-}
+}