tdk-api-wrapper 1.3.0 → 1.3.1

package/README.md

@@ -97,9 +97,9 @@ Aşağıdaki metotlar `TDK` sınıfı üzerinden statik olarak erişilebilir dur
 
 TDK dışındaki bu üç kaynak da her zaman kullanılabilir/dokümante edilmiş resmî API'ler değildir; her biri **fragile scraping** (kırılgan, dokümante edilmemiş entegrasyon) — kaynak taraflarında bir değişiklik olursa `null`/`[]` dönerler, hataya düşmezler. Verinin telif/kullanım koşulları kaynağa göre farklıdır: Wiktionary içeriği CC BY-SA lisanslıdır (açık); Nişanyan Sözlük ücretsiz, açık bir kişisel/akademik kaynaktır; **Kubbealtı Lugatı ise ticari bir sözlük ürünüdür** — bu kütüphane onu da dokümante edilmemiş bir uç noktadan çekebiliyor olsa da, kullanımınızı Kubbealtı'nın kendi kullanım şartlarına göre değerlendirmeniz önerilir.
 
-- **`TDK.getKubbealti(word)`**: Kubbealtı Lugatı'nın ("Misalli Büyük Türkçe Sözlük") verilerini `{ kelime, anlam }` dizisi olarak döner (`anlam` zengin tipografi içeren ham HTML'dir). `getKubbealtiMeanings(word)` aynı veriyi düz metne çevirir. `getKubbealtiSuggestions(prefix)` Kubbealtı'nın kendi otomatik tamamlama uç noktasını kullanır (TDK'nin `getSuggestions()`'ından bağımsız, ayrı bir veri kaynağı). Not: Kubbealtı'nın veri sunucusu (`eski.lugatim.com`) sertifika zincirini eksik gönderiyor; bu kütüphane eksik ara sertifikaları ekleyerek zinciri düzgün doğruluyor (doğrulamayı kapatmıyor) — Let's Encrypt bu ara sertifikayı döndürürse bu entegrasyon `null` dönmeye başlar.
+- **`TDK.getKubbealti(word)`**: Kubbealtı Lugatı'nın ("Misalli Büyük Türkçe Sözlük") verilerini `{ kelime, anlam }` dizisi olarak döner (`anlam` zengin tipografi içeren ham HTML'dir). `getKubbealtiMeanings(word)` aynı veriyi düz metne çevirir. `getKubbealtiSuggestions(prefix)` Kubbealtı'nın kendi otomatik tamamlama uç noktasını kullanır (TDK'nin `getSuggestions()`'ından bağımsız, ayrı bir veri kaynağı). Kubbealtı başlıkları klasik Türkçe imlayla (ü/ö/ç/ğ/ş, düzeltme işareti) indekslidir; düz ASCII'ye yakın bir sorgu (örn. `ruzgar`) boş dönerse, kütüphane tek harflik Türkçeleştirme varyasyonlarını (`rüzgâr`, `rûzgar` vb.) otomatik dener. Not: Kubbealtı'nın veri sunucusu (`eski.lugatim.com`) sertifika zincirini eksik gönderiyor; bu kütüphane eksik ara sertifikaları ekleyerek zinciri düzgün doğruluyor (doğrulamayı kapatmıyor) — Let's Encrypt bu ara sertifikayı döndürürse bu entegrasyon `null` dönmeye başlar.
 - **`TDK.getNisanyan(word)`**: Nişanyan Sözlük'ten kelimenin etimoloji paragrafını düz metin olarak döner; kelime bulunamazsa `null`.
