### Install Development Tools with Homebrew

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

Installs essential development tools like SwiftLint, SwiftFormat, MarkdownLint, and XCSift using Homebrew. Ensure Homebrew is installed first.

```bash
brew install swiftlint swiftformat markdownlint xcsift
```

--------------------------------

### Quick Start: TMDb API Client Usage

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

Demonstrates basic usage of the TMDb client, including discovering popular movies, fetching movie details, searching across different media types, getting trending movies, retrieving watch providers, and generating image URLs. Requires API key initialization.

```swift
import TMDb

// Initialize client
let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>")

// Discover movies with filters
let popularMovies = try await tmdbClient.discover.movies(
    sortedBy: .popularity(descending: true)
).results

// Get movie details
let fightClub = try await tmdbClient.movies.details(forMovie: 550)
print("Title: \(fightClub.title)")
if let releaseDate = fightClub.releaseDate {
    print("Release Date: \(releaseDate.formatted(.dateTime.year().month().day()))")
}
if let voteAverage = fightClub.voteAverage {
    print("Rating: \(voteAverage.formatted(.voteAveragePercentage))")
}

// Search across movies, TV shows, and people
let searchResults = try await tmdbClient.search.multi(query: "Breaking Bad")

// Get trending movies today
let trendingMovies = try await tmdbClient.trending.movies(inTimeWindow: .day)

// Get streaming providers for a movie
let watchProviders = try await tmdbClient.movies.watchProviders(forMovie: 550)
if let usProvider = watchProviders.first(where: { $0.countryCode == "US" }) {
    print("Available on: \(usProvider.watchProviders.flatRate?.map(\.name) ?? [])")
}

// Generate poster image URL
let config = try await tmdbClient.configurations.apiConfiguration()
if let posterPath = fightClub.posterPath {
    let posterURL = config.images.posterURL(for: posterPath, idealWidth: 500)
}

// Or request a specific size, directly from the model
let posterURL = fightClub.posterURL(using: config.images, size: .width(500))
```

--------------------------------

### Generate Poster URL using Model Accessor

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/GeneratingImageURLs.md

Models conforming to image-providing protocols offer convenience methods to generate image URLs. This example uses a movie model's accessor to get a poster URL with a specific size.

```swift
let posterURL = barbieMovie.posterURL(
    using: imagesConfiguration,
    size: .width(500)
)
```

--------------------------------

### Create TMDbClient with API Key

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/GettingStarted/CreatingTMDbClient.md

Instantiate a TMDbClient using your TMDb API key. This is the most basic setup for making API requests.

```swift
let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>")
```

--------------------------------

### Fetch Movie Images and Videos

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/FetchingMovieAndTVDetails.md

Get image assets (posters, backdrops) and video content (trailers, clips) for a movie using MovieService/images and MovieService/videos.

```swift
let images = try await tmdbClient.movies.images(forMovie: 550)
print("Posters: \(images.posters.count)")
print("Backdrops: \(images.backdrops.count)")

let videos = try await tmdbClient.movies.videos(forMovie: 550)
for video in videos.results {
    print("\(video.name) (\(video.type))")
}
```

--------------------------------

### Generate Movie Poster URL

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/GeneratingImageURLs.md

Once you have the images configuration, you can generate a full URL for a movie's poster using its path. This example demonstrates fetching movie details and then creating the poster URL.

```swift
let barbieMovie = try await tmdbClient.movies.details(forMovie: 346698)

let barbiePosterURL = imagesConfiguration.posterURL(
    for: barbieMovie.posterPath
)
```

--------------------------------

### Fetch Watch Providers for a Movie

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/FetchingMovieAndTVDetails.md

Find where a movie is available for streaming by using MovieService/watchProviders. This example shows how to filter by country code (e.g., US).

```swift
let providers = try await tmdbClient.movies.watchProviders(
    forMovie: 550
)

if let usProvider = providers.first(where: {
    $0.countryCode == "US"
}) {
    let streaming = usProvider.watchProviders.flatRate?.map(
        \.name
    ) ?? []
    print("Streaming on: \(streaming.joined(separator: ", "))")
}
```

--------------------------------

### Discover Popular Movies

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/DiscoveringMoviesAndTVSeries.md

Access the DiscoverService through the TMDbClient.discover property to find movies. This example shows how to discover popular movies and sort them by popularity in descending order.

