homebridge-shelly-blu-trv 1.0.0 → 1.0.7

package/README.md

@@ -82,24 +82,55 @@ To test the plugin locally in a running Homebridge instance:
 
 To test in a development Homebridge container, you can mount the packed tarball or install from the working directory with `npm i -g` after `npm run build`.
 
+### E2E (fake gateway) tests
+
+We include a simple fake Shelly BLU gateway and an E2E runner to validate discovery and polling locally:
+
+- Start the fake gateway + headless Homebridge locally: `npm run e2e` (the script builds the project and runs the fake gateway + Homebridge, it times out after ~60s if discovery/polling isn't observed).
+- The repository also includes a GitHub Actions workflow `.github/workflows/e2e.yml` that runs the same test in CI.
+
+### Coverage check
+
+To ensure coverage is sufficient:
+
+- Run tests with coverage: `npm test`
+- Check coverage threshold (lines): `npm run check-coverage` (configured to require at least 80% lines by default, set `COVERAGE_THRESHOLD` env to override)
+
+
 ## Publishing
 
-Automatic publishing is configured to run on new GitHub releases (see `.github/workflows/publish.yml`).
-To publish manually:
+- The repository contains two publishing workflows:
+  - **Publish** (`.github/workflows/publish.yml`) — runs when a GitHub Release is *created* and performs an `npm publish` step.
+  - **Semantic Release** (`.github/workflows/semantic-release.yml`) — when enabled, automatically creates releases, changelogs and publishes to npm on `main` via `semantic-release`.
 
-1. Ensure you're logged in to npm (`npm login`).
+**NOTE:** The automatic semantic-release runs are currently **paused** (workflow trigger switched to `workflow_dispatch`). To run it manually: go to the Actions tab → **Semantic Release** → **Run workflow** (choose `main`).
+
+Manual publish steps
+
+1. Ensure you're logged in to npm: `npm login`.
 2. Build the package: `npm run build`.
-3. Bump the version and push tags, or run `npm version <patch|minor|major>` and push tags.
-4. Publish: `npm publish --access public`.
+3. Bump the package version (e.g. `npm version patch`) and push the tag.
+4. Create a GitHub Release (or run `npm publish --access public` manually).
+
+Developer notes about `NPM_TOKEN` and automation
 
-Automated semantic releases are configured with `semantic-release`. The workflow runs on pushes to `main` and publishes a GitHub Release + npm package when a new release is performed.
+- For CI-based publishing you must set the repository secret `NPM_TOKEN` (Settings → Secrets → Actions) to a valid **npm automation token** with publish rights.
+  - Create it on npm: Settings → Access Tokens → **Create New Token** → choose **Automation** and ensure it has publish rights.
+  - If your npm account uses Two-Factor Authentication (2FA), pick a token that is usable for CI (set 2FA to **Authorization only** for automation tokens). See https://docs.npmjs.com/getting-started/working_with_tokens for details.
+- If semantic-release reports `EINVALIDNPMTOKEN` or `401 Unauthorized`, try re-creating the token and updating `NPM_TOKEN` in repo secrets.
+- The repository also includes a Publish workflow (triggered on Release creation) which can publish even if semantic-release is paused — this is useful for one-off releases.
 
-Note: You must add the following repository secrets for automatic publishing to work:
+E2E and local verification (developer)
 
-- `NPM_TOKEN` — npm token with publish permissions
-- `GITHUB_TOKEN` — typically provided automatically by GitHub Actions (`secrets.GITHUB_TOKEN`) but keep it available if you customize tokens
+- Run the E2E runner locally: `npm run e2e` — this will install deps, build the project, install a local shim, start the fake gateway and a headless Homebridge instance and look for discovery/polling logs.
+- Run unit tests + coverage: `npm test` (creates `coverage/lcov.info` and an `lcov-report` directory).
+- Check coverage threshold: `npm run check-coverage` (defaults to 80% lines; use `COVERAGE_THRESHOLD` to override).
+
+If you'd like, I can add a small diagnostic Action that runs `npm whoami` using `NPM_TOKEN` (safely) so you can quickly confirm which npm account the token maps to before re-enabling semantic-release.
+
+---
 
-If you'd like me to open a PR with this setup and add a draft release, say so and I will create the branch and PR now.
+If you want this documentation expanded into a `DEVELOPING.md` file or want me to add the diagnostic Action, tell me which and I'll add it in a PR.
 
 ## License
 

package/dist/accessory.js

@@ -52,7 +52,7 @@ class ShellyTrvAccessory {
             this.log.warn(`[${this.accessory.displayName}] Device offline, unable to retrieve ${key}`);
             throw new this.platform.api.hap.HapStatusError(-70402 /* this.platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE */);
         }
-        // accessing dynamic state keys
+        // accessing typed state keys
         const value = s[key];
         this.log.debug(`[${this.accessory.displayName}] Retrieved ${key}: ${value}`);
         return value;

package/dist/shellyApi.js

@@ -21,8 +21,16 @@ class ShellyApi {
                 signal: AbortSignal.timeout(this.requestTimeout)
             });
             if (!res.ok) {
-                this.log.error(`[ShellyApi] HTTP ${res.status} from gateway ${this.gw.host}`);
-                throw new Error(`HTTP ${res.status}`);
+                // Try to extract body text for better diagnostics
+                let bodyText = '';
+                try {
+                    bodyText = await res.text();
+                }
+                catch {
+                    bodyText = '<no body>';
+                }
+                this.log.error(`[ShellyApi] HTTP ${res.status} from gateway ${this.gw.host}${path} - ${bodyText}`);
+                throw new Error(`HTTP ${res.status}: ${bodyText}`);
             }
             const data = await res.json();
             this.log.debug(`[ShellyApi] Successfully fetched from ${this.gw.host}${path}`);
