@switchbot/homebridge-switchbot 5.0.0-beta.99 → 5.0.1

package/docs/index.html

@@ -19,6 +19,27 @@
 <li>Click <strong>Install</strong></li>
 </ol>
 <h2 id="configuration" class="tsd-anchor-link">Configuration<a href="#configuration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<h3 id="openapi-pollingrate-advanced-settings-ui" class="tsd-anchor-link">OpenAPI Polling/Rate Advanced Settings (UI)<a href="#openapi-pollingrate-advanced-settings-ui" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<p>You can now configure global OpenAPI polling and rate-limiting options directly from the Homebridge UI:</p>
+<ul>
+<li>Go to the SwitchBot plugin settings in Homebridge Config UI X.</li>
+<li>Scroll to the <strong>Advanced Settings</strong> section at the bottom of the page.</li>
+<li>Adjust the following options as needed:
+<ul>
+<li><strong>OpenAPI Polling Interval (seconds):</strong> How often to poll devices via OpenAPI for status. Default: 300 (5 min). Min: 30. Can be overridden per device.</li>
+<li><strong>Enable Batched OpenAPI Polling:</strong> Poll all OpenAPI devices in a single batch at the configured interval. Devices with per-device refreshRate are excluded from the batch.</li>
+<li><strong>OpenAPI Batch Polling Interval (seconds):</strong> Interval for batched OpenAPI polling. Falls back to OpenAPI Polling Interval if not set. Default: 300.</li>
+<li><strong>OpenAPI Daily Request Limit:</strong> Maximum OpenAPI requests per day allowed by the plugin. Default: 10000.</li>
+<li><strong>OpenAPI Reserve for Commands:</strong> Requests reserved for user actions. When remaining budget reaches this value, background polling pauses. Default: 1000.</li>
+<li><strong>Reset OpenAPI Counter at Local Midnight:</strong> If true, resets the daily OpenAPI request counter at local midnight. If false, resets at UTC midnight.</li>
+<li><strong>Only Allow Webhooks on Reserve:</strong> When remaining OpenAPI budget reaches the reserve, only webhooks and user commands are allowed. Background polling/discovery pauses.</li>
+<li><strong>OpenAPI Batch Concurrency:</strong> Maximum number of parallel OpenAPI status calls during a batch. Default: 5.</li>
+<li><strong>OpenAPI Batch Jitter (seconds):</strong> Random startup delay before the first batch to reduce synchronized spikes. Default: 0.</li>
+</ul>
+</li>
+</ul>
+<p>Click <strong>Save Advanced Settings</strong> to apply changes. These settings match the options available in <code>config.schema.json</code> and can be overridden per device.</p>
+<!-- Optionally add a screenshot here -->
 <ul>
 <li>
 <h3 id="if-using-openapi-connection" class="tsd-anchor-link">If using OpenAPI Connection<a href="#if-using-openapi-connection" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
@@ -281,6 +302,15 @@ Without this step, then you will receive the following error when the swichbot p
 </li>
 </ul>
 </li>
+<li><a href="https://us.switch-bot.com/products/switchbot-hub-mini-2">SwitchBot Hub Mini 2</a>
+<ul>
+<li>Supports OpenAPI &amp; Bluetooth Low Energy (BLE) Connections
+<ul>
+<li>Enables Humidity, Temperature, and Light Sensor</li>
+</ul>
+</li>
+</ul>
+</li>
 <li><a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a>
 <ul>
 <li>Supports OpenAPI &amp; Bluetooth Low Energy (BLE) Connections
@@ -301,8 +331,34 @@ Without this step, then you will receive the following error when the swichbot p
 </ul>
 </li>
 </ul>
