Expand description
§Podbean an async Podbean client for connecting to the Podbean API.
§Podbean API Client
A fully async Rust client for the Podbean API, built with Tokio and Reqwest.
§Features
- Fully async: Built on Tokio runtime and Reqwest for efficient HTTP requests
- OAuth2 support: Handles authentication, token refresh, and authorization flows
- Rate limiting: Built-in rate limiting to avoid hitting API limits
- Comprehensive API coverage: Supports podcasts, episodes, media files, and more
- Proper error handling: Custom error types with detailed information
- Type-safe: Strongly typed API responses with Serde
§Installation
Add the following to your Cargo.toml
:
[dependencies]
podbean = "0.2.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
§Quick Start
use podbean::PodbeanClient;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create a new client with your credentials
let mut client = PodbeanClient::new("your_client_id", "your_client_secret").unwrap();
// Generate authorization URL for the user to visit
let auth_url = client.get_authorization_url(
"https://your-app.com/callback",
Some("state_for_csrf_protection")
)?;
println!("Please visit: {}", auth_url);
// After user authorization, exchange the code for a token
client.authorize("authorization_code_from_callback", "https://your-app.com/callback").await?;
// Now you can use the API
let podcasts = client.list_podcasts(None, Some(10)).await?;
println!("You have {} podcasts", podcasts.count);
Ok(())
}
§Examples
§Uploading and Publishing a Podcast Episode
use podbean::{PodbeanClient, EpisodeStatus, EpisodeType, MediaFormat};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create a new client with your credentials
let mut client = PodbeanClient::new("your_client_id", "your_client_secret").unwrap();
// Upload an audio file
let media_key = client.upload_media("episode.mp3".to_string(), vec![], MediaFormat::Mp3).await?;
// Publish a new episode
let episode_id = client.publish_episode(
"your_podcast_id",
"Episode Title",
"Episode description and show notes...",
&media_key,
EpisodeStatus::Draft,
EpisodeType::Public,
None, // Publish immediately
).await?;
println!("Published new episode with ID: {}", episode_id);
Ok(())
}
§Managing Episodes
use podbean::PodbeanClient;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Create a new client with your credentials
let mut client = PodbeanClient::new("your_client_id", "your_client_secret").unwrap();
// List episodes
let episodes = client.list_episodes(Some("your_podcast_id"), None, Some(20)).await?;
println!("Found {} episodes", episodes.count);
// Get a specific episode
let episode = client.get_episode("episode_id").await?;
println!("Episode: {} (URL: {})", episode.title, episode.player_url);
// Update an episode
client.update_episode(
"episode_id",
Some("Updated Title"),
Some("Updated description"),
None, // Keep current status
None, // Keep current publish time
).await?;
// Delete an episode
client.delete_episode("episode_id").await?;
Ok(())
}
§API Reference
§Authentication
PodbeanClient::new(client_id, client_secret)
- Create a new clientclient.get_authorization_url(redirect_uri, state)
- Generate OAuth authorization URLclient.authorize(code, redirect_uri)
- Exchange authorization code for tokenclient.refresh_token()
- Refresh the access token when expired
§Podcasts
client.list_podcasts(offset, limit)
- List podcasts for the authenticated user
§Episodes
client.list_episodes(podcast_id, offset, limit)
- List episodesclient.get_episode(episode_id)
- Get a specific episodeclient.publish_episode(podcast_id, title, content, media_key, EpisodeStatus::Draft, EpisodeType::Public, publish_timestamp)
- Publish a new episodeclient.update_episode(episode_id, title, content, status, publish_timestamp)
- Update an episodeclient.delete_episode(episode_id)
- Delete an episode
§Media Files
client.upload_media(file_name, file_bytes, content_type)
- Upload a media fileclient.list_media(offset, limit)
- List media files
§Error Handling
The library uses a custom PodbeanError
type that provides detailed information about what went wrong:
§License
MIT
§Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Structs§
- Episode
- Represents a podcast episode. https://developers.podbean.com/podbean-api-docs/#EpisodeObject
- Episode
List Response - Response for a list of episodes.
- Media
Item - Represents a media item in Podbean.
- Media
List Response - Response for a list of media items.
- Podbean
Client - A client for interacting with the Podbean API.
- Podcast
List Response - Response for a list of podcasts.
- Token
Response - Response from OAuth token endpoint.
Enums§
- Episode
Status - Episode status
- Episode
Type - Represents a episode type.
- Media
Format - Audio format for media files.
- Podbean
Error - Possible errors that can occur when using the Podbean API client.
Type Aliases§
- Podbean
Result - Result type for Podbean API operations.