cameo 0.1.0

Unified movie/TV show database SDK for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192

#![allow(async_fn_in_trait)]

use super::models::{
    UnifiedEpisode, UnifiedMovie, UnifiedMovieDetails, UnifiedPerson, UnifiedPersonDetails,
    UnifiedSearchResult, UnifiedSeasonDetails, UnifiedTvShow, UnifiedTvShowDetails,
    UnifiedWatchProviders,
};
use crate::core::pagination::PaginatedResponse;

/// Provider that can search for movies, TV shows, and people.
pub trait SearchProvider {
    /// The error type returned by this provider.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Search for movies by title.
    async fn search_movies(
        &self,
        query: &str,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedMovie>, Self::Error>;

    /// Search for TV shows by name.
    async fn search_tv_shows(
        &self,
        query: &str,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedTvShow>, Self::Error>;

    /// Search for people by name.
    async fn search_people(
        &self,
        query: &str,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedPerson>, Self::Error>;

    /// Multi-search across movies, TV shows, and people.
    async fn search_multi(
        &self,
        query: &str,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedSearchResult>, Self::Error>;
}

/// Provider that can fetch detailed information about individual items.
pub trait DetailProvider {
    /// The error type returned by this provider.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Get detailed information about a movie by provider-specific ID.
    async fn movie_details(&self, id: i32) -> Result<UnifiedMovieDetails, Self::Error>;

    /// Get detailed information about a TV show by provider-specific ID.
    async fn tv_show_details(&self, id: i32) -> Result<UnifiedTvShowDetails, Self::Error>;

    /// Get detailed information about a person by provider-specific ID.
    async fn person_details(&self, id: i32) -> Result<UnifiedPersonDetails, Self::Error>;
}

/// Provider that can discover trending and popular content.
pub trait DiscoveryProvider {
    /// The error type returned by this provider.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Get trending movies.
    async fn trending_movies(
        &self,
        time_window: crate::core::config::TimeWindow,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedMovie>, Self::Error>;

    /// Get trending TV shows.
    async fn trending_tv_shows(
        &self,
        time_window: crate::core::config::TimeWindow,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedTvShow>, Self::Error>;

    /// Get popular movies.
    async fn popular_movies(
        &self,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedMovie>, Self::Error>;

    /// Get top-rated movies.
    async fn top_rated_movies(
        &self,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedMovie>, Self::Error>;

    /// Get popular TV shows.
    async fn popular_tv_shows(
        &self,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedTvShow>, Self::Error>;

    /// Get top-rated TV shows.
    async fn top_rated_tv_shows(
        &self,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedTvShow>, Self::Error>;
}

/// Provider that can fetch recommendations and similar content.
///
/// # Provider support
///
/// Not all providers implement this trait. When a [`crate::unified::CameoClient`] is
/// configured without any provider that supports recommendations, calls will return
/// [`crate::unified::CameoClientError::NoProviders`].
pub trait RecommendationProvider {
    /// The error type returned by this provider.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Get movie recommendations based on a movie.
    async fn movie_recommendations(
        &self,
        id: i32,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedMovie>, Self::Error>;

    /// Get TV show recommendations based on a TV show.
    async fn tv_recommendations(
        &self,
        id: i32,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedTvShow>, Self::Error>;

    /// Get movies similar to a given movie.
    async fn similar_movies(
        &self,
        id: i32,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedMovie>, Self::Error>;

    /// Get TV shows similar to a given TV show.
    async fn similar_tv_shows(
        &self,
        id: i32,
        page: Option<u32>,
    ) -> Result<PaginatedResponse<UnifiedTvShow>, Self::Error>;
}

/// Provider that can fetch season and episode details.
///
/// # Provider support
///
/// Not all providers implement this trait. When a [`crate::unified::CameoClient`] is
/// configured without any provider that supports season/episode data, calls will return
/// [`crate::unified::CameoClientError::NoProviders`].
pub trait SeasonProvider {
    /// The error type returned by this provider.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Get details for a specific season of a TV show.
    async fn season_details(
        &self,
        show_id: i32,
        season_number: u32,
    ) -> Result<UnifiedSeasonDetails, Self::Error>;

    /// Get details for a specific episode of a TV show.
    async fn episode_details(
        &self,
        show_id: i32,
        season_number: u32,
        episode_number: u32,
    ) -> Result<UnifiedEpisode, Self::Error>;
}

/// Provider that can fetch streaming availability.
///
/// # Provider support
///
/// Not all providers implement this trait. When a [`crate::unified::CameoClient`] is
/// configured without any provider that supports watch provider data, calls will return
/// [`crate::unified::CameoClientError::NoProviders`].
pub trait WatchProviderTrait {
    /// The error type returned by this provider.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Get streaming providers for a movie.
    async fn movie_watch_providers(&self, id: i32) -> Result<UnifiedWatchProviders, Self::Error>;

    /// Get streaming providers for a TV show.
    async fn tv_watch_providers(&self, id: i32) -> Result<UnifiedWatchProviders, Self::Error>;
}

/// A provider that supports search, detail, and discovery operations.
pub trait MediaProvider: SearchProvider + DetailProvider + DiscoveryProvider {}

/// Blanket implementation: anything that implements all three traits is a `MediaProvider`.
impl<T> MediaProvider for T where T: SearchProvider + DetailProvider + DiscoveryProvider {}