matterbridge-lg-thinq-plugin 0.1.0

package/src/platform/thinq/thinqWasherStopCommandResolver.ts

@@ -0,0 +1,62 @@
+export interface WasherStopCommandPayload {
+	readonly command?: string;
+	readonly dataKey?: string;
+	readonly dataValue?: unknown;
+	readonly dataSetList?: Record<string, unknown>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null;
+}
+
+function toWasherStopCommandPayload(entry: Record<string, unknown>): WasherStopCommandPayload {
+	const payload: {
+		command?: string;
+		dataKey?: string;
+		dataValue?: unknown;
+		dataSetList?: Record<string, unknown>;
+	} = {};
+
+	if (typeof entry.command === 'string') {
+		payload.command = entry.command;
+	}
+	if (typeof entry.dataKey === 'string') {
+		payload.dataKey = entry.dataKey;
+	}
+	if ('dataValue' in entry) {
+		payload.dataValue = entry.dataValue;
+	}
+	if (isRecord(entry.dataSetList)) {
+		payload.dataSetList = entry.dataSetList;
+	} else if (isRecord(entry.data)) {
+		payload.dataSetList = entry.data;
+	}
+
+	return payload;
+}
+
+/**
+ * Extracts a real `WMStop`/`WMOff` command payload from a device's own downloaded model JSON
+ * (`ControlWifi` slice). Pure, no I/O — returns `undefined` on any missing/malformed shape instead of
+ * throwing, so callers can treat "no usable command" as a normal (fail-closed) outcome.
+ */
+export function extractWasherStopCommand(deviceModel: Record<string, unknown>): WasherStopCommandPayload | undefined {
+	if (!isRecord(deviceModel)) {
+		return undefined;
+	}
+
+	const controlWifi = deviceModel.ControlWifi;
+	if (!isRecord(controlWifi)) {
+		return undefined;
+	}
+
+	const stopEntry = isRecord(controlWifi.WMStop) ? controlWifi.WMStop : undefined;
+	const offEntry = isRecord(controlWifi.WMOff) ? controlWifi.WMOff : undefined;
+	const entry = stopEntry ?? offEntry;
+
+	if (!entry) {
+		return undefined;
+	}
+
+	return toWasherStopCommandPayload(entry);
+}

package/src/services/authentication/AccountAuthStrategy.test.ts

