homebridge-bluos 0.1.0

package/dist/settings.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Plugin-wide constants and the plugin version reader.
+ *
+ * Numbers that came from the BluOS Custom Integration API v1.7 specification or
+ * from measurements against real players cite their source, so a future reader
+ * can tell a vendor requirement apart from a judgement call.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_NAME_LENGTH = exports.MAX_LOG_FIELD_LENGTH = exports.DISCOVERY_VERIFY_CONCURRENCY = exports.MAX_DISCOVERY_CANDIDATES = exports.MAX_DISCOVERY_RECORDS = exports.REDISCOVERY_MIN_INTERVAL_MS = exports.FAILURES_BEFORE_REDISCOVERY = exports.MAX_DISCOVERY_TIMEOUT_SEC = exports.MIN_DISCOVERY_TIMEOUT_SEC = exports.DEFAULT_DISCOVERY_TIMEOUT_SEC = exports.MDNS_SERVICE_SECONDARY = exports.MDNS_SERVICE_PRIMARY = exports.MAX_XML_ATTRIBUTES = exports.MAX_XML_ELEMENTS = exports.MAX_XML_DEPTH = exports.MAX_XML_BYTES = exports.MUTED_DB_SENTINEL = exports.FIXED_VOLUME_SENTINEL = exports.VOLUME_MAX = exports.VOLUME_MIN = exports.SLIDER_COALESCE_MS = exports.DEFAULT_RESTORE_VOLUME = exports.HOMEKIT_WRITE_BUDGET_MS = exports.POLL_FAILURE_REWARN_MS = exports.POLL_FAILURES_BEFORE_UNKNOWN = exports.POLL_BACKOFF_MAX_MS = exports.POLL_BACKOFF_BASE_MS = exports.CONTROL_RATE_LIMIT_MS = exports.STATUS_TIMEOUT_MS = exports.CONTROL_TIMEOUT_MS = exports.CONNECT_TIMEOUT_MS = exports.SAME_RESOURCE_MIN_GAP_MS = exports.LONG_POLL_READ_SLACK_MS = exports.LONG_POLL_SEC = exports.MAX_PORT = exports.MIN_PORT = exports.DOCUMENTED_BLUOS_PORTS = exports.DEFAULT_BLUOS_PORT = exports.DEFAULT_MODEL = exports.DEFAULT_BRAND = exports.UNKNOWN_PLUGIN_VERSION = exports.UUID_PREFIX = exports.PLATFORM_NAME = exports.PLUGIN_NAME = void 0;
+exports.readPluginVersion = readPluginVersion;
+/** npm package name. Must match `package.json` `name` for Homebridge to load us. */
+exports.PLUGIN_NAME = 'homebridge-bluos';
+/** Platform alias used in `config.json` and `config.schema.json`. */
+exports.PLATFORM_NAME = 'BluOS';
+/**
+ * Namespace for generated accessory UUIDs.
+ *
+ * Deliberately does not include a host or port: seeding accessory identity with
+ * an address means a DHCP lease change re-creates every accessory and destroys
+ * the rooms, scenes and automations the user built on top of them.
+ */
+exports.UUID_PREFIX = 'homebridge-bluos:';
+/** Reported when `package.json` cannot be read. */
+exports.UNKNOWN_PLUGIN_VERSION = '0.0.0';
+/** Manufacturer shown when `/SyncStatus` does not report a brand. */
+exports.DEFAULT_BRAND = 'BluOS';
+/** Model shown when `/SyncStatus` does not report one. */
+exports.DEFAULT_MODEL = 'BluOS Player';
+// --- Endpoints -------------------------------------------------------------
+/** Control port for a primary player (API v1.7 section 1). */
+exports.DEFAULT_BLUOS_PORT = 11_000;
+/**
+ * Ports the specification documents for multi-zone chassis.
+ *
+ * API v1.7 section 1: the CI 580 exposes four streamer nodes on one IP, using
+ * 11000, 11010, 11020 and 11030. The CI-S2 uses 11000 and 11010. Ports outside
+ * this set are accepted but warned about, because mDNS SRV records are the
+ * authority on which port a zone actually listens to.
+ */
+exports.DOCUMENTED_BLUOS_PORTS = [11_000, 11_010, 11_020, 11_030];
+/** Lowest port number accepted anywhere in configuration. */
+exports.MIN_PORT = 1;
+/** Highest port number accepted anywhere in configuration. */
+exports.MAX_PORT = 65_535;
+// --- Polling ---------------------------------------------------------------
+/**
+ * Duration passed as `/SyncStatus?timeout=`.
+ *
+ * The specification recommends 180 s for `/SyncStatus`, and forbids anything
+ * faster than 10 s. 100 s is inside that envelope and halves the worst-case
+ * delay before an unplugged player's socket read times out, which is how a
+ * silent disappearance (as opposed to a connection reset) gets noticed.
+ */
+exports.LONG_POLL_SEC = 100;
+/** Read headroom beyond the player's own long-poll timeout. */
+exports.LONG_POLL_READ_SLACK_MS = 5_000;
+/**
+ * Minimum gap between two consecutive requests for the same resource.
+ *
+ * API v1.7 section 2 makes this a requirement, not a suggestion: "a client must
+ * not make two consecutive requests for the same resource less than one second
+ * apart, even if the first request returns in less than one second".
+ */
+exports.SAME_RESOURCE_MIN_GAP_MS = 1_000;
+/** Connect timeout. Short so a powered-off player cannot stall startup. */
+exports.CONNECT_TIMEOUT_MS = 2_500;
+/** Total timeout for a control call (`/Volume?level=`, `/Volume?mute=`). */
+exports.CONTROL_TIMEOUT_MS = 5_000;
+/** Total timeout for a plain, non-long-poll status read. */
+exports.STATUS_TIMEOUT_MS = 6_000;
+/** Minimum spacing between control calls to one endpoint. */
+exports.CONTROL_RATE_LIMIT_MS = 100;
+/** First reconnect delay after a failed poll. Doubles up to the ceiling. */
+exports.POLL_BACKOFF_BASE_MS = 2_000;
+/** Ceiling for poll backoff. */
+exports.POLL_BACKOFF_MAX_MS = 60_000;
+/** Consecutive poll failures before an accessory reports No Response. */
+exports.POLL_FAILURES_BEFORE_UNKNOWN = 3;
+/** How long before a still-failing player is warned about again. */
+exports.POLL_FAILURE_REWARN_MS = 3_600_000;
+// --- HomeKit ---------------------------------------------------------------
+/**
+ * How long a HomeKit write may block before HAP gives up on it.
+ *
+ * HAP-NodeJS warns at `Accessory.TIMEOUT_WARNING` (3 s) and abandons the write
+ * at 9 s total, returning `OPERATION_TIMED_OUT` and discarding whatever the
+ * handler eventually returns. A set therefore has to answer well inside that
+ * window and finish any slower work in the background.
+ */
+exports.HOMEKIT_WRITE_BUDGET_MS = 2_500;
+/** Level restored when the slider is switched on and no previous level is known. */
+exports.DEFAULT_RESTORE_VOLUME = 20;
+/**
+ * Window for coalescing the pair of writes HomeKit sends when a slider moves
+ * from off.
+ *
+ * Dragging a Fanv2 up from zero produces an `Active` write immediately followed
+ * by a `RotationSpeed` write. Acting on both would set the restore level and then
+ * the requested level, which the user hears as a jump. Waiting briefly lets the
+ * second write supersede the first, so one value reaches the player. Short enough
+ * to be imperceptible next to the LAN round trip.
+ */
+exports.SLIDER_COALESCE_MS = 150;
+// --- Volume ----------------------------------------------------------------
+/** Lowest BluOS volume level. */
+exports.VOLUME_MIN = 0;
+/** Highest BluOS volume level. */
+exports.VOLUME_MAX = 100;
+/**
+ * `volume="-1"` means the player's output level is fixed.
+ *
+ * API v1.7 section 2.2: "-1 means fixed volume". Such a player must not be
+ * given a volume slider; writing a level to it is meaningless.
+ */
+exports.FIXED_VOLUME_SENTINEL = -1;
+/**
+ * `db="-100"` means silence, and is not a real output level.
+ *
+ * Measured on firmware 4.16.6: muting reports `volume="0" db="-100"` alongside
+ * `muteVolume` and `muteDb` carrying the pre-mute values. Note that writing
+ * `level=0` reports the same `db="-100"` with no `muteVolume`, so this value
+ * cannot be used to detect mute — see `readMuted` in `api/sync-status.ts`.
+ */
+exports.MUTED_DB_SENTINEL = -100;
+// --- XML parsing -----------------------------------------------------------
+/**
+ * Largest `/SyncStatus` body accepted.
+ *
+ * Real responses measure a few hundred bytes; a fully grouped CI 580 is still
+ * far under a kilobyte. 128 KiB is generous while keeping a hostile or
+ * malfunctioning endpoint from growing the heap.
+ */
+exports.MAX_XML_BYTES = 131_072;
+/** Deepest element nesting accepted. */
+exports.MAX_XML_DEPTH = 16;
+/** Most elements accepted in one document. */
+exports.MAX_XML_ELEMENTS = 2_000;
+/** Most attributes accepted on one element. */
+exports.MAX_XML_ATTRIBUTES = 64;
+// --- Discovery -------------------------------------------------------------
+/** mDNS service type advertised by primary players. */
+exports.MDNS_SERVICE_PRIMARY = '_musc._tcp.local';
+/**
+ * mDNS service type advertised by secondary zones of a multi-zone chassis.
+ *
+ * API v1.7 appendix 13.1 maps this to LSDP class 0x0003, "BluOS Player
+ * (secondary in multi-zone players such as the CI580)".
+ */
+exports.MDNS_SERVICE_SECONDARY = '_musp._tcp.local';
+/** Default discovery window, in seconds. */
+exports.DEFAULT_DISCOVERY_TIMEOUT_SEC = 5;
+/** Shortest configurable discovery window. */
+exports.MIN_DISCOVERY_TIMEOUT_SEC = 1;
+/** Longest configurable discovery window. */
+exports.MAX_DISCOVERY_TIMEOUT_SEC = 30;
+/** Consecutive poll failures before the platform tries to re-resolve an address. */
+exports.FAILURES_BEFORE_REDISCOVERY = 3;
+/** Minimum gap between address re-resolution attempts. */
+exports.REDISCOVERY_MIN_INTERVAL_MS = 60_000;
+/**
+ * Most records of one kind kept from a browse window.
+ *
+ * Anything on the segment can answer a multicast query, and a browse window can
+ * be as long as 30 s, so the maps that accumulate advertisements need a ceiling
+ * they cannot be talked past. A household fleet uses a handful of entries.
+ */
+exports.MAX_DISCOVERY_RECORDS = 256;
+/**
+ * Most candidate endpoints verified from one browse.
+ *
+ * Verification opens a real connection per candidate, so the count of
+ * advertisements must not decide how many sockets this plugin opens.
+ */
+exports.MAX_DISCOVERY_CANDIDATES = 64;
+/** Candidate endpoints verified at once. Bounds concurrent sockets during a sweep. */
+exports.DISCOVERY_VERIFY_CONCURRENCY = 6;
+// --- Logging ---------------------------------------------------------------
+/** Longest untrusted string interpolated into a log line. */
+exports.MAX_LOG_FIELD_LENGTH = 100;
+/** Longest accepted HomeKit display name. */
+exports.MAX_NAME_LENGTH = 64;
+let cachedVersion;
+/**
+ * Read this plugin's version from `package.json`.
+ *
+ * Reported to HomeKit as FirmwareRevision, which makes the version visible in
+ * the Home app and therefore in bug reports.
+ */
+function readPluginVersion(log) {
+    if (cachedVersion !== undefined) {
+        return cachedVersion;
+    }
+    try {
+        const pkg = require('../package.json');
+        cachedVersion = typeof pkg.version === 'string' && pkg.version.length > 0
+            ? pkg.version
+            : exports.UNKNOWN_PLUGIN_VERSION;
+    }
+    catch (error) {
+        log?.debug(`could not read plugin version: ${String(error)}`);
+        cachedVersion = exports.UNKNOWN_PLUGIN_VERSION;
+    }
+    return cachedVersion;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Shared types for configuration, accessory identity and the
+ * observations read back from a player.
+ */
+/** The subset of Homebridge's logger this plugin uses. */
+export interface PluginLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+}
+/**
+ * What an accessory does. Part of its identity, and therefore of its UUID.
+ *
+ * `volume` is the fake slider, `mute` the mute switch, `volumePreset` a
+ * one-level switch, and `battery` the state-of-charge sensor for portables.
+ */
+export declare const ACCESSORY_KINDS: readonly ["volume", "mute", "volumePreset", "battery"];
+/** @see ACCESSORY_KINDS */
+export type AccessoryKind = (typeof ACCESSORY_KINDS)[number];
+/** Narrow an unknown value to an {@link AccessoryKind}. */
+export declare function isAccessoryKind(value: unknown): value is AccessoryKind;
+/**
+ * Which HAP service impersonates the volume slider.
+ *
+ * HomeKit has no first-class speaker volume control that the Home app renders,
+ * so a slider has to borrow one. `fan` uses Fanv2 `RotationSpeed`; `lightbulb`
+ * uses `Brightness`. They render identically, but a Lightbulb is swept up by
+ * "turn off all the lights", which silences the house.
+ */
+export declare const SLIDER_SERVICES: readonly ["fan", "lightbulb"];
+/** @see SLIDER_SERVICES */
+export type SliderService = (typeof SLIDER_SERVICES)[number];
+/** Narrow an unknown value to a {@link SliderService}. */
+export declare function isSliderService(value: unknown): value is SliderService;
+/** A named volume level exposed as a switch. */
+export interface VolumePresetConfig {
+    name: string;
+    volume: number;
+}
+/** One configured player zone. */
+export interface BluOSDeviceConfig {
+    /**
+     * Stable identity, normally `{normalised-mac}:{port}`.
+     *
+     * Never contains an IP address, so a DHCP change does not re-create the
+     * accessory. Written by the discovery UI; hand-editable but not derived.
+     */
+    id: string;
+    name: string;
+    /** Last known address. Re-resolved at launch and when the player goes silent. */
+    host: string;
+    port?: number;
+    model?: string;
+    brand?: string;
+    volumeSlider?: boolean;
+    sliderService?: SliderService;
+    mute?: boolean;
+    battery?: boolean;
+    volumePresets?: VolumePresetConfig[];
+}
+/** Platform-level tuning. */
+export interface BluOSPlatformOptions {
+    discoveryTimeoutSec?: number;
+    sliderService?: SliderService;
+}
+/** Shape of one `platforms[]` entry in `config.json`. */
+export interface BluOSPlatformConfig {
+    platform: string;
+    name?: string;
+    devices?: BluOSDeviceConfig[];
+    options?: BluOSPlatformOptions;
+}
+/** A configured device after validation and defaulting. */
+export interface ResolvedDevice {
+    id: string;
+    name: string;
+    host: string;
+    port: number;
+    model?: string;
+    brand?: string;
+    volumeSlider: boolean;
+    sliderService: SliderService;
+    mute: boolean;
+    battery: boolean;
+    volumePresets: VolumePresetConfig[];
+}
+/** One accessory to expose, derived from a {@link ResolvedDevice}. */
+export interface ResolvedAccessory {
+    kind: AccessoryKind;
+    /** Owning device's stable id. */
+    deviceId: string;
+    /** HomeKit display name. */
+    name: string;
+    sliderService: SliderService;
+    /** Target level, for `volumePreset` only. */
+    volume?: number;
+}
+/**
+ * What gets persisted in `PlatformAccessory.context`.
+ *
+ * Survives restarts, so anything needed to serve HomeKit before the first poll
+ * completes belongs here.
+ */
+export interface AccessoryContext {
+    kind: AccessoryKind;
+    deviceId: string;
+    /** Last known address. Informational only; never part of identity. */
+    host: string;
+    port: number;
+    brand: string;
+    model: string;
+    /** Opaque, stable, generated once. Not the MAC: that would leak and churn. */
+    serialNumber: string;
+    /** True when this accessory was adopted from a different UUID scheme. */
+    adoptedLegacyUuid: boolean;
+    sliderService: SliderService;
+    /** Target level, for `volumePreset` only. */
+    volume?: number;
+    /**
+     * Last level seen above zero, used to restore the slider when switched on.
+     *
+     * Only a fallback: a player that was muted reports `muteVolume`, which is
+     * authoritative and preferred.
+     */
+    lastNonZeroVolume?: number;
+}
+/**
+ * How a player relates to a runtime sync group.
+ *
+ * A union rather than a const array plus a narrower, because nothing has to
+ * validate an incoming value against it: the role is derived from the shape of a
+ * `/SyncStatus` response, never read from configuration.
+ */
+export type SyncRole = 'standalone' | 'primary' | 'secondary';
+/** Battery state, present only on players with a battery pack. */
+export interface BatteryObservation {
+    level: number;
+    charging: boolean;
+}
+/**
+ * A parsed `/SyncStatus` response.
+ *
+ * `/Status` is deliberately not used: the specification points at `/SyncStatus`
+ * when "only the name, volume and grouping status of a player is of interest",
+ * and for a group secondary it is the only endpoint that reports that player's
+ * own volume rather than the group's.
+ */
+export interface PlayerObservation {
+    name: string;
+    brand?: string;
+    /** Model code, e.g. `CI-S2`. */
+    model?: string;
+    /** Display model name, e.g. `CI S2`. */
+    modelName?: string;
+    firmware?: string;
+    /** Normalised chassis MAC with no zone-port suffix, upper case. */
+    mac?: string;
+    /** Level 0..100, or undefined when the player reports fixed volume. */
+    volume?: number;
+    /** True when fixed-output; a slider must not be exposed. */
+    fixedVolume: boolean;
+    muted: boolean;
+    /** Pre-mute level, present only while muted. */
+    muteVolume?: number;
+    /**
+     * Output level in dB. Absent or sentinel while muted.
+     *
+     * Parsed and carried but not yet acted on: no accessory needs it, because
+     * HomeKit has no decibel characteristic. Kept because it is the only reading
+     * that describes the actual output of a player whose 0-100 level is mapped onto
+     * a restricted dB range, which is what a future dB-aware control would need.
+     */
+    db?: number;
+    syncRole: SyncRole;
+    battery?: BatteryObservation;
+    /** Opaque long-poll token from the response root. */
+    etag?: string;
+    /**
+     * Opaque sync-generation token from the response root.
+     *
+     * Parsed and carried but not yet acted on: grouping is derived from the
+     * `<master>` and `<slave>` elements instead. Kept because it changes whenever
+     * group membership does, which is the cheap way to notice a regrouping without
+     * comparing element lists.
+     */
+    syncStat?: string;
+}
+/** A player found by discovery and confirmed to answer `/SyncStatus`. */
+export interface DiscoveredPlayer {
+    id: string;
+    name: string;
+    host: string;
+    port: number;
+    brand?: string;
+    model?: string;
+    modelName?: string;
+    firmware?: string;
+    mac?: string;
+    fixedVolume: boolean;
+    hasBattery: boolean;
+}
+/** Why a refresh was requested, for logging and coalescing. */
+export type RefreshReason = 'poll' | 'post-set' | 'startup';
+/** An accessory handler the platform can drive. */
+export interface RefreshableAccessory {
+    readonly deviceId: string;
+    readonly displayName: string;
+    /** Apply a fresh observation to HomeKit characteristics. */
+    applyObservation(observation: PlayerObservation, reason: RefreshReason): void;
+    /** Report that the player could not be reached. */
+    noteUnreachable(error: unknown): void;
+}

