# Collectors – sub-CLAUDE.md

Ši direktorija – tik šaltinių adapteriai. Kiekvienas failas ≈ vienas šaltinis.

## Kontraktas

Kiekviena klasė paveldi `base.BaseCollector` ir privalo:

```python
class FooCollector(BaseCollector):
    name = "foo"             # unikalus, naudojamas config.yaml ir scheduler.py
    source_type = "rss"      # "rss" | "api" | "scrape" | "search_trends" | ...

    def collect_for_country(self, country: Country) -> List[TrendItem]:
        # 1) pasiimk konfigūraciją iš self.cfg["collectors"]["foo"]
        # 2) padaryk HTTP per self.http (NE requests tiesiogiai)
        # 3) iteruok rezultatus → yield/return List[TrendItem]
        # NEDARYK self.db.upsert_trend – tai pipeline darbas.
```

## TrendItem laukai (visi optional, išskyrus `keyword`)

| Laukas | Tipas | Pastabos |
|---|---|---|
| `keyword` | str | Nevalytas, su rašmenimis – pipeline išvalys |
| `trend_type` | str | `realtime` / `hourly` / `daily` |
| `category` | str? | Užuomina pipeline'ui (jis tikrins) |
| `language` | str? | ISO 639-1 (`lt`, `en`...). Jei `None`, pipeline atspės |
| `rank` | int? | 1..N (1 – populiariausia) |
| `score` | float? | 0..1 normalizuotas (jei šaltinis duoda %) |
| `volume` | int? | absoliutus skaičius (paieškos, paminėjimai) |
| `description` | str? | trumpas santrauka iki ~500 simb. |
| `url` | str? | šaltinio URL |

## Kontrolės sąrašas naujam kolektoriui

- [ ] Failas `trends_collector/collectors/<name>.py`
- [ ] `name`, `source_type` klasės atributai
- [ ] `collect_for_country` – `try/except` užklausoms, bet **leisk klaidoms
      pakelti**, jei viskas šaltinyje žlugę – pipeline pažymės kaip `error`.
- [ ] Per `self.http.get(url)` / `self.http.get_json(url)` – ne `requests`
- [ ] `self.log.info("[%s] found %d items", country.iso_code, len(items))`
- [ ] Įrašas į `scheduler.COLLECTOR_CLASSES`
- [ ] Įrašas į `config.yaml` `collectors:` su `enabled: false` (saugus default)
- [ ] Testas `tests/test_<name>_collector.py` su mock'intu `HttpClient`
- [ ] Jei reikia API rakto – aprašyk README'e ir naudok env var override
      per `config.py`

## Pavyzdys – paprastas RSS-like kolektorius

```python
"""Naujo šaltinio pavyzdys."""
from __future__ import annotations
from typing import List
from .base import BaseCollector, TrendItem
from ..database import Country


class ExampleCollector(BaseCollector):
    name = "example"
    source_type = "api"

    def collect_for_country(self, country: Country) -> List[TrendItem]:
        api_cfg = self.cfg.get("collectors", {}).get(self.name, {})
        base = api_cfg.get("base_url", "https://example.com/api")
        url = f"{base}/trends?country={country.iso_code}"

        data = self.http.get_json(url)
        if not data or "items" not in data:
            return []

        items: List[TrendItem] = []
        for i, row in enumerate(data["items"][:50], start=1):
            items.append(TrendItem(
                keyword=row["title"],
                trend_type="hourly",
                category=row.get("category"),
                rank=i,
                volume=row.get("count"),
                url=row.get("link"),
            ))
        self.log.info("[%s] example: %d items", country.iso_code, len(items))
        return items
```

## Šalių aprėpties patarimai

Jei šaltinis veikia tik dalies šalių (kaip Google Trends ~49 ISO):
- Saugok mapinimą kolektoriaus modulyje (kaip `PYTRENDS_PN` arba
  `SUBREDDITS_BY_COUNTRY`), ne `countries.py`.
- Jei šalis nepalaikoma → `return []` su `self.log.debug(...)`. **Ne klaida.**
- Jei šaltinis universalus (GDELT, Wikipedia) – naudok `country.iso_code`
  arba FIPS kodą su atvirkštiniu mapinimu.