@centrali-io/centrali-sdk 5.5.1 → 6.0.0

package/src/realtime/manager.ts

@@ -0,0 +1,292 @@
+import { EventSource as EventSourcePolyfill } from 'eventsource';
+import { getRealtimeUrl } from '../urls';
+import { emitDeprecationWarning } from '../internal/deprecation';
+import type {
+    RealtimeSubscribeOptions,
+    RealtimeSubscription,
+    RealtimeRecordEvent,
+    RealtimeCloseEvent,
+} from '../types/realtime';
+
+// Use native EventSource in browser, polyfill in Node.js
+const EventSourceImpl: typeof EventSource = typeof EventSource !== 'undefined'
+    ? EventSource
+    : EventSourcePolyfill as unknown as typeof EventSource;
+
+/**
+ * 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`;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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 collection filter
+                if (options.collections?.length) {
+                    url.searchParams.set('collections', options.collections.join(','));
+                } else if (options.structures?.length) {
+                    emitDeprecationWarning("The 'structures' filter option is deprecated. Use 'collections' instead.");
+                    url.searchParams.set('collections', 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);
+                }
+
+                // Add compute function filters
+                if (options.jobId) {
+                    url.searchParams.set('jobId', options.jobId);
+                }
+                if (options.triggerType) {
+                    url.searchParams.set('triggerType', options.triggerType);
+                }
+                if (options.functionId) {
+                    url.searchParams.set('functionId', options.functionId);
+                }
+
+                // Add orchestration filters
+                if (options.orchestrationId) {
+                    url.searchParams.set('orchestrationId', options.orchestrationId);
+                }
+                if (options.runId) {
+                    url.searchParams.set('runId', options.runId);
+                }
+
+                // 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;
+            },
+        };
+    }
+}

package/src/types/allowedDomains.ts

@@ -0,0 +1,29 @@
+// =====================================================
+// Allowed Domains Types
+// =====================================================
+
+/**
+ * An allowed domain entry for compute function external calls.
+ */
+export interface AllowedDomain {
+    id: string;
+    domain: string;
+    createdAt: string;
+    createdBy: string;
+}
+
+/**
+ * Response from listing allowed domains.
+ */
+export interface AllowedDomainsListResponse {
+    data: AllowedDomain[];
+    meta: { total: number };
+}
+
+/**
+ * Options for adding an allowed domain.
+ */
+export interface AddAllowedDomainOptions {
+    /** The domain to allow (e.g., 'api.example.com'). No protocol prefix. */
+    domain: string;
+}

package/src/types/auth.ts

@@ -0,0 +1,83 @@
+// =====================================================
+// Authorization Types (BYOT - Bring Your Own Token)
+// =====================================================
+
+/**
+ * Resource category for authorization.
+ * - 'workspace': Workspace-level resources (e.g., settings, members)
+ * - 'structure': Structure-level resources (e.g., specific records)
+ * - 'custom': Custom resources defined by the user for AuthZ-as-a-Service
+ */
+export type ResourceCategory = 'workspace' | 'structure' | 'custom';
+
+/**
+ * Options for authorization check.
+ * Use this when authorizing access using an external IdP token (BYOT).
+ */
+export interface CheckAuthorizationOptions {
+    /**
+     * The JWT token from your external identity provider (e.g., Clerk, Auth0, Okta).
+     * The token will be validated against the configured external auth provider.
+     */
+    token: string;
+
+    /**
+     * The resource being accessed.
+     * Can be a Centrali system resource (e.g., 'records', 'files') or a custom
+     * resource you've defined for AuthZ-as-a-Service (e.g., 'orders', 'invoices').
+     */
+    resource: string;
+
+    /**
+     * The action being performed on the resource.
+     * Common actions: 'create', 'read', 'update', 'delete', 'admin'
+     * You can also define custom actions (e.g., 'approve', 'publish').
+     */
+    action: string;
+
+    /**
+     * Resource category for authorization evaluation.
+     * - 'workspace': Workspace-level resources
+     * - 'structure': Structure-level resources
+     * - 'custom': Custom resources for AuthZ-as-a-Service
+     * @default 'custom'
+     */
+    resourceCategory?: ResourceCategory;
+
+    /**
+     * Optional context data for policy evaluation.
+     * This data becomes available as `request_metadata` in policies.
+     *
+     * @example
+     * // Policy can reference: request_metadata.orderId, request_metadata.amount
+     * context: {
+     *   orderId: 'order-123',
+     *   amount: 50000,
+     *   department: 'sales'
+     * }
+     */
+    context?: Record<string, unknown>;
+}
+
+/**
+ * Result of an authorization check.
+ */
+export interface AuthorizationResult {
+    /**
+     * Whether the action is allowed.
+     */
+    allowed: boolean;
+
+    /**
+     * The decision from the policy evaluator.
+     * - 'allow': Access granted
+     * - 'deny': Access denied
+     * - 'not_applicable': No matching policy found
+     */
+    decision: 'allow' | 'deny' | 'not_applicable';
+
+    /**
+     * Human-readable message explaining the decision.
+     */
+    message?: string;
+}

