wscraper/README.md

<p align="center">
  <img src="logo-v2.png" alt="wscraper logo" width="240" />
</p>

<p align="center">
  <a href="https://gitea.wisecolt-panda.net/wisecolt/Bookmark-Tracker">
    <img src="https://img.shields.io/badge/Gitea-Repository-609926?logo=gitea&logoColor=white" alt="Gitea">
  </a>
  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/Trackers-HappyFappy%20%7C%20PrivateHD-0A7B83" alt="Trackers">
  <img src="https://img.shields.io/badge/Runtime-scrapling%20%2B%20Playwright-1f6feb" alt="Runtime">
</p>

# wscraper

`wscraper`, tracker bookmark / wishlist akışlarını ortak bir Python adapter katmanında toplayan çoklu tracker scraper paketidir. Bugünkü kullanım şekli iki parçalıdır:

- `bin/wscraper/`: Python paketinin kendisi, tracker adapter'ları ve CLI
- `bin/wscraper-service/server.py`: `q-buffer` backend'in HTTP ile konuştuğu host-side servis

`q-buffer` watcher akışı artık `wscraper` CLI'yi doğrudan Docker içinde spawn etmek yerine, host makinede çalışan `wscraper-service` üzerinden kullanır. Bunun ana nedeni `scrapling + Playwright` zincirinin tracker tarafında daha stabil çalışmasının host ortamında olmasıdır.

## Desteklenen Tracker'lar

- `happyfappy` (`hf`)
- `privatehd` (`phd`)

Desteklenen ortak aksiyonlar:

- `get-bookmarks`
- `download-torrent-files`
- `remove-bookmark`

## Mimari

`wscraper` paket yapısı artık tracker-registry tabanlıdır:

- `src/wscraper/registry.py`
  - desteklenen tracker adapter'larını kaydeder
- `src/wscraper/types.py`
  - ortak `BookmarkItem`, `DownloadResult`, `TrackerAdapter` tiplerini tanımlar
- `src/wscraper/sites/happyfappy.py`
  - HappyFappy adapter'ı
- `src/wscraper/sites/privatehd.py`
  - PrivateHD adapter'ı
- `src/wscraper/cli.py`
  - tüm tracker'lar için ortak CLI entrypoint

Bu sayede yeni tracker eklemek için mevcut CLI'yi kopyalamak yerine sadece yeni bir adapter yazmak yeterlidir.

## Kurulum

### macOS / Linux

```bash
cd bin/wscraper
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
scrapling install
```

Alternatif:

- `python3.12` yoksa `python3.11` veya `python3.10` kullan
- `scrapling install`, Playwright/browser bağımlılıklarını kurar

### Windows PowerShell

```powershell
cd bin/wscraper
py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .
scrapling install
```

## CLI Kullanımı

Genel form:

```bash
wscraper <tracker> --action <action> [opsiyonlar]
```

### Bookmark / Wishlist Çekme

```bash
wscraper happyfappy --action get-bookmarks -c cookies.txt -o bookmarks.json
wscraper privatehd --action get-bookmarks -c cookies.txt -o bookmarks.json
```

İsteğe bağlı `wishlist_url` override:

```bash
wscraper privatehd --action get-bookmarks -c cookies.txt --wishlist-url "https://privatehd.to/bookmarks" -o bookmarks.json
```

### Torrent Dosyası İndirme

```bash
wscraper happyfappy --action download-torrent-files \
  -c cookies.txt \
  -u "https://www.happyfappy.net/torrents.php?id=110178" \
  --title "Sample" \
  --image-url "https://example.com/poster.jpg" \
  -o torrent
```

```bash
wscraper privatehd --action download-torrent-files \
  -c cookies.txt \
  -u "https://privatehd.to/torrent/12345" \
  --download-url "https://privatehd.to/download.php?id=12345" \
  --title "Sample" \
  -o torrent
```

### Bookmark Silme

```bash
wscraper happyfappy --action remove-bookmark \
  -c cookies.txt \
  -u "https://www.happyfappy.net/torrents.php?id=110178" \
  --title "Sample"
```

```bash
wscraper privatehd --action remove-bookmark \
  -c cookies.txt \
  -u "https://privatehd.to/torrent/12345" \
  --remove-token "bookmark-delete-token" \
  --title "Sample"
```

