golib/tmdb/README.md

# TMDB - v0.9.2

A Go client library for The Movie Database (TMDB) API with automatic rate limiting, retry logic, and convenient helper functions.

## Features

- Clean interface for TMDB's REST API
- Automatic rate limiting with exponential backoff
- Retry logic for rate limit errors (respects Retry-After header)
- Movie search functionality
- Movie details retrieval
- Cast and crew information
- Image URL helpers
- Environment variable configuration with ConfigFromEnv
- EZConf integration for unified configuration
- Comprehensive test coverage (94.1%)

## Installation

```bash
go get git.haelnorr.com/h/golib/tmdb
```

## Quick Start

### Basic Usage

```go
package main

import (
    "fmt"
    "log"
    "git.haelnorr.com/h/golib/tmdb"
)

func main() {
    // Create API connection
    api, err := tmdb.NewAPIConnection()
    if err != nil {
        log.Fatal(err)
    }

    // Search for a movie
    results, err := api.SearchMovies("Fight Club", false, 1)
    if err != nil {
        log.Fatal(err)
    }

    for _, movie := range results.Results {
        fmt.Printf("%s (%s)\n", movie.Title, movie.ReleaseYear())
        fmt.Printf("Poster: %s\n", movie.GetPoster(&api.Image, "w500"))
    }
}
```

### Getting Movie Details

```go
// Get detailed information about a movie
movie, err := api.GetMovie(550) // Fight Club
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Title: %s\n", movie.Title)
fmt.Printf("Overview: %s\n", movie.Overview)
fmt.Printf("Release Date: %s\n", movie.ReleaseDate)
fmt.Printf("IMDb ID: %s\n", movie.IMDbID)
fmt.Printf("Rating: %.1f/10\n", movie.VoteAverage)
```

### Getting Cast and Crew

```go
// Get credits for a movie
credits, err := api.GetCredits(550)
if err != nil {
    log.Fatal(err)
}

fmt.Println("Cast:")
for _, actor := range credits.Cast {
    fmt.Printf("  %s as %s\n", actor.Name, actor.Character)
}

fmt.Println("\nDirector:")
for _, member := range credits.Crew {
    if member.Job == "Director" {
        fmt.Printf("  %s\n", member.Name)
    }
}
```

## Configuration

### Environment Variables

The package requires the following environment variable:

```bash
# TMDB API access token (required)
TMDB_TOKEN=your_api_token_here
```

Get your API token from: https://www.themoviedb.org/settings/api

### Using EZConf Integration

```go
import (
    "git.haelnorr.com/h/golib/ezconf"
    "git.haelnorr.com/h/golib/tmdb"
)

loader := ezconf.New()
loader.RegisterIntegration(tmdb.NewEZConfIntegration())
loader.Load()

// Get the configured API connection
api, ok := loader.GetConfig("tmdb")
if !ok {
    log.Fatal("tmdb config not found")
}
```

## Rate Limiting

TMDB has rate limits around 40 requests per second. This package implements automatic retry logic with exponential backoff:

- **Initial backoff**: 1 second
- **Exponential growth**: 1s → 2s → 4s → 8s → 16s → 32s (max)
- **Maximum retries**: 3 attempts
- **Respects** Retry-After header when provided by the API

All API calls automatically handle rate limiting, so you don't need to worry about it.

## Image URLs

The TMDB API provides base URLs for images. Use helper methods to construct full image URLs:

```go
// Available poster sizes: "w92", "w154", "w185", "w342", "w500", "w780", "original"
posterURL := movie.GetPoster(&api.Image, "w500")

// Available backdrop sizes: "w300", "w780", "w1280", "original"
backdropURL := movie.GetBackdrop(&api.Image, "w1280")

// Available profile sizes: "w45", "w185", "h632", "original"
profileURL := actor.GetProfile(&api.Image, "w185")
```

## API Reference

### Main Functions

- `NewAPIConnection() (*APIConnection, error)` - Create a new API connection
- `SearchMovies(query string, includeAdult bool, page int) (*SearchResponse, error)` - Search for movies
- `GetMovie(movieID int) (*Movie, error)` - Get detailed movie information
- `GetCredits(movieID int) (*Credits, error)` - Get cast and crew information

### Helper Methods

**Movie Methods:**
- `ReleaseYear() string` - Extract year from release date
- `GetPoster(imgConfig *ImageConfig, size string) string` - Get full poster URL
- `GetBackdrop(imgConfig *ImageConfig, size string) string` - Get full backdrop URL

**Cast/Crew Methods:**
- `GetProfile(imgConfig *ImageConfig, size string) string` - Get full profile image URL

## Error Handling

The package returns wrapped errors for easy debugging:

```go
data, err := api.SearchMovies("Inception", false, 1)
if err != nil {
    if strings.Contains(err.Error(), "rate limit exceeded") {
        // Handle rate limiting
    } else if strings.Contains(err.Error(), "unexpected status code: 401") {
        // Invalid API token
    } else if strings.Contains(err.Error(), "unexpected status code: 404") {
        // Resource not found
    } else {
        // Network or other errors
    }
}
```

## Documentation

For detailed documentation, see the [TMDB Wiki](https://git.haelnorr.com/h/golib/wiki/TMDB.md).

Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/tmdb).

## Testing

Run the test suite (requires a valid TMDB_TOKEN environment variable):

```bash
export TMDB_TOKEN=your_api_token_here
go test -v ./...
```

Current test coverage: 94.1%

## Best Practices

1. **Reuse API connections** - Create one connection and reuse it for multiple requests
2. **Cache responses** - Cache API responses when appropriate to reduce API calls
3. **Use specific image sizes** - Use appropriate image sizes instead of "original" to save bandwidth
4. **Handle rate limits gracefully** - The library handles this automatically, but be aware it may introduce delays
5. **Set a timeout** - Consider using context with timeout for long-running operations

## Example Projects

Check out these projects using the TMDB library:

- [Project ReShoot](https://git.haelnorr.com/h/reshoot) - Movie database application

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Related Projects

- [ezconf](https://git.haelnorr.com/h/golib/ezconf) - Unified configuration management
- [hlog](https://git.haelnorr.com/h/golib/hlog) - Structured logging with zerolog

## External Resources

- [TMDB API Documentation](https://developer.themoviedb.org/docs)
- [Get API Token](https://www.themoviedb.org/settings/api)
- [TMDB Website](https://www.themoviedb.org/)