```swift
let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>")

// Discover popular movies (no filters)
let popularMovies = try await tmdbClient.discover.movies()

// Sort by popularity
let sorted = try await tmdbClient.discover.movies(
    sortedBy: .popularity(descending: true)
)

for movie in sorted.results {
    print(movie.title)
}
```

--------------------------------

### Early Termination of Pagination Loop

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/UsingAutoPagination.md

Break out of the pagination loop to stop fetching additional pages, which saves unnecessary network requests. This example retrieves only the first 50 top-rated movies.

```swift
// Get only the first 50 top-rated movies
var count = 0
for try await movie in tmdbClient.movies.allTopRated() {
    count += 1
    if count >= 50 { break }
}
```

--------------------------------

### Compose Movie Filters Fluently

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/DiscoveringMoviesAndTVSeries.md

Filters can be composed incrementally using copy-returning builder methods. Each method returns a new filter, leaving the original unchanged. This example demonstrates chaining filters for genres, vote average, and release year.

```swift
let filter = DiscoverMovieFilter()
    .withGenres([28, 12])
    .voteAverage(in: 7...10)
    .primaryReleaseYear(.on(2024))
```

--------------------------------

### Add All TMDb Tools to a Language Model Session

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/UsingLanguageModelTools.md

Instantiate a `TMDbClient` and add all available TMDb tools to a `LanguageModelSession` to allow it to answer general movie and TV questions.

```swift
import FoundationModels
import TMDb

let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>")

let session = LanguageModelSession(tools: tmdbClient.languageModelTools)
let reply = try await session.respond(to: "What's trending?")
print(reply.content)
```

--------------------------------

### Run Integration Tests and Create GitHub PR

Source: https://github.com/adamayoung/tmdb/blob/main/CLAUDE.md

Demonstrates running integration tests and creating a GitHub pull request. Ensure required environment variables are set in `.claude/settings.local.json`.

```bash
make integration-test
gh pr create ...
```

--------------------------------

### TV Season Translations

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/TVSeasonService.md

Gets the translations for a TV season.

```APIDOC
### Translations

#### `translations(forSeason:inTVSeries:)`

Retrieves the translations for a specific TV season.

```

--------------------------------

### User Authentication and Session Creation

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

Create a user session by requesting a token, directing the user for approval, and then creating a session with the approved token.

```swift
// Authenticate the user and create a session
let token = try await tmdbClient.authentication.requestToken()
let authURL = tmdbClient.authentication.authenticateURL(for: token)
// Present authURL to the user to approve the token, then:
let session = try await tmdbClient.authentication.createSession(withToken: token)
```

--------------------------------

### Get Movie Watchlist

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

Retrieve the list of movies currently in the user's watchlist using an authenticated session.

```swift
// Get the movie watchlist
let watchlist = try await tmdbClient.account.movieWatchlist(
    authenticatedSession: authenticatedSession
)
```

--------------------------------

### Run Development Commands

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

Provides quick commands for common development tasks: auto-formatting code, checking code style, running unit tests, and performing full CI validation. Ensure all tests pass before submitting a PR.

```bash
make format        # Auto-format code
make lint          # Check code style
make test          # Run unit tests
make ci            # Full CI validation
```

--------------------------------

### Get Weekly Trending People

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/WorkingWithTrending.md

Fetch trending people for the current week. This requires an active TMDbClient instance.

```swift
let trendingPeople = try await tmdbClient.trending.people(
    inTimeWindow: .week
)

for person in trendingPeople.results {
    print(person.name)
}
```

--------------------------------

### Get All Person Changes (Auto-Pagination)

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves all person changes within a specified date range using auto-pagination.

```APIDOC
## GET /changes/person/all

### Description
Retrieves all person changes within a specified date range using auto-pagination.

### Method
GET

### Endpoint
/changes/person/all

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
```

--------------------------------

### Use Direct Client Tools in a Session

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/UsingLanguageModelTools.md

Utilize individual tools directly from the `TMDbClient` instance when default language or region settings are not required for the session.

```swift
let session = LanguageModelSession(
    tools: [tmdbClient.searchTool, tmdbClient.watchProvidersTool]
)
```

--------------------------------

### Select Specific TMDb Tools for a Session

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/UsingLanguageModelTools.md

Construct a `TMDbToolbox` with a specific client and region, then pass a curated subset of tools to a `LanguageModelSession` for focused tasks.

```swift
let toolbox = TMDbToolbox(client: tmdbClient, region: "GB")

let session = LanguageModelSession(
    tools: [toolbox.search, toolbox.discoverMovies, toolbox.watchProviders]
)
let reply = try await session.respond(to: "A thriller on Netflix?")
```

