@homebridge-plugins/homebridge-august 3.3.0-beta.0 → 3.3.0-beta.1

package/.github/copilot-instructions.md

@@ -1,200 +0,0 @@
-# Copilot Instructions for Homebridge August Plugin
-
-## Repository Overview
-
-This repository is a Homebridge dynamic platform plugin for August and Yale locks.
-
-- Runtime uses TypeScript + ES modules.
-- The plugin supports a dual runtime path:
-  - HAP path via AugustPlatform.
-  - Matter path via AugustMatterPlatform when Homebridge Matter is available and enabled.
-
-## Current Architecture
-
-- Plugin type: dynamic platform plugin.
-- Entry point: src/index.ts.
-- HAP platform class: src/Platform.HAP.ts (AugustPlatform).
-- Matter platform class: src/Platform.Matter.ts (AugustMatterPlatform).
-- Shared device logic: src/devices/device.ts and src/devices/lock.ts.
-- Connectivity state machine: src/connectivity-manager.ts.
-- Config/types/constants: src/settings.ts.
-- UI backend/static assets: src/homebridge-ui/.
-
-The entry point in src/index.ts registers a proxy constructor that selects Matter or HAP at runtime based on:
-- api.isMatterAvailable()
-- api.isMatterEnabled()
-- config.options.disableMatter
-
-## Toolchain and Runtime
-
-Use the values from package.json and tsconfig.json as source of truth.
-
-- Node support: ^22 || ^24
-- Homebridge support: ^2.0.0
-- TypeScript target: ES2022
-- Module: ES2022
-- Module resolution: bundler
-- Strict mode: enabled (noImplicitAny is false)
-
-## Commands
-
-### Build and Packaging
-
-```bash
-npm run clean
-npm run build
-npm run prepublishOnly
-```
-
-### Lint
-
-```bash
-npm run lint
-npm run lint:fix
-```
-
-### Test
-
-```bash
-npm test
-npm run test:watch
-npm run test-coverage
-```
-
-### Docs
-
-```bash
-npm run docs
-npm run docs:lint
-```
-
-### Development
-
-```bash
-npm run watch
-npm run plugin-ui
-```
-
-## Branch and Release Workflow
-
-This repo follows a beta-first workflow.
-
-- Do not target main directly.
-- Target a beta branch named beta-X.Y.Z.
-- Use issue labels to determine bump type:
-  - patch
-  - minor
-  - major
-
-If no matching beta branch exists, create one from the next expected version.
-
-## Coding Expectations
-
-1. Keep imports as ES module paths ending in .js.
-2. Preserve Homebridge plugin constants:
-   - PLATFORM_NAME = August
-   - PLUGIN_NAME = homebridge-august
-3. Maintain backward compatibility unless issue scope is explicitly breaking.
-4. Keep runtime and schema aligned:
-   - Update src/settings.ts and config.schema.json together for option changes.
-5. Add or update Vitest coverage for behavior changes.
-6. Never commit generated output from dist/.
-
-## Homebridge and August/Yale Patterns
-
-- Use Homebridge DynamicPlatformPlugin patterns for lifecycle methods.
-- Use PlatformAccessory caching and proper unregister/update behavior.
-- Handle August auth and refresh flows defensively.
-- Respect polling and push/update intervals from options.
-- Prefer robust error classification and graceful retries over broad catch-and-ignore.
-
-## Matter and HomeKit Integration
-
-### Matter Implementation
-
-The plugin uses a dual-mode runtime that selects HAP or Matter at startup.
-
-- HAP mode (HomeKit Accessory Protocol): implemented by AugustPlatform in src/Platform.HAP.ts.
-- Matter mode: implemented by AugustMatterPlatform in src/Platform.Matter.ts.
-
-In src/index.ts, the platform proxy chooses AugustMatterPlatform only when Matter is available and enabled, and the user has not disabled Matter via config.options.disableMatter. Otherwise it falls back to AugustPlatform.
-
-### Matter Device Type Mapping
-
-Matter registrations use api.matter.deviceTypes.* and api.matter.types.* from Homebridge's Matter API.
-
-| August Device | HAP Service | Matter DeviceType | Matter Clusters |
-|---|---|---|---|
-| August/Yale lock | LockMechanism (plus optional ContactSensor in HAP mode) | DoorLock | doorLock |
-
-Notes:
-- AugustMatterPlatform currently maps lock accessories to Matter DoorLock.
-- Lock state updates are written through the doorLock cluster (for example lockState) and mirrored from August API polling/push updates.
-
-### Authoritative Matter References
-
-1. https://matter-js.github.io/docs/index.html
-2. https://github.com/homebridge-plugins/homebridge-matter
-
-For cluster, attribute, deviceType, and conversion details, use the homebridge-matter wiki:
-- Introduction: https://github.com/homebridge-plugins/homebridge-matter/wiki/Introduction
-- Core Concepts: https://github.com/homebridge-plugins/homebridge-matter/wiki/Core-Concepts
-- Getting Started: https://github.com/homebridge-plugins/homebridge-matter/wiki/Getting-Started
-- State Management: https://github.com/homebridge-plugins/homebridge-matter/wiki/State-Management
-- Monitoring External Changes: https://github.com/homebridge-plugins/homebridge-matter/wiki/Monitoring-External-Changes
-- Best Practices: https://github.com/homebridge-plugins/homebridge-matter/wiki/Best-Practices
-- Advanced Patterns: https://github.com/homebridge-plugins/homebridge-matter/wiki/Advanced-Patterns
-- API Reference: https://github.com/homebridge-plugins/homebridge-matter/wiki/API-Reference
-- Matter Types: https://github.com/homebridge-plugins/homebridge-matter/wiki/Matter-Types
-- Value Conversions: https://github.com/homebridge-plugins/homebridge-matter/wiki/Value-Conversions
-
-Device reference pages:
-- Sensors (Section 7): https://github.com/homebridge-plugins/homebridge-matter/wiki/Section-7-Sensors
-- Closure (Section 8): https://github.com/homebridge-plugins/homebridge-matter/wiki/Section-8-Closure
-
-## Testing Guidelines
-
-- Test files live under test/ with .test.ts suffix.
-- Mock external dependencies:
-  - august-yale
-  - file system
-  - Homebridge API surfaces
-- Cover:
-  - startup and discovery
-  - polling loops
-  - push/pull state sync
-  - Matter fallback behavior
-  - error paths and retries
-
-## Files to Avoid Editing Directly
-
-- dist/
-- node_modules/
-- docs/ generated output unless intentionally regenerating docs
-
-## Changelog Requirements
-
-When adding a release entry to CHANGELOG.md:
-
-1. Header format:
-
-```md
-## [X.Y.Z](https://github.com/homebridge-plugins/homebridge-august/releases/tag/vX.Y.Z) (YYYY-MM-DD)
-```
-
-2. Add sections as needed (for example Bug Fixes, Features, Documentation).
-
-3. Include a trailing full changelog comparison line:
-
-```md
-**Full Changelog**: https://github.com/homebridge-plugins/homebridge-august/compare/vX.Y.(Z-1)...vX.Y.Z
-```
-
-4. Ensure commit links point to this repository:
-- https://github.com/homebridge-plugins/homebridge-august/commit/<sha>
-
-## Security and Privacy
-
-- Never log secrets (passwords, tokens, validation codes).
-- Avoid exposing sensitive values in thrown errors.
-- Validate user-supplied config inputs before use.

