matterbridge-lg-thinq-plugin 0.1.0

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

@@ -0,0 +1,217 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { asPartial, createMockLogger } from '../../tests/helpers/testUtils.js';
+import type { ThinqApiClient } from '../thinq/thinqApiClient.js';
+import { AccountAuthStrategy } from './AccountAuthStrategy.js';
+import type { ThinqAuthContext, ThinqUserData } from './AuthContext.js';
+import { AuthenticationCoordinator } from './AuthenticationCoordinator.js';
+import { TokenAuthStrategy } from './TokenAuthStrategy.js';
+
+describe('AuthenticationCoordinator', () => {
+	let mockAccountStrategy: AccountAuthStrategy;
+	let mockTokenStrategy: TokenAuthStrategy;
+	let mockApiClient: ThinqApiClient;
+	let mockLogger: ReturnType<typeof createMockLogger>;
+	let coordinator: AuthenticationCoordinator;
+
+	const testUserData: ThinqUserData = {
+		accessToken: 'access-token-123',
+		refreshToken: 'refresh-token-123',
+		expiresAtEpochSeconds: Math.floor(Date.now() / 1000) + 3600,
+		country: 'US',
+		language: 'en',
+	};
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockLogger = createMockLogger();
+		mockAccountStrategy = asPartial<AccountAuthStrategy>({
+			authenticate: vi.fn(),
+		});
+		mockTokenStrategy = asPartial<TokenAuthStrategy>({
+			authenticate: vi.fn(),
+		});
+		mockApiClient = asPartial<ThinqApiClient>({
+			getUserNumber: vi.fn(),
+			setUserNumber: vi.fn(),
+		});
+		coordinator = new AuthenticationCoordinator(mockAccountStrategy, mockTokenStrategy, mockApiClient, mockLogger);
+	});
+
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	describe('authenticate', () => {
+		it('should dispatch to AccountAuthStrategy when method is "account"', async () => {
+			vi.mocked(mockAccountStrategy.authenticate).mockResolvedValue(testUserData);
+			vi.mocked(mockApiClient.getUserNumber).mockResolvedValue('user-number-123');
+
+			const context = asPartial<ThinqAuthContext>({
+				username: 'test@example.com',
+				password: 'password',
+				country: 'US',
+				language: 'en',
+			});
+
+			await coordinator.authenticate('account', context);
+
+			expect(mockAccountStrategy.authenticate).toHaveBeenCalledWith(context);
+		});
+
+		it('should dispatch to TokenAuthStrategy when method is "token"', async () => {
+			vi.mocked(mockTokenStrategy.authenticate).mockResolvedValue(testUserData);
+			vi.mocked(mockApiClient.getUserNumber).mockResolvedValue('user-number-123');
+
+			const context = asPartial<ThinqAuthContext>({
+				refreshToken: 'refresh-token-123',
+				country: 'US',
+				language: 'en',
+			});
+
+			await coordinator.authenticate('token', context);
+
+			expect(mockTokenStrategy.authenticate).toHaveBeenCalledWith(context);
+		});
+
+		it('should throw Error with available methods when method is unknown', async () => {
+			const context = asPartial<ThinqAuthContext>({
+				country: 'US',
+				language: 'en',
+			});
+
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			await expect(coordinator.authenticate('invalid-method' as any, context)).rejects.toThrow(
+				/Unknown ThinQ authentication method/,
+			);
+		});
+
+		it('should include available methods in error message', async () => {
+			const context = asPartial<ThinqAuthContext>({
+				country: 'US',
+				language: 'en',
+			});
+
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			const error = await coordinator.authenticate('unknown' as any, context).catch((e: unknown) => e);
+			expect(error).toBeInstanceOf(Error);
+			expect((error as Error).message).toContain('Unknown ThinQ authentication method');
+			expect(mockLogger.error).toHaveBeenCalledWith(expect.stringContaining('account'));
+			expect(mockLogger.error).toHaveBeenCalledWith(expect.stringContaining('token'));
+		});
+
+		it('should fetch user number after successful authentication', async () => {
+			vi.mocked(mockAccountStrategy.authenticate).mockResolvedValue(testUserData);
+			vi.mocked(mockApiClient.getUserNumber).mockResolvedValue('user-number-456');
+
+			const context = asPartial<ThinqAuthContext>({
+				username: 'test@example.com',
+				password: 'password',
+				country: 'US',
+				language: 'en',
+			});
+
+			await coordinator.authenticate('account', context);
+
+			expect(mockApiClient.getUserNumber).toHaveBeenCalledWith('access-token-123');
+		});
+
+		it('should set user number on API client', async () => {
+			vi.mocked(mockAccountStrategy.authenticate).mockResolvedValue(testUserData);
+			vi.mocked(mockApiClient.getUserNumber).mockResolvedValue('user-number-789');
+
+			const context = asPartial<ThinqAuthContext>({
+				username: 'test@example.com',
+				password: 'password',
+				country: 'US',
+				language: 'en',
+			});
+
+			await coordinator.authenticate('account', context);
+
+			expect(mockApiClient.setUserNumber).toHaveBeenCalledWith('user-number-789');
+		});
+
+		it('should return user data with user number added', async () => {
+			vi.mocked(mockAccountStrategy.authenticate).mockResolvedValue(testUserData);
+			vi.mocked(mockApiClient.getUserNumber).mockResolvedValue('user-number-999');
+
+			const context = asPartial<ThinqAuthContext>({
+				username: 'test@example.com',
+				password: 'password',
+				country: 'US',
+				language: 'en',
+			});
+
+			const result = await coordinator.authenticate('account', context);
+
+			expect(result?.userNumber).toBe('user-number-999');
+			expect(result?.accessToken).toBe(testUserData.accessToken);
+			expect(result?.refreshToken).toBe(testUserData.refreshToken);
+		});
+
+		it('should return undefined when strategy returns undefined', async () => {
+			vi.mocked(mockAccountStrategy.authenticate).mockResolvedValue(undefined);
+
+			const context = asPartial<ThinqAuthContext>({
+				username: 'test@example.com',
+				password: 'password',
+				country: 'US',
+				language: 'en',
+			});
+
+			const result = await coordinator.authenticate('account', context);
+
+			expect(result).toBeUndefined();
+			expect(mockApiClient.getUserNumber).not.toHaveBeenCalled();
+		});
+
+		it('should log debug message before resolving user number', async () => {
+			vi.mocked(mockAccountStrategy.authenticate).mockResolvedValue(testUserData);
+			vi.mocked(mockApiClient.getUserNumber).mockResolvedValue('user-number-123');
+
+			const context = asPartial<ThinqAuthContext>({
+				username: 'test@example.com',
+				password: 'password',
+				country: 'US',
+				language: 'en',
+			});
+
+			await coordinator.authenticate('account', context);
+
+			expect(mockLogger.debug).toHaveBeenCalledWith(
+				'AuthenticationCoordinator: resolving ThinQ user number post-login',
+			);
+		});
+
+		it('should propagate getUserNumber errors', async () => {
+			vi.mocked(mockAccountStrategy.authenticate).mockResolvedValue(testUserData);
+			vi.mocked(mockApiClient.getUserNumber).mockRejectedValue(new Error('User number fetch failed'));
+
+			const context = asPartial<ThinqAuthContext>({
+				username: 'test@example.com',
+				password: 'password',
+				country: 'US',
+				language: 'en',
+			});
+
+			await expect(coordinator.authenticate('account', context)).rejects.toThrow('User number fetch failed');
+		});
+
+		it('should work with TokenAuthStrategy', async () => {
+			vi.mocked(mockTokenStrategy.authenticate).mockResolvedValue(testUserData);
+			vi.mocked(mockApiClient.getUserNumber).mockResolvedValue('user-number-token');
+
+			const context = asPartial<ThinqAuthContext>({
+				refreshToken: 'refresh-token-123',
+				country: 'US',
+				language: 'en',
+			});
+
+			const result = await coordinator.authenticate('token', context);
+
+			expect(result?.userNumber).toBe('user-number-token');
+			expect(mockTokenStrategy.authenticate).toHaveBeenCalledWith(context);
+		});
+	});
+});