--------------------------------

### Get All Movie Changes (Auto-Pagination)

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves all movie changes within a specified date range using auto-pagination.

```APIDOC
## GET /changes/movie/all

### Description
Retrieves all movie changes within a specified date range using auto-pagination.

### Method
GET

### Endpoint
/changes/movie/all

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
```

--------------------------------

### Use TMDbClient to Discover Movies and Fetch Details

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/GettingStarted/CreatingTMDbClient.md

Demonstrates how to use a configured TMDbClient to discover movies and retrieve detailed information for a specific movie.

```swift
let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>")

let moviesToDiscover = try await tmdbClient.discover.movies().results
let fightClub = try await tmdbClient.movies.details(forMovie: 550)
```

--------------------------------

### Get Person Change Details

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves detailed changes for a specific person within a specified date range and page.

```APIDOC
## GET /person/{person_id}/changes

### Description
Retrieves detailed changes for a specific person within a specified date range and page.

### Method
GET

### Endpoint
/person/{person_id}/changes

### Parameters
#### Path Parameters
- **person_id** (integer) - Required - The ID of the person.
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
- **page** (integer) - Optional - The page number for pagination.
```

--------------------------------

### Request Authentication Token and Session

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/ManagingUserAccounts.md

Before using account features, create a session by first requesting a token, presenting an authentication URL to the user, and then creating a session with the approved token.

```swift
let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>")

// Create a request token
let token = try await tmdbClient.authentication.requestToken()

// Get the authentication URL for the user to approve the token
let authURL = tmdbClient.authentication.authenticateURL(
    for: token
)
// Present authURL to the user in a browser...

// After the user approves, create a session
let session = try await tmdbClient.authentication.createSession(
    withToken: token
)
```

--------------------------------

### Get Movie Change Details

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves detailed changes for a specific movie within a specified date range and page.

```APIDOC
## GET /movie/{movie_id}/changes

### Description
Retrieves detailed changes for a specific movie within a specified date range and page.

### Method
GET

### Endpoint
/movie/{movie_id}/changes

### Parameters
#### Path Parameters
- **movie_id** (integer) - Required - The ID of the movie.
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
- **page** (integer) - Optional - The page number for pagination.
```

--------------------------------

### Get Changed Person IDs

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves a list of person IDs that have changed within a specified date range and page.

```APIDOC
## GET /changes/person

### Description
Retrieves a list of person IDs that have changed within a specified date range and page.

### Method
GET

### Endpoint
/changes/person

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
- **page** (integer) - Optional - The page number for pagination.
```

--------------------------------

### Accessing Sample Data

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDbTesting/TMDbTesting.docc/TMDbTesting.md

Access realistic sample data models for movies and genres. These are useful for previews, fixtures, and as default return values for mock services.

```swift
let movie = Movie.sample
let genres = [Genre].samples
```

--------------------------------

### Get Changed Movie IDs

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves a list of movie IDs that have changed within a specified date range and page.

```APIDOC
## GET /changes/movie

### Description
Retrieves a list of movie IDs that have changed within a specified date range and page.

### Method
GET

### Endpoint
/changes/movie

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
- **page** (integer) - Optional - The page number for pagination.
```

--------------------------------

### Run CI Checks

Source: https://github.com/adamayoung/tmdb/blob/main/CLAUDE.md

Execute the full Continuous Integration pipeline, including linting, testing, and building release artifacts. This is the mandatory pre-Pull Request gate.

```makefile
make ci
```

--------------------------------

### Get Daily Trending TV Series

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/WorkingWithTrending.md

Retrieve trending TV series for the current day. Ensure the TMDbClient is properly configured.

```swift
let trendingTV = try await tmdbClient.trending.tvSeries(
    inTimeWindow: .day
)

for series in trendingTV.results {
    print(series.name)
}
```

--------------------------------

### Manage Episode Account States and Ratings

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/TVEpisodeService.md

Allows users to get account states and manage ratings for a specific TV episode.

```APIDOC
## Manage Episode Account States and Ratings

### Description
Manages account states and ratings for a specific TV episode using a provided session.

### Method Signature
`accountStates(forEpisode:inSeason:inTVSeries:session:)`
`addRating(_:toEpisode:inSeason:inTVSeries:session:)`
`deleteRating(forEpisode:inSeason:inTVSeries:session:)`

### Parameters
- `forEpisode` (Int) - Required - The ID of the episode.
- `inSeason` (Int) - Required - The season number the episode belongs to.
- `inTVSeries` (Int) - Required - The ID of the TV series the episode belongs to.
- `session` (String) - Required - The user's session ID.
- `rating` (Double) - Required for `addRating` - The rating value to add.
```

