tdk-api-wrapper 1.0.1 → 1.1.0

package/dist/index.js

@@ -30,16 +30,48 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  TDK: () => TDK
+  TDK: () => TDK,
+  TDKError: () => TDKError,
+  TDKNetworkError: () => TDKNetworkError,
+  TDKValidationError: () => TDKValidationError
 });
 module.exports = __toCommonJS(src_exports);
 
+// src/errors.ts
+var TDKError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TDKError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var TDKValidationError = class extends TDKError {
+  constructor(message) {
+    super(message);
+    this.name = "TDKValidationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var TDKNetworkError = class extends TDKError {
+  status;
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = "TDKNetworkError";
+    this.status = options?.status;
+    this.cause = options?.cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
 // src/tdk.ts
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
 var os = __toESM(require("os"));
+var https = __toESM(require("https"));
 var TDK = class {
   static BASE_URL = "https://sozluk.gov.tr";
+  static AUDIO_API_HOST = "api.sozluk.gov.tr";
   // Cache Mechanism
   static isCacheEnabled = false;
   static wordCache = /* @__PURE__ */ new Map();
@@ -70,35 +102,42 @@ var TDK = class {
    */
   static async getWord(word) {
     if (!word || word.trim() === "") {
-      throw new Error("Word parameter cannot be empty.");
+      throw new TDKValidationError("Word parameter cannot be empty.");
     }
-    const cleanWord = word.trim().toLowerCase();
+    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;
     try {
-      const response = await fetch(url, {
+      response = await fetch(url, {
         headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" }
       });
-      if (!response.ok)
-        throw new Error(`HTTP error! status: ${response.status}`);
-      const data = await response.json();
-      if (!Array.isArray(data) && data && "error" in data) {
-        if (this.isCacheEnabled)
-          this.wordCache.set(cleanWord, []);
-        return [];
-      }
-      const results = data;
-      if (this.isCacheEnabled) {
-        this.wordCache.set(cleanWord, results);
-      }
-      return results;
     } catch (error) {
-      if (error instanceof Error)
-        throw new Error(`Failed to fetch word from TDK: ${error.message}`);
-      throw new Error("Failed to fetch word from TDK: Unknown 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;
+    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) {
+      if (this.isCacheEnabled)
+        this.wordCache.set(cleanWord, []);
+      return [];
+    }
+    const results = data;
+    if (this.isCacheEnabled) {
+      this.wordCache.set(cleanWord, results);
+    }
+    return results;
   }
   /**
    * Helper method to get only the meanings (definitions) of a word as a string array.
@@ -135,8 +174,8 @@ var TDK = class {
         return [];
       }
     }
-    const cleanPrefix = prefix.toLowerCase();
-    return this.autocompleteCache.filter((w) => w.toLowerCase().startsWith(cleanPrefix)).slice(0, 10);
+    const cleanPrefix = prefix.toLocaleLowerCase("tr-TR");
+    return this.autocompleteCache.filter((w) => w.toLocaleLowerCase("tr-TR").startsWith(cleanPrefix)).slice(0, 10);
   }
   /**
    * Returns a list of proverbs and idioms containing the word.
@@ -157,14 +196,40 @@ var TDK = class {
     return proverbs;
   }
   /**
-   * Returns the etymological origin of the word if it's a foreign word.
+   * 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.
    */
   static async getOrigin(word) {
     const results = await this.getWord(word);
-    if (results.length > 0 && results[0].lisan) {
-      return results[0].lisan;
+    if (results.length === 0)
+      return null;
+    return results[0].lisan || "T\xFCrk\xE7e";
+  }
+  /**
+   * Returns whether the word has a recorded foreign etymological origin.
+   * Returns `null` (instead of a boolean) when the word isn't found at all.
+   */
+  static async isForeignWord(word) {
+    const origin = await this.getOrigin(word);
+    if (origin === null)
+      return null;
+    return origin !== "T\xFCrk\xE7e";
+  }
+  /**
+   * Groups a list of words by their etymological origin. Words not found in
+   * the dictionary are grouped under "Bilinmiyor". Throttled like getWordsBatch.
+   */
+  static async groupByOrigin(words) {
+    const groups = {};
+    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 "T\xFCrk\xE7e";
+    return groups;
   }
   /**
    * Returns literature examples containing the word.
@@ -187,15 +252,108 @@ var TDK = class {
     return examples;
   }
   /**
-   * Returns the direct URL of the audio pronunciation if available.
-   * Note: TDK audio URL usually uses the exact audio id. Sometimes it requires MD5, but we provide a common pattern.
+   * 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.
+   */
+  static fetchGtsYeni(word) {
+    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();
+    });
+  }
+  static async fetchSeskod(word) {
+    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.
+   */
+  static async getSynonyms(word) {
+    if (!word || word.trim() === "")
+      return [];
+    const data = await this.fetchGtsYeni(word.trim().toLocaleLowerCase("tr-TR"));
+    if (!data)
+      return [];
+    const synonyms = [];
+    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.
+   */
+  static async getAntonyms(word) {
+    if (!word || word.trim() === "")
+      return [];
+    const data = await this.fetchGtsYeni(word.trim().toLocaleLowerCase("tr-TR"));
+    if (!data)
+      return [];
+    const antonyms = [];
+    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.
    */
   static async getAudioUrl(word) {
-    const results = await this.getWord(word);
-    if (results.length > 0) {
-      return `https://sozluk.gov.tr/ses/${encodeURIComponent(word)}.wav`;
+    if (!word || word.trim() === "") {
+      throw new TDKValidationError("Word parameter cannot be empty.");
     }
-    return null;
+    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.
@@ -226,14 +384,29 @@ var TDK = class {
     }
     const daily = await this.getDailyContent();
     if (daily) {
-      const syydMatch = daily.syyd.find((s) => s.yanliskelime.toLowerCase() === word.toLowerCase());
+      const syydMatch = daily.syyd.find((s) => s.yanliskelime.toLocaleLowerCase("tr-TR") === word.toLocaleLowerCase("tr-TR"));
       if (syydMatch) {
         return { isCorrect: false, word, suggestion: syydMatch.dogrukelime };
       }
-      const mixMatch = daily.karistirma.find((s) => s.yanlis.toLowerCase() === word.toLowerCase());
+      const mixMatch = daily.karistirma.find((s) => s.yanlis.toLocaleLowerCase("tr-TR") === word.toLocaleLowerCase("tr-TR"));
       if (mixMatch) {
         return { isCorrect: false, word, suggestion: mixMatch.dogru };
       }
+      const candidates = [
+        ...daily.syyd.map((s) => s.dogrukelime),
+        ...daily.karistirma.flatMap((s) => [s.yanlis, s.dogru]),
+        ...daily.kelime.map((k) => k.madde)
+      ];
+      let best = null;
+      for (const candidate of candidates) {
+        const distance = this.levenshtein(word.toLocaleLowerCase("tr-TR"), candidate.toLocaleLowerCase("tr-TR"));
+        if (distance > 0 && (!best || distance < best.distance)) {
+          best = { candidate, distance };
+        }
+      }
+      if (best && best.distance <= 2) {
+        return { isCorrect: false, word, suggestion: best.candidate };
+      }
     }
     return { isCorrect: false, word };
   }
@@ -258,6 +431,94 @@ var TDK = class {
     }
     return null;
   }
+  /**
+   * Returns today's word of the day along with all of its listed meanings.
+   */
+  static async getWordOfTheDay() {
+    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.
+   */
+  static async getRandomWord() {
+    const daily = await this.getDailyContent();
+    if (!daily)
+      return null;
+    const pool = [
+      ...daily.kelime.map((k) => ({ type: "kelime", madde: k.madde, anlam: k.anlam })),
+      ...daily.atasoz.map((a) => ({ type: "atasoz", 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.
+   */
+  static async getKurallar() {
+    const daily = await this.getDailyContent();
+    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 (bounded, with a
+   * short delay) until it finds a match or gives up. Returns `null` if no
+   * match turns up within the attempt budget or the matched page can't be
+   * parsed.
+   */
+  static async getRule(name) {
+    if (!name || name.trim() === "")
+      return null;
+    const target = name.trim().toLocaleLowerCase("tr-TR");
+    for (let attempt = 0; attempt < 25; attempt++) {
+      const rules = await this.getKurallar();
+      const match = rules.find((r) => r.adi.toLocaleLowerCase("tr-TR").includes(target));
+      if (match)
+        return this.fetchRuleText(match.url);
+      await this.delay(100);
+    }
+    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.
+   */
+  static async fetchRuleText(url) {
+    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;
+    }
+  }
+  static htmlToPlainText(html) {
+    return html.replace(/<br\s*\/?>/gi, "\n").replace(/<\/(p|div)>/gi, "\n\n").replace(/<[^>]+>/g, "").replace(/&nbsp;/gi, " ").replace(/&amp;/gi, "&").replace(/&quot;/gi, '"').replace(/&#39;|&rsquo;/gi, "'").replace(/[ \t]+/g, " ").replace(/[ \t]*\n[ \t]*/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+  }
   /**
    * Returns compound words that contain this word.
    */
@@ -276,6 +537,9 @@ var TDK = class {
   }
   /**
    * 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.
    */
   static async getPartOfSpeech(word) {
     const results = await this.getWord(word);
@@ -285,7 +549,8 @@ var TDK = class {
         for (const anlam of result.anlamlarListe) {
           if (anlam.ozelliklerListe) {
             for (const ozellik of anlam.ozelliklerListe) {
-              pos.add(ozellik.tam_adi);
+              if (ozellik.tur === "3")
+                pos.add(ozellik.tam_adi);
             }
           }
         }
@@ -296,6 +561,116 @@ var TDK = class {
     }
     return Array.from(pos);
   }
+  /**
+   * Compares two words side by side: meaning count, etymological origin,
+   * syllables and vowel-harmony compliance.
+   */
+  static async compareWords(a, b) {
+    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)
+      },
+      b: {
+        word: b,
+        meaningCount: meaningsB.length,
+        origin: originB,
+        syllables: this.syllabicate(b),
+        harmony: this.checkVowelHarmony(b)
+      }
+    };
+  }
+  static STOPWORDS = /* @__PURE__ */ new Set([
+    "ve",
+    "veya",
+    "ile",
+    "ama",
+    "fakat",
+    "ancak",
+    "de",
+    "da",
+    "ki",
+    "bu",
+    "\u015Fu",
+    "o",
+    "bir",
+    "\xE7ok",
+    "az",
+    "gibi",
+    "i\xE7in",
+    "mi",
+    "m\u0131",
+    "mu",
+    "m\xFC",
+    "ne",
+    "her",
+    "hi\xE7",
+    "ben",
+    "sen",
+    "biz",
+    "siz",
+    "onlar",
+    "de\u011Fil",
+    "bile",
+    "diye"
+  ]);
+  static firstMeaning(results) {
+    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.
+   */
+  static async analyzeText(text) {
+    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 = [];
+    for (const word of unique) {
+      const results = await this.getWord(word);
+      const found = results.length > 0;
+      analyses.push({
+        word,
+        found,
+        meaning: found ? this.firstMeaning(results) : null,
+        origin: found ? results[0].lisan || "T\xFCrk\xE7e" : null
+      });
+      await this.delay(200);
+    }
+    return analyses;
+  }
+  /**
+   * Classic edit-distance between two strings.
+   */
+  static levenshtein(a, b) {
+    const dp = 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);
+      }
+    }
+    return dp[a.length][b.length];
+  }
   /**
    * Fetches multiple words concurrently with a small delay to avoid rate limiting.
    */
@@ -346,16 +721,23 @@ var TDK = class {
   }
   /**
    * 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).
    */
   static checkVowelHarmony(word) {
-    const backVowels = /[aıou]/i;
-    const frontVowels = /[eiöü]/i;
-    const hasBack = backVowels.test(word);
-    const hasFront = frontVowels.test(word);
+    const lower = word.toLocaleLowerCase("tr-TR");
+    const backVowels = /[aıou]/;
+    const frontVowels = /[eiöü]/;
+    const hasBack = backVowels.test(lower);
+    const hasFront = frontVowels.test(lower);
     return !(hasBack && hasFront);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  TDK
+  TDK,
+  TDKError,
+  TDKNetworkError,
+  TDKValidationError
 });

package/dist/index.mjs

@@ -1,6 +1,12 @@
 import {
-  TDK
-} from "./chunk-MGSXCUAX.mjs";
+  TDK,
+  TDKError,
+  TDKNetworkError,
+  TDKValidationError
+} from "./chunk-P3GX7I53.mjs";
 export {
-  TDK
+  TDK,
+  TDKError,
+  TDKNetworkError,
+  TDKValidationError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tdk-api-wrapper",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "TDK (Türk Dil Kurumu) unofficial live data API wrapper for Node.js",
   "main": "dist/index.js",
   "module": "dist/index.mjs",