ai-l10n-core 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,68 @@ 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.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: string; 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: `"noApiKey"`, `"unauthorized"`, `"paymentRequired"`, `"badRequest"`, `"requestTooLarge"`, `"serverError"`, `"networkError"`, `"translationError"`
+- **`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

@@ -7,7 +7,7 @@ Platform-independent core for AI-powered localization — translation API client
 
 This is the foundational library for the [ai-l10n](https://www.npmjs.com/package/ai-l10n) ecosystem. It provides the low-level translation API client, logger interface, and language utilities used by the SDK and CLI.
 
-Powered by [l10n.dev](https://l10n.dev).
+Powered by [l10n](https://l10n.dev).dev
 
 ## Installation
 
@@ -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
+
+**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.
 
-##### `predictLanguages(input: string, limit?: number): Promise<Language[]>`
+**Error reasons:** `noApiKey`, `unauthorized`, `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,76 @@ 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:** `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`, `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: string; 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 +262,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 +351,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 +383,43 @@ interface SupportedLanguage {
 
 #### Error Handling
 
-The service throws errors for:
+All methods always resolve — they never throw. Check `response.success`:
+
+##### `translate()` error reasons
+
+| `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 |
+| `"requestTooLarge"` | Request exceeds 5 MB (413) |
+| `"serverError"` | Internal server error (500) |
+| `"networkError"` | Connection or other failure |
+| `"translationError"` | API returned `finishReason: "error"` |
+
+##### `getBalance()` error reasons
+
+| `reason` | Description |
+|----------|-------------|
+| `"noApiKey"` | API key was not provided |
+| `"unauthorized"` | API key is invalid (401) |
+| `"networkError"` | Connection or other failure |
+
+##### `getLanguages()` error reasons
 
-- **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: ...)"`
+| `reason` | Description |
+|----------|-------------|
+| `"noApiKey"` | API key was not provided |
+| `"unauthorized"` | API key is invalid (401) |
+| `"badRequest"` | Validation error (400); `message` contains details |
+| `"networkError"` | Connection or other failure |
 
-Returns `null` with error logged for:
+##### `predictLanguages()` error reasons
 
-- **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..."`
+| `reason` | Description |
+|----------|-------------|
+| `"networkError"` | Connection or other failure |
 
 ---
 
@@ -484,4 +574,4 @@ MIT
 
 ## Credits
 
-Powered by [l10n.dev](https://l10n.dev) — AI-powered localization service
+Powered by [l10n](https://l10n.dev).dev — AI-powered localization service

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: string;
+    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;
 }