@goodsamsoftware/freshbooks-mcp 1.0.0

package/dist/auth/oauth.d.ts

@@ -0,0 +1,93 @@
+/**
+ * FreshBooks OAuth2 Implementation
+ *
+ * Handles the complete OAuth2 Authorization Code flow for FreshBooks API:
+ * - Authorization URL generation
+ * - Authorization code exchange
+ * - Token refresh
+ * - Token management
+ * - Session status
+ */
+import { OAuthConfig, TokenData, AuthStatus, TokenStore } from './types.js';
+/**
+ * FreshBooks OAuth2 client
+ *
+ * Manages the complete OAuth2 flow for FreshBooks API authentication.
+ * Handles authorization, token exchange, refresh, and revocation.
+ */
+export declare class FreshBooksOAuth {
+    private config;
+    private tokenStore;
+    private static readonly AUTH_URL;
+    private static readonly TOKEN_URL;
+    private static readonly REVOKE_URL;
+    private static readonly EXPIRY_BUFFER_SECONDS;
+    constructor(config: OAuthConfig, tokenStore: TokenStore);
+    /**
+     * Generate OAuth2 authorization URL
+     *
+     * User must visit this URL to authorize the application.
+     * After authorization, FreshBooks redirects to the redirect_uri with an authorization code.
+     *
+     * @param state Optional state parameter for CSRF protection
+     * @returns Authorization URL for user to visit
+     */
+    generateAuthorizationUrl(state?: string): string;
+    /**
+     * Exchange authorization code for access tokens
+     *
+     * After user authorizes the application, exchange the authorization code
+     * for access and refresh tokens.
+     *
+     * @param code Authorization code from OAuth redirect
+     * @returns Token data including access and refresh tokens
+     * @throws OAuthError if exchange fails
+     */
+    exchangeCode(code: string): Promise<TokenData>;
+    /**
+     * Refresh expired access token using refresh token
+     *
+     * @returns New token data with refreshed access token
+     * @throws OAuthError if refresh fails or no refresh token available
+     */
+    refreshAccessToken(): Promise<TokenData>;
+    /**
+     * Get valid access token, automatically refreshing if needed
+     *
+     * This is the primary method for obtaining tokens for API requests.
+     * Automatically handles token refresh if token is expired or about to expire.
+     *
+     * @returns Valid access token
+     * @throws OAuthError if not authenticated or refresh fails
+     */
+    getValidToken(): Promise<string>;
+    /**
+     * Revoke current authentication tokens
+     *
+     * Revokes the access token with FreshBooks and clears local storage.
+     * Best effort - continues to clear local storage even if revocation fails.
+     */
+    revokeToken(): Promise<void>;
+    /**
+     * Get current authentication status
+     *
+     * @returns Authentication status including validity and expiration
+     */
+    getStatus(): Promise<AuthStatus>;
+    /**
+     * Update account and business selection in token data
+     *
+     * @param accountId FreshBooks account ID
+     * @param businessId FreshBooks business ID
+     */
+    setActiveAccount(accountId: string, businessId?: number): Promise<void>;
+    /**
+     * Parse OAuth token response into TokenData
+     */
+    private parseTokenResponse;
+    /**
+     * Map OAuth error codes to internal error codes
+     */
+    private mapErrorCode;
+}
+//# sourceMappingURL=oauth.d.ts.map

package/dist/auth/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAc,UAAU,EAAE,MAAM,YAAY,CAAC;AAqBxF;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,UAAU,CAAa;IAG/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAA4D;IAC5F,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAiD;IAClF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAkD;IAGpF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAO;gBAExC,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU;IAKvD;;;;;;;;OAQG;IACH,wBAAwB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;IAoBhD;;;;;;;;;OASG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IA6CpD;;;;;OAKG;IACG,kBAAkB,IAAI,OAAO,CAAC,SAAS,CAAC;IAiE9C;;;;;;;;OAQG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAuBtC;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBlC;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC;IAqCtC;;;;;OAKG;IACG,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB7E;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;OAEG;IACH,OAAO,CAAC,YAAY;CAWrB"}

package/dist/auth/oauth.js