+<h2 id="ble-encryption-support" class="tsd-anchor-link">BLE Encryption Support<a href="#ble-encryption-support" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<h3 id="ble-encryption-key-and-key-id" class="tsd-anchor-link">BLE Encryption Key and Key ID<a href="#ble-encryption-key-and-key-id" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<p>Some SwitchBot devices (notably newer locks, curtains, and select sensors) require a BLE encryption key and keyId for secure Bluetooth communication. This plugin supports configuring these fields for each device.</p>
+<h4 id="how-to-obtain-ble-encryption-key-and-key-id" class="tsd-anchor-link">How to Obtain BLE Encryption Key and Key ID<a href="#how-to-obtain-ble-encryption-key-and-key-id" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
+<ol>
+<li><strong>Open the SwitchBot App</strong> and select your device.</li>
+<li>Go to <strong>Device Settings</strong> (gear icon).</li>
+<li>Tap <strong>Device Info</strong>.</li>
+<li>If your device supports BLE encryption, you will see fields for <strong>Encryption Key</strong> and <strong>Key ID</strong>. (If not visible, your device may not require encryption or may need a firmware update.)</li>
+<li>Copy the <strong>Encryption Key</strong> and <strong>Key ID</strong> values.</li>
+</ol>
+<h4 id="how-to-configure-in-homebridge" class="tsd-anchor-link">How to Configure in Homebridge<a href="#how-to-configure-in-homebridge" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
+<p>In the Homebridge UI, when adding or editing a SwitchBot device, enter the <strong>Encryption Key</strong> and <strong>Key ID</strong> in the provided fields. These values will be securely used for BLE communication with your device.</p>
+<p><strong>Example device config excerpt:</strong></p>
+<pre><code class="json"><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;deviceId&quot;</span><span class="hl-1">: </span><span class="hl-7">&quot;E7F8A1B2C3D4&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;deviceName&quot;</span><span class="hl-1">: </span><span class="hl-7">&quot;SwitchBot Lock&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;enableBLE&quot;</span><span class="hl-1">: </span><span class="hl-8">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;encryptionKey&quot;</span><span class="hl-1">: </span><span class="hl-7">&quot;0123456789abcdef0123456789abcdef&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;keyId&quot;</span><span class="hl-1">: </span><span class="hl-7">&quot;01&quot;</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+
+<h4 id="which-devices-require-ble-encryption" class="tsd-anchor-link">Which Devices Require BLE Encryption?<a href="#which-devices-require-ble-encryption" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
+<ul>
+<li>SwitchBot Lock (and Lock Pro)</li>
+<li>SwitchBot Curtain 3 (and some Curtain 2 with updated firmware)</li>
+<li>Some sensors and new device models (see device info in app)</li>
+</ul>
+<p>If you are unsure, check your device's info in the SwitchBot app. If the fields are present, copy them into the plugin config.</p>
+<p><strong>Note:</strong> If you enter an incorrect key or keyId, BLE communication will fail for that device. Double-check values if you encounter connection issues.</p>
+<hr>
 <h2 id="supported-ir-devices" class="tsd-anchor-link">Supported IR Devices<a href="#supported-ir-devices" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
