edilkamin 1.10.0 → 1.10.2

package/src/cli.ts

@@ -6,6 +6,7 @@ import { version } from "../package.json";
 import { NEW_API_URL, OLD_API_URL } from "./constants";
 import { configure, configureAmplify, getSession, signIn } from "./library";
 import { clearSession, createFileStorage } from "./token-storage";
+import { AlarmCode, AlarmDescriptions } from "./types";
 
 const promptPassword = (): Promise<string> => {
   const rl = readline.createInterface({
@@ -336,6 +337,117 @@ const createProgram = (): Command => {
         mac: string,
       ) => api.getPelletAutonomyTime(jwtToken, mac),
     },
+    // Statistics getters
+    {
+      commandName: "getTotalCounters",
+      description:
+        "Get lifetime operating counters (power-ons, runtime by power level)",
+      getter: (
+        api: ReturnType<typeof configure>,
+        jwtToken: string,
+        mac: string,
+      ) => api.getTotalCounters(jwtToken, mac),
+    },
+    {
+      commandName: "getServiceCounters",
+      description: "Get service counters (runtime since last maintenance)",
+      getter: (
+        api: ReturnType<typeof configure>,
+        jwtToken: string,
+        mac: string,
+      ) => api.getServiceCounters(jwtToken, mac),
+    },
+    {
+      commandName: "getRegenerationData",
+      description: "Get regeneration and maintenance data",
+      getter: (
+        api: ReturnType<typeof configure>,
+        jwtToken: string,
+        mac: string,
+      ) => api.getRegenerationData(jwtToken, mac),
+    },
+    {
+      commandName: "getServiceTime",
+      description: "Get total service time in hours",
+      getter: (
+        api: ReturnType<typeof configure>,
+        jwtToken: string,
+        mac: string,
+      ) => api.getServiceTime(jwtToken, mac),
+    },
+    // Analytics getters
+    {
+      commandName: "getTotalOperatingHours",
+      description: "Get total operating hours across all power levels",
+      getter: (
+        api: ReturnType<typeof configure>,
+        jwtToken: string,
+        mac: string,
+      ) => api.getTotalOperatingHours(jwtToken, mac),
+    },
+    {
+      commandName: "getPowerDistribution",
+      description: "Get power level usage distribution as percentages",
+      getter: async (
+        api: ReturnType<typeof configure>,
+        jwtToken: string,
+        mac: string,
+      ) => {
+        const result = await api.getPowerDistribution(jwtToken, mac);
+        return {
+          p1: `${result.p1.toFixed(1)}%`,
+          p2: `${result.p2.toFixed(1)}%`,
+          p3: `${result.p3.toFixed(1)}%`,
+          p4: `${result.p4.toFixed(1)}%`,
+          p5: `${result.p5.toFixed(1)}%`,
+        };
+      },
+    },
+    {
+      commandName: "getServiceStatus",
+      description: "Get service status including whether maintenance is due",
+      getter: (
+        api: ReturnType<typeof configure>,
+        jwtToken: string,
+        mac: string,
+      ) => api.getServiceStatus(jwtToken, mac),
+    },
+    {
+      commandName: "getUsageAnalytics",
+      description: "Get comprehensive usage analytics in single response",
+      getter: async (
+        api: ReturnType<typeof configure>,
+        jwtToken: string,
+        mac: string,
+      ) => {
+        const analytics = await api.getUsageAnalytics(jwtToken, mac);
+        return {
+          lifetime: {
+            powerOnCount: analytics.totalPowerOns,
+            totalOperatingHours: analytics.totalOperatingHours,
+            blackoutCount: analytics.blackoutCount,
+          },
+          powerDistribution: {
+            p1: `${analytics.powerDistribution.p1.toFixed(1)}%`,
+            p2: `${analytics.powerDistribution.p2.toFixed(1)}%`,
+            p3: `${analytics.powerDistribution.p3.toFixed(1)}%`,
+            p4: `${analytics.powerDistribution.p4.toFixed(1)}%`,
+            p5: `${analytics.powerDistribution.p5.toFixed(1)}%`,
+          },
+          service: {
+            totalServiceHours: analytics.serviceStatus.totalServiceHours,
+            hoursSinceLastService: analytics.serviceStatus.hoursSinceService,
+            thresholdHours: analytics.serviceStatus.serviceThresholdHours,
+            isServiceDue: analytics.serviceStatus.isServiceDue,
+            lastMaintenanceDate:
+              analytics.lastMaintenanceDate?.toISOString() || "Never",
+          },
+          alarms: {
+            totalCount: analytics.alarmCount,
+          },
+        };
+      },
+    },
   ].forEach(({ commandName, description, getter }) => {
     addLegacyOption(
       addMacOption(
@@ -676,6 +788,50 @@ const createProgram = (): Command => {
     console.log(JSON.stringify(result, null, 2));
   });
 
+  // Alarm history command with human-readable descriptions
+  addLegacyOption(
+    addMacOption(
+      addAuthOptions(
+        program
+          .command("getAlarmHistory")
+          .description(
+            "Get alarm history log with human-readable descriptions",
+          ),
+      ),
+    ),
+  ).action(async (options) => {
+    const { username, password, mac, legacy = false } = options;
+    const normalizedMac = mac.replace(/:/g, "");
+    const storage = createFileStorage();
+    configureAmplify(storage);
+    let jwtToken: string;
+    try {
+      jwtToken = await getSession(false, legacy);
+    } catch {
+      if (!username) {
+        throw new Error(
+          "No session found. Please provide --username to sign in.",
+        );
+      }
+      const pwd = password || (await promptPassword());
+      jwtToken = await signIn(username, pwd, legacy);
+    }
+    const apiUrl = legacy ? OLD_API_URL : NEW_API_URL;
+    const api = configure(apiUrl);
+    const result = await api.getAlarmHistory(jwtToken, normalizedMac);
+    // Format alarms with human-readable descriptions
+    const formattedAlarms = result.alarms.map((alarm) => ({
+      ...alarm,
+      typeName: AlarmCode[alarm.type] || "UNKNOWN",
+      description:
+        AlarmDescriptions[alarm.type as AlarmCode] || "Unknown alarm",
+      date: new Date(alarm.timestamp * 1000).toISOString(),
+    }));
+    console.log(
+      JSON.stringify({ ...result, alarms: formattedAlarms }, null, 2),
+    );
+  });
+
   // Command: register
   addLegacyOption(
     addAuthOptions(

package/src/index.ts

@@ -3,13 +3,15 @@ import { configure } from "./library";
 export { bleToWifiMac } from "./bluetooth-utils";
 export { decompressBuffer, isBuffer, processResponse } from "./buffer-utils";
 export { API_URL, NEW_API_URL, OLD_API_URL } from "./constants";
-export { configure, getSession, signIn } from "./library";
+export { configure, deriveUsageAnalytics, getSession, signIn } from "./library";
 export {
   serialNumberDisplay,
   serialNumberFromHex,
   serialNumberToHex,
 } from "./serial-utils";
 export {
+  AlarmEntryType,
+  AlarmsLogType,
   BufferEncodedType,
   CommandsType,
   DeviceAssociationBody,
@@ -18,10 +20,18 @@ export {
   DeviceInfoType,
   DiscoveredDevice,
   EditDeviceAssociationBody,
+  PowerDistributionType,
+  RegenerationDataType,
+  ServiceCountersType,
+  ServiceStatusType,
+  StatusCountersType,
   StatusType,
   TemperaturesType,
+  TotalCountersType,
+  UsageAnalyticsType,
   UserParametersType,
 } from "./types";
+export { AlarmCode, AlarmDescriptions } from "./types";
 
 export const {
   deviceInfo,

package/src/library.test.ts

@@ -3,7 +3,11 @@ import * as amplifyAuth from "aws-amplify/auth";
 import pako from "pako";
 import sinon from "sinon";
 
-import { configure, createAuthService } from "../src/library";
+import {
+  configure,
+  createAuthService,
+  deriveUsageAnalytics,
+} from "../src/library";
 import { API_URL } from "./constants";
 
 /**
@@ -242,6 +246,17 @@ describe("library", () => {
       "getLanguage",
       "getPelletInReserve",
       "getPelletAutonomyTime",
+      // Statistics getters
+      "getTotalCounters",
+      "getServiceCounters",
+      "getAlarmHistory",
+      "getRegenerationData",
+      "getServiceTime",
+      // Analytics functions
+      "getTotalOperatingHours",
+      "getPowerDistribution",
+      "getServiceStatus",
+      "getUsageAnalytics",
     ];
     it("should create API methods with the correct baseURL", async () => {
       const baseURL = "https://example.com/api/";
@@ -1017,6 +1032,453 @@ describe("library", () => {
     });
   });
 
+  describe("statistics getters", () => {
+    const mockDeviceInfoWithStats = {
+      status: {
+        commands: { power: true },
+        temperatures: { board: 25, enviroment: 20 },
+        flags: { is_pellet_in_reserve: false },
+        pellet: { autonomy_time: 900 },
+        counters: { service_time: 1108 },
+      },
+      nvm: {
+        user_parameters: {
+          language: 1,
+          is_auto: false,
+          is_fahrenheit: false,
+          is_sound_active: false,
+          enviroment_1_temperature: 19,
+          enviroment_2_temperature: 20,
+          enviroment_3_temperature: 20,
+          manual_power: 1,
+          fan_1_ventilation: 3,
+          fan_2_ventilation: 0,
+          fan_3_ventilation: 0,
+          is_standby_active: false,
+          standby_waiting_time: 60,
+        },
+        total_counters: {
+          power_ons: 278,
+          p1_working_time: 833,
+          p2_working_time: 15,
+          p3_working_time: 19,
+          p4_working_time: 8,
+          p5_working_time: 17,
+        },
+        service_counters: {
+          p1_working_time: 100,
+          p2_working_time: 10,
+          p3_working_time: 5,
+          p4_working_time: 2,
+          p5_working_time: 1,
+        },
+        alarms_log: {
+          number: 2,
+          index: 2,
+          alarms: [
+            { type: 3, timestamp: 1700000000 },
+            { type: 21, timestamp: 1700001000 },
+          ],
+        },
+        regeneration: {
+          time: 0,
+          last_intervention: 1577836800,
+          daylight_time_flag: 0,
+          blackout_counter: 43,
+          airkare_working_hours_counter: 0,
+        },
+      },
+    };
+
+    it("should get total counters", async () => {
+      fetchStub.resolves(mockResponse(mockDeviceInfoWithStats));
+      const api = configure(API_URL);
+      const result = await api.getTotalCounters(
+        expectedToken,
+        "00:11:22:33:44:55",
+      );
+      assert.deepEqual(result, mockDeviceInfoWithStats.nvm.total_counters);
+    });
+
+    it("should get service counters", async () => {
+      fetchStub.resolves(mockResponse(mockDeviceInfoWithStats));
+      const api = configure(API_URL);
+      const result = await api.getServiceCounters(
+        expectedToken,
+        "00:11:22:33:44:55",
+      );
+      assert.deepEqual(result, mockDeviceInfoWithStats.nvm.service_counters);
+    });
+
+    it("should get alarm history", async () => {
+      fetchStub.resolves(mockResponse(mockDeviceInfoWithStats));
+      const api = configure(API_URL);
+      const result = await api.getAlarmHistory(
+        expectedToken,
+        "00:11:22:33:44:55",
+      );
+      assert.deepEqual(result, mockDeviceInfoWithStats.nvm.alarms_log);
+    });
+
+    it("should get regeneration data", async () => {
+      fetchStub.resolves(mockResponse(mockDeviceInfoWithStats));
+      const api = configure(API_URL);
+      const result = await api.getRegenerationData(
+        expectedToken,
+        "00:11:22:33:44:55",
+      );
+      assert.deepEqual(result, mockDeviceInfoWithStats.nvm.regeneration);
+    });
+
+    it("should get service time", async () => {
+      fetchStub.resolves(mockResponse(mockDeviceInfoWithStats));
+      const api = configure(API_URL);
+      const result = await api.getServiceTime(
+        expectedToken,
+        "00:11:22:33:44:55",
+      );
+      assert.equal(result, 1108);
+    });
+  });
+
+  describe("analytics functions", () => {
+    const mockDeviceInfoWithStats = {
+      status: {
+        commands: { power: true },
+        temperatures: { board: 25, enviroment: 20 },
+        flags: { is_pellet_in_reserve: false },
+        pellet: { autonomy_time: 900 },
+        counters: { service_time: 1108 },
+      },
+      nvm: {
+        user_parameters: {
+          language: 1,
+          is_auto: false,
+          is_fahrenheit: false,
+          is_sound_active: false,
+          enviroment_1_temperature: 19,
+          enviroment_2_temperature: 20,
+          enviroment_3_temperature: 20,
+          manual_power: 1,
+          fan_1_ventilation: 3,
+          fan_2_ventilation: 0,
+          fan_3_ventilation: 0,
+          is_standby_active: false,
+          standby_waiting_time: 60,
+        },
+        total_counters: {
+          power_ons: 278,
+          p1_working_time: 833,
+          p2_working_time: 15,
+          p3_working_time: 19,
+          p4_working_time: 8,
+          p5_working_time: 17,
+        },
+        service_counters: {
+          p1_working_time: 100,
+          p2_working_time: 10,
+          p3_working_time: 5,
+          p4_working_time: 2,
+          p5_working_time: 1,
+        },
+        alarms_log: {
+          number: 2,
+          index: 2,
+          alarms: [
+            { type: 3, timestamp: 1700000000 },
+            { type: 21, timestamp: 1700001000 },
+          ],
+        },
+        regeneration: {
+          time: 0,
+          last_intervention: 1577836800,
+          daylight_time_flag: 0,
+          blackout_counter: 43,
+          airkare_working_hours_counter: 0,
+        },
+      },
+    };
+
+    it("should calculate total operating hours", async () => {
+      fetchStub.resolves(mockResponse(mockDeviceInfoWithStats));
+      const api = configure(API_URL);
+      const result = await api.getTotalOperatingHours(
+        expectedToken,
+        "00:11:22:33:44:55",
+      );
+      // 833 + 15 + 19 + 8 + 17 = 892
+      assert.equal(result, 892);
+    });
+
+    it("should calculate power distribution percentages", async () => {
+      fetchStub.resolves(mockResponse(mockDeviceInfoWithStats));
+      const api = configure(API_URL);
+      const result = await api.getPowerDistribution(
+        expectedToken,
+        "00:11:22:33:44:55",
+      );
+      // Total: 892 hours
+      assert.ok(result.p1 > 90); // 833/892 = 93.4%
+      assert.ok(result.p2 < 5); // 15/892 = 1.7%
+      // Sum should be ~100%
+      const sum = result.p1 + result.p2 + result.p3 + result.p4 + result.p5;
+      assert.ok(Math.abs(sum - 100) < 0.1);
+    });
+
+    it("should handle zero operating hours in power distribution", async () => {
+      const zeroHoursInfo = {
+        ...mockDeviceInfoWithStats,
+        nvm: {
+          ...mockDeviceInfoWithStats.nvm,
+          total_counters: {
+            power_ons: 0,
+            p1_working_time: 0,
+            p2_working_time: 0,
+            p3_working_time: 0,
+            p4_working_time: 0,
+            p5_working_time: 0,
+          },
+        },
+      };
+      fetchStub.resolves(mockResponse(zeroHoursInfo));
+      const api = configure(API_URL);
+      const result = await api.getPowerDistribution(
+        expectedToken,
+        "00:11:22:33:44:55",
+      );
+      assert.deepEqual(result, { p1: 0, p2: 0, p3: 0, p4: 0, p5: 0 });
+    });
+
+    it("should calculate service status", async () => {
+      fetchStub.resolves(mockResponse(mockDeviceInfoWithStats));
+      const api = configure(API_URL);
+      const result = await api.getServiceStatus(
+        expectedToken,
+        "00:11:22:33:44:55",
+      );
+      assert.equal(result.totalServiceHours, 1108);
+      // 100 + 10 + 5 + 2 + 1 = 118 hours since service
+      assert.equal(result.hoursSinceService, 118);
+      assert.equal(result.isServiceDue, false); // 118 < 2000
+    });
+
+    it("should indicate service is due when threshold exceeded", async () => {
+      fetchStub.resolves(mockResponse(mockDeviceInfoWithStats));
+      const api = configure(API_URL);
+      // Use threshold of 100 hours
+      const result = await api.getServiceStatus(
+        expectedToken,
+        "00:11:22:33:44:55",
+        100,
+      );
+      assert.equal(result.isServiceDue, true); // 118 >= 100
+    });
+
+    it("should get comprehensive usage analytics", async () => {
+      fetchStub.resolves(mockResponse(mockDeviceInfoWithStats));
+      const api = configure(API_URL);
+      const result = await api.getUsageAnalytics(
+        expectedToken,
+        "00:11:22:33:44:55",
+      );
+
+      assert.equal(result.totalPowerOns, 278);
+      assert.equal(result.totalOperatingHours, 892);
+      assert.equal(result.blackoutCount, 43);
+      assert.equal(result.alarmCount, 2);
+      assert.ok(result.lastMaintenanceDate instanceof Date);
+      assert.equal(result.serviceStatus.isServiceDue, false);
+    });
+
+    it("should handle null lastMaintenanceDate when timestamp is 0", async () => {
+      const noMaintenanceInfo = {
+        ...mockDeviceInfoWithStats,
+        nvm: {
+          ...mockDeviceInfoWithStats.nvm,
+          regeneration: {
+            ...mockDeviceInfoWithStats.nvm.regeneration,
+            last_intervention: 0,
+          },
+        },
+      };
+      fetchStub.resolves(mockResponse(noMaintenanceInfo));
+      const api = configure(API_URL);
+      const result = await api.getUsageAnalytics(
+        expectedToken,
+        "00:11:22:33:44:55",
+      );
+      assert.equal(result.lastMaintenanceDate, null);
+    });
+  });
+
+  describe("deriveUsageAnalytics", () => {
+    const mockDeviceInfoForDerive = {
+      status: {
+        commands: {
+          power: false,
+        },
+        temperatures: {
+          enviroment: 20,
+          set_air: 21,
+          get_air: 20,
+          set_water: 40,
+          get_water: 35,
+        },
+        counters: {
+          service_time: 1108,
+        },
+        flags: {
+          is_pellet_in_reserve: false,
+        },
+        pellet: {
+          autonomy_time: 180,
+        },
+      },
+      nvm: {
+        user_parameters: {
+          language: 1,
+          is_auto: false,
+          is_fahrenheit: false,
+          is_sound_active: false,
+          enviroment_1_temperature: 19,
+          enviroment_2_temperature: 20,
+          enviroment_3_temperature: 20,
+          manual_power: 1,
+          fan_1_ventilation: 3,
+          fan_2_ventilation: 0,
+          fan_3_ventilation: 0,
+          is_standby_active: false,
+          standby_waiting_time: 60,
+        },
+        total_counters: {
+          power_ons: 278,
+          p1_working_time: 833,
+          p2_working_time: 15,
+          p3_working_time: 19,
+          p4_working_time: 8,
+          p5_working_time: 17,
+        },
+        service_counters: {
+          p1_working_time: 100,
+          p2_working_time: 10,
+          p3_working_time: 5,
+          p4_working_time: 2,
+          p5_working_time: 1,
+        },
+        regeneration: {
+          time: 0,
+          last_intervention: 1577836800,
+          daylight_time_flag: 0,
+          blackout_counter: 43,
+          airkare_working_hours_counter: 0,
+        },
+        alarms_log: {
+          number: 6,
+          index: 6,
+          alarms: [],
+        },
+      },
+    };
+
+    it("should derive analytics from device info without API call", () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const analytics = deriveUsageAnalytics(mockDeviceInfoForDerive as any);
+
+      assert.equal(analytics.totalPowerOns, 278);
+      assert.equal(analytics.totalOperatingHours, 892); // 833+15+19+8+17
+      assert.equal(analytics.blackoutCount, 43);
+      assert.equal(analytics.alarmCount, 6);
+    });
+
+    it("should calculate power distribution correctly", () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const analytics = deriveUsageAnalytics(mockDeviceInfoForDerive as any);
+
+      // P1: 833/892 ≈ 93.4%
+      assert.ok(analytics.powerDistribution.p1 > 93);
+      assert.ok(analytics.powerDistribution.p1 < 94);
+
+      // Sum should be 100%
+      const sum = Object.values(analytics.powerDistribution).reduce(
+        (a, b) => a + b,
+        0,
+      );
+      assert.ok(Math.abs(sum - 100) < 0.001);
+    });
+
+    it("should handle zero operating hours", () => {
+      const zeroHoursInfo = {
+        ...mockDeviceInfoForDerive,
+        nvm: {
+          ...mockDeviceInfoForDerive.nvm,
+          total_counters: {
+            power_ons: 0,
+            p1_working_time: 0,
+            p2_working_time: 0,
+            p3_working_time: 0,
+            p4_working_time: 0,
+            p5_working_time: 0,
+          },
+        },
+      };
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const analytics = deriveUsageAnalytics(zeroHoursInfo as any);
+      assert.deepEqual(analytics.powerDistribution, {
+        p1: 0,
+        p2: 0,
+        p3: 0,
+        p4: 0,
+        p5: 0,
+      });
+    });
+
+    it("should respect custom service threshold", () => {
+      const analytics = deriveUsageAnalytics(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        mockDeviceInfoForDerive as any,
+        100,
+      );
+
+      // 118 hours since service >= 100 threshold
+      assert.equal(analytics.serviceStatus.isServiceDue, true);
+      assert.equal(analytics.serviceStatus.serviceThresholdHours, 100);
+    });
+
+    it("should use default threshold of 2000 hours", () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const analytics = deriveUsageAnalytics(mockDeviceInfoForDerive as any);
+
+      assert.equal(analytics.serviceStatus.serviceThresholdHours, 2000);
+      assert.equal(analytics.serviceStatus.isServiceDue, false); // 118 < 2000
+    });
+
+    it("should convert last_intervention timestamp to Date", () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const analytics = deriveUsageAnalytics(mockDeviceInfoForDerive as any);
+
+      assert.ok(analytics.lastMaintenanceDate instanceof Date);
+      assert.equal(analytics.lastMaintenanceDate?.getTime(), 1577836800 * 1000);
+    });
+
+    it("should return null for lastMaintenanceDate when timestamp is 0", () => {
+      const noMaintenanceInfo = {
+        ...mockDeviceInfoForDerive,
+        nvm: {
+          ...mockDeviceInfoForDerive.nvm,
+          regeneration: {
+            ...mockDeviceInfoForDerive.nvm.regeneration,
+            last_intervention: 0,
+          },
+        },
+      };
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const analytics = deriveUsageAnalytics(noMaintenanceInfo as any);
+      assert.equal(analytics.lastMaintenanceDate, null);
+    });
+  });
+
   describe("Error Handling", () => {
     const errorTests = [
       { status: 400, statusText: "Bad Request" },