tdk-api-wrapper 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,187 @@
+interface Author {
+    yazar_id: string;
+    tam_adi: string;
+    kisa_adi: string;
+    ekno: string;
+}
+interface Example {
+    ornek_id: string;
+    anlam_id: string;
+    ornek_sira: string;
+    ornek: string;
+    kac: string;
+    yazar_id: string;
+    yazar_vd: string;
+    yazar?: Author[];
+}
+interface Feature {
+    ozellik_id: string;
+    tur: string;
+    tam_adi: string;
+    kisa_adi: string;
+    ekno: string;
+}
+interface Meaning {
+    anlam_id: string;
+    madde_id: string;
+    anlam_sira: string;
+    fiil: string;
+    tipkes: string;
+    anlam: string;
+    anlam_html: string | null;
+    gos: string;
+    gos_kelime: string;
+    gos_kultur: string;
+    orneklerListe?: Example[];
+    ozelliklerListe?: Feature[];
+}
+interface Proverb {
+    madde_id: string;
+    madde: string;
+    on_taki: string | null;
+}
+interface WordInfo {
+    madde_id: string;
+    kac: string;
+    kelime_no: string;
+    cesit: string;
+    anlam_gor: string;
+    on_taki: string | null;
+    on_taki_html: string | null;
+    madde: string;
+    madde_html: string | null;
+    cesit_say: string;
+    anlam_say: string;
+    taki: string;
+    cogul_mu: string;
+    ozel_mi: string;
+    egik_mi: string;
+    lisan_kodu: string;
+    lisan: string;
+    telaffuz_html: string | null;
+    telaffuz: string;
+    birlesikler: string | null;
+    font: string | null;
+    madde_duz: string;
+    gosterim_tarihi: string | null;
+    anlamlarListe?: Meaning[];
+    atasozu?: Proverb[];
+}
+interface DailyContent {
+    kelime: {
+        madde: string;
+        anlam: string;
+    }[];
+    atasoz: {
+        madde: string;
+        anlam: string;
+    }[];
+    kural: {
+        adi: string;
+        url: string;
+    }[];
+    syyd: {
+        id: string;
+        yanliskelime: string;
+        dogrukelime: string;
+    }[];
+    karistirma: {
+        id: string;
+        yanlis: string;
+        dogru: string;
+    }[];
+}
+interface SpellCheckResult {
+    isCorrect: boolean;
+    word: string;
+    suggestion?: string;
+}
+type TDKResponse = WordInfo[] | {
+    error: string;
+};
+
+/**
+ * TDK (Türk Dil Kurumu) API Wrapper
+ */
+declare class TDK {
+    private static readonly BASE_URL;
+    private static isCacheEnabled;
+    private static wordCache;
+    private static dailyContentCache;
+    private static autocompleteCache;
+    /**
+     * Enables or disables in-memory caching for API requests.
+     */
+    static enableCache(status?: boolean): void;
+    /**
+     * Clears the internal cache.
+     */
+    static clearCache(): void;
+    private static delay;
+    /**
+     * Fetches detailed information for a given word from the TDK Dictionary.
+     */
+    static getWord(word: string): Promise<WordInfo[]>;
+    /**
+     * Helper method to get only the meanings (definitions) of a word as a string array.
+     */
+    static getMeanings(word: string): Promise<string[]>;
+    /**
+     * Returns suggestions (autocomplete) for a given prefix.
+     */
+    static getSuggestions(prefix: string): Promise<string[]>;
+    /**
+     * Returns a list of proverbs and idioms containing the word.
+     */
+    static getProverbs(word: string): Promise<string[]>;
+    /**
+     * Returns the etymological origin of the word if it's a foreign word.
+     */
+    static getOrigin(word: string): Promise<string | null>;
+    /**
+     * Returns literature examples containing the word.
+     */
+    static getExamples(word: string): Promise<{
+        sentence: string;
+        author: string | null;
+    }[]>;
+    /**
+     * 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.
+     */
+    static getAudioUrl(word: string): Promise<string | null>;
+    /**
+     * Downloads the audio pronunciation to the specified path.
+     */
+    static downloadAudio(word: string, destPath?: string): Promise<string | null>;
+    /**
+     * Checks spelling and returns suggestions if wrong.
+     */
+    static checkSpelling(word: string): Promise<SpellCheckResult>;
+    /**
+     * Fetches daily content (word of the day, proverbs, rules, etc).
+     */
+    static getDailyContent(): Promise<DailyContent | null>;
+    /**
+     * Returns compound words that contain this word.
+     */
+    static getCompoundWords(word: string): Promise<string[]>;
+    /**
+     * Returns the part of speech (isim, sıfat, zarf vb.).
+     */
+    static getPartOfSpeech(word: string): Promise<string[]>;
+    /**
+     * Fetches multiple words concurrently with a small delay to avoid rate limiting.
+     */
+    static getWordsBatch(words: string[]): Promise<WordInfo[][]>;
+    /**
+     * Syllabicates a Turkish word based on general grammar rules.
+     */
+    static syllabicate(word: string): string[];
+    /**
+     * Checks if a word follows Turkish Major Vowel Harmony (Büyük Ünlü Uyumu).
+     */
+    static checkVowelHarmony(word: string): boolean;
+}
+
+export { type Author, type DailyContent, type Example, type Feature, type Meaning, type Proverb, type SpellCheckResult, TDK, type TDKResponse, type WordInfo };

