ai-l10n-core 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to the core package will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.1] - 2026-04-17
+
+### Changed
+- Set default client identifier on `translate()` requests.
+- Standardized the `reason` type used in API error responses to a fixed union of values.
+
+### Fixed
+- API documentation
+
 ## [1.5.0] - 2026-04-16
 
 ### Added
@@ -12,7 +21,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ```typescript
   type ApiResponse<T> =
     | { success: true; data: T }
-    | { success: false; reason: string; message: string };
+    | {
+        success: false;
+        reason:
+          | "paymentRequired"
+          | "translationError"
+          | "requestTooLarge"
+          | "badRequest"
+          | "unauthorized"
+          | "forbidden"
+          | "rateLimited"
+          | "serverError"
+          | "networkError"
+          | "noApiKey";
+        message: string;
+      };
   ```
 - **Balance API** — New `getBalance(apiKey)` method on `L10nTranslationService` retrieves the current character balance from the `GET /v2/balance` endpoint. Returns `ApiResponse<BalanceResponse>` (always resolves, never throws).
 - **`BalanceResponse` type** — `{ currentBalance: number }`
@@ -24,7 +47,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - The method always resolves — it never throws
   - On success: `{ success: true, data: TranslationResult, currentBalance?: number }`
   - On error: `{ success: false, reason: string, message: string, currentBalance?: number }`
-  - `reason` values: `"noApiKey"`, `"unauthorized"`, `"paymentRequired"`, `"badRequest"`, `"requestTooLarge"`, `"serverError"`, `"networkError"`, `"translationError"`
+  - `reason` values: "paymentRequired", "translationError", "requestTooLarge", "badRequest", "unauthorized", "forbidden", "rateLimited", "serverError", "networkError", "noApiKey"
 - **`getLanguages()` now requires `apiKey` as its first parameter** (bug fix — previously no API key was sent)
   - New signature: `getLanguages(apiKey: string, options?: ...): Promise<ApiResponse<SupportedLanguagesResponse>>`
   - Returns structured `ApiResponse` instead of throwing; error reasons: `noApiKey`, `unauthorized`, `badRequest`, `networkError`

package/README.md

@@ -150,7 +150,7 @@ Retrieves the current character balance available for translation.
 
 **Returns:** `Promise<ApiResponse<BalanceResponse>>` — Always resolves (never throws). Check `success` to determine success or failure. On success, `data.currentBalance` holds the number of characters available.
 
-**Error reasons:** `noApiKey`, `unauthorized`, `networkError`
+**Error reasons:** `noApiKey`, `unauthorized`, `serverError`, `networkError`
 
 **Example:**
 ```typescript
@@ -172,7 +172,7 @@ Predicts possible language codes from a text input (language name in English or
 
 **Returns:** `Promise<ApiResponse<Language[]>>` — Always resolves (never throws). On success, `data` is an array of predicted languages with codes and names.
 
-**Error reasons:** `networkError`
+**Error reasons:** , `serverError`, `networkError`
 
 ##### `getLanguages(apiKey: string, options?: { codes?: string[]; proficiencyLevels?: LanguageProficiencyLevel[] }): Promise<ApiResponse<SupportedLanguagesResponse>>`
 
@@ -186,7 +186,7 @@ Retrieves a list of supported languages, optionally filtered by language codes o
 
 **Returns:** `Promise<ApiResponse<SupportedLanguagesResponse>>` — Always resolves (never throws). On success, `data.languages` is an array of `SupportedLanguage` entries.
 
-**Error reasons:** `noApiKey`, `unauthorized`, `badRequest`, `networkError`
+**Error reasons:** `noApiKey`, `unauthorized`, `badRequest`, `serverError`, `networkError`
 
 **Example:**
 ```typescript
@@ -216,7 +216,21 @@ const response = await service.getLanguages(apiKey, {
 ```typescript
 type ApiResponse<T> =
   | { success: true; data: T }
-  | { success: false; reason: string; message: string };
+  | {
+      success: false;
+      reason:
+        | "paymentRequired"
+        | "translationError"
+        | "requestTooLarge"
+        | "badRequest"
+        | "unauthorized"
+        | "forbidden"
+        | "rateLimited"
+        | "serverError"
+        | "networkError"
+        | "noApiKey";
+      message: string;
+    };
 ```
 
 All methods that contact the API return an `ApiResponse<T>`. Check `success` before accessing `data`.
@@ -389,14 +403,16 @@ All methods always resolve — they never throw. Check `response.success`:
 
 | `reason` | Description |
 |----------|-------------|
-| `"noApiKey"` | API key was not provided |
-| `"unauthorized"` | API key is invalid (401) |
 | `"paymentRequired"` | Insufficient balance (402); `currentBalance` is set |
-| `"badRequest"` | Validation error (400); `message` contains details |
+| `"translationError"` | Translation failed; API returned `finishReason: "error"` |
 | `"requestTooLarge"` | Request exceeds 5 MB (413) |
+| `"badRequest"` | Validation error (400); `message` contains details |
+| `"unauthorized"` | API key is invalid (401) |
+| `"forbidden"` | API key lacks required permissions (403) |
+| `"rateLimited"` | Requests are being rate-limited (429) |
 | `"serverError"` | Internal server error (500) |
 | `"networkError"` | Connection or other failure |
-| `"translationError"` | API returned `finishReason: "error"` |
+| `"noApiKey"` | API key was not provided |
 
 ##### `getBalance()` error reasons
 
@@ -404,6 +420,7 @@ All methods always resolve — they never throw. Check `response.success`:
 |----------|-------------|
 | `"noApiKey"` | API key was not provided |
 | `"unauthorized"` | API key is invalid (401) |
+| `"serverError"` | Internal server error (500) |
 | `"networkError"` | Connection or other failure |
 
 ##### `getLanguages()` error reasons
@@ -413,12 +430,14 @@ All methods always resolve — they never throw. Check `response.success`:
 | `"noApiKey"` | API key was not provided |
 | `"unauthorized"` | API key is invalid (401) |
 | `"badRequest"` | Validation error (400); `message` contains details |
+| `"serverError"` | Internal server error (500) |
 | `"networkError"` | Connection or other failure |
 
 ##### `predictLanguages()` error reasons
 
 | `reason` | Description |
 |----------|-------------|
+| `"serverError"` | Internal server error (500) |
 | `"networkError"` | Connection or other failure |
 
 ---

package/dist/translationService.d.ts

@@ -93,7 +93,7 @@ export type ApiResponse<T> = {
     data: T;
 } | {
     success: false;
-    reason: string;
+    reason: "paymentRequired" | "translationError" | "requestTooLarge" | "badRequest" | "unauthorized" | "forbidden" | "rateLimited" | "serverError" | "networkError" | "noApiKey";
     message: string;
 };
 /**

package/dist/translationService.js

@@ -93,6 +93,9 @@ class L10nTranslationService {
             return apiKeyError;
         }
         this.logger.logInfo(`Starting translation to ${request.targetLanguageCode}`);
+        if (!request.client) {
+            request.client = "ai-l10n-core-npmjs";
+        }
         const response = await fetch(`${constants_1.URLS.API_BASE}/v2/translate`, {
             method: "POST",
             headers: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-l10n-core",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Platform-independent core for AI-powered localization — translation API client, language utilities, and shared types",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",