matterbridge-lg-thinq-plugin 0.1.0

package/src/cli/main.ts

@@ -0,0 +1,66 @@
+import { AnsiLogger, LogLevel } from 'matterbridge/logger';
+
+import { cmdDevices } from './commands/devices.js';
+import { cmdEnergy, parseEnergyOptions } from './commands/energy.js';
+import { cmdLogin } from './commands/login.js';
+import { HELP_TEXT } from './help.js';
+import { loadSession } from './session.js';
+import { parseArgs } from './utils.js';
+
+export async function main(): Promise<void> {
+	const args = parseArgs(process.argv.slice(2));
+	const command = args['command'];
+
+	const help = args['help'] === 'true';
+	if (!command || command === 'help' || help) {
+		console.log(HELP_TEXT);
+		process.exit(command || help ? 0 : 1);
+	}
+
+	const debug = args['debug'] === 'true';
+	const logger = AnsiLogger.create({ logName: 'CLI', logLevel: debug ? LogLevel.DEBUG : LogLevel.WARN });
+
+	try {
+		if (command === 'login') {
+			const type = (args['type'] || 'account') as 'account' | 'token';
+			const country = args['country'] || 'US';
+			const language = args['language'] || 'en-US';
+
+			await cmdLogin(type, country, language, logger);
+			return;
+		}
+
+		if (command === 'devices') {
+			const session = loadSession();
+			if (!session) {
+				console.error('No session found. Run `--command login` first.');
+				process.exitCode = 1;
+				return;
+			}
+
+			const dumpSnapshotDeviceId = args['dump-snapshot'];
+			const probeFilterDeviceId = args['probe-filter'];
+			await cmdDevices(session, logger, dumpSnapshotDeviceId, probeFilterDeviceId);
+			return;
+		}
+
+		if (command === 'energy') {
+			const options = parseEnergyOptions(args);
+			const session = loadSession();
+			if (!session) {
+				console.error('No session found. Run `--command login` first.');
+				process.exitCode = 1;
+				return;
+			}
+
+			await cmdEnergy(session, options, logger);
+			return;
+		}
+
+		console.error(`Unknown command: ${command}\n\n${HELP_TEXT}`);
+		process.exit(1);
+	} catch (err) {
+		console.error('Error:', err instanceof Error ? err.message : String(err));
+		process.exit(1);
+	}
+}

package/src/cli/session.ts

@@ -0,0 +1,15 @@
+import fs from 'node:fs';
+
+import { CliSession, SESSION_FILE } from './types.js';
+
+export function saveSession(session: CliSession): void {
+	fs.writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2));
+}
+
+export function loadSession(): CliSession | null {
+	try {
+		return JSON.parse(fs.readFileSync(SESSION_FILE, 'utf-8')) as CliSession;
+	} catch {
+		return null;
+	}
+}

package/src/cli/types.ts

@@ -0,0 +1,10 @@
+import type { ThinqUserData } from '../services/authentication/AuthContext.js';
+
+export interface CliSession {
+	readonly loginType: 'account' | 'token';
+	readonly country: string;
+	readonly language: string;
+	readonly userData: ThinqUserData;
+}
+
+export const SESSION_FILE = '.cli-session.json';

package/src/cli/utils.ts

@@ -0,0 +1,30 @@
+import readline from 'node:readline';
+
+export { maskSecret } from '../utils/mask.js';
+
+export function parseArgs(args: string[]): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (let i = 0; i < args.length; i++) {
+		const key = args[i];
+		if (!key.startsWith('--')) continue;
+		const name = key.slice(2);
+		const next = args[i + 1];
+		if (next !== undefined && !next.startsWith('--')) {
+			result[name] = next;
+			i++;
+		} else {
+			result[name] = 'true';
+		}
+	}
+	return result;
+}
+
+export async function prompt(question: string): Promise<string> {
+	const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+	return new Promise((resolve) => {
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer.trim());
+		});
+	});
+}

package/src/cli.ts

@@ -0,0 +1,3 @@
+import { main } from './cli/main.js';
+
+main();

package/src/constants/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Centralized constants for the LG ThinQ plugin (webOS lands in a later phase).
+ * Import from this module to access all constants.
+ *
+ * @module constants
+ */
+
+export const UNREGISTER_DEVICES_DELAY_MS = 500;