--------------------------------

### Fetch API Configuration

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/GeneratingImageURLs.md

Before generating image URLs, you must fetch the API's image configuration. This snippet shows how to initialize the TMDb client and retrieve the necessary configuration.

```swift
let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>")

let apiConfiguration = try await tmdbClient.configurations.apiConfiguration()
let imagesConfiguration = apiConfiguration.images
```

--------------------------------

### Get All Person Changes Pages (Auto-Pagination)

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves all person changes pages within a specified date range using auto-pagination.

```APIDOC
## GET /changes/person/pages

### Description
Retrieves all person changes pages within a specified date range using auto-pagination.

### Method
GET

### Endpoint
/changes/person/pages

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
```

--------------------------------

### CI Linux Build is Handled by `build-test-linux` Job

Source: https://github.com/adamayoung/tmdb/blob/main/knowledge/gotchas.md

The `make ci` command does not run the Linux build. Linux/Windows portability is verified by the `build-test-linux` job in the CI workflow, which uses a specific Docker image.

```bash
swift build --build-tests
```

--------------------------------

### Check Foundation Model Availability

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/UsingLanguageModelTools.md

Verify the availability of the default system language model before initializing a `LanguageModelSession` to ensure it can process requests.

```swift
switch SystemLanguageModel.default.availability {
case .available:
    let session = LanguageModelSession(tools: tmdbClient.languageModelTools)
    // ...

case .unavailable(let reason):
    print("Foundation model unavailable: \(reason)")
}
```

--------------------------------

### Get All Movie Changes Pages (Auto-Pagination)

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves all movie changes pages within a specified date range using auto-pagination.

```APIDOC
## GET /changes/movie/pages

### Description
Retrieves all movie changes pages within a specified date range using auto-pagination.

### Method
GET

### Endpoint
/changes/movie/pages

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
```

--------------------------------

### Get All TV Series Changes (Auto-Pagination)

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves all TV series changes within a specified date range using auto-pagination.

```APIDOC
## GET /changes/tv/all

### Description
Retrieves all TV series changes within a specified date range using auto-pagination.

### Method
GET

### Endpoint
/changes/tv/all

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
```

--------------------------------

### Using MockMovieService for Testing

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDbTesting/TMDbTesting.docc/TMDbTesting.md

Instantiate and use MockMovieService for testing movie-related TMDb calls. It provides default sample data or allows injecting specific results and asserting on recorded calls.

```swift
import TMDb
import TMDbTesting

let movieService = MockMovieService()

// Zero-config: returns Movie.sample.
let movie = try await movieService.details(forMovie: 550)

// Inject a specific outcome.
movieService.detailsResult = .failure(.notFound)

// Assert on what was called.
#expect(movieService.detailsCalls.first?.movieID == 550)
```

--------------------------------

### Initialize TMDbClient with API Key and System Locale

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

Initialize the TMDb client using an API key. The client will automatically use the system's current language and country settings.

```swift
import TMDb

// Uses system locale automatically (recommended)
let tmdbClient = TMDbClient(apiKey: "<your-api-key>")
```

--------------------------------

### Move TMDbTesting Sources to TMDbIntelligenceTesting

Source: https://github.com/adamayoung/tmdb/blob/main/plans/tmdb-intelligence-product-extraction.md

Relocate testing kit sources from TMDbTesting to TMDbIntelligenceTesting using git mv. Each moved file should gain an import for TMDbIntelligence while retaining its TMDb import.

```bash
git mv Sources/TMDbTesting/ Services/MockNaturalLanguageSearchService.swift
Sources/TMDbTesting/ Samples/NaturalLanguageSearchResult+Sample.swift
Sources/TMDbTesting/ Samples/NaturalLanguageSearchAvailability+Sample.swift
Sources/TMDbTesting/ Samples/SearchPlan+Sample.swift

```

--------------------------------

### Get Daily and Weekly Trending Movies

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/WorkingWithTrending.md

Fetch trending movies for a specific time window (daily or weekly). Requires an initialized TMDbClient.

