@centrali-io/centrali-sdk 2.8.7 → 2.8.8

package/README.md

@@ -78,6 +78,7 @@ const centrali = new CentraliSDK({
 - ✅ **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
+- ✅ **Orchestrations** - Multi-step workflows with compute functions, decision logic, and delays
 - ✅ **Service accounts** - Automatic token refresh for server-to-server auth
 
 ## Core Operations
@@ -454,6 +455,126 @@ console.log('By severity:', summary.data.bySeverity);
 | `orphaned_reference` | References to deleted or non-existent records |
 | `reference_integrity` | Broken relationships between records |
 
+### Orchestrations
+
+Multi-step workflows that chain compute functions together with conditional logic, delays, and decision branches:
+
+```typescript
+// List all orchestrations
+const orchestrations = await centrali.orchestrations.list();
+
+// Get an orchestration by ID
+const orch = await centrali.orchestrations.get('orch-id');
+console.log('Name:', orch.data.name);
+console.log('Status:', orch.data.status);
+console.log('Steps:', orch.data.steps.length);
+
+// Create a new orchestration
+const newOrch = await centrali.orchestrations.create({
+  slug: 'order-processing',
+  name: 'Order Processing Workflow',
+  trigger: { type: 'on-demand' },
+  steps: [
+    {
+      id: 'validate',
+      type: 'compute',
+      functionId: 'func_validate_order',
+      onSuccess: { nextStepId: 'check-result' }
+    },
+    {
+      id: 'check-result',
+      type: 'decision',
+      cases: [
+        {
+          conditions: [{ path: 'steps.validate.output.isValid', op: 'eq', value: true }],
+          nextStepId: 'fulfill'
+        }
+      ],
+      defaultNextStepId: 'reject'
+    },
+    {
+      id: 'fulfill',
+      type: 'compute',
+      functionId: 'func_fulfill_order'
+    },
+    {
+      id: 'reject',
+      type: 'compute',
+      functionId: 'func_reject_order'
+    }
+  ]
+});
+
+// Trigger an orchestration run
+const run = await centrali.orchestrations.trigger('orch-id', {
+  input: {
+    orderId: '12345',
+    customerId: 'cust_abc'
+  }
+});
+console.log('Run started:', run.data.id);
+console.log('Status:', run.data.status);
+
+// Get run status
+const runStatus = await centrali.orchestrations.getRun('orch-id', run.data.id);
+console.log('Current step:', runStatus.data.currentStepId);
+console.log('Has errors:', runStatus.data.hasErrors);
+
+// Get run with step history
+const runWithSteps = await centrali.orchestrations.getRun('orch-id', run.data.id, true);
+for (const step of runWithSteps.data.steps || []) {
+  console.log(`${step.stepId}: ${step.status}`);
+}
+
+// List runs for an orchestration
+const runs = await centrali.orchestrations.listRuns('orch-id', {
+  status: 'completed',  // Filter by status
+  limit: 10
+});
+
+// Activate an orchestration (enables scheduled/event triggers)
+await centrali.orchestrations.activate('orch-id');
+
+// Pause an orchestration (disables all triggers)
+await centrali.orchestrations.pause('orch-id');
+
+// Update an orchestration
+await centrali.orchestrations.update('orch-id', {
+  name: 'Updated Name',
+  status: 'active'
+});
+
+// Delete an orchestration
+await centrali.orchestrations.delete('orch-id');
+```
+
+#### Trigger Types
+
+| Type | Description |
+|------|-------------|
+| `on-demand` | Manual invocation via API |
+| `event-driven` | React to record events (created, updated, deleted) |
+| `scheduled` | Run on a schedule (cron, interval, or once) |
+| `http-trigger` | External webhook endpoint |
+
+#### Step Types
+
+| Type | Description |
+|------|-------------|
+| `compute` | Execute a compute function |
+| `decision` | Branch based on conditions |
+| `delay` | Wait for a duration |
+
+#### Run Statuses
+
+| Status | Description |
+|--------|-------------|
+| `pending` | Run is queued |
+| `running` | Run is executing |
+| `waiting` | Run is waiting (delay step) |
+| `completed` | Run finished successfully |
+| `failed` | Run failed with error |
+
 ## TypeScript Support
 
 The SDK includes full TypeScript definitions for type-safe development:

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.ValidationManager = exports.AnomalyInsightsManager = exports.SmartQueriesManager = exports.TriggersManager = exports.RealtimeManager = void 0;
+exports.CentraliSDK = exports.ValidationManager = exports.AnomalyInsightsManager = exports.SmartQueriesManager = exports.TriggersManager = exports.OrchestrationsManager = exports.RealtimeManager = void 0;
 exports.getApiUrl = getApiUrl;
 exports.getAuthUrl = getAuthUrl;
 exports.getRealtimeUrl = getRealtimeUrl;
@@ -50,6 +50,9 @@ exports.getValidationSummaryApiPath = getValidationSummaryApiPath;
 exports.getValidationRecordSuggestionsApiPath = getValidationRecordSuggestionsApiPath;
 exports.getValidationPendingCountApiPath = getValidationPendingCountApiPath;
 exports.getValidationScanApiPath = getValidationScanApiPath;
+exports.getOrchestrationsApiPath = getOrchestrationsApiPath;
+exports.getOrchestrationRunsApiPath = getOrchestrationRunsApiPath;
+exports.getOrchestrationRunStepsApiPath = getOrchestrationRunStepsApiPath;
 const axios_1 = __importDefault(require("axios"));
 const qs_1 = __importDefault(require("qs"));
 const eventsource_1 = require("eventsource");
@@ -512,6 +515,320 @@ function getValidationScanApiPath(workspaceId, batchId) {
     return batchId ? `${basePath}/${batchId}` : basePath;
 }
 // =====================================================
+// Orchestration API Paths
+// =====================================================
+/**
+ * Generate Orchestrations API URL PATH.
+ * Routes to the orchestration service.
+ */
+function getOrchestrationsApiPath(workspaceId, orchestrationId) {
+    const basePath = `orchestration/ws/${workspaceId}/api/v1/orchestrations`;
+    return orchestrationId ? `${basePath}/${orchestrationId}` : basePath;
+}
+/**
+ * Generate Orchestration Runs API URL PATH.
+ */
+function getOrchestrationRunsApiPath(workspaceId, orchestrationId, runId) {
+    const basePath = `orchestration/ws/${workspaceId}/api/v1/orchestrations/${orchestrationId}/runs`;
+    return runId ? `${basePath}/${runId}` : basePath;
+}
+/**
+ * Generate Orchestration Run Steps API URL PATH.
+ */
+function getOrchestrationRunStepsApiPath(workspaceId, orchestrationId, runId) {
+    return `orchestration/ws/${workspaceId}/api/v1/orchestrations/${orchestrationId}/runs/${runId}/steps`;
+}
+// =====================================================
+// Orchestrations Manager
+// =====================================================
+/**
+ * OrchestrationsManager provides methods for managing orchestrations and triggering runs.
+ * Access via `client.orchestrations`.
+ *
+ * Orchestrations are multi-step workflows that chain compute functions together
+ * with conditional logic, delays, and decision branches.
+ *
+ * Usage:
+ * ```ts
+ * // List all orchestrations
+ * const orchestrations = await client.orchestrations.list();
+ *
+ * // Get an orchestration by ID
+ * const orch = await client.orchestrations.get('orch-id');
+ *
+ * // Trigger an on-demand orchestration
+ * const run = await client.orchestrations.trigger('orch-id', {
+ *   input: { orderId: '12345' }
+ * });
+ *
+ * // Get run status
+ * const runStatus = await client.orchestrations.getRun('orch-id', run.data.id);
+ *
+ * // List runs for an orchestration
+ * const runs = await client.orchestrations.listRuns('orch-id');
+ * ```
+ */
+class OrchestrationsManager {
+    constructor(workspaceId, requestFn) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+    }
+    /**
+     * List all orchestrations in the workspace.
+     *
+     * @param options - Optional pagination and filtering options
+     * @returns Paginated list of orchestrations
+     *
+     * @example
+     * ```ts
+     * // List all orchestrations
+     * const result = await client.orchestrations.list();
+     * console.log('Total:', result.data.meta.total);
+     *
+     * // With pagination and status filter
+     * const result = await client.orchestrations.list({
+     *   limit: 10,
+     *   offset: 0,
+     *   status: 'active'
+     * });
+     * ```
+     */
+    list(options) {
+        const path = getOrchestrationsApiPath(this.workspaceId);
+        return this.requestFn('GET', path, null, options);
+    }
+    /**
+     * Get an orchestration by ID.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @returns The orchestration details including all steps
+     *
+     * @example
+     * ```ts
+     * const orch = await client.orchestrations.get('orch-id');
+     * console.log('Name:', orch.data.name);
+     * console.log('Steps:', orch.data.steps.length);
+     * ```
+     */
+    get(orchestrationId) {
+        const path = getOrchestrationsApiPath(this.workspaceId, orchestrationId);
+        return this.requestFn('GET', path);
+    }
+    /**
+     * Create a new orchestration.
+     *
+     * @param input - The orchestration definition
+     * @returns The created orchestration
+     *
+     * @example
+     * ```ts
+     * const orch = await client.orchestrations.create({
+     *   slug: 'order-processing',
+     *   name: 'Order Processing Workflow',
+     *   trigger: { type: 'on-demand' },
+     *   steps: [
+     *     {
+     *       id: 'validate',
+     *       type: 'compute',
+     *       functionId: 'func_validate',
+     *       onSuccess: { nextStepId: 'process' }
+     *     },
+     *     {
+     *       id: 'process',
+     *       type: 'compute',
+     *       functionId: 'func_process'
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    create(input) {
+        const path = getOrchestrationsApiPath(this.workspaceId);
+        return this.requestFn('POST', path, input);
+    }
+    /**
+     * Update an existing orchestration.
+     *
+     * Updates increment the orchestration version. Running instances use the
+     * version at the time they started.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @param input - Fields to update
+     * @returns The updated orchestration
+     *
+     * @example
+     * ```ts
+     * // Activate an orchestration
+     * await client.orchestrations.update('orch-id', { status: 'active' });
+     *
+     * // Update steps
+     * await client.orchestrations.update('orch-id', {
+     *   steps: [...]
+     * });
+     * ```
+     */
+    update(orchestrationId, input) {
+        const path = getOrchestrationsApiPath(this.workspaceId, orchestrationId);
+        return this.requestFn('PUT', path, input);
+    }
+    /**
+     * Delete an orchestration.
+     *
+     * This also deletes all runs associated with the orchestration.
+     *
+     * @param orchestrationId - The orchestration ID
+     *
+     * @example
+     * ```ts
+     * await client.orchestrations.delete('orch-id');
+     * ```
+     */
+    delete(orchestrationId) {
+        const path = getOrchestrationsApiPath(this.workspaceId, orchestrationId);
+        return this.requestFn('DELETE', path);
+    }
+    /**
+     * Trigger an orchestration run.
+     *
+     * This creates a new run instance and starts executing the workflow.
+     * Can be used on on-demand, draft, or active orchestrations.
+     * Paused orchestrations cannot be triggered.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @param options - Optional input data and correlation ID
+     * @returns The created run
+     *
+     * @example
+     * ```ts
+     * // Simple trigger
+     * const run = await client.orchestrations.trigger('orch-id');
+     *
+     * // With input data
+     * const run = await client.orchestrations.trigger('orch-id', {
+     *   input: {
+     *     orderId: '12345',
+     *     customerId: 'cust_abc'
+     *   }
+     * });
+     *
+     * // With correlation ID for tracing
+     * const run = await client.orchestrations.trigger('orch-id', {
+     *   input: { orderId: '12345' },
+     *   correlationId: 'req-123'
+     * });
+     * ```
+     */
+    trigger(orchestrationId, options) {
+        var _a;
+        const path = getOrchestrationRunsApiPath(this.workspaceId, orchestrationId);
+        const body = {
+            input: (_a = options === null || options === void 0 ? void 0 : options.input) !== null && _a !== void 0 ? _a : {},
+            correlationId: options === null || options === void 0 ? void 0 : options.correlationId
+        };
+        return this.requestFn('POST', path, body);
+    }
+    /**
+     * List runs for an orchestration.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @param options - Optional pagination and filtering options
+     * @returns Paginated list of runs
+     *
+     * @example
+     * ```ts
+     * // List all runs
+     * const runs = await client.orchestrations.listRuns('orch-id');
+     *
+     * // Filter by status
+     * const failedRuns = await client.orchestrations.listRuns('orch-id', {
+     *   status: 'failed'
+     * });
+     * ```
+     */
+    listRuns(orchestrationId, options) {
+        const path = getOrchestrationRunsApiPath(this.workspaceId, orchestrationId);
+        return this.requestFn('GET', path, null, options);
+    }
+    /**
+     * Get a specific run by ID.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @param runId - The run ID
+     * @param includeSteps - Whether to include step execution history
+     * @returns The run details
+     *
+     * @example
+     * ```ts
+     * // Get basic run info
+     * const run = await client.orchestrations.getRun('orch-id', 'run-id');
+     * console.log('Status:', run.data.status);
+     *
+     * // Include step history
+     * const run = await client.orchestrations.getRun('orch-id', 'run-id', true);
+     * console.log('Steps:', run.data.steps);
+     * ```
+     */
+    getRun(orchestrationId, runId, includeSteps) {
+        const path = getOrchestrationRunsApiPath(this.workspaceId, orchestrationId, runId);
+        const params = includeSteps ? { include: 'steps' } : undefined;
+        return this.requestFn('GET', path, null, params);
+    }
+    /**
+     * Get step execution history for a run.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @param runId - The run ID
+     * @returns List of step executions
+     *
+     * @example
+     * ```ts
+     * const steps = await client.orchestrations.getRunSteps('orch-id', 'run-id');
+     * for (const step of steps.data.data) {
+     *   console.log(`${step.stepId}: ${step.status}`);
+     * }
+     * ```
+     */
+    getRunSteps(orchestrationId, runId) {
+        const path = getOrchestrationRunStepsApiPath(this.workspaceId, orchestrationId, runId);
+        return this.requestFn('GET', path);
+    }
+    /**
+     * Activate an orchestration.
+     *
+     * Convenience method to set status to 'active'.
+     * Active orchestrations can be triggered by scheduled events, record events, and webhooks.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @returns The updated orchestration
+     *
+     * @example
+     * ```ts
+     * await client.orchestrations.activate('orch-id');
+     * ```
+     */
+    activate(orchestrationId) {
+        return this.update(orchestrationId, { status: 'active' });
+    }
+    /**
+     * Pause an orchestration.
+     *
+     * Convenience method to set status to 'paused'.
+     * Paused orchestrations cannot be triggered by any mechanism.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @returns The updated orchestration
+     *
+     * @example
+     * ```ts
+     * await client.orchestrations.pause('orch-id');
+     * ```
+     */
+    pause(orchestrationId) {
+        return this.update(orchestrationId, { status: 'paused' });
+    }
+}
+exports.OrchestrationsManager = OrchestrationsManager;
+// =====================================================
 // Triggers Manager
 // =====================================================
 /**
@@ -1222,6 +1539,7 @@ class CentraliSDK {
         this._smartQueries = null;
         this._anomalyInsights = null;
         this._validation = null;
+        this._orchestrations = null;
         this.options = options;
         this.token = options.token || null;
         const apiUrl = getApiUrl(options.baseUrl);
@@ -1392,6 +1710,43 @@ class CentraliSDK {
         }
         return this._validation;
     }
+    /**
+     * Orchestrations namespace for managing multi-step workflows.
+     *
+     * Orchestrations chain compute functions together with conditional logic,
+     * delays, and decision branches to automate complex business processes.
+     *
+     * Usage:
+     * ```ts
+     * // List all orchestrations
+     * const orchestrations = await client.orchestrations.list();
+     *
+     * // Trigger an on-demand orchestration
+     * const run = await client.orchestrations.trigger('orch-id', {
+     *   input: { orderId: '12345' }
+     * });
+     *
+     * // Get run status
+     * const runStatus = await client.orchestrations.getRun('orch-id', run.data.id);
+     *
+     * // Create a new orchestration
+     * const orch = await client.orchestrations.create({
+     *   slug: 'order-processing',
+     *   name: 'Order Processing',
+     *   trigger: { type: 'on-demand' },
+     *   steps: [
+     *     { id: 'validate', type: 'compute', functionId: 'func_validate', onSuccess: { nextStepId: 'process' } },
+     *     { id: 'process', type: 'compute', functionId: 'func_process' }
+     *   ]
+     * });
+     * ```
+     */
+    get orchestrations() {
+        if (!this._orchestrations) {
+            this._orchestrations = new OrchestrationsManager(this.options.workspaceId, this.request.bind(this));
+        }
+        return this._orchestrations;
+    }
     /**
      * Manually set or update the bearer token for subsequent requests.
      */

package/index.ts

@@ -545,6 +545,450 @@ export interface DeleteRecordOptions {
  */
 export type TriggerInvokeResponse = string;
 
+// =====================================================
+// 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+
+    // 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;
+}
+
+/**
+ * Paginated response wrapper.
+ */
+export interface PaginatedResponse<T> {
+    /** Data items */
+    data: T[];
+    /** Pagination metadata */
+    meta: {
+        /** Total number of items */
+        total: number;
+        /** Current page number */
+        page: number;
+        /** Items per page */
+        pageSize: number;
+    };
+}
+
 // =====================================================
 // Smart Query Types
 // =====================================================
@@ -1526,6 +1970,341 @@ export function getValidationScanApiPath(workspaceId: string, batchId?: string):
     return batchId ? `${basePath}/${batchId}` : basePath;
 }
 
