ai-l10n-core 1.4.1 → 1.5.1

package/CHANGELOG.md

@@ -5,6 +5,91 @@ 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
+- **`ApiResponse<T>` type** — Generic discriminated union used as the return type of all API methods:
+  ```typescript
+  type ApiResponse<T> =
+    | { success: true; data: T }
+    | {
+        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 }`
+- **Structured responses for all methods** — `getBalance()`, `getLanguages()`, and `predictLanguages()` now return `ApiResponse<T>` and never throw
+
+### Changed
+- **`translate()` return type changed from `TranslationResult | null` to `TranslationResponse`** (breaking change)
+  - `TranslationResponse` is now `ApiResponse<TranslationResult> & { currentBalance?: number }`
+  - 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: "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`
+- **`getBalance()` no longer throws** — returns `ApiResponse<BalanceResponse>`; error reasons: `noApiKey`, `unauthorized`, `networkError`
+- **`predictLanguages()` no longer throws** — returns `ApiResponse<Language[]>`; error reason: `networkError`
+
+### Migration
+```typescript
+// translate() — Before (1.4.x)
+try {
+  const result = await service.translate(request, apiKey);
+  if (!result) return; // null for 401/402
+  console.log(result.translations);
+} catch (e) {
+  console.error(e.message); // thrown for 400/413/500
+}
+
+// translate() — After (1.5.0)
+const response = await service.translate(request, apiKey);
+if (!response.success) {
+  console.error(response.message, '| reason:', response.reason);
+  return;
+}
+console.log(response.data.translations);
+
+// getBalance() — Before (1.4.x)
+const { currentBalance } = await service.getBalance(apiKey); // threw on error
+
+// getBalance() — After (1.5.0)
+const result = await service.getBalance(apiKey);
+if (!result.success) console.error(result.reason);
+else console.log(result.data.currentBalance);
+
+// getLanguages() — Before (1.4.x)
+const { languages } = await service.getLanguages(options); // no apiKey, threw on error
+
+// getLanguages() — After (1.5.0)
+const result = await service.getLanguages(apiKey, options);
+if (!result.success) console.error(result.reason);
+else console.log(result.data.languages);
+```
+
 ## [1.4.0] - 2026-04-02
 
 ### Added

package/README.md

@@ -117,7 +117,7 @@ const service = new L10nTranslationService(customLogger);
 
 #### Methods
 
-##### `translate(request: TranslationRequest, apiKey: string): Promise<TranslationResult | null>`
+##### `translate(request: TranslationRequest, apiKey: string): Promise<TranslationResponse>`
 
 Translates localization content using the l10n.dev API.
 
@@ -125,11 +125,44 @@ Translates localization content using the l10n.dev API.
 - `request: TranslationRequest` — Translation request configuration
 - `apiKey: string` — API key for authentication
 
-**Returns:** `Promise<TranslationResult | null>` — Translation result, or `null` for 401/402 responses
+**Returns:** `Promise<TranslationResponse>` — Always resolves (never throws). Check `success` field to determine success or failure.
 
-**Throws:** Error for 400, 413, 500, and other failure conditions
+**Example:**
+```typescript
+const response = await service.translate(request, apiKey);
+if (!response.success) {
+  console.error(response.message, 'reason:', response.reason);
+  if (response.reason === 'paymentRequired') {
+    console.log('Current balance:', response.currentBalance);
+  }
+} else {
+  console.log('Translated:', response.data.translations);
+  console.log('Balance remaining:', response.currentBalance);
+}
+```
+
+##### `getBalance(apiKey: string): Promise<ApiResponse<BalanceResponse>>`
+
+Retrieves the current character balance available for translation.
+
+**Parameters:**
+- `apiKey: string` — API key for authentication
 
