zigbee-clusters 2.8.1 → 2.9.0

package/index.js

@@ -44,6 +44,8 @@ const {
   ZCLStruct,
 } = zclTypes;
 
+const { ZIGBEE_PROFILE_ID, ZIGBEE_DEVICE_ID, IAS_ZONE_TYPE } = require('./lib/constants');
+
 module.exports = {
   Cluster,
   BoundCluster,
@@ -55,4 +57,7 @@ module.exports = {
   ZCLStruct,
   ...Clusters,
   debug,
+  ZIGBEE_PROFILE_ID,
+  ZIGBEE_DEVICE_ID,
+  IAS_ZONE_TYPE,
 };

package/lib/constants.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * Zigbee Profile IDs from the ZCL specification.
+ */
+const ZIGBEE_PROFILE_ID = {
+  INDUSTRIAL_PLANT_MONITORING: 0x0101,
+  HOME_AUTOMATION: 0x0104,
+  COMMERCIAL_BUILDING_AUTOMATION: 0x0105,
+  TELECOM_APPLICATIONS: 0x0107,
+  PERSONAL_HOME_AND_HOSPITAL_CARE: 0x0108,
+  ADVANCED_METERING_INITIATIVE: 0x0109,
+};
+
+/**
+ * Zigbee Device IDs from the ZCL specification.
+ */
+const ZIGBEE_DEVICE_ID = {
+  GENERIC: {
+    ON_OFF_SWITCH: 0x0000,
+    LEVEL_CONTROL_SWITCH: 0x0001,
+    ON_OFF_OUTPUT: 0x0002,
+    LEVEL_CONTROLLABLE_OUTPUT: 0x0003,
+    SCENE_SELECTOR: 0x0004,
+    CONFIGURATION_TOOL: 0x0005,
+    REMOTE_CONTROL: 0x0006,
+    COMBINED_INTERFACE: 0x0007,
+    RANGE_EXTENDER: 0x0008,
+    MAINS_POWER_OUTLET: 0x0009,
+    DOOR_LOCK: 0x000a,
+    DOOR_LOCK_CONTROLLER: 0x000b,
+    SIMPLE_SENSOR: 0x000c,
+    CONSUMPTION_AWARENESS_DEVICE: 0x000d,
+    HOME_GATEWAY: 0x0050,
+    SMART_PLUG: 0x0051,
+    WHITE_GOODS: 0x0052,
+    METER_INTERFACE: 0x0053,
+  },
+  LIGHTING: {
+    ON_OFF_LIGHT: 0x0100,
+    DIMMABLE_LIGHT: 0x0101,
+    COLOR_DIMMABLE_LIGHT: 0x0102,
+    ON_OFF_LIGHT_SWITCH: 0x0103,
+    DIMMER_SWITCH: 0x0104,
+    COLOR_DIMMER_SWITCH: 0x0105,
+    LIGHT_SENSOR: 0x0106,
+    OCCUPANCY_SENSOR: 0x0107,
+  },
+  CLOSURES: {
+    SHADE: 0x0200,
+    SHADE_CONTROLLER: 0x0201,
+    WINDOW_COVERING_DEVICE: 0x0202,
+    WINDOW_COVERING_CONTROLLER: 0x0203,
+  },
+  HVAC: {
+    HEATING_COOLING_UNIT: 0x0300,
+    THERMOSTAT: 0x0301,
+    TEMPERATURE_SENSOR: 0x0302,
+    PUMP: 0x0303,
+    PUMP_CONTROLLER: 0x0304,
+    PRESSURE_SENSOR: 0x0305,
+    FLOW_SENSOR: 0x0306,
+  },
+  INTRUDER_ALARM_SYSTEMS: {
+    IAS_CONTROL_INDICATING_EQUIPMENT: 0x0400,
+    IAS_ANCILLARY_CONTROL_EQUIPMENT: 0x0401,
+    IAS_ZONE: 0x0402,
+    IAS_WARNING_DEVICE: 0x0403,
+  },
+};
+
+/**
+ * IAS Zone Type values from the ZCL specification (IAS Zone cluster, zoneType attribute).
+ */
+const IAS_ZONE_TYPE = {
+  STANDARD_CIE: 0x0000,
+  MOTION_SENSOR: 0x000d,
+  CONTACT_SWITCH: 0x0015,
+  FIRE_SENSOR: 0x0028,
+  WATER_SENSOR: 0x002a,
+  CARBON_MONOXIDE_SENSOR: 0x002b,
+  PERSONAL_EMERGENCY_DEVICE: 0x002c,
+  VIBRATION_MOVEMENT_SENSOR: 0x002d,
+  REMOTE_CONTROL: 0x010f,
+  KEY_FOB: 0x0115,
+  KEYPAD: 0x021d,
+  STANDARD_WARNING_DEVICE: 0x0225,
+  GLASS_BREAK_SENSOR: 0x0226,
+  SECURITY_REPEATER: 0x0229,
+  INVALID_ZONE_TYPE: 0xffff,
+};
+
+module.exports = {
+  ZIGBEE_PROFILE_ID,
+  ZIGBEE_DEVICE_ID,
+  IAS_ZONE_TYPE,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zigbee-clusters",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "description": "Zigbee Cluster Library for Node.js",
   "main": "index.js",
   "types": "index.d.ts",

package/scripts/generate-types.js

@@ -179,6 +179,8 @@ function generateClusterInterface(cluster) {
     lines.push(`  readAttributes<K extends ${attrNames}>(attributeNames: K[], opts?: { timeout?: number }): Promise<Pick<${interfaceName}Attributes, K>>;`);
     lines.push(`  readAttributes(attributeNames: Array<keyof ${interfaceName}Attributes | number>, opts?: { timeout?: number }): Promise<Partial<${interfaceName}Attributes> & Record<number, unknown>>;`);
     lines.push(`  writeAttributes(attributes: Partial<${interfaceName}Attributes>, opts?: { timeout?: number }): Promise<unknown>;`);
+    lines.push(`  on<K extends keyof ${interfaceName}Attributes & string>(eventName: \`attr.\${K}\`, listener: (value: ${interfaceName}Attributes[K]) => void): this;`);
+    lines.push(`  once<K extends keyof ${interfaceName}Attributes & string>(eventName: \`attr.\${K}\`, listener: (value: ${interfaceName}Attributes[K]) => void): this;`);
   }
 
   // Add command methods
@@ -208,9 +210,29 @@ function generateClusterInterface(cluster) {
 /**
  * Generate the full index.d.ts file
  * @param {object[]} clusters - Array of parsed cluster definitions
+ * @param {Array<{
+ *   constantName: string;
+ *   clusterId: number;
+ *   clusterName: string;
+ * }>} clusterDefinitions - Array of CLUSTER definitions used to generate typed CLUSTER exports
  * @returns {string} Complete TypeScript definitions file
  */
-function generateTypesFile(clusters) {
+function generateConstantObject(obj, indent = 2) {
+  const lines = [];
+  const pad = ' '.repeat(indent);
+  for (const [key, value] of Object.entries(obj)) {
+    if (typeof value === 'object' && value !== null) {
+      lines.push(`${pad}${key}: {`);
+      lines.push(generateConstantObject(value, indent + 2));
+      lines.push(`${pad}};`);
+    } else {
+      lines.push(`${pad}${key}: ${typeof value === 'number' ? value : JSON.stringify(value)};`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function generateTypesFile(clusters, clusterDefinitions, constants) {
   const lines = [];
 
   // Header
@@ -309,6 +331,42 @@ type ZCLNodeConstructorInput = {
   lines.push('}');
   lines.push('');
 
+  // Generate cluster type lookup maps for inference helpers
+  lines.push('/** Cluster type lookup by cluster NAME */');
+  lines.push('export interface ClusterTypeByName {');
+  for (const cluster of clusters) {
+    const interfaceName = toInterfaceName(cluster);
+    lines.push(`  ${cluster.clusterName}: ${interfaceName};`);
+  }
+  lines.push('}');
+  lines.push('');
+
+  // Generate cluster attribute lookup maps for inference helpers
+  lines.push('/** Cluster attributes lookup by cluster NAME */');
+  lines.push('export interface ClusterAttributesByName {');
+  for (const cluster of clusters) {
+    const interfaceName = toInterfaceName(cluster);
+    const attributesInterfaceName = `${interfaceName}Attributes`;
+    const attributesType = cluster.attributes.length > 0 ? attributesInterfaceName : 'Record<string, unknown>';
+    lines.push(`  ${cluster.clusterName}: ${attributesType};`);
+  }
+  lines.push('}');
+  lines.push('');
+
+  lines.push('/** Infer a typed cluster interface from a CLUSTER definition object. */');
+  lines.push('export type ClusterTypeFromDefinition<TDef extends { NAME: string; ID: number }> =');
+  lines.push("  TDef['NAME'] extends keyof ClusterTypeByName");
+  lines.push("    ? ClusterTypeByName[TDef['NAME']]");
+  lines.push('    : ZCLNodeCluster;');
+  lines.push('');
+
+  lines.push('/** Infer typed cluster attribute map from a CLUSTER definition object. */');
+  lines.push('export type ClusterAttributesFromDefinition<TDef extends { NAME: string; ID: number }> =');
+  lines.push("  TDef['NAME'] extends keyof ClusterAttributesByName");
+  lines.push("    ? ClusterAttributesByName[TDef['NAME']]");
+  lines.push('    : Record<string, unknown>;');
+  lines.push('');
+
   // Generate endpoint type
   lines.push(`export type ZCLNodeEndpoint = {
   clusters: ClusterRegistry & {
@@ -327,30 +385,61 @@ export interface ZCLNode {
 }
 `);
 
-  // Module declaration for CommonJS compatibility
-  lines.push(`declare module "zigbee-clusters" {
-  export const ZCLNode: {
-    new (node: ZCLNodeConstructorInput): ZCLNode;
-  };
-  export const CLUSTER: {
-    [key: string]: { ID: number; NAME: string; ATTRIBUTES: unknown; COMMANDS: unknown };
-  };
-  export { ZCLNodeCluster };`);
+  // Runtime value exports
+  lines.push(`export const ZCLNode: {
+  new (node: ZCLNodeConstructorInput): ZCLNode;
+};
 
-  // Export all cluster classes
-  for (const cluster of clusters) {
-    const interfaceName = toInterfaceName(cluster);
-    const exportName = cluster.exportName || interfaceName;
-    lines.push(`  export const ${exportName}: {`);
-    lines.push(`    new (...args: any[]): ${interfaceName};`);
+export const CLUSTER: {
+`);
+  for (const def of clusterDefinitions) {
+    lines.push(`  ${def.constantName}: {`);
     lines.push('    ID: number;');
-    lines.push('    NAME: string;');
+    lines.push(`    NAME: '${def.clusterName}';`);
     lines.push('    ATTRIBUTES: unknown;');
     lines.push('    COMMANDS: unknown;');
     lines.push('  };');
   }
+  lines.push('};');
 
-  lines.push('}');
+  // Export all cluster classes
+  for (const cluster of clusters) {
+    const interfaceName = toInterfaceName(cluster);
+    const exportName = cluster.exportName || interfaceName;
+    lines.push(`export const ${exportName}: {`);
+    lines.push(`  new (...args: any[]): ${interfaceName};`);
+    lines.push(`  ID: ${cluster.clusterId};`);
+    lines.push(`  NAME: '${cluster.clusterName}';`);
+    lines.push('  ATTRIBUTES: unknown;');
+    lines.push('  COMMANDS: unknown;');
+    lines.push('};');
+  }
+
+  // Export constants
+  if (constants) {
+    for (const [name, value] of Object.entries(constants)) {
+      lines.push('');
+      lines.push(`export const ${name}: {`);
+      lines.push(generateConstantObject(value));
+      lines.push('};');
+    }
+  }
+
+  lines.push('');
+  lines.push('declare const _default: {');
+  lines.push('  ZCLNode: typeof ZCLNode;');
+  lines.push('  CLUSTER: typeof CLUSTER;');
+  for (const cluster of clusters) {
+    const exportName = cluster.exportName || toInterfaceName(cluster);
+    lines.push(`  ${exportName}: typeof ${exportName};`);
+  }
+  if (constants) {
+    for (const name of Object.keys(constants)) {
+      lines.push(`  ${name}: typeof ${name};`);
+    }
+  }
+  lines.push('};');
+  lines.push('export default _default;');
 
   return lines.join('\n');
 }
@@ -381,8 +470,20 @@ function main() {
   // Sort clusters alphabetically
   clusters.sort((a, b) => a.clusterName.localeCompare(b.clusterName));
 
+  const clusterDefinitions = Object.entries(clustersModule.CLUSTER)
+    .map(([constantName, value]) => ({
+      constantName,
+      clusterId: value.ID,
+      clusterName: value.NAME,
+    }))
+    .sort((a, b) => a.constantName.localeCompare(b.constantName));
+
+  // Load constants
+  const { ZIGBEE_PROFILE_ID, ZIGBEE_DEVICE_ID, IAS_ZONE_TYPE } = require('../lib/constants');
+  const constants = { ZIGBEE_PROFILE_ID, ZIGBEE_DEVICE_ID, IAS_ZONE_TYPE };
+
   console.log(`\nGenerating ${OUTPUT_FILE}...`);
-  const output = generateTypesFile(clusters);
+  const output = generateTypesFile(clusters, clusterDefinitions, constants);
   fs.writeFileSync(OUTPUT_FILE, output);
 
   console.log(`Done! Generated types for ${clusters.length} clusters.`);