@lingo.dev/_sdk 0.14.1 → 0.15.0

package/build/index.cjs

@@ -2,6 +2,97 @@
 var _zod = require('zod'); var _zod2 = _interopRequireDefault(_zod);
 var __spec = require('@lingo.dev/_spec');
 var _cuid2 = require('@paralleldrive/cuid2');
+
+// src/utils/observability.ts
+var _crypto = require('crypto');
+
+// src/utils/tracking-events.ts
+var TRACKING_EVENTS = {
+  LOCALIZE_START: "sdk.localize.start",
+  LOCALIZE_SUCCESS: "sdk.localize.success",
+  LOCALIZE_ERROR: "sdk.localize.error",
+  RECOGNIZE_START: "sdk.recognize.start",
+  RECOGNIZE_SUCCESS: "sdk.recognize.success",
+  RECOGNIZE_ERROR: "sdk.recognize.error"
+};
+var TRACKING_VERSION = "1.0";
+var SDK_PACKAGE = "@lingo.dev/_sdk";
+
+// src/utils/observability.ts
+var POSTHOG_API_KEY = "phc_eR0iSoQufBxNY36k0f0T15UvHJdTfHlh8rJcxsfhfXk";
+var POSTHOG_HOST = "https://eu.i.posthog.com";
+var identityCache = /* @__PURE__ */ new Map();
+function trackEvent(apiKey, apiUrl, event, properties) {
+  if (process.env.DO_NOT_TRACK === "1") {
+    return;
+  }
+  resolveIdentityAndCapture(apiKey, apiUrl, event, properties).catch(
+    (error) => {
+      if (process.env.DEBUG === "true") {
+        console.error("[Tracking] Error:", error);
+      }
+    }
+  );
+}
+async function resolveIdentityAndCapture(apiKey, apiUrl, event, properties) {
+  const identityInfo = await getDistinctId(apiKey, apiUrl);
+  if (process.env.DEBUG === "true") {
+    console.log(
+      `[Tracking] Event: ${event}, ID: ${identityInfo.distinct_id}, Source: ${identityInfo.distinct_id_source}`
+    );
+  }
+  const { PostHog } = await Promise.resolve().then(() => _interopRequireWildcard(require("posthog-node")));
+  const posthog = new PostHog(POSTHOG_API_KEY, {
+    host: POSTHOG_HOST,
+    flushAt: 1,
+    flushInterval: 0
+  });
+  await posthog.capture({
+    distinctId: identityInfo.distinct_id,
+    event,
+    properties: {
+      ...properties,
+      tracking_version: TRACKING_VERSION,
+      sdk_package: SDK_PACKAGE,
+      distinct_id_source: identityInfo.distinct_id_source
+    }
+  });
+  await posthog.shutdown();
+}
+async function getDistinctId(apiKey, apiUrl) {
+  const cached = identityCache.get(apiKey);
+  if (cached) return cached;
+  try {
+    const res = await fetch(`${apiUrl}/whoami`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json"
+      }
+    });
+    if (res.ok) {
+      const payload = await res.json();
+      if (_optionalChain([payload, 'optionalAccess', _ => _.email])) {
+        const identity2 = {
+          distinct_id: payload.email,
+          distinct_id_source: "email"
+        };
+        identityCache.set(apiKey, identity2);
+        return identity2;
+      }
+    }
+  } catch (e) {
+  }
+  const hash = _crypto.createHash.call(void 0, "sha256").update(apiKey).digest("hex").slice(0, 16);
+  const identity = {
+    distinct_id: `apikey-${hash}`,
+    distinct_id_source: "api_key_hash"
+  };
+  identityCache.set(apiKey, identity);
+  return identity;
+}
+
+// src/index.ts
 var engineParamsSchema = _zod2.default.object({
   apiKey: _zod2.default.string(),
   apiUrl: _zod2.default.string().url().default("https://engine.lingo.dev"),
@@ -171,7 +262,43 @@ var LingoDotDevEngine = class {
    * @returns A new object with the same structure but localized string values
    */
   async localizeObject(obj, params, progressCallback, signal) {
-    return this._localizeRaw(obj, params, progressCallback, signal);
+    const trackProps = {
+      method: "localizeObject",
+      sourceLocale: params.sourceLocale,
+      targetLocale: params.targetLocale
+    };
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.LOCALIZE_START,
+      trackProps
+    );
+    try {
+      const result = await this._localizeRaw(
+        obj,
+        params,
+        progressCallback,
+        signal
+      );
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_SUCCESS,
+        trackProps
+      );
+      return result;
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
+        }
+      );
+      throw error;
+    }
   }
   /**
    * Localize a single text string
@@ -185,13 +312,44 @@ var LingoDotDevEngine = class {
    * @returns The localized text string
    */
   async localizeText(text, params, progressCallback, signal) {
-    const response = await this._localizeRaw(
-      { text },
-      params,
-      progressCallback,
-      signal
+    const trackProps = {
+      method: "localizeText",
+      sourceLocale: params.sourceLocale,
+      targetLocale: params.targetLocale
+    };
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.LOCALIZE_START,
+      trackProps
     );
-    return response.text || "";
+    try {
+      const response = await this._localizeRaw(
+        { text },
+        params,
+        progressCallback,
+        signal
+      );
+      const result = response.text || "";
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_SUCCESS,
+        trackProps
+      );
+      return result;
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
+        }
+      );
+      throw error;
+    }
   }
   /**
    * Localize a text string to multiple target locales
@@ -230,15 +388,45 @@ var LingoDotDevEngine = class {
    * @returns An array of localized strings in the same order
    */
   async localizeStringArray(strings, params) {
-    const mapped = strings.reduce(
-      (acc, str, i) => {
-        acc[`item_${i}`] = str;
-        return acc;
-      },
-      {}
+    const trackProps = {
+      method: "localizeStringArray",
+      sourceLocale: params.sourceLocale,
+      targetLocale: params.targetLocale
+    };
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.LOCALIZE_START,
+      trackProps
     );
-    const result = await this.localizeObject(mapped, params);
-    return Object.values(result);
+    try {
+      const mapped = strings.reduce(
+        (acc, str, i) => {
+          acc[`item_${i}`] = str;
+          return acc;
+        },
+        {}
+      );
+      const result = await this._localizeRaw(mapped, params);
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_SUCCESS,
+        trackProps
+      );
+      return Object.values(result);
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
+        }
+      );
+      throw error;
+    }
   }
   /**
    * Localize a chat sequence while preserving speaker names
@@ -252,16 +440,47 @@ var LingoDotDevEngine = class {
    * @returns Array of localized chat messages with preserved structure
    */
   async localizeChat(chat, params, progressCallback, signal) {
-    const localized = await this._localizeRaw(
-      { chat },
-      params,
-      progressCallback,
-      signal
+    const trackProps = {
+      method: "localizeChat",
+      sourceLocale: params.sourceLocale,
+      targetLocale: params.targetLocale
+    };
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.LOCALIZE_START,
+      trackProps
     );
-    return Object.entries(localized).map(([key, value]) => ({
-      name: chat[parseInt(key.split("_")[1])].name,
-      text: value
-    }));
+    try {
+      const localized = await this._localizeRaw(
+        { chat },
+        params,
+        progressCallback,
+        signal
+      );
+      const result = Object.entries(localized).map(([key, value]) => ({
+        name: chat[parseInt(key.split("_")[1])].name,
+        text: value
+      }));
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_SUCCESS,
+        trackProps
+      );
+      return result;
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
+        }
+      );
+      throw error;
+    }
   }
   /**
    * Localize an HTML document while preserving structure and formatting
@@ -276,105 +495,136 @@ var LingoDotDevEngine = class {
    * @returns The localized HTML document as a string, with updated lang attribute
    */
   async localizeHtml(html, params, progressCallback, signal) {
-    const jsdomPackage = await Promise.resolve().then(() => _interopRequireWildcard(require("jsdom")));
-    const { JSDOM } = jsdomPackage;
-    const dom = new JSDOM(html);
-    const document = dom.window.document;
-    const LOCALIZABLE_ATTRIBUTES = {
-      meta: ["content"],
-      img: ["alt"],
-      input: ["placeholder"],
-      a: ["title"]
+    const trackProps = {
+      method: "localizeHtml",
+      sourceLocale: params.sourceLocale,
+      targetLocale: params.targetLocale
     };
-    const UNLOCALIZABLE_TAGS = ["script", "style"];
-    const extractedContent = {};
-    const getPath = (node, attribute) => {
-      const indices = [];
-      let current = node;
-      let rootParent = "";
-      while (current) {
-        const parent = current.parentElement;
-        if (!parent) break;
-        if (parent === document.documentElement) {
-          rootParent = current.nodeName.toLowerCase();
-          break;
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.LOCALIZE_START,
+      trackProps
+    );
+    try {
+      const jsdomPackage = await Promise.resolve().then(() => _interopRequireWildcard(require("jsdom")));
+      const { JSDOM } = jsdomPackage;
+      const dom = new JSDOM(html);
+      const document = dom.window.document;
+      const LOCALIZABLE_ATTRIBUTES = {
+        meta: ["content"],
+        img: ["alt"],
+        input: ["placeholder"],
+        a: ["title"]
+      };
+      const UNLOCALIZABLE_TAGS = ["script", "style"];
+      const extractedContent = {};
+      const getPath = (node, attribute) => {
+        const indices = [];
+        let current = node;
+        let rootParent = "";
+        while (current) {
+          const parent = current.parentElement;
+          if (!parent) break;
+          if (parent === document.documentElement) {
+            rootParent = current.nodeName.toLowerCase();
+            break;
+          }
+          const siblings = Array.from(parent.childNodes).filter(
+            (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _2 => _2.textContent, 'optionalAccess', _3 => _3.trim, 'call', _4 => _4()])
+          );
+          const index = siblings.indexOf(current);
+          if (index !== -1) {
+            indices.unshift(index);
+          }
+          current = parent;
         }
-        const siblings = Array.from(parent.childNodes).filter(
-          (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _ => _.textContent, 'optionalAccess', _2 => _2.trim, 'call', _3 => _3()])
-        );
-        const index = siblings.indexOf(current);
-        if (index !== -1) {
-          indices.unshift(index);
+        const basePath = rootParent ? `${rootParent}/${indices.join("/")}` : indices.join("/");
+        return attribute ? `${basePath}#${attribute}` : basePath;
+      };
+      const processNode = (node) => {
+        let parent = node.parentElement;
+        while (parent) {
+          if (UNLOCALIZABLE_TAGS.includes(parent.tagName.toLowerCase())) {
+            return;
+          }
+          parent = parent.parentElement;
         }
-        current = parent;
-      }
-      const basePath = rootParent ? `${rootParent}/${indices.join("/")}` : indices.join("/");
-      return attribute ? `${basePath}#${attribute}` : basePath;
-    };
-    const processNode = (node) => {
-      let parent = node.parentElement;
-      while (parent) {
-        if (UNLOCALIZABLE_TAGS.includes(parent.tagName.toLowerCase())) {
-          return;
+        if (node.nodeType === 3) {
+          const text = _optionalChain([node, 'access', _5 => _5.textContent, 'optionalAccess', _6 => _6.trim, 'call', _7 => _7()]) || "";
+          if (text) {
+            extractedContent[getPath(node)] = text;
+          }
+        } else if (node.nodeType === 1) {
+          const element = node;
+          const tagName = element.tagName.toLowerCase();
+          const attributes = LOCALIZABLE_ATTRIBUTES[tagName] || [];
+          attributes.forEach((attr) => {
+            const value = element.getAttribute(attr);
+            if (value) {
+              extractedContent[getPath(element, attr)] = value;
+            }
+          });
+          Array.from(element.childNodes).filter(
+            (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _8 => _8.textContent, 'optionalAccess', _9 => _9.trim, 'call', _10 => _10()])
+          ).forEach(processNode);
         }
-        parent = parent.parentElement;
-      }
-      if (node.nodeType === 3) {
-        const text = _optionalChain([node, 'access', _4 => _4.textContent, 'optionalAccess', _5 => _5.trim, 'call', _6 => _6()]) || "";
-        if (text) {
-          extractedContent[getPath(node)] = text;
+      };
+      Array.from(document.head.childNodes).filter(
+        (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _11 => _11.textContent, 'optionalAccess', _12 => _12.trim, 'call', _13 => _13()])
+      ).forEach(processNode);
+      Array.from(document.body.childNodes).filter(
+        (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _14 => _14.textContent, 'optionalAccess', _15 => _15.trim, 'call', _16 => _16()])
+      ).forEach(processNode);
+      const localizedContent = await this._localizeRaw(
+        extractedContent,
+        params,
+        progressCallback,
+        signal
+      );
+      document.documentElement.setAttribute("lang", params.targetLocale);
+      Object.entries(localizedContent).forEach(([path, value]) => {
+        const [nodePath, attribute] = path.split("#");
+        const [rootTag, ...indices] = nodePath.split("/");
+        let parent = rootTag === "head" ? document.head : document.body;
+        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', _17 => _17.textContent, 'optionalAccess', _18 => _18.trim, 'call', _19 => _19()])
+          );
+          current = siblings[parseInt(index)] || null;
+          if (_optionalChain([current, 'optionalAccess', _20 => _20.nodeType]) === 1) {
+            parent = current;
+          }
         }
-      } else if (node.nodeType === 1) {
-        const element = node;
-        const tagName = element.tagName.toLowerCase();
-        const attributes = LOCALIZABLE_ATTRIBUTES[tagName] || [];
-        attributes.forEach((attr) => {
-          const value = element.getAttribute(attr);
-          if (value) {
-            extractedContent[getPath(element, attr)] = value;
+        if (current) {
+          if (attribute) {
+            current.setAttribute(attribute, value);
+          } else {
+            current.textContent = value;
           }
-        });
-        Array.from(element.childNodes).filter(
-          (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _7 => _7.textContent, 'optionalAccess', _8 => _8.trim, 'call', _9 => _9()])
-        ).forEach(processNode);
-      }
-    };
-    Array.from(document.head.childNodes).filter(
-      (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _10 => _10.textContent, 'optionalAccess', _11 => _11.trim, 'call', _12 => _12()])
-    ).forEach(processNode);
-    Array.from(document.body.childNodes).filter(
-      (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _13 => _13.textContent, 'optionalAccess', _14 => _14.trim, 'call', _15 => _15()])
-    ).forEach(processNode);
-    const localizedContent = await this._localizeRaw(
-      extractedContent,
-      params,
-      progressCallback,
-      signal
-    );
-    document.documentElement.setAttribute("lang", params.targetLocale);
-    Object.entries(localizedContent).forEach(([path, value]) => {
-      const [nodePath, attribute] = path.split("#");
-      const [rootTag, ...indices] = nodePath.split("/");
-      let parent = rootTag === "head" ? document.head : document.body;
-      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', _16 => _16.textContent, 'optionalAccess', _17 => _17.trim, 'call', _18 => _18()])
-        );
-        current = siblings[parseInt(index)] || null;
-        if (_optionalChain([current, 'optionalAccess', _19 => _19.nodeType]) === 1) {
-          parent = current;
         }
-      }
-      if (current) {
-        if (attribute) {
-          current.setAttribute(attribute, value);
-        } else {
-          current.textContent = value;
+      });
+      const result = dom.serialize();
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_SUCCESS,
+        trackProps
+      );
+      return result;
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
         }