-<h3 id="all-ir-devices-require-switchbot-hub-2-switchbot-hub-3-or-hub-mini" class="tsd-anchor-link"><em>(All IR Devices require <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a>, or <a href="https://www.switch-bot.com/products/switchbot-hub-mini">Hub Mini</a>)</em><a href="#all-ir-devices-require-switchbot-hub-2-switchbot-hub-3-or-hub-mini" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<h3 id="all-ir-devices-require-switchbot-hub-2-switchbot-hub-mini-2-switchbot-hub-3-or-hub-mini" class="tsd-anchor-link"><em>(All IR Devices require <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-mini-2">SwitchBot Hub Mini 2</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a>, or <a href="https://www.switch-bot.com/products/switchbot-hub-mini">Hub Mini</a>)</em><a href="#all-ir-devices-require-switchbot-hub-2-switchbot-hub-mini-2-switchbot-hub-3-or-hub-mini" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <ul>
 <li>TV
 <ul>
@@ -404,13 +460,16 @@ Without this step, then you will receive the following error when the swichbot p
 <li>The batch worklist is randomized every cycle to further distribute API load.</li>
 </ul>
 <p>These controls keep API usage smooth and predictable while preserving per-device control when needed.</p>
-<h2 id="whats-new-in-the-v4-beta-summary" class="tsd-anchor-link">What's new in the v4 beta (summary)<a href="#whats-new-in-the-v4-beta-summary" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<h2 id="whats-new-with-node-switchbot-v400" class="tsd-anchor-link">What's new with node-switchbot v4.0.0<a href="#whats-new-with-node-switchbot-v400" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <ul>
 <li>
 <p>Matter-first: when Homebridge Matter is available the plugin now prefers registering Matter accessories (with HAP fallback).</p>
 </li>
 <li>
-<p>Hybrid client: the plugin dynamically imports <code>node-switchbot@4</code> if available and falls back to OpenAPI when <code>openApiToken</code> is configured.</p>
+<p>Hybrid client: the plugin uses <code>node-switchbot@^4.0.0</code> with BLE + OpenAPI discovery and OpenAPI fallback.</p>
+</li>
+<li>
+<p>OpenAPI credentials: cloud discovery and cloud fallback paths require both <code>openApiToken</code> and <code>openApiSecret</code>.</p>
 </li>
 <li>
 <p>UI always served: the plugin UI is packaged into <code>dist/homebridge-ui</code> and is always served when Homebridge UI support is present; there is no platform-level opt-out.</p>
@@ -419,6 +478,9 @@ Without this step, then you will receive the following error when the swichbot p
 <p>OpenAPI hardening: OpenAPI calls have AbortController timeouts, jittered exponential backoff, per-device retry limits and cooldowns, and safe response parsing for resilient behavior.</p>
 </li>
 <li>
+<p>v4 resilience enabled in discovery: plugin discovery enables retry, circuit-breaker, and connection-intelligence flags from <code>node-switchbot</code> v4.</p>
+</li>
+<li>
 <p>Write coalescing (debounce): command writes to the same device are coalesced by default to avoid command floods. Configure with <code>writeDebounceMs</code> (milliseconds, default 100). Set to <code>0</code> to disable coalescing.</p>
 </li>
 </ul>
@@ -432,7 +494,7 @@ Without this step, then you will receive the following error when the swichbot p
 <li><code>dailyApiResetLocalMidnight</code> (boolean, default false): if true, resets the daily counter at local midnight; when false, resets at UTC midnight.</li>
 </ul>
 <p>Example (excerpt):</p>
-<pre><code class="json"><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;options&quot;</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;dailyApiLimit&quot;</span><span class="hl-1">: </span><span class="hl-5">10000</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;dailyApiReserveForCommands&quot;</span><span class="hl-1">: </span><span class="hl-5">1000</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;webhookOnlyOnReserve&quot;</span><span class="hl-1">: </span><span class="hl-7">false</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;dailyApiResetLocalMidnight&quot;</span><span class="hl-1">: </span><span class="hl-7">true</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+<pre><code class="json"><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;options&quot;</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;dailyApiLimit&quot;</span><span class="hl-1">: </span><span class="hl-5">10000</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;dailyApiReserveForCommands&quot;</span><span class="hl-1">: </span><span class="hl-5">1000</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;webhookOnlyOnReserve&quot;</span><span class="hl-1">: </span><span class="hl-8">false</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;dailyApiResetLocalMidnight&quot;</span><span class="hl-1">: </span><span class="hl-8">true</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="switchbot-apis" class="tsd-anchor-link">SwitchBot APIs<a href="#switchbot-apis" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
@@ -444,10 +506,25 @@ Without this step, then you will receive the following error when the swichbot p
 </ul>
 </li>
 </ul>
+<h2 id="development-tests" class="tsd-anchor-link">Development / Tests<a href="#development-tests" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<ul>
+<li>
+<p>Run unit tests:</p>
+<pre><code class="bash"><span class="hl-9">npm</span><span class="hl-1"> </span><span class="hl-7">run</span><span class="hl-1"> </span><span class="hl-7">test</span>
+</code><button type="button">Copy</button></pre>
+
+</li>
+<li>
+<p>Notes:</p>
+<ul>
+<li>Added Lock Ultra (Cloud + BLE) support with <code>node-switchbot</code> v4.</li>
+</ul>
+</li>
+</ul>
 <h2 id="community" class="tsd-anchor-link">Community<a href="#community" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <ul>
 <li><a href="https://www.switch-bot.com/">SwitchBot (Official website)</a></li>
 <li><a href="https://www.facebook.com/SwitchBotRobot/">Facebook @SwitchBotRobot</a></li>
 <li><a href="https://twitter.com/switchbot">Twitter @SwitchBot</a></li>
 </ul>
-</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#switchbothomebridge-switchbot"><span>@switchbot/homebridge-<wbr/>switchbot</span></a><ul><li><a href="#installation"><span>Installation</span></a></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#if-using-openapi-connection"><span>If using <wbr/>Open<wbr/>API <wbr/>Connection</span></a></li><li><a href="#if-using-ble-connection"><span>If using <wbr/>BLE <wbr/>Connection</span></a></li></ul></li><li><a href="#troubleshooting"><span>Troubleshooting</span></a></li><li><ul><li><a href="#if-using-linux-raspberry-pi-os"><span>If using <wbr/>Linux / <wbr/>Raspberry <wbr/>Pi <wbr/>OS</span></a></li><li><a href="#if-using-macos"><span>If using <wbr/>Mac<wbr/>OS</span></a></li></ul></li><li><a href="#supported-switchbot-devices"><span>Supported <wbr/>Switch<wbr/>Bot <wbr/>Devices</span></a></li><li><a href="#supported-ir-devices"><span>Supported <wbr/>IR <wbr/>Devices</span></a></li><li><ul><li><a href="#all-ir-devices-require-switchbot-hub-2-switchbot-hub-3-or-hub-mini"><span>(<wbr/>All <wbr/>IR <wbr/>Devices require <wbr/>Switch<wbr/>Bot <wbr/>Hub 2, <wbr/>Switch<wbr/>Bot <wbr/>Hub 3, or <wbr/>Hub <wbr/>Mini)</span></a></li></ul></li><li><a href="#matter-platform"><span>Matter <wbr/>Platform</span></a></li><li><ul><li><a href="#batched-refresh-and-api-load-control"><span>Batched refresh and <wbr/>API load control</span></a></li></ul></li><li><a href="#whats-new-in-the-v4-beta-summary"><span>What&#39;s new in the v4 beta (summary)</span></a></li><li><a href="#openapi-rate-limiting-and-daily-budget"><span>Open<wbr/>API rate limiting and daily budget</span></a></li><li><a href="#switchbot-apis"><span>Switch<wbr/>Bot <wbr/>AP<wbr/>Is</span></a></li><li><a href="#community"><span>Community</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">@switchbot/homebridge-switchbot</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>
+</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#switchbothomebridge-switchbot"><span>@switchbot/homebridge-<wbr/>switchbot</span></a><ul><li><a href="#installation"><span>Installation</span></a></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#openapi-pollingrate-advanced-settings-ui"><span>Open<wbr/>API <wbr/>Polling/<wbr/>Rate <wbr/>Advanced <wbr/>Settings (<wbr/>UI)</span></a></li><li><a href="#if-using-openapi-connection"><span>If using <wbr/>Open<wbr/>API <wbr/>Connection</span></a></li><li><a href="#if-using-ble-connection"><span>If using <wbr/>BLE <wbr/>Connection</span></a></li></ul></li><li><a href="#troubleshooting"><span>Troubleshooting</span></a></li><li><ul><li><a href="#if-using-linux-raspberry-pi-os"><span>If using <wbr/>Linux / <wbr/>Raspberry <wbr/>Pi <wbr/>OS</span></a></li><li><a href="#if-using-macos"><span>If using <wbr/>Mac<wbr/>OS</span></a></li></ul></li><li><a href="#supported-switchbot-devices"><span>Supported <wbr/>Switch<wbr/>Bot <wbr/>Devices</span></a></li><li><a href="#ble-encryption-support"><span>BLE <wbr/>Encryption <wbr/>Support</span></a></li><li><ul><li><a href="#ble-encryption-key-and-key-id"><span>BLE <wbr/>Encryption <wbr/>Key and <wbr/>Key <wbr/>ID</span></a></li><li><ul><li><a href="#how-to-obtain-ble-encryption-key-and-key-id"><span>How to <wbr/>Obtain <wbr/>BLE <wbr/>Encryption <wbr/>Key and <wbr/>Key <wbr/>ID</span></a></li><li><a href="#how-to-configure-in-homebridge"><span>How to <wbr/>Configure in <wbr/>Homebridge</span></a></li><li><a href="#which-devices-require-ble-encryption"><span>Which <wbr/>Devices <wbr/>Require <wbr/>BLE <wbr/>Encryption?</span></a></li></ul></li></ul></li><li><a href="#supported-ir-devices"><span>Supported <wbr/>IR <wbr/>Devices</span></a></li><li><ul><li><a href="#all-ir-devices-require-switchbot-hub-2-switchbot-hub-mini-2-switchbot-hub-3-or-hub-mini"><span>(<wbr/>All <wbr/>IR <wbr/>Devices require <wbr/>Switch<wbr/>Bot <wbr/>Hub 2, <wbr/>Switch<wbr/>Bot <wbr/>Hub <wbr/>Mini 2, <wbr/>Switch<wbr/>Bot <wbr/>Hub 3, or <wbr/>Hub <wbr/>Mini)</span></a></li></ul></li><li><a href="#matter-platform"><span>Matter <wbr/>Platform</span></a></li><li><ul><li><a href="#batched-refresh-and-api-load-control"><span>Batched refresh and <wbr/>API load control</span></a></li></ul></li><li><a href="#whats-new-with-node-switchbot-v400"><span>What&#39;s new with node-<wbr/>switchbot v4.0.0</span></a></li><li><a href="#openapi-rate-limiting-and-daily-budget"><span>Open<wbr/>API rate limiting and daily budget</span></a></li><li><a href="#switchbot-apis"><span>Switch<wbr/>Bot <wbr/>AP<wbr/>Is</span></a></li><li><a href="#development-tests"><span>Development / <wbr/>Tests</span></a></li><li><a href="#community"><span>Community</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">@switchbot/homebridge-switchbot</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>

package/docs/variables/default.html

@@ -1 +1,3 @@
-<!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>default | @switchbot/homebridge-switchbot</title><meta name="description" content="Documentation for @switchbot/homebridge-switchbot"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">@switchbot/homebridge-switchbot</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">default</a></li></ul><h1>Variable default</h1></div><div class="tsd-signature"><span class="tsd-kind-variable">default</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">api</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">API</span><span class="tsd-signature-symbol">)</span> <span class="tsd-signature-symbol">=&gt;</span> <span class="tsd-signature-type">void</span></div><div class="tsd-type-declaration"><h4>Type Declaration</h4><ul class="tsd-parameters"><li class="tsd-parameter-signature"><ul class="tsd-signatures"><li class="tsd-signature" id="__type"><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">api</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">API</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">void</span></li><li class="tsd-description"><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">api</span>: <span class="tsd-signature-type">API</span></span></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4></li></ul></li></ul></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/OpenWonderLabs/homebridge-switchbot/blob/dbdf57e1761be5ce89ad468b26d416a09f504972/src/index.ts#L12">index.ts:12</a></li></ul></aside></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">@switchbot/homebridge-switchbot</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>
+<!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>default | @switchbot/homebridge-switchbot</title><meta name="description" content="Documentation for @switchbot/homebridge-switchbot"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">@switchbot/homebridge-switchbot</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">default</a></li></ul><h1>Variable default</h1></div><div class="tsd-signature"><span class="tsd-kind-variable">default</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">api</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">API</span><span class="tsd-signature-symbol">)</span> <span class="tsd-signature-symbol">=&gt;</span> <span class="tsd-signature-type">void</span></div><div class="tsd-comment tsd-typography"><p>Registers the SwitchBot platform with Homebridge.</p>
+</div><div class="tsd-type-declaration"><h4>Type Declaration</h4><ul class="tsd-parameters"><li class="tsd-parameter-signature"><ul class="tsd-signatures"><li class="tsd-signature" id="__type"><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">api</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">API</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">void</span></li><li class="tsd-description"><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">api</span>: <span class="tsd-signature-type">API</span></span><div class="tsd-comment tsd-typography"><p>The Homebridge API instance.</p>
+</div></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4></li></ul></li></ul></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/OpenWonderLabs/homebridge-switchbot/blob/d950b8418492383290fb3f20b573b22faa39f964/src/index.ts#L22">index.ts:22</a></li></ul></aside></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">@switchbot/homebridge-switchbot</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>