package/.github/dependabot.yml

@@ -1,17 +0,0 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
-
-version: 2
-updates:
-  - package-ecosystem: 'npm' # See documentation for possible values
-    directory: '/' # Location of package manifests
-    target-branch: 'beta-*.*.*'
-    schedule:
-      interval: 'daily'
-  - package-ecosystem: 'github-actions' # See documentation for possible values
-    directory: '/' # Location of package manifests
-    target-branch: 'beta-*.*.*'
-    schedule:
-      interval: 'daily'

package/.github/labeler.yml

@@ -1,38 +0,0 @@
-# Add 'branding' label to any changes within 'docs' folder or any subfolders
-branding:
-- changed-files:
-  - any-glob-to-any-file: branding/**
-
-# Add 'docs' label to any change to .md files within the entire repository 
-docs:
-- changed-files:
-  - any-glob-to-any-file: '**/*.md'
-
-# Add 'enhancement' label to any change to src files within the source dir EXCEPT for the docs sub-folder
-enhancement:
-  - changed-files:
-    - any-glob-to-any-file: 'src/**/*'
-    - any-glob-to-any-file: 'config.schema.json'
-
-# Add 'dependencies' label to any change to src files within the source dir EXCEPT for the docs sub-folder
-dependencies:
-  - changed-files:
-    - any-glob-to-any-file: 'package.json'
-    - any-glob-to-any-file: 'package-lock.json'
-
-# Add 'beta' label to any PR that is opened against the `beta` branch
-beta:
-- base-branch: 'beta*'
-
-# Add 'alpha' label to any PR that is opened against the `alpha` branch
-alpha:
-- base-branch: 'alpha*'
-
-# Add 'latest' label to any PR that is opened against the `latest` branch
-latest:
-- base-branch: 'latest'
-
-# Add 'workflow' to any changes within 'workflow' folder or any subfolders
-workflow:
-- changed-files:
-  - any-glob-to-any-file: .github/**

package/.github/npm-version-script-esm.js

@@ -1,97 +0,0 @@
-#!/bin/env node
-
-/**
- * This scripts queries the npm registry to pull out the latest version for a given tag.
- */
-
-import assert from 'node:assert'
-import child_process from 'node:child_process'
-import fs from 'node:fs'
-import process from 'node:process'
-
-const BRANCH_VERSION_PATTERN = /^([A-Z]+)-(\d+\.\d+\.\d+)$/i
-
-// Load the contents of the package.json file
-const packageJSON = JSON.parse(fs.readFileSync('package.json', 'utf8'))
-
-const refArgument = process.argv[2]
-const tagArgument = process.argv[3] || 'latest'
-
-if (!refArgument) {
-  console.error('ref argument is missing')
-  console.error('Usage: npm-version-script-esm.js <ref> [tag]')
-  process.exit(1)
-}
-
-/**
- * Queries the NPM registry for the latest version for the provided base version and tag.
- * If the tag is latest, then the base version is returned if it exists. For other tags, the latest
- * version found for that base version and tag is returned.
- * @param baseVersion The base version to query for, e.g. 2.0.0
- * @param tag The tag to query for, e.g. beta or latest
- * @returns {string} Returns the version, or '' if not found
- */
-function getTagVersionFromNpm(baseVersion, tag) {
-  try {
-    return JSON.parse(child_process.execSync(`npm info ${packageJSON.name} versions --json`).toString('utf8').trim())
-      .filter(v => tag === 'latest' ? v === baseVersion : v.startsWith(`${baseVersion}-${tag}.`)) // find all published versions for this base version and tag
-      .reduce((_, current) => current, '') // choose the last as they're sorted in ascending order, or '' if there are none
-  } catch (e) {
-    console.error(`Failed to query the npm registry for the latest version for tag: ${tag}`, e)
-    // throw e;
-    return ''
-  }
-}
-
-function desiredTargetVersion(ref) {
-  // ref is a GitHub action ref string
-  if (ref.startsWith('refs/pull/')) {
-    throw new Error('The version script was executed inside a PR!')
-  }
-
-  assert(ref.startsWith('refs/heads/'))
-  const branchName = ref.slice('refs/heads/'.length)
-
-  const results = branchName.match(BRANCH_VERSION_PATTERN)
-  if (results !== null) {
-    if (results[1] !== tagArgument) {
-      console.warn(`The base branch name (${results[1]}) differs from the tag name ${tagArgument}`)
-    }
-
-    return results[2]
-  }
-
-  throw new Error(`Malformed branch name for ref: ${ref}. Can't derive the base version. Use a branch name like: beta-x.x.x or alpha-x.x.x`)
-}
-
-// derive the base version from the branch ref
-const baseVersion = desiredTargetVersion(refArgument)
-
-// query the npm registry for the latest version of the provided tag name
-const latestReleasedVersion = getTagVersionFromNpm(baseVersion, tagArgument) // e.g. 0.7.0-beta.12
-
-let publishTag
-
-if (latestReleasedVersion) {
-  console.warn(`Latest published version for ${baseVersion} with tag ${tagArgument} is ${latestReleasedVersion}`)
-  publishTag = latestReleasedVersion // set this released beta or alpha to be incremented
-} else {
-  console.warn(`No published versions for ${baseVersion} with tag ${tagArgument}`)
-  publishTag = baseVersion // start off with a new beta or alpha version
-}
-
-if (packageJSON.version !== publishTag) {
-  // report the change for CI
-  console.warn(`Changing version in package.json from ${packageJSON.version} to ${publishTag}`)
-
-  // save the package.json
-  packageJSON.version = publishTag
-  fs.writeFileSync('package.json', JSON.stringify(packageJSON, null, 2))
-
-  // perform the same change to the package-lock.json
-  const packageLockJSON = JSON.parse(fs.readFileSync('package-lock.json', 'utf8'))
-  packageLockJSON.version = publishTag
-  fs.writeFileSync('package-lock.json', JSON.stringify(packageLockJSON, null, 2))
-} else {
-  console.warn(`Leaving version in package.json at ${packageJSON.version}`)
-}

