matterbridge-lg-thinq-plugin 0.1.0

package/dist/tests/helpers/testUtils.js

@@ -0,0 +1,87 @@
+import { vi } from 'vitest';
+export function createMockLogger() {
+    return {
+        debug: vi.fn(),
+        info: vi.fn(),
+        notice: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        fatal: vi.fn(),
+        setMaxListeners: vi.fn(),
+        getMaxListeners: vi.fn(),
+        addListener: vi.fn(),
+        on: vi.fn(),
+        once: vi.fn(),
+        removeListener: vi.fn(),
+        off: vi.fn(),
+        removeAllListeners: vi.fn(),
+        listeners: vi.fn(),
+        rawListeners: vi.fn(),
+        emit: vi.fn(),
+        listenerCount: vi.fn(),
+        prependListener: vi.fn(),
+        prependOnceListener: vi.fn(),
+        eventNames: vi.fn(),
+    };
+}
+export function asPartial(partial) {
+    return partial;
+}
+export function buildGatewayResponse(overrides) {
+    return {
+        empTermsUri: 'https://emp-terms.lgecloud.com',
+        empSpxUri: 'https://emp-spx.lgecloud.com',
+        thinq2Uri: 'https://aic-service.lgecloud.com',
+        thinq1Uri: 'https://v1aic-service.lgecloud.com',
+        countryCode: 'US',
+        languageCode: 'en',
+        ...overrides,
+    };
+}
+export function buildThinqDeviceData(overrides) {
+    return {
+        deviceId: '12345678-1234-1234-1234-123456789012',
+        alias: 'Living Room AC',
+        modelJsonUri: 'https://example.com/model.json',
+        deviceType: 401,
+        modelName: 'DualCool Plus',
+        manufacture: {
+            macAddress: '00:00:00:00:00:00',
+            salesModel: 'AC123',
+            serialNo: 'SN12345',
+            manufactureModel: 'AC123-MANU',
+        },
+        modemInfo: {
+            appVersion: '1.0',
+            modelName: 'AC123',
+        },
+        snapshot: {
+            online: true,
+            'airState.operation': 1,
+            'airState.tempState.current': 24,
+            'airState.tempState.target': 22,
+            'airState.opMode': 0,
+            'airState.windStrength': 2,
+        },
+        platformType: 'THINQ',
+        online: true,
+        ...overrides,
+    };
+}
+export function createMockNodePersist() {
+    return {
+        getItem: vi.fn(),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+        clear: vi.fn(),
+        keys: vi.fn(),
+        length: vi.fn(),
+    };
+}
+export function setReadOnlyProperty(obj, key, value) {
+    Object.defineProperty(obj, key, {
+        value,
+        writable: false,
+        configurable: true,
+    });
+}

package/dist/utils/mask.js

