tdk-api-wrapper 1.2.2 → 1.3.1

package/src/tdk.ts

@@ -7,12 +7,15 @@ import type {
   WordComparison,
   WordAnalysis,
   TDKRule,
+  KubbealtiEntry,
+  WiktionaryEntry,
 } 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";
+import * as tls from "node:tls";
 
 /**
  * TDK (Türk Dil Kurumu) API Wrapper
@@ -20,6 +23,84 @@ import * as https from "node:https";
 export class TDK {
   private static readonly BASE_URL = "https://sozluk.gov.tr";
   private static readonly AUDIO_API_HOST = "api.sozluk.gov.tr";
+  private static readonly KUBBEALTI_HOST = "eski.lugatim.com";
+
+  /**
+   * `eski.lugatim.com` (Kubbealtı Lugatı's data API) sends only its leaf
+   * certificate during the TLS handshake, omitting the intermediates a
+   * correctly configured server would include — a server-side misconfiguration,
+   * not something we should paper over by disabling verification. These are
+   * the two certificates the server *should* be sending (fetched from the
+   * leaf's own Authority Information Access URLs), supplied here so Node can
+   * still build a full, properly verified chain up to a root it already
+   * trusts (ISRG Root X1). If Let's Encrypt rotates this intermediate, this
+   * stops working and every Kubbealtı call fails closed to `null` — same
+   * fail-closed contract as the rest of this file's fragile integrations.
+   */
+  private static readonly KUBBEALTI_EXTRA_CA = [
+    `-----BEGIN CERTIFICATE-----
+MIIE2jCCAsKgAwIBAgIQTr0klH4k05SALYSlL9WzGTANBgkqhkiG9w0BAQsFADAu
+MQswCQYDVQQGEwJVUzENMAsGA1UEChMESVNSRzEQMA4GA1UEAxMHUm9vdCBZUjAe
+Fw0yNTA5MDMwMDAwMDBaFw0yODA5MDIyMzU5NTlaMDMxCzAJBgNVBAYTAlVTMRYw
+FAYDVQQKEw1MZXQncyBFbmNyeXB0MQwwCgYDVQQDEwNZUjIwggEiMA0GCSqGSIb3
+DQEBAQUAA4IBDwAwggEKAoIBAQDZ0LxwBppqh84luqMerV/eeL/fXQ7mLQQv1Lnp
+WKZbyvGpx6wh6AfnslAnF6ewTkcHA+gSOoBvm3Dfm06AuGiF+KRut4fAcowqnAQQ
+CW98+QPP/eOv/wug7Iyk4NkOxf2I6g2f55T6nJoOTLFcukeRq80JGQEYan+dPFr9
+OGUgQK2hGKgNkW87pappsOAuUJcroYhRt5uUis4qaZireiseu32gzDJNBAiKtsvd
+6HX4v25bpkRNcS/B/Gtc9kVbUpD+2PLPxdei3Tim55k4tfAEXwD2qyiPTxrTNq6l
+N+AMr5g2c1dNqkOTwjxeV6L5lpP1rGiYvLnRaPlOqyZRPW+5AgMBAAGjge4wgesw
+DgYDVR0PAQH/BAQDAgGGMBMGA1UdJQQMMAoGCCsGAQUFBwMBMBIGA1UdEwEB/wQI
+MAYBAf8CAQAwHQYDVR0OBBYEFEAVLSZ57TIgnt+ach3WMh+BDIEMMB8GA1UdIwQY
+MBaAFN7nW2DQIm1AKH0/DQH+pLVStFGUMDIGCCsGAQUFBwEBBCYwJDAiBggrBgEF
+BQcwAoYWaHR0cDovL3lyLmkubGVuY3Iub3JnLzATBgNVHSAEDDAKMAgGBmeBDAEC
+ATAnBgNVHR8EIDAeMBygGqAYhhZodHRwOi8veXIuYy5sZW5jci5vcmcvMA0GCSqG
+SIb3DQEBCwUAA4ICAQB0ZUQWZ9/Yn9COEpo+JfecMnB0h0vwDm/M66IqXqw3LoaL
+mx9lZvRTeDIS67PUeI3yCA2W6PKRD0/FE/G57lOmS+Xy5AaaL00ICGOqjNcCaMWW
+8o8nevHOd4i4lqgtznE/28QwlcdJyF8yBiWHpnyjhEpmNWJURgOCOg2xpwRMBCsj
+MScqYPtOhBeuYQvSwAEeTML2Ukh6uGuX4E14q65Ja8cdjF5bAldnP1eE4FBaAwsZ
+G2fOqqrKV03Y85Nw2btedP1AtliQuJZs/Jo/gXxXdc7LrH3McgnpnbTiAncX7yES
+hP6kzQejllqMCIt52HOjxDGWafS7Xw+DKwqmH+Eqy8dcbOuag/1AYlQoKNVK3F5q
+Hh6tEDiMqQcLIibGKteE6iHo4A/bIScbzrhXUYuism42ZYzmc48FMVIH3qy4L84E
+TdAH2gtxw0PAhvRVXp8HP7wfngpzsN/8xOTpeRSbM4+Qbc56G6+Bifmv6sk1ieQb
+NA3wJdl4DDUuQSV8hBgx6zoI1ZSGORprDFux7c6rhc77QZMSRrEgomBeklervEve
+86ylWmZ3WWHV6RLMi8xNvjd71r4EPIGgY7BZU/VPBkq+uA7Gb6mbJnFgV43uh3xy
+LRFgxIAphIukwTGSMZZR+AI+Qnp0BYTWovHXozOf3H8r6hozEoT02JHn0AeTfA==
+-----END CERTIFICATE-----`,
+    `-----BEGIN CERTIFICATE-----
+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
+-----END CERTIFICATE-----`,
+  ];
 
   // Cache Mechanism
   private static isCacheEnabled = false;
