homebridge-yoto 0.0.28 → 0.0.32

package/lib/sanitize-name.js

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Utility functions for the plugin
+ *
+ * Includes code adapted from `homebridge-plugin-utils`:
+ * - Source: https://github.com/hjdhjd/homebridge-plugin-utils/blob/main/src/util.ts
+ *
+ * ISC License
+ * ===========
+ *
+ * Copyright (c) 2017-2025, HJD https://github.com/hjdhjd
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any purpose
+ * with or without fee is hereby granted, provided that the above copyright notice
+ * and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+ * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+ * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+ * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+ * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+ * THIS SOFTWARE.
+ */
+
+/**
+ * Sanitize an accessory/service name according to HomeKit naming conventions.
+ *
+ * Starts and ends with a letter or number. Exception: may end with a period.
+ * May have the following special characters: -"',.#&.
+ * Must not include emojis.
+ *
+ * @param {string} name - The name to sanitize
+ * @returns {string} The HomeKit-sanitized version of the name
+ */
+export function sanitizeName (name) {
+  return name
+    // Replace any disallowed char (including emojis) with a space.
+    .replace(/[^\p{L}\p{N}\-"'.,#&\s]/gu, ' ')
+    // Collapse multiple spaces to one.
+    .replace(/\s+/g, ' ')
+    // Trim spaces at the beginning and end of the string.
+    .trim()
+    // Strip any leading non-letter/number.
+    .replace(/^[^\p{L}\p{N}]+/u, '')
+    // Collapse two or more trailing periods into one.
+    .replace(/\.{2,}$/g, '.')
+    // Remove any other trailing char that's not letter/number/period.
+    .replace(/[^\p{L}\p{N}.]$/u, '')
+}

package/lib/settings.js

@@ -0,0 +1,16 @@
+import { configSchema } from '../config.schema.cjs'
+
+/**
+ * This is the name of the platform that users will use to register the plugin in the Homebridge config.json
+ */
+export const PLATFORM_NAME = 'Yoto'
+
+/**
+ * This must match the name of your plugin as defined the package.json `name` property
+ */
+export const PLUGIN_NAME = 'homebridge-yoto'
+
+/**
+ * Default OAuth Client ID from config schema
+ */
+export const DEFAULT_CLIENT_ID = configSchema.schema.properties.clientId.default

package/lib/sync-service-names.js

@@ -0,0 +1,34 @@
+/** @import { Service, Characteristic } from 'homebridge' */
+import { sanitizeName } from './sanitize-name.js'
+
+/**
+ * Apply HomeKit-visible naming to a service.
+ *
+ * We set both `Name` and `ConfiguredName` on every service we manage so HomeKit tiles are consistently labeled.
+ *
+ * @param {object} params
+ * @param {Service} params.service
+ * @param {string} params.name
+ * @param {typeof Characteristic} params.Characteristic
+ * @returns {void}
+ */
+export function syncServiceNames ({
+  Characteristic,
+  service,
+  name
+}) {
+  const sanitizedName = sanitizeName(name)
+  service.displayName = sanitizedName
+
+  service.updateCharacteristic(Characteristic.Name, sanitizedName)
+
+  // Set ConfiguredName on all services, not just ones that say they support it.
+  // This is the only way to set the service name inside an accessory.
+  // const hasConfiguredNameCharacteristic = service.characteristics.some(c => c.UUID === Characteristic.ConfiguredName.UUID)
+  // const hasConfiguredNameOptional = service.optionalCharacteristics.some(c => c.UUID === Characteristic.ConfiguredName.UUID)
+  // if (!hasConfiguredNameCharacteristic && !hasConfiguredNameOptional) {
+  //   service.addOptionalCharacteristic(Characteristic.ConfiguredName)
+  // }
+
+  service.updateCharacteristic(Characteristic.ConfiguredName, sanitizedName)
+}

package/package.json

@@ -1,28 +1,30 @@
 {
   "name": "homebridge-yoto",
   "description": "Control your Yoto players through Apple HomeKit with real-time MQTT updates",
-  "version": "0.0.28",
+  "version": "0.0.32",
   "author": "Bret Comnes <bcomnes@gmail.com> (https://bret.io)",
   "bugs": {
     "url": "https://github.com/bcomnes/homebridge-yoto/issues"
   },
   "dependencies": {
-    "homebridge-lib": "^7.2.0",
-    "mqtt": "^5.14.1"
+    "@homebridge/plugin-ui-utils": "^2.1.2",
+    "color-convert": "3.1.3",
+    "yoto-nodejs-client": "^0.0.7"
   },
   "devDependencies": {
     "@types/node": "^25.0.0",
     "@voxpelli/tsconfig": "^16.1.0",
     "auto-changelog": "^2.0.0",
     "c8": "^10.0.0",
+    "eslint": "^9.39.2",
     "gh-release": "^7.0.0",
-    "homebridge": "^1.6.1",
+    "homebridge": "^2.0.0-beta.66",
     "neostandard": "^0.12.0",
     "npm-run-all2": "^8.0.1",
     "typescript": "~5.9.3"
   },
   "engines": {
-    "node": ">=20",
+    "node": ">=22",
     "npm": ">=10",
     "homebridge": "^1.8.0 || ^2.0.0-beta.0"
   },
@@ -36,26 +38,21 @@
   "module": "index.js",
   "main": "index.js",
   "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "index.d.ts.map",
+    "config.schema.json",
+    "config.schema.cjs",
+    "lib/",
+    "homebridge-ui/",
+    "README.md",
+    "LICENSE"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/bcomnes/homebridge-yoto.git"
   },
-  "scripts": {
-    "prepublishOnly": "npm run build && git push --follow-tags && gh-release -y",
-    "postpublish": "npm run clean",
-    "test": "run-s test:*",
-    "test:lint": "eslint",
-    "test:tsc": "tsc",
-    "test:node-test": "c8 node --test --test-reporter spec",
-    "version": "run-s version:*",
-    "version:changelog": "auto-changelog -p --template keepachangelog auto-changelog --breaking-pattern 'BREAKING CHANGE:'",
-    "version:git": "git add CHANGELOG.md",
-    "build": "npm run clean && run-p build:*",
-    "build:declaration": "tsc -p declaration.tsconfig.json",
-    "clean": "run-p clean:*",
-    "clean:declarations-top": "rm -rf $(find . -maxdepth 1 -type f -name '*.d.ts*')",
-    "clean:declarations-lib": "rm -rf $(find lib -type f -name '*.d.ts*' ! -name '*-types.d.ts')"
-  },
   "funding": {
     "type": "individual",
     "url": "https://github.com/sponsors/bcomnes"
@@ -65,5 +62,14 @@
       "lcov",
       "text"
     ]
+  },
+  "scripts": {
+    "test": "run-s test:*",
+    "test:lint": "eslint",
+    "test:tsc": "tsc",
+    "test:node-test": "c8 node --test --test-reporter spec",
+    "version": "run-s version:*",
+    "version:changelog": "auto-changelog -p --template keepachangelog auto-changelog --breaking-pattern 'BREAKING CHANGE:'",
+    "version:git": "git add CHANGELOG.md"
   }
-}
+}

