cyberdrop_client/lib.rs
1//! Cyberdrop API client.
2//!
3//! This crate provides a small, async wrapper around a subset of Cyberdrop's HTTP API.
4//! It is built on [`reqwest`] and is intended to be copy-paste friendly in CLI tools and
5//! simple services.
6//!
7//! ## Quickstart
8//!
9//! Authenticate, then call endpoints that require a token:
10//!
11//! ```no_run
12//! use cyberdrop_client::CyberdropClient;
13//! use std::path::Path;
14//!
15//! # #[tokio::main]
16//! # async fn main() -> Result<(), cyberdrop_client::CyberdropError> {
17//! // 1) Create an unauthenticated client.
18//! let client = CyberdropClient::new()?;
19//!
20//! // 2) Exchange credentials for a token.
21//! let token = client.login("username", "password").await?;
22//!
23//! // 3) Use a cloned client that includes the token on authenticated requests.
24//! let authed = client.with_auth_token(token.into_string());
25//! let albums = authed.list_albums().await?;
26//! println!("albums: {}", albums.len());
27//!
28//! // 4) Create an album and upload a file into it.
29//! let album_id = authed
30//! .create_album("my uploads", Some("created by cyberdrop-client"))
31//! .await?;
32//! let uploaded = authed
33//! .upload_file(Path::new("path/to/file.jpg"), Some(album_id))
34//! .await?;
35//! println!("uploaded {} -> {}", uploaded.name, uploaded.url);
36//! # Ok(())
37//! # }
38//! ```
39//!
40//! Note: `upload_file` streams smaller files and reads larger files in chunks.
41//!
42//! ## Authentication
43//!
44//! Authenticated endpoints use an HTTP header named `token` (not an `Authorization: Bearer ...`
45//! header). Methods that *require* authentication return [`CyberdropError::MissingAuthToken`]
46//! if no token is configured.
47//!
48//! ## Timeouts, Retries, Polling
49//!
50//! - **Timeouts:** The client uses a single 30 second *request* timeout. Timeout failures surface
51//! as [`CyberdropError::Http`] (from `reqwest`).
52//! - **Retries:** This crate does not implement retries, backoff, or idempotency safeguards.
53//! If you need retries, add them at the call site.
54//! - **Polling:** This crate does not poll for eventual consistency. Methods return once the HTTP
55//! request/response completes.
56//!
57//! ## Error Model
58//!
59//! Higher-level API methods (for example, [`CyberdropClient::list_albums`]) treat non-2xx HTTP
60//! responses as errors:
61//! - `401`/`403` become [`CyberdropError::AuthenticationFailed`]
62//! - other non-2xx statuses become [`CyberdropError::RequestFailed`]
63//!
64//! External system failures are surfaced as:
65//! - [`CyberdropError::Io`] when reading local files (for example, in [`CyberdropClient::upload_file`])
66//! - [`CyberdropError::Http`] for network/transport failures (DNS, TLS, connection errors, timeouts)
67
68mod account;
69mod albums;
70mod client;
71mod config;
72mod error;
73mod files;
74mod token;
75mod uploads;
76
77pub use account::{Permissions, TokenVerification};
78pub use albums::{Album, AlbumFiles, EditAlbumResult};
79pub use client::CyberdropClient;
80pub use error::CyberdropError;
81pub use files::AlbumFile;
82pub use token::AuthToken;
83pub use uploads::{UploadProgress, UploadedFile};