@@ -0,0 +1,39 @@
+export function maskSecret(value, visibleChars = 4) {
+    if (!value) {
+        return '';
+    }
+    if (value.length <= visibleChars) {
+        return '*'.repeat(value.length);
+    }
+    return '*'.repeat(value.length - visibleChars) + value.slice(-visibleChars);
+}
+const SENSITIVE_FIELD_NAMES = new Set([
+    'refresh_token',
+    'refreshtoken',
+    'access_token',
+    'accesstoken',
+    'password',
+    'client_secret',
+    'clientsecret',
+    'secret',
+    'x-emp-token',
+    'authorization',
+]);
+export function maskSensitiveFields(source) {
+    if (!source) {
+        return source;
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (SENSITIVE_FIELD_NAMES.has(key.toLowerCase())) {
+            result[key] = typeof value === 'string' ? maskSecret(value) : value;
+        }
+        else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            result[key] = maskSensitiveFields(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/docs/README_CLI.md

@@ -0,0 +1,166 @@
+# ThinQ CLI Login Helper
+
+A standalone command-line tool for authenticating with LG ThinQ, saving your session, and listing discovered devices for use with the Matterbridge LG ThinQ plugin.
+
+## Setup
+
+Build the project first:
+
+```bash
+npm run build:local
+```
+
+This compiles TypeScript and generates the CLI binary at `dist/cli.js`.
+
+## Usage
+
+Run the CLI with:
+
+```bash
+npm run cli -- --command <command> [options]
+```
+
+## Commands
+
+| Command   | Options                             | Description                                          |
+| --------- | ----------------------------------- | ---------------------------------------------------- |
+| `login`   | `--type`, `--country`, `--language` | Authenticate and save session                        |
+| `devices` |                                     | List all discovered ThinQ devices (requires `login`) |
+| `help`    |                                     | Show help message                                    |
+
+## Login Command
+
+The `login` command guides you through authentication and saves your credentials to a local session file.
+
+### Options
+
+- `--type`: Authentication method (default: `account`)
+  - `account`: Username/password authentication
+  - `token`: Refresh token authentication
+- `--country`: Country code (default: `US`) — must match your LG ThinQ account region
+- `--language`: Language code (default: `en-US`)
+- `--debug`: Enable debug logging
+
+### Examples
+
+#### Account-based authentication (default):
+
+```bash
+npm run cli -- --command login
+```
+
+You will be prompted for:
+
+- Username (email)
+- Password
+
+#### Account-based authentication with specific region:
+
+```bash
+npm run cli -- --command login --type account --country KR --language ko-KR
+```
+
+#### Token-based authentication:
+
+```bash
+npm run cli -- --command login --type token
+```
+
+You will be prompted for:
+
+- Refresh token
+
+### Example Session Output
+
+```
+Login successful. Session saved to .cli-session.json
+Session Summary:
+  Login Type: account
+  Country: US
+  Language: en-US
+  Access Token: ****XXXX
+  Refresh Token: ****XXXX
+  Expires At: 2026-09-08T23:59:59.000Z
+```
+
+Note: All tokens are masked in the output for security.
+
+## Devices Command
+
+The `devices` command lists all ThinQ devices discovered in your account, using the session saved by a prior `login` command.
+
+### Options
+
+- `--debug`: Enable debug logging
+
+### Prerequisites
+
+You must run `--command login` successfully first. If no session file is found, the command prints an error and exits.
+
+### Example
+
+```bash
+npm run cli -- --command devices
+```
+
+### Example Output
+
+```
+Found 2 device(s):
+
+1. Living Room AC
+   Device ID:     a1b2c3d4-e5f6-7890-abcd-ef1234567890
+   Type:          AC
+   Platform Type: thinq2
+   Model Name:    RAC-1234
+   Online:        true
+
+2. Kitchen Fridge
+   Device ID:     b2c3d4e5-f6a7-8901-bcde-f12345678901
+   Type:          REFRIGERATOR
+   Platform Type: thinq2
+   Model Name:    LRF-5678
+   Online:        false
+```
+
+## Session File
+
+After successful login, your session is saved to `.cli-session.json` in your working directory:
+
+```json
+{
+  "loginType": "account",
+  "country": "US",
+  "language": "en-US",
+  "userData": {
+    "accessToken": "...",
+    "refreshToken": "...",
+    "expiresAtEpochSeconds": 1234567890,
+    "country": "US",
+    "language": "en-US"
+  }
+}
+```
+
+**⚠️ Important:** This file contains authentication credentials. Keep it secure and do NOT commit it to version control (it is in `.gitignore` by default).
+
+## Notes
+
+### Supported Authentication Methods
+
+- **Account (username/password):** Uses LG's standard account login flow
+- **Refresh token:** For previously-saved tokens; skips the full login chain
+
+### Browser-Based SSO
+
+Third-party SSO (Google, Apple, Facebook, Amazon) is not yet supported in this CLI tool. If your account uses only these methods, you will need to use the Matterbridge web UI or manually obtain a refresh token.
+
+### Device Control
+
+This CLI supports authentication (`login`) and device discovery/listing (`devices`). Device control is not yet available and is handled by the full Matterbridge runtime instead.
+
+### Credentials Security
+
+- Passwords are **never printed** to the console or stored anywhere (only the token is saved).
+- All displayed tokens are automatically masked for security.
+- Input credentials are read interactively via the terminal, not from command-line arguments, to avoid exposure in shell history.

package/eslint.config.js

@@ -0,0 +1,194 @@
+import path from 'node:path';
+import url from 'node:url';
+
+import js from '@eslint/js';
+import json from '@eslint/json';
+import markdown from '@eslint/markdown';
+import vitest from '@vitest/eslint-plugin';
+import { defineConfig } from 'eslint/config';
+import n from 'eslint-plugin-n';
+import prettier from 'eslint-plugin-prettier/recommended';
+import pluginSimpleImportSort from 'eslint-plugin-simple-import-sort';
+import tseslint from 'typescript-eslint';
+
+const sourceFiles = ['**/*.{js,mjs,cjs,ts,mts,cts}'];
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+export default defineConfig([
+	{
+		name: 'Global Ignores',
+		ignores: [
+			'dist/',
+			'build/',
+			'node_modules/',
+			'coverage/',
+			'report/',
+			'.claude/',
+			'vite.config.ts',
+			'docs/**/*',
+			'workspace/*',
+		],
+	},
+	{ ...js.configs.recommended, files: sourceFiles },
+	...tseslint.configs.stylistic.map((config) => ({ ...config, files: sourceFiles })),
+	...tseslint.configs.strictTypeChecked.map((config) => ({ ...config, files: sourceFiles })),
+	{ ...n.configs['flat/recommended-script'], files: sourceFiles },
+	prettier,
+	{
+		name: 'JavaScript & TypeScript Source Files',
+		files: sourceFiles,
+		languageOptions: {
+			sourceType: 'module',
+			ecmaVersion: 'latest',
+		},
+		linterOptions: {
+			reportUnusedDisableDirectives: 'error', // Report unused eslint-disable directives
+			reportUnusedInlineConfigs: 'error', // Report unused eslint-disable-line directives
+		},
+		plugins: {
+			js,
+			n,
+			'simple-import-sort': pluginSimpleImportSort,
+		},
+		extends: ['js/recommended'],
+		rules: {
+			'no-console': 'warn', // Warn on console usage
+			'no-undef': 'off',
+			'spaced-comment': ['error', 'always'], // Require space after comment markers. Deprecated, but we still want to enforce it cause it's not handled by Prettier
+			'@typescript-eslint/no-unused-vars': [
+				'error',
+				{
+					'args': 'none',
+					'varsIgnorePattern': '^_',
+				},
+			],
+			'no-unused-vars': 'warn', // Use the base rule for unused variables
+			'simple-import-sort/imports': ['warn'],
+			'simple-import-sort/exports': ['warn'],
+			'n/prefer-node-protocol': 'error', // Prefer using 'node:' protocol for built-in modules
+			'n/no-unsupported-features/node-builtins': ['error', { ignores: ['fetch'] }],
+			'n/no-extraneous-import': 'off', // Allow imports from node_modules
+			'n/no-unpublished-import': 'off', // Allow imports from unpublished packages
+			'n/no-missing-import': 'off', // Allow subpath imports from peer dependencies
+			'prettier/prettier': 'warn', // Use Prettier for formatting
+			'@typescript-eslint/no-unnecessary-condition': 'off',
+			'@typescript-eslint/restrict-template-expressions': 'off',
+			'@typescript-eslint/no-unsafe-assignment': 'off',
+			'@typescript-eslint/no-unsafe-member-access': 'off',
+			'@typescript-eslint/no-unsafe-call': 'off',
+			'@typescript-eslint/no-unsafe-return': 'off',
+			'@typescript-eslint/no-unsafe-argument': 'off',
+			'@typescript-eslint/unbound-method': 'off',
+			'@typescript-eslint/no-floating-promises': 'off',
+			'@typescript-eslint/require-await': 'off',
+			'@typescript-eslint/no-misused-promises': 'off',
+			'@typescript-eslint/no-unsafe-enum-comparison': 'off',
+			'@typescript-eslint/no-useless-default-assignment': 'off',
+			'@typescript-eslint/no-misused-spread': 'off',
+			'@typescript-eslint/no-confusing-void-expression': 'off',
+			'@typescript-eslint/no-redundant-type-constituents': 'off',
+			'@typescript-eslint/no-deprecated': 'off',
+			'@typescript-eslint/restrict-plus-operands': 'off',
+		},
+	},
+	{
+		name: 'JavaScript Source Files',
+		files: ['**/*.{js,mjs,cjs}'],
+		extends: [tseslint.configs.disableTypeChecked],
+	},
+	{
+		name: 'TypeScript Source Files',
+		files: ['**/*.ts'],
+		ignores: ['**/tests/**/*.ts'],
+		languageOptions: {
+			ecmaVersion: 'latest',
+			sourceType: 'module',
+			parser: tseslint.parser,
+			parserOptions: {
+				tsconfigRootDir: __dirname,
+				project: './tsconfig.json',
+			},
+		},
+		rules: {
+			'no-redeclare': 'off', // Disable no-redeclare for TypeScript files since TypeScript already checks for redeclarations
+			'no-undef': 'off', // Disable no-undef for TypeScript files since TypeScript already checks for undefined variables
+			'no-unused-vars': 'off', // Disable base rule for unused variables and use the TypeScript-specific rule instead
+			'@typescript-eslint/no-unused-vars': [
+				'error',
+				{
+					vars: 'all',
+					args: 'none',
+					ignoreRestSiblings: true,
+					varsIgnorePattern: '^_', // Ignore unused variables starting with _
+					caughtErrorsIgnorePattern: '^_', // Ignore unused caught errors starting with _
+				},
+			],
+		},
+	},
+	{
+		name: 'Vitest Test Files',
+		files: ['**/tests/**/*.ts'],
+		languageOptions: {
+			sourceType: 'module',
+			ecmaVersion: 'latest',
+			parser: tseslint.parser,
+			parserOptions: {
+				tsconfigRootDir: __dirname,
+				project: './tsconfig.vitest.json',
+			},
+		},
+		plugins: { vitest },
+		rules: {
+			'no-unused-vars': 'off', // Disable base rule for unused variables in test files
+			'@typescript-eslint/no-unused-vars': 'off', // Disable TypeScript rule for unused variables in test files
+			'@typescript-eslint/no-explicit-any': 'off', // Allow 'any' type in test files
+			'@typescript-eslint/no-empty-function': 'off', // Allow empty functions in test files
+			'@typescript-eslint/no-floating-promises': 'off', // Allow floating promises in tests
+			'@typescript-eslint/require-await': 'off', // Allow async without await in tests
+			'@typescript-eslint/no-deprecated': 'off', // Allow testing deprecated methods
+
+			'@typescript-eslint/no-confusing-void-expression': 'off',
+			'@typescript-eslint/no-unnecessary-type-assertion': 'off',
+			'@typescript-eslint/use-unknown-in-catch-callback-variable': 'off',
+			'@typescript-eslint/no-misused-spread': 'off',
+			'@typescript-eslint/no-unnecessary-type-parameters': 'off',
+			'@typescript-eslint/no-unnecessary-type-arguments': 'off',
+
+			...vitest.configs.recommended.rules,
+			'vitest/valid-expect': 'off',
+		},
+	},
+	{
+		name: 'CLI file',
+		files: ['src/cli.ts', 'src/cli/**'],
+		rules: {
+			'no-console': 'off',
+			'n/no-process-exit': 'off',
+		},
+	},
+	{
+		name: 'JSON Files',
+		files: ['**/*.json'],
+		ignores: ['**/devcontainer.json'],
+		plugins: { json },
+		language: 'json/json',
+		rules: {
+			'json/no-duplicate-keys': 'error',
+		},
+	},
+	{
+		name: 'JSONC files',
+		files: ['**/devcontainer.json', '**/*.jsonc'],
+		plugins: { json },
+		language: 'json/jsonc',
+	},
+	{
+		name: 'Markdown Files',
+		files: ['**/*.md'],
+		plugins: { markdown },
+		language: 'markdown/commonmark',
+		rules: {
+			'markdown/no-html': 'off', // Allow HTML in Markdown files
+		},
+	},
+]);

package/matterbridge-lg-thinq-plugin.config.json

@@ -0,0 +1,27 @@
+{
+	"name": "matterbridge-lg-thinq-plugin",
+	"type": "DynamicPlatform",
+	"version": "0.1.0",
+	"thinq": {
+		"loginType": "account",
+		"username": "",
+		"password": "",
+		"refreshToken": "",
+		"country": "US",
+		"language": "en-US",
+		"refreshIntervalSeconds": 60,
+		"filterMonitoringIntervalSeconds": 3600,
+		"devices": []
+	},
+	"webos": {
+		"devices": []
+	},
+	"advancedFeature": {
+		"settings": {
+			"debug": true,
+			"clearStorageOnStartup": false,
+			"forceAuthentication": false,
+			"unregisterOnShutdown": false
+		}
+	}
+}