Merge pull request #32 from DeepLcom/feat/free-key-endpoint-resolution

feat: free key endpoint resolution and custom/regional URL support

Author: shirgoldbird

CHANGELOG.md

@@ -7,12 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Free API key (`:fx` suffix) support with automatic endpoint resolution to `api-free.deepl.com`
+- Shared endpoint resolver used by all commands including voice, auth, and init
+- Custom/regional endpoint support (e.g. `api-jp.deepl.com`) that takes priority over auto-detection
+
+### Changed
+
+- Voice API no longer hardcodes the Pro endpoint; it follows the same endpoint resolution as all other commands
+- `auth set-key` and `init` now validate entered keys against the correct endpoint based on key suffix
+- Standard DeepL URLs (`api.deepl.com`, `api-free.deepl.com`) in saved config no longer override key-based auto-detection
+
 ### Security
+
 - Updated `minimatch` from `^9.0.5` to `^10.2.1` to fix ReDoS vulnerability (GHSA-3ppc-4f35-3m26)
 
 ## [1.0.0] - 2026-02-17
 
 ### Added
+
 - Text translation via DeepL's next-generation LLM (`deepl translate`)
 - Document translation for PDF, DOCX, PPTX, XLSX, HTML, SRT, XLIFF, and images with formatting preservation
 - Structured file translation for JSON and YAML i18n locale files (keys, nesting, comments preserved)
@@ -42,6 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Advanced XML/HTML tag handling with splitting, non-splitting, and ignore tags
 
 ### Security
+
 - HTTPS enforcement for all API communication (localhost exempted for testing)
 - Symlink rejection on all file-reading paths to prevent directory traversal
 - API key masking in logs, config output, and error messages
@@ -50,4 +65,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Atomic writes for translated output and config files to prevent corruption
 
 ### Changed
+
 - Requires Node.js >= 20

README.md

@@ -73,6 +73,7 @@ deepl --version
 ```
 
 > **Note:** This project uses [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3) for local caching, which requires native compilation. If `npm install` fails with build errors, ensure you have:
+>
 > - **macOS**: Xcode Command Line Tools (`xcode-select --install`)
 > - **Linux**: `python3`, `make`, and `gcc` (`apt install python3 make gcc g++`)
 > - **Windows**: Visual Studio Build Tools or `windows-build-tools` (`npm install -g windows-build-tools`)
@@ -119,13 +120,13 @@ deepl translate "Hello, world!" --to es
 
 DeepL CLI supports global flags that work with all commands:
 
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--version` | `-V` | Show version number |
-| `--quiet` | `-q` | Suppress non-essential output |
-| `--verbose` | `-v` | Show extra information |
-| `--config FILE` | `-c` | Use alternate configuration file |
-| `--no-input` | | Disable all interactive prompts (abort instead of prompting) |
+| Flag            | Short | Description                                                  |
+| --------------- | ----- | ------------------------------------------------------------ |
+| `--version`     | `-V`  | Show version number                                          |
+| `--quiet`       | `-q`  | Suppress non-essential output                                |
+| `--verbose`     | `-v`  | Show extra information                                       |
+| `--config FILE` | `-c`  | Use alternate configuration file                             |
+| `--no-input`    |       | Disable all interactive prompts (abort instead of prompting) |
 
 ### Verbose Mode
 
@@ -222,12 +223,12 @@ $ deepl -c /path/to/test-config.json usage
 
 The CLI follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/):
 
-| Priority | Condition | Config path | Cache path |
-|----------|-----------|-------------|------------|
-| 1 | `DEEPL_CONFIG_DIR` set | `$DEEPL_CONFIG_DIR/config.json` | `$DEEPL_CONFIG_DIR/cache.db` |
-| 2 | `~/.deepl-cli/` exists | `~/.deepl-cli/config.json` | `~/.deepl-cli/cache.db` |
-| 3 | XDG env vars set | `$XDG_CONFIG_HOME/deepl-cli/config.json` | `$XDG_CACHE_HOME/deepl-cli/cache.db` |
-| 4 | Default | `~/.config/deepl-cli/config.json` | `~/.cache/deepl-cli/cache.db` |
+| Priority | Condition              | Config path                              | Cache path                           |
+| -------- | ---------------------- | ---------------------------------------- | ------------------------------------ |
+| 1        | `DEEPL_CONFIG_DIR` set | `$DEEPL_CONFIG_DIR/config.json`          | `$DEEPL_CONFIG_DIR/cache.db`         |
+| 2        | `~/.deepl-cli/` exists | `~/.deepl-cli/config.json`               | `~/.deepl-cli/cache.db`              |
+| 3        | XDG env vars set       | `$XDG_CONFIG_HOME/deepl-cli/config.json` | `$XDG_CACHE_HOME/deepl-cli/cache.db` |
+| 4        | Default                | `~/.config/deepl-cli/config.json`        | `~/.cache/deepl-cli/cache.db`        |
 
 Existing `~/.deepl-cli/` installations continue to work with no changes needed.
 
@@ -942,6 +943,7 @@ deepl languages
 ```
 
 **Note:** Languages are grouped into three categories:
+
 - **Core** (32) — Full feature support including formality and glossaries
 - **Regional** (7) — Target-only variants: `en-gb`, `en-us`, `es-419`, `pt-br`, `pt-pt`, `zh-hans`, `zh-hant`
 - **Extended** (82) — Only support `quality_optimized` model, no formality or glossary
@@ -957,7 +959,7 @@ Configuration is stored in `~/.config/deepl-cli/config.json` (or `~/.deepl-cli/c
 deepl config list
 # {
 #   "auth": { "apiKey": "..." },
-#   "api": { "baseUrl": "https://api-free.deepl.com/v2", ... },
+#   "api": { "baseUrl": "https://api.deepl.com", "usePro": true, ... },
 #   "cache": { "enabled": true, "maxSize": 1073741824, "ttl": 2592000 },
 #   ...
 # }
@@ -1444,15 +1446,15 @@ npm run examples:fast
 
 ## 🌐 Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `DEEPL_API_KEY` | API authentication key |
-| `DEEPL_CONFIG_DIR` | Override config and cache directory |
-| `XDG_CONFIG_HOME` | Override XDG config base (default: `~/.config`) |
-| `XDG_CACHE_HOME` | Override XDG cache base (default: `~/.cache`) |
-| `NO_COLOR` | Disable colored output |
-| `FORCE_COLOR` | Force colored output even when terminal doesn't support it. Useful in CI. `NO_COLOR` takes priority if both are set. |
-| `TERM=dumb` | Disables colored output and progress spinners. Automatically set by some CI environments and editors. |
+| Variable           | Description                                                                                                          |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `DEEPL_API_KEY`    | API authentication key                                                                                               |
+| `DEEPL_CONFIG_DIR` | Override config and cache directory                                                                                  |
+| `XDG_CONFIG_HOME`  | Override XDG config base (default: `~/.config`)                                                                      |
+| `XDG_CACHE_HOME`   | Override XDG cache base (default: `~/.cache`)                                                                        |
+| `NO_COLOR`         | Disable colored output                                                                                               |
+| `FORCE_COLOR`      | Force colored output even when terminal doesn't support it. Useful in CI. `NO_COLOR` takes priority if both are set. |
+| `TERM=dumb`        | Disables colored output and progress spinners. Automatically set by some CI environments and editors.                |
 
 See [docs/API.md#environment-variables](./docs/API.md#environment-variables) for full details.