subopen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wisecolt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# subopen
+
+**opensubtitles.org** için unofficial API — IMDB numarasıyla altyazı arama ve indirme.
+
+subTR paketinin kardeşi: turkcealtyazi.org yerine opensubtitles.org'u hedefler, aynı mimariyi
+(fetchWithRetry + ZIP parse + UTF-8 dönüşümü) kullanır. Film ve dizi ayrımı otomatik yapılır.
+
+Modern, Promise-tabanlı, ES Modules. Node 18+ native `fetch` kullanır.
+
+## Nasıl çalışır?
+
+Sitedeki arama formuna IMDB numarası yazınca site tahmin edilebilir bir GET adresine gider:
+
+```
+https://www.opensubtitles.org/en/search/sublanguageid-{DİL}/imdbid-{IMDB}
+```
+
+Bu paket aynı adresin `/xml` sürümünü çeker — HTML parse yok, yapılandırılmış XML gelir.
+İndirme için `dl.opensubtitles.org` uç noktası kullanılır (token/session gerekmez).
+
+## Kurulum
+
+```bash
+npm install subopen
+```
+
+## Kullanım
+
+```js
+import { search, download } from "subopen";
+
+// 1. IMDB ile ara (film VEYA dizi — otomatik algılanır)
+const result = await search({ imdbId: "tt0111161", lang: "tur" });
+
+if (result.kind === "movie") {
+  // Film (veya dizi bölümü): altyazılar hazır
+  console.log(result.movie.title);        // "The Shawshank Redemption"
+  console.log(result.total);              // 67
+  console.log(result.subtitles[0]);
+  // {
+  //   id: "10749539",
+  //   name: "The Shawshank Redemption (1994) - YIFY",
+  //   language: "Turkish", iso: "tr", format: "srt", cds: 1,
+  //   date: "2024-07-01", rating: 0, downloads: 160,
+  //   hd: true, bad: false, uploader: "SubSceneImport",
+  //   url: "https://www.opensubtitles.org/en/subtitles/10749539/...",
+  //   downloadUrl: "https://dl.opensubtitles.org/en/download/subad/10749539"
+  // }
+
+  // 2. Altyazıyı indir
+  const { srt, fileName } = await download(result.subtitles[0].id);
+  fs.writeFileSync("shawshank.tr.srt", srt, "utf8");
+} else {
+  // Dizi: sonuç bölüm listesidir; her bölümün kendi IMDB numarası vardır.
+  // İstenen bölümün IMDB'siyle search tekrar çağrılır → altyazılar.
+  const ep = result.episodes.find((e) => e.season === 1 && e.episode === 1);
+  const epResult = await search({ imdbId: ep.imdbId, lang: "tur" });
+  const { srt } = await download(epResult.subtitles[0].id);
+}
+```
+
+## API
+
+### `search({ imdbId, lang, offset })` → `Promise<SearchResult>`
+
+opensubtitles.org'da IMDB numarasıyla arar. Sonuç türü `kind` alanıyla ayrılır —
+kullanıcının film mi dizi mi bilmesine gerek yoktur.
+
+| Parametre | Tip | Açıklama |
+|-----------|-----|----------|
+| `imdbId` | `string \| number` | IMDB numarası: `"tt0111161"`, `"0111161"`, `111161` (zorunlu) |
+| `lang` | `string` | Dil kodu: `"tur"` (varsayılan), `"eng"`, `"tur,eng"`, `"all"` |
+| `offset` | `number` | Sayfalama başlangıcı; sayfa başına 40 sonuç (varsayılan `0`) |
+
+**Film sonucu:** `{ kind: "movie", movie, total, offset, subtitles }`
+
+| Alan | Açıklama |
+|------|----------|
+| `movie` | `{ title, year, imdbId, imdbRating }` |
+| `total` | Toplam sonuç sayısı (tüm sayfalar) |
+| `subtitles` | Altyazı dizisi (site sıralamasıyla) |
+
+**Dizi sonucu:** `{ kind: "series", movie, episodes }`
+
+| Alan | Açıklama |
+|------|----------|
+| `movie` | `{ title, year: null, imdbId, imdbRating: null }` — başlık bölüm adlarından çıkarılır |
+| `episodes` | `{ season, episode, name, imdbId, count }[]` — `imdbId` ile `search()` tekrar çağrılır |
+
+> Dizi bölümlerinin altyazıları, bölümün kendi IMDB numarasıyla sorgulanınca
+> `kind: "movie"` şeklinde döner (bölüm sayfası tek yapıştır). Bu iki adımlı akış
+> paketin tasarımının parçasıdır — sitenin kendisi de böyle çalışır.
+
+### `download(subtitleId)` → `Promise<{ srt, fileName }>`
+
+Altyazıyı indirir ve UTF-8 SRT olarak döner.
+
+| Parametre | Tip | Açıklama |
+|-----------|-----|----------|
+| `subtitleId` | `string \| number` | `search()` sonucundaki `id` alanı (örn `"10749539"`) |
+
+**Dönüş:** `{ srt: string (UTF-8), fileName: string }` — ZIP'ten SRT çıkarılır,
+CP1254 (Türkçe Windows-1254) encoding UTF-8'e çevrilir.
+
+## Özellikler
+
+- ✅ IMDB ile arama (`tt` öneki, baştaki sıfırlar, sayı girdisi — hepsi kabul)
+- ✅ Film/dizi otomatik ayrımı (`kind`) — dizi ise bölüm listesi + bölüm IMDB'leri
+- ✅ Çoklu dil desteği (`"tur,eng"` gibi)
+- ✅ Sayfalama (`offset`; sayfa başına 40)
+- ✅ Altyazı indirme (dl.opensubtitles.org → ZIP → UTF-8 SRT)
+- ✅ CP1254 → UTF-8 encoding dönüşümü
+- ✅ Timeout + retry (ağ halletarına dayanıklı)
+- ✅ Zero-config: API key / login gerekmez
+- ✅ HTML scrape yok — resmî XML uç noktası (site tasarım değişikliğine dayanıklı)
+
+## Test
+
+```bash
+npm test
+```
+
+### Doğrulanmış test sonuçleri (28/28 geçti)
+
+| Senaryo | Sonuç |
+|---------|-------|
+| Film: The Shawshank Redemption (tt0111161, tur) | 67 sonuç, alanlar doğru |
+| Dizi: Breaking Bad (tt0903747, tur) | `kind: "series"`, 62 bölüm, bölüm IMDB'leri |
+| Bölüm: S1E1 Pilot (959621, tur) | 9 altyazı |
+| Çoklu dil: tur,eng (111161) | 215 sonuç, iki dil de var |
+| Olmayan IMDB (tt999999999) | Boş sonuç, crash yok |
+| Geçersiz girdi ("abc") | Anlaşılır hata |
+| Download: 10749539 | 101K UTF-8 SRT, Türkçe karakterler düzgün |
+
+## subTR ile farklar
+
+| | subTR | subopen |
+|---|-------|---------|
+| Kaynak | turkcealtyazi.org | opensubtitles.org |
+| Arama | İsim/yıl/IMDB (HTML scrape) | Sadece IMDB (XML uç noktası) |
+| Dil | Sadece Türkçe | Tüm diller (`lang` parametresi) |
+| Dizi davranışı | Sezon/bölüm altyazı alanlarında | Bölüm listesi → bölüm IMDB'siyle 2. arama |
+| FPS bilgisi | ✅ | ❌ (OpenSubtitles XML'de yok) |
+
+## Süreç (adım adım)
+
+```
+search({ imdbId, lang, offset })
+  │
+  ├─ 1. IMDB normalize ("tt0111161" → "111161")
+  ├─ 2. GET /en/search/sublanguageid-{lang}/imdbid-{imdb}[/offset-N]/xml
+  ├─ 3. XML'de <search><results><subtitle> satırlarını parse et:
+  │     • IDSubtitle'lı satır → altyazı kaydı
+  │     • EpisodeName'li satır → bölüm kaydı (bölüm IMDB'si linkte)
+  └─ 4. Bölüm satırı varsa → { kind: "series", episodes }
+        yoksa             → { kind: "movie", subtitles }
+
+download(subtitleId)
+  │
+  ├─ 1. GET https://dl.opensubtitles.org/en/download/subad/{id} → ZIP
+  ├─ 2. ZIP'ten SRT çıkar (tüm entry'ler taranır, .nfo atlanır)
+  └─ 3. UTF-8 dene, bozuksa CP1254 → UTF-8 çevir
+```
+
+## Notlar
+
+- Site düz bot isteklerine 401 döndürdüğü için gerçekçi bir Chrome User-Agent gönderilir.
+- `subtitleserve` indirme uç noktası bot koruması (Anubis) arkasında olduğundan
+  `dl.opensubtitles.org` kullanılır — anonim indirme çalışır.
+- OpenSubtitles'ta anonim kullanıcılara günlük indirme limiti uygulanabilir.
+
+## Uyarı: unofficial ve best-effort
+
+Bu paket opensubtitles.org'un **resmî API'sini kullanmaz**; sitenin halka açık
+XML arama sayfasını ve `dl.opensubtitles.org` indirme uç noktasını okur. Site
+bu uç noktalardan birini değiştirirse paket bozulabilir — böyle bir durumda
+issue açın. Sürümün 0.x'te tutulmasının sebebi tam olarak bu dış bağımlılıktır.
+
+## Lisans
+
+MIT

package/index.d.ts

@@ -0,0 +1,71 @@
+// subopen — tip tanımları
+// Kaynak: lib/search.js ve lib/download.js içindeki dokümante edilmiş sözleşme.
+
+/** opensubtitles.org arama seçenekleri. */
+export interface SearchOptions {
+  /** IMDB numarası: "tt0111161", "0111161" veya 111161 (zorunlu). */
+  imdbId: string | number;
+  /** Dil kodu: "tur" (varsayılan), "eng", "tur,eng", "all". */
+  lang?: string;
+  /** Sayfalama başlangıcı; sayfa başına 40 sonuç (varsayılan 0). */
+  offset?: number;
+}
+
+/** Film/dizi künye bilgisi. Dizi aramalarında year ve imdbRating null'dur. */
+export interface MovieInfo {
+  title: string | null;
+  year: string | null;
+  imdbId: string;
+  imdbRating: string | null;
+}
+
+/** Tek bir altyazı kaydı (film veya dizi bölümü sayfası). */
+export interface SubtitleItem {
+  id: string;
+  name: string;
+  language: string;
+  iso: string;
+  format: string;
+  cds: number | null;
+  date: string;
+  rating: number;
+  downloads: number;
+  hd: boolean;
+  bad: boolean;
+  uploader: string;
+  url: string | null;
+  downloadUrl: string;
+}
+
+/** Dizi aramasında tek bir bölüm; imdbId ile search() tekrar çağrılır. */
+export interface EpisodeItem {
+  season: number | null;
+  episode: number | null;
+  name: string;
+  fullName: string;
+  imdbId: string;
+  count: number | null;
+}
+
+export interface MovieResult {
+  kind: "movie";
+  movie: MovieInfo;
+  /** Tüm sayfaların toplam sonucu. */
+  total: number;
+  offset: number;
+  subtitles: SubtitleItem[];
+}
+
+export interface SeriesResult {
+  kind: "series";
+  movie: MovieInfo;
+  episodes: EpisodeItem[];
+}
+
+export type SearchResult = MovieResult | SeriesResult;
+
+export declare function search(options: SearchOptions): Promise<SearchResult>;
+
+export declare function download(
+  subtitleId: string | number
+): Promise<{ srt: string; fileName: string }>;

package/index.js

@@ -0,0 +1,20 @@
+// subopen — opensubtitles.org unofficial API
+//
+// Export edilen fonksiyonlar:
+//   search({ imdbId, lang, offset }) → Promise<SearchResult>
+//     SearchResult: { kind: "movie", movie, total, subtitles }
+//                | { kind: "series", movie, episodes }
+//   download(subtitleId) → Promise<{ srt, fileName }>
+//
+// Örnek kullanım:
+//   import { search, download } from "subopen";
+//   const result = await search({ imdbId: "tt0111161", lang: "tur" });
+//   if (result.kind === "movie") {
+//     const { srt } = await download(result.subtitles[0].id);
+//   } else {
+//     // Dizi: bölüm listesi gelir, bölümün IMDB'siyle tekrar aranır
+//     const ep = await search({ imdbId: result.episodes[0].imdbId, lang: "tur" });
+//   }
+
+export { search } from "./lib/search.js";
+export { download } from "./lib/download.js";

package/lib/download.js

@@ -0,0 +1,149 @@
+// opensubtitles.org altyazı indirme.
+//
+// Akış:
+//   1. GET https://dl.opensubtitles.org/en/download/subad/{id} → ZIP dosyası
+//      (subtitleserve uç noktası bot koruması arkasında olduğu için
+//       dl.opensubtitles.org kullanılır; token/session gerekmez)
+//   2. ZIP'ten SRT çıkar
+//   3. Encoding'i UTF-8'e çevir (OpenSubtitles SRT'leri çoğunlukla CP1254'tür)
+//
+// ZIP parse mantığı subTR paketinden (lib/download.js) uyarlanmıştır;
+// giriş sırası ne olursa olsun tüm entry'ler taranır (.srt + .nfo karışık
+// sıralı ZIP'lerde bile).
+
+import zlib from "zlib";
+import { fetchWithRetry, DOWNLOAD_HOST } from "./http.js";
+
+/**
+ * Bir altyazıyı indir.
+ * @param {string|number} subtitleId — IDSubtitle değeri (örn "10749539"; search() sonucunun id alanı)
+ * @returns {Promise<{ srt: string, fileName: string }>} UTF-8 SRT içeriği
+ */
+export async function download(subtitleId) {
+  const id = String(subtitleId ?? "").trim();
+  if (!/^\d+$/.test(id)) {
+    throw new Error(`Geçersiz altyazı ID: ${JSON.stringify(subtitleId)} (örn. "10749539")`);
+  }
+
+  const resp = await fetchWithRetry(`${DOWNLOAD_HOST}/en/download/subad/${id}`);
+  if (!resp.ok) {
+    throw new Error(`İndirme başarısız (HTTP ${resp.status})`);
+  }
+
+  // Bot koruması / hata sayfası ZIP değil HTML döndürür
+  const contentType = resp.headers.get("content-type") || "";
+  if (contentType.includes("text/html")) {
+    throw new Error("İndirme engellendi (HTML döndü). ID doğru mu kontrol edin.");
+  }
+
+  const zipBuffer = Buffer.from(await resp.arrayBuffer());
+  const extracted = extractSrtFromZip(zipBuffer);
+  if (!extracted) {
+    throw new Error("ZIP içinde SRT dosyası bulunamadı");
+  }
+  return extracted;
+}
+
+/**
+ * ZIP buffer'ından SRT içeriğini çıkarır.
+ * OpenSubtitles ZIP'leri genelde .srt + .nfo içerir; .srt hangi sırada
+ * olursa olsun bulunana kadar tüm entry'ler taranır.
+ * @param {Buffer} zipBuffer
+ * @returns {{ srt: string, fileName: string } | null}
+ */
+function extractSrtFromZip(zipBuffer) {
+  let offset = 0;
+  while (offset < zipBuffer.length - 4) {
+    // Local file header signature: PK\x03\x04
+    if (zipBuffer[offset] === 0x50 && zipBuffer[offset + 1] === 0x4b &&
+        zipBuffer[offset + 2] === 0x03 && zipBuffer[offset + 3] === 0x04) {
+      const entry = parseZipEntry(zipBuffer, offset);
+      if (entry.srt) return entry;
+      offset = entry.nextOffset;
+    } else {
+      offset++;
+    }
+  }
+  return null;
+}
+
+/**
+ * Tek bir ZIP local file header'ını parse eder.
+ * Sadece deflate (method 8) ve store (method 0) destekler.
+ */
+function parseZipEntry(buf, headerOffset) {
+  // Local file header yapısı (ZIP spec):
+  //   0  signature (4)          18  compressed size (4)
+  //   4  version needed (2)     22  uncompressed size (4)
+  //   6  flags (2)              26  filename length (2)
+  //   8  compression method (2) 28  extra field length (2)
+  //  10  mod time (2)           30  filename
+  //  12  mod date (2)           ... extra field
+  //  14  CRC-32 (4)             ... file data
+
+  const compressionMethod = buf.readUInt16LE(headerOffset + 8);
+  const compressedSize = buf.readUInt32LE(headerOffset + 18);
+  const filenameLen = buf.readUInt16LE(headerOffset + 26);
+  const extraLen = buf.readUInt16LE(headerOffset + 28);
+
+  const filenameStart = headerOffset + 30;
+  const fileName = buf.slice(filenameStart, filenameStart + filenameLen).toString("latin1");
+
+  const dataStart = filenameStart + filenameLen + extraLen;
+  const compressedData = buf.slice(dataStart, dataStart + compressedSize);
+
+  // Sadece .srt dosyalarını işle; diğer entry'leri (.nfo vb.) atla
+  if (!fileName.toLowerCase().endsWith(".srt")) {
+    return { nextOffset: dataStart + compressedSize, srt: null, fileName: null };
+  }
+
+  let fileBuffer;
+  if (compressionMethod === 0) {
+    fileBuffer = compressedData; // Store (sıkıştırmasız)
+  } else if (compressionMethod === 8) {
+    fileBuffer = inflateRaw(compressedData); // Deflate
+  } else {
+    return { nextOffset: dataStart + compressedSize, srt: null, fileName: null };
+  }
+
+  if (!fileBuffer) {
+    return { nextOffset: dataStart + compressedSize, srt: null, fileName: null };
+  }
+
+  const srt = decodeSubtitle(fileBuffer);
+  return { srt, fileName, nextOffset: dataStart + compressedSize };
+}
+
+/** Raw deflate decompression (zlib). */
+function inflateRaw(data) {
+  try {
+    return zlib.inflateRawSync(data);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Subtitle buffer'ını UTF-8 string'e çevirir.
+ * Önce UTF-8 dener, bozuk karakter varsa Windows-1254 (Türkçe CP1254) kullanır.
+ */
+function decodeSubtitle(buf) {
+  // UTF-8 BOM varsa direkt UTF-8
+  if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+    return buf.slice(3).toString("utf8");
+  }
+  // UTF-8 decode kontrolü — U+FFFD varsa Windows-1254 dene
+  const text = buf.toString("utf8");
+  if (!text.includes("\uFFFD")) return text;
+
+  // Windows-1254 / ISO-8859-9 decode
+  return buf.toString("binary").replace(/[\u00C0-\u00FF]/g, (ch) => {
+    const code = ch.charCodeAt(0);
+    const map = {
+      0xD0: "\u011E", 0xDD: "\u0130", 0xDE: "\u015E", 0xFE: "\u015F",
+      0xFD: "\u0131", 0xF0: "\u011F", 0xC7: "\u00C7", 0xE7: "\u00E7",
+      0xD6: "\u00D6", 0xF6: "\u00F6", 0xDC: "\u00DC", 0xFC: "\u00FC",
+    };
+    return map[code] || ch;
+  });
+}

package/lib/http.js

@@ -0,0 +1,78 @@
+// HTTP yardımcı fonksiyonları — opensubtitles.org ile güvenli iletişim.
+//
+// Tasarım: subTR paketinin (lib/http.js) fetchWithRetry pattern'ini taklip
+// eder. Node 18+ native fetch kullanır. Timeout (AbortController) + retry +
+// User-Agent header.
+//
+// Önemli: OpenSubtitles, tarayıcı imzası olmayan isteklere 401 döndürür;
+// gerçekçi bir Chrome User-Agent'ı zorunludur. XML arama ve indirme
+// uç noktaları farklı host'lardadır:
+//   Arama   : https://www.opensubtitles.org/en/search/.../xml
+//   İndirme : https://dl.opensubtitles.org/en/download/subad/{id}
+
+const BASE_URL = "https://www.opensubtitles.org";
+const DOWNLOAD_HOST = "https://dl.opensubtitles.org";
+const USER_AGENT =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36";
+
+const RETRYABLE_ERRORS = new Set([
+  "AbortError",
+  "TypeError",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ENOTFOUND",
+]);
+
+/**
+ * Verilen URL'i timeout ve retry ile fetch eder.
+ * @param {string} url — Tam URL (https://...)
+ * @param {object} [options] — fetch options (method, headers, body, ...)
+ * @param {number} [timeoutMs=20000] — İstek timeout (ms)
+ * @param {number} [retries=3] — Ağ hatasında yeniden deneme sayısı
+ * @returns {Promise<Response>}
+ */
+export async function fetchWithRetry(url, options = {}, timeoutMs = 20000, retries = 3) {
+  const headers = {
+    "User-Agent": USER_AGENT,
+    "Accept-Language": "en-US,en;q=0.9",
+    ...(options.headers || {}),
+  };
+
+  let lastErr = null;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const resp = await fetch(url, { ...options, headers, signal: controller.signal, redirect: "follow" });
+      clearTimeout(timer);
+      return resp;
+    } catch (err) {
+      clearTimeout(timer);
+      lastErr = err;
+      const errType = err?.name || err?.cause?.code || "Unknown";
+      const isNetwork =
+        RETRYABLE_ERRORS.has(errType) || (err?.message || "").includes("fetch failed");
+      if (!isNetwork || attempt === retries) throw err;
+      const delay = 1000 * (attempt + 1);
+      console.warn(`⚠️ subopen ağ hatası (${errType}), ${delay}ms sonra yeniden denenecek (${attempt + 1}/${retries})`);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * XML arama yanıtı çeker (text olarak).
+ * @param {string} path — "/en/search/..." gibi path
+ * @returns {Promise<string>} XML içeriği
+ */
+export async function fetchXml(path) {
+  const resp = await fetchWithRetry(BASE_URL + path);
+  if (!resp.ok) {
+    throw new Error(`opensubtitles.org isteği başarısız (HTTP ${resp.status}): ${path}`);
+  }
+  return await resp.text();
+}
+
+export { BASE_URL, DOWNLOAD_HOST, USER_AGENT };

package/lib/search.js

@@ -0,0 +1,180 @@
+// opensubtitles.org arama — IMDB numarasıyla XML uç noktası üzerinden.
+//
+// Akış:
+//   1. search({ imdbId, lang, offset }) → /en/search/sublanguageid-{lang}/imdbid-{imdb}/xml
+//      (Form doldurmaya gerek yok; sonuç sayfasının URL'si tahmin edilebilir.
+//       Aynı adresin /xml sürümü yapılandırılmış veri döndürür — HTML parse yok.)
+//   2. <search> bölümündeki <subtitle> satırlarını parse et:
+//      • IDSubtitle içeren satır → altyazı kaydı (film VEYA dizi bölümü sayfası)
+//      • EpisodeName içeren satır → dizi aramasında bölüm listesi satırı;
+//        her bölümün kendi IMDB numarası EpisodeName bağlantısındadır
+//        (imdbid-959621 gibi) → o numarayla tekrar search() yapılır
+//   3. Film mi dizi mi ayrımı bununla otomatik çözülür:
+//      kind: "movie" → subtitles hazır
+//      kind: "series" → episodes listesi; episodes[i].imdbId ile alt seviyeye in
+
+import { XMLParser } from "fast-xml-parser";
+import { fetchXml, BASE_URL, DOWNLOAD_HOST } from "./http.js";
+
+const parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+});
+
+/** Sayfa başına sonuç sayısı (site kuralı). */
+export const PAGE_SIZE = 40;
+
+/**
+ * opensubtitles.org'da IMDB numarasıyla altyazı ara.
+ *
+ * @param {object} params
+ * @param {string|number} params.imdbId — IMDB numarası: "tt0111161", "0111161", 111161...
+ * @param {string} [params.lang="tur"] — Dil kodu: "tur", "eng", "tur,eng", "all"
+ * @param {number} [params.offset=0] — Sayfalama başlangıcı (sayfa başına 40)
+ * @returns {Promise<SearchResult>}
+ *   Film ise : { kind: "movie", movie, total, offset, subtitles }
+ *   Dizi ise : { kind: "series", movie, episodes }
+ */
+export async function search({ imdbId, lang = "tur", offset = 0 } = {}) {
+  const imdb = normalizeImdbId(imdbId);
+
+  const path =
+    `/en/search/sublanguageid-${lang}/imdbid-${imdb}` +
+    (offset > 0 ? `/offset-${offset}` : "") +
+    "/xml";
+  const xml = await fetchXml(path);
+  return parseSearchXml(xml, imdb, offset);
+}
+
+/**
+ * "tt0111161" | "0111161" | 111161 → "111161". Geçersiz girdide hata fırlatır.
+ * @param {string|number} value
+ * @returns {string}
+ */
+export function normalizeImdbId(value) {
+  const raw = String(value ?? "").trim().toLowerCase();
+  const digits = raw.replace(/^tt/, "");
+  if (!/^\d+$/.test(digits)) {
+    throw new Error(`Geçersiz IMDB numarası: ${JSON.stringify(value)} (örn. "tt0111161" veya "0111161")`);
+  }
+  return digits.replace(/^0+(?=\d)/, "");
+}
+
+/**
+ * XML arama yanıtını parse eder; film/dizi ayrımını yapar.
+ * @param {string} xml
+ * @param {string} imdb
+ * @param {number} offset
+ * @returns {SearchResult}
+ */
+function parseSearchXml(xml, imdb, offset) {
+  const doc = parser.parse(xml);
+  const searchEl = doc?.opensubtitles?.search;
+  if (!searchEl) {
+    return { kind: "movie", movie: { title: null, year: null, imdbId: imdb }, total: 0, offset, subtitles: [] };
+  }
+
+  const resultsEl = searchEl.results;
+  const rows = arrayify(resultsEl?.subtitle);
+
+  const subtitles = [];
+  const episodes = [];
+
+  for (const row of rows) {
+    const idEl = row.IDSubtitle;
+    const id = textOf(idEl);
+
+    if (id) {
+      // Altyazı satırı (film sayfası veya dizi bölümü sayfası)
+      subtitles.push({
+        id,
+        name: textOf(row.MovieReleaseName) || textOf(row.MovieName) || "",
+        language: textOf(row.LanguageName) || "",
+        iso: textOf(row.ISO639) || "",
+        format: textOf(row.SubFormat) || "",
+        cds: numOr(textOf(row.SubSumCD), null),
+        date: textOf(row.SubAddDate) || "",
+        rating: numOr(textOf(row.SubRating), 0),
+        downloads: numOr(textOf(row.SubDownloadsCnt), 0),
+        hd: textOf(row.SubHD) === "1",
+        bad: textOf(row.SubBad) === "1",
+        uploader: textOf(row.UserNickName) || "",
+        url: idEl?.["@_Link"] ? BASE_URL + idEl["@_Link"] : null,
+        downloadUrl:
+          idEl?.["@_LinkDownload"] || `${DOWNLOAD_HOST}/en/download/subad/${id}`,
+      });
+      continue;
+    }
+
+    // Dizi araması: satır bir bölüm. Reklam/boş satırları EpisodeName olmayanı
+    // atarak eler; bölümün kendi IMDB numarası EpisodeName bağlantısındadır.
+    const epNameEl = row.EpisodeName;
+    if (epNameEl) {
+      const link = epNameEl?.["@_Link"] || "";
+      const m = String(link).match(/imdbid-(\d+)/);
+      if (m) {
+        episodes.push({
+          season: numOr(textOf(row.SeriesSeason), null),
+          episode: numOr(textOf(row.SeriesEpisode), null),
+          name: textOf(epNameEl) || "",
+          fullName: textOf(row.MovieName) || "",
+          imdbId: m[1],
+          count: numOr(textOf(row.SeriesSubtitles), null),
+        });
+      }
+    }
+  }
+
+  // Sıralama site sırası korunur (ilgililik/varsayılan sıralama).
+  const total = numOr(resultsEl?.["@_itemsfound"], subtitles.length + episodes.length);
+
+  if (episodes.length > 0) {
+    return {
+      kind: "series",
+      movie: buildMovieInfo(searchEl.Movie, imdb, episodes),
+      episodes,
+    };
+  }
+  return {
+    kind: "movie",
+    movie: buildMovieInfo(searchEl.Movie, imdb, []),
+    total,
+    offset,
+    subtitles,
+  };
+}
+
+/**
+ * <Movie> öğesinden film bilgisi üretir. Dizi aramalarında <Movie> bulunmaz;
+ * başlık '"Breaking Bad" Pilot' biçimindeki bölüm tam adından çıkarılır.
+ */
+function buildMovieInfo(movieEl, imdb, episodes) {
+  let title = textOf(movieEl?.MovieName) || null;
+  const year = textOf(movieEl?.MovieYear) || null;
+  const imdbRating = textOf(movieEl?.MovieImdbRating) || null;
+
+  if (!title && episodes.length > 0) {
+    const m = (episodes[0].fullName || "").match(/^"([^"]+)"/);
+    if (m) title = m[1];
+  }
+  return { title, year, imdbId: imdb, imdbRating };
+}
+
+/** fast-xml-parser düğümünden metin çıkarır ("10749539" | 10749539 | {#text} | undefined). */
+function textOf(node) {
+  if (node == null) return "";
+  if (typeof node === "object") return String(node["#text"] ?? "");
+  return String(node);
+}
+
+/** Tek düğümü diziye sarar (fast-xml-parser tek kayıtta object döner). */
+function arrayify(node) {
+  if (node == null) return [];
+  return Array.isArray(node) ? node : [node];
+}
+
+/** Sayıya çevirir; mümkün değilse fallback döner. */
+function numOr(value, fallback) {
+  const n = Number(String(value ?? "").trim());
+  return Number.isFinite(n) ? n : fallback;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "subopen",
+  "version": "0.1.0",
+  "description": "Unofficial API for opensubtitles.org — IMDB ile altyazı arama ve indirme (film + dizi)",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "lib/"
+  ],
+  "scripts": {
+    "test": "node test/test.js"
+  },
+  "keywords": [
+    "subtitle",
+    "altyazi",
+    "opensubtitles",
+    "imdb",
+    "turkish",
+    "api",
+    "scraper"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/szbk/subOpen.git"
+  },
+  "author": "wisecolt",
+  "license": "MIT",
+  "dependencies": {
+    "fast-xml-parser": "^4.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "types": "index.d.ts"
+}