package/eslint.config.js

@@ -10,15 +10,22 @@ export default antfu(
     },
     rules: {
       'curly': ['error', 'multi-line'],
+      'import/order': 0,
       'jsdoc/check-alignment': 'error',
       'jsdoc/check-line-alignment': 'error',
+      'no-new': 0,
+      'no-undef': 0,
       'perfectionist/sort-exports': 'error',
       'perfectionist/sort-imports': [
         'error',
         {
           groups: [
-            'type',
-            ['builtin', 'external'],
+            'type-builtin',
+            'type-external',
+            'type-internal',
+            ['type-parent', 'type-sibling', 'type-index'],
+            'builtin',
+            'external',
             'internal',
             ['parent', 'sibling', 'index'],
             'unknown',
@@ -35,9 +42,6 @@ export default antfu(
       'test/no-only-tests': 'error',
       'unicorn/no-useless-spread': 'error',
       'unused-imports/no-unused-vars': ['error', { caughtErrors: 'none' }],
-      'no-new': 0, // Disable the no-new rule
-      'new-cap': 0, // Disable the new-cap rule
-      'no-undef': 0, // Disable the no-undef rule
     },
   },
 )

package/nodemon.json

@@ -1,8 +1,8 @@
 {
   "watch": ["src"],
-  "ext": "ts, html, json",
+  "ext": "ts,html,json",
   "ignore": [],
-  "exec": "DEBUG= tsc && homebridge -T -D -P -I -U ~/.homebridge-dev ..",
+  "exec": "npm run build",
   "signal": "SIGTERM",
   "env": {
     "NODE_OPTIONS": "--trace-warnings"

package/package.json

@@ -2,7 +2,7 @@
   "name": "@switchbot/homebridge-switchbot",
   "displayName": "SwitchBot",
   "type": "module",
-  "version": "5.0.0-beta.99",
+  "version": "5.0.1",
   "description": "The SwitchBot plugin allows you to access your SwitchBot device(s) from HomeKit.",
   "author": "SwitchBot <support@wondertechlabs.com> (https://github.com/SwitchBot)",
   "contributors": [
@@ -56,20 +56,29 @@
   "icon": "https://raw.githubusercontent.com/OpenWonderLabs/homebridge-switchbot/latest/branding/icon.png",
   "engineStrict": true,
   "engines": {
-    "homebridge": "^2.0.0-beta.50",
-    "node": "^20 || ^22 || ^24"
+    "homebridge": "^2.0.0-beta.89",
+    "node": "^22 || ^24"
   },
   "directories": {
     "doc": "docs"
   },
   "scripts": {
+    "sync:device-types": "node scripts/sync-device-types.mjs",
     "check": "npm install && npm outdated",
-    "lint": "eslint src/**/*.ts",
-    "lint:fix": "eslint src/**/*.ts --fix",
-    "watch": "npm run build && npm run plugin-ui && npm link && nodemon",
-    "plugin-ui": "mkdir -p ./dist/homebridge-ui/public && if [ -d ./src/homebridge-ui/public ]; then rsync -a ./src/homebridge-ui/public/ ./dist/homebridge-ui/public/; fi",
-    "build": "npm run clean && tsc && npm run plugin-ui",
-    "prepublishOnly": "npm run lint && npm run build && npm run plugin-ui && npm run docs && npm run docs:lint",
+    "ports:free": "node scripts/free-dev-ports.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint --no-warn-ignored src/**/*.ts test/**/*.ts src/homebridge-ui/**/*.html src/homebridge-ui/public/js/*.ts && npm run typecheck",
+    "lint:src": "eslint --no-warn-ignored src/**/*.ts",
+    "lint:test": "eslint --no-warn-ignored test/**/*.ts",
+    "lint:ui": "eslint --no-warn-ignored src/homebridge-ui/**/*.html",
+    "lint:fix": "eslint --no-warn-ignored src/**/*.ts test/**/*.ts src/homebridge-ui/**/*.html src/homebridge-ui/public/js/*.ts --fix && npm run typecheck",
+    "watch": "npm run ports:free && npm run build && npm run build:ui && npm run plugin-ui && npm link && nodemon",
+    "watch:ui": "npm run ports:free && bash -c 'npx homebridge -I -U -D ~/.homebridge-dev & HB_PID=$!; sleep 6; UIX_STORAGE_PATH=~/.homebridge-dev node ./node_modules/homebridge-config-ui-x/dist/bin/standalone.js & npm run watch:files'",
+    "watch:files": "nodemon",
+    "plugin-ui": "mkdir -p ./dist/homebridge-ui/public && if [ -d ./src/homebridge-ui/public ]; then rsync -a ./src/homebridge-ui/public/ ./dist/homebridge-ui/public/; fi && node scripts/build-ui.js",
+    "build": "npm run sync:device-types && npm run clean && tsc && npm run plugin-ui",
+    "build:ui": "tsc --project tsconfig.ui.json",
+    "prepublishOnly": "npm run lint && npm run build && npm run build:ui && npm run plugin-ui && npm run docs && npm run docs:lint",
     "postpublish": "npm run clean && npm ci",
     "clean": "shx rm -rf ./dist",
     "test": "vitest run",
@@ -82,25 +91,29 @@
     "access": "public"
   },
   "dependencies": {
-    "@homebridge/plugin-ui-utils": "^2.2.1",
-    "node-switchbot": "^4.0.0-beta.3"
+    "@homebridge/plugin-ui-utils": "^2.2.3",
+    "class-validator": "^0.15.1",
+    "node-switchbot": "^4.0.1"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^7.6.1",
-    "@types/debug": "^4.1.12",
+    "@antfu/eslint-config": "^8.2.0",
+    "@types/debug": "^4.1.13",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^25.3.3",
+    "@types/node": "^25.6.0",
     "@types/semver": "^7.7.1",
     "@types/source-map-support": "^0.5.10",
-    "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^10.0.2",
+    "@vitest/coverage-v8": "^4.1.4",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.2.0",
     "eslint-plugin-format": "^2.0.1",
-    "homebridge": "^2.0.0-beta.77",
-    "homebridge-config-ui-x": "^5.19.0",
+    "eslint-plugin-html": "^8.1.4",
+    "eslint-plugin-perfectionist": "^5.8.0",
+    "homebridge": "^2.0.0-beta.89",
+    "homebridge-config-ui-x": "^5.21.0",
     "nodemon": "^3.1.14",
     "shx": "^0.4.0",
-    "typedoc": "^0.28.17",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "typedoc": "^0.28.19",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
   }
-}
+}

package/scripts/build-ui.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import esbuild from 'esbuild'
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const srcDir = path.resolve(__dirname, '../src/homebridge-ui/public/js')
+const outputDir = path.resolve(__dirname, '../dist/homebridge-ui/public/js')
+
+// Ensure output directory exists
+fs.mkdirSync(outputDir, { recursive: true })
+
+// Transpile TypeScript to JavaScript with esbuild
+esbuild
+  .build({
+    entryPoints: [path.join(srcDir, 'app.ts')],
+    outfile: path.join(outputDir, 'app.js'),
+    bundle: true,
+    target: 'es2020',
+    platform: 'browser',
+    format: 'esm',
+    sourcemap: true,
+    external: [],
+    minify: false,
+    logLevel: 'info',
+  })
+  .then(() => {
+    console.log('✓ UI bundling complete')
+  })
+  .catch((error) => {
+    console.error('✗ UI bundling failed:', error)
+    process.exit(1)
+  })

package/scripts/free-dev-ports.mjs

@@ -0,0 +1,105 @@
+import { execSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { resolve } from 'node:path'
+
+function resolvePorts() {
+  let bridgePort = 51829
+  let uiPort = 8581
+
+  try {
+    const configPath = resolve(homedir(), '.homebridge-dev', 'config.json')
+    const config = JSON.parse(readFileSync(configPath, 'utf8'))
+
+    if (typeof config?.bridge?.port === 'number') {
+      bridgePort = config.bridge.port
+    }
+
+    const configUiPlatform = Array.isArray(config?.platforms)
+      ? config.platforms.find(platform => platform?.platform === 'config')
+      : undefined
+
+    if (typeof configUiPlatform?.port === 'number') {
+      uiPort = configUiPlatform.port
+    }
+  } catch {}
+
+  return [...new Set([bridgePort, uiPort])]
+}
+
+function pidsForPort(port) {
+  try {
+    const output = execSync(`lsof -ti tcp:${port}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim()
+    return output ? output.split('\n').filter(Boolean) : []
+  } catch {
+    return []
+  }
+}
+
+function freePort(port) {
+  const initialPids = pidsForPort(port)
+  if (initialPids.length === 0) {
+    return
+  }
+
+  try {
+    execSync(`lsof -ti tcp:${port} | xargs -r kill -TERM`, { stdio: ['ignore', 'ignore', 'ignore'] })
+  } catch {}
+
+  const remainingPids = pidsForPort(port)
+  if (remainingPids.length > 0) {
+    try {
+      execSync(`lsof -ti tcp:${port} | xargs -r kill -KILL`, { stdio: ['ignore', 'ignore', 'ignore'] })
+    } catch {}
+  }
+}
+
+function cleanupDevProcesses() {
+  let output = ''
+  try {
+    output = execSync('ps -axo pid=,command=', { stdio: ['ignore', 'pipe', 'ignore'] }).toString()
+  } catch {
+    return
+  }
+
+  const targetPids = output
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const firstSpace = line.indexOf(' ')
+      if (firstSpace === -1) {
+        return null
+      }
+
+      const pid = Number(line.slice(0, firstSpace).trim())
+      const command = line.slice(firstSpace + 1)
+      return Number.isFinite(pid) ? { pid, command } : null
+    })
+    .filter((entry) => {
+      if (!entry) {
+        return false
+      }
+
+      if (entry.pid === process.pid || entry.pid === process.ppid) {
+        return false
+      }
+
+      const isNodemonProcess = entry.command.includes('homebridge-switchbot/node_modules/.bin/nodemon')
+      const isConfigUiProcess = entry.command.trim().startsWith('homebridge-config-ui-x')
+      return isNodemonProcess || isConfigUiProcess
+    })
+    .map(entry => entry.pid)
+
+  for (const pid of targetPids) {
+    try {
+      process.kill(pid, 'SIGTERM')
+    } catch {}
+  }
+}
+
+cleanupDevProcesses()
+
+for (const port of resolvePorts()) {
+  freePort(port)
+}

package/scripts/generate-matter-maps.js

@@ -1,6 +1,6 @@
-#!/usr/bin/env node
-const fs = require('fs')
-const path = require('path')
+const fs = require('node:fs')
+const path = require('node:path')
+const process = require('node:process')
 
 function usage() {
   console.error('Usage: node scripts/generate-matter-maps.js <input-json> [output-file]')
@@ -10,39 +10,50 @@ function usage() {
 const input = process.argv[2]
 const outFile = process.argv[3] || path.join(__dirname, '..', 'src', 'matter-maps.generated.ts')
 
-if (!input) usage()
+if (!input) {
+  usage()
+}
 if (!fs.existsSync(input)) {
   console.error('Input file not found:', input)
   process.exit(2)
 }
 
-const json = JSON.parse(fs.readFileSync(input, 'utf8'))
+let json
+try {
+  json = JSON.parse(fs.readFileSync(input, 'utf8'))
+} catch (e) {
+  console.error('Failed to parse input JSON:', e.message)
+  process.exit(2)
+}
 
 // Expecting structure: { clusters: [{ name, id, attributes: [{ name, id }, ...] }, ...] }
-const clusters = json.clusters || []
+const clusters = Array.isArray(json.clusters) ? json.clusters : []
 
 const clusterMapEntries = []
 const attrGroups = {}
 
 for (const c of clusters) {
-  if (!c.name || typeof c.id === 'undefined') continue
-  const key = c.name.replace(/[^A-Za-z0-9_]/g, '')
-  clusterMapEntries.push(`  ${key}: 0x${parseInt(String(c.id), 10).toString(16)}`)
+  if (!c.name || typeof c.id === 'undefined') {
+    continue
+  }
+  const key = c.name.replace(/\W/g, '')
+  clusterMapEntries.push(`  ${key}: 0x${Number.parseInt(String(c.id), 10).toString(16)}`)
   const attrs = {}
   if (Array.isArray(c.attributes)) {
     for (const a of c.attributes) {
-      if (!a.name || typeof a.id === 'undefined') continue
-      const an = a.name.replace(/[^A-Za-z0-9_]/g, '')
-      attrs[an] = `0x${parseInt(String(a.id), 10).toString(16)}`
+      if (!a.name || typeof a.id === 'undefined') {
+        continue
+      }
+      const an = a.name.replace(/\W/g, '')
+      attrs[an] = `0x${Number.parseInt(String(a.id), 10).toString(16)}`
     }
   }
-  if (Object.keys(attrs).length) attrGroups[key] = attrs
+  if (Object.keys(attrs).length) {
+    attrGroups[key] = attrs
+  }
 }
 
-const clusterMap = `export const MATTER_CLUSTER_IDS = {
-${clusterMapEntries.join(',\n')}
-} as const
-\n`
+const clusterMap = `export const MATTER_CLUSTER_IDS = {\n${clusterMapEntries.join(',\n')}\n} as const\n\n`
 
 let attrText = 'export const MATTER_ATTRIBUTE_IDS = {\n'
 for (const [k, v] of Object.entries(attrGroups)) {
@@ -56,5 +67,11 @@ attrText += `} as const\n`
 
 const fileContent = `// GENERATED FILE - do not edit by hand.\n// Run: node scripts/generate-matter-maps.js <zap-matter.json>\n\n${clusterMap}\n${attrText}`
 
+// Ensure output directory exists
+const outDir = path.dirname(outFile)
+if (!fs.existsSync(outDir)) {
+  fs.mkdirSync(outDir, { recursive: true })
+}
+
 fs.writeFileSync(outFile, fileContent, 'utf8')
 console.log('Wrote', outFile)