package/.github/dependabot.yml

@@ -1,18 +0,0 @@
-# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
-version: 2
-updates:
-  - package-ecosystem: "npm"
-    directory: "/"
-    # Check the npm registry for updates every day (weekdays)
-    schedule:
-      interval: "daily"
-    groups:
-      typescript:
-        patterns:
-          - "typescript"
-          - "@types/node"
-          - "@voxpelli/tsconfig"
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "daily"

package/.github/funding.yml

@@ -1,4 +0,0 @@
-# These are supported funding model platforms
-
-github: ['bcomnes']
-custom: ['https://bret.io']

package/.github/workflows/release.yml

@@ -1,41 +0,0 @@
-name: npm bump
-
-on:
-  workflow_dispatch:
-    inputs:
-      newversion:
-        description: 'npm version {major,minor,patch}'
-        required: true
-
-env:
-  FORCE_COLOR: 1
-
-concurrency: # prevent concurrent releases
-  group: npm-bump
-  cancel-in-progress: true
-
-jobs:
-  version_and_release:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v6
-      with:
-        # fetch full history so things like auto-changelog work properly
-        fetch-depth: 0
-    - name: Use Node.js ${{ env.node }}
-      uses: actions/setup-node@v6
-      with:
-        node-version-file: package.json
-        # setting a registry enables the NODE_AUTH_TOKEN env variable where we can set an npm token.  REQUIRED
-        registry-url: 'https://registry.npmjs.org'
-    - run: npm i
-    - run: npm test
-    - name: npm version && npm publish
-      uses: bcomnes/npm-bump@v2
-      with:
-        git_email: bcomnes@gmail.com
-        git_username: ${{ github.actor }}
-        newversion: ${{ github.event.inputs.newversion }}
-        github_token: ${{ secrets.GITHUB_TOKEN }} # built in actions token.  Passed tp gh-release if in use.
-        npm_token: ${{ secrets.NPM_TOKEN }} # user set secret token generated at npm
-

package/.github/workflows/tests.yml

@@ -1,37 +0,0 @@
-name: tests
-
-on: [pull_request, push]
-
-env:
-  FORCE_COLOR: 1
-
-jobs:
-  test:
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest]
-        node: ['lts/*']
-
-    steps:
-    - uses: actions/checkout@v6
-    - name: Use Node.js ${{ matrix.node }}
-      uses: actions/setup-node@v6
-      with:
-        node-version: ${{ matrix.node }}
-    - run: npm i
-    - run: npm test --color=always
-
-  automerge:
-    needs: test
-    runs-on: ubuntu-latest
-    permissions:
-      pull-requests: write
-      contents: write
-    steps:
-      - uses: fastify/github-action-merge-dependabot@v3
-        if: ${{ github.actor == 'dependabot[bot]' && github.event_name == 'pull_request' && contains(github.head_ref, 'dependabot/github_actions') }}
-        with:
-          github-token: ${{secrets.github_token}}

