@centrali-io/centrali-sdk 5.5.1 → 6.0.0

package/src/types/realtime.ts

@@ -0,0 +1,403 @@
+// =====================================================
+// Realtime Types
+// =====================================================
+
+/**
+ * Record event types emitted by the realtime service.
+ */
+export type RecordEventType = 'record_created' | 'record_updated' | 'record_deleted' | 'records_bulk_created';
+
+/**
+ * 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';
+
+/**
+ * Compute function event types emitted by the realtime service.
+ */
+export type ComputeEventType = 'function_run_completed' | 'function_run_failed';
+
+/**
+ * Orchestration run event types emitted by the realtime service.
+ */
+export type OrchestrationEventType = 'orchestration_run_started' | 'orchestration_run_completed' | 'orchestration_run_failed';
+
+/**
+ * All event types emitted by the realtime service.
+ * Matches: services/backend/realtime/internal/redis/message.go
+ */
+export type RealtimeEventType = RecordEventType | ValidationEventType | AnomalyEventType | ComputeEventType | OrchestrationEventType;
+
+/**
+ * Record event payload from the realtime service.
+ * Matches: services/backend/realtime/internal/redis/message.go RecordEvent
+ */
+export interface RealtimeRecordEvent {
+    /** Event type */
+    event: RecordEventType;
+    /** Workspace slug where the event occurred */
+    workspaceSlug: string;
+    /** Structure's record slug (e.g., "order") */
+    recordSlug: string;
+    /** Record ID */
+    recordId: string;
+    /** Record data. For updates, contains "before" and "after" fields */
+    data?: Record<string, unknown>;
+    /** ISO timestamp when the event occurred */
+    timestamp: string;
+    /** User who created the record (for create events) */
+    createdBy?: string;
+    /** User who updated the record (for update events) */
+    updatedBy?: string;
+    /** User who deleted the record (for delete events) */
+    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;
+}
+
+/**
+ * Function run error details.
+ */
+export interface FunctionRunError {
+    /** Error message */
+    message: string;
+    /** Error code */
+    code?: string;
+    /** Stack trace */
+    stack?: string;
+}
+
+/**
+ * Memory usage metrics from function execution.
+ */
+export interface FunctionMemoryUsage {
+    /** Heap memory used in bytes */
+    heapUsed: number;
+    /** Resident set size in bytes */
+    rss: number;
+}
+
+/**
+ * Compute function run event payload.
+ * Matches the format published by handle_function_run_events.ts
+ */
+export interface RealtimeFunctionRunEvent {
+    /** Event type */
+    event: ComputeEventType;
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** Unique job identifier (returned from execute call) */
+    jobId: string;
+    /** Function run record ID */
+    runId: string;
+    /** Trigger that initiated the run */
+    triggerId: string;
+    /** Function that was executed */
+    functionId: string;
+    /** Trigger type: on-demand, event-driven, scheduled, http-trigger */
+    triggerType: 'on-demand' | 'event-driven' | 'scheduled' | 'http-trigger';
+    /** Execution status */
+    status: 'completed' | 'failure';
+    /** Function return value (if completed) */
+    outputs?: unknown;
+    /** Error details (if failed) */
+    error?: FunctionRunError;
+    /** Execution time in milliseconds */
+    duration: number;
+    /** Memory usage metrics */
+    memoryUsage?: FunctionMemoryUsage;
+    /** User who triggered the run */
+    userId: string;
+    /** ISO timestamp when the function completed */
+    timestamp: string;
+}
+
+/**
+ * Orchestration failure reason details.
+ */
+export interface OrchestrationFailureReason {
+    /** Error code (e.g., "STEP_EXECUTION_FAILED") */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** ID of the step that failed */
+    stepId?: string;
+}
+
+/**
+ * Orchestration run event payload from the realtime service.
+ * Matches: services/backend/realtime/internal/redis/message.go OrchestrationRunEvent
+ */
+export interface RealtimeOrchestrationRunEvent {
+    /** Event type */
+    event: OrchestrationEventType;
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** Orchestration run ID */
+    runId: string;
+    /** Orchestration definition ID */
+    orchestrationId: string;
+    /** Orchestration name */
+    orchestrationName: string;
+    /** Trigger type: on-demand, event-driven, scheduled, http-trigger */
+    triggerType: 'on-demand' | 'event-driven' | 'scheduled' | 'http-trigger';
+    /** Outputs from completed steps (for completed/failed events) */
+    stepOutputs?: Record<string, unknown>;
+    /** Execution time in milliseconds (for completed/failed events) */
+    duration?: number;
+    /** Failure details (for failed events only) */
+    failureReason?: OrchestrationFailureReason;
+    /** ISO timestamp when the event occurred */
+    timestamp: string;
+}
+
+/**
+ * Close event payload from the realtime service.
+ */
+export interface RealtimeCloseEvent {
+    /** Reason for the close */
+    reason: string;
+    /** Whether the client should attempt to reconnect */
+    reconnect: boolean;
+}
+
+/**
+ * Union type of all realtime events.
+ */
+export type RealtimeEvent = RealtimeRecordEvent | RealtimeValidationSuggestionEvent | RealtimeValidationBatchEvent | RealtimeAnomalyInsightEvent | RealtimeAnomalyDetectionEvent | RealtimeFunctionRunEvent | RealtimeOrchestrationRunEvent;
+
+/**
+ * Error object for realtime connection errors.
+ */
+export interface RealtimeError {
+    /** Error code from the server */
+    code: 'MISSING_TOKEN' | 'TOKEN_EXPIRED' | 'WORKSPACE_MISMATCH' | 'INVALID_TOKEN' | 'FORBIDDEN' | 'AUTH_ERROR' | 'RATE_LIMIT_EXCEEDED' | 'CONNECTION_ERROR' | 'PARSE_ERROR';
+    /** Human-readable error message */
+    message: string;
+    /** Whether the error is recoverable (client should retry) */
+    recoverable: boolean;
+}
+
+/**
+ * Options for subscribing to realtime events.
+ */
+export interface RealtimeSubscribeOptions {
+    /** Structure recordSlugs to filter events (e.g., ["order", "customer"]). Empty = all structures */
+    structures?: string[];
+    /** Collection recordSlugs to filter events (e.g., ["order", "customer"]). Empty = all collections */
+    collections?: string[];
+    /** Event types to filter (e.g., ["record_created"]). Empty = all events */
+    events?: RealtimeEventType[];
+    /** CFL (Centrali Filter Language) expression for data filtering (e.g., "status = 'active'") */
+    filter?: string;
+    /** Filter compute events to a specific job ID (only affects function_run_* events) */
+    jobId?: string;
+    /** Filter compute events by trigger type: on-demand, event-driven, scheduled, http-trigger */
+    triggerType?: 'on-demand' | 'event-driven' | 'scheduled' | 'http-trigger';
+    /** Filter compute events to a specific function ID */
+    functionId?: string;
+    /** Filter orchestration events to a specific orchestration ID */
+    orchestrationId?: string;
+    /** Filter orchestration events to a specific run ID */
+    runId?: string;
+    /** Callback for record events */
+    onEvent: (event: RealtimeEvent) => void;
+    /** Callback for errors */
+    onError?: (error: RealtimeError) => void;
+    /** Callback when connected */
+    onConnected?: () => void;
+    /** Callback when disconnected */
+    onDisconnected?: (reason?: string) => void;
+}
+
+/**
+ * Realtime subscription handle returned by subscribe().
+ */
+export interface RealtimeSubscription {
+    /** Unsubscribe and close the connection */
+    unsubscribe: () => void;
+    /** Whether the connection is currently open */
+    readonly connected: boolean;
+}
+

