Merge release v1.3.1

Author: github-actions[bot]

CHANGELOG.md

@@ -1,4 +1,7 @@
 # Changelog
+## [1.3.1] - 2025-10-26
+- Fixed forwarding direction for HMB devices. (#96)
+- Added retry logic with exponential backoff for Hame API calls to handle temporary server errors (#97)
 
 ## [1.3.0] - 2025-10-03
 - **BREAKING**: Username and password are now required for Home Assistant addon

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:18.19.1-alpine AS builder
+FROM node:23.11-alpine AS builder
 
 WORKDIR /build
 
@@ -19,7 +19,7 @@ RUN npm run build
 RUN npm ci --only=production
 
 # Runtime stage
-FROM node:20-alpine
+FROM node:23.11-alpine
 
 WORKDIR /app
 

hassio-addon/Dockerfile

@@ -1,5 +1,5 @@
 # Build stage
-FROM node:18.19.1-alpine AS builder
+FROM node:23.11-alpine AS builder
 
 WORKDIR /build
 

package-lock.json

@@ -17,14 +17,13 @@
   "dependencies": {
     "mqtt": "^5.3.5",
     "node-fetch": "^3.3.2",
-    "pino": "^9.7.0",
+    "pino": "^10.1.0",
     "pino-pretty": "^13.0.0"
   },
   "devDependencies": {
-    "@types/mqtt": "^2.5.0",
-    "@types/node": "^20.11.0",
+    "@types/node": "^24.9.1",
     "prettier": "^3.6.2",
-    "rimraf": "^5.0.5",
+    "rimraf": "^6.0.1",
     "tsx": "^4.20.3",
     "typescript": "^5.3.3"
   }

package.json

@@ -2,6 +2,119 @@ import { createHash } from "crypto";
 import fetch from "node-fetch";
 import { logger } from "./logger.js";
 
+/**
+ * Custom error class that includes HTTP status code information
+ */
+class HttpError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode: number,
+  ) {
+    super(message);
+    this.name = "HttpError";
+  }
+}
+
+interface RetryOptions {
+  maxRetries: number;
+  baseDelayMs: number;
+  maxDelayMs: number;
+  backoffMultiplier: number;
+}
+
+const DEFAULT_RETRY_OPTIONS: RetryOptions = {
+  maxRetries: 3,
+  baseDelayMs: 1000,
+  maxDelayMs: 10000,
+  backoffMultiplier: 2,
+};
+
+/**
+ * Determines if an error should be retried based on HTTP status codes
+ * Uses a simple, reliable approach: only retry on known server errors and timeouts
+ */
+function shouldRetryError(error: Error, statusCode?: number): boolean {
+  // If we have an HTTP status code, use standard HTTP semantics
+  if (statusCode !== undefined) {
+    // Only retry server errors (5xx)
+    return statusCode >= 500;
+  }
+
+  // For network errors without status codes, only retry specific known transient issues
+  // Check Node.js system error codes (most reliable)
+  if ("code" in error && typeof (error as any).code === "string") {
+    const code = (error as any).code;
+    return code === "ETIMEDOUT" || code === "ECONNRESET";
+  }
+
+  // Don't retry anything else - be conservative
+  return false;
+}
+
+async function withRetry<T>(
+  operation: () => Promise<T>,
+  operationName: string,
+  options: Partial<RetryOptions> = {},
+): Promise<T> {
+  const { maxRetries, baseDelayMs, maxDelayMs, backoffMultiplier } = {
+    ...DEFAULT_RETRY_OPTIONS,
+    ...options,
+  };
+
+  let lastError: Error;
+  let lastStatusCode: number | undefined;
+
+  for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+    try {
+      const result = await operation();
+      if (attempt > 1) {
+        logger.info(`${operationName} succeeded on attempt ${attempt}`);
+      }
+      return result;
+    } catch (error) {
+      lastError = error as Error;
+
+      // Extract status code if it's an HttpError
+      if (error instanceof HttpError) {
+        lastStatusCode = error.statusCode;
+      } else {
+        lastStatusCode = undefined;
+      }
+
+      if (
+        attempt <= maxRetries &&
+        shouldRetryError(lastError, lastStatusCode)
+      ) {
+        const delay = Math.min(
+          baseDelayMs * Math.pow(backoffMultiplier, attempt - 1),
+          maxDelayMs,
+        );
+
+        const statusInfo = lastStatusCode ? ` (HTTP ${lastStatusCode})` : "";
+        logger.warn(
+          `${operationName} failed on attempt ${attempt}/${maxRetries + 1}: ${lastError.message}${statusInfo}. Retrying in ${delay}ms...`,
+        );
+
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      } else {
+        if (attempt <= maxRetries) {
+          const statusInfo = lastStatusCode ? ` (HTTP ${lastStatusCode})` : "";
+          logger.info(
+            `${operationName} failed with non-retryable error: ${lastError.message}${statusInfo}. Not retrying.`,
+          );
+        } else {
+          logger.error(
+            `${operationName} failed after ${maxRetries + 1} attempts. Final error: ${lastError.message}`,
+          );
+        }
+        break;
+      }
+    }
+  }
+
+  throw lastError!;
+}
+
 export interface HameApiResponse {
   code: string;
   msg: string;
@@ -60,16 +173,28 @@ export class HameApi {
     url.searchParams.append("pwd", hashedPassword);
 
     logger.info(`Fetching device token for ${mailbox}...`);
-    const resp = await fetch(url.toString(), { headers: this.headers });
-    const data = (await resp.json()) as HameApiResponse;
 
-    if (data.code !== "2" || !data.token) {
-      throw new Error(
-        `Unexpected API response code: ${data.code} - ${data.msg}`,
-      );
-    }
+    return withRetry(async () => {
+      const resp = await fetch(url.toString(), { headers: this.headers });
 
-    return data;
+      // Check HTTP status first - we have the response object here
+      if (!resp.ok) {
+        throw new HttpError(
+          `HTTP ${resp.status}: ${resp.statusText}`,
+          resp.status,
+        );
+      }
+
+      const data = (await resp.json()) as HameApiResponse;
+
+      if (data.code !== "2" || !data.token) {
+        throw new Error(
+          `Unexpected API response code: ${data.code} - ${data.msg}`,
+        );
+      }
+
+      return data;
+    }, `Fetch device token for ${mailbox}`);
   }
 
   async fetchDeviceList(
@@ -84,21 +209,42 @@ export class HameApi {
     url.searchParams.append("token", token);
 
     logger.info("Fetching device list...");
-    const resp = await fetch(url.toString(), { headers: this.headers });
-    const data = (await resp.json()) as HameDeviceListResponse;
 
-    if (data.code !== 1) {
-      throw new Error(
-        `Unexpected API response from device list: ${data.code} - ${data.msg}`,
-      );
-    }
+    return withRetry(async () => {
+      const resp = await fetch(url.toString(), { headers: this.headers });
 
-    return data;
+      // Check HTTP status first - we have the response object here
+      if (!resp.ok) {
+        throw new HttpError(
+          `HTTP ${resp.status}: ${resp.statusText}`,
+          resp.status,
+        );
+      }
+
+      const data = (await resp.json()) as HameDeviceListResponse;
+
+      if (data.code !== 1) {
+        throw new Error(
+          `Unexpected API response from device list: ${data.code} - ${data.msg}`,
+        );
+      }
+
+      return data;
+    }, "Fetch device list");
   }
 
   async fetchDevices(mailbox: string, password: string): Promise<DeviceInfo[]> {
-    const tokenResp = await this.fetchDeviceToken(mailbox, password);
-    const list = await this.fetchDeviceList(mailbox, tokenResp.token!);
-    return list.data;
+    return withRetry(
+      async () => {
+        const tokenResp = await this.fetchDeviceToken(mailbox, password);
+        const list = await this.fetchDeviceList(mailbox, tokenResp.token!);
+        logger.info(
+          `Successfully fetched ${list.data.length} devices from Hame API`,
+        );
+        return list.data;
+      },
+      "Fetch devices from Hame API",
+      { maxRetries: 2 }, // Fewer retries for the overall operation since individual calls already retry
+    );
   }
 }

src/hame_api.ts

@@ -8,7 +8,7 @@ export const logger = pino({
         target: "pino-pretty",
         options: {
           colorize: false,
-          translateTime: "HH:MM:ss",
+          translateTime: "yyyy-mm-dd HH:MM:ss",
           ignore: "pid,hostname",
         },
       },

src/logger.ts

@@ -245,7 +245,7 @@ async function start() {
       // Set inverse forwarding based on device type and configuration
       if (device.inverse_forwarding === undefined) {
         const deviceType = device.type.toUpperCase();
-        const selectableTypes = ["HMA", "HMF", "HMK", "HMJ"];
+        const selectableTypes = ["HMA", "HMF", "HMK", "HMJ", "HMB"];
 
         if (selectableTypes.some((type) => deviceType.startsWith(type))) {
           // For selectable device types, check if device ID is in the list