```swift
let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>")

// Get today's trending movies
let dailyTrending = try await tmdbClient.trending.movies(
    inTimeWindow: .day
)

for movie in dailyTrending.results {
    print(movie.title)
}

// Get this week's trending movies
let weeklyTrending = try await tmdbClient.trending.movies(
    inTimeWindow: .week
)
```

--------------------------------

### Auto-Pagination: All Multi

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/SearchService.md

Fetches all results across multiple media types with auto-pagination, including optional filtering and language.

```APIDOC
## allMulti(query:filter:language:)

### Description
Fetches all results across multiple media types with auto-pagination, including optional filtering and language.

### Parameters
#### Path Parameters
- **query** (String) - Required - The search query.
- **filter** (String) - Optional - The filter to apply to the search.
- **language** (String) - Optional - The language for the search results.
```

--------------------------------

### Get TV Episode Change Details

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves detailed changes for a specific TV episode within a specified date range and page.

```APIDOC
## GET /episode/{episode_id}/changes

### Description
Retrieves detailed changes for a specific TV episode within a specified date range and page.

### Method
GET

### Endpoint
/episode/{episode_id}/changes

### Parameters
#### Path Parameters
- **episode_id** (integer) - Required - The ID of the TV episode.
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
- **page** (integer) - Optional - The page number for pagination.
```

--------------------------------

### Get TV Season Change Details

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves detailed changes for a specific TV season within a specified date range and page.

```APIDOC
## GET /season/{season_id}/changes

### Description
Retrieves detailed changes for a specific TV season within a specified date range and page.

### Method
GET

### Endpoint
/season/{season_id}/changes

### Parameters
#### Path Parameters
- **season_id** (integer) - Required - The ID of the TV season.
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
- **page** (integer) - Optional - The page number for pagination.
```

--------------------------------

### Creating Sessions

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/AuthenticationService.md

Methods for creating different types of user sessions.

```APIDOC
## `guestSession()`

### Description
Creates a guest session for a user.

### Method
Not specified (likely a SDK method call)

### Endpoint
Not specified

### Parameters
None

### Response
Details not specified.
```

```APIDOC
## `requestToken()`

### Description
Requests an authentication token for user authentication.

### Method
Not specified (likely a SDK method call)

### Endpoint
Not specified

### Parameters
None

### Response
Details not specified.
```

```APIDOC
## `authenticateURL(for:redirectURL:)`

### Description
Generates an authentication URL for redirecting users to authenticate.

### Method
Not specified (likely a SDK method call)

### Endpoint
Not specified

### Parameters
- **for** (type not specified) - Description not specified.
- **redirectURL** (type not specified) - Description not specified.

### Response
Details not specified.
```

```APIDOC
## `createSession(withToken:)`

### Description
Creates a user session using a provided authentication token.

### Method
Not specified (likely a SDK method call)

### Endpoint
Not specified

### Parameters
- **withToken** (type not specified) - Description not specified.

### Response
Details not specified.
```

```APIDOC
## `createSession(withCredential:)`

### Description
Creates a user session using user credentials.

### Method
Not specified (likely a SDK method call)

### Endpoint
Not specified

### Parameters
- **withCredential** (type not specified) - Description not specified.

### Response
Details not specified.
```

```APIDOC
## `createSession(withV4AccessToken:)`

### Description
Creates a user session using a v4 access token.

### Method
Not specified (likely a SDK method call)

### Endpoint
Not specified

### Parameters
- **withV4AccessToken** (type not specified) - Description not specified.

### Response
Details not specified.
```

--------------------------------

### Enable Response Caching with Default Configuration

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/GettingStarted/CreatingTMDbClient.md

Activate default response caching with a 1-hour TTL and 100 entries. This reduces redundant network requests on Apple platforms.

```swift
let configuration = TMDbConfiguration(
    cache: .default  // 1-hour TTL, 100 entries
)

let tmdbClient = TMDbClient(
    apiKey: "<your-tmdb-api-key>",
    configuration: configuration
)
```

--------------------------------

### Get TV Series Change Details

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves detailed changes for a specific TV series within a specified date range and page.

```APIDOC
## GET /tv/{tv_id}/changes

### Description
Retrieves detailed changes for a specific TV series within a specified date range and page.

### Method
GET

### Endpoint
/tv/{tv_id}/changes

### Parameters
#### Path Parameters
- **tv_id** (integer) - Required - The ID of the TV series.
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
- **page** (integer) - Optional - The page number for pagination.
```

--------------------------------

### Get Changed TV Series IDs

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves a list of TV series IDs that have changed within a specified date range and page.

