yoto-nodejs-client 0.0.1 → 0.0.3

package/lib/helpers/power-state.js

@@ -0,0 +1,73 @@
+/**
+ * Power state detection helper for Yoto device status
+ *
+ * Analyzes shutdown field and uptime to determine device power state changes
+ */
+
+/**
+ * Power state detection result
+ * @typedef {Object} PowerStateResult
+ * @property {'running' | 'shutdown' | 'startup'} state - Device power state
+ * @property {string | null} shutDownReason - Shutdown reason if state is 'shutdown'
+ * @property {number | null} upTime - Device uptime in seconds if state is 'startup'
+ */
+
+/**
+ * Detect device power state from legacy status
+ *
+ * @param {string | null | undefined} shutDown - shutDown field from legacy status
+ * @param {number | null | undefined} upTime - upTime field from legacy status in seconds
+ * @returns {PowerStateResult}
+ *
+ * @example
+ * // Device running normally
+ * detectPowerState('nA', 3600)
+ * // { state: 'running', shutDownReason: null, upTime: null }
+ *
+ * @example
+ * // Device just started (low uptime)
+ * detectPowerState('nA', 45)
+ * // { state: 'startup', shutDownReason: null, upTime: 45 }
+ *
+ * @example
+ * // Device shutting down
+ * detectPowerState('userShutdown', 3600)
+ * // { state: 'shutdown', shutDownReason: 'userShutdown', upTime: null }
+ */
+export function detectPowerState (shutDown, upTime) {
+  // No shutdown field - assume running
+  if (shutDown == null) {
+    return {
+      state: 'running',
+      shutDownReason: null,
+      upTime: null
+    }
+  }
+
+  // shutDown: 'nA' means "not applicable" - device is running
+  if (shutDown === 'nA') {
+    // Low uptime indicates recent startup (< 2 minutes)
+    if (upTime != null && upTime < 120) {
+      return {
+        state: 'startup',
+        shutDownReason: null,
+        upTime
+      }
+    }
+
+    // Normal running state
+    return {
+      state: 'running',
+      shutDownReason: null,
+      upTime: null
+    }
+  }
+
+  // Any other value means device is shutting down or has shut down
+  // Examples: 'userShutdown', 'lowBattery', 'timeout', etc.
+  return {
+    state: 'shutdown',
+    shutDownReason: shutDown,
+    upTime: null
+  }
+}

package/lib/helpers/power-state.test.js

@@ -0,0 +1,100 @@
+import test from 'node:test'
+import assert from 'node:assert'
+import { detectPowerState } from './power-state.js'
+
+test('detectPowerState', async (t) => {
+  await t.test('should detect normal running state', () => {
+    const result = detectPowerState('nA', 3600)
+    assert.strictEqual(result.state, 'running')
+    assert.strictEqual(result.shutDownReason, null)
+    assert.strictEqual(result.upTime, null)
+  })
+
+  await t.test('should detect startup state with low uptime', () => {
+    const result = detectPowerState('nA', 45)
+    assert.strictEqual(result.state, 'startup')
+    assert.strictEqual(result.shutDownReason, null)
+    assert.strictEqual(result.upTime, 45)
+  })
+
+  await t.test('should detect startup at exactly 119 seconds', () => {
+    const result = detectPowerState('nA', 119)
+    assert.strictEqual(result.state, 'startup')
+    assert.strictEqual(result.upTime, 119)
+  })
+
+  await t.test('should detect running at exactly 120 seconds (threshold)', () => {
+    const result = detectPowerState('nA', 120)
+    assert.strictEqual(result.state, 'running')
+    assert.strictEqual(result.upTime, null)
+  })
+
+  await t.test('should detect user shutdown', () => {
+    const result = detectPowerState('userShutdown', 3600)
+    assert.strictEqual(result.state, 'shutdown')
+    assert.strictEqual(result.shutDownReason, 'userShutdown')
+    assert.strictEqual(result.upTime, null)
+  })
+
+  await t.test('should detect any non-nA value as shutdown', () => {
+    const testCases = [
+      'lowBattery',
+      'timeout',
+      'powerLoss',
+      'unknown',
+      'anyOtherValue'
+    ]
+
+    for (const shutDownValue of testCases) {
+      const result = detectPowerState(shutDownValue, 1000)
+      assert.strictEqual(result.state, 'shutdown')
+      assert.strictEqual(result.shutDownReason, shutDownValue)
+      assert.strictEqual(result.upTime, null)
+    }
+  })
+
+  await t.test('should handle null shutDown as running', () => {
+    const result = detectPowerState(null, 500)
+    assert.strictEqual(result.state, 'running')
+    assert.strictEqual(result.shutDownReason, null)
+    assert.strictEqual(result.upTime, null)
+  })
+
+  await t.test('should handle undefined shutDown as running', () => {
+    const result = detectPowerState(undefined, 500)
+    assert.strictEqual(result.state, 'running')
+    assert.strictEqual(result.shutDownReason, null)
+    assert.strictEqual(result.upTime, null)
+  })
+
+  await t.test('should handle null upTime with nA', () => {
+    const result = detectPowerState('nA', null)
+    assert.strictEqual(result.state, 'running')
+    assert.strictEqual(result.upTime, null)
+  })
+
+  await t.test('should handle undefined upTime with nA', () => {
+    const result = detectPowerState('nA', undefined)
+    assert.strictEqual(result.state, 'running')
+    assert.strictEqual(result.upTime, null)
+  })
+
+  await t.test('should detect startup with uptime 0', () => {
+    const result = detectPowerState('nA', 0)
+    assert.strictEqual(result.state, 'startup')
+    assert.strictEqual(result.upTime, 0)
+  })
+
+  await t.test('should detect startup with uptime 1', () => {
+    const result = detectPowerState('nA', 1)
+    assert.strictEqual(result.state, 'startup')
+    assert.strictEqual(result.upTime, 1)
+  })
+
+  await t.test('should ignore upTime when shutting down', () => {
+    const result = detectPowerState('userShutdown', 10)
+    assert.strictEqual(result.state, 'shutdown')
+    assert.strictEqual(result.shutDownReason, 'userShutdown')
+    assert.strictEqual(result.upTime, null)
+  })
+})

