Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@ TMDB_READ_TOKEN=

# OMDb key. Only the nightly job and local data scripts read it; it never reaches the browser.
OMDB_API_KEY=

# WATCHMODE_API_KEY= (optional, tier-3 deep links, not used yet)
9 changes: 9 additions & 0 deletions .github/workflows/enrich-data.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,15 @@ jobs:
DATA_DIR: data
TMDB_READ_TOKEN: ${{ secrets.TMDB_READ_TOKEN }}

- name: Fold in where-to-watch availability (TMDB / JustWatch)
# A providers failure keeps last night's provider catalogue and publishes tonight's
# rails without `watch`; the UI treats that as unknown, never as unavailable.
continue-on-error: true
run: pnpm data:providers
env:
DATA_DIR: data
TMDB_READ_TOKEN: ${{ secrets.TMDB_READ_TOKEN }}

- name: Fetch ratings from OMDb (hard cap 1,000 requests)
# A rejected OMDb key fails this step visibly but still publishes tonight's catalogue.
continue-on-error: true
Expand Down
24 changes: 19 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# Interval

What to watch, and where. A static film and series discovery site with IMDb, Rotten Tomatoes,
Metacritic and TMDB scores side by side. Phase 1 of [PLAN.md](PLAN.md).
Metacritic and TMDB scores side by side, plus where each title streams, rents or buys in India.
Phase 1 and Phase 2 of [PLAN.md](PLAN.md) (see [docs/phase-2-plan.md](docs/phase-2-plan.md)).

Non-commercial by design: TMDB's free tier and OMDb's CC BY-NC licence both depend on it.

Expand Down Expand Up @@ -32,6 +33,9 @@ OMDB_MAX_NEW=50 pnpm data:ratings # OMDb → public/data/ratings/NN.json
| `pnpm e2e` | Playwright smoke tests against a GitHub-Pages-like server, TMDB mocked |
| `pnpm lint` / `pnpm lint:fix` | Biome |
| `pnpm check:bundle` | Fails if first-load JS exceeds 180 KB gzipped |
| `pnpm data:catalog` | TMDB → `public/data/catalog/*.json` |
| `pnpm data:providers` | TMDB watch/providers → `public/data/providers-tmdb-in.json`, folds `watch` into every catalogue entry |
| `pnpm data:ratings` | OMDb → `public/data/ratings/NN.json` |

## One-time setup (PLAN.md §16, Phase 0)

Expand All @@ -56,15 +60,19 @@ OMDB_MAX_NEW=50 pnpm data:ratings # OMDb → public/data/ratings/NN.json
```
Nightly, 02:30 IST (.github/workflows/enrich-data.yml)
build-catalog.ts TMDB lists → data/catalog/<rail>.json, resolves IMDb IDs
build-providers.ts TMDB watch/providers → data/providers-tmdb-in.json,
folds `watch` (India availability) into every catalogue entry
build-ratings.ts OMDb, ≤500 new + ≤500 stale, hard cap 1,000 → data/ratings/00…99.json
then folds scores into the catalogue entries
force-push `data` branch, one squashed commit
Deploy (on push to main, and after each nightly run)
data branch → public/data → vite build → GitHub Pages and Cloudflare Pages
```

The browser calls TMDB directly for search and title pages, and reads ratings from the
prebuilt shards. It never talks to OMDb and never sees the OMDb key.
The browser calls TMDB directly for search, title pages and per-result availability lookups, and
reads ratings from the prebuilt shards. It never talks to OMDb and never sees the OMDb key. A
title page's own availability comes bundled into the same TMDB detail call
(`append_to_response=watch/providers`), not a separate request.

