@centrali-io/centrali-sdk 2.0.6 → 2.0.9

package/README.md

@@ -73,6 +73,7 @@ const centrali = new CentraliSDK({
 - ✅ **Automatic authentication** and token management
 - ✅ **Records management** - Create, read, update, delete records
 - ✅ **Query operations** - Powerful data querying with filters and sorting
+- ✅ **Realtime events** - Subscribe to record changes via SSE
 - ✅ **Compute functions** - Execute serverless functions
 - ✅ **File uploads** - Upload files to Centrali storage
 - ✅ **Service accounts** - Automatic token refresh for server-to-server auth
@@ -107,6 +108,104 @@ const products = await centrali.queryRecords('Product', {
 });
 ```
 
+### Realtime Events
+
+Subscribe to record changes in real-time using Server-Sent Events (SSE):
+
+```typescript
+// Subscribe to realtime events
+const subscription = centrali.realtime.subscribe({
+  structures: ['Order'],  // Filter by structure (optional)
+  events: ['record_created', 'record_updated'],  // Filter by event type (optional)
+  filter: 'status = "pending"',  // CFL filter expression (optional)
+
+  onEvent: (event) => {
+    console.log('Event received:', event.event);
+    console.log('Record:', event.recordSlug, event.recordId);
+    console.log('Data:', event.data);
+  },
+
+  onConnected: () => {
+    console.log('Connected to realtime service');
+  },
+
+  onDisconnected: (reason) => {
+    console.log('Disconnected:', reason);
+  },
+
+  onError: (error) => {
+    console.error('Realtime error:', error.code, error.message);
+  }
+});
+
+// Later: cleanup subscription
+subscription.unsubscribe();
+```
+
+#### Initial Sync Pattern
+
+Realtime delivers only **new events** after connection. For dashboards and lists, always:
+
+1. Fetch current records first
+2. Subscribe to realtime
+3. Apply diffs while UI shows the snapshot
+
+```typescript
+// 1. Fetch initial data
+const orders = await centrali.queryRecords('Order', {
+  filter: 'status = "pending"'
+});
+renderOrders(orders.data);
+
+// 2. Subscribe to realtime updates
+const subscription = centrali.realtime.subscribe({
+  structures: ['Order'],
+  events: ['record_created', 'record_updated', 'record_deleted'],
+  filter: 'status = "pending"',
+  onEvent: (event) => {
+    // 3. Apply updates to UI
+    switch (event.event) {
+      case 'record_created':
+        addOrderToUI(event.data);
+        break;
+      case 'record_updated':
+        updateOrderInUI(event.recordId, event.data);
+        break;
+      case 'record_deleted':
+        removeOrderFromUI(event.recordId);
+        break;
+    }
+  }
+});
+```
+
+#### Event Types
+
+| Event | Description |
+|-------|-------------|
+| `record_created` | A new record was created |
+| `record_updated` | An existing record was updated |
+| `record_deleted` | A record was deleted |
+
+#### Reconnection
+
+The SDK automatically reconnects with exponential backoff when connections drop. Configure reconnection behavior:
+
+```typescript
+import { RealtimeManager } from '@centrali-io/centrali-sdk';
+
+const realtime = new RealtimeManager(
+  'https://centrali.io',
+  'your-workspace',
+  () => centrali.getToken(),
+  {
+    maxReconnectAttempts: 10,      // Default: 10
+    initialReconnectDelayMs: 1000, // Default: 1000ms
+    maxReconnectDelayMs: 30000     // Default: 30000ms
+  }
+);
+```
+
 ### Compute Functions
 
 ```typescript

package/dist/index.js

@@ -2,7 +2,7 @@
 /*
  * Centrali TypeScript SDK
  * ----------------------
- * A lightweight SDK for interacting with Centrali's Data and Compute APIs,
+ * A lightweight SDK for interacting with Centrali's Data, Compute, and Realtime APIs,
  * with support for user-provided tokens or client credentials (Client ID/Secret).
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
@@ -18,15 +18,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CentraliSDK = void 0;
+exports.CentraliSDK = exports.TriggersManager = exports.RealtimeManager = void 0;
 exports.getApiUrl = getApiUrl;
 exports.getAuthUrl = getAuthUrl;
+exports.getRealtimeUrl = getRealtimeUrl;
 exports.fetchClientToken = fetchClientToken;
 exports.getRecordApiPath = getRecordApiPath;
 exports.getFileUploadApiPath = getFileUploadApiPath;
-exports.getComputeFunctionTriggerApiPath = getComputeFunctionTriggerApiPath;
+exports.getFunctionTriggersApiPath = getFunctionTriggersApiPath;
+exports.getFunctionTriggerExecuteApiPath = getFunctionTriggerExecuteApiPath;
 const axios_1 = __importDefault(require("axios"));
 const qs_1 = __importDefault(require("qs"));
+const eventsource_1 = require("eventsource");
+// Use native EventSource in browser, polyfill in Node.js
+const EventSourceImpl = typeof EventSource !== 'undefined'
+    ? EventSource
+    : eventsource_1.EventSource;
 // Helper to encode form data
 function encodeFormData(data) {
     return new URLSearchParams(data).toString();
@@ -55,6 +62,230 @@ function getAuthUrl(baseUrl) {
         : url.hostname;
     return `${url.protocol}//auth.${hostname}`;
 }
+/**
+ * Generate the realtime service URL from the base URL.
+ * E.g., https://centrali.io -> https://api.centrali.io/realtime
+ */
+function getRealtimeUrl(baseUrl) {
+    return `${getApiUrl(baseUrl)}/realtime`;
+}
+/**
+ * Generate the SSE endpoint path for a workspace.
+ * Matches: services/backend/realtime/internal/sse/handler.go ServeHTTP route
+ */
+function getRealtimeEventPath(workspaceSlug) {
+    return `/workspace/${workspaceSlug}/events`;
+}
+/**
+ * Default realtime configuration.
+ */
+const DEFAULT_REALTIME_CONFIG = {
+    maxReconnectAttempts: 10,
+    initialReconnectDelayMs: 1000,
+    maxReconnectDelayMs: 30000,
+};
+/**
+ * RealtimeManager handles SSE connections to the Centrali Realtime Service.
+ * Provides automatic reconnection with exponential backoff.
+ *
+ * Usage:
+ * ```ts
+ * const realtime = new RealtimeManager(baseUrl, workspaceSlug, () => client.getToken());
+ * const sub = realtime.subscribe({
+ *   structures: ['order'],
+ *   events: ['record_created', 'record_updated'],
+ *   onEvent: (event) => console.log(event),
+ *   onError: (error) => console.error(error),
+ * });
+ * // Later: sub.unsubscribe();
+ * ```
+ */
+class RealtimeManager {
+    constructor(baseUrl, workspaceSlug, getToken, config) {
+        this.baseUrl = baseUrl;
+        this.workspaceSlug = workspaceSlug;
+        this.getToken = getToken;
+        this.config = Object.assign(Object.assign({}, DEFAULT_REALTIME_CONFIG), config);
+    }
+    /**
+     * Subscribe to realtime events for the workspace.
+     *
+     * IMPORTANT: Initial Sync Pattern
+     * Realtime delivers only new events after connection. For dashboards and lists:
+     * 1. Fetch current records first
+     * 2. Subscribe to realtime
+     * 3. Apply diffs while UI shows the snapshot
+     *
+     * @param options - Subscription options
+     * @returns Subscription handle with unsubscribe() method
+     */
+    subscribe(options) {
+        let eventSource = null;
+        let unsubscribed = false;
+        let connected = false;
+        let reconnectAttempt = 0;
+        let reconnectTimeout = null;
+        const connect = () => __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            // Zombie loop prevention: don't reconnect if unsubscribed
+            if (unsubscribed) {
+                return;
+            }
+            try {
+                // Get token (may be async for client credentials flow)
+                const token = yield Promise.resolve(this.getToken());
+                if (!token) {
+                    (_a = options.onError) === null || _a === void 0 ? void 0 : _a.call(options, {
+                        code: 'MISSING_TOKEN',
+                        message: 'No authentication token available',
+                        recoverable: false,
+                    });
+                    return;
+                }
+                // Build SSE URL with query params
+                const realtimeBaseUrl = getRealtimeUrl(this.baseUrl);
+                const path = getRealtimeEventPath(this.workspaceSlug);
+                const url = new URL(`${realtimeBaseUrl}${path}`);
+                // Add access token
+                url.searchParams.set('access_token', token);
+                // Add structure filter
+                if ((_b = options.structures) === null || _b === void 0 ? void 0 : _b.length) {
+                    url.searchParams.set('structures', options.structures.join(','));
+                }
+                // Add event type filter
+                if ((_c = options.events) === null || _c === void 0 ? void 0 : _c.length) {
+                    url.searchParams.set('events', options.events.join(','));
+                }
+                // Add CFL filter
+                if (options.filter) {
+                    url.searchParams.set('filter', options.filter);
+                }
+                // Create EventSource (uses polyfill in Node.js)
+                eventSource = new EventSourceImpl(url.toString());
+                // Handle connection open
+                eventSource.onopen = () => {
+                    var _a;
+                    if (unsubscribed) {
+                        eventSource === null || eventSource === void 0 ? void 0 : eventSource.close();
+                        return;
+                    }
+                    connected = true;
+                    reconnectAttempt = 0;
+                    (_a = options.onConnected) === null || _a === void 0 ? void 0 : _a.call(options);
+                };
+                // Handle record events - server sends all record events as 'message' type
+                // The event.event field inside the payload contains the actual type
+                // (record_created, record_updated, record_deleted)
+                eventSource.addEventListener('message', (e) => {
+                    var _a;
+                    if (unsubscribed)
+                        return;
+                    try {
+                        const event = JSON.parse(e.data);
+                        options.onEvent(event);
+                    }
+                    catch (err) {
+                        (_a = options.onError) === null || _a === void 0 ? void 0 : _a.call(options, {
+                            code: 'PARSE_ERROR',
+                            message: `Failed to parse event: ${err}`,
+                            recoverable: true,
+                        });
+                    }
+                });
+                // Handle close event from server
+                eventSource.addEventListener('close', (e) => {
+                    var _a;
+                    if (unsubscribed)
+                        return;
+                    try {
+                        const closeEvent = JSON.parse(e.data);
+                        connected = false;
+                        (_a = options.onDisconnected) === null || _a === void 0 ? void 0 : _a.call(options, closeEvent.reason);
+                        // Reconnect if server says to
+                        if (closeEvent.reconnect && !unsubscribed) {
+                            scheduleReconnect();
+                        }
+                    }
+                    catch (_b) {
+                        // Ignore parse errors for close events
+                    }
+                });
+                // Handle errors
+                eventSource.onerror = () => {
+                    var _a, _b;
+                    if (unsubscribed) {
+                        eventSource === null || eventSource === void 0 ? void 0 : eventSource.close();
+                        return;
+                    }
+                    connected = false;
+                    eventSource === null || eventSource === void 0 ? void 0 : eventSource.close();
+                    eventSource = null;
+                    // EventSource error events don't provide much detail
+                    // The connection will be closed, so we notify and potentially reconnect
+                    (_a = options.onDisconnected) === null || _a === void 0 ? void 0 : _a.call(options, 'connection_error');
+                    (_b = options.onError) === null || _b === void 0 ? void 0 : _b.call(options, {
+                        code: 'CONNECTION_ERROR',
+                        message: 'Connection to realtime service failed',
+                        recoverable: true,
+                    });
+                    scheduleReconnect();
+                };
+            }
+            catch (err) {
+                (_d = options.onError) === null || _d === void 0 ? void 0 : _d.call(options, {
+                    code: 'CONNECTION_ERROR',
+                    message: `Failed to connect: ${err}`,
+                    recoverable: true,
+                });
+                scheduleReconnect();
+            }
+        });
+        const scheduleReconnect = () => {
+            var _a;
+            // Zombie loop prevention
+            if (unsubscribed)
+                return;
+            reconnectAttempt++;
+            if (reconnectAttempt > this.config.maxReconnectAttempts) {
+                (_a = options.onError) === null || _a === void 0 ? void 0 : _a.call(options, {
+                    code: 'CONNECTION_ERROR',
+                    message: `Max reconnection attempts (${this.config.maxReconnectAttempts}) exceeded`,
+                    recoverable: false,
+                });
+                return;
+            }
+            // Exponential backoff with jitter
+            const delay = Math.min(this.config.initialReconnectDelayMs * Math.pow(2, reconnectAttempt - 1), this.config.maxReconnectDelayMs);
+            const jitter = Math.random() * 0.3 * delay; // 0-30% jitter
+            reconnectTimeout = setTimeout(() => {
+                if (!unsubscribed) {
+                    connect();
+                }
+            }, delay + jitter);
+        };
+        // Start connection
+        connect();
+        // Return subscription handle
+        return {
+            unsubscribe: () => {
+                unsubscribed = true;
+                connected = false;
+                if (reconnectTimeout) {
+                    clearTimeout(reconnectTimeout);
+                    reconnectTimeout = null;
+                }
+                if (eventSource) {
+                    eventSource.close();
+                    eventSource = null;
+                }
+            },
+            get connected() {
+                return connected;
+            },
+        };
+    }
+}
+exports.RealtimeManager = RealtimeManager;
 /**
  * Retrieve an access token using the Client Credentials flow.
  */
