matterbridge-lg-thinq-plugin 0.1.0

package/src/platform/deviceRegistry.ts

@@ -0,0 +1,58 @@
+/**
+ * Registry for managing plugin devices (ThinQ now, webOS in a later phase).
+ * Provides centralized storage and lookup for registered device handles, keyed by device id.
+ * Empty skeleton for Phase 0 — device shapes land alongside their family's discovery/configurator (Phase 1/3).
+ */
+export class DeviceRegistry {
+	private readonly devices = new Map<string, unknown>();
+
+	/**
+	 * Register a device by id.
+	 */
+	public register(deviceId: string, device: unknown): void {
+		if (!deviceId) return;
+		this.devices.set(deviceId, device);
+	}
+
+	/**
+	 * Unregister a device by id.
+	 */
+	public unregister(deviceId: string): void {
+		this.devices.delete(deviceId);
+	}
+
+	/**
+	 * Get a device by id.
+	 */
+	public getDevice(deviceId: string): unknown {
+		return this.devices.get(deviceId);
+	}
+
+	/**
+	 * Get all registered devices.
+	 */
+	public getAllDevices(): unknown[] {
+		return Array.from(this.devices.values());
+	}
+
+	/**
+	 * Get the number of registered devices.
+	 */
+	public get size(): number {
+		return this.devices.size;
+	}
+
+	/**
+	 * Check if there are any registered devices.
+	 */
+	public hasDevices(): boolean {
+		return this.devices.size > 0;
+	}
+
+	/**
+	 * Clear all registered devices.
+	 */
+	public clear(): void {
+		this.devices.clear();
+	}
+}

package/src/platform/platformConfigManager.ts

@@ -0,0 +1,133 @@
+/**
+ * Platform configuration manager.
+ * Provides validation and defaults over the raw plugin config.
+ */
+
+import type { AnsiLogger } from 'matterbridge/logger';
+
+import type { AirConditionerCapabilities } from '../core/domain/value-objects/AirConditionerCapabilities.js';
+import { resolveAirConditionerCapabilities } from '../core/domain/value-objects/AirConditionerCapabilities.js';
+import {
+	createDefaultAdvancedFeature,
+	createDefaultThinqConfig,
+	LgThinqPluginPlatformConfig,
+	type MatterOverrideSettings,
+	type ThinqAcFilterControlConfig,
+	type ThinqWasherControlConfig,
+} from '../model/LgThinqPluginPlatformConfig.js';
+
+const DEFAULT_THINQ_REFRESH_INTERVAL_SECONDS = 60;
+const DEFAULT_FILTER_MONITORING_INTERVAL_SECONDS = 3600;
+
+/**
+ * Manages platform configuration with validation and defaults.
+ */
+export class PlatformConfigManager {
+	private constructor(
+		private readonly config: LgThinqPluginPlatformConfig,
+		private readonly log: AnsiLogger,
+	) {
+		this.config.thinq ??= createDefaultThinqConfig();
+		this.config.webos ??= { devices: [] };
+		this.config.advancedFeature ??= createDefaultAdvancedFeature();
+	}
+
+	/**
+	 * Create a PlatformConfigManager with defaults applied.
+	 */
+	public static create(config: LgThinqPluginPlatformConfig, log: AnsiLogger): PlatformConfigManager {
+		return new PlatformConfigManager(config, log);
+	}
+
+	public get rawConfig(): LgThinqPluginPlatformConfig {
+		return this.config;
+	}
+
+	public get debug(): boolean {
+		return this.config.advancedFeature.settings.debug;
+	}
+
+	public get isClearStorageOnStartupEnabled(): boolean {
+		return this.config.advancedFeature.settings.clearStorageOnStartup;
+	}
+
+	public get isForceAuthenticationEnabled(): boolean {
+		return this.config.advancedFeature.settings.forceAuthentication;
+	}
+
+	public get unregisterOnShutdown(): boolean {
+		return this.config.advancedFeature.settings.unregisterOnShutdown;
+	}
+
+	public get thinqLoginType(): 'account' | 'token' {
+		return this.config.thinq.loginType;
+	}
+
+	public get thinqUsername(): string | undefined {
+		return this.config.thinq.username;
+	}
+
+	public get thinqPassword(): string | undefined {
+		return this.config.thinq.password;
+	}
+
+	public get thinqRefreshToken(): string | undefined {
+		return this.config.thinq.refreshToken;
+	}
+
+	public get country(): string {
+		return this.config.thinq.country;
+	}
+
+	public get language(): string {
+		return this.config.thinq.language;
+	}
+
+	public get thinqRefreshIntervalSeconds(): number {
+		return this.config.thinq.refreshIntervalSeconds ?? DEFAULT_THINQ_REFRESH_INTERVAL_SECONDS;
+	}
+
+	public get thinqFilterMonitoringIntervalSeconds(): number {
+		return this.config.thinq.filterMonitoringIntervalSeconds ?? DEFAULT_FILTER_MONITORING_INTERVAL_SECONDS;
+	}
+
+	public getDeviceCapabilities(deviceId: string): AirConditionerCapabilities {
+		return resolveAirConditionerCapabilities(this.config.thinq.devices, deviceId);
+	}
+
+	public getWasherControlConfig(deviceId: string): ThinqWasherControlConfig {
+		return this.config.thinq.devices?.find((d) => d.deviceId === deviceId)?.washerControl ?? {};
+	}
+
+	public getAcFilterControlConfig(deviceId: string): ThinqAcFilterControlConfig {
+		return this.config.thinq.devices?.find((d) => d.deviceId === deviceId)?.acFilterControl ?? {};
+	}
+
+	public get overrideMatterConfiguration(): boolean {
+		return this.config.advancedFeature.settings.overrideMatterConfiguration;
+	}
+
+	public get matterOverrideSettings(): MatterOverrideSettings {
+		return this.config.advancedFeature.settings.matterOverrideSettings;
+	}
+
+	public getProductNameForDevice(deviceId: string): string | undefined {
+		if (!this.overrideMatterConfiguration) return undefined;
+		return this.config.thinq.devices?.find((d) => d.deviceId === deviceId)?.productName;
+	}
+
+	public getProductIdForDevice(deviceId: string): number | undefined {
+		if (!this.overrideMatterConfiguration) return undefined;
+		return this.config.thinq.devices?.find((d) => d.deviceId === deviceId)?.productId;
+	}
+
+	public validateConfig(): boolean {
+		this.log.debug('Validating platform config');
+
+		if (this.thinqLoginType === 'token') {
+			return Boolean(this.thinqRefreshToken);
+		}
+
+		return Boolean(this.thinqUsername && this.thinqPassword);
+	}
+}

