@centrali-io/centrali-sdk 5.5.0 → 6.0.0

package/src/managers/orchestrationRuns.ts

@@ -0,0 +1,122 @@
+// =====================================================
+// Orchestration Runs Manager
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type { OrchestrationRun } from '../types/orchestrations';
+import type { QueryDefinition, QueryResult } from '../../query-types';
+import { getOrchestrationRunsCanonicalApiPath } from '../internal/paths';
+
+// =====================================================
+// Orchestration Runs Manager
+// =====================================================
+
+/**
+ * OrchestrationRunsManager — canonical query surface for orchestration runs
+ * (CEN-1217 / Phase 3 of the query foundation).
+ *
+ * Available methods:
+ * - {@link OrchestrationRunsManager.query | query} — canonical
+ *   `POST /orchestration-runs/query`. Use for nested boolean trees, `select`
+ *   projection, paging.
+ * - {@link OrchestrationRunsManager.test | test} — authoring dry-run against
+ *   `/orchestration-runs/query/test`. Validates and plans without executing.
+ *
+ * Per-orchestration trigger / list / get-by-id helpers stay on
+ * `client.orchestrations.{trigger, listRuns, getRun, getRunSteps}` — those
+ * back the legacy nested `/orchestrations/{id}/runs` routes (which now emit a
+ * Deprecation header pointing here for the list shape).
+ *
+ * Access via `client.orchestrationRuns`.
+ */
+export class OrchestrationRunsManager {
+    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;
+    }
+
+    /**
+     * Run a canonical query against `POST /workspace/<ws>/api/v1/orchestration-runs/query`.
+     *
+     * The body **is** a `QueryDefinition`. `resource` is forced to
+     * `"orchestration-runs"` — the orchestration-service executor rejects
+     * anything else. Returns the canonical `{ data, meta }` envelope.
+     *
+     * Queryable fields are the fixed-schema columns: `id`, `orchestrationId`,
+     * `orchestrationVersion`, `status`, `currentStepId`, `correlationId`,
+     * `triggerType`, `hasErrors`, `delayStepCount`, `loopIterationCount`,
+     * `failureReason`, `startedAt`, `completedAt`, `ttlExpiresAt`. The JSONB
+     * columns (`input`, `context`, `stepOutputs`, `triggerMetadata`,
+     * `activeLoop`) are intentionally not queryable —
+     * fetch a specific run via
+     * `client.orchestrations.getRun(orchestrationId, runId, true)` if you need
+     * its payload and step history.
+     *
+     * The `where` clause that pins `orchestrationId.eq` or `id.eq` (in a pure
+     * AND-of-scalar-eq shape) uses `orchestrations:retrieve` server-side;
+     * everything else uses `orchestrations:list`. Retrieve-only roles can
+     * still query a specific orchestration's run history this way.
+     *
+     * @example
+     * ```ts
+     * // Recent failed runs for a specific orchestration
+     * const failures = await client.orchestrationRuns.query({
+     *   resource: 'orchestration-runs',
+     *   where: {
+     *     and: [
+     *       { orchestrationId: { eq: 'orch-123' } },
+     *       { status: { eq: 'failed' } },
+     *     ],
+     *   },
+     *   sort: [{ field: 'startedAt', direction: 'desc' }],
+     *   page: { limit: 50 },
+     * });
+     *
+     * // Workspace-wide run activity in a date window with field projection
+     * const activity = await client.orchestrationRuns.query({
+     *   resource: 'orchestration-runs',
+     *   where: {
+     *     and: [
+     *       { startedAt: { gte: '2026-04-01' } },
+     *       { startedAt: { lt: '2026-05-01' } },
+     *     ],
+     *   },
+     *   sort: [{ field: 'startedAt', direction: 'desc' }],
+     *   page: { limit: 100 },
+     *   select: { fields: ['id', 'orchestrationId', 'status', 'startedAt', 'completedAt', 'hasErrors'] },
+     * });
+     * ```
+     */
+    public async query<T = OrchestrationRun>(
+        definition: Omit<QueryDefinition, 'resource'> & { resource?: string }
+    ): Promise<QueryResult<T>> {
+        const path = getOrchestrationRunsCanonicalApiPath(this.workspaceId, 'query');
+        const body: QueryDefinition = { ...definition, resource: 'orchestration-runs' };
+        const resp = await this.requestFn<T[]>('POST', path, body);
+        return resp as unknown as QueryResult<T>;
+    }
+
+    /**
+     * Authoring-time dry-run against `POST /orchestration-runs/query/test`.
+     *
+     * Same input shape as {@link OrchestrationRunsManager.query | query}.
+     * Returns a plan summary on success or structured `QueryError`s on
+     * failure, without executing the query. Use from query builders to
+     * surface precise errors before saving / running.
+     */
+    public async test(
+        definition: Omit<QueryDefinition, 'resource'> & { resource?: string }
+    ): Promise<{ ok: true; plan: { executor: string; resource: string; mode: string; hasUnreadableField: boolean } }> {
+        const path = getOrchestrationRunsCanonicalApiPath(this.workspaceId, 'query/test');
+        const body: QueryDefinition = { ...definition, resource: 'orchestration-runs' };
+        const resp = await this.requestFn<{ ok: true; plan: { executor: string; resource: string; mode: string; hasUnreadableField: boolean } }>('POST', path, body);
+        return resp.data;
+    }
+}

