@qrlwallet/connect 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,409 @@
+import EventEmitter from 'eventemitter3';
+
+/** dApp metadata shown to user in approval UI */
+interface DAppMetadata {
+    name: string;
+    url: string;
+    icon?: string;
+}
+/** Stored session for reconnection */
+interface DAppSession {
+    channelId: string;
+    privateKey: string;
+    otherPublicKey: string | null;
+    dappMetadata: DAppMetadata;
+    connectedAccounts: string[];
+    chainId: string;
+    createdAt: number;
+    lastActivity: number;
+}
+/** Pending JSON-RPC request awaiting wallet response */
+interface PendingRequest {
+    id: string | number;
+    method: string;
+    params?: unknown[];
+    resolve: (result: unknown) => void;
+    reject: (error: Error) => void;
+    timestamp: number;
+}
+/** Key exchange message types */
+declare enum KeyExchangeMessageType {
+    SYN = "key_handshake_SYN",
+    SYNACK = "key_handshake_SYNACK",
+    ACK = "key_handshake_ACK"
+}
+/** Message types for the relay protocol */
+declare enum MessageType {
+    KEY_EXCHANGE = "key_exchange",
+    JSONRPC = "jsonrpc",
+    WALLET_INFO = "wallet_info",
+    ORIGINATOR_INFO = "originator_info",
+    TERMINATE = "terminate",
+    PING = "ping",
+    READY = "ready"
+}
+/** Wire message format sent through the relay */
+interface RelayMessage {
+    id: string;
+    clientType: 'dapp' | 'wallet';
+    message: string | object;
+    seq?: number;
+}
+/** Connection state */
+declare enum ConnectionStatus {
+    DISCONNECTED = "disconnected",
+    CONNECTING = "connecting",
+    WAITING = "waiting",
+    KEY_EXCHANGE = "key_exchange",
+    CONNECTED = "connected",
+    RECONNECTING = "reconnecting"
+}
+/** EIP-1193 provider events */
+interface ProviderEvents {
+    connect: (info: {
+        chainId: string;
+    }) => void;
+    disconnect: (error: {
+        code: number;
+        message: string;
+    }) => void;
+    chainChanged: (chainId: string) => void;
+    accountsChanged: (accounts: string[]) => void;
+    message: (message: {
+        type: string;
+        data: unknown;
+    }) => void;
+    statusChanged: (status: ConnectionStatus) => void;
+}
+/** JSON-RPC request */
+interface JsonRpcRequest {
+    jsonrpc?: string;
+    id?: string | number;
+    method: string;
+    params?: unknown[];
+}
+/** JSON-RPC response */
+interface JsonRpcResponse {
+    jsonrpc: string;
+    id: string | number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** QRL Connect configuration */
+interface QRLConnectOptions {
+    dappMetadata: DAppMetadata;
+    relayUrl?: string;
+    chainId?: string;
+    /** Auto-reconnect to stored session on init */
+    autoReconnect?: boolean;
+    /** Session storage key prefix */
+    storageKey?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+/**
+ * QRL Connect EIP-1193 Provider.
+ * Bridges JSON-RPC requests from dApp to QRL Wallet via the relay.
+ */
+
+declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
+    private connectionManager;
+    private pendingRequests;
+    private options;
+    readonly isQRLConnect = true;
+    constructor(options: QRLConnectOptions);
+    private setupConnectionListeners;
+    /**
+     * Generate a connection URI for QR code display or deep link redirect.
+     */
+    getConnectionURI(): Promise<string>;
+    /**
+     * Check if the current browser is mobile.
+     */
+    isMobile(): boolean;
+    /**
+     * Get the app store URL for the QRL Wallet app.
+     */
+    getAppStoreUrl(): string;
+    /**
+     * EIP-1193 request method.
+     */
+    request(args: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
+    /**
+     * Get the current connection status.
+     */
+    getStatus(): ConnectionStatus;
+    /**
+     * Get connected accounts.
+     */
+    getAccounts(): string[];
+    /**
+     * Get the channel ID for this connection.
+     */
+    getChannelId(): string;
+    /**
+     * Check if connected and keys exchanged.
+     */
+    isConnected(): boolean;
+    /**
+     * Check if a stored session exists that can be reconnected.
+     */
+    hasStoredSession(): boolean;
+    /**
+     * Reset the connection and start a fresh pairing with a new channel.
+     * Use this when the user wants to create a new connection instead of
+     * reconnecting to an existing session.
+     */
+    newConnection(): Promise<string>;
+    /**
+     * Disconnect from wallet and clean up.
+     */
+    disconnect(): void;
+}
+
+/**
+ * Connection Manager - Orchestrates socket connection, key exchange,
+ * and encrypted message routing. Manages session persistence and reconnection.
+ */
+
+interface ConnectionManagerEvents {
+    status_changed: (status: ConnectionStatus) => void;
+    accounts_changed: (accounts: string[]) => void;
+    chain_changed: (chainId: string) => void;
+    jsonrpc_response: (response: JsonRpcResponse) => void;
+    wallet_info: (info: {
+        accounts: string[];
+        chainId: string;
+    }) => void;
+    connection_lost: () => void;
+    error: (error: Error) => void;
+}
+declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
+    private socketClient;
+    private ecies;
+    private keyExchange;
+    private status;
+    private channelId;
+    private dappMetadata;
+    private chainId;
+    private relayUrl;
+    private connectedAccounts;
+    private storageKey;
+    private unresponsiveTimer;
+    private synRetryTimer;
+    private failedReconnects;
+    private synSent;
+    private synAttempts;
+    private walletPresent;
+    private static MAX_RECONNECT_FAILURES;
+    private static SYN_RETRY_MS;
+    private static MAX_SYN_ATTEMPTS;
+    constructor(options: {
+        dappMetadata: DAppMetadata;
+        relayUrl?: string;
+        chainId?: string;
+        storageKey?: string;
+    });
+    private setupSocketListeners;
+    private setupKeyExchangeListeners;
+    /**
+     * Generate the connection URI and start listening for wallet connection.
+     */
+    getConnectionURI(retryOnConflict?: boolean): Promise<string>;
+    /**
+     * Reconnect to an existing session.
+     */
+    reconnect(): Promise<boolean>;
+    /**
+     * Send a JSON-RPC request to the wallet.
+     */
+    sendJsonRpc(request: JsonRpcRequest): void;
+    /**
+     * Handle an incoming relay message.
+     */
+    private handleRelayMessage;
+    private handleKeyExchangeMessage;
+    private handleDecryptedMessage;
+    /** Send a plaintext (unencrypted) message through the relay. */
+    private sendPlaintext;
+    /** Send an encrypted message through the relay. */
+    private sendEncrypted;
+    private startUnresponsiveTimer;
+    private clearUnresponsiveTimer;
+    private sendSYN;
+    private scheduleSynRetry;
+    private clearSynRetryTimer;
+    private setStatus;
+    private isDappParticipantConflictError;
+    private areArraysEqual;
+    getStatus(): ConnectionStatus;
+    getAccounts(): string[];
+    getChainId(): string;
+    getChannelId(): string;
+    /** Check if a stored session exists (without loading/restoring it). */
+    hasStoredSession(): boolean;
+    /**
+     * Reset the connection and create a new channel for a fresh pairing.
+     * Disconnects any existing session, generates a new channel ID and keys.
+     */
+    resetForNewChannel(): void;
+    /** Disconnect and clean up. */
+    disconnect(): void;
+    private saveSession;
+    private loadSession;
+    private clearSession;
+}
+
+/**
+ * ECIES encryption/decryption client.
+ * Adapted from MetaMask SDK's ECIES.ts pattern.
+ */
+declare class ECIESClient {
+    private privateKey;
+    constructor(existingPrivateKey?: string);
+    /** Get public key as hex string */
+    getPublicKey(): string;
+    /** Get private key as hex string (for session persistence) */
+    getPrivateKeyHex(): string;
+    /** Encrypt a string message for the given public key. Returns base64. */
+    encrypt(data: string, otherPublicKey: string): string;
+    /** Decrypt a base64-encoded message using our private key. */
+    decrypt(encryptedBase64: string): string;
+}
+
+/**
+ * Key Exchange - 3-step SYN/SYNACK/ACK handshake protocol.
+ * Adapted from MetaMask SDK's KeyExchange.ts.
+ */
+
+interface KeyExchangeEvents {
+    keys_exchanged: () => void;
+    step_change: (step: KeyExchangeMessageType) => void;
+}
+declare class KeyExchange extends EventEmitter<KeyExchangeEvents> {
+    private ecies;
+    private otherPublicKey;
+    private keysExchanged;
+    private awaitingSynAck;
+    private awaitingAck;
+    private step;
+    private isOriginator;
+    constructor(ecies: ECIESClient, isOriginator: boolean, otherPublicKey?: string);
+    /** Get the SYN message to start the handshake (originator/dApp side). */
+    createSYN(): object;
+    /**
+     * Process an incoming key exchange message.
+     * Returns a response message to send back, or null if handshake is complete.
+     */
+    onMessage(message: {
+        type: KeyExchangeMessageType;
+        pubkey?: string;
+        v?: number;
+    }): object | null;
+    /** Encrypt a message for the counterparty. */
+    encryptMessage(data: string): string;
+    /** Decrypt a message from the counterparty. */
+    decryptMessage(encryptedBase64: string): string;
+    /** Reset key exchange state for a fresh handshake (e.g. new QR code). */
+    reset(): void;
+    areKeysExchanged(): boolean;
+    getOtherPublicKey(): string | null;
+    getCurrentStep(): KeyExchangeMessageType;
+}
+
+/**
+ * Socket.IO client wrapper for relay communication.
+ */
+
+interface SocketClientEvents {
+    message: (data: RelayMessage) => void;
+    connected: () => void;
+    disconnected: (reason: string) => void;
+    reconnected: () => void;
+    participants_changed: (data: {
+        event: string;
+        clientType?: string;
+    }) => void;
+    error: (err: Error) => void;
+}
+declare class SocketClient extends EventEmitter<SocketClientEvents> {
+    private socket;
+    private relayUrl;
+    private channelId;
+    private clientType;
+    private seq;
+    private pendingJoin;
+    constructor(relayUrl: string, clientType: 'dapp' | 'wallet');
+    /**
+     * Connect to the relay server.
+     */
+    connect(): void;
+    /**
+     * Join a relay channel.
+     */
+    joinChannel(channelId: string): Promise<{
+        bufferedMessages: unknown[];
+    }>;
+    private joinChannelNow;
+    /**
+     * Send a message through the relay.
+     */
+    sendMessage(data: RelayMessage): Promise<{
+        success: boolean;
+        buffered: boolean;
+    }>;
+    /**
+     * Leave the current channel.
+     */
+    leaveChannel(): void;
+    /**
+     * Disconnect from the relay.
+     */
+    disconnect(): void;
+    isConnected(): boolean;
+    getChannelId(): string | null;
+}
+
+interface QRConnectParams {
+    channelId: string;
+    pubKey: string;
+    name: string;
+    url: string;
+    icon?: string;
+    chainId: string;
+    relayUrl: string;
+}
+/**
+ * Generate a qrlconnect:// URI for QR code or deep link.
+ */
+declare function generateConnectionURI(params: QRConnectParams): string;
+/**
+ * Parse a qrlconnect:// URI back into its components.
+ */
+declare function parseConnectionURI(uri: string): QRConnectParams | null;
+
+/**
+ * Detect if the current browser is on a mobile device.
+ */
+declare function isMobileBrowser(): boolean;
+/**
+ * Check if the QRL Wallet app is likely installed by attempting a deep link.
+ * Falls back to app store URL after timeout.
+ */
+declare function getAppStoreUrl(): string;
+
+declare const DEFAULT_RELAY_URL = "https://qrlwallet.com";
+/** RPC methods that require user approval in the wallet */
+declare const RESTRICTED_METHODS: Set<string>;
+/** RPC methods that can be auto-proxied without approval */
+declare const UNRESTRICTED_METHODS: Set<string>;
+
+export { ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, ECIESClient, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, MessageType, type PendingRequest, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, RESTRICTED_METHODS, type RelayMessage, SocketClient, UNRESTRICTED_METHODS, generateConnectionURI, getAppStoreUrl, isMobileBrowser, parseConnectionURI };