package/src/core/domain/entities/ThinqDevice.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, it } from 'vitest';
+
+import { asPartial, buildThinqDeviceData } from '../../../tests/helpers/testUtils.js';
+import type { ThinqDevice } from './ThinqDevice.js';
+import { isAirConditionerDevice, isValidThinqDeviceId, isWasherDevice, toThinqDevice } from './ThinqDevice.js';
+
+describe('ThinqDevice', () => {
+	describe('isValidThinqDeviceId', () => {
+		it('should return true for a valid UUID v4 format', () => {
+			const validId = '12345678-1234-1234-1234-123456789012';
+			expect(isValidThinqDeviceId(validId)).toBe(true);
+		});
+
+		it('should return true for a valid uppercase UUID v4 format', () => {
+			const validId = '12345678-ABCD-ABCD-ABCD-123456789ABC';
+			expect(isValidThinqDeviceId(validId)).toBe(true);
+		});
+
+		it('should return false for a malformed UUID', () => {
+			expect(isValidThinqDeviceId('12345678-1234-1234-1234')).toBe(false);
+		});
+
+		it('should return false for a non-UUID string', () => {
+			expect(isValidThinqDeviceId('not-a-uuid')).toBe(false);
+		});
+
+		it('should return false for non-string values', () => {
+			expect(isValidThinqDeviceId(null)).toBe(false);
+			expect(isValidThinqDeviceId(undefined)).toBe(false);
+			expect(isValidThinqDeviceId(12345)).toBe(false);
+		});
+
+		it('should return false for an empty string', () => {
+			expect(isValidThinqDeviceId('')).toBe(false);
+		});
+	});
+
+	describe('isAirConditionerDevice', () => {
+		it('should return true for a device with type AC', () => {
+			const device = asPartial<ThinqDevice>({ type: 'AC' });
+			expect(isAirConditionerDevice(device)).toBe(true);
+		});
+
+		it('should return false for a non-AC device type', () => {
+			const device = asPartial<ThinqDevice>({ type: 'WASHER' });
+			expect(isAirConditionerDevice(device)).toBe(false);
+		});
+
+		it('should return false for any other type string', () => {
+			const device = asPartial<ThinqDevice>({ type: 'REFRIGERATOR' });
+			expect(isAirConditionerDevice(device)).toBe(false);
+		});
+	});
+
+	describe('isWasherDevice', () => {
+		it('should return true for a device with type WASHER', () => {
+			const device = asPartial<ThinqDevice>({ type: 'WASHER' });
+			expect(isWasherDevice(device)).toBe(true);
+		});
+
+		it('should return false for AC device type', () => {
+			const device = asPartial<ThinqDevice>({ type: 'AC' });
+			expect(isWasherDevice(device)).toBe(false);
+		});
+
+		it('should return false for WASHER_NEW type (not supported in v1)', () => {
+			const device = asPartial<ThinqDevice>({ type: 'WASHER_NEW' });
+			expect(isWasherDevice(device)).toBe(false);
+		});
+
+		it('should return false for WASH_TOWER type (not supported in v1)', () => {
+			const device = asPartial<ThinqDevice>({ type: 'WASH_TOWER' });
+			expect(isWasherDevice(device)).toBe(false);
+		});
+
+		it('should return false for WASH_TOWER_2 type (not supported in v1)', () => {
+			const device = asPartial<ThinqDevice>({ type: 'WASH_TOWER_2' });
+			expect(isWasherDevice(device)).toBe(false);
+		});
+
+		it('should return false for any other type string', () => {
+			const device = asPartial<ThinqDevice>({ type: 'REFRIGERATOR' });
+			expect(isWasherDevice(device)).toBe(false);
+		});
+	});
+
+	describe('toThinqDevice', () => {
+		it('should map raw ThinqDeviceData to ThinqDevice with all fields', () => {
+			const data = buildThinqDeviceData({
+				deviceId: 'test-id',
+				alias: 'Test Device',
+				deviceType: 401,
+				modelName: 'ModelXYZ',
+				online: true,
+			});
+
+			const device = toThinqDevice(data);
+
+			expect(device.id).toBe('test-id');
+			expect(device.name).toBe('Test Device');
+			expect(device.type).toBe('AC');
+			expect(device.modelName).toBe('ModelXYZ');
+			expect(device.online).toBe(true);
+			expect(device.platformType).toBe('THINQ');
+		});
+
+		it('should use modemInfo.modelName as fallback when modelName is absent', () => {
+			const data = buildThinqDeviceData({
+				modelName: undefined,
+				modemInfo: { modelName: 'ModemModel', appVersion: '1.0' },
+			});
+
+			const device = toThinqDevice(data);
+
+			expect(device.modelName).toBe('ModemModel');
+		});
+
+		it('should use manufacture.manufactureModel as fallback when both modelName and modemInfo.modelName are absent', () => {
+			const data = buildThinqDeviceData({
+				modelName: undefined,
+				modemInfo: undefined,
+				manufacture: { manufactureModel: 'ManuModel' },
+			});
+
+			const device = toThinqDevice(data);
+
+			expect(device.modelName).toBe('ManuModel');
+		});
+
+		it('should use empty string as final fallback for modelName', () => {
+			const data = buildThinqDeviceData({
+				modelName: undefined,
+				modemInfo: undefined,
+				manufacture: undefined,
+			});
+
+			const device = toThinqDevice(data);
+
+			expect(device.modelName).toBe('');
+		});
+
+		it('should resolve deviceType to correct type string', () => {
+			const testCases = [
+				{ deviceType: 401, expectedType: 'AC' },
+				{ deviceType: 201, expectedType: 'WASHER' },
+				{ deviceType: 202, expectedType: 'DRYER' },
+				{ deviceType: 204, expectedType: 'DISHWASHER' },
+				{ deviceType: 301, expectedType: 'OVEN' },
+				{ deviceType: 302, expectedType: 'MICROWAVE' },
+				{ deviceType: 101, expectedType: 'REFRIGERATOR' },
+				{ deviceType: 403, expectedType: 'DEHUMIDIFIER' },
+			];
+
+			for (const { deviceType, expectedType } of testCases) {
+				const data = buildThinqDeviceData({ deviceType });
+				const device = toThinqDevice(data);
+				expect(device.type).toBe(expectedType);
+			}
+		});
+
+		it('should fallback to string representation of unknown deviceType', () => {
+			const data = buildThinqDeviceData({ deviceType: 9999 });
+
+			const device = toThinqDevice(data);
+
+			expect(device.type).toBe('9999');
+		});
+
+		it('should use snapshot.online as fallback when data.online is absent', () => {
+			const data = buildThinqDeviceData({
+				online: undefined,
+				snapshot: { online: true },
+			});
+
+			const device = toThinqDevice(data);
+
+			expect(device.online).toBe(true);
+		});
+
+		it('should use false as final fallback for online when both are absent', () => {
+			const data = buildThinqDeviceData({
+				online: undefined,
+				snapshot: { online: undefined },
+			});
+
+			const device = toThinqDevice(data);
+
+			expect(device.online).toBe(false);
+		});
+
+		it('should create a ThinqSnapshot from the snapshot data', () => {
+			const data = buildThinqDeviceData({
+				snapshot: { online: true, 'airState.operation': 1, 'airState.windStrength': 2 },
+			});
+
+			const device = toThinqDevice(data);
+
+			expect(device.snapshot).toBeDefined();
+			expect(device.snapshot.isPowerOn).toBe(true);
+			expect(device.snapshot.windStrength).toBe(2);
+		});
+
+		it('should carry modelJsonUri when present', () => {
+			const modelUri = 'https://example.com/model.json';
+			const data = buildThinqDeviceData({
+				modelJsonUri: modelUri,
+			});
+
+			const device = toThinqDevice(data);
+
+			expect(device.modelJsonUri).toBe(modelUri);
+		});
+
+		it('should have undefined modelJsonUri when absent', () => {
+			const data = buildThinqDeviceData({
+				modelJsonUri: undefined,
+			});
+
+			const device = toThinqDevice(data);
+
+			expect(device.modelJsonUri).toBeUndefined();
+		});
+	});
+});

