tdk-api-wrapper 1.0.1 → 1.2.0

package/dist/index.d.ts

@@ -96,6 +96,36 @@ interface SpellCheckResult {
     word: string;
     suggestion?: string;
 }
+interface WordOfTheDay {
+    word: string;
+    meanings: string[];
+}
+interface DailyPick {
+    type: "kelime" | "atasoz";
+    madde: string;
+    anlam: string;
+}
+interface TDKRule {
+    adi: string;
+    url: string;
+}
+interface WordComparisonSide {
+    word: string;
+    meaningCount: number;
+    origin: string | null;
+    syllables: string[];
+    harmony: boolean;
+}
+interface WordComparison {
+    a: WordComparisonSide;
+    b: WordComparisonSide;
+}
+interface WordAnalysis {
+    word: string;
+    found: boolean;
+    meaning: string | null;
+    origin: string | null;
+}
 type TDKResponse = WordInfo[] | {
     error: string;
 };
@@ -105,6 +135,7 @@ type TDKResponse = WordInfo[] | {
  */
 declare class TDK {
     private static readonly BASE_URL;
+    private static readonly AUDIO_API_HOST;
     private static isCacheEnabled;
     private static wordCache;
     private static dailyContentCache;
@@ -127,7 +158,22 @@ declare class TDK {
      */
     static getMeanings(word: string): Promise<string[]>;
     /**
-     * Returns suggestions (autocomplete) for a given prefix.
+     * `sozluk.gov.tr`'s dedicated `/autocomplete.json` (and `/data/autocomplete.json`)
+     * routes no longer serve JSON — they fall through to the SPA's `index.html`.
+     * The full ~81k-word headword list the site's own autocomplete UI uses is
+     * instead bundled directly into its main JS asset as a
+     * `JSON.parse(\`[{"madde":"..."}]\`)` literal, so this fetches the home
+     * page to find that asset's current hashed filename, downloads it (a few
+     * MB, only once per process), and extracts the literal out of it. Fragile
+     * scraping of an implementation detail — if TDK's build stops embedding
+     * this, this fails closed to `[]` rather than throwing.
+     */
+    private static fetchAutocompleteData;
+    /**
+     * Returns autocomplete suggestions for a given prefix, searched over TDK's
+     * full headword list (see `fetchAutocompleteData`). The list is fetched
+     * and cached once per process regardless of `enableCache()` — the same
+     * caching behavior as before — and only cleared by `clearCache()`.
      */
     static getSuggestions(prefix: string): Promise<string[]>;
     /**
@@ -135,9 +181,21 @@ declare class TDK {
      */
     static getProverbs(word: string): Promise<string[]>;
     /**
-     * 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.
      */
     static getOrigin(word: string): Promise<string | null>;
+    /**
+     * Returns whether the word has a recorded foreign etymological origin.
+     * Returns `null` (instead of a boolean) when the word isn't found at all.
+     */
+    static isForeignWord(word: string): Promise<boolean | null>;
+    /**
+     * Groups a list of words by their etymological origin. Words not found in
+     * the dictionary are grouped under "Bilinmiyor". Throttled like getWordsBatch.
+     */
+    static groupByOrigin(words: string[]): Promise<Record<string, string[]>>;
     /**
      * Returns literature examples containing the word.
      */
@@ -146,8 +204,34 @@ declare class TDK {
         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.
+     * 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;
+    private static fetchSeskod;
+    /**
+     * 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.
+     */
+    static getSynonyms(word: string): Promise<string[]>;
+    /**
+     * 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.
+     */
+    static getAntonyms(word: string): Promise<string[]>;
+    /**
+     * Returns the direct URL of the audio pronunciation, if TDK has one recorded for this word.
      */
     static getAudioUrl(word: string): Promise<string | null>;
     /**
@@ -162,14 +246,70 @@ declare class TDK {
      * Fetches daily content (word of the day, proverbs, rules, etc).
      */
     static getDailyContent(): Promise<DailyContent | null>;
+    /**
+     * Returns today's word of the day along with all of its listed meanings.
+     */
+    static getWordOfTheDay(): Promise<WordOfTheDay | null>;
+    /**
+     * Picks a random entry (word or proverb) from today's daily content.
+     * Note: this samples from today's `getDailyContent()` picks, not the full dictionary.
+     */
+    static getRandomWord(): Promise<DailyPick | null>;
+    /**
+     * 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.
+     */
+    static getKurallar(): Promise<TDKRule[]>;
+    /**
+     * 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.
+     */
+    static getRule(name: string): Promise<string | 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 fetchRuleText;
+    private static htmlToPlainText;
     /**
      * Returns compound words that contain this word.
      */
     static getCompoundWords(word: string): Promise<string[]>;
     /**
      * 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.
      */
     static getPartOfSpeech(word: string): Promise<string[]>;
+    /**
+     * Compares two words side by side: meaning count, etymological origin,
+     * syllables and vowel-harmony compliance.
+     */
+    static compareWords(a: string, b: string): Promise<WordComparison>;
+    private static readonly STOPWORDS;
+    private static firstMeaning;
+    /**
+     * 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.
+     */
+    static analyzeText(text: string): Promise<WordAnalysis[]>;
+    /**
+     * Classic edit-distance between two strings.
+     */
+    private static levenshtein;
     /**
      * Fetches multiple words concurrently with a small delay to avoid rate limiting.
      */
@@ -180,8 +320,36 @@ declare class TDK {
     static syllabicate(word: string): string[];
     /**
      * 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).
      */
     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 };
+/**
+ * Base class for all errors thrown by this library.
+ */
+declare class TDKError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a caller-supplied argument is invalid (e.g. an empty word).
+ */
+declare class TDKValidationError extends TDKError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a request to sozluk.gov.tr fails at the network/HTTP level
+ * (connection failure, non-OK HTTP status, unparsable response, etc).
+ */
+declare class TDKNetworkError extends TDKError {
+    readonly status?: number;
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+
+export { type Author, type DailyContent, type DailyPick, type Example, type Feature, type Meaning, type Proverb, type SpellCheckResult, TDK, TDKError, TDKNetworkError, type TDKResponse, type TDKRule, TDKValidationError, type WordAnalysis, type WordComparison, type WordComparisonSide, type WordInfo, type WordOfTheDay };