class AnalyticsTracker {
  // ========================
  //   Globals & Constants
  // ========================
  static globalState = {
    isSearchListenerAdded: false,
  };

  static API_ENDPOINTS = {
    PRO: "api.deepl.com",
    FREE: "api-free.deepl.com"
  }

  static PAGE_ID_DEVELOPERS_WEBSITE_DOCUMENTATION = 4001;
  static PAGE_ID_DEVELOPERS_WEBSITE_API_REFERENCE = 4002;

  static EVENT_ID_PAGEVIEW = 1;
  static EVENT_ID_NETWORK_REQUEST = 5000;
  static EVENT_ID_SEARCH_INPUT = 5001; // TODO change this after DAP update

  static isProdStage = window.location.hostname === "developers.deepl.com";
  static statisticsUrl = this.isProdStage ? 
    "https://s.deepl.com/web/statistics"
    : "https://s.deepl.dev/web/statistics"

  // ========================
  //   Cookie Helper Inner Class
  // ========================
  static CookieHelper = class {
    static DAP_UID_KEY = 'dapUid';
    static DAP_SID_KEY = 'dapSid';
    
    static YEAR_IN_MINUTES = 60 * 24 * 30 * 12;
    static SID_TTL_MINUTES = 30;

    static getCookieItem(cookieName) {
      if (typeof window === 'undefined') {
        throw new Error('Error occurs when you are going to use a browser-specific code on server-side or other way around. Please check your code logic.');
      }
      const cookies = document.cookie.split('; ') || [];
      const cookie = cookies.find(c => c.startsWith(`${cookieName}=`)) || '';
      const value = cookie.split('=').at(1);
      return value ? decodeURIComponent(value) : value;
    }

    static setCookieItem(cookieName, cookieValue, expiresInMinutes = 0) {
      if (typeof window === 'undefined') {
        throw new Error('Error occurs when you are going to use a browser-specific code on server-side or other way around. Please check your code logic.');
      }
      const cookieValueToStore = (
        typeof cookieValue === 'string' || typeof cookieValue === 'number'
          ? cookieValue
          : JSON.stringify(cookieValue)
      );
      let expireString = '';
      if (expiresInMinutes) {
        const date = new Date();
        const expiresInMilliseconds = expiresInMinutes * 60 * 1000;
        date.setTime(date.getTime() + expiresInMilliseconds);
        expireString = `; expires=${date.toUTCString()}`;
      }
      const domain = AnalyticsTracker.isProdStage ? '.deepl.com' : window.location.hostname;
      const domainString = `; domain=${domain}`;
      const secure = '; secure';
      document.cookie = `${cookieName}=${encodeURIComponent(cookieValueToStore)}${domainString}; path=/${expireString}; samesite=lax${secure}`;
    }

    static mkUUID() {
      if (typeof window === 'undefined') {
        return '';
      }
      if (!Object.prototype.hasOwnProperty.call(window, 'crypto')) {
        return '';
      }
      if (typeof window.crypto.randomUUID === 'function') {
        return window.crypto.randomUUID();
      }
      return [1e7, -1e3, -4e3, -8e3, -1e11].join('').replace(/[018]/g, c =>
        (parseInt(c, 10) ^ (window.crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> (parseInt(c, 10) / 4)))).toString(16));
    }

    static getUid() {
      let uid = this.getCookieItem(this.DAP_UID_KEY);
      if (uid === undefined) {
        this.setCookieItem(
          this.DAP_UID_KEY,
          this.mkUUID(),
          this.YEAR_IN_MINUTES
        );
      }
      uid = this.getCookieItem(this.DAP_UID_KEY);
      return uid;
    }