package/src/core/domain/entities/ThinqDevice.ts

@@ -0,0 +1,74 @@
+import type { ThinqDeviceData } from '../../../services/thinq/thinqApiClient.js';
+import { ThinqSnapshot } from '../value-objects/ThinqSnapshot.js';
+
+const DEVICE_ID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+/** Numeric `deviceType` → ThinQ type-name mapping (`homebridge-lg-thinq/src/lib/constants.ts`). Phase 1 subset. */
+const DEVICE_TYPE_NAMES: Record<number, string> = {
+	101: 'REFRIGERATOR',
+	102: 'KIMCHI_REFRIGERATOR',
+	103: 'WATER_PURIFIER',
+	201: 'WASHER',
+	221: 'WASHER_NEW',
+	222: 'WASH_TOWER',
+	223: 'WASH_TOWER_2',
+	202: 'DRYER',
+	203: 'STYLER',
+	204: 'DISHWASHER',
+	301: 'OVEN',
+	302: 'MICROWAVE',
+	303: 'COOKTOP',
+	304: 'HOOD',
+	401: 'AC',
+	402: 'AIR_PURIFIER',
+	403: 'DEHUMIDIFIER',
+	410: 'AERO_TOWER',
+};
+
+/** Generic ThinQ device entity, common to every device type/generation. */
+export interface ThinqDevice {
+	readonly id: string;
+	readonly name: string;
+	readonly type: string;
+	readonly modelName: string;
+	readonly platformType: string | undefined;
+	readonly online: boolean;
+	readonly snapshot: ThinqSnapshot;
+	readonly modelJsonUri?: string;
+}
+
+/** ThinQ device narrowed to the AirConditioner type (`deviceType === 401`, `type === 'AC'`). */
+export interface ThinqAirConditionerDevice extends ThinqDevice {
+	readonly type: 'AC';
+}
+
+/** ThinQ device narrowed to the Washer type (`deviceType === 201`, `type === 'WASHER'`). */
+export interface ThinqWasherDevice extends ThinqDevice {
+	readonly type: 'WASHER';
+}
+
+export function isValidThinqDeviceId(id: unknown): id is string {
+	return typeof id === 'string' && DEVICE_ID_PATTERN.test(id);
+}
+
+export function isAirConditionerDevice(device: ThinqDevice): device is ThinqAirConditionerDevice {
+	return device.type === 'AC';
+}
+
+export function isWasherDevice(device: ThinqDevice): device is ThinqWasherDevice {
+	return device.type === 'WASHER';
+}
+
+/** Maps a raw `ThinqDeviceData` REST response into the generic `ThinqDevice` domain entity. */
+export function toThinqDevice(data: ThinqDeviceData): ThinqDevice {
+	return {
+		id: data.deviceId,
+		name: data.alias,
+		type: DEVICE_TYPE_NAMES[data.deviceType] ?? String(data.deviceType),
+		modelName: data.modelName ?? data.modemInfo?.modelName ?? data.manufacture?.manufactureModel ?? '',
+		platformType: data.platformType,
+		online: data.online ?? data.snapshot.online ?? false,
+		snapshot: new ThinqSnapshot(data.snapshot),
+		modelJsonUri: data.modelJsonUri,
+	};
+}

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

