@centrali-io/centrali-sdk 4.4.2 → 4.4.5

package/README.md

@@ -4,6 +4,8 @@ Official Node.js SDK for Centrali - Build modern web applications without managi
 
 [![npm version](https://badge.fury.io/js/%40centrali-io%2Fcentrali-sdk.svg)](https://www.npmjs.com/package/@centrali-io/centrali-sdk)
 
+> **Full documentation:** [docs.centrali.io](https://docs.centrali.io) — SDK guide, API reference, compute functions, orchestrations, and more.
+
 > **Try it now!** Explore the SDK in our [Live Playground on StackBlitz](https://stackblitz.com/~/github.com/centrali-demo/sdk-playground) - no setup required.
 
 ## Installation
@@ -20,7 +22,7 @@ import { CentraliSDK } from '@centrali-io/centrali-sdk';
 // Initialize the SDK
 const centrali = new CentraliSDK({
   baseUrl: 'https://centrali.io',
-  workspaceId: 'your-workspace',
+  workspaceId: 'your-workspace-slug',  // This is the workspace slug, not a UUID
   token: 'your-api-key'
 });
 
@@ -40,7 +42,16 @@ console.log('Found:', results.data.totalHits, 'results');
 
 ## Authentication
 
-The SDK supports three authentication methods. See the [full authentication guide](../docs/sdk/authentication.md) for details.
+The SDK supports three authentication methods. See the [full authentication guide](https://docs.centrali.io/guides/centrali-sdk#authentication) for details.
+
+### Recommended Auth by Context
+
+| Context | Method | Why |
+|---------|--------|-----|
+| **Browser / frontend app** | Publishable key | Safe to expose in client code, scoped to specific resources |
+| **Server app / API route** | Service account | Server-to-server, automatic token refresh |
+| **MCP agent** | Service account (env vars) | `CENTRALI_CLIENT_ID` + `CENTRALI_CLIENT_SECRET` + `CENTRALI_WORKSPACE_ID` |
+| **App with its own auth (Clerk, Auth0)** | External token / BYOT | Dynamic token callback |
 
 ### Publishable Key (Frontend Apps)
 
@@ -49,7 +60,7 @@ Safe to use in browser code. Scoped to specific resources.
 ```typescript
 const centrali = new CentraliSDK({
   baseUrl: 'https://centrali.io',
-  workspaceId: 'your-workspace',
+  workspaceId: 'your-workspace-slug',
   publishableKey: 'pk_live_your_key_here'
 });
 ```
@@ -61,7 +72,7 @@ Dynamic token callback for apps with their own auth.
 ```typescript
 const centrali = new CentraliSDK({
   baseUrl: 'https://centrali.io',
-  workspaceId: 'your-workspace',
+  workspaceId: 'your-workspace-slug',
   getToken: async () => await clerk.session.getToken()
 });
 ```
@@ -73,12 +84,14 @@ Never use in browser code. Client secret must stay on the server.
 ```typescript
 const centrali = new CentraliSDK({
   baseUrl: 'https://centrali.io',
-  workspaceId: 'your-workspace',
+  workspaceId: 'your-workspace-slug',
   clientId: process.env.CENTRALI_CLIENT_ID,
   clientSecret: process.env.CENTRALI_CLIENT_SECRET
 });
 ```
 
+> **Note:** `workspaceId` is always the **workspace slug** (e.g., `"acme"`), not a UUID.
+
 ## Features
 
 - ✅ **Type-safe API** with full TypeScript support
@@ -403,17 +416,106 @@ const realtime = new RealtimeManager(
 );
 ```
 
-### Compute Functions (via Triggers)
+### Compute Functions
+
+Compute functions are JavaScript code blocks that execute in a sandboxed environment. Every function uses the same signature:
+
+```javascript
+async function run() {
+  // Three variables are available:
+  // - api:             SDK for records, HTTP, files, crypto, logging
+  // - triggerParams:   static config from the trigger definition
+  // - executionParams: dynamic data from the current invocation
+
+  const result = await api.httpRequest({
+    url: 'https://api.example.com/data',
+    method: 'POST',
+    body: JSON.stringify(executionParams.payload)
+  });
+
+  return { success: true, data: result };
+}
+```
+
+> **Important:** Use `async function run() { ... }`. Do NOT use `module.exports`.
+
+#### Compute Input Contract
+
+What `triggerParams` and `executionParams` contain depends on how the function is invoked:
+
+| Trigger type | `triggerParams` | `executionParams` |
+|--------------|-----------------|-------------------|
+| **HTTP trigger** | Static params from trigger definition | `{ payload }` — parsed request body |
+| **Endpoint trigger** | Static params from trigger definition | `{ payload, method, headers, query }` — full HTTP context |
+| **Scheduled trigger** | Static params from trigger definition (max 64KB) | `{}` — empty |
+| **Pages action** | `{ input, token }` — from page action invocation | `{}` — empty |
+| **Orchestration step** | Orchestration input + previous step outputs + decrypted encrypted params | Not used (all input arrives via `triggerParams`) |
+
+#### The `api` Object
+
+Every compute function has access to `api`, which provides:
+
+| Category | Methods |
+|----------|---------|
+| **Records** | `queryRecords`, `fetchRecord`, `createRecord`, `updateRecord`, `deleteRecord`, `bulkCreateRecords`, `bulkUpdateRecords`, `bulkDeleteRecords` |
+| **HTTP** | `httpRequest`, `httpFetch` (outbound calls to allowed domains) |
+| **Files** | `storeFile`, `storeAsCSV`, `storeAsJSON` |
+| **Crypto** | `crypto.sha256`, `crypto.hmacSha256`, `crypto.rsaSign`, `crypto.signJwt` |
+| **Utilities** | `uuid`, `formatDate`, `chunk`, `merge`, `math`, `evaluate`, `renderTemplate`, `log`, `logError` |
+| **Conversion** | `toCSV`, `toJSON` |
+
+#### Secrets in Compute Functions
+
+Compute functions have **no built-in environment variables or secrets field**. To pass secrets (API keys, credentials) to a compute function:
+
+- **Recommended:** Wrap the function in an orchestration and use **encrypted params** on the compute step. Encrypted params are stored with AES-256-GCM at rest and decrypted at execution time — they arrive in `triggerParams`.
+- **Alternative:** Pass secrets in the trigger invocation payload via `executionParams`. This works but means the calling app is the courier for the secret.
+
+See [Orchestrations](#orchestrations) for encrypted params usage.
+
+#### Invoking Triggers
+
+Trigger invocation is **asynchronous** — it returns a job ID, not the execution result. Use the function runs API to poll for the result.
 
 ```typescript
-// Invoke an on-demand trigger to execute a compute function
+// Invoke an on-demand trigger
 const job = await centrali.triggers.invoke('trigger-id', {
   payload: { data: 'your-input-data' }
 });
-
 console.log('Job queued:', job.data);
+
+// Poll for the result using function runs
+// (The job ID maps to a function run — query by trigger to find it)
+const runs = await centrali.runs.listByTrigger('trigger-id', { limit: 1 });
+const latestRun = runs.data.data[0];
+console.log('Status:', latestRun.status);       // pending | running | completed | failure | timeout
+console.log('Result:', latestRun.runData);       // execution output (once completed)
+console.log('Error:', latestRun.errorMessage);   // error details (if failed)
+```
+
+#### Function Runs (Execution History)
+
+Query execution history for debugging and observability:
+
+```typescript
+// Get a specific run by ID
+const run = await centrali.runs.get('run-uuid');
+console.log('Status:', run.data.status);
+console.log('Output:', run.data.runData);
+console.log('Duration:', run.data.startedAt, '→', run.data.endedAt);
+
+// List runs for a trigger (most recent first)
+const triggerRuns = await centrali.runs.listByTrigger('trigger-uuid', {
+  status: 'failure',  // Filter by status
+  limit: 10
+});
+
+// List runs for a function
+const functionRuns = await centrali.runs.listByFunction('function-uuid');
 ```
 
+Run statuses: `pending` → `running` → `completed` | `failure` | `timeout`
+
 ### File Uploads
 
 ```typescript

package/dist/index.js

@@ -51,7 +51,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CentraliSDK = exports.ComputeFunctionsManager = exports.CollectionsManager = exports.StructuresManager = exports.AllowedDomainsManager = exports.ValidationManager = exports.AnomalyInsightsManager = exports.SmartQueriesManager = exports.TriggersManager = exports.OrchestrationsManager = exports.RealtimeManager = exports.CentraliError = void 0;
+exports.CentraliSDK = exports.FunctionRunsManager = exports.ComputeFunctionsManager = exports.CollectionsManager = exports.StructuresManager = exports.AllowedDomainsManager = exports.ValidationManager = exports.AnomalyInsightsManager = exports.SmartQueriesManager = exports.TriggersManager = exports.OrchestrationsManager = exports.RealtimeManager = exports.CentraliError = void 0;
 exports.isCentraliError = isCentraliError;
 exports.getApiUrl = getApiUrl;
 exports.getAuthUrl = getAuthUrl;
@@ -84,6 +84,9 @@ exports.getCollectionBySlugApiPath = getCollectionBySlugApiPath;
 exports.getCollectionValidateApiPath = getCollectionValidateApiPath;
 exports.getComputeFunctionsApiPath = getComputeFunctionsApiPath;
 exports.getComputeFunctionTestApiPath = getComputeFunctionTestApiPath;
+exports.getFunctionRunsApiPath = getFunctionRunsApiPath;
+exports.getFunctionRunsByTriggerApiPath = getFunctionRunsByTriggerApiPath;
+exports.getFunctionRunsByFunctionApiPath = getFunctionRunsByFunctionApiPath;
 exports.getSmartQueryTestApiPath = getSmartQueryTestApiPath;
 exports.getValidationSuggestionsApiPath = getValidationSuggestionsApiPath;
 exports.getValidationSuggestionAcceptApiPath = getValidationSuggestionAcceptApiPath;
@@ -656,6 +659,28 @@ function getComputeFunctionTestApiPath(workspaceId) {
     return `data/workspace/${workspaceId}/api/v1/compute-functions/test`;
 }
 // =====================================================
+// Function Runs API Path Helpers
+// =====================================================
+/**
+ * Generate Function Runs base API URL PATH.
+ */
+function getFunctionRunsApiPath(workspaceId, runId) {
+    const basePath = `data/workspace/${workspaceId}/api/v1/function-runs`;
+    return runId ? `${basePath}/${runId}` : basePath;
+}
+/**
+ * Generate Function Runs by trigger API URL PATH.
+ */
+function getFunctionRunsByTriggerApiPath(workspaceId, triggerId) {
+    return `data/workspace/${workspaceId}/api/v1/function-runs/trigger/${triggerId}`;
+}
+/**
+ * Generate Function Runs by function API URL PATH.
+ */
+function getFunctionRunsByFunctionApiPath(workspaceId, functionId) {
+    return `data/workspace/${workspaceId}/api/v1/function-runs/function/${functionId}`;
+}
+// =====================================================
 // Smart Query Test API Path Helper (Configuration-as-Code)
 // =====================================================
 /**
@@ -2382,12 +2407,12 @@ exports.CollectionsManager = CollectionsManager;
  * // Create a new function
  * const fn = await client.functions.create({
  *   name: 'Process Order',
- *   code: 'module.exports = async (ctx) => { return { processed: true }; }'
+ *   code: 'async function run() { return { processed: true }; }'
  * });
  *
  * // Test execute code without saving
  * const result = await client.functions.testExecute({
- *   code: 'module.exports = async (ctx) => { return ctx.executionParams; }',
+ *   code: 'async function run() { return executionParams; }',
  *   params: { orderId: '123' }
  * });
  * ```
@@ -2439,7 +2464,7 @@ class ComputeFunctionsManager {
      * ```ts
      * const fn = await client.functions.create({
      *   name: 'Process Order',
-     *   code: 'module.exports = async (ctx) => { return { processed: true }; }',
+     *   code: 'async function run() { return { processed: true }; }',
      *   description: 'Processes incoming orders',
      *   timeoutMs: 60000
      * });
@@ -2459,7 +2484,7 @@ class ComputeFunctionsManager {
      * @example
      * ```ts
      * const updated = await client.functions.update('function-uuid', {
-     *   code: 'module.exports = async (ctx) => { return { v2: true }; }',
+     *   code: 'async function run() { return { v2: true }; }',
      *   timeoutMs: 120000
      * });
      * ```
@@ -2492,7 +2517,7 @@ class ComputeFunctionsManager {
      * @example
      * ```ts
      * const result = await client.functions.testExecute({
-     *   code: 'module.exports = async (ctx) => { return { sum: ctx.executionParams.a + ctx.executionParams.b }; }',
+     *   code: 'async function run() { return { sum: executionParams.a + executionParams.b }; }',
      *   params: { a: 1, b: 2 }
      * });
      * console.log('Output:', result.data.output); // { sum: 3 }
@@ -2505,6 +2530,97 @@ class ComputeFunctionsManager {
     }
 }
 exports.ComputeFunctionsManager = ComputeFunctionsManager;
+/**
+ * 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.
+ *
+ * Access via `client.runs`.
+ */
+class FunctionRunsManager {
+    constructor(workspaceId, requestFn) {
+        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.runs.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');
+     * ```
+     */
+    get(runId) {
+        const path = getFunctionRunsApiPath(this.workspaceId, runId);
+        return this.requestFn('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.runs.listByTrigger('trigger-uuid');
+     *
+     * // Filter to only failed runs
+     * const failed = await client.runs.listByTrigger('trigger-uuid', {
+     *   status: 'failure'
+     * });
+     * ```
+     */
+    listByTrigger(triggerId, options) {
+        const path = getFunctionRunsByTriggerApiPath(this.workspaceId, triggerId);
+        const queryParams = {};
+        if (options === null || options === void 0 ? void 0 : options.page)
+            queryParams.page = options.page;
+        if (options === null || options === void 0 ? void 0 : options.limit)
+            queryParams.limit = options.limit;
+        if (options === null || options === void 0 ? void 0 : options.status)
+            queryParams.status = options.status;
+        return this.requestFn('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.runs.listByFunction('function-uuid');
+     *
+     * // Only completed runs, page 2
+     * const completed = await client.runs.listByFunction('function-uuid', {
+     *   status: 'completed',
+     *   page: 2
+     * });
+     * ```
+     */
+    listByFunction(functionId, options) {
+        const path = getFunctionRunsByFunctionApiPath(this.workspaceId, functionId);
+        const queryParams = {};
+        if (options === null || options === void 0 ? void 0 : options.page)
+            queryParams.page = options.page;
+        if (options === null || options === void 0 ? void 0 : options.limit)
+            queryParams.limit = options.limit;
+        if (options === null || options === void 0 ? void 0 : options.status)
+            queryParams.status = options.status;
+        return this.requestFn('GET', path, null, queryParams);
+    }
+}
+exports.FunctionRunsManager = FunctionRunsManager;
 /**
  * Main Centrali SDK client.
  */
@@ -2521,6 +2637,7 @@ class CentraliSDK {
         this._structures = null;
         this._collections = null;
         this._functions = null;
+        this._runs = null;
         this.isRefreshingToken = false;
         this.tokenRefreshPromise = null;
         this.options = options;
@@ -2897,12 +3014,12 @@ class CentraliSDK {
      * // Create a function
      * const fn = await client.functions.create({
      *   name: 'Process Order',
-         *   code: 'module.exports = async (ctx) => { return { ok: true }; }'
+     *   code: 'async function run() { return { ok: true }; }'
      * });
      *
      * // Test execute without saving
      * const result = await client.functions.testExecute({
-     *   code: 'module.exports = async (ctx) => { return ctx.executionParams; }',
+     *   code: 'async function run() { return executionParams; }',
      *   params: { test: true }
      * });
      * ```
@@ -2913,6 +3030,29 @@ class CentraliSDK {
         }
         return this._functions;
     }
+    /**
+     * Runs namespace for querying execution history.
+     *
+     * Usage:
+     * ```ts
+     * // Get a specific run
+     * const run = await client.runs.get('run-id');
+     *
+     * // List runs for a trigger
+     * const runs = await client.runs.listByTrigger('trigger-id');
+     *
+     * // List failed runs for a compute definition
+     * const failed = await client.runs.listByFunction('fn-id', {
+     *   status: 'failure'
+     * });
+     * ```
+     */
+    get runs() {
+        if (!this._runs) {
+            this._runs = new FunctionRunsManager(this.options.workspaceId, this.request.bind(this));
+        }
+        return this._runs;
+    }
     /**
      * Manually set or update the bearer token for subsequent requests.
      */

package/index.ts

@@ -1780,6 +1780,66 @@ export interface TestComputeFunctionResult {
     error?: string;
 }
 
+// =====================================================
+// Function Run Types
+// =====================================================
+
+/**
+ * Execution source for a function run.
+ */
+export type FunctionRunExecutionSource = 'trigger' | 'rerun' | 'manual' | 'scheduled' | 'http-trigger' | 'orchestration' | 'endpoint';
+
+/**
+ * Status of a function run.
+ */
+export type FunctionRunStatus = 'pending' | 'running' | 'completed' | 'failure' | 'timeout';
+
+/**
+ * A function run record representing a single execution of a compute function.
+ */
+export interface FunctionRun {
+    id: string;
+    createdBy: string;
+    functionId: string;
+    workspaceSlug: string;
+    jobId: string;
+    status: FunctionRunStatus;
+    runData: any | null;
+    startedAt: string;
+    endedAt?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+    executionId: string;
+    triggerId?: string | null;
+    triggerType?: string | null;
+    orchestrationRunId?: string | null;
+    orchestrationStepId?: string | null;
+    originalRunId?: string | null;
+    isRerun: boolean;
+    rerunCount: number;
+    rerunBy?: string | null;
+    rerunReason?: string | null;
+    functionCodeHash?: string | null;
+    functionVersion?: string | null;
+    executionSource: FunctionRunExecutionSource;
+    memoryUsageBytes?: number | null;
+    cpuUsageSeconds?: number | null;
+    errorCode?: string | null;
+    errorMessage?: string | null;
+    dataStrippedAt?: string | null;
+    archiveStorageAddress?: string | null;
+    archivedAt?: string | null;
+}
+
+/**
+ * Options for listing function runs by trigger or function.
+ */
+export interface ListFunctionRunsOptions {
+    page?: number;
+    limit?: number;
+    status?: FunctionRunStatus;
+}
+
 // =====================================================
 // Trigger CRUD Types (Configuration-as-Code)
 // =====================================================
@@ -2734,6 +2794,32 @@ export function getComputeFunctionTestApiPath(workspaceId: string): string {
     return `data/workspace/${workspaceId}/api/v1/compute-functions/test`;
 }
 
+// =====================================================
+// Function Runs API Path Helpers
+// =====================================================
+
+/**
+ * Generate Function Runs base API URL PATH.
+ */
+export function getFunctionRunsApiPath(workspaceId: string, runId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/function-runs`;
+    return runId ? `${basePath}/${runId}` : basePath;
+}
+
+/**
+ * Generate Function Runs by trigger API URL PATH.
+ */
+export function getFunctionRunsByTriggerApiPath(workspaceId: string, triggerId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/function-runs/trigger/${triggerId}`;
+}
+
+/**
+ * Generate Function Runs by function API URL PATH.
+ */
+export function getFunctionRunsByFunctionApiPath(workspaceId: string, functionId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/function-runs/function/${functionId}`;
+}
+
 // =====================================================
 // Smart Query Test API Path Helper (Configuration-as-Code)
 // =====================================================
@@ -4626,12 +4712,12 @@ export class CollectionsManager {
  * // Create a new function
  * const fn = await client.functions.create({
  *   name: 'Process Order',
- *   code: 'module.exports = async (ctx) => { return { processed: true }; }'
+ *   code: 'async function run() { return { processed: true }; }'
  * });
  *
  * // Test execute code without saving
  * const result = await client.functions.testExecute({
- *   code: 'module.exports = async (ctx) => { return ctx.executionParams; }',
+ *   code: 'async function run() { return executionParams; }',
  *   params: { orderId: '123' }
  * });
  * ```
@@ -4692,7 +4778,7 @@ export class ComputeFunctionsManager {
      * ```ts
      * const fn = await client.functions.create({
      *   name: 'Process Order',
-     *   code: 'module.exports = async (ctx) => { return { processed: true }; }',
+     *   code: 'async function run() { return { processed: true }; }',
      *   description: 'Processes incoming orders',
      *   timeoutMs: 60000
      * });
@@ -4713,7 +4799,7 @@ export class ComputeFunctionsManager {
      * @example
      * ```ts
      * const updated = await client.functions.update('function-uuid', {
-     *   code: 'module.exports = async (ctx) => { return { v2: true }; }',
+     *   code: 'async function run() { return { v2: true }; }',
      *   timeoutMs: 120000
      * });
      * ```
@@ -4748,7 +4834,7 @@ export class ComputeFunctionsManager {
      * @example
      * ```ts
      * const result = await client.functions.testExecute({
-     *   code: 'module.exports = async (ctx) => { return { sum: ctx.executionParams.a + ctx.executionParams.b }; }',
+     *   code: 'async function run() { return { sum: executionParams.a + executionParams.b }; }',
      *   params: { a: 1, b: 2 }
      * });
      * console.log('Output:', result.data.output); // { sum: 3 }
@@ -4761,6 +4847,100 @@ export class ComputeFunctionsManager {
     }
 }
 
+/**
+ * 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.
+ *
+ * Access via `client.runs`.
+ */
+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.runs.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.runs.listByTrigger('trigger-uuid');
+     *
+     * // Filter to only failed runs
+     * const failed = await client.runs.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.runs.listByFunction('function-uuid');
+     *
+     * // Only completed runs, page 2
+     * const completed = await client.runs.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);
+    }
+}
+
 /**
  * Main Centrali SDK client.
  */
@@ -4778,6 +4958,7 @@ export class CentraliSDK {
     private _structures: StructuresManager | null = null;
     private _collections: CollectionsManager | null = null;
     private _functions: ComputeFunctionsManager | null = null;
+    private _runs: FunctionRunsManager | null = null;
     private isRefreshingToken: boolean = false;
     private tokenRefreshPromise: Promise<string> | null = null;
 
@@ -5228,12 +5409,12 @@ export class CentraliSDK {
      * // Create a function
      * const fn = await client.functions.create({
      *   name: 'Process Order',
-         *   code: 'module.exports = async (ctx) => { return { ok: true }; }'
+     *   code: 'async function run() { return { ok: true }; }'
      * });
      *
      * // Test execute without saving
      * const result = await client.functions.testExecute({
-     *   code: 'module.exports = async (ctx) => { return ctx.executionParams; }',
+     *   code: 'async function run() { return executionParams; }',
      *   params: { test: true }
      * });
      * ```
@@ -5248,6 +5429,33 @@ export class CentraliSDK {
         return this._functions;
     }
 
+    /**
+     * Runs namespace for querying execution history.
+     *
+     * Usage:
+     * ```ts
+     * // Get a specific run
+     * const run = await client.runs.get('run-id');
+     *
+     * // List runs for a trigger
+     * const runs = await client.runs.listByTrigger('trigger-id');
+     *
+     * // List failed runs for a compute definition
+     * const failed = await client.runs.listByFunction('fn-id', {
+     *   status: 'failure'
+     * });
+     * ```
+     */
+    public get runs(): FunctionRunsManager {
+        if (!this._runs) {
+            this._runs = new FunctionRunsManager(
+                this.options.workspaceId,
+                this.request.bind(this)
+            );
+        }
+        return this._runs;
+    }
+
     /**
      * Manually set or update the bearer token for subsequent requests.
      */

package/package.json

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