@onekeyfe/hwk-ledger-adapter 1.1.26-alpha.106 → 1.1.26-alpha.4

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { IHardwareWallet, IConnector, TransportType, IUiHandler, UiResponseEvent, DeviceInfo, Response, ChainCapability, EvmGetAddressParams, EvmAddress, ProgressCallback, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, ChainForFingerprint, ConnectionType, DeviceDescriptor, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, DeviceChangeEvent, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
+import { IHardwareWallet, IConnector, TransportType, IUiHandler, UiResponseEvent, DeviceInfo, Response, ChainCapability, EvmGetAddressParams, EvmAddress, ProgressCallback, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, ChainForFingerprint, ConnectionType, DeviceDescriptor, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, DeviceChangeEvent, Failure, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
 import { DeviceManagementKit, DeviceActionState as DeviceActionState$1, DiscoveredDevice, ExecuteDeviceActionReturnType } from '@ledgerhq/device-management-kit';
 import { Address, Signature, SignerEth as SignerEth$1, TypedData } from '@ledgerhq/device-signer-kit-ethereum';
 import { SignerBtc as SignerBtc$1 } from '@ledgerhq/device-signer-kit-bitcoin';
@@ -32,7 +32,15 @@ declare class LedgerAdapter implements IHardwareWallet {
     private _discoveredDevices;
     private _sessions;
     private readonly _uiRegistry;
+    private readonly _jobQueue;
     constructor(connector: IConnector, options?: LedgerAdapterOptions);
+    /**
+     * Classify a method's interruptibility.
+     * - Signing / typed data / transaction → 'confirm' (user may decide via preemption UI)
+     * - Read-only queries (getAddress / getPublicKey / getMasterFingerprint) → 'safe'
+     *   (auto-cancels any pending read for the same device)
+     */
+    private static _getInterruptibility;
     get activeTransport(): TransportType | null;
     getAvailableTransports(): TransportType[];
     switchTransport(_type: TransportType): Promise<void>;
@@ -128,6 +136,16 @@ declare class LedgerAdapter implements IHardwareWallet {
      * 4. On disconnect error: clears stale session, re-connects, retries once
      */
     private connectorCall;
+    /**
+     * Race a promise against an abort signal. If the signal fires, rejects with the
+     * signal's reason (or a generic Error). The underlying connector.call() cannot
+     * actually be cancelled on Ledger DMK, but the caller gets the abort immediately.
+     */
+    private static _abortable;
+    /** Throw an AbortError if signal is already aborted. */
+    private static _throwIfAborted;
+    /** Actual work done under the job queue — connection, fingerprint, call, and recovery. */
+    private _runConnectorCall;
     /** Clear stale session, reconnect, and retry the call. */
     private _retryWithFreshConnection;
     /**
@@ -188,7 +206,7 @@ declare class LedgerConnectorBase implements IConnector {
     private readonly _eventHandlers;
     private readonly _providedDmk;
     private readonly _createTransport;
-    private readonly _connectionType;
+    readonly connectionType: ConnectionType;
     private _connectIdToPath;
     private _pathToConnectId;
     /** Register a connectId <-> path mapping from a device descriptor. */
@@ -197,6 +215,7 @@ declare class LedgerConnectorBase implements IConnector {
     private _getPathForConnectId;
     /** Get external connectId from DMK path. Falls back to path itself. */
     private _getConnectIdForPath;
+    private readonly _cancellers;
     /**
      * Resolves a Ledger signer kit module by package name.
      * Override via constructor to use CJS paths for Metro (React Native).
@@ -225,7 +244,7 @@ declare class LedgerConnectorBase implements IConnector {
     connect(deviceId?: string): Promise<ConnectorSession>;
     disconnect(sessionId: string): Promise<void>;
     call(sessionId: string, method: string, params: unknown): Promise<unknown>;
-    cancel(_sessionId: string): Promise<void>;
+    cancel(sessionId: string): Promise<void>;
     uiResponse(_response: UiResponseEvent): void;
     on<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
     off<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
@@ -335,6 +354,12 @@ declare class SignerEth {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
     constructor(_sdk: SignerEth$1);
+    /**
+     * Optional callback registered per-call so the caller can obtain a canceller
+     * for the underlying DeviceAction. Caller can invoke it to release DMK's
+     * IntentQueue slot and unsubscribe from the action's observable.
+     */
+    onRegisterCanceller?: (cancel: () => void) => void;
     getAddress(derivationPath: string, options?: {
         checkOnDevice?: boolean;
     }): Promise<SignerEvmAddress>;
@@ -352,16 +377,16 @@ type SignerEthBuilderFn = (args: {
     build(): SignerEth$1;
 }>;
 /**
- * Manages per-sessionId SignerEth instances.
- * Creates on demand, caches for reuse, invalidates on session change.
+ * Per-sessionId SignerEth factory. Builds fresh on every call — DMK signers
+ * hold DeviceAction state that isn't safe to reuse, so `invalidate` /
+ * `clearAll` are kept as no-op lifecycle hooks for callers.
  */
 declare class SignerManager {
-    private readonly _cache;
     private readonly _dmk;
     private readonly _builderFn;
     constructor(dmk: DeviceManagementKit, builderFn?: SignerEthBuilderFn);
     getOrCreate(sessionId: string): Promise<SignerEth>;
-    invalidate(sessionId: string): void;
+    invalidate(_sessionId: string): void;
     clearAll(): void;
     private static _defaultBuilder;
 }
@@ -377,6 +402,7 @@ type BtcMessageOptions = Parameters<SignerBtc$1['signMessage']>[2];
 declare class SignerBtc {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
+    onRegisterCanceller?: (cancel: () => void) => void;
     constructor(_sdk: SignerBtc$1);
     getWalletAddress(wallet: BtcWallet, addressIndex: number, options?: {
         checkOnDevice?: boolean;
@@ -422,6 +448,7 @@ type SolMsgOptions = Parameters<SignerSolana['signMessage']>[2];
 declare class SignerSol {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
+    onRegisterCanceller?: (cancel: () => void) => void;
     constructor(_sdk: SignerSolana);
     /**
      * Get the Solana address (base58-encoded Ed25519 public key) at the given derivation path.
@@ -473,8 +500,12 @@ declare class DmkTransport extends Transport {
  *
  * @param timeoutMs  Timeout in ms. Resets each time the Observable emits (device is alive).
  *                   Pass 0 to disable. Default: 30s.
+ * @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): Promise<T>;
+declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: () => void) => void): Promise<T>;
 
 interface AppManagerOptions {
     waitMs?: number;
@@ -522,6 +553,21 @@ declare class AppManager {
     private _wait;
 }
 
+/**
+ * Ledger-specific Failure: adds `appName` for "the currently-open app" — a
+ * Ledger hardware concept not shared with other vendors, so it lives here
+ * rather than in core's generic Failure.
+ */
+type LedgerFailure = Omit<Failure, 'payload'> & {
+    payload: Failure['payload'] & {
+        appName?: string;
+    };
+};
+/**
+ * Structurally compatible with `Failure`; writes `appName` only when provided,
+ * so `'appName' in payload` is a reliable "has info" signal for consumers.
+ */
+declare function ledgerFailure(code: HardwareErrorCode, error: string, appName?: string): LedgerFailure;
 /** Check if an error (or any error in its chain) represents a locked Ledger device. */
 declare function isDeviceLockedError(err: unknown): boolean;
 /**
@@ -534,4 +580,14 @@ declare function mapLedgerError(err: unknown): {
     appName?: string;
 };
 
-export { AppManager, type DeviceActionState, type DmkDiscoveredDevice, DmkTransport, LedgerAdapter, LedgerConnectorBase, type LedgerConnectorBaseOptions, LedgerDeviceManager, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, SignerSol, type TransportFactory, deviceActionToPromise, isDeviceLockedError, mapLedgerError };
+/**
+ * Centralised debug logger for the Ledger adapter.
+ *
+ * Off by default. Toggle programmatically via `setDebugEnabled(true)`.
+ */
+/** Enable or disable debug logging at runtime. */
+declare function setDebugEnabled(value: boolean): void;
+/** Returns the current debug-enabled state. */
+declare function isDebugEnabled(): boolean;
+
+export { AppManager, type DeviceActionState, type DmkDiscoveredDevice, DmkTransport, LedgerAdapter, LedgerConnectorBase, type LedgerConnectorBaseOptions, LedgerDeviceManager, type LedgerFailure, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, SignerSol, type TransportFactory, deviceActionToPromise, isDebugEnabled, isDeviceLockedError, ledgerFailure, mapLedgerError, setDebugEnabled };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { IHardwareWallet, IConnector, TransportType, IUiHandler, UiResponseEvent, DeviceInfo, Response, ChainCapability, EvmGetAddressParams, EvmAddress, ProgressCallback, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, ChainForFingerprint, ConnectionType, DeviceDescriptor, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, DeviceChangeEvent, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
+import { IHardwareWallet, IConnector, TransportType, IUiHandler, UiResponseEvent, DeviceInfo, Response, ChainCapability, EvmGetAddressParams, EvmAddress, ProgressCallback, EvmSignTxParams, EvmSignedTx, EvmSignMsgParams, EvmSignature, EvmSignTypedDataParams, BtcGetAddressParams, BtcAddress, BtcGetPublicKeyParams, BtcPublicKey, BtcSignTxParams, BtcSignedTx, BtcSignPsbtParams, BtcSignedPsbt, BtcSignMsgParams, BtcSignature, SolGetAddressParams, SolAddress, SolSignTxParams, SolSignedTx, SolSignMsgParams, SolSignature, TronGetAddressParams, TronAddress, TronSignTxParams, TronSignedTx, TronSignMsgParams, TronSignature, HardwareEventMap, DeviceEventListener, ChainForFingerprint, ConnectionType, DeviceDescriptor, ConnectorDevice, ConnectorSession, ConnectorEventType, ConnectorEventMap, DeviceChangeEvent, Failure, HardwareErrorCode } from '@onekeyfe/hwk-adapter-core';
 import { DeviceManagementKit, DeviceActionState as DeviceActionState$1, DiscoveredDevice, ExecuteDeviceActionReturnType } from '@ledgerhq/device-management-kit';
 import { Address, Signature, SignerEth as SignerEth$1, TypedData } from '@ledgerhq/device-signer-kit-ethereum';
 import { SignerBtc as SignerBtc$1 } from '@ledgerhq/device-signer-kit-bitcoin';
@@ -32,7 +32,15 @@ declare class LedgerAdapter implements IHardwareWallet {
     private _discoveredDevices;
     private _sessions;
     private readonly _uiRegistry;
+    private readonly _jobQueue;
     constructor(connector: IConnector, options?: LedgerAdapterOptions);
+    /**
+     * Classify a method's interruptibility.
+     * - Signing / typed data / transaction → 'confirm' (user may decide via preemption UI)
+     * - Read-only queries (getAddress / getPublicKey / getMasterFingerprint) → 'safe'
+     *   (auto-cancels any pending read for the same device)
+     */
+    private static _getInterruptibility;
     get activeTransport(): TransportType | null;
     getAvailableTransports(): TransportType[];
     switchTransport(_type: TransportType): Promise<void>;
@@ -128,6 +136,16 @@ declare class LedgerAdapter implements IHardwareWallet {
      * 4. On disconnect error: clears stale session, re-connects, retries once
      */
     private connectorCall;
+    /**
+     * Race a promise against an abort signal. If the signal fires, rejects with the
+     * signal's reason (or a generic Error). The underlying connector.call() cannot
+     * actually be cancelled on Ledger DMK, but the caller gets the abort immediately.
+     */
+    private static _abortable;
+    /** Throw an AbortError if signal is already aborted. */
+    private static _throwIfAborted;
+    /** Actual work done under the job queue — connection, fingerprint, call, and recovery. */
+    private _runConnectorCall;
     /** Clear stale session, reconnect, and retry the call. */
     private _retryWithFreshConnection;
     /**
@@ -188,7 +206,7 @@ declare class LedgerConnectorBase implements IConnector {
     private readonly _eventHandlers;
     private readonly _providedDmk;
     private readonly _createTransport;
-    private readonly _connectionType;
+    readonly connectionType: ConnectionType;
     private _connectIdToPath;
     private _pathToConnectId;
     /** Register a connectId <-> path mapping from a device descriptor. */
@@ -197,6 +215,7 @@ declare class LedgerConnectorBase implements IConnector {
     private _getPathForConnectId;
     /** Get external connectId from DMK path. Falls back to path itself. */
     private _getConnectIdForPath;
+    private readonly _cancellers;
     /**
      * Resolves a Ledger signer kit module by package name.
      * Override via constructor to use CJS paths for Metro (React Native).
@@ -225,7 +244,7 @@ declare class LedgerConnectorBase implements IConnector {
     connect(deviceId?: string): Promise<ConnectorSession>;
     disconnect(sessionId: string): Promise<void>;
     call(sessionId: string, method: string, params: unknown): Promise<unknown>;
-    cancel(_sessionId: string): Promise<void>;
+    cancel(sessionId: string): Promise<void>;
     uiResponse(_response: UiResponseEvent): void;
     on<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
     off<K extends ConnectorEventType>(event: K, handler: (data: ConnectorEventMap[K]) => void): void;
@@ -335,6 +354,12 @@ declare class SignerEth {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
     constructor(_sdk: SignerEth$1);
+    /**
+     * Optional callback registered per-call so the caller can obtain a canceller
+     * for the underlying DeviceAction. Caller can invoke it to release DMK's
+     * IntentQueue slot and unsubscribe from the action's observable.
+     */
+    onRegisterCanceller?: (cancel: () => void) => void;
     getAddress(derivationPath: string, options?: {
         checkOnDevice?: boolean;
     }): Promise<SignerEvmAddress>;
@@ -352,16 +377,16 @@ type SignerEthBuilderFn = (args: {
     build(): SignerEth$1;
 }>;
 /**
- * Manages per-sessionId SignerEth instances.
- * Creates on demand, caches for reuse, invalidates on session change.
+ * Per-sessionId SignerEth factory. Builds fresh on every call — DMK signers
+ * hold DeviceAction state that isn't safe to reuse, so `invalidate` /
+ * `clearAll` are kept as no-op lifecycle hooks for callers.
  */
 declare class SignerManager {
-    private readonly _cache;
     private readonly _dmk;
     private readonly _builderFn;
     constructor(dmk: DeviceManagementKit, builderFn?: SignerEthBuilderFn);
     getOrCreate(sessionId: string): Promise<SignerEth>;
-    invalidate(sessionId: string): void;
+    invalidate(_sessionId: string): void;
     clearAll(): void;
     private static _defaultBuilder;
 }
@@ -377,6 +402,7 @@ type BtcMessageOptions = Parameters<SignerBtc$1['signMessage']>[2];
 declare class SignerBtc {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
+    onRegisterCanceller?: (cancel: () => void) => void;
     constructor(_sdk: SignerBtc$1);
     getWalletAddress(wallet: BtcWallet, addressIndex: number, options?: {
         checkOnDevice?: boolean;
@@ -422,6 +448,7 @@ type SolMsgOptions = Parameters<SignerSolana['signMessage']>[2];
 declare class SignerSol {
     private readonly _sdk;
     onInteraction?: (interaction: string) => void;
+    onRegisterCanceller?: (cancel: () => void) => void;
     constructor(_sdk: SignerSolana);
     /**
      * Get the Solana address (base58-encoded Ed25519 public key) at the given derivation path.
@@ -473,8 +500,12 @@ declare class DmkTransport extends Transport {
  *
  * @param timeoutMs  Timeout in ms. Resets each time the Observable emits (device is alive).
  *                   Pass 0 to disable. Default: 30s.
+ * @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): Promise<T>;
+declare function deviceActionToPromise<T>(action: DeviceAction<T>, onInteraction?: (interaction: string) => void, timeoutMs?: number, onRegisterCanceller?: (cancel: () => void) => void): Promise<T>;
 
 interface AppManagerOptions {
     waitMs?: number;
@@ -522,6 +553,21 @@ declare class AppManager {
     private _wait;
 }
 
+/**
+ * Ledger-specific Failure: adds `appName` for "the currently-open app" — a
+ * Ledger hardware concept not shared with other vendors, so it lives here
+ * rather than in core's generic Failure.
+ */
+type LedgerFailure = Omit<Failure, 'payload'> & {
+    payload: Failure['payload'] & {
+        appName?: string;
+    };
+};
+/**
+ * Structurally compatible with `Failure`; writes `appName` only when provided,
+ * so `'appName' in payload` is a reliable "has info" signal for consumers.
+ */
+declare function ledgerFailure(code: HardwareErrorCode, error: string, appName?: string): LedgerFailure;
 /** Check if an error (or any error in its chain) represents a locked Ledger device. */
 declare function isDeviceLockedError(err: unknown): boolean;
 /**
@@ -534,4 +580,14 @@ declare function mapLedgerError(err: unknown): {
     appName?: string;
 };
 
-export { AppManager, type DeviceActionState, type DmkDiscoveredDevice, DmkTransport, LedgerAdapter, LedgerConnectorBase, type LedgerConnectorBaseOptions, LedgerDeviceManager, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, SignerSol, type TransportFactory, deviceActionToPromise, isDeviceLockedError, mapLedgerError };
+/**
+ * Centralised debug logger for the Ledger adapter.
+ *
+ * Off by default. Toggle programmatically via `setDebugEnabled(true)`.
+ */
+/** Enable or disable debug logging at runtime. */
+declare function setDebugEnabled(value: boolean): void;
+/** Returns the current debug-enabled state. */
+declare function isDebugEnabled(): boolean;
+
+export { AppManager, type DeviceActionState, type DmkDiscoveredDevice, DmkTransport, LedgerAdapter, LedgerConnectorBase, type LedgerConnectorBaseOptions, LedgerDeviceManager, type LedgerFailure, SignerBtc, type SignerBtcAddress, SignerEth, type SignerEvmAddress, type SignerEvmSignature, SignerManager, SignerSol, type TransportFactory, deviceActionToPromise, isDebugEnabled, isDeviceLockedError, ledgerFailure, mapLedgerError, setDebugEnabled };