@keyringnetwork/keyring-connect-sdk 4.1.0-alpha.2 → 4.1.0-alpha.3

package/dist/index.d.cts

@@ -0,0 +1,263 @@
+export * from '@keyringnetwork/contracts-abi';
+import { ExtensionStatus, BaseWebSocketMessage, DataTransportType, UserJourneyType, SessionStatus } from '@keyringnetwork/keyring-core-sdk';
+export { DataTransportType, EVENT_ACTIONS, ExtensionLaunchConfig, ExtensionStatus, UserJourneyType } from '@keyringnetwork/keyring-core-sdk';
+import { DatasourceTypes } from '@keyringnetwork/keyring-dtos';
+
+type AttestationStatus = "onboarding_required" | "onboarding_pending" | "attestation_ready" | "non_compliant";
+type CredentialStatus = "expired" | "valid" | "none";
+type User = {
+    /**
+     * Off-chain attestation status.
+     */
+    attestation_status: AttestationStatus;
+    /**
+     * On-chain keyring credential status.
+     */
+    credential_status: CredentialStatus;
+    /**
+     * Connected wallet address of the user.
+     */
+    wallet_address: string;
+    /**
+     * Keyring User ID.
+     */
+    user_id: string;
+    /**
+     * Keyring Entity ID.
+     */
+    entity_id: string;
+};
+interface ExtensionState {
+    status: ExtensionStatus;
+    manifest?: unknown;
+    error?: string;
+    user?: User;
+    tlsn_proof?: string;
+    credentialData?: CredentialData;
+}
+
+type ConnectWebSocketMessage<TType extends string, TData = unknown> = BaseWebSocketMessage<TType, TData> & {
+    session_id: string;
+    timestamp: number;
+};
+type SessionCreatedMessage = ConnectWebSocketMessage<"session_created", {
+    session_id: string;
+    qr_code_data: string;
+    expires_at: number | string;
+}>;
+type ExtensionConnectedMessage = ConnectWebSocketMessage<"extension_connected", {
+    device_info: {
+        platform: "extension";
+        extension_id: string;
+        extension_version: string;
+    };
+}>;
+type MobileConnectedMessage = ConnectWebSocketMessage<"mobile_connected", {
+    device_info: {
+        platform: "ios" | "android";
+        app_version: string;
+    };
+    connection_id: string;
+}>;
+type ProcessingStartedMessage = ConnectWebSocketMessage<"processing_started", Record<string, unknown> | undefined>;
+type ProcessingCompletedMessage = ConnectWebSocketMessage<"processing_completed", {
+    result: {
+        credential_data: CredentialData;
+        entity_type: string;
+        datasourceObject: DatasourceTypes.DatasourceObject;
+    };
+    status: "success" | "error" | "cancelled";
+}>;
+type ProcessingFailedMessage = ConnectWebSocketMessage<"processing_failed" | "error", {
+    error: string;
+    [key: string]: unknown;
+}>;
+type SessionExpiredMessage = ConnectWebSocketMessage<"session_expired", {
+    reason: "timeout" | "manual";
+}>;
+type WebSocketMessage = SessionCreatedMessage | ExtensionConnectedMessage | MobileConnectedMessage | ProcessingStartedMessage | ProcessingCompletedMessage | ProcessingFailedMessage | SessionExpiredMessage | ConnectWebSocketMessage<string, unknown>;
+
+interface SessionConfig {
+    /**
+     * The name of the client.
+     */
+    name: string;
+    /**
+     * The URL of the client app which the chrome extension will communicate with.
+     */
+    app_url: string;
+    /**
+     * The URL of the client logo.
+     */
+    logo_url: string;
+    /**
+     * The onchain policy ID of the client.
+     */
+    policy_id: number;
+    /**
+     * The wallet address and chain ID of the user.
+     */
+    credential_config: {
+        chain_id: number;
+        wallet_address: string;
+    };
+    /**
+     * The short-lived browser token used to create backend sessions.
+     */
+    clientToken?: string;
+    /**
+     * Keyring Network configuration for the extension.
+     * @note this is meant to be used for internal testing and development purposes.
+     */
+    krn_config?: {
+        keyring_api_url?: string;
+        keyring_user_app_url?: string;
+        analytics_api_url?: string;
+        notaryUrl?: string;
+        websocketProxyUrl?: string;
+    };
+    dataTransport?: DataTransportType;
+    userJourney?: UserJourneyType;
+    websocket?: {
+        session_id: string;
+        session_token: string;
+    };
+}
+interface CredentialData {
+    trader: `0x${string}`;
+    policyId: number;
+    chainId: number;
+    validUntil: number;
+    cost: number;
+    key: string;
+    signature: string;
+    backdoor: string;
+}
+interface SDKError {
+    code: string;
+    message: string;
+    details?: any;
+}
+type SDKErrorCode = "BACKEND_UNAVAILABLE" | "SESSION_CREATION_FAILED" | "SESSION_NOT_FOUND" | "SESSION_EXPIRED" | "WEBSOCKET_CONNECTION_FAILED" | "WEBSOCKET_DISCONNECTED" | "PROCESSING_FAILED" | "NETWORK_ERROR" | "VALIDATION_ERROR" | "TIMEOUT_ERROR" | "QR_DISPLAY_NOT_SUPPORTED";
+interface SDKCallbacks {
+    onExtensionConnected?: (data: ExtensionConnectedMessage["data"]) => void;
+    onSessionCreated?: (data: SessionCreatedMessage["data"]) => void;
+    onMobileConnected?: (data: MobileConnectedMessage["data"]) => void;
+    onProcessingStarted?: (data: ProcessingStartedMessage["data"]) => void;
+    onProcessingCompleted?: (data: ProcessingCompletedMessage["data"]) => void;
+    onProcessingFailed?: (data: ProcessingFailedMessage["data"]) => void;
+    onSessionExpired?: (data: SessionExpiredMessage["data"]) => void;
+    onError?: (error: SDKError) => void;
+    onConnectionStatusChanged?: (connected: boolean) => void;
+}
+type SDKEventTypes = "sessionCreated" | "extensionConnected" | "mobileConnected" | "processingStarted" | "processingCompleted" | "processingFailed" | "sessionExpired" | "error" | "connectionStatusChanged";
+type SDKEventData = {
+    sessionCreated: SessionCreatedMessage["data"];
+    extensionConnected: ExtensionConnectedMessage["data"];
+    mobileConnected: MobileConnectedMessage["data"];
+    processingStarted: ProcessingStartedMessage["data"];
+    processingCompleted: ProcessingCompletedMessage["data"];
+    processingFailed: ProcessingFailedMessage["data"];
+    sessionExpired: SessionExpiredMessage["data"];
+    error: SDKError;
+    connectionStatusChanged: boolean;
+};
+
+interface CrossDeviceSession {
+    session_id: string;
+    session_token: string;
+    config: SessionConfig;
+    origin_url: string;
+    status: SessionStatus;
+    created_at: number | string;
+    expires_at: number | string;
+    result?: {
+        credential_data?: CredentialData;
+        entity_type?: string;
+        datasourceObject?: DatasourceTypes.DatasourceObject;
+    };
+    error?: string;
+    platform: "web" | "mobile";
+    qr_code_data: string;
+    connected_clients: {
+        web?: string;
+        mobile?: string;
+    };
+}
+
+/**
+ * Represents an active verification session with proper cleanup
+ */
+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 flowType;
+    private resultPromise?;
+    private resolveResult?;
+    private rejectResult?;
+    private closePromise?;
+    private resultSettled;
+    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;
+    private resolvePendingResult;
+    private rejectPendingResult;
+    private clearPendingResultHandlers;
+    private cleanup;
+    private resolveDataTransport;
+    private validateTransportRequirements;
+    private startChromeApiFlow;
+    /**
+     * Initialize mobile-specific resources (HTTP client, session, WebSocket)
+     */
+    private initializeSession;
+    private setupWebSocket;
+    private setupUI;
+    private showQR;
+    private showMobileModal;
+    /**
+     * Start HTTP polling as fallback when WebSocket is disconnected
+     */
+    private startPollingFallback;
+    private createSession;
+    private closeBackendSession;
+    private getSession;
+    /**
+     * Handle session updates from HTTP polling
+     */
+    private handlePollingUpdate;
+    private emit;
+}
+
+export { type AttestationStatus, type CredentialData, type CredentialStatus, type CrossDeviceSession, type ExtensionConnectedMessage, type ExtensionState, type MobileConnectedMessage, type ProcessingCompletedMessage, type ProcessingFailedMessage, type ProcessingStartedMessage, type SDKCallbacks, type SDKError, type SDKErrorCode, type SDKEventData, type SDKEventTypes, type SessionConfig, type SessionCreatedMessage, type SessionExpiredMessage, type User, VerificationSession, type WebSocketMessage };

