@centrali-io/centrali-sdk 2.3.0 → 2.3.2

package/dist/index.js

@@ -18,7 +18,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CentraliSDK = exports.SmartQueriesManager = exports.TriggersManager = exports.RealtimeManager = void 0;
+exports.CentraliSDK = exports.ValidationManager = exports.AnomalyInsightsManager = exports.SmartQueriesManager = exports.TriggersManager = exports.RealtimeManager = void 0;
 exports.getApiUrl = getApiUrl;
 exports.getAuthUrl = getAuthUrl;
 exports.getRealtimeUrl = getRealtimeUrl;
@@ -34,6 +34,22 @@ exports.getSmartQueriesStructureApiPath = getSmartQueriesStructureApiPath;
 exports.getSmartQueryByNameApiPath = getSmartQueryByNameApiPath;
 exports.getSmartQueryExecuteApiPath = getSmartQueryExecuteApiPath;
 exports.getSearchApiPath = getSearchApiPath;
+exports.getAnomalyInsightsApiPath = getAnomalyInsightsApiPath;
+exports.getAnomalyInsightsSummaryApiPath = getAnomalyInsightsSummaryApiPath;
+exports.getAnomalyInsightAcknowledgeApiPath = getAnomalyInsightAcknowledgeApiPath;
+exports.getAnomalyInsightDismissApiPath = getAnomalyInsightDismissApiPath;
+exports.getAnomalyInsightsBulkAcknowledgeApiPath = getAnomalyInsightsBulkAcknowledgeApiPath;
+exports.getAnomalyAnalysisTriggerApiPath = getAnomalyAnalysisTriggerApiPath;
+exports.getStructureInsightsApiPath = getStructureInsightsApiPath;
+exports.getValidationSuggestionsApiPath = getValidationSuggestionsApiPath;
+exports.getValidationSuggestionAcceptApiPath = getValidationSuggestionAcceptApiPath;
+exports.getValidationSuggestionRejectApiPath = getValidationSuggestionRejectApiPath;
+exports.getValidationBulkAcceptApiPath = getValidationBulkAcceptApiPath;
+exports.getValidationBulkRejectApiPath = getValidationBulkRejectApiPath;
+exports.getValidationSummaryApiPath = getValidationSummaryApiPath;
+exports.getValidationRecordSuggestionsApiPath = getValidationRecordSuggestionsApiPath;
+exports.getValidationPendingCountApiPath = getValidationPendingCountApiPath;
+exports.getValidationScanApiPath = getValidationScanApiPath;
 const axios_1 = __importDefault(require("axios"));
 const qs_1 = __importDefault(require("qs"));
 const eventsource_1 = require("eventsource");