    static getSid() {
      let sidCookie = this.getCookieItem(this.DAP_SID_KEY);
      let sidObj;
      if (sidCookie) {
        try {
          sidObj = JSON.parse(sidCookie);
        } catch {
          sidObj = null;
        }
      }
      const now = Date.now();
      if (sidObj && sidObj.sid && sidObj.lastUpdate) {
        // SID exists already
        if (now - sidObj.lastUpdate > this.SID_TTL_MINUTES * 60 * 1000) {
          sidObj = {
            sid: this.mkUUID(),
            lastUpdate: now
          };
        } else {
          sidObj = {
            ...sidObj,
            lastUpdate: now
          };
        }
      } else {
        // SID does not exist
        sidObj = {
          sid: this.mkUUID(),
          lastUpdate: now
        };
      }
      this.setCookieItem(this.DAP_SID_KEY, JSON.stringify(sidObj), this.SID_TTL_MINUTES);
      return sidObj.sid;
    }
  };

  // ========================
  //   Request Helper Inner Class
  // ========================
  static RequestHelper = class {
    static async baseRequest(url, getPayload) {
      const payload = getPayload();
      try {
        const response = await fetch(
          url,
          {
            headers: {
              "content-type": "application/json",
            },
            body: JSON.stringify(payload),
            method: "POST",
          }
        );
        const data = await response.json();
        // console.log('Fetched data: ', data);
        return data;
      } catch (error) {
        console.error('Fetch error: ', error);
      }
    }

    static getPageId() {
      const pathname = window.location.pathname;
      const secondSlash = pathname.indexOf("/", 1);
      const firstSubpath = secondSlash !== -1 ? pathname.substring(0, secondSlash) : pathname;
      switch (firstSubpath) {
        case "/docs":
          return AnalyticsTracker.PAGE_ID_DEVELOPERS_WEBSITE_DOCUMENTATION;
        case "/api-reference":
          return AnalyticsTracker.PAGE_ID_DEVELOPERS_WEBSITE_API_REFERENCE;
        default:
          return 0;
      }
    }

    static requestToDAP(eventId, extraFields) {
      // console.log(`[${eventId}]: ${JSON.stringify(extraFields)}`); 
      
      this.baseRequest(
        AnalyticsTracker.statisticsUrl,
        () => ({
          instanceId: AnalyticsTracker.CookieHelper.getUid(),
          sessionId: AnalyticsTracker.CookieHelper.getSid(),
          eventId: eventId,
          pageId: this.getPageId(),
          userAgent: navigator.userAgent,
          interfaceLanguage: navigator.language,
          screenInfo: {
            widthCssPixel: window.screen.width,
            heightCssPixel: window.screen.height,
            viewportWidthCssPixel: window.innerWidth,
            viewportHeightCssPixel: window.innerHeight,
            devicePixelRatio: window.devicePixelRatio
          },
          url: `${window.location.origin}${window.location.pathname}${window.location.search}`,
          ...extraFields
        })
      );
    }
  };

  // ========================
  //   Track Page Navigation Inner Class
  // ========================
  static PageNavigationTracker = class {
    static navigationState = {
      lastTrackedUrl: null
    }

    static sendPageview() {
      AnalyticsTracker.RequestHelper.requestToDAP(
        AnalyticsTracker.EVENT_ID_PAGEVIEW, 
        {
          pageviewData: {
            referrer: document.referrer,
            pageVariant: 0,
          }
        }
      );
    }

    static sendPageviewDeduped() {
      const currentUrl = window.location.href;
      if (currentUrl === this.navigationState.lastTrackedUrl) return; // Skip duplicate
      this.navigationState.lastTrackedUrl = currentUrl;
      this.sendPageview(); 
    }

    static setupNavigationTrackers() {
      const _pushState = history.pushState;
      const _replaceState = history.replaceState;

      history.pushState = function (...args) {
        _pushState.apply(this, args);
        AnalyticsTracker.PageNavigationTracker.sendPageviewDeduped();
      };

      history.replaceState = function (...args) {
        _replaceState.apply(this, args);
        AnalyticsTracker.PageNavigationTracker.sendPageviewDeduped();
      };

      window.addEventListener('popstate', () => {
        AnalyticsTracker.PageNavigationTracker.sendPageviewDeduped();
      });

      window.addEventListener('hashchange', () => {
        AnalyticsTracker.PageNavigationTracker.sendPageviewDeduped();
      });

      this.sendPageviewDeduped();
    }
  };

  // ========================
  //   Network Request Tracking Inner Class
  // ========================
  static NetworkRequestTracker = class {
    static sendOutgoingNetworkResponse(statusCode, apiUrl) {
      AnalyticsTracker.RequestHelper.requestToDAP(
        AnalyticsTracker.EVENT_ID_NETWORK_REQUEST, 
        {
          developersWebsiteNetworkData: {
            statusCode,
            apiUrl 
          }
        }
      );
    }

    static setupNetworkRequestTracking() {
      const originalOpen = XMLHttpRequest.prototype.open;
      const originalSend = XMLHttpRequest.prototype.send;

      XMLHttpRequest.prototype.open = function(method, url) {
        const xhr = this;
        xhr._recordedUrl = url;
        return originalOpen.apply(xhr, arguments);
      };

      XMLHttpRequest.prototype.send = function(body) {
        // Note: we cannot log the url, request body, or response body because of sensitive info
        const xhr = this;
        const originalOnReadyStateChange = xhr.onreadystatechange;
        xhr.onreadystatechange = function() {
          if (xhr.readyState === 4) { // DONE
            
            const urlObj = new URL(xhr._recordedUrl)
            if (
              urlObj.hostname === AnalyticsTracker.API_ENDPOINTS.PRO ||
              urlObj.hostname === AnalyticsTracker.API_ENDPOINTS.FREE
            ) {
              // Prune out any custom query params which could be input data
              const prunedUrl = `${urlObj.origin}${urlObj.pathname}`

              AnalyticsTracker.NetworkRequestTracker.sendOutgoingNetworkResponse(
                xhr.status,
                prunedUrl
              );
            }
            else {
              // do nothing for other requests
            }
          }
          if (originalOnReadyStateChange) {
            originalOnReadyStateChange.apply(xhr, arguments);
          }
        };
        return originalSend.apply(xhr, arguments);
      };
    }
  };

  // ========================
  //   Search Input Tracking Inner Class
  // ========================
  static SearchInputTracker = class {
    static InputClassification = {
      Partial: 'Partial',
      Submitted: 'Submitted', // Not implemented yet
      AiAssistant: 'AiAssistant'
    };

    static filteredHostnames = ['leaves.mintlify.com'];

    static sendSearchInput(searchInputText, classification) {
      AnalyticsTracker.RequestHelper.requestToDAP(
        AnalyticsTracker.EVENT_ID_SEARCH_INPUT, 
        {
          searchInputText,
          classification
        }
      );
    }

    static addSearchInputListener() {
      const searchInput = document.getElementById('search-input');
      if (!AnalyticsTracker.globalState.isSearchListenerAdded && searchInput) {
        searchInput.addEventListener('input', (event) => {
          const inputText = event.target.value;
          this.sendSearchInput(inputText, this.InputClassification.Partial);
        });
        AnalyticsTracker.globalState.isSearchListenerAdded = true;
      }
    }

    static removeSearchInputListener() {
      const searchInput = document.getElementById('search-input');
      if (AnalyticsTracker.globalState.isSearchListenerAdded && !searchInput) {
        AnalyticsTracker.globalState.isSearchListenerAdded = false;
      }
    }

    static setupSearchInputTracking() {
      // As the user is typing
      const observer = new MutationObserver((mutations) => {
        mutations.forEach((mutation) => {
          if (mutation.addedNodes.length) {
            this.addSearchInputListener();
          }
          if (mutation.removedNodes.length) {
            this.removeSearchInputListener();
          }
        });
      });
      observer.observe(document.body, { childList: true, subtree: true });
      this.addSearchInputListener();

      // When a user submits to the AI Assistant
      const originalFetch = window.fetch;
      window.fetch = async (...args) => {
        try {
          const url = typeof args[0] === 'string' ? args[0] : args[0].url;
          const requestHostname = new URL(url).hostname;
          if (this.filteredHostnames.includes(requestHostname)) {
            this.sendSearchInput(args[1].body, this.InputClassification.AiAssistant);
          }
          return originalFetch(...args);;
        } catch (error) {
          return originalFetch(...args);
        }
      };
    }
  };

  // ========================
  //   Initialization
  // ========================
  static init() {
    this.PageNavigationTracker.setupNavigationTrackers();
    this.NetworkRequestTracker.setupNetworkRequestTracking();
    // this.SearchInputTracker.setupSearchInputTracking(); // Disable this for now
  }
}