package/dist/index.js

@@ -0,0 +1,361 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  TDK: () => TDK
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/tdk.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var os = __toESM(require("os"));
+var TDK = class {
+  static BASE_URL = "https://sozluk.gov.tr";
+  // Cache Mechanism
+  static isCacheEnabled = false;
+  static wordCache = /* @__PURE__ */ new Map();
+  static dailyContentCache = null;
+  static autocompleteCache = [];
+  /**
+   * Enables or disables in-memory caching for API requests.
+   */
+  static enableCache(status = true) {
+    this.isCacheEnabled = status;
+    if (!status) {
+      this.clearCache();
+    }
+  }
+  /**
+   * Clears the internal cache.
+   */
+  static clearCache() {
+    this.wordCache.clear();
+    this.dailyContentCache = null;
+    this.autocompleteCache = [];
+  }
+  static delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Fetches detailed information for a given word from the TDK Dictionary.
+   */
+  static async getWord(word) {
+    if (!word || word.trim() === "") {
+      throw new Error("Word parameter cannot be empty.");
+    }
+    const cleanWord = word.trim().toLowerCase();
+    if (this.isCacheEnabled && this.wordCache.has(cleanWord)) {
+      return this.wordCache.get(cleanWord);
+    }
+    const url = `${this.BASE_URL}/gts?ara=${encodeURIComponent(cleanWord)}`;
+    try {
+      const 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");
+    }
+  }
+  /**
+   * Helper method to get only the meanings (definitions) of a word as a string array.
+   */
+  static async getMeanings(word) {
+    const results = await this.getWord(word);
+    if (results.length === 0)
+      return [];
+    const meanings = [];
+    for (const result of results) {
+      if (result.anlamlarListe) {
+        for (const anlam of result.anlamlarListe) {
+          if (anlam.anlam)
+            meanings.push(anlam.anlam);
+        }
+      }
+    }
+    return meanings;
+  }
+  /**
+   * Returns suggestions (autocomplete) for a given prefix.
+   */
+  static async getSuggestions(prefix) {
+    if (this.autocompleteCache.length === 0) {
+      try {
+        const response = await fetch(`${this.BASE_URL}/autocomplete.json`, {
+          headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" }
+        });
+        if (response.ok) {
+          const data = await response.json();
+          this.autocompleteCache = data.map((item) => item.madde);
+        }
+      } catch (e) {
+        return [];
+      }
+    }
+    const cleanPrefix = prefix.toLowerCase();
+    return this.autocompleteCache.filter((w) => w.toLowerCase().startsWith(cleanPrefix)).slice(0, 10);
+  }
+  /**
+   * Returns a list of proverbs and idioms containing the word.
+   */
+  static async getProverbs(word) {
+    const results = await this.getWord(word);
+    if (results.length === 0)
+      return [];
+    const proverbs = [];
+    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 if it's a foreign word.
+   */
+  static async getOrigin(word) {
+    const results = await this.getWord(word);
+    if (results.length > 0 && results[0].lisan) {
+      return results[0].lisan;
+    }
+    return "T\xFCrk\xE7e";
+  }
+  /**
+   * Returns literature examples containing the word.
+   */
+  static async getExamples(word) {
+    const results = await this.getWord(word);
+    const examples = [];
+    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;
+  }
+  /**
+   * 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.
+   */
+  static async getAudioUrl(word) {
+    const results = await this.getWord(word);
+    if (results.length > 0) {
+      return `https://sozluk.gov.tr/ses/${encodeURIComponent(word)}.wav`;
+    }
+    return null;
+  }
+  /**
+   * Downloads the audio pronunciation to the specified path.
+   */
+  static async downloadAudio(word, destPath) {
+    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.
+   */
+  static async checkSpelling(word) {
+    const results = await this.getWord(word);
+    if (results.length > 0) {
+      return { isCorrect: true, word };
+    }
+    const daily = await this.getDailyContent();
+    if (daily) {
+      const syydMatch = daily.syyd.find((s) => s.yanliskelime.toLowerCase() === word.toLowerCase());
+      if (syydMatch) {
+        return { isCorrect: false, word, suggestion: syydMatch.dogrukelime };
+      }
+      const mixMatch = daily.karistirma.find((s) => s.yanlis.toLowerCase() === word.toLowerCase());
+      if (mixMatch) {
+        return { isCorrect: false, word, suggestion: mixMatch.dogru };
+      }
+    }
+    return { isCorrect: false, word };
+  }
+  /**
+   * Fetches daily content (word of the day, proverbs, rules, etc).
+   */
+  static async getDailyContent() {
+    if (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();
+        if (this.isCacheEnabled)
+          this.dailyContentCache = data;
+        return data;
+      }
+    } catch {
+      return null;
+    }
+    return null;
+  }
+  /**
+   * Returns compound words that contain this word.
+   */
+  static async getCompoundWords(word) {
+    const results = await this.getWord(word);
+    if (results.length === 0)
+      return [];
+    const compound = [];
+    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.).
+   */
+  static async getPartOfSpeech(word) {
+    const results = await this.getWord(word);
+    const pos = /* @__PURE__ */ new Set();
+    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 (pos.size === 0 && results.length > 0) {
+      pos.add("isim");
+    }
+    return Array.from(pos);
+  }
+  /**
+   * Fetches multiple words concurrently with a small delay to avoid rate limiting.
+   */
+  static async getWordsBatch(words) {
+    const results = [];
+    for (const word of words) {
+      try {
+        const res = await this.getWord(word);
+        results.push(res);
+      } catch {
+        results.push([]);
+      }
+      await this.delay(200);
+    }
+    return results;
+  }
+  /**
+   * Syllabicates a Turkish word based on general grammar rules.
+   */
+  static syllabicate(word) {
+    const vowels = /[aeıioöuüAEIİOÖUÜ]/;
+    const result = [];
+    let currentSyllable = "";
+    for (let i = word.length - 1; i >= 0; i--) {
+      currentSyllable = word[i] + currentSyllable;
+      if (vowels.test(word[i])) {
+        if (i - 1 >= 0 && !vowels.test(word[i - 1])) {
+          if (i - 2 >= 0 && vowels.test(word[i - 2])) {
+            currentSyllable = word[i - 1] + currentSyllable;
+            i--;
+          } else if (i - 2 >= 0 && !vowels.test(word[i - 2])) {
+            currentSyllable = word[i - 1] + currentSyllable;
+            i--;
+          }
+        }
+        result.unshift(currentSyllable);
+        currentSyllable = "";
+      }
+    }
+    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).
+   */
+  static checkVowelHarmony(word) {
+    const backVowels = /[aıou]/i;
+    const frontVowels = /[eiöü]/i;
+    const hasBack = backVowels.test(word);
+    const hasFront = frontVowels.test(word);
+    return !(hasBack && hasFront);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TDK
+});

package/dist/index.mjs

@@ -0,0 +1,6 @@
+import {
+  TDK
+} from "./chunk-MGSXCUAX.mjs";
+export {
+  TDK
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "tdk-api-wrapper",
+  "version": "1.0.1",
+  "description": "TDK (Türk Dil Kurumu) unofficial live data API wrapper for Node.js",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "tdk": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean --shims"
+  },
+  "keywords": [
+    "tdk",
+    "sozluk",
+    "api",
+    "turkish",
+    "dictionary",
+    "turkce"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { TDK } from "./tdk";
+
+const args = process.argv.slice(2);
+const command = args[0];
+const word = args[1];
+
+async function run() {
+  if (!command) {
+    console.log("Kullanım: tdk <komut> <kelime>");
+    console.log("Komutlar: ara, anlam, koken, ornek, hece, uyum, yazim");
+    process.exit(1);
+  }
+
+  TDK.enableCache(false);
+
+  try {
+    switch (command) {
+      case "ara":
+      case "anlam":
+        if (!word) throw new Error("Kelime belirtmelisiniz.");
+        const meanings = await TDK.getMeanings(word);
+        if (meanings.length === 0) {
+          console.log("Sonuç bulunamadı.");
+        } else {
+          meanings.forEach((m, i) => console.log(`${i + 1}. ${m}`));
+        }
+        break;
+
+      case "koken":
+        if (!word) throw new Error("Kelime belirtmelisiniz.");
+        const origin = await TDK.getOrigin(word);
+        console.log(`Köken: ${origin}`);
+        break;
+
+      case "ornek":
+        if (!word) throw new Error("Kelime belirtmelisiniz.");
+        const examples = await TDK.getExamples(word);
+        if (examples.length === 0) {
+          console.log("Örnek bulunamadı.");
+        } else {
+          examples.forEach((ex, i) => {
+            const yazar = ex.author ? ` (${ex.author})` : "";
+            console.log(`${i + 1}. ${ex.sentence}${yazar}`);
+          });
+        }
+        break;
+
+      case "hece":
+        if (!word) throw new Error("Kelime belirtmelisiniz.");
+        const syllables = TDK.syllabicate(word);
+        console.log(`Heceler: ${syllables.join("-")}`);
+        break;
+
+      case "uyum":
+        if (!word) throw new Error("Kelime belirtmelisiniz.");
+        const isHarmony = TDK.checkVowelHarmony(word);
+        console.log(`Büyük Ünlü Uyumu: ${isHarmony ? "Uyar" : "Uymaz"}`);
+        break;
+
+      case "yazim":
+        if (!word) throw new Error("Kelime belirtmelisiniz.");
+        const spellResult = await TDK.checkSpelling(word);
+        if (spellResult.isCorrect) {
+          console.log("Doğru yazım.");
+        } else {
+          console.log(`Yanlış yazım.${spellResult.suggestion ? " Doğrusu: " + spellResult.suggestion : ""}`);
+        }
+        break;
+
+      default:
+        console.log("Bilinmeyen komut.");
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.log(`Hata: ${error.message}`);
+    }
+  }
+}
+
+run();

package/src/index.ts

@@ -0,0 +1,2 @@
+export { TDK } from "./tdk";
+export * from "./types";