matterbridge-lg-thinq-plugin 0.1.0

package/src/platform/thinq/thinqDeviceConfigurator.ts

@@ -0,0 +1,191 @@
+import { MatterbridgeEndpoint } from 'matterbridge';
+import { AnsiLogger } from 'matterbridge/logger';
+import { FanControl } from 'matterbridge/matter/clusters';
+
+import type { ThinqAirConditionerDevice, ThinqWasherDevice } from '../../core/domain/entities/ThinqDevice.js';
+import type { ThinqApiClient } from '../../services/thinq/thinqApiClient.js';
+import { PlatformConfigManager } from '../platformConfigManager.js';
+import {
+	registerAirConditionerCommandHandlers,
+	THINQ_FAN_SPEED_AUTO,
+	THINQ_FAN_SPEED_LOW,
+	THINQ_FAN_SPEED_MEDIUM,
+} from './thinqAirConditionerCommandHandlers.js';
+import { buildAirConditionerEndpoint } from './thinqAirConditionerEndpointFactory.js';
+import { registerFilterResetCommandHandler } from './thinqAirConditionerFilterResetCommandHandler.js';
+import { registerWasherCommandHandlers } from './thinqWasherCommandHandlers.js';
+import { buildWasherEndpoint } from './thinqWasherEndpointFactory.js';
+import { extractWasherStopCommand, type WasherStopCommandPayload } from './thinqWasherStopCommandResolver.js';
+
+const DEFAULT_TEMPERATURE_CELSIUS = 20;
+const MAX_HEAT_SETPOINT_LIMIT_CELSIUS = 30;
+const MIN_COOL_SETPOINT_LIMIT_CELSIUS = 18;
+
+const DEFAULT_PRODUCT_IDENTITY: Record<'AC' | 'WASHER', { productId: number; productName: string }> = {
+	AC: { productId: 0x8000, productName: 'LG Air Conditioner' },
+	WASHER: { productId: 0x8001, productName: 'LG Washer' },
+};
+
+export function mapWindStrengthToFanMode(windStrength: number | undefined): FanControl.FanMode {
+	if (windStrength === undefined || windStrength === THINQ_FAN_SPEED_AUTO) {
+		return FanControl.FanMode.Auto;
+	}
+	if (windStrength <= THINQ_FAN_SPEED_LOW) {
+		return FanControl.FanMode.Low;
+	}
+	if (windStrength <= THINQ_FAN_SPEED_MEDIUM) {
+		return FanControl.FanMode.Medium;
+	}
+	return FanControl.FanMode.High;
+}
+
+export function mapWindStrengthToFixedFanMode(windStrength: number | undefined): FanControl.FanMode {
+	return windStrength === undefined ? FanControl.FanMode.Off : FanControl.FanMode.High;
+}
+
+/**
+ * Builds Matterbridge `AirConditioner` device endpoints from a ThinQ AirConditioner snapshot
+ * (mirrors `matterbridge-example-dynamic-platform/src/module.ts:2726-2734`).
+ */
+export class ThinqDeviceConfigurator {
+	constructor(
+		private readonly logger: AnsiLogger,
+		private readonly apiClient: ThinqApiClient,
+		private readonly configManager: PlatformConfigManager,
+	) {}
+
+	private resolveProductIdentity(device: ThinqAirConditionerDevice | ThinqWasherDevice): {
+		productId: number;
+		productName: string;
+	} {
+		const productIdOverride = this.configManager.getProductIdForDevice(device.id);
+		const productNameOverride = this.configManager.getProductNameForDevice(device.id);
+		const defaultIdentity = DEFAULT_PRODUCT_IDENTITY[device.type];
+
+		return {
+			productId: productIdOverride ?? defaultIdentity.productId,
+			productName: productNameOverride ?? defaultIdentity.productName,
+		};
+	}
+
+	public async registerAirConditioner(device: ThinqAirConditionerDevice): Promise<MatterbridgeEndpoint> {
+		const snapshot = device.snapshot;
+		const currentTemperature = snapshot.currentTemperatureCelsius ?? DEFAULT_TEMPERATURE_CELSIUS;
+		const targetTemperature = snapshot.targetTemperatureCelsius ?? DEFAULT_TEMPERATURE_CELSIUS;
+		const capabilities = this.configManager.getDeviceCapabilities(device.id);
+
+		this.logger.debug(`registerAirConditioner: entry for deviceId=${device.id}`);
+		this.logger.info(`Registering ThinQ AirConditioner: ${device.name} (${device.id})`);
+
+		const initialFanMode = capabilities.supportsFanSpeedControl
+			? mapWindStrengthToFanMode(snapshot.windStrength)
+			: mapWindStrengthToFixedFanMode(snapshot.windStrength);
+
+		const matterOverride = this.configManager.overrideMatterConfiguration
+			? this.configManager.matterOverrideSettings
+			: undefined;
+		const productIdentity = this.resolveProductIdentity(device);
+
+		const airConditioner = buildAirConditionerEndpoint(
+			device,
+			capabilities,
+			{
+				currentTemperature,
+				targetTemperature,
+				minHeatSetpointLimitCelsius: 0,
+				maxHeatSetpointLimitCelsius: MAX_HEAT_SETPOINT_LIMIT_CELSIUS,
+				minCoolSetpointLimitCelsius: MIN_COOL_SETPOINT_LIMIT_CELSIUS,
+				maxCoolSetpointLimitCelsius: 50,
+			},
+			initialFanMode,
+			{
+				vendorId: matterOverride?.matterVendorId,
+				vendorName: matterOverride?.matterVendorName,
+				productId: productIdentity.productId,
+				productName: productIdentity.productName,
+			},
+		)
+			.createDefaultTemperatureMeasurementClusterServer(currentTemperature * 100)
+			.addRequiredClusterServers();
+
+		// Hardcoded: the AC is always exposed as its own standalone Matter node (server mode) so it can get its own
+		// power tile in Apple Home. Not user-configurable.
+		airConditioner.mode = 'server';
+
+		registerAirConditionerCommandHandlers(airConditioner, device, this.apiClient, this.logger, capabilities);
+
+		const filterResetControl = this.configManager.getAcFilterControlConfig(device.id);
+		registerFilterResetCommandHandler(
+			airConditioner,
+			device,
+			this.apiClient,
+			this.logger,
+			capabilities,
+			filterResetControl,
+		);
+
+		this.logger.debug(`registerAirConditioner: completed for deviceId=${device.id}`);
+		return Promise.resolve(airConditioner);
+	}
+
+	public async registerWasher(device: ThinqWasherDevice): Promise<MatterbridgeEndpoint> {
+		this.logger.debug(`registerWasher: entry for deviceId=${device.id}`);
+		this.logger.info(`Registering ThinQ Washer: ${device.name} (${device.id})`);
+
+		const matterOverride = this.configManager.overrideMatterConfiguration
+			? this.configManager.matterOverrideSettings
+			: undefined;
+		const productIdentity = this.resolveProductIdentity(device);
+
+		const washer = buildWasherEndpoint(device, {
+			vendorId: matterOverride?.matterVendorId,
+			vendorName: matterOverride?.matterVendorName,
+			productId: productIdentity.productId,
+			productName: productIdentity.productName,
+		});
+
+		// Hardcoded: the washer is always exposed as its own standalone Matter node (server mode), matching the AC.
+		washer.mode = 'server';
+
+		const washerControl = this.configManager.getWasherControlConfig(device.id);
+		const stopCommandPayload = await this.resolveWasherStopCommandPayload(device);
+		registerWasherCommandHandlers(washer, device, this.apiClient, this.logger, washerControl, stopCommandPayload);
+
+		this.logger.debug(`registerWasher: completed for deviceId=${device.id}`);
+		return washer;
+	}
+
+	/**
+	 * Resolves a real `WMStop`/`WMOff` command payload from the device's own downloaded model JSON.
+	 * Runs unconditionally at registration (read-only GET, no washer state mutated) regardless of
+	 * whether `washerControl.allowRemoteStop` is set, so the resolved payload is visible in the logs
+	 * for manual sanity-checking before the opt-in flag is ever turned on. Never throws — any
+	 * fetch/parse failure resolves to `undefined`, so a broken model-JSON URL can never block
+	 * washer registration.
+	 */
+	private async resolveWasherStopCommandPayload(
+		device: ThinqWasherDevice,
+	): Promise<WasherStopCommandPayload | undefined> {
+		if (!device.modelJsonUri) {
+			return undefined;
+		}
+
+		try {
+			const model = await this.apiClient.getDeviceModel(device.modelJsonUri);
+			const payload = extractWasherStopCommand(model);
+			if (payload) {
+				this.logger.info(
+					`ThinQ Washer ${device.id}: resolved stop-command payload from device model: ${JSON.stringify(payload)}`,
+				);
+			} else {
+				this.logger.info(`ThinQ Washer ${device.id}: device model has no WMStop/WMOff entry.`);
+			}
+			return payload;
+		} catch (error) {
+			this.logger.debug(
+				`ThinQ Washer ${device.id}: failed to resolve stop-command payload from device model: ${error instanceof Error ? error.message : String(error)}`,
+			);
+			return undefined;
+		}
+	}
+}