package/dist/types/index.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Shared types for configuration, accessory identity and the
+ * observations read back from a player.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SLIDER_SERVICES = exports.ACCESSORY_KINDS = void 0;
+exports.isAccessoryKind = isAccessoryKind;
+exports.isSliderService = isSliderService;
+/**
+ * What an accessory does. Part of its identity, and therefore of its UUID.
+ *
+ * `volume` is the fake slider, `mute` the mute switch, `volumePreset` a
+ * one-level switch, and `battery` the state-of-charge sensor for portables.
+ */
+exports.ACCESSORY_KINDS = ['volume', 'mute', 'volumePreset', 'battery'];
+/** Narrow an unknown value to an {@link AccessoryKind}. */
+function isAccessoryKind(value) {
+    return typeof value === 'string' && exports.ACCESSORY_KINDS.includes(value);
+}
+/**
+ * Which HAP service impersonates the volume slider.
+ *
+ * HomeKit has no first-class speaker volume control that the Home app renders,
+ * so a slider has to borrow one. `fan` uses Fanv2 `RotationSpeed`; `lightbulb`
+ * uses `Brightness`. They render identically, but a Lightbulb is swept up by
+ * "turn off all the lights", which silences the house.
+ */
+exports.SLIDER_SERVICES = ['fan', 'lightbulb'];
+/** Narrow an unknown value to a {@link SliderService}. */
+function isSliderService(value) {
+    return typeof value === 'string' && exports.SLIDER_SERVICES.includes(value);
+}