-##### `predictLanguages(input: string, limit?: number): Promise<Language[]>`
+**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`, `serverError`, `networkError`
+
+**Example:**
+```typescript
+const response = await service.getBalance(apiKey);
+if (!response.success) {
+  console.error(response.message, 'reason:', response.reason);
+} else {
+  console.log(`Available: ${response.data.currentBalance.toLocaleString()} characters`);
+}
+```
+
+##### `predictLanguages(input: string, limit?: number): Promise<ApiResponse<Language[]>>`
 
 Predicts possible language codes from a text input (language name in English or native language, region, or script).
 
@@ -137,39 +170,90 @@ Predicts possible language codes from a text input (language name in English or
 - `input: string` — Text to analyze
 - `limit?: number` — Maximum number of predictions (default: 10)
 
-**Returns:** `Promise<Language[]>` — Array of predicted languages with codes and names
+**Returns:** `Promise<ApiResponse<Language[]>>` — Always resolves (never throws). On success, `data` is an array of predicted languages with codes and names.
+
+**Error reasons:** , `serverError`, `networkError`
 
-##### `getLanguages(options?: { codes?: string[]; proficiencyLevels?: LanguageProficiencyLevel[] }): Promise<SupportedLanguagesResponse>`
+##### `getLanguages(apiKey: string, options?: { codes?: string[]; proficiencyLevels?: LanguageProficiencyLevel[] }): Promise<ApiResponse<SupportedLanguagesResponse>>`
 
 Retrieves a list of supported languages, optionally filtered by language codes or proficiency levels.
 
 **Parameters:**
+- `apiKey: string` — API key for authentication
 - `options?` — Optional filter object
   - `codes?: string[]` — Filter by specific language codes (e.g., `["en", "es", "fr"]`)
   - `proficiencyLevels?: LanguageProficiencyLevel[]` — Filter by proficiency level: `"strong"`, `"high"`, `"moderate"`, or `"limited"`
 
-**Returns:** `Promise<SupportedLanguagesResponse>` — Object containing a `languages` array of `SupportedLanguage` entries
+**Returns:** `Promise<ApiResponse<SupportedLanguagesResponse>>` — Always resolves (never throws). On success, `data.languages` is an array of `SupportedLanguage` entries.
 
-**Throws:** Error if the API request fails (non-2xx response)
+**Error reasons:** `noApiKey`, `unauthorized`, `badRequest`, `serverError`, `networkError`
 
 **Example:**
 ```typescript
 // Get all supported languages
-const { languages } = await service.getLanguages();
+const response = await service.getLanguages(apiKey);
+if (!response.success) {
+  console.error(response.message, 'reason:', response.reason);
+} else {
+  const { languages } = response.data;
+}
 
 // Filter by proficiency level
