@centrali-io/centrali-sdk 2.2.3 → 2.3.1

package/index.ts

@@ -19,10 +19,25 @@ const EventSourceImpl: typeof EventSource = typeof EventSource !== 'undefined'
 // =====================================================
 
 /**
- * Event types emitted by the realtime service.
+ * Record event types emitted by the realtime service.
+ */
+export type RecordEventType = 'record_created' | 'record_updated' | 'record_deleted';
+
+/**
+ * Validation event types emitted by the realtime service.
+ */
+export type ValidationEventType = 'validation_suggestion_created' | 'validation_batch_completed';
+
+/**
+ * Anomaly event types emitted by the realtime service.
+ */
+export type AnomalyEventType = 'anomaly_insight_created' | 'anomaly_detection_completed';
+
+/**
+ * All event types emitted by the realtime service.
  * Matches: services/backend/realtime/internal/redis/message.go
  */
-export type RealtimeEventType = 'record_created' | 'record_updated' | 'record_deleted';
+export type RealtimeEventType = RecordEventType | ValidationEventType | AnomalyEventType;
 
 /**
  * Record event payload from the realtime service.
@@ -30,7 +45,7 @@ export type RealtimeEventType = 'record_created' | 'record_updated' | 'record_de
  */
 export interface RealtimeRecordEvent {
     /** Event type */
-    event: RealtimeEventType;
+    event: RecordEventType;
     /** Workspace slug where the event occurred */
     workspaceSlug: string;
     /** Structure's record slug (e.g., "order") */
@@ -49,6 +64,184 @@ export interface RealtimeRecordEvent {
     deletedBy?: string;
 }
 
+/**
+ * Validation suggestion data nested in the event.
+ */
+export interface ValidationSuggestionData {
+    /** Structure slug */
+    structureSlug: string;
+    /** Field with the issue */
+    field: string;
+    /** Type of issue */
+    issueType: 'format' | 'typo' | 'duplicate' | 'semantic';
+    /** Original value */
+    originalValue: string | null;
+    /** Suggested value */
+    suggestedValue: string | null;
+    /** Confidence score 0-1 */
+    confidence: number;
+    /** Suggestion status */
+    status: 'pending' | 'auto-applied';
+    /** Batch ID if from a batch scan */
+    batchId: string | null;
+}
+
+/**
+ * Validation suggestion created event payload.
+ * Matches the format published by process_validation_events.ts
+ */
+export interface RealtimeValidationSuggestionEvent {
+    /** Event type */
+    event: 'validation_suggestion_created';
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** Record slug (structure slug for filtering) */
+    recordSlug: string;
+    /** Record ID the suggestion applies to */
+    recordId: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Validation-specific data */
+    data: ValidationSuggestionData;
+}
+
+/**
+ * Validation batch data nested in the event.
+ */
+export interface ValidationBatchData {
+    /** Structure slug that was scanned */
+    structureSlug: string;
+    /** Batch ID */
+    batchId: string;
+    /** Total records processed */
+    processed: number;
+    /** Issues found */
+    issuesFound: number;
+    /** Issues auto-applied */
+    autoApplied: number;
+    /** Final status */
+    status: 'completed' | 'failed';
+    /** Error message if failed */
+    error?: string;
+    /** When scan started */
+    startedAt: string;
+    /** When scan completed */
+    completedAt: string;
+}
+
+/**
+ * Validation batch completed event payload.
+ * Matches the format published by process_validation_events.ts
+ */
+export interface RealtimeValidationBatchEvent {
+    /** Event type */
+    event: 'validation_batch_completed';
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** Record slug (structure slug for filtering) */
+    recordSlug: string;
+    /** Record ID (batch ID for tracking) */
+    recordId: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Batch-specific data */
+    data: ValidationBatchData;
+}
+
+/**
+ * Anomaly insight data nested in the event.
+ */
+export interface AnomalyInsightData {
+    /** Structure ID */
+    structureId: string;
+    /** Structure slug */
+    structureSlug: string;
+    /** Insight ID */
+    insightId: string;
+    /** Type of anomaly detected */
+    insightType: 'time_series_anomaly' | 'statistical_outlier' | 'pattern_deviation' | 'volume_spike' | 'missing_data' | 'orphaned_reference' | 'reference_integrity';
+    /** Severity level */
+    severity: 'info' | 'warning' | 'critical';
+    /** Short title */
+    title: string;
+    /** Detailed description */
+    description: string;
+    /** Affected field if applicable */
+    affectedField?: string;
+    /** IDs of affected records */
+    affectedRecordIds?: string[];
+    /** Confidence score 0-1 */
+    confidence: number;
+    /** Batch ID if from batch analysis */
+    batchId?: string;
+}
+
+/**
+ * Anomaly insight created event payload.
+ * Matches the format published by process_anomaly_events.ts
+ */
+export interface RealtimeAnomalyInsightEvent {
+    /** Event type */
+    event: 'anomaly_insight_created';
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** Record slug (structure slug for filtering) */
+    recordSlug: string;
+    /** Record ID (insight ID for tracking) */
+    recordId: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Anomaly insight data */
+    data: AnomalyInsightData;
+}
+
+/**
+ * Anomaly detection batch data nested in the event.
+ */
+export interface AnomalyDetectionData {
+    /** Structure ID */
+    structureId: string;
+    /** Structure slug */
+    structureSlug: string;
+    /** Batch ID */
+    batchId: string;
+    /** Number of insights created */
+    insightsCreated: number;
+    /** Number of records analyzed */
+    recordsAnalyzed: number;
+    /** Types of analysis performed */
+    analysisTypes: string[];
+    /** Count of critical severity insights */
+    criticalCount: number;
+    /** Count of warning severity insights */
+    warningCount: number;
+    /** Count of info severity insights */
+    infoCount: number;
+    /** When analysis started */
+    startedAt: string;
+    /** When analysis completed */
+    completedAt: string;
+}
+
+/**
+ * Anomaly detection completed event payload.
+ * Matches the format published by process_anomaly_events.ts
+ */
+export interface RealtimeAnomalyDetectionEvent {
+    /** Event type */
+    event: 'anomaly_detection_completed';
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** Record slug (structure slug for filtering) */
+    recordSlug: string;
+    /** Record ID (batch ID for tracking) */
+    recordId: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Anomaly detection data */
+    data: AnomalyDetectionData;
+}
+
 /**
  * Close event payload from the realtime service.
  */
@@ -62,7 +255,7 @@ export interface RealtimeCloseEvent {
 /**
  * Union type of all realtime events.
  */
-export type RealtimeEvent = RealtimeRecordEvent;
+export type RealtimeEvent = RealtimeRecordEvent | RealtimeValidationSuggestionEvent | RealtimeValidationBatchEvent | RealtimeAnomalyInsightEvent | RealtimeAnomalyDetectionEvent;
 
 /**
  * Error object for realtime connection errors.
@@ -381,6 +574,287 @@ export interface SearchResponse {
     query: string;
 }
 
+// =====================================================
+// Anomaly Insights Types
+// =====================================================
+
+/**
+ * Anomaly insight types.
+ */
+export type InsightType = 'time_series_anomaly' | 'statistical_outlier' | 'pattern_deviation' | 'volume_spike' | 'missing_data' | 'orphaned_reference' | 'reference_integrity';
+
+/**
+ * Anomaly insight severity levels.
+ */
+export type InsightSeverity = 'info' | 'warning' | 'critical';
+
+/**
+ * Anomaly insight status.
+ */
+export type InsightStatus = 'active' | 'acknowledged' | 'dismissed';
+
+/**
+ * Anomaly insight record.
+ */
+export interface AnomalyInsight {
+    /** Unique identifier */
+    id: string;
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** Structure ID */
+    structureId: string;
+    /** Structure slug */
+    structureSlug: string;
+    /** Batch ID if created in batch */
+    batchId: string | null;
+    /** Type of insight */
+    insightType: InsightType;
+    /** Severity level */
+    severity: InsightSeverity;
+    /** Short title */
+    title: string;
+    /** Detailed description */
+    description: string;
+    /** Affected field if applicable */
+    affectedField: string | null;
+    /** IDs of affected records */
+    affectedRecordIds: string[] | null;
+    /** Additional metadata */
+    metadata: Record<string, any>;
+    /** Confidence score 0-1 */
+    confidence: number;
+    /** Current status */
+    status: InsightStatus;
+    /** When acknowledged */
+    acknowledgedAt: string | null;
+    /** Who acknowledged */
+    acknowledgedBy: string | null;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+}
+
+/**
+ * Options for listing anomaly insights.
+ */
+export interface ListInsightsOptions {
+    /** Filter by severity */
+    severity?: InsightSeverity;
+    /** Filter by status */
+    status?: InsightStatus;
+    /** Filter by insight type */
+    type?: InsightType;
+    /** Filter by structure slug */
+    structureSlug?: string;
+    /** Maximum results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+
+/**
+ * Result of triggering anomaly analysis.
+ */
+export interface AnomalyAnalysisResult {
+    /** Whether the analysis was triggered */
+    success: boolean;
+    /** Status message */
+    message: string;
+    /** Batch ID for tracking (if triggered) */
+    batchId?: string;
+}
+
+/**
+ * Summary of anomaly insights.
+ */
+export interface InsightsSummary {
+    /** Total insights */
+    total: number;
+    /** Active insights */
+    active: number;
+    /** Acknowledged insights */
+    acknowledged: number;
+    /** Dismissed insights */
+    dismissed: number;
+    /** Breakdown by severity */
+    bySeverity: {
+        critical: number;
+        warning: number;
+        info: number;
+    };
+    /** Breakdown by type */
+    byType: Record<string, number>;
+}
+
+// =====================================================
+// Validation Types (Data Quality)
+// =====================================================
+
+/**
+ * Validation issue types.
+ * - 'type': Schema type mismatch (e.g., string where array expected) - rule-based
+ * - 'format': Format validation (email, phone, url patterns) - rule-based
+ * - 'typo': Spelling/typo detection - AI-based
+ * - 'duplicate': Duplicate record detection - rule-based
+ * - 'semantic': Logical/semantic issues - AI-based
+ */
+export type ValidationIssueType = 'type' | 'format' | 'typo' | 'duplicate' | 'semantic';
+
+/**
+ * Validation suggestion status.
+ */
+export type ValidationSuggestionStatus = 'pending' | 'accepted' | 'rejected' | 'auto-applied';
+
+/**
+ * A validation suggestion from the AI validation system.
+ */
+export interface ValidationSuggestion {
+    /** Unique identifier */
+    id: string;
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** Structure ID */
+    structureId: string;
+    /** Record ID */
+    recordId: string;
+    /** Structure's record slug */
+    recordSlug: string;
+    /** Field name with the issue */
+    field: string;
+    /** Type of issue detected */
+    issueType: ValidationIssueType;
+    /** Original value in the field */
+    originalValue: string | null;
+    /** Suggested corrected value */
+    suggestedValue: string | null;
+    /** Confidence score 0-1 */
+    confidence: number;
+    /** Current status */
+    status: ValidationSuggestionStatus;
+    /** Batch ID if created during batch scan */
+    batchId: string | null;
+    /** Additional metadata */
+    metadata: Record<string, any>;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+    /** When resolved (accepted/rejected) */
+    resolvedAt: string | null;
+    /** Who resolved */
+    resolvedBy: string | null;
+}
+
+/**
+ * Options for listing validation suggestions.
+ */
+export interface ListValidationSuggestionsOptions {
+    /** Filter by structure ID */
+    structureId?: string;
+    /** Filter by record ID */
+    recordId?: string;
+    /** Filter by status */
+    status?: ValidationSuggestionStatus;
+    /** Filter by issue type */
+    issueType?: ValidationIssueType;
+    /** Filter by batch ID */
+    batchId?: string;
+    /** Minimum confidence threshold */
+    minConfidence?: number;
+    /** Maximum results (default: 50, max: 100) */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+
+/**
+ * Batch scan status.
+ */
+export type BatchScanStatus = 'queued' | 'pending' | 'processing' | 'completed' | 'failed';
+
+/**
+ * Result from triggering a batch validation scan.
+ */
+export interface BatchScanResult {
+    /** Unique batch identifier */
+    batchId: string;
+    /** Current status */
+    status: BatchScanStatus;
+    /** Total records to scan */
+    total: number;
+    /** Records processed so far */
+    processed: number;
+    /** Issues found so far */
+    issuesFound: number;
+    /** When the scan started */
+    startedAt: string;
+    /** When the scan completed (if finished) */
+    completedAt?: string;
+    /** Error message if failed */
+    error?: string;
+}
+
+/**
+ * Options for triggering a batch scan.
+ */
+export interface TriggerScanOptions {
+    /** Validation types to run (defaults to structure config) */
+    validationTypes?: ValidationIssueType[];
+}
+
+/**
+ * Options for waiting for a scan to complete.
+ */
+export interface WaitForScanOptions {
+    /** Poll interval in milliseconds (default: 5000) */
+    pollInterval?: number;
+    /** Timeout in milliseconds (default: 300000 = 5 minutes) */
+    timeout?: number;
+}
+
+/**
+ * Summary of validation suggestions.
+ */
+export interface ValidationSummary {
+    /** Total suggestions */
+    total: number;
+    /** Pending suggestions */
+    pending: number;
+    /** Accepted suggestions */
+    accepted: number;
+    /** Rejected suggestions */
+    rejected: number;
+    /** Auto-applied suggestions */
+    autoApplied: number;
+    /** Breakdown by issue type */
+    byIssueType: Record<string, number>;
+}
+
+/**
+ * Result from accepting a suggestion.
+ */
+export interface AcceptSuggestionResult {
+    /** The updated suggestion */
+    suggestion: ValidationSuggestion;
+    /** Whether the record was updated */
+    recordUpdated: boolean;
+    /** Status message */
+    message: string;
+}
+
+/**
+ * Result from bulk operations.
+ */
+export interface BulkOperationResult {
+    /** Number of successful operations */
+    count: number;
+    /** Errors for failed operations */
+    errors?: Array<{ id: string; error: string }>;
+    /** Status message */
+    message: string;
+}
+
 /**
  * Generate the API URL from the base URL by adding the 'api.' subdomain.
  * E.g., https://centrali.io -> https://api.centrali.io
@@ -769,6 +1243,126 @@ export function getSearchApiPath(workspaceId: string): string {
     return `search/workspace/${workspaceId}/api/v1/records/search`;
 }
 
+/**
+ * Generate Anomaly Insights base API URL PATH.
+ */
+export function getAnomalyInsightsApiPath(workspaceId: string, insightId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/ai/insights`;
+    return insightId ? `${basePath}/${insightId}` : basePath;
+}
+
+/**
+ * Generate Anomaly Insights summary API URL PATH.
+ */
+export function getAnomalyInsightsSummaryApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/summary`;
+}
+
+/**
+ * Generate Anomaly Insights acknowledge API URL PATH.
+ */
+export function getAnomalyInsightAcknowledgeApiPath(workspaceId: string, insightId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/${insightId}/acknowledge`;
+}
+
+/**
+ * Generate Anomaly Insights dismiss API URL PATH.
+ */
+export function getAnomalyInsightDismissApiPath(workspaceId: string, insightId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/${insightId}/dismiss`;
+}
+
+/**
+ * Generate Anomaly Insights bulk acknowledge API URL PATH.
+ */
+export function getAnomalyInsightsBulkAcknowledgeApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/bulk-acknowledge`;
+}
+
+/**
+ * Generate Anomaly analysis trigger API URL PATH.
+ */
+export function getAnomalyAnalysisTriggerApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/anomalies/analyze`;
+}
+
+/**
+ * Generate structure-scoped anomaly insights API URL PATH.
+ */
+export function getStructureInsightsApiPath(workspaceId: string, structureSlug: string): string {
+    return `data/workspace/${workspaceId}/api/v1/structures/${structureSlug}/insights`;
+}
+
+// =====================================================
+// Validation API Path Helpers
+// =====================================================
+
+/**
+ * Generate Validation suggestions base API URL PATH.
+ */
+export function getValidationSuggestionsApiPath(workspaceId: string, suggestionId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions`;
+    return suggestionId ? `${basePath}/${suggestionId}` : basePath;
+}
+
+/**
+ * Generate Validation suggestion accept API URL PATH.
+ */
+export function getValidationSuggestionAcceptApiPath(workspaceId: string, suggestionId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/${suggestionId}/accept`;
+}
+
+/**
+ * Generate Validation suggestion reject API URL PATH.
+ */
+export function getValidationSuggestionRejectApiPath(workspaceId: string, suggestionId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/${suggestionId}/reject`;
+}
+
+/**
+ * Generate Validation bulk accept API URL PATH.
+ */
+export function getValidationBulkAcceptApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/bulk-accept`;
+}
+
+/**
+ * Generate Validation bulk reject API URL PATH.
+ */
+export function getValidationBulkRejectApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/bulk-reject`;
+}
+
+/**
+ * Generate Validation summary API URL PATH.
+ */
+export function getValidationSummaryApiPath(workspaceId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/summary`;
+}
+
+/**
+ * Generate Validation record suggestions API URL PATH.
+ */
+export function getValidationRecordSuggestionsApiPath(workspaceId: string, recordId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/records/${recordId}/suggestions`;
+}
+
+/**
+ * Generate Validation structure pending count API URL PATH.
+ */
+export function getValidationPendingCountApiPath(workspaceId: string, structureId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/structures/${structureId}/pending-count`;
+}
+
+/**
+ * Generate Validation batch scan API URL PATH (AI Service).
+ * Note: This routes to the AI service, not the Data service.
+ */
+export function getValidationScanApiPath(workspaceId: string, batchId?: string): string {
+    const basePath = `ai/workspace/${workspaceId}/api/v1/validate/scan`;
+    return batchId ? `${basePath}/${batchId}` : basePath;
+}
+
 // =====================================================
 // Triggers Manager
 // =====================================================
@@ -1082,6 +1676,475 @@ export class SmartQueriesManager {
     }
 }
 
+// =====================================================
+// Anomaly Insights Manager
+// =====================================================
+
+/**
+ * AnomalyInsightsManager provides methods for querying and managing AI-generated anomaly insights.
+ * Access via `client.anomalyInsights`.
+ *
+ * Usage:
+ * ```ts
+ * // List all active insights
+ * const insights = await client.anomalyInsights.list({ status: 'active' });
+ *
+ * // Get insights for a specific structure
+ * const orderInsights = await client.anomalyInsights.listByStructure('orders');
+ *
+ * // Get insight summary
+ * const summary = await client.anomalyInsights.getSummary();
+ *
+ * // Acknowledge an insight
+ * await client.anomalyInsights.acknowledge('insight-id');
+ *
+ * // Dismiss an insight
+ * await client.anomalyInsights.dismiss('insight-id');
+ * ```
+ */
+export class AnomalyInsightsManager {
+    private requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>;
+    private workspaceId: string;
+
+    constructor(
+        workspaceId: string,
+        requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>
+    ) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+    }
+
+    /**
+     * List anomaly insights with optional filters.
+     *
+     * @param options - Optional filter and pagination options
+     * @returns List of anomaly insights
+     *
+     * @example
+     * ```ts
+     * // List all active critical insights
+     * const insights = await client.anomalyInsights.list({
+     *   status: 'active',
+     *   severity: 'critical'
+     * });
+     *
+     * // List insights for a specific structure
+     * const orderInsights = await client.anomalyInsights.list({
+     *   structureSlug: 'orders'
+     * });
+     * ```
+     */
+    public list(options?: ListInsightsOptions): Promise<ApiResponse<AnomalyInsight[]>> {
+        const path = getAnomalyInsightsApiPath(this.workspaceId);
+        return this.requestFn<AnomalyInsight[]>('GET', path, null, options);
+    }
+
+    /**
+     * List insights for a specific structure.
+     *
+     * @param structureSlug - The structure's record slug
+     * @param options - Optional filter options
+     * @returns List of insights for the structure
+     *
+     * @example
+     * ```ts
+     * const insights = await client.anomalyInsights.listByStructure('orders');
+     * ```
+     */
+    public listByStructure(
+        structureSlug: string,
+        options?: Omit<ListInsightsOptions, 'structureSlug'>
+    ): Promise<ApiResponse<AnomalyInsight[]>> {
+        const path = getStructureInsightsApiPath(this.workspaceId, structureSlug);
+        return this.requestFn<AnomalyInsight[]>('GET', path, null, options);
+    }
+
+    /**
+     * Get a single insight by ID.
+     *
+     * @param insightId - The insight UUID
+     * @returns The insight details
+     *
+     * @example
+     * ```ts
+     * const insight = await client.anomalyInsights.get('insight-id');
+     * console.log('Insight:', insight.data.title);
+     * ```
+     */
+    public get(insightId: string): Promise<ApiResponse<AnomalyInsight>> {
+        const path = getAnomalyInsightsApiPath(this.workspaceId, insightId);
+        return this.requestFn<AnomalyInsight>('GET', path);
+    }
+
+    /**
+     * Acknowledge an insight.
+     * Marks the insight as reviewed/handled.
+     *
+     * @param insightId - The insight UUID
+     * @returns The updated insight
+     *
+     * @example
+     * ```ts
+     * await client.anomalyInsights.acknowledge('insight-id');
+     * ```
+     */
+    public acknowledge(insightId: string): Promise<ApiResponse<AnomalyInsight>> {
+        const path = getAnomalyInsightAcknowledgeApiPath(this.workspaceId, insightId);
+        return this.requestFn<AnomalyInsight>('POST', path);
+    }
+
+    /**
+     * Dismiss an insight.
+     * Marks the insight as not relevant/false positive.
+     *
+     * @param insightId - The insight UUID
+     * @returns The updated insight
+     *
+     * @example
+     * ```ts
+     * await client.anomalyInsights.dismiss('insight-id');
+     * ```
+     */
+    public dismiss(insightId: string): Promise<ApiResponse<AnomalyInsight>> {
+        const path = getAnomalyInsightDismissApiPath(this.workspaceId, insightId);
+        return this.requestFn<AnomalyInsight>('POST', path);
+    }
+
+    /**
+     * Bulk acknowledge multiple insights.
+     *
+     * @param ids - Array of insight IDs to acknowledge
+     * @returns Result with count of updated insights
+     *
+     * @example
+     * ```ts
+     * const result = await client.anomalyInsights.bulkAcknowledge(['id1', 'id2']);
+     * console.log('Acknowledged:', result.data.updated);
+     * ```
+     */
+    public bulkAcknowledge(ids: string[]): Promise<ApiResponse<{ updated: number; message: string }>> {
+        const path = getAnomalyInsightsBulkAcknowledgeApiPath(this.workspaceId);
+        return this.requestFn<{ updated: number; message: string }>('POST', path, { ids });
+    }
+
+    /**
+     * Get insights summary/statistics.
+     *
+     * @param structureSlug - Optional structure to filter summary
+     * @returns Summary of insights by status and severity
+     *
+     * @example
+     * ```ts
+     * // Get overall summary
+     * const summary = await client.anomalyInsights.getSummary();
+     * console.log('Critical insights:', summary.data.bySeverity.critical);
+     *
+     * // Get summary for a specific structure
+     * const orderSummary = await client.anomalyInsights.getSummary('orders');
+     * ```
+     */
+    public getSummary(structureSlug?: string): Promise<ApiResponse<InsightsSummary>> {
+        const path = getAnomalyInsightsSummaryApiPath(this.workspaceId);
+        const params = structureSlug ? { structureSlug } : undefined;
+        return this.requestFn<InsightsSummary>('GET', path, null, params);
+    }
+
+    /**
+     * Trigger anomaly analysis for a structure.
+     * Starts an AI-powered analysis to detect anomalies in the structure's data.
+     *
+     * @param structureSlug - The structure's record slug to analyze
+     * @returns Result indicating if analysis was triggered and the batch ID
+     *
+     * @example
+     * ```ts
+     * const result = await client.anomalyInsights.triggerAnalysis('orders');
+     * if (result.data.success) {
+     *   console.log('Analysis started:', result.data.batchId);
+     * }
+     * ```
+     */
+    public triggerAnalysis(structureSlug: string): Promise<ApiResponse<AnomalyAnalysisResult>> {
+        const path = getAnomalyAnalysisTriggerApiPath(this.workspaceId);
+        return this.requestFn<AnomalyAnalysisResult>('POST', path, { structureSlug });
+    }
+}
+
+// =====================================================
+// Validation Manager (Data Quality)
+// =====================================================
+
+/**
+ * ValidationManager provides methods for AI-powered data quality validation.
+ * Access via `client.validation`.
+ *
+ * Features:
+ * - Trigger batch validation scans on structures
+ * - List and manage validation suggestions (typos, format issues, duplicates)
+ * - Accept or reject suggestions to fix data
+ * - Get validation summaries and statistics
+ *
+ * Usage:
+ * ```ts
+ * // Trigger a batch scan
+ * const batch = await client.validation.triggerScan('orders');
+ * console.log('Scan started:', batch.data.batchId);
+ *
+ * // Wait for completion
+ * const result = await client.validation.waitForScan(batch.data.batchId);
+ *
+ * // List pending suggestions
+ * const suggestions = await client.validation.listSuggestions({ status: 'pending' });
+ *
+ * // Accept a suggestion (applies the fix)
+ * await client.validation.accept('suggestion-id');
+ *
+ * // Bulk accept high-confidence suggestions
+ * const highConfidence = suggestions.data.filter(s => s.confidence >= 0.95);
+ * await client.validation.bulkAccept(highConfidence.map(s => s.id));
+ * ```
+ */
+export class ValidationManager {
+    private requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>;
+    private workspaceId: string;
+
+    constructor(
+        workspaceId: string,
+        requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>
+    ) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+    }
+
+    /**
+     * Trigger a batch validation scan on a structure.
+     *
+     * @param structureSlug - The structure's slug to scan
+     * @param options - Optional scan configuration
+     * @returns The batch scan result with batchId for tracking
+     *
+     * @example
+     * ```ts
+     * const batch = await client.validation.triggerScan('orders');
+     * console.log('Batch ID:', batch.data.batchId);
+     * console.log('Records to scan:', batch.data.total);
+     * ```
+     */
+    public triggerScan(
+        structureSlug: string,
+        options?: TriggerScanOptions
+    ): Promise<ApiResponse<BatchScanResult>> {
+        const path = getValidationScanApiPath(this.workspaceId);
+        // Note: workspaceSlug is in URL path, not body
+        return this.requestFn<BatchScanResult>('POST', path, {
+            structureSlug,
+            validationTypes: options?.validationTypes,
+        });
+    }
+
+    /**
+     * Get the status of a batch validation scan.
+     *
+     * @param batchId - The batch scan ID
+     * @returns Current scan status and progress
+     *
+     * @example
+     * ```ts
+     * const status = await client.validation.getScanStatus('batch-id');
+     * console.log('Progress:', status.data.processed, '/', status.data.total);
+     * ```
+     */
+    public getScanStatus(batchId: string): Promise<ApiResponse<BatchScanResult>> {
+        const path = getValidationScanApiPath(this.workspaceId, batchId);
+        return this.requestFn<BatchScanResult>('GET', path);
+    }
+
+    /**
+     * Wait for a batch scan to complete with polling.
+     *
+     * @param batchId - The batch scan ID
+     * @param options - Polling configuration
+     * @returns The final scan result
+     * @throws Error if scan fails or times out
+     *
+     * @example
+     * ```ts
+     * const result = await client.validation.waitForScan('batch-id', {
+     *   pollInterval: 5000,  // 5 seconds
+     *   timeout: 300000      // 5 minutes
+     * });
+     * console.log('Scan complete:', result.data.issuesFound, 'issues found');
+     * ```
+     */
+    public async waitForScan(
+        batchId: string,
+        options?: WaitForScanOptions
+    ): Promise<ApiResponse<BatchScanResult>> {
+        const pollInterval = options?.pollInterval ?? 5000;
+        const timeout = options?.timeout ?? 300000;
+        const startTime = Date.now();
+
+        while (true) {
+            const result = await this.getScanStatus(batchId);
+            const status = result.data.status;
+
+            if (status === 'completed') {
+                return result;
+            }
+
+            if (status === 'failed') {
+                throw new Error(`Scan failed: ${result.data.error || 'Unknown error'}`);
+            }
+
+            if (Date.now() - startTime > timeout) {
+                throw new Error(`Scan timed out after ${timeout}ms`);
+            }
+
+            await new Promise(resolve => setTimeout(resolve, pollInterval));
+        }
+    }
+
+    /**
+     * List validation suggestions with optional filters.
+     *
+     * @param options - Filter and pagination options
+     * @returns List of validation suggestions
+     *
+     * @example
+     * ```ts
+     * // List all pending suggestions
+     * const pending = await client.validation.listSuggestions({ status: 'pending' });
+     *
+     * // List high-confidence typo suggestions
+     * const typos = await client.validation.listSuggestions({
+     *   issueType: 'typo',
+     *   minConfidence: 0.9
+     * });
+     * ```
+     */
+    public listSuggestions(
+        options?: ListValidationSuggestionsOptions
+    ): Promise<ApiResponse<ValidationSuggestion[]>> {
+        const path = getValidationSuggestionsApiPath(this.workspaceId);
+        return this.requestFn<ValidationSuggestion[]>('GET', path, null, options);
+    }
+
+    /**
+     * Get a single validation suggestion by ID.
+     *
+     * @param suggestionId - The suggestion UUID
+     * @returns The suggestion details
+     */
+    public getSuggestion(suggestionId: string): Promise<ApiResponse<ValidationSuggestion>> {
+        const path = getValidationSuggestionsApiPath(this.workspaceId, suggestionId);
+        return this.requestFn<ValidationSuggestion>('GET', path);
+    }
+
+    /**
+     * Get all suggestions for a specific record.
+     *
+     * @param recordId - The record UUID
+     * @param status - Optional status filter
+     * @returns List of suggestions for the record
+     */
+    public getRecordSuggestions(
+        recordId: string,
+        status?: ValidationSuggestionStatus
+    ): Promise<ApiResponse<ValidationSuggestion[]>> {
+        const path = getValidationRecordSuggestionsApiPath(this.workspaceId, recordId);
+        const params = status ? { status } : undefined;
+        return this.requestFn<ValidationSuggestion[]>('GET', path, null, params);
+    }
+
+    /**
+     * Accept a validation suggestion and apply the fix to the record.
+     *
+     * @param suggestionId - The suggestion UUID
+     * @returns Result with updated suggestion and record status
+     *
+     * @example
+     * ```ts
+     * const result = await client.validation.accept('suggestion-id');
+     * if (result.data.recordUpdated) {
+     *   console.log('Fix applied successfully');
+     * }
+     * ```
+     */
+    public accept(suggestionId: string): Promise<ApiResponse<AcceptSuggestionResult>> {
+        const path = getValidationSuggestionAcceptApiPath(this.workspaceId, suggestionId);
+        return this.requestFn<AcceptSuggestionResult>('POST', path);
+    }
+
+    /**
+     * Reject a validation suggestion.
+     *
+     * @param suggestionId - The suggestion UUID
+     * @returns The updated suggestion
+     */
+    public reject(suggestionId: string): Promise<ApiResponse<ValidationSuggestion>> {
+        const path = getValidationSuggestionRejectApiPath(this.workspaceId, suggestionId);
+        return this.requestFn<ValidationSuggestion>('POST', path);
+    }
+
+    /**
+     * Bulk accept multiple suggestions.
+     *
+     * @param ids - Array of suggestion IDs to accept (max 100)
+     * @returns Result with count and any errors
+     *
+     * @example
+     * ```ts
+     * const result = await client.validation.bulkAccept(['id1', 'id2', 'id3']);
+     * console.log('Accepted:', result.data.count);
+     * ```
+     */
+    public bulkAccept(ids: string[]): Promise<ApiResponse<BulkOperationResult>> {
+        const path = getValidationBulkAcceptApiPath(this.workspaceId);
+        return this.requestFn<BulkOperationResult>('POST', path, { ids });
+    }
+
+    /**
+     * Bulk reject multiple suggestions.
+     *
+     * @param ids - Array of suggestion IDs to reject (max 100)
+     * @returns Result with count and any errors
+     */
+    public bulkReject(ids: string[]): Promise<ApiResponse<BulkOperationResult>> {
+        const path = getValidationBulkRejectApiPath(this.workspaceId);
+        return this.requestFn<BulkOperationResult>('POST', path, { ids });
+    }
+
+    /**
+     * Get validation summary statistics.
+     *
+     * @param structureId - Optional structure ID to filter summary
+     * @returns Summary of suggestions by status and type
+     *
+     * @example
+     * ```ts
+     * const summary = await client.validation.getSummary();
+     * console.log('Pending:', summary.data.pending);
+     * console.log('By type:', summary.data.byIssueType);
+     * ```
+     */
+    public getSummary(structureId?: string): Promise<ApiResponse<ValidationSummary>> {
+        const path = getValidationSummaryApiPath(this.workspaceId);
+        const params = structureId ? { structureId } : undefined;
+        return this.requestFn<ValidationSummary>('GET', path, null, params);
+    }
+
+    /**
+     * Get the count of pending suggestions for a structure.
+     *
+     * @param structureId - The structure UUID
+     * @returns Object with pending count
+     */
+    public getPendingCount(structureId: string): Promise<ApiResponse<{ structureId: string; pendingCount: number }>> {
+        const path = getValidationPendingCountApiPath(this.workspaceId, structureId);
+        return this.requestFn<{ structureId: string; pendingCount: number }>('GET', path);
+    }
+}
+
 /**
  * Main Centrali SDK client.
  */
