@centrali-io/centrali-sdk 4.4.4 → 4.4.6

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

@@ -87,6 +87,7 @@ exports.getComputeFunctionTestApiPath = getComputeFunctionTestApiPath;
 exports.getFunctionRunsApiPath = getFunctionRunsApiPath;
 exports.getFunctionRunsByTriggerApiPath = getFunctionRunsByTriggerApiPath;
 exports.getFunctionRunsByFunctionApiPath = getFunctionRunsByFunctionApiPath;
+exports.getComputeJobStatusApiPath = getComputeJobStatusApiPath;
 exports.getSmartQueryTestApiPath = getSmartQueryTestApiPath;
 exports.getValidationSuggestionsApiPath = getValidationSuggestionsApiPath;
 exports.getValidationSuggestionAcceptApiPath = getValidationSuggestionAcceptApiPath;
@@ -681,6 +682,15 @@ function getFunctionRunsByFunctionApiPath(workspaceId, functionId) {
     return `data/workspace/${workspaceId}/api/v1/function-runs/function/${functionId}`;
 }
 // =====================================================
+// Compute Job Status API Path Helper
+// =====================================================
+/**
+ * Generate Compute Job Status API URL PATH.
+ */
+function getComputeJobStatusApiPath(workspaceId, jobId) {
+    return `data/workspace/${workspaceId}/api/v1/jobs/compute/${jobId}`;
+}
+// =====================================================
 // Smart Query Test API Path Helper (Configuration-as-Code)
 // =====================================================
 /**
@@ -2407,12 +2417,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' }
  * });
  * ```
@@ -2464,7 +2474,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
      * });
@@ -2484,7 +2494,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
      * });
      * ```
@@ -2517,7 +2527,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 }
@@ -2619,6 +2629,38 @@ class FunctionRunsManager {
             queryParams.status = options.status;
         return this.requestFn('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.runs.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);
+     * }
+     * ```
+     */
+    getJobStatus(jobId) {
+        const path = getComputeJobStatusApiPath(this.workspaceId, jobId);
+        return this.requestFn('GET', path);
+    }
 }
 exports.FunctionRunsManager = FunctionRunsManager;
 /**
@@ -3014,12 +3056,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 }
      * });
      * ```

package/index.ts

@@ -1840,6 +1840,22 @@ export interface ListFunctionRunsOptions {
     status?: FunctionRunStatus;
 }
 
+/**
+ * Status of a compute job in the execution pipeline.
+ */
+export type ComputeJobStatus = 'queued' | 'running' | 'completed' | 'failed';
+
+/**
+ * A compute job status response from the job status endpoint.
+ * Represents the state of an async compute execution.
+ */
+export interface ComputeJobStatusResponse {
+    jobId: string;
+    status: ComputeJobStatus;
+    returnValue?: any;
+    failedReason?: string | null;
+}
+
 // =====================================================
 // Trigger CRUD Types (Configuration-as-Code)
 // =====================================================
@@ -2820,6 +2836,17 @@ export function getFunctionRunsByFunctionApiPath(workspaceId: string, functionId
     return `data/workspace/${workspaceId}/api/v1/function-runs/function/${functionId}`;
 }
 
+// =====================================================
+// Compute Job Status API Path Helper
+// =====================================================
+
+/**
+ * Generate Compute Job Status API URL PATH.
+ */
+export function getComputeJobStatusApiPath(workspaceId: string, jobId: string): string {
+    return `data/workspace/${workspaceId}/api/v1/jobs/compute/${jobId}`;
+}
+
 // =====================================================
 // Smart Query Test API Path Helper (Configuration-as-Code)
 // =====================================================
@@ -4712,12 +4739,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' }
  * });
  * ```
@@ -4778,7 +4805,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
      * });
@@ -4799,7 +4826,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
      * });
      * ```
@@ -4834,7 +4861,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 }
@@ -4939,6 +4966,39 @@ export class FunctionRunsManager {
         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.runs.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);
+    }
 }
 
 /**
@@ -5409,12 +5469,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 }
      * });
      * ```

package/package.json

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