package/lib/helpers/temperature.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Temperature parsing helper for Yoto device status
+ *
+ * Temperature field format: colon-separated string where second value (index [1]) is temperature in Celsius
+ * Examples: '0:19' → 19°C, '12:20:23' → 20°C, '0:0' → 0°C, '0:unavailable' → null
+ * Plain string format: '19' → 19°C, '0' → 0°C
+ */
+/**
+ * Parse temperature from Yoto status message
+ *
+ * @param {string | number | null | undefined} tempValue - Temperature value from status message
+ * @returns {number | null} Temperature in Celsius, or null if unavailable/invalid
+ *
+ * @example
+ * parseTemperature('0:19')        // 19
+ * parseTemperature('12:20:23')    // 20
+ * parseTemperature('0:0')         // 0
+ * parseTemperature('0:unavailable') // null
+ * parseTemperature('0')           // 0
+ * parseTemperature('19')          // 19
+ * parseTemperature(null)          // null
+ */
+export function parseTemperature(tempValue: string | number | null | undefined): number | null;
+//# sourceMappingURL=temperature.d.ts.map

package/lib/helpers/temperature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temperature.d.ts","sourceRoot":"","sources":["temperature.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;GAcG;AACH,4CAZW,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAChC,MAAM,GAAG,IAAI,CAgDzB"}

package/lib/helpers/temperature.js

@@ -0,0 +1,61 @@
+/**
+ * Temperature parsing helper for Yoto device status
+ *
+ * Temperature field format: colon-separated string where second value (index [1]) is temperature in Celsius
+ * Examples: '0:19' → 19°C, '12:20:23' → 20°C, '0:0' → 0°C, '0:unavailable' → null
+ * Plain string format: '19' → 19°C, '0' → 0°C
+ */
+
+/**
+ * Parse temperature from Yoto status message
+ *
+ * @param {string | number | null | undefined} tempValue - Temperature value from status message
+ * @returns {number | null} Temperature in Celsius, or null if unavailable/invalid
+ *
+ * @example
+ * parseTemperature('0:19')        // 19
+ * parseTemperature('12:20:23')    // 20
+ * parseTemperature('0:0')         // 0
+ * parseTemperature('0:unavailable') // null
+ * parseTemperature('0')           // 0
+ * parseTemperature('19')          // 19
+ * parseTemperature(null)          // null
+ */
+export function parseTemperature (tempValue) {
+  // Handle null/undefined
+  if (tempValue == null) {
+    return null
+  }
+
+  // Convert to string
+  const tempStr = String(tempValue)
+
+  // Empty string
+  if (!tempStr) {
+    return null
+  }
+
+  // Colon-separated format (e.g., '0:19', '12:20:23', '0:unavailable')
+  if (tempStr.includes(':')) {
+    const parts = tempStr.split(':')
+    const secondValue = parts[1] ?? ''
+
+    // Parse second value as number
+    const parsed = parseFloat(secondValue)
+
+    // Return null if not a valid number (e.g., 'unavailable', 'notSupported')
+    if (isNaN(parsed)) {
+      return null
+    }
+
+    return parsed
+  }
+
+  // Fallback: try to parse as plain number (e.g., '19' or '0')
+  const parsed = parseFloat(tempStr)
+  if (isNaN(parsed)) {
+    return null
+  }
+
+  return parsed
+}