package/src/platform/thinq/thinqDeviceDiscovery.test.ts

@@ -0,0 +1,173 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { ThinqDevice } from '../../core/domain/entities/ThinqDevice.js';
+import type { ThinqDeviceService } from '../../services/thinq/thinqDeviceService.js';
+import { asPartial, createMockLogger } from '../../tests/helpers/testUtils.js';
+import { ThinqDeviceDiscovery } from './thinqDeviceDiscovery.js';
+
+describe('ThinqDeviceDiscovery', () => {
+	let mockDeviceService: ThinqDeviceService;
+	let mockLogger: ReturnType<typeof createMockLogger>;
+	let discovery: ThinqDeviceDiscovery;
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockLogger = createMockLogger();
+		mockDeviceService = asPartial<ThinqDeviceService>({
+			discoverDevices: vi.fn(),
+		});
+		discovery = new ThinqDeviceDiscovery(mockDeviceService, mockLogger);
+	});
+
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	describe('discoverDevices', () => {
+		it('should return empty array when no devices discovered', async () => {
+			vi.mocked(mockDeviceService.discoverDevices).mockResolvedValue([]);
+
+			const result = await discovery.discoverDevices();
+
+			expect(result).toEqual([]);
+		});
+
+		it('should include AC device type', async () => {
+			const acDevice = asPartial<ThinqDevice>({
+				type: 'AC',
+				id: 'device-ac-1',
+				name: 'Air Conditioner',
+				modelName: 'ModelXYZ',
+				online: true,
+			});
+			vi.mocked(mockDeviceService.discoverDevices).mockResolvedValue([acDevice]);
+
+			const result = await discovery.discoverDevices();
+
+			expect(result).toHaveLength(1);
+			expect(result[0].type).toBe('AC');
+		});
+
+		it('should include WASHER device type (v1 support)', async () => {
+			const washerDevice = asPartial<ThinqDevice>({
+				type: 'WASHER',
+				id: 'device-washer-1',
+				name: 'Washer',
+				modelName: 'VCDWL_QEUK',
+				online: true,
+			});
+			vi.mocked(mockDeviceService.discoverDevices).mockResolvedValue([washerDevice]);
+
+			const result = await discovery.discoverDevices();
+
+			expect(result).toHaveLength(1);
+			expect(result[0].type).toBe('WASHER');
+		});
+
+		it('should skip unsupported washer variants (WASHER_NEW)', async () => {
+			const washerNewDevice = asPartial<ThinqDevice>({
+				type: 'WASHER_NEW',
+				id: 'device-washer-new-1',
+				name: 'Washer New',
+			});
+			vi.mocked(mockDeviceService.discoverDevices).mockResolvedValue([washerNewDevice]);
+
+			await discovery.discoverDevices();
+
+			expect(mockLogger.info).toHaveBeenCalledWith(
+				expect.stringContaining('ThinQ device type not supported, skipping: WASHER_NEW'),
+			);
+		});
+
+		it('should log device ID in skip message', async () => {
+			const device = asPartial<ThinqDevice>({
+				type: 'REFRIGERATOR',
+				id: 'test-device-id-123',
+				name: 'Fridge',
+			});
+			vi.mocked(mockDeviceService.discoverDevices).mockResolvedValue([device]);
+
+			await discovery.discoverDevices();
+
+			expect(mockLogger.info).toHaveBeenCalledWith(expect.stringContaining('test-device-id-123'));
+		});
+
+		it('should filter supported and unsupported devices correctly', async () => {
+			const acDevice = asPartial<ThinqDevice>({
+				type: 'AC',
+				id: 'device-ac-1',
+				name: 'Air Conditioner',
+			});
+			const washerDevice = asPartial<ThinqDevice>({
+				type: 'WASHER',
+				id: 'device-washer-1',
+				name: 'Washer',
+			});
+			const anotherAcDevice = asPartial<ThinqDevice>({
+				type: 'AC',
+				id: 'device-ac-2',
+				name: 'Bedroom AC',
+			});
+			const dishwasherDevice = asPartial<ThinqDevice>({
+				type: 'DISHWASHER',
+				id: 'device-dw-1',
+				name: 'Dishwasher',
+			});
+
+			vi.mocked(mockDeviceService.discoverDevices).mockResolvedValue([
+				acDevice,
+				washerDevice,
+				anotherAcDevice,
+				dishwasherDevice,
+			]);
+
+			const result = await discovery.discoverDevices();
+
+			expect(result).toHaveLength(3);
+			expect(result[0].id).toBe('device-ac-1');
+			expect(result[1].id).toBe('device-washer-1');
+			expect(result[2].id).toBe('device-ac-2');
+		});
+
+		it('should properly narrow AC device type', async () => {
+			const acDevice = asPartial<ThinqDevice>({
+				type: 'AC',
+				id: 'device-ac-1',
+				name: 'Air Conditioner',
+				modelName: 'Model123',
+				online: true,
+			});
+			vi.mocked(mockDeviceService.discoverDevices).mockResolvedValue([acDevice]);
+
+			const result = await discovery.discoverDevices();
+
+			expect(result).toHaveLength(1);
+			const discoveredDevice = result[0];
+			// The dispatch method should return the device with AC type narrowed
+			expect(discoveredDevice.type).toBe('AC');
+		});
+
+		it('should propagate errors from device service', async () => {
+			const error = new Error('Device discovery failed');
+			vi.mocked(mockDeviceService.discoverDevices).mockRejectedValue(error);
+
+			await expect(discovery.discoverDevices()).rejects.toThrow('Device discovery failed');
+		});
+
+		it('should skip devices with other types like DRYER, REFRIGERATOR, OVEN', async () => {
+			const devices: ThinqDevice[] = [
+				asPartial<ThinqDevice>({ type: 'DRYER', id: 'device-1' }),
+				asPartial<ThinqDevice>({ type: 'REFRIGERATOR', id: 'device-2' }),
+				asPartial<ThinqDevice>({ type: 'OVEN', id: 'device-3' }),
+				asPartial<ThinqDevice>({ type: 'MICROWAVE', id: 'device-4' }),
+				asPartial<ThinqDevice>({ type: 'AC', id: 'device-5' }),
+			];
+			vi.mocked(mockDeviceService.discoverDevices).mockResolvedValue(devices);
+
+			const result = await discovery.discoverDevices();
+
+			expect(result).toHaveLength(1);
+			expect(result[0].id).toBe('device-5');
+		});
+	});
+});

package/src/platform/thinq/thinqDeviceDiscovery.ts

@@ -0,0 +1,51 @@
+import { AnsiLogger } from 'matterbridge/logger';
+
+import type {
+	ThinqAirConditionerDevice,
+	ThinqDevice,
+	ThinqWasherDevice,
+} from '../../core/domain/entities/ThinqDevice.js';
+import { ThinqDeviceService } from '../../services/thinq/thinqDeviceService.js';
+
+/**
+ * Dispatches discovered ThinQ devices to their typed device entity, keyed by `deviceType` string
+ * (ports `Helper.make`, `homebridge-lg-thinq/src/helper.ts:32-49`). Supports AirConditioner ('AC') and
+ * Washer ('WASHER') — every other type is unregistered (returns `undefined`), matching the source's
+ * `unregisterUnsupportedDevice` fail-closed behavior.
+ */
+export class ThinqDeviceDiscovery {
+	constructor(
+		private readonly deviceService: ThinqDeviceService,
+		private readonly logger: AnsiLogger,
+	) {}
+
+	public async discoverDevices(): Promise<ThinqDevice[]> {
+		const devices = await this.deviceService.discoverDevices();
+		this.logger.debug(`ThinQ discoverDevices: ${devices.length} raw device(s) returned before filtering`);
+		const supported: ThinqDevice[] = [];
+
+		for (const device of devices) {
+			const resolved = this.dispatch(device);
+			if (resolved) {
+				supported.push(resolved);
+				continue;
+			}
+
+			this.logger.info(`ThinQ device type not supported, skipping: ${device.type} (${device.id})`);
+		}
+
+		this.logger.debug(`ThinQ discoverDevices: ${supported.length} device(s) supported after filtering`);
+		return supported;
+	}
+
+	private dispatch(device: ThinqDevice): ThinqAirConditionerDevice | ThinqWasherDevice | undefined {
+		switch (device.type) {
+			case 'AC':
+				return { ...device, type: 'AC' };
+			case 'WASHER':
+				return { ...device, type: 'WASHER' };
+			default:
+				return undefined;
+		}
+	}
+}

package/src/platform/thinq/thinqWasherCommandHandlers.ts

@@ -0,0 +1,120 @@
+import { MatterbridgeEndpoint } from 'matterbridge';
+import { AnsiLogger } from 'matterbridge/logger';
+import { LaundryWasherMode, OnOff, OperationalState } from 'matterbridge/matter/clusters';
+
+import type { ThinqWasherDevice } from '../../core/domain/entities/ThinqDevice.js';
+import type { ThinqWasherControlConfig } from '../../model/LgThinqPluginPlatformConfig.js';
+import type { ThinqApiClient } from '../../services/thinq/thinqApiClient.js';
+import type { WasherStopCommandPayload } from './thinqWasherStopCommandResolver.js';
+
+/**
+ * v1 washer support is read-only telemetry only (mirrors `homebridge-lg-thinq`'s own washer
+ * implementation), except for `stop` (v2, real command — see `registerWasherCommandHandlers`).
+ * Every command in this list throws before any real ThinQ call happens. Because the currently
+ * installed matterbridge dispatches commands without awaiting the handler (see revert helpers
+ * below), each throw is paired with a best-effort revert so Apple Home self-corrects immediately
+ * instead of showing a value ThinQ never accepted.
+ */
+const READ_ONLY_WASHER_COMMANDS = ['on', 'off', 'pause', 'start', 'resume', 'changeToMode'] as const;
+
+const ON_OFF_COMMANDS = new Set<(typeof READ_ONLY_WASHER_COMMANDS)[number]>(['on', 'off']);
+
+/**
+ * Reverts `OnOff.onOff` back to `oldValue` after a rejected command, so Apple Home self-corrects
+ * immediately instead of showing a value ThinQ never accepted. Best-effort: `updateAttribute`
+ * failures are swallowed since the rejection is already logged by the caller.
+ */
+function revertOnOffOnFailure(washer: MatterbridgeEndpoint, oldValue: boolean): void {
+	washer.updateAttribute(OnOff.id, 'onOff', oldValue, washer.log).catch(() => {
+		// Best-effort revert; rejection already logged by the caller.
+	});
+}
+
+/**
+ * Reverts `OperationalState.operationalState` (and, for `changeToMode`, `LaundryWasherMode.currentMode`)
+ * back to their last-known-correct values after a rejected command. Best-effort: `updateAttribute`
+ * failures are swallowed since the rejection is already logged by the caller.
+ */
+function revertOperationalStateOnFailure(
+	washer: MatterbridgeEndpoint,
+	oldOperationalState: number,
+	command: (typeof READ_ONLY_WASHER_COMMANDS)[number],
+	oldCurrentMode: number,
+): void {
+	washer.updateAttribute(OperationalState.id, 'operationalState', oldOperationalState, washer.log).catch(() => {
+		// Best-effort revert; rejection already logged by the caller.
+	});
+
+	if (command === 'changeToMode') {
+		washer.updateAttribute(LaundryWasherMode.id, 'currentMode', oldCurrentMode, washer.log).catch(() => {
+			// Best-effort revert; rejection already logged by the caller.
+		});
+	}
+}
+
+export function registerWasherCommandHandlers(
+	washer: MatterbridgeEndpoint,
+	device: ThinqWasherDevice,
+	apiClient: ThinqApiClient,
+	logger: AnsiLogger,
+	washerControl: ThinqWasherControlConfig,
+	stopCommandPayload: WasherStopCommandPayload | undefined,
+): void {
+	for (const command of READ_ONLY_WASHER_COMMANDS) {
+		washer.addCommandHandler(command, async () => {
+			logger.warn(`ThinQ Washer remote control ('${command}') is not supported yet (deviceId=${device.id})`);
+
+			if (ON_OFF_COMMANDS.has(command)) {
+				const previousOnOff = washer.getAttribute(OnOff.id, 'onOff') as boolean | undefined;
+				revertOnOffOnFailure(washer, previousOnOff ?? false);
+			} else {
+				const previousOperationalState = washer.getAttribute(OperationalState.id, 'operationalState') as
+					number | undefined;
+				const previousCurrentMode = washer.getAttribute(LaundryWasherMode.id, 'currentMode') as number | undefined;
+				revertOperationalStateOnFailure(
+					washer,
+					previousOperationalState ?? OperationalState.OperationalStateEnum.Stopped,
+					command,
+					previousCurrentMode ?? 0,
+				);
+			}
+
+			throw new Error(`ThinQ Washer remote control ('${command}') is not supported yet`);
+		});
+	}
+
+	washer.addCommandHandler('stop', async () => {
+		if (!washerControl.allowRemoteStop) {
+			logger.warn(`ThinQ Washer remote control ('stop') is disabled by configuration (deviceId=${device.id})`);
+			throw new Error(`ThinQ Washer remote control ('stop') is disabled by configuration.`);
+		}
+
+		if (!stopCommandPayload) {
+			logger.warn(
+				`ThinQ Washer remote control ('stop') is not available for this device model yet (deviceId=${device.id})`,
+			);
+			throw new Error(`ThinQ Washer remote control ('stop') is not available for this device model yet.`);
+		}
+
+		const previousState = washer.getAttribute(OperationalState.id, 'operationalState') as number | undefined;
+
+		try {
+			await apiClient.sendCommand(device.id, { ctrlKey: 'WMControl', ...stopCommandPayload });
+		} catch (error) {
+			logger.error(
+				`ThinQ Washer command 'stop' failed: ${error instanceof Error ? error.message : String(error)} (deviceId=${device.id})`,
+			);
+			washer
+				.updateAttribute(
+					OperationalState.id,
+					'operationalState',
+					previousState ?? OperationalState.OperationalStateEnum.Stopped,
+					washer.log,
+				)
+				.catch(() => {
+					// Best-effort revert; original failure already logged above.
+				});
+			throw error;
+		}
+	});
+}

package/src/platform/thinq/thinqWasherEndpointFactory.ts

@@ -0,0 +1,37 @@
+import { MatterbridgeEndpoint } from 'matterbridge';
+import { LaundryWasher } from 'matterbridge/devices';
+
+import type { ThinqWasherDevice } from '../../core/domain/entities/ThinqDevice.js';
+
+/**
+ * Options for building a washer endpoint with custom vendor/product identity.
+ * Mirrors `BuildAirConditionerEndpointOptions` field-for-field.
+ */
+export interface BuildWasherEndpointOptions {
+	vendorId?: number;
+	vendorName?: string;
+	productId?: number;
+	productName?: string;
+}
+
+/**
+ * Builds a Matterbridge `LaundryWasher`-shaped endpoint for a ThinQ Washer device.
+ * `LaundryWasher`'s constructor already self-composes every mandatory cluster (OnOff DeadFront,
+ * LaundryWasherMode, LaundryWasherControls, TemperatureControl, OperationalState) — no capability
+ * gating or extra cluster-server calls are needed, unlike the AirConditioner's hand-composed pattern.
+ */
+export function buildWasherEndpoint(
+	device: ThinqWasherDevice,
+	options?: BuildWasherEndpointOptions,
+): MatterbridgeEndpoint {
+	const washer = new LaundryWasher(device.name, device.id);
+	washer.createDefaultBasicInformationClusterServer(
+		device.name,
+		device.id,
+		options?.vendorId ?? 0xfff1,
+		options?.vendorName ?? 'Matterbridge',
+		options?.productId ?? 0x8000,
+		options?.productName ?? 'Matterbridge Laundry Washer',
+	);
+	return washer;
+}

package/src/platform/thinq/thinqWasherStateSync.ts

@@ -0,0 +1,60 @@
+import { MatterbridgeEndpoint } from 'matterbridge';
+import { AnsiLogger } from 'matterbridge/logger';
+import { OnOff, OperationalState } from 'matterbridge/matter/clusters';
+
+import type { ThinqSnapshot } from '../../core/domain/value-objects/ThinqSnapshot.js';
+
+/** Maps a ThinQ washer snapshot to a Matter `OperationalState.OperationalStateEnum`. */
+export function mapWasherStateToOperationalState(snapshot: ThinqSnapshot): OperationalState.OperationalStateEnum {
+	if (snapshot.isWasherError) {
+		return OperationalState.OperationalStateEnum.Error;
+	}
+	if (snapshot.isWasherRunning) {
+		return OperationalState.OperationalStateEnum.Running;
+	}
+	if (snapshot.washerRawState === 'PAUSE') {
+		return OperationalState.OperationalStateEnum.Paused;
+	}
+	return OperationalState.OperationalStateEnum.Stopped;
+}
+
+/**
+ * Pushes a freshly polled ThinQ Washer snapshot onto the Matter `LaundryWasher` endpoint's attributes
+ * (device → Apple Home). Read-only v1: no washer-specific commands are ever sent back.
+ */
+export async function applyThinqSnapshotToWasher(
+	washer: MatterbridgeEndpoint,
+	snapshot: ThinqSnapshot,
+	logger: AnsiLogger,
+): Promise<void> {
+	const deviceId = washer.serialNumber ?? washer.uniqueId ?? 'unknown';
+
+	if (snapshot.washerRawState === undefined) {
+		logger.debug(`applyThinqSnapshotToWasher: skipped (source key absent): washerDryer.state, deviceId=${deviceId}`);
+		return;
+	}
+
+	logger.debug(`applyThinqSnapshotToWasher: entry for deviceId=${deviceId}`);
+
+	await washer.updateAttribute(OnOff.id, 'onOff', snapshot.isWasherPowerOn, logger);
+	await washer.updateAttribute(
+		OperationalState.id,
+		'operationalState',
+		mapWasherStateToOperationalState(snapshot),
+		logger,
+	);
+	await washer.updateAttribute(
+		OperationalState.id,
+		'operationalError',
+		{
+			errorStateId: snapshot.isWasherError
+				? OperationalState.ErrorState.UnableToCompleteOperation
+				: OperationalState.ErrorState.NoError,
+		},
+		logger,
+	);
+
+	if (snapshot.washerRemainingDurationSeconds !== undefined) {
+		await washer.updateAttribute(OperationalState.id, 'countdownTime', snapshot.washerRemainingDurationSeconds, logger);
+	}
+}