yokatlas-api-wrapper 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,450 @@
+/** Puan türleri (sınav kategorisi). */
+type PuanTuru = "SAY" | "SÖZ" | "EA" | "DİL" | "TYT";
+/** Üniversite türü. */
+type UniversiteTuru = "DEVLET" | "VAKIF" | "VAKIF MYO";
+/** Birim (program) türü — LİSANS ya da ÖNLİSANS. API "ÖNLISANS" gönderir, bu kütüphane "ONLISANS" olarak normalize eder. */
+type BirimTuru = "LISANS" | "ONLISANS";
+interface University {
+    universiteId: number;
+    universiteAdi: string;
+}
+interface ProgramGroup {
+    birimGrupId: number;
+    birimGrupAdi: string;
+    puanTuru: string;
+}
+interface City {
+    ilKodu: number;
+    ilAdi: string;
+}
+/** Tek bir yıla ait kontenjan/kadro/puan/sıra/KPSS istatistikleri. */
+interface YearlyStats {
+    year: number;
+    kontenjan: number | null;
+    /** Genel kontenjandan yerleşen (gkY). */
+    yerlesen: number | null;
+    kontenjanObs: number | null;
+    kontenjanY34: number | null;
+    prof: number | null;
+    doc: number | null;
+    dou: number | null;
+    ogrGor: number | null;
+    arGor: number | null;
+    kpss1: number | null;
+    kpss2: number | null;
+    minPuan: number | null;
+    basariSirasi: number | null;
+}
+/** `/api/tercih-kilavuz/search` endpoint'inden dönen tek bir program satırı. */
+interface Program {
+    osymKilavuzId: number | null;
+    sinav: string | null;
+    yil: number;
+    donem: string | null;
+    tabloTuru: string | null;
+    birimId: number | null;
+    birimHiyerarsi: string | null;
+    kilavuzKodu: number;
+    universiteId: number;
+    universiteAdi: string;
+    uniIlKodu: number | null;
+    uniIlAdi: string | null;
+    uniIlceKodu: number | null;
+    uniIlceAdi: string | null;
+    fymkId: number | null;
+    fymkAdi: string | null;
+    fymkIlKodu: number | null;
+    fymkIlAdi: string | null;
+    fymkIlceKodu: number | null;
+    fymkIlceAdi: string | null;
+    birimAdi: string;
+    birimGrupId: number | null;
+    birimGrupAdi: string | null;
+    birimTuruId: number | null;
+    birimTuruAdi: BirimTuru;
+    ogrenimTuruId: number | null;
+    ogrenimTuruAdi: string | null;
+    ogrenimSuresi: number | null;
+    puanTuru: string;
+    ogrenimDiliId: number | null;
+    ogrenimDiliAdi: string | null;
+    bursOraniId: number | null;
+    bursOraniAdi: string | null;
+    ilKodu: number | null;
+    ilAdi: string | null;
+    ilceKodu: number | null;
+    ilceAdi: string | null;
+    universiteTuru: UniversiteTuru;
+    /** En güncel yılın istatistikleri. */
+    current: YearlyStats;
+    /** Önceki 3 yıl (yeni → eski). */
+    history: YearlyStats[];
+}
+/**
+ * Net Sihirbazı sonucu — bir program/üniversite/yıl için son yerleşen
+ * kişinin TYT/AYT/YDT net sayıları (`/api/netler/search`).
+ *
+ * Hangi `*Net` alanlarının dolu geleceği `puanTuru`'ye bağlıdır: TYT alanları
+ * her zaman gelir; SAY `aytMat/Fiz/Kim/BioNet` ekler; SÖZ `aytTde/Trh1/Cog1/
+ * Trh2/Cog2/Fel/DinNet` ekler; EA ikisinin bir alt kümesini ekler; DİL
+ * `ydtYdilNet` ekler.
+ */
+interface Net {
+    yil: number;
+    kilavuzKodu: number;
+    puanTuru: string;
+    katsayi: number | null;
+    tabanPuan: number | null;
+    obp: number | null;
+    tytTrkNet: number | null;
+    tytSosNet: number | null;
+    tytMatNet: number | null;
+    tytFenNet: number | null;
+    aytMatNet: number | null;
+    aytFizNet: number | null;
+    aytKimNet: number | null;
+    aytBioNet: number | null;
+    aytTdeNet: number | null;
+    aytTrh1Net: number | null;
+    aytCog1Net: number | null;
+    aytTrh2Net: number | null;
+    aytCog2Net: number | null;
+    aytFelNet: number | null;
+    aytDinNet: number | null;
+    ydtYdilNet: number | null;
+    universiteId: number;
+    universiteAdi: string;
+    birimGrupId: number | null;
+    birimGrupAdi: string | null;
+    birimId: number | null;
+    birimAdi: string;
+    birimTuruId: number | null;
+    birimTuruAdi: BirimTuru;
+    universiteTuru: UniversiteTuru;
+}
+/** Spring-tarzı sayfalanmış sonuç zarfı. */
+interface SearchPage<T> {
+    content: T[];
+    totalElements: number;
+    totalPages: number;
+    size: number;
+    number: number;
+    first: boolean;
+    last: boolean;
+    numberOfElements: number;
+    empty: boolean;
+    yil?: number | null;
+    source?: string | null;
+}
+/**
+ * `YokAtlas.search()` tarafından kabul edilen filtreler.
+ *
+ * *Akıllı* (string) alanlar (`universite`, `program`, `il`) `smartSearch`
+ * açıkken (varsayılan) istek anında ID karşılıklarına çözülür. ID
+ * alanlarıyla (`universiteId`, `birimGrupId`, `ilKodu`) aynı anda verilemez.
+ */
+interface SearchFilters {
+    puanTuru?: PuanTuru | null;
+    universiteId?: number[] | null;
+    birimGrupId?: number[] | null;
+    ilKodu?: number[] | null;
+    /** 46 = LİSANS, 47 = ÖNLİSANS. Bkz. {@link BIRIM_TURU}. */
+    birimTuruId?: number | null;
+    universiteTuru?: "DEVLET" | "VAKIF" | null;
+    /** 0 = Ücretsiz/Burslu. */
+    bursOraniId?: number | null;
+    ogrenimTuruId?: number | null;
+    kilavuzKodu?: number | null;
+    minBasariSirasi?: number | null;
+    maxBasariSirasi?: number | null;
+    /** Akıllı alan — serbest yazım, fuzzy eşleşir (örn. "boğaziçi"). */
+    universite?: string | string[] | null;
+    /** Akıllı alan — serbest yazım, fuzzy eşleşir (örn. "bilgisayar mühendisliği"). */
+    program?: string | string[] | null;
+    /** Akıllı alan — serbest yazım, fuzzy eşleşir (örn. "ankara"). */
+    il?: string | string[] | null;
+}
+/**
+ * `YokAtlas.searchNetler()` tarafından kabul edilen filtreler.
+ *
+ * {@link SearchFilters}'in aksine `universiteId`/`birimGrupId` *tekildir* —
+ * Net Sihirbazı endpoint'i liste kabul etmez.
+ */
+interface NetFilters {
+    puanTuru?: PuanTuru | null;
+    universiteId?: number | null;
+    birimGrupId?: number | null;
+    birimTuruId?: number | null;
+    universiteTuru?: "DEVLET" | "VAKIF" | null;
+    yil?: number | null;
+    katsayi?: number | null;
+    universite?: string | null;
+    program?: string | null;
+}
+interface SearchOptions {
+    page?: number;
+    size?: number;
+    sortBy?: string;
+    direction?: "ASC" | "DESC";
+    /** Akıllı (string) filtreleri otomatik ID'ye çözer. Varsayılan: true. */
+    smartSearch?: boolean;
+    signal?: AbortSignal;
+}
+interface NetSearchOptions {
+    page?: number;
+    size?: number;
+    smartSearch?: boolean;
+    signal?: AbortSignal;
+}
+/** {@link YokAtlas.searchAllPages} için seçenekler. */
+interface SearchAllPagesOptions extends Omit<SearchOptions, "page"> {
+    /** Sayfa başına kaç kayıt çekileceği. Varsayılan: 100. */
+    pageSize?: number;
+    /** En fazla kaç sayfa gezileceği (güvenlik sınırı). Varsayılan: 50. */
+    maxPages?: number;
+}
+/** Kullanıcının başarı sırasına göre bir programa yerleşme olasılığı tahmini. */
+interface AdmissionEstimate {
+    program: Program;
+    /** Kullanıcının kendi başarı sırası. */
+    basariSirasi: number;
+    /** Programın güncel yıl kesme başarı sırası. */
+    cutoffBasariSirasi: number | null;
+    verdict: "kesine yakın" | "olası" | "sınırda" | "zayıf" | "belirsiz";
+    /** Kullanıcı sırası ile kesme sırası arasındaki fark (negatif = kullanıcı daha iyi sırada). */
+    margin: number | null;
+    message: string;
+}
+/** İki program arasındaki karşılaştırma sonucu. */
+interface ProgramComparison {
+    a: Program;
+    b: Program;
+    /** Hangisinin güncel başarı sırası daha iyi (küçük) — o daha rekabetçidir. */
+    moreCompetitive: "a" | "b" | "eşit" | "belirsiz";
+    scoreDiff: number | null;
+    quotaDiff: number | null;
+}
+/** Bir programın yıllar içindeki başarı sırası eğilimi. */
+interface ProgramTrend {
+    program: Program;
+    direction: "yükseliyor" | "düşüyor" | "sabit" | "belirsiz";
+    /** Eskiden yeniye başarı sıraları (null'lar atlanır). */
+    series: {
+        year: number;
+        basariSirasi: number | null;
+    }[];
+    message: string;
+}
+interface LookupCacheStatus {
+    cached: boolean;
+    fetchedAt: number | null;
+    ageMs: number | null;
+    ttlMs: number;
+    universiteSayisi: number;
+    programGrubuSayisi: number;
+    ilSayisi: number;
+}
+interface YokAtlasConfig {
+    baseUrl?: string;
+    /** HTTP istek zaman aşımı (ms). Varsayılan: 30000. */
+    timeoutMs?: number;
+    userAgent?: string;
+    /** Ağ hatalarında (bağlantı kopması vb.) kaç kez yeniden denenir. Varsayılan: 2. */
+    maxRetries?: number;
+    /** Üniversite/program/il lookup önbelleğinin ömrü (ms). Varsayılan: 3600000 (1 saat). 0 = sonsuz. */
+    lookupCacheTtlMs?: number;
+}
+
+/**
+ * YÖK Atlas tercih kılavuzu JSON API'si için statik istemci.
+ *
+ * Tüm metotlar `static`'tir — örnekleme gerekmez, doğrudan `YokAtlas.search(...)`
+ * gibi çağırılır. Üniversite/program/il lookup tabloları süreç içi (in-process)
+ * bir TTL önbellekte tutulur ve akıllı arama (`universite`, `program`, `il`
+ * serbest metin filtreleri) için otomatik olarak kullanılır.
+ */
+declare class YokAtlas {
+    private static baseUrl;
+    private static timeoutMs;
+    private static userAgent;
+    private static maxRetries;
+    private static lookupCacheTtlMs;
+    private static lookupCache;
+    private constructor();
+    /** İstemcinin temel URL'sini, zaman aşımını, User-Agent'ını, retry ve önbellek ayarlarını değiştirir. */
+    static configure(config: YokAtlasConfig): void;
+    /** YÖK Atlas tercih kılavuzunda program arar. */
+    static search(filters?: SearchFilters, options?: SearchOptions): Promise<SearchPage<Program>>;
+    /** Net Sihirbazı'nı sorgular: son yerleşen kişinin TYT/AYT/YDT netleri. */
+    static searchNetler(filters?: NetFilters, options?: NetSearchOptions): Promise<SearchPage<Net>>;
+    /** Tek bir programı ÖSYM kılavuz kodundan getirir; bulunamazsa `null` döner. */
+    static getProgram(kilavuzKodu: number | string, signal?: AbortSignal): Promise<Program | 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 getPrograms(kilavuzKodlari: (number | string)[], options?: {
+        concurrency?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        kilavuzKodu: number | string;
+        status: "fulfilled" | "rejected";
+        program?: Program | null;
+        reason?: unknown;
+    }[]>;
+    /**
+     * `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 searchAllPages(filters?: SearchFilters, options?: SearchAllPagesOptions): Promise<Program[]>;
+    /** Tüm üniversiteleri (ID + ad) döner. */
+    static listUniversities(signal?: AbortSignal): Promise<University[]>;
+    /** Tüm program gruplarını (ID + ad + puan türü) döner. */
+    static listProgramGroups(signal?: AbortSignal): Promise<ProgramGroup[]>;
+    /** Tüm illeri (kod + ad) döner. */
+    static listCities(signal?: AbortSignal): Promise<City[]>;
+    /** Lookup önbelleğini zorla yeniler. */
+    static refreshLookups(signal?: AbortSignal): Promise<void>;
+    /** Lookup önbelleğini boşaltır (bir sonraki çağrıda yeniden çekilir). */
+    static clearCache(): void;
+    /** Lookup önbelleğinin durumunu (dolu mu, ne zaman çekildi, kaç kayıt var) döner. */
+    static getCacheStatus(): LookupCacheStatus;
+    /** Serbest yazılmış bir üniversite adını fuzzy eşleştirerek {@link University} kaydına çözer. */
+    static findUniversity(name: string, signal?: AbortSignal): Promise<University>;
+    /** Serbest yazılmış bir program adını fuzzy eşleştirerek {@link ProgramGroup} kaydına çözer. */
+    static findProgramGroup(name: string, signal?: AbortSignal): Promise<ProgramGroup>;
+    /** Serbest yazılmış bir il adını fuzzy eşleştirerek {@link City} kaydına çözer. */
+    static findCity(name: string, signal?: AbortSignal): Promise<City>;
+    /** Belirli bir üniversitenin (serbest yazım) tüm programlarını arar. */
+    static searchByUniversity(universiteAdi: string, filters?: Omit<SearchFilters, "universite">, options?: SearchOptions): Promise<SearchPage<Program>>;
+    /** Belirli bir program grubunu (serbest yazım) tüm üniversitelerde arar. */
+    static searchByProgram(programAdi: string, filters?: Omit<SearchFilters, "program">, options?: SearchOptions): Promise<SearchPage<Program>>;
+    /** Belirli bir ildeki (serbest yazım) tüm programları arar. */
+    static searchByCity(ilAdi: string, filters?: Omit<SearchFilters, "il">, options?: SearchOptions): Promise<SearchPage<Program>>;
+    /** Sadece lisans (4 yıllık) programlarını arar. */
+    static searchLisans(filters?: Omit<SearchFilters, "birimTuruId">, options?: SearchOptions): Promise<SearchPage<Program>>;
+    /** Sadece ön lisans (2 yıllık) programlarını arar. */
+    static searchOnlisans(filters?: Omit<SearchFilters, "birimTuruId">, options?: SearchOptions): Promise<SearchPage<Program>>;
+    /** Sadece ücretsiz/tam burslu programları arar. */
+    static searchBurslu(filters?: Omit<SearchFilters, "bursOraniId">, options?: SearchOptions): Promise<SearchPage<Program>>;
+    /** Belirli bir başarı sırası aralığındaki programları arar (`minBasariSirasi`/`maxBasariSirasi` kısayolu). */
+    static searchByScoreRange(range: {
+        min?: number;
+        max?: number;
+    }, filters?: Omit<SearchFilters, "minBasariSirasi" | "maxBasariSirasi">, options?: SearchOptions): Promise<SearchPage<Program>>;
+    /**
+     * 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: Program, basariSirasi: number): AdmissionEstimate;
+    /** İ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: Program, b: Program): ProgramComparison;
+    /**
+     * 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: Program): ProgramTrend;
+    /** Bir program dizisini, verilen anahtar fonksiyonuna göre gruplar. */
+    static groupBy<K extends string | number>(programs: Program[], keyFn: (p: Program) => K): Record<K, Program[]>;
+    /** 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: Program[], direction?: "asc" | "desc"): Program[];
+    /** Bir programı tek satırlık okunur bir özet metnine çevirir (log/konsol için). */
+    static formatSummary(program: Program): string;
+    private static ensureLookups;
+    private static fetchLookups;
+    private static resolveSmartFilters;
+    private static resolveNetSmartFilters;
+    private static normalizePuanTuru;
+    private static filtersToPayload;
+    private static netFiltersToPayload;
+    private static toSearchPage;
+    private static normalizeOnlisansSpelling;
+    private static toNumber;
+    private static buildYearlyStats;
+    private static buildProgram;
+    private static buildNet;
+    private static getJson;
+    private static postJson;
+    private static request;
+    private static handleResponse;
+}
+
+/**
+ * Bu kütüphanenin fırlattığı tüm hataların temel sınıfı.
+ */
+declare class YokAtlasError extends Error {
+    constructor(message: string);
+}
+/**
+ * Çağıranın verdiği bir parametre geçersiz olduğunda fırlatılır (örn. boş kılavuz kodu).
+ */
+declare class YokAtlasValidationError extends YokAtlasError {
+    constructor(message: string);
+}
+/**
+ * YÖK Atlas API isteği ağ/HTTP seviyesinde başarısız olduğunda fırlatılır
+ * (bağlantı hatası, HTTP hata kodu, ayrıştırılamayan yanıt vb.).
+ */
+declare class YokAtlasAPIError extends YokAtlasError {
+    readonly status?: number;
+    readonly body?: string;
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        status?: number;
+        body?: string;
+        cause?: unknown;
+    });
+}
+/** İstenen kaynak (örn. kılavuz kodu) bulunamadığında fırlatılır. */
+declare class YokAtlasNotFoundError extends YokAtlasAPIError {
+    constructor(message: string, options?: {
+        status?: number;
+        body?: string;
+    });
+}
+/** API oran sınırlama (rate limit) durum kodu döndürdüğünde fırlatılır. */
+declare class YokAtlasRateLimitError extends YokAtlasAPIError {
+    constructor(message: string, options?: {
+        status?: number;
+        body?: string;
+    });
+}
+/**
+ * Akıllı arama (üniversite/program/il isim çözümü) bir sonuca ulaşamadığında fırlatılır.
+ */
+declare class YokAtlasLookupError extends YokAtlasError {
+    readonly query: string;
+    readonly kind: "üniversite" | "program" | "il";
+    readonly suggestions: string[];
+    constructor(query: string, options: {
+        kind: "üniversite" | "program" | "il";
+        suggestions?: string[];
+    });
+}
+
+/** `birimTuruId` filtre değerleri. */
+declare const BIRIM_TURU: {
+    readonly LISANS: 46;
+    readonly ONLISANS: 47;
+};
+/** `bursOraniId` sık kullanılan değerler. */
+declare const BURS_ORANI: {
+    /** Ücretsiz / tam burslu. */
+    readonly UCRETSIZ: 0;
+};
+/** `puanTuru` kısaltmalarının okunur Türkçe karşılıkları. */
+declare const PUAN_TURU_ETIKETLERI: Record<string, string>;
+/** `birimTuruAdi` değerlerinin okunur Türkçe karşılıkları. */
+declare const BIRIM_TURU_ETIKETLERI: Record<string, string>;
+/** `universiteTuru` değerlerinin okunur Türkçe karşılıkları. */
+declare const UNIVERSITE_TURU_ETIKETLERI: Record<string, string>;
+/** Verilen puan türü kodunu okunur Türkçe etikete çevirir; bilinmiyorsa kodu olduğu gibi döner. */
+declare function getPuanTuruLabel(puanTuru: string | null | undefined): string;
+/** Verilen birim türü kodunu okunur Türkçe etikete çevirir; bilinmiyorsa kodu olduğu gibi döner. */
+declare function getBirimTuruLabel(birimTuruAdi: string | null | undefined): string;
+/** Verilen üniversite türü kodunu okunur Türkçe etikete çevirir; bilinmiyorsa kodu olduğu gibi döner. */
+declare function getUniversiteTuruLabel(universiteTuru: string | null | undefined): string;
+
+export { type AdmissionEstimate, BIRIM_TURU, BIRIM_TURU_ETIKETLERI, BURS_ORANI, type BirimTuru, type City, type LookupCacheStatus, type Net, type NetFilters, type NetSearchOptions, PUAN_TURU_ETIKETLERI, type Program, type ProgramComparison, type ProgramGroup, type ProgramTrend, type PuanTuru, type SearchAllPagesOptions, type SearchFilters, type SearchOptions, type SearchPage, UNIVERSITE_TURU_ETIKETLERI, type UniversiteTuru, type University, type YearlyStats, YokAtlas, YokAtlasAPIError, type YokAtlasConfig, YokAtlasError, YokAtlasLookupError, YokAtlasNotFoundError, YokAtlasRateLimitError, YokAtlasValidationError, YokAtlas as default, getBirimTuruLabel, getPuanTuruLabel, getUniversiteTuruLabel };