@bytezhang/ledger-adapter 0.0.6 → 0.0.8

package/dist/index.d.ts

@@ -1,406 +0,0 @@
-import { IHardwareWallet, IConnector, TransportType, IUiHandler, DeviceInfo, Response, ChainCapability, HardwareEventMap, DeviceEventListener, EvmGetAddressParams, EvmAddress, ProgressCallback, EvmGetPublicKeyParams, EvmPublicKey, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolGetPublicKeyParams, SolPublicKey, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, DeviceDescriptor, DeviceChangeEvent, HardwareErrorCode } from '@bytezhang/hardware-wallet-core';
-
-/**
- * Ledger hardware wallet adapter that delegates to an IConnector.
- *
- * This is a thin translation layer that:
- * - Accepts a pre-configured IConnector (transport decisions are made at connector creation time)
- * - Translates IHardwareWallet method calls to connector.call() invocations
- * - Maps connector results/errors to our Response<T> format with enriched error messages
- * - Translates connector events to HardwareEventMap events
- * - Integrates with IUiHandler for permission flows
- */
-declare class LedgerAdapter implements IHardwareWallet {
-    readonly vendor: "ledger";
-    private readonly connector;
-    private readonly emitter;
-    private _uiHandler;
-    private _discoveredDevices;
-    private _sessions;
-    constructor(connector: IConnector);
-    get activeTransport(): TransportType | null;
-    getAvailableTransports(): TransportType[];
-    switchTransport(_type: TransportType): Promise<void>;
-    setUiHandler(handler: Partial<IUiHandler>): void;
-    init(_config?: unknown): Promise<void>;
-    dispose(): Promise<void>;
-    searchDevices(): Promise<DeviceInfo[]>;
-    connectDevice(connectId: string): Promise<Response<string>>;
-    disconnectDevice(connectId: string): Promise<void>;
-    getDeviceInfo(connectId: string, deviceId: string): Promise<Response<DeviceInfo>>;
-    getSupportedChains(): ChainCapability[];
-    on<K extends keyof HardwareEventMap>(event: K, listener: (event: HardwareEventMap[K]) => void): void;
-    on(event: string, listener: DeviceEventListener): void;
-    off<K extends keyof HardwareEventMap>(event: K, listener: (event: HardwareEventMap[K]) => void): void;
-    off(event: string, listener: DeviceEventListener): void;
-    cancel(connectId: string): void;
-    evmGetAddress(connectId: string, _deviceId: string, params: EvmGetAddressParams): Promise<Response<EvmAddress>>;
-    evmGetAddresses(connectId: string, deviceId: string, params: EvmGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<EvmAddress[]>>;
-    evmGetPublicKey(connectId: string, _deviceId: string, params: EvmGetPublicKeyParams): Promise<Response<EvmPublicKey>>;
-    evmSignTransaction(connectId: string, _deviceId: string, params: EvmSignTxParams): Promise<Response<EvmSignedTx>>;
-    evmSignMessage(connectId: string, _deviceId: string, params: EvmSignMsgParams): Promise<Response<EvmSignature>>;
-    evmSignTypedData(connectId: string, _deviceId: string, params: EvmSignTypedDataParams): Promise<Response<EvmSignature>>;
-    btcGetAddress(connectId: string, _deviceId: string, params: BtcGetAddressParams): Promise<Response<BtcAddress>>;
-    btcGetAddresses(connectId: string, deviceId: string, params: BtcGetAddressParams[], onProgress?: ProgressCallback): Promise<Response<BtcAddress[]>>;
-    btcGetPublicKey(connectId: string, _deviceId: string, params: BtcGetPublicKeyParams): Promise<Response<BtcPublicKey>>;
-    btcSignTransaction(connectId: string, _deviceId: string, params: BtcSignTxParams): Promise<Response<BtcSignedTx>>;
-    btcSignMessage(_connectId: string, _deviceId: string, _params: BtcSignMsgParams): Promise<Response<BtcSignature>>;
-    btcGetMasterFingerprint(connectId: string, _deviceId: string, params?: {
-        skipOpenApp?: boolean;
-    }): Promise<Response<{
-        masterFingerprint: string;
-    }>>;
-    solGetAddress(_connectId: string, _deviceId: string, _params: SolGetAddressParams): Promise<Response<SolAddress>>;
-    solGetAddresses(_connectId: string, _deviceId: string, _params: SolGetAddressParams[], _onProgress?: ProgressCallback): Promise<Response<SolAddress[]>>;
-    solGetPublicKey(_connectId: string, _deviceId: string, _params: SolGetPublicKeyParams): Promise<Response<SolPublicKey>>;
-    solSignTransaction(_connectId: string, _deviceId: string, _params: SolSignTxParams): Promise<Response<SolSignedTx>>;
-    solSignMessage(_connectId: string, _deviceId: string, _params: SolSignMsgParams): Promise<Response<SolSignature>>;
-    /**
-     * Ensure at least one device is connected and return a valid connectId.
-     *
-     * - If a session already exists for the given connectId, reuse it.
-     * - If ANY session exists (Ledger IDs are ephemeral), reuse it.
-     * - Otherwise: search → 1 device: auto-connect, multiple: ask user, 0: throw.
-     */
-    private static readonly MAX_DEVICE_RETRY;
-    private _deviceConnectResolve;
-    private static readonly DEVICE_CONNECT_TIMEOUT_MS;
-    /**
-     * Wait for user to connect and unlock device.
-     * Emits 'ui-request' event via the adapter's own emitter.
-     * The consumer (monorepo adapter wrapper) listens for this and shows UI.
-     * When user confirms, they call adapter.deviceConnectResponse() which resolves this promise.
-     * Times out after 60 seconds if no response is received.
-     */
-    private _waitForDeviceConnect;
-    /**
-     * Called by consumer to respond to ui-request-device-connect.
-     * type='confirm' → retry search, type='cancel' → abort.
-     */
-    deviceConnectResponse(type: 'confirm' | 'cancel'): void;
-    private ensureConnected;
-    private _connectFirstOrSelect;
-    /**
-     * Call the connector with automatic session resolution and disconnect retry.
-     *
-     * 1. Resolves a valid connectId via ensureConnected()
-     * 2. Looks up sessionId from _sessions
-     * 3. Calls connector.call()
-     * 4. On disconnect error: clears stale session, re-connects, retries once
-     */
-    private connectorCall;
-    /**
-     * Ensure device permission before proceeding.
-     * - No connectId (searchDevices): check environment-level permission
-     * - With connectId (business methods): check device-level permission
-     * If not granted, calls onDevicePermission so the consumer can request access.
-     */
-    private _ensureDevicePermission;
-    /**
-     * Convert a thrown error to a Response failure.
-     * Uses mapLedgerError to parse Ledger DMK error codes into HardwareErrorCode values.
-     */
-    private errorToFailure;
-    /**
-     * Generic batch call with progress reporting.
-     * If any single call fails, returns the failure immediately.
-     */
-    private batchCall;
-    private deviceConnectHandler;
-    private deviceDisconnectHandler;
-    private uiRequestHandler;
-    private uiEventHandler;
-    private registerEventListeners;
-    private unregisterEventListeners;
-    private handleUiEvent;
-    private connectorDeviceToDeviceInfo;
-    private extractDeviceInfoFromPayload;
-    private unknownDevice;
-}
-
-interface DmkDiscoveredDevice {
-    id: string;
-    deviceModel: {
-        id: string;
-        productName: string;
-        model: string;
-        name: string;
-    };
-    transport: string;
-    [key: string]: unknown;
-}
-interface IDmk {
-    startDiscovering(args?: {
-        transport?: string;
-    }): {
-        subscribe(observer: {
-            next: (device: DmkDiscoveredDevice) => void;
-            error?: (err: unknown) => void;
-        }): {
-            unsubscribe: () => void;
-        };
-    };
-    stopDiscovering(): void;
-    listenToAvailableDevices(args?: {
-        transport?: string;
-    }): {
-        subscribe(observer: {
-            next: (devices: DmkDiscoveredDevice[]) => void;
-            error?: (err: unknown) => void;
-        }): {
-            unsubscribe: () => void;
-        };
-    };
-    connect(params: {
-        device: DmkDiscoveredDevice;
-    }): Promise<string>;
-    disconnect(params: {
-        sessionId: string;
-    }): Promise<void>;
-    sendCommand(params: {
-        sessionId: string;
-        command: unknown;
-    }): Promise<unknown>;
-    close?(): void;
-}
-interface DeviceActionState$1<T> {
-    status: 'pending' | 'completed' | 'error';
-    output?: T;
-    error?: unknown;
-    intermediateValue?: {
-        requiredUserInteraction?: string;
-        [key: string]: unknown;
-    };
-}
-interface SignerEvmAddress {
-    address: string;
-    publicKey: string;
-}
-interface SignerEvmSignature {
-    r: string;
-    s: string;
-    v: number;
-}
-interface SignerBtcAddress {
-    address: string;
-}
-interface TransportProviderOptions {
-    logger?: unknown;
-}
-interface TransportProviderInstance {
-    dmk: IDmk;
-    dispose?: () => Promise<void>;
-}
-interface TransportProvider {
-    create(options?: TransportProviderOptions): TransportProviderInstance;
-}
-
-/**
- * Manages device discovery, connection, and session tracking.
- * Wraps DMK's Observable APIs into simpler imperative calls.
- */
-declare class LedgerDeviceManager {
-    private readonly _dmk;
-    private readonly _discovered;
-    private readonly _sessions;
-    private readonly _sessionToDevice;
-    private _listenSub;
-    constructor(dmk: IDmk);
-    /**
-     * One-shot enumeration: subscribe to listenToAvailableDevices,
-     * take the first emission, unsubscribe, return DeviceDescriptors.
-     */
-    enumerate(): Promise<DeviceDescriptor[]>;
-    /**
-     * Continuous listening: tracks device connect/disconnect via diffing.
-     */
-    listen(onChange: (event: DeviceChangeEvent) => void): void;
-    stopListening(): void;
-    /**
-     * Trigger browser device selection (WebHID requestDevice).
-     * Starts discovery for a short period, then stops.
-     */
-    requestDevice(timeoutMs?: number): Promise<void>;
-    /** Connect to a previously discovered device. Returns sessionId. */
-    connect(deviceId: string): Promise<string>;
-    /** Disconnect a session. */
-    disconnect(sessionId: string): Promise<void>;
-    getSessionId(deviceId: string): string | undefined;
-    getDeviceId(sessionId: string): string | undefined;
-    /** Get the underlying DMK instance (needed by SignerManager). */
-    getDmk(): IDmk;
-    dispose(): void;
-}
-
-/**
- * SDK signer interface — duck-typed to avoid hard dependency on
- * @ledgerhq/device-signer-kit-ethereum.
- */
-interface ISdkSignerEth {
-    getAddress(derivationPath: string, options?: {
-        checkOnDevice?: boolean;
-    }): unknown;
-    signTransaction(derivationPath: string, transaction: Uint8Array, options?: unknown): unknown;
-    signMessage(derivationPath: string, message: string): unknown;
-    signTypedData(derivationPath: string, data: unknown): unknown;
-}
-/**
- * Wraps Ledger's SDK signer (Observable-based DeviceActions) into
- * a simple async interface returning plain serializable data.
- */
-declare class SignerEth {
-    private readonly _sdk;
-    onInteraction?: (interaction: string) => void;
-    constructor(_sdk: ISdkSignerEth);
-    getAddress(derivationPath: string, options?: {
-        checkOnDevice?: boolean;
-    }): Promise<SignerEvmAddress>;
-    signTransaction(derivationPath: string, serializedTxHex: string): Promise<SignerEvmSignature>;
-    signMessage(derivationPath: string, message: string): Promise<SignerEvmSignature>;
-    signTypedData(derivationPath: string, data: unknown): Promise<SignerEvmSignature>;
-}
-
-type SignerEthBuilderFn = (args: {
-    dmk: IDmk;
-    sessionId: string;
-}) => {
-    build(): unknown;
-} | Promise<{
-    build(): unknown;
-}>;
-/**
- * Manages per-sessionId SignerEth instances.
- * Creates on demand, caches for reuse, invalidates on session change.
- */
-declare class SignerManager {
-    private readonly _cache;
-    private readonly _dmk;
-    private readonly _builderFn;
-    constructor(dmk: IDmk, builderFn?: SignerEthBuilderFn);
-    getOrCreate(sessionId: string): Promise<SignerEth>;
-    invalidate(sessionId: string): void;
-    clearAll(): void;
-    private static _defaultBuilder;
-}
-
-/**
- * SDK BTC signer interface — duck-typed to avoid hard dependency on
- * @ledgerhq/device-signer-kit-bitcoin.
- */
-interface ISdkSignerBtc {
-    getExtendedPublicKey(derivationPath: string, options?: {
-        checkOnDevice?: boolean;
-    }): unknown;
-    getWalletAddress(wallet: unknown, addressIndex: number, options?: {
-        checkOnDevice?: boolean;
-        change?: boolean;
-    }): unknown;
-    getMasterFingerprint(options?: {
-        skipOpenApp?: boolean;
-    }): unknown;
-}
-/**
- * Wraps Ledger's BTC SDK signer (Observable-based DeviceActions) into
- * a simple async interface returning plain serializable data.
- */
-declare class SignerBtc {
-    private readonly _sdk;
-    onInteraction?: (interaction: string) => void;
-    constructor(_sdk: ISdkSignerBtc);
-    getWalletAddress(wallet: unknown, addressIndex: number, options?: {
-        checkOnDevice?: boolean;
-        change?: boolean;
-    }): Promise<SignerBtcAddress>;
-    getExtendedPublicKey(derivationPath: string, options?: {
-        checkOnDevice?: boolean;
-    }): Promise<string>;
-    getMasterFingerprint(options?: {
-        skipOpenApp?: boolean;
-    }): Promise<Uint8Array>;
-}
-
-/** DeviceAction state emitted by DMK signer operations. */
-interface DeviceActionState<T> {
-    status: 'pending' | 'completed' | 'error';
-    output?: T;
-    error?: unknown;
-    intermediateValue?: {
-        requiredUserInteraction?: string;
-        [key: string]: unknown;
-    };
-}
-/**
- * Convert a DMK DeviceAction (Observable-based) into a Promise.
- * Handles pending → completed/error state transitions and interaction callbacks.
- */
-declare function deviceActionToPromise<T>(action: {
-    observable: {
-        subscribe(observer: {
-            next: (value: DeviceActionState<T>) => void;
-            error?: (err: unknown) => void;
-            complete?: () => void;
-        }): {
-            unsubscribe: () => void;
-        };
-    };
-}, onInteraction?: (interaction: string) => void): Promise<T>;
-
-declare function registerTransport(type: string, provider: TransportProvider): void;
-declare function unregisterTransport(type: string): void;
-declare function getTransportProvider(type: string): TransportProvider | null;
-declare function listRegisteredTransports(): string[];
-declare function clearRegistry(): void;
-
-interface AppManagerOptions {
-    waitMs?: number;
-    maxRetries?: number;
-}
-/**
- * Orchestrates opening / closing Ledger on-device apps so that the
- * correct signer application is running before any signing call.
- */
-declare class AppManager {
-    private readonly _dmk;
-    private readonly _waitMs;
-    private readonly _maxRetries;
-    constructor(dmk: IDmk, options?: AppManagerOptions);
-    /**
-     * Return the Ledger app name for a given chain ticker,
-     * or undefined if the chain is not supported.
-     */
-    static getAppName(chain: string): string | undefined;
-    /**
-     * Ensure the target app is open on the device identified by `sessionId`.
-     *
-     * Flow:
-     * 1. Check the currently running app.
-     * 2. If it is already the target, return immediately.
-     * 3. If a different app is running (not dashboard), close it first.
-     * 4. Open the target app.
-     * 5. Poll until the device confirms the target app is running.
-     */
-    ensureAppOpen(sessionId: string, targetAppName: string): Promise<void>;
-    private _getCurrentApp;
-    private _openApp;
-    private _closeCurrentApp;
-    /**
-     * Poll the device until the expected app is reported as running,
-     * or throw after `_maxRetries` attempts.
-     */
-    private _waitForApp;
-    private _isDashboard;
-    private _wait;
-}
-
-/** Check if an error (or any error in its chain) represents a locked Ledger device. */
-declare function isDeviceLockedError(err: unknown): boolean;
-/**
- * Map a Ledger DMK error to a HardwareErrorCode and human-readable message
- * with actionable recovery information for the caller.
- */
-declare function mapLedgerError(err: unknown): {
-    code: HardwareErrorCode;
-    message: string;
-};
-
-export { AppManager, type DeviceActionState$1 as DeviceActionState, type DmkDiscoveredDevice, type IDmk, LedgerAdapter, LedgerDeviceManager, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, type TransportProvider, type TransportProviderInstance, type TransportProviderOptions, clearRegistry, deviceActionToPromise, getTransportProvider, isDeviceLockedError, listRegisteredTransports, mapLedgerError, registerTransport, unregisterTransport };