@@ -0,0 +1,279 @@
+/**
+ * FreshBooks OAuth2 Implementation
+ *
+ * Handles the complete OAuth2 Authorization Code flow for FreshBooks API:
+ * - Authorization URL generation
+ * - Authorization code exchange
+ * - Token refresh
+ * - Token management
+ * - Session status
+ */
+import { OAuthError } from './types.js';
+/**
+ * FreshBooks OAuth2 client
+ *
+ * Manages the complete OAuth2 flow for FreshBooks API authentication.
+ * Handles authorization, token exchange, refresh, and revocation.
+ */
+export class FreshBooksOAuth {
+    config;
+    tokenStore;
+    // FreshBooks OAuth2 endpoints
+    static AUTH_URL = 'https://my.freshbooks.com/service/auth/oauth/authorize';
+    static TOKEN_URL = 'https://api.freshbooks.com/auth/oauth/token';
+    static REVOKE_URL = 'https://api.freshbooks.com/auth/oauth/revoke';
+    // Token expiration buffer (refresh if expires in less than 5 minutes)
+    static EXPIRY_BUFFER_SECONDS = 300;
+    constructor(config, tokenStore) {
+        this.config = config;
+        this.tokenStore = tokenStore;
+    }
+    /**
+     * Generate OAuth2 authorization URL
+     *
+     * User must visit this URL to authorize the application.
+     * After authorization, FreshBooks redirects to the redirect_uri with an authorization code.
+     *
+     * @param state Optional state parameter for CSRF protection
+     * @returns Authorization URL for user to visit
+     */
+    generateAuthorizationUrl(state) {
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            response_type: 'code',
+            redirect_uri: this.config.redirectUri,
+        });
+        // Add scopes if configured
+        if (this.config.scopes?.length) {
+            params.set('scope', this.config.scopes.join(' '));
+        }
+        // Add state parameter for CSRF protection
+        if (state) {
+            params.set('state', state);
+        }
+        return `${FreshBooksOAuth.AUTH_URL}?${params.toString()}`;
+    }
+    /**
+     * Exchange authorization code for access tokens
+     *
+     * After user authorizes the application, exchange the authorization code
+     * for access and refresh tokens.
+     *
+     * @param code Authorization code from OAuth redirect
+     * @returns Token data including access and refresh tokens
+     * @throws OAuthError if exchange fails
+     */
+    async exchangeCode(code) {
+        try {
+            const response = await fetch(FreshBooksOAuth.TOKEN_URL, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Api-Version': 'alpha',
+                },
+                body: JSON.stringify({
+                    grant_type: 'authorization_code',
+                    client_id: this.config.clientId,
+                    client_secret: this.config.clientSecret,
+                    code,
+                    redirect_uri: this.config.redirectUri,
+                }),
+            });
+            if (!response.ok) {
+                const error = await response.json();
+                throw new OAuthError(this.mapErrorCode(error.error), error.error_description || 'Failed to exchange authorization code', error);
+            }
+            const data = await response.json();
+            const tokenData = this.parseTokenResponse(data);
+            // Save tokens to store
+            await this.tokenStore.save(tokenData);
+            return tokenData;
+        }
+        catch (error) {
+            if (error instanceof OAuthError) {
+                throw error;
+            }
+            throw new OAuthError('token_exchange_failed', 'Failed to exchange authorization code', error);
+        }
+    }
+    /**
+     * Refresh expired access token using refresh token
+     *
+     * @returns New token data with refreshed access token
+     * @throws OAuthError if refresh fails or no refresh token available
+     */
+    async refreshAccessToken() {
+        const current = await this.tokenStore.get();
+        if (!current?.refreshToken) {
+            throw new OAuthError('no_refresh_token', 'No refresh token available. Please re-authenticate.');
+        }
+        try {
+            const response = await fetch(FreshBooksOAuth.TOKEN_URL, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Api-Version': 'alpha',
+                },
+                body: JSON.stringify({
+                    grant_type: 'refresh_token',
+                    client_id: this.config.clientId,
+                    client_secret: this.config.clientSecret,
+                    refresh_token: current.refreshToken,
+                }),
+            });
+            if (!response.ok) {
+                const error = await response.json();
+                // If refresh token is invalid, clear all tokens
+                await this.tokenStore.clear();
+                throw new OAuthError(this.mapErrorCode(error.error), error.error_description || 'Failed to refresh access token', error);
+            }
+            const data = await response.json();
+            const tokenData = this.parseTokenResponse(data);
+            // Preserve account/business selection if set
+            if (current.accountId) {
+                tokenData.accountId = current.accountId;
+            }
+            if (current.businessId) {
+                tokenData.businessId = current.businessId;
+            }
+            // Save new tokens
+            await this.tokenStore.save(tokenData);
+            return tokenData;
+        }
+        catch (error) {
+            if (error instanceof OAuthError) {
+                throw error;
+            }
+            throw new OAuthError('refresh_failed', 'Failed to refresh access token', error);
+        }
+    }
+    /**
+     * Get valid access token, automatically refreshing if needed
+     *
+     * This is the primary method for obtaining tokens for API requests.
+     * Automatically handles token refresh if token is expired or about to expire.
+     *
+     * @returns Valid access token
+     * @throws OAuthError if not authenticated or refresh fails
+     */
+    async getValidToken() {
+        const token = await this.tokenStore.get();
+        if (!token) {
+            throw new OAuthError('not_authenticated', 'No authentication found. Please authenticate first.');
+        }
+        // Check if token is expired or about to expire
+        const now = Math.floor(Date.now() / 1000);
+        const expiresIn = token.expiresAt - now;
+        // Refresh if token expires within buffer period
+        if (expiresIn < FreshBooksOAuth.EXPIRY_BUFFER_SECONDS) {
+            const newToken = await this.refreshAccessToken();
+            return newToken.accessToken;
+        }
+        return token.accessToken;
+    }
+    /**
+     * Revoke current authentication tokens
+     *
+     * Revokes the access token with FreshBooks and clears local storage.
+     * Best effort - continues to clear local storage even if revocation fails.
+     */
+    async revokeToken() {
+        const token = await this.tokenStore.get();
+        if (token?.accessToken) {
+            try {
+                // Attempt to revoke token with FreshBooks
+                await fetch(FreshBooksOAuth.REVOKE_URL, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${token.accessToken}`,
+                    },
+                    body: JSON.stringify({
+                        token: token.accessToken,
+                    }),
+                });
+            }
+            catch {
+                // Best effort - continue to clear local storage even if revocation fails
+            }
+        }
+        // Clear local token storage
+        await this.tokenStore.clear();
+    }
+    /**
+     * Get current authentication status
+     *
+     * @returns Authentication status including validity and expiration
+     */
+    async getStatus() {
+        const token = await this.tokenStore.get();
+        if (!token) {
+            return {
+                authenticated: false,
+                reason: 'no_token',
+            };
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const expiresIn = token.expiresAt - now;
+        if (expiresIn <= 0) {
+            return {
+                authenticated: false,
+                reason: 'token_expired',
+                canRefresh: !!token.refreshToken,
+            };
+        }
+        const status = {
+            authenticated: true,
+            expiresIn,
+        };
+        if (token.accountId) {
+            status.accountId = token.accountId;
+        }
+        if (token.businessId !== undefined) {
+            status.businessId = token.businessId;
+        }
+        return status;
+    }
+    /**
+     * Update account and business selection in token data
+     *
+     * @param accountId FreshBooks account ID
+     * @param businessId FreshBooks business ID
+     */
+    async setActiveAccount(accountId, businessId) {
+        const token = await this.tokenStore.get();
+        if (!token) {
+            throw new OAuthError('not_authenticated', 'No authentication found. Please authenticate first.');
+        }
+        token.accountId = accountId;
+        if (businessId !== undefined) {
+            token.businessId = businessId;
+        }
+        await this.tokenStore.save(token);
+    }
+    /**
+     * Parse OAuth token response into TokenData
+     */
+    parseTokenResponse(data) {
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token,
+            expiresAt: Math.floor(Date.now() / 1000) + data.expires_in,
+            tokenType: data.token_type || 'Bearer',
+        };
+    }
+    /**
+     * Map OAuth error codes to internal error codes
+     */
+    mapErrorCode(errorCode) {
+        const errorMap = {
+            'invalid_grant': 'invalid_grant',
+            'invalid_client': 'invalid_client',
+            'invalid_request': 'invalid_request',
+            'unauthorized_client': 'unauthorized_client',
+            'unsupported_grant_type': 'unsupported_grant_type',
+        };
+        return errorMap[errorCode] || 'token_exchange_failed';
+    }
+}
+//# sourceMappingURL=oauth.js.map

package/dist/auth/oauth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"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"}

package/dist/auth/token-store.d.ts

@@ -0,0 +1,80 @@
+/**
+ * FreshBooks OAuth2 Token Storage
+ *
+ * Provides secure encrypted file storage and environment-based storage for OAuth tokens.
+ */
+import { TokenData, TokenStore } from './types.js';
+/**
+ * Encrypted file-based token storage using AES-256-GCM
+ *
+ * Tokens are encrypted at rest using a key derived from:
+ * - Machine-specific identifier (username + platform)
+ * - Optional password from environment variable
+ *
+ * This provides defense-in-depth: even if the token file is accessed,
+ * it cannot be decrypted without the correct machine context.
+ */
+export declare class EncryptedFileTokenStore implements TokenStore {
+    private filePath;
+    private encryptionKey;
+    constructor(filePath: string);
+    /**
+     * Derive encryption key from machine-specific data
+     */
+    private getKey;
+    /**
+     * Generate machine-specific identifier for key derivation
+     */
+    private getMachineId;
+    /**
+     * Save encrypted token data to file
+     */
+    save(token: TokenData): Promise<void>;
+    /**
+     * Retrieve and decrypt token data from file
+     */
+    get(): Promise<TokenData | null>;
+    /**
+     * Clear all stored tokens
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Environment-based token storage for CI/testing
+ *
+ * Reads tokens from environment variables:
+ * - FRESHBOOKS_ACCESS_TOKEN (required)
+ * - FRESHBOOKS_REFRESH_TOKEN (optional)
+ * - FRESHBOOKS_TOKEN_EXPIRES (optional, unix timestamp)
+ * - FRESHBOOKS_ACCOUNT_ID (optional)
+ * - FRESHBOOKS_BUSINESS_ID (optional)
+ *
+ * This store is read-only and cannot persist token changes.
+ */
+export declare class EnvTokenStore implements TokenStore {
+    /**
+     * Retrieve token from environment variables
+     */
+    get(): Promise<TokenData | null>;
+    /**
+     * Save operation not supported for environment store
+     */
+    save(_token: TokenData): Promise<void>;
+    /**
+     * Clear operation not supported for environment store
+     */
+    clear(): Promise<void>;
+}
+/**
+ * In-memory token storage for testing
+ *
+ * Stores tokens in memory only. Tokens are lost when process exits.
+ * Useful for unit tests and temporary operations.
+ */
+export declare class InMemoryTokenStore implements TokenStore {
+    private token;
+    get(): Promise<TokenData | null>;
+    save(token: TokenData): Promise<void>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=token-store.d.ts.map

package/dist/auth/token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../src/auth/token-store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAInD;;;;;;;;;GASG;AACH,qBAAa,uBAAwB,YAAW,UAAU;IACxD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAAuB;gBAEhC,QAAQ,EAAE,MAAM;IAI5B;;OAEG;YACW,MAAM;IAiBpB;;OAEG;IACH,OAAO,CAAC,YAAY;IASpB;;OAEG;IACG,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAoC3C;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAiCtC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAU7B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,YAAW,UAAU;IAC9C;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAgCtC;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7B;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,KAAK,CAA0B;IAEjC,GAAG,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAIhC,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/auth/token-store.js

@@ -0,0 +1,204 @@
+/**
+ * FreshBooks OAuth2 Token Storage
+ *
+ * Provides secure encrypted file storage and environment-based storage for OAuth tokens.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, scrypt } from 'crypto';
+import { promises as fs } from 'fs';
+import { promisify } from 'util';
+import { dirname } from 'path';
+const scryptAsync = promisify(scrypt);
+/**
+ * Encrypted file-based token storage using AES-256-GCM
+ *
+ * Tokens are encrypted at rest using a key derived from:
+ * - Machine-specific identifier (username + platform)
+ * - Optional password from environment variable
+ *
+ * This provides defense-in-depth: even if the token file is accessed,
+ * it cannot be decrypted without the correct machine context.
+ */
+export class EncryptedFileTokenStore {
+    filePath;
+    encryptionKey = null;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    /**
+     * Derive encryption key from machine-specific data
+     */
+    async getKey() {
+        if (this.encryptionKey) {
+            return this.encryptionKey;
+        }
+        // Use machine-specific salt
+        const machineId = this.getMachineId();
+        // Optional password from environment, or default
+        const password = process.env.FRESHBOOKS_TOKEN_PASSWORD || 'freshbooks-mcp-default-key';
+        // Derive 32-byte key using scrypt
+        this.encryptionKey = (await scryptAsync(password, machineId, 32));
+        return this.encryptionKey;
+    }
+    /**
+     * Generate machine-specific identifier for key derivation
+     */
+    getMachineId() {
+        // Combine platform-specific data for unique salt
+        const username = process.env.USERNAME || process.env.USER || 'unknown';
+        const platform = process.platform;
+        const hostname = process.env.COMPUTERNAME || process.env.HOSTNAME || 'unknown';
+        return `${username}-${platform}-${hostname}-freshbooks-mcp`;
+    }
+    /**
+     * Save encrypted token data to file
+     */
+    async save(token) {
+        const key = await this.getKey();
+        // Generate random IV for this encryption
+        const iv = randomBytes(16);
+        // Create cipher
+        const cipher = createCipheriv('aes-256-gcm', key, iv);
+        // Encrypt token data
+        const data = JSON.stringify(token);
+        const encrypted = Buffer.concat([
+            cipher.update(data, 'utf8'),
+            cipher.final(),
+        ]);
+        // Get authentication tag
+        const authTag = cipher.getAuthTag();
+        // Store IV, auth tag, and encrypted data
+        const stored = {
+            iv: iv.toString('hex'),
+            authTag: authTag.toString('hex'),
+            data: encrypted.toString('hex'),
+        };
+        // Ensure directory exists
+        await fs.mkdir(dirname(this.filePath), { recursive: true });
+        // Write to file with restricted permissions
+        await fs.writeFile(this.filePath, JSON.stringify(stored), {
+            encoding: 'utf8',
+            mode: 0o600, // Owner read/write only
+        });
+    }
+    /**
+     * Retrieve and decrypt token data from file
+     */
+    async get() {
+        try {
+            // Read encrypted file
+            const content = await fs.readFile(this.filePath, 'utf8');
+            const stored = JSON.parse(content);
+            // Get decryption key
+            const key = await this.getKey();
+            // Parse stored components
+            const iv = Buffer.from(stored.iv, 'hex');
+            const authTag = Buffer.from(stored.authTag, 'hex');
+            const encrypted = Buffer.from(stored.data, 'hex');
+            // Create decipher
+            const decipher = createDecipheriv('aes-256-gcm', key, iv);
+            decipher.setAuthTag(authTag);
+            // Decrypt data
+            const decrypted = Buffer.concat([
+                decipher.update(encrypted),
+                decipher.final(),
+            ]);
+            // Parse and return token data
+            return JSON.parse(decrypted.toString('utf8'));
+        }
+        catch (error) {
+            // File doesn't exist, is corrupted, or decryption failed
+            // Return null to indicate no valid token
+            return null;
+        }
+    }
+    /**
+     * Clear all stored tokens
+     */
+    async clear() {
+        try {
+            await fs.unlink(this.filePath);
+        }
+        catch {
+            // File may not exist, ignore error
+        }
+        // Clear cached encryption key
+        this.encryptionKey = null;
+    }
+}
+/**
+ * Environment-based token storage for CI/testing
+ *
+ * Reads tokens from environment variables:
+ * - FRESHBOOKS_ACCESS_TOKEN (required)
+ * - FRESHBOOKS_REFRESH_TOKEN (optional)
+ * - FRESHBOOKS_TOKEN_EXPIRES (optional, unix timestamp)
+ * - FRESHBOOKS_ACCOUNT_ID (optional)
+ * - FRESHBOOKS_BUSINESS_ID (optional)
+ *
+ * This store is read-only and cannot persist token changes.
+ */
+export class EnvTokenStore {
+    /**
+     * Retrieve token from environment variables
+     */
+    async get() {
+        const accessToken = process.env.FRESHBOOKS_ACCESS_TOKEN;
+        if (!accessToken) {
+            return null;
+        }
+        const refreshToken = process.env.FRESHBOOKS_REFRESH_TOKEN || '';
+        const expiresAt = parseInt(process.env.FRESHBOOKS_TOKEN_EXPIRES || '0', 10);
+        const accountId = process.env.FRESHBOOKS_ACCOUNT_ID;
+        const businessId = process.env.FRESHBOOKS_BUSINESS_ID
+            ? parseInt(process.env.FRESHBOOKS_BUSINESS_ID, 10)
+            : undefined;
+        const tokenData = {
+            accessToken,
+            refreshToken,
+            expiresAt,
+            tokenType: 'Bearer',
+        };
+        if (accountId) {
+            tokenData.accountId = accountId;
+        }
+        if (businessId !== undefined) {
+            tokenData.businessId = businessId;
+        }
+        return tokenData;
+    }
+    /**
+     * Save operation not supported for environment store
+     */
+    async save(_token) {
+        // Environment store is read-only
+        // Tokens should be updated via environment variable configuration
+        console.error('Warning: EnvTokenStore is read-only. Cannot persist token updates. ' +
+            'Update FRESHBOOKS_ACCESS_TOKEN and related environment variables manually.');
+    }
+    /**
+     * Clear operation not supported for environment store
+     */
+    async clear() {
+        // Cannot clear environment variables
+        console.error('Warning: EnvTokenStore is read-only. Cannot clear environment variables.');
+    }
+}
+/**
+ * In-memory token storage for testing
+ *
+ * Stores tokens in memory only. Tokens are lost when process exits.
+ * Useful for unit tests and temporary operations.
+ */
+export class InMemoryTokenStore {
+    token = null;
+    async get() {
+        return this.token;
+    }
+    async save(token) {
+        this.token = token;
+    }
+    async clear() {
+        this.token = null;
+    }
+}
+//# sourceMappingURL=token-store.js.map