package/src/services/authentication/AuthenticationCoordinator.ts

@@ -0,0 +1,59 @@
+import { AnsiLogger } from 'matterbridge/logger';
+
+import type { ThinqApiClient } from '../thinq/thinqApiClient.js';
+import { AccountAuthStrategy } from './AccountAuthStrategy.js';
+import type { ThinqAuthContext, ThinqUserData } from './AuthContext.js';
+import type { IAuthStrategy } from './IAuthStrategy.js';
+import { TokenAuthStrategy } from './TokenAuthStrategy.js';
+
+export type ThinqAuthMethod = 'account' | 'token';
+
+/**
+ * Coordinates ThinQ authentication strategies based on the selected method. Also owns the mandatory
+ * post-login bootstrap step (`API.ready()`, `API.ts:392-399`): fetching the account's numeric profile ID
+ * (`userNumber`) and activating it on the shared `ThinqApiClient` so subsequent ThinQ2 calls (`service/homes`,
+ * etc.) send `x-user-no` and a per-session `x-client-id`. Centralized here so neither `AccountAuthStrategy`
+ * nor `TokenAuthStrategy` needs to duplicate the fetch-and-compute logic.
+ */
+export class AuthenticationCoordinator {
+	private readonly strategies: Map<string, IAuthStrategy>;
+
+	constructor(
+		accountStrategy: AccountAuthStrategy,
+		tokenStrategy: TokenAuthStrategy,
+		private readonly apiClient: ThinqApiClient,
+		private readonly logger: AnsiLogger,
+	) {
+		this.strategies = new Map<string, IAuthStrategy>([
+			['account', accountStrategy],
+			['token', tokenStrategy],
+		]);
+	}
+
+	/**
+	 * Authenticate user using the specified method.
+	 * @param method Authentication method ('account' or 'token')
+	 * @param context Authentication context containing credentials
+	 * @returns ThinqUserData if successful, undefined if further action required
+	 */
+	public async authenticate(method: ThinqAuthMethod, context: ThinqAuthContext): Promise<ThinqUserData | undefined> {
+		const strategy = this.strategies.get(method);
+
+		if (!strategy) {
+			const availableMethods = Array.from(this.strategies.keys()).join(', ');
+			this.logger.error(`Unknown ThinQ authentication method: ${method}. Available methods: ${availableMethods}`);
+			throw new Error(`Unknown ThinQ authentication method: ${method}`);
+		}
+
+		const userData = await strategy.authenticate(context);
+		if (!userData) {
+			return userData;
+		}
+
+		this.logger.debug('AuthenticationCoordinator: resolving ThinQ user number post-login');
+		const userNumber = await this.apiClient.getUserNumber(userData.accessToken);
+		this.apiClient.setUserNumber(userNumber);
+
+		return { ...userData, userNumber };
+	}
+}