package/.github/workflows/release.yml

@@ -1,169 +0,0 @@
-name: Release
-
-on:
-  push:
-    branches:
-      - 'beta-*'
-      - 'beta'
-      - 'latest'
-  workflow_dispatch:
-    inputs:
-      release_type:
-        description: Release channel
-        required: true
-        type: choice
-        options:
-          - latest
-          - beta
-          - alpha
-        default: latest
-      is_esm:
-        description: Package is ESM
-        required: true
-        type: boolean
-        default: true
-      version_override:
-        description: Exact version (for example 2.1.0). Leave empty for auto bump.
-        required: false
-        type: string
-      version_bump:
-        description: Auto bump type when version_override is empty
-        required: false
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-        default: patch
-      max_attempts:
-        description: Max retries for prerelease collision handling
-        required: false
-        type: number
-        default: 5
-
-# Cancel any in-progress workflow for the same branch. A new push should
-# supersede the previous run rather than racing it to publish.
-concurrency:
-  group: release-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  # ─── QUALITY GATE (all branches) ────────────────────────────────────────────
-  # Build and test run for EVERY push, regardless of branch. Both the beta
-  # and stable release paths depend on these passing before anything is
-  # published or version-bumped.
-
-  # 1️⃣ Build and test
-  build_and_test:
-    uses: homebridge/.github/.github/workflows/nodejs-build-and-test.yml@latest
-    with:
-      enable_coverage: false
-    secrets:
-      token: ${{ secrets.GITHUB_TOKEN }}
-
-  # 2️⃣ Lint
-  lint:
-    needs: build_and_test
-    uses: homebridge/.github/.github/workflows/eslint.yml@latest
-
-
-  # ─── BETA RELEASE (branches starting with "beta") ────────────────────────────
-
-  # 3️⃣ Publish beta to NPM (OIDC — id-token required here and in the reusable workflow)
-  beta-publish:
-    if: startsWith(github.ref_name, 'beta')
-    needs: lint
-    permissions:
-      id-token: write
-    uses: homebridge/.github/.github/workflows/npm-publish-esm-oidc.yml@latest
-    with:
-      tag: 'beta'
-      dynamically_adjust_version: true
-      npm_version_command: 'pre'
-      pre_id: 'beta'
-
-  # 4️⃣ Create GitHub pre-release
-  beta-pre-release:
-    if: startsWith(github.ref_name, 'beta')
-    needs: beta-publish
-    uses: homebridge/.github/.github/workflows/pre-release.yml@latest
-    with:
-      npm_version: ${{ needs.beta-publish.outputs.NPM_VERSION }}
-      body: |
-        **Beta Release**
-        **Version**: v${{ needs.beta-publish.outputs.NPM_VERSION }}
-        [How To Test Beta Releases](https://github.com/homebridge-plugins/homebridge-august/wiki/Beta-Version)
-
-
-  # ─── STABLE RELEASE (branch: "latest") ───────────────────────────────────────
-
-  # 3️⃣ Determine release type, ESM status, and branch name
-  determine-release-type:
-    if: github.ref_name == 'latest'
-    needs: lint
-    uses: homebridge/.github/.github/workflows/determine-release-type.yml@latest
-    with:
-      ref_name: ${{ github.ref_name }}
-
-  # 4️⃣ Update version and changelog using the scripts
-  update-version:
-    if: github.ref_name == 'latest'
-    needs: determine-release-type
-    uses: homebridge/.github/.github/workflows/update-version.yml@latest
-    with:
-      release_type: ${{ needs.determine-release-type.outputs.release_type || inputs.release_type }}
-      is_esm: ${{ needs.determine-release-type.outputs.is_esm == 'true' || inputs.is_esm == 'true' }}
-      version_override: ${{ inputs.version_override }}
-      version_bump: ${{ inputs.version_bump }}
-
-  # 5️⃣ Publish to NPM and create GitHub release (OIDC — id-token required here and in the reusable workflow)
-  publish-release:
-    if: github.ref_name == 'latest'
-    needs: [determine-release-type, update-version]
-    permissions:
-      id-token: write
-      contents: write
-    uses: homebridge/.github/.github/workflows/publish-release.yml@latest
-    with:
-      release_type: ${{ needs.determine-release-type.outputs.release_type }}
-      version: ${{ needs.update-version.outputs.version }}
-      is_esm: ${{ needs.determine-release-type.outputs.is_esm == 'true' }}
-      version_override: ${{ inputs.version_override || '' }}
-      version_bump: ${{ inputs.version_bump || 'patch' }}
-      max_attempts: ${{ inputs.max_attempts || 5 }}
-    secrets:
-      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-  # 6️⃣ Promote branch if this is a prerelease (alpha/beta)
-  promote-branch:
-    if: ${{ github.ref_name == 'latest' && needs.determine-release-type.outputs.release_type != 'latest' && needs.determine-release-type.outputs.release_type != 'skip' }}
-    needs: [determine-release-type, publish-release]
-    uses: homebridge/.github/.github/workflows/promote-branch.yml@latest
-    with:
-      branch_name: ${{ needs.determine-release-type.outputs.branch_name }}
-      release_type: ${{ needs.determine-release-type.outputs.release_type }}
-      is_esm: ${{ needs.determine-release-type.outputs.is_esm == 'true' || inputs.is_esm == 'true' }}
-
-  # 7️⃣ Notify if any job fails
-  workflow-failure:
-    if: failure()
-    needs: [build_and_test, lint, determine-release-type, update-version, publish-release, promote-branch]
-    uses: homebridge/.github/.github/workflows/report-failure.yml@latest
-    with:
-      workflow_name: ${{ github.workflow }}
-      job_name: ${{ github.job }}
-      run_url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-
-  # 8️⃣ Post to Discord (Beta + Stable)
-  discord:
-    name: Release Notifications
-    if: ${{ always() && ((startsWith(github.ref_name, 'beta') && needs.beta-publish.result == 'success') || (github.ref_name == 'latest' && needs.publish-release.result == 'success')) }}
-    needs: [beta-publish, update-version, publish-release]
-    uses: homebridge/.github/.github/workflows/discord-webhooks.yml@latest
-    with:
-      title: ${{ startsWith(github.ref_name, 'beta') && 'Homebridge August Beta Release' || 'Homebridge August Release' }}
-      description: |
-        Version `v${{ startsWith(github.ref_name, 'beta') && needs.beta-publish.outputs.NPM_VERSION || needs.update-version.outputs.version }}`
-      url: "https://github.com/homebridge-plugins/homebridge-august/releases/tag/v${{ startsWith(github.ref_name, 'beta') && needs.beta-publish.outputs.NPM_VERSION || needs.update-version.outputs.version }}"
-    secrets:
-      DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK_URL_LATEST }}

package/.github/workflows/stale.yml

@@ -1,12 +0,0 @@
-name: Stale workflow
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: '45 11 * * *'
-
-jobs:
-  stale:
-    uses: homebridge/.github/.github/workflows/stale.yml@latest
-    secrets:
-      token: ${{ secrets.GITHUB_TOKEN }}

package/SECURITY.md

@@ -1,19 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-Use this section to tell people about which versions of your project are
-currently being supported with security updates.
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 1.0.0   | :white_check_mark: |
-| < 0.0.0 | :x:                |
-
-## Reporting a Vulnerability
-
-Use this section to tell people how to report a vulnerability.
-
-Tell them where to go, how often they can expect to get an update on a
-reported vulnerability, what to expect if the vulnerability is accepted or
-declined, etc.