@onekeyfe/hd-common-connect-sdk 1.2.8-alpha.2 → 1.2.8-alpha.20

package/README.md

@@ -28,6 +28,33 @@ function init() {
 }
 ```
 
+## Desktop USB identity discovery
+
+`probeUsbDeviceIdentities({ commType: 'webusb' | 'bridge' })` is a named export for
+choosing a Desktop connection before switching the active SDK. It does not require
+SDK initialization, dispose Core, change BLE settings, or open a wallet session.
+Concurrent probes for the same mode share one pending request.
+
+```typescript
+import { probeUsbDeviceIdentities } from '@onekeyfe/hd-common-connect-sdk';
+
+const devices = await probeUsbDeviceIdentities({ commType: 'webusb' });
+```
+
+Each result contains `path`, `serialNo`, `deviceId`, `deviceType`, `connectProtocol`,
+and `commType`. `path` locates the USB endpoint; compare `serialNo` with the target's
+physical identity, or `deviceId` for legacy devices without a physical serial.
+Missing identities remain `null`; a descriptor path is never substituted for them.
+The protocol comes from an active device response. V1 uses read-only Features;
+V2 uses hardware DeviceInfo and does not query a wallet session.
+
+Busy, ambiguous, disconnected, or unverified endpoints are omitted. An active
+WebUSB request's identity can be reused only for the exact USB handle it owns.
+Discovery releases only handles it acquired and does not replace the active SDK's
+disconnect observer. An empty result is not proof that the device is absent.
+Keep the selected transport fixed during a hardware operation; reevaluate it
+between operations. Firmware updates must separately validate their live target.
+
 ## Docs
 
 Documentation is available [Hardware SDK Getting Started](https://developer.onekey.so/en/hardware-sdk/getting-started)

package/__tests__/device-state-events.test.ts

@@ -1,10 +1,16 @@
 import { readFileSync } from 'fs';
 import { resolve } from 'path';
 import EventEmitter from 'events';
-import { CORE_EVENT, initCore } from '@onekeyfe/hd-core';
-import { createDeferred } from '@onekeyfe/hd-shared';
+import {
+  CORE_EVENT,
+  UI_REQUEST,
+  initCore,
+  probeUsbDeviceIdentitiesWithTransport,
+} from '@onekeyfe/hd-core';
+import { HardwareErrorCode, createDeferred } from '@onekeyfe/hd-shared';
+import HttpTransport from '@onekeyfe/hd-transport-http';
 
-import sdkExport, { messagePromises } from '../src';
+import sdkExport, { messagePromises, probeUsbDeviceIdentities } from '../src';
 
 jest.mock('../../core/src/data/config', () => ({
   getSDKVersion: jest.fn(() => '1.0.0-test'),
@@ -15,9 +21,10 @@ jest.mock('@onekeyfe/hd-core', () => ({
   __esModule: true,
   default: (options: unknown) => options,
   initCore: jest.fn(),
+  probeUsbDeviceIdentitiesWithTransport: jest.fn(),
 }));
-jest.mock('@onekeyfe/hd-transport-http', () => ({}));
-jest.mock('@onekeyfe/hd-transport-web-device', () => ({}));
+jest.mock('@onekeyfe/hd-transport-http', () => ({ __esModule: true, default: jest.fn() }));
+jest.mock('@onekeyfe/hd-transport-web-device', () => ({ WebUsbTransport: jest.fn() }));
 jest.mock('@onekeyfe/hd-transport-lowlevel', () => ({}));
 jest.mock('@onekeyfe/hd-transport-emulator', () => ({}));
 
@@ -56,6 +63,17 @@ describe('SDK request cleanup', () => {
     await sdk.dispose();
   });
 
+  test.each([
+    [HardwareErrorCode.BlePoweredOff, UI_REQUEST.BLUETOOTH_POWERED_OFF],
+    [HardwareErrorCode.BleUnsupported, UI_REQUEST.BLUETOOTH_UNSUPPORTED],
+    [HardwareErrorCode.BleLocationError, UI_REQUEST.LOCATION_PERMISSION],
+  ])('emits the adapter UI request for error %s', async (code, type) => {
+    const response = { success: false, payload: { code, error: 'Adapter unavailable' } };
+    core.handleMessage.mockResolvedValueOnce(response);
+    await expect(sdk.call({ method: 'searchDevices' })).resolves.toEqual(response);
+    expect(core.handleMessage).toHaveBeenNthCalledWith(2, expect.objectContaining({ type }));
+  });
+
   test('removes only the completed request when calls settle out of order', async () => {
     const first = createDeferred<unknown>();
     const second = createDeferred<unknown>();
@@ -71,6 +89,45 @@ describe('SDK request cleanup', () => {
     expect(Object.keys(messagePromises)).toHaveLength(0);
   });
 
+  test.each(['webusb'] as const)(
+    'probes %s without disposing an outstanding BLE request and coalesces concurrent probes',
+    async commType => {
+      const pending = createDeferred<unknown>();
+      const discovery = createDeferred<never[]>();
+      core.handleMessage.mockReturnValueOnce(pending.promise);
+      const request = sdk.call({ method: 'getDeviceState' });
+      jest
+        .mocked(probeUsbDeviceIdentitiesWithTransport)
+        .mockReset()
+        .mockReturnValueOnce(discovery.promise);
+      const initializationCount = jest.mocked(initCore).mock.calls.length;
+      const first = probeUsbDeviceIdentities({ commType });
+      const second = probeUsbDeviceIdentities({ commType });
+      expect(second).toBe(first);
+      expect(probeUsbDeviceIdentitiesWithTransport).toHaveBeenCalledTimes(1);
+      discovery.resolve([]);
+      await first;
+      expect(core.dispose).not.toHaveBeenCalled();
+      expect(initCore).toHaveBeenCalledTimes(initializationCount);
+      expect(core.listenerCount(CORE_EVENT)).toBe(1);
+      expect(Object.keys(messagePromises)).toHaveLength(1);
+      pending.resolve({ success: true, payload: {} });
+      await expect(request).resolves.toMatchObject({ success: true });
+      expect(Object.keys(messagePromises)).toHaveLength(0);
+    }
+  );
+
+  test('rejects the withdrawn Bridge probe without creating a transport or affecting BLE', async () => {
+    jest.mocked(HttpTransport).mockClear();
+    jest.mocked(probeUsbDeviceIdentitiesWithTransport).mockClear();
+    await expect(probeUsbDeviceIdentities({ commType: 'bridge' })).rejects.toMatchObject({
+      errorCode: HardwareErrorCode.CallMethodInvalidParameter,
+    });
+    expect(HttpTransport).not.toHaveBeenCalled();
+    expect(probeUsbDeviceIdentitiesWithTransport).not.toHaveBeenCalled();
+    expect(core.dispose).not.toHaveBeenCalled();
+  });
+
   test('waits for Core disposal and does not retain old listeners after reinitialization', async () => {
     const cleanup = createDeferred<void>();
     core.dispose.mockImplementationOnce(async () => {

package/dist/index.d.ts

@@ -1,9 +1,14 @@
 import * as _onekeyfe_hd_core from '@onekeyfe/hd-core';
+import { UsbDeviceIdentity } from '@onekeyfe/hd-core';
 import { Deferred } from '@onekeyfe/hd-shared';
 
+/** Identify WebUSB without disposing the current SDK, changing settings, or opening a wallet. */
+declare const probeUsbDeviceIdentities: ({ commType, }: {
+    commType: UsbDeviceIdentity['commType'];
+}) => Promise<UsbDeviceIdentity[]>;
 declare const messagePromises: {
     [key: number]: Deferred<any>;
 };
 declare const HardwareCommonConnectSdk: _onekeyfe_hd_core.CoreApi;
 
-export { HardwareCommonConnectSdk as default, messagePromises };
+export { HardwareCommonConnectSdk as default, messagePromises, probeUsbDeviceIdentities };

package/dist/index.js

@@ -607,6 +607,30 @@ var getTransport = function (env) { return __awaiter(void 0, void 0, void 0, fun
 }); };
 var _core;
 var _settings = HardwareSdk.parseConnectSettings();
+var usbIdentityProbeTransports = {};
+var usbIdentityProbes = {};
+/** Identify WebUSB without disposing the current SDK, changing settings, or opening a wallet. */
+var probeUsbDeviceIdentities = function (_a) {
+    var commType = _a.commType;
+    if (commType !== 'webusb') {
+        return Promise.reject(hdShared.ERRORS.TypedError(hdShared.HardwareErrorCode.CallMethodInvalidParameter));
+    }
+    var pending = usbIdentityProbes[commType];
+    if (pending)
+        return pending;
+    var transport = usbIdentityProbeTransports[commType];
+    if (!transport) {
+        transport = new hdTransportWebDevice.WebUsbTransport(true);
+        usbIdentityProbeTransports[commType] = transport;
+    }
+    var probe = HardwareSdk.probeUsbDeviceIdentitiesWithTransport(transport, commType, function (descriptor) {
+        return _core === null || _core === void 0 ? void 0 : _core.getOwnedUsbDeviceIdentity(descriptor);
+    }).finally(function () {
+        delete usbIdentityProbes[commType];
+    });
+    usbIdentityProbes[commType] = probe;
+    return probe;
+};
 var _messageID = 0;
 var messagePromises = {};
 var dispose = function () { return __awaiter(void 0, void 0, void 0, function () {
@@ -736,18 +760,18 @@ var init = function (settings, _, plugin) { return __awaiter(void 0, void 0, voi
 }); };
 var call = function (params) { return __awaiter(void 0, void 0, void 0, function () {
     var blockLog, response, error_2;
-    var _a, _b, _c;
-    return __generator(this, function (_d) {
-        switch (_d.label) {
+    var _a, _b, _c, _d;
+    return __generator(this, function (_e) {
+        switch (_e.label) {
             case 0:
                 blockLog = HardwareSdk.getLogBlockLabel(params);
                 Log.debug('call: ', blockLog !== null && blockLog !== void 0 ? blockLog : params);
-                _d.label = 1;
+                _e.label = 1;
             case 1:
-                _d.trys.push([1, 3, , 4]);
+                _e.trys.push([1, 3, , 4]);
                 return [4 /*yield*/, postMessage({ event: HardwareSdk.IFRAME.CALL, type: HardwareSdk.IFRAME.CALL, payload: params })];
             case 2:
-                response = _d.sent();
+                response = _e.sent();
                 if (response) {
                     Log.debug('response: ', blockLog ? '[REDACTED]' : response);
                     if (!response.success) {
@@ -760,12 +784,15 @@ var call = function (params) { return __awaiter(void 0, void 0, void 0, function
                         if (((_c = response.payload) === null || _c === void 0 ? void 0 : _c.code) === hdShared.HardwareErrorCode.BlePermissionError) {
                             postMessage(HardwareSdk.createUiMessage(HardwareSdk.UI_REQUEST.BLUETOOTH_PERMISSION), false);
                         }
+                        if (((_d = response.payload) === null || _d === void 0 ? void 0 : _d.code) === hdShared.HardwareErrorCode.BleLocationError) {
+                            postMessage(HardwareSdk.createUiMessage(HardwareSdk.UI_REQUEST.LOCATION_PERMISSION), false);
+                        }
                     }
                     return [2 /*return*/, response];
                 }
                 return [2 /*return*/, HardwareSdk.createErrorMessage(hdShared.ERRORS.TypedError(hdShared.HardwareErrorCode.CallMethodNotResponse))];
             case 3:
-                error_2 = _d.sent();
+                error_2 = _e.sent();
                 Log.error('__call error: ', error_2);
                 return [2 /*return*/, HardwareSdk.createErrorMessage(error_2)];
             case 4: return [2 /*return*/];
@@ -787,3 +814,4 @@ var HardwareCommonConnectSdk = HardwareSdk__default["default"]({
 
 exports["default"] = HardwareCommonConnectSdk;
 exports.messagePromises = messagePromises;
+exports.probeUsbDeviceIdentities = probeUsbDeviceIdentities;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-common-connect-sdk",
-  "version": "1.2.8-alpha.2",
+  "version": "1.2.8-alpha.20",
   "author": "OneKey",
   "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
   "license": "ISC",
@@ -21,13 +21,13 @@
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@onekeyfe/hd-core": "1.2.8-alpha.2",
-    "@onekeyfe/hd-shared": "1.2.8-alpha.2",
-    "@onekeyfe/hd-transport-emulator": "1.2.8-alpha.2",
-    "@onekeyfe/hd-transport-http": "1.2.8-alpha.2",
-    "@onekeyfe/hd-transport-lowlevel": "1.2.8-alpha.2",
-    "@onekeyfe/hd-transport-usb": "1.2.8-alpha.2",
-    "@onekeyfe/hd-transport-web-device": "1.2.8-alpha.2"
+    "@onekeyfe/hd-core": "1.2.8-alpha.20",
+    "@onekeyfe/hd-shared": "1.2.8-alpha.20",
+    "@onekeyfe/hd-transport-emulator": "1.2.8-alpha.20",
+    "@onekeyfe/hd-transport-http": "1.2.8-alpha.20",
+    "@onekeyfe/hd-transport-lowlevel": "1.2.8-alpha.20",
+    "@onekeyfe/hd-transport-usb": "1.2.8-alpha.20",
+    "@onekeyfe/hd-transport-web-device": "1.2.8-alpha.20"
   },
-  "gitHead": "74ac64464df3806ef44ad54d313378754c3eaed2"
+  "gitHead": "973f059fe93a58fdcf098ddb32ba63f621a2c78e"
 }

package/src/index.ts

@@ -17,6 +17,7 @@ import HardwareSdk, {
   getLogger,
   initCore,
   parseConnectSettings,
+  probeUsbDeviceIdentitiesWithTransport,
   setLoggerPostMessage,
 } from '@onekeyfe/hd-core';
 import { ERRORS, HardwareErrorCode, createDeferred } from '@onekeyfe/hd-shared';
@@ -32,6 +33,7 @@ import type {
   CoreMessage,
   LowLevelCoreApi,
   UiResponseEvent,
+  UsbDeviceIdentity,
 } from '@onekeyfe/hd-core';
 import type { LowlevelTransportSharedPlugin } from '@onekeyfe/hd-transport';
 
@@ -57,6 +59,37 @@ const getTransport = async (env: ConnectSettings['env']) => {
 let _core: Core | undefined;
 let _settings = parseConnectSettings();
 
+const usbIdentityProbeTransports: Partial<Record<UsbDeviceIdentity['commType'], WebUsbTransport>> =
+  {};
+const usbIdentityProbes: Partial<
+  Record<UsbDeviceIdentity['commType'], Promise<UsbDeviceIdentity[]>>
+> = {};
+
+/** Identify WebUSB without disposing the current SDK, changing settings, or opening a wallet. */
+export const probeUsbDeviceIdentities = ({
+  commType,
+}: {
+  commType: UsbDeviceIdentity['commType'];
+}): Promise<UsbDeviceIdentity[]> => {
+  if (commType !== 'webusb') {
+    return Promise.reject(ERRORS.TypedError(HardwareErrorCode.CallMethodInvalidParameter));
+  }
+  const pending = usbIdentityProbes[commType];
+  if (pending) return pending;
+  let transport = usbIdentityProbeTransports[commType];
+  if (!transport) {
+    transport = new WebUsbTransport(true);
+    usbIdentityProbeTransports[commType] = transport;
+  }
+  const probe = probeUsbDeviceIdentitiesWithTransport(transport, commType, descriptor =>
+    _core?.getOwnedUsbDeviceIdentity(descriptor)
+  ).finally(() => {
+    delete usbIdentityProbes[commType];
+  });
+  usbIdentityProbes[commType] = probe;
+  return probe;
+};
+
 let _messageID = 0;
 export const messagePromises: { [key: number]: Deferred<any> } = {};
 
@@ -188,6 +221,9 @@ const call = async (params: any) => {
         if (response.payload?.code === HardwareErrorCode.BlePermissionError) {
           postMessage(createUiMessage(UI_REQUEST.BLUETOOTH_PERMISSION), false);
         }
+        if (response.payload?.code === HardwareErrorCode.BleLocationError) {
+          postMessage(createUiMessage(UI_REQUEST.LOCATION_PERMISSION), false);
+        }
       }
 
       return response;