```APIDOC
## GET /changes/tv

### Description
Retrieves a list of TV series IDs that have changed within a specified date range and page.

### Method
GET

### Endpoint
/changes/tv

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
- **page** (integer) - Optional - The page number for pagination.
```

--------------------------------

### Auto-Pagination: Prefetching Next Page

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

Opt in to prefetching the next page concurrently as the current page is consumed, reducing inter-page latency. This is an opt-in feature.

```swift
// Opt in to prefetching: the next page is fetched concurrently as the current
// page is consumed, hiding inter-page latency on long scans.
for try await movie in tmdbClient.movies.allPopular().prefetchingNextPage() {
    print(movie.title)
}
```

--------------------------------

### Get Movie Watch Providers

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

Retrieve streaming availability information for a movie. Filters results by country code to find providers in a specific region.

```swift
let providers = try await tmdbClient.movies.watchProviders(forMovie: movieId)
if let usProvider = providers.first(where: { $0.countryCode == "US" }) {
    print("Available on: \(usProvider.watchProviders.flatRate?.map(\.name) ?? [])")
}
```

--------------------------------

### TMDbClient Initializers

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/TMDbClient.md

Initializers for creating an instance of TMDbClient. You can authenticate using an API key or a bearer token, and optionally provide a custom HTTP client.

```APIDOC
## Initializers

### `init(apiKey:configuration:)`

Initializes the TMDbClient with an API key and configuration.

### `init(apiKey:httpClient:configuration:)`

Initializes the TMDbClient with an API key, a custom HTTP client, and configuration.

### `init(bearerToken:configuration:)`

Initializes the TMDbClient with a bearer token and configuration.

### `init(bearerToken:httpClient:configuration:)`

Initializes the TMDbClient with a bearer token, a custom HTTP client, and configuration.
```

--------------------------------

### Get All TV Series Changes Pages (Auto-Pagination)

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/ChangesService.md

Retrieves all TV series changes pages within a specified date range using auto-pagination.

```APIDOC
## GET /changes/tv/pages

### Description
Retrieves all TV series changes pages within a specified date range using auto-pagination.

### Method
GET

### Endpoint
/changes/tv/pages

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for the changes.
- **endDate** (string) - Required - The end date for the changes.
```

--------------------------------

### Mock TMDb Movie Service in Tests

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

Demonstrates using MockMovieService from TMDbTesting to stub API responses and verify calls in tests. Use .sample for believable default data.

```swift
import TMDb
import TMDbTesting

let movieService = MockMovieService()
movieService.detailsResult = .success(.sample)

let movie = try await movieService.details(forMovie: 550)
#expect(movieService.detailsCalls.first?.movieID == 550)

```

--------------------------------

### Build Discover/Browse Interface with Filters

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

Compose movie discovery filters fluently using builder methods. Supports combining genre, vote average, and release year criteria.

```swift
let filter = DiscoverMovieFilter()
    .withGenres([28, 12]) // Action AND Adventure
    .voteAverage(in: 7...10)
    .primaryReleaseYear(.on(2024))

let movies = try await tmdbClient.discover.movies(
    filter: filter,
    sortedBy: .popularity(descending: true)
)
```

--------------------------------

### Auto-Pagination: All Keywords

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/SearchService.md

Fetches all keyword results with auto-pagination, including the query.

```APIDOC
## allKeywords(query:)

### Description
Fetches all keyword results with auto-pagination, including the query.

### Parameters
#### Path Parameters
- **query** (String) - Required - The search query.
```

--------------------------------

### Configure TMDbClient with a Custom HTTP Client

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/GettingStarted/CreatingTMDbClient.md

Integrate a custom HTTP client, such as AsyncHTTPClient, by conforming to the HTTPClient protocol. This allows for advanced network task management.

```swift
class MyHTTPClient: HTTPClient {
    func perform(request: HTTPRequest) async throws -> HTTPResponse {
        // Implement performing a network request.
    }
}

let customHTTPClient = MyHTTPClient()

let tmdbClient = TMDbClient(
    apiKey: "<your-tmdb-api-key>",
    httpClient: customHTTPClient
)
```

--------------------------------

### Discover Popular TV Series

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/DiscoveringMoviesAndTVSeries.md

Use DiscoverService/tvSeries to browse TV series with similar filtering and sorting options as movies. This example discovers popular TV series sorted by popularity.

