@keyringnetwork/keyring-connect-sdk 3.1.0 → 4.1.0-alpha.1

package/dist/core/VerificationSession.d.ts

@@ -0,0 +1,62 @@
+import { CredentialData, SDKEventData, SDKEventTypes, SessionConfig } from "../types";
+/**
+ * Represents an active verification session with proper cleanup
+ */
+export declare class VerificationSession {
+    private readonly sessionConfig;
+    private static activeSession;
+    private static staticLogger;
+    private logger;
+    private httpClient?;
+    private wsClient?;
+    private sessionResponse?;
+    private stopPolling?;
+    private uiManager?;
+    private eventListeners;
+    private isWebsocketActive;
+    private resultPromise?;
+    private resolveResult?;
+    private rejectResult?;
+    private constructor();
+    /**
+     * Launch verification flow with automatic platform detection and fallback
+     */
+    static launch(sessionConfig: SessionConfig): Promise<VerificationSession>;
+    /**
+     * Start the verification session
+     */
+    start(): Promise<CredentialData | null>;
+    get sessionId(): string | undefined;
+    get sessionToken(): string | undefined;
+    /**
+     * Add event listener for verification events
+     */
+    addEventListener<T extends SDKEventTypes>(eventType: T, listener: (data: SDKEventData[T]) => void): void;
+    /**
+     * Remove event listener
+     */
+    removeEventListener<T extends SDKEventTypes>(eventType: T, listener: (data: SDKEventData[T]) => void): void;
+    /**
+     * Clean up all resources
+     */
+    close(): Promise<void>;
+    private complete;
+    private fail;
+    /**
+     * Initialize mobile-specific resources (HTTP client, session, WebSocket)
+     */
+    private initializeMobileResources;
+    private setupWebSocket;
+    private setupUI;
+    private showQR;
+    private showMobileModal;
+    /**
+     * Start HTTP polling as fallback when WebSocket is disconnected
+     */
+    private startPollingFallback;
+    /**
+     * Handle session updates from HTTP polling
+     */
+    private handlePollingUpdate;
+    private emit;
+}

package/dist/core/VerificationSession.js

