@onekeyfe/hd-transport-web-device 1.2.0-alpha.11 → 1.2.0-alpha.111

package/__tests__/webusb-protocol-v2-timeout.test.ts

@@ -0,0 +1,386 @@
+import transport, {
+  PROTOCOL_V2_CHANNEL_USB,
+  ProtocolV2,
+  ProtocolV2LinkError,
+} from '@onekeyfe/hd-transport';
+import { HardwareErrorCode, ONEKEY_WEBUSB_FILTER } from '@onekeyfe/hd-shared';
+
+import WebUsbTransport from '../src/webusb';
+
+const schema = {
+  nested: {
+    Ping: { fields: { message: { type: 'string', id: 1 } } },
+    Success: { fields: { message: { type: 'string', id: 1 } } },
+    MessageType: {
+      values: {
+        MessageType_Ping: 60206,
+        MessageType_Success: 60207,
+      },
+    },
+  },
+};
+
+describe('WebUsbTransport Protocol V2 timeout recovery', () => {
+  test('only enumerates devices with real USB serial numbers', async () => {
+    const filter = ONEKEY_WEBUSB_FILTER[0];
+    const deviceWithSerial = {
+      ...filter,
+      manufacturerName: 'OneKey',
+      productName: 'OneKey Pro 2',
+      serialNumber: 'PRO2-SERIAL',
+    } as USBDevice;
+    const deviceWithoutSerial = {
+      ...filter,
+      manufacturerName: 'OneKey',
+      productName: 'OneKey Pro 2',
+      serialNumber: null,
+    } as USBDevice;
+    const webusb = new WebUsbTransport();
+    webusb.usb = {
+      getDevices: jest.fn().mockResolvedValue([deviceWithSerial, deviceWithoutSerial]),
+    } as unknown as USB;
+
+    await expect(webusb.getConnectedDevices()).resolves.toEqual([
+      {
+        path: 'PRO2-SERIAL',
+        device: deviceWithSerial,
+        commType: 'webusb',
+      },
+    ]);
+  });
+
+  test('keeps active links when the Protocol V2 schema is configured repeatedly', () => {
+    const webusb = new WebUsbTransport() as any;
+    webusb.invalidateAllProtocolV2UsbLinks = jest.fn().mockResolvedValue(undefined);
+    const schemaSource = JSON.stringify(schema);
+
+    webusb.configureProtocolV2(schemaSource);
+    webusb.configureProtocolV2(schemaSource);
+
+    expect(webusb.invalidateAllProtocolV2UsbLinks).not.toHaveBeenCalled();
+
+    webusb.configureProtocolV2(
+      JSON.stringify({
+        ...schema,
+        nested: {
+          ...schema.nested,
+          Failure: { fields: { message: { type: 'string', id: 1 } } },
+        },
+      })
+    );
+    expect(webusb.invalidateAllProtocolV2UsbLinks).toHaveBeenCalledWith(
+      'Protocol V2 schema reconfigured'
+    );
+  });
+
+  test('resets the connection between a failed V1 probe and the V2 probe', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    const events: string[] = [];
+    webusb.probeProtocolV1 = jest.fn().mockImplementation(() => {
+      events.push('probe-v1');
+      return Promise.resolve(false);
+    });
+    webusb.resetConnectionAfterProbe = jest.fn().mockImplementation(() => {
+      events.push('reset');
+      return Promise.resolve();
+    });
+    webusb.probeProtocolV2 = jest.fn().mockImplementation(() => {
+      events.push('probe-v2');
+      return Promise.resolve(true);
+    });
+
+    await expect(webusb.detectProtocol(path)).resolves.toBe('V2');
+
+    expect(events).toEqual(['probe-v1', 'reset', 'probe-v2']);
+    expect(webusb.deviceProtocol.get(path)).toBe('V2');
+  });
+
+  test('reports DeviceNotFound when automatic protocol detection exhausts both probes', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'unresponsive-webusb';
+    webusb.probeProtocolV1 = jest.fn().mockResolvedValue(false);
+    webusb.probeProtocolV2 = jest.fn().mockResolvedValue(false);
+    webusb.resetConnectionAfterProbe = jest.fn().mockResolvedValue(undefined);
+    webusb.closeConnectionAfterProbe = jest.fn().mockResolvedValue(undefined);
+
+    await expect(webusb.detectProtocol(path)).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.DeviceNotFound,
+    });
+
+    expect(webusb.probeProtocolV1).toHaveBeenCalledTimes(1);
+    expect(webusb.probeProtocolV2).toHaveBeenCalledTimes(1);
+    expect(webusb.resetConnectionAfterProbe).toHaveBeenCalledTimes(1);
+    expect(webusb.closeConnectionAfterProbe).toHaveBeenCalledTimes(1);
+    expect(webusb.deviceProtocol.has(path)).toBe(false);
+  });
+
+  test('allows legacy WebUSB Initialize up to the Node USB probe timeout', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro-webusb';
+    webusb.messages = {};
+    webusb.callProtocolV1 = jest.fn().mockResolvedValue({});
+
+    await expect(webusb.probeProtocolV1(path)).resolves.toBe(true);
+
+    expect(webusb.callProtocolV1).toHaveBeenCalledWith(
+      path,
+      'Initialize',
+      {},
+      {
+        timeoutMs: 5000,
+      }
+    );
+  });
+
+  test('retries an expected Protocol V2 probe once after resetting the connection', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    webusb.probeProtocolV1 = jest.fn();
+    webusb.probeProtocolV2 = jest.fn().mockResolvedValueOnce(false).mockResolvedValueOnce(true);
+    webusb.resetConnectionAfterProbe = jest.fn().mockResolvedValue(undefined);
+
+    await expect(webusb.detectProtocol(path, 'V2')).resolves.toBe('V2');
+
+    expect(webusb.probeProtocolV2).toHaveBeenCalledTimes(2);
+    expect(webusb.probeProtocolV1).not.toHaveBeenCalled();
+    expect(webusb.resetConnectionAfterProbe).toHaveBeenCalledTimes(1);
+    expect(webusb.deviceProtocol.get(path)).toBe('V2');
+  });
+
+  test('reports a device initialization failure only after the bounded retry is exhausted', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    webusb.probeProtocolV1 = jest.fn();
+    webusb.probeProtocolV2 = jest.fn().mockResolvedValue(false);
+    webusb.resetConnectionAfterProbe = jest.fn().mockResolvedValue(undefined);
+    webusb.closeConnectionAfterProbe = jest.fn().mockResolvedValue(undefined);
+
+    await expect(webusb.detectProtocol(path, 'V2')).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.DeviceInitializeFailed,
+      message: 'Protocol V2 probe timeout after 2 attempts',
+    });
+
+    expect(webusb.probeProtocolV2).toHaveBeenCalledTimes(2);
+    expect(webusb.probeProtocolV1).not.toHaveBeenCalled();
+    expect(webusb.resetConnectionAfterProbe).toHaveBeenCalledTimes(1);
+    expect(webusb.closeConnectionAfterProbe).toHaveBeenCalledTimes(1);
+    expect(webusb.deviceProtocol.has(path)).toBe(false);
+  });
+
+  test('closes the reopened device when acquire exhausts the expected Protocol V2 probe', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    const device = {
+      opened: false,
+      releaseInterface: jest.fn().mockResolvedValue(undefined),
+      close: jest.fn().mockImplementation(() => {
+        device.opened = false;
+        return Promise.resolve();
+      }),
+    };
+    webusb.deviceList = [{ path, device }];
+    webusb.Log = { debug: jest.fn() };
+    webusb.rotateProtocolV2UsbGeneration = jest.fn().mockResolvedValue(undefined);
+    webusb.connect = jest.fn().mockImplementation(() => {
+      device.opened = true;
+      return Promise.resolve();
+    });
+    webusb.detectProtocol = jest.fn().mockRejectedValue(new Error('terminal probe failure'));
+
+    await expect(webusb.acquire({ path, expectedProtocol: 'V2' })).rejects.toThrow(
+      'terminal probe failure'
+    );
+
+    expect(device.releaseInterface).toHaveBeenCalledTimes(1);
+    expect(device.close).toHaveBeenCalledTimes(1);
+    expect(device.opened).toBe(false);
+  });
+
+  test('invalidates and resets the cached connection before another call can start', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    webusb.messages = transport.parseConfigure(schema);
+    webusb.messagesV2 = transport.parseConfigure(schema);
+    webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+    webusb.readProtocolV2UsbPacket = jest.fn(() => new Promise<void>(() => {}));
+    webusb.resetProtocolV2UsbNativeLink = jest.fn().mockResolvedValue(undefined);
+    webusb.resetConnectionAfterProbe = jest.fn();
+    await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+    await expect(
+      webusb.callProtocolV2(path, 'Ping', { message: 'timeout' }, { timeoutMs: 10 })
+    ).rejects.toThrow('timeout');
+
+    expect(webusb.resetProtocolV2UsbNativeLink).toHaveBeenCalledWith(
+      path,
+      expect.stringContaining('timeout')
+    );
+    expect(webusb.resetConnectionAfterProbe).not.toHaveBeenCalled();
+  });
+
+  test('does not reconnect inside a Protocol V2 frame read after a USB I/O failure', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    webusb.messages = transport.parseConfigure(schema);
+    webusb.messagesV2 = transport.parseConfigure(schema);
+    webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+    webusb.readProtocolV2UsbPacket = jest
+      .fn()
+      .mockRejectedValue(new Error('NetworkError: transferIn device disconnected'));
+    webusb.resetProtocolV2UsbNativeLink = jest.fn().mockResolvedValue(undefined);
+    webusb.resetConnectionAfterProbe = jest.fn();
+    await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+    await expect(webusb.callProtocolV2(path, 'Ping', { message: 'read-error' })).rejects.toThrow(
+      'NetworkError'
+    );
+
+    expect(webusb.readProtocolV2UsbPacket).toHaveBeenCalledTimes(1);
+    expect(webusb.resetProtocolV2UsbNativeLink).toHaveBeenCalledWith(
+      path,
+      expect.stringContaining('NetworkError')
+    );
+    expect(webusb.resetConnectionAfterProbe).not.toHaveBeenCalled();
+  });
+
+  test('rejects an active Protocol V2 read without reconnecting after release', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    let markReadStarted: () => void = () => undefined;
+    const readStarted = new Promise<void>(resolve => {
+      markReadStarted = resolve;
+    });
+    webusb.messages = transport.parseConfigure(schema);
+    webusb.messagesV2 = transport.parseConfigure(schema);
+    webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+    webusb.readProtocolV2UsbPacket = jest.fn().mockImplementation(() => {
+      markReadStarted();
+      return new Promise<void>(() => {});
+    });
+    webusb.closeOpenDevice = jest.fn().mockResolvedValue(undefined);
+    webusb.connect = jest.fn();
+    await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+    const call = webusb.callProtocolV2(path, 'Ping', { message: 'release' });
+    await readStarted;
+    await webusb.release(path);
+
+    await expect(call).rejects.toThrow('WebUSB transport released');
+    expect(webusb.connect).not.toHaveBeenCalled();
+  });
+
+  test.each(['router', 'packet-source', 'ack-sequence', 'response-sequence', 'frame'] as const)(
+    'invalidates cached state for typed Protocol V2 %s errors',
+    async code => {
+      const webusb = new WebUsbTransport() as any;
+      const path = 'pro2-webusb';
+      webusb.messages = transport.parseConfigure(schema);
+      webusb.messagesV2 = transport.parseConfigure(schema);
+      webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+      const recoveredResponse = ProtocolV2.encodeFrame(
+        { protocolV1: webusb.messages, protocolV2: webusb.messagesV2 },
+        'Success',
+        { message: 'recovered' },
+        { seq: 1 }
+      );
+      webusb.readProtocolV2UsbPacket = jest
+        .fn()
+        .mockRejectedValueOnce(
+          new ProtocolV2LinkError(code, `Protocol V2 ${code} validation failed`)
+        )
+        .mockResolvedValue(recoveredResponse);
+      webusb.resetProtocolV2UsbNativeLink = jest.fn().mockResolvedValue(undefined);
+      webusb.resetConnectionAfterProbe = jest.fn();
+      await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+      await expect(webusb.callProtocolV2(path, 'Ping', { message: 'mismatch' })).rejects.toThrow(
+        `${code} validation failed`
+      );
+
+      expect(webusb.resetProtocolV2UsbNativeLink).toHaveBeenCalledWith(
+        path,
+        expect.stringContaining(`${code} validation failed`)
+      );
+      expect(webusb.resetConnectionAfterProbe).not.toHaveBeenCalled();
+
+      await webusb.rotateProtocolV2UsbGeneration(path, 'test reconnect');
+      await expect(
+        webusb.callProtocolV2(path, 'Ping', { message: 'after-reset' })
+      ).resolves.toMatchObject({
+        type: 'Success',
+        message: { message: 'recovered' },
+      });
+    }
+  );
+
+  test('does not discard buffered Protocol V2 frames before each call', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    webusb.messages = transport.parseConfigure(schema);
+    webusb.messagesV2 = transport.parseConfigure(schema);
+    webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+    const firstResponse = ProtocolV2.encodeFrame(
+      { protocolV1: webusb.messages, protocolV2: webusb.messagesV2 },
+      'Success',
+      { message: 'first' },
+      { router: PROTOCOL_V2_CHANNEL_USB, seq: 1 }
+    );
+    const secondResponse = ProtocolV2.encodeFrame(
+      { protocolV1: webusb.messages, protocolV2: webusb.messagesV2 },
+      'Success',
+      { message: 'second' },
+      { router: PROTOCOL_V2_CHANNEL_USB, seq: 2 }
+    );
+    const coalescedResponses = new Uint8Array(firstResponse.length + secondResponse.length);
+    coalescedResponses.set(firstResponse);
+    coalescedResponses.set(secondResponse, firstResponse.length);
+    webusb.readProtocolV2UsbPacket = jest.fn().mockResolvedValue(coalescedResponses);
+    webusb.resetProtocolV2UsbNativeLink = jest.fn().mockResolvedValue(undefined);
+    await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+    await expect(webusb.callProtocolV2(path, 'Ping', { message: 'first' })).resolves.toMatchObject({
+      type: 'Success',
+      message: { message: 'first' },
+    });
+    await expect(webusb.callProtocolV2(path, 'Ping', { message: 'second' })).resolves.toMatchObject(
+      {
+        type: 'Success',
+        message: { message: 'second' },
+      }
+    );
+
+    expect(webusb.readProtocolV2UsbPacket).toHaveBeenCalledTimes(1);
+  });
+
+  test('keeps queued Protocol V2 read timeouts scoped to each call', async () => {
+    const webusb = new WebUsbTransport() as any;
+    const path = 'pro2-webusb';
+    let responseSequence = 0;
+    const readTimeouts: number[] = [];
+    webusb.messages = transport.parseConfigure(schema);
+    webusb.messagesV2 = transport.parseConfigure(schema);
+    webusb.writeProtocolV2UsbPacket = jest.fn().mockResolvedValue(undefined);
+    webusb.readProtocolV2UsbPacket = jest.fn().mockImplementation((_path, context) => {
+      responseSequence += 1;
+      readTimeouts.push(context.timeoutMs);
+      return Promise.resolve(
+        ProtocolV2.encodeFrame(
+          { protocolV1: webusb.messages, protocolV2: webusb.messagesV2 },
+          'Success',
+          { message: 'ok' },
+          { seq: responseSequence }
+        )
+      );
+    });
+    webusb.resetProtocolV2UsbNativeLink = jest.fn().mockResolvedValue(undefined);
+    await webusb.rotateProtocolV2UsbGeneration(path, 'test connection');
+
+    await Promise.all([
+      webusb.callProtocolV2(path, 'Ping', { message: 'long' }, { timeoutMs: 1_000 }),
+      webusb.callProtocolV2(path, 'Ping', { message: 'short' }, { timeoutMs: 25 }),
+    ]);
+
+    expect(readTimeouts).toEqual([1_000, 25]);
+  });
+});

