@centrali-io/centrali-sdk 2.0.5 → 2.0.8

package/index.ts

@@ -1,12 +1,123 @@
 /*
  * 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).
  */
 
 import axios, {AxiosInstance, AxiosRequestConfig, AxiosRequestHeaders, AxiosResponse, Method} from 'axios';
 import qs from 'qs';
+import {EventSource as EventSourcePolyfill} from 'eventsource';
+
+// Use native EventSource in browser, polyfill in Node.js
+const EventSourceImpl: typeof EventSource = typeof EventSource !== 'undefined'
+    ? EventSource
+    : EventSourcePolyfill as unknown as typeof EventSource;
+
+// =====================================================
+// Realtime Types
+// =====================================================
+
+/**
+ * Event types emitted by the realtime service.
+ * Matches: services/backend/realtime/internal/redis/message.go
+ */
+export type RealtimeEventType = 'record_created' | 'record_updated' | 'record_deleted';
+
+/**
+ * Record event payload from the realtime service.
+ * Matches: services/backend/realtime/internal/redis/message.go RecordEvent
+ */
+export interface RealtimeRecordEvent {
+    /** Event type */
+    event: RealtimeEventType;
+    /** Workspace slug where the event occurred */
+    workspaceSlug: string;
+    /** Structure's record slug (e.g., "order") */
+    recordSlug: string;
+    /** Record ID */
+    recordId: string;
+    /** Record data. For updates, contains "before" and "after" fields */
+    data?: Record<string, unknown>;
+    /** ISO timestamp when the event occurred */
+    timestamp: string;
+    /** User who created the record (for create events) */
+    createdBy?: string;
+    /** User who updated the record (for update events) */
+    updatedBy?: string;
+    /** User who deleted the record (for delete events) */
+    deletedBy?: string;
+}
+
+/**
+ * Close event payload from the realtime service.
+ */
+export interface RealtimeCloseEvent {
+    /** Reason for the close */
+    reason: string;
+    /** Whether the client should attempt to reconnect */
+    reconnect: boolean;
+}
+
+/**
+ * Union type of all realtime events.
+ */
+export type RealtimeEvent = RealtimeRecordEvent;
+
+/**
+ * Error object for realtime connection errors.
+ */
+export interface RealtimeError {
+    /** Error code from the server */
+    code: 'MISSING_TOKEN' | 'TOKEN_EXPIRED' | 'WORKSPACE_MISMATCH' | 'INVALID_TOKEN' | 'FORBIDDEN' | 'AUTH_ERROR' | 'RATE_LIMIT_EXCEEDED' | 'CONNECTION_ERROR' | 'PARSE_ERROR';
+    /** Human-readable error message */
+    message: string;
+    /** Whether the error is recoverable (client should retry) */
+    recoverable: boolean;
+}
+
+/**
+ * Options for subscribing to realtime events.
+ */
+export interface RealtimeSubscribeOptions {
+    /** Structure recordSlugs to filter events (e.g., ["order", "customer"]). Empty = all structures */
+    structures?: string[];
+    /** Event types to filter (e.g., ["record_created"]). Empty = all events */
+    events?: RealtimeEventType[];
+    /** CFL (Centrali Filter Language) expression for data filtering (e.g., "status = 'active'") */
+    filter?: string;
+    /** Callback for record events */
+    onEvent: (event: RealtimeEvent) => void;
+    /** Callback for errors */
+    onError?: (error: RealtimeError) => void;
+    /** Callback when connected */
+    onConnected?: () => void;
+    /** Callback when disconnected */
+    onDisconnected?: (reason?: string) => void;
+}
+
+/**
+ * Realtime subscription handle returned by subscribe().
+ */
+export interface RealtimeSubscription {
+    /** Unsubscribe and close the connection */
+    unsubscribe: () => void;
+    /** Whether the connection is currently open */
+    readonly connected: boolean;
+}
+
+/**
+ * Internal configuration for realtime connections.
+ */
+interface RealtimeConfig {
+    /** Maximum reconnection attempts (default: 10) */
+    maxReconnectAttempts: number;
+    /** Initial reconnect delay in ms (default: 1000) */
+    initialReconnectDelayMs: number;
+    /** Maximum reconnect delay in ms (default: 30000) */
+    maxReconnectDelayMs: number;
+}
+
 // Helper to encode form data
 function encodeFormData(data: Record<string, string>): string {
     return new URLSearchParams(data).toString();
@@ -40,6 +151,47 @@ export interface ApiResponse<T> {
     updatedAt?: string;
 }
 
+// =====================================================
+// Trigger Types
+// =====================================================
+
+/**
+ * Trigger execution types supported by Centrali.
+ */
+export type TriggerExecutionType = 'on-demand' | 'event-driven' | 'scheduled' | 'webhook';
+
+/**
+ * Function trigger definition.
+ */
+export interface FunctionTrigger {
+    id: string;
+    name: string;
+    description?: string;
+    workspaceSlug: string;
+    functionId: string;
+    executionType: TriggerExecutionType;
+    triggerMetadata: Record<string, any>;
+    schedulerJobId?: string;
+    createdBy: string;
+    updatedBy: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+
+/**
+ * Options for invoking an on-demand trigger.
+ */
+export interface InvokeTriggerOptions {
+    /** Custom payload/parameters to pass to the trigger execution */
+    payload?: Record<string, any>;
+}
+
+/**
+ * Response from invoking a trigger.
+ * Currently the API returns the queued job ID as a string.
+ */
+export type TriggerInvokeResponse = string;
+
 
 
 /**
@@ -68,6 +220,258 @@ export function getAuthUrl(baseUrl: string): string {
     return `${url.protocol}//auth.${hostname}`;
 }
 
+/**
+ * Generate the realtime service URL from the base URL.
+ * E.g., https://centrali.io -> https://api.centrali.io/realtime
+ */
+export function getRealtimeUrl(baseUrl: string): string {
+    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: string): string {
+    return `/workspace/${workspaceSlug}/events`;
+}
+
+/**
+ * Default realtime configuration.
+ */
+const DEFAULT_REALTIME_CONFIG: RealtimeConfig = {
+    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();
+ * ```
+ */
+export class RealtimeManager {
+    private baseUrl: string;
+    private workspaceSlug: string;
+    private getToken: () => string | null | Promise<string | null>;
+    private config: RealtimeConfig;
+
+    constructor(
+        baseUrl: string,
+        workspaceSlug: string,
+        getToken: () => string | null | Promise<string | null>,
+        config?: Partial<RealtimeConfig>
+    ) {
+        this.baseUrl = baseUrl;
+        this.workspaceSlug = workspaceSlug;
+        this.getToken = getToken;
+        this.config = { ...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
+     */
+    public subscribe(options: RealtimeSubscribeOptions): RealtimeSubscription {
+        let eventSource: EventSource | null = null;
+        let unsubscribed = false;
+        let connected = false;
+        let reconnectAttempt = 0;
+        let reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
+
+        const connect = async () => {
+            // Zombie loop prevention: don't reconnect if unsubscribed
+            if (unsubscribed) {
+                return;
+            }
+
+            try {
+                // Get token (may be async for client credentials flow)
+                const token = await Promise.resolve(this.getToken());
+                if (!token) {
+                    options.onError?.({
+                        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 (options.structures?.length) {
+                    url.searchParams.set('structures', options.structures.join(','));
+                }
+
+                // Add event type filter
+                if (options.events?.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 = () => {
+                    if (unsubscribed) {
+                        eventSource?.close();
+                        return;
+                    }
+                    connected = true;
+                    reconnectAttempt = 0;
+                    options.onConnected?.();
+                };
+
+                // 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: MessageEvent) => {
+                    if (unsubscribed) return;
+                    try {
+                        const event = JSON.parse(e.data) as RealtimeRecordEvent;
+                        options.onEvent(event);
+                    } catch (err) {
+                        options.onError?.({
+                            code: 'PARSE_ERROR',
+                            message: `Failed to parse event: ${err}`,
+                            recoverable: true,
+                        });
+                    }
+                });
+
+                // Handle close event from server
+                eventSource.addEventListener('close', (e: MessageEvent) => {
+                    if (unsubscribed) return;
+                    try {
+                        const closeEvent = JSON.parse(e.data) as RealtimeCloseEvent;
+                        connected = false;
+                        options.onDisconnected?.(closeEvent.reason);
+
+                        // Reconnect if server says to
+                        if (closeEvent.reconnect && !unsubscribed) {
+                            scheduleReconnect();
+                        }
+                    } catch {
+                        // Ignore parse errors for close events
+                    }
+                });
+
+                // Handle errors
+                eventSource.onerror = () => {
+                    if (unsubscribed) {
+                        eventSource?.close();
+                        return;
+                    }
+
+                    connected = false;
+                    eventSource?.close();
+                    eventSource = null;
+
+                    // EventSource error events don't provide much detail
+                    // The connection will be closed, so we notify and potentially reconnect
+                    options.onDisconnected?.('connection_error');
+                    options.onError?.({
+                        code: 'CONNECTION_ERROR',
+                        message: 'Connection to realtime service failed',
+                        recoverable: true,
+                    });
+
+                    scheduleReconnect();
+                };
+
+            } catch (err) {
+                options.onError?.({
+                    code: 'CONNECTION_ERROR',
+                    message: `Failed to connect: ${err}`,
+                    recoverable: true,
+                });
+                scheduleReconnect();
+            }
+        };
+
+        const scheduleReconnect = () => {
+            // Zombie loop prevention
+            if (unsubscribed) return;
+
+            reconnectAttempt++;
+            if (reconnectAttempt > this.config.maxReconnectAttempts) {
+                options.onError?.({
+                    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;
+            },
+        };
+    }
+}
+
 /**
  * Retrieve an access token using the Client Credentials flow.
  */
@@ -113,11 +517,146 @@ export function getFileUploadApiPath(workspaceId: string): string {
     return `storage/ws/${workspaceId}/api/v1/files`;
 }
 
-/*
-* Generate Compute Function Trigger API URL PATH.
+/**
+ * Generate Function Triggers base API URL PATH.
+ */
+export function getFunctionTriggersApiPath(workspaceId: string, triggerId?: string): string {
+    const basePath = `data/workspace/${workspaceId}/api/v1/function-triggers`;
+    return triggerId ? `${basePath}/${triggerId}` : basePath;
+}
+
+/**
+ * Generate Function Trigger execute API URL PATH.
+ */
+export function getFunctionTriggerExecuteApiPath(workspaceId: string, triggerId: string): string {
+    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();
+ * ```
  */
-export function getComputeFunctionTriggerApiPath(workspaceId: string, functionId: string): string {
-    return `data/workspace/${workspaceId}/api/v1/function-triggers/${functionId}/execute`;
+export class TriggersManager {
+    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;
+    }
+
+    /**
+     * 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' }
+     * });
+     * ```
+     */
+    public invoke(
+        triggerId: string,
+        options?: InvokeTriggerOptions
+    ): Promise<ApiResponse<TriggerInvokeResponse>> {
+        const path = getFunctionTriggerExecuteApiPath(this.workspaceId, triggerId);
+        const data = options?.payload ?? {};
+        return this.requestFn<TriggerInvokeResponse>('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);
+     * ```
+     */
+    public async get(triggerId: string): Promise<ApiResponse<FunctionTrigger>> {
+        const path = getFunctionTriggersApiPath(this.workspaceId, triggerId);
+        const response = await this.requestFn<FunctionTrigger>('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' });
+     * ```
+     */
+    public list(queryParams?: Record<string, any>): Promise<ApiResponse<FunctionTrigger[]>> {
+        const path = getFunctionTriggersApiPath(this.workspaceId);
+        // Always filter for on-demand triggers only
+        const params = {
+            ...queryParams,
+            executionType: 'on-demand'
+        };
+        return this.requestFn<FunctionTrigger[]>('GET', path, null, params);
+    }
 }
 
 /**
@@ -127,6 +666,8 @@ export class CentraliSDK {
     private axios: AxiosInstance;
     private token: string | null = null;
     private options: CentraliSDKOptions;
+    private _realtime: RealtimeManager | null = null;
+    private _triggers: TriggersManager | null = null;
 
     constructor(options: CentraliSDKOptions) {
         this.options = options;
@@ -159,6 +700,82 @@ export class CentraliSDK {
         );
     }
 
+    /**
+     * 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
+     */
+    public get realtime(): RealtimeManager {
+        if (!this._realtime) {
+            this._realtime = new RealtimeManager(
+                this.options.baseUrl,
+                this.options.workspaceId,
+                async () => {
+                    // 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 = await 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();
+     * ```
+     */
+    public get triggers(): TriggersManager {
+        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.
      */
@@ -271,18 +888,6 @@ export class CentraliSDK {
         return this.request('DELETE', path);
     }
 
-    // ------------------ Compute API Methods ------------------
-
-    /** Invoke a compute function by name with given payload. */
-    public invokeFunction<T = any>(
-        functionId: string,
-        payload: Record<string, any>
-    ): Promise<ApiResponse<T>> {
-        const path = getComputeFunctionTriggerApiPath(this.options.workspaceId, functionId);
-        return this.request('POST', path, { data: payload });
-    }
-
-
 
 
     // ------------------ Storage API Methods ------------------
@@ -319,6 +924,7 @@ export class CentraliSDK {
  *
  * const options: CentraliSDKOptions = {
  *   baseUrl: 'https://centrali.io',
+ *   workspaceId: 'my-workspace',
  *   clientId: process.env.CLIENT_ID,
  *   clientSecret: process.env.CLIENT_SECRET,
  * };
@@ -330,5 +936,43 @@ export class 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));
  *```
  */