package/dist/ui-api.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The surface the configuration UI server is allowed to use.
+ *
+ * An explicit contract rather than a barrel. The UI runs in a separate process
+ * and is the one consumer outside the plugin itself, so pinning what it may
+ * reach means its dependencies are visible here instead of being discovered by
+ * breaking it. In particular the identity helpers are shared rather than
+ * reimplemented: the ids the UI writes into configuration have to match what the
+ * platform derives, and two implementations would eventually disagree.
+ */
+export { BluOSClient } from './api/client';
+export { BluOSDiscovery } from './api/discovery';
+export { makeGeneratedPlayerId } from './api/identity';
+export { DEFAULT_DISCOVERY_TIMEOUT_SEC, DOCUMENTED_BLUOS_PORTS, MAX_DISCOVERY_TIMEOUT_SEC, MIN_DISCOVERY_TIMEOUT_SEC, } from './settings';
+export { isProbeableHost, isValidHost } from './utils/validators';

package/dist/ui-api.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The surface the configuration UI server is allowed to use.
+ *
+ * An explicit contract rather than a barrel. The UI runs in a separate process
+ * and is the one consumer outside the plugin itself, so pinning what it may
+ * reach means its dependencies are visible here instead of being discovered by
+ * breaking it. In particular the identity helpers are shared rather than
+ * reimplemented: the ids the UI writes into configuration have to match what the
+ * platform derives, and two implementations would eventually disagree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidHost = exports.isProbeableHost = exports.MIN_DISCOVERY_TIMEOUT_SEC = exports.MAX_DISCOVERY_TIMEOUT_SEC = exports.DOCUMENTED_BLUOS_PORTS = exports.DEFAULT_DISCOVERY_TIMEOUT_SEC = exports.makeGeneratedPlayerId = exports.BluOSDiscovery = exports.BluOSClient = void 0;
+var client_1 = require("./api/client");
+Object.defineProperty(exports, "BluOSClient", { enumerable: true, get: function () { return client_1.BluOSClient; } });
+var discovery_1 = require("./api/discovery");
+Object.defineProperty(exports, "BluOSDiscovery", { enumerable: true, get: function () { return discovery_1.BluOSDiscovery; } });
+var identity_1 = require("./api/identity");
+Object.defineProperty(exports, "makeGeneratedPlayerId", { enumerable: true, get: function () { return identity_1.makeGeneratedPlayerId; } });
+var settings_1 = require("./settings");
+Object.defineProperty(exports, "DEFAULT_DISCOVERY_TIMEOUT_SEC", { enumerable: true, get: function () { return settings_1.DEFAULT_DISCOVERY_TIMEOUT_SEC; } });
+Object.defineProperty(exports, "DOCUMENTED_BLUOS_PORTS", { enumerable: true, get: function () { return settings_1.DOCUMENTED_BLUOS_PORTS; } });
+Object.defineProperty(exports, "MAX_DISCOVERY_TIMEOUT_SEC", { enumerable: true, get: function () { return settings_1.MAX_DISCOVERY_TIMEOUT_SEC; } });
+Object.defineProperty(exports, "MIN_DISCOVERY_TIMEOUT_SEC", { enumerable: true, get: function () { return settings_1.MIN_DISCOVERY_TIMEOUT_SEC; } });
+var validators_1 = require("./utils/validators");
+Object.defineProperty(exports, "isProbeableHost", { enumerable: true, get: function () { return validators_1.isProbeableHost; } });
+Object.defineProperty(exports, "isValidHost", { enumerable: true, get: function () { return validators_1.isValidHost; } });

