homebridge-yoto 0.0.28 → 0.0.31

package/AGENTS.md

@@ -2,6 +2,8 @@
 
 This document contains patterns, conventions, and guidelines for developing the homebridge-yoto plugin.
 
+## Dont write summary markdown files unless asked to do so
+
 ## JSDoc Typing Patterns
 
 ### Use TypeScript-in-JavaScript (ts-in-js)
@@ -80,174 +82,57 @@ import { EventEmitter } from 'events';
 /** @import { API, PlatformAccessory } from 'homebridge' */
 ```
 
-### Homebridge Type Import Patterns
-
-Homebridge types are available from the `homebridge` package:
-
-```javascript
-/** @import { API, Characteristic, DynamicPlatformPlugin, Logger, PlatformAccessory, PlatformConfig, Service } from 'homebridge' */
-/** @import { CharacteristicValue } from 'homebridge' */
-```
-
-For HAP (HomeKit Accessory Protocol) types:
-
-```javascript
-/** @import { HAPStatus } from 'homebridge' */
-
-/**
- * @throws {import('homebridge').HapStatusError}
- */
-function throwNotResponding() {
-  throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
-}
-```
-
-### Prefer Schema-Based Types
-
-Define types for API responses and configuration objects using JSDoc typedef.
-
-```javascript
-/**
- * @typedef {Object} YotoDeviceStatus
- * @property {string} deviceId
- * @property {number} batteryLevelPercentage
- * @property {boolean} isCharging
- * @property {boolean} isOnline
- * @property {string | null} activeCard
- * @property {number} userVolumePercentage
- * @property {number} systemVolumePercentage
- * @property {number} temperatureCelcius
- * @property {number} wifiStrength
- * @property {0 | 1 | 2} cardInsertionState - 0=none, 1=physical, 2=remote
- * @property {-1 | 0 | 1} dayMode - -1=unknown, 0=night, 1=day
- * @property {0 | 1 | 2 | 3} powerSource - 0=battery, 1=V2 dock, 2=USB-C, 3=Qi
- */
-
-/**
- * @typedef {Object} YotoDevice
- * @property {string} deviceId
- * @property {string} name
- * @property {string} description
- * @property {boolean} online
- * @property {string} releaseChannel
- * @property {string} deviceType
- * @property {string} deviceFamily
- * @property {string} deviceGroup
- */
-
-/**
- * @typedef {Object} YotoDeviceConfig
- * @property {string} name
- * @property {YotoDeviceConfigSettings} config
- */
-
-/**
- * @typedef {Object} YotoDeviceConfigSettings
- * @property {any[]} alarms
- * @property {string} ambientColour
- * @property {string} bluetoothEnabled
- * @property {boolean} btHeadphonesEnabled
- * @property {string} clockFace
- * @property {string} dayDisplayBrightness
- * @property {string} dayTime
- * @property {string} maxVolumeLimit
- * @property {string} nightAmbientColour
- * @property {string} nightDisplayBrightness
- * @property {string} nightMaxVolumeLimit
- * @property {string} nightTime
- * @property {boolean} repeatAll
- * @property {string} shutdownTimeout
- * @property {string} volumeLevel
- */
-```
-
-### API Response Typing
+## Event Pattern Preference
 
-Type API responses explicitly:
+### Use Aggregate Events with Exhaustive Type Narrowing
 
-```javascript
-/**
- * @typedef {Object} YotoApiDevicesResponse
- * @property {YotoDevice[]} devices
- */
+The `yoto-nodejs-client` library should emit **only aggregate events** with `changedFields` arrays:
 