+// =====================================================
+// Orchestration API Paths
+// =====================================================
+
+/**
+ * Generate Orchestrations API URL PATH.
+ * Routes to the orchestration service.
+ */
+export function getOrchestrationsApiPath(workspaceId: string, orchestrationId?: string): string {
+    const basePath = `orchestration/ws/${workspaceId}/api/v1/orchestrations`;
+    return orchestrationId ? `${basePath}/${orchestrationId}` : basePath;
+}
+
+/**
+ * Generate Orchestration Runs API URL PATH.
+ */
+export function getOrchestrationRunsApiPath(workspaceId: string, orchestrationId: string, runId?: string): string {
+    const basePath = `orchestration/ws/${workspaceId}/api/v1/orchestrations/${orchestrationId}/runs`;
+    return runId ? `${basePath}/${runId}` : basePath;
+}
+
+/**
+ * Generate Orchestration Run Steps API URL PATH.
+ */
+export function getOrchestrationRunStepsApiPath(workspaceId: string, orchestrationId: string, runId: string): string {
+    return `orchestration/ws/${workspaceId}/api/v1/orchestrations/${orchestrationId}/runs/${runId}/steps`;
+}
+
+// =====================================================
+// Orchestrations Manager
+// =====================================================
+
+/**
+ * OrchestrationsManager provides methods for managing orchestrations and triggering runs.
+ * Access via `client.orchestrations`.
+ *
+ * Orchestrations are multi-step workflows that chain compute functions together
+ * with conditional logic, delays, and decision branches.
+ *
+ * Usage:
+ * ```ts
+ * // List all orchestrations
+ * const orchestrations = await client.orchestrations.list();
+ *
+ * // Get an orchestration by ID
+ * const orch = await client.orchestrations.get('orch-id');
+ *
+ * // Trigger an on-demand orchestration
+ * const run = await client.orchestrations.trigger('orch-id', {
+ *   input: { orderId: '12345' }
+ * });
+ *
+ * // Get run status
+ * const runStatus = await client.orchestrations.getRun('orch-id', run.data.id);
+ *
+ * // List runs for an orchestration
+ * const runs = await client.orchestrations.listRuns('orch-id');
+ * ```
+ */
+export class OrchestrationsManager {
+    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;
+    }
+
+    /**
+     * List all orchestrations in the workspace.
+     *
+     * @param options - Optional pagination and filtering options
+     * @returns Paginated list of orchestrations
+     *
+     * @example
+     * ```ts
+     * // List all orchestrations
+     * const result = await client.orchestrations.list();
+     * console.log('Total:', result.data.meta.total);
+     *
+     * // With pagination and status filter
+     * const result = await client.orchestrations.list({
+     *   limit: 10,
+     *   offset: 0,
+     *   status: 'active'
+     * });
+     * ```
+     */
+    public list(options?: ListOrchestrationsOptions): Promise<ApiResponse<PaginatedResponse<Orchestration>>> {
+        const path = getOrchestrationsApiPath(this.workspaceId);
+        return this.requestFn<PaginatedResponse<Orchestration>>('GET', path, null, options);
+    }
+
+    /**
+     * Get an orchestration by ID.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @returns The orchestration details including all steps
+     *
+     * @example
+     * ```ts
+     * const orch = await client.orchestrations.get('orch-id');
+     * console.log('Name:', orch.data.name);
+     * console.log('Steps:', orch.data.steps.length);
+     * ```
+     */
+    public get(orchestrationId: string): Promise<ApiResponse<Orchestration>> {
+        const path = getOrchestrationsApiPath(this.workspaceId, orchestrationId);
+        return this.requestFn<Orchestration>('GET', path);
+    }
+
+    /**
+     * Create a new orchestration.
+     *
+     * @param input - The orchestration definition
+     * @returns The created orchestration
+     *
+     * @example
+     * ```ts
+     * const orch = await client.orchestrations.create({
+     *   slug: 'order-processing',
+     *   name: 'Order Processing Workflow',
+     *   trigger: { type: 'on-demand' },
+     *   steps: [
+     *     {
+     *       id: 'validate',
+     *       type: 'compute',
+     *       functionId: 'func_validate',
+     *       onSuccess: { nextStepId: 'process' }
+     *     },
+     *     {
+     *       id: 'process',
+     *       type: 'compute',
+     *       functionId: 'func_process'
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    public create(input: CreateOrchestrationInput): Promise<ApiResponse<Orchestration>> {
+        const path = getOrchestrationsApiPath(this.workspaceId);
+        return this.requestFn<Orchestration>('POST', path, input);
+    }
+
+    /**
+     * Update an existing orchestration.
+     *
+     * Updates increment the orchestration version. Running instances use the
+     * version at the time they started.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @param input - Fields to update
+     * @returns The updated orchestration
+     *
+     * @example
+     * ```ts
+     * // Activate an orchestration
+     * await client.orchestrations.update('orch-id', { status: 'active' });
+     *
+     * // Update steps
+     * await client.orchestrations.update('orch-id', {
+     *   steps: [...]
+     * });
+     * ```
+     */
+    public update(orchestrationId: string, input: UpdateOrchestrationInput): Promise<ApiResponse<Orchestration>> {
+        const path = getOrchestrationsApiPath(this.workspaceId, orchestrationId);
+        return this.requestFn<Orchestration>('PUT', path, input);
+    }
+
+    /**
+     * Delete an orchestration.
+     *
+     * This also deletes all runs associated with the orchestration.
+     *
+     * @param orchestrationId - The orchestration ID
+     *
+     * @example
+     * ```ts
+     * await client.orchestrations.delete('orch-id');
+     * ```
+     */
+    public delete(orchestrationId: string): Promise<ApiResponse<void>> {
+        const path = getOrchestrationsApiPath(this.workspaceId, orchestrationId);
+        return this.requestFn<void>('DELETE', path);
+    }
+
+    /**
+     * Trigger an orchestration run.
+     *
+     * This creates a new run instance and starts executing the workflow.
+     * Can be used on on-demand, draft, or active orchestrations.
+     * Paused orchestrations cannot be triggered.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @param options - Optional input data and correlation ID
+     * @returns The created run
+     *
+     * @example
+     * ```ts
+     * // Simple trigger
+     * const run = await client.orchestrations.trigger('orch-id');
+     *
+     * // With input data
+     * const run = await client.orchestrations.trigger('orch-id', {
+     *   input: {
+     *     orderId: '12345',
+     *     customerId: 'cust_abc'
+     *   }
+     * });
+     *
+     * // With correlation ID for tracing
+     * const run = await client.orchestrations.trigger('orch-id', {
+     *   input: { orderId: '12345' },
+     *   correlationId: 'req-123'
+     * });
+     * ```
+     */
+    public trigger(orchestrationId: string, options?: TriggerOrchestrationRunOptions): Promise<ApiResponse<OrchestrationRun>> {
+        const path = getOrchestrationRunsApiPath(this.workspaceId, orchestrationId);
+        const body = {
+            input: options?.input ?? {},
+            correlationId: options?.correlationId
+        };
+        return this.requestFn<OrchestrationRun>('POST', path, body);
+    }
+
+    /**
+     * List runs for an orchestration.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @param options - Optional pagination and filtering options
+     * @returns Paginated list of runs
+     *
+     * @example
+     * ```ts
+     * // List all runs
+     * const runs = await client.orchestrations.listRuns('orch-id');
+     *
+     * // Filter by status
+     * const failedRuns = await client.orchestrations.listRuns('orch-id', {
+     *   status: 'failed'
+     * });
+     * ```
+     */
+    public listRuns(orchestrationId: string, options?: ListOrchestrationRunsOptions): Promise<ApiResponse<PaginatedResponse<OrchestrationRun>>> {
+        const path = getOrchestrationRunsApiPath(this.workspaceId, orchestrationId);
+        return this.requestFn<PaginatedResponse<OrchestrationRun>>('GET', path, null, options);
+    }
+
+    /**
+     * Get a specific run by ID.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @param runId - The run ID
+     * @param includeSteps - Whether to include step execution history
+     * @returns The run details
+     *
+     * @example
+     * ```ts
+     * // Get basic run info
+     * const run = await client.orchestrations.getRun('orch-id', 'run-id');
+     * console.log('Status:', run.data.status);
+     *
+     * // Include step history
+     * const run = await client.orchestrations.getRun('orch-id', 'run-id', true);
+     * console.log('Steps:', run.data.steps);
+     * ```
+     */
+    public getRun(orchestrationId: string, runId: string, includeSteps?: boolean): Promise<ApiResponse<OrchestrationRun & { steps?: OrchestrationRunStep[] }>> {
+        const path = getOrchestrationRunsApiPath(this.workspaceId, orchestrationId, runId);
+        const params = includeSteps ? { include: 'steps' } : undefined;
+        return this.requestFn<OrchestrationRun & { steps?: OrchestrationRunStep[] }>('GET', path, null, params);
+    }
+
+    /**
+     * Get step execution history for a run.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @param runId - The run ID
+     * @returns List of step executions
+     *
+     * @example
+     * ```ts
+     * const steps = await client.orchestrations.getRunSteps('orch-id', 'run-id');
+     * for (const step of steps.data.data) {
+     *   console.log(`${step.stepId}: ${step.status}`);
+     * }
+     * ```
+     */
+    public getRunSteps(orchestrationId: string, runId: string): Promise<ApiResponse<{ data: OrchestrationRunStep[]; meta: { total: number } }>> {
+        const path = getOrchestrationRunStepsApiPath(this.workspaceId, orchestrationId, runId);
+        return this.requestFn<{ data: OrchestrationRunStep[]; meta: { total: number } }>('GET', path);
+    }
+
+    /**
+     * Activate an orchestration.
+     *
+     * Convenience method to set status to 'active'.
+     * Active orchestrations can be triggered by scheduled events, record events, and webhooks.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @returns The updated orchestration
+     *
+     * @example
+     * ```ts
+     * await client.orchestrations.activate('orch-id');
+     * ```
+     */
+    public activate(orchestrationId: string): Promise<ApiResponse<Orchestration>> {
+        return this.update(orchestrationId, { status: 'active' });
+    }
+
+    /**
+     * Pause an orchestration.
+     *
+     * Convenience method to set status to 'paused'.
+     * Paused orchestrations cannot be triggered by any mechanism.
+     *
+     * @param orchestrationId - The orchestration ID
+     * @returns The updated orchestration
+     *
+     * @example
+     * ```ts
+     * await client.orchestrations.pause('orch-id');
+     * ```
+     */
+    public pause(orchestrationId: string): Promise<ApiResponse<Orchestration>> {
+        return this.update(orchestrationId, { status: 'paused' });
+    }
+}
+
 // =====================================================
 // Triggers Manager
 // =====================================================