@@ -0,0 +1,404 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VerificationSession = void 0;
+const UIManager_1 = require("../ui/UIManager");
+const logger_1 = require("../utils/logger");
+const platformUtils_1 = require("../utils/platformUtils");
+const errors_1 = require("./errors");
+const htppClient_1 = require("./htppClient");
+const keyringConnectExtension_1 = require("./keyringConnectExtension");
+const websocketClient_1 = require("./websocketClient");
+/**
+ * Represents an active verification session with proper cleanup
+ */
+class VerificationSession {
+    constructor(sessionConfig) {
+        this.sessionConfig = sessionConfig;
+        this.eventListeners = new Map();
+        this.isWebsocketActive = false;
+        // Initialize with basic logger, will be updated with sessionId after session is created
+        this.logger = logger_1.KeyringLogger.init("VerificationSession").child({
+            policyId: sessionConfig.policy_id,
+            name: sessionConfig.name,
+        });
+        this.logger.debug("Creating verification session");
+    }
+    /**
+     * Launch verification flow with automatic platform detection and fallback
+     */
+    static launch(sessionConfig) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.staticLogger.info({ sessionConfig }, "Launching verification flow");
+            try {
+                // Clean up any existing session
+                if (this.activeSession) {
+                    this.staticLogger.debug("Cleaning up existing session");
+                    this.activeSession.close();
+                    this.activeSession = null;
+                }
+                // Ensure online connectivity
+                if (!(yield platformUtils_1.PlatformUtils.waitForOnline(5000))) {
+                    throw new errors_1.KeyringError(errors_1.KeyringErrorCode.NETWORK_ERROR, "No internet connection available");
+                }
+                // Create and start verification session
+                this.activeSession = new VerificationSession(sessionConfig);
+                return this.activeSession;
+            }
+            catch (error) {
+                this.staticLogger.error(error, "Launch failed");
+                const keyringError = errors_1.KeyringError.fromUnknown(error);
+                throw keyringError;
+            }
+        });
+    }
+    /**
+     * Start the verification session
+     */
+    start() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.logger.debug("Starting verification session");
+            // Create result promise that will be resolved when verification completes
+            this.resultPromise = new Promise((resolve, reject) => {
+                this.resolveResult = resolve;
+                this.rejectResult = reject;
+            });
+            try {
+                // Setup UI - this will handle mobile/extension branching
+                yield this.setupUI();
+                // Return promise that resolves when verification completes
+                return this.resultPromise;
+            }
+            catch (error) {
+                this.close();
+                throw errors_1.KeyringError.fromUnknown(error, { sessionId: this.sessionId });
+            }
+        });
+    }
+    get sessionId() {
+        var _a;
+        return (_a = this.sessionResponse) === null || _a === void 0 ? void 0 : _a.session_id;
+    }
+    get sessionToken() {
+        var _a;
+        return (_a = this.sessionResponse) === null || _a === void 0 ? void 0 : _a.session_token;
+    }
+    /**
+     * Add event listener for verification events
+     */
+    addEventListener(eventType, listener) {
+        if (!this.eventListeners.has(eventType)) {
+            this.eventListeners.set(eventType, []);
+        }
+        this.eventListeners.get(eventType).push(listener);
+    }
+    /**
+     * Remove event listener
+     */
+    removeEventListener(eventType, listener) {
+        const listeners = this.eventListeners.get(eventType);
+        if (listeners) {
+            const index = listeners.indexOf(listener);
+            if (index > -1) {
+                listeners.splice(index, 1);
+            }
+        }
+    }
+    /**
+     * Clean up all resources
+     */
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.logger.debug("Cleaning up verification session");
+            // Stop polling if active
+            if (this.stopPolling) {
+                this.stopPolling();
+                this.stopPolling = undefined;
+            }
+            // Clean up WebSocket (mobile only)
+            if (this.wsClient) {
+                this.isWebsocketActive = false;
+                this.wsClient.disconnect();
+                this.wsClient = undefined;
+            }
+            // Clean up HTTP session (mobile only)
+            if (this.httpClient && this.sessionId && this.sessionToken) {
+                this.logger.debug({ sessionId: this.sessionId }, "Deleting session from backend");
+                yield this.httpClient.closeSession(this.sessionId, this.sessionToken);
+            }
+            // Clear event listeners
+            this.eventListeners.clear();
+            // Reject result promise if still pending
+            if (this.rejectResult) {
+                const error = new errors_1.KeyringError(errors_1.KeyringErrorCode.USER_CANCELLED, "Session was cleaned up");
+                this.rejectResult(error);
+                this.resolveResult = undefined;
+                this.rejectResult = undefined;
+            }
+        });
+    }
+    complete(result) {
+        var _a;
+        this.logger.debug("Session completed successfully");
+        (_a = this.resolveResult) === null || _a === void 0 ? void 0 : _a.call(this, result);
+        this.close();
+    }
+    fail(error) {
+        var _a;
+        this.logger.error(error, "Session failed");
+        (_a = this.rejectResult) === null || _a === void 0 ? void 0 : _a.call(this, error);
+        this.close();
+    }
+    /**
+     * Initialize mobile-specific resources (HTTP client, session, WebSocket)
+     */
+    initializeMobileResources() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Initialize HTTP client
+            this.httpClient = htppClient_1.HttpClient.initializeHttpClient(this.sessionConfig.api_key);
+            // Create backend session
+            this.sessionResponse = yield this.httpClient.createSession(this.sessionConfig);
+            // Update logger with sessionId now that we have it
+            this.logger = this.logger.child({
+                sessionId: this.sessionResponse.session_id,
+            });
+            this.logger.debug({
+                sessionId: this.sessionResponse.session_id,
+                status: this.sessionResponse.status,
+            }, "Mobile session created");
+        });
+    }
+    setupWebSocket() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (!((_a = this.sessionResponse) === null || _a === void 0 ? void 0 : _a.session_id)) {
+                throw new errors_1.KeyringError(errors_1.KeyringErrorCode.SESSION_NOT_FOUND, "Session not initialized for mobile flow");
+            }
+            const wsCallbacks = {
+                onConnectionStatusChanged: (connected) => {
+                    var _a;
+                    this.emit("connectionStatusChanged", connected);
+                    if (connected) {
+                        (_a = this.uiManager) === null || _a === void 0 ? void 0 : _a.updateStatus("Connected to Keyring app", "connected");
+                        // Stop polling if WebSocket reconnects
+                        if (this.stopPolling) {
+                            this.logger.debug("WebSocket reconnected, stopping polling");
+                            this.stopPolling();
+                            this.stopPolling = undefined;
+                        }
+                    }
+                    else {
+                        // Only start polling if session is still active (not intentionally closed)
+                        if (this.isWebsocketActive) {
+                            // WebSocket disconnected, start polling as fallback
+                            this.startPollingFallback();
+                        }
+                    }
+                },
+                onMobileConnected: (data) => {
+                    var _a;
+                    this.emit("mobileConnected", data);
+                    (_a = this.uiManager) === null || _a === void 0 ? void 0 : _a.updateStatus("Connected to mobile app", "connected");
+                },
+                onProcessingStarted: (data) => {
+                    var _a;
+                    this.logger.debug(data, "Processing started");
+                    (_a = this.uiManager) === null || _a === void 0 ? void 0 : _a.updateStatus("Processing verification...", "processing");
+                    this.emit("processingStarted", data);
+                },
+                onProcessingCompleted: (data) => {
+                    var _a, _b;
+                    this.logger.debug(data, "Processing completed");
+                    if (!data.result.credential_data) {
+                        (_a = this.uiManager) === null || _a === void 0 ? void 0 : _a.updateStatus("Verification failed", "failed");
+                        this.fail(new errors_1.KeyringError(errors_1.KeyringErrorCode.PROCESSING_FAILED, "Processing failed"));
+                        return;
+                    }
+                    else {
+                        (_b = this.uiManager) === null || _b === void 0 ? void 0 : _b.showCompleteModal(data.result.entity_type, data.result.datasource);
+                        this.emit("processingCompleted", data);
+                        this.complete(data.result.credential_data);
+                    }
+                },
+                onSessionExpired: (data) => {
+                    var _a, _b;
+                    (_a = this.uiManager) === null || _a === void 0 ? void 0 : _a.updateStatus("Session expired", "expired");
+                    this.emit("sessionExpired", data);
+                    (_b = this.uiManager) === null || _b === void 0 ? void 0 : _b.showTerminatedModal();
+                    this.fail(new errors_1.KeyringError(errors_1.KeyringErrorCode.SESSION_EXPIRED, "Verification session has expired"));
+                },
+                onError: (data) => {
+                    var _a;
+                    this.logger.error(data, "WebSocket error");
+                    this.emit("error", data);
+                    const errorMessage = typeof data === "object" && "message" in data ? data.message : data;
+                    (_a = this.uiManager) === null || _a === void 0 ? void 0 : _a.updateStatus("Verification failed", "failed");
+                    this.fail(errors_1.KeyringError.fromUnknown(errorMessage, { sessionId: this.sessionId }));
+                },
+            };
+            this.wsClient = new websocketClient_1.KeyringWebSocketClient(this.sessionResponse.session_id, this.sessionResponse.session_token, wsCallbacks);
+            this.isWebsocketActive = true;
+            yield this.wsClient.connect();
+        });
+    }
+    setupUI() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.uiManager = new UIManager_1.UIManager();
+            this.uiManager.setCallbacks(
+            // onCancel
+            () => {
+                this.fail(new errors_1.KeyringError(errors_1.KeyringErrorCode.USER_CANCELLED, "User cancelled verification"));
+            }, 
+            // onExtensionSelected
+            () => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                try {
+                    this.logger.debug("Extension selected");
+                    const result = yield keyringConnectExtension_1.KeyringConnectExtension.launchExtension(this.sessionConfig);
+                    this.complete(result);
+                }
+                catch (error) {
+                    this.fail(new errors_1.KeyringError(errors_1.KeyringErrorCode.PROCESSING_FAILED, (_a = error.message) !== null && _a !== void 0 ? _a : "Extension launch failed"));
+                }
+            }), 
+            // onMobileSelected
+            () => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                try {
+                    this.logger.debug("Mobile selected");
+                    // Initialize mobile resources when mobile is selected
+                    yield this.initializeMobileResources();
+                    // Setup WebSocket connection
+                    yield this.setupWebSocket();
+                    // Show QR code
+                    this.showQR();
+                }
+                catch (error) {
+                    this.logger.error({ error }, "Failed to initialize mobile flow");
+                    this.fail(new errors_1.KeyringError(errors_1.KeyringErrorCode.SESSION_CREATION_FAILED, (_a = error.message) !== null && _a !== void 0 ? _a : "Failed to initialize mobile flow"));
+                }
+            }));
+            // Show appropriate UI based on platform
+            const platform = platformUtils_1.PlatformUtils.detectPlatform();
+            if (platform.isDesktop) {
+                this.uiManager.showSelectionModal();
+            }
+            else {
+                // For mobile platforms, initialize mobile resources immediately
+                yield this.initializeMobileResources();
+                yield this.setupWebSocket();
+                this.showMobileModal();
+            }
+        });
+    }
+    showQR() {
+        if (!this.uiManager || !this.sessionResponse)
+            return;
+        this.uiManager.showQRModal(this.sessionResponse.qr_code_data, this.sessionResponse.session_id, this.sessionResponse.expires_at);
+    }
+    showMobileModal() {
+        if (!this.uiManager || !this.sessionResponse)
+            return;
+        this.uiManager.showMobileModal(this.sessionResponse.qr_code_data, this.sessionResponse.expires_at);
+    }
+    /**
+     * Start HTTP polling as fallback when WebSocket is disconnected
+     */
+    startPollingFallback() {
+        var _a, _b;
+        if (!this.httpClient || !((_a = this.sessionResponse) === null || _a === void 0 ? void 0 : _a.session_id)) {
+            this.logger.warn("Cannot start polling: httpClient or sessionId not available");
+            return;
+        }
+        // Don't start polling if already active
+        if (this.stopPolling) {
+            return;
+        }
+        this.logger.info("Starting HTTP polling fallback");
+        (_b = this.uiManager) === null || _b === void 0 ? void 0 : _b.updateStatus("Connection lost, checking status...", "processing");
+        this.stopPolling = this.httpClient.startPolling(this.sessionResponse.session_id, this.sessionResponse.session_token, (session) => {
+            this.handlePollingUpdate(session);
+        }, (error) => {
+            this.logger.error({ error }, "Polling error");
+            this.fail(new errors_1.KeyringError(errors_1.KeyringErrorCode.NETWORK_ERROR, "Polling failed"));
+        }, 2000 // Poll every 2 seconds
+        );
+    }
+    /**
+     * Handle session updates from HTTP polling
+     */
+    handlePollingUpdate(session) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        if (!this.isWebsocketActive) {
+            return;
+        }
+        this.logger.debug({ status: session.status, hasResult: !!session.result }, "Received polling update");
+        // Handle different session statuses
+        switch (session.status) {
+            case "processing_completed":
+                this.logger.debug("Session completed via polling");
+                const result = session.result;
+                const hasRequiredData = (result === null || result === void 0 ? void 0 : result.credential_data) && (result === null || result === void 0 ? void 0 : result.entity_type) && (result === null || result === void 0 ? void 0 : result.datasource);
+                if (hasRequiredData) {
+                    (_a = this.uiManager) === null || _a === void 0 ? void 0 : _a.showCompleteModal(result.entity_type, result.datasource);
+                    this.emit("processingCompleted", {
+                        result: {
+                            credential_data: result.credential_data,
+                            entity_type: result.entity_type,
+                            datasource: result.datasource,
+                        },
+                        status: "success",
+                    });
+                    this.complete(result.credential_data);
+                }
+                else {
+                    (_b = this.uiManager) === null || _b === void 0 ? void 0 : _b.updateStatus("Verification failed", "failed");
+                    this.fail(new errors_1.KeyringError(errors_1.KeyringErrorCode.PROCESSING_FAILED, "No credential data in result"));
+                }
+                break;
+            case "processing_failed":
+                this.logger.debug("Session failed via polling");
+                (_c = this.uiManager) === null || _c === void 0 ? void 0 : _c.updateStatus("Verification failed", "failed");
+                this.fail(new errors_1.KeyringError(errors_1.KeyringErrorCode.PROCESSING_FAILED, session.error || "Verification failed"));
+                break;
+            case "session_expired":
+                this.logger.debug("Session expired via polling");
+                (_d = this.uiManager) === null || _d === void 0 ? void 0 : _d.showTerminatedModal();
+                this.fail(new errors_1.KeyringError(errors_1.KeyringErrorCode.SESSION_EXPIRED, "Verification session has expired"));
+                break;
+            case "processing_started":
+                (_e = this.uiManager) === null || _e === void 0 ? void 0 : _e.updateStatus("Processing verification...", "processing");
+                break;
+            case "mobile_connected":
+                (_f = this.uiManager) === null || _f === void 0 ? void 0 : _f.updateStatus("Mobile app connected...", "connected");
+                break;
+            case "session_created":
+                (_g = this.uiManager) === null || _g === void 0 ? void 0 : _g.updateStatus("Waiting for mobile app...", "connected");
+                break;
+        }
+    }
+    emit(eventType, data) {
+        const listeners = this.eventListeners.get(eventType);
+        if (listeners) {
+            listeners.forEach((listener) => {
+                try {
+                    listener(data);
+                }
+                catch (error) {
+                    this.logger.error(error, `Error in event listener for ${eventType}`);
+                }
+            });
+        }
+    }
+}
+exports.VerificationSession = VerificationSession;
+VerificationSession.activeSession = null;
+VerificationSession.staticLogger = logger_1.KeyringLogger.init("VerificationSession");

