Add OAuth2 token management and storage implementation

workers/main/src/common/errors/OAuth2Error.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { OAuth2Error } from './OAuth2Error';
+
+describe('OAuth2Error', () => {
+  it('should set the message, name, and default error code', () => {
+    const err = new OAuth2Error('test message');
+
+    expect(err.message).toBe('test message');
+    expect(err.name).toBe('OAuth2Error');
+    expect(err.code).toBe('UNKNOWN_OAUTH2_ERROR');
+  });
+
+  it('should set the message, name, and custom error code', () => {
+    const err = new OAuth2Error('test message', 'CUSTOM_ERROR');
+
+    expect(err.message).toBe('test message');
+    expect(err.name).toBe('OAuth2Error');
+    expect(err.code).toBe('CUSTOM_ERROR');
+  });
+});

workers/main/src/common/errors/OAuth2Error.ts

@@ -0,0 +1,10 @@
+import { AppError } from './AppError';
+
+export class OAuth2Error extends AppError {
+  public readonly code: string;
+
+  constructor(message: string, code: string = 'UNKNOWN_OAUTH2_ERROR') {
+    super(message, 'OAuth2Error');
+    this.code = code;
+  }
+}

workers/main/src/common/errors/index.ts

@@ -1,6 +1,7 @@
 export * from './AppError';
 export * from './FileUtilsError';
 export * from './FinAppRepositoryError';
+export * from './OAuth2Error';
 export * from './QuickBooksRepositoryError';
 export * from './SlackRepositoryError';
 export * from './TargetUnitRepositoryError';

workers/main/src/services/OAuth2/FileTokenStorage.ts

@@ -0,0 +1,72 @@
+import { promises as fs } from 'fs';
+import { join } from 'path';
+
+import { OAuth2Error } from '../../common/errors';
+import { TokenStorageProvider } from './types';
+import { TokenData } from './types';
+
+export class FileTokenStorage implements TokenStorageProvider {
+  private readonly tokenFilePath: string;
+  private readonly serviceName: string;
+
+  constructor(serviceName: string = 'qbo', tokenFilePath?: string) {
+    this.serviceName = serviceName;
+    this.tokenFilePath =
+      tokenFilePath ||
+      join(process.cwd(), 'data', 'oauth2_tokens', `${serviceName}.json`);
+  }
+
+  async save(tokenData: TokenData): Promise<void> {
+    try {
+      const dir = join(this.tokenFilePath, '..');
+
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(
+        this.tokenFilePath,
+        JSON.stringify(tokenData, null, 2),
+      );
+    } catch {
+      throw new OAuth2Error('Failed to save token data to file');
+    }
+  }
+
+  async load(): Promise<TokenData | null> {
+    try {
+      const data = await fs.readFile(this.tokenFilePath, 'utf8');
+      const tokenData = JSON.parse(data) as TokenData;
+
+      if (!this.isValidTokenData(tokenData)) {
+        return null;
+      }
+
+      return tokenData;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return null;
+      }
+
+      return null;
+    }
+  }
+
+  async clear(): Promise<void> {
+    try {
+      await fs.unlink(this.tokenFilePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw new OAuth2Error('Failed to clear token data from file');
+      }
+    }
+  }
+
+  private isValidTokenData(data: unknown): data is TokenData {
+    return (
+      typeof data === 'object' &&
+      data !== null &&
+      typeof (data as TokenData).access_token === 'string' &&
+      typeof (data as TokenData).refresh_token === 'string' &&
+      typeof (data as TokenData).expires_at === 'number' &&
+      typeof (data as TokenData).token_type === 'string'
+    );
+  }
+}