@@ -88,18 +319,139 @@ function getRecordApiPath(workspaceId, recordSlug, id) {
 function getFileUploadApiPath(workspaceId) {
     return `storage/ws/${workspaceId}/api/v1/files`;
 }
-/*
-* Generate Compute Function Trigger API URL PATH.
+/**
+ * Generate Function Triggers base API URL PATH.
+ */
+function getFunctionTriggersApiPath(workspaceId, triggerId) {
+    const basePath = `data/workspace/${workspaceId}/api/v1/function-triggers`;
+    return triggerId ? `${basePath}/${triggerId}` : basePath;
+}
+/**
+ * Generate Function Trigger execute API URL PATH.
+ */
+function getFunctionTriggerExecuteApiPath(workspaceId, triggerId) {
+    return `data/workspace/${workspaceId}/api/v1/function-triggers/${triggerId}/execute`;
+}
+// =====================================================
+// Triggers Manager
+// =====================================================
+/**
+ * TriggersManager provides methods for working with on-demand function triggers.
+ * Access via `client.triggers`.
+ *
+ * Note: This manager only works with on-demand triggers. Scheduled, event-driven,
+ * and webhook triggers are managed through other mechanisms.
+ *
+ * Usage:
+ * ```ts
+ * // Invoke an on-demand trigger
+ * const result = await client.triggers.invoke('trigger-id');
+ *
+ * // Invoke with custom payload
+ * const result = await client.triggers.invoke('trigger-id', {
+ *   payload: { customData: 'value' }
+ * });
+ *
+ * // Get an on-demand trigger by ID
+ * const trigger = await client.triggers.get('trigger-id');
+ *
+ * // List all on-demand triggers
+ * const triggers = await client.triggers.list();
+ * ```
  */
-function getComputeFunctionTriggerApiPath(workspaceId, functionId) {
-    return `data/workspace/${workspaceId}/api/v1/function-triggers/${functionId}/execute`;
+class TriggersManager {
+    constructor(workspaceId, requestFn) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+    }
+    /**
+     * Invoke an on-demand trigger by ID.
+     *
+     * @param triggerId - The ID of the trigger to invoke
+     * @param options - Optional invoke options including custom payload
+     * @returns The queued job ID for tracking the execution
+     *
+     * @example
+     * ```ts
+     * // Simple invocation
+     * const job = await client.triggers.invoke('trigger-id');
+     * console.log('Job queued:', job.data);
+     *
+     * // With custom payload
+     * const job = await client.triggers.invoke('trigger-id', {
+     *   payload: { orderId: '12345', action: 'process' }
+     * });
+     * ```
+     */
+    invoke(triggerId, options) {
+        var _a;
+        const path = getFunctionTriggerExecuteApiPath(this.workspaceId, triggerId);
+        const data = (_a = options === null || options === void 0 ? void 0 : options.payload) !== null && _a !== void 0 ? _a : {};
+        return this.requestFn('POST', path, data);
+    }
+    /**
+     * Get an on-demand trigger by ID.
+     *
+     * Note: This method validates that the trigger is an on-demand trigger.
+     * If the trigger exists but is not on-demand, an error will be thrown.
+     *
+     * @param triggerId - The ID of the on-demand trigger to retrieve
+     * @returns The trigger details
+     * @throws Error if the trigger is not an on-demand trigger
+     *
+     * @example
+     * ```ts
+     * const trigger = await client.triggers.get('trigger-id');
+     * console.log('Trigger name:', trigger.data.name);
+     * ```
+     */
+    get(triggerId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const path = getFunctionTriggersApiPath(this.workspaceId, triggerId);
+            const response = yield this.requestFn('GET', path);
+            // Validate that the trigger is on-demand
+            if (response.data && response.data.executionType !== 'on-demand') {
+                throw new Error(`Trigger '${triggerId}' is not an on-demand trigger. Only on-demand triggers can be invoked via the SDK.`);
+            }
+            return response;
+        });
+    }
+    /**
+     * List all on-demand triggers in the workspace.
+     *
+     * This method automatically filters to only return triggers with executionType 'on-demand'.
+     *
+     * @param queryParams - Optional query parameters for pagination, search, etc.
+     * @returns List of on-demand triggers with pagination metadata
+     *
+     * @example
+     * ```ts
+     * // List all on-demand triggers
+     * const triggers = await client.triggers.list();
+     *
+     * // With pagination
+     * const triggers = await client.triggers.list({ limit: 10, page: 1 });
+     *
+     * // With search
+     * const triggers = await client.triggers.list({ search: 'process-order' });
+     * ```
+     */
+    list(queryParams) {
+        const path = getFunctionTriggersApiPath(this.workspaceId);
+        // Always filter for on-demand triggers only
+        const params = Object.assign(Object.assign({}, queryParams), { executionType: 'on-demand' });
+        return this.requestFn('GET', path, null, params);
+    }
 }
