@centrali-io/centrali-sdk 2.3.0 → 2.3.1

package/README.md

@@ -74,6 +74,8 @@ const centrali = new CentraliSDK({
 - ✅ **Realtime events** - Subscribe to record changes via SSE
 - ✅ **Compute functions** - Execute serverless functions
 - ✅ **File uploads** - Upload files to Centrali storage
+- ✅ **Data Validation** - AI-powered typo detection, format validation, duplicate detection
+- ✅ **Anomaly Insights** - AI-powered anomaly detection and data quality insights
 - ✅ **Service accounts** - Automatic token refresh for server-to-server auth
 
 ## Core Operations
@@ -248,6 +250,48 @@ const subscription = centrali.realtime.subscribe({
 | `record_created` | A new record was created |
 | `record_updated` | An existing record was updated |
 | `record_deleted` | A record was deleted |
+| `validation_suggestion_created` | AI detected a data quality issue |
+| `validation_batch_completed` | Batch validation scan finished |
+| `anomaly_insight_created` | AI detected a data anomaly |
+| `anomaly_detection_completed` | Anomaly detection scan finished |
+
+#### Subscribing to Validation Events
+
+```typescript
+// Subscribe to validation events for a structure
+const subscription = centrali.realtime.subscribe({
+  structures: ['orders'],  // Filter by structure
+  events: ['validation_suggestion_created', 'validation_batch_completed'],
+  onEvent: (event) => {
+    if (event.event === 'validation_suggestion_created') {
+      console.log('New suggestion:', event.data.field, event.data.issueType);
+      console.log('Confidence:', event.data.confidence);
+    } else if (event.event === 'validation_batch_completed') {
+      console.log('Scan complete:', event.data.issuesFound, 'issues found');
+    }
+  }
+});
+```
+
+#### Subscribing to Anomaly Events
+
+```typescript
+// Subscribe to anomaly detection events for a structure
+const subscription = centrali.realtime.subscribe({
+  structures: ['orders'],
+  events: ['anomaly_insight_created', 'anomaly_detection_completed'],
+  onEvent: (event) => {
+    if (event.event === 'anomaly_insight_created') {
+      console.log('New anomaly:', event.data.title);
+      console.log('Severity:', event.data.severity);
+      console.log('Type:', event.data.insightType);
+    } else if (event.event === 'anomaly_detection_completed') {
+      console.log('Analysis complete:', event.data.insightsCreated, 'anomalies found');
+      console.log('Critical:', event.data.criticalCount);
+    }
+  }
+});
+```
 
 #### Reconnection
 
@@ -292,6 +336,122 @@ const uploadResult = await centrali.uploadFile(
 console.log('File URL:', uploadResult.data);
 ```
 
+### Data Validation
+
+AI-powered data quality validation to detect typos, format issues, duplicates, and semantic errors:
+
+```typescript
+// Trigger a batch validation scan on a structure
+const batch = await centrali.validation.triggerScan('orders');
+console.log('Scan started:', batch.data.batchId);
+console.log('Records to scan:', batch.data.total);
+
+// Wait for the scan to complete (with polling)
+const result = await centrali.validation.waitForScan(batch.data.batchId, {
+  pollInterval: 5000,  // Check every 5 seconds
+  timeout: 300000      // Timeout after 5 minutes
+});
+console.log('Issues found:', result.data.issuesFound);
+
+// List pending validation suggestions
+const suggestions = await centrali.validation.listSuggestions({
+  status: 'pending',
+  issueType: 'typo'  // 'format' | 'typo' | 'duplicate' | 'semantic'
+});
+
+// Review a suggestion
+for (const suggestion of suggestions.data) {
+  console.log(`Field: ${suggestion.field}`);
+  console.log(`Original: ${suggestion.originalValue}`);
+  console.log(`Suggested: ${suggestion.suggestedValue}`);
+  console.log(`Confidence: ${suggestion.confidence}`);
+}
+
+// Accept a suggestion (applies the fix to the record)
+const accepted = await centrali.validation.accept('suggestion-id');
+if (accepted.data.recordUpdated) {
+  console.log('Fix applied successfully');
+}
+
+// Reject a suggestion
+await centrali.validation.reject('suggestion-id');
+
+// Bulk accept high-confidence suggestions
+const highConfidence = suggestions.data.filter(s => s.confidence >= 0.95);
+await centrali.validation.bulkAccept(highConfidence.map(s => s.id));
+
+// Get validation summary
+const summary = await centrali.validation.getSummary();
+console.log('Pending:', summary.data.pending);
+console.log('By type:', summary.data.byIssueType);
+
+// Get pending count for a structure
+const count = await centrali.validation.getPendingCount('structure-uuid');
+console.log('Pending issues:', count.data.pendingCount);
+```
+
+#### Validation Issue Types
+
+| Type | Description |
+|------|-------------|
+| `format` | Format validation (email, phone, URL patterns) |
+| `typo` | Spelling mistakes in text fields |
+| `duplicate` | Duplicate records detected |
+| `semantic` | Logical inconsistencies (e.g., end date before start date) |
+
+### Anomaly Insights
+
+AI-powered anomaly detection to identify unusual patterns in your data:
+
+```typescript
+// Trigger anomaly analysis for a structure
+const result = await centrali.anomalyInsights.triggerAnalysis('orders');
+if (result.data.success) {
+  console.log('Analysis started:', result.data.batchId);
+}
+
+// List all active insights
+const insights = await centrali.anomalyInsights.list({
+  status: 'active',
+  severity: 'critical'  // 'info' | 'warning' | 'critical'
+});
+
+// List insights for a specific structure
+const orderInsights = await centrali.anomalyInsights.listByStructure('orders');
+
+// Get a single insight
+const insight = await centrali.anomalyInsights.get('insight-id');
+console.log('Title:', insight.data.title);
+console.log('Description:', insight.data.description);
+console.log('Affected records:', insight.data.affectedRecordIds);
+
+// Acknowledge an insight (mark as reviewed)
+await centrali.anomalyInsights.acknowledge('insight-id');
+
+// Dismiss an insight (mark as not relevant)
+await centrali.anomalyInsights.dismiss('insight-id');
+
+// Bulk acknowledge multiple insights
+await centrali.anomalyInsights.bulkAcknowledge(['id1', 'id2', 'id3']);
+
+// Get insights summary
+const summary = await centrali.anomalyInsights.getSummary();
+console.log('Active:', summary.data.active);
+console.log('By severity:', summary.data.bySeverity);
+```
+
+#### Insight Types
+
+| Type | Description |
+|------|-------------|
+| `time_series_anomaly` | Unusual patterns in time-series data |
+| `statistical_outlier` | Values significantly outside normal ranges |
+| `pattern_deviation` | Deviations from expected data patterns |
+| `volume_spike` | Unusual spikes or drops in data volume |
+| `missing_data` | Missing or null values in required fields |
+| `orphaned_reference` | References to deleted or non-existent records |
+| `reference_integrity` | Broken relationships between records |
+
 ## TypeScript Support
 
 The SDK includes full TypeScript definitions for type-safe development: