matterbridge-lg-thinq-plugin 0.1.0

package/src/core/domain/value-objects/ThinqSnapshot.ts

@@ -0,0 +1,162 @@
+/**
+ * ThinQ `washerDryer.state` values that do NOT count as "actively running" (ported verbatim from
+ * `homebridge-lg-thinq/src/devices/WasherDryer.ts:14-15`).
+ */
+const WASHER_NOT_RUNNING_STATES = [
+	'COOLDOWN',
+	'POWEROFF',
+	'POWERFAIL',
+	'INITIAL',
+	'PAUSE',
+	'AUDIBLE_DIAGNOSIS',
+	'FIRMWARE',
+	'COURSE_DOWNLOAD',
+	'ERROR',
+	'END',
+];
+
+/**
+ * Typed accessor over a ThinQ device's raw flat-key snapshot bag (e.g. `airState.opMode`).
+ * Phase 1 only exposes the AirConditioner fields used by `ThinqDeviceConfigurator`.
+ */
+export class ThinqSnapshot {
+	constructor(private readonly data: Record<string, unknown>) {}
+
+	public get raw(): Record<string, unknown> {
+		return this.data;
+	}
+
+	public has(key: string): boolean {
+		const value = this.data[key];
+		return value !== undefined && value !== null;
+	}
+
+	public get isPowerOn(): boolean {
+		return Number(this.data['airState.operation']) === 1;
+	}
+
+	public get currentTemperatureCelsius(): number | undefined {
+		return this.readNumber('airState.tempState.current');
+	}
+
+	public get targetTemperatureCelsius(): number | undefined {
+		return this.readNumber('airState.tempState.target');
+	}
+
+	public get operationMode(): number | undefined {
+		return this.readNumber('airState.opMode');
+	}
+
+	public get windStrength(): number | undefined {
+		return this.readNumber('airState.windStrength');
+	}
+
+	public get online(): boolean | undefined {
+		return typeof this.data.online === 'boolean' ? this.data.online : undefined;
+	}
+
+	public get isJetModeOn(): boolean {
+		return Number(this.data['airState.wMode.jet']) === 1;
+	}
+
+	public get isQuietModeOn(): boolean {
+		return Number(this.data['airState.miscFuncState.silentAWHP']) === 1;
+	}
+
+	public get isEnergySaveModeOn(): boolean {
+		return Number(this.data['airState.powerSave.basic']) === 1;
+	}
+
+	public get isAirCleanModeOn(): boolean {
+		return Number(this.data['airState.wMode.airClean']) === 1;
+	}
+
+	public get isLedOn(): boolean {
+		return Number(this.data['airState.lightingState.displayControl']) === 1;
+	}
+
+	public get isVerticalSwingOn(): boolean {
+		return Number(this.data['airState.wDir.vStep']) === 100;
+	}
+
+	public get isHorizontalSwingOn(): boolean {
+		return Number(this.data['airState.wDir.hStep']) === 100;
+	}
+
+	public get humidityPercent(): number | undefined {
+		const value = this.readNumber('airState.humidity.current');
+		if (value === undefined) {
+			return undefined;
+		}
+		return value > 100 ? value / 10 : value;
+	}
+
+	public get airQualityOverall(): number | undefined {
+		return this.readNumber('airState.quality.overall');
+	}
+
+	public get pm25(): number | undefined {
+		return this.readNumber('airState.quality.PM2');
+	}
+
+	public get pm10(): number | undefined {
+		return this.readNumber('airState.quality.PM10');
+	}
+
+	public get powerConsumptionWatts(): number | undefined {
+		const value = this.readNumber('airState.energy.onCurrent');
+		return value === undefined || Number.isNaN(value) ? undefined : value;
+	}
+
+	private get washerDryer(): Record<string, unknown> | undefined {
+		const value = this.data['washerDryer'];
+		return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined;
+	}
+
+	public get hasWasherDryer(): boolean {
+		return this.washerDryer !== undefined;
+	}
+
+	public get washerRawState(): string | undefined {
+		const value = this.washerDryer?.['state'];
+		return typeof value === 'string' ? value : undefined;
+	}
+
+	public get isWasherPowerOn(): boolean {
+		return this.washerRawState !== undefined && !['POWEROFF', 'POWERFAIL'].includes(this.washerRawState);
+	}
+
+	public get isWasherRunning(): boolean {
+		return (
+			this.isWasherPowerOn &&
+			this.washerRawState !== undefined &&
+			!WASHER_NOT_RUNNING_STATES.includes(this.washerRawState)
+		);
+	}
+
+	public get isWasherError(): boolean {
+		return this.washerRawState === 'ERROR';
+	}
+
+	public get washerRemainingDurationSeconds(): number | undefined {
+		const hours = this.readWasherNumber('remainTimeHour');
+		const minutes = this.readWasherNumber('remainTimeMinute');
+		if (hours === undefined && minutes === undefined) {
+			return undefined;
+		}
+		if (!this.isWasherRunning) {
+			return 0;
+		}
+		return (hours ?? 0) * 3600 + (minutes ?? 0) * 60;
+	}
+
+	private readNumber(key: string): number | undefined {
+		const value = this.data[key];
+		return typeof value === 'number' ? value : undefined;
+	}
+
+	private readWasherNumber(key: string): number | undefined {
+		const value = this.washerDryer?.[key];
+		return typeof value === 'number' ? value : undefined;
+	}
+}

package/src/errors/AuthenticationError.ts

@@ -0,0 +1,37 @@
+import { BaseError } from './BaseError.js';
+
+/** Base error for ThinQ authentication failures. */
+export class AuthenticationError extends BaseError {
+	constructor(message: string, metadata?: Record<string, unknown>) {
+		super(message, 'THINQ_AUTH_ERROR', 401, metadata);
+	}
+}
+
+/** Invalid ThinQ username or password. */
+export class InvalidCredentialsError extends AuthenticationError {
+	constructor(username?: string) {
+		super('Invalid LG ThinQ username or password. Please check your credentials.', {
+			reason: 'INVALID_CREDENTIALS',
+			username,
+		});
+	}
+}
+
+/** ThinQ access token has expired and could not be refreshed. */
+export class TokenExpiredError extends AuthenticationError {
+	constructor() {
+		super('LG ThinQ authentication token has expired. Please log in again.', {
+			reason: 'TOKEN_EXPIRED',
+		});
+	}
+}
+
+/** LG requires a manual action (e.g. accepting new terms, or completing a third-party SSO login) before continuing. */
+export class ManualProcessNeededError extends BaseError {
+	constructor(
+		message = 'LG ThinQ requires a manual process (e.g. accepting new terms in the native LG app) before continuing.',
+		metadata?: Record<string, unknown>,
+	) {
+		super(message, 'MANUAL_PROCESS_NEEDED', 428, metadata);
+	}
+}

package/src/errors/BaseError.ts

@@ -0,0 +1,38 @@
+/**
+ * Base error class for all plugin errors.
+ * Provides common error structure with error codes, status codes, and metadata.
+ */
+export abstract class BaseError extends Error {
+	/**
+	 * Creates a new BaseError instance.
+	 * @param message - Human-readable error message
+	 * @param code - Error code for programmatic handling
+	 * @param statusCode - HTTP-like status code (optional)
+	 * @param metadata - Additional context information
+	 */
+	constructor(
+		message: string,
+		public readonly code: string,
+		public readonly statusCode?: number,
+		public readonly metadata?: Record<string, unknown>,
+	) {
+		super(message);
+		this.name = this.constructor.name;
+		Error.captureStackTrace(this, this.constructor);
+	}
+
+	/**
+	 * Serialize error to JSON for logging.
+	 * @returns Object representation of the error
+	 */
+	toJSON(): Record<string, unknown> {
+		return {
+			name: this.name,
+			message: this.message,
+			code: this.code,
+			statusCode: this.statusCode,
+			metadata: this.metadata,
+			stack: this.stack,
+		};
+	}
+}

package/src/errors/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Error handling module.
+ *
+ * Provides a hierarchical error structure for type-safe error handling throughout the plugin.
+ * All errors extend from BaseError and include error codes, status codes, and metadata.
+ *
+ * @example
+ * ```typescript
+ * import { BaseError } from './errors';
+ *
+ * class MyError extends BaseError {}
+ * ```
+ */
+
+// Base error
+export { BaseError } from './BaseError.js';
+
+// Authentication errors
+export {
+	AuthenticationError,
+	InvalidCredentialsError,
+	ManualProcessNeededError,
+	TokenExpiredError,
+} from './AuthenticationError.js';

package/src/model/LgThinqPluginPlatformConfig.ts

@@ -0,0 +1,94 @@
+import { PlatformConfig } from 'matterbridge';
+
+export interface ThinqDeviceCapabilityConfig {
+	supportsHeat?: boolean;
+	supportsFanSpeedControl?: boolean;
+	supportsSwingMode?: boolean;
+	supportsHumiditySensor?: boolean;
+	supportsAirQualitySensor?: boolean;
+	supportsEnergyMonitoring?: boolean;
+	supportsFilterMonitoring?: boolean;
+}
+
+export interface MatterOverrideSettings {
+	matterVendorName: string;
+	matterVendorId: number;
+}
+
+export interface ThinqWasherControlConfig {
+	allowRemoteStop?: boolean;
+}
+
+export interface ThinqAcFilterControlConfig {
+	allowFilterReset?: boolean;
+}
+
+export interface ThinqDeviceConfigEntry {
+	deviceId: string;
+	deviceType?: 'AC' | 'WASHER';
+	capabilities?: ThinqDeviceCapabilityConfig;
+	productName?: string;
+	productId?: number;
+	washerControl?: ThinqWasherControlConfig;
+	acFilterControl?: ThinqAcFilterControlConfig;
+}
+
+export interface ThinqAuthConfig {
+	loginType: 'account' | 'token';
+	username?: string;
+	password?: string;
+	refreshToken?: string;
+	country: string;
+	language: string;
+	refreshIntervalSeconds?: number;
+	filterMonitoringIntervalSeconds?: number;
+	devices: ThinqDeviceConfigEntry[];
+}
+
+export interface WebosPluginConfig {
+	devices: unknown[];
+}
+
+export interface AdvancedFeatureSetting {
+	debug: boolean;
+	clearStorageOnStartup: boolean;
+	forceAuthentication: boolean;
+	unregisterOnShutdown: boolean;
+	overrideMatterConfiguration: boolean;
+	matterOverrideSettings: MatterOverrideSettings;
+}
+
+export interface AdvancedFeatureConfiguration {
+	settings: AdvancedFeatureSetting;
+}
+
+export interface LgThinqPluginPlatformConfig extends PlatformConfig {
+	thinq: ThinqAuthConfig;
+	webos: WebosPluginConfig;
+	advancedFeature: AdvancedFeatureConfiguration;
+}
+
+export function createDefaultAdvancedFeature(): AdvancedFeatureConfiguration {
+	return {
+		settings: {
+			debug: false,
+			clearStorageOnStartup: false,
+			forceAuthentication: false,
+			unregisterOnShutdown: false,
+			overrideMatterConfiguration: false,
+			matterOverrideSettings: {
+				matterVendorName: 'Matterbridge',
+				matterVendorId: 0xfff1,
+			},
+		},
+	};
+}
+
+export function createDefaultThinqConfig(): ThinqAuthConfig {
+	return {
+		loginType: 'account',
+		country: 'US',
+		language: 'en-US',
+		devices: [],
+	};
+}

package/src/module.ts

