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

package/.github/copilot-instructions.md

@@ -0,0 +1,200 @@
+# 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/npm-version-script-esm.js

@@ -0,0 +1,97 @@
+#!/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/CHANGELOG.md

@@ -1,30 +1,57 @@
-## [3.2.1](https://github.com/homebridge-plugins/homebridge-august/compare/v3.2.0...v3.2.1) (2026-04-30)
+## [3.3.0](https://github.com/homebridge-plugins/homebridge-august/releases/tag/v3.3.0) (2026-05-09)
 
 
+### Features
+
+- Major refactor: Introduced a new shared Base Platform architecture for HAP (HomeKit) and Matter platforms, improving reliability and maintainability.
+- Improved lock/device management and connectivity handling for both HAP and Matter modes.
+
+### Other Changes
+
+- Internal codebase cleanup and test reorganization.
+- Removed legacy scripts and reduced code duplication.
+
+**Full Changelog**: https://github.com/homebridge-plugins/homebridge-august/compare/v3.2.3...v3.3.0
+
+## [3.2.3](https://github.com/homebridge-plugins/homebridge-august/releases/tag/v3.2.3) (2026-05-04)
+
 ### Bug Fixes
 
-* **platform:** probe with a fresh client; add offline heartbeat ([682c68b](https://github.com/homebridge-plugins/homebridge-august/commit/682c68bcbd7d86fb9df350ab0ccac9a07d3e1e2b))
-* **platform:** use August.resetTransport() for connectivity recovery ([6ea4f34](https://github.com/homebridge-plugins/homebridge-august/commit/6ea4f34cb710cbff333e71d84b048bb61d34ea64))
+* **platform:** align platform filename/import casing for ESM paths on case-sensitive systems ([974768a](https://github.com/homebridge-plugins/homebridge-august/commit/974768a6c2de6a5682b1d06e60f62bcbc7933841))
 
+**Full Changelog**: https://github.com/homebridge-plugins/homebridge-august/compare/v3.2.2...v3.2.3
+
+## [3.2.2](https://github.com/homebridge-plugins/homebridge-august/releases/tag/v3.2.2) (2026-05-03)
+
+### Bug Fixes
 
+* bump package.json deps ([60b5cf2](https://github.com/homebridge-plugins/homebridge-august/commit/60b5cf2032b9f5da9089019b8ca22b1fcdfd9e05))
 
-# [3.2.0](https://github.com/homebridge-plugins/homebridge-august/compare/v3.1.4...v3.2.0) (2026-04-29)
+**Full Changelog**: https://github.com/homebridge-plugins/homebridge-august/compare/v3.2.1...v3.2.2
 
+## [3.2.1](https://github.com/homebridge-plugins/homebridge-august/releases/tag/v3.2.1) (2026-04-30)
 
 ### Bug Fixes
 
-* **platform:** use august-yale's typed exceptions for error classification ([93219ac](https://github.com/homebridge-plugins/homebridge-august/commit/93219accdf8571330b8f3fefa029d727ddf7a6c3))
+* **platform:** probe with a fresh client; add offline heartbeat ([682c68b](https://github.com/homebridge-plugins/homebridge-august/commit/682c68bcbd7d86fb9df350ab0ccac9a07d3e1e2b))
+* **platform:** use August.resetTransport() for connectivity recovery ([6ea4f34](https://github.com/homebridge-plugins/homebridge-august/commit/6ea4f34cb710cbff333e71d84b048bb61d34ea64))
 
+**Full Changelog**: https://github.com/homebridge-plugins/homebridge-august/compare/v3.2.0...v3.2.1
+
+# [3.2.0](https://github.com/homebridge-plugins/homebridge-august/releases/tag/v3.2.0) (2026-04-29)
+
+### Bug Fixes
 
+* **platform:** use august-yale's typed exceptions for error classification ([93219ac](https://github.com/homebridge-plugins/homebridge-august/commit/93219accdf8571330b8f3fefa029d727ddf7a6c3))
 
-## [3.1.4](https://github.com/homebridge-plugins/homebridge-august/compare/v3.1.3...v3.1.4) (2026-04-27)
+**Full Changelog**: https://github.com/homebridge-plugins/homebridge-august/compare/v3.1.4...v3.2.0
 
+## [3.1.4](https://github.com/homebridge-plugins/homebridge-august/releases/tag/v3.1.4) (2026-04-27)
 
 ### Bug Fixes
 
 * **platform:** destroy August client on session refresh instead of end() ([a12f2b3](https://github.com/homebridge-plugins/homebridge-august/commit/a12f2b328263523eef3b2549383f00ce6dfbf0a1))
 
-
 ### Features
 
 * **lock:** wire PubNub reconnect signal into ConnectivityManager ([462b22c](https://github.com/homebridge-plugins/homebridge-august/commit/462b22c5b53e125d3ec31eceea538a74360f5760))
@@ -33,9 +60,17 @@
 * **platform:** route pushChanges through ConnectivityManager ([41080f4](https://github.com/homebridge-plugins/homebridge-august/commit/41080f490cd71b504e22f56a80ae6e1c8c9eb016))
 * **platform:** wire ConnectivityManager into AugustPlatform ([0ce28e3](https://github.com/homebridge-plugins/homebridge-august/commit/0ce28e359a68720ed278e17097f61262ea8705b4))
 
+**Full Changelog**: https://github.com/homebridge-plugins/homebridge-august/compare/v3.1.3...v3.1.4
+
+## [3.1.3](https://github.com/homebridge-plugins/homebridge-august/releases/tag/v3.1.3) (2026-04-18)
+
+### Bug Fixes
+
+* update dependencies ([ed90943](https://github.com/homebridge-plugins/homebridge-august/commit/ed9094358ab9ec6f724df58c1d98d38cee7db751))
 
+**Full Changelog**: https://github.com/homebridge-plugins/homebridge-august/compare/v3.1.2...v3.1.3
 
-## [3.1.2](https://github.com/homebridge-plugins/homebridge-august/compare/v3.1.1...v3.1.2) (2026-04-18)
+## [3.1.2](https://github.com/homebridge-plugins/homebridge-august/releases/tag/v3.1.2) (2026-04-18)
 
 ### Bug Fixes
 
@@ -44,7 +79,7 @@
 
 **Full Changelog**: https://github.com/homebridge-plugins/homebridge-august/compare/v3.1.1...v3.1.2
 
-## [3.1.1](https://github.com/homebridge-plugins/homebridge-august/compare/v3.1.0...v3.1.1) (2026-04-16)
+## [3.1.1](https://github.com/homebridge-plugins/homebridge-august/releases/tag/v3.1.1) (2026-04-16)
 
 ### Bug Fixes
 

package/dist/Platform.Base.d.ts

@@ -0,0 +1,288 @@
+import type { API, DynamicPlatformPlugin, Logging, PlatformAccessory } from 'homebridge';
+import type { AugustPlatformConfig, credentials, device, devicesConfig, options } from './settings.js';
+import { PluginLogger } from '@homebridge/plugin-logger';
+import August from 'august-yale';
+import { ConnectivityManager } from './connectivity-manager.js';
+/**
+ * Base platform class for August/Yale Homebridge plugin.
+ * Contains all shared logic for config, credentials, device discovery, polling, etc.
+ * Protocol-specific logic (HAP/Matter) should be implemented in subclasses.
+ */
+export declare class AugustPlatformBase implements DynamicPlatformPlugin {
+    /**
+     * Subscribes to PubNub push updates for a given lockId.
+     * Stores unsubscribe/teardown functions in the lockMechanisms map for unified cleanup.
+     * Calls the provided event handler on push events.
+     *
+     * @param {string} lockId - The lock ID to subscribe to.
+     * @param {(event: any, timestamp: Date) => Promise<void>} onEvent - Handler for push events.
+     * @param {(status: any) => void} [onStatus] - Optional handler for PubNub status events.
+     * @returns {Promise<void>}
+     */
+    subscribePubNub(lockId: string, onEvent: (event: any, timestamp: Date) => Promise<void>, onStatus?: (status: any) => void): Promise<void>;
+    /**
+     * Tears down the PubNub subscription for a given lockId (if present).
+     * Safe to call multiple times.
+     * @param {string} lockId
+     */
+    tearDownPubNubSubscription(lockId: string): void;
+    accessories: PlatformAccessory[];
+    readonly api: API;
+    readonly log: Logging;
+    config: AugustPlatformConfig;
+    platformConfig: AugustPlatformConfig;
+    platformLogging: options['logging'];
+    platformRefreshRate: options['refreshRate'];
+    platformPushRate: options['pushRate'];
+    platformUpdateRate: options['updateRate'];
+    registeringDevice: boolean;
+    debugMode: boolean;
+    version: string;
+    augustConfig?: August;
+    connectivity?: ConnectivityManager;
+    protected readonly lockMechanisms: Map<string, any>;
+    protected pollTimer?: NodeJS.Timeout;
+    protected normalizedCredentialsCache?: credentials;
+    logger: PluginLogger;
+    constructor(log: Logging, config: AugustPlatformConfig, api: API);
+    Lock(device: any): Promise<void>;
+    /**
+     * Tears down resources for a lock mechanism, including PubNub subscriptions and polling if present.
+     *
+     * Removes the lock mechanism from the internal map and calls tearDownPubNubSubscription if implemented.
+     * Used by both HAP and Matter platforms. Lock mechanisms must implement tearDownPubNubSubscription for proper cleanup.
+     *
+     * @param {string} lockId - The lock ID whose mechanism should be torn down.
+     * @returns {void}
+     */
+    protected tearDownLockMechanism(lockId: string): void;
+    /**
+     * Handles restoration of cached accessories from disk during Homebridge startup.
+     *
+     * Called by Homebridge for each accessory previously registered and persisted in the cache.
+     * Adds the accessory to the platform's accessories array for tracking and future management.
+     * Subclasses should override this method to set up event handlers and update characteristic values as needed.
+     *
+     * @param {PlatformAccessory} accessory - The accessory instance restored from cache.
+     * @returns {Promise<void>} Resolves when the accessory is processed and added to the cache.
+     */
+    configureAccessory(accessory: PlatformAccessory): Promise<void>;
+    /**
+     * Verifies that the plugin configuration contains all required credentials.
+     *
+     * Checks for the presence of credentials, August ID, and password. Throws descriptive errors
+     * if any required field is missing. Should be called during initialization to ensure the platform
+     * is properly configured before proceeding with authentication or device discovery.
+     *
+     * @returns {Promise<void>} Resolves if the configuration is valid.
+     * @throws {Error} If credentials, August ID, or password are missing.
+     */
+    verifyConfig(): Promise<void>;
+    /**
+     * Validates the August credentials and manages the Homebridge config state for authentication.
+     *
+     * - If the session is not validated and a validateCode is present, attempts to validate with the code,
+     *   updates the config, and clears the validateCode on success.
+     * - If already validated or no validateCode is present, ensures installId is set and prompts the user
+     *   to enter the verification code if needed.
+     * - Always updates the config file and clears the normalized credentials cache after changes.
+     * - Handles device discovery after successful validation.
+     *
+     * @returns {Promise<void>} Resolves when validation and config updates are complete.
+     * @throws {Error} If credentials are missing or validation fails unexpectedly.
+     */
+    validated(): Promise<void>;
+    /**
+     * Initializes and manages the August API credentials and connectivity manager.
+     *
+     * Ensures credentials are present, initializes the ConnectivityManager if needed,
+     * and keeps the public augustConfig field in sync with the manager's internal client.
+     * If already initialized, skips re-initialization. Handles automatic client rebuilds
+     * on authentication failures and network recovery.
+     *
+     * @returns {Promise<void>} Resolves when credentials and connectivity are initialized.
+     * @throws {Error} If credentials are missing.
+     */
+    augustCredentials(): Promise<void>;
+    /**
+     * Normalizes credentials for August API compatibility, handling country code variations.
+     *
+     * Maps regional country codes (e.g., CA, MX) to supported API endpoints (US) unless normalization is disabled in config.
+     * Logs normalization actions for debugging and API compatibility.
+     *
+     * @param {credentials} credentials - The credentials object to normalize.
+     * @returns {Promise<credentials>} Resolves with the normalized credentials object.
+     * @throws {Error} If credentials are null or undefined.
+     */
+    private normalizeCredentialsForApi;
+    /**
+     * Clears the cached normalized credentials.
+     *
+     * Should be called whenever credentials are updated or invalidated to ensure
+     * that subsequent API calls use fresh, normalized credentials.
+     * Logs the cache clear operation for debugging.
+     *
+     * @returns {void}
+     */
+    clearNormalizedCredentialsCache(): void;
+    /**
+     * Returns normalized credentials for use by device classes, with caching to avoid redundant normalization.
+     *
+     * If the credentials have not changed since the last call, returns the cached normalized credentials.
+     * Otherwise, normalizes the credentials, caches them, and returns the new value.
+     *
+     * @returns {Promise<credentials>} Resolves with the normalized credentials object for API use.
+     * @throws {Error} If credentials are missing or invalid.
+     */
+    getNormalizedCredentials(): Promise<credentials>;
+    /**
+     * Starts the platform-level polling cycle for device state updates.
+     *
+     * Iterates registered locks serially (not in parallel) and short-circuits on the first failure.
+     *
+     * **Why serial:**
+     *   - One outstanding request at a time on a healthy network is cheap enough (most cycles complete in <1s for a handful of locks) and avoids racing the August API.
+     *   - On a failing network, a parallel cycle would produce N timeouts ~simultaneously, which is exactly the log-spam pattern the ConnectivityManager exists to prevent. Serial means one timeout, classified once, and the rest of the cycle aborts.
+     *
+     * **Why short-circuit on first failure:**
+     *   - If the first call fails with a network error, the manager has already entered 'degraded' state and scheduled a probe. The remaining N-1 calls would all hit the same dead network and produce identical errors. Aborting the cycle is the correct thing to do.
+     *
+     * **Why skip when offline:**
+     *   - The manager's state machine is already managing recovery via scheduled probes. Polling on top of that just wastes API calls and risks rate limiting.
+     *
+     * Idempotent: If discovery re-runs (e.g. after re-auth), does not stack timers.
+     *
+     * @returns {void}
+     */
+    startPolling(): void;
+    /**
+     * Stops the platform polling cycle for device state updates.
+     *
+     * Clears the polling timer if active, halting periodic device refreshes.
+     * Typically called during plugin shutdown or when polling is no longer needed.
+     *
+     * @returns {void}
+     */
+    stopPolling(): void;
+    /**
+     * Loads and returns the plugin's configuration and the full Homebridge config from disk.
+     *
+     * Reads the Homebridge config file, finds this plugin's config section, and ensures credentials is an object.
+     * Throws if the platforms array or plugin config is missing.
+     *
+     * @returns {Promise<{ pluginConfig: any, currentConfig: any }>} Resolves with the plugin's config and the full config object.
+     * @throws {TypeError|Error} If the platforms array or plugin config is missing.
+     */
+    pluginConfig(): Promise<{
+        pluginConfig: any;
+        currentConfig: any;
+    }>;
+    /**
+     * Discovers and registers August/Yale lock devices for the platform.
+     *
+     * Fetches device details from the August API using normalized credentials, applies config-based filtering,
+     * unregisters excluded accessories, merges config overrides, and registers each device via the Lock method.
+     * Handles authentication errors and triggers re-authentication if needed.
+     *
+     * @returns {Promise<void>} Resolves when all devices have been discovered and registered.
+     * @throws {Error} If device discovery or authentication fails.
+     */
+    discoverDevices(): Promise<void>;
+    /**
+     * --- Additional shared methods for config, logging, etc. ---
+     */
+    /**
+     * Determines if a device should be registered based on its visibility and HomeKit enablement.
+     *
+     * This is a generic version; subclasses may override for protocol-specific logic.
+     * Sets the registeringDevice flag and logs the registration decision.
+     *
+     * @param {any} device - The device object to evaluate for registration.
+     * @returns {Promise<boolean>} Resolves to true if the device should be registered, false otherwise.
+     */
+    protected registerDevice(device: any): Promise<boolean>;
+    /**
+     * Unregisters a platform accessory from Homebridge and removes it from the cache.
+     *
+     * Calls the Homebridge API to unregister the accessory, tears down the lock mechanism,
+     * removes the accessory from the internal cache, and logs the removal.
+     *
+     * @param {PlatformAccessory} existingAccessory - The accessory to unregister.
+     * @param {any} device - The device object (used for lockId and logging).
+     * @returns {Promise<void>} Resolves when the accessory has been unregistered and removed from cache.
+     */
+    protected unregisterPlatformAccessories(existingAccessory: PlatformAccessory, device: any): Promise<void>;
+    /**
+     * Publishes an accessory as either an external accessory or a platform accessory based on device config.
+     *
+     * If the device config has `external` set, publishes the accessory as an external accessory and logs the mode.
+     * Otherwise, registers it as a platform accessory and logs the mode.
+     *
+     * @param {device & devicesConfig} device - The device configuration object.
+     * @param {PlatformAccessory} accessory - The accessory to publish or register.
+     * @returns {Promise<void>} Resolves when the accessory has been published or registered.
+     */
+    externalOrPlatform(device: device & devicesConfig, accessory: PlatformAccessory): Promise<void>;
+    /**
+     * Publishes an accessory as an external accessory to Homebridge.
+     *
+     * Calls the Homebridge API to publish the provided accessory as an external accessory.
+     * This is used for accessories that should be exposed independently from the main bridge.
+     *
+     * @param {PlatformAccessory} accessory - The accessory to publish externally.
+     * @returns {Promise<void>} Resolves when the accessory has been published.
+     */
+    externalAccessory(accessory: PlatformAccessory): Promise<void>;
+    /**
+     * Asynchronously determines and logs the platform logging mode based on config options and debug flags.
+     *
+     * Sets the platformLogging property to 'debug', 'standard', 'none', or 'debugMode' depending on config and CLI flags.
+     * Logs the selected logging mode for debugging purposes.
+     *
+     * @returns {Promise<void>} Resolves when the logging mode has been determined, set, and logged.
+     */
+    protected getPlatformLogSettings(): Promise<void>;
+    /**
+     * Asynchronously loads and logs platform polling, update, and push rate settings from the config options.
+     *
+     * Reads refreshRate, updateRate, and pushRate from the config options, assigns them to instance properties,
+     * and logs the values for debugging purposes.
+     *
+     * @returns {Promise<void>} Resolves when the rates have been loaded, assigned, and logged.
+     */
+    protected getPlatformRateSettings(): Promise<void>;
+    /**
+     * Asynchronously loads and logs platform configuration settings from the config options.
+     *
+     * Reads logging, refreshRate, updateRate, and pushRate from the config options,
+     * builds a platformConfig object, logs it if present, and assigns it to this.platformConfig.
+     *
+     * @returns {Promise<void>} Resolves when the config has been loaded, logged, and assigned.
+     */
+    protected getPlatformConfigSettings(): Promise<void>;
+    /**
+     * Asynchronously retrieves and logs the plugin version from package.json.
+     *
+     * Reads the version from the package.json file, logs it using logger.debug, and
+     * assigns it to the `version` property of the class instance.
+     *
+     * @returns {Promise<void>} Resolves when the version has been read, logged, and assigned.
+     */
+    protected getVersion(): Promise<void>;
+    /**
+     * Asynchronously validates and cleans a display name or characteristic value for HomeKit compatibility.
+     *
+     * If invalid characters are not allowed (default), this method:
+     *   - Ensures the value contains only alphanumeric, space, and apostrophe characters.
+     *   - Removes any invalid characters and trims invalid start/end characters.
+     *   - Logs warnings and before/after values if modifications are made.
+     * If invalid characters are allowed by config, the value is returned unchanged.
+     *
+     * @param {string} displayName - The accessory's display name (for logging context).
+     * @param {string} name - The characteristic name (for logging context).
+     * @param {string} value - The value to validate and clean.
+     * @returns {Promise<string>} The cleaned (or original) value, suitable for HomeKit.
+     */
+    protected validateAndCleanDisplayName(displayName: string, name: string, value: string): Promise<string>;
+}
+//# sourceMappingURL=Platform.Base.d.ts.map