@onekeyfe/hwk-ledger-adapter 1.1.26-alpha.14 → 1.1.26-alpha.20

package/dist/index.d.mts

@@ -6,26 +6,101 @@ import { SignerBtc as SignerBtc$1 } from '@ledgerhq/device-signer-kit-bitcoin';
 import { SignerSolana } from '@ledgerhq/device-signer-kit-solana';
 import Transport from '@ledgerhq/hw-transport';
 
-interface LedgerAdapterOptions {
-    /**
-     * `true` — emit `REQUEST_SELECT_DEVICE` on multi-device discovery and await
-     * `uiResponse({ type: RECEIVE_SELECT_DEVICE, payload: { sdkConnectId } })`.
-     * `false` (default) — silently pick the first device.
-     */
-    handleSelectDevice?: boolean;
+/**
+ * Re-export DMK types under local aliases for backward compatibility.
+ * These replace the previous duck-typed interfaces with the real SDK types.
+ */
+type DmkDiscoveredDevice = DiscoveredDevice;
+/**
+ * DMK DeviceAction — the Observable-based return type of all DMK signer methods.
+ *
+ * This is a permissive alias for `ExecuteDeviceActionReturnType` that accepts
+ * any Error and IntermediateValue generics. Signer wrapper code only cares about
+ * the Output type and the observable/cancel shape.
+ */
+type DeviceAction<T> = ExecuteDeviceActionReturnType<T, any, any>;
+/**
+ * DMK DeviceActionState — re-exported with permissive Error/IntermediateValue.
+ * The real type is a discriminated union on `status`.
+ */
+type DeviceActionState<T> = DeviceActionState$1<T, any, any>;
+/** ETH address result — re-exported from DMK for backward compatibility. */
+type SignerEvmAddress = Address;
+/** ETH signature result — re-exported from DMK for backward compatibility. */
+type SignerEvmSignature = Signature;
+/** BTC address result (WalletAddress not exported from DMK top-level). */
+interface SignerBtcAddress {
+    address: string;
+}
+
+/** Optional context attached to the rejection when a canceller fires. */
+interface CancelReason {
+    code?: number;
+    tag?: string;
+    message?: string;
+}
+/**
+ * Convert a DMK DeviceAction (Observable-based) into a Promise.
+ * Handles pending -> completed/error state transitions and interaction callbacks.
+ *
+ * Tracks the last DMK step observed (e.g. `signer.eth.steps.blindSignTransactionFallback`)
+ * and attaches it to the rejected error as a non-enumerable `_lastStep` property,
+ * so upstream error classifiers can distinguish failure contexts (e.g. Blind signing
+ * disabled vs. generic Invalid data).
+ *
+ * @param timeoutMs  Idle watchdog ms. Re-armed on each emission, paused
+ *                   during interactive pending. 0 disables. Default 65s
+ *                   (covers DMK's 60s + margin; we're a backstop only).
+ * @param onRegisterCanceller  Optional callback that receives a function which, when
+ *                             called, unsubscribes and cancels the underlying DeviceAction
+ *                             (releases DMK's IntentQueue slot). Caller is responsible
+ *                             for invoking the canceller on timeout/abort scenarios.
+ */
+declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void, onIntermediate?: (intermediateValue: unknown) => void): Promise<T>;
+
+interface AppMetadata {
+    versionName: string;
+    versionId: number;
+    version: string;
+    versionDisplayName: string | null;
+    description: string | null;
+    icon: string | null;
+    bytes: number | null;
+    currencyId: string | null;
+    isDevTools: boolean;
+}
+interface FirmwareVersion {
+    /** BOLOS version on the secure element — the user-facing firmware version. */
+    seVersion: string;
+    /** MCU SEPH (SE–MCU link protocol) version. */
+    mcuSephVersion: string;
+    /** MCU bootloader version. */
+    mcuBootloaderVersion: string;
+    /** Hardware revision (e.g. "00" / "01" on Nano X). */
+    hwVersion: string;
 }