-- **`TDK.getWiktionary(word)`**: Türkçe Vikisözlük'ten (`tr.wiktionary.org`) resmî MediaWiki API'si (`action=query&prop=extracts`) üzerinden veri çeker — bu üçü arasında scraping olmayan, resmî ve en kararlı olanı. `{ raw, sections }` döner; `sections` metni `== Köken ==`, `=== Söyleniş ===` gibi başlıklara göre bir sözlüğe ayırır. `getWiktionarySection(word, sectionName)` tek bir bölümü (örn. `"Köken"`) büyük/küçük harf duyarsız süzer.
+- **`TDK.getWiktionary(word)`**: Türkçe Vikisözlük'ten (`tr.wiktionary.org`) resmî MediaWiki API'si (`action=query&prop=extracts`) üzerinden veri çeker — bu üçü arasında scraping olmayan, resmî ve en kararlı olanı. `{ raw, sections }` döner; `sections` metni `== Köken ==`, `=== Söyleniş ===` gibi başlıklara göre bir sözlüğe ayırır. `getWiktionarySection(word, sectionName)` tek bir bölümü (örn. `"Köken"`) büyük/küçük harf duyarsız süzer. Bu wiki'de başlık büyütme kapalı (`$wgCapitalLinks=false` — "Türkiye" ile bir küçük harfli kelime ayrı sayfalardır), o yüzden `TDK.getWiktionary("türkiye")` gibi tam eşleşmeyen aramalar otomatik olarak ilk harfi (Türkçe kurallarına göre, örn. `istanbul` → `İstanbul`) büyütülmüş hâliyle tekrar denenir.
 
 ## Hata Yönetimi
 

package/dist/{chunk-SLNXKZKR.mjs → chunk-ACMGCL7T.mjs}