package/src/services/authentication/IAuthStrategy.ts

@@ -0,0 +1,10 @@
+import type { ThinqAuthContext, ThinqUserData } from './AuthContext.js';
+
+/** Strategy interface for different ThinQ authentication methods. */
+export interface IAuthStrategy {
+	/**
+	 * Authenticate user with the provided context.
+	 * @returns ThinqUserData if authentication succeeds, undefined if further action required.
+	 */
+	authenticate(context: ThinqAuthContext): Promise<ThinqUserData | undefined>;
+}

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

@@ -0,0 +1,167 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { AuthenticationError } from '../../errors/index.js';
+import { asPartial, buildGatewayResponse, createMockLogger } from '../../tests/helpers/testUtils.js';
+import { ThinqSession } from '../thinq/session.js';
+import type { ThinqApiClient } from '../thinq/thinqApiClient.js';
+import type { ThinqAuthContext } from './AuthContext.js';
+import { TokenAuthStrategy } from './TokenAuthStrategy.js';
+
+describe('TokenAuthStrategy', () => {
+	let mockApiClient: ThinqApiClient;
+	let mockLogger: ReturnType<typeof createMockLogger>;
+	let strategy: TokenAuthStrategy;
+
+	const testContext: ThinqAuthContext = {
+		refreshToken: 'refresh-token-123',
+		country: 'US',
+		language: 'en',
+	};
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockLogger = createMockLogger();
+		mockApiClient = asPartial<ThinqApiClient>({
+			getGateway: vi.fn(),
+			refreshToken: vi.fn(),
+		});
+		strategy = new TokenAuthStrategy(mockApiClient, mockLogger);
+	});
+
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	describe('authenticate', () => {
+		it('should throw AuthenticationError when refreshToken is missing', async () => {
+			const contextWithoutToken = asPartial<ThinqAuthContext>({
+				country: 'US',
+				language: 'en',
+			});
+
+			await expect(strategy.authenticate(contextWithoutToken)).rejects.toThrow(AuthenticationError);
+		});
+
+		it('should throw AuthenticationError when refreshToken is empty string', async () => {
+			const contextWithEmptyToken = asPartial<ThinqAuthContext>({
+				refreshToken: '',
+				country: 'US',
+				language: 'en',
+			});
+
+			await expect(strategy.authenticate(contextWithEmptyToken)).rejects.toThrow(AuthenticationError);
+		});
+
+		it('should call getGateway before refreshing token', async () => {
+			const gatewayData = buildGatewayResponse();
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+			vi.mocked(mockApiClient.refreshToken).mockResolvedValue(
+				new ThinqSession('new-access-token', 'refresh-token-123', Math.floor(Date.now() / 1000) + 3600),
+			);
+
+			await strategy.authenticate(testContext);
+
+			expect(mockApiClient.getGateway).toHaveBeenCalled();
+		});
+
+		it('should call refreshToken with a ThinqSession containing the refresh token', async () => {
+			const gatewayData = buildGatewayResponse();
+			const newSession = new ThinqSession(
+				'new-access-token',
+				'refresh-token-123',
+				Math.floor(Date.now() / 1000) + 3600,
+			);
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+			vi.mocked(mockApiClient.refreshToken).mockResolvedValue(newSession);
+
+			await strategy.authenticate(testContext);
+
+			expect(mockApiClient.refreshToken).toHaveBeenCalled();
+			const callArg = vi.mocked(mockApiClient.refreshToken).mock.calls[0][0];
+			expect(callArg.refreshToken).toBe('refresh-token-123');
+		});
+
+		it('should return ThinqUserData with tokens from refreshToken response', async () => {
+			const gatewayData = buildGatewayResponse();
+			const newSession = new ThinqSession(
+				'new-access-token',
+				'refresh-token-updated',
+				Math.floor(Date.now() / 1000) + 3600,
+			);
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+			vi.mocked(mockApiClient.refreshToken).mockResolvedValue(newSession);
+
+			const result = await strategy.authenticate(testContext);
+
+			expect(result).toBeDefined();
+			expect(result?.accessToken).toBe('new-access-token');
+			expect(result?.refreshToken).toBe('refresh-token-updated');
+			expect(result?.country).toBe('US');
+			expect(result?.language).toBe('en');
+			expect(result?.expiresAtEpochSeconds).toBeGreaterThan(0);
+		});
+
+		it('should preserve country and language from context', async () => {
+			const contextWithDifferentLocale = asPartial<ThinqAuthContext>({
+				refreshToken: 'refresh-token-123',
+				country: 'KR',
+				language: 'ko',
+			});
+
+			const gatewayData = buildGatewayResponse();
+			const newSession = new ThinqSession(
+				'new-access-token',
+				'refresh-token-123',
+				Math.floor(Date.now() / 1000) + 3600,
+			);
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+			vi.mocked(mockApiClient.refreshToken).mockResolvedValue(newSession);
+
+			const result = await strategy.authenticate(contextWithDifferentLocale);
+
+			expect(result?.country).toBe('KR');
+			expect(result?.language).toBe('ko');
+		});
+
+		it('should log authentication start message', async () => {
+			const gatewayData = buildGatewayResponse();
+			const newSession = new ThinqSession(
+				'new-access-token',
+				'refresh-token-123',
+				Math.floor(Date.now() / 1000) + 3600,
+			);
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+			vi.mocked(mockApiClient.refreshToken).mockResolvedValue(newSession);
+
+			await strategy.authenticate(testContext);
+
+			expect(mockLogger.notice).toHaveBeenCalledWith('Authenticating with LG ThinQ refresh token...');
+		});
+
+		it('should log debug message before getting gateway', async () => {
+			const gatewayData = buildGatewayResponse();
+			const newSession = new ThinqSession(
+				'new-access-token',
+				'refresh-token-123',
+				Math.floor(Date.now() / 1000) + 3600,
+			);
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+			vi.mocked(mockApiClient.refreshToken).mockResolvedValue(newSession);
+
+			await strategy.authenticate(testContext);
+
+			expect(mockLogger.debug).toHaveBeenCalledWith(
+				'TokenAuthStrategy: resolving gateway before refresh-token exchange',
+			);
+		});
+
+		it('should propagate errors from refreshToken', async () => {
+			const gatewayData = buildGatewayResponse();
+			const error = new Error('Token refresh failed');
+			vi.mocked(mockApiClient.getGateway).mockResolvedValue(gatewayData);
+			vi.mocked(mockApiClient.refreshToken).mockRejectedValue(error);
+
+			await expect(strategy.authenticate(testContext)).rejects.toThrow('Token refresh failed');
+		});
+	});
+});