+exports.TriggersManager = TriggersManager;
 /**
  * Main Centrali SDK client.
  */
 class CentraliSDK {
     constructor(options) {
         this.token = null;
+        this._realtime = null;
+        this._triggers = null;
         this.options = options;
         this.token = options.token || null;
         const apiUrl = getApiUrl(options.baseUrl);
@@ -115,6 +467,69 @@ class CentraliSDK {
             return config;
         }), (error) => Promise.reject(error));
     }
+    /**
+     * Realtime namespace for subscribing to SSE events.
+     *
+     * Usage:
+     * ```ts
+     * const sub = client.realtime.subscribe({
+     *   structures: ['order'],
+     *   events: ['record_created', 'record_updated'],
+     *   onEvent: (event) => console.log(event),
+     * });
+     * // Later: sub.unsubscribe();
+     * ```
+     *
+     * IMPORTANT: Initial Sync Pattern
+     * Realtime delivers only new events after connection. For dashboards and lists:
+     * 1. Fetch current records first
+     * 2. Subscribe to realtime
+     * 3. Apply diffs while UI shows the snapshot
+     */
+    get realtime() {
+        if (!this._realtime) {
+            this._realtime = new RealtimeManager(this.options.baseUrl, this.options.workspaceId, () => __awaiter(this, void 0, void 0, function* () {
+                // If token exists, return it
+                if (this.token) {
+                    return this.token;
+                }
+                // For client-credentials flow, fetch token if not available
+                if (this.options.clientId && this.options.clientSecret) {
+                    this.token = yield fetchClientToken(this.options.clientId, this.options.clientSecret, this.options.baseUrl);
+                    return this.token;
+                }
+                // No token and no credentials
+                return null;
+            }));
+        }
+        return this._realtime;
+    }
+    /**
+     * Triggers namespace for invoking and managing function triggers.
+     *
+     * Usage:
+     * ```ts
+     * // Invoke an on-demand trigger
+     * const job = await client.triggers.invoke('trigger-id');
+     *
+     * // Invoke with custom payload
+     * const job = await client.triggers.invoke('trigger-id', {
+     *   payload: { orderId: '12345' }
+     * });
+     *
+     * // Get trigger details
+     * const trigger = await client.triggers.get('trigger-id');
+     *
+     * // List all triggers
+     * const triggers = await client.triggers.list();
+     * ```
+     */
+    get triggers() {
+        if (!this._triggers) {
+            this._triggers = new TriggersManager(this.options.workspaceId, this.request.bind(this));
+        }
+        return this._triggers;
+    }
     /**
      * Manually set or update the bearer token for subsequent requests.
      */
