zigbee-clusters 2.7.2 → 2.8.1

package/lib/Cluster.js

@@ -403,29 +403,39 @@ class Cluster extends EventEmitter {
   /**
    * Command which reads a given set of attributes from the remote cluster.
    * Note: do not mix regular and manufacturer specific attributes.
-   * @param {string[]} attributeNames
+   * @param {Array<string | number>} attributes - Attribute names or numeric IDs
    * @param {object} [opts=] - Optional parameters
-   * @param {number} [opts.timeout] - Optional timeout in milliseconds for waiting for response
-   * @returns {Promise<Object.<string, unknown>>} - Object with values (e.g. `{ onOff: true }`)
+   * @param {number} [opts.timeout] - Optional timeout in ms
+   * @returns {Promise<Object.<string, unknown>>} - Keyed by attribute name or
+   * numeric ID
    */
-  async readAttributes(attributeNames, opts) {
-    if (attributeNames instanceof Array === false) {
-      throw new Error('Expected attribute names array, as of zigbee-clusters@2.0.0 call readAttributes([\'myAttr\'])');
+  async readAttributes(attributes, opts) {
+    if (attributes instanceof Array === false) {
+      throw new Error('Expected attributes array, as of zigbee-clusters@2.0.0 call readAttributes([\'myAttr\'])');
     }
 
-    if (!attributeNames.length) {
-      attributeNames = Object.keys(this.constructor.attributes);
-    }
-    const mismatch = attributeNames.find(n => !this.constructor.attributes[n]);
-    if (mismatch) {
-      throw new TypeError(`${mismatch} is not a valid attribute of ${this.name}`);
+    if (!attributes.length) {
+      attributes = Object.keys(this.constructor.attributes);
     }
 
     const idToName = {};
-    const attrIds = new Set(attributeNames.map(a => {
-      idToName[this.constructor.attributes[a].id] = a;
-      return this.constructor.attributes[a].id;
-    }));
+    const numericIds = new Set();
+    const attrIds = new Set();
+    for (const attr of attributes) {
+      if (typeof attr === 'number') {
+        if (!Number.isInteger(attr) || attr < 0 || attr > 0xFFFF) {
+          throw new TypeError(`${attr} is not a valid numeric attribute ID for ${this.name}, must be an integer between 0 and 0xFFFF`);
+        }
+        numericIds.add(attr);
+        if (idToName[attr] === undefined) idToName[attr] = attr;
+        attrIds.add(attr);
+      } else if (this.constructor.attributes[attr]) {
+        idToName[this.constructor.attributes[attr].id] = attr;
+        attrIds.add(this.constructor.attributes[attr].id);
+      } else {
+        throw new TypeError(`${attr} is not a valid attribute of ${this.name}`);
+      }
+    }
 
     const resultObj = {};
     while (attrIds.size) {
@@ -433,19 +443,23 @@ class Cluster extends EventEmitter {
       const manufacturerId = this._checkForManufacturerSpecificAttributes(Array.from(attrIds));
       debug(this.logId, 'read attributes', [...attrIds], manufacturerId ? `manufacturer specific id ${manufacturerId}` : '');
 
-      const { attributes } = await super.readAttributes({
+      const response = await super.readAttributes({
         attributes: [...attrIds],
         manufacturerId,
       }, opts);
 
-      debug(this.logId, 'read attributes result', { attributes });
-      const result = this.constructor.attributeArrayStatusDataType.fromBuffer(attributes, 0);
+      debug(this.logId, 'read attributes result', response);
+      const { attributeArrayStatusDataType } = this.constructor;
+      const result = attributeArrayStatusDataType.fromBuffer(response.attributes, 0);
       if (!result.length) break;
 
       result.forEach(a => {
         attrIds.delete(a.id);
         if (a.status === 'SUCCESS') {
           resultObj[idToName[a.id]] = a.value;
+          if (numericIds.has(a.id) && idToName[a.id] !== a.id) {
+            resultObj[a.id] = a.value;
+          }
         }
       });
     }
@@ -690,8 +704,13 @@ class Cluster extends EventEmitter {
     for (const attr of attributes) {
       const attribute = this.constructor.attributesById[attr.id];
       const discoveredAttribute = {
-        acl: attr.acl,
+        acl: {
+          readable: !!attr.acl.readable,
+          writable: !!attr.acl.writable,
+          reportable: !!attr.acl.reportable,
+        },
         id: attr.id,
+        dataTypeId: attr.dataTypeId,
       };
 
       // If the attribute is implemented in zigbee-clusters add name

package/package.json

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

package/scripts/generate-types.js

@@ -89,7 +89,7 @@ function zclTypeToTS(dataType) {
  * @param {Function} ClusterClass - Cluster class with static ATTRIBUTES/COMMANDS
  * @returns {object} Cluster definition
  */
-function parseCluster(ClusterClass) {
+function parseCluster(ClusterClass, exportName) {
   const clusterName = ClusterClass.NAME;
   const clusterId = ClusterClass.ID;
   const attributes = [];
@@ -132,7 +132,11 @@ function parseCluster(ClusterClass) {
   }
 
   return {
-    clusterName, clusterId, attributes, commands,
+    exportName,
+    clusterName,
+    clusterId,
+    attributes,
+    commands,
   };
 }
 
@@ -141,8 +145,9 @@ function parseCluster(ClusterClass) {
  * @param {string} clusterName
  * @returns {string}
  */
-function toInterfaceName(clusterName) {
-  const name = clusterName.charAt(0).toUpperCase() + clusterName.slice(1);
+function toInterfaceName(cluster) {
+  if (cluster.exportName) return cluster.exportName;
+  const name = cluster.clusterName.charAt(0).toUpperCase() + cluster.clusterName.slice(1);
   return `${name}Cluster`;
 }
 
@@ -152,7 +157,7 @@ function toInterfaceName(clusterName) {
  * @returns {string} TypeScript interface code
  */
 function generateClusterInterface(cluster) {
-  const interfaceName = toInterfaceName(cluster.clusterName);
+  const interfaceName = toInterfaceName(cluster);
   const lines = [];
 
   // Generate attributes interface
@@ -172,7 +177,8 @@ function generateClusterInterface(cluster) {
   if (cluster.attributes.length > 0) {
     const attrNames = cluster.attributes.map(a => `'${a.name}'`).join(' | ');
     lines.push(`  readAttributes<K extends ${attrNames}>(attributeNames: K[], opts?: { timeout?: number }): Promise<Pick<${interfaceName}Attributes, K>>;`);
-    lines.push(`  writeAttributes(attributes: Partial<${interfaceName}Attributes>): Promise<void>;`);
+    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>;`);
   }
 
   // Add command methods
@@ -188,9 +194,9 @@ function generateClusterInterface(cluster) {
       const allArgsOptional = cmd.args.every(a => a.tsType === 'Buffer');
       const argsType = `{ ${cmd.args.map(a => `${a.name}${a.tsType === 'Buffer' ? '?' : ''}: ${a.tsType}`).join('; ')} }`;
       // If all args are optional, make the entire args object optional
-      lines.push(`  ${cmd.name}(args${allArgsOptional ? '?' : ''}: ${argsType}): Promise<${returnType}>;`);
+      lines.push(`  ${cmd.name}(args${allArgsOptional ? '?' : ''}: ${argsType}, opts?: ClusterCommandOptions): Promise<${returnType}>;`);
     } else {
-      lines.push(`  ${cmd.name}(): Promise<${returnType}>;`);
+      lines.push(`  ${cmd.name}(opts?: ClusterCommandOptions): Promise<${returnType}>;`);
     }
   }
 
@@ -225,30 +231,47 @@ type ConstructorOptions = {
   endpointDescriptors: EndpointDescriptor[];
   sendFrame: (endpointId: number, clusterId: number, frame: Buffer) => Promise<void>;
 };
+
+type ClusterCommandOptions = {
+  timeout?: number;
+  waitForResponse?: boolean;
+  disableDefaultResponse?: boolean;
+};
+
+type ZCLNodeConstructorInput = {
+  endpointDescriptors?: EndpointDescriptor[];
+  sendFrame: (endpointId: number, clusterId: number, frame: Buffer) => Promise<void>;
+  handleFrame?: (
+    endpointId: number,
+    clusterId: number,
+    frame: Buffer,
+    meta?: unknown
+  ) => Promise<void>;
+};
 `);
 
   // Base ZCLNodeCluster interface
   lines.push(`export interface ZCLNodeCluster extends EventEmitter {
-  discoverCommandsGenerated(opts?: {
+  discoverCommandsGenerated(params?: {
     startValue?: number;
     maxResults?: number;
-  }): Promise<number[]>;
+  }, opts?: { timeout?: number }): Promise<(string | number)[]>;
 
-  discoverCommandsReceived(opts?: {
+  discoverCommandsReceived(params?: {
     startValue?: number;
     maxResults?: number;
-  }): Promise<number[]>;
+  }, opts?: { timeout?: number }): Promise<(string | number)[]>;
 
   readAttributes(
-    attributeNames: string[],
+    attributes: Array<string | number>,
     opts?: { timeout?: number }
   ): Promise<{ [x: string]: unknown }>;
 
-  writeAttributes(attributes?: object): Promise<void>;
+  writeAttributes(attributes?: object, opts?: { timeout?: number }): Promise<unknown>;
 
-  configureReporting(attributes?: object): Promise<void>;
+  configureReporting(attributes?: object, opts?: { timeout?: number }): Promise<void>;
 
-  readReportingConfiguration(attributes?: (string | number)[]): Promise<{
+  readReportingConfiguration(attributes?: (string | number)[], opts?: { timeout?: number }): Promise<{
     status: string;
     direction: 'reported' | 'received';
     attributeId: number;
@@ -259,11 +282,12 @@ type ConstructorOptions = {
     timeoutPeriod?: number;
   }[]>;
 
-  discoverAttributes(): Promise<(string | number)[]>;
+  discoverAttributes(opts?: { timeout?: number }): Promise<(string | number)[]>;
 
-  discoverAttributesExtended(): Promise<{
+  discoverAttributesExtended(opts?: { timeout?: number }): Promise<{
     name?: string;
     id: number;
+    dataTypeId: number;
     acl: { readable: boolean; writable: boolean; reportable: boolean };
   }[]>;
 }
@@ -279,7 +303,7 @@ type ConstructorOptions = {
   lines.push('/** Type-safe cluster registry */');
   lines.push('export interface ClusterRegistry {');
   for (const cluster of clusters) {
-    const interfaceName = toInterfaceName(cluster.clusterName);
+    const interfaceName = toInterfaceName(cluster);
     lines.push(`  ${cluster.clusterName}?: ${interfaceName};`);
   }
   lines.push('}');
@@ -306,7 +330,7 @@ export interface ZCLNode {
   // Module declaration for CommonJS compatibility
   lines.push(`declare module "zigbee-clusters" {
   export const ZCLNode: {
-    new (options: ConstructorOptions): ZCLNode;
+    new (node: ZCLNodeConstructorInput): ZCLNode;
   };
   export const CLUSTER: {
     [key: string]: { ID: number; NAME: string; ATTRIBUTES: unknown; COMMANDS: unknown };
@@ -315,8 +339,15 @@ export interface ZCLNode {
 
   // Export all cluster classes
   for (const cluster of clusters) {
-    const interfaceName = toInterfaceName(cluster.clusterName);
-    lines.push(`  export const ${interfaceName}: ${interfaceName};`);
+    const interfaceName = toInterfaceName(cluster);
+    const exportName = cluster.exportName || interfaceName;
+    lines.push(`  export const ${exportName}: {`);
+    lines.push(`    new (...args: any[]): ${interfaceName};`);
+    lines.push('    ID: number;');
+    lines.push('    NAME: string;');
+    lines.push('    ATTRIBUTES: unknown;');
+    lines.push('    COMMANDS: unknown;');
+    lines.push('  };');
   }
 
   lines.push('}');
@@ -338,7 +369,7 @@ function main() {
   for (const [name, value] of Object.entries(clustersModule)) {
     if (name.endsWith('Cluster') && typeof value === 'function' && value.NAME) {
       try {
-        const cluster = parseCluster(value);
+        const cluster = parseCluster(value, name);
         clusters.push(cluster);
         console.log(`  ✓ ${cluster.clusterName} (${cluster.attributes.length} attrs, ${cluster.commands.length} cmds)`);
       } catch (err) {