watchwhere 0.2.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Esma Oruç
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# watchwhere
+
+CLI to check which of your streaming subs has a movie, in your region.
+
+![demo](docs/demo.gif)
+
+## why
+
+I have a handful of streaming subs and I always forget which one has what.
+Got tired of opening JustWatch every time — or clicking through each app
+one by one to search. Terminal version of that lookup.
+
+## quick start
+
+Needs [Bun](https://bun.sh) (≥ 1.1).
+
+```bash
+bun install -g watchwhere
+export WATCHWHERE_PROXY=https://watchwhere-proxy.ethsmaa.workers.dev
+ww init       # asks for region + your subscriptions
+ww matrix     # search a movie
+```
+
+That's it. The hosted proxy handles TMDB calls — **no API token needed**.
+
+To make the proxy stick across terminal sessions, add the `export` line to
+your `~/.zshrc` or `~/.bashrc`.
+
+## with your own TMDB token (no proxy)
+
+Prefer to talk to TMDB directly? Get a free v4 Read Access Token from
+[themoviedb.org/settings/api](https://www.themoviedb.org/settings/api)
+(pick the **v4 Read Access Token**, not the v3 API key), then:
+
+```bash
+bun install -g watchwhere
+ww init       # paste your token, then region + subs
+ww matrix
+```
+
+## commands
+
+```
+ww <title>       search and show providers
+ww init          set up token, region, subscriptions
+ww subs          edit subscriptions
+ww lang          change UI language (en / tr)
+ww region        change region
+ww config        show current config
+ww --help
+ww --version
+```
+
+## notes
+
+- config lives in `~/.watchwhere/config.json`
+- ui defaults to english, turkish available via `ww lang`
+- self-host your own proxy from [`proxy/`](./proxy) if you'd rather not use
+  the hosted one
+
+## license
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "watchwhere",
+  "version": "0.2.0",
+  "description": "region-aware streaming availability CLI — find which of your subs has a given title",
+  "type": "module",
+  "bin": {
+    "watchwhere": "./src/index.ts",
+    "ww": "./src/index.ts"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepare": "lefthook install"
+  },
+  "keywords": [
+    "cli",
+    "tmdb",
+    "streaming",
+    "movies",
+    "bun",
+    "typescript"
+  ],
+  "author": "Esma Oruç",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ethsmaa/watchwhere.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ethsmaa/watchwhere/issues"
+  },
+  "homepage": "https://github.com/ethsmaa/watchwhere#readme",
+  "dependencies": {
+    "@inquirer/prompts": "^7.2.1"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.1",
+    "@commitlint/config-conventional": "^21.0.1",
+    "@types/bun": "latest",
+    "lefthook": "^2.1.8",
+    "typescript": "^5.6.3"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/cache.ts

@@ -0,0 +1,66 @@
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getRegionProviders, type TmdbProvider } from "./tmdb.ts";
+
+const CACHE_DIR = join(homedir(), ".watchwhere", "cache");
+const TTL_MS = 24 * 60 * 60 * 1000;
+
+interface CacheEntry {
+  fetchedAt: string;
+  providers: ReadonlyArray<TmdbProvider>;
+}
+
+function cachePath(region: string): string {
+  return join(CACHE_DIR, `providers-${region.toUpperCase()}.json`);
+}
+
+function parseEntry(raw: unknown): CacheEntry | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const v = raw as { fetchedAt?: unknown; providers?: unknown };
+  if (typeof v.fetchedAt !== "string" || !Array.isArray(v.providers)) return null;
+  return { fetchedAt: v.fetchedAt, providers: v.providers as TmdbProvider[] };
+}
+
+async function readCache(region: string): Promise<CacheEntry | null> {
+  try {
+    const raw = await readFile(cachePath(region), "utf8");
+    const parsed = parseEntry(JSON.parse(raw) as unknown);
+    if (!parsed) return null;
+    const age = Date.now() - Date.parse(parsed.fetchedAt);
+    if (Number.isNaN(age) || age > TTL_MS || age < 0) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(region: string, providers: ReadonlyArray<TmdbProvider>): Promise<void> {
+  await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
+  const entry: CacheEntry = { fetchedAt: new Date().toISOString(), providers };
+  const path = cachePath(region);
+  const tmp = `${path}.tmp.${process.pid}`;
+  await writeFile(tmp, JSON.stringify(entry), "utf8");
+  await rename(tmp, path);
+}
+
+export async function getCachedRegionProviders(
+  region: string,
+  token: string,
+  language?: string,
+): Promise<ReadonlyArray<TmdbProvider>> {
+  const cached = await readCache(region);
+  if (cached) return cached.providers;
+  const fresh = await getRegionProviders(region, token, language);
+  writeCache(region, fresh).catch(() => {});
+  return fresh;
+}
+
+export async function isCacheFresh(region: string): Promise<boolean> {
+  try {
+    const s = await stat(cachePath(region));
+    return Date.now() - s.mtimeMs < TTL_MS;
+  } catch {
+    return false;
+  }
+}

package/src/colors.ts

@@ -0,0 +1,20 @@
+const enabled =
+  process.stdout.isTTY === true &&
+  process.env.NO_COLOR === undefined &&
+  process.env.TERM !== "dumb";
+
+function wrap(code: string): (s: string) => string {
+  if (!enabled) return (s) => s;
+  return (s) => `\x1b[${code}m${s}\x1b[0m`;
+}
+
+export const c = {
+  bold: wrap("1"),
+  dim: wrap("2"),
+  red: wrap("31"),
+  green: wrap("32"),
+  yellow: wrap("33"),
+  blue: wrap("34"),
+  cyan: wrap("36"),
+  gray: wrap("90"),
+};

package/src/commands/config.ts

@@ -0,0 +1,58 @@
+import { c } from "../colors.ts";
+import { configPath, loadConfig } from "../config.ts";
+import { resolveLocale, t } from "../i18n.ts";
+import { getCachedRegionProviders } from "../cache.ts";
+
+function redact(token: string): string {
+  if (token.length <= 8) return "*".repeat(token.length);
+  return `${"*".repeat(token.length - 4)}${token.slice(-4)}`;
+}
+
+function relativeTime(iso: string, m: ReturnType<typeof t>): string {
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return iso;
+  const seconds = Math.floor((Date.now() - then) / 1000);
+  if (seconds < 60) return m.relativeNow;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return m.relativeMinutes(minutes);
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return m.relativeHours(hours);
+  const days = Math.floor(hours / 24);
+  return m.relativeDays(days);
+}
+
+export async function runConfig(): Promise<void> {
+  const cfg = await loadConfig();
+  if (!cfg) {
+    throw new Error(t(resolveLocale()).noConfigYet);
+  }
+  const m = t(resolveLocale(cfg.language));
+
+  process.stdout.write(c.dim(`  ${m.resolvingNames}`));
+  let subNames: ReadonlyArray<string> = [];
+  try {
+    const providers = await getCachedRegionProviders(cfg.region, cfg.tmdbToken);
+    const byId = new Map(providers.map((p) => [p.provider_id, p.provider_name]));
+    subNames = cfg.subscriptions.map((id) => byId.get(id) ?? `#${id}`);
+    console.log(c.dim(m.done));
+  } catch {
+    subNames = cfg.subscriptions.map((id) => `#${id}`);
+    console.log(c.yellow(m.offline));
+  }
+
+  console.log();
+  console.log(`  ${c.bold(m.configTitle)}`);
+  console.log();
+  console.log(`    ${m.regionLabel.padEnd(13)} ${cfg.region}`);
+  console.log(`    ${m.languageLabel.padEnd(13)} ${cfg.language}`);
+  console.log(`    ${m.tokenLabel.padEnd(13)} ${c.dim(redact(cfg.tmdbToken))}`);
+  console.log(`    ${m.updatedLabel.padEnd(13)} ${c.dim(relativeTime(cfg.updatedAt, m))}`);
+  console.log(`    ${m.pathLabel.padEnd(13)} ${c.dim(configPath)}`);
+  console.log();
+  console.log(`  ${c.dim(`${m.subscriptionsLabel} (${subNames.length})`)}`);
+  if (subNames.length === 0) {
+    console.log(`    ${c.dim(m.noSubs)}`);
+  } else {
+    for (const name of subNames) console.log(`    ${c.green("●")} ${name}`);
+  }
+}

package/src/commands/init.ts

@@ -0,0 +1,86 @@
+import { checkbox, input, password } from "@inquirer/prompts";
+import { c } from "../colors.ts";
+import { loadConfig, saveConfig } from "../config.ts";
+import { resolveLocale, t } from "../i18n.ts";
+import { getCachedRegionProviders } from "../cache.ts";
+import { usingProxy, verifyToken } from "../tmdb.ts";
+import { pickLanguage } from "./lang.ts";
+
+export async function runInit(): Promise<void> {
+  const existing = await loadConfig();
+  const m = t(resolveLocale(existing?.language));
+
+  if (existing) {
+    console.log(c.dim(`  ${m.existingConfig(existing.region)}`));
+    console.log();
+  }
+
+  let tmdbToken: string;
+  if (usingProxy) {
+    console.log(c.dim(`  ${m.usingProxyNotice}`));
+    console.log();
+    tmdbToken = existing?.tmdbToken ?? "proxy";
+  } else {
+    tmdbToken = await password({
+      message: `${m.tokenPrompt} ${c.dim(`— ${m.tokenHint}`)}`,
+      mask: "*",
+      validate: (v) => (v.trim().length > 20 ? true : m.tokenTooShort),
+    });
+
+    process.stdout.write(c.dim(`  ${m.verifying}`));
+    const ok = await verifyToken(tmdbToken.trim());
+    if (!ok) {
+      console.log(c.red(m.failed));
+      throw new Error(m.invalidToken);
+    }
+    console.log(c.green(m.ok));
+  }
+
+  const region = (
+    await input({
+      message: m.regionPrompt,
+      default: existing?.region ?? "TR",
+      validate: (v) =>
+        /^[A-Za-z]{2}$/.test(v.trim()) ? true : m.regionInvalid,
+    })
+  )
+    .trim()
+    .toUpperCase();
+
+  const language = await pickLanguage(m, existing?.language);
+
+  process.stdout.write(c.dim(`  ${m.loadingProviders(region)}`));
+  const providers = await getCachedRegionProviders(region, tmdbToken.trim());
+  console.log(c.dim(m.providersFound(providers.length)));
+
+  if (providers.length === 0) {
+    throw new Error(m.noProviders(region));
+  }
+
+  const choices = providers.map((p) => ({
+    name: p.provider_name,
+    value: p.provider_id,
+    checked: existing?.subscriptions.includes(p.provider_id) ?? false,
+  }));
+
+  const subscriptions = await checkbox<number>({
+    message: `${m.yourSubsLabel(region)} ${c.dim(m.toggleHintConfirm)}:`,
+    choices,
+    pageSize: 15,
+    loop: false,
+  });
+
+  const saved = await saveConfig({
+    tmdbToken: tmdbToken.trim(),
+    region,
+    language,
+    subscriptions,
+  });
+
+  const m2 = t(resolveLocale(language));
+  console.log();
+  console.log(`  ${c.green("✓")} ${m2.savedTo} ${c.dim("~/.watchwhere/config.json")}`);
+  console.log(`    ${m2.regionLabel.padEnd(13)} ${saved.region}`);
+  console.log(`    ${m2.languageLabel.padEnd(13)} ${saved.language}`);
+  console.log(`    ${m2.subscriptionsLabel.padEnd(13)} ${saved.subscriptions.length}`);
+}

package/src/commands/lang.ts

@@ -0,0 +1,53 @@
+import { select } from "@inquirer/prompts";
+import { c } from "../colors.ts";
+import { loadConfig, saveConfig } from "../config.ts";
+import { resolveLocale, t } from "../i18n.ts";
+
+export const LANGUAGE_PRESETS: ReadonlyArray<{ code: string; label: string }> = [
+  { code: "tr-TR", label: "Türkçe" },
+  { code: "en-US", label: "English" },
+];
+
+export async function pickLanguage(
+  m: ReturnType<typeof t>,
+  current?: string,
+): Promise<string> {
+  return select<string>({
+    message: m.displayLanguagePrompt,
+    choices: LANGUAGE_PRESETS.map((l) => ({
+      name: `${l.label} ${c.dim(`(${l.code})`)}`,
+      value: l.code,
+    })),
+    default: current ?? "en-US",
+  });
+}
+
+export async function runLang(): Promise<void> {
+  const cfg = await loadConfig();
+  if (!cfg) {
+    throw new Error(t(resolveLocale()).noConfigYet);
+  }
+  const m = t(resolveLocale(cfg.language));
+
+  console.log(c.dim(`  ${m.currentLanguage(cfg.language)}`));
+  console.log();
+
+  const language = await pickLanguage(m, cfg.language);
+
+  if (language === cfg.language) {
+    console.log();
+    console.log(c.dim(`  ${m.currentLanguage(language)}`));
+    return;
+  }
+
+  await saveConfig({
+    tmdbToken: cfg.tmdbToken,
+    region: cfg.region,
+    language,
+    subscriptions: cfg.subscriptions,
+  });
+
+  const m2 = t(resolveLocale(language));
+  console.log();
+  console.log(`  ${c.green("✓")} ${m2.languageUpdated(language)}`);
+}

package/src/commands/region.ts

@@ -0,0 +1,45 @@
+import { input } from "@inquirer/prompts";
+import { c } from "../colors.ts";
+import { loadConfig, saveConfig } from "../config.ts";
+import { resolveLocale, t } from "../i18n.ts";
+
+export async function runRegion(): Promise<void> {
+  const cfg = await loadConfig();
+  if (!cfg) {
+    throw new Error(t(resolveLocale()).noConfigYet);
+  }
+  const m = t(resolveLocale(cfg.language));
+
+  console.log(c.dim(`  ${m.currentRegion(cfg.region)}`));
+  console.log();
+
+  const region = (
+    await input({
+      message: m.regionPrompt,
+      default: cfg.region,
+      validate: (v) =>
+        /^[A-Za-z]{2}$/.test(v.trim()) ? true : m.regionInvalid,
+    })
+  )
+    .trim()
+    .toUpperCase();
+
+  if (region === cfg.region) {
+    console.log();
+    console.log(c.dim(`  ${m.currentRegion(region)}`));
+    return;
+  }
+
+  // subs are kept — some provider IDs may not exist in the new region
+  // but ww subs lets the user prune; don't destroy data silently
+  await saveConfig({
+    tmdbToken: cfg.tmdbToken,
+    region,
+    language: cfg.language,
+    subscriptions: cfg.subscriptions,
+  });
+
+  console.log();
+  console.log(`  ${c.green("✓")} ${m.regionUpdated(region)}`);
+  console.log(c.dim(`  ${m.regionHintReviewSubs}`));
+}

package/src/commands/search.ts

@@ -0,0 +1,199 @@
+import { c } from "../colors.ts";
+import type { Config } from "../config.ts";
+import { resolveLocale, t } from "../i18n.ts";
+import { picker } from "../picker.ts";
+import { editableInput } from "../prompts.ts";
+import {
+  getWatchProviders,
+  searchAll,
+  type MediaItem,
+  type TmdbProvider,
+} from "../tmdb.ts";
+
+const PAGE_SIZE = 10;
+const SOFT_LIMIT = 25;
+const OVERVIEW_MAX = 140;
+
+function year(date: string | null): string {
+  return date && date.length >= 4 ? date.slice(0, 4) : "????";
+}
+
+function tag(type: MediaItem["mediaType"], m: ReturnType<typeof t>): string {
+  return c.dim(`[${type === "tv" ? m.tagTv : m.tagMovie}]`);
+}
+
+function pad(s: string, n: number): string {
+  return s.length >= n ? s : s + " ".repeat(n - s.length);
+}
+
+function mark(owned: boolean): string {
+  return owned ? c.green("✓") : c.red("✗");
+}
+
+function joinNames(providers: ReadonlyArray<TmdbProvider> | undefined): string {
+  return providers?.map((p) => p.provider_name).join(", ") ?? "";
+}
+
+async function pickItem(
+  results: ReadonlyArray<MediaItem>,
+  m: ReturnType<typeof t>,
+): Promise<MediaItem | null> {
+  const visible = results.slice(0, SOFT_LIMIT);
+  const dropped = results.length - visible.length;
+
+  const choices = visible.map((mi) => ({
+    name: `${tag(mi.mediaType, m)} ${mi.title} ${c.dim(`(${year(mi.date)})`)}${mi.title !== mi.originalTitle ? c.dim(` — ${mi.originalTitle}`) : ""}`,
+    value: mi,
+    description: mi.overview.slice(0, OVERVIEW_MAX),
+  }));
+
+  const headerParts: string[] = [m.whichOne];
+  if (dropped > 0) {
+    headerParts.push(c.dim(`(${visible.length}/${results.length})`));
+  }
+
+  return picker<MediaItem>({
+    message: headerParts.join(" "),
+    pageSize: PAGE_SIZE,
+    choices,
+    extraKeys: [["esc", "edit"]],
+  });
+}
+
+function printOwnership(
+  flat: ReadonlyArray<TmdbProvider>,
+  owned: ReadonlySet<number>,
+  m: ReturnType<typeof t>,
+): void {
+  if (flat.length === 0) return;
+  const sorted = [...flat].sort((a, b) => {
+    const ao = owned.has(a.provider_id) ? 0 : 1;
+    const bo = owned.has(b.provider_id) ? 0 : 1;
+    return ao - bo || a.provider_name.localeCompare(b.provider_name);
+  });
+  const width = Math.max(...sorted.map((p) => p.provider_name.length));
+  for (const p of sorted) {
+    const isOwned = owned.has(p.provider_id);
+    const name = pad(p.provider_name, width);
+    const status = isOwned ? c.green(m.owned) : c.dim(m.notOwned);
+    console.log(`  ${c.dim(m.onPrefix)} ${name}  ${mark(isOwned)} ${status}`);
+  }
+}
+
+async function displayItem(
+  item: MediaItem,
+  cfg: Config,
+  m: ReturnType<typeof t>,
+): Promise<void> {
+  process.stdout.write(c.dim(`  ${m.fetchingProviders(cfg.region)}`));
+  const providers = await getWatchProviders(item.id, item.mediaType, cfg.tmdbToken);
+  console.log(c.dim(m.done));
+
+  const regionData = providers.results[cfg.region];
+  const owned = new Set(cfg.subscriptions);
+
+  console.log();
+  console.log(
+    `  ${c.bold(item.title)} ${c.dim(`(${year(item.date)})`)}  ${tag(item.mediaType, m)}  ${c.dim(cfg.region)}`,
+  );
+  console.log();
+
+  if (!regionData) {
+    console.log(`  ${c.yellow(m.notAvailable(cfg.region))}`);
+    console.log(c.dim(`  ${m.notAvailableHint}`));
+    return;
+  }
+
+  const flat = regionData.flatrate ?? [];
+  const ownedHits = flat.filter((p) => owned.has(p.provider_id));
+
+  if (ownedHits.length > 0) {
+    const names = ownedHits.map((p) => p.provider_name).join(", ");
+    console.log(`  ${c.green("●")} ${m.onYourSubsPrefix} ${c.bold(names)}`);
+  } else if (flat.length > 0) {
+    console.log(`  ${c.yellow("●")} ${m.streamingNotOnSubs(cfg.region)}`);
+  } else {
+    console.log(`  ${c.yellow("●")} ${m.noStreamingSub(cfg.region)}`);
+  }
+
+  if (flat.length > 0) {
+    console.log();
+    printOwnership(flat, owned, m);
+  }
+
+  const free = regionData.free ?? [];
+  if (free.length > 0) {
+    console.log();
+    console.log(c.dim(`  ${m.free}`));
+    printOwnership(free, owned, m);
+  }
+
+  const ads = regionData.ads ?? [];
+  if (ads.length > 0) {
+    console.log();
+    console.log(`  ${pad(m.ads, 6)}${joinNames(ads)}`);
+  }
+
+  const rent = regionData.rent ?? [];
+  const buy = regionData.buy ?? [];
+  if (rent.length > 0 || buy.length > 0) {
+    if (ads.length === 0) console.log();
+    if (rent.length > 0) console.log(`  ${pad(m.rent, 6)}${joinNames(rent)}`);
+    if (buy.length > 0) console.log(`  ${pad(m.buy, 6)}${joinNames(buy)}`);
+  }
+
+  if (regionData.link) {
+    console.log();
+    console.log(`  ${c.dim(m.link)}  ${c.cyan(regionData.link)}`);
+  }
+}
+
+export async function runSearch(query: string, cfg: Config): Promise<void> {
+  const m = t(resolveLocale(cfg.language));
+  let currentQuery = query.trim();
+  if (!currentQuery) throw new Error(m.searchEmpty);
+
+  // pipe mode: no prompts
+  if (!process.stdin.isTTY) {
+    process.stdout.write(c.dim(`  ${m.searching(currentQuery)}`));
+    const results = await searchAll(currentQuery, cfg.tmdbToken, {
+      region: cfg.region,
+      language: cfg.language,
+    });
+    console.log(c.dim(m.resultsCount(results.length)));
+    if (results.length === 0) throw new Error(m.noMatch);
+    if (results.length > 1) throw new Error(m.ambiguousQuery(results.length));
+    await displayItem(results[0]!, cfg, m);
+    return;
+  }
+
+  while (true) {
+    process.stdout.write(c.dim(`  ${m.searching(currentQuery)}`));
+    const results = await searchAll(currentQuery, cfg.tmdbToken, {
+      region: cfg.region,
+      language: cfg.language,
+    });
+    console.log(c.dim(m.resultsCount(results.length)));
+
+    let picked: MediaItem | null = null;
+    if (results.length > 0) {
+      picked = await pickItem(results, m);
+    } else {
+      console.log(`\n  ${m.noMatch}`);
+    }
+
+    if (picked !== null) {
+      await displayItem(picked, cfg, m);
+      return;
+    }
+
+    const next = (
+      await editableInput({
+        message: c.dim("ww"),
+        prefill: currentQuery,
+      })
+    ).trim();
+    if (!next) throw new Error(m.searchEmpty);
+    currentQuery = next;
+  }
+}