Search can surface titles the ratings index has not reached yet; they show "—" for IMDb and
RT. Add their IMDb IDs to `scripts/wanted.txt` (or the workflow's manual-run input) and the
Expand All @@ -73,8 +81,14 @@ next run fetches them first.
## Where things live

- `config/app.config.ts`: name, regions, home genre rails, credibility floor, cache TTLs.
- `src/lib/`: TMDB client and types, ratings shard loader, shared formats.
- `src/features/`: browse (home, genre), search, title, watchlist.
- `config/providers.ts`, `config/provider-links.ts`: the streaming-service picker list, provider
ID aliases, and verified tier-2 search-link URLs (docs/phase-2-plan.md §4.4).
- `public/providers-in.json`: hand-maintained India subscription prices, re-verified quarterly
(docs/RUNBOOK.md).
- `src/lib/`: TMDB client and types, ratings shard loader, watch-providers formatting, shared formats.
- `src/features/`: browse (home, genre), search, title, watch (availability block, services
picker, Watchable-now toggle), watchlist.
- `src/ui/`: the handful of primitives: poster card, rail, grid, scorecard and friends.
- `scripts/`: the nightly pipeline and its tests.
- `docs/DECISIONS.md`: why things are the way they are. `docs/RUNBOOK.md`: what breaks.
`docs/phase-2-plan.md`: the Phase 2 ("where to watch") implementation plan.
2 changes: 1 addition & 1 deletion config/app.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ export const app = {
tmdbStaleMinutes: 60,
ratingsCacheTtlMinutes: 60,
priceStaleAfterDays: 120, // hide prices older than this
features: { watchProviders: false, ai: false, groups: false },
features: { watchProviders: true, ai: false, groups: false },
} as const;

export type Region = (typeof app.regions)[number];
41 changes: 41 additions & 0 deletions config/provider-links.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
// Provider site-search URLs: tier 2 (PLAN §8.3). Ordinary search links, not JustWatch data.
// Entries with checked: null are never shown. Click-test each from India; re-check quarterly.
// Last full check: 2026-09-28 (Prime Video, Apple TV only).
export interface ProviderLink {
label: string;
url: (query: string) => string;
checked: string | null;
}

export const PROVIDER_LINKS: Readonly<Record<number, ProviderLink>> = {
119: {
label: 'Prime Video',
url: (q) => `https://www.primevideo.com/search?phrase=${encodeURIComponent(q)}`,
checked: '2026-09-28',
},
350: {
label: 'Apple TV',
url: (q) => `https://tv.apple.com/in/search?term=${encodeURIComponent(q)}`,
checked: '2026-09-28',
},
8: {
label: 'Netflix',
url: (q) => `https://www.netflix.com/search?q=${encodeURIComponent(q)}`,
checked: null,
},
2336: {
label: 'JioHotstar',
url: (q) => `https://www.jiohotstar.com/explore?search_query=${encodeURIComponent(q)}`,
checked: null,
},
237: {
label: 'Sony LIV',
url: (q) => `https://www.sonyliv.com/search?searchTerm=${encodeURIComponent(q)}`,
checked: null,
},
232: {
label: 'ZEE5',
url: (q) => `https://www.zee5.com/search?q=${encodeURIComponent(q)}`,
checked: null,
},
};
30 changes: 30 additions & 0 deletions config/providers.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
/** Canonical IDs offered in "Your services", in display order. Streaming only: rent/buy stores
* (2, 3, 10, 124, 192) are excluded because /discover evaluates providers and monetization
* independently (docs/phase-2-plan.md §2.4). Last checked against TMDB 2026-09-28. */
export const PICKER_PROVIDERS: ReadonlyArray<{ id: number; name: string }> = [
{ id: 8, name: 'Netflix' },
{ id: 119, name: 'Prime Video' },
{ id: 2336, name: 'JioHotstar' },
{ id: 232, name: 'ZEE5' },
{ id: 237, name: 'Sony LIV' },
{ id: 350, name: 'Apple TV' },
{ id: 309, name: 'Sun NXT' },
{ id: 532, name: 'aha' },
{ id: 315, name: 'Hoichoi' },
{ id: 482, name: 'ManoramaMAX' },
{ id: 561, name: 'Lionsgate Play' },
{ id: 510, name: 'Discovery+' },
{ id: 11, name: 'MUBI' },
{ id: 283, name: 'Crunchyroll' },
{ id: 437, name: 'Hungama Play' },
{ id: 474, name: 'ShemarooMe' },
{ id: 476, name: 'EPIC ON' },
{ id: 1898, name: 'Amazon MX Player (free)' },
];

/** Variant → canonical. Owning the canonical ID covers the variant. Never alias channels. */
export const PROVIDER_ALIASES: Readonly<Record<number, number>> = {
2100: 119, // Amazon Prime Video with Ads
175: 8, // Netflix Kids
515: 1898, // MX Player (pre-2024 brand) → Amazon MX Player
};
46 changes: 46 additions & 0 deletions docs/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,4 +136,50 @@ doesn't depend on where the bar is set, only on which titles are being considere
were nearly merged into one query keyed on the thresholds too; that would have re-run the external
ID lookups on every dropdown change for no reason, so they were split.

## 2026-09-28 · Phase 2: where to watch in India

Full research and rationale in `docs/phase-2-plan.md`. The load-bearing decisions:

1. **Availability comes appended to the title detail call, not a separate request.**
`append_to_response=watch/providers` on the same `/movie|tv/{id}` call TMDB already makes for
a title page adds ~2 KB gzip and zero extra round trips, with no second loading state for the
block to handle.
2. **`checked:false` is unknown, never "not available."** A failed or not-yet-attempted lookup is
absent from the UI (the block renders nothing, a filtered rail simply excludes the title,
search puts it under "Couldn't check") — the copy never claims a title *isn't* available when
the honest answer is "we don't know."
3. **"Watchable now" means stream ∪ free ∪ ads intersects your ticked services.** Free/ad-supported
apps count only when the viewer has actually ticked them, so the catalogue filter (client-side
`isWatchableWith`) and `/discover`'s server-side filter agree on the same definition.
4. **The picker only offers services that stream.** Rent/buy stores (Apple TV Store, Google Play,
YouTube, Amazon Video, BookMyShow) are left out of `PICKER_PROVIDERS`, because TMDB's `/discover`
evaluates `with_watch_providers` and `with_watch_monetization_types` independently rather than
per-provider — a store ticked as "owned" would produce false-positive "watchable" matches on
titles that are only rentable there.
5. **Plan variants alias to their parent; channels never do.** `config/providers.ts`'s
`PROVIDER_ALIASES` maps 2100→119 (Prime Video with Ads), 175→8 (Netflix Kids) and 515→1898
(the old MX Player brand), so owning the parent plan marks the variant as owned too. Add-on
"channels" (e.g. an Apple TV Amazon Channel) are deliberately never aliased — they are separate
subscriptions a person may not have.
6. **Watchable-now is a persisted personal preference, not a URL parameter.** Unlike genre filters,
what a person can watch depends on services only they know about, so `usePreferences().
watchableOnly` lives in `localStorage`, never in a shareable link.
7. **Search results are partitioned, not filtered.** `/search/multi` has no provider parameter, so
hiding "not on your services" results would require guessing; instead, each visible result gets
its own `/watch/providers` lookup (≤20 per page, cached) and the same page is split into "On
your services," "Couldn't check" and "Not on your services" sections, in that order, nothing
hidden.
8. **Prices and tier-2 search links are hidden by default, shown only once verified.** A cost line
needs `verified` set and less than `priceStaleAfterDays` (120) old; a provider search link needs
a non-null `checked` date in `config/provider-links.ts`. Both default to hidden rather than
risking a stale or unconfirmed claim.
9. **The region switcher lives inside the availability block, independent of the header's region
select.** The header's existing selector means "which Popular list," a pre-existing and
unrelated concept; coupling the two would silently change one control's meaning when the other
changes.
10. **JustWatch attribution sits inside every availability block, and next to the Watchable-now
toggle when it's on, not only in the footer.** TMDB's own guidance for this data is "a
reference or logo on each media item," so the line travels with the data everywhere it
appears, with a single footer mention besides.


11 changes: 11 additions & 0 deletions docs/RUNBOOK.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,12 @@ PLAN.md §12, trimmed to what exists in Phase 1. Extend it as phases land.

- Re-read TMDB's API terms. The attribution requirements are the ones that get keys revoked.
- Confirm the footer still shows the TMDB logo and notice.
- Re-verify every entry in `public/providers-in.json` against its `source` URL and bump
`verified` to today (ZEE5 ships unverified — check it first). Never backdate `verified`.
- Click every `config/provider-links.ts` URL from a browser in India; set `checked` to today or
to `null` if it no longer works.
- Confirm the JustWatch attribution line is still present inside the availability block and in
the footer.

## Things that will break

Expand All @@ -24,6 +30,10 @@ PLAN.md §12, trimmed to what exists in Phase 1. Extend it as phases land.
| Every page says TMDB rejected the token | Build ran without `TMDB_READ_TOKEN`, or the v3 key was used | Set the repository variable to the v4 read token and redeploy |
| Deep links 404 on GitHub Pages | The build ran without `SPA_404=true` | It is set in `deploy-pages.yml`; check nobody removed it |
| TMDB 429s | Something is looping | Look for new code that fetches outside TanStack Query |
| Where to watch missing on every title | TMDB watch-providers outage or a revoked token | Confirm the block is absent, not "unavailable" (that's correct behaviour); check the "Watch providers" step summary for the run |
| Watchable now empty on home with services picked | The providers step failed last night | Check the "Watch providers" summary; rerun Enrich data |
| Prices vanished from the Stream group | Entries older than `priceStaleAfterDays` (120) | Re-verify `public/providers-in.json` and bump `verified` |
| A service disappears from the picker's logos | TMDB renamed or re-ID'd it (Hotstar 122 → JioHotstar 2336 already happened once) | Update `config/providers.ts` with the new ID/name |

## Knobs for the nightly job

Expand All @@ -36,3 +46,4 @@ Environment variables read by `scripts/build-*.ts`. Change them in `enrich-data.
| `STALE_AFTER_DAYS` | 30 | Age at which a record is refreshed |
| `OMDB_PACING_MS` | 300 | Delay between OMDb calls |
| `BACKLOG_PAGES` | 10 | Pages per backlog list per night (20 titles each) |
| `PROVIDERS_RPS` | 7 | Requests/second for the watch-providers nightly step |
36 changes: 33 additions & 3 deletions e2e/fixtures/data/catalog/popular-in.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,17 @@
"genres": [35, 18],
"lang": "hi",
"imdb": "tt1187043",
"scores": { "i": 8.4, "rt": 100 }
"scores": { "i": 8.4, "rt": 100 },
"watch": {
"checked": true,
"region": "IN",
"link": "https://www.themoviedb.org/movie/20453/watch?locale=IN",
"stream": [],
"free": [],
"ads": [],
"rent": [3, 192],
"buy": [3, 192]
}
},
{
"id": 19404,
Expand All @@ -26,7 +36,17 @@
"genres": [35, 18, 10749],
"lang": "hi",
"imdb": "tt0112870",
"scores": { "i": 8, "rt": 92 }
"scores": { "i": 8, "rt": 92 },
"watch": {
"checked": true,
"region": "IN",
"link": "https://www.themoviedb.org/movie/19404/watch?locale=IN",
"stream": [8],
"free": [],
"ads": [],
"rent": [],
"buy": []
}
},
{
"id": 577922,
Expand All @@ -39,7 +59,17 @@
"genres": [28, 53, 878],
"lang": "en",
"imdb": "tt6723592",
"scores": { "i": 7.3, "rt": 69 }
"scores": { "i": 7.3, "rt": 69 },
"watch": {
"checked": true,
"region": "IN",
"link": "https://www.themoviedb.org/movie/577922/watch?locale=IN",
"stream": [8, 119, 2100],
"free": [],
"ads": [],
"rent": [],
"buy": []
}
}
]
}
51 changes: 46 additions & 5 deletions e2e/fixtures/data/catalog/trending.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,17 @@
"genres": [35, 18, 10749],
"lang": "hi",
"imdb": "tt0112870",
"scores": { "i": 8, "rt": 92 }
"scores": { "i": 8, "rt": 92 },
"watch": {
"checked": true,
"region": "IN",
"link": "https://www.themoviedb.org/movie/19404/watch?locale=IN",
"stream": [8],
"free": [],
"ads": [],
"rent": [],
"buy": []
}
},
{
"id": 577922,
Expand All @@ -31,7 +41,17 @@
"genres": [28, 53, 878],
"lang": "en",
"imdb": "tt6723592",
"scores": { "i": 7.3, "rt": 69 }
"scores": { "i": 7.3, "rt": 69 },
"watch": {
"checked": true,
"region": "IN",
"link": "https://www.themoviedb.org/movie/577922/watch?locale=IN",
"stream": [8, 119, 2100],
"free": [],
"ads": [],
"rent": [],
"buy": []
}
},
{
"id": 9001,
Expand All @@ -45,7 +65,17 @@
"votes": 300,
"genres": [35, 18],
"lang": "hi",
"imdb": null
"imdb": null,
"watch": {
"checked": true,
"region": "IN",
"link": "https://www.themoviedb.org/tv/9001/watch?locale=IN",
"stream": [119, 2100],
"free": [],
"ads": [],
"rent": [],
"buy": []
}
},
{
"id": 20453,
Expand All @@ -60,7 +90,17 @@
"genres": [35, 18],
"lang": "hi",
"imdb": "tt1187043",
"scores": { "i": 8.4, "rt": 100 }
"scores": { "i": 8.4, "rt": 100 },
"watch": {
"checked": true,
"region": "IN",
"link": "https://www.themoviedb.org/movie/20453/watch?locale=IN",
"stream": [],
"free": [],
"ads": [],
"rent": [3, 192],
"buy": [3, 192]
}
},
{
"id": 9002,
Expand All @@ -74,7 +114,8 @@
"votes": 180,
"genres": [53, 18],
"lang": "ml",
"imdb": null
"imdb": null,
"watch": { "checked": false }
},
{
"id": 9003,
Expand Down
8 changes: 8 additions & 0 deletions e2e/fixtures/data/providers-tmdb-in.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
[
{ "id": 8, "name": "Netflix", "logo": "/netflix.png", "priority": 0 },
{ "id": 119, "name": "Amazon Prime Video", "logo": "/prime.png", "priority": 1 },
{ "id": 350, "name": "Apple TV", "logo": "/apple.png", "priority": 2 },
{ "id": 2336, "name": "JioHotstar", "logo": "/jiohotstar.png", "priority": 3 },
{ "id": 232, "name": "Zee5", "logo": "/zee5.png", "priority": 7 },
{ "id": 237, "name": "Sony Liv", "logo": "/sonyliv.png", "priority": 10 }
]
Loading
Loading