# wavecatcher — viral-product wave detection for e-commerce

Watches big tech YouTube channels + Google News for posts featuring cool
physical products. Every 15 minutes: poll feeds -> skip seen IDs -> score each
new item with Workers AI (llama-3.3-70b) on ONE axis:

  product_wave (0-100): is a specific purchasable PHYSICAL product featured /
  prominent, how novel, how strong the affordability angle.

Score >= 55 triggers ONE consolidated alert email per run (max 3/day) with
ready-to-click research links: AliExpress search, Amazon search, Google Trends
— so a product page can be live while search volume spikes.

## Sources
- YouTube channel feeds (Atom, keyless): Mrwhosetheboss, mkbhd, LinusTechTips,
  UnboxTherapy, austinevans, UrAvgConsumer
- Google News RSS: gadget china launch / chinese drone consumer price /
  single-person drone price (automatic Bing News RSS fallback per query —
  news.google.com currently serves 503 to datacenter IPs)
- Manage sources via POST /api/v1/sources (operator token required)

## Endpoints
GET  /                  human dashboard: today's hits by score, source health, totals
GET  /api/v1/signals    public JSON, newest 100, optional ?min_score=N
POST /api/v1/sources    {"action":"add|remove","kind":"yt_channel_id|news_query","value":"...","name":"optional label"} (auth: OPERATOR_TOKEN)
GET  /run               execute one full poll cycle now (auth: OPERATOR_TOKEN via ?token= or Bearer)
GET  /llms.txt          this file
GET  /robots.txt        allow all

## Data model (KV)
signal:<id>     full scored record, TTL 90d
signals:index   newest-first array capped at 200
seen:<src>:<id> dedupe, TTL 30d
health:<skey>   last successful feed poll per source
wave:lastpoll   summary of most recent cycle

## Honest status
Alerts currently human-reviewed; agent-facing signal API + paid realtime tiers planned.