@onekeyfe/hd-core 1.2.0-alpha.16 → 1.2.0-alpha.160

package/src/device/DeviceCommands.ts

@@ -1,7 +1,16 @@
 import { ERRORS, HardwareError, HardwareErrorCode } from '@onekeyfe/hd-shared';
+import {
+  DeviceErrorCode,
+  DeviceSessionErrorCode,
+  type FailureType,
+  type Messages,
+  type Transport,
+  type TransportCallOptions,
+  getSafeTransportLogPayload,
+  isProtocolV2LinkDisabledFailure,
+} from '@onekeyfe/hd-transport';
 
 import TransportManager from '../data-manager/TransportManager';
-import DataManager from '../data-manager/DataManager';
 import { LoggerNames, getLogger, patchFeatures } from '../utils';
 import { DEVICE, type PassphraseRequestPayload } from '../events';
 import { DeviceModelToTypes } from '../types';
@@ -12,12 +21,6 @@ import {
 } from '../utils/tracing';
 
 import type { Device } from './Device';
-import type {
-  FailureType,
-  Messages,
-  Transport,
-  TransportCallOptions,
-} from '@onekeyfe/hd-transport';
 
 export type PassphrasePromptResponse = {
   passphrase?: string;
@@ -37,10 +40,6 @@ type TypedCallResponseMap = {
 };
 export type DefaultMessageResponse = TypedCallResponseMap[MessageKey];
 
-const MAX_DEBUG_ARRAY_ITEMS = 20;
-const MAX_DEBUG_OBJECT_KEYS = 40;
-const MAX_DEBUG_STRING_LENGTH = 512;
-const MAX_DEBUG_DEPTH = 4;
 const HIGH_VOLUME_DEBUG_CALLS = new Set([
   'FilesystemFileRead',
   'FilesystemFileWrite',
@@ -51,100 +50,37 @@ const HIGH_VOLUME_DEBUG_CALLS = new Set([
   'FirmwareUpload',
   'ResourceAck',
 ]);
+const DEVICE_SESSION_CALLS = new Set([
+  'DeviceSessionGet',
+  'DeviceSessionAskPin',
+  'DeviceSessionAskPassphrase',
+]);
+const DEVICE_CONTROL_CALLS = new Set([
+  'DeviceReboot',
+  'DeviceSettingsGet',
+  'DeviceSettingsSet',
+  'DeviceSettingsPageShow',
+  'DeviceCertificateWrite',
+  'DeviceCertificateRead',
+  'DeviceCertificateSign',
+  'DeviceMiscUsbMscControl',
+]);
+
+// Older Protocol V2 firmware may omit the cancellation subcode, so retain a
+// narrow message fallback for compatibility.
+const isProtocolV2ActionCancelledMessage = (message: string) =>
+  /^(?:cancel(?:led|ed)(?: on device)?|confirm dismissed|update cancel(?:led|ed)|user cancel(?:led|ed)(?:\s+.*)?)$/i.test(
+    message
+  );
 
 function shouldReduceDebugForCall(type: string) {
   return HIGH_VOLUME_DEBUG_CALLS.has(type);
 }
 
-function getBinaryByteLength(value: unknown): number | undefined {
-  if (value instanceof ArrayBuffer) {
-    return value.byteLength;
-  }
-
-  if (ArrayBuffer.isView(value)) {
-    return value.byteLength;
-  }
-
-  if (typeof Blob !== 'undefined' && value instanceof Blob) {
-    return value.size;
-  }
-
-  return undefined;
-}
-
-function summarizeRedactedData(value: unknown): string {
-  const byteLength = getBinaryByteLength(value);
-  if (byteLength !== undefined) {
-    return `[redacted data: ${byteLength} bytes]`;
-  }
-
-  if (typeof value === 'string') {
-    return `[redacted data: string length=${value.length}]`;
-  }
-
-  if (Array.isArray(value)) {
-    return `[redacted data: array length=${value.length}]`;
-  }
-
-  if (value && typeof value === 'object') {
-    return `[redacted data: object keys=${Object.keys(value).length}]`;
-  }
-
-  return `[redacted data: ${typeof value}]`;
-}
-
-function sanitizeDebugPayload(value: unknown, key = '', depth = 0): unknown {
-  if (key === 'data' && value !== null && value !== undefined) {
-    return summarizeRedactedData(value);
-  }
-
-  const byteLength = getBinaryByteLength(value);
-  if (byteLength !== undefined) {
-    return `[binary: ${byteLength} bytes]`;
-  }
-
-  if (typeof value === 'string') {
-    return value.length > MAX_DEBUG_STRING_LENGTH
-      ? `${value.slice(0, MAX_DEBUG_STRING_LENGTH)}... (len=${value.length})`
-      : value;
-  }
-
-  if (!value || typeof value !== 'object') {
-    return value;
-  }
-
-  if (depth >= MAX_DEBUG_DEPTH) {
-    return Array.isArray(value)
-      ? `[array length=${value.length}]`
-      : `[object keys=${Object.keys(value).length}]`;
-  }
-
-  if (Array.isArray(value)) {
-    const items = value
-      .slice(0, MAX_DEBUG_ARRAY_ITEMS)
-      .map(item => sanitizeDebugPayload(item, key, depth + 1));
-    if (value.length > MAX_DEBUG_ARRAY_ITEMS) {
-      items.push(`... (${value.length - MAX_DEBUG_ARRAY_ITEMS} more)`);
-    }
-    return items;
-  }
-
-  const entries = Object.entries(value).slice(0, MAX_DEBUG_OBJECT_KEYS);
-  const sanitized: Record<string, unknown> = {};
-  entries.forEach(([entryKey, entryValue]) => {
-    sanitized[entryKey] = sanitizeDebugPayload(entryValue, entryKey, depth + 1);
-  });
-  if (Object.keys(value).length > MAX_DEBUG_OBJECT_KEYS) {
-    sanitized.__truncated__ = `${Object.keys(value).length - MAX_DEBUG_OBJECT_KEYS} more keys`;
-  }
-  return sanitized;
-}
-
 /**
- * 交互式 Ack（ButtonAck / PinMatrixAck / PassphraseAck 等）不应继承原调用的
- * timeoutMs：设备在等待用户操作（确认、输入 PIN/passphrase），思考时间不可预估，
- * 沿用业务调用的超时会把用户操作截断。仅保留 expectedTypes / intermediateTypes
- * 等与响应类型相关的选项。
+ * Interactive acknowledgements must not inherit timeoutMs from the original call.
+ * User confirmation and PIN/passphrase entry have unbounded think time. Preserve only
+ * response-related options such as expectedTypes and intermediateTypes.
  */
 const stripInteractiveAckTimeout = (
   options?: TransportCallOptions
@@ -326,20 +262,40 @@ export class DeviceCommands {
     if (this.disposed) {
       return;
     }
-    this.dispose(true);
-    if (this.callPromise) {
-      try {
-        await Promise.all([
-          new Promise((_resolve, reject) =>
-            // eslint-disable-next-line no-promise-executor-return
-            setTimeout(() => reject(new Error('cancel timeout')), 10 * 1000)
-          ),
-          await this.callPromise,
-        ]);
-      } catch {
-        // device error
+    const activeCall = this.callPromise;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
+    const cancellation = (async () => {
+      await this.dispose(true);
+      await activeCall?.catch(() => undefined);
+    })();
+
+    try {
+      await Promise.race([
+        cancellation,
+        new Promise<void>(resolve => {
+          timer = setTimeout(() => {
+            timedOut = true;
+            resolve();
+          }, 10 * 1000);
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+      if (
+        timedOut &&
+        this.transport.name === 'ReactNativeBleTransport' &&
+        this.transport.disconnect
+      ) {
+        await this.transport.disconnect(this.mainId).catch(error => {
+          Log.debug('BLE cancellation timeout disconnect error (ignored)', error);
+        });
+      }
+      if (this.callPromise === activeCall) {
         this.callPromise = undefined;
       }
+      // The cancellation work may finish after the bounded wait.
+      cancellation.catch(() => undefined);
     }
   }
 
@@ -351,22 +307,28 @@ export class DeviceCommands {
   ): Promise<DefaultMessageResponse> {
     const shouldReduceDebug = shouldReduceDebugForCall(type);
     if (!shouldReduceDebug) {
-      Log.debug('[DeviceCommands] [call] Sending', type);
+      Log.debug(
+        '[DeviceCommands] [call] Sending',
+        type,
+        getSafeTransportLogPayload(msg ?? {}, type)
+      );
     }
 
     try {
       const promise = this.transport.call(this.mainId, type, msg ?? {}, options) as any;
       this.callPromise = promise;
       const res = await promise;
-      if (res.type === 'Failure') {
-        LogCore.debug('[DeviceCommands] [call] Received', res.type, res.message);
-      } else if (!shouldReduceDebug) {
-        LogCore.debug('[DeviceCommands] [call] Received', res.type);
-      }
       return res;
     } catch (error) {
-      LogCore.debug('[DeviceCommands] [call] Received error', error);
-      if (error.errorCode === HardwareErrorCode.BleDeviceBondError) {
+      LogCore.debug('[DeviceCommands] [call] Received error', {
+        request: type,
+        errorCode: error?.errorCode,
+        response: getSafeTransportLogPayload(error?.response?.data, type),
+      });
+      if (
+        error.errorCode === HardwareErrorCode.BleDeviceBondError ||
+        error.errorCode === HardwareErrorCode.BlePeerRemovedPairingInformation
+      ) {
         return {
           type: 'BleDeviceBondError',
           message: {
@@ -386,9 +348,6 @@ export class DeviceCommands {
         }
       }
 
-      if (responseData) {
-        Log.debug('error response', responseData);
-      }
       if (responseError === 'device disconnected during action') {
         return { type: 'BridgeDeviceDisconnected', message: { error: responseError } } as any;
       }
@@ -433,31 +392,6 @@ export class DeviceCommands {
       );
     }
 
-    // Structured log of actual outgoing payloads (skip acks)
-    try {
-      const skipTypes: MessageKey[] = [
-        'ButtonAck',
-        'PinMatrixAck',
-        'PassphraseAck',
-        'Cancel',
-        'BixinPinInputOnDevice',
-        'FilesystemFileRead',
-        'FilesystemFileWrite',
-        'FileRead',
-        'FileWrite',
-        'EmmcFileRead',
-        'EmmcFileWrite',
-        'FirmwareUpload',
-        'ResourceAck',
-      ] as any;
-      if (!skipTypes.includes(type) && msg) {
-        // Use debug channel to avoid noise escalation
-        Log.debug('[DeviceCommands] [typedCall] Sending payload', type, sanitizeDebugPayload(msg));
-      }
-    } catch (e) {
-      // ignore logging errors
-    }
-
     const expectedTypes = Array.isArray(resType) ? resType : resType.split('|');
     const response = await this._commonCall(type, msg, {
       ...options,
@@ -479,7 +413,6 @@ export class DeviceCommands {
             request: type,
             expected: resType,
             received: response.type,
-            response: sanitizeDebugPayload(response.message),
           });
           // Do not intercept CallMethodError
           // Do not intercept “assertType: Response of unexpected type” error
@@ -491,6 +424,9 @@ export class DeviceCommands {
           if (error.message.indexOf('BleDeviceBondError') > -1) {
             throw ERRORS.TypedError(HardwareErrorCode.BleDeviceBondError);
           }
+          if (error.message.indexOf('BlePeerRemovedPairingInformation') > -1) {
+            throw ERRORS.TypedError(HardwareErrorCode.BlePeerRemovedPairingInformation);
+          }
           if (error.message.indexOf('BridgeDeviceDisconnected') > -1) {
             throw ERRORS.TypedError(HardwareErrorCode.BridgeDeviceDisconnected);
           }
@@ -519,12 +455,14 @@ export class DeviceCommands {
     options?: TransportCallOptions
   ): Promise<DefaultMessageResponse> {
     try {
-      if (shouldReduceDebugForCall(callType)) {
-        // 高频文件写入每个 chunk 都会经过这里，避免 debug log 反向拖慢传输。
-      } else if (DataManager.getSettings('env') === 'react-native') {
-        Log.debug('_filterCommonTypes: ', JSON.stringify(sanitizeDebugPayload(res)));
-      } else {
-        Log.debug('_filterCommonTypes: ', sanitizeDebugPayload(res));
+      if (!shouldReduceDebugForCall(callType)) {
+        Log.debug('_filterCommonTypes: ', {
+          request: callType,
+          response: {
+            type: res.type,
+            message: getSafeTransportLogPayload(res.message, res.type),
+          },
+        });
       }
     } catch (error) {
       // ignore
@@ -563,7 +501,7 @@ export class DeviceCommands {
         if (message === 'Please confirm the BlindSign enabled') {
           error = ERRORS.TypedError(HardwareErrorCode.BlindSignDisabled);
         }
-        if (message === 'File already exists') {
+        if (message === 'File already exists' || message === 'NFT already exists') {
           error = ERRORS.TypedError(HardwareErrorCode.FileAlreadyExists);
         }
         if (message?.includes('bytes overflow')) {
@@ -577,10 +515,96 @@ export class DeviceCommands {
         }
       }
 
-      if (code === 'Failure_ProcessError') {
+      if (isProtocolV2LinkDisabledFailure(code, message)) {
+        error = ERRORS.TypedError(HardwareErrorCode.BleUnavailableWhileUsbConnected, undefined, {
+          failureCode: code,
+          firmwareMessage: message,
+        });
+      } else if (code === 'Failure_ProcessError') {
+        const normalizedMessage = message?.trim() ?? '';
+        const isProtocolV2ActionCancelledFailure =
+          this.device.isProtocolV2() && isProtocolV2ActionCancelledMessage(normalizedMessage);
+        const isProtocolV2DeviceBusyFailure =
+          this.device.isProtocolV2() &&
+          DEVICE_CONTROL_CALLS.has(callType) &&
+          subcode === DeviceErrorCode.DeviceError_Busy;
         const isLegacyProtocolV2LockedFailure =
-          this.device.isProtocolV2() && /^device (?:is )?locked$/i.test(message?.trim() ?? '');
-        if (subcode === 9 || isLegacyProtocolV2LockedFailure) {
+          this.device.isProtocolV2() && /^device (?:is )?locked$/i.test(normalizedMessage);
+        if (
+          DEVICE_SESSION_CALLS.has(callType) &&
+          subcode === DeviceSessionErrorCode.DeviceSessionError_InvalidSession
+        ) {
+          error = ERRORS.TypedError(HardwareErrorCode.WalletSessionInvalid, message, {
+            failureCode: code,
+            subcode,
+            firmwareMessage: message,
+          });
+        } else if (
+          DEVICE_SESSION_CALLS.has(callType) &&
+          subcode === DeviceSessionErrorCode.DeviceSessionError_UserCancelled
+        ) {
+          error = ERRORS.TypedError(HardwareErrorCode.ActionCancelled, message, {
+            failureCode: code,
+            subcode,
+            firmwareMessage: message,
+          });
+        } else if (
+          DEVICE_SESSION_CALLS.has(callType) &&
+          subcode === DeviceSessionErrorCode.DeviceSessionError_AttachPinUnavailable
+        ) {
+          error = ERRORS.TypedError(HardwareErrorCode.DeviceCheckUnlockTypeError, message, {
+            failureCode: code,
+            subcode,
+            firmwareMessage: message,
+          });
+        } else if (
+          DEVICE_SESSION_CALLS.has(callType) &&
+          subcode === DeviceSessionErrorCode.DeviceSessionError_PassphraseDisabled
+        ) {
+          error = ERRORS.TypedError(HardwareErrorCode.DeviceNotOpenedPassphrase, message, {
+            failureCode: code,
+            subcode,
+            firmwareMessage: message,
+          });
+        } else if (
+          DEVICE_SESSION_CALLS.has(callType) &&
+          (subcode === DeviceSessionErrorCode.DeviceSessionError_Busy ||
+            /^(?:busy|another flow in progress)$/i.test(normalizedMessage))
+        ) {
+          error = ERRORS.TypedError(HardwareErrorCode.DeviceBusy, message, {
+            failureCode: code,
+            subcode,
+            firmwareMessage: message,
+          });
+        } else if (
+          callType === 'DeviceSessionAskPin' &&
+          /^passphrase disabled$/i.test(normalizedMessage)
+        ) {
+          error = ERRORS.TypedError(HardwareErrorCode.DeviceNotOpenedPassphrase, message, {
+            failureCode: code,
+            subcode,
+            firmwareMessage: message,
+          });
+        } else if (isProtocolV2DeviceBusyFailure) {
+          error = ERRORS.TypedError(HardwareErrorCode.DeviceBusy, message, {
+            failureCode: code,
+            subcode,
+            firmwareMessage: message,
+          });
+        } else if (
+          (DEVICE_CONTROL_CALLS.has(callType) &&
+            subcode === DeviceErrorCode.DeviceError_ActionCancelled) ||
+          isProtocolV2ActionCancelledFailure
+        ) {
+          error = ERRORS.TypedError(HardwareErrorCode.ActionCancelled, message, {
+            failureCode: code,
+            subcode,
+            firmwareMessage: message,
+          });
+        } else if (
+          subcode === DeviceErrorCode.DeviceError_DeviceLocked ||
+          isLegacyProtocolV2LockedFailure
+        ) {
           error = ERRORS.TypedError(HardwareErrorCode.DeviceLocked, message, {
             failureCode: code,
             subcode,
@@ -663,7 +687,7 @@ export class DeviceCommands {
 
     if (res.type === 'PassphraseRequest') {
       const existsAttachPinUser = res.message.exists_attach_pin_user;
-      return this._promptPassphrase({
+      return this.promptPassphrase({
         existsAttachPinUser,
       }).then(response => {
         const { passphrase, passphraseOnDevice, attachPinOnDevice } = response;
@@ -761,10 +785,27 @@ export class DeviceCommands {
     });
   }
 
-  _promptPassphrase(options: PassphraseRequestPayload) {
+  promptPassphrase(
+    options: PassphraseRequestPayload,
+    promptOptions: { cancelDeviceOnReject?: boolean } = {}
+  ) {
     return new Promise<PassphrasePromptResponse>((resolve, reject) => {
-      const cancelAndReject = (_error?: Error) =>
-        cancelDeviceInPrompt(this.device, false)
+      const cancelAndReject = (_error?: Error) => {
+        const rejectWithCancelledError = () => {
+          reject(
+            ERRORS.TypedError(
+              HardwareErrorCode.CallQueueActionCancelled,
+              `${DEVICE.PASSPHRASE} canceled`
+            )
+          );
+        };
+
+        if (promptOptions.cancelDeviceOnReject === false) {
+          rejectWithCancelledError();
+          return Promise.resolve();
+        }
+
+        return cancelDeviceInPrompt(this.device, false)
           .then(onCancel => {
             const error = ERRORS.TypedError(
               HardwareErrorCode.CallQueueActionCancelled,
@@ -781,6 +822,7 @@ export class DeviceCommands {
           .catch(error => {
             reject(error);
           });
+      };
 
       if (this.device.listenerCount(DEVICE.PASSPHRASE) > 0) {
         this.device.setCancelableAction(cancelAndReject);

package/src/device/DeviceConnector.ts

@@ -1,3 +1,4 @@
+import { isProtocolV2LinkDisabledError } from '@onekeyfe/hd-transport';
 import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
 
 import { safeThrowError } from '../constants';
@@ -14,7 +15,7 @@ import type { OneKeyDeviceInfo as DeviceDescriptor, Transport } from '@onekeyfe/
 const Log = getLogger(LoggerNames.DeviceConnector);
 
 export default class DeviceConnector {
-  transport: Transport;
+  transport?: Transport;
 
   listenTimestamp = 0;
 
@@ -30,9 +31,21 @@ export default class DeviceConnector {
     DevicePool.setConnector(this);
   }
 
+  private getActiveTransport(): Transport {
+    const transport = this.transport ?? TransportManager.getTransport();
+    if (!transport) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.TransportNotConfigured,
+        'Device connector was created before transport initialization'
+      );
+    }
+    this.transport = transport;
+    return transport;
+  }
+
   async enumerate() {
     try {
-      const descriptors = await this.transport.enumerate();
+      const descriptors = await this.getActiveTransport().enumerate();
       this.upcoming = descriptors;
       this._reportDevicesChange();
       return { descriptors } as DeviceDescriptorDiff;
@@ -50,11 +63,10 @@ export default class DeviceConnector {
     let descriptors: DeviceDescriptor[];
 
     try {
+      const transport = this.getActiveTransport();
       Log.debug('Start listening', current);
       this.listenTimestamp = new Date().getTime();
-      descriptors = waitForEvent
-        ? await this.transport.listen(current)
-        : await this.transport.enumerate();
+      descriptors = waitForEvent ? await transport.listen(current) : await transport.enumerate();
       if (!this.listening) return; // do not continue if stop() was called
 
       this.upcoming = descriptors;
@@ -82,44 +94,63 @@ export default class DeviceConnector {
     path: string,
     session?: string | null,
     forceCleanRunPromise?: boolean,
-    connectProtocol?: HardwareConnectProtocol
+    expectedProtocol?: HardwareConnectProtocol,
+    protocolHint?: HardwareConnectProtocol,
+    forceProtocolDetection?: boolean
   ) {
-    Log.debug('acquire', path, session, connectProtocol);
+    Log.debug('acquire', path, session, expectedProtocol, protocolHint);
     const env = DataManager.getSettings('env');
     try {
+      const transport = this.getActiveTransport();
       let res;
       if (DataManager.isBleConnect(env)) {
-        res = await this.transport.acquire({
+        res = await transport.acquire({
           uuid: path,
           forceCleanRunPromise,
-          expectedProtocol: connectProtocol,
+          expectedProtocol,
+          protocolHint,
+          forceProtocolDetection,
         });
       } else {
-        res = await this.transport.acquire({
+        res = await transport.acquire({
           path,
           previous: session ?? null,
-          expectedProtocol: connectProtocol,
+          expectedProtocol,
+          protocolHint,
+          forceProtocolDetection,
         });
       }
-      if (connectProtocol) {
-        const detectedProtocol = this.transport.getProtocolType(path);
-        if (detectedProtocol !== connectProtocol) {
+      if (expectedProtocol) {
+        // The acquire response is the stable snapshot from this active probe. A delayed
+        // disconnect from an older generation may clear caches, so do not rely on cache alone.
+        const acquiredProtocol =
+          typeof res === 'object' && res !== null
+            ? (res as DeviceDescriptor).protocolType
+            : undefined;
+        const detectedProtocol = acquiredProtocol ?? transport.getProtocolType(path);
+        if (detectedProtocol !== expectedProtocol) {
           throw ERRORS.TypedError(
             HardwareErrorCode.RuntimeError,
-            `Device protocol mismatch: expected ${connectProtocol}, detected ${detectedProtocol}`
+            `Device protocol mismatch: expected ${expectedProtocol}, detected ${detectedProtocol}`
           );
         }
       }
       return res;
     } catch (error) {
       Log.error('acquire error: ', error.message);
+      if (isProtocolV2LinkDisabledError(error)) {
+        throw ERRORS.TypedError(HardwareErrorCode.BleUnavailableWhileUsbConnected, undefined, {
+          failureCode: error.failureCode,
+          firmwareMessage: error.firmwareMessage,
+        });
+      }
       safeThrowError(error);
     }
   }
 
-  async release(session: string, onclose: boolean) {
+  async release(session: string, onclose: boolean, keepSession?: boolean) {
     try {
-      const res = await this.transport.release(session, onclose);
+      const res = await this.getActiveTransport().release(session, onclose, keepSession);
       return res;
     } catch (error) {
       safeThrowError(error);
@@ -128,8 +159,9 @@ export default class DeviceConnector {
 
   async disconnect(session: string | undefined | null) {
     try {
-      if (this.transport.disconnect && !!session) {
-        await this.transport.disconnect(session);
+      const transport = this.getActiveTransport();
+      if (transport.disconnect && !!session) {
+        await transport.disconnect(session);
       }
     } catch (error) {
       safeThrowError(error);
@@ -137,10 +169,11 @@ export default class DeviceConnector {
   }
 
   promptDeviceAccess(): Promise<USBDevice | BluetoothDevice | null> {
-    if (!this.transport.promptDeviceAccess) {
+    const transport = this.getActiveTransport();
+    if (!transport.promptDeviceAccess) {
       return Promise.resolve(null);
     }
-    return this.transport.promptDeviceAccess();
+    return transport.promptDeviceAccess();
   }
 
   _reportDevicesChange() {

package/src/device/DeviceFeaturesState.ts

@@ -0,0 +1,25 @@
+import type { Features } from '../types';
+
+/**
+ * Merge a field-level device-state patch.
+ *
+ * `undefined` means the response omitted a field and preserves the cache; `null`
+ * means the device explicitly returned an empty value and must be cached. Callers
+ * provide complete object fields such as raw; this function does not deep-merge.
+ */
+export function mergeDeviceFeaturesPatch(previous: Features, patch: Partial<Features>): Features {
+  let next = previous;
+
+  for (const [key, value] of Object.entries(patch) as Array<
+    [keyof Features, Features[keyof Features] | undefined]
+  >) {
+    if (value !== undefined && !Object.is(previous[key], value)) {
+      if (next === previous) {
+        next = { ...previous };
+      }
+      (next as Record<keyof Features, Features[keyof Features]>)[key] = value;
+    }
+  }
+
+  return next;
+}