package/dist/utils/context.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Validation of the data cached on a restored accessory.
+ *
+ * Homebridge hands back whatever was persisted when the plugin last ran, which
+ * may have been written by an older version with a different shape. Reading it
+ * through one checked path means a stale or hand-edited cache produces a clear
+ * error for that one accessory instead of an undefined field surfacing much
+ * later as a wrong characteristic value.
+ */
+import type { PlatformAccessory } from 'homebridge';
+import { type AccessoryContext } from '../types';
+/** Read and validate a restored accessory's context. */
+export declare function parseAccessoryContext(accessory: PlatformAccessory): AccessoryContext;

package/dist/utils/context.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Validation of the data cached on a restored accessory.
+ *
+ * Homebridge hands back whatever was persisted when the plugin last ran, which
+ * may have been written by an older version with a different shape. Reading it
+ * through one checked path means a stale or hand-edited cache produces a clear
+ * error for that one accessory instead of an undefined field surfacing much
+ * later as a wrong characteristic value.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAccessoryContext = parseAccessoryContext;
+const settings_1 = require("../settings");
+const types_1 = require("../types");
+const errors_1 = require("./errors");
+const validators_1 = require("./validators");
+/** Read and validate a restored accessory's context. */
+function parseAccessoryContext(accessory) {
+    const raw = (accessory.context ?? {});
+    if (!(0, types_1.isAccessoryKind)(raw.kind)) {
+        throw new errors_1.ConfigValidationError(`cached accessory ${(0, validators_1.forLog)(accessory.displayName)} has an unknown kind ${(0, validators_1.forLog)(raw.kind)}`);
+    }
+    if (typeof raw.deviceId !== 'string' || raw.deviceId.length === 0) {
+        throw new errors_1.ConfigValidationError(`cached accessory ${(0, validators_1.forLog)(accessory.displayName)} has no device id`);
+    }
+    if (typeof raw.serialNumber !== 'string' || raw.serialNumber.length === 0) {
+        throw new errors_1.ConfigValidationError(`cached accessory ${(0, validators_1.forLog)(accessory.displayName)} has no serial number`);
+    }
+    if (raw.kind === 'volumePreset' && !Number.isInteger(raw.volume)) {
+        throw new errors_1.ConfigValidationError(`cached preset ${(0, validators_1.forLog)(accessory.displayName)} has no target volume`);
+    }
+    const sliderService = (0, types_1.isSliderService)(raw.sliderService) ? raw.sliderService : 'fan';
+    const context = {
+        kind: raw.kind,
+        deviceId: raw.deviceId,
+        host: typeof raw.host === 'string' ? raw.host : '',
+        port: Number.isInteger(raw.port) ? raw.port : settings_1.DEFAULT_BLUOS_PORT,
+        brand: typeof raw.brand === 'string' && raw.brand.length > 0 ? raw.brand : settings_1.DEFAULT_BRAND,
+        model: typeof raw.model === 'string' && raw.model.length > 0 ? raw.model : settings_1.DEFAULT_MODEL,
+        serialNumber: raw.serialNumber,
+        adoptedLegacyUuid: raw.adoptedLegacyUuid === true,
+        sliderService,
+    };
+    if (Number.isInteger(raw.volume)) {
+        context.volume = raw.volume;
+    }
+    if (Number.isInteger(raw.lastNonZeroVolume)) {
+        context.lastNonZeroVolume = raw.lastNonZeroVolume;
+    }
+    return context;
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Error description helpers.
+ *
+ * Node wraps low-level network failures in `cause` chains, so a bare
+ * `error.message` frequently reads "fetch failed" while the useful detail
+ * (ECONNREFUSED, ETIMEDOUT) sits one level down.
+ */
+/**
+ * Describe an error, including any `cause` chain, for a single log line.
+ *
+ * Control characters are stripped: an error message can contain remote input,
+ * and a newline inside a log line lets an attacker forge log entries.
+ */
+export declare function describeError(error: unknown): string;
+/** Describe an error and append its stack, for `log.debug` only. */
+export declare function describeErrorStack(error: unknown): string;
+/** Raised when configuration cannot produce a usable accessory set. */
+export declare class ConfigValidationError extends Error {
+    constructor(message: string);
+}
+/** Raised when a player answers, but not with something we can parse. */
+export declare class ProtocolError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Raised when a player cannot be reached at all. */
+export declare class ConnectionError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}