-/**
- * Get all devices for authenticated user
- * @returns {Promise<YotoDevice[]>}
- */
-async function getDevices() {
-  const response = await fetch('https://api.yotoplay.com/device-v2/devices/mine', {
-    headers: { 'Authorization': `Bearer ${this.accessToken}` }
-  });
-  
-  /** @type {YotoApiDevicesResponse} */
-  const data = await response.json();
-  return data.devices;
-}
-```
+- `statusUpdate` - passes `(status, source, changedFields[])`
+- `configUpdate` - passes `(config, changedFields[])`
+- `playbackUpdate` - passes `(playback, changedFields[])`
 
-### Platform Accessory Context Typing
+**Do NOT create granular field events** like `volumeChanged`, `batteryLevelChanged`, etc.
 
-Define the context object structure stored in accessories:
+### Homebridge Plugin Pattern
 
-```javascript
-/**
- * @typedef {Object} YotoAccessoryContext
- * @property {YotoDevice} device
- * @property {YotoDeviceStatus | null} lastStatus
- * @property {number} lastUpdate
- */
-
-/**
- * @param {PlatformAccessory<YotoAccessoryContext>} accessory
- */
-function configureAccessory(accessory) {
-  const device = accessory.context.device;
-  this.log.info('Restoring device:', device.name);
-}
-```
-
-### Nullable Fields in API Responses
-
-Use union types with `null` for fields that may be absent:
+The plugin should use exhaustive switch statements to handle field updates:
 
 ```javascript