@@ -0,0 +1,50 @@
+import type { ThinqDeviceConfigEntry } from '../../../model/LgThinqPluginPlatformConfig.js';
+
+/** Resolved per-device Matter capability set for a ThinQ AirConditioner endpoint. */
+export interface AirConditionerCapabilities {
+	readonly supportsHeat: boolean;
+	readonly supportsFanSpeedControl: boolean;
+	readonly supportsSwingMode: boolean;
+	readonly supportsHumiditySensor: boolean;
+	readonly supportsAirQualitySensor: boolean;
+	readonly supportsEnergyMonitoring: boolean;
+	readonly supportsFilterMonitoring: boolean;
+}
+
+export const DEFAULT_AIR_CONDITIONER_CAPABILITIES: AirConditionerCapabilities = {
+	supportsHeat: true,
+	supportsFanSpeedControl: true,
+	supportsSwingMode: false,
+	supportsHumiditySensor: false,
+	supportsAirQualitySensor: false,
+	supportsEnergyMonitoring: false,
+	supportsFilterMonitoring: false,
+};
+
+/**
+ * Merges configured per-device capability flags over the full-support default.
+ * Existing flags (supportsHeat/supportsFanSpeedControl) default to `true`.
+ * New flags (all others) default to `false` (opt-in).
+ */
+export function resolveAirConditionerCapabilities(
+	devices: ThinqDeviceConfigEntry[] | undefined,
+	deviceId: string,
+): AirConditionerCapabilities {
+	const entry = devices?.find((device) => device.deviceId === deviceId);
+	const capabilities = entry?.capabilities;
+
+	return {
+		supportsHeat: capabilities?.supportsHeat ?? DEFAULT_AIR_CONDITIONER_CAPABILITIES.supportsHeat,
+		supportsFanSpeedControl:
+			capabilities?.supportsFanSpeedControl ?? DEFAULT_AIR_CONDITIONER_CAPABILITIES.supportsFanSpeedControl,
+		supportsSwingMode: capabilities?.supportsSwingMode ?? DEFAULT_AIR_CONDITIONER_CAPABILITIES.supportsSwingMode,
+		supportsHumiditySensor:
+			capabilities?.supportsHumiditySensor ?? DEFAULT_AIR_CONDITIONER_CAPABILITIES.supportsHumiditySensor,
+		supportsAirQualitySensor:
+			capabilities?.supportsAirQualitySensor ?? DEFAULT_AIR_CONDITIONER_CAPABILITIES.supportsAirQualitySensor,
+		supportsEnergyMonitoring:
+			capabilities?.supportsEnergyMonitoring ?? DEFAULT_AIR_CONDITIONER_CAPABILITIES.supportsEnergyMonitoring,
+		supportsFilterMonitoring:
+			capabilities?.supportsFilterMonitoring ?? DEFAULT_AIR_CONDITIONER_CAPABILITIES.supportsFilterMonitoring,
+	};
+}

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

