Merge pull request #211 from athombv/feature/export-endpoint

feat: export Endpoint, so a device serving bound clusters need not fake a peer

Author: RobinBol

index.d.ts

@@ -2778,12 +2778,21 @@ declare module "zigbee-clusters" {
     getLogId(endpointId: number, clusterId: number): string;
   }
 
-  class ZCLNodeEndpoint extends EventEmitter {
-    constructor(node: ZCLNode, descriptor: {
+  /**
+   * Minimum shape an Endpoint needs from its owner. Endpoint only ever calls `sendFrame`, so a
+   * plain object is enough - a device serving bound clusters does not need a full ZCLNode, which
+   * models one remote peer and bakes that peer's address into its own `sendFrame`.
+   */
+  type EndpointInput = {
+    sendFrame(endpointId: number, clusterId: number, frame: Buffer): Promise<unknown>;
+  };
+
+  class Endpoint extends EventEmitter {
+    constructor(node: EndpointInput, descriptor: {
       endpointId: number;
       inputClusters: number[];
-      outputClusters: number[];
-    }[]);
+      outputClusters?: number[];
+    });
     // Typed lookup: known cluster names (per the generated `ClustersByName`)
     // resolve to their specific class (e.g. `clusters.onOff` is `OnOffCluster`),
     // while unknown keys fall back to the generic Cluster via the index half.
@@ -2795,8 +2804,21 @@ declare module "zigbee-clusters" {
     unbind(clusterName: string): void;
 
     makeDefaultResponseFrame(receivedFrame: unknown, success: boolean, status: types.ZCLEnum8Status): typeof zclFrames.ZCLStandardHeader | typeof zclFrames.ZCLMfgSpecificHeader;
+
+    /**
+     * Dispatch an incoming ZCL frame to the bound cluster and write the response. Handles the
+     * command-response rules: no reply to a Default Response or a group-addressed frame
+     * (ZCL 2.5.12.2), a Default Response carrying a thrown ZCLError's status, and
+     * `disableDefaultResponse`.
+     *
+     * Pass `meta.groupId` for a group-addressed frame, or the suppression cannot be applied.
+     */
+    handleFrame(clusterId: number, frame: Buffer, meta?: { groupId?: number }): Promise<void>;
   }
 
+  /** @deprecated Use {@link Endpoint}; kept so existing references keep compiling. */
+  type ZCLNodeEndpoint = Endpoint;
+
   type ZCLDataType<Value> = import('@athombv/data-types').DataType<Value>;
   const ZCLDataTypes: ZCLDataTypes;
   const ZCLStruct: typeof import('@athombv/data-types').Struct;

index.js

@@ -3,6 +3,7 @@
 const _debug = require('debug');
 
 const ZCLNode = require('./lib/Node');
+const Endpoint = require('./lib/Endpoint');
 const Cluster = require('./lib/Cluster');
 const BoundCluster = require('./lib/BoundCluster');
 const zclTypes = require('./lib/zclTypes');
@@ -105,6 +106,7 @@ module.exports = {
 
   // ZCL
   ZCLNode,
+  Endpoint,
   zclTypes,
   zclFrames,
   ZCLDataTypes,

scripts/template.d.ts.txt

@@ -53,12 +53,21 @@ declare module 'zigbee-clusters' {
     getLogId(endpointId: number, clusterId: number): string;
   }
 
-  class ZCLNodeEndpoint extends EventEmitter {
-    constructor(node: ZCLNode, descriptor: {
+  /**
+   * Minimum shape an Endpoint needs from its owner. Endpoint only ever calls `sendFrame`, so a
+   * plain object is enough - a device serving bound clusters does not need a full ZCLNode, which
+   * models one remote peer and bakes that peer's address into its own `sendFrame`.
+   */
+  type EndpointInput = {
+    sendFrame(endpointId: number, clusterId: number, frame: Buffer): Promise<unknown>;
+  };
+
+  class Endpoint extends EventEmitter {
+    constructor(node: EndpointInput, descriptor: {
       endpointId: number;
       inputClusters: number[];
-      outputClusters: number[];
-    }[]);
+      outputClusters?: number[];
+    });
     // Typed lookup: known cluster names (per the generated `ClustersByName`)
     // resolve to their specific class (e.g. `clusters.onOff` is `OnOffCluster`),
     // while unknown keys fall back to the generic Cluster via the index half.
@@ -70,8 +79,21 @@ declare module 'zigbee-clusters' {
     unbind(clusterName: string): void;
 
     makeDefaultResponseFrame(receivedFrame: unknown, success: boolean, status: types.ZCLEnum8Status): typeof zclFrames.ZCLStandardHeader | typeof zclFrames.ZCLMfgSpecificHeader;
+
+    /**
+     * Dispatch an incoming ZCL frame to the bound cluster and write the response. Handles the
+     * command-response rules: no reply to a Default Response or a group-addressed frame
+     * (ZCL 2.5.12.2), a Default Response carrying a thrown ZCLError's status, and
+     * `disableDefaultResponse`.
+     *
+     * Pass `meta.groupId` for a group-addressed frame, or the suppression cannot be applied.
+     */
+    handleFrame(clusterId: number, frame: Buffer, meta?: { groupId?: number }): Promise<void>;
   }
 
+  /** @deprecated Use {@link Endpoint}; kept so existing references keep compiling. */
+  type ZCLNodeEndpoint = Endpoint;
+
   type ZCLDataType<Value> = import('@athombv/data-types').DataType<Value>;
   const ZCLDataTypes: ZCLDataTypes;
   const ZCLStruct: typeof import('@athombv/data-types').Struct;

test/endpointStandalone.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const assert = require('assert');
+
+const { Endpoint, BoundCluster } = require('..');
+
+const BASIC_CLUSTER_ID = 0x0000;
+const MODEL_ID = 0x0005;
+
+class Basic extends BoundCluster {
+
+  get modelId() {
+    return 'Homey Bridge';
+  }
+
+}
+
+describe('Endpoint standalone', function() {
+  it('serves bound clusters with nothing but a sendFrame owner', async function() {
+    // The whole point of the export: a device answering incoming commands is not a peer, so it
+    // should not have to construct a ZCLNode - which models one remote node and bakes that node's
+    // address into its own sendFrame. Endpoint touches its owner in exactly one place (sendFrame),
+    // so a plain object is enough. If that ever stops being true, this fails.
+    let sent;
+    const endpoint = new Endpoint(
+      {
+        sendFrame: async (_endpointId, _clusterId, frame) => {
+          sent = frame;
+        },
+      },
+      { endpointId: 1, inputClusters: [BASIC_CLUSTER_ID], outputClusters: [] },
+    );
+    endpoint.bind('basic', new Basic());
+
+    const request = Buffer.from([0x00, 0x07, 0x00, MODEL_ID, 0x00]);
+    await endpoint.handleFrame(BASIC_CLUSTER_ID, request);
+
+    assert.equal(sent.toString('hex'), '180701050000420c486f6d657920427269646765');
+  });
+});