@@ -0,0 +1,358 @@
+import axios from 'axios';
+import MockAdapter from 'axios-mock-adapter';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { AuthenticationError, InvalidCredentialsError } from '../../errors/index.js';
+import { asPartial, buildGatewayResponse, createMockLogger } from '../../tests/helpers/testUtils.js';
+import type { ThinqApiClient } from '../thinq/thinqApiClient.js';
+import { AccountAuthStrategy } from './AccountAuthStrategy.js';
+import type { ThinqAuthContext } from './AuthContext.js';
+
+describe('AccountAuthStrategy', () => {
+	let mockAxios: MockAdapter;
+	let mockApiClient: ThinqApiClient;
+	let mockLogger: ReturnType<typeof createMockLogger>;
+	let strategy: AccountAuthStrategy;
+
+	const testContext: ThinqAuthContext = {
+		username: 'test@example.com',
+		password: 'testpassword123',
+		country: 'US',
+		language: 'en',
+	};
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		mockAxios = new MockAdapter(axios as any);
+		mockLogger = createMockLogger();
+		mockApiClient = asPartial<ThinqApiClient>({
+			getGateway: vi.fn(),
+		});
+		strategy = new AccountAuthStrategy(mockApiClient, mockLogger);
+	});
+
+	afterEach(() => {
+		mockAxios.reset();
+		vi.clearAllMocks();
+	});
+
+	describe('authenticate', () => {
+		it('should throw InvalidCredentialsError when username is missing', async () => {
+			const contextWithoutUsername = asPartial<ThinqAuthContext>({
+				password: 'password',
+				country: 'US',
+				language: 'en',
+			});
+
+			await expect(strategy.authenticate(contextWithoutUsername)).rejects.toThrow(InvalidCredentialsError);
+		});
+
+		it('should throw InvalidCredentialsError when password is missing', async () => {
+			const contextWithoutPassword = asPartial<ThinqAuthContext>({
+				username: 'test@example.com',
+				country: 'US',
+				language: 'en',
+			});
+
+			await expect(strategy.authenticate(contextWithoutPassword)).rejects.toThrow(InvalidCredentialsError);
+		});
+
+		it('should throw InvalidCredentialsError when both username and password are missing', async () => {
+			const emptyContext = asPartial<ThinqAuthContext>({
+				country: 'US',
+				language: 'en',
+			});
+
+			await expect(strategy.authenticate(emptyContext)).rejects.toThrow(InvalidCredentialsError);
+		});
+
+		it('should throw InvalidCredentialsError on preLogin 4xx response', async () => {
+			const gatewayData = buildGatewayResponse();
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+
+			mockAxios.onPost(`${gatewayData.empSpxUri}/preLogin`).reply(401);
+
+			await expect(strategy.authenticate(testContext)).rejects.toThrow(InvalidCredentialsError);
+		});
+
+		it('should throw AuthenticationError on preLogin non-4xx failure', async () => {
+			const gatewayData = buildGatewayResponse();
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+
+			mockAxios.onPost(`${gatewayData.empSpxUri}/preLogin`).reply(500);
+
+			await expect(strategy.authenticate(testContext)).rejects.toThrow(AuthenticationError);
+		});
+
+		it('should throw InvalidCredentialsError on account/session 4xx response', async () => {
+			const gatewayData = buildGatewayResponse();
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+
+			const preLoginResponse = {
+				signature: 'test-signature',
+				tStamp: '1234567890',
+				encrypted_pw: 'encrypted-password',
+			};
+
+			mockAxios.onPost(`${gatewayData.empSpxUri}/preLogin`).reply(200, preLoginResponse);
+			mockAxios
+				.onPost(
+					new RegExp(`${gatewayData.empTermsUri.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/emp/v2.0/account/session/.*`),
+				)
+				.reply(403);
+
+			await expect(strategy.authenticate(testContext)).rejects.toThrow(InvalidCredentialsError);
+		});
+
+		it('should throw AuthenticationError on account/session non-4xx failure', async () => {
+			const gatewayData = buildGatewayResponse();
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+
+			const preLoginResponse = {
+				signature: 'test-signature',
+				tStamp: '1234567890',
+				encrypted_pw: 'encrypted-password',
+			};
+
+			mockAxios.onPost(`${gatewayData.empSpxUri}/preLogin`).reply(200, preLoginResponse);
+			mockAxios
+				.onPost(
+					new RegExp(`${gatewayData.empTermsUri.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/emp/v2.0/account/session/.*`),
+				)
+				.reply(500);
+
+			await expect(strategy.authenticate(testContext)).rejects.toThrow(AuthenticationError);
+		});
+
+		it('should throw AuthenticationError on OAuth key lookup failure', async () => {
+			const gatewayData = buildGatewayResponse();
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+
+			const preLoginResponse = {
+				signature: 'test-signature',
+				tStamp: '1234567890',
+				encrypted_pw: 'encrypted-password',
+			};
+
+			const accountResponse = {
+				account: {
+					userIDType: 'LGE',
+					country: 'US',
+					userID: 'test@example.com',
+					loginSessionID: 'session-id',
+				},
+			};
+
+			mockAxios.onPost(`${gatewayData.empSpxUri}/preLogin`).reply(200, preLoginResponse);
+			mockAxios
+				.onPost(
+					new RegExp(`${gatewayData.empTermsUri.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/emp/v2.0/account/session/.*`),
+				)
+				.reply(200, accountResponse);
+			mockAxios.onGet(`${gatewayData.empSpxUri}/searchKey?key_name=OAUTH_SECRETKEY&sever_type=OP`).reply(500);
+
+			await expect(strategy.authenticate(testContext)).rejects.toThrow(AuthenticationError);
+		});
+
+		it('should throw AuthenticationError on EMP authorization failure when status is not 1', async () => {
+			const gatewayData = buildGatewayResponse();
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+
+			const preLoginResponse = {
+				signature: 'test-signature',
+				tStamp: '1234567890',
+				encrypted_pw: 'encrypted-password',
+			};
+
+			const accountResponse = {
+				account: {
+					userIDType: 'LGE',
+					country: 'US',
+					userID: 'test@example.com',
+					loginSessionID: 'session-id',
+				},
+			};
+
+			const secretKeyResponse = {
+				returnData: 'secret-key-data',
+			};
+
+			mockAxios.onPost(`${gatewayData.empSpxUri}/preLogin`).reply(200, preLoginResponse);
+			mockAxios
+				.onPost(
+					new RegExp(`${gatewayData.empTermsUri.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/emp/v2.0/account/session/.*`),
+				)
+				.reply(200, accountResponse);
+			mockAxios
+				.onGet(`${gatewayData.empSpxUri}/searchKey?key_name=OAUTH_SECRETKEY&sever_type=OP`)
+				.reply(200, secretKeyResponse);
+			mockAxios
+				.onGet(new RegExp('https://emp-oauth.lgecloud.com/emp/oauth2/authorize/empsession.*'))
+				.reply(200, { status: 0, message: 'Auth failed', redirect_uri: '' });
+
+			await expect(strategy.authenticate(testContext)).rejects.toThrow(AuthenticationError);
+		});
+
+		it('should throw AuthenticationError on EMP authorization network failure', async () => {
+			const gatewayData = buildGatewayResponse();
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+
+			const preLoginResponse = {
+				signature: 'test-signature',
+				tStamp: '1234567890',
+				encrypted_pw: 'encrypted-password',
+			};
+
+			const accountResponse = {
+				account: {
+					userIDType: 'LGE',
+					country: 'US',
+					userID: 'test@example.com',
+					loginSessionID: 'session-id',
+				},
+			};
+
+			const secretKeyResponse = {
+				returnData: 'secret-key-data',
+			};
+
+			mockAxios.onPost(`${gatewayData.empSpxUri}/preLogin`).reply(200, preLoginResponse);
+			mockAxios
+				.onPost(
+					new RegExp(`${gatewayData.empTermsUri.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/emp/v2.0/account/session/.*`),
+				)
+				.reply(200, accountResponse);
+			mockAxios
+				.onGet(`${gatewayData.empSpxUri}/searchKey?key_name=OAUTH_SECRETKEY&sever_type=OP`)
+				.reply(200, secretKeyResponse);
+			mockAxios.onGet(new RegExp('https://emp-oauth.lgecloud.com/emp/oauth2/authorize/empsession.*')).reply(500);
+
+			await expect(strategy.authenticate(testContext)).rejects.toThrow(AuthenticationError);
+		});
+
+		it('should throw AuthenticationError on token exchange failure', async () => {
+			const gatewayData = buildGatewayResponse();
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+
+			const preLoginResponse = {
+				signature: 'test-signature',
+				tStamp: '1234567890',
+				encrypted_pw: 'encrypted-password',
+			};
+
+			const accountResponse = {
+				account: {
+					userIDType: 'LGE',
+					country: 'US',
+					userID: 'test@example.com',
+					loginSessionID: 'session-id',
+				},
+			};
+
+			const secretKeyResponse = {
+				returnData: 'secret-key-data',
+			};
+
+			const empResponse = {
+				status: 1,
+				redirect_uri: 'lgaccount.lgsmartthinq:/?code=test-code&oauth2_backend_url=https://test.com/',
+			};
+
+			mockAxios.onPost(`${gatewayData.empSpxUri}/preLogin`).reply(200, preLoginResponse);
+			mockAxios
+				.onPost(
+					new RegExp(`${gatewayData.empTermsUri.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/emp/v2.0/account/session/.*`),
+				)
+				.reply(200, accountResponse);
+			mockAxios
+				.onGet(`${gatewayData.empSpxUri}/searchKey?key_name=OAUTH_SECRETKEY&sever_type=OP`)
+				.reply(200, secretKeyResponse);
+			mockAxios
+				.onGet(new RegExp('https://emp-oauth.lgecloud.com/emp/oauth2/authorize/empsession.*'))
+				.reply(200, empResponse);
+			mockAxios.onPost(new RegExp('https://test.com/oauth/1.0/oauth2/token')).reply(500);
+
+			await expect(strategy.authenticate(testContext)).rejects.toThrow(AuthenticationError);
+		});
+
+		it('should return ThinqUserData on successful authentication', async () => {
+			const gatewayData = buildGatewayResponse();
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+
+			const preLoginResponse = {
+				signature: 'test-signature',
+				tStamp: '1234567890',
+				encrypted_pw: 'encrypted-password',
+			};
+
+			const accountResponse = {
+				account: {
+					userIDType: 'LGE',
+					country: 'US',
+					userID: 'test@example.com',
+					loginSessionID: 'session-id',
+				},
+			};
+
+			const secretKeyResponse = {
+				returnData: 'secret-key-data',
+			};
+
+			const empResponse = {
+				status: 1,
+				redirect_uri: 'lgaccount.lgsmartthinq:/?code=test-code&oauth2_backend_url=https://test.com/',
+			};
+
+			const tokenResponse = {
+				access_token: 'access-token-123',
+				refresh_token: 'refresh-token-123',
+				expires_in: '3600',
+			};
+
+			mockAxios.onPost(`${gatewayData.empSpxUri}/preLogin`).reply(200, preLoginResponse);
+			mockAxios
+				.onPost(
+					new RegExp(`${gatewayData.empTermsUri.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/emp/v2.0/account/session/.*`),
+				)
+				.reply(200, accountResponse);
+			mockAxios
+				.onGet(`${gatewayData.empSpxUri}/searchKey?key_name=OAUTH_SECRETKEY&sever_type=OP`)
+				.reply(200, secretKeyResponse);
+			mockAxios
+				.onGet(new RegExp('https://emp-oauth.lgecloud.com/emp/oauth2/authorize/empsession.*'))
+				.reply(200, empResponse);
+			mockAxios.onPost(new RegExp('https://test.com/oauth/1.0/oauth2/token')).reply(200, tokenResponse);
+
+			const result = await strategy.authenticate(testContext);
+
+			expect(result).toBeDefined();
+			expect(result?.accessToken).toBe('access-token-123');
+			expect(result?.refreshToken).toBe('refresh-token-123');
+			expect(result?.country).toBe('US');
+			expect(result?.language).toBe('en');
+			expect(result?.expiresAtEpochSeconds).toBeGreaterThan(0);
+		});
+
+		it('should log authentication start message', async () => {
+			const gatewayData = buildGatewayResponse();
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+
+			const preLoginResponse = {
+				signature: 'test-signature',
+				tStamp: '1234567890',
+				encrypted_pw: 'encrypted-password',
+			};
+
+			mockAxios.onPost(`${gatewayData.empSpxUri}/preLogin`).reply(200, preLoginResponse);
+			mockAxios
+				.onPost(
+					new RegExp(`${gatewayData.empTermsUri.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/emp/v2.0/account/session/.*`),
+				)
+				.reply(401);
+
+			await expect(strategy.authenticate(testContext)).rejects.toThrow();
+			expect(mockLogger.notice).toHaveBeenCalledWith('Authenticating with LG ThinQ account credentials...');
+		});
+	});
+});