package/lib/helpers/temperature.test.js

@@ -0,0 +1,58 @@
+import test from 'node:test'
+import assert from 'node:assert'
+import { parseTemperature } from './temperature.js'
+
+test('parseTemperature', async (t) => {
+  await t.test('should parse standard two-part format', () => {
+    assert.strictEqual(parseTemperature('0:19'), 19)
+    assert.strictEqual(parseTemperature('0:25'), 25)
+    assert.strictEqual(parseTemperature('0:0'), 0)
+  })
+
+  await t.test('should parse three-part format using middle value', () => {
+    assert.strictEqual(parseTemperature('12:20:23'), 20)
+    assert.strictEqual(parseTemperature('10:15:20'), 15)
+    assert.strictEqual(parseTemperature('0:42:100'), 42)
+  })
+
+  await t.test('should return null for unavailable/unsupported', () => {
+    assert.strictEqual(parseTemperature('0:unavailable'), null)
+    assert.strictEqual(parseTemperature('0:notSupported'), null)
+    assert.strictEqual(parseTemperature('notSupported'), null)
+  })
+
+  await t.test('should handle null and undefined', () => {
+    assert.strictEqual(parseTemperature(null), null)
+    assert.strictEqual(parseTemperature(undefined), null)
+  })
+
+  await t.test('should handle empty string', () => {
+    assert.strictEqual(parseTemperature(''), null)
+  })
+
+  await t.test('should parse plain numbers as fallback', () => {
+    assert.strictEqual(parseTemperature('25'), 25)
+    assert.strictEqual(parseTemperature('0'), 0)
+    assert.strictEqual(parseTemperature(25), 25)
+    assert.strictEqual(parseTemperature(0), 0)
+  })
+
+  await t.test('should handle decimal temperatures', () => {
+    assert.strictEqual(parseTemperature('0:19.5'), 19.5)
+    assert.strictEqual(parseTemperature('12:20.75:23'), 20.75)
+    assert.strictEqual(parseTemperature('19.5'), 19.5)
+  })
+
+  await t.test('should handle negative temperatures', () => {
+    assert.strictEqual(parseTemperature('0:-5'), -5)
+    assert.strictEqual(parseTemperature('10:-2:15'), -2)
+    assert.strictEqual(parseTemperature('-5'), -5)
+  })
+
+  await t.test('should return null for invalid formats', () => {
+    assert.strictEqual(parseTemperature('invalid'), null)
+    assert.strictEqual(parseTemperature('abc:xyz'), null)
+    assert.strictEqual(parseTemperature(':'), null)
+    assert.strictEqual(parseTemperature('::'), null)
+  })
+})

package/lib/helpers/typed-keys.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @template {Record<PropertyKey, unknown>} T
+ * @param {T} obj
+ * @returns {(keyof T)[]}
+ */
+export function typedKeys<T extends Record<PropertyKey, unknown>>(obj: T): (keyof T)[];
+//# sourceMappingURL=typed-keys.d.ts.map

package/lib/helpers/typed-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-keys.d.ts","sourceRoot":"","sources":["typed-keys.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,0BAJ4C,CAAC,SAA/B,MAAM,CAAC,WAAW,EAAE,OAAO,CAAE,OAChC,CAAC,GACC,CAAC,MAAM,CAAC,CAAC,EAAE,CAIvB"}

package/lib/helpers/typed-keys.js

@@ -0,0 +1,8 @@
+/**
+ * @template {Record<PropertyKey, unknown>} T
+ * @param {T} obj
+ * @returns {(keyof T)[]}
+ */
+export function typedKeys (obj) {
+  return Object.keys(obj)
+}