package/src/types/records.ts

@@ -0,0 +1,261 @@
+/**
+ * Options for deleting a record.
+ */
+export interface DeleteRecordOptions {
+    /** Perform a hard delete (permanent). Default: false (soft delete) */
+    hard?: boolean;
+}
+
+/**
+ * Options for setting TTL (Time-To-Live) on a record.
+ */
+export interface RecordTtlOptions {
+    /** TTL in seconds. Record expires after this duration. */
+    ttlSeconds?: number;
+    /** Explicit expiration timestamp (ISO 8601 string). */
+    expiresAt?: string;
+    /** Set to true to remove TTL and make record permanent. Only valid on update. */
+    clearTtl?: boolean;
+}
+
+/**
+ * Options for expanding reference fields when fetching records.
+ * Expanded data is placed in the `_expanded` object within the record's data.
+ */
+export interface ExpandOptions {
+    /**
+     * Comma-separated list of reference fields to expand.
+     * Supports nested expansion using dot notation (up to 3 levels deep).
+     *
+     * @example
+     * // Single field
+     * expand: 'customer'
+     *
+     * // Multiple fields
+     * expand: 'customer,product'
+     *
+     * // Nested expansion
+     * expand: 'customer,customer.address'
+     */
+    expand?: string;
+}
+
+/**
+ * Options for retrieving a single record.
+ */
+export interface GetRecordOptions extends ExpandOptions {}
+
+// =====================================================
+// Canonical query types (CEN-1194 — Phase 1 query foundation)
+// =====================================================
+// Re-exports the canonical `QueryDefinition` surface from @centrali/query.
+// `query-types.ts` is generated from `services/backend/shared/query/src/types.ts`
+// by `scripts/sync-query-types.mjs` (runs on prebuild). Do not edit it by hand.
+//
+// Use these for new code:
+//   - `client.records.query(resource, definition)`        — POST /records/query
+//   - `client.records.list(resource, urlOpts?)`           — GET adapter
+//   - `client.records.search(resource, text, opts?)`      — sugar over `{ text }`
+//   - `client.records.test(resource, definition)`         — authoring dry-run
+//   - `client.queryRecords<T>(resource, definition)`      — top-level convenience
+//
+// Saved queries: `client.savedQueries.*` is the canonical namespace, routing
+// through the `/saved-queries/*` HTTP endpoints (Phase 4 — CEN-1198).
+// `client.smartQueries.*` is preserved as a deprecated alias during the
+// deprecation window.
+//
+// The legacy `FilterOperators` / `QueryRecordOptions` block below is preserved
+// for the GET adapter (`client.records.list()` and the legacy
+// `client.queryRecords(slug, urlOpts)` form). Migration guidance for the
+// canonical operator vocabulary lives in
+// `docs/maintainers/overview/query-foundation.md`.
+export * from '../../query-types';
+
+/**
+ * Filter operators for querying records via the legacy GET adapter.
+ *
+ * Pass filters at the TOP LEVEL of query params (not nested under 'filter').
+ * Use bracket notation for operators: `'data.field[operator]': value`
+ *
+ * @deprecated Since 5.5.0. Prefer canonical `FieldCondition` from
+ *   `@centrali-io/centrali-sdk` (re-exported above) and use `client.records.query()`
+ *   with a `QueryDefinition` body. This shape stays for back-compat with
+ *   `client.queryRecords(slug, options)` / `client.records.list()`.
+ *
+ * @example
+ * // Simple equality - just use the field name
+ * { 'data.status': 'active' }
+ *
+ * // With operators - use bracket notation
+ * { 'data.age[gte]': 18, 'data.age[lte]': 65 }
+ * { 'data.status[in]': 'pending,processing' }  // comma-separated for 'in'
+ * { 'data.email[contains]': '@gmail.com' }
+ */
+export interface FilterOperators {
+    /** Equal to (default if just a value is provided) */
+    eq?: string | number | boolean;
+    /** Not equal to */
+    ne?: string | number | boolean;
+    /** Greater than */
+    gt?: number | string;
+    /** Greater than or equal to */
+    gte?: number | string;
+    /** Less than */
+    lt?: number | string;
+    /** Less than or equal to */
+    lte?: number | string;
+    /** Value is in the provided array */
+    in?: (string | number)[];
+    /** Value is not in the provided array */
+    nin?: (string | number)[];
+    /** String contains substring (case-insensitive) */
+    contains?: string;
+    /** String starts with (case-insensitive) */
+    startswith?: string;
+    /** String ends with (case-insensitive) */
+    endswith?: string;
+    /** Array field contains any of the provided values */
+    hasAny?: (string | number)[];
+    /** Array field contains all of the provided values */
+    hasAll?: (string | number)[];
+}
+
+/**
+ * Filter value can be a direct value or an object with operators.
+ */
+export type FilterValue = string | number | boolean | null | FilterOperators;
+
+/**
+ * Date range filter for restricting results to a time window.
+ *
+ * @example
+ * // Records created in the last 30 days
+ * { field: 'createdAt', from: '2024-01-01T00:00:00Z' }
+ *
+ * // Records updated in a specific range
+ * { field: 'updatedAt', from: '2024-01-01T00:00:00Z', to: '2024-03-31T23:59:59Z' }
+ */
+export interface DateWindowOption {
+    /** The date field to filter on (e.g., 'createdAt', 'updatedAt', or a custom date field) */
+    field: string;
+    /** ISO 8601 date string — lower bound (inclusive, gte) */
+    from?: string;
+    /** ISO 8601 date string — upper bound (inclusive, lte) */
+    to?: string;
+}
+
+/**
+ * Options for querying records via the GET adapter.
+ *
+ * Supports two filter styles:
+ *
+ * **Style 1 — Top-level filters (recommended for SDK):**
+ * Pass filter fields directly as top-level keys with `data.` prefix and bracket notation.
+ * ```ts
+ * { 'data.status': 'active', 'data.price[lte]': 100, pageSize: 10 }
+ * ```
+ *
+ * **Style 2 — Nested filter object (same syntax as compute functions):**
+ * Wrap filters in a `filter` object. Useful if you prefer the same syntax as `api.queryRecords` in compute functions.
+ * ```ts
+ * { filter: { 'data.status': 'active', 'data.price': { lte: 100 } }, pageSize: 10 }
+ * ```
+ *
+ * Both styles are supported and can be mixed. Use `data.` prefix for custom fields.
+ * System fields (`id`, `createdAt`, `updatedAt`, `status`) don't need the prefix.
+ *
+ * @deprecated Since 5.5.0. This is the URL-param shape consumed by
+ *   `client.records.list()` and the legacy `client.queryRecords(slug, opts)`
+ *   form. New code should use a canonical `QueryDefinition` (`POST /records/query`)
+ *   via `client.records.query()` or the canonical `client.queryRecords(resource, definition)`
+ *   overload — same engine, but boolean trees, `select`, `text`, and `include`
+ *   become first-class. The GET adapter and this type stay supported during
+ *   the deprecation window per `docs/maintainers/overview/query-foundation.md`.
+ *
+ * @example
+ * // Top-level filters with bracket notation
+ * { 'data.status': 'active', 'data.age[gte]': 18, sort: '-createdAt' }
+ *
+ * // Nested filter object
+ * { filter: { 'data.status': 'active', 'data.age': { gte: 18 } }, sort: '-createdAt' }
+ *
+ * // Date window
+ * { dateWindow: { field: 'createdAt', from: '2024-01-01T00:00:00Z' }, sort: '-createdAt' }
+ */
+export interface QueryRecordOptions extends ExpandOptions {
+    /**
+     * Structured filter object. Wrap your field filters here as an alternative to top-level keys.
+     * Uses the same syntax as compute function `api.queryRecords`.
+     *
+     * @example
+     * { filter: { 'data.status': 'active', 'data.age': { gte: 18 } } }
+     */
+    filter?: Record<string, any>;
+    /** Sort field with optional direction prefix (e.g., '-createdAt' for descending) */
+    sort?: string;
+    /** Page number (1-indexed, default: 1) */
+    page?: number;
+    /** Number of records per page (default: 50, max: 500) */
+    pageSize?: number;
+    /** Alias for pageSize */
+    limit?: number;
+    /** Include soft-deleted records */
+    includeDeleted?: boolean;
+    /** Include archived (soft-deleted) records. Alias for includeDeleted. */
+    includeArchived?: boolean;
+    /** Shorthand for includeDeleted (from HTTP query params) */
+    all?: boolean;
+    /** Include total count in response metadata */
+    includeTotal?: boolean;
+    /** Search query string */
+    search?: string;
+    /** Field(s) to search in (comma-separated or single field) */
+    searchField?: string;
+    /** Fields to search in (array format) */
+    searchFields?: string[];
+    /**
+     * Date range filter. Restricts results to records where the specified date field
+     * falls within the given range.
+     *
+     * @example
+     * { dateWindow: { field: 'createdAt', from: '2024-01-01T00:00:00Z', to: '2024-12-31T23:59:59Z' } }
+     */
+    dateWindow?: DateWindowOption;
+    /** Comma-separated fields to return (field selection) */
+    fields?: string;
+    /** Field selection (alias for fields) */
+    select?: string[];
+    /**
+     * Additional filter fields — pass at TOP LEVEL with 'data.' prefix for custom fields.
+     * Use bracket notation for operators: 'data.field[operator]': value
+     *
+     * Supported operators: eq, ne, gt, gte, lt, lte, in, nin, contains, startswith, endswith, hasAny, hasAll
+     */
+    [key: string]: any;
+}
+
+/**
+ * Response from invoking a trigger.
+ * Currently the API returns the queued job ID as a string.
+ */
+export type TriggerInvokeResponse = string;
+
+/**
+ * Record event name constants — use these when constructing `events` on a
+ * webhook subscription instead of hand-typing strings.
+ *
+ * @example
+ * ```ts
+ * await centrali.webhookSubscriptions.create({
+ *   name: 'Order created',
+ *   url: 'https://my-app.example.com/webhooks/centrali',
+ *   events: [RecordEvents.CREATED, RecordEvents.UPDATED],
+ * });
+ * ```
+ */
+export const RecordEvents = {
+    CREATED: 'record_created',
+    UPDATED: 'record_updated',
+    DELETED: 'record_deleted',
+    BULK_CREATED: 'records_bulk_created',
+} as const;