```swift
let tvSeries = try await tmdbClient.discover.tvSeries(
    sortedBy: .popularity(descending: true)
)

for series in tvSeries.results {
    print(series.name)
}
```

--------------------------------

### Filter Movies by Genre and Release Year

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/DiscoveringMoviesAndTVSeries.md

Use DiscoverMovieFilter to narrow down movie search results. This example filters for Action & Adventure movies released in the last year and sorts them by popularity.

```swift
// Action & Adventure movies from the last year
let currentYear = Calendar.current.component(.year, from: Date())
let filter = DiscoverMovieFilter(
    genres: [28, 12],
    primaryReleaseYear: .between(
        start: currentYear - 1,
        end: currentYear
    )
)

let actionMovies = try await tmdbClient.discover.movies(
    filter: filter,
    sortedBy: .popularity(descending: true)
)
```

--------------------------------

### Default In-Memory Cache Configuration

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/CachingResponses.md

Configure the TMDbClient with the default in-memory cache settings, which include a 1-hour time-to-live and a capacity for up to 100 entries.

```swift
let configuration = TMDbConfiguration(cache: .default)
let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>", configuration: configuration)
```

--------------------------------

### All Custom Lists (Auto-Pagination)

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/AccountService.md

Retrieves all custom lists created by the user, automatically handling pagination.

```APIDOC
## GET /account/{account_id}/lists

### Description
Retrieves all custom lists created by the user, automatically handling pagination.

### Method
GET

### Endpoint
/account/{account_id}/lists

### Parameters
#### Path Parameters
- **account_id** (integer) - Required - The ID of the account.
- **session** (string) - Required - The session ID for authentication.
```

--------------------------------

### Configure Custom Cache Behavior

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/GettingStarted/CreatingTMDbClient.md

Customize cache settings by defining the default time-to-live (TTL) and the maximum number of entries allowed in the cache.

```swift
let cacheConfig = CacheConfiguration(
    defaultTTL: .seconds(1800),    // 30-minute TTL
    maximumEntryCount: 200
)

let configuration = TMDbConfiguration(cache: cacheConfig)

let tmdbClient = TMDbClient(
    apiKey: "<your-tmdb-api-key>",
    configuration: configuration
)
```

--------------------------------

### List Paths in TMDB OpenAPI Spec

Source: https://github.com/adamayoung/tmdb/blob/main/knowledge/tmdb-api-notes.md

Use this `jq` command to list all available API paths defined in the TMDB OpenAPI JSON file. This is useful for understanding the API structure.

```bash
jq -r '.paths | keys[]' tmdb-openapi.json
```

--------------------------------

### Move Natural Language Search Sources

Source: https://github.com/adamayoung/tmdb/blob/main/plans/tmdb-intelligence-product-extraction.md

Relocate the Natural Language Search source files from TMDb to TMDbIntelligence using git mv to preserve history. Update imports to include TMDb.

```bash
git mv Sources/TMDb/Domain/Services/NaturalLanguageSearch/ Sources/TMDbIntelligence/NaturalLanguageSearch/

```

--------------------------------

### details(forNetwork:)

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/NetworkService.md

Fetches detailed information for a specific network.

```APIDOC
## details(forNetwork:)

### Description
Fetches detailed information for a specific network.

### Method
GET

### Endpoint
/network/{network_id}/details

### Parameters
#### Path Parameters
- **network_id** (int) - Required - The ID of the network to retrieve details for.

### Response
#### Success Response (200)
- **headquarters** (string) - The headquarters of the network.
- **homepage** (string) - The homepage URL of the network.
- **logo_path** (string) - The path to the network's logo.
- **name** (string) - The name of the network.
- **origin_country** (string) - The country of origin for the network.
```

--------------------------------

### Auto-Pagination: All Keywords Pages

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/SearchService.md

Fetches all keyword results with auto-pagination across pages, including the query.

```APIDOC
## allKeywordsPages(query:)

### Description
Fetches all keyword results with auto-pagination across pages, including the query.

### Parameters
#### Path Parameters
- **query** (String) - Required - The search query.
```

--------------------------------

### Custom HTTP Client with Configured URLCache

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/CachingResponses.md

Implement a custom `HTTPClient` to provide a `URLSession` with a specific `URLCache` configuration. This allows you to control memory and disk capacity or disable caching by setting `urlCache` to `nil`.

