edilkamin 1.10.0 → 1.10.1

package/src/library.test.ts

@@ -242,6 +242,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 +1028,285 @@ 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("Error Handling", () => {
     const errorTests = [
       { status: 400, statusText: "Bad Request" },

package/src/library.ts

@@ -6,11 +6,18 @@ import { cognitoUserPoolsTokenProvider } from "aws-amplify/auth/cognito";
 import { processResponse } from "./buffer-utils";
 import { API_URL } from "./constants";
 import {
+  AlarmsLogType,
   DeviceAssociationBody,
   DeviceAssociationResponse,
   DeviceInfoRawType,
   DeviceInfoType,
   EditDeviceAssociationBody,
+  PowerDistributionType,
+  RegenerationDataType,
+  ServiceCountersType,
+  ServiceStatusType,
+  TotalCountersType,
+  UsageAnalyticsType,
 } from "./types";
 
 /**
@@ -624,6 +631,246 @@ const getPelletAutonomyTime =
     return info.status.pellet.autonomy_time;
   };
 
+const getTotalCounters =
+  (baseURL: string) =>
+  /**
+   * Retrieves lifetime operating counters.
+   * Includes power-on count and runtime hours per power level.
+   * These counters are never reset.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<TotalCountersType>} - Lifetime operating statistics.
+   */
+  async (jwtToken: string, macAddress: string): Promise<TotalCountersType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.nvm.total_counters;
+  };
+
+const getServiceCounters =
+  (baseURL: string) =>
+  /**
+   * Retrieves service counters (runtime since last maintenance).
+   * These counters track hours per power level since last service reset.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<ServiceCountersType>} - Service tracking statistics.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+  ): Promise<ServiceCountersType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.nvm.service_counters;
+  };
+
+const getAlarmHistory =
+  (baseURL: string) =>
+  /**
+   * Retrieves the alarm history log.
+   * Contains a circular buffer of recent alarms with timestamps.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<AlarmsLogType>} - Alarm history log.
+   */
+  async (jwtToken: string, macAddress: string): Promise<AlarmsLogType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.nvm.alarms_log;
+  };
+
+const getRegenerationData =
+  (baseURL: string) =>
+  /**
+   * Retrieves regeneration and maintenance data.
+   * Includes blackout counter and last intervention timestamp.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<RegenerationDataType>} - Maintenance tracking data.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+  ): Promise<RegenerationDataType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.nvm.regeneration;
+  };
+
+const getServiceTime =
+  (baseURL: string) =>
+  /**
+   * Retrieves the total service time in hours.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<number>} - Total service hours.
+   */
+  async (jwtToken: string, macAddress: string): Promise<number> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    return info.status.counters.service_time;
+  };
+
+/**
+ * Default service threshold in hours (from OEM parameters).
+ * Most devices use 2000 hours.
+ */
+const DEFAULT_SERVICE_THRESHOLD = 2000;
+
+const getTotalOperatingHours =
+  (baseURL: string) =>
+  /**
+   * Calculates total operating hours across all power levels.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<number>} - Total operating hours.
+   */
+  async (jwtToken: string, macAddress: string): Promise<number> => {
+    const counters = await getTotalCounters(baseURL)(jwtToken, macAddress);
+    return (
+      counters.p1_working_time +
+      counters.p2_working_time +
+      counters.p3_working_time +
+      counters.p4_working_time +
+      counters.p5_working_time
+    );
+  };
+
+const getPowerDistribution =
+  (baseURL: string) =>
+  /**
+   * Calculates power level usage distribution as percentages.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @returns {Promise<PowerDistributionType>} - Percentage time at each power level.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+  ): Promise<PowerDistributionType> => {
+    const counters = await getTotalCounters(baseURL)(jwtToken, macAddress);
+    const total =
+      counters.p1_working_time +
+      counters.p2_working_time +
+      counters.p3_working_time +
+      counters.p4_working_time +
+      counters.p5_working_time;
+
+    if (total === 0) {
+      return { p1: 0, p2: 0, p3: 0, p4: 0, p5: 0 };
+    }
+
+    return {
+      p1: (counters.p1_working_time / total) * 100,
+      p2: (counters.p2_working_time / total) * 100,
+      p3: (counters.p3_working_time / total) * 100,
+      p4: (counters.p4_working_time / total) * 100,
+      p5: (counters.p5_working_time / total) * 100,
+    };
+  };
+
+const getServiceStatus =
+  (baseURL: string) =>
+  /**
+   * Calculates service status including whether maintenance is due.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @param {number} [thresholdHours=2000] - Service threshold in hours.
+   * @returns {Promise<ServiceStatusType>} - Service status with computed fields.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+    thresholdHours: number = DEFAULT_SERVICE_THRESHOLD,
+  ): Promise<ServiceStatusType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+    const serviceCounters = info.nvm.service_counters;
+    const hoursSinceService =
+      serviceCounters.p1_working_time +
+      serviceCounters.p2_working_time +
+      serviceCounters.p3_working_time +
+      serviceCounters.p4_working_time +
+      serviceCounters.p5_working_time;
+
+    return {
+      totalServiceHours: info.status.counters.service_time,
+      hoursSinceService,
+      serviceThresholdHours: thresholdHours,
+      isServiceDue: hoursSinceService >= thresholdHours,
+    };
+  };
+
+const getUsageAnalytics =
+  (baseURL: string) =>
+  /**
+   * Retrieves comprehensive usage analytics in a single call.
+   * Combines multiple statistics into a unified analytics object.
+   *
+   * @param {string} jwtToken - The JWT token for authentication.
+   * @param {string} macAddress - The MAC address of the device.
+   * @param {number} [serviceThreshold=2000] - Service threshold in hours.
+   * @returns {Promise<UsageAnalyticsType>} - Comprehensive usage analytics.
+   */
+  async (
+    jwtToken: string,
+    macAddress: string,
+    serviceThreshold: number = DEFAULT_SERVICE_THRESHOLD,
+  ): Promise<UsageAnalyticsType> => {
+    const info = await deviceInfo(baseURL)(jwtToken, macAddress);
+
+    const totalCounters = info.nvm.total_counters;
+    const serviceCounters = info.nvm.service_counters;
+    const regeneration = info.nvm.regeneration;
+    const alarmsLog = info.nvm.alarms_log;
+
+    const totalOperatingHours =
+      totalCounters.p1_working_time +
+      totalCounters.p2_working_time +
+      totalCounters.p3_working_time +
+      totalCounters.p4_working_time +
+      totalCounters.p5_working_time;
+
+    const hoursSinceService =
+      serviceCounters.p1_working_time +
+      serviceCounters.p2_working_time +
+      serviceCounters.p3_working_time +
+      serviceCounters.p4_working_time +
+      serviceCounters.p5_working_time;
+
+    const powerDistribution: PowerDistributionType =
+      totalOperatingHours === 0
+        ? { p1: 0, p2: 0, p3: 0, p4: 0, p5: 0 }
+        : {
+            p1: (totalCounters.p1_working_time / totalOperatingHours) * 100,
+            p2: (totalCounters.p2_working_time / totalOperatingHours) * 100,
+            p3: (totalCounters.p3_working_time / totalOperatingHours) * 100,
+            p4: (totalCounters.p4_working_time / totalOperatingHours) * 100,
+            p5: (totalCounters.p5_working_time / totalOperatingHours) * 100,
+          };
+
+    return {
+      totalPowerOns: totalCounters.power_ons,
+      totalOperatingHours,
+      powerDistribution,
+      serviceStatus: {
+        totalServiceHours: info.status.counters.service_time,
+        hoursSinceService,
+        serviceThresholdHours: serviceThreshold,
+        isServiceDue: hoursSinceService >= serviceThreshold,
+      },
+      blackoutCount: regeneration.blackout_counter,
+      lastMaintenanceDate:
+        regeneration.last_intervention > 0
+          ? new Date(regeneration.last_intervention * 1000)
+          : null,
+      alarmCount: alarmsLog.number,
+    };
+  };
+
 const registerDevice =
   (baseURL: string) =>
   /**
@@ -748,6 +995,17 @@ const configure = (baseURL: string = API_URL) => ({
   getLanguage: getLanguage(baseURL),
   getPelletInReserve: getPelletInReserve(baseURL),
   getPelletAutonomyTime: getPelletAutonomyTime(baseURL),
+  // Statistics getters
+  getTotalCounters: getTotalCounters(baseURL),
+  getServiceCounters: getServiceCounters(baseURL),
+  getAlarmHistory: getAlarmHistory(baseURL),
+  getRegenerationData: getRegenerationData(baseURL),
+  getServiceTime: getServiceTime(baseURL),
+  // Analytics functions
+  getTotalOperatingHours: getTotalOperatingHours(baseURL),
+  getPowerDistribution: getPowerDistribution(baseURL),
+  getServiceStatus: getServiceStatus(baseURL),
+  getUsageAnalytics: getUsageAnalytics(baseURL),
 });
 
 export {