package/src/types/common.ts

@@ -0,0 +1,57 @@
+import type { AxiosRequestConfig } from 'axios';
+
+/**
+ * Options for initializing the Centrali SDK client.
+ */
+export interface CentraliSDKOptions {
+    /** Base URL of Centrali (e.g. https://centrali.io). The SDK automatically uses api.centrali.io for API calls. */
+    baseUrl: string;
+    workspaceId: string;
+
+    // Auth path 1: Publishable key (frontend apps — safe to expose in browser code)
+    /** Publishable key for frontend access. Sent as x-api-key header. No token refresh needed. */
+    publishableKey?: string;
+
+    // Auth path 2: Bearer token (existing) + dynamic token callback (new)
+    /** Optional initial bearer token for authentication */
+    token?: string;
+    /** Optional callback to dynamically fetch a fresh token before each request (e.g., for Clerk, Auth0) */
+    getToken?: () => Promise<string>;
+
+    // Auth path 3: Service account (server-side only — never use in browser)
+    /** Optional OAuth2 client credentials */
+    clientId?: string;
+    clientSecret?: string;
+
+    /** Optional custom axios config */
+    axiosConfig?: AxiosRequestConfig;
+}
+
+/**
+ * Generic API response wrapper.
+ */
+export interface ApiResponse<T> {
+    data: T;
+    meta?: Record<string, any>;
+    error?: any
+    id?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+
+/**
+ * Paginated API response wrapper.
+ */
+export interface PaginatedResponse<T> {
+    /** Data items */
+    data: T[];
+    /** Pagination metadata */
+    meta: {
+        /** Total number of items */
+        total: number;
+        /** Current page number */
+        page: number;
+        /** Items per page */
+        pageSize: number;
+    };
+}

package/src/types/compute.ts

@@ -0,0 +1,145 @@
+// =====================================================
+// Compute Function Types (Configuration-as-Code)
+// =====================================================
+
+/**
+ * Compute function definition.
+ */
+export interface ComputeFunction {
+    id: string;
+    name: string;
+    code: string;
+    description?: string;
+    workspaceSlug: string;
+    createdBy: string;
+    updatedBy?: string;
+    timeoutMs?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * Input for creating a new compute function.
+ */
+export interface CreateComputeFunctionInput {
+    name: string;
+    code: string;
+    description?: string;
+    timeoutMs?: number;
+}
+
+/**
+ * Input for updating an existing compute function.
+ */
+export interface UpdateComputeFunctionInput {
+    name?: string;
+    description?: string;
+    code?: string;
+    timeoutMs?: number;
+}
+
+/**
+ * Options for listing compute functions.
+ */
+export interface ListComputeFunctionsOptions {
+    page?: number;
+    limit?: number;
+    search?: string;
+    searchField?: string;
+}
+
+/**
+ * Input for test-executing a compute function without saving.
+ */
+export interface TestComputeFunctionInput {
+    code: string;
+    params?: Record<string, any>;
+    timeoutMs?: number;
+}
+
+/**
+ * Result from test-executing a compute function.
+ */
+export interface TestComputeFunctionResult {
+    success: boolean;
+    output?: any;
+    duration_ms?: number;
+    logs?: string[];
+    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;
+}
+
+/**
+ * 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;
+}