package/src/services/authentication/TokenAuthStrategy.ts

@@ -0,0 +1,40 @@
+import { AnsiLogger } from 'matterbridge/logger';
+
+import { AuthenticationError } from '../../errors/index.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';
+
+/**
+ * Refresh-token authentication strategy. Skips the 5-call EMP login chain entirely and exchanges a
+ * pre-obtained `refresh_token` directly for an access token (`Auth.refreshNewToken`, `Auth.ts:347-391`).
+ */
+export class TokenAuthStrategy implements IAuthStrategy {
+	constructor(
+		private readonly apiClient: ThinqApiClient,
+		private readonly logger: AnsiLogger,
+	) {}
+
+	public async authenticate(context: ThinqAuthContext): Promise<ThinqUserData | undefined> {
+		if (!context.refreshToken) {
+			throw new AuthenticationError('A ThinQ refresh token is required for token-based authentication.');
+		}
+
+		this.logger.notice('Authenticating with LG ThinQ refresh token...');
+		this.logger.debug('TokenAuthStrategy: resolving gateway before refresh-token exchange');
+
+		await this.apiClient.getGateway();
+
+		const session = new ThinqSession('', context.refreshToken, 0);
+		const refreshed = await this.apiClient.refreshToken(session);
+
+		return {
+			accessToken: refreshed.accessToken,
+			refreshToken: refreshed.refreshToken,
+			expiresAtEpochSeconds: refreshed.expiresAtEpochSeconds,
+			country: context.country,
+			language: context.language,
+		};
+	}
+}

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