@@ -580,15 +661,234 @@ export class TDK {
       .replace(/<\/(p|div)>/gi, "\n\n")
       .replace(/<[^>]+>/g, "")
       .replace(/&nbsp;/gi, " ")
-      .replace(/&amp;/gi, "&")
+      .replace(/&lt;/gi, "<")
+      .replace(/&gt;/gi, ">")
       .replace(/&quot;/gi, '"')
       .replace(/&#39;|&rsquo;/gi, "'")
+      .replace(/&amp;/gi, "&")
       .replace(/[ \t]+/g, " ")
       .replace(/[ \t]*\n[ \t]*/g, "\n")
       .replace(/\n{3,}/g, "\n\n")
       .trim();
   }
 
+  /**
+   * GETs a JSON path from Kubbealtı Lugatı's data API (`eski.lugatim.com`),
+   * supplying `KUBBEALTI_EXTRA_CA` to work around that host's incomplete
+   * certificate chain (see the constant's doc comment). Fails closed to
+   * `null` on any error — network, TLS, HTTP, or JSON parse.
+   */
+  private static fetchKubbealtiJson(path: string): Promise<any> {
+    return new Promise((resolve) => {
+      const req = https.request(
+        {
+          hostname: this.KUBBEALTI_HOST,
+          path,
+          method: "GET",
+          ca: [...tls.rootCertificates, ...this.KUBBEALTI_EXTRA_CA],
+          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",
+          },
+        },
+        (res) => {
+          if (res.statusCode !== 200) {
+            res.resume();
+            resolve(null);
+            return;
+          }
+          let body = "";
+          res.on("data", (chunk) => (body += chunk));
+          res.on("end", () => {
+            try {
+              resolve(JSON.parse(body));
+            } catch {
+              resolve(null);
+            }
+          });
+        }
+      );
+      req.on("error", () => resolve(null));
+      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.
+   */
+  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. 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;
+    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 [];
+  }
+
+  /**
+   * Same as `getKubbealti()` but with each entry's `anlam` HTML stripped to
+   * plain text via `htmlToPlainText()`.
+   */
+  public static async getKubbealtiMeanings(word: string): Promise<string[] | null> {
+    const entries = await this.getKubbealti(word);
+    if (!entries) return null;
+    return entries.map((e) => this.htmlToPlainText(e.anlam));
+  }
+
+  /**
+   * Autocomplete suggestions from Kubbealtı Lugatı's own typeahead endpoint
+   * (separate from `getSuggestions()`, which uses TDK's data).
+   */
+  public static async getKubbealtiSuggestions(prefix: string): Promise<string[]> {
+    if (!prefix || prefix.trim() === "") return [];
+    const data = await this.fetchKubbealtiJson(`/rest/word-search/${encodeURIComponent(prefix.trim())}`);
+    if (!Array.isArray(data)) return [];
+    return data.map((item: any) => item.display).filter(Boolean);
+  }
+
+  /**
+   * Returns the etymology paragraph for a word from Nişanyan Sözlük, scraped
+   * from that page's server-rendered `<meta name="description">` tag (the
+   * page already puts the full etymology text there for SEO, so no need to
+   * parse the site's internal SvelteKit data format). Returns `null` if the
+   * word isn't found (the page falls back to a generic site tagline in that
+   * case) or the request fails.
+   */
+  public static async getNisanyan(word: string): Promise<string | null> {
+    if (!word || word.trim() === "") return null;
+    try {
+      const response = await fetch(
+        `https://www.nisanyansozluk.com/kelime/${encodeURIComponent(word.trim().toLocaleLowerCase("tr-TR"))}`,
+        { headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" } }
+      );
+      if (!response.ok) return null;
+      const html = await response.text();
+      const match = html.match(/<meta name="description" content="([^"]*)"/);
+      if (!match) return null;
+      const description = this.htmlToPlainText(match[1]);
+      if (description === "Çağdaş Türkçenin Etimolojisi") return null;
+      return description;
+    } catch {
+      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(
+        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;
+      const data = await response.json();
+      const page = data?.query?.pages?.[0];
+      if (!page || page.missing || !page.extract) return null;
+
+      const raw: string = page.extract;
+      const sections: Record<string, string> = {};
+      const parts = raw.split(/\n(={2,4})\s*(.+?)\s*\1\n/);
+      // parts[0] is text before the first heading (usually empty); after
+      // that, headings and their following text alternate in triples.
+      for (let i = 1; i < parts.length; i += 3) {
+        const title = parts[i + 1]?.trim();
+        const content = parts[i + 2]?.trim();
+        if (title) sections[title] = 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.
+   */
+  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
+   * case-insensitively. Returns `null` if the word or the section isn't found.
+   */
+  public static async getWiktionarySection(word: string, sectionName: string): Promise<string | null> {
+    const entry = await this.getWiktionary(word);
+    if (!entry) return null;
+    const key = Object.keys(entry.sections).find(
+      (k) => k.toLocaleLowerCase("tr-TR") === sectionName.trim().toLocaleLowerCase("tr-TR")
+    );
+    return key ? entry.sections[key] : null;
+  }
+
   /**
    * Returns compound words that contain this word.
    */

package/src/types.ts

@@ -123,4 +123,14 @@ export interface WordAnalysis {
   origin: string | null;
 }
 
+export interface KubbealtiEntry {
+  kelime: string;
+  anlam: string;
+}
+
+export interface WiktionaryEntry {
+  raw: string;
+  sections: Record<string, string>;
+}
+
 export type TDKResponse = WordInfo[] | { error: string };