@centrali-io/centrali-sdk 5.5.0 → 6.0.0

package/src/managers/validation.ts

@@ -0,0 +1,303 @@
+// =====================================================
+// Validation Manager (Data Quality)
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type {
+    BatchScanResult,
+    TriggerScanOptions,
+    WaitForScanOptions,
+    ValidationSuggestion,
+    ValidationSuggestionStatus,
+    ListValidationSuggestionsOptions,
+    AcceptSuggestionResult,
+    BulkOperationResult,
+    ValidationSummary,
+} from '../types/validation';
+import {
+    getValidationScanApiPath,
+    getValidationSuggestionsApiPath,
+    getValidationRecordSuggestionsApiPath,
+    getValidationSuggestionAcceptApiPath,
+    getValidationSuggestionRejectApiPath,
+    getValidationBulkAcceptApiPath,
+    getValidationBulkRejectApiPath,
+    getValidationSummaryApiPath,
+    getValidationPendingCountApiPath,
+} from '../internal/paths';
+
+// =====================================================
+// 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(structureSlug?: string): Promise<ApiResponse<ValidationSummary>> {
+        const path = getValidationSummaryApiPath(this.workspaceId);
+        const params = structureSlug ? { structureSlug } : undefined;
+        return this.requestFn<ValidationSummary>('GET', path, null, params);
+    }
+
+    /**
+     * Get the count of pending suggestions for a structure.
+     *
+     * @param structureSlug - The structure slug (recordSlug)
+     * @returns Object with pending count
+     */
+    public getPendingCount(structureSlug: string): Promise<ApiResponse<{ structureSlug: string; pendingCount: number }>> {
+        const path = getValidationPendingCountApiPath(this.workspaceId, structureSlug);
+        return this.requestFn<{ structureSlug: string; pendingCount: number }>('GET', path);
+    }
+}

package/src/managers/webhookSubscriptions.ts

