@lingo.dev/_sdk 0.16.3 → 0.16.5

package/build/index.cjs

@@ -1,5 +1,8 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3;// src/index.ts
 var _zod = require('zod'); var _zod2 = _interopRequireDefault(_zod);
+
+
+
 var __spec = require('@lingo.dev/_spec');
 var _cuid2 = require('@paralleldrive/cuid2');
 
@@ -111,14 +114,21 @@ var engineParamsSchema = _zod2.default.object({
   apiUrl: _zod2.default.string().url().default("https://api.lingo.dev"),
   batchSize: _zod2.default.number().int().gt(0).lte(250).default(25),
   idealBatchItemSize: _zod2.default.number().int().gt(0).lte(2500).default(250),
-  engineId: _zod2.default.string().optional()
+  engineId: _zod2.default.string().optional(),
+  // Number of times a localization request is retried after a transient
+  // failure (5xx response or network error). `0` disables retries.
+  maxRetries: _zod2.default.number().int().gte(0).default(3),
+  // Base delay (ms) for the exponential backoff between retries. The actual
+  // wait grows as `retryDelayMs * 2 ** attempt` plus a small random jitter.
+  retryDelayMs: _zod2.default.number().int().gte(0).default(500)
 }).passthrough();
+var normalizedLocaleCodeSchema = __spec.localeCodeSchema.transform(__spec.normalizeLocale);
 var payloadSchema = _zod2.default.record(_zod2.default.string(), _zod2.default.any());
