iobroker.easee 2.0.0 → 3.0.0

package/README.md

@@ -40,6 +40,10 @@ This adapter would not have been possible without the great work of @Newan (http
   Placeholder for the next version (at the beginning of the line):
   ### **WORK IN PROGRESS**
 -->
+### 3.0.0 (2026-10-23)
+- (Voodoo2man) Migrated the adapter to TypeScript; Node.js 22.19.0 or newer is required
+- (Voodoo2man) Updated adapter tooling, Admin configuration, and runtime metadata
+
 ### 2.0.0 (2026-10-18)
 - (Voodoo2man) Improved charger status and connectivity handling with the Observations API, SignalR resilience, bounded polling, and API retries, incorporating contributions from @Voodoo2man, @Michaelnorge, @Codibris, and @m1chel87, with earlier Node.js and JSON-config groundwork from @NCIceWolf.
 - (Voodoo2man) Improved circuit-current update reliability and added configurable, rate-limit-aware session polling across chargers.
@@ -60,9 +64,6 @@ This adapter would not have been possible without the great work of @Newan (http
 * (walburgf)  modified internationalization to use jsonConfig.json. this needs at least ioBroker.admin version 5
 * (walburgf)  added dependency to admin >=v5.1.28
 
-### 1.0.8 (2023-07-02)
-* (Newan)  small fixes
-
 [Older changelogs can be found there](CHANGELOG_OLD.md)
 
 ## Donation

package/admin/jsonConfig.json

@@ -17,7 +17,7 @@
             "lg": 4,
             "xl": 4,
             "label": "Username",
-            "help": "Username to access Easee cloud"
+            "help": "username to access Easee cloud"
         },
         "client_secret": {
             "type": "password",
@@ -55,6 +55,11 @@
         },
         "sessionPollMode": {
             "type": "select",
+            "xs": 12,
+            "sm": 12,
+            "md": 6,
+            "lg": 4,
+            "xl": 4,
             "options": [
                 { "label": "Automatic", "value": "auto" },
                 { "label": "Manual", "value": "manual" }
@@ -65,6 +70,11 @@
         },
         "sessionPollInterval": {
             "type": "number",
+            "xs": 12,
+            "sm": 12,
+            "md": 6,
+            "lg": 4,
+            "xl": 4,
             "min": 7,
             "step": 1,
             "unit": "min",

package/io-package.json

@@ -1,8 +1,21 @@
 {
   "common": {
     "name": "easee",
-    "version": "2.0.0",
+    "version": "3.0.0",
     "news": {
+      "3.0.0": {
+        "en": "Migrated the adapter to TypeScript; Node.js 22.19.0 or newer is required\nUpdated adapter tooling, Admin configuration, and runtime metadata",
+        "de": "Adapter auf TypeScript migriert; Node.js 22.19.0 oder neuer nötig\nAdapter-Tools, Admin-Konfiguration und Runtime-Metadaten aktualisiert",
+        "ru": "Адаптер перенесен на TypeScript; требуется Node.js 22.19.0 или новее\nОбновленные инструменты адаптера, конфигурация администратора и метаданные времени выполнения",
+        "pt": "Migrou o adaptador para o TypeScript; requer Node.js 22.19.0 ou maior\nAdaptador, configuração Admin e metadados de tempo de execução atualizados",
+        "nl": "De adapter is overgezet naar TypeScript; Node.js 22.19.0 of nieuwer is vereist\nBijgewerkte adapterhulpmiddelen, beheerdersconfiguratie en runtime-metagegevens",
+        "fr": "L'adaptateur a migré vers TypeScript ; Node.js 22.19.0 ou plus récent est requis\nOutils d'adaptation, configuration admin et métadonnées d'exécution mis à jour",
+        "it": "È migrato l'adattatore a TypeScript; è richiesto Node.js 22.19.0 o più\nAdapter, configurazione admin e metadati di runtime aggiornati",
+        "es": "Migró el adaptador a TypeScript; se necesita Node.js 22.19.0 o más\nSe actualizaron los adaptadores, la configuración de administración y los metadatos",
+        "pl": "Przeniesiono adapter do TypeScript; wymagany jest plik Node.js 22.19.0 lub nowszy\nZaktualizowano oprzyrządowanie adaptera, konfigurację administratora i metadane środowiska wykonawczego",
+        "uk": "Перемістив адаптер на TypeScript; потрібен Node.js 22.19.0 або новіший\nОновлені інструменти адаптера, конфігурація адміністратора та метадані виконання",
+        "zh-cn": "已将适配器迁移到 TypeScript；需要 Node.js 22.19.0 或更高版本\n更新了适配器工具、管理员配置和运行时元数据"
+      },
       "2.0.0": {
         "en": "Improved charger status and connectivity handling with the Observations API, SignalR resilience, bounded polling, and API retries, incorporating contributions from @Voodoo2man, @Michaelnorge, @Codibris, and @m1chel87, with earlier Node.js and JSON-config groundwork from @NCIceWolf.\nImproved circuit-current update reliability and added configurable, rate-limit-aware session polling across chargers.\nAdded configurable net charging prices and VAT with synchronized gross prices.",
         "de": "Verbesserter Ladestatus und Konnektivität mit Observations API, SignalR Resilience, Bounded Polling und API-Wiederholungen, mit Beiträgen von @Voodoo2man, @Michaelnorge, @Codibris und @m1chel87, mit früheren Node.js- und JSON-Config-Grundlagen von @NCIceWolf.\nZuverlässiger Stromausgleich und konfigurierbares, ratenbegrenztes Session-Polling auf Ladegeräten hinzugefügt.\nNettopreise und Mehrwertsteuer mit synchronisierten Bruttopreisen hinzugefügt.",
@@ -115,7 +128,7 @@
     "tier": 3,
     "mode": "daemon",
     "type": "vehicle",
-    "compact": true,
+    "compact": false,
     "connectionType": "cloud",
     "dataSource": "poll",
     "adminUI": {

package/lib/{enum.js → enum.ts}

@@ -315,7 +315,7 @@
 #define COMMAND_SET_LISTEN_TO_CONTROL_PULSE_ARG_LISTEN_TO_CONTROL_PULSE 1 //ListenToControlPulse [Boolean]
 #endif
 */
-const easeeIds = {
+const easeeIds: Record<number, string> = {
   //config
   31: ".config.isEnabled",
   36: ".config.wiFiSSID",
@@ -358,12 +358,10 @@ const easeeIds = {
   199: ".status.inVoltageT4T5",
 };
 Object.freeze(easeeIds);
-module.exports = {
-  getNameByEnum: function (id) {
-    return easeeIds[id];
-    //return "Not Found"
-  },
-  getValue: function () {
-    // whatever
-  },
-};
+export function getNameByEnum(id: number): string | undefined {
+  return easeeIds[id];
+}
+
+export function getValue(): undefined {
+  return undefined;
+}

package/lib/observations.ts

@@ -0,0 +1,156 @@
+"use strict";
+
+export const CHARGER_STATE_OBSERVATION_IDS = [
+  46, 48, 68, 80, 96, 102, 103, 109, 111, 112, 113, 114, 120, 122, 124, 132,
+  182, 183, 184, 185, 190, 191, 192, 193, 194, 195, 196, 197, 198, 199, 250,
+];
+
+const STATE_FIELDS_BY_OBSERVATION_ID: Record<
+  number,
+  keyof ChargerObservationState
+> = {
+  46: "ledMode",
+  48: "dynamicChargerCurrent",
+  68: "wiFiAPEnabled",
+  80: "chargerFirmware",
+  96: "reasonForNoCurrent",
+  102: "smartCharging",
+  103: "cableLocked",
+  109: "chargerOpMode",
+  111: "dynamicCircuitCurrentP1",
+  112: "dynamicCircuitCurrentP2",
+  113: "dynamicCircuitCurrentP3",
+  114: "outputCurrent",
+  120: "totalPower",
+  122: "energyPerHour",
+  124: "lifetimeEnergy",
+  132: "wiFiRSSI",
+  182: "inCurrentT2",
+  183: "inCurrentT3",
+  184: "inCurrentT4",
+  185: "inCurrentT5",
+  190: "inVoltageT1T2",
+  191: "inVoltageT1T3",
+  192: "inVoltageT1T4",
+  193: "inVoltageT1T5",
+  194: "inVoltageT2T3",
+  195: "inVoltageT2T4",
+  196: "inVoltageT2T5",
+  197: "inVoltageT3T4",
+  198: "inVoltageT3T5",
+  199: "inVoltageT4T5",
+};
+
+const SUPPLY_VOLTAGE_FIELDS = [
+  "inVoltageT2T3",
+  "inVoltageT1T3",
+  "inVoltageT1T4",
+  "inVoltageT1T5",
+  "inVoltageT2T4",
+  "inVoltageT2T5",
+];
+
+/** Easee observation returned by the API. */
+export interface ChargerObservation {
+  id: number;
+  value: unknown;
+}
+
+/** Observation collection returned by the API. */
+export interface ChargerObservationResponse {
+  observations?: ChargerObservation[];
+}
+
+/** Charger state values produced from observations. */
+export interface ChargerObservationState {
+  [field: string]: ioBroker.StateValue | undefined;
+  ledMode: ioBroker.StateValue;
+  dynamicChargerCurrent: ioBroker.StateValue;
+  wiFiAPEnabled: ioBroker.StateValue;
+  chargerFirmware: ioBroker.StateValue;
+  reasonForNoCurrent: ioBroker.StateValue;
+  smartCharging: ioBroker.StateValue;
+  cableLocked: ioBroker.StateValue;
+  chargerOpMode: ioBroker.StateValue;
+  dynamicCircuitCurrentP1: ioBroker.StateValue;
+  dynamicCircuitCurrentP2: ioBroker.StateValue;
+  dynamicCircuitCurrentP3: ioBroker.StateValue;
+  outputCurrent: ioBroker.StateValue;
+  totalPower: ioBroker.StateValue;
+  energyPerHour: ioBroker.StateValue;
+  lifetimeEnergy: ioBroker.StateValue;
+  wiFiRSSI: ioBroker.StateValue;
+  inCurrentT2: ioBroker.StateValue;
+  inCurrentT3: ioBroker.StateValue;
+  inCurrentT4: ioBroker.StateValue;
+  inCurrentT5: ioBroker.StateValue;
+  inVoltageT1T2: ioBroker.StateValue;
+  inVoltageT1T3: ioBroker.StateValue;
+  inVoltageT1T4: ioBroker.StateValue;
+  inVoltageT1T5: ioBroker.StateValue;
+  inVoltageT2T3: ioBroker.StateValue;
+  inVoltageT2T4: ioBroker.StateValue;
+  inVoltageT2T5: ioBroker.StateValue;
+  inVoltageT3T4: ioBroker.StateValue;
+  inVoltageT3T5: ioBroker.StateValue;
+  inVoltageT4T5: ioBroker.StateValue;
+  isOnline?: boolean;
+  voltage: number | null;
+}
+
+/**
+ * Converts Easee API observations to the existing charger state fields.
+ *
+ * @param responseData
+ */
+export function observationsToChargerState(
+  responseData: ChargerObservationResponse | null | undefined,
+): ChargerObservationState {
+  const observations = Array.isArray(responseData?.observations)
+    ? responseData.observations
+    : [];
+  const chargerState: Record<string, ioBroker.StateValue | undefined> =
+    Object.fromEntries(
+      Object.values(STATE_FIELDS_BY_OBSERVATION_ID).map((field) => [
+        field,
+        null,
+      ]),
+    );
+
+  for (const observation of observations) {
+    const field = STATE_FIELDS_BY_OBSERVATION_ID[observation.id];
+    if (field !== undefined && isStateValue(observation.value)) {
+      chargerState[field] = observation.value;
+    }
+  }
+
+  const cloudObservation = observations.find(
+    (observation) => observation.id === 250,
+  );
+  if (cloudObservation) {
+    if (isStateValue(cloudObservation.value)) {
+      chargerState.isOnline = Boolean(cloudObservation.value);
+    }
+  }
+  chargerState.voltage = null;
+  for (const field of SUPPLY_VOLTAGE_FIELDS) {
+    const value = chargerState[field];
+    if (
+      typeof value === "number" &&
+      Number.isFinite(value) &&
+      value >= 100 &&
+      value <= 300
+    ) {
+      chargerState.voltage = value;
+      break;
+    }
+  }
+
+  return chargerState as ChargerObservationState;
+}
+
+function isStateValue(value: unknown): value is ioBroker.StateValue {
+  return (
+    value === null || ["string", "number", "boolean"].includes(typeof value)
+  );
+}

package/lib/{signalr-http-client.js → signalr-http-client.ts}

@@ -1,35 +1,45 @@
 "use strict";
 
-const axios = require("axios").default;
-const signalR = require("@microsoft/signalr");
-const { CookieJar } = require("tough-cookie");
+import axios from "axios";
+import * as signalR from "@microsoft/signalr";
+import { CookieJar } from "tough-cookie";
+import type { HttpRequest, HttpResponse } from "@microsoft/signalr";
 
-function hasHeader(headers, name) {
+type SignalRRequest = HttpRequest;
+
+interface SignalRHttpClientLike {
+  request: typeof axios.request;
+}
+
+function hasHeader(headers: Record<string, string>, name: string): boolean {
   return Object.keys(headers).some(
     (headerName) => headerName.toLowerCase() === name.toLowerCase(),
   );
 }
 
 class AxiosSignalRHttpClient extends signalR.HttpClient {
-  /** @param {any} [httpClient] */
-  constructor(httpClient = axios) {
+  httpClient: SignalRHttpClientLike;
+  cookieJar: InstanceType<typeof CookieJar>;
+
+  constructor(httpClient: SignalRHttpClientLike = axios) {
     super();
     this.httpClient = httpClient;
     this.cookieJar = new CookieJar();
   }
 
-  async send(request) {
+  async send(request: SignalRRequest): Promise<HttpResponse> {
     if (!request.url) {
       throw new Error("SignalR HTTP request URL is missing");
     }
-    const headers = { ...request.headers };
+    const headers = { ...(request.headers || {}) };
     const cookie = this.cookieJar.getCookieStringSync(request.url);
     if (cookie && !hasHeader(headers, "cookie")) {
       headers.Cookie = cookie;
     }
     const cancelSource = axios.CancelToken.source();
-    const abortHandler = () =>
+    const abortHandler = (): void => {
       cancelSource.cancel("SignalR HTTP request aborted");
+    };
     if (request.abortSignal) {
       request.abortSignal.onabort = abortHandler;
     }
@@ -43,7 +53,7 @@ class AxiosSignalRHttpClient extends signalR.HttpClient {
         cancelToken: cancelSource.token,
         responseType:
           request.responseType === "arraybuffer" ? "arraybuffer" : "text",
-        transformResponse: [(data) => data],
+        transformResponse: [(data: unknown) => data],
         validateStatus: () => true,
       });
       for (const setCookie of response.headers?.["set-cookie"] || []) {
@@ -75,9 +85,21 @@ class AxiosSignalRHttpClient extends signalR.HttpClient {
     }
   }
 
-  getCookieString(url) {
+  get(url: string, options?: SignalRRequest): Promise<HttpResponse> {
+    return this.send({ ...options, url, method: "GET" });
+  }
+
+  post(url: string, options?: SignalRRequest): Promise<HttpResponse> {
+    return this.send({ ...options, url, method: "POST" });
+  }
+
+  delete(url: string, options?: SignalRRequest): Promise<HttpResponse> {
+    return this.send({ ...options, url, method: "DELETE" });
+  }
+
+  getCookieString(url: string): string {
     return this.cookieJar.getCookieStringSync(url);
   }
 }
 
-module.exports = AxiosSignalRHttpClient;
+export = AxiosSignalRHttpClient;

package/lib/tools.ts

@@ -0,0 +1,120 @@
+import axios from "axios";
+import type { AxiosError } from "axios";
+
+/**
+ * Tests whether the given variable is a real object and not an Array
+ *
+ * @param it The variable to test
+ * @returns True if the variable is an object, false otherwise
+ */
+export function isObject(it: unknown): it is Record<string, unknown> {
+  return Object.prototype.toString.call(it) === "[object Object]";
+}
+
+/**
+ * Tests whether the given variable is really an Array
+ *
+ * @param it The variable to test
+ * @returns True if the variable is an array, false otherwise
+ */
+export function isArray(it: unknown): it is unknown[] {
+  return Array.isArray(it);
+}
+
+/**
+ * Translates text to the target language. Automatically chooses the right translation API.
+ *
+ * @param text The text to translate
+ * @param targetLang The target language
+ * @param [yandexApiKey] The yandex API key. You can create one for free at https://translate.yandex.com/developers
+ * @returns The translated text
+ */
+export async function translateText(
+  text: string,
+  targetLang: string,
+  yandexApiKey?: string,
+): Promise<string> {
+  if (!text) {
+    return "";
+  }
+  if (targetLang === "en") {
+    return text;
+  }
+
+  return yandexApiKey
+    ? translateYandex(text, targetLang, yandexApiKey)
+    : translateGoogle(text, targetLang);
+}
+
+/**
+ * Translates text with Yandex API
+ *
+ * @param text The text to translate
+ * @param targetLang The target language
+ * @param apiKey The yandex API key. You can create one for free at https://translate.yandex.com/developers
+ * @returns The translated text
+ */
+async function translateYandex(
+  text: string,
+  targetLang: string,
+  apiKey: string,
+): Promise<string> {
+  if (targetLang === "zh-cn") {
+    targetLang = "zh";
+  }
+
+  const url = `https://translate.yandex.net/api/v1.5/tr.json/translate?key=${apiKey}&text=${encodeURIComponent(text)}&lang=en-${targetLang}`;
+  try {
+    const response = await axios.get(url, { timeout: 15000 });
+    if (response.data?.text && isArray(response.data.text)) {
+      return response.data.text[0];
+    }
+    throw new Error("Invalid response for translate request");
+  } catch (error) {
+    throw new Error(
+      `Could not translate to "${targetLang}": ${getErrorMessage(error)}`,
+    );
+  }
+}
+
+/**
+ * Translates text with Google API
+ *
+ * @param text The text to translate
+ * @param targetLang The target language
+ * @returns The translated text
+ */
+async function translateGoogle(
+  text: string,
+  targetLang: string,
+): Promise<string> {
+  const url = `http://translate.googleapis.com/translate_a/single?client=gtx&sl=en&tl=${targetLang}&dt=t&q=${encodeURIComponent(text)}&ie=UTF-8&oe=UTF-8`;
+  try {
+    const response = await axios.get<unknown>(url, { timeout: 15000 });
+    const translation = response.data;
+    if (
+      Array.isArray(translation) &&
+      Array.isArray(translation[0]) &&
+      Array.isArray(translation[0][0]) &&
+      typeof translation[0][0][0] === "string"
+    ) {
+      return translation[0][0][0];
+    }
+    throw new Error("Invalid response for translate request");
+  } catch (error) {
+    const response = axios.isAxiosError(error)
+      ? (error as AxiosError).response
+      : undefined;
+    const detail =
+      response?.status === 429
+        ? `Rate-limited by Google Translate`
+        : getErrorMessage(error);
+    throw new Error(`Could not translate to "${targetLang}": ${detail}`);
+  }
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export { translateYandex, translateGoogle };