### Kısa Alias'lar

```bash
wscraper hf -a gb -c cookies.txt -o bookmarks.json
wscraper phd -a gb -c cookies.txt -o bookmarks.json
wscraper hf -a dtf -c cookies.txt -u "https://www.happyfappy.net/torrents.php?id=110178" -o torrent
wscraper phd -a rb -c cookies.txt -u "https://privatehd.to/torrent/12345" --remove-token "token"
```

## q-buffer ile Entegrasyon

`q-buffer` içinde watcher tarafı artık şu şekilde çalışır:

1. UI'dan watcher tanımlanır
2. `q-buffer` backend cookie'yi şifreli saklar
3. Docker içindeki `server`, host'taki `wscraper-service`e HTTP çağrısı yapar
4. `wscraper-service`, `wscraper` adapter'ı ile bookmarkları çeker
5. yeni bookmark için torrent dosyasını indirir
6. `q-buffer` backend `.torrent` içeriğini alır ve qBittorrent'e yollar
7. başarılı import sonrası bookmark tracker tarafında kaldırılır

Bu yüzden `wscraper` tek başına bir CLI olmanın ötesinde artık `q-buffer watcher` entegrasyonunun backend scraping motorudur.

## wscraper-service API

`bin/wscraper-service/server.py` şu endpoint'leri sunar:

- `GET /health`
- `GET /trackers`
- `POST /bookmarks`
- `POST /download`
- `POST /remove-bookmark`

Örnek `POST /bookmarks` payload:

```json
{
  "tracker": "happyfappy",
  "cookie": "raw-cookie",
  "wishlistUrl": "optional-override"
}
```

Örnek `POST /download` payload:

```json
{
  "tracker": "privatehd",
  "cookie": "raw-cookie",
  "wishlistUrl": "optional-override",
  "item": {
    "pageURL": "https://privatehd.to/torrent/12345",
    "title": "Example",
    "downloadURL": "https://privatehd.to/download.php?id=12345",
    "removeToken": "bookmark-token"
  }
}
```

## q-buffer İlk Kurulumunda wscraper Nasıl Hazırlanır?

Bu adım özellikle önemlidir. `q-buffer` reposunda scraping logic `bin/wscraper/` içindedir. Host servis ise `bin/wscraper-service/server.py` dosyasıdır. Yani:

- `bin/wscraper/` yalnızca `server.py` değildir
- `server.py`, ayrı `wscraper-service` klasöründedir
- asıl tracker kodları `bin/wscraper/src/wscraper/...` altındadır

İlk kurulum için önerilen yol:

1. repo root'ta `.env.example` dosyasını `.env` olarak kopyala
2. `.env` içinde watcher servis ayarlarını gözden geçir:
   - `WSCRAPER_SERVICE_BASE_URL`
   - `WSCRAPER_SERVICE_TOKEN`
   - `WSCRAPER_SERVICE_HOST`
   - `WSCRAPER_SERVICE_PORT`
   - `WSCRAPER_SERVICE_PYTHON_BIN`
3. repo root'ta şu komutu çalıştır:

```bash
./scripts/bootstrap.sh --dev-mode
```

Bu script:

- Docker `web` ve `server` servislerini `up --build` ile kaldırır
- host'ta `.runtime/wscraper-service/.venv` oluşturur
- `scrapling[fetchers]` kurar
- `scrapling install` çalıştırır
- `bin/wscraper-service/server.py` servis sürecini başlatır

Kurulum daha önce tamamsa script aynı işlemleri baştan yapmaz; sadece eksikleri tamamlar.

## Testler

`wscraper` içinde canlı sistemlere karşı çalışan `pytest` tabanlı e2e testleri vardır. Bunlar varsayılan olarak kapalıdır; yalnızca açıkça etkinleştirildiğinde çalışırlar.

Test dosyaları:

- `tests/e2e/test_happyfappy_live.py`
- `tests/e2e/test_privatehd_live.py`
- `tests/e2e/_helpers.py`

### Testleri Etkinleştirme

Tüm live testler için:

```bash
export WSCRAPER_E2E=1
```

Bu değişken yoksa veya `1` değilse, e2e testleri `skip` olur.

### HappyFappy Live Testleri

Mevcut test kapsamı:

- `get-bookmarks`
- `download-torrent-files`

