tdk-api-wrapper 1.0.1

package/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to npm
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - name: Check if version changed
+        id: version-check
+        run: |
+          LOCAL_VERSION=$(node -p "require('./package.json').version")
+          PKG_NAME=$(node -p "require('./package.json').name")
+          PUBLISHED_VERSION=$(npm view "$PKG_NAME" version 2>/dev/null || echo "0.0.0")
+          echo "Local: $LOCAL_VERSION / Published: $PUBLISHED_VERSION"
+          if [ "$LOCAL_VERSION" != "$PUBLISHED_VERSION" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build
+        if: steps.version-check.outputs.changed == 'true'
+        run: npm run build
+
+      - name: Publish
+        if: steps.version-check.outputs.changed == 'true'
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# TDK API Node.js Wrapper
+
+Bu proje, Türk Dil Kurumu (TDK) sözlük verilerine Node.js ortamından doğrudan, hızlı ve güvenilir bir şekilde erişim sağlamak amacıyla geliştirilmiş, TypeScript tabanlı resmî olmayan bir sarmalayıcı (wrapper) kütüphanedir. Herhangi bir dış bağımlılığa veya ikili (binary) dosyaya ihtiyaç duymadan HTTP üzerinden güncel verileri çeker.
+
+## Kurulum
+
+Projeyi Node.js projenize dahil etmek için aşağıdaki paket yöneticilerinden uygun olanı kullanabilirsiniz:
+
+```bash
+npm install tdk-api
+```
+veya global yükleyerek komut satırı aracını (CLI) kullanmak için:
+```bash
+npm install -g tdk-api
+```
+
+## Komut Satırı Arayüzü (CLI) Kullanımı
+
+Paketi global kurduğunuzda, `tdk` komutunu terminalinizden doğrudan kullanabilirsiniz. Çıktılar olabildiğince sade ve okunabilirdir.
+
+```bash
+tdk ara kalem
+tdk ornek araba
+tdk koken lisan
+tdk hece muvaffakiyet
+tdk uyum elma
+tdk yazim herkes
+```
+
+## Kullanım Başlangıcı
+
+Modülü projenize dahil edip TDK sınıfını kullanarak tüm işlemleri başlatabilirsiniz. CommonJS ve ECMAScript Modules (ESM) yapıları tam olarak desteklenmektedir.
+
+```typescript
+import { TDK } from 'tdk-api';
+
+// Performansı artırmak için bellek içi önbelleği (Memory Cache) aktif etme
+TDK.enableCache(true);
+```
+
+## API Referansı ve Fonksiyonlar
+
+Aşağıdaki metotlar `TDK` sınıfı üzerinden statik olarak erişilebilir durumdadır:
+
+### 1. Temel Arama ve Anlamlar
+- **`TDK.getWord(word)`**: Kelimenin TDK sözlüğündeki tüm yapısal özelliklerini tam veri seti (JSON) olarak getirir.
+- **`TDK.getMeanings(word)`**: Sadece anlamları basit bir string dizisi olarak döner.
+- **`TDK.getWordsBatch(wordsArray)`**: Birden fazla kelimeyi aynı anda aramak için kullanılır (sunucuyu yormamak adına yerleşik gecikme içerir).
+
+### 2. Dilbilgisi ve Gramer Özellikleri
+- **`TDK.syllabicate(word)`**: Kelimeyi Türkçe heceleme kurallarına göre doğru hecelerine ayırır (Örn: `['mu', 'vaf', 'fa', 'ki', 'yet']`). API isteği atmaz, çok hızlıdır.
+- **`TDK.checkVowelHarmony(word)`**: Kelimenin büyük ünlü uyumuna uyup uymadığını (boolean) kontrol eder.
+- **`TDK.getPartOfSpeech(word)`**: Kelimenin sözcük türünü (isim, sıfat, zarf vb.) döndürür.
+- **`TDK.checkSpelling(word)`**: Sıkça yapılan yanlışlar listesini ve TDK veritabanını kullanarak kelimenin doğru yazılıp yazılmadığını kontrol eder. Yanlışsa doğrusunu önerir.
+- **`TDK.getCompoundWords(word)`**: Aranan kelime ile oluşturulmuş birleşik kelimeleri (Örn: dolma kalem) listeler.
+
+### 3. Edebi ve Kültürel Analiz
+- **`TDK.getExamples(word)`**: Ünlü yazarlardan edebi örnek cümleleri ve yazar isimlerini liste halinde döner.
+- **`TDK.getOrigin(word)`**: Kelimenin hangi dilden geldiğini (etimolojik lisan kökenini) döner.
+- **`TDK.getProverbs(word)`**: Yalnızca aranan kelimenin geçtiği atasözü ve deyimleri dizi olarak getirir.
+
+### 4. Yardımcı Metotlar
+- **`TDK.getSuggestions(prefix)`**: Kelimenin sadece ilk birkaç harfini girdiğinizde otomatik tamamlama önerilerini çeker.
+- **`TDK.getAudioUrl(word)`**: Varsa TDK telaffuz ses dosyasının URL'sini oluşturur. `downloadAudio(word, destPath)` ile cihazınıza indirebilirsiniz.
+- **`TDK.getDailyContent()`**: TDK anasayfasında yer alan "Günün Kelimesi, Atasözü ve Kuralı" içeriklerini çeker.
+
+## Lisans
+
+Bu proje MIT Lisansı ile lisanslanmıştır. Kullanım hakları ve kısıtlamalar için kaynak kod içerisindeki lisans metnini inceleyebilirsiniz.

package/dist/chunk-MGSXCUAX.mjs

@@ -0,0 +1,325 @@
+// src/tdk.ts
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "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);
+  }
+};
+
+export {
+  TDK
+};

package/dist/cli.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node