// Initialize on page load
AnalyticsTracker.init();


Download translated document

auth header

The document is provided as a download. There is no other data included in the response besides the document data. The content type used in the response corresponds to the document type.

Bad request. Please check error message and your parameters.

Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header.

Trying to download a document using a non-existing document ID or the wrong document key will result in a 404 error. As stated above, documents can only be downloaded once before they are deleted from the server and their document ID is invalidated.

Too many requests. Please wait and resend your request.

Quota exceeded. The character limit has been reached.

A 503 result will be returned if the user tries to download a translated document that is currently being processed and is not yet ready for download.
Please make sure to check that the document status is 'done' before trying to send a download request.

Resource currently unavailable. Try again later.

Download Translated Document

DeepL Documentation

Welcome to the developer home of DeepL API.

Introduction

About

Learn where to find your authentication key and how to access the DeepL API.

Access and authentication

A guide to creating API keys, getting API key-level usage, and setting API key-level limits.

Managing API keys

Make your first API requests to translate and improve text with the DeepL API.

Your first API request

Use our official Postman collection to get familiar with and test the DeepL API.

Test your API requests with Postman

The DeepL API supports the following languages. We will update this list as we introduce new languages.

Languages supported

Here's what we recommend reviewing to get your DeepL API application ready for production.

Pre-production checklist

Learn more about alpha and beta features in the DeepL API and how to best make use of them.

Alpha and beta features

Error handling

CORS requests

Translation context

Language detection

Subscription-level cost control

Learn how to translate XML content with the DeepL API.

XML handling

Learn how to work with structured XML content with the DeepL API.

Structured XML content

Learn how to customize XML outline detection with the DeepL API.

Customized XML outline detection

Learn how to translate HTML content with the DeepL API.

HTML handling

Brief summaries of recent DeepL API releases, such as support for new languages and document formats, new API parameters, and more.

Release notes

Here's what API users can expect when DeepL adds translation support for a new language or language variant.

API Reference

Download translated document

Authorizations

Path Parameters

Body

Response