homebridge-nest-accfactory 0.3.0 → 0.3.2

package/dist/HomeKitDevice.js

@@ -1,41 +1,42 @@
 // HomeKitDevice class
 //
-// This is the base class for all HomeKit accessories we code for in Homebridge/HAP-NodeJS
+// Base class for all HomeKit accessories using Homebridge or HAP-NodeJS.
 //
-// The deviceData structure should at a minimum contain the following elements:
+// Provides internal device tracking, metadata validation, lifecycle management,
+// centralized message dispatch, and optional EveHome-compatible history logging.
 //
-// Homebridge Plugin:
+// The `deviceData` object must include:
+//   serialNumber, softwareVersion, description, manufacturer, model
 //
-// serialNumber
-// softwareVersion
-// description
-// manufacturer
-// model
+// For enabling EveHome history support, include in the `deviceData`:
+//   eveHistory
 //
-// HAP-NodeJS Library Accessory:
+// For HAP-NodeJS standalone mode, also required:
+//   hkUsername, hkPairingCode
 //
-// serialNumber
-// softwareVersion
-// description
-// manufacturer
-// model
-// hkUsername
-// hkPairingCode
+// The following static constants should be defined in subclasses:
+//   HomeKitDevice.PLUGIN_NAME           // Required (string)
+//   HomeKitDevice.PLATFORM_NAME         // Required (string)
+//   HomeKitDevice.TYPE                  // Optional (device type string)
+//   HomeKitDevice.VERSION               // Optional (device code version)
+//   HomeKitDevice.EVEHOME               // Optional (EveHome-compatible history module)
 //
-// Following constants should be overridden in the module loading this class file
+// The following instance methods can be optionally implemented by subclasses:
+//   async onAdd(message, ...args)       // Called when HomeKitDevice.ADD is received
+//   async onUpdate(deviceData, ...args) // Called when HomeKitDevice.UPDATE is received
+//   async onRemove(message, ...args)    // Called when HomeKitDevice.REMOVE is received
+//   async onHistory(target, entry)      // Called after a history entry is logged
+//   async onGet(message, ...args)       // Called when HomeKitDevice.GET is received
+//   async onSet(message, ...args)       // Called when HomeKitDevice.SET is received
+//   async onMessage(type, message)      // Called for unhandled or custom message types
 //
-// HomeKitDevice.HOMEKITHISTORY
-// HomeKitDevice.PLUGIN_NAME
-// HomeKitDevice.PLATFORM_NAME
-// HomeKitDevice.TYPE
-// HomeKitDevice.VERSION
+// Messages should be sent via:
+//   await device.message(type, message, ...args);
 //
-// The following functions should be overriden in your class which extends this
+// All internal lifecycle events (`add`, `update`, `remove`, `history`, `get`, `set`) and external
+// interactions should use the `message()` dispatch system for consistency.
 //
-// HomeKitDevice.setupDevice()
-// HomeKitDevice.removeDevice()
-// HomeKitDevice.updateDevice(deviceData)
-// HomeKitDevice.messageDevice(type, message)
+// See README.md for usage examples and detailed documentation.
 //
 // Mark Hulskamp
 'use strict';
@@ -45,106 +46,116 @@ import crypto from 'crypto';
 import EventEmitter from 'node:events';
 
 // Define constants