Kullanılan env değişkenleri:

- `WSCRAPER_COOKIE_FILE`
- `WSCRAPER_TEST_TORRENT_URL`

Örnek:

```bash
export WSCRAPER_E2E=1
export WSCRAPER_COOKIE_FILE=/absolute/path/to/happyfappy-cookies.txt
export WSCRAPER_TEST_TORRENT_URL="https://www.happyfappy.net/torrents.php?id=110178"
pytest tests/e2e/test_happyfappy_live.py -m e2e -s
```

### PrivateHD Live Testleri

PrivateHD için eklenen test kapsamı:

- `get-bookmarks`
- `download-torrent-files`
- `remove-bookmark`

Kullanılan env değişkenleri:

- `WSCRAPER_PRIVATEHD_COOKIE_FILE`
- `WSCRAPER_PRIVATEHD_WISHLIST_URL`
- `WSCRAPER_PRIVATEHD_TEST_TORRENT_URL`
- `WSCRAPER_PRIVATEHD_TEST_DOWNLOAD_URL`
- `WSCRAPER_PRIVATEHD_TEST_REMOVE_URL`
- `WSCRAPER_PRIVATEHD_TEST_REMOVE_TOKEN`

Fallback kuralı:

- `WSCRAPER_PRIVATEHD_COOKIE_FILE` yoksa `WSCRAPER_COOKIE_FILE` kullanılır

Örnek:

```bash
export WSCRAPER_E2E=1
export WSCRAPER_PRIVATEHD_COOKIE_FILE=/absolute/path/to/privatehd-cookies.txt
export WSCRAPER_PRIVATEHD_WISHLIST_URL="https://privatehd.to/profile/blackdockers/wishlist"
export WSCRAPER_PRIVATEHD_TEST_TORRENT_URL="https://privatehd.to/torrent/12345-example"
export WSCRAPER_PRIVATEHD_TEST_DOWNLOAD_URL="https://privatehd.to/download/torrent/12345.example.torrent"
pytest tests/e2e/test_privatehd_live.py -m e2e -s
```

### remove-bookmark Testi Hakkında

`PrivateHD remove-bookmark` testi gerçek wishlist kaydını sildiği için özellikle dikkatli kullanılmalıdır.

Bu test:

- yalnızca `WSCRAPER_PRIVATEHD_TEST_REMOVE_URL` ve `WSCRAPER_PRIVATEHD_TEST_REMOVE_TOKEN` verilirse çalışır
- aksi halde güvenli şekilde `skip` olur

Örnek:

```bash
export WSCRAPER_E2E=1
export WSCRAPER_PRIVATEHD_COOKIE_FILE=/absolute/path/to/privatehd-cookies.txt
export WSCRAPER_PRIVATEHD_WISHLIST_URL="https://privatehd.to/profile/blackdockers/wishlist"
export WSCRAPER_PRIVATEHD_TEST_REMOVE_URL="https://privatehd.to/torrent/12345-example"
export WSCRAPER_PRIVATEHD_TEST_REMOVE_TOKEN="467471"
pytest tests/e2e/test_privatehd_live.py -m e2e -s -k remove
```

### Notlar

- Bu testler gerçek tracker hesaplarına ve geçerli cookie'lere ihtiyaç duyar
- `remove-bookmark` testi mutasyon yapar; test datası bilinçli seçilmelidir
- `tests/e2e/_helpers.py`, tüm tracker live testlerinde ortak CLI çalıştırma ve loglama yardımcılarını içerir

## Dizin Yapısı

```text
bin/
├── wscraper/
│   ├── README.md
│   ├── pyproject.toml
│   ├── setup.py
│   └── src/
│       └── wscraper/
│           ├── cli.py
│           ├── registry.py
│           ├── types.py
│           └── sites/
│               ├── happyfappy.py
│               └── privatehd.py
└── wscraper-service/
    └── server.py
```

## Notlar

- Cookie hem raw string hem Netscape cookie file formatında verilebilir
- Tracker metadata alanları (`backgroundImage`, `downloadURL`, `removeToken`, `size`, `seeders`, `leechers`) adapter tarafından normalize edilir
- `q-buffer` tarafında image proxy, watcher item cache ve qBittorrent enrichment katmanları bu scraper çıktısını kullanır