yokatlas-api-wrapper 1.0.0

package/dist/index.js

@@ -0,0 +1,827 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BIRIM_TURU: () => BIRIM_TURU,
+  BIRIM_TURU_ETIKETLERI: () => BIRIM_TURU_ETIKETLERI,
+  BURS_ORANI: () => BURS_ORANI,
+  PUAN_TURU_ETIKETLERI: () => PUAN_TURU_ETIKETLERI,
+  UNIVERSITE_TURU_ETIKETLERI: () => UNIVERSITE_TURU_ETIKETLERI,
+  YokAtlas: () => YokAtlas,
+  YokAtlasAPIError: () => YokAtlasAPIError,
+  YokAtlasError: () => YokAtlasError,
+  YokAtlasLookupError: () => YokAtlasLookupError,
+  YokAtlasNotFoundError: () => YokAtlasNotFoundError,
+  YokAtlasRateLimitError: () => YokAtlasRateLimitError,
+  YokAtlasValidationError: () => YokAtlasValidationError,
+  default: () => index_default,
+  getBirimTuruLabel: () => getBirimTuruLabel,
+  getPuanTuruLabel: () => getPuanTuruLabel,
+  getUniversiteTuruLabel: () => getUniversiteTuruLabel
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var YokAtlasError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "YokAtlasError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var YokAtlasValidationError = class extends YokAtlasError {
+  constructor(message) {
+    super(message);
+    this.name = "YokAtlasValidationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var YokAtlasAPIError = class extends YokAtlasError {
+  status;
+  body;
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = "YokAtlasAPIError";
+    this.status = options?.status;
+    this.body = options?.body;
+    this.cause = options?.cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var YokAtlasNotFoundError = class extends YokAtlasAPIError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "YokAtlasNotFoundError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var YokAtlasRateLimitError = class extends YokAtlasAPIError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "YokAtlasRateLimitError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var YokAtlasLookupError = class extends YokAtlasError {
+  query;
+  kind;
+  suggestions;
+  constructor(query, options) {
+    const base = query ? `'${query}' i\xE7in bir ${options.kind} bulunamad\u0131.` : `Bo\u015F bir ${options.kind} ad\u0131 \xE7\xF6z\xFCmlenemez.`;
+    const message = options.suggestions && options.suggestions.length > 0 ? `${base} \u015Eunu mu demek istediniz: ${options.suggestions.join(", ")}?` : base;
+    super(message);
+    this.name = "YokAtlasLookupError";
+    this.query = query;
+    this.kind = options.kind;
+    this.suggestions = options.suggestions ?? [];
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/lookup.ts
+var TR_MAP = {
+  "\u0130": "I",
+  "\u0131": "i",
+  "\u011E": "G",
+  "\u011F": "g",
+  "\u015E": "S",
+  "\u015F": "s",
+  "\xC7": "C",
+  "\xE7": "c",
+  "\xD6": "O",
+  "\xF6": "o",
+  "\xDC": "U",
+  "\xFC": "u"
+};
+function normalizeTurkish(text) {
+  const ascii = text.replace(/[İıĞğŞşÇçÖöÜü]/g, (ch) => TR_MAP[ch] ?? ch);
+  return ascii.toLowerCase().trim().replace(/\s+/g, " ");
+}
+function levenshteinDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array(n + 1);
+  let curr = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+function similarityRatio(a, b) {
+  const maxLen = Math.max(a.length, b.length);
+  if (maxLen === 0) return 1;
+  return 1 - levenshteinDistance(a, b) / maxLen;
+}
+function resolveByName(query, items, nameOf, kind, cutoff = 0.6) {
+  if (!query || !query.trim()) {
+    throw new YokAtlasLookupError(query, { kind });
+  }
+  const key = normalizeTurkish(query);
+  for (const item of items) {
+    if (normalizeTurkish(nameOf(item)) === key) return item;
+  }
+  for (const item of items) {
+    const norm = normalizeTurkish(nameOf(item));
+    if (norm.includes(key) || key.includes(norm)) return item;
+  }
+  let best = null;
+  let bestScore = -1;
+  const scored = [];
+  for (const item of items) {
+    const score = similarityRatio(key, normalizeTurkish(nameOf(item)));
+    scored.push({ item, score });
+    if (score > bestScore) {
+      bestScore = score;
+      best = item;
+    }
+  }
+  if (best && bestScore >= cutoff) return best;
+  const suggestions = scored.sort((x, y) => y.score - x.score).filter((s) => s.score >= 0.4).slice(0, 3).map((s) => nameOf(s.item));
+  throw new YokAtlasLookupError(query, { kind, suggestions });
+}
+
+// src/yokatlas.ts
+var SEARCH_PATH = "/api/tercih-kilavuz/search";
+var UNIVERSITIES_PATH = "/api/tercih-kilavuz/universiteler";
+var PROGRAMS_PATH = "/api/tercih-kilavuz/universite-programlar";
+var CITIES_PATH = "/api/tercih-kilavuz/universite-iller";
+var NETLER_SEARCH_PATH = "/api/netler/search";
+var YEARLY_OFFSET_FIELDS = {
+  kontenjan: "kontenjan",
+  yerlesen: "gkY",
+  kontenjanObs: "kontenjanObs",
+  kontenjanY34: "kontenjanY34",
+  prof: "prof",
+  doc: "doc",
+  dou: "dou",
+  ogrGor: "ogrGor",
+  arGor: "arGor",
+  kpss1: "kpss1",
+  kpss2: "kpss2",
+  minPuan: "minPuan",
+  basariSirasi: "basariSirasi"
+};
+var YokAtlas = class {
+  static baseUrl = "https://yokatlas.yok.gov.tr";
+  static timeoutMs = 3e4;
+  static userAgent = "yokatlas-api-wrapper/1.0 (+https://www.npmjs.com/package/yokatlas-api-wrapper)";
+  static maxRetries = 2;
+  static lookupCacheTtlMs = 36e5;
+  static lookupCache = null;
+  constructor() {
+  }
+  // ---------------------------------------------------------------------
+  // Yapılandırma
+  // ---------------------------------------------------------------------
+  /** İstemcinin temel URL'sini, zaman aşımını, User-Agent'ını, retry ve önbellek ayarlarını değiştirir. */
+  static configure(config) {
+    if (config.baseUrl !== void 0) this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    if (config.timeoutMs !== void 0) this.timeoutMs = config.timeoutMs;
+    if (config.userAgent !== void 0) this.userAgent = config.userAgent;
+    if (config.maxRetries !== void 0) this.maxRetries = config.maxRetries;
+    if (config.lookupCacheTtlMs !== void 0) this.lookupCacheTtlMs = config.lookupCacheTtlMs;
+  }
+  // ---------------------------------------------------------------------
+  // Temel arama
+  // ---------------------------------------------------------------------
+  /** YÖK Atlas tercih kılavuzunda program arar. */
+  static async search(filters = {}, options = {}) {
+    const { page = 0, size = 20, sortBy = "basariSirasi", direction = "ASC", smartSearch = true, signal } = options;
+    let resolved = filters;
+    if (smartSearch && (filters.universite != null || filters.program != null || filters.il != null)) {
+      await this.ensureLookups();
+      resolved = this.resolveSmartFilters(filters);
+    }
+    const body = {
+      filters: this.filtersToPayload(resolved),
+      page,
+      size,
+      sortBy,
+      direction: direction.toUpperCase()
+    };
+    const raw = await this.postJson(SEARCH_PATH, body, signal);
+    return this.toSearchPage(raw, (row) => this.buildProgram(row));
+  }
+  /** Net Sihirbazı'nı sorgular: son yerleşen kişinin TYT/AYT/YDT netleri. */
+  static async searchNetler(filters = {}, options = {}) {
+    const { page = 0, size = 20, smartSearch = true, signal } = options;
+    let resolved = filters;
+    if (smartSearch && (filters.universite != null || filters.program != null)) {
+      await this.ensureLookups();
+      resolved = this.resolveNetSmartFilters(filters);
+    }
+    const body = { filters: this.netFiltersToPayload(resolved), page, size };
+    const raw = await this.postJson(NETLER_SEARCH_PATH, body, signal);
+    return this.toSearchPage(raw, (row) => this.buildNet(row));
+  }
+  /** Tek bir programı ÖSYM kılavuz kodundan getirir; bulunamazsa `null` döner. */
+  static async getProgram(kilavuzKodu, signal) {
+    const code = Number(kilavuzKodu);
+    if (!Number.isFinite(code)) {
+      throw new YokAtlasValidationError(`kilavuzKodu bir say\u0131 olmal\u0131 (al\u0131nan: ${String(kilavuzKodu)})`);
+    }
+    const page = await this.search({ kilavuzKodu: code }, { size: 1, smartSearch: false, signal });
+    return page.content[0] ?? null;
+  }
+  /**
+   * Birden çok programı kılavuz koduyla, sınırlı eşzamanlılıkla getirir.
+   * Her kod bağımsız çözülür — biri başarısız olursa diğerlerini etkilemez.
+   */
+  static async getPrograms(kilavuzKodlari, options = {}) {
+    const { concurrency = 4, signal } = options;
+    const results = new Array(
+      kilavuzKodlari.length
+    );
+    let index = 0;
+    const worker = async () => {
+      while (index < kilavuzKodlari.length) {
+        const i = index++;
+        const kod = kilavuzKodlari[i];
+        try {
+          const program = await this.getProgram(kod, signal);
+          results[i] = { kilavuzKodu: kod, status: "fulfilled", program };
+        } catch (reason) {
+          results[i] = { kilavuzKodu: kod, status: "rejected", reason };
+        }
+      }
+    };
+    const workers = Array.from({ length: Math.max(1, Math.min(concurrency, kilavuzKodlari.length || 1)) }, () => worker());
+    await Promise.all(workers);
+    return results;
+  }
+  /**
+   * `search()`'ü sayfa sayfa dolaşıp tüm sonuçları düz bir diziye toplar.
+   * `maxPages` güvenlik sınırına takılırsa erken durur.
+   */
+  static async searchAllPages(filters = {}, options = {}) {
+    const { pageSize = 100, maxPages = 50, sortBy, direction, smartSearch = true, signal } = options;
+    const all = [];
+    let resolvedFilters = filters;
+    if (smartSearch && (filters.universite != null || filters.program != null || filters.il != null)) {
+      await this.ensureLookups(signal);
+      resolvedFilters = this.resolveSmartFilters(filters);
+    }
+    for (let page = 0; page < maxPages; page++) {
+      const result = await this.search(resolvedFilters, {
+        page,
+        size: pageSize,
+        sortBy,
+        direction,
+        smartSearch: false,
+        signal
+      });
+      all.push(...result.content);
+      if (result.last || result.content.length === 0) break;
+    }
+    return all;
+  }
+  // ---------------------------------------------------------------------
+  // Lookup tabloları
+  // ---------------------------------------------------------------------
+  /** Tüm üniversiteleri (ID + ad) döner. */
+  static async listUniversities(signal) {
+    await this.ensureLookups(signal);
+    return [...this.lookupCache.universities];
+  }
+  /** Tüm program gruplarını (ID + ad + puan türü) döner. */
+  static async listProgramGroups(signal) {
+    await this.ensureLookups(signal);
+    return [...this.lookupCache.programGroups];
+  }
+  /** Tüm illeri (kod + ad) döner. */
+  static async listCities(signal) {
+    await this.ensureLookups(signal);
+    return [...this.lookupCache.cities];
+  }
+  /** Lookup önbelleğini zorla yeniler. */
+  static async refreshLookups(signal) {
+    this.lookupCache = null;
+    await this.fetchLookups(signal);
+  }
+  /** Lookup önbelleğini boşaltır (bir sonraki çağrıda yeniden çekilir). */
+  static clearCache() {
+    this.lookupCache = null;
+  }
+  /** Lookup önbelleğinin durumunu (dolu mu, ne zaman çekildi, kaç kayıt var) döner. */
+  static getCacheStatus() {
+    const cache = this.lookupCache;
+    return {
+      cached: cache !== null,
+      fetchedAt: cache?.fetchedAt ?? null,
+      ageMs: cache ? Date.now() - cache.fetchedAt : null,
+      ttlMs: this.lookupCacheTtlMs,
+      universiteSayisi: cache?.universities.length ?? 0,
+      programGrubuSayisi: cache?.programGroups.length ?? 0,
+      ilSayisi: cache?.cities.length ?? 0
+    };
+  }
+  /** Serbest yazılmış bir üniversite adını fuzzy eşleştirerek {@link University} kaydına çözer. */
+  static async findUniversity(name, signal) {
+    await this.ensureLookups(signal);
+    return resolveByName(name, this.lookupCache.universities, (u) => u.universiteAdi, "\xFCniversite");
+  }
+  /** Serbest yazılmış bir program adını fuzzy eşleştirerek {@link ProgramGroup} kaydına çözer. */
+  static async findProgramGroup(name, signal) {
+    await this.ensureLookups(signal);
+    return resolveByName(name, this.lookupCache.programGroups, (p) => p.birimGrupAdi, "program");
+  }
+  /** Serbest yazılmış bir il adını fuzzy eşleştirerek {@link City} kaydına çözer. */
+  static async findCity(name, signal) {
+    await this.ensureLookups(signal);
+    return resolveByName(name, this.lookupCache.cities, (c) => c.ilAdi, "il");
+  }
+  // ---------------------------------------------------------------------
+  // Kısayol aramalar
+  // ---------------------------------------------------------------------
+  /** Belirli bir üniversitenin (serbest yazım) tüm programlarını arar. */
+  static async searchByUniversity(universiteAdi, filters = {}, options = {}) {
+    return this.search({ ...filters, universite: universiteAdi }, options);
+  }
+  /** Belirli bir program grubunu (serbest yazım) tüm üniversitelerde arar. */
+  static async searchByProgram(programAdi, filters = {}, options = {}) {
+    return this.search({ ...filters, program: programAdi }, options);
+  }
+  /** Belirli bir ildeki (serbest yazım) tüm programları arar. */
+  static async searchByCity(ilAdi, filters = {}, options = {}) {
+    return this.search({ ...filters, il: ilAdi }, options);
+  }
+  /** Sadece lisans (4 yıllık) programlarını arar. */
+  static async searchLisans(filters = {}, options = {}) {
+    return this.search({ ...filters, birimTuruId: 46 }, options);
+  }
+  /** Sadece ön lisans (2 yıllık) programlarını arar. */
+  static async searchOnlisans(filters = {}, options = {}) {
+    return this.search({ ...filters, birimTuruId: 47 }, options);
+  }
+  /** Sadece ücretsiz/tam burslu programları arar. */
+  static async searchBurslu(filters = {}, options = {}) {
+    return this.search({ ...filters, bursOraniId: 0 }, options);
+  }
+  /** Belirli bir başarı sırası aralığındaki programları arar (`minBasariSirasi`/`maxBasariSirasi` kısayolu). */
+  static async searchByScoreRange(range, filters = {}, options = {}) {
+    return this.search({ ...filters, minBasariSirasi: range.min ?? null, maxBasariSirasi: range.max ?? null }, options);
+  }
+  // ---------------------------------------------------------------------
+  // Türetilmiş / çevrimdışı analiz yardımcıları (ekstra ağ isteği yapmaz)
+  // ---------------------------------------------------------------------
+  /**
+   * Kullanıcının kendi başarı sırasını, bir programın güncel yıl kesme
+   * sırasıyla karşılaştırarak kaba bir yerleşme tahmini üretir. Sıra ne
+   * kadar küçükse o kadar iyi bir konumdur (1. sıra en iyisidir).
+   */
+  static estimateAdmission(program, basariSirasi) {
+    const cutoff = program.current.basariSirasi;
+    if (cutoff === null) {
+      return {
+        program,
+        basariSirasi,
+        cutoffBasariSirasi: null,
+        verdict: "belirsiz",
+        margin: null,
+        message: "Bu program i\xE7in g\xFCncel y\u0131l ba\u015Far\u0131 s\u0131ras\u0131 verisi yok; tahmin yap\u0131lam\u0131yor."
+      };
+    }
+    const margin = basariSirasi - cutoff;
+    const relativeMargin = margin / cutoff;
+    let verdict;
+    let message;
+    if (relativeMargin <= -0.1) {
+      verdict = "kesine yak\u0131n";
+      message = `S\u0131ran\u0131z (${basariSirasi.toLocaleString("tr-TR")}) ge\xE7en y\u0131lki kesme s\u0131ras\u0131ndan (${cutoff.toLocaleString("tr-TR")}) belirgin \u015Fekilde iyi; yerle\u015Fme olas\u0131l\u0131\u011F\u0131n\u0131z y\xFCksek.`;
+    } else if (relativeMargin <= 0) {
+      verdict = "olas\u0131";
+      message = `S\u0131ran\u0131z (${basariSirasi.toLocaleString("tr-TR")}) ge\xE7en y\u0131lki kesme s\u0131ras\u0131ndan (${cutoff.toLocaleString("tr-TR")}) iyi; yerle\u015Fmeniz olas\u0131 ama kesin de\u011Fil.`;
+    } else if (relativeMargin <= 0.1) {
+      verdict = "s\u0131n\u0131rda";
+      message = `S\u0131ran\u0131z (${basariSirasi.toLocaleString("tr-TR")}) ge\xE7en y\u0131lki kesme s\u0131ras\u0131na (${cutoff.toLocaleString("tr-TR")}) yak\u0131n; s\u0131n\u0131rda bir durum.`;
+    } else {
+      verdict = "zay\u0131f";
+      message = `S\u0131ran\u0131z (${basariSirasi.toLocaleString("tr-TR")}) ge\xE7en y\u0131lki kesme s\u0131ras\u0131ndan (${cutoff.toLocaleString("tr-TR")}) belirgin \u015Fekilde geride; yerle\u015Fme olas\u0131l\u0131\u011F\u0131n\u0131z d\xFC\u015F\xFCk.`;
+    }
+    return { program, basariSirasi, cutoffBasariSirasi: cutoff, verdict, margin, message };
+  }
+  /** İki programı güncel yıl rekabet düzeyi (başarı sırası) ve kontenjan açısından karşılaştırır. */
+  static compare(a, b) {
+    const aScore = a.current.basariSirasi;
+    const bScore = b.current.basariSirasi;
+    let moreCompetitive = "belirsiz";
+    if (aScore !== null && bScore !== null) {
+      if (aScore < bScore) moreCompetitive = "a";
+      else if (bScore < aScore) moreCompetitive = "b";
+      else moreCompetitive = "e\u015Fit";
+    }
+    const scoreDiff = aScore !== null && bScore !== null ? aScore - bScore : null;
+    const aQuota = a.current.kontenjan;
+    const bQuota = b.current.kontenjan;
+    const quotaDiff = aQuota !== null && bQuota !== null ? aQuota - bQuota : null;
+    return { a, b, moreCompetitive, scoreDiff, quotaDiff };
+  }
+  /**
+   * Bir programın `history` + `current` verisindeki başarı sırası dizisine
+   * bakarak eğilimini ("yükseliyor"/"düşüyor"/"sabit") kestirir. Başarı
+   * sırasının küçülmesi programın *daha* rekabetçi hale geldiği anlamına gelir.
+   */
+  static getTrend(program) {
+    const series = [...program.history].slice().reverse().concat(program.current).map((s) => ({ year: s.year, basariSirasi: s.basariSirasi }));
+    const known = series.filter((s) => s.basariSirasi !== null);
+    if (known.length < 2) {
+      return { program, direction: "belirsiz", series, message: "E\u011Filim hesaplamak i\xE7in yeterli y\u0131ll\u0131k veri yok." };
+    }
+    const first = known[0].basariSirasi;
+    const last = known[known.length - 1].basariSirasi;
+    const changeRatio = (last - first) / first;
+    let direction;
+    let message;
+    if (changeRatio <= -0.05) {
+      direction = "y\xFCkseliyor";
+      message = `Ba\u015Far\u0131 s\u0131ras\u0131 ${known[0].year}'den ${known[known.length - 1].year}'e k\xFC\xE7\xFClm\xFC\u015F (${first.toLocaleString("tr-TR")} \u2192 ${last.toLocaleString("tr-TR")}); program giderek daha rekabet\xE7i hale geliyor.`;
+    } else if (changeRatio >= 0.05) {
+      direction = "d\xFC\u015F\xFCyor";
+      message = `Ba\u015Far\u0131 s\u0131ras\u0131 ${known[0].year}'den ${known[known.length - 1].year}'e b\xFCy\xFCm\xFC\u015F (${first.toLocaleString("tr-TR")} \u2192 ${last.toLocaleString("tr-TR")}); program\u0131n rekabet d\xFCzeyi azal\u0131yor.`;
+    } else {
+      direction = "sabit";
+      message = `Ba\u015Far\u0131 s\u0131ras\u0131 ${known[0].year}'den ${known[known.length - 1].year}'e b\xFCy\xFCk \xF6l\xE7\xFCde stabil kalm\u0131\u015F (${first.toLocaleString("tr-TR")} \u2192 ${last.toLocaleString("tr-TR")}).`;
+    }
+    return { program, direction, series, message };
+  }
+  /** Bir program dizisini, verilen anahtar fonksiyonuna göre gruplar. */
+  static groupBy(programs, keyFn) {
+    const result = {};
+    for (const program of programs) {
+      const key = keyFn(program);
+      if (!result[key]) result[key] = [];
+      result[key].push(program);
+    }
+    return result;
+  }
+  /** Bir program dizisini güncel yıl başarı sırasına göre sıralar (varsayılan: küçükten büyüğe / en iyi önce). */
+  static sortByScore(programs, direction = "asc") {
+    const withScore = programs.filter((p) => p.current.basariSirasi !== null);
+    const withoutScore = programs.filter((p) => p.current.basariSirasi === null);
+    withScore.sort((a, b) => {
+      const diff = a.current.basariSirasi - b.current.basariSirasi;
+      return direction === "asc" ? diff : -diff;
+    });
+    return [...withScore, ...withoutScore];
+  }
+  /** Bir programı tek satırlık okunur bir özet metnine çevirir (log/konsol için). */
+  static formatSummary(program) {
+    const puan = program.current.minPuan !== null ? program.current.minPuan.toLocaleString("tr-TR") : "\u2014";
+    const sira = program.current.basariSirasi !== null ? program.current.basariSirasi.toLocaleString("tr-TR") : "\u2014";
+    return `${program.universiteAdi} \u2014 ${program.birimAdi} (${program.puanTuru}, ${program.current.year}) | Puan: ${puan} \xB7 S\u0131ra: ${sira}`;
+  }
+  // ---------------------------------------------------------------------
+  // İç mekanizma — lookup önbelleği
+  // ---------------------------------------------------------------------
+  static async ensureLookups(signal) {
+    const cache = this.lookupCache;
+    const fresh = cache !== null && (this.lookupCacheTtlMs <= 0 || Date.now() - cache.fetchedAt < this.lookupCacheTtlMs);
+    if (fresh) return;
+    await this.fetchLookups(signal);
+  }
+  static async fetchLookups(signal) {
+    const [universities, programGroups, cities] = await Promise.all([
+      this.getJson(UNIVERSITIES_PATH, signal),
+      this.getJson(PROGRAMS_PATH, signal),
+      this.getJson(CITIES_PATH, signal)
+    ]);
+    this.lookupCache = { universities, programGroups, cities, fetchedAt: Date.now() };
+  }
+  static resolveSmartFilters(filters) {
+    const cache = this.lookupCache;
+    const resolved = { ...filters };
+    if (filters.universite != null) {
+      const names = Array.isArray(filters.universite) ? filters.universite : [filters.universite];
+      resolved.universiteId = names.map((n) => resolveByName(n, cache.universities, (u) => u.universiteAdi, "\xFCniversite").universiteId);
+      resolved.universite = null;
+    }
+    if (filters.program != null) {
+      const names = Array.isArray(filters.program) ? filters.program : [filters.program];
+      resolved.birimGrupId = names.map((n) => resolveByName(n, cache.programGroups, (p) => p.birimGrupAdi, "program").birimGrupId);
+      resolved.program = null;
+    }
+    if (filters.il != null) {
+      const names = Array.isArray(filters.il) ? filters.il : [filters.il];
+      resolved.ilKodu = names.map((n) => resolveByName(n, cache.cities, (c) => c.ilAdi, "il").ilKodu);
+      resolved.il = null;
+    }
+    return resolved;
+  }
+  static resolveNetSmartFilters(filters) {
+    const cache = this.lookupCache;
+    const resolved = { ...filters };
+    if (filters.universite != null) {
+      resolved.universiteId = resolveByName(filters.universite, cache.universities, (u) => u.universiteAdi, "\xFCniversite").universiteId;
+      resolved.universite = null;
+    }
+    if (filters.program != null) {
+      const resolvedProgram = resolveByName(filters.program, cache.programGroups, (p) => p.birimGrupAdi, "program");
+      resolved.birimGrupId = resolvedProgram.birimGrupId;
+      resolved.program = null;
+      if (filters.puanTuru == null) {
+        resolved.puanTuru = resolvedProgram.puanTuru;
+      }
+    }
+    return resolved;
+  }
+  // ---------------------------------------------------------------------
+  // İç mekanizma — payload/response dönüşümleri
+  // ---------------------------------------------------------------------
+  static normalizePuanTuru(value) {
+    if (!value) return null;
+    const upper = value.toUpperCase();
+    if (upper === "SOZ") return "S\xD6Z";
+    if (upper === "DIL") return "D\u0130L";
+    return upper;
+  }
+  static filtersToPayload(f) {
+    return {
+      puanTuru: this.normalizePuanTuru(f.puanTuru),
+      universiteId: f.universiteId ?? [],
+      birimGrupId: f.birimGrupId ?? [],
+      ilKodu: f.ilKodu ?? [],
+      birimTuruId: f.birimTuruId ?? null,
+      universiteTuru: f.universiteTuru ?? null,
+      bursOraniId: f.bursOraniId ?? null,
+      ogrenimTuruId: f.ogrenimTuruId ?? null,
+      kilavuzKodu: f.kilavuzKodu ?? null,
+      minBasariSirasi: f.minBasariSirasi ?? null,
+      maxBasariSirasi: f.maxBasariSirasi ?? null
+    };
+  }
+  static netFiltersToPayload(f) {
+    return {
+      puanTuru: this.normalizePuanTuru(f.puanTuru),
+      universiteId: f.universiteId ?? null,
+      birimGrupId: f.birimGrupId ?? null,
+      birimTuruId: f.birimTuruId ?? null,
+      universiteTuru: f.universiteTuru ?? null,
+      yil: f.yil != null ? String(f.yil) : null,
+      katsayi: f.katsayi ?? null
+    };
+  }
+  static toSearchPage(raw, mapRow) {
+    const content = Array.isArray(raw.content) ? raw.content : [];
+    return {
+      content: content.map(mapRow),
+      totalElements: Number(raw.totalElements ?? content.length),
+      totalPages: Number(raw.totalPages ?? 1),
+      size: Number(raw.size ?? content.length),
+      number: Number(raw.number ?? 0),
+      first: Boolean(raw.first ?? true),
+      last: Boolean(raw.last ?? true),
+      numberOfElements: Number(raw.numberOfElements ?? content.length),
+      empty: Boolean(raw.empty ?? content.length === 0),
+      yil: raw.yil != null ? Number(raw.yil) : null,
+      source: raw.source ?? null
+    };
+  }
+  static normalizeOnlisansSpelling(row) {
+    if (row.birimTuruAdi === "\xD6NLISANS") {
+      return { ...row, birimTuruAdi: "ONLISANS" };
+    }
+    return row;
+  }
+  static toNumber(value) {
+    if (value === null || value === void 0 || value === "") return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+  }
+  static buildYearlyStats(row, suffix, year) {
+    const stats = { year };
+    for (const [field, apiBase] of Object.entries(YEARLY_OFFSET_FIELDS)) {
+      stats[field] = this.toNumber(row[`${apiBase}${suffix}`]);
+    }
+    return stats;
+  }
+  static buildProgram(rawRow) {
+    const row = this.normalizeOnlisansSpelling(rawRow);
+    const year = this.toNumber(row.yil) ?? 0;
+    const current = this.buildYearlyStats(row, "", year);
+    const history = [1, 2, 3].map((offset) => this.buildYearlyStats(row, String(offset), year - offset));
+    return {
+      osymKilavuzId: this.toNumber(row.osymKilavuzId),
+      sinav: row.sinav ?? null,
+      yil: year,
+      donem: row.donem ?? null,
+      tabloTuru: row.tabloTuru ?? null,
+      birimId: this.toNumber(row.birimId),
+      birimHiyerarsi: row.birimHiyerarsi ?? null,
+      kilavuzKodu: this.toNumber(row.kilavuzKodu),
+      universiteId: this.toNumber(row.universiteId),
+      universiteAdi: row.universiteAdi,
+      uniIlKodu: this.toNumber(row.uniIlKodu),
+      uniIlAdi: row.uniIlAdi ?? null,
+      uniIlceKodu: this.toNumber(row.uniIlceKodu),
+      uniIlceAdi: row.uniIlceAdi ?? null,
+      fymkId: this.toNumber(row.fymkId),
+      fymkAdi: row.fymkAdi ?? null,
+      fymkIlKodu: this.toNumber(row.fymkIlKodu),
+      fymkIlAdi: row.fymkIlAdi ?? null,
+      fymkIlceKodu: this.toNumber(row.fymkIlceKodu),
+      fymkIlceAdi: row.fymkIlceAdi ?? null,
+      birimAdi: row.birimAdi,
+      birimGrupId: this.toNumber(row.birimGrupId),
+      birimGrupAdi: row.birimGrupAdi ?? null,
+      birimTuruId: this.toNumber(row.birimTuruId),
+      birimTuruAdi: row.birimTuruAdi,
+      ogrenimTuruId: this.toNumber(row.ogrenimTuruId),
+      ogrenimTuruAdi: row.ogrenimTuruAdi ?? null,
+      ogrenimSuresi: this.toNumber(row.ogrenimSuresi),
+      puanTuru: row.puanTuru,
+      ogrenimDiliId: this.toNumber(row.ogrenimDiliId),
+      ogrenimDiliAdi: row.ogrenimDiliAdi ?? null,
+      bursOraniId: this.toNumber(row.bursOraniId),
+      bursOraniAdi: row.bursOraniAdi ?? null,
+      ilKodu: this.toNumber(row.ilKodu),
+      ilAdi: row.ilAdi ?? null,
+      ilceKodu: this.toNumber(row.ilceKodu),
+      ilceAdi: row.ilceAdi ?? null,
+      universiteTuru: row.universiteTuru,
+      current,
+      history
+    };
+  }
+  static buildNet(rawRow) {
+    const row = this.normalizeOnlisansSpelling(rawRow);
+    return {
+      yil: this.toNumber(row.yil),
+      kilavuzKodu: this.toNumber(row.kilavuzKodu),
+      puanTuru: row.puanTuru,
+      katsayi: this.toNumber(row.katsayi),
+      tabanPuan: this.toNumber(row.tabanPuan),
+      obp: this.toNumber(row.obp),
+      tytTrkNet: this.toNumber(row.tytTrkNet),
+      tytSosNet: this.toNumber(row.tytSosNet),
+      tytMatNet: this.toNumber(row.tytMatNet),
+      tytFenNet: this.toNumber(row.tytFenNet),
+      aytMatNet: this.toNumber(row.aytMatNet),
+      aytFizNet: this.toNumber(row.aytFizNet),
+      aytKimNet: this.toNumber(row.aytKimNet),
+      aytBioNet: this.toNumber(row.aytBioNet),
+      aytTdeNet: this.toNumber(row.aytTdeNet),
+      aytTrh1Net: this.toNumber(row.aytTrh1Net),
+      aytCog1Net: this.toNumber(row.aytCog1Net),
+      aytTrh2Net: this.toNumber(row.aytTrh2Net),
+      aytCog2Net: this.toNumber(row.aytCog2Net),
+      aytFelNet: this.toNumber(row.aytFelNet),
+      aytDinNet: this.toNumber(row.aytDinNet),
+      ydtYdilNet: this.toNumber(row.ydtYdilNet),
+      universiteId: this.toNumber(row.universiteId),
+      universiteAdi: row.universiteAdi,
+      birimGrupId: this.toNumber(row.birimGrupId),
+      birimGrupAdi: row.birimGrupAdi ?? null,
+      birimId: this.toNumber(row.birimId),
+      birimAdi: row.birimAdi,
+      birimTuruId: this.toNumber(row.birimTuruId),
+      birimTuruAdi: row.birimTuruAdi,
+      universiteTuru: row.universiteTuru
+    };
+  }
+  // ---------------------------------------------------------------------
+  // İç mekanizma — HTTP taşıma katmanı
+  // ---------------------------------------------------------------------
+  static async getJson(path, signal) {
+    return this.request(path, { method: "GET", signal });
+  }
+  static async postJson(path, body, signal) {
+    return this.request(path, { method: "POST", body: JSON.stringify(body), signal });
+  }
+  static async request(path, init) {
+    const url = `${this.baseUrl}${path}`;
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const timeoutController = new AbortController();
+      const timeoutId = setTimeout(() => timeoutController.abort(), this.timeoutMs);
+      const onExternalAbort = () => timeoutController.abort();
+      init.signal?.addEventListener("abort", onExternalAbort);
+      try {
+        const response = await fetch(url, {
+          method: init.method,
+          headers: {
+            Accept: "application/json",
+            ...init.body ? { "Content-Type": "application/json" } : {},
+            "User-Agent": this.userAgent
+          },
+          body: init.body,
+          signal: timeoutController.signal
+        });
+        return await this.handleResponse(response, path);
+      } catch (error) {
+        lastError = error;
+        if (error instanceof YokAtlasAPIError) throw error;
+        if (init.signal?.aborted) {
+          throw new YokAtlasAPIError(`\u0130stek iptal edildi: ${path}`, { cause: error });
+        }
+        if (attempt === this.maxRetries) {
+          throw new YokAtlasAPIError(`Y\xD6K Atlas API iste\u011Fi ba\u015Far\u0131s\u0131z: ${path}`, { cause: error });
+        }
+        await new Promise((resolve) => setTimeout(resolve, 200 * (attempt + 1)));
+      } finally {
+        clearTimeout(timeoutId);
+        init.signal?.removeEventListener("abort", onExternalAbort);
+      }
+    }
+    throw new YokAtlasAPIError(`Y\xD6K Atlas API iste\u011Fi ba\u015Far\u0131s\u0131z: ${path}`, { cause: lastError });
+  }
+  static async handleResponse(response, path) {
+    if (!response.ok) {
+      const body = await response.text().catch(() => void 0);
+      const message = `Y\xD6K Atlas API hatas\u0131 ${response.status}: ${path}`;
+      if (response.status === 404) throw new YokAtlasNotFoundError(message, { status: response.status, body });
+      if (response.status === 418 || response.status === 429) throw new YokAtlasRateLimitError(message, { status: response.status, body });
+      throw new YokAtlasAPIError(message, { status: response.status, body });
+    }
+    try {
+      return await response.json();
+    } catch (error) {
+      throw new YokAtlasAPIError(`Y\xD6K Atlas API yan\u0131t\u0131 JSON olarak ayr\u0131\u015Ft\u0131r\u0131lamad\u0131: ${path}`, { status: response.status, cause: error });
+    }
+  }
+};
+
+// src/constants.ts
+var BIRIM_TURU = {
+  LISANS: 46,
+  ONLISANS: 47
+};
+var BURS_ORANI = {
+  /** Ücretsiz / tam burslu. */
+  UCRETSIZ: 0
+};
+var PUAN_TURU_ETIKETLERI = {
+  SAY: "Say\u0131sal",
+  "S\xD6Z": "S\xF6zel",
+  EA: "E\u015Fit A\u011F\u0131rl\u0131k",
+  "D\u0130L": "Dil",
+  TYT: "TYT (\xD6n Lisans)"
+};
+var BIRIM_TURU_ETIKETLERI = {
+  LISANS: "Lisans",
+  ONLISANS: "\xD6n Lisans"
+};
+var UNIVERSITE_TURU_ETIKETLERI = {
+  DEVLET: "Devlet \xDCniversitesi",
+  VAKIF: "Vak\u0131f \xDCniversitesi",
+  "VAKIF MYO": "Vak\u0131f Meslek Y\xFCksekokulu"
+};
+function getPuanTuruLabel(puanTuru) {
+  if (!puanTuru) return "Bilinmiyor";
+  return PUAN_TURU_ETIKETLERI[puanTuru.toUpperCase()] ?? puanTuru;
+}
+function getBirimTuruLabel(birimTuruAdi) {
+  if (!birimTuruAdi) return "Bilinmiyor";
+  return BIRIM_TURU_ETIKETLERI[birimTuruAdi.toUpperCase()] ?? birimTuruAdi;
+}
+function getUniversiteTuruLabel(universiteTuru) {
+  if (!universiteTuru) return "Bilinmiyor";
+  return UNIVERSITE_TURU_ETIKETLERI[universiteTuru.toUpperCase()] ?? universiteTuru;
+}
+
+// src/index.ts
+var index_default = YokAtlas;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BIRIM_TURU,
+  BIRIM_TURU_ETIKETLERI,
+  BURS_ORANI,
+  PUAN_TURU_ETIKETLERI,
+  UNIVERSITE_TURU_ETIKETLERI,
+  YokAtlas,
+  YokAtlasAPIError,
+  YokAtlasError,
+  YokAtlasLookupError,
+  YokAtlasNotFoundError,
+  YokAtlasRateLimitError,
+  YokAtlasValidationError,
+  getBirimTuruLabel,
+  getPuanTuruLabel,
+  getUniversiteTuruLabel
+});