# 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 --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.
## 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