+/** Full GetOsVersionResponse projected to a plain serializable shape. */
+interface LedgerDeviceInfo extends FirmwareVersion {
+    isBootloader: boolean;
+    isOsu: boolean;
+    targetId: number;
+    seTargetId?: number;
+    mcuTargetId?: number;
+    /** Secure element flags as hex string (raw bytes turned readable). */
+    seFlagsHex: string;
+}
+
 declare class LedgerAdapter implements IHardwareWallet {
     readonly vendor: "ledger";
     private readonly connector;
     private readonly emitter;
-    private readonly _handleSelectDevice;
     private _discoveredDevices;
     private _sessions;
     private readonly _uiRegistry;
     private _btcHighIndexConfirmedThisSession;
     private readonly _jobQueue;
     private _doConnectAbortController;
-    constructor(connector: IConnector, options?: LedgerAdapterOptions);
+    constructor(connector: IConnector);
     get activeTransport(): TransportType | null;
     getAvailableTransports(): TransportType[];
     switchTransport(_type: TransportType): Promise<void>;
@@ -39,6 +114,9 @@ declare class LedgerAdapter implements IHardwareWallet {
     dispose(): Promise<void>;
     uiResponse(response: UiResponseEvent): void;
     searchDevices(options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
+    /** Compact snapshot helpers for diagnostic logs. */
+    private _snapshotSessions;
+    private _snapshotDiscovered;
     private static readonly MAX_BUSINESS_RETRY_BUDGET;
     private static readonly STUCK_APP_RETRY_DELAY_MS;
     private static readonly MAX_DOCONNECT_CONFIRMS;
@@ -67,6 +145,11 @@ declare class LedgerAdapter implements IHardwareWallet {
     tronGetAddress(connectId: string, deviceId: string, params: TronGetAddressParams): Promise<Response<TronAddress>>;
     tronSignTransaction(connectId: string, deviceId: string, params: TronSignTxParams): Promise<Response<TronSignedTx>>;
     tronSignMessage(connectId: string, deviceId: string, params: TronSignMsgParams): Promise<Response<TronSignature>>;
+    installApp(connectId: string, appName: string): Promise<Response<void>>;
+    listInstalledApps(connectId: string): Promise<Response<AppMetadata[]>>;
+    listAvailableApps(connectId: string): Promise<Response<AppMetadata[]>>;
+    getLedgerFirmwareVersion(connectId: string): Promise<Response<FirmwareVersion>>;
+    getLedgerDeviceInfo(connectId: string): Promise<Response<LedgerDeviceInfo>>;
     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;
@@ -98,7 +181,7 @@ declare class LedgerAdapter implements IHardwareWallet {
      *
      * - 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.
+     * - Otherwise: search → 1 USB device: auto-connect, multiple USB devices: throw, 0: throw.
      */
     private _connectingPromise;
     private _waitForDeviceConnect;
@@ -115,7 +198,6 @@ declare class LedgerAdapter implements IHardwareWallet {
     private _doConnect;
     private _connectFirstOrSelect;
     private _connectDeviceOrThrow;
-    private _chooseDeviceFromList;
     /**
      * Call the connector with automatic session resolution and disconnect retry.
      *
@@ -178,33 +260,6 @@ declare class LedgerAdapter implements IHardwareWallet {
     private connectorDeviceToDeviceInfo;
 }
 
-/**
- * Re-export DMK types under local aliases for backward compatibility.
- * These replace the previous duck-typed interfaces with the real SDK types.
- */
-type DmkDiscoveredDevice = DiscoveredDevice;
-/**
- * DMK DeviceAction — the Observable-based return type of all DMK signer methods.
- *
- * This is a permissive alias for `ExecuteDeviceActionReturnType` that accepts
- * any Error and IntermediateValue generics. Signer wrapper code only cares about
- * the Output type and the observable/cancel shape.
- */
-type DeviceAction<T> = ExecuteDeviceActionReturnType<T, any, any>;
-/**
- * DMK DeviceActionState — re-exported with permissive Error/IntermediateValue.
- * The real type is a discriminated union on `status`.
- */
-type DeviceActionState<T> = DeviceActionState$1<T, any, any>;
-/** ETH address result — re-exported from DMK for backward compatibility. */
-type SignerEvmAddress = Address;
-/** ETH signature result — re-exported from DMK for backward compatibility. */
-type SignerEvmSignature = Signature;
-/** BTC address result (WalletAddress not exported from DMK top-level). */
-interface SignerBtcAddress {
-    address: string;
-}
-
 /**
  * Manages device discovery, connection, and session tracking.
  * Wraps DMK's Observable APIs into simpler imperative calls.
@@ -320,6 +375,7 @@ interface LedgerConnectorBaseOptions {
 declare class LedgerConnectorBase implements IConnector {
     private _deviceManager;
     private _signerManager;
+    private _deviceAppsManager;
     private _dmk;
     private readonly _eventHandlers;
     private readonly _providedDmk;
@@ -363,6 +419,7 @@ declare class LedgerConnectorBase implements IConnector {
      * enumerate() cache survives peripherals going offline.
      */
     protected _discoverDescriptors(dm: LedgerDeviceManager): Promise<DeviceDescriptor[]>;
+    private _assertSingleUsbDescriptor;
     searchDevices(): Promise<ConnectorDevice[]>;
     connect(deviceId?: string): Promise<ConnectorSession>;
     disconnect(sessionId: string): Promise<void>;
@@ -395,6 +452,7 @@ declare class LedgerConnectorBase implements IConnector {
     private _initManagers;
     private _getDeviceManager;
     private _getSignerManager;
+    private _getDeviceAppsManager;
     private _invalidateSession;
     /**
      * Replace an old session with a new one after app switch.
@@ -421,31 +479,6 @@ declare class LedgerConnectorBase implements IConnector {
     private _wrapError;
 }
 
-/** Optional context attached to the rejection when a canceller fires. */
-interface CancelReason {
-    code?: number;
-    tag?: string;
-    message?: string;
-}
-/**
- * Convert a DMK DeviceAction (Observable-based) into a Promise.
- * Handles pending -> completed/error state transitions and interaction callbacks.
- *
- * Tracks the last DMK step observed (e.g. `signer.eth.steps.blindSignTransactionFallback`)
- * and attaches it to the rejected error as a non-enumerable `_lastStep` property,
- * so upstream error classifiers can distinguish failure contexts (e.g. Blind signing
- * disabled vs. generic Invalid data).
- *
- * @param timeoutMs  Idle watchdog ms. Re-armed on each emission, paused
- *                   during interactive pending. 0 disables. Default 65s
- *                   (covers DMK's 60s + margin; we're a backstop only).
- * @param onRegisterCanceller  Optional callback that receives a function which, when
- *                             called, unsubscribes and cancels the underlying DeviceAction
- *                             (releases DMK's IntentQueue slot). Caller is responsible
- *                             for invoking the canceller on timeout/abort scenarios.
- */
-declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void): Promise<T>;
-
 /**
  * Wraps Ledger's SDK signer (Observable-based DeviceActions) into
  * a simple async interface returning plain serializable data.

package/dist/index.d.ts

@@ -6,26 +6,101 @@ import { SignerBtc as SignerBtc$1 } from '@ledgerhq/device-signer-kit-bitcoin';
 import { SignerSolana } from '@ledgerhq/device-signer-kit-solana';
 import Transport from '@ledgerhq/hw-transport';
 
-interface LedgerAdapterOptions {
-    /**
-     * `true` — emit `REQUEST_SELECT_DEVICE` on multi-device discovery and await
-     * `uiResponse({ type: RECEIVE_SELECT_DEVICE, payload: { sdkConnectId } })`.
-     * `false` (default) — silently pick the first device.
-     */
-    handleSelectDevice?: boolean;
+/**
+ * Re-export DMK types under local aliases for backward compatibility.
+ * These replace the previous duck-typed interfaces with the real SDK types.
+ */
+type DmkDiscoveredDevice = DiscoveredDevice;
+/**
+ * DMK DeviceAction — the Observable-based return type of all DMK signer methods.
+ *
+ * This is a permissive alias for `ExecuteDeviceActionReturnType` that accepts
+ * any Error and IntermediateValue generics. Signer wrapper code only cares about
+ * the Output type and the observable/cancel shape.
+ */
+type DeviceAction<T> = ExecuteDeviceActionReturnType<T, any, any>;
+/**
+ * DMK DeviceActionState — re-exported with permissive Error/IntermediateValue.
+ * The real type is a discriminated union on `status`.
+ */
+type DeviceActionState<T> = DeviceActionState$1<T, any, any>;
+/** ETH address result — re-exported from DMK for backward compatibility. */
+type SignerEvmAddress = Address;
+/** ETH signature result — re-exported from DMK for backward compatibility. */
+type SignerEvmSignature = Signature;
+/** BTC address result (WalletAddress not exported from DMK top-level). */
+interface SignerBtcAddress {
+    address: string;
+}
+
+/** Optional context attached to the rejection when a canceller fires. */
+interface CancelReason {
+    code?: number;
+    tag?: string;
+    message?: string;
+}
+/**
+ * Convert a DMK DeviceAction (Observable-based) into a Promise.
+ * Handles pending -> completed/error state transitions and interaction callbacks.
+ *
+ * Tracks the last DMK step observed (e.g. `signer.eth.steps.blindSignTransactionFallback`)
+ * and attaches it to the rejected error as a non-enumerable `_lastStep` property,
+ * so upstream error classifiers can distinguish failure contexts (e.g. Blind signing
+ * disabled vs. generic Invalid data).
+ *
+ * @param timeoutMs  Idle watchdog ms. Re-armed on each emission, paused
+ *                   during interactive pending. 0 disables. Default 65s
+ *                   (covers DMK's 60s + margin; we're a backstop only).
+ * @param onRegisterCanceller  Optional callback that receives a function which, when
+ *                             called, unsubscribes and cancels the underlying DeviceAction
+ *                             (releases DMK's IntentQueue slot). Caller is responsible
+ *                             for invoking the canceller on timeout/abort scenarios.
+ */
+declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void, onIntermediate?: (intermediateValue: unknown) => void): Promise<T>;
+
+interface AppMetadata {
+    versionName: string;
+    versionId: number;
+    version: string;
+    versionDisplayName: string | null;
+    description: string | null;
+    icon: string | null;
+    bytes: number | null;
+    currencyId: string | null;
+    isDevTools: boolean;
+}
+interface FirmwareVersion {
+    /** BOLOS version on the secure element — the user-facing firmware version. */
+    seVersion: string;
+    /** MCU SEPH (SE–MCU link protocol) version. */
+    mcuSephVersion: string;
+    /** MCU bootloader version. */
+    mcuBootloaderVersion: string;
+    /** Hardware revision (e.g. "00" / "01" on Nano X). */
+    hwVersion: string;
 }
+/** Full GetOsVersionResponse projected to a plain serializable shape. */
+interface LedgerDeviceInfo extends FirmwareVersion {
+    isBootloader: boolean;
+    isOsu: boolean;
+    targetId: number;
+    seTargetId?: number;
+    mcuTargetId?: number;
+    /** Secure element flags as hex string (raw bytes turned readable). */
+    seFlagsHex: string;
+}
+
 declare class LedgerAdapter implements IHardwareWallet {
     readonly vendor: "ledger";
     private readonly connector;
     private readonly emitter;
-    private readonly _handleSelectDevice;
     private _discoveredDevices;
     private _sessions;
     private readonly _uiRegistry;
     private _btcHighIndexConfirmedThisSession;
     private readonly _jobQueue;
     private _doConnectAbortController;
-    constructor(connector: IConnector, options?: LedgerAdapterOptions);
+    constructor(connector: IConnector);
     get activeTransport(): TransportType | null;
     getAvailableTransports(): TransportType[];
     switchTransport(_type: TransportType): Promise<void>;
@@ -39,6 +114,9 @@ declare class LedgerAdapter implements IHardwareWallet {
     dispose(): Promise<void>;
     uiResponse(response: UiResponseEvent): void;
     searchDevices(options?: SearchDevicesOptions): Promise<DeviceInfo[]>;
+    /** Compact snapshot helpers for diagnostic logs. */
+    private _snapshotSessions;
+    private _snapshotDiscovered;
     private static readonly MAX_BUSINESS_RETRY_BUDGET;
     private static readonly STUCK_APP_RETRY_DELAY_MS;
     private static readonly MAX_DOCONNECT_CONFIRMS;
@@ -67,6 +145,11 @@ declare class LedgerAdapter implements IHardwareWallet {
     tronGetAddress(connectId: string, deviceId: string, params: TronGetAddressParams): Promise<Response<TronAddress>>;
     tronSignTransaction(connectId: string, deviceId: string, params: TronSignTxParams): Promise<Response<TronSignedTx>>;
     tronSignMessage(connectId: string, deviceId: string, params: TronSignMsgParams): Promise<Response<TronSignature>>;
+    installApp(connectId: string, appName: string): Promise<Response<void>>;
+    listInstalledApps(connectId: string): Promise<Response<AppMetadata[]>>;
+    listAvailableApps(connectId: string): Promise<Response<AppMetadata[]>>;
+    getLedgerFirmwareVersion(connectId: string): Promise<Response<FirmwareVersion>>;
+    getLedgerDeviceInfo(connectId: string): Promise<Response<LedgerDeviceInfo>>;
     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;
@@ -98,7 +181,7 @@ declare class LedgerAdapter implements IHardwareWallet {
      *
      * - 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.
+     * - Otherwise: search → 1 USB device: auto-connect, multiple USB devices: throw, 0: throw.
      */
     private _connectingPromise;
     private _waitForDeviceConnect;
@@ -115,7 +198,6 @@ declare class LedgerAdapter implements IHardwareWallet {
     private _doConnect;
     private _connectFirstOrSelect;
     private _connectDeviceOrThrow;
-    private _chooseDeviceFromList;
     /**
      * Call the connector with automatic session resolution and disconnect retry.
      *
@@ -178,33 +260,6 @@ declare class LedgerAdapter implements IHardwareWallet {
     private connectorDeviceToDeviceInfo;
 }
 
-/**
- * Re-export DMK types under local aliases for backward compatibility.
- * These replace the previous duck-typed interfaces with the real SDK types.
- */
-type DmkDiscoveredDevice = DiscoveredDevice;
-/**
- * DMK DeviceAction — the Observable-based return type of all DMK signer methods.
- *
- * This is a permissive alias for `ExecuteDeviceActionReturnType` that accepts
- * any Error and IntermediateValue generics. Signer wrapper code only cares about
- * the Output type and the observable/cancel shape.
- */
-type DeviceAction<T> = ExecuteDeviceActionReturnType<T, any, any>;
-/**
- * DMK DeviceActionState — re-exported with permissive Error/IntermediateValue.
- * The real type is a discriminated union on `status`.
- */
-type DeviceActionState<T> = DeviceActionState$1<T, any, any>;
-/** ETH address result — re-exported from DMK for backward compatibility. */
-type SignerEvmAddress = Address;
-/** ETH signature result — re-exported from DMK for backward compatibility. */
-type SignerEvmSignature = Signature;
-/** BTC address result (WalletAddress not exported from DMK top-level). */
-interface SignerBtcAddress {
-    address: string;
-}
-
 /**
  * Manages device discovery, connection, and session tracking.
  * Wraps DMK's Observable APIs into simpler imperative calls.
@@ -320,6 +375,7 @@ interface LedgerConnectorBaseOptions {
 declare class LedgerConnectorBase implements IConnector {
     private _deviceManager;
     private _signerManager;
+    private _deviceAppsManager;
     private _dmk;
     private readonly _eventHandlers;
     private readonly _providedDmk;
@@ -363,6 +419,7 @@ declare class LedgerConnectorBase implements IConnector {
      * enumerate() cache survives peripherals going offline.
      */
     protected _discoverDescriptors(dm: LedgerDeviceManager): Promise<DeviceDescriptor[]>;
+    private _assertSingleUsbDescriptor;
     searchDevices(): Promise<ConnectorDevice[]>;
     connect(deviceId?: string): Promise<ConnectorSession>;
     disconnect(sessionId: string): Promise<void>;
@@ -395,6 +452,7 @@ declare class LedgerConnectorBase implements IConnector {
     private _initManagers;
     private _getDeviceManager;
     private _getSignerManager;
+    private _getDeviceAppsManager;
     private _invalidateSession;
     /**
      * Replace an old session with a new one after app switch.
@@ -421,31 +479,6 @@ declare class LedgerConnectorBase implements IConnector {
     private _wrapError;
 }
 
-/** Optional context attached to the rejection when a canceller fires. */
-interface CancelReason {
-    code?: number;
-    tag?: string;
-    message?: string;
-}
-/**
- * Convert a DMK DeviceAction (Observable-based) into a Promise.
- * Handles pending -> completed/error state transitions and interaction callbacks.
- *
- * Tracks the last DMK step observed (e.g. `signer.eth.steps.blindSignTransactionFallback`)
- * and attaches it to the rejected error as a non-enumerable `_lastStep` property,
- * so upstream error classifiers can distinguish failure contexts (e.g. Blind signing
- * disabled vs. generic Invalid data).
- *
- * @param timeoutMs  Idle watchdog ms. Re-armed on each emission, paused
- *                   during interactive pending. 0 disables. Default 65s
- *                   (covers DMK's 60s + margin; we're a backstop only).
- * @param onRegisterCanceller  Optional callback that receives a function which, when
- *                             called, unsubscribes and cancels the underlying DeviceAction
- *                             (releases DMK's IntentQueue slot). Caller is responsible
- *                             for invoking the canceller on timeout/abort scenarios.
- */
-declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: (reason?: CancelReason) => void) => void): Promise<T>;
-
 /**
  * Wraps Ledger's SDK signer (Observable-based DeviceActions) into
  * a simple async interface returning plain serializable data.