Skip to main content
← back to extensions

Tmdb

@magistr/tmdbv2026.10.25.10· MIT· 1d agoBEHAVIORS
01README

The Movie Database (TMDB) v3 API for swamp — read-only metadata.

  • search — free-text movie / tv / multi search, results scored against the query.
  • details — one movie or show with credits, keywords, external ids and regional certification, normalized.
  • match — fan-out: resolve a whole batch of parsed titles (title + alternative titles + year) to TMDB candidates in one run. Every item keeps its top-5 scored candidates and a string-score verdict (matched / ambiguous / unmatched); a tmdbId on an item pins it. Idempotent: verdicts younger than ttlDays with an unchanged query are reused without a request.
  • enrich — fan-out: fetch normalized details for many ids into one titles resource, with the same TTL cache.

Auth: v4 read-access token (Bearer) or v3 API key; marked sensitive, never persisted, redacted from errors. Requests are spaced (minIntervalMs) and 429/5xx retried honouring Retry-After.

02Release Notes

2026.10.25.10

  • Repo-wide republish; no functional change.
03Behaviors1
@magistr/tmdbv2026.10.25.10extensions/models/tmdb.ts
fn search(query: string)
Search TMDB for a movie, TV show, or both (multi)
ArgumentTypeDescription
querystringFree-text title query
fn details(id: number, kind?: enum)
Fetch full details (credits, keywords, external ids, certification) for one movie or TV show
ArgumentTypeDescription
idnumberTMDB id
kind?enum
fn enrich(id: number, kind?: enum, refresh?: boolean)
Fetch details for many TMDB ids in one run (fan-out) into one titles resource; idempotent via a TTL cache
ArgumentTypeDescription
idnumber
kind?enum
refresh?booleanRefetch everything
fn match()
Resolve a batch of parsed titles to TMDB ids in one run (fan-out), embedding details; idempotent via a TTL cache of prior verdicts

Resources

search(infinite)— Raw search results for one query
title(infinite)— Normalized details of one movie or TV show
titles(infinite)— Batch details cache: normalized details for many movies/shows, keyed kind:id
match(infinite)— Batch title→TMDB resolution cache: verdict, candidates and embedded details per item key
04Previous Versions10
2026.10.25.1MIT

2026.10.25.1

Changed

  • README: swamp vault put now prompts for secrets (hidden input) instead of taking them on the command line, where shell history keeps them.
2026.10.15.9MIT

2026.10.15.9

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.8MIT

2026.10.15.8

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.6MIT

2026.10.15.6

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.5MIT

2026.10.15.5

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.4MIT

2026.10.15.4

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.3MIT

2026.10.15.3

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.2MIT

2026.10.15.2

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.1MIT

2026.10.15.1

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.08.1MIT

2026.10.08.1

  • Initial release: search, details, match (batch title → candidates with TTL cache, pins, maxQueries budget) and enrich (batch id → normalized details with TTL cache).
05Stats
A
100 / 100
Downloads
15
Archive size
23.6 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
Repository
https://github.com/umag/swamp-workspace
06Platforms
07Labels
#tmdb#movies#films#metadata