@nextsparkjs/plugin-ai 0.1.0-beta.1

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

@@ -0,0 +1,330 @@
+/**
+ * AI History Entity Fields Configuration
+ *
+ * Generic AI interaction history for all plugins and operations.
+ * Tracks AI usage with cost metrics and polymorphic relationships.
+ *
+ * Features:
+ * - User tracking
+ * - Polymorphic relationships (relatedEntityType + relatedEntityId)
+ * - Cost and performance metrics
+ * - Status tracking through operation lifecycle
+ * - Support for multiple AI providers (Anthropic, OpenAI, etc.)
+ */
+
+import type { EntityField } from '@nextsparkjs/core/lib/entities/types'
+
+export const aiHistoryFields: EntityField[] = [
+  // User Relationship
+  {
+    name: 'userId',
+    type: 'text',
+    required: true,
+    display: {
+      label: 'User ID',
+      description: 'User who initiated the AI operation',
+      placeholder: 'User ID',
+      showInList: true,
+      showInDetail: true,
+      showInForm: false,
+      order: 1,
+      columnWidth: 6,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+
+  // Polymorphic Relationship (Generic Entity Link)
+  {
+    name: 'relatedEntityType',
+    type: 'text',
+    required: false,
+    display: {
+      label: 'Related Entity Type',
+      description: 'Type of entity this operation relates to (e.g., "contents", "products", "campaigns")',
+      placeholder: 'contents',
+      showInList: true,
+      showInDetail: true,
+      showInForm: false,
+      order: 2,
+      columnWidth: 6,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+  {
+    name: 'relatedEntityId',
+    type: 'text',
+    required: false,
+    display: {
+      label: 'Related Entity ID',
+      description: 'ID of the related entity (polymorphic relationship)',
+      placeholder: 'Entity ID',
+      showInList: false,
+      showInDetail: true,
+      showInForm: false,
+      order: 3,
+      columnWidth: 6,
+    },
+    api: {
+      searchable: true,
+      sortable: false,
+      readOnly: true,
+    },
+  },
+
+  // AI Operation Details
+  {
+    name: 'operation',
+    type: 'select',
+    required: true,
+    options: [
+      { value: 'generate', label: 'Generate' },
+      { value: 'refine', label: 'Refine' },
+      { value: 'analyze', label: 'Analyze' },
+      { value: 'chat', label: 'Chat' },
+      { value: 'completion', label: 'Completion' },
+      { value: 'other', label: 'Other' },
+    ],
+    display: {
+      label: 'Operation',
+      description: 'Type of AI operation',
+      placeholder: 'Select operation...',
+      showInList: true,
+      showInDetail: true,
+      showInForm: false,
+      order: 4,
+      columnWidth: 4,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+  {
+    name: 'model',
+    type: 'text',
+    required: true,
+    display: {
+      label: 'AI Model',
+      description: 'AI model used (e.g., claude-3-5-sonnet-20241022, gpt-4)',
+      placeholder: 'claude-3-5-sonnet-20241022',
+      showInList: true,
+      showInDetail: true,
+      showInForm: false,
+      order: 5,
+      columnWidth: 4,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+  {
+    name: 'provider',
+    type: 'select',
+    required: true,
+    defaultValue: 'anthropic',
+    options: [
+      { value: 'anthropic', label: 'Anthropic' },
+      { value: 'openai', label: 'OpenAI' },
+      { value: 'google', label: 'Google' },
+      { value: 'azure', label: 'Azure' },
+      { value: 'other', label: 'Other' },
+    ],
+    display: {
+      label: 'Provider',
+      description: 'AI provider',
+      placeholder: 'Select provider...',
+      showInList: true,
+      showInDetail: true,
+      showInForm: false,
+      order: 6,
+      columnWidth: 4,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+
+  // Status and Metrics
+  {
+    name: 'status',
+    type: 'select',
+    required: true,
+    defaultValue: 'pending',
+    options: [
+      { value: 'pending', label: 'Pending' },
+      { value: 'processing', label: 'Processing' },
+      { value: 'completed', label: 'Completed' },
+      { value: 'failed', label: 'Failed' },
+    ],
+    display: {
+      label: 'Status',
+      description: 'Operation processing status',
+      placeholder: 'Select status...',
+      showInList: true,
+      showInDetail: true,
+      showInForm: false,
+      order: 7,
+      columnWidth: 3,
+    },
+    api: {
+      searchable: true,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+  {
+    name: 'tokensUsed',
+    type: 'number',
+    required: false,
+    display: {
+      label: 'Tokens Used',
+      description: 'Total tokens consumed (input + output)',
+      placeholder: '0',
+      showInList: true,
+      showInDetail: true,
+      showInForm: false,
+      order: 8,
+      columnWidth: 3,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+  {
+    name: 'creditsUsed',
+    type: 'number',
+    required: false,
+    display: {
+      label: 'Credits Used',
+      description: 'Credits deducted for this operation',
+      placeholder: '0',
+      showInList: true,
+      showInDetail: true,
+      showInForm: false,
+      order: 9,
+      columnWidth: 3,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+  {
+    name: 'estimatedCost',
+    type: 'number',
+    required: false,
+    display: {
+      label: 'Estimated Cost ($)',
+      description: 'Cost in USD based on model pricing',
+      placeholder: '0.00',
+      showInList: true,
+      showInDetail: true,
+      showInForm: false,
+      order: 10,
+      columnWidth: 3,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+  {
+    name: 'balanceAfter',
+    type: 'number',
+    required: false,
+    display: {
+      label: 'Balance After',
+      description: 'User credit balance after this operation',
+      placeholder: '0',
+      showInList: false,
+      showInDetail: true,
+      showInForm: false,
+      order: 11,
+      columnWidth: 3,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+
+  // Error Tracking
+  {
+    name: 'errorMessage',
+    type: 'textarea',
+    required: false,
+    display: {
+      label: 'Error Message',
+      description: 'Error message if operation failed',
+      placeholder: 'Error details...',
+      showInList: false,
+      showInDetail: true,
+      showInForm: false,
+      order: 12,
+      columnWidth: 12,
+    },
+    api: {
+      searchable: false,
+      sortable: false,
+      readOnly: true,
+    },
+  },
+
+  // Timestamps
+  {
+    name: 'createdAt',
+    type: 'datetime',
+    required: false,
+    display: {
+      label: 'Created At',
+      description: 'When the AI operation was initiated',
+      showInList: true,
+      showInDetail: true,
+      showInForm: false,
+      order: 97,
+      columnWidth: 6,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+  {
+    name: 'completedAt',
+    type: 'datetime',
+    required: false,
+    display: {
+      label: 'Completed At',
+      description: 'When the AI operation finished (success or failure)',
+      showInList: false,
+      showInDetail: true,
+      showInForm: false,
+      order: 98,
+      columnWidth: 6,
+    },
+    api: {
+      searchable: false,
+      sortable: true,
+      readOnly: true,
+    },
+  },
+]

package/entities/ai-history/messages/en.json

@@ -0,0 +1,56 @@
+{
+  "entity": {
+    "name": "AI History",
+    "namePlural": "AI History",
+    "description": "Generic audit trail for AI interactions with cost and performance metrics"
+  },
+  "fields": {
+    "userId": "User ID",
+    "relatedEntityType": "Related Entity Type",
+    "relatedEntityId": "Related Entity ID",
+    "operation": "Operation",
+    "model": "AI Model",
+    "provider": "Provider",
+    "status": "Status",
+    "tokensUsed": "Tokens Used",
+    "creditsUsed": "Credits Used",
+    "estimatedCost": "Estimated Cost ($)",
+    "balanceAfter": "Balance After",
+    "errorMessage": "Error Message",
+    "createdAt": "Created At",
+    "completedAt": "Completed At"
+  },
+  "operations": {
+    "generate": "Generate",
+    "refine": "Refine",
+    "analyze": "Analyze",
+    "chat": "Chat",
+    "completion": "Completion",
+    "other": "Other"
+  },
+  "providers": {
+    "anthropic": "Anthropic",
+    "openai": "OpenAI",
+    "google": "Google",
+    "azure": "Azure",
+    "other": "Other"
+  },
+  "actions": {
+    "create": "Create History Entry",
+    "edit": "Edit History Entry",
+    "delete": "Delete History Entry",
+    "view": "View History Entry"
+  },
+  "messages": {
+    "created": "History entry created successfully",
+    "updated": "History entry updated successfully",
+    "deleted": "History entry deleted successfully",
+    "error": "An error occurred"
+  },
+  "status": {
+    "pending": "Pending",
+    "processing": "Processing",
+    "completed": "Completed",
+    "failed": "Failed"
+  }
+}

package/entities/ai-history/messages/es.json

@@ -0,0 +1,56 @@
+{
+  "entity": {
+    "name": "Historial IA",
+    "namePlural": "Historial IA",
+    "description": "Auditoría genérica de interacciones con IA y métricas de costos"
+  },
+  "fields": {
+    "userId": "ID de Usuario",
+    "relatedEntityType": "Tipo de Entidad Relacionada",
+    "relatedEntityId": "ID de Entidad Relacionada",
+    "operation": "Operación",
+    "model": "Modelo IA",
+    "provider": "Proveedor",
+    "status": "Estado",
+    "tokensUsed": "Tokens Usados",
+    "creditsUsed": "Créditos Usados",
+    "estimatedCost": "Costo Estimado ($)",
+    "balanceAfter": "Balance Después",
+    "errorMessage": "Mensaje de Error",
+    "createdAt": "Creado el",
+    "completedAt": "Completado el"
+  },
+  "operations": {
+    "generate": "Generar",
+    "refine": "Refinar",
+    "analyze": "Analizar",
+    "chat": "Chat",
+    "completion": "Completado",
+    "other": "Otro"
+  },
+  "providers": {
+    "anthropic": "Anthropic",
+    "openai": "OpenAI",
+    "google": "Google",
+    "azure": "Azure",
+    "other": "Otro"
+  },
+  "actions": {
+    "create": "Crear Entrada de Historial",
+    "edit": "Editar Entrada de Historial",
+    "delete": "Eliminar Entrada de Historial",
+    "view": "Ver Entrada de Historial"
+  },
+  "messages": {
+    "created": "Entrada de historial creada exitosamente",
+    "updated": "Entrada de historial actualizada exitosamente",
+    "deleted": "Entrada de historial eliminada exitosamente",
+    "error": "Ocurrió un error"
+  },
+  "status": {
+    "pending": "Pendiente",
+    "processing": "Procesando",
+    "completed": "Completado",
+    "failed": "Fallido"
+  }
+}

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

@@ -0,0 +1,167 @@
+-- =============================================
+-- AI HISTORY ENTITY MIGRATION - PLUGIN ENTITY
+-- Plugin: AI
+-- Entity: ai-history
+-- Generic AI interaction history for all plugins
+-- Date: 2025-10-03
+-- =============================================
+
+-- =============================================
+-- MAIN AI_HISTORY TABLE
+-- =============================================
+
+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,
+
+  -- Generic polymorphic relationship (flexible for any future use case)
+  "relatedEntityType" TEXT,
+  "relatedEntityId" TEXT,
+
+  -- AI operation details
+  operation TEXT NOT NULL CHECK (operation IN ('generate', 'refine', 'analyze', 'chat', 'completion', 'other')),
+  model TEXT NOT NULL,
+  provider TEXT NOT NULL DEFAULT 'anthropic',
+
+  -- Metrics and cost tracking
+  "tokensUsed" INTEGER,
+  "tokensInput" INTEGER, -- ✅ Input tokens (prompt) - for precise cost calculation
+  "tokensOutput" INTEGER, -- ✅ Output tokens (completion) - for precise cost calculation
+  "creditsUsed" INTEGER,
+  "estimatedCost" DECIMAL(10, 6),
+  "balanceAfter" INTEGER,
+
+  -- Status tracking
+  status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'processing', 'completed', 'failed')),
+
+  -- Error tracking
+  "errorMessage" TEXT,
+
+  -- Timestamps
+  "createdAt" TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "completedAt" TIMESTAMPTZ
+);
+
+-- =============================================
+-- INDEXES
+-- =============================================
+
+CREATE INDEX IF NOT EXISTS idx_ai_history_user_id ON "ai_history"("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);
+CREATE INDEX IF NOT EXISTS idx_ai_history_model ON "ai_history"(model);
+CREATE INDEX IF NOT EXISTS idx_ai_history_provider ON "ai_history"(provider);
+CREATE INDEX IF NOT EXISTS idx_ai_history_created_at ON "ai_history"("createdAt" DESC);
+CREATE INDEX IF NOT EXISTS idx_ai_history_user_status ON "ai_history"("userId", status);
+CREATE INDEX IF NOT EXISTS idx_ai_history_user_operation ON "ai_history"("userId", operation);
+CREATE INDEX IF NOT EXISTS idx_ai_history_tokens_input ON "ai_history"("tokensInput") WHERE "tokensInput" IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_ai_history_tokens_output ON "ai_history"("tokensOutput") WHERE "tokensOutput" IS NOT NULL;
+
+-- =============================================
+-- ROW LEVEL SECURITY (enableRLS: true)
+-- =============================================
+
+-- Enable RLS
+ALTER TABLE "ai_history" ENABLE ROW LEVEL SECURITY;
+
+-- Policies for ai_history table
+DROP POLICY IF EXISTS "Users can view own ai history" ON "ai_history";
+CREATE POLICY "Users can view own ai history" ON "ai_history"
+  FOR SELECT USING ("userId" = public.get_auth_user_id());
+
+DROP POLICY IF EXISTS "Users can insert own ai history" ON "ai_history";
+CREATE POLICY "Users can insert own ai history" ON "ai_history"
+  FOR INSERT WITH CHECK ("userId" = public.get_auth_user_id());
+
+DROP POLICY IF EXISTS "Users can update own ai history" ON "ai_history";
+CREATE POLICY "Users can update own ai history" ON "ai_history"
+  FOR UPDATE USING ("userId" = public.get_auth_user_id())
+  WITH CHECK ("userId" = public.get_auth_user_id());
+
+DROP POLICY IF EXISTS "Users can delete own ai history" ON "ai_history";
+CREATE POLICY "Users can delete own ai history" ON "ai_history"
+  FOR DELETE USING ("userId" = public.get_auth_user_id());
+
+-- Admins can manage all ai history
+DROP POLICY IF EXISTS "Admins can manage all ai history" ON "ai_history";
+CREATE POLICY "Admins can manage all ai history" ON "ai_history"
+  FOR ALL USING (
+    EXISTS (
+      SELECT 1 FROM "users"
+      WHERE id = public.get_auth_user_id()
+        AND role IN ('admin','superadmin')
+    )
+  )
+  WITH CHECK (
+    EXISTS (
+      SELECT 1 FROM "users"
+      WHERE id = public.get_auth_user_id()
+        AND role IN ('admin','superadmin')
+    )
+  );
+
+-- =============================================
+-- TRIGGER: Auto-update completedAt
+-- =============================================
+CREATE OR REPLACE FUNCTION update_ai_history_completed_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  IF NEW.status IN ('completed', 'failed') AND OLD.status NOT IN ('completed', 'failed') THEN
+    NEW."completedAt" = now();
+  END IF;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER ai_history_completed_at
+  BEFORE UPDATE ON "ai_history"
+  FOR EACH ROW
+  EXECUTE FUNCTION update_ai_history_completed_at();
+
+-- =============================================
+-- CONSTRAINT: Token Split Validation
+-- =============================================
+-- Ensures data integrity: tokensUsed = tokensInput + tokensOutput when both present
+ALTER TABLE "ai_history"
+ADD CONSTRAINT chk_tokens_sum
+CHECK (
+  ("tokensInput" IS NULL AND "tokensOutput" IS NULL)
+  OR
+  ("tokensUsed" = "tokensInput" + "tokensOutput")
+);
+
+-- =============================================
+-- COMMENTS
+-- =============================================
+COMMENT ON TABLE "ai_history" IS 'Generic audit trail for AI interactions with cost and performance metrics';
+COMMENT ON COLUMN "ai_history"."userId" IS 'User who initiated the AI operation';
+COMMENT ON COLUMN "ai_history"."relatedEntityType" IS 'Type of entity this operation relates to (e.g., ''contents'', ''products'', ''campaigns'')';
+COMMENT ON COLUMN "ai_history"."relatedEntityId" IS 'ID of the related entity (polymorphic relationship)';
+COMMENT ON COLUMN "ai_history".operation IS 'Type of AI operation: generate, refine, analyze, chat, completion, or other';
+COMMENT ON COLUMN "ai_history".model IS 'AI model used (e.g., claude-3-5-sonnet-20241022, gpt-4)';
+COMMENT ON COLUMN "ai_history".provider IS 'AI provider: anthropic, openai, etc.';
+COMMENT ON COLUMN "ai_history".status IS 'Processing status: pending, processing, completed, or failed';
+COMMENT ON COLUMN "ai_history"."tokensUsed" IS 'Total tokens consumed (input + output) - kept for backward compatibility';
+COMMENT ON COLUMN "ai_history"."tokensInput" IS 'Input tokens (prompt) - for precise cost calculation with asymmetric pricing';
+COMMENT ON COLUMN "ai_history"."tokensOutput" IS 'Output tokens (completion) - for precise cost calculation with asymmetric pricing';
+COMMENT ON COLUMN "ai_history"."creditsUsed" IS 'Credits deducted for this operation';
+COMMENT ON COLUMN "ai_history"."estimatedCost" IS 'Cost in USD based on model pricing';
+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"."completedAt" IS 'When the AI operation finished (success or failure)';
+
+-- =============================================
+-- MIGRATION COMPLETE
+-- =============================================
+
+DO $$
+BEGIN
+  RAISE NOTICE 'AI History entity migration completed successfully!';
+  RAISE NOTICE 'Plugin: ai';
+  RAISE NOTICE 'Table created: ai_history';
+  RAISE NOTICE 'RLS policies enabled for user isolation';
+END $$;