package/AGENTS.md

@@ -1,253 +0,0 @@
-# Agent Development Notes
-
-This document contains patterns, conventions, and guidelines for developing the homebridge-yoto plugin.
-
-## JSDoc Typing Patterns
-
-### Use TypeScript-in-JavaScript (ts-in-js)
-
-All source files use `.js` extensions with JSDoc comments for type safety. This provides type checking without TypeScript compilation overhead.
-
-### Avoid `any` types
-
-Always provide specific types. Use `unknown` when the type is truly unknown, then narrow it with type guards.
-
-**Bad:**
-```javascript
-/**
- * @param {any} data
- */
-function processData(data) {
-  return data.value;
-}
-```
-
-**Good:**
-```javascript
-/**
- * @param {YotoDeviceStatus} status
- * @returns {number}
- */
-function getBatteryLevel(status) {
-  return status.batteryLevelPercentage;
-}
-```
-
-### Use @ts-expect-error over @ts-ignore
-
-When you must suppress a TypeScript error, use `@ts-expect-error` with a comment explaining why. This will error if the issue is fixed, prompting cleanup.
-
-**Bad:**
-```javascript
-// @ts-ignore
-const value = accessory.context.device.unknownProperty;
-```
-
-**Good:**
-```javascript
-// @ts-expect-error - API may return undefined for offline devices
-const lastSeen = accessory.context.device.lastSeenAt;
-```
-
-### Use newer @import syntax in jsdoc/ts-in-js for types only
-
-Import types using the `@import` JSDoc tag to avoid runtime imports of type-only dependencies.
-
-```javascript
-/** @import { API, DynamicPlatformPlugin, Logger, PlatformAccessory, PlatformConfig, Service, Characteristic } from 'homebridge' */
-/** @import { YotoDevice, YotoDeviceStatus, YotoDeviceConfig } from './types.js' */
-
-/**
- * @param {Logger} log
- * @param {PlatformConfig} config
- * @param {API} api
- */
-export function YotoPlatform(log, config, api) {
-  this.log = log;
-  this.config = config;
-  this.api = api;
-}
-```
-
-### Import Consolidation
-
-Keep regular imports and type imports separate. Use single-line imports for types when possible.
-
-```javascript
-import { EventEmitter } from 'events';
-
-/** @import { YotoDevice } from './types.js' */
-/** @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
-
-Type API responses explicitly:
-
-```javascript
-/**
- * @typedef {Object} YotoApiDevicesResponse
- * @property {YotoDevice[]} devices
- */
-
-/**
- * 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;
-}
-```
-
-### Platform Accessory Context Typing
-
-Define the context object structure stored in accessories:
-
-```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:
-
-```javascript
-/**
- * @typedef {Object} YotoCardContent
- * @property {string} cardId
- * @property {string} title
- * @property {string | null} author
- * @property {string | null} description
- * @property {YotoChapter[] | null} chapters
- */
-```
-
-### 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
- */
-```
-
-## 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 +0,0 @@
-# homebridge-yoto Change Log
-All notable changes to this project will be documented in this file.
-This project adheres to [Semantic Versioning](http://semver.org/).
-
-## Unreleased
-
-## 1.0.0 - {{date}}
-* ...

package/CONTRIBUTING.md

@@ -1,34 +0,0 @@
-# Contributing
-
-## Releasing
-
-Changelog and releasing are automated with npm scripts and actions. To create a release:
-
-- Navigate to the Actions tab.
-- Select the `npm bump` action.
-- Trigger the action, specifying the semantic version bump that is needed.
-- Changelog, GitHub release, and npm publish are handled by the action.
-- An in-depth review of this system is documented here: [bret.io/projects/package-automation](https://bret.io/projects/package-automation/).
-
-If for some reason this isn't working or a local release is preferred, follow these steps:
-
-- Ensure a clean working git workspace.
-- Run `npm version {patch, minor, major}`.
-  - This will update the version number and generate the changelog.
-- Run `npm publish`.
-  - This will push your local git branch and tags to the default remote, perform a [gh-release](https://ghub.io/gh-release), and create an npm publication.
-
-## Guidelines
-
-- Patches, ideas, and changes are welcome.
-- Fixes are almost always welcome.
-- Features are sometimes welcome.
-  - Please open an issue to discuss the idea prior to spending lots of time on the problem.
-  - It may be rejected.
-  - If you don't want to wait for the discussion to commence and you really want to jump into the implementation work, be prepared to fork the project if the idea is respectfully declined.
-- Try to stay within the style of the existing code.
-- All tests must pass.
-- Additional features or code paths must be tested.
-- Aim for 100% test coverage.
-- Questions are welcome. However, unless there is an official support contract established between the maintainers and the requester, support is not guaranteed.
-- Contributors reserve the right to walk away from this project at any moment, with or without notice.