-/**
- * @typedef {Object} YotoCardContent
- * @property {string} cardId
- * @property {string} title
- * @property {string | null} author
- * @property {string | null} description
- * @property {YotoChapter[] | null} chapters
- */
+this.deviceModel.on('statusUpdate', (status, source, changedFields) => {
+  for (const field of changedFields) {
+    switch (field) {
+      case 'volume':
+        // Update volume characteristic
+        break
+      
+      case 'batteryLevelPercentage':
+        // Update battery characteristic
+        break
+      
+      // ... handle all fields
+      
+      case 'firmwareVersion':
+        // Empty case - available but not used yet
+        break
+      
+      default: {
+        // Exhaustive check - TypeScript error if field missed
+        const _exhaustive: never = field
+        break
+      }
+    }
+  }
+})
 ```
 
-### Optional vs Nullable
-
-Distinguish between optional fields (may not exist) and nullable fields (exists but may be null):
-
-```javascript
-/**
- * @typedef {Object} YotoPlayerState
- * @property {string} deviceId - Always present
- * @property {string | null} activeCard - Present but may be null
- * @property {string} [lastPlayedCard] - May not be present in response
- */
-```
+**Benefits:**
+- Fewer event listeners (3 instead of 20+)
+- Exhaustive TypeScript checking ensures all fields handled
+- Empty cases document available fields
+- Easy to extend - just fill in empty cases
+- Type-safe with proper field typing
 
 ## Changelog Management
 
 **NEVER manually edit CHANGELOG.md**
-
-The changelog is automatically generated using `auto-changelog` during the version bump process:
-
-- When running `npm version [patch|minor|major]`, the `version:changelog` script runs automatically
-- It uses the keepachangelog template
-- Detects breaking changes via `BREAKING CHANGE:` pattern in commit messages
-- Generates entries from git commits
-
-To ensure proper changelog generation:
-- Write meaningful git commit messages
-- Use conventional commit format when possible
-- Mark breaking changes with `BREAKING CHANGE:` in commit body
-- Let the automation handle changelog updates during `npm version`

package/CHANGELOG.md

@@ -1,8 +1,16 @@
-# homebridge-yoto Change Log
+# Changelog
+
 All notable changes to this project will be documented in this file.
-This project adheres to [Semantic Versioning](http://semver.org/).
 
-## Unreleased
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
+
+## 0.0.31
+
+### Commits
 
-## 1.0.0 - {{date}}
-* ...
+- init [`88b35b6`](https://github.com/bcomnes/homebridge-yoto/commit/88b35b695166c6f5c3e3ec381c4afb52940a369b)
+- WIP [`cf0e5c8`](https://github.com/bcomnes/homebridge-yoto/commit/cf0e5c85df5984eb7fe10a2118de08990d875337)
+- Implement against client [`27d4fae`](https://github.com/bcomnes/homebridge-yoto/commit/27d4fae930a84f12a4671d3cd129c299505e398b)

package/NOTES.md

@@ -0,0 +1,87 @@
+Homebridge Notes

+http://bee.local:8581/login
+
+
+- Instance: https://homebridge.io
+- Homepage: https://homebridge.io
+- Plugin Docs: https://developers.homebridge.io/#/
+- Wiki: https://github.com/homebridge/homebridge/wiki
+- Homebridge package: https://github.com/homebridge/homebridge
+- Plugins Repo: https://github.com/homebridge/plugins
+- Plugin UI Utils: https://github.com/homebridge/plugin-ui-utils
+- HAP Client: https://github.com/homebridge/hap-client
+- HAP-NodeJS: https://github.com/homebridge/HAP-NodeJS
+- HAP-NodeJS JSDocs: https://developers.homebridge.io/HAP-NodeJS/modules.html
+- Old docs?: https://github.com/homebridge/documentation
+- PLugin Tempalte: https://github.com/homebridge/homebridge-plugin-template
+- Template lib helper thing: https://github.com/ebaauw/homebridge-lib 
+- Ring: https://github.com/homebridge-plugins/homebridge-meross/blob/9ea479ea94a8cfa8dce9051976fafb8308faae85/lib/platform.js#L1037
+- Scoped Plugins (Reference) https://github.com/homebridge/plugins/wiki/Scoped-Plugins#available-plugins
+- https://github.com/homebridge-plugins/homebridge-rainbird/blob/latest/src/platform.ts
+- https://github.com/homebridge-plugins/homebridge-unifi-network
+
+
+Yoto Docs:

+- https://yoto.dev/get-started/start-here/
+- https://yoto.dev/api/
+- https://yoto.space/developers
+- https://yoto.space/developers/post/home-assistant-integration-Ao9OxbsMDBqaG9I
+- https://github.com/yotoplay/examples
+- https://github.com/yotoplay/twine-to-yoto
+
+MQTT
+- MQTT: https://github.com/mqttjs/MQTT.js
+- https://mqtt.org
+- https://www.emqx.com/en/blog/the-easiest-guide-to-getting-started-with-mqtt
+- https://aws.amazon.com/what-is/mqtt/
+- https://en.wikipedia.org/wiki/MQTT
+-
+
+- https://github.com/ebaauw/homebridge-zp/issues/10#issuecomment-270743358
+
+
+- Implement a improved config type, and populate it.
+- Audit the set functions in hb, make sure the client works/helps with that. 
+- Clean up unused vars and config
+- Audit online/offline config set methods
+
+
+[12/26/2025, 4:05:52 PM] [homebridge-yoto] Device discovered: GGs Boombox (y29sZvOdk63vN50Qed5eH4Y0)
+[12/26/2025, 4:05:52 PM] [homebridge-yoto] Adding new accessory: GGs Boombox
+[12/26/2025, 4:05:52 PM] [homebridge-yoto] [Accessory] Setting up GGs Boombox
+[GGs Boombox@GGs Boombox@Status Active] Characteristic not in required or optional characteristic section for service SmartSpeaker. Adding anyway.
+[GGs Boombox@GGs Boombox Battery@Status Active] Characteristic not in required or optional characteristic section for service Battery. Adding anyway.
+[12/26/2025, 4:05:52 PM] [homebridge-yoto] [Accessory] ✓ GGs Boombox ready
+[12/26/2025, 4:05:52 PM] [homebridge-yoto] Publishing new external accessory: GGs Boombox
+[12/26/2025, 4:05:52 PM] GGs Boombox 55FC is running on port 45125.
+[12/26/2025, 4:05:52 PM] Please add [GGs Boombox 55FC] manually in Home app. Setup Code: 547-78-744
+[12/26/2025, 4:05:54 PM] [homebridge-yoto] Device discovered: Gigis mini (y2JVD5AxvJEeaK1g6nvBWkej)
+[12/26/2025, 4:05:54 PM] [homebridge-yoto] Adding new accessory: Gigis mini
+[12/26/2025, 4:05:54 PM] [homebridge-yoto] [Accessory] Setting up Gigis mini
+[Gigis mini@Gigis mini@Status Active] Characteristic not in required or optional characteristic section for service SmartSpeaker. Adding anyway.
+[Gigis mini@Gigis mini Battery@Status Active] Characteristic not in required or optional characteristic section for service Battery. Adding anyway.
+[12/26/2025, 4:05:54 PM] [homebridge-yoto] [Accessory] ✓ Gigis mini ready
+[12/26/2025, 4:05:54 PM] [homebridge-yoto] Publishing new external accessory: Gigis mini
+[12/26/2025, 4:05:54 PM] Gigis mini 8D02 is running on port 38987.
+[12/26/2025, 4:05:54 PM] Please add [Gigis mini 8D02] manually in Home app. Setup Code: 547-78-744
+[12/26/2025, 4:05:55 PM] [homebridge-yoto] Device discovered: Otto's mini  (y2iYT7ItkMRWbuMzTDuGjgmS)
+[12/26/2025, 4:05:55 PM] [homebridge-yoto] Adding new accessory: Otto's mini 
+[12/26/2025, 4:05:55 PM] [homebridge-yoto] [Accessory] Setting up Otto's mini 
+[Otto's mini @Otto's mini @Status Active] Characteristic not in required or optional characteristic section for service SmartSpeaker. Adding anyway.
+[Otto's mini @Otto's mini  Battery@Status Active] Characteristic not in required or optional characteristic section for service Battery. Adding anyway.
+[12/26/2025, 4:05:55 PM] [homebridge-yoto] [Accessory] ✓ Otto's mini  ready
+[12/26/2025, 4:05:55 PM] [homebridge-yoto] Publishing new external accessory: Otto's mini 
+[12/26/2025, 4:05:55 PM] Otto's mini  024E is running on port 33839.
+[12/26/2025, 4:05:55 PM] Please add [Otto's mini  024E] manually in Home app. Setup Code: 547-78-744
+[12/26/2025, 4:05:57 PM] [homebridge-yoto] Device discovered: Ottos Boombox (y2knTzvDkKVtvnhl09z9bWfe)
+[12/26/2025, 4:05:57 PM] [homebridge-yoto] Adding new accessory: Ottos Boombox
+[12/26/2025, 4:05:57 PM] [homebridge-yoto] [Accessory] Setting up Ottos Boombox
+[Ottos Boombox@Ottos Boombox@Status Active] Characteristic not in required or optional characteristic section for service SmartSpeaker. Adding anyway.
+[Ottos Boombox@Ottos Boombox Battery@Status Active] Characteristic not in required or optional characteristic section for service Battery. Adding anyway.
+[12/26/2025, 4:05:57 PM] [homebridge-yoto] [Accessory] ✓ Ottos Boombox ready
+[12/26/2025, 4:05:57 PM] [homebridge-yoto] Publishing new external accessory: Ottos Boombox
+[12/26/2025, 4:05:57 PM] [homebridge-yoto] ✓ Yoto account started with 4 device(s)
+[12/26/2025, 4:05:57 PM] Ottos Boombox 3486 is running on port 37845.
+[12/26/2025, 4:05:57 PM] Please add [Ottos Boombox 3486] manually in Home app. Setup Code: 547-78-744
+[12/26/2025, 4:05:59 PM] [homebridge-yoto] This plugin generated a warning from the characteristic 'Brightness': characteristic was supplied illegal value: number 255 exceeded maximum of 100. See https://homebridge.io/w/JtMGR for more info.
+[12/26/2025, 4:05:59 PM] [homebridge-yoto] This plugin generated a warning from the characteristic 'Brightness': characteristic was supplied illegal value: number 255 exceeded maximum of 100. See https://homebridge.io/w/JtMGR for more info.