@centrali-io/centrali-sdk 5.5.0 → 6.0.0

package/src/types/insights.ts

@@ -0,0 +1,113 @@
+// =====================================================
+// 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>;
+}
+

package/src/types/orchestrations.ts

@@ -0,0 +1,460 @@
+// =====================================================
+// Orchestration Types
+// =====================================================
+
+/**
+ * Orchestration trigger types.
+ */
+export type OrchestrationTriggerType = 'event-driven' | 'scheduled' | 'on-demand' | 'http-trigger';
+
+/**
+ * Schedule types for scheduled orchestrations.
+ */
+export type OrchestrationScheduleType = 'interval' | 'cron' | 'once';
+
+/**
+ * Orchestration lifecycle status.
+ */
+export type OrchestrationStatus = 'draft' | 'active' | 'paused';
+
+/**
+ * Orchestration run status.
+ */
+export type OrchestrationRunStatus = 'pending' | 'running' | 'waiting' | 'completed' | 'failed';
+
+/**
+ * Orchestration step types.
+ */
+export type OrchestrationStepType = 'compute' | 'decision' | 'delay';
+
+/**
+ * Run step status.
+ */
+export type OrchestrationStepStatus = 'pending' | 'running' | 'waiting' | 'succeeded' | 'failed';
+
+/**
+ * Condition operators for decision steps.
+ */
+export type ConditionOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'exists' | 'notExists' | 'in' | 'notIn';
+
+/**
+ * Orchestration trigger configuration.
+ */
+export interface OrchestrationTrigger {
+    /** Trigger type */
+    type: OrchestrationTriggerType;
+
+    // Event-driven trigger config
+    /** Event type for event-driven triggers */
+    eventType?: string;
+    /** Structure slug to watch */
+    structureSlug?: string;
+
+    // Scheduled trigger config
+    /** Schedule type for scheduled triggers */
+    scheduleType?: OrchestrationScheduleType;
+    /** Interval in seconds (for interval type) */
+    interval?: number;
+    /** Cron expression (for cron type) */
+    cronExpression?: string;
+    /** ISO datetime (for once type) */
+    scheduledAt?: string;
+    /** IANA timezone (default: UTC) */
+    timezone?: string;
+
+    // HTTP trigger config
+    /** Webhook path */
+    path?: string;
+    /** Whether to validate HMAC signature */
+    validateSignature?: boolean;
+    /** Signing secret for HMAC validation */
+    signingSecret?: string;
+    /** Header name for signature */
+    signatureHeaderName?: string;
+    /** Header name for message ID */
+    signatureIdHeaderName?: string;
+    /** Header name for timestamp (separate header format) */
+    timestampHeaderName?: string;
+    /** Regex to extract timestamp from signature header (compound format, e.g. Stripe) */
+    timestampExtractionPattern?: string;
+    /** HMAC algorithm (default: sha256) */
+    hmacAlgorithm?: string;
+    /** HMAC digest encoding (default: base64) */
+    hmacEncoding?: string;
+    /** Regex to extract signature value from header */
+    extractionPattern?: string;
+    /** Secret key encoding after prefix split (default: base64) */
+    encoding?: string;
+    /** How to derive HMAC key: 'raw' uses full string as UTF-8 (Stripe), 'prefixed-base64' strips prefix before _ and base64-decodes (Svix) */
+    secretEncoding?: 'raw' | 'prefixed-base64';
+}
+
+/**
+ * Retry configuration for compute steps.
+ */
+export interface OrchestrationRetryConfig {
+    /** Maximum retry attempts */
+    maxAttempts: number;
+    /** Backoff delay in milliseconds */
+    backoffMs: number;
+}
+
+/**
+ * On success configuration for compute steps.
+ */
+export interface OrchestrationOnSuccess {
+    /** Next step ID to execute on success */
+    nextStepId?: string;
+}
+
+/**
+ * On failure configuration for compute steps.
+ */
+export interface OrchestrationOnFailure {
+    /** Action to take on failure: 'fail' or 'end' */
+    action: 'fail' | 'end';
+}
+
+/**
+ * Condition in a decision case.
+ */
+export interface OrchestrationCondition {
+    /** Path to evaluate (e.g., 'input.data.status', 'steps.validate.output.isValid') */
+    path: string;
+    /** Comparison operator */
+    op: ConditionOperator;
+    /** Static value to compare against */
+    value?: unknown;
+    /** Path to dynamic value to compare against (alternative to value) */
+    valuePath?: string;
+}
+
+/**
+ * Decision case in a decision step.
+ */
+export interface OrchestrationDecisionCase {
+    /** Conditions to evaluate (AND logic) */
+    conditions: OrchestrationCondition[];
+    /** Next step ID if conditions match */
+    nextStepId: string;
+}
+
+/**
+ * Encrypted parameter for a compute step. To encrypt a new value, set encrypt=true and value=plaintext.
+ * Stored values have encrypted=true and value is masked in API responses.
+ */
+export interface StepEncryptedParam {
+    /** The parameter value (plaintext on create, masked as "********" on read) */
+    value: string;
+    /** True when the value is encrypted at rest */
+    encrypted?: boolean;
+    /** Encryption key version (for key rotation support) */
+    keyVersion?: number;
+    /** Client flag: set to true to encrypt this plaintext value */
+    encrypt?: boolean;
+}
+
+/**
+ * Orchestration step definition.
+ */
+export interface OrchestrationStep {
+    /** Unique step identifier */
+    id: string;
+    /** Human-readable step name */
+    name?: string;
+    /** Step type */
+    type: OrchestrationStepType;
+
+    // Compute step fields
+    /** Function ID to execute (for compute steps) */
+    functionId?: string;
+    /** Timeout in milliseconds (for compute steps) */
+    timeoutMs?: number;
+    /** Retry configuration (for compute steps) */
+    retry?: OrchestrationRetryConfig;
+    /** On success handler (for compute steps) */
+    onSuccess?: OrchestrationOnSuccess;
+    /** On failure handler (for compute steps) */
+    onFailure?: OrchestrationOnFailure;
+    /** Encrypted parameters for compute steps. Secrets are encrypted at rest and decrypted at execution time. */
+    encryptedParams?: Record<string, StepEncryptedParam>;
+
+    // Decision step fields
+    /** Decision cases (for decision steps) */
+    cases?: OrchestrationDecisionCase[];
+    /** Default next step if no case matches (for decision steps) */
+    defaultNextStepId?: string;
+
+    // Delay step fields
+    /** Delay duration in milliseconds (for delay steps) */
+    delayMs?: number;
+    /** Next step ID (for delay steps) */
+    nextStepId?: string;
+}
+
+/**
+ * Orchestration definition.
+ */
+export interface Orchestration {
+    /** Unique identifier */
+    id: string;
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** URL-friendly slug */
+    slug: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Version number (increments on update) */
+    version: number;
+    /** Lifecycle status */
+    status: OrchestrationStatus;
+    /** Trigger configuration */
+    trigger: OrchestrationTrigger;
+    /** Workflow steps */
+    steps: OrchestrationStep[];
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** User who created the orchestration */
+    createdBy: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+    /** User who last updated the orchestration */
+    updatedBy: string;
+}
+
+/**
+ * Input for creating an orchestration.
+ */
+export interface CreateOrchestrationInput {
+    /** URL-friendly slug (unique within workspace) */
+    slug: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Trigger configuration */
+    trigger: OrchestrationTrigger;
+    /** Workflow steps */
+    steps: OrchestrationStep[];
+}
+
+/**
+ * Input for updating an orchestration.
+ */
+export interface UpdateOrchestrationInput {
+    /** Updated name */
+    name?: string;
+    /** Updated description */
+    description?: string;
+    /** Updated status */
+    status?: OrchestrationStatus;
+    /** Updated trigger configuration */
+    trigger?: OrchestrationTrigger;
+    /** Updated workflow steps */
+    steps?: OrchestrationStep[];
+}
+
+/**
+ * Trigger metadata for a run.
+ */
+export interface OrchestrationTriggerMetadata {
+    /** Event type (for event-driven triggers) */
+    eventType?: string;
+    /** Schedule ID (for scheduled triggers) */
+    scheduleId?: string;
+    /** Principal ID who initiated the run (for manual triggers) */
+    initiatedByPrincipalId?: string;
+    /** Webhook path (for HTTP triggers) */
+    webhookPath?: string;
+}
+
+/**
+ * Orchestration run instance.
+ */
+export interface OrchestrationRun {
+    /** Unique run identifier */
+    id: string;
+    /** Parent orchestration ID */
+    orchestrationId: string;
+    /** Orchestration version at time of run */
+    orchestrationVersion: number;
+    /** Workspace slug */
+    workspaceSlug: string;
+    /** Run status */
+    status: OrchestrationRunStatus;
+    /** Current step being executed */
+    currentStepId?: string;
+    /** Input data that triggered the run */
+    input: Record<string, unknown>;
+    /** Shared context across steps */
+    context: Record<string, unknown>;
+    /** Outputs from completed steps */
+    stepOutputs: Record<string, unknown>;
+    /** Correlation ID for tracing */
+    correlationId?: string;
+    /** How the run was triggered */
+    triggerType: OrchestrationTriggerType;
+    /** Trigger-specific metadata */
+    triggerMetadata?: OrchestrationTriggerMetadata;
+    /** Whether any step has errors */
+    hasErrors: boolean;
+    /** Number of delay steps encountered */
+    delayStepCount: number;
+    /** Reason for failure (if failed) */
+    failureReason?: string;
+    /** ISO timestamp when run started */
+    startedAt: string;
+    /** ISO timestamp when run completed */
+    completedAt?: string;
+    /** ISO timestamp when run data expires */
+    ttlExpiresAt: string;
+}
+
+/**
+ * Decision result from a decision step.
+ */
+export interface OrchestrationDecisionResult {
+    /** Number of cases evaluated */
+    evaluatedCases: number;
+    /** Index of matched case (null if default) */
+    matchedCaseIndex?: number;
+    /** Selected next step ID */
+    selectedNextStepId: string;
+    /** Detailed evaluation of each case */
+    evaluations?: OrchestrationCaseEvaluation[];
+}
+
+/**
+ * Evaluation result for a single decision case.
+ */
+export interface OrchestrationCaseEvaluation {
+    /** Case index */
+    caseIndex: number;
+    /** Next step ID for this case */
+    nextStepId: string;
+    /** Condition evaluations */
+    conditions: OrchestrationConditionEvaluation[];
+    /** Whether this case matched */
+    matched: boolean;
+}
+
+/**
+ * Evaluation result for a single condition.
+ */
+export interface OrchestrationConditionEvaluation {
+    /** Path that was evaluated */
+    path: string;
+    /** Operator used */
+    operator: string;
+    /** Expected value */
+    expectedValue?: unknown;
+    /** Value path (if comparing against another path) */
+    valuePath?: string;
+    /** Actual value found at path */
+    actualValue?: unknown;
+    /** Whether the path exists */
+    pathExists: boolean;
+    /** Whether condition matched */
+    matched: boolean;
+    /** Error message if evaluation failed */
+    error?: string;
+}
+
+/**
+ * Delay configuration result from a delay step.
+ */
+export interface OrchestrationDelayConfig {
+    /** Delay duration in milliseconds */
+    delayMs: number;
+    /** ISO timestamp when step will resume */
+    resumeAt: string;
+    /** ISO timestamp when step actually resumed */
+    resumedAt?: string;
+}
+
+/**
+ * Error information from a failed step.
+ */
+export interface OrchestrationStepError {
+    /** Error message */
+    message: string;
+    /** Error code */
+    code?: string;
+    /** Stack trace */
+    stack?: string;
+}
+
+/**
+ * Run step execution record.
+ */
+export interface OrchestrationRunStep {
+    /** Unique step execution identifier */
+    id: string;
+    /** Parent run ID */
+    orchestrationRunId: string;
+    /** Step ID from orchestration definition */
+    stepId: string;
+    /** Step type */
+    stepType: OrchestrationStepType;
+    /** Attempt number (for retries) */
+    attempt: number;
+    /** Step execution status */
+    status: OrchestrationStepStatus;
+    /** Input data for this step */
+    input?: Record<string, unknown>;
+    /** Output data from this step */
+    output?: Record<string, unknown>;
+    /** Decision result (for decision steps) */
+    decisionResult?: OrchestrationDecisionResult;
+    /** Delay configuration (for delay steps) */
+    delayConfig?: OrchestrationDelayConfig;
+    /** Error information (if failed) */
+    error?: OrchestrationStepError;
+    /** ISO timestamp when step started */
+    startedAt?: string;
+    /** ISO timestamp when step completed */
+    completedAt?: string;
+    /** Compute gateway execution ID (for logs) */
+    executionId?: string;
+    /** Function run ID (for UI linking) */
+    functionRunId?: string;
+    /** Function ID that was executed */
+    functionId?: string;
+}
+
+/**
+ * Options for triggering an orchestration run.
+ */
+export interface TriggerOrchestrationRunOptions {
+    /** Input data for the run */
+    input?: Record<string, unknown>;
+    /** Correlation ID for tracing */
+    correlationId?: string;
+}
+
+/**
+ * Options for listing orchestrations.
+ */
+export interface ListOrchestrationsOptions {
+    /** Number of items per page (default: 20, max: 100) */
+    limit?: number;
+    /** Number of items to skip */
+    offset?: number;
+    /** Filter by status */
+    status?: OrchestrationStatus;
+}
+
+/**
+ * Options for listing orchestration runs.
+ */
+export interface ListOrchestrationRunsOptions {
+    /** Number of items per page (default: 20, max: 100) */
+    limit?: number;
+    /** Number of items to skip */
+    offset?: number;
+    /** Filter by run status */
+    status?: OrchestrationRunStatus;
+}
+