workers/main/src/services/OAuth2/OAuth2TokenManager.basic.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { OAuth2TokenManager } from './OAuth2TokenManager';
+import { TokenData } from './types';
+
+vi.mock('./FileTokenStorage', () => ({
+  FileTokenStorage: vi.fn().mockImplementation(() => ({
+    save: vi.fn().mockResolvedValue(undefined),
+    load: vi.fn().mockResolvedValue(null),
+    clear: vi.fn().mockResolvedValue(undefined),
+  })),
+}));
+
+vi.mock('./OAuth2TokenRefreshProvider', () => ({
+  OAuth2TokenRefreshProvider: vi.fn().mockImplementation(() => ({
+    refreshToken: vi.fn().mockResolvedValue({
+      access_token: 'new-access-token',
+      refresh_token: 'new-refresh-token',
+      expires_at: Date.now() + 3600000,
+      token_type: 'Bearer',
+    }),
+  })),
+}));
+
+vi.mock('../../configs/qbo', () => ({
+  qboConfig: {
+    clientId: 'test-client-id',
+    clientSecret: 'test-client-secret',
+    refreshToken: 'test-refresh-token',
+    tokenUrl: 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer',
+  },
+}));
+
+describe('OAuth2TokenManager - Basic', () => {
+  let tokenManager: OAuth2TokenManager;
+
+  beforeEach(async () => {
+    tokenManager = new OAuth2TokenManager('qbo', 'test-refresh-token');
+    // Wait for async initialization to complete
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should create OAuth2TokenManager instance', () => {
+    expect(tokenManager).toBeInstanceOf(OAuth2TokenManager);
+  });
+
+  it('should return false when no token is set', () => {
+    expect(tokenManager.isTokenValid()).toBe(false);
+  });
+
+  it('should return false when token is expired', () => {
+    const expiredTokenData: TokenData = {
+      access_token: 'expired-token',
+      refresh_token: 'refresh-token',
+      expires_at: Date.now() - 3600000,
+      token_type: 'Bearer',
+    };
+
+    tokenManager.setTokenDataForTesting(expiredTokenData);
+    expect(tokenManager.isTokenValid()).toBe(false);
+  });
+
+  it('should return true when token is valid', () => {
+    const validTokenData: TokenData = {
+      access_token: 'valid-token',
+      refresh_token: 'refresh-token',
+      expires_at: Date.now() + 3600000,
+      token_type: 'Bearer',
+    };
+
+    tokenManager.setTokenDataForTesting(validTokenData);
+    expect(tokenManager.isTokenValid()).toBe(true);
+  });
+
+  it('should return refresh token from config when no cached token', () => {
+    expect(tokenManager.getCurrentRefreshToken()).toBe('test-refresh-token');
+  });
+
+  it('should return cached refresh token when available', () => {
+    const tokenData: TokenData = {
+      access_token: 'test-access-token',
+      refresh_token: 'cached-refresh-token',
+      expires_at: Date.now() + 3600000,
+      token_type: 'Bearer',
+    };
+
+    tokenManager.setTokenDataForTesting(tokenData);
+    expect(tokenManager.getCurrentRefreshToken()).toBe('cached-refresh-token');
+  });
+
+  it('should return cached access token when valid', async () => {
+    const tokenData: TokenData = {
+      access_token: 'valid-access-token',
+      refresh_token: 'refresh-token',
+      expires_at: Date.now() + 3600000,
+      token_type: 'Bearer',
+    };
+
+    tokenManager.setTokenDataForTesting(tokenData);
+    const accessToken = await tokenManager.getAccessToken();
+
+    expect(accessToken).toBe('valid-access-token');
+  });
+
+  it('should refresh token when expired and return new access token', async () => {
+    const expiredTokenData: TokenData = {
+      access_token: 'expired-access-token',
+      refresh_token: 'refresh-token',
+      expires_at: Date.now() - 3600000,
+      token_type: 'Bearer',
+    };
+
+    tokenManager.setTokenDataForTesting(expiredTokenData);
+    const accessToken = await tokenManager.getAccessToken();
+
+    expect(accessToken).toBe('new-access-token');
+  });
+
+  it('should handle malformed token data gracefully', () => {
+    // Test that the manager correctly handles invalid token data
+    // by using the default refresh token and reporting token as invalid
+    expect(tokenManager.getCurrentRefreshToken()).toBe('test-refresh-token');
+    expect(tokenManager.isTokenValid()).toBe(false);
+  });
+});

