@centrali-io/centrali-sdk 4.4.4 → 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

@@ -2407,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' }
  * });
  * ```
@@ -2464,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
      * });
@@ -2484,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
      * });
      * ```
@@ -2517,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 }
@@ -3014,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 }
      * });
      * ```

package/index.ts

@@ -4712,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' }
  * });
  * ```
@@ -4778,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
      * });
@@ -4799,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
      * });
      * ```
@@ -4834,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 }
@@ -5409,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 }
      * });
      * ```

package/package.json

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