package/dist/index.d.ts

@@ -1,3 +1,263 @@
-export * from "@keyringnetwork/contracts-abi";
-export { VerificationSession } from "./core/VerificationSession";
-export * from "./types";
+export * from '@keyringnetwork/contracts-abi';
+import { ExtensionStatus, BaseWebSocketMessage, DataTransportType, UserJourneyType, SessionStatus } from '@keyringnetwork/keyring-core-sdk';
+export { DataTransportType, EVENT_ACTIONS, ExtensionLaunchConfig, ExtensionStatus, UserJourneyType } from '@keyringnetwork/keyring-core-sdk';
+import { DatasourceTypes } from '@keyringnetwork/keyring-dtos';
+
+type AttestationStatus = "onboarding_required" | "onboarding_pending" | "attestation_ready" | "non_compliant";
+type CredentialStatus = "expired" | "valid" | "none";
+type User = {
+    /**
+     * Off-chain attestation status.
+     */
+    attestation_status: AttestationStatus;
+    /**
+     * On-chain keyring credential status.
+     */
+    credential_status: CredentialStatus;
+    /**
+     * Connected wallet address of the user.
+     */
+    wallet_address: string;
+    /**
+     * Keyring User ID.
+     */
+    user_id: string;
+    /**
+     * Keyring Entity ID.
+     */
+    entity_id: string;
+};
+interface ExtensionState {
+    status: ExtensionStatus;
+    manifest?: unknown;
+    error?: string;
+    user?: User;
+    tlsn_proof?: string;
+    credentialData?: CredentialData;
+}
+
+type ConnectWebSocketMessage<TType extends string, TData = unknown> = BaseWebSocketMessage<TType, TData> & {
+    session_id: string;
+    timestamp: number;
+};
+type SessionCreatedMessage = ConnectWebSocketMessage<"session_created", {
+    session_id: string;
+    qr_code_data: string;
+    expires_at: number | string;
+}>;
+type ExtensionConnectedMessage = ConnectWebSocketMessage<"extension_connected", {
+    device_info: {
+        platform: "extension";
+        extension_id: string;
+        extension_version: string;
+    };
+}>;
+type MobileConnectedMessage = ConnectWebSocketMessage<"mobile_connected", {
+    device_info: {
+        platform: "ios" | "android";
+        app_version: string;
+    };
+    connection_id: string;
+}>;
+type ProcessingStartedMessage = ConnectWebSocketMessage<"processing_started", Record<string, unknown> | undefined>;
+type ProcessingCompletedMessage = ConnectWebSocketMessage<"processing_completed", {
+    result: {
+        credential_data: CredentialData;
+        entity_type: string;
+        datasourceObject: DatasourceTypes.DatasourceObject;
+    };
+    status: "success" | "error" | "cancelled";
+}>;
+type ProcessingFailedMessage = ConnectWebSocketMessage<"processing_failed" | "error", {
+    error: string;
+    [key: string]: unknown;
+}>;
+type SessionExpiredMessage = ConnectWebSocketMessage<"session_expired", {
+    reason: "timeout" | "manual";
+}>;
+type WebSocketMessage = SessionCreatedMessage | ExtensionConnectedMessage | MobileConnectedMessage | ProcessingStartedMessage | ProcessingCompletedMessage | ProcessingFailedMessage | SessionExpiredMessage | ConnectWebSocketMessage<string, unknown>;
+
+interface SessionConfig {
+    /**
+     * The name of the client.
+     */
+    name: string;
+    /**
+     * The URL of the client app which the chrome extension will communicate with.
+     */
+    app_url: string;
+    /**
+     * The URL of the client logo.
+     */
+    logo_url: string;
+    /**
+     * The onchain policy ID of the client.
+     */
+    policy_id: number;
+    /**
+     * The wallet address and chain ID of the user.
+     */
+    credential_config: {
+        chain_id: number;
+        wallet_address: string;
+    };
+    /**
+     * The short-lived browser token used to create backend sessions.
+     */
+    clientToken?: string;
+    /**
+     * Keyring Network configuration for the extension.
+     * @note this is meant to be used for internal testing and development purposes.
+     */
+    krn_config?: {
+        keyring_api_url?: string;
+        keyring_user_app_url?: string;
+        analytics_api_url?: string;
+        notaryUrl?: string;
+        websocketProxyUrl?: string;
+    };
+    dataTransport?: DataTransportType;
+    userJourney?: UserJourneyType;
+    websocket?: {
+        session_id: string;
+        session_token: string;
+    };
+}
+interface CredentialData {
+    trader: `0x${string}`;
+    policyId: number;
+    chainId: number;
+    validUntil: number;
+    cost: number;
+    key: string;
+    signature: string;
+    backdoor: string;
+}
+interface SDKError {
+    code: string;
+    message: string;
+    details?: any;
+}
+type SDKErrorCode = "BACKEND_UNAVAILABLE" | "SESSION_CREATION_FAILED" | "SESSION_NOT_FOUND" | "SESSION_EXPIRED" | "WEBSOCKET_CONNECTION_FAILED" | "WEBSOCKET_DISCONNECTED" | "PROCESSING_FAILED" | "NETWORK_ERROR" | "VALIDATION_ERROR" | "TIMEOUT_ERROR" | "QR_DISPLAY_NOT_SUPPORTED";
+interface SDKCallbacks {
+    onExtensionConnected?: (data: ExtensionConnectedMessage["data"]) => void;
+    onSessionCreated?: (data: SessionCreatedMessage["data"]) => void;
+    onMobileConnected?: (data: MobileConnectedMessage["data"]) => void;
+    onProcessingStarted?: (data: ProcessingStartedMessage["data"]) => void;
+    onProcessingCompleted?: (data: ProcessingCompletedMessage["data"]) => void;
+    onProcessingFailed?: (data: ProcessingFailedMessage["data"]) => void;
+    onSessionExpired?: (data: SessionExpiredMessage["data"]) => void;
+    onError?: (error: SDKError) => void;
+    onConnectionStatusChanged?: (connected: boolean) => void;
+}
+type SDKEventTypes = "sessionCreated" | "extensionConnected" | "mobileConnected" | "processingStarted" | "processingCompleted" | "processingFailed" | "sessionExpired" | "error" | "connectionStatusChanged";
+type SDKEventData = {
+    sessionCreated: SessionCreatedMessage["data"];
+    extensionConnected: ExtensionConnectedMessage["data"];
+    mobileConnected: MobileConnectedMessage["data"];
+    processingStarted: ProcessingStartedMessage["data"];
+    processingCompleted: ProcessingCompletedMessage["data"];
+    processingFailed: ProcessingFailedMessage["data"];
+    sessionExpired: SessionExpiredMessage["data"];
+    error: SDKError;
+    connectionStatusChanged: boolean;
+};
+
+interface CrossDeviceSession {
+    session_id: string;
+    session_token: string;
+    config: SessionConfig;
+    origin_url: string;
+    status: SessionStatus;
+    created_at: number | string;
+    expires_at: number | string;
+    result?: {
+        credential_data?: CredentialData;
+        entity_type?: string;
+        datasourceObject?: DatasourceTypes.DatasourceObject;
+    };
+    error?: string;
+    platform: "web" | "mobile";
+    qr_code_data: string;
+    connected_clients: {
+        web?: string;
+        mobile?: string;
+    };
+}
+
+/**
+ * Represents an active verification session with proper cleanup
+ */
+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 flowType;
+    private resultPromise?;
+    private resolveResult?;
+    private rejectResult?;
+    private closePromise?;
+    private resultSettled;
+    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;
+    private resolvePendingResult;
+    private rejectPendingResult;
+    private clearPendingResultHandlers;
+    private cleanup;
+    private resolveDataTransport;
+    private validateTransportRequirements;
+    private startChromeApiFlow;
+    /**
+     * Initialize mobile-specific resources (HTTP client, session, WebSocket)
+     */
+    private initializeSession;
+    private setupWebSocket;
+    private setupUI;
+    private showQR;
+    private showMobileModal;
+    /**
+     * Start HTTP polling as fallback when WebSocket is disconnected
+     */
+    private startPollingFallback;
+    private createSession;
+    private closeBackendSession;
+    private getSession;
+    /**
+     * Handle session updates from HTTP polling
+     */
+    private handlePollingUpdate;
+    private emit;
+}
+
+export { type AttestationStatus, type CredentialData, type CredentialStatus, type CrossDeviceSession, type ExtensionConnectedMessage, type ExtensionState, type MobileConnectedMessage, type ProcessingCompletedMessage, type ProcessingFailedMessage, type ProcessingStartedMessage, type SDKCallbacks, type SDKError, type SDKErrorCode, type SDKEventData, type SDKEventTypes, type SessionConfig, type SessionCreatedMessage, type SessionExpiredMessage, type User, VerificationSession, type WebSocketMessage };