package/src/platform/platformState.ts

@@ -0,0 +1,16 @@
+/**
+ * Platform state container.
+ * Holds ephemeral runtime state for the platform (startup completion, etc.).
+ * Uses strict types (no `any`) and provides simple accessor/mutator API.
+ */
+export class PlatformState {
+	private startupCompleted = false;
+
+	public get isStartupCompleted(): boolean {
+		return this.startupCompleted;
+	}
+
+	public setStartupCompleted(completed: boolean): void {
+		this.startupCompleted = completed;
+	}
+}

package/src/platform/thinq/thinqAirConditionerCommandHandlers.ts

@@ -0,0 +1,291 @@
+import { MatterbridgeEndpoint } from 'matterbridge';
+import { AnsiLogger } from 'matterbridge/logger';
+import { FanControl, Thermostat } from 'matterbridge/matter/clusters';
+import { isValidNumber } from 'matterbridge/utils';
+
+import type { ThinqAirConditionerDevice } from '../../core/domain/entities/ThinqDevice.js';
+import type { AirConditionerCapabilities } from '../../core/domain/value-objects/AirConditionerCapabilities.js';
+import { ThinqApiClient } from '../../services/thinq/thinqApiClient.js';
+
+/** LG `airState.windStrength` values (`homebridge-lg-thinq/src/devices/AirConditioner.ts:15,19-25`). */
+export const THINQ_FAN_SPEED_AUTO = 8;
+export const THINQ_FAN_SPEED_LOW = 2;
+export const THINQ_FAN_SPEED_MEDIUM = 4;
+export const THINQ_FAN_SPEED_HIGH = 6;
+
+const THINQ_OPERATION_ON = 1;
+const THINQ_OPERATION_OFF = 0;
+
+/** LG ACs commonly step Celsius setpoints by half a degree; snapping to this avoids ThinQ 400s on off-step values. */
+const THINQ_TEMPERATURE_STEP_CELSIUS = 0.5;
+
+function withErrorHandling(commandName: string, logger: AnsiLogger, handler: () => Promise<void>): () => Promise<void> {
+	return async () => {
+		try {
+			await handler();
+		} catch (error) {
+			logger.error(
+				`ThinQ AirConditioner command '${commandName}' failed: ${error instanceof Error ? error.message : String(error)}`,
+			);
+			throw error;
+		}
+	};
+}
+
+/** Rounds a Celsius value to the nearest multiple of `step` (e.g. 25.3 -> 25.5 for step 0.5). */
+function roundToStep(value: number, step: number): number {
+	return Math.round(value / step) * step;
+}
+
+/**
+ * Reverts a Thermostat setpoint attribute back to `oldValue` after a failed ThinQ command, so Apple Home
+ * self-corrects immediately instead of showing a value ThinQ never accepted. Best-effort: `updateAttribute`
+ * failures are swallowed since the original command failure is already logged by `withErrorHandling`.
+ */
+function revertSetpointOnFailure(
+	airConditioner: MatterbridgeEndpoint,
+	attribute: 'occupiedCoolingSetpoint' | 'occupiedHeatingSetpoint',
+	oldValue: number,
+): () => void {
+	return () => {
+		airConditioner.updateAttribute(Thermostat.id, attribute, oldValue, airConditioner.log).catch(() => {
+			// Best-effort revert; original failure already logged inside withErrorHandling.
+		});
+	};
+}
+
+function mapPercentToWindStrength(percent: number): number | undefined {
+	if (percent === 0) {
+		return undefined;
+	}
+	if (percent <= 33) {
+		return THINQ_FAN_SPEED_LOW;
+	}
+	if (percent <= 66) {
+		return THINQ_FAN_SPEED_MEDIUM;
+	}
+	return THINQ_FAN_SPEED_HIGH;
+}
+
+function mapFanModeToWindStrength(fanMode: FanControl.FanMode): number | undefined {
+	switch (fanMode) {
+		case FanControl.FanMode.Auto:
+			return THINQ_FAN_SPEED_AUTO;
+		case FanControl.FanMode.Low:
+			return THINQ_FAN_SPEED_LOW;
+		case FanControl.FanMode.Medium:
+			return THINQ_FAN_SPEED_MEDIUM;
+		case FanControl.FanMode.High:
+			return THINQ_FAN_SPEED_HIGH;
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Registers Apple Home → ThinQ command handlers on an already-constructed `AirConditioner` endpoint.
+ * `OnOff.on`/`off` and `subscribeAttribute` for setpoints/fan speed all forward to `ThinqApiClient.sendCommand`.
+ */
+export function registerAirConditionerCommandHandlers(
+	airConditioner: MatterbridgeEndpoint,
+	device: ThinqAirConditionerDevice,
+	apiClient: ThinqApiClient,
+	logger: AnsiLogger,
+	capabilities: AirConditionerCapabilities,
+): void {
+	airConditioner.addCommandHandler(
+		'on',
+		withErrorHandling('on', logger, async () => {
+			logger.debug(
+				`ThinQ AirConditioner ${device.id}: 'on' command handler invoked, capabilities=${JSON.stringify(capabilities)}`,
+			);
+			await apiClient.sendCommand(device.id, {
+				command: 'Operation',
+				dataKey: 'airState.operation',
+				dataValue: THINQ_OPERATION_ON,
+			});
+		}),
+	);
+
+	airConditioner.addCommandHandler(
+		'off',
+		withErrorHandling('off', logger, async () => {
+			logger.debug(
+				`ThinQ AirConditioner ${device.id}: 'off' command handler invoked, capabilities=${JSON.stringify(capabilities)}`,
+			);
+			await apiClient.sendCommand(device.id, {
+				command: 'Operation',
+				dataKey: 'airState.operation',
+				dataValue: THINQ_OPERATION_OFF,
+			});
+		}),
+	);
+
+	airConditioner.subscribeAttribute(
+		Thermostat.id,
+		'occupiedCoolingSetpoint',
+		(newValue: number, oldValue: number, context) => {
+			if (context.fabric === undefined) {
+				return;
+			}
+			logger.debug(
+				`ThinQ AirConditioner ${device.id}: 'occupiedCoolingSetpoint' command handler invoked, newValue=${newValue}, capabilities=${JSON.stringify(capabilities)}`,
+			);
+			void withErrorHandling('occupiedCoolingSetpoint', logger, async () => {
+				await apiClient.sendCommand(device.id, {
+					dataKey: 'airState.tempState.target',
+					dataValue: roundToStep(newValue / 100, THINQ_TEMPERATURE_STEP_CELSIUS),
+				});
+			})().catch(revertSetpointOnFailure(airConditioner, 'occupiedCoolingSetpoint', oldValue));
+		},
+		airConditioner.log,
+	);
+
+	if (capabilities.supportsHeat) {
+		airConditioner.subscribeAttribute(
+			Thermostat.id,
+			'occupiedHeatingSetpoint',
+			(newValue: number, oldValue: number, context) => {
+				if (context.fabric === undefined) {
+					return;
+				}
+				logger.debug(
+					`ThinQ AirConditioner ${device.id}: 'occupiedHeatingSetpoint' command handler invoked, newValue=${newValue}, capabilities=${JSON.stringify(capabilities)}`,
+				);
+				void withErrorHandling('occupiedHeatingSetpoint', logger, async () => {
+					await apiClient.sendCommand(device.id, {
+						dataKey: 'airState.tempState.target',
+						dataValue: roundToStep(newValue / 100, THINQ_TEMPERATURE_STEP_CELSIUS),
+					});
+				})().catch(revertSetpointOnFailure(airConditioner, 'occupiedHeatingSetpoint', oldValue));
+			},
+			airConditioner.log,
+		);
+	}
+
+	airConditioner.subscribeAttribute(
+		FanControl,
+		'percentSetting',
+		(newValue, _oldValue, context) => {
+			if (context.fabric === undefined) {
+				return;
+			}
+			logger.debug(
+				`ThinQ AirConditioner ${device.id}: 'percentSetting' command handler invoked, newValue=${newValue}, capabilities=${JSON.stringify(capabilities)}`,
+			);
+			if (!capabilities.supportsFanSpeedControl) {
+				logger.debug(
+					`ThinQ AirConditioner ${device.id}: ignoring percentSetting change — fan speed control not supported per configured capabilities.`,
+				);
+				return;
+			}
+			if (newValue === null || !isValidNumber(newValue, 0, 100)) {
+				return;
+			}
+			const windStrength = mapPercentToWindStrength(newValue);
+			if (windStrength === undefined) {
+				logger.debug(`ThinQ AirConditioner ${device.id}: ignoring percentSetting=0 (ambiguous, no ThinQ equivalent).`);
+				return;
+			}
+			void withErrorHandling('percentSetting', logger, async () => {
+				await apiClient.sendCommand(device.id, {
+					dataKey: 'airState.windStrength',
+					dataValue: windStrength,
+				});
+			})();
+		},
+		airConditioner.log,
+	);
+
+	airConditioner.subscribeAttribute(
+		FanControl,
+		'fanMode',
+		(newValue: FanControl.FanMode, _oldValue: FanControl.FanMode, context) => {
+			if (context.fabric === undefined) {
+				return;
+			}
+			logger.debug(
+				`ThinQ AirConditioner ${device.id}: 'fanMode' command handler invoked, newValue=${FanControl.FanMode[newValue]}, capabilities=${JSON.stringify(capabilities)}`,
+			);
+			if (!capabilities.supportsFanSpeedControl) {
+				logger.debug(
+					`ThinQ AirConditioner ${device.id}: ignoring fanMode change — fan speed control not supported per configured capabilities.`,
+				);
+				return;
+			}
+			const windStrength = mapFanModeToWindStrength(newValue);
+			if (windStrength === undefined) {
+				logger.debug(
+					`ThinQ AirConditioner ${device.id}: ignoring fanMode=${FanControl.FanMode[newValue]} (no ThinQ equivalent).`,
+				);
+				return;
+			}
+			void withErrorHandling('fanMode', logger, async () => {
+				await apiClient.sendCommand(device.id, {
+					dataKey: 'airState.windStrength',
+					dataValue: windStrength,
+				});
+			})();
+		},
+		airConditioner.log,
+	);
+
+	if (capabilities.supportsSwingMode) {
+		airConditioner.subscribeAttribute(
+			FanControl,
+			'rockSetting',
+			(newValue: unknown, oldValue: unknown, context) => {
+				if (context.fabric === undefined) {
+					return;
+				}
+
+				const newRock = newValue as Record<string, boolean> | undefined;
+				const oldRock = oldValue as Record<string, boolean> | undefined;
+
+				logger.debug(
+					`ThinQ AirConditioner ${device.id}: 'rockSetting' command handler invoked, newValue=${JSON.stringify(newRock)}, capabilities=${JSON.stringify(capabilities)}`,
+				);
+
+				if (!newRock || !oldRock) {
+					return;
+				}
+
+				const verticalChanged = newRock.rockUpDown !== oldRock.rockUpDown;
+				const horizontalChanged = newRock.rockLeftRight !== oldRock.rockLeftRight;
+
+				if (!verticalChanged && !horizontalChanged) {
+					return;
+				}
+
+				void withErrorHandling('rockSetting', logger, async () => {
+					if (verticalChanged && horizontalChanged && newRock.rockUpDown && newRock.rockLeftRight) {
+						await apiClient.sendCommand(device.id, {
+							dataKey: null,
+							dataValue: null,
+							command: 'Set',
+							ctrlKey: 'favoriteCtrl',
+							dataSetList: {
+								'airState.wDir.vStep': '100',
+								'airState.wDir.hStep': '100',
+							},
+						});
+					} else {
+						if (verticalChanged) {
+							await apiClient.sendCommand(device.id, {
+								dataKey: 'airState.wDir.vStep',
+								dataValue: newRock.rockUpDown ? '100' : '0',
+							});
+						}
+						if (horizontalChanged) {
+							await apiClient.sendCommand(device.id, {
+								dataKey: 'airState.wDir.hStep',
+								dataValue: newRock.rockLeftRight ? '100' : '0',
+							});
+						}
+					}
+				})();
+			},
+			airConditioner.log,
+		);
+	}
+}

package/src/platform/thinq/thinqAirConditionerEndpointFactory.ts

@@ -0,0 +1,145 @@
+import {
+	airQualitySensor,
+	electricalSensor,
+	humiditySensor,
+	MatterbridgeEndpoint,
+	powerSource,
+	roomAirConditioner,
+} from 'matterbridge';
+import { AirQuality, FanControl, PowerTopology } from 'matterbridge/matter/clusters';
+
+import type { ThinqAirConditionerDevice } from '../../core/domain/entities/ThinqDevice.js';
+import type { AirConditionerCapabilities } from '../../core/domain/value-objects/AirConditionerCapabilities.js';
+
+export interface AirConditionerEndpointSetpoints {
+	currentTemperature: number;
+	targetTemperature: number;
+	minHeatSetpointLimitCelsius: number;
+	maxHeatSetpointLimitCelsius: number;
+	minCoolSetpointLimitCelsius: number;
+	maxCoolSetpointLimitCelsius: number;
+}
+
+/**
+ * Hand-composes an `AirConditioner`-shaped `MatterbridgeEndpoint`, mirroring
+ * `@matterbridge/core`'s own `AirConditioner` constructor, but branching the
+ * Thermostat/FanControl cluster construction on the device's configured capabilities
+ * (`Behaviors.require()` throws on a 2nd call for the same cluster id, so the feature
+ * set must be chosen up-front — see `.claude/memory.md`).
+ */
+export interface BuildAirConditionerEndpointOptions {
+	vendorId?: number;
+	vendorName?: string;
+	productId?: number;
+	productName?: string;
+}
+
+export function buildAirConditionerEndpoint(
+	device: ThinqAirConditionerDevice,
+	capabilities: AirConditionerCapabilities,
+	setpoints: AirConditionerEndpointSetpoints,
+	initialFanMode: FanControl.FanMode,
+	options?: BuildAirConditionerEndpointOptions,
+): MatterbridgeEndpoint {
+	const {
+		currentTemperature,
+		targetTemperature,
+		minHeatSetpointLimitCelsius,
+		maxHeatSetpointLimitCelsius,
+		minCoolSetpointLimitCelsius,
+		maxCoolSetpointLimitCelsius,
+	} = setpoints;
+
+	const endpoint = new MatterbridgeEndpoint(
+		capabilities.supportsEnergyMonitoring
+			? [roomAirConditioner, powerSource, electricalSensor]
+			: [roomAirConditioner, powerSource],
+		{
+			id: `${device.name.replaceAll(' ', '')}-${device.id.replaceAll(' ', '')}`,
+		},
+	)
+		.createDefaultIdentifyClusterServer()
+		.createDefaultBasicInformationClusterServer(
+			device.name,
+			device.id,
+			options?.vendorId ?? 0xfff1,
+			options?.vendorName ?? 'Matterbridge',
+			options?.productId ?? 0x8000,
+			options?.productName ?? 'Matterbridge Air Conditioner',
+		)
+		.createDefaultPowerSourceWiredClusterServer()
+		.createDeadFrontOnOffClusterServer(true);
+
+	if (capabilities.supportsHeat) {
+		endpoint.createDefaultThermostatClusterServer(
+			currentTemperature,
+			targetTemperature,
+			targetTemperature,
+			1,
+			minHeatSetpointLimitCelsius,
+			maxHeatSetpointLimitCelsius,
+			minCoolSetpointLimitCelsius,
+			maxCoolSetpointLimitCelsius,
+		);
+	} else {
+		endpoint.createDefaultCoolingThermostatClusterServer(
+			currentTemperature,
+			targetTemperature,
+			minCoolSetpointLimitCelsius,
+			maxCoolSetpointLimitCelsius,
+		);
+	}
+	endpoint.createDefaultThermostatUserInterfaceConfigurationClusterServer();
+
+	if (capabilities.supportsFanSpeedControl && capabilities.supportsSwingMode) {
+		endpoint.createCompleteFanControlClusterServer(
+			initialFanMode,
+			FanControl.FanModeSequence.OffLowMedHighAuto,
+			0,
+			0,
+			undefined,
+			undefined,
+			undefined,
+			{ rockLeftRight: true, rockUpDown: true, rockRound: true },
+			{ rockLeftRight: false, rockUpDown: false, rockRound: false },
+		);
+	} else if (capabilities.supportsFanSpeedControl) {
+		endpoint.createDefaultFanControlClusterServer(initialFanMode, FanControl.FanModeSequence.OffLowMedHighAuto, 0, 0);
+	} else {
+		endpoint.createOnOffFanControlClusterServer(initialFanMode);
+	}
+
+	if (capabilities.supportsHumiditySensor) {
+		// RelativeHumidityMeasurement is spec-legal directly on roomAirConditioner, but Apple Home only builds a
+		// Humidity service from an endpoint actually typed humiditySensor (confirmed by regression: moving this
+		// onto the AC's own endpoint made the reading disappear from Apple Home entirely). Keep as a child.
+		endpoint
+			.addChildDeviceType('HumiditySensor', [humiditySensor])
+			.createDefaultIdentifyClusterServer()
+			.createDefaultRelativeHumidityMeasurementClusterServer(0);
+	}
+
+	if (capabilities.supportsAirQualitySensor) {
+		endpoint
+			.addChildDeviceType('AirQualitySensor', [airQualitySensor])
+			.createDefaultIdentifyClusterServer()
+			.createDefaultAirQualityClusterServer(AirQuality.AirQualityEnum.Unknown)
+			.createDefaultPm25ConcentrationMeasurementClusterServer()
+			.createDefaultPm10ConcentrationMeasurementClusterServer();
+	}
+
+	if (capabilities.supportsEnergyMonitoring) {
+		// Electrical measurement lives on the AC endpoint itself (electricalSensor device type). PowerTopology is
+		// mandatory for electricalSensor; NodeTopology because the AC is now its own standalone Matter node (server
+		// mode), not shared with a bridge. activePower starts at 0 (not null) because Apple may hide null.
+		endpoint
+			.createDefaultPowerTopologyClusterServer(PowerTopology.Feature.NodeTopology)
+			.createDefaultElectricalPowerMeasurementClusterServer(null, null, 0, null);
+	}
+
+	if (capabilities.supportsFilterMonitoring) {
+		endpoint.createDefaultHepaFilterMonitoringClusterServer();
+	}
+
+	return endpoint;
+}