package/dist/core/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Keyring SDK Error Codes
+ */
+export declare enum KeyringErrorCode {
+    NETWORK_ERROR = "NETWORK_ERROR",
+    SESSION_CREATION_FAILED = "SESSION_CREATION_FAILED",
+    WEBSOCKET_CONNECTION_FAILED = "WEBSOCKET_CONNECTION_FAILED",
+    EXTENSION_NOT_FOUND = "EXTENSION_NOT_FOUND",
+    EXTENSION_TIMEOUT = "EXTENSION_TIMEOUT",
+    CHROME_RUNTIME_ERROR = "CHROME_RUNTIME_ERROR",
+    EXTENSION_LAUNCH_FAILED = "EXTENSION_LAUNCH_FAILED",
+    SESSION_EXPIRED = "SESSION_EXPIRED",
+    SESSION_NOT_FOUND = "SESSION_NOT_FOUND",
+    INVALID_SESSION_CONFIG = "INVALID_SESSION_CONFIG",
+    USER_CANCELLED = "USER_CANCELLED",
+    TIMEOUT_ERROR = "TIMEOUT_ERROR",
+    QR_DISPLAY_NOT_SUPPORTED = "QR_DISPLAY_NOT_SUPPORTED",
+    WEBSOCKET_NOT_SUPPORTED = "WEBSOCKET_NOT_SUPPORTED",
+    INVALID_CONFIG = "INVALID_CONFIG",
+    MISSING_REQUIRED_FIELD = "MISSING_REQUIRED_FIELD",
+    PROCESSING_FAILED = "PROCESSING_FAILED",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Keyring SDK Error class with structured error information
+ */
+export declare class KeyringError extends Error {
+    readonly code: KeyringErrorCode;
+    readonly cause?: unknown | undefined;
+    readonly context?: Record<string, any> | undefined;
+    readonly name = "KeyringError";
+    readonly timestamp: string;
+    constructor(code: KeyringErrorCode, message: string, cause?: unknown | undefined, context?: Record<string, any> | undefined);
+    /**
+     * Create error from unknown source
+     */
+    static fromUnknown(error: unknown, context?: Record<string, any>): KeyringError;
+    /**
+     * Convert to JSON for logging/debugging
+     */
+    toJSON(): {
+        name: string;
+        code: KeyringErrorCode;
+        message: string;
+        timestamp: string;
+        context: Record<string, any> | undefined;
+        cause: unknown;
+    };
+}

package/dist/core/errors.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyringError = exports.KeyringErrorCode = void 0;
+/**
+ * Keyring SDK Error Codes
+ */
+var KeyringErrorCode;
+(function (KeyringErrorCode) {
+    // Network related errors
+    KeyringErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    KeyringErrorCode["SESSION_CREATION_FAILED"] = "SESSION_CREATION_FAILED";
+    KeyringErrorCode["WEBSOCKET_CONNECTION_FAILED"] = "WEBSOCKET_CONNECTION_FAILED";
+    // Extension related errors
+    KeyringErrorCode["EXTENSION_NOT_FOUND"] = "EXTENSION_NOT_FOUND";
+    KeyringErrorCode["EXTENSION_TIMEOUT"] = "EXTENSION_TIMEOUT";
+    KeyringErrorCode["CHROME_RUNTIME_ERROR"] = "CHROME_RUNTIME_ERROR";
+    KeyringErrorCode["EXTENSION_LAUNCH_FAILED"] = "EXTENSION_LAUNCH_FAILED";
+    // Session related errors
+    KeyringErrorCode["SESSION_EXPIRED"] = "SESSION_EXPIRED";
+    KeyringErrorCode["SESSION_NOT_FOUND"] = "SESSION_NOT_FOUND";
+    KeyringErrorCode["INVALID_SESSION_CONFIG"] = "INVALID_SESSION_CONFIG";
+    // User interaction errors
+    KeyringErrorCode["USER_CANCELLED"] = "USER_CANCELLED";
+    KeyringErrorCode["TIMEOUT_ERROR"] = "TIMEOUT_ERROR";
+    // Platform support errors
+    KeyringErrorCode["QR_DISPLAY_NOT_SUPPORTED"] = "QR_DISPLAY_NOT_SUPPORTED";
+    KeyringErrorCode["WEBSOCKET_NOT_SUPPORTED"] = "WEBSOCKET_NOT_SUPPORTED";
+    // Validation errors
+    KeyringErrorCode["INVALID_CONFIG"] = "INVALID_CONFIG";
+    KeyringErrorCode["MISSING_REQUIRED_FIELD"] = "MISSING_REQUIRED_FIELD";
+    // Processing errors
+    KeyringErrorCode["PROCESSING_FAILED"] = "PROCESSING_FAILED";
+    KeyringErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+})(KeyringErrorCode || (exports.KeyringErrorCode = KeyringErrorCode = {}));
+/**
+ * Keyring SDK Error class with structured error information
+ */
+class KeyringError extends Error {
+    constructor(code, message, cause, context) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.context = context;
+        this.name = 'KeyringError';
+        this.timestamp = new Date().toISOString();
+        // Maintain proper stack trace for debugging
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, KeyringError);
+        }
+    }
+    /**
+     * Create error from unknown source
+     */
+    static fromUnknown(error, context) {
+        if (error instanceof KeyringError) {
+            return error;
+        }
+        if (error instanceof Error) {
+            return new KeyringError(KeyringErrorCode.UNKNOWN_ERROR, error.message, error, context);
+        }
+        return new KeyringError(KeyringErrorCode.UNKNOWN_ERROR, String(error), error, context);
+    }
+    /**
+     * Convert to JSON for logging/debugging
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            timestamp: this.timestamp,
+            context: this.context,
+            cause: this.cause instanceof Error ? {
+                name: this.cause.name,
+                message: this.cause.message,
+                stack: this.cause.stack
+            } : this.cause
+        };
+    }
+}
+exports.KeyringError = KeyringError;

package/dist/core/htppClient.d.ts

@@ -0,0 +1,17 @@
+import { CrossDeviceSession, SessionConfig } from "../types/";
+export declare class HttpClient {
+    private static instance;
+    private httpClient;
+    private logger;
+    private constructor();
+    private setupAxiosInterceptors;
+    static initializeHttpClient(apiKey: string): HttpClient;
+    createSession(sessionConfig: SessionConfig): Promise<CrossDeviceSession>;
+    closeSession(sessionId: string, sessionToken: string): Promise<void>;
+    getSession(sessionId: string, sessionToken: string): Promise<CrossDeviceSession | null>;
+    /**
+     * Start polling for session updates
+     * Returns a function to stop polling
+     */
+    startPolling(sessionId: string, sessionToken: string, onUpdate: (session: CrossDeviceSession) => void, onError: (error: any) => void, interval?: number): () => void;
+}