package/src/managers/orchestrations.ts

@@ -0,0 +1,297 @@
+// =====================================================
+// Orchestrations Manager
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse, PaginatedResponse } from '../types/common';
+import type {
+    Orchestration,
+    CreateOrchestrationInput,
+    UpdateOrchestrationInput,
+    OrchestrationRun,
+    OrchestrationRunStep,
+    TriggerOrchestrationRunOptions,
+    ListOrchestrationsOptions,
+    ListOrchestrationRunsOptions,
+} from '../types/orchestrations';
+import {
+    getOrchestrationsApiPath,
+    getOrchestrationRunsApiPath,
+    getOrchestrationRunStepsApiPath,
+} from '../internal/paths';
+
+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' });
+    }
+}

package/src/managers/query.ts

@@ -0,0 +1,199 @@
+// =====================================================
+// Query Manager (canonical query primitives — CEN-1202)
+// =====================================================
+
+import {
+    validateQueryDefinition,
+    translateLegacyQuery,
+    parseUrlQuery,
+    queryErrorsToHttp,
+} from '@centrali/query';
+import type {
+    QueryDefinition,
+    QueryError,
+    ValidationResult,
+} from '../../query-types';
+import { CentraliError } from '../internal/error';
+
+// ---------------------------------------------------------------------------
+// Vendored option/result types
+//
+// These mirror the option/result shapes exported from `@centrali/query`
+// (validator.ts, legacyTranslator.ts, urlParser.ts, errorAdapter.ts). They
+// are vendored locally so the published `dist/index.d.ts` does not pull in
+// `@centrali/query` (which would force consumers to install the workspace
+// package — failing the SDK's "one install" promise and breaking
+// `tsc --skipLibCheck=false`).
+//
+// Drift is caught by the parity tests in `tests/queryParity.test.ts` —
+// the runtime functions imported above expect the upstream shapes, and
+// any incompatibility surfaces as a TypeScript error at SDK build time.
+// ---------------------------------------------------------------------------
+
+/** Mirror of `@centrali/query`'s `ValidateOptions`. */
+export type QueryValidateOptions = {
+    rejectReservedClauses?: boolean;
+    reservedClauses?: readonly (keyof QueryDefinition)[];
+};
+
+/** Mirror of `@centrali/query`'s `LegacyTranslateWarning`. */
+export type LegacyTranslateWarning = {
+    kind:
+        | 'regex_translated'
+        | 'operator_renamed'
+        | 'variable_syntax_canonicalized'
+        | 'operator_dropped';
+    path: string;
+    from: string;
+    to?: string;
+};
+
+/** Mirror of `@centrali/query`'s `LegacyTranslateResult`. */
+export type LegacyTranslateResult = {
+    query: QueryDefinition;
+    warnings: LegacyTranslateWarning[];
+};
+
+/** Mirror of `@centrali/query`'s `LegacyTranslateOptions`. */
+export type LegacyTranslateOptions = {
+    resource?: string;
+    dataProperties?: ReadonlySet<string>;
+};
+
+/** Mirror of `@centrali/query`'s `ParsedUrlQuery`. */
+export type ParsedUrlQuery = {
+    query: QueryDefinition;
+    searchTerm?: string;
+};
+
+/** Mirror of `@centrali/query`'s `UrlParserOptions`. */
+export type UrlParserOptions = {
+    resource: string;
+    filterableFields?: readonly string[];
+    defaultLimit?: number;
+    maxLimit?: number;
+};
+
+/** Mirror of `@centrali/query`'s `QueryHttpErrorCode`. */
+export type QueryHttpErrorCode =
+    | 'UNSUPPORTED_CLAUSE'
+    | 'UNSUPPORTED_OPERATOR'
+    | 'UNSUPPORTED_LEGACY_OPERATOR'
+    | 'UNREADABLE_FIELD'
+    | 'INVALID_QUERY'
+    | 'LEGACY_WRITE_UNSUPPORTED'
+    | 'UNKNOWN_VARIABLE'
+    | 'VARIABLE_TYPE_MISMATCH'
+    | 'MISSING_REQUIRED_VARIABLE'
+    | 'EXTRA_VARIABLE'
+    | 'JOINS_LENGTH_EXCEEDED'
+    | 'UNSUPPORTED_COMBINATION'
+    | 'DUPLICATE_JOIN_ALIAS';
+
+/** Mirror of `@centrali/query`'s `QueryHttpError`. */
+export type QueryHttpError = {
+    status: number;
+    code: QueryHttpErrorCode;
+    message: string;
+    errors: QueryError[];
+};
+
+/**
+ * QueryManager exposes the canonical query primitives bundled into the SDK.
+ *
+ * The same source that runs server-side (`@centrali/query`) is bundled into
+ * the SDK artifact, so callers can validate a `QueryDefinition` locally and
+ * skip a roundtrip when the body is malformed. Output is byte-for-byte
+ * identical to the server's validator.
+ *
+ * Access via `client.query`.
+ *
+ * @example
+ * ```ts
+ * const result = client.query.validate({
+ *   resource: 'orders',
+ *   where: { 'data.status': { eq: 'open' } },
+ *   page: { limit: 50 },
+ * });
+ * if (!result.ok) {
+ *   for (const err of result.errors) console.log(err.code, err.path, err.message);
+ * }
+ *
+ * // Migrate a legacy saved-query body to canonical
+ * const t = client.query.translateLegacy({ collection: 'orders', limit: 25 });
+ * if (t.ok) console.log(t.value.query, t.value.warnings);
+ * ```
+ */
+export class QueryManager {
+    /**
+     * Validate a canonical `QueryDefinition` locally. Returns the same
+     * `ValidationResult` shape the server returns — `ok: true` plus the
+     * narrowed value, or `ok: false` plus the error list.
+     */
+    public validate(
+        definition: unknown,
+        options?: QueryValidateOptions
+    ): ValidationResult<QueryDefinition> {
+        return validateQueryDefinition(definition, options);
+    }
+
+    /**
+     * Translate a legacy query body (`{ collection, $eq, ... }`) into a
+     * canonical `QueryDefinition`. Useful for migration tooling and for
+     * smart-query authors carrying older bodies forward.
+     *
+     * Returns translation warnings alongside the canonical query so callers
+     * can surface "this used to be a regex / dropped operator" notes.
+     */
+    public translateLegacy(
+        legacyBody: unknown,
+        options?: LegacyTranslateOptions
+    ): ValidationResult<LegacyTranslateResult> {
+        return translateLegacyQuery(legacyBody, options) as ValidationResult<LegacyTranslateResult>;
+    }
+
+    /**
+     * Parse a URL-style flat query (`?status=paid&sort=-createdAt&limit=10`)
+     * into a canonical `QueryDefinition` slice. Mirrors the server-side
+     * GET-adapter so SDK consumers can pre-build canonical bodies from
+     * search-page URL state without a roundtrip.
+     */
+    public parseUrl(
+        params: Record<string, unknown>,
+        options: UrlParserOptions
+    ): ValidationResult<ParsedUrlQuery> {
+        return parseUrlQuery(params, options) as ValidationResult<ParsedUrlQuery>;
+    }
+
+    /**
+     * Aggregate one or more `QueryError`s into the same `{ status, code,
+     * message, errors }` shape the server emits. Use to convert a
+     * validation failure into a thrown `CentraliError` matching the wire
+     * format.
+     */
+    public errorsToHttp(errors: QueryError[]): QueryHttpError {
+        return queryErrorsToHttp(errors) as QueryHttpError;
+    }
+}
+
+/**
+ * Convert a list of `QueryError`s to a `CentraliError` matching what the
+ * server would have sent on a `422`. Used by `RecordsManager.query()` for
+ * local pre-rejection.
+ *
+ * @internal
+ */
+export function queryErrorsToCentraliError(errors: QueryError[]): CentraliError {
+    const http = queryErrorsToHttp(errors);
+    const fieldErrors = errors
+        .filter((e) => typeof e.path === 'string' && e.path.length > 0)
+        .map((e) => ({ field: e.path as string, message: e.message }));
+    return new CentraliError(
+        http.message,
+        http.status,
+        http.status === 422 ? 'Unprocessable Entity' : 'Bad Request',
+        { code: http.code, message: http.message, errors: http.errors },
+        http.code,
+        fieldErrors.length > 0 ? fieldErrors : undefined
+    );
+}