@@ -0,0 +1,298 @@
+import Path from 'node:path';
+
+import { MatterbridgeDynamicPlatform, MatterbridgeEndpoint, PlatformConfig, PlatformMatterbridge } from 'matterbridge';
+import { AnsiLogger, LogLevel } from 'matterbridge/logger';
+import NodePersist from 'node-persist';
+
+import { UNREGISTER_DEVICES_DELAY_MS } from './constants/index.js';
+import { isAirConditionerDevice, isWasherDevice } from './core/domain/entities/ThinqDevice.js';
+import { ManualProcessNeededError } from './errors/index.js';
+import { LgThinqPluginPlatformConfig } from './model/LgThinqPluginPlatformConfig.js';
+// Platform layer imports
+import { DeviceRegistry } from './platform/deviceRegistry.js';
+import { PlatformConfigManager } from './platform/platformConfigManager.js';
+import { PlatformState } from './platform/platformState.js';
+import { applyThinqFilterStateToAirConditioner } from './platform/thinq/thinqAirConditionerFilterStateSync.js';
+import { applyThinqSnapshotToAirConditioner } from './platform/thinq/thinqAirConditionerStateSync.js';
+import { reconcileThinqDeviceConfigEntries } from './platform/thinq/thinqDeviceConfigReconciler.js';
+import { applyThinqSnapshotToWasher } from './platform/thinq/thinqWasherStateSync.js';
+import { ThinqServiceContainer } from './services/thinq/serviceContainer.js';
+import { ThinqSession } from './services/thinq/session.js';
+import { ThinqDeviceUpdateListener } from './services/thinq/thinqDeviceService.js';
+import type { ThinqFilterUpdateListener } from './services/thinq/thinqFilterMonitoringService.js';
+import { PLUGIN_NAME } from './settings.js';
+
+export default function initializePlugin(
+	matterbridge: PlatformMatterbridge,
+	log: AnsiLogger,
+	config: PlatformConfig,
+): LgThinqMatterbridgePlatform {
+	return new LgThinqMatterbridgePlatform(matterbridge, log, config as LgThinqPluginPlatformConfig);
+}
+
+/**
+ * LG ThinQ platform for Matterbridge (webOS TV lands in a later phase, see below).
+ * Empty lifecycle skeleton (Phase 0) — device discovery/configuration lands in Phase 1 (ThinQ) and Phase 3 (webOS).
+ */
+export class LgThinqMatterbridgePlatform extends MatterbridgeDynamicPlatform {
+	public persist: NodePersist.LocalStorage;
+
+	// Platform layer
+	public readonly registry: DeviceRegistry;
+	public readonly configManager: PlatformConfigManager;
+	public readonly state: PlatformState;
+
+	// ThinQ family services (Phase 1: auth + discovery + polling, AirConditioner only)
+	public readonly thinqServices: ThinqServiceContainer;
+
+	private thinqPollingIntervalMs: number | undefined;
+	private readonly thinqDeviceKindById = new Map<string, 'AC' | 'WASHER'>();
+	private readonly filterMonitoringDeviceIds: string[] = [];
+
+	constructor(
+		matterbridge: PlatformMatterbridge,
+		logger: AnsiLogger,
+		override config: LgThinqPluginPlatformConfig,
+	) {
+		super(matterbridge, logger, config);
+		logger.logLevel = this.config.advancedFeature.settings.debug ? LogLevel.DEBUG : LogLevel.INFO;
+
+		this.log.info('Initializing platform:', this.config.name);
+
+		// Initialize persistence
+		const persistDir = Path.join(this.matterbridge.matterbridgePluginDirectory, PLUGIN_NAME, 'persist');
+		this.persist = NodePersist.create({ dir: persistDir });
+
+		// Initialize platform layer
+		this.configManager = PlatformConfigManager.create(config, this.log);
+		this.registry = new DeviceRegistry();
+		this.state = new PlatformState();
+		this.thinqServices = new ThinqServiceContainer(
+			this.log,
+			this.persist,
+			this.configManager,
+			Path.join(this.matterbridge.matterbridgePluginDirectory, PLUGIN_NAME, 'mqtt-certs'),
+		);
+	}
+
+	// #region Lifecycle
+	public override async onStart(reason?: string): Promise<void> {
+		this.log.debug(`onStart: entry (reason=${reason ?? 'none'})`);
+		this.log.notice('onStart called with reason:', reason ?? 'none');
+
+		await this.ready;
+		await this.clearSelect();
+		await this.persist.init();
+
+		if (this.configManager.isClearStorageOnStartupEnabled) {
+			this.log.debug('onStart: exit early — clear-storage-on-startup enabled, skipping device startup');
+			return;
+		}
+
+		if (!this.configManager.validateConfig()) {
+			this.log.error('Platform configuration is invalid.');
+			this.state.setStartupCompleted(false);
+			this.log.debug('onStart: exit — invalid platform configuration');
+			return;
+		}
+
+		try {
+			await this.startThinqDevices();
+		} catch (error) {
+			this.log.error(`ThinQ startup failed: ${error instanceof Error ? error.message : String(error)}`);
+			this.state.setStartupCompleted(false);
+			this.log.debug('onStart: exit — ThinQ startup threw');
+			return;
+		}
+
+		this.log.notice('onStart finished');
+		this.state.setStartupCompleted(true);
+		this.log.debug('onStart: exit — startup completed successfully');
+	}
+
+	public override async onConfigure(): Promise<void> {
+		await super.onConfigure();
+		this.log.debug('onConfigure: entry');
+		this.log.notice('onConfigure called');
+
+		if (this.configManager.isClearStorageOnStartupEnabled) {
+			this.log.warn('Clearing persistence storage as per configuration.');
+			await this.persist
+				.clear()
+				.then(() => this.unregisterAllDevices(UNREGISTER_DEVICES_DELAY_MS))
+				.then(() => {
+					this.log.notice('Please restart the platform now.');
+					this.wssSendRestartRequired();
+				})
+				.catch((error: unknown) => {
+					this.log.error(`Error clearing persistence storage: ${error}`);
+				});
+			this.log.debug('onConfigure: exit early — clear-storage-on-startup enabled');
+			return;
+		}
+
+		if (!this.state.isStartupCompleted) {
+			this.log.debug('onConfigure: exit early — startup did not complete, skipping polling setup');
+			return;
+		}
+
+		const applyDeviceUpdate: ThinqDeviceUpdateListener = (deviceId, snapshot) => {
+			const endpoint = this.registry.getDevice(deviceId) as MatterbridgeEndpoint | undefined;
+			if (!endpoint) {
+				this.log.debug(`ThinQ device update received for unregistered device ${deviceId}, skipping.`);
+				return;
+			}
+
+			if (this.thinqDeviceKindById.get(deviceId) === 'WASHER') {
+				void applyThinqSnapshotToWasher(endpoint, snapshot, this.log).catch((error: unknown) => {
+					this.log.error(
+						`Failed to apply ThinQ state update for ${deviceId}: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				});
+				return;
+			}
+
+			void applyThinqSnapshotToAirConditioner(
+				endpoint,
+				snapshot,
+				this.configManager.getDeviceCapabilities(deviceId),
+				this.log,
+			).catch((error: unknown) => {
+				this.log.error(
+					`Failed to apply ThinQ state update for ${deviceId}: ${error instanceof Error ? error.message : String(error)}`,
+				);
+			});
+		};
+
+		this.thinqPollingIntervalMs = this.configManager.thinqRefreshIntervalSeconds * 1000;
+		this.thinqServices.getDeviceService().startPolling(this.thinqPollingIntervalMs, applyDeviceUpdate);
+		this.thinqServices.getDeviceService().startKeepAlive();
+		void this.thinqServices
+			.getMqttListener()
+			.start(applyDeviceUpdate)
+			.catch((error: unknown) => {
+				this.log.error(
+					`ThinQ MQTT listener failed to start: ${error instanceof Error ? error.message : String(error)}`,
+				);
+			});
+
+		if (this.filterMonitoringDeviceIds.length > 0) {
+			const applyFilterUpdate: ThinqFilterUpdateListener = (deviceId, filterState) => {
+				const endpoint = this.registry.getDevice(deviceId) as MatterbridgeEndpoint | undefined;
+				if (!endpoint) {
+					this.log.debug(`ThinQ filter update received for unregistered device ${deviceId}, skipping.`);
+					return;
+				}
+				void applyThinqFilterStateToAirConditioner(endpoint, filterState, this.log).catch((error: unknown) => {
+					this.log.error(
+						`Failed to apply ThinQ filter state update for ${deviceId}: ${error instanceof Error ? error.message : String(error)}`,
+					);
+				});
+			};
+			const filterMonitoringIntervalMs = this.configManager.thinqFilterMonitoringIntervalSeconds * 1000;
+			this.thinqServices
+				.getFilterMonitoringService()
+				.startPolling(filterMonitoringIntervalMs, this.filterMonitoringDeviceIds, applyFilterUpdate);
+		}
+
+		this.log.debug(`onConfigure: exit — polling started at ${this.thinqPollingIntervalMs}ms interval`);
+	}
+
+	public override async onShutdown(reason?: string): Promise<void> {
+		await super.onShutdown(reason);
+		this.log.debug(`onShutdown: entry (reason=${reason ?? 'none'})`);
+		this.log.notice('onShutdown called with reason:', reason ?? 'none');
+
+		this.thinqServices.getDeviceService().stopPolling();
+		this.thinqServices.getDeviceService().stopKeepAlive();
+		this.thinqServices.getMqttListener().stop();
+		this.thinqServices.getFilterMonitoringService().stopPolling();
+
+		if (this.configManager.unregisterOnShutdown) {
+			await this.unregisterAllDevices(UNREGISTER_DEVICES_DELAY_MS);
+		}
+
+		this.state.setStartupCompleted(false);
+		this.log.debug('onShutdown: exit');
+	}
+
+	/**
+	 * Authenticates against LG ThinQ (account or token strategy), discovers AirConditioner devices,
+	 * and registers each of them with Matterbridge. Ports the sibling plugin's discovery/configure split.
+	 */
+	private async startThinqDevices(): Promise<void> {
+		const userDataRepository = this.thinqServices.getUserDataRepository();
+		let userData = this.configManager.isForceAuthenticationEnabled
+			? undefined
+			: await userDataRepository.loadUserData();
+
+		if (!userData) {
+			userData = await this.thinqServices
+				.getAuthenticationCoordinator()
+				.authenticate(this.configManager.thinqLoginType, {
+					username: this.configManager.thinqUsername,
+					password: this.configManager.thinqPassword,
+					refreshToken: this.configManager.thinqRefreshToken,
+					country: this.configManager.country,
+					language: this.configManager.language,
+				});
+		}
+
+		if (!userData) {
+			throw new ManualProcessNeededError(
+				'LG ThinQ authentication did not return user data. This account likely uses a third-party SSO login ' +
+					'(Google/Apple/Facebook/Amazon), which is not yet supported headlessly — please log in with a native ' +
+					'LG account (email/password) or refresh token instead.',
+				{ reason: 'THIRD_PARTY_SSO_NOT_SUPPORTED' },
+			);
+		}
+
+		this.thinqServices.apiClient.setSession(ThinqSession.fromData(userData));
+		if (userData.userNumber) {
+			this.thinqServices.apiClient.setUserNumber(userData.userNumber);
+		}
+		await userDataRepository.saveUserData(userData);
+
+		const devices = await this.thinqServices.getDeviceDiscovery().discoverDevices();
+
+		const configChanged = reconcileThinqDeviceConfigEntries(this.config.thinq.devices, devices);
+		if (configChanged) {
+			try {
+				this.saveConfig(this.config);
+			} catch (error) {
+				this.log.error(
+					`Failed to persist auto-populated ThinQ device config: ${error instanceof Error ? error.message : String(error)}`,
+				);
+			}
+		}
+
+		const configurator = this.thinqServices.getDeviceConfigurator();
+
+		for (const device of devices) {
+			if (isAirConditionerDevice(device)) {
+				const airConditioner = await configurator.registerAirConditioner(device);
+				await this.registerDevice(airConditioner);
+				this.registry.register(device.id, airConditioner);
+				this.thinqDeviceKindById.set(device.id, 'AC');
+				if (this.configManager.getDeviceCapabilities(device.id).supportsFilterMonitoring) {
+					this.filterMonitoringDeviceIds.push(device.id);
+				}
+				continue;
+			}
+
+			if (isWasherDevice(device)) {
+				const washer = await configurator.registerWasher(device);
+				await this.registerDevice(washer);
+				this.registry.register(device.id, washer);
+				this.thinqDeviceKindById.set(device.id, 'WASHER');
+				continue;
+			}
+		}
+	}
+
+	public override async onChangeLoggerLevel(logLevel: LogLevel): Promise<void> {
+		this.log.notice(`Change ${PLUGIN_NAME} log level: ${logLevel} (was ${this.log.logLevel})`);
+		this.log.logLevel = logLevel;
+	}
+	// #endregion Lifecycle
+}