# Catalog Fallback Verification Pattern

## The 3-Layer Fallback Chain

NexStream uses a 3-layer catalog fallback in `HomeViewModel.fetchCatalogSafe()`:

```
1. Stremio Addons (AddonRepository.getCatalogRows)
   → If installed addons return items, use those.
2. Cloudflare Worker Relay (NexStreamCatalogRepository.getCatalogRow)
   → Key-protected edge cache. No keys in APK.
3. Native TMDB (TmdbCatalogRepository.getCatalogRow)
   → Final fallback. Requires TMDB API key in BuildConfig.
```

## How to Verify End-to-End

```bash
# 1. Health check
curl -s https://nexstream-catalog.tw24fr.workers.dev/v1/health
# → {"ok":true,"service":"nexstream-catalog","version":"1"}

# 2. Test specific catalog IDs the Android app uses
curl -s 'https://nexstream-catalog.tw24fr.workers.dev/v1/catalog/movie/tmdb.trending?skip=0' \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d.get('items',[])),'items')"

# 3. Verify ALL catalog IDs return data
for id in tmdb.trending tmdb.popular tmdb.now_playing tmdb.top_rated tmdb.upcoming; do
  n=$(curl -s "https://nexstream-catalog.tw24fr.workers.dev/v1/catalog/movie/$id?skip=0" \
    | python3 -c "import sys,json; print(len(json.load(sys.stdin).get('items',[])))")
  echo "$id: $n items"
done
```

## Worker CatalogID Mapping

The Worker normalizes catalogIds via `normalizeCatalogId()` in `catalogs.ts`:
- `tmdb.trending` → `tmdb.trending_week`
- `netflix` → `tmdb.ott.netflix`
- `hbo` / `max` → `tmdb.ott.hbo`

The Android `HomeViewModel` sends IDs like `"tmdb.trending"` — the Worker handles the mapping.

## Android Client Verification

The Worker URL is set in `BuildConfig.NEXSTREAM_CATALOG_BASE_URL` which reads from:
- `gradle.properties` → `NEXSTREAM_CATALOG_BASE_URL`
- Or env var `NEXSTREAM_CATALOG_BASE_URL`
- Falls back to `""` → uses dummy URL → relay skipped, TMDB fallback used

Verify:
```bash
grep NEXSTREAM_CATALOG app/build/generated/source/buildConfig/debug/com/nexstream/app/BuildConfig.java
```

## If Catalogs Show Empty

1. Check Worker health endpoint
2. Test a specific catalog ID with curl
3. Verify `BuildConfig.NEXSTREAM_CATALOG_BASE_URL` is not empty
4. Check if any Stremio addons are installed (addons take priority)
5. Check Logcat for `CatalogModule` / `AddonClient` errors