fix: auto-detect free API endpoint from :fx key suffix

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- Free API keys (ending with `:fx`) now auto-detect the correct endpoint (`api-free.deepl.com`), matching the behavior of official DeepL SDKs
+
 ### Security
 - Updated `minimatch` from `^9.0.5` to `^10.2.1` to fix ReDoS vulnerability (GHSA-3ppc-4f35-3m26)
 

src/api/http-client.ts

@@ -20,7 +20,6 @@ export interface ProxyConfig {
 }
 
 export interface DeepLClientOptions {
-  usePro?: boolean;
   timeout?: number;
   maxRetries?: number;
   baseUrl?: string;
@@ -42,6 +41,10 @@ export function sanitizeUrl(url: string): string {
 
 const FREE_API_URL = 'https://api-free.deepl.com';
 const PRO_API_URL = 'https://api.deepl.com';
+
+export function isFreeApiKey(apiKey: string): boolean {
+  return apiKey.endsWith(':fx');
+}
 const DEFAULT_TIMEOUT = 30000;
 const DEFAULT_MAX_RETRIES = 3;
 const MAX_SOCKETS = 10;
@@ -99,7 +102,8 @@ export class HttpClient {
       throw new AuthError('API key is required');
     }
 
-    const baseURL = options.baseUrl ?? (options.usePro ? PRO_API_URL : FREE_API_URL);
+    const autoUrl = isFreeApiKey(apiKey) ? FREE_API_URL : PRO_API_URL;
+    const baseURL = options.baseUrl ?? autoUrl;
 
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
 

src/cli/commands/auth.ts

@@ -27,11 +27,8 @@ export class AuthCommand {
     // Note: No format validation - let the API determine if the key is valid
     // This supports production keys (:fx suffix), free keys, and test keys
     try {
-      // Use configured API endpoint for validation
-      const baseUrl = this.config.getValue<string>('api.baseUrl');
-      const usePro = this.config.getValue<boolean>('api.usePro');
-
-      const client = new DeepLClient(apiKey, { baseUrl, usePro });
+      // Let the client auto-detect the endpoint from the key suffix
+      const client = new DeepLClient(apiKey);
       await client.getUsage(); // Test API key validity
     } catch (error) {
       if (error instanceof Error) {

src/cli/commands/config.ts

@@ -6,7 +6,6 @@
 import { ConfigService } from '../../storage/config.js';
 
 const BOOLEAN_KEYS = [
-  'api.usePro',
   'cache.enabled',
   'output.verbose',
   'output.color',

src/cli/commands/init.ts

@@ -39,9 +39,7 @@ export class InitCommand {
     Logger.output('\nValidating API key...');
 
     const { DeepLClient } = await import('../../api/deepl-client.js');
-    const baseUrl = this.config.getValue<string>('api.baseUrl');
-    const usePro = this.config.getValue<boolean>('api.usePro');
-    const client = new DeepLClient(apiKey.trim(), { baseUrl, usePro });
+    const client = new DeepLClient(apiKey.trim());
     await client.getUsage();
 
     this.config.set('auth.apiKey', apiKey.trim());

src/cli/commands/register-config.ts

@@ -17,7 +17,7 @@ export function registerConfig(
     .description('Manage configuration')
     .addHelpText('after', `
 Examples:
-  $ deepl config set api.usePro true
+  $ deepl config set api.baseUrl https://api.deepl.com
   $ deepl config get auth.apiKey
   $ deepl config list
   $ deepl config reset

src/cli/index.ts

@@ -35,8 +35,6 @@ import { registerCompletion } from './commands/register-completion.js';
 import { registerVoice } from './commands/register-voice.js';
 import { registerInit } from './commands/register-init.js';
 import { registerDetect } from './commands/register-detect.js';
-import { validateApiUrl } from '../utils/validate-url.js';
-
 // Get __dirname equivalent in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -99,16 +97,13 @@ async function createDeepLClient(overrideBaseUrl?: string): Promise<DeepLClient>
     process.exit(ExitCode.AuthError);
   }
 
-  const baseUrl = overrideBaseUrl ?? configService.getValue<string>('api.baseUrl');
-  const usePro = configService.getValue<boolean>('api.usePro');
-
-  if (baseUrl) {
+  if (overrideBaseUrl) {
     const { validateApiUrl } = await import('../utils/validate-url.js');
-    validateApiUrl(baseUrl);
+    validateApiUrl(overrideBaseUrl);
   }
 
   const { DeepLClient: Client } = await import('../api/deepl-client.js');
-  return new Client(key, { baseUrl, usePro });
+  return new Client(key, { baseUrl: overrideBaseUrl });
 }
 
 // Create program
@@ -194,13 +189,7 @@ function getApiKeyAndOptions(): { apiKey: string; options: import('../api/http-c
     process.exit(ExitCode.AuthError);
   }
 
-  const baseUrl = configService.getValue<string>('api.baseUrl');
-  if (baseUrl) {
-    validateApiUrl(baseUrl);
-  }
-  const usePro = configService.getValue<boolean>('api.usePro');
-
-  return { apiKey: key, options: { baseUrl, usePro } };
+  return { apiKey: key, options: {} };
 }
 
 // Shared dependencies passed to register functions

src/storage/config.ts

@@ -28,7 +28,6 @@ const VALID_OUTPUT_FORMATS: readonly OutputFormat[] = [
 ] as const;
 
 const BOOLEAN_CONFIG_PATHS = [
-  'api.usePro',
   'cache.enabled',
   'output.verbose',
   'output.color',
@@ -169,8 +168,7 @@ export class ConfigService {
         apiKey: undefined,
       },
       api: {
-        baseUrl: 'https://api.deepl.com',
-        usePro: true,
+        baseUrl: undefined,
       },
       defaults: {
         sourceLang: undefined,

src/types/config.ts

@@ -9,8 +9,7 @@ export interface DeepLConfig {
     apiKey?: string;
   };
   api: {
-    baseUrl: string;
-    usePro: boolean;
+    baseUrl?: string;
   };
   defaults: {
     sourceLang?: Language;

tests/e2e/cli-success-paths.e2e.test.ts

@@ -59,7 +59,7 @@ describe('CLI Success Paths E2E', () => {
   function writeConfig(configDir: string, apiUrl: string): void {
     const config = {
       auth: { apiKey: 'mock-api-key-for-testing:fx' },
-      api: { baseUrl: apiUrl, usePro: false },
+      api: { baseUrl: apiUrl },
       defaults: {
         targetLangs: [],
         formality: 'default',

tests/e2e/cli-watch.e2e.test.ts

@@ -110,7 +110,7 @@ describe('Watch Command E2E', () => {
       const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'deepl-watch-e2e-'));
       const configWithDefaults = {
         auth: { apiKey: 'test-key:fx' },
-        api: { baseUrl: 'https://api-free.deepl.com', usePro: false },
+        api: { baseUrl: 'https://api-free.deepl.com' },
         defaults: { targetLangs: ['es', 'fr'], formality: 'default', preserveFormatting: true },
         cache: { enabled: false, maxSize: 1048576, ttl: 2592000 },
         output: { format: 'text', verbose: false, color: false },

tests/integration/batch-translation.integration.test.ts

@@ -46,7 +46,7 @@ describe('Batch Translation Service Integration', () => {
     mockConfig = createMockConfigService({
       get: jest.fn(() => ({
         auth: {},
-        api: { baseUrl: '', usePro: false },
+        api: { baseUrl: '' },
         defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
         cache: { enabled: true },
         output: { format: 'text', color: true },

tests/integration/cli-config-file.integration.test.ts

@@ -38,7 +38,7 @@ describe('CLI --config flag integration', () => {
     // Set up default config with a test API key
     const defaultConfig = {
       auth: { apiKey: 'default-test-key' },
-      api: { baseUrl: 'https://api.deepl.com', usePro: true },
+      api: { baseUrl: 'https://api.deepl.com' },
       defaults: { sourceLang: undefined, targetLangs: [], formality: 'default', preserveFormatting: true },
       cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
       output: { format: 'text', verbose: false, color: true },
@@ -50,7 +50,7 @@ describe('CLI --config flag integration', () => {
     // Set up custom config with different API key
     const customConfig = {
       auth: { apiKey: 'custom-test-key' },
-      api: { baseUrl: 'https://api-free.deepl.com', usePro: false },
+      api: { baseUrl: 'https://api-free.deepl.com' },
       defaults: { sourceLang: 'en', targetLangs: ['es', 'fr'], formality: 'more', preserveFormatting: false },
       cache: { enabled: false, maxSize: 104857600, ttl: 86400 },
       output: { format: 'json', verbose: true, color: false },
@@ -79,7 +79,7 @@ describe('CLI --config flag integration', () => {
     });
 
     it('should read nested config values from custom config', () => {
-      const output = runCLI(`deepl --config "${customConfigPath}" config get api.usePro`);
+      const output = runCLI(`deepl --config "${customConfigPath}" config get cache.enabled`);
       expect(output.trim()).toBe('false');
     });
 
@@ -116,15 +116,15 @@ describe('CLI --config flag integration', () => {
       const config = JSON.parse(output.trim());
       // API keys are masked in list output
       expect(config.auth.apiKey).toBe('defa...-key');
-      expect(config.api.usePro).toBe(true);
+      expect(config.api.baseUrl).toBe('https://api.deepl.com');
     });
 
     it('should list custom config when --config is specified', () => {
       const output = runCLI(`deepl --config "${customConfigPath}" config list`);
       const config = JSON.parse(output.trim());
       // API keys are masked in list output
       expect(config.auth.apiKey).toBe('cust...-key');
-      expect(config.api.usePro).toBe(false);
+      expect(config.api.baseUrl).toBe('https://api-free.deepl.com');
       expect(config.defaults.formality).toBe('more');
     });
   });
@@ -223,7 +223,7 @@ describe('CLI --config flag integration', () => {
       const upperCasePath = path.join(testDir, 'config.JSON');
       fs.writeFileSync(upperCasePath, JSON.stringify({
         auth: { apiKey: 'upper-case-key' },
-        api: { baseUrl: 'https://api.deepl.com', usePro: true },
+        api: { baseUrl: 'https://api.deepl.com' },
         defaults: { targetLangs: [], formality: 'default', preserveFormatting: true },
         cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
         output: { format: 'text', verbose: false, color: true },

tests/integration/cli-config.integration.test.ts

@@ -24,7 +24,6 @@ describe('Config CLI Integration', () => {
       auth: { apiKey: undefined },
       api: {
         baseUrl: 'https://api-free.deepl.com/v2',
-        usePro: false,
       },
       defaults: {
         sourceLang: undefined,

tests/integration/cli-structured-file-translate.integration.test.ts

@@ -24,7 +24,7 @@ describe('Structured File Translation CLI Integration', () => {
       path.join(testConfig.path, 'config.json'),
       JSON.stringify({
         auth: { apiKey: 'test-api-key-123' },
-        api: { baseUrl: 'https://api-free.deepl.com/v2', usePro: false },
+        api: { baseUrl: 'https://api-free.deepl.com/v2' },
         defaults: { sourceLang: undefined, targetLangs: [], formality: 'default', preserveFormatting: true },
         cache: { enabled: false, maxSize: 1073741824, ttl: 2592000 },
       })

tests/integration/cli-style-rules.integration.test.ts

@@ -499,8 +499,8 @@ describe('Style Rules API Integration', () => {
       expect(receivedBody).toBe('');
     });
 
-    it('should use Pro API URL when configured', async () => {
-      const proClient = new DeepLClient(API_KEY, { usePro: true });
+    it('should use Pro API URL for pro keys', async () => {
+      const proClient = new DeepLClient('test-pro-api-key');
       const proCommand = new StyleRulesCommand(new StyleRulesService(proClient));
 
       const scope = nock('https://api.deepl.com')

tests/integration/cli-translate.integration.test.ts

@@ -116,7 +116,7 @@ describe('Translate CLI Integration', () => {
       const configPath = path.join(testConfigDir, 'config.json');
       const config = {
         auth: {},
-        api: { baseUrl: 'https://api.deepl.com', usePro: true },
+        api: {},
         defaults: {
           targetLangs: ['es'],
           formality: 'default',

tests/integration/cli-voice.integration.test.ts

@@ -123,7 +123,7 @@ describe('Voice CLI Integration', () => {
       const configPath = path.join(testConfig.path, 'config.json');
       fs.writeFileSync(configPath, JSON.stringify({
         auth: { apiKey: 'test-key-for-url-validation' },
-        api: { baseUrl: 'http://evil-server.example.com/v2', usePro: false },
+        api: { baseUrl: 'http://evil-server.example.com/v2' },
       }));
 
       expect.assertions(1);

tests/integration/deepl-client.integration.test.ts

@@ -33,8 +33,8 @@ describe('DeepLClient Integration', () => {
       expect(() => new DeepLClient('')).toThrow('API key is required');
     });
 
-    it('should use free API URL by default', async () => {
-      const client = new DeepLClient(API_KEY);
+    it('should auto-detect free API URL from :fx key suffix', async () => {
+      const client = new DeepLClient(API_KEY); // API_KEY ends with :fx
       clients.push(client);
 
       const scope = nock(FREE_API_URL)
@@ -45,8 +45,9 @@ describe('DeepLClient Integration', () => {
       expect(scope.isDone()).toBe(true);
     });
 
-    it('should use pro API URL when usePro is true', async () => {
-      const client = new DeepLClient(API_KEY, { usePro: true });
+    it('should auto-detect pro API URL for keys without :fx suffix', async () => {
+      const proKey = 'test-pro-api-key';
+      const client = new DeepLClient(proKey);
       clients.push(client);
 
       const scope = nock(PRO_API_URL)
@@ -69,6 +70,20 @@ describe('DeepLClient Integration', () => {
       await client.getUsage();
       expect(scope.isDone()).toBe(true);
     });
+
+    it('should use explicit baseUrl even for :fx keys', async () => {
+      const freeKey = 'my-free-api-key:fx';
+      const customUrl = 'https://custom-deepl.example.com';
+      const client = new DeepLClient(freeKey, { baseUrl: customUrl });
+      clients.push(client);
+
+      const scope = nock(customUrl)
+        .get('/v2/usage')
+        .reply(200, { character_count: 0, character_limit: 500000 });
+
+      await client.getUsage();
+      expect(scope.isDone()).toBe(true);
+    });
   });
 
   describe('translate()', () => {
@@ -639,8 +654,9 @@ describe('DeepLClient Integration', () => {
       expect(scope.isDone()).toBe(true);
     });
 
-    it('should use pro API URL when usePro is true', async () => {
-      const client = new DeepLClient(API_KEY, { usePro: true });
+    it('should auto-detect pro API URL for pro key', async () => {
+      const proKey = 'test-pro-api-key';
+      const client = new DeepLClient(proKey);
       clients.push(client);
 
       const scope = nock(PRO_API_URL)

tests/unit/auth-command.test.ts

@@ -63,6 +63,18 @@ describe('AuthCommand', () => {
       expect(mockGetUsage).toHaveBeenCalled();
     });
 
+    it('should create client without config baseUrl to allow auto-detection', async () => {
+      const mockGetUsage = jest.fn().mockResolvedValue({ character: { count: 0, limit: 500000 } });
+      (DeepLClient as jest.MockedClass<typeof DeepLClient>).mockImplementation(() => ({
+        getUsage: mockGetUsage,
+      } as any));
+
+      await authCommand.setKey('test-key:fx');
+
+      // Client should be created with just the key, no baseUrl from config
+      expect(DeepLClient).toHaveBeenCalledWith('test-key:fx');
+    });
+
     it('should throw error for empty API key', async () => {
       await expect(authCommand.setKey('')).rejects.toThrow('API key cannot be empty');
     });

tests/unit/cli-translate-workflow.test.ts

@@ -32,7 +32,7 @@ describe('Translation Workflow Integration', () => {
     mockConfig = createMockConfigService({
       get: jest.fn(() => ({
         auth: {},
-        api: { baseUrl: '', usePro: false },
+        api: { baseUrl: '' },
         defaults: { targetLangs: [], formality: 'default', preserveFormatting: false },
         cache: { enabled: true },
         output: { format: 'text', color: true },
@@ -87,7 +87,7 @@ describe('Translation Workflow Integration', () => {
       mockConfig = createMockConfigService({
         get: jest.fn(() => ({
           auth: {},
-          api: { baseUrl: '', usePro: false },
+          api: { baseUrl: '' },
           defaults: {
             targetLangs: [],
             sourceLang: 'en',

tests/unit/cli.test.ts

@@ -78,7 +78,7 @@ describe('CLI Entry Point', () => {
       const configPath = path.join(testConfigDir, 'config.json');
       fs.writeFileSync(configPath, JSON.stringify({
         auth: {},
-        api: { baseUrl: 'https://api.deepl.com', usePro: true },
+        api: { baseUrl: 'https://api.deepl.com' },
         defaults: { targetLangs: [], formality: 'default', preserveFormatting: true },
         cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
         output: { format: 'text', verbose: false, color: false },
@@ -103,7 +103,7 @@ describe('CLI Entry Point', () => {
       const configPath = path.join(testConfigDir, 'config.json');
       fs.writeFileSync(configPath, JSON.stringify({
         auth: {},
-        api: { baseUrl: 'https://api.deepl.com', usePro: true },
+        api: { baseUrl: 'https://api.deepl.com' },
         defaults: { targetLangs: [], formality: 'default', preserveFormatting: true },
         cache: { enabled: true, maxSize: 1073741824, ttl: 2592000 },
         output: { format: 'text', verbose: false, color: true },