@@ -0,0 +1,206 @@
+// =====================================================
+// Webhook Subscriptions Manager
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type {
+    WebhookSubscription,
+    WebhookDelivery,
+    WebhookDeliverySummary,
+    WebhookDeliveriesListMeta,
+    WebhookReplayResponse,
+    WebhookCancelResponse,
+    CreateWebhookSubscriptionInput,
+    UpdateWebhookSubscriptionInput,
+    ListWebhookDeliveriesOptions,
+} from '../types/webhooks';
+import {
+    getWebhookSubscriptionsApiPath,
+    getWebhookSubscriptionRotateSecretApiPath,
+    getWebhookSubscriptionDeliveriesApiPath,
+    getWebhookDeliveryRetryApiPath,
+    getWebhookDeliveryCancelApiPath,
+} from '../internal/paths';
+
+// =====================================================
+// Webhook Subscriptions Manager
+// =====================================================
+
+/**
+ * WebhookSubscriptionsManager provides methods for managing outbound webhook
+ * subscriptions and inspecting delivery history. Access via
+ * `centrali.webhookSubscriptions`.
+ *
+ * Subscriptions listen for record events (`record_created`, `record_updated`,
+ * `record_deleted`, `records_bulk_created`) and POST a signed JSON payload to
+ * your URL. Payloads are signed with HMAC-SHA256 using the subscription's
+ * `whsec_` secret and delivered in the `X-Signature` header.
+ *
+ * Usage:
+ * ```ts
+ * // Create a subscription
+ * const sub = await centrali.webhookSubscriptions.create({
+ *   name: 'Orders webhook',
+ *   url: 'https://my-app.example.com/webhooks/centrali',
+ *   events: [RecordEvents.CREATED, RecordEvents.UPDATED],
+ *   recordSlugs: ['orders'],
+ * });
+ * // The signing secret is returned on create — copy it now, it's not shown again.
+ * // `secret` is typed `string | undefined` (reads omit it), so assert here.
+ * console.log('Signing secret:', sub.data.secret!);
+ *
+ * // Rotate the secret (immediate cutover)
+ * const rotated = await centrali.webhookSubscriptions.rotateSecret(sub.data.id);
+ *
+ * // Inspect delivery history
+ * const deliveries = await centrali.webhookSubscriptions.deliveries.list(sub.data.id);
+ *
+ * // Replay a delivery
+ * await centrali.webhookSubscriptions.deliveries.retry(deliveryId);
+ * ```
+ */
+export class WebhookSubscriptionsManager {
+    private requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>;
+    private workspaceId: string;
+
+    /**
+     * Delivery history and replay controls. Deliveries are per-subscription for
+     * list/get, but retry/cancel are workspace-scoped — the backend routes
+     * those under `/webhook-subscriptions/deliveries/{id}/retry|cancel`, so the
+     * subscription ID is not needed to replay or cancel.
+     */
+    public readonly deliveries: {
+        /**
+         * List deliveries for a subscription. Rows omit `requestPayload` and
+         * `responseBody` — use `deliveries.get()` to fetch the full record.
+         * `result.data` is the array of trimmed rows; `result.meta` carries
+         * the pagination counters (`total`, `limit`, `offset`).
+         */
+        list: (subscriptionId: string, options?: ListWebhookDeliveriesOptions) => Promise<ApiResponse<WebhookDeliverySummary[]> & { meta?: WebhookDeliveriesListMeta }>;
+        /** Get a single delivery including the full payload and response body. */
+        get: (subscriptionId: string, deliveryId: string) => Promise<ApiResponse<WebhookDelivery>>;
+        /**
+         * Replay a previously recorded delivery. Queues a new delivery row
+         * pointing at `replayedFrom` the original. Returns the new delivery ID.
+         */
+        retry: (deliveryId: string) => Promise<ApiResponse<WebhookReplayResponse>>;
+        /**
+         * Cancel a delivery that is currently in `retrying` status. Flips the
+         * row to `failed` with `lastError = 'Cancelled by user'`.
+         */
+        cancel: (deliveryId: string) => Promise<ApiResponse<WebhookCancelResponse>>;
+    };
+
+    constructor(
+        workspaceId: string,
+        requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>
+    ) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+
+        const toIso = (v: string | Date | undefined): string | undefined => {
+            if (!v) return undefined;
+            return v instanceof Date ? v.toISOString() : v;
+        };
+
+        this.deliveries = {
+            list: (subscriptionId: string, options?: ListWebhookDeliveriesOptions) => {
+                const path = getWebhookSubscriptionDeliveriesApiPath(this.workspaceId, subscriptionId);
+                const queryParams: Record<string, any> = {};
+                if (options?.status) queryParams.status = options.status;
+                if (options?.since) queryParams.since = toIso(options.since);
+                if (options?.until) queryParams.until = toIso(options.until);
+                if (options?.limit !== undefined) queryParams.limit = options.limit;
+                if (options?.offset !== undefined) queryParams.offset = options.offset;
+                return this.requestFn<WebhookDeliverySummary[]>(
+                    'GET',
+                    path,
+                    null,
+                    Object.keys(queryParams).length > 0 ? queryParams : undefined
+                ) as Promise<ApiResponse<WebhookDeliverySummary[]> & { meta?: WebhookDeliveriesListMeta }>;
+            },
+            get: (subscriptionId: string, deliveryId: string) => {
+                const path = getWebhookSubscriptionDeliveriesApiPath(this.workspaceId, subscriptionId, deliveryId);
+                return this.requestFn<WebhookDelivery>('GET', path);
+            },
+            retry: (deliveryId: string) => {
+                const path = getWebhookDeliveryRetryApiPath(this.workspaceId, deliveryId);
+                return this.requestFn<WebhookReplayResponse>('POST', path);
+            },
+            cancel: (deliveryId: string) => {
+                const path = getWebhookDeliveryCancelApiPath(this.workspaceId, deliveryId);
+                return this.requestFn<WebhookCancelResponse>('POST', path);
+            },
+        };
+    }
+
+    /**
+     * List all webhook subscriptions in the workspace.
+     *
+     * @example
+     * ```ts
+     * const subs = await centrali.webhookSubscriptions.list();
+     * for (const sub of subs.data) console.log(sub.name, sub.url);
+     * ```
+     */
+    public list(): Promise<ApiResponse<WebhookSubscription[]>> {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId);
+        return this.requestFn<WebhookSubscription[]>('GET', path);
+    }
+
+    /**
+     * Get a webhook subscription by ID.
+     * @param subscriptionId - The subscription UUID
+     */
+    public get(subscriptionId: string): Promise<ApiResponse<WebhookSubscription>> {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn<WebhookSubscription>('GET', path);
+    }
+
+    /**
+     * Create a webhook subscription. The response `secret` field is only
+     * populated on this call (and on `rotateSecret`) — copy it immediately;
+     * subsequent `get`/`list` responses do not return the secret.
+     *
+     * @example
+     * ```ts
+     * const sub = await centrali.webhookSubscriptions.create({
+     *   name: 'Order notifications',
+     *   url: 'https://api.example.com/hooks/centrali',
+     *   events: [RecordEvents.CREATED, RecordEvents.UPDATED],
+     *   recordSlugs: ['orders'],
+     * });
+     * const signingSecret = sub.data.secret; // copy once — not returned on reads
+     * ```
+     */
+    public create(input: CreateWebhookSubscriptionInput): Promise<ApiResponse<WebhookSubscription>> {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId);
+        return this.requestFn<WebhookSubscription>('POST', path, input);
+    }
+
+    /**
+     * Update fields on a webhook subscription. The signing secret is managed
+     * by the server — use `rotateSecret()` to regenerate it.
+     */
+    public update(subscriptionId: string, patch: UpdateWebhookSubscriptionInput): Promise<ApiResponse<WebhookSubscription>> {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn<WebhookSubscription>('PATCH', path, patch);
+    }
+
+    /** Delete a webhook subscription. Existing delivery history is retained. */
+    public delete(subscriptionId: string): Promise<ApiResponse<void>> {
+        const path = getWebhookSubscriptionsApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn<void>('DELETE', path);
+    }
+
+    /**
+     * Rotate the signing secret. Immediate cutover — the previous secret stops
+     * signing on the next dispatch. The response includes the new secret;
+     * capture it before closing the response.
+     */
+    public rotateSecret(subscriptionId: string): Promise<ApiResponse<WebhookSubscription>> {
+        const path = getWebhookSubscriptionRotateSecretApiPath(this.workspaceId, subscriptionId);
+        return this.requestFn<WebhookSubscription>('POST', path);
+    }
+}