workers/main/src/services/OAuth2/OAuth2TokenManager.errors.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { OAuth2TokenManager } from './OAuth2TokenManager';
+import { TokenData } from './types';
+
+vi.mock('./FileTokenStorage', () => ({
+  FileTokenStorage: vi.fn().mockImplementation(() => ({
+    save: vi.fn().mockResolvedValue(undefined),
+    load: vi.fn().mockResolvedValue(null),
+    clear: vi.fn().mockResolvedValue(undefined),
+  })),
+}));
+
+vi.mock('./OAuth2TokenRefreshProvider', () => ({
+  OAuth2TokenRefreshProvider: vi.fn().mockImplementation(() => ({
+    refreshToken: vi.fn().mockResolvedValue({
+      access_token: 'new-access-token',
+      refresh_token: 'new-refresh-token',
+      expires_at: Date.now() + 3600000,
+      token_type: 'Bearer',
+    }),
+  })),
+}));
+
+vi.mock('../../configs/qbo', () => ({
+  qboConfig: {
+    clientId: 'test-client-id',
+    clientSecret: 'test-client-secret',
+    refreshToken: 'test-refresh-token',
+    tokenUrl: 'https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer',
+  },
+}));
+
+describe('OAuth2TokenManager - Error Handling', () => {
+  let tokenManager: OAuth2TokenManager;
+
+  beforeEach(async () => {
+    tokenManager = new OAuth2TokenManager('qbo', 'test-refresh-token');
+    // Wait for async initialization to complete
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('token validation', () => {
+    it('should return false for empty access token', () => {
+      const tokenData: TokenData = {
+        access_token: '',
+        refresh_token: 'refresh-token',
+        expires_at: Date.now() + 3600000,
+        token_type: 'Bearer',
+      };
+
+      tokenManager.setTokenDataForTesting(tokenData);
+      expect(tokenManager.isTokenValid()).toBe(false);
+    });
+
+    it('should return false for null access token', () => {
+      const tokenData: TokenData = {
+        access_token: null as unknown as string,
+        refresh_token: 'refresh-token',
+        expires_at: Date.now() + 3600000,
+        token_type: 'Bearer',
+      };
+
+      tokenManager.setTokenDataForTesting(tokenData);
+      expect(tokenManager.isTokenValid()).toBe(false);
+    });
+
+    it('should return false for expired token', () => {
+      const tokenData: TokenData = {
+        access_token: 'expired-token',
+        refresh_token: 'refresh-token',
+        expires_at: Date.now() - 3600000,
+        token_type: 'Bearer',
+      };
+
+      tokenManager.setTokenDataForTesting(tokenData);
+      expect(tokenManager.isTokenValid()).toBe(false);
+    });
+
+    it('should return true for valid token', () => {
+      const tokenData: TokenData = {
+        access_token: 'valid-token',
+        refresh_token: 'refresh-token',
+        expires_at: Date.now() + 3600000,
+        token_type: 'Bearer',
+      };
+
+      tokenManager.setTokenDataForTesting(tokenData);
+      expect(tokenManager.isTokenValid()).toBe(true);
+    });
+  });
+
+  describe('refresh token handling', () => {
+    it('should return default refresh token when no cached token', () => {
+      expect(tokenManager.getCurrentRefreshToken()).toBe('test-refresh-token');
+    });
+
+    it('should return cached refresh token when available', () => {
+      const tokenData: TokenData = {
+        access_token: 'test-access-token',
+        refresh_token: 'cached-refresh-token',
+        expires_at: Date.now() + 3600000,
+        token_type: 'Bearer',
+      };
+
+      tokenManager.setTokenDataForTesting(tokenData);
+      expect(tokenManager.getCurrentRefreshToken()).toBe(
+        'cached-refresh-token',
+      );
+    });
+  });
+});