@nextsparkjs/plugin-ai 0.1.0-beta.1

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

@@ -0,0 +1,103 @@
+-- =============================================
+-- AI HISTORY METADATA SYSTEM
+-- Plugin: AI
+-- Entity: ai-history
+-- =============================================
+--
+-- This migration adds comprehensive metadata capabilities through ai_history_metas table
+--
+-- Purpose: Flexible metadata storage for AI operations
+-- - Better query performance (indexed key-value lookups)
+-- - Granular auditing (when was each meta value set)
+-- - Flexible schema (any metadata without ALTER TABLE)
+-- - Type hints for client-side parsing
+--
+-- Common metadata keys:
+-- - sourceOperationId: UUID linking to parent operation (for refine chains)
+-- - userInstruction: Custom user instruction for refinements
+-- - temperature: AI generation temperature setting
+-- - tone: Content tone (casual, professional, etc.)
+-- - platform: Social media platform target (instagram, tiktok, etc.)
+-- - audience: Target audience description
+-- - topic: Content topic
+-- - language: Content language (en, es, etc.)
+--
+-- Date: 2025-11-04
+-- =============================================
+
+-- =============================================
+-- AI_HISTORY_METAS TABLE
+-- =============================================
+
+CREATE TABLE IF NOT EXISTS public."ai_history_metas" (
+  id             TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  "entityId"     TEXT NOT NULL REFERENCES public."ai_history"(id) ON DELETE CASCADE,
+  "metaKey"      TEXT NOT NULL,
+  "metaValue"    JSONB NOT NULL DEFAULT '{}'::jsonb,
+  "dataType"     TEXT DEFAULT 'json' CHECK ("dataType" IN ('string', 'number', 'boolean', 'json', 'array')),
+  "isPublic"     BOOLEAN NOT NULL DEFAULT false,
+  "isSearchable" BOOLEAN NOT NULL DEFAULT false,
+  "createdAt"    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt"    TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  -- Prevent duplicate keys per history record
+  CONSTRAINT ai_history_metas_unique_key UNIQUE ("entityId", "metaKey")
+);
+
+-- Trigger for auto-updating updatedAt (using Better Auth's function)
+CREATE TRIGGER ai_history_metas_set_updated_at
+BEFORE UPDATE ON public."ai_history_metas"
+FOR EACH ROW EXECUTE FUNCTION public.set_updated_at();
+
+-- Indexes for efficient queries
+CREATE INDEX idx_ai_history_metas_entity_id ON public."ai_history_metas"("entityId");
+CREATE INDEX idx_ai_history_metas_key ON public."ai_history_metas"("metaKey");
+CREATE INDEX idx_ai_history_metas_composite ON public."ai_history_metas"("entityId", "metaKey");
+
+-- GIN index for JSONB queries (enables @>, ?, ?&, ?| operators)
+CREATE INDEX idx_ai_history_metas_value_gin ON public."ai_history_metas" USING GIN ("metaValue");
+
+-- RLS Policies
+ALTER TABLE public."ai_history_metas" ENABLE ROW LEVEL SECURITY;
+
+-- Cleanup existing policies
+DROP POLICY IF EXISTS "AI history metas owner can do all" ON public."ai_history_metas";
+DROP POLICY IF EXISTS "AI history metas inherit parent access" ON public."ai_history_metas";
+
+-- Policy: Inherit access from parent ai_history record
+CREATE POLICY "AI history metas inherit parent access"
+ON public."ai_history_metas"
+FOR ALL TO authenticated
+USING (
+  EXISTS (
+    SELECT 1 FROM public."ai_history"
+    WHERE "ai_history".id = "ai_history_metas"."entityId"
+    AND "ai_history"."userId" = public.get_auth_user_id()
+  )
+)
+WITH CHECK (
+  EXISTS (
+    SELECT 1 FROM public."ai_history"
+    WHERE "ai_history".id = "ai_history_metas"."entityId"
+    AND "ai_history"."userId" = public.get_auth_user_id()
+  )
+);
+
+-- Comments for documentation
+COMMENT ON TABLE public."ai_history_metas" IS 'Flexible metadata storage for AI history records. Supports any key-value pairs with JSONB values.';
+COMMENT ON COLUMN public."ai_history_metas"."metaValue" IS 'JSONB value allows storing any data structure (string, number, boolean, object, array)';
+COMMENT ON COLUMN public."ai_history_metas"."dataType" IS 'Hint for parsing metaValue on client side (actual type is always JSONB in DB)';
+COMMENT ON COLUMN public."ai_history_metas"."isPublic" IS 'Whether this meta is publicly accessible or private to owner';
+COMMENT ON COLUMN public."ai_history_metas"."isSearchable" IS 'Whether this meta should be included in search operations';
+
+-- =============================================
+-- MIGRATION COMPLETE
+-- =============================================
+
+DO $$
+BEGIN
+  RAISE NOTICE 'AI History metadata migration completed successfully!';
+  RAISE NOTICE 'Created: ai_history_metas table for flexible metadata';
+  RAISE NOTICE 'Performance: GIN indexes for fast JSONB queries';
+  RAISE NOTICE 'Security: RLS policies enabled on ai_history_metas';
+END $$;

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

@@ -0,0 +1,379 @@
+import { MetaService } from '@nextsparkjs/core/lib/services/meta.service';
+import { CreateMetaPayload } from '@nextsparkjs/core/types/meta.types';
+
+/**
+ * AI History Metadata Service
+ *
+ * Specialized service for managing ai_history metadata using the core MetaService.
+ * Provides ai_history-specific helper methods for common metadata operations.
+ *
+ * IMPORTANT: All metadata is stored in ai_history_metas table via completeOperation(metas).
+ * The ai_history table itself has NO metadata column - only structured fields.
+ *
+ * ============================================
+ * 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")
+ * - additionalRequirements: Custom user instructions
+ *
+ * Platform analytics:
+ * - platforms: Comma-separated platform list (e.g., "instagram,linkedin,twitter")
+ * - platformCount: Number of platforms generated for
+ *
+ * Multimodal analytics (feature usage tracking):
+ * - imageCount: Number of images used in generation
+ * - isMultimodal: Boolean - whether images were used
+ *
+ * Entity relationships (CRITICAL for business analytics):
+ * - clientId: Which client generated this content
+ * - productId: Related product (if specified)
+ * - 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)
+ * ============================================
+ * - tokensInput: Use ai_history.tokensInput column
+ * - tokensOutput: Use ai_history.tokensOutput column
+ * - operation: Use ai_history.operation column
+ * - model: Use ai_history.model column
+ * - provider: Use ai_history.provider column
+ */
+export class AIHistoryMetaService {
+  private static readonly ENTITY_TYPE = 'ai-history'; // ✅ Must match entity registry name (with hyphen, not underscore)
+
+  /**
+   * Get all metadata for an AI history record
+   */
+  static async getAllMetas(
+    historyId: string,
+    userId: string,
+    includePrivate: boolean = true
+  ): Promise<Record<string, unknown>> {
+    return MetaService.getEntityMetas(
+      this.ENTITY_TYPE,
+      historyId,
+      userId,
+      includePrivate
+    );
+  }
+
+  /**
+   * Get specific metadata value
+   */
+  static async getMeta(
+    historyId: string,
+    metaKey: string,
+    userId: string
+  ): Promise<unknown> {
+    return MetaService.getEntityMeta(
+      this.ENTITY_TYPE,
+      historyId,
+      metaKey,
+      userId
+    );
+  }
+
+  /**
+   * Set a single metadata value
+   */
+  static async setMeta(
+    historyId: string,
+    metaKey: string,
+    metaValue: unknown,
+    userId: string,
+    options: Partial<CreateMetaPayload> = {}
+  ): Promise<void> {
+    return MetaService.setEntityMeta(
+      this.ENTITY_TYPE,
+      historyId,
+      metaKey,
+      metaValue,
+      userId,
+      options
+    );
+  }
+
+  /**
+   * Set multiple metadata values in batch
+   */
+  static async setBulkMetas(
+    historyId: string,
+    metas: Record<string, unknown>,
+    userId: string,
+    options: Partial<CreateMetaPayload> = {}
+  ): Promise<void> {
+    return MetaService.setBulkEntityMetas(
+      this.ENTITY_TYPE,
+      historyId,
+      metas,
+      userId,
+      options
+    );
+  }
+
+  /**
+   * Delete a metadata key
+   */
+  static async deleteMeta(
+    historyId: string,
+    metaKey: string,
+    userId: string
+  ): Promise<void> {
+    return MetaService.deleteEntityMeta(
+      this.ENTITY_TYPE,
+      historyId,
+      metaKey,
+      userId
+    );
+  }
+
+  /**
+   * Delete all metadata for an AI history record
+   */
+  static async deleteAllMetas(
+    historyId: string,
+    userId: string
+  ): Promise<void> {
+    return MetaService.deleteAllEntityMetas(
+      this.ENTITY_TYPE,
+      historyId,
+      userId
+    );
+  }
+
+  // ============================================
+  // AI History-Specific Helper Methods
+  // ============================================
+
+  /**
+   * Set source operation ID (for refine chains)
+   * Example: refine(B) → sourceOperationId = generate(A)
+   */
+  static async setSourceOperationId(
+    historyId: string,
+    sourceOperationId: string,
+    userId: string
+  ): Promise<void> {
+    return this.setMeta(
+      historyId,
+      'sourceOperationId',
+      sourceOperationId,
+      userId,
+      { dataType: 'string', isPublic: false, isSearchable: false }
+    );
+  }
+
+  /**
+   * Get source operation ID (for workflow tracking)
+   */
+  static async getSourceOperationId(
+    historyId: string,
+    userId: string
+  ): Promise<string | null> {
+    const value = await this.getMeta(historyId, 'sourceOperationId', userId);
+    return value as string | null;
+  }
+
+  /**
+   * Set user instruction (for refinements)
+   */
+  static async setUserInstruction(
+    historyId: string,
+    instruction: string,
+    userId: string
+  ): Promise<void> {
+    return this.setMeta(
+      historyId,
+      'userInstruction',
+      instruction,
+      userId,
+      { dataType: 'string', isPublic: false, isSearchable: true }
+    );
+  }
+
+  /**
+   * Get user instruction
+   */
+  static async getUserInstruction(
+    historyId: string,
+    userId: string
+  ): Promise<string | null> {
+    const value = await this.getMeta(historyId, 'userInstruction', userId);
+    return value as string | null;
+  }
+
+  /**
+   * Set generation parameters (temperature, tone, platform, etc.)
+   */
+  static async setGenerationParams(
+    historyId: string,
+    params: {
+      temperature?: number;
+      tone?: string;
+      platform?: string;
+      style?: string;
+      audienceType?: string;
+      [key: string]: unknown;
+    },
+    userId: string
+  ): Promise<void> {
+    const metas: Record<string, unknown> = {};
+    const options: Partial<CreateMetaPayload> = {
+      isPublic: false,
+      isSearchable: true
+    };
+
+    if (params.temperature !== undefined) {
+      metas.temperature = params.temperature;
+    }
+    if (params.tone !== undefined) {
+      metas.tone = params.tone;
+    }
+    if (params.platform !== undefined) {
+      metas.platform = params.platform;
+    }
+    if (params.style !== undefined) {
+      metas.style = params.style;
+    }
+    if (params.audienceType !== undefined) {
+      metas.audienceType = params.audienceType;
+    }
+
+    // Include any additional custom params
+    Object.keys(params).forEach(key => {
+      if (!['temperature', 'tone', 'platform', 'style', 'audienceType'].includes(key)) {
+        metas[key] = params[key];
+      }
+    });
+
+    if (Object.keys(metas).length > 0) {
+      return this.setBulkMetas(historyId, metas, userId, options);
+    }
+  }
+
+  /**
+   * Get generation parameters
+   */
+  static async getGenerationParams(
+    historyId: string,
+    userId: string
+  ): Promise<Record<string, unknown>> {
+    const allMetas = await this.getAllMetas(historyId, userId, true);
+    const params: Record<string, unknown> = {};
+
+    // Extract known generation params
+    const knownParams = ['temperature', 'tone', 'platform', 'style', 'audienceType'];
+    knownParams.forEach(key => {
+      if (key in allMetas) {
+        params[key] = allMetas[key];
+      }
+    });
+
+    return params;
+  }
+
+  /**
+   * Search AI history records by metadata
+   * Example: Find all refinements with specific instruction
+   */
+  static async searchByMeta(
+    metaKey: string,
+    metaValue: unknown,
+    userId: string,
+    limit: number = 100,
+    offset: number = 0
+  ): Promise<{ historyIds: string[], total: number }> {
+    const result = await MetaService.searchByMeta(
+      this.ENTITY_TYPE,
+      metaKey,
+      metaValue,
+      userId,
+      limit,
+      offset
+    );
+
+    return {
+      historyIds: result.entities,
+      total: result.total
+    };
+  }
+
+  /**
+   * Get metadata for multiple AI history records (bulk)
+   * Useful for analytics and reporting
+   */
+  static async getBulkMetas(
+    historyIds: string[],
+    userId: string,
+    includePrivate: boolean = true
+  ): Promise<Record<string, Record<string, unknown>>> {
+    return MetaService.getBulkEntityMetas(
+      this.ENTITY_TYPE,
+      historyIds,
+      userId,
+      includePrivate
+    );
+  }
+
+  /**
+   * Get specific metadata keys for multiple AI history records (bulk)
+   */
+  static async getBulkSpecificMetas(
+    historyIds: string[],
+    metaKeys: string[],
+    userId: string
+  ): Promise<Record<string, Record<string, unknown>>> {
+    return MetaService.getBulkSpecificEntityMetas(
+      this.ENTITY_TYPE,
+      historyIds,
+      metaKeys,
+      userId
+    );
+  }
+
+  /**
+   * Count metadata entries for an AI history record
+   */
+  static async countMetas(
+    historyId: string,
+    userId: string
+  ): Promise<number> {
+    return MetaService.countEntityMetas(
+      this.ENTITY_TYPE,
+      historyId,
+      userId
+    );
+  }
+}