@@ -2320,6 +3099,7 @@ export class CentraliSDK {
     private _smartQueries: SmartQueriesManager | null = null;
     private _anomalyInsights: AnomalyInsightsManager | null = null;
     private _validation: ValidationManager | null = null;
+    private _orchestrations: OrchestrationsManager | null = null;
 
     constructor(options: CentraliSDKOptions) {
         this.options = options;
@@ -2531,6 +3311,47 @@ export class CentraliSDK {
         return this._validation;
     }
 
+    /**
+     * Orchestrations namespace for managing multi-step workflows.
+     *
+     * Orchestrations chain compute functions together with conditional logic,
+     * delays, and decision branches to automate complex business processes.
+     *
+     * Usage:
+     * ```ts
+     * // List all orchestrations
+     * const orchestrations = await client.orchestrations.list();
+     *
+     * // Trigger an on-demand orchestration
+     * const run = await client.orchestrations.trigger('orch-id', {
+     *   input: { orderId: '12345' }
+     * });
+     *
+     * // Get run status
+     * const runStatus = await client.orchestrations.getRun('orch-id', run.data.id);
+     *
+     * // Create a new orchestration
+     * const orch = await client.orchestrations.create({
+     *   slug: 'order-processing',
+     *   name: 'Order Processing',
+     *   trigger: { type: 'on-demand' },
+     *   steps: [
+     *     { id: 'validate', type: 'compute', functionId: 'func_validate', onSuccess: { nextStepId: 'process' } },
+     *     { id: 'process', type: 'compute', functionId: 'func_process' }
+     *   ]
+     * });
+     * ```
+     */
+    public get orchestrations(): OrchestrationsManager {
+        if (!this._orchestrations) {
+            this._orchestrations = new OrchestrationsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._orchestrations;
+    }
+
     /**
      * Manually set or update the bearer token for subsequent requests.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-sdk",
-  "version": "2.8.7",
+  "version": "2.8.8",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
   "type": "commonjs",