matterbridge-lg-thinq-plugin 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,195 @@
+# Changelog
+
+## [0.1.0-rc13] - 2026-09-24
+
+### Added
+
+- **Per-device `deviceType` field** — a new read-only field, auto-detected from LG's own device type code, is now shown per device in the config UI; not user-editable (PR #19).
+- **Automatic `deviceType` population at startup** — the plugin now actually writes `deviceType` into the saved config for every discovered device at startup (new devices get an entry created, existing entries get backfilled); previously the schema claimed this was "Auto-populated on discovery" but nothing implemented it (PR #19).
+- **Per-device product identity override** — product identity (name/id shown in Apple Home) moves from a single global, AC-only override to a per-device override with type-specific defaults: AC uses 32768/"LG Air Conditioner", washer uses 32769/"LG Washer" (the washer never had a real product identity wired up before this) (PR #19).
+
+### Changed
+
+- **Config UI now scoped by device type** — each device's settings only show what's relevant to its actual type: `Capabilities` and `AC Filter Control` now only appear for AC devices (`AC Filter Control` additionally requires `Supports Filter Monitoring` to be on), and `Washer Control` only appears for washer devices (PR #19).
+- **`ThinQ Devices` list moved below credentials** — the device list now renders after the credential fields (password/refresh token) in the config UI instead of before them, for better visual flow (PR #19).
+- **Vendor identity stays global** — vendor identity (name/id) remains a single global setting, since it applies to one Matterbridge install (PR #19).
+
+**Upgrade note:** existing users who had customized the old shared `matterOverrideSettings.matterProductName`/`matterProductId` will see those fields disappear from the config UI on upgrade — there is no migration, this was an accepted, explicit decision — and will need to re-set a product name/ID per device if they want that customization again.
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc12] - 2026-09-24
+
+### Changed
+
+- **AC and washer now pair as standalone Matter nodes** — both device endpoints are hardcoded to `server` mode, so each pairs to Apple Home as its own node with its own pairing code instead of being bridged; not user-configurable, no schema/config option (PR #18). This is experimental: whether `server` mode actually produces a per-device Apple Home power tile for the AC is unconfirmed, since properly testing it requires a real Matter Device Attestation Certificate — self-signed dev certs show "not certified" in Apple Home and may not unlock the full UI.
+- **PowerTopology now uses NodeTopology** — the AC's energy-monitoring `PowerTopology` cluster switched from the `TreeTopology` feature to `NodeTopology`, matching the endpoint no longer being shared with a bridge (PR #18).
+- **AC scene buttons removed** — the custom quick-access buttons that created a separate `genericSwitch` child Matter endpoint next to the AC have been removed entirely, following the same no-extra-devices-on-the-AC policy as the earlier removal of the Jet/Quiet/Energy-Save/Air-Clean/LED auxiliary toggles (PR #18).
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc11] - 2026-09-23
+
+### Changed
+
+- **Removed AC auxiliary toggle child devices** — Jet, Quiet, Energy Save, Air Clean, and LED no longer create separate child switch/light devices attached to the AC in Apple Home; this is a deliberate feature removal, with no replacement control surface, so users who had these enabled will see the corresponding entities disappear from Apple Home after upgrading (PR #17).
+
+### Refactored
+
+- **Removed dead `supportsDry` capability flag** — the field used to gate whether Dry opMode reported Matter SystemMode.Dry vs Cool, but that branch was already removed in the rc10 cleanup, leaving the capability field, config field, and schema toggle as inert plumbing; all three are now removed (PR #16).
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc10] - 2026-09-23
+
+### Added
+
+- **LG ThinQ Washer support (v1, read-only)** — reports power, run state, and remaining time, registering as Matterbridge's LaundryWasher device type; note that Apple Home does not display the appliance device type at all, a confirmed Matterbridge/Apple platform limitation rather than a bug in this plugin, so the washer is usable today via Home Assistant, SmartThings, or other Matter controllers (PR #13).
+- **Opt-in washer Stop command** — `washerControl.allowRemoteStop` (default off) lets Apple Home send a real stop/cancel command to the physical washer (PR #13).
+- **AC filter life monitoring** — opt-in via `supportsFilterMonitoring` (default off), exposed as HepaFilterMonitoring; live-verified against a real device with an exact match to the official LG app (PR #15).
+- **Opt-in AC filter reset command** — `acFilterControl.allowFilterReset` (default off) sends a real filter-counter reset command after you've replaced/cleaned the filter; this command has not been live-tested yet, so enable only when you are ready to verify it yourself (PR #15).
+
+### Fixed
+
+- **AC mode dropdown showing unsupported values** — Dry and Fan-only opModes now report as Cool instead of SystemMode values Apple Home silently dropped, so the mode dropdown only ever shows what Apple can actually display (Off/Heat/Cool/Auto) (PR #14).
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc09] - 2026-09-20
+
+### Changed
+
+- **AC is now a bridged device** — the AC registers as a normal bridged device and the hardcoded standalone "server" mode was removed, because on iOS 27 the Apple Home Energy tab (whole-home total and per-device detail) only worked in bridged mode. Note for users: remove the old standalone AC from Apple Home and pair through Matterbridge's bridge.
+- **Energy measurement on the AC endpoint** — when `supportsEnergyMonitoring` is on, the electrical measurement now always lives on the AC endpoint itself (room air conditioner + power source + electrical sensor device types, with PowerTopology and ElectricalPowerMeasurement); the separate EnergyMonitor child endpoint and the `energyMonitoringPlacement` setting were removed.
+
+### Fixed
+
+- **Power shown while AC is off** — power now reads 0 W when the AC is off; LG reports a floor of about 50 in that state, which was wrongly shown as real consumption.
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc08] - 2026-09-19
+
+### Changed
+
+- **Power reading scale** — `airState.energy.onCurrent` is now read as raw watts (no division by 100), so reported power values are about 100 times larger than before (a running 1 hp AC shows about 900 to 1000 W); the Matter value is still written in milliwatts (PR #11).
+
+### Fixed
+
+- **AC flipping On/Off in Apple Home** — LG MQTT pushes are partial and state sync treated them as full snapshots, so a missing power field read as off; state sync now writes a Matter attribute only when its source property is present in the update (PR #11).
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc07] - 2026-09-19
+
+### Added
+
+- **energyMonitoringPlacement** — experimental per-device setting (`'child'` default, or `'endpoint'`) to host the electrical power measurement on the AC endpoint itself; opt-in, and the AC is not turned into an outlet (PR #10).
+- **`energy` CLI command** — live power-reading diagnostics with `--device`, `--samples`, `--interval` and `--keep-alive` options.
+
+### Fixed
+
+- **EnergyMonitor child endpoint** — added the PowerTopology cluster required by the electricalSensor device type, and `activePower` now starts at 0 instead of null. This changes the shape of the child, so Apple Home may need the AC removed and added again.
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc06] - 2026-09-19
+
+### Added
+
+- **overrideMatterConfiguration** — configurable Matter Basic-Information identity (vendor name/id, product name/id) for the AC device, plus an optional per-device `productName` override (PR #9).
+
+### Fixed
+
+- **ElectricalPowerMeasurement attribute bug** — corrected the attribute name from `power` to `activePower` and fixed the missing watts-to-milliwatts unit conversion.
+- **EISDIR unhandled rejection on plugin load** — moved the MQTT certificate directory out from inside node-persist's scanned storage directory into a sibling `mqtt-certs/` directory, avoiding the crash on load.
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc05] - 2026-09-19
+
+### Fixed
+
+- **ThinQ token-expiry detection** — treat LG resultCode `0102` as token-expired alongside HTTP 401, resolving AC on/off command failures caused by expired tokens not being refreshed (PR #8).
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc04] - 2026-09-19
+
+### Added
+
+- **AC swing/vane control** — expose vertical/horizontal vane swing mode as a Matter control, gated per-device by capability flag.
+- **AC humidity and air-quality sensors** — surface humidity and air-quality (AQI, PM2.5, PM10) readings as Matter sensors for supporting devices.
+- **AC energy consumption monitoring** — report instantaneous power consumption for devices that expose it.
+- **AC custom scene buttons** — optional quick-access scene buttons that switch the AC to a saved operation-mode combo with one tap.
+- **AC Jet/Quiet/Energy-save/Air-clean/LED toggles** — per-device capability-gated toggles for jet mode, quiet mode, energy-save mode, air-clean mode, and LED/display light control.
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc03] - 2026-09-18
+
+### Added
+
+- **AC keep-alive heartbeat** — periodic heartbeat alongside the existing polling loop keeps ThinQ AirConditioner connections alive between state refreshes, reducing stale/dropped device sessions (PR #6).
+
+### Changed
+
+- **Test coverage** — closed a coverage gap to keep CI at the required 75% threshold.
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc02] - 2026-09-16
+
+### Added
+
+- **ThinQ2 MQTT push support** — subscribes to ThinQ2 MQTT push notifications for near-real-time device state updates, with full test coverage.
+- **Devices CLI command** — new CLI command to list all ThinQ devices discovered on the account.
+- **Lifecycle debug tracing** — debug-level tracing across the ThinQ AirConditioner runtime lifecycle for easier troubleshooting.
+
+### Changed
+
+- **Matterbridge dependency bump** — updated the required Matterbridge version.
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---
+
+## [0.1.0-rc01] - 2026-09-14
+
+### Added
+
+- **Plugin bootstrap** — initial Matterbridge dynamic platform lifecycle skeleton for LG ThinQ + webOS TV integration.
+- **ThinQ CLI login helper** — command-line authentication flow with session persistence for LG ThinQ accounts.
+- **ThinQ AirConditioner command wiring** — device discovery, registration, and command dispatch for ThinQ AirConditioner devices.
+- **Per-device AC capability flags** — configurable capability detection per AirConditioner device to gate supported features.
+- **GitHub Actions workflow templates** — CI workflow scaffolding for automated builds and checks.
+
+### Changed
+
+- **AirConditioner state synchronization** — polling loop applies ThinQ device snapshots to registered Matterbridge endpoints, respecting per-device capabilities.
+
+<a href="https://www.buymeacoffee.com/rinnvspktr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
+
+---

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli/commands/devices.js

@@ -0,0 +1,52 @@
+import { toThinqDevice } from '../../core/domain/entities/ThinqDevice.js';
+import { ThinqSession } from '../../services/thinq/session.js';
+import { ThinqApiClient } from '../../services/thinq/thinqApiClient.js';
+export async function cmdDevices(session, logger, dumpSnapshotDeviceId, probeFilterDeviceId) {
+    const { userData, country, language } = session;
+    const thinqSession = new ThinqSession(userData.accessToken, userData.refreshToken, userData.expiresAtEpochSeconds);
+    const apiClient = new ThinqApiClient(thinqSession, country, language, logger);
+    if (userData.userNumber) {
+        apiClient.setUserNumber(userData.userNumber);
+    }
+    if (probeFilterDeviceId) {
+        const response = await apiClient.sendCommandAndGetResponse(probeFilterDeviceId, {
+            ctrlKey: 'filterMngStateCtrl',
+            command: 'Get',
+            dataGetList: [
+                'airState.filterMngState.useTime',
+                'airState.filterMngState.remainTime',
+                'airState.filterMngState.maxTime',
+                'airState.filterMngState.changeDate',
+                'airState.filterMngState.type',
+            ],
+        });
+        console.log(JSON.stringify(response, null, 2));
+        return;
+    }
+    const rawDevices = await apiClient.getListDevices();
+    const devices = rawDevices.map(toThinqDevice);
+    if (devices.length === 0) {
+        console.log('No devices found.');
+        return;
+    }
+    if (dumpSnapshotDeviceId) {
+        const device = devices.find((d) => d.id === dumpSnapshotDeviceId);
+        if (!device) {
+            console.error(`Device not found: ${dumpSnapshotDeviceId}`);
+            process.exitCode = 1;
+            return;
+        }
+        console.log(JSON.stringify(device.snapshot.raw, null, 2));
+        return;
+    }
+    console.log(`Found ${devices.length} device(s):\n`);
+    devices.forEach((device, index) => {
+        console.log(`${index + 1}. ${device.name}`);
+        console.log(`   Device ID:     ${device.id}`);
+        console.log(`   Type:          ${device.type}`);
+        console.log(`   Platform Type: ${device.platformType ?? 'unknown'}`);
+        console.log(`   Model Name:    ${device.modelName}`);
+        console.log(`   Online:        ${device.online}`);
+        console.log('');
+    });
+}

package/dist/cli/commands/energy.js

@@ -0,0 +1,122 @@
+import { isAirConditionerDevice, toThinqDevice } from '../../core/domain/entities/ThinqDevice.js';
+import { ThinqSession } from '../../services/thinq/session.js';
+import { ThinqApiClient } from '../../services/thinq/thinqApiClient.js';
+const ENERGY_KEY = 'airState.energy.onCurrent';
+const OPERATION_KEY = 'airState.operation';
+const KEEP_ALIVE_WAIT_MS = 2000;
+function parsePositiveNumber(name, raw, fallback, integer) {
+    if (raw === undefined) {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0 || (integer && !Number.isInteger(value))) {
+        throw new Error(`Invalid --${name} value "${raw}": expected a positive ${integer ? 'integer' : 'number'}.`);
+    }
+    return value;
+}
+export function parseEnergyOptions(args) {
+    const deviceArg = args['device'];
+    return {
+        deviceId: deviceArg && deviceArg !== 'true' ? deviceArg : undefined,
+        samples: parsePositiveNumber('samples', args['samples'], 1, true),
+        intervalSeconds: parsePositiveNumber('interval', args['interval'], 5, false),
+        keepAlive: args['keep-alive'] === 'true',
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function describe(value) {
+    return `${JSON.stringify(value)} (typeof ${typeof value})`;
+}
+function listDeviceIds(devices) {
+    if (devices.length === 0) {
+        console.log('  (no devices discovered)');
+        return;
+    }
+    for (const device of devices) {
+        console.log(`  ${device.id}  type=${device.type}  name=${device.name}`);
+    }
+}
+function printSample(device, index, total) {
+    const { snapshot } = device;
+    const raw = snapshot.raw;
+    console.log(`--- Sample ${index}/${total} @ ${new Date().toISOString()} ---`);
+    console.log(`online (device):        ${device.online}`);
+    console.log(`online (snapshot):      ${describe(raw['online'])}`);
+    console.log(`${OPERATION_KEY}: ${describe(raw[OPERATION_KEY])}  -> isPowerOn=${snapshot.isPowerOn}`);
+    const keys = Object.keys(raw)
+        .filter((key) => {
+        const lower = key.toLowerCase();
+        return lower.startsWith('airstate.energy.') || lower.includes('energy') || lower.includes('power');
+    })
+        .sort();
+    console.log('Energy/power related keys:');
+    if (keys.length === 0) {
+        console.log('  (none found)');
+    }
+    for (const key of keys) {
+        console.log(`  ${key} = ${describe(raw[key])}`);
+    }
+    console.log(`${ENERGY_KEY}:`);
+    if (!(ENERGY_KEY in raw)) {
+        console.log('  key is ABSENT from this snapshot');
+    }
+    else {
+        console.log(`  raw value:                 ${describe(raw[ENERGY_KEY])}`);
+    }
+    const watts = snapshot.powerConsumptionWatts;
+    if (watts === undefined) {
+        console.log('  powerConsumptionWatts:     undefined (plugin would NOT write activePower)');
+    }
+    else {
+        console.log(`  powerConsumptionWatts:     ${watts} W`);
+        console.log(`  activePower the plugin writes: ${Math.round(watts * 1000)} mW`);
+    }
+    console.log('');
+}
+export async function cmdEnergy(session, options, logger) {
+    const { userData, country, language } = session;
+    const thinqSession = new ThinqSession(userData.accessToken, userData.refreshToken, userData.expiresAtEpochSeconds);
+    const apiClient = new ThinqApiClient(thinqSession, country, language, logger);
+    if (userData.userNumber) {
+        apiClient.setUserNumber(userData.userNumber);
+    }
+    const fetchDevices = async () => (await apiClient.getListDevices()).map(toThinqDevice);
+    let devices = await fetchDevices();
+    const target = options.deviceId
+        ? devices.find((device) => device.id === options.deviceId)
+        : devices.find(isAirConditionerDevice);
+    if (!target) {
+        console.error(options.deviceId
+            ? `Device "${options.deviceId}" was not found. Discovered device ids:`
+            : 'No AC device found. Discovered device ids:');
+        listDeviceIds(devices);
+        process.exitCode = 1;
+        return;
+    }
+    if (!isAirConditionerDevice(target)) {
+        console.warn(`Warning: device ${target.id} is type ${target.type}, not AC; continuing anyway.`);
+    }
+    console.log(`Device: ${target.name} (${target.id}) type=${target.type} model=${target.modelName || 'unknown'}`);
+    console.log(`Samples: ${options.samples}, interval: ${options.intervalSeconds}s, keep-alive: ${options.keepAlive ? 'yes' : 'no'}\n`);
+    if (options.keepAlive) {
+        await apiClient.sendKeepAlive(target.id);
+        console.log(`Keep-alive sent (allEventEnable, airState.mon.timeout=70). Waiting ${KEEP_ALIVE_WAIT_MS / 1000}s...\n`);
+        await sleep(KEEP_ALIVE_WAIT_MS);
+        devices = await fetchDevices();
+    }
+    for (let i = 1; i <= options.samples; i++) {
+        if (i > 1) {
+            await sleep(options.intervalSeconds * 1000);
+            devices = await fetchDevices();
+        }
+        const current = devices.find((device) => device.id === target.id);
+        if (!current) {
+            console.error(`Sample ${i}/${options.samples}: device ${target.id} is missing from the device list.`);
+            process.exitCode = 1;
+            continue;
+        }
+        printSample(current, i, options.samples);
+    }
+}

package/dist/cli/commands/login.js

@@ -0,0 +1,54 @@
+import { AccountAuthStrategy } from '../../services/authentication/AccountAuthStrategy.js';
+import { AuthenticationCoordinator } from '../../services/authentication/AuthenticationCoordinator.js';
+import { TokenAuthStrategy } from '../../services/authentication/TokenAuthStrategy.js';
+import { ThinqSession } from '../../services/thinq/session.js';
+import { ThinqApiClient } from '../../services/thinq/thinqApiClient.js';
+import { saveSession } from '../session.js';
+import { maskSecret } from '../utils.js';
+import { prompt } from '../utils.js';
+async function buildAuthContext(type, country, language) {
+    if (type === 'token') {
+        const refreshToken = await prompt('Refresh token: ');
+        return {
+            refreshToken,
+            country,
+            language,
+        };
+    }
+    const username = await prompt('Username (email): ');
+    const password = await prompt('Password: ');
+    return {
+        username,
+        password,
+        country,
+        language,
+    };
+}
+export async function cmdLogin(type, country, language, logger) {
+    const context = await buildAuthContext(type, country, language);
+    const apiClient = new ThinqApiClient(new ThinqSession('', '', 0), country, language, logger);
+    const accountStrategy = new AccountAuthStrategy(apiClient, logger);
+    const tokenStrategy = new TokenAuthStrategy(apiClient, logger);
+    const coordinator = new AuthenticationCoordinator(accountStrategy, tokenStrategy, apiClient, logger);
+    const userData = await coordinator.authenticate(type, context);
+    if (!userData) {
+        console.error('Login did not complete: no session data was returned (a manual process may be required).');
+        process.exitCode = 1;
+        return;
+    }
+    const session = {
+        loginType: type,
+        country,
+        language,
+        userData,
+    };
+    saveSession(session);
+    console.log('Login successful. Session saved to .cli-session.json');
+    console.log('Session Summary:');
+    console.log(`  Login Type: ${session.loginType}`);
+    console.log(`  Country: ${session.country}`);
+    console.log(`  Language: ${session.language}`);
+    console.log(`  Access Token: ${maskSecret(session.userData.accessToken)}`);
+    console.log(`  Refresh Token: ${maskSecret(session.userData.refreshToken)}`);
+    console.log(`  Expires At: ${new Date(session.userData.expiresAtEpochSeconds * 1000).toISOString()}`);
+}

package/dist/cli/help.js

@@ -0,0 +1,50 @@
+const b = '\x1b[1m';
+const c = '\x1b[36m';
+const y = '\x1b[33m';
+const g = '\x1b[32m';
+const d = '\x1b[2m';
+const r = '\x1b[0m';
+const NAME_WIDTH = 12;
+function row(name, args, desc) {
+    const paddedName = name.padEnd(NAME_WIDTH);
+    const paddedArgs = args.padEnd(40);
+    return `  ${g}${paddedName}${r}${d}${paddedArgs}${r}${desc}`;
+}
+export const HELP_TEXT = `
+${b}Usage:${r}
+  npm run cli -- --command ${c}<command>${r} [options]
+
+${b}Options:${r}
+  ${y}--type${r}         account|token (default: account)
+  ${y}--country${r}      Country code (default: US)
+  ${y}--language${r}     Language code (default: en-US)
+  ${y}--help${r}         Show this help message
+  ${y}--debug${r}        Enable debug logging
+
+${b}Devices options:${r}
+  ${y}--dump-snapshot${r} Device id; prints its full raw ThinQ snapshot JSON instead of the device list
+  ${y}--probe-filter${r}  Device id; sends a filterMngStateCtrl Get probe and prints the raw response JSON
+
+${b}Energy options:${r}
+  ${y}--device${r}       Device id (default: first AC device)
+  ${y}--samples${r}      Number of snapshots to fetch (default: 1)
+  ${y}--interval${r}     Seconds between samples (default: 5)
+  ${y}--keep-alive${r}   Send the plugin's keep-alive first, wait 2s, then sample
+
+${b}Commands:${r}
+${row('login', '', 'Authenticate with LG ThinQ')}
+${row('devices', '', 'List all discovered ThinQ devices (requires a prior login)')}
+${row('energy', '[energy options]', 'Print raw AC power/energy snapshot fields (requires a prior login)')}
+${row('help', '', 'Show this help message')}
+
+${b}Examples:${r}
+  npm run cli -- ${y}--help${r}
+  npm run cli -- --command ${g}login${r}
+  npm run cli -- --command ${g}login${r} --type account --country US --language en-US
+  npm run cli -- --command ${g}login${r} --type token
+  npm run cli -- --command ${g}devices${r}
+  npm run cli -- --command ${g}devices${r} --dump-snapshot <deviceId>
+  npm run cli -- --command ${g}devices${r} --probe-filter <deviceId>
+  npm run cli -- --command ${g}energy${r}
+  npm run cli -- --command ${g}energy${r} --samples 5 --interval 10 --keep-alive
+`;

package/dist/cli/main.js

@@ -0,0 +1,56 @@
+import { AnsiLogger } 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() {
+    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 ? "debug" : "warn" });
+    try {
+        if (command === 'login') {
+            const type = (args['type'] || 'account');
+            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/dist/cli/session.js

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

package/dist/cli/types.js

@@ -0,0 +1 @@
+export const SESSION_FILE = '.cli-session.json';

package/dist/cli/utils.js

@@ -0,0 +1,29 @@
+import readline from 'node:readline';
+export { maskSecret } from '../utils/mask.js';
+export function parseArgs(args) {
+    const result = {};
+    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) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}

package/dist/cli.js

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

package/dist/constants/index.js

@@ -0,0 +1 @@
+export const UNREGISTER_DEVICES_DELAY_MS = 500;

package/dist/core/domain/entities/ThinqDevice.js

@@ -0,0 +1,43 @@
+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}$/;
+const DEVICE_TYPE_NAMES = {
+    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',
+};
+export function isValidThinqDeviceId(id) {
+    return typeof id === 'string' && DEVICE_ID_PATTERN.test(id);
+}
+export function isAirConditionerDevice(device) {
+    return device.type === 'AC';
+}
+export function isWasherDevice(device) {
+    return device.type === 'WASHER';
+}
+export function toThinqDevice(data) {
+    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,
+    };
+}