@@ -30,11 +38,58 @@ class ShellyApi {
         }
         catch (error) {
             if (error instanceof Error) {
-                this.log.error(`[ShellyApi] Request failed to ${this.gw.host}: ${error.message}`);
+                this.log.error(`[ShellyApi] Request failed to ${this.gw.host}${path}: ${error.message}`);
             }
             throw error;
         }
     }
+    async rpcCall(id, method, params) {
+        // Try several RPC variants for wider compatibility with firmware differences
+        const paramsStr = params ? `&params=${encodeURIComponent(JSON.stringify(params))}` : '';
+        const candidates = [
+            `/rpc/BluTrv.call?id=${id}&method=${method}${paramsStr}`,
+            `/rpc/BluTrv.call&id=${id}&method=${method}${paramsStr}`
+        ];
+        for (const path of candidates) {
+            try {
+                return await this.get(path);
+            }
+            catch (err) {
+                // If 404, try next candidate; otherwise propagate
+                if (err instanceof Error && err.message.includes('HTTP 404')) {
+                    this.log.debug(`[ShellyApi] RPC variant failed (404), trying next: ${path}`);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        // Fallback: try POST to /rpc/BluTrv.call with JSON body
+        try {
+            const url = buildUrl(this.gw.host, '/rpc/BluTrv.call', this.gw.token);
+            const res = await fetch(url, {
+                method: 'POST',
+                body: JSON.stringify({ id, method, params }),
+                headers: { 'Content-Type': 'application/json' },
+                signal: AbortSignal.timeout(this.requestTimeout)
+            });
+            if (!res.ok) {
+                let bodyText = '';
+                try {
+                    bodyText = await res.text();
+                }
+                catch {
+                    bodyText = '<no body>';
+                }
+                this.log.error(`[ShellyApi] HTTP ${res.status} from gateway ${this.gw.host} (POST /rpc/BluTrv.call): ${bodyText}`);
+                throw new Error(`HTTP ${res.status}: ${bodyText}`);
+            }
+            return res.json();
+        }
+        catch (err) {
+            this.log.error(`[ShellyApi] RPC call failed for TRV ${id} method ${method}: ${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
+    }
     async discoverTrvs() {
         this.log.debug(`[ShellyApi] Discovering TRVs from gateway ${this.gw.host}`);
         try {
@@ -57,7 +112,7 @@ class ShellyApi {
     async getTrvState(id) {
         this.log.debug(`[ShellyApi] Fetching state for TRV ${id}`);
         try {
-            const rpc = await this.get(`/rpc/BluTrv.call&id=${id}&method=TRV.GetStatus`);
+            const rpc = await this.rpcCall(id, 'TRV.GetStatus');
             const status = await this.get("/status");
             const dev = status.ble?.devices?.find((d) => d.id === id);
             const state = {
@@ -78,8 +133,7 @@ class ShellyApi {
     async setTargetTemp(id, value) {
         this.log.debug(`[ShellyApi] Setting target temperature for TRV ${id} to ${value}°C`);
         try {
-            await this.get(`/rpc/BluTrv.call&id=${id}&method=TRV.SetTarget&params=` +
-                encodeURIComponent(JSON.stringify({ target_C: value })));
+            await this.rpcCall(id, 'TRV.SetTarget', { target_C: value });
             this.log.debug(`[ShellyApi] Successfully set target temperature for TRV ${id}`);
         }
         catch (error) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-shelly-blu-trv",
   "displayName": "Shelly BLU TRV",
-  "version": "1.0.0",
+  "version": "1.0.7",
   "description": "Homebridge plugin for Shelly BLU TRV thermostats via Shelly BLU Gateway Gen3",
   "license": "MIT",
   "author": "agiplv",
@@ -39,6 +39,8 @@
     "test": "vitest run --coverage",
     "test:watch": "vitest",
     "lint": "eslint . --ext .ts",
+    "e2e": "node scripts/run-e2e.js",
+    "check-coverage": "node scripts/check-coverage.js",
     "release:patch": "npm version patch -m \"chore(release): %s\" && git push --follow-tags",
     "semantic-release": "semantic-release"
   },