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

package/dist/Platform.Base.js

@@ -0,0 +1,797 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { argv } from 'node:process';
+import { PluginLogger } from '@homebridge/plugin-logger';
+import August from 'august-yale';
+import { ConnectivityManager } from './connectivity-manager.js';
+import { PLATFORM_NAME, PLUGIN_NAME } from './settings.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 class AugustPlatformBase {
+    /**
+     * 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>}
+     */
+    async subscribePubNub(lockId, onEvent, onStatus) {
+        await this.augustCredentials();
+        const normalizedCredentials = await this.getNormalizedCredentials();
+        // Defensive: clean up any previous subscription for this lock
+        this.tearDownPubNubSubscription(lockId);
+        // Dynamically import August for compatibility
+        const AugustModule = await import('august-yale');
+        const August = AugustModule.default;
+        // Create a new August instance for PubNub (not shared with HTTP client)
+        const pubnubAugust = new August(normalizedCredentials);
+        let pubnubStatusUnsubscribe;
+        if (onStatus) {
+            pubnubStatusUnsubscribe = pubnubAugust.onPubNubStatus(onStatus);
+        }
+        const pubnubUnsubscribe = await pubnubAugust.subscribe(lockId, onEvent);
+        // Store teardown logic in the lockMechanism for this lock
+        let mechanism = this.lockMechanisms.get(lockId);
+        if (!mechanism) {
+            mechanism = { device: { lockId } };
+            this.lockMechanisms.set(lockId, mechanism);
+        }
+        mechanism.pubnubAugust = pubnubAugust;
+        mechanism.pubnubUnsubscribe = pubnubUnsubscribe;
+        mechanism.pubnubStatusUnsubscribe = pubnubStatusUnsubscribe;
+        mechanism.tearDownPubNubSubscription = () => {
+            if (mechanism.pubnubStatusUnsubscribe) {
+                try {
+                    mechanism.pubnubStatusUnsubscribe();
+                }
+                catch (e) {
+                    // ignore
+                }
+                mechanism.pubnubStatusUnsubscribe = undefined;
+            }
+            if (mechanism.pubnubUnsubscribe) {
+                try {
+                    mechanism.pubnubUnsubscribe();
+                }
+                catch (e) {
+                    // ignore
+                }
+                mechanism.pubnubUnsubscribe = undefined;
+            }
+            if (mechanism.pubnubAugust) {
+                try {
+                    mechanism.pubnubAugust.destroy();
+                }
+                catch (e) {
+                    // ignore
+                }
+                mechanism.pubnubAugust = undefined;
+            }
+        };
+    }
+    /**
+     * Tears down the PubNub subscription for a given lockId (if present).
+     * Safe to call multiple times.
+     * @param {string} lockId
+     */
+    tearDownPubNubSubscription(lockId) {
+        const mechanism = this.lockMechanisms.get(lockId);
+        if (mechanism && typeof mechanism.tearDownPubNubSubscription === 'function') {
+            mechanism.tearDownPubNubSubscription();
+        }
+    }
+    accessories;
+    api;
+    log;
+    config;
+    platformConfig;
+    platformLogging;
+    platformRefreshRate;
+    platformPushRate;
+    platformUpdateRate;
+    registeringDevice;
+    debugMode;
+    version;
+    augustConfig;
+    connectivity;
+    lockMechanisms = new Map();
+    pollTimer;
+    normalizedCredentialsCache;
+    logger;
+    constructor(log, config, api) {
+        this.accessories = [];
+        this.api = api;
+        this.log = log;
+        this.logger = new PluginLogger(log, {
+            getLoggingMode: async () => this.platformLogging || 'standard',
+        });
+        if (!config) {
+            return;
+        }
+        this.config = {
+            platform: 'August',
+            name: config.name,
+            credentials: config.credentials,
+            options: config.options,
+        };
+        this.getPlatformLogSettings();
+        this.getPlatformRateSettings();
+        this.getPlatformConfigSettings();
+        this.getVersion();
+        this.logger.debug(`Finished initializing platform: ${config.name}`);
+        (async () => {
+            try {
+                await this.verifyConfig();
+                this.logger.debug('Config OK');
+            }
+            catch (e) {
+                this.logger.error(`Verify Config, Error Message: ${e.message ?? e}, Submit Bugs Here: https://bit.ly/august-bug-report`);
+            }
+        })();
+    }
+    // --- Device/Accessory management stubs ---
+    // Subclasses must implement protocol-specific logic
+    async Lock(device) {
+        void device; // suppress unused parameter warning
+        throw new Error('Lock() must be implemented by subclass');
+    }
+    /**
+     * 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}
+     */
+    tearDownLockMechanism(lockId) {
+        const lockMechanism = this.lockMechanisms.get(lockId);
+        if (lockMechanism) {
+            if (typeof lockMechanism.tearDownPubNubSubscription === 'function') {
+                lockMechanism.tearDownPubNubSubscription();
+            }
+            this.lockMechanisms.delete(lockId);
+        }
+    }
+    /**
+     * 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.
+     */
+    async configureAccessory(accessory) {
+        await this.logger.debug(`Loading accessory from cache: ${accessory.displayName}`);
+        // add the restored accessory to the accessories cache so we can track if it has already been registered
+        this.accessories.push(accessory);
+    }
+    /**
+     * 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.
+     */
+    async verifyConfig() {
+        if (!this.config.credentials) {
+            throw new Error('Missing Credentials');
+        }
+        else {
+            if (!this.config.credentials.augustId) {
+                throw new Error('Missing August ID (E-mail/Phone Number)');
+            }
+            if (!this.config.credentials.password) {
+                throw new Error('Missing August Password');
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async validated() {
+        if (!this.config.credentials?.installId) {
+            this.config.credentials.installId = this.api.hap.uuid.generate(`${this.config.credentials?.augustId}`);
+        }
+        await this.augustCredentials();
+        if (!this.config.credentials?.isValidated && this.config.credentials?.validateCode) {
+            const validateCode = this.config.credentials?.validateCode;
+            const normalizedCredentials = await this.normalizeCredentialsForApi(this.config.credentials);
+            const isValidated = await August.validate(normalizedCredentials, validateCode);
+            // If validated successfully, set flag for future use, and you can now use the API
+            this.config.credentials.isValidated = isValidated;
+            // Clear the cache since credentials have been updated
+            this.clearNormalizedCredentialsCache();
+            // load in the current config
+            const { pluginConfig, currentConfig } = await this.pluginConfig();
+            pluginConfig.credentials.isValidated = this.config.credentials?.isValidated;
+            if (this.config.credentials.isValidated) {
+                pluginConfig.credentials.validateCode = undefined;
+            }
+            await this.logger.debugWarn(`isValidated: ${pluginConfig.credentials.isValidated}`);
+            await this.logger.debugWarn(`validateCode: ${pluginConfig.credentials.validateCode}`);
+            // save the config, ensuring we maintain pretty json
+            writeFileSync(this.api.user.configPath(), JSON.stringify(currentConfig, null, 4));
+            if (!isValidated) {
+                this.logger.debugError('Validate Code is Invalid, Please Check Your Code and Restart Homebridge.');
+            }
+            else {
+                try {
+                    await this.discoverDevices();
+                    await this.logger.debugWarn(`isValidated: ${this.config.credentials?.isValidated}`);
+                }
+                catch (e) {
+                    await this.logger.error(`Validate, Discover Devices: ${e.message ?? e}`);
+                }
+            }
+        }
+        else {
+            // load in the current config
+            const { pluginConfig, currentConfig } = await this.pluginConfig();
+            // set the refresh token
+            pluginConfig.credentials.installId = this.config.credentials?.installId;
+            // Clear the cache since credentials have been updated
+            this.clearNormalizedCredentialsCache();
+            await this.logger.debugWarn(`installId: ${pluginConfig.credentials.installId}`);
+            // save the config, ensuring we maintain pretty json
+            writeFileSync(this.api.user.configPath(), JSON.stringify(currentConfig, null, 4));
+            // A 6-digit code will be sent to your email or phone (depending on what you used for your augustId).
+            // Need some way to get this code from the user.
+            const normalizedCredentials = await this.normalizeCredentialsForApi(this.config.credentials);
+            August.authorize(normalizedCredentials);
+            await this.logger.warn('Input Your August email verification code into the validateCode config and restart Homebridge.');
+        }
+    }
+    /**
+     * 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.
+     */
+    async augustCredentials() {
+        if (!this.config.credentials) {
+            throw new Error('Missing Credentials');
+        }
+        else if (this.augustConfig) {
+            await this.logger.debug('August API instance already initialized, skipping');
+        }
+        else {
+            // The ConnectivityManager owns the August client and rebuilds it
+            // automatically on auth failures and after probe-confirmed network
+            // recovery. We hand it a credentials factory rather than a one-shot
+            // value so rebuilds always pick up the latest normalized credentials,
+            // and a callback so the platform's public augustConfig field stays
+            // in sync with the manager's internal client.
+            if (!this.connectivity) {
+                this.connectivity = new ConnectivityManager(this.logger, () => this.normalizeCredentialsForApi(this.config.credentials), (client) => { this.augustConfig = client; });
+            }
+            await this.connectivity.init();
+            await this.logger.debug(`August Credentials: ${JSON.stringify(this.augustConfig)}`);
+        }
+    }
+    /**
+     * 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.
+     */
+    async normalizeCredentialsForApi(credentials) {
+        if (!credentials) {
+            throw new Error('Credentials cannot be null or undefined');
+        }
+        const normalizedCredentials = { ...credentials };
+        // Country code normalization mapping for API compatibility
+        // Some regions don't have dedicated August API endpoints and need to use US servers
+        const countryCodeMapping = {
+            CA: 'US', // Canada -> United States (North American region)
+            MX: 'US', // Mexico -> United States (North American region)
+        };
+        const originalCountryCode = credentials.countryCode?.toUpperCase();
+        const normalizedCountryCode = originalCountryCode ? countryCodeMapping[originalCountryCode] : undefined;
+        // Check if user has disabled normalization via config
+        const normalizationDisabled = this.config.options?.disableCountryCodeNormalization === true;
+        if (originalCountryCode && normalizedCountryCode && !normalizationDisabled) {
+            await this.logger.debugWarn(`Country code normalization: ${originalCountryCode} -> ${normalizedCountryCode} for API compatibility. `
+                + `To disable this behavior, set 'disableCountryCodeNormalization: true' in options.`);
+            normalizedCredentials.countryCode = normalizedCountryCode;
+        }
+        else if (originalCountryCode && normalizedCountryCode && normalizationDisabled) {
+            await this.logger.debug(`Country code normalization disabled by config. Using original country code: ${originalCountryCode}`);
+        }
+        else if (originalCountryCode && !normalizedCountryCode) {
+            await this.logger.debug(`Country code ${originalCountryCode} does not require normalization.`);
+        }
+        return normalizedCredentials;
+    }
+    /**
+     * 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() {
+        this.normalizedCredentialsCache = undefined;
+        this.logger.debug('Cleared normalized credentials cache');
+    }
+    /**
+     * 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.
+     */
+    async getNormalizedCredentials() {
+        if (!this.config.credentials) {
+            throw new Error('Missing Credentials');
+        }
+        // Return cached credentials if available and credentials haven't changed
+        if (this.normalizedCredentialsCache) {
+            // Simple check to see if the original credentials have changed
+            const currentCredsHash = JSON.stringify(this.config.credentials);
+            const cachedCredsHash = JSON.stringify({ ...this.normalizedCredentialsCache, countryCode: this.config.credentials.countryCode });
+            if (currentCredsHash === cachedCredsHash
+                || (this.normalizedCredentialsCache.augustId === this.config.credentials.augustId
+                    && this.normalizedCredentialsCache.password === this.config.credentials.password
+                    && this.normalizedCredentialsCache.installId === this.config.credentials.installId)) {
+                await this.logger.debug('Using cached normalized credentials');
+                return this.normalizedCredentialsCache;
+            }
+        }
+        // Generate new normalized credentials and cache them
+        this.normalizedCredentialsCache = await this.normalizeCredentialsForApi(this.config.credentials);
+        await this.logger.debug('Generated and cached new normalized credentials');
+        return this.normalizedCredentialsCache;
+    }
+    /**
+     * 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() {
+        const refreshSeconds = this.platformRefreshRate ?? 30;
+        if (refreshSeconds === 0) {
+            this.logger.debug('Polling disabled (platformRefreshRate = 0)');
+            return;
+        }
+        if (this.pollTimer) {
+            // Idempotent: if discovery re-runs (e.g. after re-auth), don't
+            // stack timers.
+            this.logger.debug('Polling already started — not restarting');
+            return;
+        }
+        const tick = async () => {
+            try {
+                if (!this.connectivity || this.connectivity.getState() === 'offline') {
+                    // Skip this cycle. The manager's probe will signal recovery.
+                    return;
+                }
+                for (const lock of this.lockMechanisms.values()) {
+                    // Skip locks currently mid-push so we don't race the user's
+                    // explicit lock/unlock command with a stale poll result.
+                    if (lock.lockUpdateInProgress) {
+                        continue;
+                    }
+                    const lockId = lock.device?.lockId;
+                    if (!lockId) {
+                        continue;
+                    }
+                    const details = await this.connectivity.execute(`poll ${lockId}`, client => client.details(lockId));
+                    if (details === undefined) {
+                        // execute() returned undefined because the call failed (or
+                        // the manager went offline between iterations). The state
+                        // machine has the situation; don't keep iterating.
+                        break;
+                    }
+                    await lock.applyRefresh(details);
+                }
+            }
+            catch (e) {
+                // Belt-and-suspenders. execute() should never throw for
+                // network errors, but if anything leaks through we want the
+                // poll loop to stay alive.
+                await this.logger.error(`Polling tick failed: ${e?.message ?? e}`);
+            }
+            finally {
+                this.pollTimer = setTimeout(tick, refreshSeconds * 1000);
+            }
+        };
+        this.logger.info(`Starting platform poll loop (refreshRate=${refreshSeconds}s)`);
+        this.pollTimer = setTimeout(tick, refreshSeconds * 1000);
+    }
+    /**
+     * 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() {
+        if (this.pollTimer) {
+            clearTimeout(this.pollTimer);
+            this.pollTimer = undefined;
+        }
+    }
+    /**
+     * 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.
+     */
+    async pluginConfig() {
+        const currentConfig = JSON.parse(readFileSync(this.api.user.configPath(), 'utf8'));
+        // check the platforms section is an array before we do array things on it
+        if (!Array.isArray(currentConfig.platforms)) {
+            throw new TypeError('Cannot find platforms array in config');
+        }
+        // find this plugins current config
+        const pluginConfig = currentConfig.platforms.find((x) => x.platform === PLATFORM_NAME);
+        if (!pluginConfig) {
+            throw new Error(`Cannot find config for ${PLATFORM_NAME} in platforms array`);
+        }
+        // check the .credentials is an object before doing object things with it
+        // Note: typeof null === 'object' is true, so we need to explicitly check for null and undefined
+        if (typeof pluginConfig.credentials !== 'object' || pluginConfig.credentials === null) {
+            // Initialize credentials as an empty object if it doesn't exist or is null
+            pluginConfig.credentials = {};
+        }
+        return { pluginConfig, currentConfig };
+    }
+    /**
+     * 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.
+     */
+    async discoverDevices() {
+        try {
+            await this.augustCredentials();
+            const normalizedCredentials = await this.normalizeCredentialsForApi(this.config.credentials);
+            const devices = await August.details(normalizedCredentials, '');
+            let deviceLists;
+            if (devices.length > 1) {
+                deviceLists = devices;
+                await this.logger.info(`Total August Locks Found: ${deviceLists.length}`);
+            }
+            else {
+                deviceLists = [devices];
+                await this.logger.info(`Total August Locks Found: ${deviceLists.length}`);
+            }
+            const excludeLockIds = this.config.options?.excludeLockIds ?? [];
+            if (excludeLockIds.length > 0) {
+                const normalizedExcludeIds = excludeLockIds.map(id => id.toUpperCase().replace(/[^A-Z0-9]+/g, ''));
+                const beforeCount = deviceLists.length;
+                deviceLists = deviceLists.filter((device) => {
+                    const normalizedLockId = (device.lockId ?? device.LockId ?? '').toUpperCase().replace(/[^A-Z0-9]+/g, '');
+                    return !normalizedExcludeIds.includes(normalizedLockId);
+                });
+                const excludedCount = beforeCount - deviceLists.length;
+                if (excludedCount > 0) {
+                    await this.logger.info?.(`Excluded ${excludedCount} lock(s) via excludeLockIds config.`);
+                }
+                for (const excludedId of excludeLockIds) {
+                    const uuid = this.api.hap.uuid.generate(excludedId);
+                    const existingAccessory = this.accessories.find(accessory => accessory.UUID === uuid);
+                    if (existingAccessory) {
+                        this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [existingAccessory]);
+                        this.tearDownLockMechanism?.(excludedId);
+                        this.accessories = this.accessories.filter(accessory => accessory.UUID !== uuid);
+                        await this.logger.warn?.(`Removing excluded accessory from cache: ${existingAccessory.displayName} (${excludedId})`);
+                    }
+                }
+            }
+            if (!this.config.options?.devices) {
+                await this.logger.debugWarn?.(`August Platform Config Not Set: ${JSON.stringify(this.config.options?.devices)}`);
+                const devices = deviceLists.map((v) => v);
+                for (const device of devices) {
+                    if (device.configDeviceName) {
+                        device.deviceName = device.configDeviceName;
+                    }
+                    await this.logger.debug?.(`August Devices: ${JSON.stringify(device)}`);
+                    await this.Lock?.(device);
+                }
+            }
+            else if (this.config.options.devices) {
+                await this.logger.debugWarn?.(`August Platform Config Set: ${JSON.stringify(this.config.options?.devices)}`);
+                const deviceConfigs = this.config.options?.devices;
+                const mergeBylockId = (a1, a2) => a1.map((itm) => ({
+                    ...a2.find((item) => item.lockId.toUpperCase().replace(/[^A-Z0-9]+/g, '') === itm.lockId.toUpperCase().replace(/[^A-Z0-9]+/g, '') && item),
+                    ...itm,
+                }));
+                const devices = mergeBylockId(deviceLists, deviceConfigs);
+                await this.logger.debug?.(`August Lock(s): ${JSON.stringify(devices)}`);
+                for (const device of devices) {
+                    if (device.configDeviceName) {
+                        device.deviceName = device.configDeviceName;
+                    }
+                    await this.logger.debug?.(`device: ${JSON.stringify(device)}`);
+                    await this.Lock?.(device);
+                }
+            }
+            else {
+                await this.logger.error?.('August ID & Password Supplied, Issue with Auth.');
+            }
+        }
+        catch (error) {
+            const errorMessage = error.message || String(error);
+            if (errorMessage.includes('401') || errorMessage.toLowerCase().includes('unauthorized')) {
+                await this.logger.warn?.('Authentication session has expired or is invalid. Attempting re-authentication...');
+                this.config.credentials.isValidated = false;
+                try {
+                    const { pluginConfig, currentConfig } = await this.pluginConfig();
+                    pluginConfig.credentials.isValidated = false;
+                    writeFileSync(this.api.user.configPath(), JSON.stringify(currentConfig, null, 4));
+                    await this.logger.debug?.('Updated config file with isValidated: false to trigger re-authentication');
+                }
+                catch (configError) {
+                    await this.logger.error?.(`Failed to update config file: ${configError.message ?? configError}`);
+                }
+                try {
+                    await this.logger.warn?.('Initiating re-authentication process. Please check for verification code if prompted.');
+                    await this.validated();
+                }
+                catch (authError) {
+                    throw new Error(`Re-authentication failed: ${authError.message ?? authError}. Please check your credentials and try restarting Homebridge.`);
+                }
+            }
+            else {
+                throw new Error(`Failed to discover devices: ${errorMessage}`);
+            }
+        }
+    }
+    /**
+     * --- 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.
+     */
+    async registerDevice(device) {
+        // This is a generic version; subclasses may override for protocol-specific logic
+        if (!device.hide_device && !device.homeKitEnabled) {
+            this.registeringDevice = true;
+            await this.logger.debug?.(`Device: ${device.LockName} Enabled`);
+        }
+        else if (device.homeKitEnabled && device.overrideHomeKitEnabled) {
+            this.registeringDevice = true;
+            await this.logger.debugWarn?.(`Device: ${device.LockName} HomeKit Enabled: ${device.homeKitEnabled}, `
+                + `Override HomeKit Enabled: ${device.overrideHomeKitEnabled}`);
+        }
+        else if (device.homeKitEnabled && !device.overrideHomeKitEnabled) {
+            this.registeringDevice = false;
+            await this.logger.debugError?.(`Device: ${device.LockName} HomeKit Enabled: `
+                + `${device.homeKitEnabled}, device will not be registered. To enable, set overrideHomeKitEnabled to true.`);
+        }
+        else {
+            this.registeringDevice = false;
+            await this.logger.debug?.(`Device: ${device.LockName} is Hidden.`);
+        }
+        return this.registeringDevice;
+    }
+    /**
+     * 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.
+     */
+    async unregisterPlatformAccessories(existingAccessory, device) {
+        this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [existingAccessory]);
+        this.tearDownLockMechanism?.(device.lockId);
+        this.accessories = this.accessories.filter(accessory => accessory.UUID !== existingAccessory.UUID);
+        await this.logger.warn?.(`Removing existing accessory from cache: ${device.LockName}`);
+    }
+    /**
+     * 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.
+     */
+    async externalOrPlatform(device, accessory) {
+        if (device.external) {
+            await this.logger.info(`${accessory.displayName} External Accessory Mode: ${device.external}`);
+            await this.externalAccessory(accessory);
+        }
+        else {
+            await this.logger.debug(`${accessory.displayName} External Accessory Mode: ${device.external}`);
+            this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+        }
+    }
+    /**
+     * 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.
+     */
+    async externalAccessory(accessory) {
+        this.api.publishExternalAccessories(PLUGIN_NAME, [accessory]);
+    }
+    /**
+     * 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.
+     */
+    async getPlatformLogSettings() {
+        this.debugMode = argv.includes('-D') ?? argv.includes('--debug');
+        this.platformLogging = (this.config.options?.logging === 'debug' || this.config.options?.logging === 'standard'
+            || this.config.options?.logging === 'none')
+            ? this.config.options.logging
+            : this.debugMode ? 'debugMode' : 'standard';
+        const logging = this.config.options?.logging ? 'Platform Config' : this.debugMode ? 'debugMode' : 'Default';
+        await this.logger.debug(`Using ${logging} Logging: ${this.platformLogging}`);
+    }
+    /**
+     * 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.
+     */
+    async getPlatformRateSettings() {
+        // RefreshRate
+        this.platformRefreshRate = this.config.options?.refreshRate ? this.config.options.refreshRate : undefined;
+        const refreshRate = this.config.options?.refreshRate ? 'Using Platform Config refreshRate' : 'Platform Config refreshRate Not Set';
+        await this.logger.debug(`${refreshRate}: ${this.platformRefreshRate}`);
+        // UpdateRate
+        this.platformUpdateRate = this.config.options?.updateRate ? this.config.options.updateRate : undefined;
+        const updateRate = this.config.options?.updateRate ? 'Using Platform Config updateRate' : 'Platform Config updateRate Not Set';
+        await this.logger.debug(`${updateRate}: ${this.platformUpdateRate}`);
+        // PushRate
+        this.platformPushRate = this.config.options?.pushRate ? this.config.options.pushRate : undefined;
+        const pushRate = this.config.options?.pushRate ? 'Using Platform Config pushRate' : 'Platform Config pushRate Not Set';
+        await this.logger.debug(`${pushRate}: ${this.platformPushRate}`);
+    }
+    /**
+     * 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.
+     */
+    async getPlatformConfigSettings() {
+        if (this.config.options) {
+            const platformConfig = {
+                platform: 'August',
+            };
+            platformConfig.logging = this.config.options.logging ? this.config.options.logging : undefined;
+            platformConfig.refreshRate = this.config.options.refreshRate ? this.config.options.refreshRate : undefined;
+            platformConfig.updateRate = this.config.options.updateRate ? this.config.options.updateRate : undefined;
+            platformConfig.pushRate = this.config.options.pushRate ? this.config.options.pushRate : undefined;
+            if (Object.entries(platformConfig).length !== 0) {
+                await this.logger.debug(`Platform Config: ${JSON.stringify(platformConfig)}`);
+            }
+            this.platformConfig = platformConfig;
+        }
+    }
+    /**
+     * 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.
+     */
+    async getVersion() {
+        const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+        this.logger.debug(`Plugin Version: ${version}`);
+        this.version = version;
+    }
+    /**
+     * 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.
+     */
+    async validateAndCleanDisplayName(displayName, name, value) {
+        if (this.config.options?.allowInvalidCharacters) {
+            return value;
+        }
+        else {
+            const validPattern = /^[\p{L}\p{N}][\p{L}\p{N} ']*[\p{L}\p{N}]$/u;
+            const invalidCharsPattern = /[^\p{L}\p{N} ']/gu;
+            const invalidStartEndPattern = /^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu;
+            if (typeof value === 'string' && !validPattern.test(value)) {
+                this.logger.warn(`WARNING: The accessory '${displayName}' has an invalid '${name}' characteristic ('${value}'). Please use only alphanumeric, space, and apostrophe characters. Ensure it starts and ends with an alphabetic or numeric character, and avoid emojis. This may prevent the accessory from being added in the Home App or cause unresponsiveness.`);
+                // Remove invalid characters
+                if (invalidCharsPattern.test(value)) {
+                    const before = value;
+                    this.logger.warn(`Removing invalid characters from '${name}' characteristic, if you feel this is incorrect,  please enable \'allowInvalidCharacter\' in the config to allow all characters`);
+                    value = value.replace(invalidCharsPattern, '');
+                    this.logger.warn(`${name} Before: '${before}' After: '${value}'`);
+                }
+                // Ensure it starts and ends with an alphanumeric character
+                if (invalidStartEndPattern.test(value)) {
+                    const before = value;
+                    this.logger.warn(`Removing invalid starting or ending characters from '${name}' characteristic, if you feel this is incorrect, please enable \'allowInvalidCharacter\' in the config to allow all characters`);
+                    value = value.replace(invalidStartEndPattern, '');
+                    this.logger.warn(`${name} Before: '${before}' After: '${value}'`);
+                }
+            }
+            return value;
+        }
+    }
+}
+//# sourceMappingURL=Platform.Base.js.map