@@ -661,14 +661,46 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       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.
+   */
+  static TURKISH_DEASCII_MAP = {
+    a: ["\xE2"],
+    i: ["\u0131", "\xEE"],
+    o: ["\xF6"],
+    u: ["\xFC", "\xFB"],
+    c: ["\xE7"],
+    g: ["\u011F"],
+    s: ["\u015F"]
+  };
+  static generateTurkishVariants(word) {
+    const lower = word.trim().toLocaleLowerCase("tr-TR");
+    const variants = [];
+    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. Returns `null` on any fetch/parse failure, `[]` if the word
-   * isn't found.
+   * 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.
    */
   static async getKubbealti(word) {
     if (!word || word.trim() === "")
@@ -676,7 +708,16 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     const data = await this.fetchKubbealtiJson(`/rest/s/${encodeURIComponent(word.trim())}/`);
     if (!data || !Array.isArray(data.content))
       return null;
-    return data.content.map((entry) => ({ kelime: entry.kelime, anlam: entry.anlam }));
+    if (data.content.length > 0) {
+      return data.content.map((entry) => ({ 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) => ({ kelime: entry.kelime, anlam: entry.anlam }));
+      }
+    }
+    return [];
   }
   /**
    * Same as `getKubbealti()` but with each entry's `anlam` HTML stripped to
@@ -730,21 +771,10 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       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. Returns `null` if the page doesn't exist or the request
-   * fails.
-   */
-  static async getWiktionary(word) {
-    if (!word || word.trim() === "")
-      return null;
+  static async fetchWiktionaryEntry(title) {
     try {
       const url = `https://tr.wiktionary.org/w/api.php?action=query&prop=extracts&titles=${encodeURIComponent(
-        word.trim()
+        title
       )}&format=json&explaintext=1&formatversion=2`;
       const response = await fetch(url, { headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" } });
       if (!response.ok)
@@ -757,16 +787,42 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       const sections = {};
       const parts = raw.split(/\n(={2,4})\s*(.+?)\s*\1\n/);
       for (let i = 1; i < parts.length; i += 3) {
-        const title = parts[i + 1]?.trim();
+        const title2 = parts[i + 1]?.trim();
         const content = parts[i + 2]?.trim();
-        if (title)
-          sections[title] = content ?? "";
+        if (title2)
+          sections[title2] = 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.
+   */
+  static async getWiktionary(word) {
+    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

package/dist/cli.js

@@ -686,14 +686,46 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       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.
+   */
+  static TURKISH_DEASCII_MAP = {
+    a: ["\xE2"],
+    i: ["\u0131", "\xEE"],
+    o: ["\xF6"],
+    u: ["\xFC", "\xFB"],
+    c: ["\xE7"],
+    g: ["\u011F"],
+    s: ["\u015F"]
+  };
+  static generateTurkishVariants(word2) {
+    const lower = word2.trim().toLocaleLowerCase("tr-TR");
+    const variants = [];
+    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. Returns `null` on any fetch/parse failure, `[]` if the word
-   * isn't found.
+   * 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.
    */
   static async getKubbealti(word2) {
     if (!word2 || word2.trim() === "")
@@ -701,7 +733,16 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     const data = await this.fetchKubbealtiJson(`/rest/s/${encodeURIComponent(word2.trim())}/`);
     if (!data || !Array.isArray(data.content))
       return null;
-    return data.content.map((entry) => ({ kelime: entry.kelime, anlam: entry.anlam }));
+    if (data.content.length > 0) {
+      return data.content.map((entry) => ({ kelime: entry.kelime, anlam: entry.anlam }));
+    }
+    for (const variant of this.generateTurkishVariants(word2)) {
+      const variantData = await this.fetchKubbealtiJson(`/rest/s/${encodeURIComponent(variant)}/`);
+      if (variantData && Array.isArray(variantData.content) && variantData.content.length > 0) {
+        return variantData.content.map((entry) => ({ kelime: entry.kelime, anlam: entry.anlam }));
+      }
+    }
+    return [];
   }
   /**
    * Same as `getKubbealti()` but with each entry's `anlam` HTML stripped to
@@ -755,21 +796,10 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       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. Returns `null` if the page doesn't exist or the request
-   * fails.
-   */
-  static async getWiktionary(word2) {
-    if (!word2 || word2.trim() === "")
-      return null;
+  static async fetchWiktionaryEntry(title) {
     try {
       const url = `https://tr.wiktionary.org/w/api.php?action=query&prop=extracts&titles=${encodeURIComponent(
-        word2.trim()
+        title
       )}&format=json&explaintext=1&formatversion=2`;
       const response = await fetch(url, { headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" } });
       if (!response.ok)
@@ -782,16 +812,42 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       const sections = {};
       const parts = raw.split(/\n(={2,4})\s*(.+?)\s*\1\n/);
       for (let i = 1; i < parts.length; i += 3) {
-        const title = parts[i + 1]?.trim();
+        const title2 = parts[i + 1]?.trim();
         const content = parts[i + 2]?.trim();
-        if (title)
-          sections[title] = content ?? "";
+        if (title2)
+          sections[title2] = 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.
+   */
+  static async getWiktionary(word2) {
+    if (!word2 || word2.trim() === "")
+      return null;
+    const trimmed = word2.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

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   TDK
-} from "./chunk-SLNXKZKR.mjs";
+} from "./chunk-ACMGCL7T.mjs";
 
 // src/cli.ts
 var rawArgs = process.argv.slice(2);

package/dist/index.d.mts

@@ -325,14 +325,29 @@ declare class TDK {
      * `null` on any error — network, TLS, HTTP, or JSON parse.
      */
     private static fetchKubbealtiJson;
+    /**
+     * 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;
+    private static generateTurkishVariants;
     /**
      * 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. Returns `null` on any fetch/parse failure, `[]` if the word
-     * isn't found.
+     * 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.
      */
     static getKubbealti(word: string): Promise<KubbealtiEntry[] | null>;
     /**
@@ -354,14 +369,20 @@ declare class TDK {
      * case) or the request fails.
      */
     static getNisanyan(word: string): Promise<string | null>;
+    private static fetchWiktionaryEntry;
     /**
      * 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. Returns `null` if the page doesn't exist or the request
-     * fails.
+     * 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.
      */
     static getWiktionary(word: string): Promise<WiktionaryEntry | null>;
     /**

package/dist/index.d.ts

@@ -325,14 +325,29 @@ declare class TDK {
      * `null` on any error — network, TLS, HTTP, or JSON parse.
      */
     private static fetchKubbealtiJson;
+    /**
+     * 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;
+    private static generateTurkishVariants;
     /**
      * 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. Returns `null` on any fetch/parse failure, `[]` if the word
-     * isn't found.
+     * 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.
      */
     static getKubbealti(word: string): Promise<KubbealtiEntry[] | null>;
     /**
@@ -354,14 +369,20 @@ declare class TDK {
      * case) or the request fails.
      */
     static getNisanyan(word: string): Promise<string | null>;
+    private static fetchWiktionaryEntry;
     /**
      * 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. Returns `null` if the page doesn't exist or the request
-     * fails.
+     * 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.
      */
     static getWiktionary(word: string): Promise<WiktionaryEntry | null>;
     /**

package/dist/index.js

@@ -700,14 +700,46 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       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.
+   */
+  static TURKISH_DEASCII_MAP = {
+    a: ["\xE2"],
+    i: ["\u0131", "\xEE"],
+    o: ["\xF6"],
+    u: ["\xFC", "\xFB"],
+    c: ["\xE7"],
+    g: ["\u011F"],
+    s: ["\u015F"]
+  };
+  static generateTurkishVariants(word) {
+    const lower = word.trim().toLocaleLowerCase("tr-TR");
+    const variants = [];
+    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. Returns `null` on any fetch/parse failure, `[]` if the word
-   * isn't found.
+   * 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.
    */
   static async getKubbealti(word) {
     if (!word || word.trim() === "")
@@ -715,7 +747,16 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     const data = await this.fetchKubbealtiJson(`/rest/s/${encodeURIComponent(word.trim())}/`);
     if (!data || !Array.isArray(data.content))
       return null;
-    return data.content.map((entry) => ({ kelime: entry.kelime, anlam: entry.anlam }));
+    if (data.content.length > 0) {
+      return data.content.map((entry) => ({ 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) => ({ kelime: entry.kelime, anlam: entry.anlam }));
+      }
+    }
+    return [];
   }
   /**
    * Same as `getKubbealti()` but with each entry's `anlam` HTML stripped to
@@ -769,21 +810,10 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       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. Returns `null` if the page doesn't exist or the request
-   * fails.
-   */
-  static async getWiktionary(word) {
-    if (!word || word.trim() === "")
-      return null;
+  static async fetchWiktionaryEntry(title) {
     try {
       const url = `https://tr.wiktionary.org/w/api.php?action=query&prop=extracts&titles=${encodeURIComponent(
-        word.trim()
+        title
       )}&format=json&explaintext=1&formatversion=2`;
       const response = await fetch(url, { headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" } });
       if (!response.ok)
@@ -796,16 +826,42 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       const sections = {};
       const parts = raw.split(/\n(={2,4})\s*(.+?)\s*\1\n/);
       for (let i = 1; i < parts.length; i += 3) {
-        const title = parts[i + 1]?.trim();
+        const title2 = parts[i + 1]?.trim();
         const content = parts[i + 2]?.trim();
-        if (title)
-          sections[title] = content ?? "";
+        if (title2)
+          sections[title2] = 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.
+   */
+  static async getWiktionary(word) {
+    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

package/dist/index.mjs

@@ -3,7 +3,7 @@ import {
   TDKError,
   TDKNetworkError,
   TDKValidationError
-} from "./chunk-SLNXKZKR.mjs";
+} from "./chunk-ACMGCL7T.mjs";
 export {
   TDK,
   TDKError,

package/package.json

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

package/src/tdk.ts

@@ -713,20 +713,65 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     });
   }
 
+  /**
+   * 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. Returns `null` on any fetch/parse failure, `[]` if the word
-   * isn't found.
+   * 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;
-    return data.content.map((entry: any) => ({ kelime: entry.kelime, anlam: entry.anlam }));
+    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 [];
   }
 
   /**
@@ -777,20 +822,10 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     }
   }
 
-  /**
-   * 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. Returns `null` if the page doesn't exist or the request
-   * fails.
-   */
-  public static async getWiktionary(word: string): Promise<WiktionaryEntry | null> {
-    if (!word || word.trim() === "") 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(
-        word.trim()
+        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;
@@ -814,6 +849,32 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     }
   }
 
+  /**
+   * 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