-      }
-    });
-    return dom.serialize();
+      );
+      throw error;
+    }
   }
   /**
    * Detect the language of a given text
@@ -383,25 +633,51 @@ var LingoDotDevEngine = class {
    * @returns Promise resolving to a locale code (e.g., 'en', 'es', 'fr')
    */
   async recognizeLocale(text, signal) {
-    const response = await fetch(`${this.config.apiUrl}/recognize`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json; charset=utf-8",
-        Authorization: `Bearer ${this.config.apiKey}`
-      },
-      body: JSON.stringify({ text }),
-      signal
-    });
-    if (!response.ok) {
-      if (response.status >= 500 && response.status < 600) {
-        throw new Error(
-          `Server error (${response.status}): ${response.statusText}. This may be due to temporary service issues.`
-        );
+    const trackProps = { method: "recognizeLocale" };
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.RECOGNIZE_START,
+      trackProps
+    );
+    try {
+      const response = await fetch(`${this.config.apiUrl}/recognize`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json; charset=utf-8",
+          Authorization: `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify({ text }),
+        signal
+      });
+      if (!response.ok) {
+        if (response.status >= 500 && response.status < 600) {
+          throw new Error(
+            `Server error (${response.status}): ${response.statusText}. This may be due to temporary service issues.`
+          );
+        }
+        throw new Error(`Error recognizing locale: ${response.statusText}`);
       }
-      throw new Error(`Error recognizing locale: ${response.statusText}`);
+      const jsonResponse = await response.json();
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.RECOGNIZE_SUCCESS,
+        trackProps
+      );
+      return jsonResponse.locale;
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.RECOGNIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
+        }
+      );
+      throw error;
     }
-    const jsonResponse = await response.json();
-    return jsonResponse.locale;
   }
   async whoami(signal) {
     try {
@@ -409,13 +685,13 @@ var LingoDotDevEngine = class {
         method: "POST",
         headers: {
           Authorization: `Bearer ${this.config.apiKey}`,
-          ContentType: "application/json"
+          "Content-Type": "application/json"
         },
         signal
       });
       if (res.ok) {
         const payload = await res.json();
-        if (!_optionalChain([payload, 'optionalAccess', _20 => _20.email])) {
+        if (!_optionalChain([payload, 'optionalAccess', _21 => _21.email])) {
           return null;
         }
         return {

package/build/index.mjs

@@ -2,6 +2,97 @@
 import Z from "zod";
 import { localeCodeSchema } from "@lingo.dev/_spec";
 import { createId } from "@paralleldrive/cuid2";
+
+// src/utils/observability.ts
+import { createHash } from "crypto";
+
+// src/utils/tracking-events.ts
+var TRACKING_EVENTS = {
+  LOCALIZE_START: "sdk.localize.start",
+  LOCALIZE_SUCCESS: "sdk.localize.success",
+  LOCALIZE_ERROR: "sdk.localize.error",
+  RECOGNIZE_START: "sdk.recognize.start",
+  RECOGNIZE_SUCCESS: "sdk.recognize.success",
+  RECOGNIZE_ERROR: "sdk.recognize.error"
+};
+var TRACKING_VERSION = "1.0";
+var SDK_PACKAGE = "@lingo.dev/_sdk";
+
+// src/utils/observability.ts
+var POSTHOG_API_KEY = "phc_eR0iSoQufBxNY36k0f0T15UvHJdTfHlh8rJcxsfhfXk";
+var POSTHOG_HOST = "https://eu.i.posthog.com";
+var identityCache = /* @__PURE__ */ new Map();
+function trackEvent(apiKey, apiUrl, event, properties) {
+  if (process.env.DO_NOT_TRACK === "1") {
+    return;
+  }
+  resolveIdentityAndCapture(apiKey, apiUrl, event, properties).catch(
+    (error) => {
+      if (process.env.DEBUG === "true") {
+        console.error("[Tracking] Error:", error);
+      }
+    }
+  );
+}
+async function resolveIdentityAndCapture(apiKey, apiUrl, event, properties) {
+  const identityInfo = await getDistinctId(apiKey, apiUrl);
+  if (process.env.DEBUG === "true") {
+    console.log(
+      `[Tracking] Event: ${event}, ID: ${identityInfo.distinct_id}, Source: ${identityInfo.distinct_id_source}`
+    );
+  }
+  const { PostHog } = await import("posthog-node");
+  const posthog = new PostHog(POSTHOG_API_KEY, {
+    host: POSTHOG_HOST,
+    flushAt: 1,
+    flushInterval: 0
+  });
+  await posthog.capture({
+    distinctId: identityInfo.distinct_id,
+    event,
+    properties: {
+      ...properties,
+      tracking_version: TRACKING_VERSION,
+      sdk_package: SDK_PACKAGE,
+      distinct_id_source: identityInfo.distinct_id_source
+    }
+  });
+  await posthog.shutdown();
+}
+async function getDistinctId(apiKey, apiUrl) {
+  const cached = identityCache.get(apiKey);
+  if (cached) return cached;
+  try {
+    const res = await fetch(`${apiUrl}/whoami`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json"
+      }
+    });
+    if (res.ok) {
+      const payload = await res.json();
+      if (payload?.email) {
+        const identity2 = {
+          distinct_id: payload.email,
+          distinct_id_source: "email"
+        };
+        identityCache.set(apiKey, identity2);
+        return identity2;
+      }
+    }
+  } catch {
+  }
+  const hash = createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
+  const identity = {
+    distinct_id: `apikey-${hash}`,
+    distinct_id_source: "api_key_hash"
+  };
+  identityCache.set(apiKey, identity);
+  return identity;
+}
+
+// src/index.ts
 var engineParamsSchema = Z.object({
   apiKey: Z.string(),
   apiUrl: Z.string().url().default("https://engine.lingo.dev"),
@@ -171,7 +262,43 @@ var LingoDotDevEngine = class {
    * @returns A new object with the same structure but localized string values
    */
   async localizeObject(obj, params, progressCallback, signal) {
-    return this._localizeRaw(obj, params, progressCallback, signal);
+    const trackProps = {
+      method: "localizeObject",
+      sourceLocale: params.sourceLocale,
+      targetLocale: params.targetLocale
+    };
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.LOCALIZE_START,
+      trackProps
+    );
+    try {
+      const result = await this._localizeRaw(
+        obj,
+        params,
+        progressCallback,
+        signal
+      );
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_SUCCESS,
+        trackProps
+      );
+      return result;
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
+        }
+      );
+      throw error;
+    }
   }
   /**
    * Localize a single text string
@@ -185,13 +312,44 @@ var LingoDotDevEngine = class {
    * @returns The localized text string
    */
   async localizeText(text, params, progressCallback, signal) {
-    const response = await this._localizeRaw(
-      { text },
-      params,
-      progressCallback,
-      signal
+    const trackProps = {
+      method: "localizeText",
+      sourceLocale: params.sourceLocale,
+      targetLocale: params.targetLocale
+    };
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.LOCALIZE_START,
+      trackProps
     );
-    return response.text || "";
+    try {
+      const response = await this._localizeRaw(
+        { text },
+        params,
+        progressCallback,
+        signal
+      );
+      const result = response.text || "";
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_SUCCESS,
+        trackProps
+      );
+      return result;
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
+        }
+      );
+      throw error;
+    }
   }
   /**
    * Localize a text string to multiple target locales
@@ -230,15 +388,45 @@ var LingoDotDevEngine = class {
    * @returns An array of localized strings in the same order
    */
   async localizeStringArray(strings, params) {
-    const mapped = strings.reduce(
-      (acc, str, i) => {
-        acc[`item_${i}`] = str;
-        return acc;
-      },
-      {}
+    const trackProps = {
+      method: "localizeStringArray",
+      sourceLocale: params.sourceLocale,
+      targetLocale: params.targetLocale
+    };
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.LOCALIZE_START,
+      trackProps
     );
-    const result = await this.localizeObject(mapped, params);
-    return Object.values(result);
+    try {
+      const mapped = strings.reduce(
+        (acc, str, i) => {
+          acc[`item_${i}`] = str;
+          return acc;
+        },
+        {}
+      );
+      const result = await this._localizeRaw(mapped, params);
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_SUCCESS,
+        trackProps
+      );
+      return Object.values(result);
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
+        }
+      );
+      throw error;
+    }
   }
   /**
    * Localize a chat sequence while preserving speaker names
@@ -252,16 +440,47 @@ var LingoDotDevEngine = class {
    * @returns Array of localized chat messages with preserved structure
    */
   async localizeChat(chat, params, progressCallback, signal) {
-    const localized = await this._localizeRaw(
-      { chat },
-      params,
-      progressCallback,
-      signal
+    const trackProps = {
+      method: "localizeChat",
+      sourceLocale: params.sourceLocale,
+      targetLocale: params.targetLocale
+    };
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.LOCALIZE_START,
+      trackProps
     );
-    return Object.entries(localized).map(([key, value]) => ({
-      name: chat[parseInt(key.split("_")[1])].name,
-      text: value
-    }));
+    try {
+      const localized = await this._localizeRaw(
+        { chat },
+        params,
+        progressCallback,
+        signal
+      );
+      const result = Object.entries(localized).map(([key, value]) => ({
+        name: chat[parseInt(key.split("_")[1])].name,
+        text: value
+      }));
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_SUCCESS,
+        trackProps
+      );
+      return result;
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
+        }
+      );
+      throw error;
+    }
   }
   /**
    * Localize an HTML document while preserving structure and formatting
@@ -276,105 +495,136 @@ var LingoDotDevEngine = class {
    * @returns The localized HTML document as a string, with updated lang attribute
    */
   async localizeHtml(html, params, progressCallback, signal) {
-    const jsdomPackage = await import("jsdom");
-    const { JSDOM } = jsdomPackage;
-    const dom = new JSDOM(html);
-    const document = dom.window.document;
-    const LOCALIZABLE_ATTRIBUTES = {
-      meta: ["content"],
-      img: ["alt"],
-      input: ["placeholder"],
-      a: ["title"]
+    const trackProps = {
+      method: "localizeHtml",
+      sourceLocale: params.sourceLocale,
+      targetLocale: params.targetLocale
     };
-    const UNLOCALIZABLE_TAGS = ["script", "style"];
-    const extractedContent = {};
-    const getPath = (node, attribute) => {
-      const indices = [];
-      let current = node;
-      let rootParent = "";
-      while (current) {
-        const parent = current.parentElement;
-        if (!parent) break;
-        if (parent === document.documentElement) {
-          rootParent = current.nodeName.toLowerCase();
-          break;
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.LOCALIZE_START,
+      trackProps
+    );
+    try {
+      const jsdomPackage = await import("jsdom");
+      const { JSDOM } = jsdomPackage;
+      const dom = new JSDOM(html);
+      const document = dom.window.document;
+      const LOCALIZABLE_ATTRIBUTES = {
+        meta: ["content"],
+        img: ["alt"],
+        input: ["placeholder"],
+        a: ["title"]
+      };
+      const UNLOCALIZABLE_TAGS = ["script", "style"];
+      const extractedContent = {};
+      const getPath = (node, attribute) => {
+        const indices = [];
+        let current = node;
+        let rootParent = "";
+        while (current) {
+          const parent = current.parentElement;
+          if (!parent) break;
+          if (parent === document.documentElement) {
+            rootParent = current.nodeName.toLowerCase();
+            break;
+          }
+          const siblings = Array.from(parent.childNodes).filter(
+            (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
+          );
+          const index = siblings.indexOf(current);
+          if (index !== -1) {
+            indices.unshift(index);
+          }
+          current = parent;
         }
-        const siblings = Array.from(parent.childNodes).filter(
-          (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
-        );
-        const index = siblings.indexOf(current);
-        if (index !== -1) {
-          indices.unshift(index);
+        const basePath = rootParent ? `${rootParent}/${indices.join("/")}` : indices.join("/");
+        return attribute ? `${basePath}#${attribute}` : basePath;
+      };
+      const processNode = (node) => {
+        let parent = node.parentElement;
+        while (parent) {
+          if (UNLOCALIZABLE_TAGS.includes(parent.tagName.toLowerCase())) {
+            return;
+          }
+          parent = parent.parentElement;
         }
-        current = parent;
-      }
-      const basePath = rootParent ? `${rootParent}/${indices.join("/")}` : indices.join("/");
-      return attribute ? `${basePath}#${attribute}` : basePath;
-    };
-    const processNode = (node) => {
-      let parent = node.parentElement;
-      while (parent) {
-        if (UNLOCALIZABLE_TAGS.includes(parent.tagName.toLowerCase())) {
-          return;
+        if (node.nodeType === 3) {
+          const text = node.textContent?.trim() || "";
+          if (text) {
+            extractedContent[getPath(node)] = text;
+          }
+        } else if (node.nodeType === 1) {
+          const element = node;
+          const tagName = element.tagName.toLowerCase();
+          const attributes = LOCALIZABLE_ATTRIBUTES[tagName] || [];
+          attributes.forEach((attr) => {
+            const value = element.getAttribute(attr);
+            if (value) {
+              extractedContent[getPath(element, attr)] = value;
+            }
+          });
+          Array.from(element.childNodes).filter(
+            (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
+          ).forEach(processNode);
         }
-        parent = parent.parentElement;
-      }
-      if (node.nodeType === 3) {
-        const text = node.textContent?.trim() || "";
-        if (text) {
-          extractedContent[getPath(node)] = text;
+      };
+      Array.from(document.head.childNodes).filter(
+        (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
+      ).forEach(processNode);
+      Array.from(document.body.childNodes).filter(
+        (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
+      ).forEach(processNode);
+      const localizedContent = await this._localizeRaw(
+        extractedContent,
+        params,
+        progressCallback,
+        signal
+      );
+      document.documentElement.setAttribute("lang", params.targetLocale);
+      Object.entries(localizedContent).forEach(([path, value]) => {
+        const [nodePath, attribute] = path.split("#");
+        const [rootTag, ...indices] = nodePath.split("/");
+        let parent = rootTag === "head" ? document.head : document.body;
+        let current = parent;
+        for (const index of indices) {
+          const siblings = Array.from(parent.childNodes).filter(
+            (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
+          );
+          current = siblings[parseInt(index)] || null;
+          if (current?.nodeType === 1) {
+            parent = current;
+          }
         }
-      } else if (node.nodeType === 1) {
-        const element = node;
-        const tagName = element.tagName.toLowerCase();
-        const attributes = LOCALIZABLE_ATTRIBUTES[tagName] || [];
-        attributes.forEach((attr) => {
-          const value = element.getAttribute(attr);
-          if (value) {
-            extractedContent[getPath(element, attr)] = value;
+        if (current) {
+          if (attribute) {
+            current.setAttribute(attribute, value);
+          } else {
+            current.textContent = value;
           }
-        });
-        Array.from(element.childNodes).filter(
-          (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
-        ).forEach(processNode);
-      }
-    };
-    Array.from(document.head.childNodes).filter(
-      (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
-    ).forEach(processNode);
-    Array.from(document.body.childNodes).filter(
-      (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
-    ).forEach(processNode);
-    const localizedContent = await this._localizeRaw(
-      extractedContent,
-      params,
-      progressCallback,
-      signal
-    );
-    document.documentElement.setAttribute("lang", params.targetLocale);
-    Object.entries(localizedContent).forEach(([path, value]) => {
-      const [nodePath, attribute] = path.split("#");
-      const [rootTag, ...indices] = nodePath.split("/");
-      let parent = rootTag === "head" ? document.head : document.body;
-      let current = parent;
-      for (const index of indices) {
-        const siblings = Array.from(parent.childNodes).filter(
-          (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
-        );
-        current = siblings[parseInt(index)] || null;
-        if (current?.nodeType === 1) {
-          parent = current;
         }
-      }
-      if (current) {
-        if (attribute) {
-          current.setAttribute(attribute, value);
-        } else {
-          current.textContent = value;
+      });
+      const result = dom.serialize();
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_SUCCESS,
+        trackProps
+      );
+      return result;
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.LOCALIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
         }
-      }
-    });
-    return dom.serialize();
+      );
+      throw error;
+    }
   }
   /**
    * Detect the language of a given text
@@ -383,25 +633,51 @@ var LingoDotDevEngine = class {
    * @returns Promise resolving to a locale code (e.g., 'en', 'es', 'fr')
    */
   async recognizeLocale(text, signal) {
-    const response = await fetch(`${this.config.apiUrl}/recognize`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json; charset=utf-8",
-        Authorization: `Bearer ${this.config.apiKey}`
-      },
-      body: JSON.stringify({ text }),
-      signal
-    });
-    if (!response.ok) {
-      if (response.status >= 500 && response.status < 600) {
-        throw new Error(
-          `Server error (${response.status}): ${response.statusText}. This may be due to temporary service issues.`
-        );
+    const trackProps = { method: "recognizeLocale" };
+    trackEvent(
+      this.config.apiKey,
+      this.config.apiUrl,
+      TRACKING_EVENTS.RECOGNIZE_START,
+      trackProps
+    );
+    try {
+      const response = await fetch(`${this.config.apiUrl}/recognize`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json; charset=utf-8",
+          Authorization: `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify({ text }),
+        signal
+      });
+      if (!response.ok) {
+        if (response.status >= 500 && response.status < 600) {
+          throw new Error(
+            `Server error (${response.status}): ${response.statusText}. This may be due to temporary service issues.`
+          );
+        }
+        throw new Error(`Error recognizing locale: ${response.statusText}`);
       }
-      throw new Error(`Error recognizing locale: ${response.statusText}`);
+      const jsonResponse = await response.json();
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.RECOGNIZE_SUCCESS,
+        trackProps
+      );
+      return jsonResponse.locale;
+    } catch (error) {
+      trackEvent(
+        this.config.apiKey,
+        this.config.apiUrl,
+        TRACKING_EVENTS.RECOGNIZE_ERROR,
+        {
+          ...trackProps,
+          errorMessage: error instanceof Error ? error.message : String(error)
+        }
+      );
+      throw error;
     }
-    const jsonResponse = await response.json();
-    return jsonResponse.locale;
   }
   async whoami(signal) {
     try {
@@ -409,7 +685,7 @@ var LingoDotDevEngine = class {
         method: "POST",
         headers: {
           Authorization: `Bearer ${this.config.apiKey}`,
-          ContentType: "application/json"
+          "Content-Type": "application/json"
         },
         signal
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingo.dev/_sdk",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Lingo.dev JS SDK",
   "private": false,
   "repository": {
@@ -26,8 +26,9 @@
   "dependencies": {
     "@paralleldrive/cuid2": "2.2.2",
     "jsdom": "25.0.1",
+    "posthog-node": "5.14.0",
     "zod": "4.1.12",
-    "@lingo.dev/_spec": "0.47.1"
+    "@lingo.dev/_spec": "0.48.0"
   },
   "devDependencies": {
     "@types/jsdom": "21.1.7",