-const { languages } = await service.getLanguages({
+const response = await service.getLanguages(apiKey, {
   proficiencyLevels: ['strong', 'high'],
 });
 
 // Filter by specific codes
-const { languages } = await service.getLanguages({
+const response = await service.getLanguages(apiKey, {
   codes: ['en', 'es', 'fr'],
 });
 ```
 
 #### Types
 
+##### ApiResponse\<T\>
+
+```typescript
+type ApiResponse<T> =
+  | { success: true; data: T }
+  | {
+      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`.
+
+##### TranslationResponse
+
+```typescript
+type TranslationResponse = ApiResponse<TranslationResult> & { currentBalance?: number };
+```
+
+The union distributes over the intersection, so `currentBalance?` is available on both branches:
+- On `success: true`: `data` holds the `TranslationResult`, `currentBalance` is the remaining balance.
+- On `success: false`: `reason` and `message` describe the error, `currentBalance` is set when `reason` is `"paymentRequired"`.
+
+##### BalanceResponse
+
+```typescript
+interface BalanceResponse {
+  /** Current balance of characters available for translation. */
+  currentBalance: number;
+}
+```
+
 ##### TranslationRequest
 
 ```typescript
@@ -192,9 +276,6 @@ interface TranslationRequest {
   /** Translate metadata along with UI strings (e.g., ARB `@key` descriptions) */
   translateMetadata?: boolean;
 
-  /** Return translations as JSON string */
-  returnTranslationsAsString: boolean;
-
   /** Client identifier */
   client: string;
 
@@ -284,9 +365,6 @@ enum FinishReason {
   /** Some content was filtered due to content policy */
   contentFilter = "contentFilter",
 
-  /** Insufficient character balance */
-  insufficientBalance = "insufficientBalance",
-
   /** Translation failed with error */
   error = "error"
 }
@@ -319,17 +397,48 @@ interface SupportedLanguage {
 
 #### Error Handling
 
-The service throws errors for:
-
-- **400 Bad Request** — Validation error with details
-- **413 Request Too Large** — `"Request too large. Maximum request size is 5 MB."`
-- **500 Server Error** — `"An internal server error occurred (Error code: ...)"`
-
-Returns `null` with error logged for:
-
-- **Missing API Key** — `"API Key not set. Please configure your API Key first."`
-- **401 Unauthorized** — `"Unauthorized. Please check your API Key."`
-- **402 Payment Required** — `"Not enough characters remaining for this translation..."`
+All methods always resolve — they never throw. Check `response.success`:
+
+##### `translate()` error reasons
+
+| `reason` | Description |
+|----------|-------------|
+| `"paymentRequired"` | Insufficient balance (402); `currentBalance` is set |
+| `"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 |
+| `"noApiKey"` | API key was not provided |
+
+##### `getBalance()` error reasons
+
+| `reason` | Description |
+|----------|-------------|
+| `"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
+
+| `reason` | Description |
+|----------|-------------|
+| `"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/consoleLogger.d.ts

@@ -19,8 +19,4 @@ export declare class ConsoleLogger implements ILogger {
      * Log error message
      */
     logError(message: string, error?: unknown): void;
-    /**
-     * Log error details to console
-     */
-    private logErrorDetails;
 }

package/dist/consoleLogger.js

@@ -9,12 +9,11 @@ class ConsoleLogger {
      * Show and log error message
      */
     showAndLogError(message, error, context, linkBtnText, url) {
-        console.error(`❌ ${message}`);
-        if (context) {
-            console.error(`Context: ${context}`);
-        }
         if (error) {
-            this.logErrorDetails(error, console.error);
+            console.error(`❌ ${message}`, context ?? "", error);
+        }
+        else {
+            console.error(`❌ ${message}`, context ?? "");
         }
         if (linkBtnText && url) {
             console.error(`${linkBtnText}: ${url}`);
@@ -30,32 +29,22 @@ class ConsoleLogger {
      * Log warning message
      */
     logWarning(message, error) {
-        console.warn(`⚠️  ${message}`);
         if (error) {
-            this.logErrorDetails(error, console.warn);
+            console.warn(`⚠️  ${message}`, error);
+        }
+        else {
+            console.warn(`⚠️  ${message}`);
         }
     }
     /**
      * Log error message
      */
     logError(message, error) {
-        console.error(`❌ ${message}`);
         if (error) {
-            this.logErrorDetails(error, console.error);
-        }
-    }
-    /**
-     * Log error details to console
-     */
-    logErrorDetails(error, logFn) {
-        if (error instanceof Error) {
-            logFn(`Error: ${error.message}`);
-            if (error.stack) {
-                logFn(error.stack);
-            }
+            console.error(`❌ ${message}`, error);
         }
         else {
-            logFn(`Error: ${String(error)}`);
+            console.error(`❌ ${message}`);
         }
     }
 }

package/dist/translationService.d.ts

@@ -16,7 +16,6 @@ export interface TranslationRequest {
     useShortening?: boolean;
     generatePluralForms?: boolean;
     translateMetadata?: boolean;
-    returnTranslationsAsString: boolean;
     client: string;
     translateOnlyNewStrings?: boolean;
     targetStrings?: string;
@@ -50,7 +49,6 @@ export declare enum FinishReason {
     stop = "stop",
     length = "length",
     contentFilter = "contentFilter",
-    insufficientBalance = "insufficientBalance",
     error = "error"
 }
 export interface Language {
@@ -82,13 +80,51 @@ export interface SupportedLanguage {
 export interface SupportedLanguagesResponse {
     languages: SupportedLanguage[];
 }
+export interface BalanceResponse {
+    /** Current balance of characters available for translation. */
+    currentBalance: number;
+}
+/**
+ * Discriminated union returned by all public service methods.
+ * Check `success` to narrow to the data or error branch.
+ */
+export type ApiResponse<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    reason: "paymentRequired" | "translationError" | "requestTooLarge" | "badRequest" | "unauthorized" | "forbidden" | "rateLimited" | "serverError" | "networkError" | "noApiKey";
+    message: string;
+};
+/**
+ * Response from translate(). Extends ApiResponse<TranslationResult> with an
+ * optional currentBalance field present on both the success and error branches.
+ *
+ * On success: data contains the TranslationResult; currentBalance is the remaining balance.
+ * On error: reason and message describe the failure; currentBalance is set on 402 errors.
+ */
+export type TranslationResponse = ApiResponse<TranslationResult> & {
+    currentBalance?: number;
+};
 export declare class L10nTranslationService {
     private readonly logger;
     constructor(logger?: ILogger);
-    getLanguages(options?: {
+    getBalance(apiKey: string): Promise<ApiResponse<BalanceResponse>>;
+    getLanguages(apiKey: string, options?: {
         codes?: string[];
         proficiencyLevels?: LanguageProficiencyLevel[];
-    }): Promise<SupportedLanguagesResponse>;
-    predictLanguages(input: string, limit?: number): Promise<Language[]>;
-    translate(request: TranslationRequest, apiKey: string): Promise<TranslationResult | null>;
+    }): Promise<ApiResponse<SupportedLanguagesResponse>>;
+    predictLanguages(input: string, limit?: number): Promise<ApiResponse<Language[]>>;
+    translate(request: TranslationRequest, apiKey: string): Promise<TranslationResponse>;
+    private checkApiKey;
+    /**
+     * Maps an HTTP error to a structured ApiResponse error.
+     * Handles 400 (with validation error extraction), 401, 403, 429, 502, 503, and 500.
+     */
+    private handleErrorResponse;
+    /**
+     * Attempts to parse the response body as JSON. If parsing fails, returns the raw text.
+     * Logs a warning if JSON parsing fails.
+     */
+    private parseErrorBody;
 }

package/dist/translationService.js

@@ -19,7 +19,6 @@ var FinishReason;
     FinishReason["stop"] = "stop";
     FinishReason["length"] = "length";
     FinishReason["contentFilter"] = "contentFilter";
-    FinishReason["insufficientBalance"] = "insufficientBalance";
     FinishReason["error"] = "error";
 })(FinishReason || (exports.FinishReason = FinishReason = {}));
 // ── Translation Service ─────────────────────────────────────────────────────
@@ -27,7 +26,28 @@ class L10nTranslationService {
     constructor(logger = new consoleLogger_1.ConsoleLogger()) {
         this.logger = logger;
     }
-    async getLanguages(options) {
+    async getBalance(apiKey) {
+        const apiKeyError = this.checkApiKey(apiKey);
+        if (apiKeyError) {
+            return apiKeyError;
+        }
+        this.logger.logInfo("Fetching current balance");
+        const response = await fetch(`${constants_1.URLS.API_BASE}/v2/balance`, {
+            headers: {
+                "X-API-Key": apiKey,
+            },
+        });
+        if (!response.ok) {
+            return this.handleErrorResponse(response, "Get balance");
+        }
+        const result = (await response.json());
+        return { success: true, data: result };
+    }
+    async getLanguages(apiKey, options) {
+        const apiKeyError = this.checkApiKey(apiKey);
+        if (apiKeyError) {
+            return apiKeyError;
+        }
         const url = new URL(`${constants_1.URLS.API_BASE}/v2/languages`);
         if (options?.codes) {
             for (const c of options.codes) {
@@ -39,11 +59,20 @@ class L10nTranslationService {
                 url.searchParams.append("p", p);
             }
         }
-        const response = await fetch(url.toString());
+        this.logger.logInfo(`Fetching supported languages with filters - codes: ${options?.codes ? options.codes.join(",") : "none"}, proficiency levels: ${options?.proficiencyLevels
+            ? options.proficiencyLevels.join(",")
+            : "none"}`);
+        const response = await fetch(url.toString(), {
+            headers: {
+                "X-API-Key": apiKey,
+            },
+        });
         if (!response.ok) {
-            throw new Error(`Failed to get languages: ${response.status} ${response.statusText}`);
+            return this.handleErrorResponse(response, "Get languages");
         }
-        return (await response.json());
+        const result = (await response.json());
+        this.logger.logInfo(`Successfully fetched ${result.languages.length} languages`);
+        return { success: true, data: result };
     }
     async predictLanguages(input, limit = 10) {
         const url = new URL(`${constants_1.URLS.API_BASE}/v2/languages/predict`);
@@ -52,20 +81,21 @@ class L10nTranslationService {
         this.logger.logInfo(`Predicting languages for input (${input.length} characters)`);
         const response = await fetch(url.toString());
         if (!response.ok) {
-            this.logger.logWarning(`Language prediction failed - ${response.status} ${response.statusText}`);
-            const error = new Error(`Failed to predict languages: ${response.statusText}`);
-            throw error;
+            return this.handleErrorResponse(response, "Predict languages");
         }
         const result = (await response.json());
         this.logger.logInfo(`Successfully predicted ${result.languages.length} languages`);
-        return result.languages;
+        return { success: true, data: result.languages };
     }
     async translate(request, apiKey) {
-        if (!apiKey) {
-            this.logger.showAndLogError("API Key not set. Please configure your API Key first.", null, "", "Get API Key", constants_1.URLS.API_KEYS);
-            return null;
+        const apiKeyError = this.checkApiKey(apiKey);
+        if (apiKeyError) {
+            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: {
@@ -74,82 +104,140 @@ class L10nTranslationService {
             },
             body: JSON.stringify(request),
         });
-        if (!response.ok) {
-            let errorMessage;
-            let errorData = null;
-            // Try to parse error response body
-            try {
-                errorData = await response.json();
+        if (response.ok) {
+            const result = (await response.json());
+            const currentBalance = result?.remainingBalance;
+            // Note: FinishReason.contentFilter and FinishReason.length return partial results with filteredStrings populated, so we treat them as success cases.
+            // Only FinishReason.error is treated as an error status.
+            if (!result || result.finishReason === FinishReason.error) {
+                const message = "Translation failed due to an error.";
+                this.logger.showAndLogError(message);
+                return {
+                    success: false,
+                    reason: "translationError",
+                    message,
+                    currentBalance,
+                };
             }
-            catch {
-                // Ignore JSON parsing errors
+            if (result.finishReason !== FinishReason.stop) {
+                this.logger.logWarning(`Translation finished with reason: ${result.finishReason}`);
             }
-            this.logger.logWarning(`Translation API error - ${response.status} ${response.statusText}`);
-            if (errorData) {
-                this.logger.logWarning(`API error details - ${JSON.stringify(errorData)}`);
+            return { success: true, data: result, currentBalance };
+        }
+        if (response.status === 402) {
+            this.logger.logWarning(`Translation error - ${response.status} ${response.statusText}`);
+            const errorData = await this.parseErrorBody(response);
+            let message = "Not enough characters remaining for this translation. You can try translating a smaller portion of your content or purchase more characters.";
+            const requiredBalance = errorData?.data?.requiredBalance;
+            const currentBalance = errorData?.data?.currentBalance;
+            if (requiredBalance && currentBalance !== undefined) {
+                message = `This translation requires ${requiredBalance.toLocaleString()} characters, but you only have ${currentBalance.toLocaleString()} characters available. You can try translating a smaller portion of your content or purchase more characters.`;
             }
-            switch (response.status) {
-                case 400: {
-                    // Try to extract validation errors from the error response
-                    let validationMessage = "Invalid request. Please check your input and try again.";
-                    if (errorData && errorData.errors) {
-                        const errorDetails = errorData.errors;
-                        if (Array.isArray(errorDetails)) {
-                            validationMessage = errorDetails.join(" ");
-                        }
-                        else if (typeof errorDetails === "object") {
-                            validationMessage = Object.values(errorDetails)
-                                .map((v) => (Array.isArray(v) ? v.join(" ") : v))
-                                .join(" ");
+            this.logger.showAndLogError(message, !requiredBalance ? errorData : undefined, "", "Visit l10n.dev", constants_1.URLS.PRICING);
+            return {
+                success: false,
+                reason: "paymentRequired",
+                message,
+                currentBalance,
+            };
+        }
+        else if (response.status === 413) {
+            this.logger.logWarning(`Translation error - ${response.status} ${response.statusText}`);
+            const errorData = await this.parseErrorBody(response);
+            const message = "Request too large. Maximum request size is 5 MB.";
+            this.logger.showAndLogError(message, errorData);
+            return { success: false, reason: "requestTooLarge", message };
+        }
+        return this.handleErrorResponse(response, "Translate");
+    }
+    checkApiKey(apiKey) {
+        if (!apiKey) {
+            const message = "API Key not set. Please configure your API Key first.";
+            this.logger.showAndLogError(message, null, "", "Get API Key", constants_1.URLS.API_KEYS);
+            return { success: false, reason: "noApiKey", message };
+        }
+        return null;
+    }
+    /**
+     * Maps an HTTP error to a structured ApiResponse error.
+     * Handles 400 (with validation error extraction), 401, 403, 429, 502, 503, and 500.
+     */
+    async handleErrorResponse(response, title) {
+        this.logger.logWarning(`${title} failed - ${response.status} ${response.statusText}`);
+        const errorData = await this.parseErrorBody(response);
+        const status = response.status;
+        switch (status) {
+            case 400: {
+                let message = "Invalid request. Please check your input and try again.";
+                if (errorData?.errors &&
+                    typeof errorData.errors === "object" &&
+                    !Array.isArray(errorData.errors)) {
+                    const e = errorData.errors;
+                    message = Object.keys(e)
+                        .map((k) => {
+                        const v = e[k];
+                        if (k) {
+                            // not empty key
+                            if (Array.isArray(v)) {
+                                return `${k}: ${v.join(" ")}`;
+                            }
+                            else {
+                                return `${k}: ${String(v)}`;
+                            }
                         }
-                    }
-                    errorMessage = validationMessage;
-                    break;
+                        return Array.isArray(v) ? v.join(" ") : String(v);
+                    })
+                        .join("; \r\n");
+                    this.logger.showAndLogError(message);
                 }
-                case 401:
-                    errorMessage = "Unauthorized. Please check your API Key.";
-                    this.logger.showAndLogError(errorMessage, errorData, "", "Get API Key", constants_1.URLS.API_KEYS);
-                    return null;
-                case 402: {
-                    // Try to extract required characters from the error response
-                    let message = "Not enough characters remaining for this translation. You can try translating a smaller portion of your file or purchase more characters.";
-                    const requiredBalance = errorData?.data?.requiredBalance;
-                    if (requiredBalance) {
-                        const currentBalance = errorData?.data?.currentBalance ?? 0;
-                        message = `This translation requires ${requiredBalance.toLocaleString()} characters, but you only have ${currentBalance.toLocaleString()} characters available. You can try translating a smaller portion of your file or purchase more characters.`;
-                    }
-                    this.logger.showAndLogError(message, errorData, "", "Visit l10n.dev", constants_1.URLS.PRICING);
-                    return null;
+                else {
+                    this.logger.showAndLogError(message, errorData);
                 }
-                case 413:
-                    errorMessage = "Request too large. Maximum request size is 5 MB.";
-                    break;
-                case 500:
-                    errorMessage = `An internal server error occurred (Error code: ${errorData?.errorCode || "unknown"}). Please try again later.`;
-                    break;
-                default:
-                    errorMessage =
-                        "Failed to translate. Please check your connection and try again.";
+                return { success: false, reason: "badRequest", message };
             }
-            throw new Error(errorMessage);
-        }
-        const result = (await response.json());
-        // Handle finish reasons
-        if (result.finishReason) {
-            if (result.finishReason !== FinishReason.stop) {
-                this.logger.logWarning(`Translation finished with reason: ${result.finishReason}`);
+            case 401: {
+                const message = "Unauthorized. Please check your API Key.";
+                this.logger.showAndLogError(message, errorData, "", "Get API Key", constants_1.URLS.API_KEYS);
+                return { success: false, reason: "unauthorized", message: message };
+            }
+            case 403: {
+                const message = "Forbidden. You don't have permission to access this resource.";
+                this.logger.showAndLogError(message, errorData);
+                return { success: false, reason: "forbidden", message: message };
+            }
+            case 429: {
+                const message = "Too many requests. You're being rate limited. Please try again later.";
+                this.logger.showAndLogError(message, errorData);
+                return { success: false, reason: "rateLimited", message: message };
             }
-            switch (result.finishReason) {
-                case FinishReason.insufficientBalance:
-                    const message = `Not enough characters remaining for this translation. You can try translating a smaller portion of your file or purchase more characters.`;
-                    this.logger.showAndLogError(message, undefined, "", "Visit l10n.dev", constants_1.URLS.PRICING);
-                    return result;
-                case FinishReason.error:
-                    throw new Error("Translation failed due to an error.");
-                // Note: FinishReason.contentFilter and FinishReason.length return partial results with filteredStrings
+            case 502:
+            case 503:
+            case 500: {
+                const message = `An internal server error occurred (Error code: ${errorData?.errorCode ?? "unknown"}). Please try again later.`;
+                this.logger.showAndLogError(message, errorData);
+                return { success: false, reason: "serverError", message: message };
             }
+            default: {
+                const message = `Failed to ${title.toLowerCase()}: ${response.status} ${response.statusText}`;
+                this.logger.showAndLogError(message, errorData);
+                return { success: false, reason: "networkError", message: message };
+            }
+        }
+    }
+    /**
+     * Attempts to parse the response body as JSON. If parsing fails, returns the raw text.
+     * Logs a warning if JSON parsing fails.
+     */
+    async parseErrorBody(response) {
+        let rawBody;
+        try {
+            rawBody = await response.text();
+            return JSON.parse(rawBody);
+        }
+        catch {
+            this.logger.logWarning("Failed to parse error response");
+            return rawBody;
         }
-        return result;
     }
 }
 exports.L10nTranslationService = L10nTranslationService;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-l10n-core",
-  "version": "1.4.1",
+  "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",