docs: images methods documentation

[lorenzopantano]

Closes #88

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lorenzopant-tmdb-docs	Ready	Preview, Comment	Apr 3, 2026 7:38pm

[qodo-code-review]

Review Summary by Qodo

Enhance image URL builder documentation with methods and examples

📝 Documentation

Walkthroughs

Description

• Add comprehensive method reference table for five image builder methods
• Provide detailed examples for each image category with real API calls
• Document all available size options per image type
• Clarify default size behavior and global configuration

Diagram

flowchart LR
  A["Image Builder Docs"] --> B["Method Reference Table"]
  A --> C["Per-Method Documentation"]
  A --> D["Size Options Reference"]
  A --> E["Configuration Guide"]
  C --> F["poster, backdrop, logo, profile, still"]
  F --> G["Code Examples"]
  G --> H["Real API Usage"]

Loading

File Changes

1. apps/docs/content/docs/getting-started/features.mdx 📝 Documentation +47/-3

Expand image builder examples and method documentation

• Add reference table documenting five image builder methods with input fields and default sizes
• Expand code examples to demonstrate all five image categories with real API calls
• Include practical examples for movies, TV series, people, networks, and episodes
• Clarify that size argument is optional and uses configured defaults when omitted

apps/docs/content/docs/getting-started/features.mdx

---

2. apps/docs/content/docs/getting-started/options/images.mdx 📝 Documentation +93/-0

Add comprehensive image builder method documentation

• Add new "Using tmdb.images" section with detailed method signatures and descriptions
• Document each of five methods (poster, backdrop, logo, profile, still) with code
 examples
• List all available size options for each image category type
• Add "Configuring Default Sizes" section explaining global configuration behavior

apps/docs/content/docs/getting-started/options/images.mdx

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX Issues (0)

1. Optional paths in examples ☑ 🐞 Bug ≡ Correctness

Description

The new docs examples pass optional fields like poster_path, backdrop_path, profile_path, and
still_path directly into tmdb.images.*, but the library types mark these fields optional while
ImageAPI requires path: string. Copying these snippets into a TS project can fail compilation
(strict mode) and/or produce URLs containing undefined at runtime.

Code

apps/docs/content/docs/getting-started/features.mdx[R145-163]

const posterUrl = tmdb.images.poster(movie.poster_path, "w500");
-// → "https://image.tmdb.org/t/p/w500/e1mjopzAS2KNsvpbpahQ1a6SkSn.jpg"
+// → "https://image.tmdb.org/t/p/w500/pB8BM7pdSp6B6Ih7QZ4DrQ3PmJK.jpg"
+
+// Backdrop — movies, TV series
+const backdropUrl = tmdb.images.backdrop(movie.backdrop_path, "w1280");
+// → "https://image.tmdb.org/t/p/w1280/rr7E0NoGKxvbkb89eR1GwfoYjpA.jpg"
+
+// Logo — companies, networks
+const network = await tmdb.networks.details({ network_id: 213 });
+const logoUrl = tmdb.images.logo(network.logo_path, "w185");
+// → "https://image.tmdb.org/t/p/w185/alqLicR1ZMHMaZGP3xRQxn9sq7p.png"
+
+// Profile — people (actors, directors, crew)
+const profileUrl = tmdb.images.profile(person.profile_path, "w185");
+// → "https://image.tmdb.org/t/p/w185/r7WLn4Kbnqb6oJ8TmSI0e3GKEAO.jpg"
+
+// Still — TV episode thumbnails
+const stillUrl = tmdb.images.still(episode.still_path, "w300");
+// → "https://image.tmdb.org/t/p/w300/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg"

Evidence

In the docs snippet, movie.poster_path, movie.backdrop_path, person.profile_path, and
episode.still_path are passed directly to tmdb.images.*. In the library, those fields are typed
as optional (?: string), while ImageAPI methods require a non-optional path: string, so this
is a type mismatch and also risks generating ${baseUrl}${size}${path} with path === undefined.

apps/docs/content/docs/getting-started/features.mdx[134-173]
packages/tmdb/src/images/images.ts[11-34]
packages/tmdb/src/types/movies.ts[31-60]
packages/tmdb/src/types/tv-series.ts[35-80]
packages/tmdb/src/types/people.ts[30-47]
packages/tmdb/src/types/tv-episodes.ts[11-38]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Docs examples pass optional `*_path` fields into `tmdb.images.*` methods that require `string`, causing TS type errors and potential `.../undefined` URLs at runtime.
### Issue Context
`ImageAPI` methods are declared as `(path: string, ...)`, while many TMDB response types expose `poster_path`, `backdrop_path`, `profile_path`, `still_path` as optional.
### Fix Focus Areas
- apps/docs/content/docs/getting-started/features.mdx[134-173]
- apps/docs/content/docs/getting-started/options/images.mdx[16-92]
### What to change
- Update snippets to either:
- guard: `if (!movie.poster_path) return;` before calling, or
- use non-null assertions with an explicit note: `tmdb.images.poster(movie.poster_path!, ...)`.
- Consider adding a one-liner note near the examples: "Image path fields can be undefined; check before building a URL."

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Redeclared const in snippet ☑ 🐞 Bug ⚙ Maintainability

Description

In the poster() docs snippet, const url is declared twice in the same code block, which throws a
redeclaration error if copied verbatim. This makes the example non-runnable as written.

Code

apps/docs/content/docs/getting-started/options/images.mdx[R23-28]

+const url = tmdb.images.poster(movie.poster_path, "w500");
+// → "https://image.tmdb.org/t/p/w500/pB8BM7pdSp6B6Ih7QZ4DrQ3PmJK.jpg"
+
+// Omit size to use the configured default (w500)
+const url = tmdb.images.poster(movie.poster_path);
+```

Evidence

The same fenced code block declares const url = ... for the explicit-size example and then
redeclares const url = ... for the default-size example, which is invalid TS/JS in a single scope.

apps/docs/content/docs/getting-started/options/images.mdx[20-28]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The `poster()` documentation example declares `const url` twice in the same fenced block, causing a redeclaration error if copy/pasted.
### Issue Context
This is purely in documentation, but it impacts copy/paste usability.
### Fix Focus Areas
- apps/docs/content/docs/getting-started/options/images.mdx[20-28]
### What to change
- Rename variables to be unique, e.g.:
- `const posterUrl = ...poster(..., "w500")`
- `const posterUrlDefault = ...poster(...)`
- (Optional) align naming with other examples (`posterUrl`, `backdropUrl`, etc.).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more