@onekeyfe/hd-transport-web-device 1.2.0-alpha.13 → 1.2.0-alpha.131

package/dist/index.d.ts

@@ -1,48 +1,99 @@
 import * as _onekeyfe_hd_transport from '@onekeyfe/hd-transport';
-import _onekeyfe_hd_transport__default, { AcquireInput, TransportCallOptions, ProtocolType, OneKeyDeviceInfoBase, OneKeyDeviceInfo } from '@onekeyfe/hd-transport';
+import _onekeyfe_hd_transport__default, { ProtocolV2UsbTransportBase, AcquireInput, TransportCallOptions, ProtocolV2Schemas, ProtocolV2CallContext, ProtocolType, OneKeyDeviceInfoBase, OneKeyDeviceInfo } from '@onekeyfe/hd-transport';
 import { Deferred } from '@onekeyfe/hd-shared';
 import { DesktopAPI } from '@onekeyfe/hd-transport-electron';
 import EventEmitter from 'events';
 
+/**
+ * Device information with path and WebUSB device instance
+ */
 interface DeviceInfo extends OneKeyDeviceInfoBase {
     path: string;
     device: USBDevice;
     protocolType?: ProtocolType;
 }
-declare class WebUsbTransport {
+declare class WebUsbTransport extends ProtocolV2UsbTransportBase<string> {
     messages: ReturnType<typeof _onekeyfe_hd_transport__default.parseConfigure> | undefined;
+    /** Protobuf schema for Protocol V2 transports. */
     messagesV2: ReturnType<typeof _onekeyfe_hd_transport__default.parseConfigure> | undefined;
+    private protocolV2SchemaSource;
+    /** Per-path protocol type detected by active wire-level probe. */
     private deviceProtocol;
     private deviceProtocolHints;
-    private protocolV2Assemblers;
-    private protocolV2Sessions;
-    private protocolV2ReadTimeouts;
+    /** Per-path USB endpoint / interface numbers (discovered from USB descriptors) */
     private deviceEndpoints;
-    private mockSerialPaths;
-    private mockSerialCounter;
     name: string;
     stopped: boolean;
     configured: boolean;
     Log?: any;
     usb?: USB;
+    /**
+     * Cached list of connected devices
+     * This is essential for maintaining device references between operations
+     */
     deviceList: Array<DeviceInfo>;
     configurationId: number;
     endpointId: number;
     interfaceId: number;
+    constructor();
+    /**
+     * Initialize WebUSB transport
+     */
     init(logger: any): void;
+    /**
+     * Configure Protocol V1 protobuf schema (legacy chunked 0x3F framing).
+     */
     configure(signedData: any): void;
+    /**
+     * Cache the Protocol V2 protobuf schema.
+     */
     configureProtocolV2(signedData: any): void;
+    /**
+     * Request user to select a device
+     * This method must be called in response to a user action
+     * to comply with WebUSB security requirements
+     */
     promptDeviceAccess(): Promise<USBDevice | null>;
+    /**
+     * Enumerate already connected devices
+     * This method only returns devices that are already authorized by the browser
+     * It does NOT prompt the user to select a device
+     */
     enumerate(): Promise<DeviceInfo[]>;
-    private getDevicePath;
+    /**
+     * Get list of connected devices
+     */
     getConnectedDevices(): Promise<DeviceInfo[]>;
+    /**
+     * Acquire device control
+     */
     acquire(input: AcquireInput): Promise<string | undefined>;
+    /**
+     * Determine protocol type after connect.
+     * Probe Protocol V1 first with Initialize. If it does not answer in time,
+     * fall back to a Protocol V2 Ping probe.
+     */
     private createProtocolMismatchError;
+    private createProtocolProbeTimeoutError;
     private createProtocolDetectionError;
     private detectProtocol;
+    /**
+     * Find device by path
+     */
     findDevice(path: string): Promise<USBDevice>;
+    /**
+     * Connect to device with retry mechanism
+     */
     connect(path: string, first: boolean): Promise<void>;
+    /**
+     * Discover vendor-class (0xFF) interface and its IN/OUT endpoint numbers from USB descriptors.
+     * Falls back to legacy hardcoded values if no vendor interface is found.
+     */
     private discoverEndpoints;
+    /**
+     * Connect to specific device.
+     * Discovers interface/endpoint numbers from USB descriptors on first connection.
+     */
     connectToDevice(path: string, first: boolean): Promise<void>;
     private closeOpenDevice;
     private clearEndpointHalt;
@@ -55,16 +106,43 @@ declare class WebUsbTransport {
     private transferOutWithRetry;
     private transferOutOnce;
     private transferInWithRetry;
+    private transferInOnce;
+    private closeConnectionAfterProbe;
     private resetConnectionAfterProbe;
     private withProtocolReadTimeout;
     private probeProtocolV1;
     private probeProtocolV2;
+    /**
+     * Call device method — branches to Protocol V1 or Protocol V2 based on active probe.
+     */
     call(path: string, name: string, data: Record<string, unknown>, options?: TransportCallOptions): Promise<_onekeyfe_hd_transport.MessageFromOneKey>;
     private callProtocolV1;
+    /**
+     * Send/receive a single call over Protocol V2 (0x5A framing).
+     *
+     * Encoding:  protobuf message → 2-byte LE messageTypeId + pb bytes → Protocol V2 frame
+     * Decoding:  Protocol V2 frame → messageTypeId + pb bytes → protobuf message
+     */
     private callProtocolV2;
-    private receiveProtocolV2Frame;
+    /**
+     * Receive data from device
+     */
     receiveData(path: string, timeoutMs?: number): Promise<string>;
+    /**
+     * Release device
+     */
     release(path: string): Promise<void>;
+    protected getProtocolV2UsbSchemas(): ProtocolV2Schemas;
+    protected getProtocolV2UsbLogger(): any;
+    protected writeProtocolV2UsbPacket(path: string, frame: Uint8Array, _context: ProtocolV2CallContext): Promise<void>;
+    protected readProtocolV2UsbPacket(path: string, _context: ProtocolV2CallContext): Promise<Uint8Array>;
+    protected resetProtocolV2UsbNativeLink(path: string, _reason: string): Promise<void>;
+    protected onProtocolV2UsbLinkInvalidated(path: string, reason: string): void;
+    protected createProtocolV2UsbTimeoutError(name: string, timeoutMs: number): Error;
+    /**
+     * Expose the detected protocol type for a given device path.
+     * Used by upper layers (e.g. TransportManager) to select the correct schema.
+     */
     getProtocolType(path: string): ProtocolType | undefined;
 }
 
@@ -77,24 +155,38 @@ type BleAcquireInput = {
     uuid: string;
     forceCleanRunPromise?: boolean;
     expectedProtocol?: ProtocolType;
+    protocolHint?: ProtocolType;
 };
+/**
+ * Desktop Electron BLE transport with automatic Protocol V1/V2 detection.
+ *
+ * Protocol V1 devices continue using chunked packets. Protocol V2 is detected
+ * after a Protocol V1 GetFeatures timeout by probing Protocol V2 Ping.
+ */
 declare class ElectronBleTransport {
     private _messages;
     private _messagesV2;
+    private protocolV2SchemaConfiguration;
     name: string;
     configured: boolean;
     runPromise: Deferred<Uint8Array | string> | null;
+    private runPromiseDeviceId;
     Log?: any;
     emitter?: EventEmitter;
     private connectedDevices;
     private deviceProtocol;
     private deviceProtocolHints;
+    private deviceMtus;
+    private devicePacketCapacities;
     private v1Buffers;
     private v2Assemblers;
     private v2FrameQueues;
     private v2FramePromises;
     private protocolV2Links;
+    /** One-shot guard so a missing preload `release` bridge is reported once. */
+    private warnedMissingRelease;
     private notificationCleanups;
+    private mtuCleanups;
     private disconnectCleanups;
     private notificationTokens;
     private nextNotificationToken;
@@ -116,7 +208,10 @@ declare class ElectronBleTransport {
         name: string | null;
         protocolType?: ProtocolType | undefined;
     }>;
-    release(id: string): Promise<void>;
+    release(id: string, _onclose?: boolean, keepSession?: boolean): Promise<void>;
+    disconnect(id: string): Promise<void>;
+    private releaseNative;
+    private releaseLogical;
     private createProtocolMismatchError;
     private createProtocolDetectionError;
     private clearProbeProtocol;
@@ -125,18 +220,21 @@ declare class ElectronBleTransport {
     private resetProbeStateAfterProtocolProbe;
     private probeProtocolV1;
     private probeProtocolV2;
-    private writeWithChunking;
     private writeOnce;
+    private refreshBlePacketCapacity;
+    private updateBlePacketCapacity;
+    private createMtuSubscription;
+    private writeProtocolV2Frame;
     private handleNotification;
     private handleProtocolV2Notification;
     private getProtocolV2FrameQueue;
     private resolveProtocolV2Frame;
-    private rejectAllProtocolV2Frames;
     private resetProtocolV2Frames;
     private rejectProtocolV2Frames;
     private readProtocolV2Frame;
     private handleProtocolV1Notification;
     call(uuid: string, name: string, data: Record<string, unknown>, options?: TransportCallOptions): Promise<_onekeyfe_hd_transport.MessageFromOneKey>;
+    post(uuid: string, name: string, data: Record<string, unknown>): Promise<void>;
     private callProtocolV1;
     private callProtocolV2;
     private createProtocolV2Adapter;