@calimero-network/mero-js 1.1.0 → 2.0.0-beta.1

package/dist/api/sse/client.d.ts

@@ -0,0 +1,76 @@
+/**
+ * SSE Client
+ *
+ * Server-Sent Events for real-time event streaming.
+ * Uses standard EventSource with manual subscription management.
+ */
+import type { HttpClient } from '../../http-client';
+import type { SseSubscriptionResponse, SseSessionResponse, SseEventHandler, SseErrorHandler } from './types';
+export interface SseClientOptions {
+    /** Base URL */
+    baseUrl: string;
+    /** HTTP client for subscription requests */
+    httpClient: HttpClient;
+    /** Function to get current auth token */
+    getAuthToken?: () => Promise<string | null>;
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Reconnect delay in ms */
+    reconnectDelay?: number;
+}
+export declare class SseClient {
+    private eventSource;
+    private options;
+    private sessionId;
+    private eventHandlers;
+    private errorHandlers;
+    private subscribedContexts;
+    private _lastEventId;
+    constructor(options: SseClientOptions);
+    /**
+     * Connect to the SSE stream
+     */
+    connect(): Promise<string>;
+    /**
+     * Disconnect from the SSE stream
+     */
+    disconnect(): void;
+    /**
+     * Subscribe to context events
+     */
+    subscribe(contextIds: string[]): Promise<SseSubscriptionResponse>;
+    /**
+     * Unsubscribe from context events
+     */
+    unsubscribe(contextIds: string[]): Promise<SseSubscriptionResponse>;
+    /**
+     * Get session information
+     */
+    getSession(): Promise<SseSessionResponse>;
+    /**
+     * Add event handler
+     */
+    onEvent(handler: SseEventHandler): () => void;
+    /**
+     * Add error handler
+     */
+    onError(handler: SseErrorHandler): () => void;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Get subscribed context IDs
+     */
+    getSubscribedContexts(): string[];
+    /**
+     * Get the last event ID (useful for resumable connections)
+     */
+    getLastEventId(): string | null;
+    private handleDisconnect;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/api/sse/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/api/sse/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAEV,uBAAuB,EACvB,kBAAkB,EAElB,eAAe,EACf,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,gBAAgB;IAC/B,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,UAAU,EAAE,UAAU,CAAC;IACvB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5C,mCAAmC;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4BAA4B;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,kBAAkB,CAAqB;IAE/C,OAAO,CAAC,YAAY,CAAuB;gBAE/B,OAAO,EAAE,gBAAgB;IASrC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAoEhC;;OAEG;IACH,UAAU,IAAI,IAAI;IAQlB;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAuBvE;;OAEG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAuBzE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAU/C;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,IAAI;IAO7C;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,IAAI;IAO7C;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B;;OAEG;IACH,qBAAqB,IAAI,MAAM,EAAE;IAIjC;;OAEG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B,OAAO,CAAC,gBAAgB;CAiBzB"}

package/dist/api/sse/client.js

@@ -0,0 +1,203 @@
+/**
+ * SSE Client
+ *
+ * Server-Sent Events for real-time event streaming.
+ * Uses standard EventSource with manual subscription management.
+ */
+export class SseClient {
+    constructor(options) {
+        this.eventSource = null;
+        this.sessionId = null;
+        this.eventHandlers = [];
+        this.errorHandlers = [];
+        this.subscribedContexts = new Set();
+        // Track last event ID for reconnection (used for resumable streams)
+        this._lastEventId = null;
+        this.options = {
+            autoReconnect: true,
+            reconnectDelay: 1000,
+            getAuthToken: async () => null,
+            ...options,
+        };
+    }
+    /**
+     * Connect to the SSE stream
+     */
+    async connect() {
+        if (this.eventSource) {
+            throw new Error('Already connected');
+        }
+        const token = await this.options.getAuthToken();
+        let url = `${this.options.baseUrl}/sse`;
+        if (token) {
+            url += `?token=${encodeURIComponent(token)}`;
+        }
+        return new Promise((resolve, reject) => {
+            this.eventSource = new EventSource(url, {
+                withCredentials: true,
+            });
+            // Handle connect event (first event with session_id)
+            this.eventSource.addEventListener('connect', (event) => {
+                const messageEvent = event;
+                try {
+                    // Session ID may be in data or as plain string
+                    const data = messageEvent.data;
+                    this.sessionId = typeof data === 'string' && data.startsWith('{')
+                        ? JSON.parse(data).session_id || JSON.parse(data).sessionId
+                        : data;
+                    resolve(this.sessionId);
+                }
+                catch {
+                    this.sessionId = messageEvent.data;
+                    resolve(this.sessionId);
+                }
+            });
+            this.eventSource.onmessage = (event) => {
+                this._lastEventId = event.lastEventId;
+                try {
+                    const data = JSON.parse(event.data);
+                    const sseEvent = {
+                        id: event.lastEventId,
+                        event: 'message',
+                        data,
+                    };
+                    this.eventHandlers.forEach(h => h(sseEvent));
+                }
+                catch {
+                    // Non-JSON message
+                    const sseEvent = {
+                        id: event.lastEventId,
+                        event: 'message',
+                        data: event.data,
+                    };
+                    this.eventHandlers.forEach(h => h(sseEvent));
+                }
+            };
+            this.eventSource.onerror = (_event) => {
+                const error = new Error('SSE connection error');
+                this.errorHandlers.forEach(h => h(error));
+                if (this.eventSource?.readyState === EventSource.CLOSED) {
+                    this.handleDisconnect();
+                    if (!this.sessionId) {
+                        reject(error);
+                    }
+                }
+            };
+        });
+    }
+    /**
+     * Disconnect from the SSE stream
+     */
+    disconnect() {
+        this.options.autoReconnect = false;
+        this.eventSource?.close();
+        this.eventSource = null;
+        this.sessionId = null;
+        this.subscribedContexts.clear();
+    }
+    /**
+     * Subscribe to context events
+     */
+    async subscribe(contextIds) {
+        if (!this.sessionId) {
+            throw new Error('Not connected');
+        }
+        const request = {
+            id: this.sessionId,
+            method: 'subscribe',
+            params: { contextIds },
+        };
+        const response = await this.options.httpClient.post('/sse/subscription', request);
+        if (!response.error) {
+            contextIds.forEach(id => this.subscribedContexts.add(id));
+        }
+        return response;
+    }
+    /**
+     * Unsubscribe from context events
+     */
+    async unsubscribe(contextIds) {
+        if (!this.sessionId) {
+            throw new Error('Not connected');
+        }
+        const request = {
+            id: this.sessionId,
+            method: 'unsubscribe',
+            params: { contextIds },
+        };
+        const response = await this.options.httpClient.post('/sse/subscription', request);
+        if (!response.error) {
+            contextIds.forEach(id => this.subscribedContexts.delete(id));
+        }
+        return response;
+    }
+    /**
+     * Get session information
+     */
+    async getSession() {
+        if (!this.sessionId) {
+            throw new Error('Not connected');
+        }
+        return this.options.httpClient.get(`/sse/session/${this.sessionId}`);
+    }
+    /**
+     * Add event handler
+     */
+    onEvent(handler) {
+        this.eventHandlers.push(handler);
+        return () => {
+            this.eventHandlers = this.eventHandlers.filter(h => h !== handler);
+        };
+    }
+    /**
+     * Add error handler
+     */
+    onError(handler) {
+        this.errorHandlers.push(handler);
+        return () => {
+            this.errorHandlers = this.errorHandlers.filter(h => h !== handler);
+        };
+    }
+    /**
+     * Check if connected
+     */
+    isConnected() {
+        return this.eventSource?.readyState === EventSource.OPEN;
+    }
+    /**
+     * Get current session ID
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Get subscribed context IDs
+     */
+    getSubscribedContexts() {
+        return Array.from(this.subscribedContexts);
+    }
+    /**
+     * Get the last event ID (useful for resumable connections)
+     */
+    getLastEventId() {
+        return this._lastEventId;
+    }
+    handleDisconnect() {
+        if (!this.options.autoReconnect) {
+            return;
+        }
+        setTimeout(async () => {
+            try {
+                await this.connect();
+                // Resubscribe to previous contexts
+                if (this.subscribedContexts.size > 0) {
+                    await this.subscribe(Array.from(this.subscribedContexts));
+                }
+            }
+            catch {
+                // Will retry via handleDisconnect on next error
+            }
+        }, this.options.reconnectDelay);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/api/sse/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/api/sse/client.ts"],"names":[],"mappings":"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"}

package/dist/api/sse/index.d.ts

@@ -0,0 +1,4 @@
+export { SseClient } from './client';
+export type { SseClientOptions } from './client';
+export type { SseSubscriptionRequest, SseSubscriptionResponse, SseSessionResponse, SseEvent, SseEventHandler, SseErrorHandler, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/sse/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/sse/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,YAAY,EACV,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,eAAe,GAChB,MAAM,SAAS,CAAC"}

package/dist/api/sse/index.js

@@ -0,0 +1,2 @@
+export { SseClient } from './client';
+//# sourceMappingURL=index.js.map

package/dist/api/sse/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/sse/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/api/sse/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SSE Types
+ * Based on OpenAPI spec: /sse endpoints
+ */
+export interface SseSubscriptionRequest {
+    /** Session ID from connect event */
+    id: string;
+    method: 'subscribe' | 'unsubscribe';
+    params: {
+        contextIds: string[];
+    };
+}
+export interface SseSubscriptionResponse {
+    data?: {
+        subscribedContextIds?: string[];
+        unsubscribedContextIds?: string[];
+    };
+    error?: string;
+}
+export interface SseSessionResponse {
+    data?: {
+        sessionId: string;
+        subscribedContextIds: string[];
+        connectedAt: string;
+    };
+    error?: string;
+}
+export interface SseEvent {
+    id?: string;
+    event: string;
+    data: unknown;
+}
+export type SseEventHandler = (event: SseEvent) => void;
+export type SseErrorHandler = (error: Error) => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/api/sse/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/api/sse/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,GAAG,aAAa,CAAC;IACpC,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE;QACL,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;QAChC,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;KACnC,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,oBAAoB,EAAE,MAAM,EAAE,CAAC;QAC/B,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;AACxD,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC"}

package/dist/api/sse/types.js

@@ -0,0 +1,6 @@
+/**
+ * SSE Types
+ * Based on OpenAPI spec: /sse endpoints
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/sse/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/api/sse/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/api/utils.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared utilities for API clients
+ */
+export type ApiResponseWrapper<T> = {
+    data: T;
+    error?: never;
+} | {
+    data?: never;
+    error: ApiError;
+};
+/**
+ * API-level error structure (returned in response body even with HTTP 200)
+ * Common in RPC-style APIs where errors are semantic, not transport-level.
+ */
+export interface ApiError {
+    type?: string;
+    code?: number;
+    message: string;
+    data?: unknown;
+}
+/**
+ * Custom error class for API errors that includes structured error data.
+ */
+export declare class ApiResponseError extends Error {
+    readonly type?: string;
+    readonly code?: number;
+    readonly data?: unknown;
+    constructor(error: ApiError);
+}
+/**
+ * Unwraps a response from the API format { data: T } to T.
+ *
+ * This function handles:
+ * 1. Standard success responses: { data: T }
+ * 2. RPC-style error responses: { error: { message, type?, code? } }
+ * 3. Null/undefined data detection
+ *
+ * @example
+ * ```typescript
+ * // Success case
+ * const apps = await unwrap(client.get<{ data: App[] }>('/apps'));
+ * // apps is App[]
+ *
+ * // Error case (throws ApiResponseError)
+ * const result = await unwrap(client.post('/rpc', badRequest));
+ * // throws ApiResponseError with message, type, code
+ * ```
+ *
+ * @param response - Promise resolving to an ApiResponseWrapper<T>
+ * @returns Promise resolving to the unwrapped data
+ * @throws ApiResponseError if the response contains an error payload
+ * @throws Error if data is null or undefined
+ */
+export declare function unwrap<T>(response: Promise<ApiResponseWrapper<T> | {
+    data: T;
+}>): Promise<T>;
+/**
+ * Safely unwraps a response, returning null instead of throwing on missing data.
+ * Still throws on explicit error payloads.
+ *
+ * @param response - Promise resolving to an ApiResponseWrapper<T>
+ * @returns Promise resolving to the unwrapped data or null
+ * @throws ApiResponseError if the response contains an error payload
+ */
+export declare function unwrapOrNull<T>(response: Promise<ApiResponseWrapper<T> | {
+    data: T;
+}>): Promise<T | null>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/api/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/api/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,IAAI,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEnG;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC;IAC9B,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC;IAC9B,SAAgB,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEnB,KAAK,EAAE,QAAQ;CAO5B;AAkBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAC5B,QAAQ,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,GACrD,OAAO,CAAC,CAAC,CAAC,CAeZ;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,GACrD,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAanB"}

package/dist/api/utils.js

@@ -0,0 +1,83 @@
+/**
+ * Shared utilities for API clients
+ */
+/**
+ * Custom error class for API errors that includes structured error data.
+ */
+export class ApiResponseError extends Error {
+    constructor(error) {
+        super(error.message);
+        this.name = 'ApiResponseError';
+        this.type = error.type;
+        this.code = error.code;
+        this.data = error.data;
+    }
+}
+/**
+ * Type guard to check if a response contains an error payload.
+ */
+function hasErrorPayload(response) {
+    return (typeof response === 'object' &&
+        response !== null &&
+        'error' in response &&
+        response.error !== null &&
+        response.error !== undefined &&
+        typeof response.error === 'object');
+}
+/**
+ * Unwraps a response from the API format { data: T } to T.
+ *
+ * This function handles:
+ * 1. Standard success responses: { data: T }
+ * 2. RPC-style error responses: { error: { message, type?, code? } }
+ * 3. Null/undefined data detection
+ *
+ * @example
+ * ```typescript
+ * // Success case
+ * const apps = await unwrap(client.get<{ data: App[] }>('/apps'));
+ * // apps is App[]
+ *
+ * // Error case (throws ApiResponseError)
+ * const result = await unwrap(client.post('/rpc', badRequest));
+ * // throws ApiResponseError with message, type, code
+ * ```
+ *
+ * @param response - Promise resolving to an ApiResponseWrapper<T>
+ * @returns Promise resolving to the unwrapped data
+ * @throws ApiResponseError if the response contains an error payload
+ * @throws Error if data is null or undefined
+ */
+export async function unwrap(response) {
+    const result = await response;
+    // Check for RPC-style error payload (even with HTTP 200)
+    if (hasErrorPayload(result)) {
+        throw new ApiResponseError(result.error);
+    }
+    // Check specifically for null/undefined, not falsy values
+    // This allows valid responses like 0, false, or empty strings
+    if (result.data === null || result.data === undefined) {
+        throw new Error('Response data is null or undefined');
+    }
+    return result.data;
+}
+/**
+ * Safely unwraps a response, returning null instead of throwing on missing data.
+ * Still throws on explicit error payloads.
+ *
+ * @param response - Promise resolving to an ApiResponseWrapper<T>
+ * @returns Promise resolving to the unwrapped data or null
+ * @throws ApiResponseError if the response contains an error payload
+ */
+export async function unwrapOrNull(response) {
+    const result = await response;
+    // Check for RPC-style error payload
+    if (hasErrorPayload(result)) {
+        throw new ApiResponseError(result.error);
+    }
+    if (result.data === null || result.data === undefined) {
+        return null;
+    }
+    return result.data;
+}
+//# sourceMappingURL=utils.js.map

package/dist/api/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/api/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiBH;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAKzC,YAAY,KAAe;QACzB,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;AAED;;GAEG;AACH,SAAS,eAAe,CACtB,QAAiB;IAEjB,OAAO,CACL,OAAO,QAAQ,KAAK,QAAQ;QAC5B,QAAQ,KAAK,IAAI;QACjB,OAAO,IAAI,QAAQ;QACnB,QAAQ,CAAC,KAAK,KAAK,IAAI;QACvB,QAAQ,CAAC,KAAK,KAAK,SAAS;QAC5B,OAAQ,QAA+B,CAAC,KAAK,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,QAAsD;IAEtD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC;IAE9B,yDAAyD;IACzD,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE;QAC3B,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;KAC1C;IAED,0DAA0D;IAC1D,8DAA8D;IAC9D,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE;QACrD,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;KACvD;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAsD;IAEtD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC;IAE9B,oCAAoC;IACpC,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE;QAC3B,MAAM,IAAI,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;KAC1C;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE;QACrD,OAAO,IAAI,CAAC;KACb;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/api/ws/client.d.ts

@@ -0,0 +1,72 @@
+/**
+ * WebSocket Client
+ *
+ * Real-time event subscriptions via WebSocket.
+ * Events are pushed from server to client.
+ * For queries/mutations, use the JSON-RPC endpoint.
+ */
+import type { WebSocketResponse, WebSocketEventHandler, WebSocketErrorHandler, WebSocketCloseHandler } from './types';
+export interface WebSocketClientOptions {
+    /** Base URL (will be converted to ws:// or wss://) */
+    baseUrl: string;
+    /** Function to get current auth token */
+    getAuthToken?: () => Promise<string | null>;
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Reconnect delay in ms */
+    reconnectDelay?: number;
+    /** Max reconnect attempts */
+    maxReconnectAttempts?: number;
+}
+export declare class WebSocketClient {
+    private ws;
+    private options;
+    private requestId;
+    private pendingRequests;
+    private eventHandlers;
+    private errorHandlers;
+    private closeHandlers;
+    private reconnectAttempts;
+    private subscribedContexts;
+    constructor(options: WebSocketClientOptions);
+    /**
+     * Connect to the WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Subscribe to context events
+     */
+    subscribe(contextIds: string[]): Promise<WebSocketResponse>;
+    /**
+     * Unsubscribe from context events
+     */
+    unsubscribe(contextIds: string[]): Promise<WebSocketResponse>;
+    /**
+     * Add event handler
+     */
+    onEvent(handler: WebSocketEventHandler): () => void;
+    /**
+     * Add error handler
+     */
+    onError(handler: WebSocketErrorHandler): () => void;
+    /**
+     * Add close handler
+     */
+    onClose(handler: WebSocketCloseHandler): () => void;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get subscribed context IDs
+     */
+    getSubscribedContexts(): string[];
+    private send;
+    private handleMessage;
+    private handleDisconnect;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/api/ws/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/api/ws/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAEV,iBAAiB,EAEjB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5C,mCAAmC;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4BAA4B;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,eAAe,CAGlB;IACL,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,kBAAkB,CAAqB;gBAEnC,OAAO,EAAE,sBAAsB;IAU3C;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC9B;;OAEG;IACH,UAAU,IAAI,IAAI;IAOlB;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAcjE;;OAEG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAcnE;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAOnD;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAOnD;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,IAAI;IAOnD;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,qBAAqB,IAAI,MAAM,EAAE;YAInB,IAAI;IAuBlB,OAAO,CAAC,aAAa;IAwBrB,OAAO,CAAC,gBAAgB;CAyBzB"}