tdk-api-wrapper 1.5.1 → 1.6.1

package/src/tdk.ts

@@ -1,1962 +0,0 @@
-import type {
-  WordInfo,
-  DailyContent,
-  SpellCheckResult,
-  StemResult,
-  WordOfTheDay,
-  DailyPick,
-  WordComparison,
-  WordAnalysis,
-  TDKRule,
-  KubbealtiEntry,
-  WiktionaryEntry,
-  ProofreadIssue,
-  ProofreadResult,
-  PatternSearchOptions,
-  AnagramOptions,
-  RhymeOptions,
-  TDKConfig,
-} from "./types";
-import { TDKValidationError, TDKNetworkError } from "./errors";
-import { getStemCandidates } from "./morphology";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-import * as https from "node:https";
-import * as tls from "node:tls";
-
-/**
- * Known frequent Turkish misspellings, erroneously joined compound words,
- * and words where vowel dropping is prohibited by TDK (Yazım Kılavuzu).
- */
-export const COMMON_MISSPELLINGS: Record<string, string> = {
-  // -şey ile biten ve ayrı yazılması zorunlu söz öbekleri
-  herşey: "her şey",
-  hersey: "her şey",
-  birşey: "bir şey",
-  birsey: "bir şey",
-  hiçbirşey: "hiçbir şey",
-  hicbirsey: "hiçbir şey",
-  çokşey: "çok şey",
-  coksey: "çok şey",
-  şeyler: "şeyler",
-  seyler: "şeyler",
-  herhangibirşey: "herhangi bir şey",
-  herhangibirsey: "herhangi bir şey",
-
-  // Sıkça birleşik yazılan ama ayrı yazılması gereken sözler
-  hergün: "her gün",
-  hergun: "her gün",
-  herzaman: "her zaman",
-  heran: "her an",
-  heryer: "her yer",
-  herbiri: "her biri",
-  pekçok: "pek çok",
-  pekcok: "pek çok",
-  pekaz: "pek az",
-  yada: "ya da",
-  tabiki: "tabii ki",
-  tabiiki: "tabii ki",
-  sağol: "sağ ol",
-  sagol: "sağ ol",
-  sağolun: "sağ olun",
-  sagolun: "sağ olun",
-  hoşçakal: "hoşça kal",
-  hoscakal: "hoşça kal",
-  hoşgeldin: "hoş geldin",
-  hosgeldin: "hoş geldin",
-  hoşgeldiniz: "hoş geldiniz",
-  hosgeldiniz: "hoş geldiniz",
-  hoşbulduk: "hoş bulduk",
-  hosbulduk: "hoş bulduk",
-  yanısıra: "yanı sıra",
-  yanisira: "yanı sıra",
-  peşisıra: "peşi sıra",
-  pesisira: "peşi sıra",
-  ardısıra: "ardı sıra",
-  ardisira: "ardı sıra",
-  artarda: "art arda",
-  yüzyüze: "yüz yüze",
-  yuzyuze: "yüz yüze",
-  elele: "el ele",
-  gözgöze: "göz göze",
-  başbaşa: "baş başa",
-  basbasa: "baş başa",
-  yanyana: "yan yana",
-  içiçe: "iç içe",
-  icice: "iç içe",
-  üstüste: "üst üste",
-  ustuste: "üst üste",
-  altalta: "alt alta",
-  önsöz: "ön söz",
-  onsoz: "ön söz",
-  önyargı: "ön yargı",
-  onyargi: "ön yargı",
-  farketmek: "fark etmek",
-  farketti: "fark etti",
-  farkettim: "fark ettim",
-  farkeder: "fark eder",
-  farketmez: "fark etmez",
-  terketmek: "terk etmek",
-  terketti: "terk etti",
-  ayırdetmek: "ayırt etmek",
-  ayırtetmek: "ayırt etmek",
-  arzetmek: "arz etmek",
-  arzederim: "arz ederim",
-  varolmak: "var olmak",
-  yokolmak: "yok olmak",
-  haketmek: "hak etmek",
-  haketti: "hak etti",
-  hakkaten: "hakikaten",
-  hiçkimse: "hiç kimse",
-  hickimse: "hiç kimse",
-
-  // Ünlü düşmesi yapılmaması gereken yer bildiren sözler (TDK Kural 15)
-  burda: "burada",
-  burdan: "buradan",
-  şurda: "şurada",
-  surda: "şurada",
-  şurdan: "şuradan",
-  surdan: "şuradan",
-  orda: "orada",
-  ordan: "oradan",
-  içerde: "içeride",
-  icerde: "içeride",
-  içerden: "içeriden",
-  icerden: "içeriden",
-  dışarda: "dışarıda",
-  disarda: "dışarıda",
-  dışardan: "dışarıdan",
-  disardan: "dışarıdan",
-  yukarda: "yukarıda",
-  yukardan: "yukarıdan",
-
-  // Sıkça yanlış yazılan sözcükler
-  herkez: "herkes",
-  yanlız: "yalnız",
-  yalnış: "yanlış",
-  orjinal: "orijinal",
-  labaratuar: "laboratuvar",
-  laboratuar: "laboratuvar",
-  şöför: "şoför",
-  sofor: "şoför",
-  egzos: "egzoz",
-  eksoz: "egzoz",
-  ekzoz: "egzoz",
-  kiprik: "kirpik",
-  kirbit: "kibrit",
-  klavuz: "kılavuz",
-  kıravat: "kravat",
-  süpriz: "sürpriz",
-  supriz: "sürpriz",
-  raslantı: "rastlantı",
-  hastahane: "hastane",
-  pastahane: "pastane",
-  postahane: "postane",
-  eczahane: "eczane",
-  meyva: "meyve",
-  sarmısak: "sarımsak",
-  dinazor: "dinozor",
-  pantalon: "pantolon",
-  tesbih: "tespih",
-  ahçı: "aşçı",
-  matba: "matbaa",
-  idda: "iddia",
-  iddaa: "iddia",
-  muhattap: "muhatap",
-  traş: "tıraş",
-  karnıbahar: "karnabahar",
-  kareografi: "koreografi",
-  poaça: "poğaça",
-  pohaça: "poğaça",
-  şarz: "şarj",
-  sarj: "şarj",
-  makina: "makine",
-  müsade: "müsaade",
-  entellektüel: "entelektüel",
-  inisiyatif: "inisiyatif",
-  insiyatif: "inisiyatif",
-  sezeryan: "sezaryen",
-  doküman: "doküman",
-  döküman: "doküman",
-  erozyon: "erozyon",
-  erizyon: "erozyon",
-  anane: "anneanne",
-  babaanne: "babaanne",
-};
-
-export const SEY_EXCEPTIONS = new Set(["düşey", "eşey", "konsey", "jersey", "şey"]);
-
-/**
- * TDK (Türk Dil Kurumu) API Wrapper
- */
-export class TDK {
-  private static readonly BASE_URL = "https://sozluk.gov.tr";
-  private static readonly AUDIO_API_HOST = "api.sozluk.gov.tr";
-  private static readonly KUBBEALTI_HOST = "eski.lugatim.com";
-
-  /**
-   * `eski.lugatim.com` (Kubbealtı Lugatı's data API) sends only its leaf
-   * certificate during the TLS handshake, omitting the intermediates a
-   * correctly configured server would include — a server-side misconfiguration,
-   * not something we should paper over by disabling verification. These are
-   * the two certificates the server *should* be sending (fetched from the
-   * leaf's own Authority Information Access URLs), supplied here so Node can
-   * still build a full, properly verified chain up to a root it already
-   * trusts (ISRG Root X1). If Let's Encrypt rotates this intermediate, this
-   * stops working and every Kubbealtı call fails closed to `null` — same
-   * fail-closed contract as the rest of this file's fragile integrations.
-   */
-  private static readonly KUBBEALTI_EXTRA_CA = [
-    `-----BEGIN CERTIFICATE-----
-MIIE2jCCAsKgAwIBAgIQTr0klH4k05SALYSlL9WzGTANBgkqhkiG9w0BAQsFADAu
-MQswCQYDVQQGEwJVUzENMAsGA1UEChMESVNSRzEQMA4GA1UEAxMHUm9vdCBZUjAe
-Fw0yNTA5MDMwMDAwMDBaFw0yODA5MDIyMzU5NTlaMDMxCzAJBgNVBAYTAlVTMRYw
-FAYDVQQKEw1MZXQncyBFbmNyeXB0MQwwCgYDVQQDEwNZUjIwggEiMA0GCSqGSIb3
-DQEBAQUAA4IBDwAwggEKAoIBAQDZ0LxwBppqh84luqMerV/eeL/fXQ7mLQQv1Lnp
-WKZbyvGpx6wh6AfnslAnF6ewTkcHA+gSOoBvm3Dfm06AuGiF+KRut4fAcowqnAQQ
-CW98+QPP/eOv/wug7Iyk4NkOxf2I6g2f55T6nJoOTLFcukeRq80JGQEYan+dPFr9
-OGUgQK2hGKgNkW87pappsOAuUJcroYhRt5uUis4qaZireiseu32gzDJNBAiKtsvd
-6HX4v25bpkRNcS/B/Gtc9kVbUpD+2PLPxdei3Tim55k4tfAEXwD2qyiPTxrTNq6l
-N+AMr5g2c1dNqkOTwjxeV6L5lpP1rGiYvLnRaPlOqyZRPW+5AgMBAAGjge4wgesw
-DgYDVR0PAQH/BAQDAgGGMBMGA1UdJQQMMAoGCCsGAQUFBwMBMBIGA1UdEwEB/wQI
-MAYBAf8CAQAwHQYDVR0OBBYEFEAVLSZ57TIgnt+ach3WMh+BDIEMMB8GA1UdIwQY
-MBaAFN7nW2DQIm1AKH0/DQH+pLVStFGUMDIGCCsGAQUFBwEBBCYwJDAiBggrBgEF
-BQcwAoYWaHR0cDovL3lyLmkubGVuY3Iub3JnLzATBgNVHSAEDDAKMAgGBmeBDAEC
-ATAnBgNVHR8EIDAeMBygGqAYhhZodHRwOi8veXIuYy5sZW5jci5vcmcvMA0GCSqG
-SIb3DQEBCwUAA4ICAQB0ZUQWZ9/Yn9COEpo+JfecMnB0h0vwDm/M66IqXqw3LoaL
-mx9lZvRTeDIS67PUeI3yCA2W6PKRD0/FE/G57lOmS+Xy5AaaL00ICGOqjNcCaMWW
-8o8nevHOd4i4lqgtznE/28QwlcdJyF8yBiWHpnyjhEpmNWJURgOCOg2xpwRMBCsj
-MScqYPtOhBeuYQvSwAEeTML2Ukh6uGuX4E14q65Ja8cdjF5bAldnP1eE4FBaAwsZ
-G2fOqqrKV03Y85Nw2btedP1AtliQuJZs/Jo/gXxXdc7LrH3McgnpnbTiAncX7yES
-hP6kzQejllqMCIt52HOjxDGWafS7Xw+DKwqmH+Eqy8dcbOuag/1AYlQoKNVK3F5q
-Hh6tEDiMqQcLIibGKteE6iHo4A/bIScbzrhXUYuism42ZYzmc48FMVIH3qy4L84E
-TdAH2gtxw0PAhvRVXp8HP7wfngpzsN/8xOTpeRSbM4+Qbc56G6+Bifmv6sk1ieQb
-NA3wJdl4DDUuQSV8hBgx6zoI1ZSGORprDFux7c6rhc77QZMSRrEgomBeklervEve
-86ylWmZ3WWHV6RLMi8xNvjd71r4EPIGgY7BZU/VPBkq+uA7Gb6mbJnFgV43uh3xy
-LRFgxIAphIukwTGSMZZR+AI+Qnp0BYTWovHXozOf3H8r6hozEoT02JHn0AeTfA==
------END CERTIFICATE-----`,
-    `-----BEGIN CERTIFICATE-----
-MIIF9DCCA9ygAwIBAgIRAPJLbRf52a18scn+p4eCaZ8wDQYJKoZIhvcNAQELBQAw
-TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
-cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMjYwNTEzMDAwMDAw
-WhcNMzIwOTAyMjM1OTU5WjAuMQswCQYDVQQGEwJVUzENMAsGA1UEChMESVNSRzEQ
-MA4GA1UEAxMHUm9vdCBZUjCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIB
-ANvGJnN78CTJdWL3+eGfsLN5TrNBJs+VH9hRXqRbwxu9sGNiB0BD1fcOxbSUQCJI
-M1xE13Db+5Cw1w0s0EBYsvuIP/6joF0w8cuImbgR1OGgYbSQ4OpzI+DG8SGuTlcE
-873OCS+kh3srlo6vl43M5OJg4Aeo1sfHp6kTJDoIiFBNJAY+OKfX/FUvYKuhjT+n
-o49lmqmupSBI5PkBQiqrEGtWU5uxU/cQWHGu8jSjFBznZqvbNPLMXMLFxCb3WTfr
-JBXXjqvWG+v4bjzxjjeAtOlU7qarRDvNOyAuQYLln904M+faKx8hnLCpJ15ZqaEg
-cNlY+9MMWcC5yvL2A2j3l9+2buggZX+dOE91zYmIdawTvSZuVvlbRrAlLxIB6pwM
-BjneXCjYQ8+3BCCjssbSNpZU3hTcBDdhfAlEDlYr6pEatnMdmDT5BqnKC92bd0Eh
-M1fbLHioLccLCuievT8ZkPhZrq7Mii7gNXAcUEAR8+lzYal+9zTg7C5DALyVOeG/
-CqfRAMn1KSHCR0NSA6P8tn/mGRlnCct5rtVCLnVySVpU6H1qGg3DgTOuskf8eahT
-MiYbI5ezPJmO5ertalskQ1utp74+eDy92PI4ftHKTbq9IWhH4YZKh3WnJEIt+oQv
-lYZbY8tpEroKrFB6PFGzrJIDRyts4HqvuH52RFj2zv/BAgMBAAGjgeswgegwDgYD
-VR0PAQH/BAQDAgEGMBMGA1UdJQQMMAoGCCsGAQUFBwMBMA8GA1UdEwEB/wQFMAMB
-Af8wHQYDVR0OBBYEFN7nW2DQIm1AKH0/DQH+pLVStFGUMB8GA1UdIwQYMBaAFHm0
-WeZ7tuXkAXOACIjIGlj26ZtuMDIGCCsGAQUFBwEBBCYwJDAiBggrBgEFBQcwAoYW
-aHR0cDovL3gxLmkubGVuY3Iub3JnLzATBgNVHSAEDDAKMAgGBmeBDAECATAnBgNV
-HR8EIDAeMBygGqAYhhZodHRwOi8veDEuYy5sZW5jci5vcmcvMA0GCSqGSIb3DQEB
-CwUAA4ICAQA8spSI95KKfn2W6GMmDpHBJSPaLbsS3W93cijJCRCYAc1fsJgL1FIL
-7C0C9ecPOdcwB2fi0Dk2p94j9iTJCxmt5CFSKLRWwnXT2MMSXexVxqoVB79BdWPx
-VXETkVme/qYSAuKVHh5Ps+5BixgmwS1JkjSAc+MfrUbNssVEEnH0aEiAh+rotXAV
-JSP/Ye7LJPEwD9DWG72vVWbhAcuOf5OLjz57Ctk7MgQHynZ7+PlHJtajroCaIbtC
-r6tcZZaAwUQm+jQyeWdV+2hv9deOYFmKeQyjjcSrN5Nadrw+L9DZJLbA1HqeNvLh
-BgqpP0fvJq2N6EtD574N6eMI7uMsJTnji2UDz9el5XLSv9fqJMuDQtYVb2oTNoKp
-oUqhxPVC0aq4eG5MESaIdn8b5ZGSSeAJLMHXljEdlNza+ncfkviXk1POLnnFdvx8
-/gk6M374WbLWFXw8N141B/Rl/tINGfl1TxOIiqtiMYkL02RSGb1kq34BL9NPP27z
-RGMuHGnzS3hFIrRTfKxrzUZ9RzQWzEG3K6fJ3r2nqSltkeytis9DIBoFY9VmVyjL
-M71DMi+y1+TRSJVClEMwvA4yL++7q9XZx5r5wBRWB4kQTKH5qyoZnDw7iiuh1lID
-yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
------END CERTIFICATE-----`,
-  ];
-
-  // Configuration
-  private static defaultTimeoutMs = 8000;
-  private static defaultRetries = 1;
-  private static maxCacheSize = 1000;
-
-  // Cache Mechanism
-  private static isCacheEnabled = false;
-  private static wordCache = new Map<string, WordInfo[]>();
-  private static dailyContentCache: DailyContent | null = null;
-  private static autocompleteCache: string[] = [];
-  private static autocompleteSet: Set<string> = new Set<string>();
-  private static stemCache = new Map<string, string | null>();
-
-  /**
-   * Configures global client options such as network timeout, retries, and cache size.
-   */
-  public static configure(config: TDKConfig): void {
-    if (config.timeoutMs !== undefined) this.defaultTimeoutMs = Math.max(100, config.timeoutMs);
-    if (config.retries !== undefined) this.defaultRetries = Math.max(0, config.retries);
-    if (config.cache !== undefined) this.enableCache(config.cache);
-    if (config.maxCacheSize !== undefined) this.maxCacheSize = Math.max(10, config.maxCacheSize);
-  }
-
-  /**
-   * Enables or disables in-memory caching for API requests.
-   */
-  public static enableCache(status = true): void {
-    this.isCacheEnabled = status;
-    if (!status) {
-      this.clearCache();
-    }
-  }
-
-  /**
-   * Clears the internal cache.
-   */
-  public static clearCache(): void {
-    this.wordCache.clear();
-    this.dailyContentCache = null;
-    this.autocompleteCache = [];
-    this.autocompleteSet.clear();
-    this.stemCache.clear();
-  }
-
-  private static setBoundedCache<K, V>(map: Map<K, V>, key: K, value: V): void {
-    if (map.size >= this.maxCacheSize) {
-      const firstKey = map.keys().next().value;
-      if (firstKey !== undefined) map.delete(firstKey);
-    }
-    map.set(key, value);
-  }
-
-  private static delay(ms: number) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-
-  /**
-   * Internal helper that performs HTTP fetch with timeout and automatic retry on network/5xx errors.
-   */
-  private static async fetchWithRetry(
-    url: string,
-    options: RequestInit = {},
-    retries: number = this.defaultRetries,
-    timeoutMs: number = this.defaultTimeoutMs
-  ): Promise<Response> {
-    let lastError: unknown;
-    for (let attempt = 0; attempt <= retries; attempt++) {
-      try {
-        const signal = AbortSignal.timeout(timeoutMs);
-        const headers = {
-          "User-Agent": "TDK-API-Nodejs-Wrapper/1.0",
-          ...((options.headers as Record<string, string>) || {}),
-        };
-        const res = await fetch(url, { ...options, headers, signal });
-        if (res.ok || (res.status >= 400 && res.status < 500)) {
-          return res;
-        }
-        // If 5xx server error, retry
-        if (attempt < retries) {
-          await this.delay(200 * (attempt + 1));
-          continue;
-        }
-        return res;
-      } catch (err) {
-        lastError = err;
-        if (attempt < retries) {
-          await this.delay(200 * (attempt + 1));
-          continue;
-        }
-      }
-    }
-    throw new TDKNetworkError(`Request to ${url} failed after ${retries + 1} attempts.`, {
-      cause: lastError,
-    });
-  }
-
-  /**
-   * Fetches detailed information for a given word from the TDK Dictionary.
-   */
-  public static async getWord(word: string): Promise<WordInfo[]> {
-    if (!word || word.trim() === "") {
-      throw new TDKValidationError("Word parameter cannot be empty.");
-    }
-
-    const cleanWord = word.trim().toLocaleLowerCase("tr-TR");
-
-    if (this.isCacheEnabled && this.wordCache.has(cleanWord)) {
-      return this.wordCache.get(cleanWord)!;
-    }
-
-    const url = `${this.BASE_URL}/gts?ara=${encodeURIComponent(cleanWord)}`;
-
-    let response: Response;
-    try {
-      response = await this.fetchWithRetry(url);
-    } catch (error) {
-      throw new TDKNetworkError("Failed to fetch word from TDK: request failed.", { cause: error });
-    }
-
-    if (!response.ok) {
-      throw new TDKNetworkError(`Failed to fetch word from TDK: HTTP ${response.status}.`, {
-        status: response.status,
-      });
-    }
-
-    let data: unknown;
-    try {
-      data = await response.json();
-    } catch (error) {
-      throw new TDKNetworkError("Failed to fetch word from TDK: invalid JSON response.", { cause: error });
-    }
-
-    if (!Array.isArray(data) && data && "error" in (data as Record<string, unknown>)) {
-      if (this.isCacheEnabled) this.setBoundedCache(this.wordCache, cleanWord, []);
-      return [];
-    }
-
-    const results = data as WordInfo[];
-    if (this.isCacheEnabled) {
-      this.setBoundedCache(this.wordCache, cleanWord, results);
-    }
-    return results;
-  }
-
-  /**
-   * Helper method to get only the meanings (definitions) of a word as a string array.
-   */
-  public static async getMeanings(word: string): Promise<string[]> {
-    const results = await this.getWord(word);
-    if (results.length === 0) return [];
-    
-    const meanings: string[] = [];
-    for (const result of results) {
-      if (result.anlamlarListe) {
-        for (const anlam of result.anlamlarListe) {
-          if (anlam.anlam) meanings.push(anlam.anlam);
-        }
-      }
-    }
-    return meanings;
-  }
-
-  /**
-   * `sozluk.gov.tr`'s dedicated `/autocomplete.json` (and `/data/autocomplete.json`)
-   * routes no longer serve JSON — they fall through to the SPA's `index.html`.
-   * The full ~81k-word headword list the site's own autocomplete UI uses is
-   * instead bundled directly into its main JS asset as a
-   * `JSON.parse(\`[{"madde":"..."}]\`)` literal, so this fetches the home
-   * page to find that asset's current hashed filename, downloads it (a few
-   * MB, only once per process), and extracts the literal out of it. Fragile
-   * scraping of an implementation detail — if TDK's build stops embedding
-   * this, this fails closed to `[]` rather than throwing.
-   */
-  private static async fetchAutocompleteData(): Promise<string[]> {
-    try {
-      const homeResponse = await fetch(`${this.BASE_URL}/`, {
-        headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" },
-      });
-      if (!homeResponse.ok) return [];
-      const html = await homeResponse.text();
-
-      const scriptMatch = html.match(/src="(\/assets\/index-[^"]+\.js)"/);
-      if (!scriptMatch) return [];
-
-      const bundleResponse = await fetch(`${this.BASE_URL}${scriptMatch[1]}`, {
-        headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" },
-      });
-      if (!bundleResponse.ok) return [];
-      const bundleJs = await bundleResponse.text();
-
-      const startMarker = 'JSON.parse(`[{"madde":';
-      const startIdx = bundleJs.indexOf(startMarker);
-      if (startIdx === -1) return [];
-      const jsonStart = startIdx + "JSON.parse(".length + 1;
-      const jsonEnd = bundleJs.indexOf("`)", jsonStart);
-      if (jsonEnd === -1) return [];
-
-      const data = JSON.parse(bundleJs.slice(jsonStart, jsonEnd)) as { madde: string }[];
-      return data.map((item) => item.madde).filter(Boolean);
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * Ensures TDK's ~81k headword list is loaded in memory for fast O(1) set operations.
-   */
-  private static async ensureAutocompleteLoaded(): Promise<void> {
-    if (this.autocompleteCache.length === 0) {
-      this.autocompleteCache = await this.fetchAutocompleteData();
-      this.autocompleteSet = new Set(
-        this.autocompleteCache.map((w) => w.toLocaleLowerCase("tr-TR"))
-      );
-    }
-  }
-
-  /**
-   * Returns autocomplete suggestions for a given prefix, searched over TDK's
-   * full headword list (see `fetchAutocompleteData`). The list is fetched
-   * and cached once per process regardless of `enableCache()` — the same
-   * caching behavior as before — and only cleared by `clearCache()`.
-   */
-  public static async getSuggestions(prefix: string): Promise<string[]> {
-    if (!prefix || prefix.trim() === "") return [];
-
-    await this.ensureAutocompleteLoaded();
-
-    const cleanPrefix = prefix.trim().toLocaleLowerCase("tr-TR");
-    return this.autocompleteCache
-      .filter(w => w.toLocaleLowerCase("tr-TR").startsWith(cleanPrefix))
-      .slice(0, 10);
-  }
-
-  /**
-   * Checks whether a word exists as a known headword in TDK dictionary.
-   * Checks in-memory autocompleteSet (81k headwords) if loaded, or queries TDK API.
-   */
-  public static async isHeadword(word: string): Promise<boolean> {
-    if (!word || word.trim() === "") return false;
-    const clean = word.trim().toLocaleLowerCase("tr-TR");
-
-    await this.ensureAutocompleteLoaded();
-    if (this.autocompleteSet.size > 0) {
-      return this.autocompleteSet.has(clean);
-    }
-
-    try {
-      const results = await this.getWord(clean);
-      return results.length > 0;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Generates candidate roots for a given Turkish word using progressive BFS suffix stripping,
-   * consonant mutation restoration, and vowel drop restoration.
-   */
-  public static getStemCandidates(word: string): string[] {
-    return getStemCandidates(word);
-  }
-
-  /**
-   * Finds the dictionary root (headword) of a word by checking direct existence
-   * and evaluating candidate stems generated by morphological analysis.
-   * Returns the root headword string if found, or null if no match in TDK.
-   */
-  public static async findRoot(word: string): Promise<string | null> {
-    if (!word || word.trim() === "") return null;
-    const clean = word.trim().toLocaleLowerCase("tr-TR");
-
-    if (this.stemCache.has(clean)) {
-      return this.stemCache.get(clean)!;
-    }
-
-    // 1. If the word itself is an exact headword, it is its own root
-    if (await this.isHeadword(clean)) {
-      this.setBoundedCache(this.stemCache, clean, clean);
-      return clean;
-    }
-
-    // 2. Test morphological stem candidates
-    const candidates = getStemCandidates(clean);
-    for (const candidate of candidates) {
-      if (await this.isHeadword(candidate)) {
-        this.setBoundedCache(this.stemCache, clean, candidate);
-        return candidate;
-      }
-    }
-
-    this.setBoundedCache(this.stemCache, clean, null);
-    return null;
-  }
-
-  /**
-   * Performs morphological stemming on a Turkish word.
-   * Returns a StemResult containing the original word, resolved root, and whether it is inflected.
-   */
-  public static async stem(word: string): Promise<StemResult | null> {
-    if (!word || word.trim() === "") return null;
-    const clean = word.trim().toLocaleLowerCase("tr-TR");
-    const root = await this.findRoot(word);
-
-    if (!root) {
-      return null;
-    }
-
-    return {
-      word,
-      root,
-      isInflected: root !== clean,
-      candidates: getStemCandidates(word),
-    };
-  }
-
-  /**
-   * Returns a list of proverbs and idioms containing the word.
-   */
-  public static async getProverbs(word: string): Promise<string[]> {
-    const results = await this.getWord(word);
-    if (results.length === 0) return [];
-    
-    const proverbs: string[] = [];
-    for (const result of results) {
-      if (result.atasozu) {
-        for (const atasoz of result.atasozu) {
-          if (atasoz.madde) proverbs.push(atasoz.madde);
-        }
-      }
-    }
-    return proverbs;
-  }
-
-  /**
-   * Returns the etymological origin of the word, or "Türkçe" if TDK doesn't
-   * record a foreign origin for it. Returns `null` only when the word itself
-   * isn't found in the dictionary at all.
-   */
-  public static async getOrigin(word: string): Promise<string | null> {
-    const results = await this.getWord(word);
-    if (results.length === 0) return null;
-    return results[0].lisan || "Türkçe";
-  }
-
-  /**
-   * Returns whether the word has a recorded foreign etymological origin.
-   * Returns `null` (instead of a boolean) when the word isn't found at all.
-   */
-  public static async isForeignWord(word: string): Promise<boolean | null> {
-    const origin = await this.getOrigin(word);
-    if (origin === null) return null;
-    return origin !== "Türkçe";
-  }
-
-  /**
-   * Groups a list of words by their etymological origin. Words not found in
-   * the dictionary are grouped under "Bilinmiyor". Throttled like getWordsBatch.
-   */
-  public static async groupByOrigin(words: string[]): Promise<Record<string, string[]>> {
-    const groups: Record<string, string[]> = {};
-    for (const word of words) {
-      const origin = (await this.getOrigin(word)) ?? "Bilinmiyor";
-      if (!groups[origin]) groups[origin] = [];
-      groups[origin].push(word);
-      await this.delay(200);
-    }
-    return groups;
-  }
-
-  /**
-   * Returns literature examples containing the word.
-   */
-  public static async getExamples(word: string): Promise<{ sentence: string; author: string | null }[]> {
-    const results = await this.getWord(word);
-    const examples: { sentence: string; author: string | null }[] = [];
-    
-    for (const result of results) {
-      if (result.anlamlarListe) {
-        for (const anlam of result.anlamlarListe) {
-          if (anlam.orneklerListe) {
-            for (const ornek of anlam.orneklerListe) {
-              const author = ornek.yazar && ornek.yazar.length > 0 ? ornek.yazar[0].tam_adi : null;
-              examples.push({ sentence: ornek.ornek, author });
-            }
-          }
-        }
-      }
-    }
-    return examples;
-  }
-
-  /**
-   * Calls the `api.sozluk.gov.tr/gts-yeni` endpoint the official web UI uses
-   * internally (richer than the public `/gts`: includes `seskod`,
-   * `anlamEsAnlam`/`anlamKarsitAnlam`, etc). That endpoint 403s unless the
-   * request looks like it came from a browser tab on sozluk.gov.tr: it needs
-   * an `Origin`/`Referer` pair matching that site AND a browser-like
-   * `User-Agent` (our usual `TDK-API-Nodejs-Wrapper/…` UA gets rejected).
-   * `fetch` (undici) also strips a manually-set `Origin` header as a
-   * forbidden header name, so this uses `node:https` directly instead.
-   * This is inherently fragile scraping of an undocumented endpoint — if
-   * TDK tightens this check further, this should fail closed to `null`
-   * rather than throw.
-   */
-  private static fetchGtsYeni(word: string): Promise<any[] | null> {
-    return new Promise((resolve) => {
-      const req = https.request(
-        {
-          hostname: this.AUDIO_API_HOST,
-          path: `/gts-yeni?ara=${encodeURIComponent(word)}`,
-          method: "GET",
-          headers: {
-            "User-Agent":
-              "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36",
-            Origin: this.BASE_URL,
-            Referer: `${this.BASE_URL}/`,
-          },
-        },
-        (res) => {
-          let body = "";
-          res.on("data", (chunk) => (body += chunk));
-          res.on("end", () => {
-            try {
-              const data = JSON.parse(body);
-              resolve(Array.isArray(data) ? data : null);
-            } catch {
-              resolve(null);
-            }
-          });
-        }
-      );
-      req.on("error", () => resolve(null));
-      req.end();
-    });
-  }
-
-  private static async fetchSeskod(word: string): Promise<string | null> {
-    const data = await this.fetchGtsYeni(word);
-    const seskod = data?.[0]?.seskod;
-    return seskod ? String(seskod) : null;
-  }
-
-  /**
-   * Returns synonyms ("eş anlamlı kelimeler") recorded for the word, pooled
-   * across all of its meanings. Uses the same undocumented `gts-yeni`
-   * endpoint as `getAudioUrl` — returns `[]` if the lookup fails.
-   */
-  public static async getSynonyms(word: string): Promise<string[]> {
-    if (!word || word.trim() === "") return [];
-    const data = await this.fetchGtsYeni(word.trim().toLocaleLowerCase("tr-TR"));
-    if (!data) return [];
-
-    const synonyms: string[] = [];
-    for (const entry of data) {
-      for (const anlam of entry.anlamlarListe ?? []) {
-        for (const es of anlam.anlamEsAnlam ?? []) {
-          if (es.deger) synonyms.push(es.deger);
-        }
-      }
-    }
-    return [...new Set(synonyms)];
-  }
-
-  /**
-   * Returns antonyms ("zıt anlamlı kelimeler") recorded for the word, pooled
-   * across all of its meanings. Uses the same undocumented `gts-yeni`
-   * endpoint as `getAudioUrl` — returns `[]` if the lookup fails.
-   */
-  public static async getAntonyms(word: string): Promise<string[]> {
-    if (!word || word.trim() === "") return [];
-    const data = await this.fetchGtsYeni(word.trim().toLocaleLowerCase("tr-TR"));
-    if (!data) return [];
-
-    const antonyms: string[] = [];
-    for (const entry of data) {
-      for (const anlam of entry.anlamlarListe ?? []) {
-        for (const ka of anlam.anlamKarsitAnlam ?? []) {
-          if (ka.deger) antonyms.push(ka.deger);
-        }
-      }
-    }
-    return [...new Set(antonyms)];
-  }
-
-  /**
-   * Returns the direct URL of the audio pronunciation, if TDK has one recorded for this word.
-   */
-  public static async getAudioUrl(word: string): Promise<string | null> {
-    if (!word || word.trim() === "") {
-      throw new TDKValidationError("Word parameter cannot be empty.");
-    }
-
-    const seskod = await this.fetchSeskod(word.trim().toLocaleLowerCase("tr-TR"));
-    if (!seskod) return null;
-    return `https://${this.AUDIO_API_HOST}/ses/${encodeURIComponent(seskod)}.wav`;
-  }
-
-  /**
-   * Downloads the audio pronunciation to the specified path.
-   */
-  public static async downloadAudio(word: string, destPath?: string): Promise<string | null> {
-    const url = await this.getAudioUrl(word);
-    if (!url) return null;
-    
-    const finalPath = destPath || path.join(os.tmpdir(), `${word}.wav`);
-    try {
-      const res = await fetch(url);
-      if (!res.ok) return null;
-      const buffer = await res.arrayBuffer();
-      fs.writeFileSync(finalPath, Buffer.from(buffer));
-      return finalPath;
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Checks spelling and returns suggestions if wrong.
-   */
-  public static async checkSpelling(word: string): Promise<SpellCheckResult> {
-    if (!word || word.trim() === "") {
-      return { isCorrect: false, word };
-    }
-
-    const cleanWord = word.trim().toLocaleLowerCase("tr-TR");
-
-    // 1. Check if word exists in TDK dictionary
-    const results = await this.getWord(word);
-    if (results.length > 0) {
-      return { isCorrect: true, word };
-    }
-
-    // 2. Common Turkish misspellings, erroneously joined compounds, and vowel drop errors
-    if (COMMON_MISSPELLINGS[cleanWord]) {
-      return { isCorrect: false, word, suggestion: COMMON_MISSPELLINGS[cleanWord] };
-    }
-
-    // 3. Dynamic -şey / -sey attached check:
-    // In Turkish, 'şey' is an indefinite pronoun and is ALWAYS written separately from the preceding word
-    // (e.g. her şey, bir şey, hiçbir şey, çok şey, her şeyi, bir şeyler).
-    const seyMatch = cleanWord.match(/^(.+?)(?:şey|sey)([ıiuaeüodekmnl]+)?$/);
-    if (seyMatch && !SEY_EXCEPTIONS.has(cleanWord)) {
-      let prefix = seyMatch[1];
-      const suffix = seyMatch[2] || "";
-      if (prefix === "hicbir") prefix = "hiçbir";
-      if (prefix === "cok") prefix = "çok";
-      return {
-        isCorrect: false,
-        word,
-        suggestion: `${prefix} şey${suffix}`,
-      };
-    }
-
-    // 4. "Sıkça yapılan yanlışlar" from DailyContent
-    const daily = await this.getDailyContent();
-    if (daily) {
-      const syydMatch = daily.syyd.find((s) => s.yanliskelime.toLocaleLowerCase("tr-TR") === cleanWord);
-      if (syydMatch) {
-        return { isCorrect: false, word, suggestion: syydMatch.dogrukelime };
-      }
-      const mixMatch = daily.karistirma.find((s) => s.yanlis.toLocaleLowerCase("tr-TR") === cleanWord);
-      if (mixMatch) {
-        return { isCorrect: false, word, suggestion: mixMatch.dogru };
-      }
-    }
-
-    // 5. Morphology Fallback: Check if the word is an inflected form or bare verb imperative of a known headword
-    // (e.g., "halılarımızın" -> "halı", "kitabımız" -> "kitap", "çocuğa" -> "çocuk", "söyle" -> "söylemek")
-    const root = await this.findRoot(word);
-    if (root) {
-      const isInflected = root !== cleanWord;
-      return {
-        isCorrect: true,
-        word,
-        isInflected,
-        root,
-      };
-    }
-
-    // 6. Check if headwords with spaces match when space is removed (e.g. "ön yargı" for "önyargı")
-    if (this.autocompleteCache.length === 0) {
-      this.autocompleteCache = await this.fetchAutocompleteData();
-    }
-    for (const candidate of this.autocompleteCache) {
-      if (candidate.includes(" ")) {
-        const candidateNoSpace = candidate.replace(/\s+/g, "").toLocaleLowerCase("tr-TR");
-        if (candidateNoSpace === cleanWord) {
-          return { isCorrect: false, word, suggestion: candidate };
-        }
-      }
-    }
-
-    // 7. No exact match or morphology root: fall back to closest headword by edit distance.
-    // Ties prefer matching first letter, and initial character mismatches are penalized
-    // so irrelevant foreign loanwords (like 'jersey') do not beat Turkish roots.
-    let best: { candidate: string; distance: number; rawDist: number; firstMismatch: number; lengthMismatch: number } | null = null;
-    for (const candidate of this.autocompleteCache) {
-      if (candidate.includes(" ") || candidate !== candidate.toLocaleLowerCase("tr-TR")) continue;
-      if (Math.abs(candidate.length - cleanWord.length) > 2) continue;
-
-      const rawDist = this.damerauLevenshtein(cleanWord, candidate);
-      if (rawDist === 0) continue;
-
-      const firstMismatch = candidate[0] === cleanWord[0] ? 0 : 1;
-      const lengthMismatch = candidate.length === cleanWord.length ? 0 : 1;
-      const distance = rawDist + (firstMismatch > 0 ? 1.2 : 0);
-
-      const better =
-        !best ||
-        distance < best.distance ||
-        (distance === best.distance && firstMismatch < best.firstMismatch) ||
-        (distance === best.distance && firstMismatch === best.firstMismatch && lengthMismatch < best.lengthMismatch);
-      if (better) {
-        best = { candidate, distance, rawDist, firstMismatch, lengthMismatch };
-      }
-    }
-    if (best && best.rawDist <= 2 && (best.firstMismatch === 0 || best.rawDist <= 1)) {
-      return { isCorrect: false, word, suggestion: best.candidate };
-    }
-    return { isCorrect: false, word };
-  }
-
-  /**
-   * Fetches daily content (word of the day, proverbs, rules, etc).
-   * `bypassCache` skips both reading and writing `dailyContentCache` even
-   * when `enableCache(true)` is on — used by `getRule()`'s retry loop, which
-   * needs a fresh random `/icerik` draw on every attempt; without it, once
-   * caching is enabled the loop would just re-read the same cached response
-   * 25 times and could never find a rule outside that first random draw.
-   */
-  public static async getDailyContent(bypassCache = false): Promise<DailyContent | null> {
-    if (!bypassCache && this.isCacheEnabled && this.dailyContentCache) return this.dailyContentCache;
-
-    try {
-      const response = await fetch(`${this.BASE_URL}/icerik`, {
-        headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" },
-      });
-      if (response.ok) {
-        const data = await response.json() as DailyContent;
-        if (!bypassCache && this.isCacheEnabled) this.dailyContentCache = data;
-        return data;
-      }
-    } catch {
-      return null;
-    }
-    return null;
-  }
-
-  /**
-   * Returns today's word of the day along with all of its listed meanings.
-   */
-  public static async getWordOfTheDay(): Promise<WordOfTheDay | null> {
-    const daily = await this.getDailyContent();
-    if (!daily || daily.kelime.length === 0) return null;
-
-    const word = daily.kelime[0].madde;
-    const meanings = daily.kelime.filter((k) => k.madde === word).map((k) => k.anlam);
-    return { word, meanings };
-  }
-
-  /**
-   * Picks a random entry (word or proverb) from today's daily content.
-   * Note: this samples from today's `getDailyContent()` picks, not the full dictionary.
-   */
-  public static async getRandomWord(): Promise<DailyPick | null> {
-    const daily = await this.getDailyContent();
-    if (!daily) return null;
-
-    const pool: DailyPick[] = [
-      ...daily.kelime.map((k) => ({ type: "kelime" as const, madde: k.madde, anlam: k.anlam })),
-      ...daily.atasoz.map((a) => ({ type: "atasoz" as const, madde: a.madde, anlam: a.anlam })),
-    ];
-    if (pool.length === 0) return null;
-
-    return pool[Math.floor(Math.random() * pool.length)];
-  }
-
-  /**
-   * Returns the spelling-rule page(s) ("yazım kuralları") linked from TDK's
-   * `/icerik` daily-content feed, e.g. `{ adi: "Kısaltmalar", url: "https://..." }`.
-   * Note: like `getRandomWord()`, this is NOT a fixed catalog — `/icerik`
-   * appears to hand back a single randomly-rotated rule per request, so two
-   * calls a second apart can return entirely different rules. `bypassCache`
-   * (used internally by `getRule()`'s retry loop) forces a fresh `/icerik`
-   * draw even when `enableCache(true)` is on.
-   */
-  public static async getKurallar(bypassCache = false): Promise<TDKRule[]> {
-    const daily = await this.getDailyContent(bypassCache);
-    return daily?.kural ?? [];
-  }
-
-  /**
-   * Fetches the full plain-text content of a named spelling rule (matched
-   * case-insensitively, substring match) from `tdk.gov.tr`. Since `/icerik`
-   * hands back a single randomly-rotated rule per request (out of a pool of
-   * roughly twenty) rather than a fixed catalog, a single `getKurallar()`
-   * draw would rarely match a given name — this re-draws until it finds a
-   * match or gives up. Draws happen in concurrent batches (each `/icerik`
-   * request is independent and stateless) rather than one-at-a-time with a
-   * delay: same total sample size (25) and hit probability as a sequential
-   * loop, but bounded to a handful of round-trips instead of 25 of them, so
-   * a miss resolves in roughly one round-trip time instead of several
-   * seconds. Every draw bypasses `dailyContentCache` — without that, once
-   * `enableCache(true)` is on, every attempt would just re-read the same
-   * cached `/icerik` response and could never find a rule outside whatever
-   * the first draw happened to be. Returns `null` if no match turns up
-   * within the attempt budget or the matched page can't be parsed.
-   */
-  public static async getRule(name: string): Promise<string | null> {
-    if (!name || name.trim() === "") return null;
-    const target = name.trim().toLocaleLowerCase("tr-TR");
-
-    const BATCH_SIZE = 5;
-    const ROUNDS = 5;
-    for (let round = 0; round < ROUNDS; round++) {
-      const batches = await Promise.all(
-        Array.from({ length: BATCH_SIZE }, () => this.getKurallar(true))
-      );
-      for (const rules of batches) {
-        const match = rules.find((r) => r.adi.toLocaleLowerCase("tr-TR").includes(target));
-        if (match) return this.fetchRuleText(match.url);
-      }
-    }
-    return null;
-  }
-
-  /**
-   * `tdk.gov.tr` rule pages are WordPress/Avada-themed. The actual article
-   * text lives in `<div ... itemprop="text">...</div>` right before a
-   * `<footer class="entry...">` (share buttons, author box, structured-data
-   * spans) — cutting there avoids that trailing cruft.
-   */
-  private static async fetchRuleText(url: string): Promise<string | null> {
-    try {
-      const response = await fetch(url, { headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" } });
-      if (!response.ok) return null;
-      const html = await response.text();
-
-      const marker = html.indexOf('itemprop="text"');
-      if (marker === -1) return null;
-      const contentStart = html.indexOf(">", marker) + 1;
-      const contentEnd = html.indexOf("<footer", contentStart);
-      if (contentEnd === -1) return null;
-
-      return this.htmlToPlainText(html.slice(contentStart, contentEnd));
-    } catch {
-      return null;
-    }
-  }
-
-  private static htmlToPlainText(html: string): string {
-    return html
-      .replace(/<br\s*\/?>/gi, "\n")
-      .replace(/<\/(p|div)>/gi, "\n\n")
-      .replace(/<[^>]+>/g, "")
-      .replace(/&nbsp;/gi, " ")
-      .replace(/&lt;/gi, "<")
-      .replace(/&gt;/gi, ">")
-      .replace(/&quot;/gi, '"')
-      .replace(/&#39;|&rsquo;/gi, "'")
-      .replace(/&amp;/gi, "&")
-      .replace(/[ \t]+/g, " ")
-      .replace(/[ \t]*\n[ \t]*/g, "\n")
-      .replace(/\n{3,}/g, "\n\n")
-      .trim();
-  }
-
-  /**
-   * GETs a JSON path from Kubbealtı Lugatı's data API (`eski.lugatim.com`),
-   * supplying `KUBBEALTI_EXTRA_CA` to work around that host's incomplete
-   * certificate chain (see the constant's doc comment). Fails closed to
-   * `null` on any error — network, TLS, HTTP, or JSON parse.
-   */
-  private static fetchKubbealtiJson(path: string): Promise<any> {
-    return new Promise((resolve) => {
-      const req = https.request(
-        {
-          hostname: this.KUBBEALTI_HOST,
-          path,
-          method: "GET",
-          ca: [...tls.rootCertificates, ...this.KUBBEALTI_EXTRA_CA],
-          headers: {
-            "User-Agent":
-              "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36",
-          },
-        },
-        (res) => {
-          if (res.statusCode !== 200) {
-            res.resume();
-            resolve(null);
-            return;
-          }
-          let body = "";
-          res.on("data", (chunk) => (body += chunk));
-          res.on("end", () => {
-            try {
-              resolve(JSON.parse(body));
-            } catch {
-              resolve(null);
-            }
-          });
-        }
-      );
-      req.on("error", () => resolve(null));
-      req.end();
-    });
-  }
-
-  /**
-   * Kubbealtı indexes headwords with full classical Turkish orthography,
-   * including letters that a plain-ASCII-ish query tends to drop — most
-   * commonly ü/ö/ç/ğ/ş, but also the circumflex ("düzeltme işareti") used in
-   * Arabic/Persian loanwords like "rüzgâr". A search for "ruzgar" misses
-   * entirely (verified: even "ruzgâr" alone still misses — it's the missing
-   * ü, not the missing â, that actually breaks the match). This generates
-   * single-letter-substitution variants to retry, one substitution per
-   * variant (not combinatorial) — covers the overwhelmingly common case of
-   * one "de-Turkished" letter without an explosion of API calls for words
-   * with several.
-   */
-  private static readonly TURKISH_DEASCII_MAP: Record<string, string[]> = {
-    a: ["â"],
-    i: ["ı", "î"],
-    o: ["ö"],
-    u: ["ü", "û"],
-    c: ["ç"],
-    g: ["ğ"],
-    s: ["ş"],
-  };
-
-  private static generateTurkishVariants(word: string): string[] {
-    const lower = word.trim().toLocaleLowerCase("tr-TR");
-    const variants: string[] = [];
-    for (let i = 0; i < lower.length; i++) {
-      for (const replacement of this.TURKISH_DEASCII_MAP[lower[i]] ?? []) {
-        variants.push(lower.slice(0, i) + replacement + lower.slice(i + 1));
-      }
-    }
-    return variants;
-  }
-
-  /**
-   * Returns Kubbealtı Lugatı ("Misalli Büyük Türkçe Sözlük") entries for a
-   * word, scraped from the site's own data API — undocumented, and Kubbealtı
-   * Lugatı is a commercial dictionary product, unlike TDK's or Wiktionary's
-   * openly-published data, so use this in line with their terms. `anlam` is
-   * raw HTML (rich typography markup); use `getKubbealtiMeanings()` for
-   * plain text. Falls back to `generateTurkishVariants()` if the exact query
-   * comes up empty (see its doc comment). Returns `null` on any fetch/parse
-   * failure, `[]` if no variant matches either.
-   */
-  public static async getKubbealti(word: string): Promise<KubbealtiEntry[] | null> {
-    if (!word || word.trim() === "") return null;
-
-    const data = await this.fetchKubbealtiJson(`/rest/s/${encodeURIComponent(word.trim())}/`);
-    if (!data || !Array.isArray(data.content)) return null;
-    if (data.content.length > 0) {
-      return data.content.map((entry: any) => ({ kelime: entry.kelime, anlam: entry.anlam }));
-    }
-
-    for (const variant of this.generateTurkishVariants(word)) {
-      const variantData = await this.fetchKubbealtiJson(`/rest/s/${encodeURIComponent(variant)}/`);
-      if (variantData && Array.isArray(variantData.content) && variantData.content.length > 0) {
-        return variantData.content.map((entry: any) => ({ kelime: entry.kelime, anlam: entry.anlam }));
-      }
-    }
-    return [];
-  }
-
-  /**
-   * Same as `getKubbealti()` but with each entry's `anlam` HTML stripped to
-   * plain text via `htmlToPlainText()`.
-   */
-  public static async getKubbealtiMeanings(word: string): Promise<string[] | null> {
-    const entries = await this.getKubbealti(word);
-    if (!entries) return null;
-    return entries.map((e) => this.htmlToPlainText(e.anlam));
-  }
-
-  /**
-   * Autocomplete suggestions from Kubbealtı Lugatı's own typeahead endpoint
-   * (separate from `getSuggestions()`, which uses TDK's data).
-   */
-  public static async getKubbealtiSuggestions(prefix: string): Promise<string[]> {
-    if (!prefix || prefix.trim() === "") return [];
-    const data = await this.fetchKubbealtiJson(`/rest/word-search/${encodeURIComponent(prefix.trim())}`);
-    if (!Array.isArray(data)) return [];
-    return data.map((item: any) => item.display).filter(Boolean);
-  }
-
-  /**
-   * Returns the etymology paragraph for a word from Nişanyan Sözlük, scraped
-   * from that page's server-rendered `<meta name="description">` tag (the
-   * page already puts the full etymology text there for SEO, so no need to
-   * parse the site's internal SvelteKit data format). Returns `null` if the
-   * word isn't found (the page falls back to a generic site tagline in that
-   * case) or the request fails.
-   */
-  public static async getNisanyan(word: string): Promise<string | null> {
-    if (!word || word.trim() === "") return null;
-    try {
-      const response = await fetch(
-        `https://www.nisanyansozluk.com/kelime/${encodeURIComponent(word.trim().toLocaleLowerCase("tr-TR"))}`,
-        { headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" } }
-      );
-      if (!response.ok) return null;
-      const html = await response.text();
-      const match = html.match(/<meta name="description" content="([^"]*)"/);
-      if (!match) return null;
-      const description = this.htmlToPlainText(match[1]);
-      if (description === "Çağdaş Türkçenin Etimolojisi") return null;
-      return description;
-    } catch {
-      return null;
-    }
-  }
-
-  private static async fetchWiktionaryEntry(title: string): Promise<WiktionaryEntry | null> {
-    try {
-      const url = `https://tr.wiktionary.org/w/api.php?action=query&prop=extracts&titles=${encodeURIComponent(
-        title
-      )}&format=json&explaintext=1&formatversion=2`;
-      const response = await fetch(url, { headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" } });
-      if (!response.ok) return null;
-      const data = await response.json();
-      const page = data?.query?.pages?.[0];
-      if (!page || page.missing || !page.extract) return null;
-
-      const raw: string = page.extract;
-      const sections: Record<string, string> = {};
-      const parts = raw.split(/\n(={2,4})\s*(.+?)\s*\1\n/);
-      // parts[0] is text before the first heading (usually empty); after
-      // that, headings and their following text alternate in triples.
-      for (let i = 1; i < parts.length; i += 3) {
-        const title = parts[i + 1]?.trim();
-        const content = parts[i + 2]?.trim();
-        if (title) sections[title] = content ?? "";
-      }
-      return { raw, sections };
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Returns the Turkish Wiktionary (`tr.wiktionary.org`) entry for a word,
-   * via MediaWiki's official Action API (`action=query&prop=extracts`) — no
-   * scraping involved, this is a stable, documented public API. `sections`
-   * splits the plain-text extract on its `== Heading ==`/`=== Heading ===`
-   * markers (e.g. "Köken", "Söyleniş", "Ad") for convenience; `raw` has the
-   * unsplit text. This wiki has title capitalization turned off
-   * ($wgCapitalLinks=false — common for Wiktionaries, since case is
-   * meaningful for a dictionary: "Türkiye" the country vs. a lowercase
-   * common word), so an exact-case miss retries with the first letter
-   * uppercased (Turkish-locale-aware, so "istanbul" tries "İstanbul", not
-   * "Istanbul") before giving up. Returns `null` if neither is found or the
-   * request fails.
-   */
-  public static async getWiktionary(word: string): Promise<WiktionaryEntry | null> {
-    if (!word || word.trim() === "") return null;
-    const trimmed = word.trim();
-
-    const direct = await this.fetchWiktionaryEntry(trimmed);
-    if (direct) return direct;
-
-    const capitalized = trimmed.charAt(0).toLocaleUpperCase("tr-TR") + trimmed.slice(1);
-    if (capitalized === trimmed) return null;
-    return this.fetchWiktionaryEntry(capitalized);
-  }
-
-  /**
-   * Convenience filter over `getWiktionary()`: returns just one section's
-   * text (e.g. `getWiktionarySection(word, "Köken")` for etymology), matched
-   * case-insensitively. Returns `null` if the word or the section isn't found.
-   */
-  public static async getWiktionarySection(word: string, sectionName: string): Promise<string | null> {
-    const entry = await this.getWiktionary(word);
-    if (!entry) return null;
-    const key = Object.keys(entry.sections).find(
-      (k) => k.toLocaleLowerCase("tr-TR") === sectionName.trim().toLocaleLowerCase("tr-TR")
-    );
-    return key ? entry.sections[key] : null;
-  }
-
-  /**
-   * Returns compound words that contain this word.
-   */
-  public static async getCompoundWords(word: string): Promise<string[]> {
-    const results = await this.getWord(word);
-    if (results.length === 0) return [];
-    
-    const compound: string[] = [];
-    for (const result of results) {
-      if (result.birlesikler) {
-        const words = result.birlesikler.split(',').map(w => w.trim());
-        compound.push(...words);
-      }
-    }
-    return [...new Set(compound)];
-  }
-
-  /**
-   * Returns the part of speech (isim, sıfat, zarf vb.).
-   * TDK's `ozelliklerListe` mixes grammatical categories (`tur: "3"`, e.g.
-   * sıfat/zarf/isim) with usage-register tags (`tur: "4"`, e.g. mecaz/argo)
-   * in the same list — only `tur === "3"` entries are actual parts of speech.
-   */
-  public static async getPartOfSpeech(word: string): Promise<string[]> {
-    const results = await this.getWord(word);
-    const pos = new Set<string>();
-
-    for (const result of results) {
-      if (result.anlamlarListe) {
-        for (const anlam of result.anlamlarListe) {
-          if (anlam.ozelliklerListe) {
-            for (const ozellik of anlam.ozelliklerListe) {
-              if (ozellik.tur === "3") pos.add(ozellik.tam_adi);
-            }
-          }
-        }
-      }
-    }
-    if (pos.size === 0 && results.length > 0) {
-      pos.add('isim'); // Default to noun if TDK doesn't specify
-    }
-    return Array.from(pos);
-  }
-
-  /**
-   * Compares two words side by side: meaning count, etymological origin,
-   * syllables and vowel-harmony compliance.
-   */
-  public static async compareWords(a: string, b: string): Promise<WordComparison> {
-    const [meaningsA, meaningsB, originA, originB] = await Promise.all([
-      this.getMeanings(a),
-      this.getMeanings(b),
-      this.getOrigin(a),
-      this.getOrigin(b),
-    ]);
-    return {
-      a: {
-        word: a,
-        meaningCount: meaningsA.length,
-        origin: originA,
-        syllables: this.syllabicate(a),
-        harmony: this.checkVowelHarmony(a),
-        labialHarmony: this.checkLabialHarmony(a),
-      },
-      b: {
-        word: b,
-        meaningCount: meaningsB.length,
-        origin: originB,
-        syllables: this.syllabicate(b),
-        harmony: this.checkVowelHarmony(b),
-        labialHarmony: this.checkLabialHarmony(b),
-      },
-    };
-  }
-
-  private static readonly STOPWORDS = new Set([
-    "ve", "veya", "ile", "ama", "fakat", "ancak", "de", "da", "ki", "bu", "şu", "o",
-    "bir", "çok", "az", "gibi", "için", "mi", "mı", "mu", "mü", "ne", "her", "hiç",
-    "ben", "sen", "biz", "siz", "onlar", "değil", "bile", "diye",
-  ]);
-
-  private static firstMeaning(results: WordInfo[]): string | null {
-    for (const result of results) {
-      for (const anlam of result.anlamlarListe ?? []) {
-        if (anlam.anlam) return anlam.anlam;
-      }
-    }
-    return null;
-  }
-
-  /**
-   * Analyzes every distinct word in a text (Turkish stopwords filtered out),
-   * returning each word's first meaning and etymological origin if found.
-   * Looks each word up individually (throttled), so scales with text length.
-   * TDK only indexes dictionary (dictionary/root) forms, not inflected ones —
-   * it does no morphological analysis, and neither does this method: a
-   * suffixed word like "evde" or "dildir" (root "ev"/"dil" plus a case/verb
-   * suffix) will come back `found: false` even though the root is a real
-   * headword. This is an inherent limitation of the data source, not a bug.
-   */
-  public static async analyzeText(text: string): Promise<WordAnalysis[]> {
-    const words = text
-      .toLocaleLowerCase("tr-TR")
-      .replace(/[^\p{L}\s]/gu, " ")
-      .split(/\s+/)
-      .filter((w) => w.length > 1 && !this.STOPWORDS.has(w));
-    const unique = [...new Set(words)];
-
-    const analyses: WordAnalysis[] = [];
-    for (const word of unique) {
-      let results = await this.getWord(word);
-      let found = results.length > 0;
-      let root: string | undefined;
-      let isInflected: boolean | undefined;
-
-      if (!found) {
-        const resolvedRoot = await this.findRoot(word);
-        if (resolvedRoot) {
-          results = await this.getWord(resolvedRoot);
-          if (results.length > 0) {
-            found = true;
-            root = resolvedRoot;
-            isInflected = true;
-          }
-        }
-      }
-
-      analyses.push({
-        word,
-        found,
-        meaning: found ? this.firstMeaning(results) : null,
-        origin: found ? results[0].lisan || "Türkçe" : null,
-        root,
-        isInflected,
-      });
-      await this.delay(200);
-    }
-    return analyses;
-  }
-
-  /**
-   * Damerau-Levenshtein edit-distance (optimal string alignment variant):
-   * like classic Levenshtein but also counts an adjacent-character
-   * transposition (e.g. "yanlız" -> "yalnız") as a single edit instead of
-   * two substitutions — a very common class of typo that plain Levenshtein
-   * otherwise misses.
-   */
-  private static damerauLevenshtein(a: string, b: string): number {
-    const dp: number[][] = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
-    for (let i = 0; i <= a.length; i++) dp[i][0] = i;
-    for (let j = 0; j <= b.length; j++) dp[0][j] = j;
-    for (let i = 1; i <= a.length; i++) {
-      for (let j = 1; j <= b.length; j++) {
-        const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-        dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
-        if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
-          dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + cost);
-        }
-      }
-    }
-    return dp[a.length][b.length];
-  }
-
-  /**
-   * Fetches multiple words concurrently with a small delay to avoid rate limiting.
-   */
-  public static async getWordsBatch(words: string[]): Promise<WordInfo[][]> {
-    const results: WordInfo[][] = [];
-    for (const word of words) {
-      try {
-        const res = await this.getWord(word);
-        results.push(res);
-      } catch {
-        results.push([]);
-      }
-      await this.delay(200); // 200ms throttle
-    }
-    return results;
-  }
-
-  /**
-   * Syllabicates a Turkish word based on general grammar rules.
-   * Handles syllable separation for vowels, single consonants, double consonants,
-   * and western loanword three-consonant clusters (e.g. e-lek-trik, kon-trol, or-kes-tra).
-   */
-  public static syllabicate(word: string): string[] {
-    const vowels = /[aeıioöuüAEIİOÖUÜ]/;
-    const ONSET_CLUSTERS = new Set(["tr", "pr", "kr", "gr", "br", "fr", "dr", "pl", "kl", "fl", "bl", "gl"]);
-    const result: string[] = [];
-    let currentSyllable = "";
-    
-    // Go from right to left.
-    for (let i = word.length - 1; i >= 0; i--) {
-      currentSyllable = word[i] + currentSyllable;
-      if (vowels.test(word[i])) {
-        // If the preceding char is a consonant and it's not the first char
-        // and the char before that is a vowel, then the consonant belongs to this syllable.
-        if (i - 1 >= 0 && !vowels.test(word[i - 1])) {
-          // It's a consonant.
-          if (i - 2 >= 0 && vowels.test(word[i - 2])) {
-            currentSyllable = word[i - 1] + currentSyllable;
-            i--; // skip the consonant
-          } else if (i - 2 >= 0 && !vowels.test(word[i - 2])) {
-            // Two consonants before this vowel. Check if three consonants exist and end in an onset cluster
-            if (i - 3 >= 0 && !vowels.test(word[i - 3]) && ONSET_CLUSTERS.has((word[i - 2] + word[i - 1]).toLowerCase())) {
-              currentSyllable = word[i - 2] + word[i - 1] + currentSyllable;
-              i -= 2;
-            } else {
-              currentSyllable = word[i - 1] + currentSyllable;
-              i--;
-            }
-          }
-        }
-        result.unshift(currentSyllable);
-        currentSyllable = "";
-      }
-    }
-    // If there is anything left (e.g. no vowels at the start like "tr"), add it to the first syllable
-    if (currentSyllable) {
-      if (result.length > 0) {
-        result[0] = currentSyllable + result[0];
-      } else {
-        result.push(currentSyllable);
-      }
-    }
-    return result;
-  }
-
-  /**
-   * Checks if a word follows Turkish Major Vowel Harmony (Büyük Ünlü Uyumu).
-   * Normalizes case via the Turkish locale first: a plain case-insensitive
-   * regex would fold ASCII "I" to "i", misreading the back vowel "I"
-   * (dotless) as the front vowel "i" (dotted).
-   */
-  public static checkVowelHarmony(word: string): boolean {
-    const lower = word.toLocaleLowerCase("tr-TR");
-    const backVowels = /[aıou]/;
-    const frontVowels = /[eiöü]/;
-    const hasBack = backVowels.test(lower);
-    const hasFront = frontVowels.test(lower);
-
-    // If it has both front and back vowels, it breaks harmony.
-    return !(hasBack && hasFront);
-  }
-
-  /**
-   * Checks if a word follows Turkish Minor Vowel Harmony (Küçük Ünlü Uyumu / Labial Harmony).
-   * Rules:
-   * 1. After an unrounded vowel (a, e, ı, i), only unrounded vowels (a, e, ı, i) can follow.
-   * 2. After a rounded vowel (o, ö, u, ü), either an unrounded wide (a, e) or rounded narrow (u, ü) vowel can follow.
-   * Single-syllable words and words with <=1 vowel are considered compliant by convention.
-   */
-  public static checkLabialHarmony(word: string): boolean {
-    const lower = word.toLocaleLowerCase("tr-TR");
-    const vowels = lower.split("").filter((ch) => "aeıioöuü".includes(ch));
-    if (vowels.length <= 1) return true;
-
-    for (let i = 0; i < vowels.length - 1; i++) {
-      const v1 = vowels[i];
-      const v2 = vowels[i + 1];
-
-      if ("aeıi".includes(v1)) {
-        if (!"aeıi".includes(v2)) return false;
-      } else if ("oöuü".includes(v1)) {
-        if (!"aeuü".includes(v2)) return false;
-      }
-    }
-    return true;
-  }
-
-  /**
-   * Searches TDK headwords using a wildcard / pattern string.
-   * Wildcards:
-   *   '_' or '?' matches any single character
-   *   '*' matches zero or more characters
-   * Example: "k_l_m" matches "kalem", "kelam", "kilim".
-   * Runs in-memory against TDK's 81k headword list.
-   */
-  public static async patternSearch(pattern: string, options?: PatternSearchOptions): Promise<string[]> {
-    if (!pattern || pattern.trim() === "") return [];
-    await this.ensureAutocompleteLoaded();
-
-    const cleanPattern = pattern.trim().toLocaleLowerCase("tr-TR");
-    const escaped = cleanPattern
-      .replace(/[.+^${}()|[\]\\]/g, "\\$&")
-      .replace(/[_?]/g, "[\\p{L}]")
-      .replace(/\*/g, "[\\p{L}]*");
-    const regex = new RegExp(`^${escaped}$`, "u");
-
-    const max = options?.maxResults ?? 50;
-    const matches: string[] = [];
-
-    for (const headword of this.autocompleteCache) {
-      const lower = headword.toLocaleLowerCase("tr-TR");
-      if (regex.test(lower)) {
-        matches.push(headword);
-        if (matches.length >= max) break;
-      }
-    }
-    return matches;
-  }
-
-  /**
-   * Finds headwords in TDK that can be formed from the given letters (anagrams).
-   * If exact-length anagrams exist, they are returned.
-   * If none exist (or exactLength is false), valid sub-anagrams (words using a subset of the letters,
-   * minimum 3 letters) are returned, sorted by length descending.
-   */
-  public static async findAnagrams(letters: string, options?: AnagramOptions): Promise<string[]> {
-    if (!letters || letters.trim() === "") return [];
-    await this.ensureAutocompleteLoaded();
-
-    const clean = letters.trim().toLocaleLowerCase("tr-TR").replace(/[^a-zçğıöşüâîû]/gi, "");
-    if (clean.length === 0) return [];
-
-    const forceExact = options?.exactLength === true;
-    const max = options?.maxResults ?? 50;
-
-    const getFrequency = (str: string): Record<string, number> => {
-      const freq: Record<string, number> = {};
-      for (const ch of str) {
-        freq[ch] = (freq[ch] || 0) + 1;
-      }
-      return freq;
-    };
-
-    const targetFreq = getFrequency(clean);
-    const exactMatches: string[] = [];
-    const subMatches: string[] = [];
-
-    for (const headword of this.autocompleteCache) {
-      const lower = headword.toLocaleLowerCase("tr-TR");
-      if (lower.includes(" ") || lower.includes("-")) continue;
-      if (lower.length > clean.length || lower.length < 3) continue;
-
-      const wordFreq = getFrequency(lower);
-      let isValid = true;
-      for (const [ch, count] of Object.entries(wordFreq)) {
-        if (!targetFreq[ch] || targetFreq[ch] < count) {
-          isValid = false;
-          break;
-        }
-      }
-
-      if (isValid && lower !== clean) {
-        if (lower.length === clean.length) {
-          exactMatches.push(headword);
-        } else {
-          subMatches.push(headword);
-        }
-      }
-    }
-
-    if (exactMatches.length > 0 || forceExact) {
-      return exactMatches.slice(0, max);
-    }
-
-    subMatches.sort((a, b) => b.length - a.length || a.localeCompare(b, "tr-TR"));
-    return subMatches.slice(0, max);
-  }
-
-  /**
-   * Finds words in TDK that rhyme with the given word (sharing the same ending suffix/letters).
-   * @param word The target word
-   * @param options.minLetters Minimum number of ending characters that must match (default: 3)
-   * @param options.maxResults Maximum number of rhyme results to return (default: 50)
-   */
-  public static async findRhymes(word: string, options?: RhymeOptions): Promise<string[]> {
-    if (!word || word.trim() === "") return [];
-    await this.ensureAutocompleteLoaded();
-
-    const clean = word.trim().toLocaleLowerCase("tr-TR");
-    const minLetters = Math.min(options?.minLetters ?? 3, clean.length);
-    const max = options?.maxResults ?? 50;
-
-    const suffix = clean.slice(-minLetters);
-    const results: string[] = [];
-
-    for (const headword of this.autocompleteCache) {
-      const lower = headword.toLocaleLowerCase("tr-TR");
-      if (lower !== clean && lower.endsWith(suffix) && !lower.includes(" ")) {
-        results.push(headword);
-        if (results.length >= max) break;
-      }
-    }
-
-    return results;
-  }
-
-  /**
-   * Performs comprehensive spelling, grammar, and syntax proofreading on a Turkish text.
-   * Detects:
-   * 1. Conjunction 'da/de' erroneously joined to verbs or words (e.g. "gitsende" -> "gitsen de")
-   * 2. Conjunction 'ki' erroneously joined to verbs (e.g. "gördümki" -> "gördüm ki"), respecting SOMBAHÇEMİ exceptions
-   * 3. Question particle 'mi/mı/mu/mü' erroneously joined to words (e.g. "geldimi" -> "geldi mi")
-   * 4. Misspelled words with dictionary suggestions (via edit-distance & morphology)
-   */
-  public static async proofread(text: string): Promise<ProofreadResult> {
-    if (!text || text.trim() === "") {
-      return { text: text || "", issues: [], isCorrect: true };
-    }
-
-    await this.ensureAutocompleteLoaded();
-    const issues: ProofreadIssue[] = [];
-
-    const SOMBAHCEMI = new Set([
-      "sanki", "oysaki", "mademki", "belki", "halbuki", "çünkü", "meğerki", "illaki"
-    ]);
-
-    // 1. Detect multi-word phrases that should be written as single compound words
-    const PHRASE_MISTAKES: {
-      regex: RegExp;
-      suggestion: string;
-      message: string;
-      type: ProofreadIssue["type"];
-    }[] = [
-      {
-        regex: /\bhiç\s+bir\b/gi,
-        suggestion: "hiçbir",
-        message: "'hiçbir' belgisiz sıfatı bitişik yazılmalıdır.",
-        type: "spelling",
-      },
-      {
-        regex: /\bbir\s+çok\b/gi,
-        suggestion: "birçok",
-        message: "'birçok' belgisiz sıfatı/zamiri bitişik yazılmalıdır.",
-        type: "spelling",
-      },
-      {
-        regex: /\bbir\s+kaç\b/gi,
-        suggestion: "birkaç",
-        message: "'birkaç' belgisiz sıfatı/zamiri bitişik yazılmalıdır.",
-        type: "spelling",
-      },
-      {
-        regex: /\bbir\s+az\b/gi,
-        suggestion: "biraz",
-        message: "'biraz' sözcüğü bitişik yazılmalıdır.",
-        type: "spelling",
-      },
-      {
-        regex: /\bher\s+hangi\b/gi,
-        suggestion: "herhangi",
-        message: "'herhangi' sözcüğü bitişik yazılmalıdır.",
-        type: "spelling",
-      },
-      {
-        regex: /\bgit\s+gide\b/gi,
-        suggestion: "gitgide",
-        message: "'gitgide' zarfı bitişik yazılmalıdır.",
-        type: "spelling",
-      },
-      {
-        regex: /\bbirden\s+bire\b/gi,
-        suggestion: "birdenbire",
-        message: "'birdenbire' zarfı bitişik yazılmalıdır.",
-        type: "spelling",
-      },
-      {
-        regex: /\brast\s+gele\b/gi,
-        suggestion: "rastgele",
-        message: "'rastgele' zarfı bitişik yazılmalıdır.",
-        type: "spelling",
-      },
-    ];
-
-    const coveredRanges: { start: number; end: number }[] = [];
-    for (const pm of PHRASE_MISTAKES) {
-      let pmMatch: RegExpExecArray | null;
-      while ((pmMatch = pm.regex.exec(text)) !== null) {
-        const start = pmMatch.index;
-        const end = start + pmMatch[0].length;
-        coveredRanges.push({ start, end });
-        issues.push({
-          type: pm.type,
-          word: pmMatch[0],
-          startIndex: start,
-          endIndex: end,
-          suggestion: pm.suggestion,
-          message: pm.message,
-        });
-      }
-    }
-
-    const tokenRegex = /[\p{L}0-9'’]+/gu;
-    let match: RegExpExecArray | null;
-
-    while ((match = tokenRegex.exec(text)) !== null) {
-      const rawWord = match[0];
-      const startIndex = match.index;
-      const endIndex = startIndex + rawWord.length;
-      const lower = rawWord.toLocaleLowerCase("tr-TR");
-
-      if (/^\d+$/.test(lower)) continue;
-      if (coveredRanges.some((r) => startIndex >= r.start && endIndex <= r.end)) continue;
-
-      let flagged = false;
-
-      // 1. Check Question Particle (mı, mi, mu, mü) erroneously attached
-      const questionMatch = lower.match(/^(.+?)(m[ıiuü](?:sin|sın|sun|sün|siniz|sınız|sunuz|sünüz|yiz|yız|yuz|yüz|m|k)?)$/);
-      if (questionMatch) {
-        const base = questionMatch[1];
-        const particle = questionMatch[2];
-        if (base.length >= 2 && (await this.isHeadword(base) || (await this.findRoot(base)) !== null)) {
-          if (!(await this.isHeadword(lower))) {
-            issues.push({
-              type: "question_particle",
-              word: rawWord,
-              startIndex,
-              endIndex,
-              suggestion: `${base} ${particle}`,
-              message: `'${particle}' soru eki kendinden önceki kelimeden ayrı yazılmalıdır.`,
-            });
-            flagged = true;
-          }
-        }
-      }
-
-      const VERB_CONJUGATION_REGEX =
-        /(?:d[ıiuü][kmmn]?|t[ıiuü][kmmn]?|d[ıiuü]n[ıiuü]z?|t[ıiuü]n[ıiuü]z?|m[ıiuü]ş(?:[szn][ıiuü]z?|lar)?|yor(?:um|sun|uz|lar)?|ecek(?:sin|iz|ler)?|acak(?:sın|ız|lar)?|s[ae][mnk]|s[ae]n[ıiz]?|meli|malı|me[mz]|ma[mz])$/i;
-
-      // 2. Check Conjunction 'ki' erroneously attached to verbs
-      if (!flagged && lower.endsWith("ki") && lower.length > 3) {
-        const base = lower.slice(0, -2);
-        if (!SOMBAHCEMI.has(lower)) {
-          if (!(await this.isHeadword(lower))) {
-            const root = await this.findRoot(base);
-            const isVerb =
-              (base === "demek" || base === "kaldı" || base === "yeter" || base === "bilmem" || VERB_CONJUGATION_REGEX.test(base)) &&
-              (root ? root.endsWith("mek") || root.endsWith("mak") : true);
-
-            if (isVerb) {
-              issues.push({
-                type: "conjunction_ki",
-                word: rawWord,
-                startIndex,
-                endIndex,
-                suggestion: `${base} ki`,
-                message: `'ki' bağlacı ayrı yazılmalıdır.`,
-              });
-              flagged = true;
-            }
-          }
-        }
-      }
-
-      // 3. Check Conjunction 'da/de/ta/te' erroneously attached to verbs
-      if (!flagged && (lower.endsWith("de") || lower.endsWith("da") || lower.endsWith("te") || lower.endsWith("ta")) && lower.length > 3) {
-        const base = lower.slice(0, -2);
-        const ending = lower.slice(-2);
-        if (!(await this.isHeadword(lower))) {
-          const root = await this.findRoot(base);
-          const isVerb =
-            VERB_CONJUGATION_REGEX.test(base) &&
-            (root ? root.endsWith("mek") || root.endsWith("mak") : false);
-
-          if (isVerb) {
-            const correctEnding = ending.startsWith("t") ? (ending === "te" ? "de" : "da") : ending;
-            issues.push({
-              type: "conjunction_da",
-              word: rawWord,
-              startIndex,
-              endIndex,
-              suggestion: `${base} ${correctEnding}`,
-              message: `'da/de' bağlacı fiillerden sonra her zaman ayrı yazılır (bağlaç olan da/de sertleşmez).`,
-            });
-            flagged = true;
-          }
-        }
-      }
-
-      // 4. Check -şey / -sey erroneously attached to preceding word
-      const seyMatch = lower.match(/^(.+?)(?:şey|sey)([ıiuaeüodekmnl]+)?$/);
-      if (!flagged && seyMatch && !SEY_EXCEPTIONS.has(lower)) {
-        let prefix = seyMatch[1];
-        const suffix = seyMatch[2] || "";
-        if (prefix === "hicbir") prefix = "hiçbir";
-        if (prefix === "cok") prefix = "çok";
-        issues.push({
-          type: "spelling",
-          word: rawWord,
-          startIndex,
-          endIndex,
-          suggestion: `${prefix} şey${suffix}`,
-          message: "'şey' sözcüğü kendinden önceki kelimeden ayrı yazılmalıdır.",
-        });
-        flagged = true;
-      }
-
-      // 5. Check 'yada' conjunction mistake
-      if (!flagged && lower === "yada") {
-        issues.push({
-          type: "spelling",
-          word: rawWord,
-          startIndex,
-          endIndex,
-          suggestion: "ya da",
-          message: "'ya da' bağlacı her zaman ayrı yazılır.",
-        });
-        flagged = true;
-      }
-
-      // 6. Check common vowel drop mistakes: burda, şurda, orda, vb. (TDK Kural 15)
-      if (!flagged && (lower === "burda" || lower === "şurda" || lower === "surda" || lower === "orda" || lower === "içerde" || lower === "icerde" || lower === "dışarda" || lower === "disarda" || lower === "yukarda")) {
-        const correct = COMMON_MISSPELLINGS[lower] || lower;
-        issues.push({
-          type: "spelling",
-          word: rawWord,
-          startIndex,
-          endIndex,
-          suggestion: correct,
-          message: `'${rawWord}' sözcüğünde ünlü düşmesi yapılmaz.`,
-        });
-        flagged = true;
-      }
-
-      // 7. General Spell Check
-      if (!flagged) {
-        const check = await this.checkSpelling(rawWord);
-        if (!check.isCorrect) {
-          issues.push({
-            type: "spelling",
-            word: rawWord,
-            startIndex,
-            endIndex,
-            suggestion: check.suggestion,
-            message: check.suggestion
-              ? `'${rawWord}' yanlış yazılmış olabilir.`
-              : `'${rawWord}' sözlükte bulunamadı.`,
-          });
-        }
-      }
-    }
-
-    issues.sort((a, b) => a.startIndex - b.startIndex);
-
-    return {
-      text,
-      issues,
-      isCorrect: issues.length === 0,
-    };
-  }
-}
-
-/**
- * Configurable instance-based client for TDK API.
- * Useful for multi-tenant applications or backend services requiring isolated configurations.
- */
-export class TDKClient {
-  constructor(config?: TDKConfig) {
-    if (config) {
-      TDK.configure(config);
-    }
-  }
-
-  public getWord(word: string): Promise<WordInfo[]> {
-    return TDK.getWord(word);
-  }
-
-  public getMeanings(word: string): Promise<string[]> {
-    return TDK.getMeanings(word);
-  }
-
-  public checkSpelling(word: string): Promise<SpellCheckResult> {
-    return TDK.checkSpelling(word);
-  }
-
-  public findRoot(word: string): Promise<string | null> {
-    return TDK.findRoot(word);
-  }
-
-  public stem(word: string): Promise<StemResult | null> {
-    return TDK.stem(word);
-  }
-
-  public proofread(text: string): Promise<ProofreadResult> {
-    return TDK.proofread(text);
-  }
-
-  public patternSearch(pattern: string, options?: PatternSearchOptions): Promise<string[]> {
-    return TDK.patternSearch(pattern, options);
-  }
-
-  public findAnagrams(letters: string, options?: AnagramOptions): Promise<string[]> {
-    return TDK.findAnagrams(letters, options);
-  }
-
-  public findRhymes(word: string, options?: RhymeOptions): Promise<string[]> {
-    return TDK.findRhymes(word, options);
-  }
-
-  public syllabicate(word: string): string[] {
-    return TDK.syllabicate(word);
-  }
-
-  public checkVowelHarmony(word: string): boolean {
-    return TDK.checkVowelHarmony(word);
-  }
-
-  public checkLabialHarmony(word: string): boolean {
-    return TDK.checkLabialHarmony(word);
-  }
-}
-