-var referenceSchema = _zod2.default.record(__spec.localeCodeSchema, payloadSchema);
+var referenceSchema = _zod2.default.record(normalizedLocaleCodeSchema, payloadSchema);
 var hintsSchema = _zod2.default.record(_zod2.default.string(), _zod2.default.array(_zod2.default.string()));
 var localizationParamsSchema = _zod2.default.object({
-  sourceLocale: _zod2.default.union([__spec.localeCodeSchema, _zod2.default.null()]),
-  targetLocale: __spec.localeCodeSchema,
+  sourceLocale: _zod2.default.union([normalizedLocaleCodeSchema, _zod2.default.null()]),
+  targetLocale: normalizedLocaleCodeSchema,
   fast: _zod2.default.boolean().optional(),
   reference: referenceSchema.optional(),
   hints: hintsSchema.optional(),
@@ -162,6 +172,74 @@ var LingoDotDevEngine = (_class = class _LingoDotDevEngine {
     }
     throw new Error(context ? `${context}: ${msg}` : msg);
   }
+  /**
+   * Sleep for `ms` milliseconds, rejecting early if the signal is aborted.
+   */
+  static sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+      if (_optionalChain([signal, 'optionalAccess', _4 => _4.aborted])) {
+        reject(new Error("Operation was aborted"));
+        return;
+      }
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(new Error("Operation was aborted"));
+      };
+      const timer = setTimeout(() => {
+        _optionalChain([signal, 'optionalAccess', _5 => _5.removeEventListener, 'call', _6 => _6("abort", onAbort)]);
+        resolve();
+      }, ms);
+      _optionalChain([signal, 'optionalAccess', _7 => _7.addEventListener, 'call', _8 => _8("abort", onAbort, { once: true })]);
+    });
+  }
+  /**
+   * Exponential backoff with full jitter: a random delay in
+   * `[0, retryDelayMs * 2 ** attempt]`. Jitter spreads out retries from many
+   * clients so a recovering server is not hit by a synchronized wave.
+   */
+  backoffDelay(attempt) {
+    const ceiling = this.config.retryDelayMs * 2 ** attempt;
+    return Math.round(Math.random() * ceiling);
+  }
+  /**
+   * Perform a fetch, retrying on transient failures (5xx responses and
+   * network errors) with exponential backoff. The retry decision is made on
+   * the HTTP status code (>= 500), so non-retryable responses (e.g. 4xx) are
+   * returned immediately for the caller to handle. Aborted requests are never
+   * retried.
+   * @param url - The request URL
+   * @param init - Fetch init options (should include the AbortSignal)
+   * @param signal - Optional AbortSignal used to short-circuit retries
+   * @returns The fetch Response (which may still be a non-retryable error)
+   */
+  async fetchWithRetry(url, init, signal) {
+    const { maxRetries } = this.config;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      if (_optionalChain([signal, 'optionalAccess', _9 => _9.aborted])) {
+        throw new Error("Operation was aborted");
+      }
+      try {
+        const res = await fetch(url, init);
+        const isServerError = res.status >= 500 && res.status < 600;
+        if (isServerError && attempt < maxRetries) {
+          await _optionalChain([res, 'access', _10 => _10.body, 'optionalAccess', _11 => _11.cancel, 'call', _12 => _12()]);
+          await _LingoDotDevEngine.sleep(this.backoffDelay(attempt), signal);
+          continue;
+        }
+        return res;
+      } catch (error) {
+        if (_optionalChain([signal, 'optionalAccess', _13 => _13.aborted])) {
+          throw error;
+        }
+        if (attempt < maxRetries) {
+          await _LingoDotDevEngine.sleep(this.backoffDelay(attempt), signal);
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new Error("Localization request failed after exhausting retries");
+  }
   /**
    * Create a new LingoDotDevEngine instance
    * @param config - Configuration options for the Engine
@@ -191,7 +269,7 @@ var LingoDotDevEngine = (_class = class _LingoDotDevEngine {
       const processedPayloadChunk = await this.localizeChunk(
         finalParams.sourceLocale,
         finalParams.targetLocale,
-        { data: chunk, reference: params.reference, hints: params.hints },
+        { data: chunk, reference: finalParams.reference, hints: params.hints },
         params.fast || false,
         params.filePath,
         params.triggerType,
@@ -229,12 +307,16 @@ var LingoDotDevEngine = (_class = class _LingoDotDevEngine {
       metadata: filePath ? { filePath } : void 0,
       ...this.config.engineId && { engineId: this.config.engineId }
     };
-    const res = await fetch(url, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify(body, null, 2),
+    const res = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify(body, null, 2),
+        signal
+      },
       signal
-    });
+    );
     await _LingoDotDevEngine.throwOnHttpError(res);
     const jsonResponse = await res.json();
     if (!jsonResponse.data && jsonResponse.error) {
@@ -575,7 +657,7 @@ var LingoDotDevEngine = (_class = class _LingoDotDevEngine {
             break;
           }
           const siblings = Array.from(parent.childNodes).filter(
-            (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _4 => _4.textContent, 'optionalAccess', _5 => _5.trim, 'call', _6 => _6()])
+            (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _14 => _14.textContent, 'optionalAccess', _15 => _15.trim, 'call', _16 => _16()])
           );
           const index = siblings.indexOf(current);
           if (index !== -1) {
@@ -595,7 +677,7 @@ var LingoDotDevEngine = (_class = class _LingoDotDevEngine {
           parent = parent.parentElement;
         }
         if (node.nodeType === 3) {
-          const text = _optionalChain([node, 'access', _7 => _7.textContent, 'optionalAccess', _8 => _8.trim, 'call', _9 => _9()]) || "";
+          const text = _optionalChain([node, 'access', _17 => _17.textContent, 'optionalAccess', _18 => _18.trim, 'call', _19 => _19()]) || "";
           if (text) {
             extractedContent[getPath(node)] = text;
           }
@@ -610,15 +692,15 @@ var LingoDotDevEngine = (_class = class _LingoDotDevEngine {
             }
           });
           Array.from(element.childNodes).filter(
-            (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _10 => _10.textContent, 'optionalAccess', _11 => _11.trim, 'call', _12 => _12()])
+            (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _20 => _20.textContent, 'optionalAccess', _21 => _21.trim, 'call', _22 => _22()])
           ).forEach(processNode);
         }
       };
       Array.from(document.head.childNodes).filter(
-        (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _13 => _13.textContent, 'optionalAccess', _14 => _14.trim, 'call', _15 => _15()])
+        (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _23 => _23.textContent, 'optionalAccess', _24 => _24.trim, 'call', _25 => _25()])
       ).forEach(processNode);
       Array.from(document.body.childNodes).filter(
-        (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _16 => _16.textContent, 'optionalAccess', _17 => _17.trim, 'call', _18 => _18()])
+        (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _26 => _26.textContent, 'optionalAccess', _27 => _27.trim, 'call', _28 => _28()])
       ).forEach(processNode);
       const localizedContent = await this._localizeRaw(
         extractedContent,
@@ -634,10 +716,10 @@ var LingoDotDevEngine = (_class = class _LingoDotDevEngine {
         let current = parent;
         for (const index of indices) {
           const siblings = Array.from(parent.childNodes).filter(
-            (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _19 => _19.textContent, 'optionalAccess', _20 => _20.trim, 'call', _21 => _21()])
+            (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _29 => _29.textContent, 'optionalAccess', _30 => _30.trim, 'call', _31 => _31()])
           );
           current = siblings[parseInt(index)] || null;
-          if (_optionalChain([current, 'optionalAccess', _22 => _22.nodeType]) === 1) {
+          if (_optionalChain([current, 'optionalAccess', _32 => _32.nodeType]) === 1) {
             parent = current;
           }
         }
@@ -726,7 +808,7 @@ var LingoDotDevEngine = (_class = class _LingoDotDevEngine {
     });
     if (res.ok) {
       const payload = await res.json();
-      if (!_optionalChain([payload, 'optionalAccess', _23 => _23.email])) {
+      if (!_optionalChain([payload, 'optionalAccess', _33 => _33.email])) {
         return null;
       }
       return {

package/build/index.d.cts

@@ -7,13 +7,15 @@ declare const engineParamsSchema: Z.ZodObject<{
     batchSize: Z.ZodDefault<Z.ZodNumber>;
     idealBatchItemSize: Z.ZodDefault<Z.ZodNumber>;
     engineId: Z.ZodOptional<Z.ZodString>;
+    maxRetries: Z.ZodDefault<Z.ZodNumber>;
+    retryDelayMs: Z.ZodDefault<Z.ZodNumber>;
 }, Z.core.$loose>;
 declare const payloadSchema: Z.ZodRecord<Z.ZodString, Z.ZodAny>;
 declare const localizationParamsSchema: Z.ZodObject<{
-    sourceLocale: Z.ZodUnion<readonly [Z.ZodString, Z.ZodNull]>;
-    targetLocale: Z.ZodString;
+    sourceLocale: Z.ZodUnion<readonly [Z.ZodPipe<Z.ZodString, Z.ZodTransform<string, string>>, Z.ZodNull]>;
+    targetLocale: Z.ZodPipe<Z.ZodString, Z.ZodTransform<string, string>>;
     fast: Z.ZodOptional<Z.ZodBoolean>;
-    reference: Z.ZodOptional<Z.ZodRecord<Z.ZodString, Z.ZodRecord<Z.ZodString, Z.ZodAny>>>;
+    reference: Z.ZodOptional<Z.ZodRecord<Z.ZodPipe<Z.ZodString, Z.ZodTransform<string, string>>, Z.ZodRecord<Z.ZodString, Z.ZodAny>>>;
     hints: Z.ZodOptional<Z.ZodRecord<Z.ZodString, Z.ZodArray<Z.ZodString>>>;
     filePath: Z.ZodOptional<Z.ZodString>;
     triggerType: Z.ZodOptional<Z.ZodEnum<{
@@ -32,6 +34,28 @@ declare class LingoDotDevEngine {
     private get headers();
     private static extractErrorMessage;
     private static throwOnHttpError;
+    /**
+     * Sleep for `ms` milliseconds, rejecting early if the signal is aborted.
+     */
+    private static sleep;
+    /**
+     * Exponential backoff with full jitter: a random delay in
+     * `[0, retryDelayMs * 2 ** attempt]`. Jitter spreads out retries from many
+     * clients so a recovering server is not hit by a synchronized wave.
+     */
+    private backoffDelay;
+    /**
+     * Perform a fetch, retrying on transient failures (5xx responses and
+     * network errors) with exponential backoff. The retry decision is made on
+     * the HTTP status code (>= 500), so non-retryable responses (e.g. 4xx) are
+     * returned immediately for the caller to handle. Aborted requests are never
+     * retried.
+     * @param url - The request URL
+     * @param init - Fetch init options (should include the AbortSignal)
+     * @param signal - Optional AbortSignal used to short-circuit retries
+     * @returns The fetch Response (which may still be a non-retryable error)
+     */
+    private fetchWithRetry;
     /**
      * Create a new LingoDotDevEngine instance
      * @param config - Configuration options for the Engine

package/build/index.d.ts

@@ -7,13 +7,15 @@ declare const engineParamsSchema: Z.ZodObject<{
     batchSize: Z.ZodDefault<Z.ZodNumber>;
     idealBatchItemSize: Z.ZodDefault<Z.ZodNumber>;
     engineId: Z.ZodOptional<Z.ZodString>;
+    maxRetries: Z.ZodDefault<Z.ZodNumber>;
+    retryDelayMs: Z.ZodDefault<Z.ZodNumber>;
 }, Z.core.$loose>;
 declare const payloadSchema: Z.ZodRecord<Z.ZodString, Z.ZodAny>;
 declare const localizationParamsSchema: Z.ZodObject<{
-    sourceLocale: Z.ZodUnion<readonly [Z.ZodString, Z.ZodNull]>;
-    targetLocale: Z.ZodString;
+    sourceLocale: Z.ZodUnion<readonly [Z.ZodPipe<Z.ZodString, Z.ZodTransform<string, string>>, Z.ZodNull]>;
+    targetLocale: Z.ZodPipe<Z.ZodString, Z.ZodTransform<string, string>>;
     fast: Z.ZodOptional<Z.ZodBoolean>;
-    reference: Z.ZodOptional<Z.ZodRecord<Z.ZodString, Z.ZodRecord<Z.ZodString, Z.ZodAny>>>;
+    reference: Z.ZodOptional<Z.ZodRecord<Z.ZodPipe<Z.ZodString, Z.ZodTransform<string, string>>, Z.ZodRecord<Z.ZodString, Z.ZodAny>>>;
     hints: Z.ZodOptional<Z.ZodRecord<Z.ZodString, Z.ZodArray<Z.ZodString>>>;
     filePath: Z.ZodOptional<Z.ZodString>;
     triggerType: Z.ZodOptional<Z.ZodEnum<{
@@ -32,6 +34,28 @@ declare class LingoDotDevEngine {
     private get headers();
     private static extractErrorMessage;
     private static throwOnHttpError;
+    /**
+     * Sleep for `ms` milliseconds, rejecting early if the signal is aborted.
+     */
+    private static sleep;
+    /**
+     * Exponential backoff with full jitter: a random delay in
+     * `[0, retryDelayMs * 2 ** attempt]`. Jitter spreads out retries from many
+     * clients so a recovering server is not hit by a synchronized wave.
+     */
+    private backoffDelay;
+    /**
+     * Perform a fetch, retrying on transient failures (5xx responses and
+     * network errors) with exponential backoff. The retry decision is made on
+     * the HTTP status code (>= 500), so non-retryable responses (e.g. 4xx) are
+     * returned immediately for the caller to handle. Aborted requests are never
+     * retried.
+     * @param url - The request URL
+     * @param init - Fetch init options (should include the AbortSignal)
+     * @param signal - Optional AbortSignal used to short-circuit retries
+     * @returns The fetch Response (which may still be a non-retryable error)
+     */
+    private fetchWithRetry;
     /**
      * Create a new LingoDotDevEngine instance
      * @param config - Configuration options for the Engine

package/build/index.mjs

@@ -1,6 +1,9 @@
 // src/index.ts
 import Z from "zod";
-import { localeCodeSchema } from "@lingo.dev/_spec";
+import {
+  localeCodeSchema,
+  normalizeLocale
+} from "@lingo.dev/_spec";
 import { createId } from "@paralleldrive/cuid2";
 
 // src/utils/observability.ts
@@ -111,14 +114,21 @@ var engineParamsSchema = Z.object({
   apiUrl: Z.string().url().default("https://api.lingo.dev"),
   batchSize: Z.number().int().gt(0).lte(250).default(25),
   idealBatchItemSize: Z.number().int().gt(0).lte(2500).default(250),
-  engineId: Z.string().optional()
+  engineId: Z.string().optional(),
+  // Number of times a localization request is retried after a transient
+  // failure (5xx response or network error). `0` disables retries.
+  maxRetries: Z.number().int().gte(0).default(3),
+  // Base delay (ms) for the exponential backoff between retries. The actual
+  // wait grows as `retryDelayMs * 2 ** attempt` plus a small random jitter.
+  retryDelayMs: Z.number().int().gte(0).default(500)
 }).passthrough();
+var normalizedLocaleCodeSchema = localeCodeSchema.transform(normalizeLocale);
 var payloadSchema = Z.record(Z.string(), Z.any());
-var referenceSchema = Z.record(localeCodeSchema, payloadSchema);
+var referenceSchema = Z.record(normalizedLocaleCodeSchema, payloadSchema);
 var hintsSchema = Z.record(Z.string(), Z.array(Z.string()));
 var localizationParamsSchema = Z.object({
-  sourceLocale: Z.union([localeCodeSchema, Z.null()]),
-  targetLocale: localeCodeSchema,
+  sourceLocale: Z.union([normalizedLocaleCodeSchema, Z.null()]),
+  targetLocale: normalizedLocaleCodeSchema,
   fast: Z.boolean().optional(),
   reference: referenceSchema.optional(),
   hints: hintsSchema.optional(),
@@ -162,6 +172,74 @@ var LingoDotDevEngine = class _LingoDotDevEngine {
     }
     throw new Error(context ? `${context}: ${msg}` : msg);
   }
+  /**
+   * Sleep for `ms` milliseconds, rejecting early if the signal is aborted.
+   */
+  static sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(new Error("Operation was aborted"));
+        return;
+      }
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(new Error("Operation was aborted"));
+      };
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      }, ms);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+  /**
+   * Exponential backoff with full jitter: a random delay in
+   * `[0, retryDelayMs * 2 ** attempt]`. Jitter spreads out retries from many
+   * clients so a recovering server is not hit by a synchronized wave.
+   */
+  backoffDelay(attempt) {
+    const ceiling = this.config.retryDelayMs * 2 ** attempt;
+    return Math.round(Math.random() * ceiling);
+  }
+  /**
+   * Perform a fetch, retrying on transient failures (5xx responses and
+   * network errors) with exponential backoff. The retry decision is made on
+   * the HTTP status code (>= 500), so non-retryable responses (e.g. 4xx) are
+   * returned immediately for the caller to handle. Aborted requests are never
+   * retried.
+   * @param url - The request URL
+   * @param init - Fetch init options (should include the AbortSignal)
+   * @param signal - Optional AbortSignal used to short-circuit retries
+   * @returns The fetch Response (which may still be a non-retryable error)
+   */
+  async fetchWithRetry(url, init, signal) {
+    const { maxRetries } = this.config;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      if (signal?.aborted) {
+        throw new Error("Operation was aborted");
+      }
+      try {
+        const res = await fetch(url, init);
+        const isServerError = res.status >= 500 && res.status < 600;
+        if (isServerError && attempt < maxRetries) {
+          await res.body?.cancel();
+          await _LingoDotDevEngine.sleep(this.backoffDelay(attempt), signal);
+          continue;
+        }
+        return res;
+      } catch (error) {
+        if (signal?.aborted) {
+          throw error;
+        }
+        if (attempt < maxRetries) {
+          await _LingoDotDevEngine.sleep(this.backoffDelay(attempt), signal);
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new Error("Localization request failed after exhausting retries");
+  }
   /**
    * Create a new LingoDotDevEngine instance
    * @param config - Configuration options for the Engine
@@ -191,7 +269,7 @@ var LingoDotDevEngine = class _LingoDotDevEngine {
       const processedPayloadChunk = await this.localizeChunk(
         finalParams.sourceLocale,
         finalParams.targetLocale,
-        { data: chunk, reference: params.reference, hints: params.hints },
+        { data: chunk, reference: finalParams.reference, hints: params.hints },
         params.fast || false,
         params.filePath,
         params.triggerType,
@@ -229,12 +307,16 @@ var LingoDotDevEngine = class _LingoDotDevEngine {
       metadata: filePath ? { filePath } : void 0,
       ...this.config.engineId && { engineId: this.config.engineId }
     };
-    const res = await fetch(url, {
-      method: "POST",
-      headers: this.headers,
-      body: JSON.stringify(body, null, 2),
+    const res = await this.fetchWithRetry(
+      url,
+      {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify(body, null, 2),
+        signal
+      },
       signal
-    });
+    );
     await _LingoDotDevEngine.throwOnHttpError(res);
     const jsonResponse = await res.json();
     if (!jsonResponse.data && jsonResponse.error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingo.dev/_sdk",
-  "version": "0.16.3",
+  "version": "0.16.5",
   "description": "Lingo.dev JS SDK",
   "private": false,
   "repository": {