@@ -382,6 +398,109 @@ function getSmartQueryExecuteApiPath(workspaceId, structureSlug, queryId) {
 function getSearchApiPath(workspaceId) {
     return `search/workspace/${workspaceId}/api/v1/records/search`;
 }
+/**
+ * Generate Anomaly Insights base API URL PATH.
+ */
+function getAnomalyInsightsApiPath(workspaceId, insightId) {
+    const basePath = `data/workspace/${workspaceId}/api/v1/ai/insights`;
+    return insightId ? `${basePath}/${insightId}` : basePath;
+}
+/**
+ * Generate Anomaly Insights summary API URL PATH.
+ */
+function getAnomalyInsightsSummaryApiPath(workspaceId) {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/summary`;
+}
+/**
+ * Generate Anomaly Insights acknowledge API URL PATH.
+ */
+function getAnomalyInsightAcknowledgeApiPath(workspaceId, insightId) {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/${insightId}/acknowledge`;
+}
+/**
+ * Generate Anomaly Insights dismiss API URL PATH.
+ */
+function getAnomalyInsightDismissApiPath(workspaceId, insightId) {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/${insightId}/dismiss`;
+}
+/**
+ * Generate Anomaly Insights bulk acknowledge API URL PATH.
+ */
+function getAnomalyInsightsBulkAcknowledgeApiPath(workspaceId) {
+    return `data/workspace/${workspaceId}/api/v1/ai/insights/bulk-acknowledge`;
+}
+/**
+ * Generate Anomaly analysis trigger API URL PATH.
+ */
+function getAnomalyAnalysisTriggerApiPath(workspaceId) {
+    return `data/workspace/${workspaceId}/api/v1/ai/anomalies/analyze`;
+}
+/**
+ * Generate structure-scoped anomaly insights API URL PATH.
+ */
+function getStructureInsightsApiPath(workspaceId, structureSlug) {
+    return `data/workspace/${workspaceId}/api/v1/structures/${structureSlug}/insights`;
+}
+// =====================================================
+// Validation API Path Helpers
+// =====================================================
+/**
+ * Generate Validation suggestions base API URL PATH.
+ */
+function getValidationSuggestionsApiPath(workspaceId, suggestionId) {
+    const basePath = `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions`;
+    return suggestionId ? `${basePath}/${suggestionId}` : basePath;
+}
+/**
+ * Generate Validation suggestion accept API URL PATH.
+ */
+function getValidationSuggestionAcceptApiPath(workspaceId, suggestionId) {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/${suggestionId}/accept`;
+}
+/**
+ * Generate Validation suggestion reject API URL PATH.
+ */
+function getValidationSuggestionRejectApiPath(workspaceId, suggestionId) {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/${suggestionId}/reject`;
+}
+/**
+ * Generate Validation bulk accept API URL PATH.
+ */
+function getValidationBulkAcceptApiPath(workspaceId) {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/bulk-accept`;
+}
+/**
+ * Generate Validation bulk reject API URL PATH.
+ */
+function getValidationBulkRejectApiPath(workspaceId) {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/suggestions/bulk-reject`;
+}
+/**
+ * Generate Validation summary API URL PATH.
+ */
+function getValidationSummaryApiPath(workspaceId) {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/summary`;
+}
+/**
+ * Generate Validation record suggestions API URL PATH.
+ */
+function getValidationRecordSuggestionsApiPath(workspaceId, recordId) {
+    return `data/workspace/${workspaceId}/api/v1/ai/validation/records/${recordId}/suggestions`;
+}
+/**
+ * Generate Validation structure pending count API URL PATH.
+ */
+function getValidationPendingCountApiPath(workspaceId, structureId) {
+    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.
+ */
+function getValidationScanApiPath(workspaceId, batchId) {
+    const basePath = `ai/workspace/${workspaceId}/api/v1/validate/scan`;
+    return batchId ? `${basePath}/${batchId}` : basePath;
+}
 // =====================================================
 // Triggers Manager
 // =====================================================
@@ -663,6 +782,425 @@ class SmartQueriesManager {
     }
 }
 exports.SmartQueriesManager = 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');
+ * ```
+ */
+class AnomalyInsightsManager {
+    constructor(workspaceId, requestFn) {
+        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'
+     * });
+     * ```
+     */
+    list(options) {
+        const path = getAnomalyInsightsApiPath(this.workspaceId);
+        return this.requestFn('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');
+     * ```
+     */
+    listByStructure(structureSlug, options) {
+        const path = getStructureInsightsApiPath(this.workspaceId, structureSlug);
+        return this.requestFn('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);
+     * ```
+     */
+    get(insightId) {
+        const path = getAnomalyInsightsApiPath(this.workspaceId, insightId);
+        return this.requestFn('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');
+     * ```
+     */
+    acknowledge(insightId) {
+        const path = getAnomalyInsightAcknowledgeApiPath(this.workspaceId, insightId);
+        return this.requestFn('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');
+     * ```
+     */
+    dismiss(insightId) {
+        const path = getAnomalyInsightDismissApiPath(this.workspaceId, insightId);
+        return this.requestFn('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);
+     * ```
+     */
+    bulkAcknowledge(ids) {
+        const path = getAnomalyInsightsBulkAcknowledgeApiPath(this.workspaceId);
+        return this.requestFn('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');
+     * ```
+     */
+    getSummary(structureSlug) {
+        const path = getAnomalyInsightsSummaryApiPath(this.workspaceId);
+        const params = structureSlug ? { structureSlug } : undefined;
+        return this.requestFn('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);
+     * }
+     * ```
+     */
+    triggerAnalysis(structureSlug) {
+        const path = getAnomalyAnalysisTriggerApiPath(this.workspaceId);
+        return this.requestFn('POST', path, { structureSlug });
+    }
+}
+exports.AnomalyInsightsManager = AnomalyInsightsManager;
+// =====================================================
+// 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));
+ * ```
+ */
+class ValidationManager {
+    constructor(workspaceId, requestFn) {
+        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);
+     * ```
+     */
+    triggerScan(structureSlug, options) {
+        const path = getValidationScanApiPath(this.workspaceId);
+        // Note: workspaceSlug is in URL path, not body
+        return this.requestFn('POST', path, {
+            structureSlug,
+            validationTypes: options === null || options === void 0 ? void 0 : 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);
+     * ```
+     */
+    getScanStatus(batchId) {
+        const path = getValidationScanApiPath(this.workspaceId, batchId);
+        return this.requestFn('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');
+     * ```
+     */
+    waitForScan(batchId, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const pollInterval = (_a = options === null || options === void 0 ? void 0 : options.pollInterval) !== null && _a !== void 0 ? _a : 5000;
+            const timeout = (_b = options === null || options === void 0 ? void 0 : options.timeout) !== null && _b !== void 0 ? _b : 300000;
+            const startTime = Date.now();
+            while (true) {
+                const result = yield 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`);
+                }
+                yield 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
+     * });
+     * ```
+     */
+    listSuggestions(options) {
+        const path = getValidationSuggestionsApiPath(this.workspaceId);
+        return this.requestFn('GET', path, null, options);
+    }
+    /**
+     * Get a single validation suggestion by ID.
+     *
+     * @param suggestionId - The suggestion UUID
+     * @returns The suggestion details
+     */
+    getSuggestion(suggestionId) {
+        const path = getValidationSuggestionsApiPath(this.workspaceId, suggestionId);
+        return this.requestFn('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
+     */
+    getRecordSuggestions(recordId, status) {
+        const path = getValidationRecordSuggestionsApiPath(this.workspaceId, recordId);
+        const params = status ? { status } : undefined;
+        return this.requestFn('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');
+     * }
+     * ```
+     */
+    accept(suggestionId) {
+        const path = getValidationSuggestionAcceptApiPath(this.workspaceId, suggestionId);
+        return this.requestFn('POST', path);
+    }
+    /**
+     * Reject a validation suggestion.
+     *
+     * @param suggestionId - The suggestion UUID
+     * @returns The updated suggestion
+     */
+    reject(suggestionId) {
+        const path = getValidationSuggestionRejectApiPath(this.workspaceId, suggestionId);
+        return this.requestFn('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);
+     * ```
+     */
+    bulkAccept(ids) {
+        const path = getValidationBulkAcceptApiPath(this.workspaceId);
+        return this.requestFn('POST', path, { ids });
+    }
+    /**
+     * Bulk reject multiple suggestions.
+     *
+     * @param ids - Array of suggestion IDs to reject (max 100)
+     * @returns Result with count and any errors
+     */
+    bulkReject(ids) {
+        const path = getValidationBulkRejectApiPath(this.workspaceId);
+        return this.requestFn('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);
+     * ```
+     */
+    getSummary(structureId) {
+        const path = getValidationSummaryApiPath(this.workspaceId);
+        const params = structureId ? { structureId } : undefined;
+        return this.requestFn('GET', path, null, params);
+    }
+    /**
+     * Get the count of pending suggestions for a structure.
+     *
+     * @param structureId - The structure UUID
+     * @returns Object with pending count
+     */
+    getPendingCount(structureId) {
+        const path = getValidationPendingCountApiPath(this.workspaceId, structureId);
+        return this.requestFn('GET', path);
+    }
+}
+exports.ValidationManager = ValidationManager;
 /**
  * Main Centrali SDK client.
  */
@@ -672,6 +1210,8 @@ class CentraliSDK {
         this._realtime = null;
         this._triggers = null;
         this._smartQueries = null;
+        this._anomalyInsights = null;
+        this._validation = null;
         this.options = options;
         this.token = options.token || null;
         const apiUrl = getApiUrl(options.baseUrl);
@@ -782,6 +1322,66 @@ 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');
+     * ```
+     */
+    get anomalyInsights() {
+        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');
+     * ```
+     */
+    get validation() {
+        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.
      */