package/dist/ble-packet-capacity.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveBlePacketCapacity(mtu: number | null | undefined, maximumPacketCapacity: number, fallbackPacketCapacity: number): number;
+//# sourceMappingURL=ble-packet-capacity.d.ts.map

package/dist/ble-packet-capacity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ble-packet-capacity.d.ts","sourceRoot":"","sources":["../src/ble-packet-capacity.ts"],"names":[],"mappings":"AAEA,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,qBAAqB,EAAE,MAAM,EAC7B,sBAAsB,EAAE,MAAM,GAC7B,MAAM,CAMR"}

package/dist/electron-ble-transport.d.ts

@@ -12,24 +12,31 @@ export type BleAcquireInput = {
     uuid: string;
     forceCleanRunPromise?: boolean;
     expectedProtocol?: ProtocolType;
+    protocolHint?: ProtocolType;
 };
 export default 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;
+    private warnedMissingRelease;
     private notificationCleanups;
+    private mtuCleanups;
     private disconnectCleanups;
     private notificationTokens;
     private nextNotificationToken;
@@ -51,7 +58,10 @@ export default 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;
@@ -60,13 +70,15 @@ export default 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;

package/dist/electron-ble-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"electron-ble-transport.d.ts","sourceRoot":"","sources":["../src/electron-ble-transport.ts"],"names":[],"mappings":";AAmBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnG,OAAO,KAAK,YAAY,MAAM,QAAQ,CAAC;AAevC,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,UAAU,CAAC,EAAE,UAAU,CAAC;KACzB;CACF;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,gBAAgB,CAAC,EAAE,YAAY,CAAC;CACjC,CAAC;AAqCF,MAAM,CAAC,OAAO,OAAO,oBAAoB;IACvC,OAAO,CAAC,SAAS,CAA0D;IAE3E,OAAO,CAAC,WAAW,CAA0D;IAE7E,IAAI,SAA0B;IAE9B,UAAU,UAAS;IAEnB,UAAU,EAAE,QAAQ,CAAC,UAAU,GAAG,MAAM,CAAC,GAAG,IAAI,CAAQ;IAExD,GAAG,CAAC,EAAE,GAAG,CAAC;IAEV,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB,OAAO,CAAC,gBAAgB,CAA0B;IAElD,OAAO,CAAC,cAAc,CAAwC;IAE9D,OAAO,CAAC,mBAAmB,CAAwC;IAEnE,OAAO,CAAC,SAAS,CAAsE;IAEvF,OAAO,CAAC,YAAY,CAAoD;IAExE,OAAO,CAAC,aAAa,CAAwC;IAE7D,OAAO,CAAC,eAAe,CAAgD;IAEvE,OAAO,CAAC,eAAe,CAmBpB;IAEH,OAAO,CAAC,oBAAoB,CAAsC;IAElE,OAAO,CAAC,kBAAkB,CAAsC;IAEhE,OAAO,CAAC,kBAAkB,CAAkC;IAE5D,OAAO,CAAC,qBAAqB,CAAK;IAElC,OAAO,CAAC,oBAAoB;IA+B5B,OAAO,CAAC,kBAAkB;IA0B1B,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,YAAY;IAcxC,SAAS,CAAC,UAAU,EAAE,GAAG;IAKzB,mBAAmB,CAAC,UAAU,EAAE,GAAG;IAQ7B,MAAM;IAIN,SAAS,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAqBxC,OAAO,CAAC,KAAK,EAAE,eAAe;;;;;;;;;;;IA0F9B,OAAO,CAAC,EAAE,EAAE,MAAM;IAgBxB,OAAO,CAAC,2BAA2B;IAOnC,OAAO,CAAC,4BAA4B;IAOpC,OAAO,CAAC,kBAAkB;YAMZ,cAAc;IA+C5B,OAAO,CAAC,8BAA8B;YAgBxB,iCAAiC;YAqCjC,eAAe;YAgBf,eAAe;YAuBf,iBAAiB;YAsBjB,SAAS;IASvB,OAAO,CAAC,kBAAkB;IAwB1B,OAAO,CAAC,4BAA4B;IAkBpC,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,yBAAyB;IAQjC,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,sBAAsB;YAShB,mBAAmB;IAiBjC,OAAO,CAAC,4BAA4B;IAgB9B,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,oBAAoB;YA+BlB,cAAc;YAuEd,cAAc;IA6B5B,OAAO,CAAC,uBAAuB;IA0C/B,OAAO,CAAC,6BAA6B;IAsCrC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;CAGxD"}
+{"version":3,"file":"electron-ble-transport.d.ts","sourceRoot":"","sources":["../src/electron-ble-transport.ts"],"names":[],"mappings":"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"}

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 Initialize 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,13 +220,15 @@ 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;