@@ -0,0 +1,149 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { PlatformConfigManager } from '../../platform/platformConfigManager.js';
+import { asPartial, createMockLogger, createMockNodePersist } from '../../tests/helpers/testUtils.js';
+import type { ThinqUserData } from './AuthContext.js';
+import { UserDataRepository } from './UserDataRepository.js';
+
+describe('UserDataRepository', () => {
+	let mockPersist: ReturnType<typeof createMockNodePersist>;
+	let mockConfigManager: PlatformConfigManager;
+	let mockLogger: ReturnType<typeof createMockLogger>;
+	let repository: UserDataRepository;
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockPersist = createMockNodePersist();
+		mockLogger = createMockLogger();
+		mockConfigManager = asPartial<PlatformConfigManager>({
+			country: 'US',
+		});
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		repository = new UserDataRepository(mockPersist as any, mockConfigManager, mockLogger);
+	});
+
+	describe('loadUserData', () => {
+		it('should return undefined when no saved data exists', async () => {
+			vi.mocked(mockPersist.getItem).mockResolvedValue(undefined);
+
+			const result = await repository.loadUserData();
+
+			expect(result).toBeUndefined();
+			expect(mockPersist.getItem).toHaveBeenCalledWith('thinq:userData');
+		});
+
+		it('should return saved data when country matches config', async () => {
+			const userData: ThinqUserData = {
+				accessToken: 'access123',
+				refreshToken: 'refresh123',
+				expiresAtEpochSeconds: 9999999999,
+				country: 'US',
+				language: 'en',
+			};
+
+			vi.mocked(mockPersist.getItem).mockResolvedValue(userData);
+
+			const result = await repository.loadUserData();
+
+			expect(result).toEqual(userData);
+			expect(mockPersist.removeItem).not.toHaveBeenCalled();
+		});
+
+		it('should clear and return undefined when saved country does not match config', async () => {
+			const userData: ThinqUserData = {
+				accessToken: 'access123',
+				refreshToken: 'refresh123',
+				expiresAtEpochSeconds: 9999999999,
+				country: 'KR',
+				language: 'ko',
+			};
+
+			vi.mocked(mockPersist.getItem).mockResolvedValue(userData);
+
+			const result = await repository.loadUserData();
+
+			expect(result).toBeUndefined();
+			expect(mockPersist.removeItem).toHaveBeenCalledWith('thinq:userData');
+		});
+
+		it('should log debug message when no saved data found', async () => {
+			vi.mocked(mockPersist.getItem).mockResolvedValue(undefined);
+
+			await repository.loadUserData();
+
+			expect(mockLogger.debug).toHaveBeenCalledWith('No saved ThinQ userData found');
+		});
+
+		it('should log debug message when data is returned', async () => {
+			const userData: ThinqUserData = {
+				accessToken: 'access123',
+				refreshToken: 'refresh123',
+				expiresAtEpochSeconds: 9999999999,
+				country: 'US',
+				language: 'en',
+			};
+
+			vi.mocked(mockPersist.getItem).mockResolvedValue(userData);
+
+			await repository.loadUserData();
+
+			expect(mockLogger.debug).toHaveBeenCalledWith('Loading saved ThinQ userData');
+		});
+
+		it('should log debug message when country does not match', async () => {
+			const userData: ThinqUserData = {
+				accessToken: 'access123',
+				refreshToken: 'refresh123',
+				expiresAtEpochSeconds: 9999999999,
+				country: 'KR',
+				language: 'ko',
+			};
+
+			vi.mocked(mockPersist.getItem).mockResolvedValue(userData);
+
+			await repository.loadUserData();
+
+			expect(mockLogger.debug).toHaveBeenCalledWith(
+				'Saved ThinQ userData country does not match current config, ignoring saved data',
+			);
+		});
+	});
+
+	describe('saveUserData', () => {
+		it('should persist user data to storage', async () => {
+			const userData: ThinqUserData = {
+				accessToken: 'access123',
+				refreshToken: 'refresh123',
+				expiresAtEpochSeconds: 9999999999,
+				country: 'US',
+				language: 'en',
+			};
+
+			await repository.saveUserData(userData);
+
+			expect(mockPersist.setItem).toHaveBeenCalledWith('thinq:userData', userData);
+		});
+
+		it('should log debug message when data is saved', async () => {
+			const userData: ThinqUserData = {
+				accessToken: 'access123',
+				refreshToken: 'refresh123',
+				expiresAtEpochSeconds: 9999999999,
+				country: 'US',
+				language: 'en',
+			};
+
+			await repository.saveUserData(userData);
+
+			expect(mockLogger.debug).toHaveBeenCalledWith('ThinQ user data saved successfully');
+		});
+	});
+
+	describe('clearUserData', () => {
+		it('should remove user data from storage', async () => {
+			await repository.clearUserData();
+
+			expect(mockPersist.removeItem).toHaveBeenCalledWith('thinq:userData');
+		});
+	});
+});

