tdk-api-wrapper 1.0.1 → 1.1.0

package/src/tdk.ts

@@ -1,14 +1,26 @@
-import type { WordInfo, DailyContent, SpellCheckResult } from "./types";
+import type {
+  WordInfo,
+  DailyContent,
+  SpellCheckResult,
+  WordOfTheDay,
+  DailyPick,
+  WordComparison,
+  WordAnalysis,
+  TDKRule,
+} from "./types";
+import { TDKValidationError, TDKNetworkError } from "./errors";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
+import * as https from "node:https";
 
 /**
  * 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";
+
   // Cache Mechanism
   private static isCacheEnabled = false;
   private static wordCache = new Map<string, WordInfo[]>();
@@ -43,10 +55,10 @@ export class TDK {
    */
   public static async getWord(word: string): Promise<WordInfo[]> {
     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)!;
@@ -54,28 +66,38 @@ export class TDK {
 
     const url = `${this.BASE_URL}/gts?ara=${encodeURIComponent(cleanWord)}`;
 
+    let response: Response;
     try {
-      const response = await fetch(url, {
+      response = await fetch(url, {
         headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" },
       });
+    } catch (error) {
+      throw new TDKNetworkError("Failed to fetch word from TDK: request failed.", { cause: error });
+    }
 
-      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 [];
-      }
+    if (!response.ok) {
+      throw new TDKNetworkError(`Failed to fetch word from TDK: HTTP ${response.status}.`, {
+        status: response.status,
+      });
+    }
 
-      const results = data as WordInfo[];
-      if (this.isCacheEnabled) {
-        this.wordCache.set(cleanWord, results);
-      }
-      return results;
+    let data: unknown;
+    try {
+      data = await response.json();
     } 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: invalid JSON response.", { cause: error });
+    }
+
+    if (!Array.isArray(data) && data && "error" in (data as Record<string, unknown>)) {
+      if (this.isCacheEnabled) this.wordCache.set(cleanWord, []);
+      return [];
     }
+
+    const results = data as WordInfo[];
+    if (this.isCacheEnabled) {
+      this.wordCache.set(cleanWord, results);
+    }
+    return results;
   }
 
   /**
@@ -114,9 +136,9 @@ export class TDK {
       }
     }
     
-    const cleanPrefix = prefix.toLowerCase();
+    const cleanPrefix = prefix.toLocaleLowerCase("tr-TR");
     return this.autocompleteCache
-      .filter(w => w.toLowerCase().startsWith(cleanPrefix))
+      .filter(w => w.toLocaleLowerCase("tr-TR").startsWith(cleanPrefix))
       .slice(0, 10);
   }
 
@@ -139,14 +161,39 @@ export class TDK {
   }
 
   /**
-   * 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.
    */
   public static async getOrigin(word: string): Promise<string | null> {
     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ü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 "Türkçe";
+    return groups;
   }
 
   /**
@@ -172,23 +219,109 @@ export class TDK {
   }
 
   /**
-   * 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.
+   */
+  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> {
-    const results = await this.getWord(word);
-    // TDK currently generates audio urls using an internal algorithm or an MD5 hash of the word in some cases.
-    // For simplicity without reversing their full hash, we provide a placeholder or return a pattern.
-    // However, if we assume 'ses/' + word + '.wav' works (it doesn't usually), we can just say it's not fully public.
-    // Since we must implement this, we'll try a common pattern.
-    if (results.length > 0) {
-      // Actually, TDK audio endpoint is often: https://sozluk.gov.tr/ses/ + md5(word) + .wav
-      // We will just return null for now if TDK has restricted audio access, but let's implement the interface.
-      // We'll return a hypothetical audio link based on standard TDK audio patterns.
-      // Wait, TDK audio uses 'yazim?ara=' sometimes or 'ses/'. Let's return a basic structure.
-      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`;
   }
 
   /**
@@ -223,14 +356,34 @@ export class TDK {
     // 2. If not, check "sıkça yapılan yanlışlar" from DailyContent
     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 };
       }
+
+      // 3. No exact match in TDK's fixed lists: fall back to the closest word
+      // (by edit distance) within that same small pool. This is NOT a search
+      // over the full dictionary — TDK exposes no such lookup — just a
+      // best-effort nudge using the "sık yapılan yanlışlar" data we already have.
+      const candidates = [
+        ...daily.syyd.map((s) => s.dogrukelime),
+        ...daily.karistirma.flatMap((s) => [s.yanlis, s.dogru]),
+        ...daily.kelime.map((k) => k.madde),
+      ];
+      let best: { candidate: string; distance: number } | null = 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 };
   }
@@ -256,6 +409,109 @@ export class TDK {
     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.
+   */
+  public static async getKurallar(): Promise<TDKRule[]> {
+    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.
+   */
+  public static async getRule(name: string): Promise<string | null> {
+    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.
+   */
+  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(/&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.
    */
@@ -275,17 +531,20 @@ export class TDK {
 
   /**
    * 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) {
-              pos.add(ozellik.tam_adi);
+              if (ozellik.tur === "3") pos.add(ozellik.tam_adi);
             }
           }
         }
@@ -297,6 +556,94 @@ export class TDK {
     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),
+      },
+      b: {
+        word: b,
+        meaningCount: meaningsB.length,
+        origin: originB,
+        syllables: this.syllabicate(b),
+        harmony: this.checkVowelHarmony(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.
+   */
+  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) {
+      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ürkçe" : null,
+      });
+      await this.delay(200);
+    }
+    return analyses;
+  }
+
+  /**
+   * Classic edit-distance between two strings.
+   */
+  private static levenshtein(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);
+      }
+    }
+    return dp[a.length][b.length];
+  }
+
   /**
    * Fetches multiple words concurrently with a small delay to avoid rate limiting.
    */
@@ -357,13 +704,17 @@ export class TDK {
 
   /**
    * 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 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);
+
     // If it has both front and back vowels, it breaks harmony.
     return !(hasBack && hasFront);
   }

package/src/types.ts

@@ -87,4 +87,40 @@ export interface SpellCheckResult {
   suggestion?: string;
 }
 
+export interface WordOfTheDay {
+  word: string;
+  meanings: string[];
+}
+
+export interface DailyPick {
+  type: "kelime" | "atasoz";
+  madde: string;
+  anlam: string;
+}
+
+export interface TDKRule {
+  adi: string;
+  url: string;
+}
+
+export interface WordComparisonSide {
+  word: string;
+  meaningCount: number;
+  origin: string | null;
+  syllables: string[];
+  harmony: boolean;
+}
+
+export interface WordComparison {
+  a: WordComparisonSide;
+  b: WordComparisonSide;
+}
+
+export interface WordAnalysis {
+  word: string;
+  found: boolean;
+  meaning: string | null;
+  origin: string | null;
+}
+
 export type TDKResponse = WordInfo[] | { error: string };