feat(snmp): add configurable SNMP runtime units with v4.3 migration support

ts/snmp/manager.ts

@@ -357,7 +357,7 @@ export class NupstSnmp {
       const powerStatus = this.determinePowerStatus(config.upsModel, powerStatusValue);
 
       // Convert to minutes for UPS models with different time units
-      const processedRuntime = this.processRuntimeValue(config.upsModel, batteryRuntime);
+      const processedRuntime = this.processRuntimeValue(config, batteryRuntime);
 
       // Process power metrics with vendor-specific scaling
       const processedVoltage = this.processVoltageValue(config.upsModel, outputVoltage);
@@ -620,22 +620,46 @@ export class NupstSnmp {
   }
 
   /**
-   * Process runtime value based on UPS model
-   * @param upsModel UPS model
+   * Process runtime value based on config runtimeUnit or UPS model
+   * @param config SNMP configuration (uses runtimeUnit if set, otherwise falls back to upsModel)
    * @param batteryRuntime Raw battery runtime value
    * @returns Processed runtime in minutes
    */
   private processRuntimeValue(
-    upsModel: TUpsModel | undefined,
+    config: ISnmpConfig,
     batteryRuntime: number,
   ): number {
     if (this.debug) {
       logger.dim(`Raw runtime value: ${batteryRuntime}`);
     }
 
+    // Explicit runtimeUnit takes precedence over model-based detection
+    if (config.runtimeUnit) {
+      if (config.runtimeUnit === 'seconds' && batteryRuntime > 0) {
+        const minutes = Math.floor(batteryRuntime / 60);
+        if (this.debug) {
+          logger.dim(
+            `Converting runtime from ${batteryRuntime} seconds to ${minutes} minutes (runtimeUnit: seconds)`,
+          );
+        }
+        return minutes;
+      } else if (config.runtimeUnit === 'ticks' && batteryRuntime > 0) {
+        const minutes = Math.floor(batteryRuntime / 6000);
+        if (this.debug) {
+          logger.dim(
+            `Converting runtime from ${batteryRuntime} ticks to ${minutes} minutes (runtimeUnit: ticks)`,
+          );
+        }
+        return minutes;
+      }
+      // runtimeUnit === 'minutes' — return as-is
+      return batteryRuntime;
+    }
+
+    // Fallback: model-based detection (for configs without runtimeUnit)
+    const upsModel = config.upsModel;
     if (upsModel === 'cyberpower' && batteryRuntime > 0) {
-      // CyberPower: TimeTicks is in 1/100 seconds, convert to minutes
-      const minutes = Math.floor(batteryRuntime / 6000); // 6000 ticks = 1 minute
+      const minutes = Math.floor(batteryRuntime / 6000);
       if (this.debug) {
         logger.dim(
           `Converting CyberPower runtime from ${batteryRuntime} ticks to ${minutes} minutes`,
@@ -643,7 +667,6 @@ export class NupstSnmp {
       }
       return minutes;
     } else if (upsModel === 'eaton' && batteryRuntime > 0) {
-      // Eaton: Runtime is in seconds, convert to minutes
       const minutes = Math.floor(batteryRuntime / 60);
       if (this.debug) {
         logger.dim(
@@ -652,10 +675,9 @@ export class NupstSnmp {
       }
       return minutes;
     } else if (batteryRuntime > 10000) {
-      // Generic conversion for large tick values (likely TimeTicks)
       const minutes = Math.floor(batteryRuntime / 6000);
       if (this.debug) {
-        logger.dim(`Converting ${batteryRuntime} ticks to ${minutes} minutes`);
+        logger.dim(`Converting ${batteryRuntime} ticks to ${minutes} minutes (heuristic)`);
       }
       return minutes;
     }

ts/snmp/types.ts

@@ -58,6 +58,11 @@ export interface IOidSet {
  */
 export type TUpsModel = 'cyberpower' | 'apc' | 'eaton' | 'tripplite' | 'liebert' | 'custom';
 
+/**
+ * Runtime unit for battery runtime SNMP values
+ */
+export type TRuntimeUnit = 'minutes' | 'seconds' | 'ticks';
+
 /**
  * SNMP Configuration interface
  */
@@ -96,6 +101,8 @@ export interface ISnmpConfig {
   upsModel?: TUpsModel;
   /** Custom OIDs when using custom UPS model */
   customOIDs?: IOidSet;
+  /** Unit of the battery runtime SNMP value. Overrides model-based auto-detection when set. */
+  runtimeUnit?: TRuntimeUnit;
 }
 
 /**