package/src/services/authentication/AccountAuthStrategy.ts

@@ -0,0 +1,209 @@
+import crypto from 'node:crypto';
+
+import axios from 'axios';
+import { AnsiLogger } from 'matterbridge/logger';
+
+import { AuthenticationError, InvalidCredentialsError } from '../../errors/index.js';
+import {
+	buildEmpDefaultHeaders,
+	formatRfc2822Utc,
+	Gateway,
+	signThinqMessage,
+	THINQ_CLIENT_ID,
+	THINQ_OAUTH_CLIENT_KEY,
+	THINQ_OAUTH_SECRET_KEY,
+} from '../thinq/gateway.js';
+import { ThinqSession } from '../thinq/session.js';
+import { ThinqApiClient } from '../thinq/thinqApiClient.js';
+import type { ThinqAuthContext, ThinqUserData } from './AuthContext.js';
+import type { IAuthStrategy } from './IAuthStrategy.js';
+
+interface PreLoginResponse {
+	signature: string;
+	tStamp: string;
+	encrypted_pw: string;
+}
+
+interface AccountSessionResponse {
+	userIDType: string;
+	country: string;
+	userID: string;
+	loginSessionID: string;
+}
+
+interface EmpAuthorizeResponse {
+	status: number;
+	message?: string;
+	redirect_uri: string;
+}
+
+interface TokenResponse {
+	access_token: string;
+	refresh_token: string;
+	expires_in: string;
+}
+
+const EMP_REDIRECT_URI = 'lgaccount.lgsmartthinq:/';
+
+/** True when `err` is an Axios error with a 4xx HTTP status (i.e. a real bad-credentials/rejected-request response). */
+function isClientErrorResponse(err: unknown): boolean {
+	if (!axios.isAxiosError(err)) {
+		return false;
+	}
+
+	const status = err.response?.status;
+
+	return status !== undefined && status >= 400 && status < 500;
+}
+
+/**
+ * Account (username/password) authentication strategy. Ports the 5-call EMP login chain
+ * (`Auth.login`→`loginStep2`, `homebridge-lg-thinq/src/lib/Auth.ts:99-229`): SHA-512 password hash,
+ * preLogin, EMP session, OAuth secret-key lookup, HMAC-SHA1-signed empsession authorize, then oauth2 token exchange.
+ */
+export class AccountAuthStrategy implements IAuthStrategy {
+	constructor(
+		private readonly apiClient: ThinqApiClient,
+		private readonly logger: AnsiLogger,
+	) {}
+
+	public async authenticate(context: ThinqAuthContext): Promise<ThinqUserData | undefined> {
+		if (!context.username || !context.password) {
+			throw new InvalidCredentialsError(context.username);
+		}
+
+		this.logger.notice('Authenticating with LG ThinQ account credentials...');
+
+		const gatewayData = await this.apiClient.getGateway();
+		const gateway = new Gateway(gatewayData);
+		const hashedPassword = crypto.createHash('sha512').update(context.password).digest('hex');
+
+		return this.loginStep2(gateway, context.username, hashedPassword, context.country, context.language);
+	}
+
+	private async loginStep2(
+		gateway: Gateway,
+		username: string,
+		encryptedPassword: string,
+		country: string,
+		language: string,
+	): Promise<ThinqUserData> {
+		const headers: Record<string, string> = { ...buildEmpDefaultHeaders(gateway) };
+
+		const preLoginData = new URLSearchParams({
+			user_auth2: encryptedPassword,
+			log_param: `login request / user_id : ${username} / third_party : null / svc_list : SVC202,SVC710 / 3rd_service : `,
+		});
+
+		const preLogin = await axios
+			.post<PreLoginResponse>(`${gateway.loginBaseUrl}preLogin`, preLoginData.toString(), { headers })
+			.then((res) => res.data)
+			.catch((err: unknown) => {
+				if (isClientErrorResponse(err)) {
+					throw new InvalidCredentialsError(username);
+				}
+
+				throw new AuthenticationError('LG pre-login failed.', { cause: err });
+			});
+
+		headers['X-Signature'] = preLogin.signature;
+		headers['X-Timestamp'] = preLogin.tStamp;
+
+		const sessionData = new URLSearchParams({
+			user_auth2: preLogin.encrypted_pw,
+			password_hash_prameter_flag: 'Y',
+			svc_list: 'SVC202,SVC710',
+		});
+
+		const loginUrl = `${gateway.empBaseUrl}emp/v2.0/account/session/${encodeURIComponent(username)}`;
+		const account = await axios
+			.post<{ account: AccountSessionResponse }>(loginUrl, sessionData.toString(), { headers })
+			.then((res) => res.data.account)
+			.catch((err: unknown) => {
+				if (isClientErrorResponse(err)) {
+					throw new InvalidCredentialsError(username);
+				}
+
+				throw new AuthenticationError('LG account login failed.', { cause: err });
+			});
+
+		const secretKeyUrl = `${gateway.loginBaseUrl}searchKey?key_name=OAUTH_SECRETKEY&sever_type=OP`;
+		const secretKey = await axios
+			.get<{ returnData: string }>(secretKeyUrl)
+			.then((res) => res.data.returnData)
+			.catch((err: unknown) => {
+				throw new AuthenticationError('LG OAuth key lookup failed.', { cause: err });
+			});
+
+		const timestamp = formatRfc2822Utc(new Date());
+		const empParams = new URLSearchParams({
+			account_type: account.userIDType,
+			client_id: THINQ_CLIENT_ID,
+			country_code: account.country,
+			redirect_uri: EMP_REDIRECT_URI,
+			response_type: 'code',
+			state: '12345',
+			username: account.userID,
+		});
+		const empUrl = new URL(`https://emp-oauth.lgecloud.com/emp/oauth2/authorize/empsession?${empParams.toString()}`);
+		const empSignature = signThinqMessage(`${empUrl.pathname}${empUrl.search}\n${timestamp}`, secretKey);
+
+		const authorize = await axios
+			.get<EmpAuthorizeResponse>(empUrl.href, {
+				headers: {
+					'lgemp-x-app-key': THINQ_OAUTH_CLIENT_KEY,
+					'lgemp-x-date': timestamp,
+					'lgemp-x-session-key': account.loginSessionID,
+					'lgemp-x-signature': empSignature,
+					Accept: 'application/json',
+					'X-Device-Type': 'M01',
+					'X-Device-Platform': 'ADR',
+					'Content-Type': 'application/x-www-form-urlencoded',
+				},
+			})
+			.then((res) => res.data)
+			.catch((err: unknown) => {
+				throw new AuthenticationError('LG OAuth authorization failed.', { cause: err });
+			});
+
+		if (authorize.status !== 1) {
+			throw new AuthenticationError(authorize.message ?? 'LG OAuth authorization was rejected.');
+		}
+
+		const redirectUri = new URL(authorize.redirect_uri);
+		const code = redirectUri.searchParams.get('code') ?? '';
+		const oauth2BackendUrl = redirectUri.searchParams.get('oauth2_backend_url') ?? gateway.loginBaseUrl;
+
+		const tokenData = new URLSearchParams({
+			code,
+			grant_type: 'authorization_code',
+			redirect_uri: EMP_REDIRECT_URI,
+		});
+		const requestPath = `/oauth/1.0/oauth2/token?${tokenData.toString()}`;
+		const tokenTimestamp = formatRfc2822Utc(new Date());
+
+		const token = await axios
+			.post<TokenResponse>(`${oauth2BackendUrl}oauth/1.0/oauth2/token`, tokenData.toString(), {
+				headers: {
+					'x-lge-app-os': 'ADR',
+					'x-lge-appkey': THINQ_CLIENT_ID,
+					'x-lge-oauth-signature': signThinqMessage(`${requestPath}\n${tokenTimestamp}`, THINQ_OAUTH_SECRET_KEY),
+					'x-lge-oauth-date': tokenTimestamp,
+					Accept: 'application/json',
+					'Content-Type': 'application/x-www-form-urlencoded',
+				},
+			})
+			.then((res) => res.data)
+			.catch((err: unknown) => {
+				throw new AuthenticationError('LG token exchange failed.', { cause: err });
+			});
+
+		return {
+			accessToken: token.access_token,
+			refreshToken: token.refresh_token,
+			expiresAtEpochSeconds: ThinqSession.expiryFromExpiresIn(Number.parseInt(token.expires_in, 10)),
+			country,
+			language,
+		};
+	}
+}

package/src/services/authentication/AuthContext.ts

@@ -0,0 +1,19 @@
+/** Context object passed to ThinQ authentication strategies. */
+export interface ThinqAuthContext {
+	readonly username?: string;
+	readonly password?: string;
+	readonly refreshToken?: string;
+	readonly country: string;
+	readonly language: string;
+}
+
+/** Result of a successful ThinQ authentication, persisted across restarts. */
+export interface ThinqUserData {
+	accessToken: string;
+	refreshToken: string;
+	expiresAtEpochSeconds: number;
+	country: string;
+	language: string;
+	/** LG's numeric account profile ID (`userNo`), fetched post-login and required for `x-user-no`/`x-client-id`. */
+	userNumber?: string;
+}