package/src/services/authentication/UserDataRepository.ts

@@ -0,0 +1,46 @@
+import { AnsiLogger } from 'matterbridge/logger';
+import type NodePersist from 'node-persist';
+
+import { PlatformConfigManager } from '../../platform/platformConfigManager.js';
+import type { ThinqUserData } from './AuthContext.js';
+
+const STORAGE_KEY = 'thinq:userData';
+
+/** Repository for persisting and retrieving ThinQ user session data. */
+export class UserDataRepository {
+	constructor(
+		private readonly persist: NodePersist.LocalStorage,
+		private readonly configManager: PlatformConfigManager,
+		private readonly logger: AnsiLogger,
+	) {}
+
+	/** Load saved ThinQ user data, discarding it if the configured country no longer matches. */
+	public async loadUserData(): Promise<ThinqUserData | undefined> {
+		const savedUserData = (await this.persist.getItem(STORAGE_KEY)) as ThinqUserData | undefined;
+
+		if (!savedUserData) {
+			this.logger.debug('No saved ThinQ userData found');
+			return undefined;
+		}
+
+		if (savedUserData.country !== this.configManager.country) {
+			this.logger.debug('Saved ThinQ userData country does not match current config, ignoring saved data');
+			await this.clearUserData();
+			return undefined;
+		}
+
+		this.logger.debug('Loading saved ThinQ userData');
+		return savedUserData;
+	}
+
+	/** Save user data for future use. */
+	public async saveUserData(userData: ThinqUserData): Promise<void> {
+		await this.persist.setItem(STORAGE_KEY, userData);
+		this.logger.debug('ThinQ user data saved successfully');
+	}
+
+	/** Clear saved user data. */
+	public async clearUserData(): Promise<void> {
+		await this.persist.removeItem(STORAGE_KEY);
+	}
+}