@@ -1092,6 +2155,8 @@ export class CentraliSDK {
     private _realtime: RealtimeManager | null = null;
     private _triggers: TriggersManager | null = null;
     private _smartQueries: SmartQueriesManager | null = null;
+    private _anomalyInsights: AnomalyInsightsManager | null = null;
+    private _validation: ValidationManager | null = null;
 
     constructor(options: CentraliSDKOptions) {
         this.options = options;
@@ -1235,6 +2300,74 @@ export class CentraliSDK {
         return this._smartQueries;
     }
 
+    /**
+     * Anomaly Insights namespace for querying and managing AI-generated insights.
+     *
+     * Usage:
+     * ```ts
+     * // List all active critical insights
+     * const insights = await client.anomalyInsights.list({
+     *   status: 'active',
+     *   severity: 'critical'
+     * });
+     *
+     * // Get insights for a specific structure
+     * const orderInsights = await client.anomalyInsights.listByStructure('orders');
+     *
+     * // Get insight summary
+     * const summary = await client.anomalyInsights.getSummary();
+     * console.log('Critical:', summary.data.bySeverity.critical);
+     *
+     * // Acknowledge an insight
+     * await client.anomalyInsights.acknowledge('insight-id');
+     *
+     * // Dismiss an insight
+     * await client.anomalyInsights.dismiss('insight-id');
+     * ```
+     */
+    public get anomalyInsights(): AnomalyInsightsManager {
+        if (!this._anomalyInsights) {
+            this._anomalyInsights = new AnomalyInsightsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._anomalyInsights;
+    }
+
+    /**
+     * Validation namespace for AI-powered data quality validation.
+     *
+     * Features:
+     * - Trigger batch validation scans on structures
+     * - List and manage validation suggestions (typos, format issues, duplicates)
+     * - Accept or reject suggestions to fix data
+     *
+     * Usage:
+     * ```ts
+     * // Trigger a batch scan
+     * const batch = await client.validation.triggerScan('orders');
+     *
+     * // Wait for completion
+     * const result = await client.validation.waitForScan(batch.data.batchId);
+     *
+     * // List pending suggestions
+     * const suggestions = await client.validation.listSuggestions({ status: 'pending' });
+     *
+     * // Accept a suggestion (applies the fix)
+     * await client.validation.accept('suggestion-id');
+     * ```
+     */
+    public get validation(): ValidationManager {
+        if (!this._validation) {
+            this._validation = new ValidationManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._validation;
+    }
+
     /**
      * Manually set or update the bearer token for subsequent requests.
      */