@centrali-io/centrali-sdk 5.5.1 → 6.0.0

package/src/managers/files.ts

@@ -0,0 +1,182 @@
+// =====================================================
+// Files Manager (CEN-1218 / Phase 3)
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type { QueryDefinition, QueryResult } from '../../query-types';
+import { getFilesCanonicalApiPath } from '../internal/paths';
+
+
+/**
+ * Canonical shape returned by `client.files.query()`. Mirrors the
+ * `filesquery` executor's canonical projection in the storage service —
+ * camelCase keys, snake_case never leaks. The truly internal blob-routing
+ * attributes (`storageAddress`, `uniqueName`) are intentionally not on
+ * the canonical surface. `renderId` IS exposed so callers can pass it to
+ * {@link CentraliCli.getFileRenderUrl} / {@link CentraliCli.getFileDownloadUrl}
+ * after discovering files via query.
+ *
+ * Optional fields are absent when unset on the row OR when not requested
+ * via `select.fields`.
+ */
+export interface FileMetadata {
+    /** UUID. Always present. */
+    id: string;
+    /** Original filename. */
+    name?: string;
+    /** Absolute storage path (e.g. `/root/shared/logo.png`). */
+    path?: string;
+    /** Parent folder display path. */
+    location?: string;
+    /** Workspace slug — pinned by the executor. */
+    workspaceSlug?: string;
+    /**
+     * Render token. Pass to {@link CentraliCli.getFileRenderUrl} to display
+     * a file inline (e.g. images), or {@link CentraliCli.getFileDownloadUrl}
+     * for an attachment-style download link.
+     */
+    renderId?: string;
+    /** MIME type (e.g. `image/png`). */
+    contentType?: string;
+    /** High-level file kind (image, video, document, …). */
+    fileType?: string;
+    /** Byte size. */
+    size?: number;
+    /** Parent folder UUID; null/absent for files at the root. */
+    folderId?: string | null;
+    /** User ID of the uploader. */
+    createdBy?: string;
+    /** ISO timestamp. */
+    createdAt?: string;
+    /** ISO timestamp. */
+    updatedAt?: string;
+    /** Whether the file is publicly accessible without auth. */
+    isPublic?: boolean;
+    /** Structure slug when this file is attached to a record (otherwise null). */
+    recordSlug?: string | null;
+    /** Authorization context: `general`, `record`, `avatar`, `support`, … */
+    fileContext?: string;
+    /** Soft-delete timestamp (null when active). */
+    deletedAt?: string | null;
+    /** Tags array; supports `hasAny` / `hasAll` operators in queries. */
+    tags?: string[];
+    /** Media duration in seconds (audio/video only). */
+    duration?: number | null;
+    /** Pixel width (image/video). */
+    width?: number | null;
+    /** Pixel height (image/video). */
+    height?: number | null;
+    /** Primary codec (e.g. `opus`, `h264`). */
+    codec?: string | null;
+    /** Bitrate in bits per second. */
+    bitrate?: number | null;
+}
+
+/**
+ * FilesManager exposes the canonical files query surface (CEN-1218,
+ * Phase 3 of the Query Foundation). Mirrors `client.orchestrationRuns`
+ * and `client.functionRuns`: a thin wrapper over
+ * `POST /files/query` and `/query/test`.
+ *
+ * Existing helpers (`client.uploadFile`, `client.getFileRenderUrl`,
+ * `client.createFolder`, …) stay where they are — those are workflow
+ * helpers, not query primitives.
+ *
+ * Access via `client.files`.
+ */
+export class FilesManager {
+    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 /storage/ws/<ws>/api/v1/files/query`.
+     *
+     * The body **is** a `QueryDefinition`. `resource` is forced to
+     * `"files"` — the storage executor rejects anything else. Returns the
+     * canonical `{ data, meta }` envelope.
+     *
+     * Queryable fields (canonical camelCase): `id`, `name`, `path`,
+     * `location`, `renderId`, `contentType`, `fileType`, `size`,
+     * `folderId`, `createdBy`, `createdAt`, `updatedAt`, `isPublic`,
+     * `recordSlug`, `fileContext`, `deletedAt`, `tags`, `duration`,
+     * `width`, `height`, `codec`, `bitrate`. Internal blob-routing
+     * columns (`storageAddress`, `uniqueName`) are intentionally not
+     * exposed.
+     *
+     * `tags` is a varchar array column — `hasAny` (overlap) and `hasAll`
+     * (contains) work; range operators don't.
+     *
+     * Authorization: a `where` that pins `id.eq` (in a flat AND-of-scalar-eq
+     * shape) routes through file-context-aware ABAC server-side, including
+     * record-backed files (`records:retrieve`) and path-keyed user / avatar
+     * / support policies. Non-scoped queries use `files:list`.
+     *
+     * @example
+     * ```ts
+     * // Recent images uploaded in the last 7 days
+     * const recent = await client.files.query({
+     *   resource: 'files',
+     *   where: {
+     *     and: [
+     *       { fileType: { eq: 'image' } },
+     *       { createdAt: { gte: '2026-04-24T00:00:00Z' } },
+     *     ],
+     *   },
+     *   sort: [{ field: 'createdAt', direction: 'desc' }],
+     *   page: { limit: 50 },
+     * });
+     *
+     * // Files in a folder, narrowed projection for a list UI
+     * const items = await client.files.query({
+     *   resource: 'files',
+     *   where: { folderId: { eq: 'folder-uuid' } },
+     *   select: { fields: ['name', 'contentType', 'size', 'createdAt'] },
+     *   page: { limit: 100 },
+     * });
+     *
+     * // Files tagged "draft" or "review"
+     * const drafts = await client.files.query({
+     *   resource: 'files',
+     *   where: { tags: { hasAny: ['draft', 'review'] } },
+     * });
+     * ```
+     */
+    public async query<T = FileMetadata>(
+        definition: Omit<QueryDefinition, 'resource'> & { resource?: string }
+    ): Promise<QueryResult<T>> {
+        const path = getFilesCanonicalApiPath(this.workspaceId, 'query');
+        const body: QueryDefinition = { ...definition, resource: 'files' };
+        const resp = await this.requestFn<T[]>('POST', path, body);
+        return resp as unknown as QueryResult<T>;
+    }
+
+    /**
+     * Authoring-time dry-run against `POST /files/query/test`.
+     *
+     * Same input shape as {@link FilesManager.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.
+     *
+     * The `/query/test` response is `{ ok, plan }` (NOT a `{ data }`
+     * envelope), so we return `resp.data` to unwrap the request layer's
+     * coercion — same convention as `client.orchestrationRuns.test`.
+     */
+    public async test(
+        definition: Omit<QueryDefinition, 'resource'> & { resource?: string }
+    ): Promise<{ ok: true; plan: { executor: string; resource: string; mode: string; hasUnreadableField: boolean } }> {
+        const path = getFilesCanonicalApiPath(this.workspaceId, 'query/test');
+        const body: QueryDefinition = { ...definition, resource: 'files' };
+        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/functionRuns.ts

@@ -0,0 +1,229 @@
+// =====================================================
+// Function Runs Manager
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse, PaginatedResponse } from '../types/common';
+import type {
+    FunctionRun,
+    ListFunctionRunsOptions,
+    ComputeJobStatusResponse,
+} from '../types/compute';
+import type { QueryDefinition, QueryResult } from '../../query-types';
+import {
+    getFunctionRunsApiPath,
+    getFunctionRunsByTriggerApiPath,
+    getFunctionRunsByFunctionApiPath,
+    getComputeJobStatusApiPath,
+} from '../internal/paths';
+
+/**
+ * Manager for querying function execution runs.
+ *
+ * Provides read access to function run history — useful for checking
+ * whether jobs completed, inspecting outputs, and monitoring trigger activity.
+ *
+ * - {@link FunctionRunsManager.query | query} — canonical `POST /function-runs/query`
+ *   (CEN-1216). Use for nested boolean trees, `select` projection, paging.
+ * - {@link FunctionRunsManager.test | test} — authoring dry-run against
+ *   `/function-runs/query/test`. Validates and plans without executing.
+ * - {@link FunctionRunsManager.listByTrigger | listByTrigger} /
+ *   {@link FunctionRunsManager.listByFunction | listByFunction} — legacy GET
+ *   surfaces, retained for back-compat. Prefer `query()` for new code.
+ *
+ * Access via `client.functionRuns` (canonical, CEN-1227). The legacy
+ * `client.runs` accessor remains as a deprecated alias.
+ */
+export class FunctionRunsManager {
+    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;
+    }
+
+    /**
+     * Get a function run by ID.
+     *
+     * @param runId - The function run UUID
+     * @returns The function run details
+     *
+     * @example
+     * ```ts
+     * const run = await client.functionRuns.get('run-uuid');
+     * console.log('Status:', run.data.status);
+     * console.log('Duration:', run.data.endedAt ? Date.parse(run.data.endedAt) - Date.parse(run.data.startedAt) : 'still running');
+     * ```
+     */
+    public get(runId: string): Promise<ApiResponse<FunctionRun>> {
+        const path = getFunctionRunsApiPath(this.workspaceId, runId);
+        return this.requestFn<FunctionRun>('GET', path);
+    }
+
+    /**
+     * List runs for a specific trigger.
+     *
+     * @param triggerId - The trigger UUID
+     * @param options - Optional pagination and status filter
+     * @returns Paginated list of function runs
+     *
+     * @example
+     * ```ts
+     * // List recent runs for a trigger
+     * const runs = await client.functionRuns.listByTrigger('trigger-uuid');
+     *
+     * // Filter to only failed runs
+     * const failed = await client.functionRuns.listByTrigger('trigger-uuid', {
+     *   status: 'failure'
+     * });
+     * ```
+     */
+    public listByTrigger(triggerId: string, options?: ListFunctionRunsOptions): Promise<ApiResponse<PaginatedResponse<FunctionRun>>> {
+        const path = getFunctionRunsByTriggerApiPath(this.workspaceId, triggerId);
+        const queryParams: Record<string, any> = {};
+        if (options?.page) queryParams.page = options.page;
+        if (options?.limit) queryParams.limit = options.limit;
+        if (options?.status) queryParams.status = options.status;
+        return this.requestFn<PaginatedResponse<FunctionRun>>('GET', path, null, queryParams);
+    }
+
+    /**
+     * List runs for a specific compute function.
+     *
+     * @param functionId - The compute function UUID
+     * @param options - Optional pagination and status filter
+     * @returns Paginated list of function runs
+     *
+     * @example
+     * ```ts
+     * // List recent runs for a function
+     * const runs = await client.functionRuns.listByFunction('function-uuid');
+     *
+     * // Only completed runs, page 2
+     * const completed = await client.functionRuns.listByFunction('function-uuid', {
+     *   status: 'completed',
+     *   page: 2
+     * });
+     * ```
+     */
+    public listByFunction(functionId: string, options?: ListFunctionRunsOptions): Promise<ApiResponse<PaginatedResponse<FunctionRun>>> {
+        const path = getFunctionRunsByFunctionApiPath(this.workspaceId, functionId);
+        const queryParams: Record<string, any> = {};
+        if (options?.page) queryParams.page = options.page;
+        if (options?.limit) queryParams.limit = options.limit;
+        if (options?.status) queryParams.status = options.status;
+        return this.requestFn<PaginatedResponse<FunctionRun>>('GET', path, null, queryParams);
+    }
+
+    /**
+     * Get the status of a compute job by job ID.
+     *
+     * This is the primary way to poll for the result of an async trigger
+     * invocation. The job ID is returned by `client.triggers.invoke()`.
+     *
+     * @param jobId - The job ID returned by invoke
+     * @returns Job status including returnValue (on success) or failedReason (on failure)
+     *
+     * @example
+     * ```ts
+     * // Invoke a trigger and poll for the result
+     * const { data: jobId } = await client.triggers.invoke('trigger-uuid');
+     *
+     * // Poll until complete
+     * let job;
+     * do {
+     *   await new Promise(r => setTimeout(r, 1000));
+     *   job = await client.functionRuns.getJobStatus(jobId);
+     * } while (job.data.status === 'queued' || job.data.status === 'running');
+     *
+     * if (job.data.status === 'completed') {
+     *   console.log('Result:', job.data.returnValue);
+     * } else {
+     *   console.error('Failed:', job.data.failedReason);
+     * }
+     * ```
+     */
+    public getJobStatus(jobId: string): Promise<ApiResponse<ComputeJobStatusResponse>> {
+        const path = getComputeJobStatusApiPath(this.workspaceId, jobId);
+        return this.requestFn<ComputeJobStatusResponse>('GET', path);
+    }
+
+    /**
+     * Run a canonical query against `POST /workspace/<ws>/api/v1/function-runs/query`.
+     *
+     * Phase 3 of the query foundation (CEN-1216). The body **is** a
+     * `QueryDefinition`. `resource` is forced to `"function-runs"` — the
+     * data-service executor rejects anything else. Returns the canonical
+     * `{ data, meta }` envelope.
+     *
+     * Queryable fields are the fixed-schema columns: `id`, `functionId`,
+     * `triggerId`, `status`, `startedAt`, `endedAt`, `executionSource`,
+     * `errorCode`, `errorMessage`, etc. The `runData` and `executionContext`
+     * JSONB columns are intentionally not queryable — fetch a specific run
+     * via `client.functionRuns.get(runId)` if you need its payload.
+     *
+     * The `where` clause that pins `functionId.eq` or `triggerId.eq` (in a
+     * pure AND-of-scalar-eq shape) uses `function_runs:retrieve` server-side;
+     * everything else uses `function_runs:list`. Retrieve-only roles can
+     * still query a specific function or trigger's run history this way.
+     *
+     * @example
+     * ```ts
+     * // Recent failures for a function
+     * const failures = await client.functionRuns.query({
+     *   resource: 'function-runs',
+     *   where: {
+     *     and: [
+     *       { functionId: { eq: 'fn-123' } },
+     *       { status: { eq: 'failure' } },
+     *     ],
+     *   },
+     *   sort: [{ field: 'startedAt', direction: 'desc' }],
+     *   page: { limit: 50 },
+     * });
+     *
+     * // Workspace-wide run activity in a date window with field projection
+     * const activity = await client.functionRuns.query({
+     *   resource: 'function-runs',
+     *   where: {
+     *     and: [
+     *       { startedAt: { gte: '2026-04-01' } },
+     *       { startedAt: { lt: '2026-05-01' } },
+     *     ],
+     *   },
+     *   sort: [{ field: 'startedAt', direction: 'desc' }],
+     *   page: { limit: 100 },
+     *   select: { fields: ['id', 'functionId', 'status', 'startedAt', 'endedAt', 'errorCode'] },
+     * });
+     * ```
+     */
+    public async query<T = FunctionRun>(
+        definition: Omit<QueryDefinition, 'resource'> & { resource?: string }
+    ): Promise<QueryResult<T>> {
+        const path = `data/workspace/${this.workspaceId}/api/v1/function-runs/query`;
+        const body: QueryDefinition = { ...definition, resource: 'function-runs' };
+        const resp = await this.requestFn<T[]>('POST', path, body);
+        return resp as unknown as QueryResult<T>;
+    }
+
+    /**
+     * Authoring-time dry-run against `POST /function-runs/query/test`.
+     *
+     * Same input shape as {@link FunctionRunsManager.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 = `data/workspace/${this.workspaceId}/api/v1/function-runs/query/test`;
+        const body: QueryDefinition = { ...definition, resource: 'function-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/functions.ts

@@ -0,0 +1,171 @@
+// =====================================================
+// Compute Functions Manager (Configuration-as-Code)
+// =====================================================
+
+import type { Method } from 'axios';
+import type { ApiResponse } from '../types/common';
+import type {
+    ComputeFunction,
+    CreateComputeFunctionInput,
+    UpdateComputeFunctionInput,
+    ListComputeFunctionsOptions,
+    TestComputeFunctionInput,
+    TestComputeFunctionResult,
+} from '../types/compute';
+import {
+    getComputeFunctionsApiPath,
+    getComputeFunctionTestApiPath,
+} from '../internal/paths';
+
+// =====================================================
+// Compute Functions Manager (Configuration-as-Code)
+// =====================================================
+
+/**
+ * ComputeFunctionsManager provides methods for managing compute functions.
+ * Compute functions are JavaScript code blocks that can be executed on triggers,
+ * schedules, or on-demand.
+ * Access via `client.functions`.
+ *
+ * Usage:
+ * ```ts
+ * // List all compute functions
+ * const fns = await client.functions.list();
+ *
+ * // Create a new function
+ * const fn = await client.functions.create({
+ *   name: 'Process Order',
+ *   code: 'async function run() { return { processed: true }; }'
+ * });
+ *
+ * // Test execute code without saving
+ * const result = await client.functions.testExecute({
+ *   code: 'async function run() { return executionParams; }',
+ *   params: { orderId: '123' }
+ * });
+ * ```
+ */
+export class ComputeFunctionsManager {
+    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 compute functions in the workspace.
+     *
+     * @param options - Optional list parameters (pagination, search)
+     * @returns List of compute functions
+     *
+     * @example
+     * ```ts
+     * const fns = await client.functions.list();
+     * const searched = await client.functions.list({ search: 'order', limit: 10 });
+     * ```
+     */
+    public list(options?: ListComputeFunctionsOptions): Promise<ApiResponse<ComputeFunction[]>> {
+        const path = getComputeFunctionsApiPath(this.workspaceId);
+        return this.requestFn<ComputeFunction[]>('GET', path, null, options);
+    }
+
+    /**
+     * Get a compute function by ID.
+     *
+     * @param functionId - The compute function UUID
+     * @returns The compute function details
+     *
+     * @example
+     * ```ts
+     * const fn = await client.functions.get('function-uuid');
+     * console.log('Function name:', fn.data.name);
+     * ```
+     */
+    public get(functionId: string): Promise<ApiResponse<ComputeFunction>> {
+        const path = getComputeFunctionsApiPath(this.workspaceId, functionId);
+        return this.requestFn<ComputeFunction>('GET', path);
+    }
+
+    /**
+     * Create a new compute function.
+     *
+     * @param input - The function definition
+     * @returns The created compute function
+     *
+     * @example
+     * ```ts
+     * const fn = await client.functions.create({
+     *   name: 'Process Order',
+     *   code: 'async function run() { return { processed: true }; }',
+     *   description: 'Processes incoming orders',
+     *   timeoutMs: 60000
+     * });
+     * ```
+     */
+    public create(input: CreateComputeFunctionInput): Promise<ApiResponse<ComputeFunction>> {
+        const path = getComputeFunctionsApiPath(this.workspaceId);
+        return this.requestFn<ComputeFunction>('POST', path, input);
+    }
+
+    /**
+     * Update an existing compute function.
+     *
+     * @param functionId - The compute function UUID
+     * @param input - The fields to update
+     * @returns The updated compute function
+     *
+     * @example
+     * ```ts
+     * const updated = await client.functions.update('function-uuid', {
+     *   code: 'async function run() { return { v2: true }; }',
+     *   timeoutMs: 120000
+     * });
+     * ```
+     */
+    public update(functionId: string, input: UpdateComputeFunctionInput): Promise<ApiResponse<ComputeFunction>> {
+        const path = getComputeFunctionsApiPath(this.workspaceId, functionId);
+        return this.requestFn<ComputeFunction>('PUT', path, input);
+    }
+
+    /**
+     * Delete a compute function.
+     *
+     * @param functionId - The compute function UUID
+     *
+     * @example
+     * ```ts
+     * await client.functions.delete('function-uuid');
+     * ```
+     */
+    public delete(functionId: string): Promise<ApiResponse<void>> {
+        const path = getComputeFunctionsApiPath(this.workspaceId, functionId);
+        return this.requestFn<void>('DELETE', path);
+    }
+
+    /**
+     * Test execute code without saving it as a function.
+     * Useful for validating function code before creating/updating.
+     *
+     * @param input - The code to test and optional input data
+     * @returns Test execution result including output, duration, and logs
+     *
+     * @example
+     * ```ts
+     * const result = await client.functions.testExecute({
+     *   code: 'async function run() { return { sum: executionParams.a + executionParams.b }; }',
+     *   params: { a: 1, b: 2 }
+     * });
+     * console.log('Output:', result.data.output); // { sum: 3 }
+     * console.log('Duration:', result.data.duration_ms, 'ms');
+     * ```
+     */
+    public testExecute(input: TestComputeFunctionInput): Promise<ApiResponse<TestComputeFunctionResult>> {
+        const path = getComputeFunctionTestApiPath(this.workspaceId);
+        return this.requestFn<TestComputeFunctionResult>('POST', path, input);
+    }
+}