@@ -0,0 +1,50 @@
+const KEY_USE_TIME = 'airState.filterMngStates.useTime';
+const KEY_MAX_TIME = 'airState.filterMngStates.maxTime';
+const KEY_CHANGE_DATE = 'airState.filterMngStates.changeDate';
+
+/**
+ * Parses the `filterMngStateCtrl` `Get` response, which comes back keyed with PLURAL
+ * `airState.filterMngStates.*` fields (not the singular `airState.filterMngState.*` request keys — a
+ * confirmed LG request/response key-casing mismatch, see `.claude/memory.md`).
+ */
+export class ThinqFilterState {
+	private constructor(
+		private readonly useTimeHours: number,
+		private readonly maxTimeHours: number,
+		private readonly changeDateRaw: number | undefined,
+	) {}
+
+	/**
+	 * Returns `undefined` (not a zeroed object) when `useTime`/`maxTime` are missing or `maxTime<=0` —
+	 * this is the mechanism that keeps AC units with no filter sensor from ever showing fake data.
+	 */
+	public static fromRaw(data: Record<string, unknown> | undefined): ThinqFilterState | undefined {
+		const useTimeHours = readNumber(data, KEY_USE_TIME);
+		const maxTimeHours = readNumber(data, KEY_MAX_TIME);
+
+		if (useTimeHours === undefined || maxTimeHours === undefined || maxTimeHours <= 0) {
+			return undefined;
+		}
+
+		return new ThinqFilterState(useTimeHours, maxTimeHours, readNumber(data, KEY_CHANGE_DATE));
+	}
+
+	public get remainingPercent(): number {
+		const percent = ((this.maxTimeHours - this.useTimeHours) / this.maxTimeHours) * 100;
+		return Math.max(0, Math.min(100, Math.round(percent)));
+	}
+
+	public get changeDate(): number | undefined {
+		return this.changeDateRaw;
+	}
+
+	/** The device's rated total filter life in hours — echoed back unchanged in a reset `Set` payload. */
+	public get ratedMaxTimeHours(): number {
+		return this.maxTimeHours;
+	}
+}
+
+function readNumber(data: Record<string, unknown> | undefined, key: string): number | undefined {
+	const value = data?.[key];
+	return typeof value === 'number' ? value : undefined;
+}