@belocal/js-sdk 0.6.0 → 0.7.0

package/dist/node.d.ts

@@ -1,8 +1,28 @@
+/**
+ * Language code for translation (e.g., 'en', 'es', 'fr', 'ru').
+ * ISO 639-1 language codes are recommended.
+ */
 type Lang = string;
+/**
+ * Key-value pairs for translation context.
+ * Supported keys:
+ * - `user_ctx` (string): Descriptive context to help improve translation quality (e.g., 'greeting message on the homepage')
+ * - `cache_type` (string): Cache type, e.g., 'managed' (managed translations cache)
+ *
+ * Other keys will be ignored by the API.
+ */
 type KV = Record<string, string>;
+/**
+ * Base transport interface for HTTP communication.
+ * @internal
+ */
 interface BaseTransport {
     post(data: any, endpointPath: string): Promise<any>;
 }
+/**
+ * Transport function type for translation requests.
+ * @internal
+ */
 type Transport = (params: {
     text: string;
     lang: Lang;
@@ -12,16 +32,21 @@ type Transport = (params: {
     text: string;
     status: string;
 }>;
+/**
+ * Configuration options for BelocalEngine.
+ */
 interface BelocalEngineOptions {
+    /** Required: Your BeLocal API key for authentication */
     apiKey: string;
-    baseUrl?: string;
+    /** Optional: Batch window in milliseconds for grouping multiple translation requests. Defaults to 50ms */
     batchWindowMs?: number;
+    /** Optional: Request timeout in milliseconds. Defaults to 10000ms (10 seconds) */
     timeoutMs?: number;
+    /** Optional: Enable debug logging to console. Defaults to false */
     debug?: boolean;
 }
 
 interface BaseNodeTransportConfig {
-    baseUrl: string;
     headers?: Record<string, string>;
     timeoutMs?: number;
     retries?: number;
@@ -41,13 +66,154 @@ interface MultiTransportConfig {
 }
 declare function createMultiTransport(config: MultiTransportConfig): Transport;
 
+/**
+ * BeLocal translation engine for Node.js environments.
+ *
+ * Provides on-demand translation with automatic request batching, caching, and deduplication.
+ * Optimized for Node.js environments using HTTP/2 with connection pooling and automatic retries.
+ *
+ * @example
+ * ```typescript
+ * const engine = new BelocalEngine({
+ *   apiKey: 'your-api-key',
+ *   debug: true
+ * });
+ *
+ * const translated = await engine.translate('Hello world', 'es');
+ * ```
+ */
 declare class BelocalEngine {
     private transport;
     private debug;
     private cache;
+    /**
+     * Creates a new BelocalEngine instance.
+     *
+     * @param options - Configuration options for the engine
+     * @throws {Error} If apiKey is not provided or invalid
+     *
+     * @example
+     * ```typescript
+     * const engine = new BelocalEngine({
+     *   apiKey: 'your-api-key',
+     *   batchWindowMs: 100,
+     *   timeoutMs: 10000,
+     *   debug: false
+     * });
+     * ```
+     */
     constructor(options: BelocalEngineOptions);
+    /**
+     * Translates a single text string to the target language.
+     *
+     * Uses in-memory cache to avoid redundant API calls. Results are automatically cached
+     * for subsequent requests with the same parameters.
+     *
+     * @param text - The text to translate
+     * @param lang - Target language code (e.g., 'es', 'fr', 'ru')
+     * @param source_lang - Optional source language code. If not provided, auto-detection is used
+     * @param ctx - Optional key-value pairs for translation context. Supported keys: `user_ctx` (string - descriptive context in English), `cache_type` ('managed' | string)
+     * @returns Promise resolving to the translated text
+     * @throws {Error} If the translation request fails (network error, API error, timeout)
+     *
+     * @example
+     * ```typescript
+     * // Simple translation
+     * const result = await engine.translate('Hello world', 'es');
+     *
+     * // With source language
+     * const result = await engine.translate('Hello world', 'es', 'en');
+     *
+     * // With context (user_ctx) - descriptive context helps improve translation quality
+     * const result = await engine.translate('Hello world', 'es', undefined, {
+     *   user_ctx: 'greeting message on the homepage'
+     * });
+     *
+     * // With cache_type
+     * const result = await engine.translate('Hello world', 'es', undefined, { cache_type: 'managed' });
+     *
+     * // With source language and context
+     * const result = await engine.translate('Hello world', 'es', 'en', {
+     *   user_ctx: 'greeting message on the homepage'
+     * });
+     * ```
+     */
     translate(text: string, lang: Lang, source_lang?: string, ctx?: KV): Promise<string>;
+    /**
+     * Translates multiple text strings to the target language in a single batch.
+     *
+     * This method is more efficient than calling `translate()` multiple times as it:
+     * - Batches requests together to reduce API calls
+     * - Checks cache for each text individually
+     * - Only requests translations for cache misses
+     * - Maintains the order of input texts in the result array
+     *
+     * @param texts - Array of texts to translate
+     * @param lang - Target language code (e.g., 'es', 'fr', 'ru')
+     * @param source_lang - Optional source language code. If not provided, auto-detection is used
+     * @param ctx - Optional key-value pairs for translation context. Supported keys: `user_ctx` (string - descriptive context in English), `cache_type` ('managed' | string)
+     * @returns Promise resolving to an array of translated texts in the same order as input
+     * @throws {Error} If the translation request fails (network error, API error, timeout)
+     *
+     * @example
+     * ```typescript
+     * // Translate multiple texts
+     * const results = await engine.translateMany(['Hello', 'World', 'Test'], 'es');
+     * // Returns: ['Hola', 'Mundo', 'Prueba']
+     *
+     * // With source language
+     * const results = await engine.translateMany(['Hello', 'World'], 'fr', 'en');
+     *
+     * // With context (user_ctx) - descriptive context helps improve translation quality
+     * const results = await engine.translateMany(
+     *   ['Hello', 'World'],
+     *   'es',
+     *   undefined,
+     *   { user_ctx: 'greeting message on the homepage' }
+     * );
+     *
+     * // With cache_type
+     * const results = await engine.translateMany(
+     *   ['Hello', 'World'],
+     *   'es',
+     *   undefined,
+     *   { cache_type: 'managed' }
+     * );
+     *
+     * // Empty array returns empty array
+     * const results = await engine.translateMany([], 'es');
+     * // Returns: []
+     * ```
+     */
     translateMany(texts: string[], lang: Lang, source_lang?: string, ctx?: KV): Promise<string[]>;
+    /**
+     * Shortcut method for translation with simplified API.
+     *
+     * This is a convenience method that wraps `translate()`. When `context` is provided as a string,
+     * it is automatically wrapped in `{user_ctx: context}` object.
+     *
+     * @param text - The text to translate
+     * @param lang - Target language code (e.g., 'es', 'fr', 'ru')
+     * @param source_lang - Optional source language code
+     * @param context - Optional descriptive context string in English (will be wrapped as {user_ctx: context})
+     * @returns Promise resolving to the translated text
+     * @throws {Error} If the translation request fails (network error, API error, timeout)
+     *
+     * @example
+     * ```typescript
+     * // Simple translation
+     * const result = await engine.t('Hello world', 'es');
+     *
+     * // With source language
+     * const result = await engine.t('Hello world', 'fr', 'en');
+     *
+     * // With context string (automatically wrapped as {user_ctx: 'greeting message on the homepage'})
+     * const result = await engine.t('Hello world', 'es', undefined, 'greeting message on the homepage');
+     *
+     * // With source language and context
+     * const result = await engine.t('Hello world', 'es', 'en', 'greeting message on the homepage');
+     * ```
+     */
     t(text: string, lang: Lang, source_lang?: string, context?: string): Promise<string>;
     private generateCacheKey;
 }

package/dist/node.mjs

@@ -146,7 +146,7 @@ function createMultiTransport(config) {
 // src/version.ts
 var SDK_VERSION = (() => {
   try {
-    return true ? "0.6.0" : "undefined";
+    return true ? "0.7.0" : "undefined";
   } catch {
     return "undefined";
   }
@@ -201,23 +201,45 @@ var DedupeTransport = class {
 };
 
 // src/transports/base/node.ts
+var BASE_URL = "https://dynamic.belocal.dev";
 var sessionCache = /* @__PURE__ */ new Map();
-function getOrCreateSession(baseUrl, debug) {
-  if (sessionCache.has(baseUrl)) {
-    const session2 = sessionCache.get(baseUrl);
-    if (!session2.destroyed) {
+var cleanupTimer = null;
+function cleanupDeadSessions() {
+  for (const [url, session] of sessionCache.entries()) {
+    if (session.destroyed || session.closed) {
+      sessionCache.delete(url);
+    }
+  }
+}
+function startCleanupTimer() {
+  if (cleanupTimer === null) {
+    cleanupTimer = setInterval(cleanupDeadSessions, 6e4);
+    if (cleanupTimer.unref) {
+      cleanupTimer.unref();
+    }
+  }
+}
+function getOrCreateSession(debug) {
+  cleanupDeadSessions();
+  startCleanupTimer();
+  if (sessionCache.has(BASE_URL)) {
+    const session2 = sessionCache.get(BASE_URL);
+    if (!session2.destroyed && !session2.closed) {
       return session2;
     }
-    sessionCache.delete(baseUrl);
+    sessionCache.delete(BASE_URL);
   }
-  const parsedUrl = new URL(baseUrl);
+  const parsedUrl = new URL(BASE_URL);
   const session = http2.connect(parsedUrl.origin);
   session.socket?.unref();
   session.on("error", () => {
-    sessionCache.delete(baseUrl);
+    sessionCache.delete(BASE_URL);
   });
   session.on("close", () => {
-    sessionCache.delete(baseUrl);
+    sessionCache.delete(BASE_URL);
+  });
+  session.on("goaway", () => {
+    sessionCache.delete(BASE_URL);
   });
   if (debug) {
     session.on("connect", () => console.log("[Base Node Transport H2] new session connected"));
@@ -226,7 +248,7 @@ function getOrCreateSession(baseUrl, debug) {
       (code, lastStreamID, opaque) => console.log("[Base Node Transport H2] goaway", code, lastStreamID)
     );
   }
-  sessionCache.set(baseUrl, session);
+  sessionCache.set(BASE_URL, session);
   return session;
 }
 function makeHttp2Request(session, path, headers, body, timeoutMs) {
@@ -278,25 +300,26 @@ var BaseNodeTransport = class {
   async post(data, endpointPath) {
     const maxRetries = this.config.retries || 0;
     let attempt = 0;
-    const url = `${this.config.baseUrl}${endpointPath}`;
+    const url = `${BASE_URL}${endpointPath}`;
     if (this.config.debug) {
       console.log(`[Base Node Transport] POST request to ${url}`, data);
     }
     while (attempt <= maxRetries) {
       try {
-        const session = getOrCreateSession(this.config.baseUrl, this.config.debug);
+        const session = getOrCreateSession(this.config.debug);
         const body = JSON.stringify(data);
         const headers = {
           "x-sdk": SDK_NAME,
           "x-sdk-version": SDK_VERSION,
           ...this.config.headers
         };
+        const timeoutMs = this.config.timeoutMs ?? 1e4;
         const response = await makeHttp2Request(
           session,
           endpointPath,
           headers,
           body,
-          this.config.timeoutMs
+          timeoutMs
         );
         if (response.statusCode < 200 || response.statusCode >= 300) {
           const errorMsg = `HTTP ${response.statusCode}: Request failed`;
@@ -345,10 +368,25 @@ var LocalCache = class {
   }
 };
 var BelocalEngine = class {
+  /**
+   * Creates a new BelocalEngine instance.
+   * 
+   * @param options - Configuration options for the engine
+   * @throws {Error} If apiKey is not provided or invalid
+   * 
+   * @example
+   * ```typescript
+   * const engine = new BelocalEngine({
+   *   apiKey: 'your-api-key',
+   *   batchWindowMs: 100,
+   *   timeoutMs: 10000,
+   *   debug: false
+   * });
+   * ```
+   */
   constructor(options) {
     const {
       apiKey,
-      baseUrl = "https://dynamic.belocal.dev",
       batchWindowMs = 50,
       timeoutMs = 1e4,
       debug = false
@@ -362,7 +400,6 @@ var BelocalEngine = class {
       "Authorization": `Bearer ${apiKey}`
     };
     const baseTransport = createBaseNodeTransport({
-      baseUrl,
       headers: authHeaders,
       timeoutMs,
       debug: this.debug
@@ -374,16 +411,97 @@ var BelocalEngine = class {
     });
     if (this.debug) {
       console.log("[BeLocal Engine] Multi transport created with config:", {
-        baseUrl,
+        baseUrl: "https://dynamic.belocal.dev",
         timeoutMs,
         batchWindowMs
       });
     }
   }
+  /**
+   * Translates a single text string to the target language.
+   * 
+   * Uses in-memory cache to avoid redundant API calls. Results are automatically cached
+   * for subsequent requests with the same parameters.
+   * 
+   * @param text - The text to translate
+   * @param lang - Target language code (e.g., 'es', 'fr', 'ru')
+   * @param source_lang - Optional source language code. If not provided, auto-detection is used
+   * @param ctx - Optional key-value pairs for translation context. Supported keys: `user_ctx` (string - descriptive context in English), `cache_type` ('managed' | string)
+   * @returns Promise resolving to the translated text
+   * @throws {Error} If the translation request fails (network error, API error, timeout)
+   * 
+   * @example
+   * ```typescript
+   * // Simple translation
+   * const result = await engine.translate('Hello world', 'es');
+   * 
+   * // With source language
+   * const result = await engine.translate('Hello world', 'es', 'en');
+   * 
+   * // With context (user_ctx) - descriptive context helps improve translation quality
+   * const result = await engine.translate('Hello world', 'es', undefined, { 
+   *   user_ctx: 'greeting message on the homepage' 
+   * });
+   * 
+   * // With cache_type
+   * const result = await engine.translate('Hello world', 'es', undefined, { cache_type: 'managed' });
+   * 
+   * // With source language and context
+   * const result = await engine.translate('Hello world', 'es', 'en', { 
+   *   user_ctx: 'greeting message on the homepage' 
+   * });
+   * ```
+   */
   async translate(text, lang, source_lang, ctx) {
     const results = await this.translateMany([text], lang, source_lang, ctx);
     return results[0];
   }
+  /**
+   * Translates multiple text strings to the target language in a single batch.
+   * 
+   * This method is more efficient than calling `translate()` multiple times as it:
+   * - Batches requests together to reduce API calls
+   * - Checks cache for each text individually
+   * - Only requests translations for cache misses
+   * - Maintains the order of input texts in the result array
+   * 
+   * @param texts - Array of texts to translate
+   * @param lang - Target language code (e.g., 'es', 'fr', 'ru')
+   * @param source_lang - Optional source language code. If not provided, auto-detection is used
+   * @param ctx - Optional key-value pairs for translation context. Supported keys: `user_ctx` (string - descriptive context in English), `cache_type` ('managed' | string)
+   * @returns Promise resolving to an array of translated texts in the same order as input
+   * @throws {Error} If the translation request fails (network error, API error, timeout)
+   * 
+   * @example
+   * ```typescript
+   * // Translate multiple texts
+   * const results = await engine.translateMany(['Hello', 'World', 'Test'], 'es');
+   * // Returns: ['Hola', 'Mundo', 'Prueba']
+   * 
+   * // With source language
+   * const results = await engine.translateMany(['Hello', 'World'], 'fr', 'en');
+   * 
+   * // With context (user_ctx) - descriptive context helps improve translation quality
+   * const results = await engine.translateMany(
+   *   ['Hello', 'World'], 
+   *   'es', 
+   *   undefined, 
+   *   { user_ctx: 'greeting message on the homepage' }
+   * );
+   * 
+   * // With cache_type
+   * const results = await engine.translateMany(
+   *   ['Hello', 'World'], 
+   *   'es', 
+   *   undefined, 
+   *   { cache_type: 'managed' }
+   * );
+   * 
+   * // Empty array returns empty array
+   * const results = await engine.translateMany([], 'es');
+   * // Returns: []
+   * ```
+   */
   async translateMany(texts, lang, source_lang, ctx) {
     const results = new Array(texts.length);
     const cacheMisses = [];
@@ -425,6 +543,34 @@ var BelocalEngine = class {
     }
     return results;
   }
+  /**
+   * Shortcut method for translation with simplified API.
+   * 
+   * This is a convenience method that wraps `translate()`. When `context` is provided as a string,
+   * it is automatically wrapped in `{user_ctx: context}` object.
+   * 
+   * @param text - The text to translate
+   * @param lang - Target language code (e.g., 'es', 'fr', 'ru')
+   * @param source_lang - Optional source language code
+   * @param context - Optional descriptive context string in English (will be wrapped as {user_ctx: context})
+   * @returns Promise resolving to the translated text
+   * @throws {Error} If the translation request fails (network error, API error, timeout)
+   * 
+   * @example
+   * ```typescript
+   * // Simple translation
+   * const result = await engine.t('Hello world', 'es');
+   * 
+   * // With source language
+   * const result = await engine.t('Hello world', 'fr', 'en');
+   * 
+   * // With context string (automatically wrapped as {user_ctx: 'greeting message on the homepage'})
+   * const result = await engine.t('Hello world', 'es', undefined, 'greeting message on the homepage');
+   * 
+   * // With source language and context
+   * const result = await engine.t('Hello world', 'es', 'en', 'greeting message on the homepage');
+   * ```
+   */
   async t(text, lang, source_lang, context) {
     if (context) {
       return this.translate(text, lang, source_lang, { user_ctx: context });