@@ -181,12 +596,6 @@ class CentraliSDK {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug, id);
         return this.request('DELETE', path);
     }
-    // ------------------ Compute API Methods ------------------
-    /** Invoke a compute function by name with given payload. */
-    invokeFunction(functionId, payload) {
-        const path = getComputeFunctionTriggerApiPath(this.options.workspaceId, functionId);
-        return this.request('POST', path, { data: payload });
-    }
     // ------------------ Storage API Methods ------------------
     /** Upload a file to the storage service. */
     uploadFile(file_1, location_1) {
@@ -215,6 +624,7 @@ exports.CentraliSDK = CentraliSDK;
  *
  * const options: CentraliSDKOptions = {
  *   baseUrl: 'https://centrali.io',
+ *   workspaceId: 'my-workspace',
  *   clientId: process.env.CLIENT_ID,
  *   clientSecret: process.env.CLIENT_SECRET,
  * };
@@ -226,5 +636,43 @@ exports.CentraliSDK = CentraliSDK;
  * // Or set a user token:
  * client.setToken('<JWT_TOKEN>');
  * await client.queryRecords('Product', { limit: 10 });
+ *
+ * // Subscribe to realtime events (Initial Sync Pattern):
+ * // 1. First fetch initial data
+ * const orders = await client.queryRecords('Order', { filter: 'status = "pending"' });
+ * setOrders(orders.data);
+ *
+ * // 2. Then subscribe to realtime updates
+ * const subscription = client.realtime.subscribe({
+ *   structures: ['Order'],
+ *   events: ['record_created', 'record_updated', 'record_deleted'],
+ *   onEvent: (event) => {
+ *     // 3. Apply updates to UI
+ *     console.log('Event:', event.event, event.recordSlug, event.recordId);
+ *   },
+ *   onError: (error) => console.error('Realtime error:', error),
+ *   onConnected: () => console.log('Connected'),
+ *   onDisconnected: (reason) => console.log('Disconnected:', reason),
+ * });
+ *
+ * // Cleanup when done
+ * subscription.unsubscribe();
+ *
+ * // Invoke an on-demand trigger:
+ * const job = await client.triggers.invoke('trigger-id');
+ * console.log('Job queued:', job.data);
+ *
+ * // Invoke trigger with custom payload:
+ * const job2 = await client.triggers.invoke('trigger-id', {
+ *   payload: { orderId: '12345', action: 'process' }
+ * });
+ *
+ * // Get trigger details:
+ * const trigger = await client.triggers.get('trigger-id');
+ * console.log('Trigger:', trigger.data.name, trigger.data.executionType);
+ *
+ * // List all triggers:
+ * const triggers = await client.triggers.list();
+ * triggers.data.forEach(t => console.log(t.name));
  *```
  */