-const HK_PIN_3_2_3 = /^\d{3}-\d{2}-\d{3}$/;
-const HK_PIN_4_4 = /^\d{4}-\d{4}$/;
-const MAC_ADDR = /^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$/;
-const LOGLEVELS = {
-  info: 'info',
-  success: 'success',
-  warn: 'warn',
-  error: 'error',
-  debug: 'debug',
+const LOG_LEVELS = {
+  INFO: 'info',
+  SUCCESS: 'success',
+  WARN: 'warn',
+  ERROR: 'error',
+  DEBUG: 'debug',
 };
 
 // Define our HomeKit device class
-class HomeKitDevice {
-  static UPDATE = 'HomeKitDevice.update'; // Device update message
-  static REMOVE = 'HomeKitDevice.remove'; // Device remove message
-  static SET = 'HomeKitDevice.set'; // Device set property message
-  static GET = 'HomeKitDevice.get'; // Device get property message
+export default class HomeKitDevice extends EventEmitter {
+  // Device messages
+  static ADD = 'HomeKitDevice.onAdd';
+  static UPDATE = 'HomeKitDevice.onUpdate';
+  static REMOVE = 'HomeKitDevice.onRemove';
+  static HISTORY = 'HomeKitDevice.onHistory';
+  static SET = 'HomeKitDevice.onSet';
+  static GET = 'HomeKitDevice.onGet';
+  static MESSAGE = 'HomeKitDevice.onMessage';
+  static SHUTDOWN = 'HomeKitDevice.onShutdown';
+
+  // HomeKit pin format and MAC address regex's
+  static HK_PIN_3_2_3 = /^\d{3}-\d{2}-\d{3}$/;
+  static HK_PIN_4_4 = /^\d{4}-\d{4}$/;
+  static MAC_ADDR = /^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$/;
 
   // Override this in the class which extends
   static PLUGIN_NAME = undefined; // Homebridge plugin name
   static PLATFORM_NAME = undefined; // Homebridge platform name
-  static HISTORY = undefined; // HomeKit History object
+  static EVEHOME = undefined; // HomeKit History object
   static TYPE = 'base'; // String naming type of device
-  static VERSION = '2025.06.12'; // Code version
+  static VERSION = '2025.07.29'; // Code version
+
+  // Backend types
+  static HOMEBRIDGE = 'homebridge';
+  static HAP_NODEJS = 'hap-nodejs';
+
+  // Internal device and listener registry
+  static #listeners = {};
+  static #deviceRegistry = new Map();
 
   deviceData = {}; // The devices data we store
   historyService = undefined; // HomeKit history service
   accessory = undefined; // HomeKit accessory service for this device
   hap = undefined; // HomeKit Accessory Protocol (HAP) API stub
   log = undefined; // Logging function object
-  uuid = undefined; // UUID for this instance
+  backend = undefined; // Backend library type
 
   // Internal data only for this class
-  #platform = undefined; // Homebridge platform api
-  #eventEmitter = undefined; // Event emitter to use for comms
+  #uuid = undefined; // UUID for this instance
+  #platform = undefined; // Homebridge platform API
   #postSetupDetails = []; // Use for extra output details once a device has been setup
 
-  constructor(accessory, api, log, eventEmitter, deviceData) {
+  constructor(accessory = undefined, api = undefined, log = undefined, deviceData = {}) {
+    super(); // Setup event emitter for our class ONLY
+
     // Validate the passed in logging object. We are expecting certain functions to be present
-    if (Object.keys(LOGLEVELS).every((fn) => typeof log?.[fn] === 'function')) {
+    if (Object.values(LOG_LEVELS).every((fn) => typeof log?.[fn] === 'function')) {
       this.log = log;
     }
 
-    // Workout if we're running under Homebridge or HAP-NodeJS library
-    if (isNaN(api?.version) === false && typeof api?.hap === 'object' && api?.HAPLibraryVersion === undefined) {
-      // We have the Homebridge version number and hap API object
+    // Determine runtime environment (Homebridge vs HAP-NodeJS)
+    if (typeof api?.hap === 'object' && isNaN(api?.version) === false && typeof api?.HAPLibraryVersion === 'undefined') {
       this.hap = api.hap;
       this.#platform = api;
-
-      this.postSetupDetail('Homebridge backend', LOGLEVELS.debug);
+      this.backend = HomeKitDevice.HOMEBRIDGE;
+      this.postSetupDetail('Homebridge backend', LOG_LEVELS.DEBUG);
     }
 
-    if (typeof api?.HAPLibraryVersion === 'function' && api?.version === undefined && api?.hap === undefined) {
-      // As we're missing the Homebridge entry points but have the HAP library version
+    if (typeof api?.hap === 'undefined' && isNaN(api?.version) === true && typeof api?.HAPLibraryVersion === 'function') {
       this.hap = api;
-
-      this.postSetupDetail('HAP-NodeJS library', LOGLEVELS.debug);
+      this.backend = HomeKitDevice.HAP_NODEJS;
+      this.postSetupDetail('HAP-NodeJS library', LOG_LEVELS.DEBUG);
     }
 
     // Generate UUID for this device instance
     // Will either be a random generated one or HAP generated one
     // HAP is based upon defined plugin name and devices serial number
-    this.uuid = HomeKitDevice.generateUUID(HomeKitDevice.PLUGIN_NAME, api, deviceData.serialNumber);
+    this.#uuid = HomeKitDevice.generateUUID(HomeKitDevice.PLUGIN_NAME, api, deviceData.serialNumber);
+
+    // Register this device instance in the static device registry
+    HomeKitDevice.#deviceRegistry.set(this.#uuid, this);
 
     // See if we were passed in an existing accessory object or array of accessory objects
     // Mainly used to restore a Homebridge cached accessory
-    if (typeof accessory === 'object' && this.#platform !== undefined) {
+    if (typeof accessory === 'object' && this.backend === HomeKitDevice.HOMEBRIDGE) {
       if (Array.isArray(accessory) === true) {
-        this.accessory = accessory.find((accessory) => this?.uuid !== undefined && accessory?.UUID === this.uuid);
+        this.accessory = accessory.find((accessory) => this?.uuid !== undefined && accessory?.UUID === this.#uuid);
       }
-      if (Array.isArray(accessory) === false && accessory?.UUID === this.uuid) {
+      if (Array.isArray(accessory) === false && accessory?.UUID === this.#uuid) {
         this.accessory = accessory;
       }
     }
 
-    // Validate if eventEmitter object passed to us is an instance of EventEmitter
-    // If valid, setup an event listener for messages to this device using our generated uuid
-    if (eventEmitter instanceof EventEmitter === true) {
-      this.#eventEmitter = eventEmitter;
-      this.#eventEmitter.addListener(this.uuid, this.#message.bind(this));
-    }
-
     // Make a clone of current data and store in this object
     // Important that we done have a 'linked' copy of the object data
-    // eslint-disable-next-line no-undef
     this.deviceData = structuredClone(deviceData);
   }
 
   // Class functions
-  async add(accessoryName, accessoryCategory, useHistoryService) {
+  async add(hapAccessoryName, hapCategory, enableHistory = false) {
     if (
       this.hap === undefined ||
       typeof HomeKitDevice.PLUGIN_NAME !== 'string' ||
       HomeKitDevice.PLUGIN_NAME === '' ||
       typeof HomeKitDevice.PLATFORM_NAME !== 'string' ||
       HomeKitDevice.PLATFORM_NAME === '' ||
-      typeof accessoryName !== 'string' ||
-      accessoryName === '' ||
-      typeof this.hap.Categories[accessoryCategory] === 'undefined' ||
-      typeof useHistoryService !== 'boolean' ||
+      typeof hapAccessoryName !== 'string' ||
+      hapAccessoryName === '' ||
+      typeof this.hap.Categories[hapCategory] === 'undefined' ||
+      typeof enableHistory !== 'boolean' ||
       typeof this.deviceData !== 'object' ||
       typeof this.deviceData?.serialNumber !== 'string' ||
       this.deviceData.serialNumber === '' ||
@@ -157,32 +168,42 @@ class HomeKitDevice {
       this.deviceData.manufacturer === '' ||
       (this.#platform === undefined &&
         (typeof this.deviceData?.hkPairingCode !== 'string' ||
-          (new RegExp(HK_PIN_3_2_3).test(this.deviceData.hkPairingCode) === false &&
-            new RegExp(HK_PIN_4_4).test(this.deviceData.hkPairingCode) === false) ||
+          (HomeKitDevice.HK_PIN_3_2_3.test(this.deviceData.hkPairingCode) === false &&
+            HomeKitDevice.HK_PIN_4_4.test(this.deviceData.hkPairingCode) === false) ||
           typeof this.deviceData?.hkUsername !== 'string' ||
-          new RegExp(MAC_ADDR).test(this.deviceData.hkUsername) === false))
+          HomeKitDevice.MAC_ADDR.test(this.deviceData.hkUsername) === false))
     ) {
       return;
     }
 
     // If we do not have an existing accessory object, create a new one
-    if (this.accessory === undefined && this.#platform !== undefined) {
+    if (
+      this.accessory === undefined &&
+      typeof this.#platform?.platformAccessory === 'function' &&
+      typeof this.#platform?.registerPlatformAccessories === 'function' &&
+      this.backend === HomeKitDevice.HOMEBRIDGE
+    ) {
       // Create Homebridge platform accessory
-      this.accessory = new this.#platform.platformAccessory(this.deviceData.description, this.uuid);
+      this.accessory = new this.#platform.platformAccessory(this.deviceData.description, this.#uuid);
       this.#platform.registerPlatformAccessories(HomeKitDevice.PLUGIN_NAME, HomeKitDevice.PLATFORM_NAME, [this.accessory]);
     }
 
-    if (this.accessory === undefined && this.#platform === undefined) {
+    if (this.accessory === undefined && this.backend === HomeKitDevice.HAP_NODEJS) {
       // Create HAP-NodeJS libray accessory
-      this.accessory = new this.hap.Accessory(accessoryName, this.uuid);
+      this.accessory = new this.hap.Accessory(hapAccessoryName, this.#uuid);
 
       this.accessory.username = this.deviceData.hkUsername;
       this.accessory.pincode = this.deviceData.hkPairingCode;
-      this.accessory.category = accessoryCategory;
+      this.accessory.category = hapCategory;
     }
 
     // Setup accessory information
     let informationService = this.accessory.getService(this.hap.Service.AccessoryInformation);
+    if (informationService === undefined) {
+      this?.log?.error?.('AccessoryInformation service not found on accessory for "%s"', this.deviceData.description);
+      return;
+    }
+
     if (informationService !== undefined) {
       informationService.updateCharacteristic(this.hap.Characteristic.Manufacturer, this.deviceData.manufacturer);
       informationService.updateCharacteristic(this.hap.Characteristic.Model, this.deviceData.model);
@@ -192,248 +213,359 @@ class HomeKitDevice {
     }
 
     // Setup our history service if module has been defined and requested to be active for this device
-    if (typeof HomeKitDevice?.HISTORY === 'function' && this.historyService === undefined && useHistoryService === true) {
-      this.historyService = new HomeKitDevice.HISTORY(this.accessory, this.log, this.hap, {});
+    if (typeof HomeKitDevice?.EVEHOME === 'function' && this.historyService === undefined && enableHistory === true) {
+      this.historyService = new HomeKitDevice.EVEHOME(this.accessory, this.hap, this.log, {});
     }
 
-    if (typeof this?.setupDevice === 'function') {
-      try {
-        this.postSetupDetail('Serial number "%s"', this.deviceData.serialNumber, LOGLEVELS.debug);
+    this.postSetupDetail('Serial number "%s"', this.deviceData.serialNumber, LOG_LEVELS.DEBUG);
 
-        await this.setupDevice();
-
-        if (this.historyService?.EveHome !== undefined) {
-          this.postSetupDetail('EveHome support as "%s"', this.historyService.EveHome.evetype);
-        }
+    // Trigger registered handlers (onAdd + listeners)
+    await this.message(HomeKitDevice.ADD);
 
-        this?.log?.info?.('Setup %s %s as "%s"', this.deviceData.manufacturer, this.deviceData.model, this.deviceData.description);
+    if (this.historyService?.EveHome !== undefined) {
+      this.postSetupDetail('EveHome support as "%s"', this.historyService.EveHome.evetype);
+    }
 
-        this.#postSetupDetails.forEach((entry) => {
-          if (typeof entry === 'string') {
-            this?.log?.[LOGLEVELS.info]?.('  += %s', entry);
-          } else if (typeof entry?.message === 'string') {
-            let level =
-              Object.hasOwn(LOGLEVELS, entry?.level) && typeof this?.log?.[entry?.level] === 'function' ? entry.level : LOGLEVELS.info;
-            this?.log?.[level]?.('  += ' + entry.message, ...(Array.isArray(entry?.args) ? entry.args : []));
-          }
-        });
-      } catch (error) {
-        this?.log?.error('setupDevice call for device "%s" failed. Error was', this.deviceData.description, error);
+    this?.log?.success?.('Setup %s %s as "%s"', this.deviceData.manufacturer, this.deviceData.model, this.deviceData.description);
+    this.#postSetupDetails.forEach((entry) => {
+      if (typeof entry === 'string') {
+        this?.log?.[LOG_LEVELS.INFO]?.('  += %s', entry);
+      } else if (typeof entry?.message === 'string') {
+        let level =
+          Object.hasOwn(LOG_LEVELS, entry?.level?.toUpperCase?.()) &&
+          typeof this?.log?.[LOG_LEVELS[entry.level.toUpperCase()]] === 'function'
+            ? LOG_LEVELS[entry.level.toUpperCase()]
+            : LOG_LEVELS.INFO;
+
+        this?.log?.[level]?.('  += ' + entry.message, ...(Array.isArray(entry?.args) ? entry.args : []));
       }
-    }
+    });
 
-    // Perform an initial update using current data
-    this.update(this.deviceData, true);
+    // Trigger registered handlers (onUpdate + listeners) for initial device data updates
+    await this.message(HomeKitDevice.UPDATE, this.deviceData, { force: true });
 
     // If using HAP-NodeJS library, publish accessory on local network
-    if (this.#platform === undefined && this.accessory !== undefined) {
+    if (this.accessory !== undefined && this.backend === HomeKitDevice.HAP_NODEJS) {
       this.accessory.publish({
         username: this.accessory.username,
         pincode: this.accessory.pincode,
         category: this.accessory.category,
       });
 
-      this?.log?.info('  += Advertising as "%s"', this.accessory.displayName);
-      this?.log?.info('  += Pairing code is "%s"', this.accessory.pincode);
+      this?.log?.info?.('  += Advertising as "%s"', this.accessory.displayName);
+      this?.log?.info?.('  += Pairing code is "%s"', this.accessory.pincode);
     }
-    this.#postSetupDetails = []; // Dont' need these anymore
+    this.#postSetupDetails = []; // Don't need these anymore
     return this.accessory; // Return our HomeKit accessory
   }
 
-  remove() {
-    this?.log?.warn?.('Device "%s" has been removed', this.deviceData.description);
+  async remove() {
+    // Trigger registered handlers (onRemove + listeners)
+    await this.message(HomeKitDevice.REMOVE);
+  }
 
-    if (this.#eventEmitter !== undefined) {
-      // Remove listener for 'messages'
-      this.#eventEmitter.removeAllListeners(this.uuid);
+  async update(deviceData, ...args) {
+    if (typeof deviceData !== 'object') {
+      return;
     }
 
-    if (typeof this?.removeDevice === 'function') {
-      try {
-        this.removeDevice();
-      } catch (error) {
-        this?.log?.error('removeDevice call for device "%s" failed. Error was', this.deviceData.description, error);
-      }
-    }
+    // Trigger registered handlers (onUpdate + listeners)
+    await this.message(HomeKitDevice.UPDATE, deviceData, ...args);
+  }
 
-    if (this.accessory !== undefined && this.#platform !== undefined) {
-      // Unregister the accessory from Homebridge platform
-      this.#platform.unregisterPlatformAccessories(HomeKitDevice.PLUGIN_NAME, HomeKitDevice.PLATFORM_NAME, [this.accessory]);
+  async history(target, entry, options = {}) {
+    if (
+      typeof this.historyService !== 'object' ||
+      typeof this.historyService.addHistory !== 'function' ||
+      typeof entry !== 'object' ||
+      typeof target !== 'object' ||
+      typeof target.UUID !== 'string'
+    ) {
+      return;
     }
 
-    if (this.accessory !== undefined && this.#platform === undefined) {
-      // Unpublish the accessory from HAP-NodeJS library
-      this.accessory.unpublish();
+    // Trigger registered handlers (onHistory + listeners)
+    await this.message(HomeKitDevice.HISTORY, target, entry, options);
+  }
+
+  async set(values, ...args) {
+    if (typeof values !== 'object' || values === null) {
+      return;
     }
 
-    this.deviceData = {};
-    this.accessory = undefined;
-    this.historyService = undefined;
-    this.hap = undefined;
-    this.log = undefined;
-    this.uuid = undefined;
-    this.#platform = undefined;
-    this.#eventEmitter = undefined;
+    // Trigger registered handlers (onSet + listeners)
+    await this.message(HomeKitDevice.SET, values, ...args);
+  }
 
-    // Do we destroy this object??
-    // this = null;
-    // delete this;
+  async get(values, ...args) {
+    // Trigger registered handlers (onGet + listeners)
+    return await this.message(HomeKitDevice.GET, values, ...args);
   }
 
-  update(deviceData, forceUpdate) {
-    if (typeof deviceData !== 'object' || typeof forceUpdate !== 'boolean') {
+  static async message(uuid, type, message = undefined, ...args) {
+    if (typeof uuid !== 'string' || uuid === '' || typeof type !== 'string' || type === '') {
       return;
     }
 
-    // Updated data may only contain selected fields, so we'll handle that here by taking our internally stored data
-    // and merge with the updates to ensure we have a complete data object
-    Object.entries(this.deviceData).forEach(([key, value]) => {
-      if (typeof deviceData[key] === 'undefined') {
-        // Updated data doesn't have this key, so add it to our internally stored data
-        deviceData[key] = value;
+    if (typeof message === 'function' || (typeof message === 'object' && message !== null && message?.constructor !== Object)) {
+      if (this.#listeners?.[uuid] === undefined) {
+        this.#listeners[uuid] = {};
+      }
+      if (Array.isArray(this.#listeners[uuid][type]) === false) {
+        this.#listeners[uuid][type] = [];
       }
-    });
 
-    // Check updated device data with our internally stored data. Flag if changes between the two
-    let changedData = false;
-    Object.keys(deviceData).forEach((key) => {
-      if (JSON.stringify(deviceData[key]) !== JSON.stringify(this.deviceData[key])) {
-        changedData = true;
+      let handler, context;
+
+      if (typeof message === 'function' || typeof message === 'string') {
+        handler = message;
+        context = undefined;
+      } else {
+        context = message;
+        handler = typeof type === 'string' ? type.match(/\.?(on[A-Z][a-zA-Z0-9]*)$/)?.[1] : undefined;
       }
-    });
 
-    // If we have any changed data OR we've been requested to force an update, do so here
-    if ((changedData === true || forceUpdate === true) && this.accessory !== undefined) {
-      let informationService = this.accessory.getService(this.hap.Service.AccessoryInformation);
-      if (informationService !== undefined) {
-        // Update details associated with the accessory
-        // ie: Name, Manufacturer, Model, Serial # and firmware version
-        if (typeof deviceData?.description === 'string' && deviceData.description !== this.deviceData.description) {
-          // Update serial number on the HomeKit accessory
-          informationService.updateCharacteristic(this.hap.Characteristic.Name, this.deviceData.description);
+      if (handler !== undefined) {
+        if (this.#listeners?.[uuid]?.[type]?.find?.((h) => h.handler === handler && h.context === context) === undefined) {
+          this.#listeners[uuid][type].push({ handler, context });
         }
+      }
 
-        if (
-          typeof deviceData?.manufacturer === 'string' &&
-          deviceData.manufacturer !== '' &&
-          deviceData.manufacturer !== this.deviceData.manufacturer
-        ) {
-          // Update manufacturer number on the HomeKit accessory
-          informationService.updateCharacteristic(this.hap.Characteristic.Manufacturer, deviceData.manufacturer);
-        }
+      return;
+    }
 
-        if (typeof deviceData?.model === 'string' && deviceData.model !== '' && deviceData.model !== this.deviceData.model) {
-          // Update model on the HomeKit accessory
-          informationService.updateCharacteristic(this.hap.Characteristic.Model, deviceData.model);
-        }
+    // Handle message delivery
+    return await this.#deviceRegistry.get(uuid)?.message?.(type, message, ...args);
+  }
 
-        if (
-          typeof deviceData?.softwareVersion === 'string' &&
-          deviceData.softwareVersion !== '' &&
-          deviceData.softwareVersion !== this.deviceData.softwareVersion
-        ) {
-          // Update software version on the HomeKit accessory
-          informationService.updateCharacteristic(this.hap.Characteristic.FirmwareRevision, deviceData.softwareVersion);
-        }
+  async message(type, message, ...args) {
+    if (typeof type !== 'string' || type === '') {
+      return;
+    }
 
-        // Check for devices serial number changing. Really shouldn't occur, but handle case anyway
-        if (
-          typeof deviceData?.serialNumber === 'string' &&
-          deviceData.serialNumber !== '' &&
-          deviceData.serialNumber.toUpperCase() !== this.deviceData.serialNumber.toUpperCase()
-        ) {
-          this?.log?.warn?.('Serial number on "%s" has changed', deviceData.description);
-          this?.log?.warn?.('This may cause the device to become unresponsive in HomeKit');
+    let result = { call: undefined, handler: undefined };
+    let handled = false;
+    let handler =
+      Array.isArray(HomeKitDevice.#listeners?.[this.#uuid]?.[type]) === true
+        ? HomeKitDevice.#listeners[this.#uuid][type]
+        : HomeKitDevice.#listeners?.[this.#uuid]?.[type] !== undefined
+          ? [HomeKitDevice.#listeners[this.#uuid][type]]
+          : [];
+
+    // Dynamically extract the handler method name from the type string (e.g., "HomeKitDevice.onAdd" becomes "onAdd")
+    // This allows consistent routing to instance methods like onAdd, onSet, onUpdate, etc.
+    let methodName = typeof type === 'string' ? type.match(/\.?(on[A-Z][a-zA-Z0-9]*)$/)?.[1] : undefined;
+
+    // Internal helper to call handlers with error trapping. Will also walk up the prototype chain
+    const callLifecycleHook = async (labelOrFn, ...params) => {
+      let results = [];
+      let called = new Set(); // track calls using context + function identity
+
+      const callMethodWithProtoChain = async (obj, method, contextLabel) => {
+        let current = obj;
+        let seen = new Set();
+
+        while (current && typeof current === 'object' && seen.has(current) === false) {
+          seen.add(current);
+
+          let fn = current?.[method];
+          if (typeof fn === 'function') {
+            let key = fn + '@' + obj;
+            if (called.has(key) === false) {
+              called.add(key);
+              try {
+                results.push(await fn.apply(obj, params));
+              } catch (error) {
+                this?.log?.warn?.('Error in %s.%s(): %s', contextLabel, method, String(error?.stack || error));
+              }
+            }
+          }
 
-          // Update software version on the HomeKit accessory
-          informationService.updateCharacteristic(this.hap.Characteristic.SerialNumber, deviceData.serialNumber);
+          current = Object.getPrototypeOf(current);
         }
-      }
-
-      if (typeof deviceData?.online === 'boolean' && deviceData.online !== this.deviceData.online) {
-        // Output device online/offline status
-        if (deviceData.online === false) {
-          this?.log?.warn?.('Device "%s" is offline', deviceData.description);
+      };
+
+      if (typeof labelOrFn === 'string') {
+        await callMethodWithProtoChain(this, labelOrFn, this?.constructor?.name ?? 'this');
+      } else if (typeof labelOrFn === 'function') {
+        let key = labelOrFn + '@' + this;
+        if (called.has(key) === false) {
+          called.add(key);
+          try {
+            results.push(await labelOrFn(...params));
+          } catch (error) {
+            this?.log?.warn?.('Error in inline function handler: %s', String(error?.stack || error));
+          }
         }
-
-        if (deviceData.online === true) {
-          this?.log?.success?.('Device "%s" is online', deviceData.description);
+      } else if (Array.isArray(labelOrFn) === true) {
+        let [label, list] = labelOrFn;
+
+        for (let item of list || []) {
+          let fn = item?.handler;
+          let context = item?.context ?? this;
+          let key = fn + '@' + context;
+
+          if (typeof fn === 'function') {
+            if (called.has(key) === false) {
+              called.add(key);
+              try {
+                results.push(await fn.call(context, ...params));
+              } catch (error) {
+                this?.log?.warn?.('Error in registered %s(): %s', label, String(error?.stack || error));
+              }
+            }
+          } else if (typeof fn === 'string' && context) {
+            await callMethodWithProtoChain(context, fn, context?.constructor?.name ?? 'handler');
+          }
         }
       }
 
-      if (typeof this?.updateDevice === 'function') {
-        try {
-          this.updateDevice(deviceData); // Pass updated data on for accessory to process as it needs
-        } catch (error) {
-          this?.log?.error('updateDevice call for device "%s" failed. Error was', deviceData.description, error);
+      return results.length === 1 ? results[0] : results;
+    };
+
+    // Handle built-in types with special behavior
+    if (type === HomeKitDevice.ADD || type === HomeKitDevice.REMOVE || type === HomeKitDevice.SET) {
+      // Call the dynamic on<Type> method (ie. onAdd, onRemove, onSet) and after
+      // Any static handler registered via HomeKitDevice.message(uuid, type, handler)
+      await callLifecycleHook(methodName, message, ...args);
+      await callLifecycleHook(['handler for ' + type, handler], message, ...args);
+      handled = true;
+
+      // Special setup for ADD
+      if (type === HomeKitDevice.ADD) {
+        // After the accessory is initialized and onAdd has run, link any EveHome services that requested it
+        if (this.deviceData?.eveHistory === true && typeof this.historyService?.linkToEveHome === 'function') {
+          for (let service of this.accessory?.services || []) {
+            let options = service?.[HomeKitDevice?.EVEHOME?.EVE_OPTIONS];
+            if (options !== undefined) {
+              delete service[HomeKitDevice?.EVEHOME?.EVE_OPTIONS];
+              this.historyService.linkToEveHome(service, options);
+            }
+          }
         }
       }
 
-      // Finally, update our internally stored data with the new data
-      // eslint-disable-next-line no-undef
-      this.deviceData = structuredClone(deviceData);
-    }
-  }
+      // Special teardown for REMOVE
+      if (type === HomeKitDevice.REMOVE) {
+        this?.log?.warn?.('Device "%s" has been removed', this.deviceData.description);
+        this?.removeAllListeners?.();
+        HomeKitDevice.#deviceRegistry.delete(this.#uuid);
+        delete HomeKitDevice.#listeners[this.#uuid];
 
-  async set(values) {
-    if (typeof values !== 'object' || this.#eventEmitter === undefined) {
-      return;
-    }
+        if (this.accessory !== undefined && typeof this.#platform?.unregisterPlatformAccessories === 'function') {
+          this.#platform.unregisterPlatformAccessories(HomeKitDevice.PLUGIN_NAME, HomeKitDevice.PLATFORM_NAME, [this.accessory]);
+        }
 
-    // Send event with data to set
-    this.#eventEmitter.emit(HomeKitDevice.SET, this.uuid, values);
+        if (this.accessory !== undefined && this.#platform === undefined) {
+          this.accessory.unpublish();
+        }
 
-    // Update the internal data for the set values, as could take sometime once we emit the event
-    Object.entries(values).forEach(([key, value]) => {
-      if (this.deviceData[key] !== undefined) {
-        this.deviceData[key] = value;
+        this.deviceData = {};
+        this.accessory = undefined;
+        this.historyService = undefined;
+        this.hap = undefined;
+        this.log = undefined;
+        this.#uuid = undefined;
+        this.#platform = undefined;
       }
-    });
-  }
-
-  async get(values) {
-    if (typeof values !== 'object' || this.#eventEmitter === undefined) {
-      return;
-    }
-
-    // Send event with data to get
-    // Once get has completed, we'll get an event back with the requested data
-    this.#eventEmitter.emit(HomeKitDevice.GET, this.uuid, values);
 
-    // This should always return, but we probably should put in a timeout?
-    let results = await EventEmitter.once(this.#eventEmitter, HomeKitDevice.GET + '->' + this.uuid);
-    return results?.[0];
-  }
-
-  #message(type, message) {
-    switch (type) {
-      case HomeKitDevice.UPDATE: {
-        // Got some device data, so process any updates
-        this.update(message, false);
-        break;
+      // Update the internal data for the set values, as could take some time once we emit the event
+      if (type === HomeKitDevice.SET) {
+        if (typeof message === 'object' && message !== null) {
+          Object.entries(message).forEach(([key, value]) => {
+            if (this.deviceData?.[key] !== undefined) {
+              this.deviceData[key] = value;
+            }
+          });
+        }
       }
+    } else if (type === HomeKitDevice.UPDATE) {
+      if (typeof message === 'object' && message !== null) {
+        let { merged, changed } = this.#mergeDeviceData(message);
+        this.#updateAccessoryInformation(merged);
+
+        if (changed === true || (typeof args?.[0] === 'object' && args?.[0]?.force === true)) {
+          // Call the onUpdate method and after any static handler registered via HomeKitDevice.message(uuid, type, handler)
+          await callLifecycleHook('onUpdate', merged, ...args);
+          await callLifecycleHook(['handler for UPDATE', handler], merged, ...args);
+        }
 
-      case HomeKitDevice.REMOVE: {
-        // Got message for device removal
-        this.remove();
-        break;
+        // Finally, update our internally stored data with the new data
+        this.deviceData = structuredClone(merged);
       }
+      handled = true;
+    } else if (type === HomeKitDevice.HISTORY) {
+      let [target, entry, options = {}] = [message, args[0], args[1]];
+      let skipHistory = false;
+
+      if (
+        typeof this.historyService === 'object' &&
+        typeof this.historyService?.addHistory === 'function' &&
+        typeof entry === 'object' &&
+        typeof target === 'object' &&
+        typeof target.UUID === 'string'
+      ) {
+        if (isNaN(entry?.time) === true) {
+          entry.time = Math.floor(Date.now() / 1000);
+        }
 
-      default: {
-        // This is not a message we know about, so pass onto accessory for it to perform any processing
-        if (typeof this?.messageDevice === 'function') {
-          try {
-            this.messageDevice(type, message);
-          } catch (error) {
-            this?.log?.error('messageDevice call for device "%s" failed. Error was', this.deviceData.description, error);
+        if (options?.force !== true && typeof this.historyService?.lastHistory === 'function') {
+          let last = this.historyService.lastHistory(target);
+          if (typeof last === 'object') {
+            let changed = Object.keys(entry).some((key) => {
+              if (key === 'time') {
+                return false;
+              }
+              let v = entry[key];
+              let lv = last[key];
+              return typeof v === 'object' ? JSON.stringify(v) !== JSON.stringify(lv) : v !== lv;
+            });
+            if (changed === false) {
+              skipHistory = true;
+            }
           }
         }
-        break;
+
+        if (skipHistory === false) {
+          this.historyService.addHistory(target, entry, isNaN(options?.timegap) === false ? options.timegap : undefined);
+        }
       }
+
+      // Call the onHistory method and after any static handler registered via HomeKitDevice.message(uuid, type, handler)
+      await callLifecycleHook('onHistory', target, entry, options);
+      await callLifecycleHook(['handler for HISTORY', handler], target, entry, options);
+
+      handled = true;
+    }
+
+    // Dynamically handle any remaining on<Type> method (e.g., onGet etc that we haven’t handled yet)
+    // Any static handler registered via HomeKitDevice.message(uuid, type, handler)
+    if (handled === false && (typeof this?.[methodName] === 'function' || (Array.isArray(handler) === true && handler.length > 0))) {
+      // Use string method name so we get inheritance merging;
+      result.call = await callLifecycleHook(methodName, message, ...args);
+      result.handler = await callLifecycleHook(['handler for ' + type, handler], message, ...args);
+      handled = true;
+    }
+
+    // Call generic handler if present and we haven't handled the message yet
+    if (handled === false) {
+      result.call = await callLifecycleHook('onMessage', type, message, ...args);
+      handled = true;
+    }
+
+    // No handler at all — not even onMessage()
+    if (handled === false && (Array.isArray(handler) === false || handler.length === 0) && typeof this?.[methodName] !== 'function') {
+      this?.log?.warn?.('Unhandled message type "%s" for device "%s"', type, this.deviceData.description);
+    }
+
+    if (typeof result.call === 'object' && typeof result.handler === 'object') {
+      return Object.assign({}, result.call, result.handler);
     }
+
+    return result.call !== undefined ? result.call : result.handler;
   }
 
-  addHKService(hkServiceType, name = '', subType = undefined) {
+  addHKService(hkServiceType, name = '', subType = undefined, eveOptions = undefined) {
     let service = undefined;
 
     if (
@@ -451,12 +583,22 @@ class HomeKitDevice {
       if (service === undefined) {
         service = this.accessory.addService(hkServiceType, name, subType);
       }
+
+      // Setup for EveHome history if enabled. The actual linkage will be done in .add() after returning from .onAdd()
+      if (
+        service !== undefined &&
+        typeof eveOptions === 'object' &&
+        this.deviceData?.eveHistory === true &&
+        typeof this.historyService?.linkToEveHome === 'function'
+      ) {
+        service[HomeKitDevice?.EVEHOME?.EVE_OPTIONS] = eveOptions;
+      }
     }
 
     return service;
   }
 
-  addHKCharacteristic(hkService, hkCharacteristicType, { props, onSet, onGet } = {}) {
+  addHKCharacteristic(hkService, hkCharacteristicType, { props, onSet, onGet, initialValue } = {}) {
     let characteristic = undefined;
 
     if (
@@ -468,9 +610,8 @@ class HomeKitDevice {
     ) {
       if (hkService.testCharacteristic(hkCharacteristicType) === false) {
         if (
-          Array.isArray(hkService?.optionalCharacteristics) &&
-          hkService.optionalCharacteristics.includes(hkCharacteristicType) &&
-          typeof hkService?.addOptionalCharacteristic === 'function'
+          Array.isArray(hkService?.optionalCharacteristics) === true &&
+          hkService.optionalCharacteristics.includes(hkCharacteristicType) === true
         ) {
           hkService.addOptionalCharacteristic(hkCharacteristicType);
         } else {
@@ -490,7 +631,13 @@ class HomeKitDevice {
       if (typeof props === 'object' && typeof characteristic.setProps === 'function') {
         characteristic.setProps(props);
       }
+
+      // Set initial value if provided
+      if (typeof initialValue !== 'undefined' && typeof hkService?.updateCharacteristic === 'function') {
+        hkService.updateCharacteristic(hkCharacteristicType, initialValue);
+      }
     }
+
     return characteristic;
   }
 
@@ -499,36 +646,29 @@ class HomeKitDevice {
       return;
     }
 
-    let level = 'info';
-    let availableLevel = Object.keys(LOGLEVELS).find((lvl) => typeof this.log?.[lvl] === 'function') || 'info';
+    let levelKey = 'INFO';
     let lastArg = args.at(-1);
 
-    if (typeof lastArg === 'string' && Object.hasOwn(LOGLEVELS, lastArg)) {
-      level = lastArg;
+    if (typeof lastArg === 'string' && Object.hasOwn(LOG_LEVELS, lastArg.toUpperCase())) {
+      levelKey = lastArg.toUpperCase();
       args = args.slice(0, -1);
-    } else {
-      level = availableLevel;
     }
 
     this.#postSetupDetails.push({
-      level,
+      level: LOG_LEVELS[levelKey], // 'info', 'debug', etc.
       message,
       args: args.length > 0 ? args : undefined,
     });
   }
 
   static generateUUID(PLUGIN_NAME, api, serialNumber) {
-    let hap = undefined;
+    let hap;
     let uuid = crypto.randomUUID();
 
-    // Workout if we're running under Homebridge or HAP-NodeJS library
-    if (isNaN(api?.version) === false && typeof api?.hap === 'object' && api?.HAPLibraryVersion === undefined) {
-      // We have the Homebridge version number and hap API object
+    // Determine runtime environment (Homebridge vs HAP-NodeJS)
+    if (typeof api?.hap === 'object' && isNaN(api?.version) === false && typeof api?.HAPLibraryVersion === 'undefined') {
       hap = api.hap;
-    }
-
-    if (typeof api?.HAPLibraryVersion === 'function' && api?.version === undefined && api?.hap === undefined) {
-      // As we're missing the Homebridge entry points but have the HAP library version
+    } else if (typeof api?.HAPLibraryVersion === 'function' && typeof api?.version === 'undefined' && typeof api?.hap === 'undefined') {
       hap = api;
     }
 
@@ -544,8 +684,110 @@ class HomeKitDevice {
 
     return uuid;
   }
-}
 
-// Define exports
-export { HK_PIN_3_2_3, HK_PIN_4_4, MAC_ADDR, HomeKitDevice };
-export default HomeKitDevice;
+  static makeValidHKName(name) {
+    // Strip invalid characters to meet HomeKit naming requirements
+    // Ensure only letters or numbers are at the beginning AND/OR end of string
+    // Matches against uni-code characters
+    return typeof name === 'string'
+      ? name
+          .replace(/[^\p{L}\p{N}\p{Z}\u2019.,-]/gu, '')
+          .replace(/^[^\p{L}\p{N}]*/gu, '')
+          .replace(/[^\p{L}\p{N}]+$/gu, '')
+      : name;
+  }
+
+  get uuid() {
+    return this.#uuid;
+  }
+
+  #mergeDeviceData(deviceDataUpdates = {}) {
+    let merged = { ...deviceDataUpdates };
+
+    // Updated data may only contain selected fields, so we'll handle that here by taking our internally stored data
+    // and merge with the updates to ensure we have a complete data object
+    Object.entries(this.deviceData).forEach(([key, value]) => {
+      if (typeof merged[key] === 'undefined') {
+        // Updated data doesn't have this key, so add it to our internally stored data
+        merged[key] = value;
+      }
+    });
+
+    // Check updated device data with our internally stored data. Flag if changes between the two
+    let changed = false;
+    Object.keys(merged).forEach((key) => {
+      if (JSON.stringify(merged[key]) !== JSON.stringify(this.deviceData[key])) {
+        changed = true;
+      }
+    });
+
+    return { merged, changed };
+  }
+
+  #updateAccessoryInformation(deviceData) {
+    // Always update accessory information if we have changed data
+    if (this.accessory === undefined) {
+      return;
+    }
+
+    let informationService = this.accessory.getService(this.hap.Service.AccessoryInformation);
+    if (informationService === undefined) {
+      this?.log?.error?.('AccessoryInformation service not found on accessory for "%s"', this.deviceData.description);
+      return;
+    }
+
+    // Update details associated with the accessory
+    // ie: Name, Manufacturer, Model, Serial # and firmware version
+    if (typeof deviceData?.description === 'string' && deviceData.description !== this.deviceData.description) {
+      // Update devices description on the HomeKit accessory
+      informationService.updateCharacteristic(this.hap.Characteristic.Name, deviceData.description);
+    }
+
+    if (
+      typeof deviceData?.manufacturer === 'string' &&
+      deviceData.manufacturer !== '' &&
+      deviceData.manufacturer !== this.deviceData.manufacturer
+    ) {
+      // Update manufacturer number on the HomeKit accessory
+      informationService.updateCharacteristic(this.hap.Characteristic.Manufacturer, deviceData.manufacturer);
+    }
+
+    if (typeof deviceData?.model === 'string' && deviceData.model !== '' && deviceData.model !== this.deviceData.model) {
+      // Update model on the HomeKit accessory
+      informationService.updateCharacteristic(this.hap.Characteristic.Model, deviceData.model);
+    }
+
+    if (
+      typeof deviceData?.softwareVersion === 'string' &&
+      deviceData.softwareVersion !== '' &&
+      deviceData.softwareVersion !== this.deviceData.softwareVersion
+    ) {
+      // Update software version on the HomeKit accessory
+      informationService.updateCharacteristic(this.hap.Characteristic.FirmwareRevision, deviceData.softwareVersion);
+    }
+
+    // Check for devices serial number changing. Really shouldn't occur, but handle case anyway
+    if (
+      typeof deviceData?.serialNumber === 'string' &&
+      deviceData.serialNumber !== '' &&
+      deviceData.serialNumber.toUpperCase() !== this.deviceData.serialNumber?.toUpperCase()
+    ) {
+      this?.log?.warn?.('Serial number on "%s" has changed', deviceData.description);
+      this?.log?.warn?.('This may cause the device to become unresponsive in HomeKit');
+
+      // Update serial number on the HomeKit accessory
+      informationService.updateCharacteristic(this.hap.Characteristic.SerialNumber, deviceData.serialNumber);
+    }
+
+    if (typeof deviceData?.online === 'boolean' && deviceData.online !== this.deviceData.online) {
+      // Output device online/offline status
+      if (deviceData.online === false) {
+        this?.log?.warn?.('Device "%s" is offline', deviceData.description);
+      }
+
+      if (deviceData.online === true) {
+        this?.log?.success?.('Device "%s" is online', deviceData.description);
+      }
+    }
+  }
+}