```swift
import Foundation
import TMDb

struct CustomHTTPClient: HTTPClient {

    private let urlSession: URLSession

    init() {
        let configuration = URLSessionConfiguration.default
        configuration.requestCachePolicy = .useProtocolCachePolicy
        // Resize the on-disk cache...
        configuration.urlCache = URLCache(memoryCapacity: 10_000_000, diskCapacity: 200_000_000)
        // ...or set `configuration.urlCache = nil` to disable HTTP caching.
        urlSession = URLSession(configuration: configuration)
    }

    func perform(request: HTTPRequest) async throws -> HTTPResponse {
        var urlRequest = URLRequest(url: request.url)
        urlRequest.httpMethod = request.method.rawValue
        urlRequest.httpBody = request.body
        for (field, value) in request.headers {
            urlRequest.setValue(value, forHTTPHeaderField: field)
        }

        let (data, response) = try await urlSession.data(for: urlRequest)
        let httpResponse = response as? HTTPURLResponse
        let statusCode = httpResponse?.statusCode ?? 0
        // Forward the headers so features like Retry-After backoff keep working.
        let headers = Dictionary(
            uniqueKeysWithValues: (httpResponse?.allHeaderFields ?? [:]).compactMap {
                key, value in (key as? String).map { ($0, "\(value)") }
            }
        )
        return HTTPResponse(statusCode: statusCode, data: data, headers: headers)
    }

}

let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>", httpClient: CustomHTTPClient())
```

--------------------------------

### Configure Custom Cache Settings

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

Customize the in-memory cache for the TMDb client by setting the default time-to-live (TTL) and the maximum number of entries.

```swift
// Custom cache configuration
let cacheConfig = CacheConfiguration(
    defaultTTL: .seconds(1800),    // 30-minute TTL
    maximumEntryCount: 200
)
let tmdbClient = TMDbClient(
    apiKey: "<your-api-key>",
    configuration: TMDbConfiguration(cache: cacheConfig)
)
```

--------------------------------

### Fetch Movie Details

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/FetchingMovieAndTVDetails.md

Use MovieService/details to retrieve comprehensive details for a specific movie. Requires an API key.

```swift
let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>")

let movie = try await tmdbClient.movies.details(forMovie: 550)
print("Title: \(movie.title)")
print("Release Date: \(movie.releaseDate?.formatted() ?? "Unknown")")
if let voteAverage = movie.voteAverage {
    print("Rating: \(voteAverage.formatted(.voteAveragePercentage))")
}
print("Overview: \(movie.overview ?? "No overview available")")
```

--------------------------------

### Auto-Pagination: All Collections

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/Extensions/SearchService.md

Fetches all collection results with auto-pagination, including optional language.

```APIDOC
## allCollections(query:language:)

### Description
Fetches all collection results with auto-pagination, including optional language.

### Parameters
#### Path Parameters
- **query** (String) - Required - The search query.
- **language** (String) - Optional - The language for the search results.
```

--------------------------------

### Feature Workflow Commands

Source: https://github.com/adamayoung/tmdb/blob/main/README.md

This outlines the sequence of commands used to build a feature end-to-end. Invoking /deliver is the plan-approval gate, and it runs autonomously to a ready-to-merge pull request.

```text
/plan                    ← you draft AND approve the plan
  │
  ▼  invoking /deliver = plan approval; it then runs autonomously:
  ├─ (feature branch)
  ├─ /review-plan        3 critics harden the plan (risky/large changes only)
  ├─ /implement-plan     Canon TDD → empty test list (unit + integration green)
  ├─ /review-changes     review + fix Critical/High (test-first; auto lite/full)
  ├─ /capture-knowledge  record learnings into knowledge/
  ├─ /pr reviewed        make ci gate → open the PR (red gate? triage, not stall)
  ├─ /watch-pr           resolve threads + fix checks    ── GATE: ready-to-merge
  └─ retrospective       append to knowledge/delivery-retros.md
```

--------------------------------

### Multi-Search Across Content Types

Source: https://github.com/adamayoung/tmdb/blob/main/Sources/TMDb/TMDb.docc/HowTos/SearchingForContent.md

Use `searchAll` to search for movies, TV series, and people in a single request. Iterate through the results and handle each item type accordingly.

```swift
let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>")

let results = try await tmdbClient.search.searchAll(
    query: "Breaking Bad"
)

for item in results.results {
    switch item {
    case let .movie(movie):
        print("Movie: \(movie.title)")
    case let .tvSeries(tvSeries):
        print("TV: \(tvSeries.name)")
    case let .person(person):
        print("Person: \(person.name)")
    }
}
```