sumup/
lib.rs

1//! # SumUp Rust SDK
2//!
3//! Official Rust SDK for the SumUp REST API.
4//!
5//! ## Quick Start
6//!
7//! ```no_run
8//! use sumup::Client;
9//!
10//! #[tokio::main]
11//! async fn main() {
12//!     // Create a client (reads SUMUP_API_KEY from environment)
13//!     let client = Client::default();
14//!
15//!     // Call an API endpoint
16//!     let checkouts = client
17//!         .checkouts()
18//!         .list(Default::default())
19//!         .await
20//!         .expect("list checkouts request failed");
21//!     println!("found {} checkouts", checkouts.len());
22//! }
23//! ```
24//!
25//! ## Configuration
26//!
27//! ### Authentication
28//!
29//! Set your API key via environment variable or explicitly:
30//!
31//! ```no_run
32//! # use sumup::{Authorization, Client};
33//! // From environment variable SUMUP_API_KEY
34//! let client = Client::default();
35//!
36//! // Explicit token
37//! let client = Client::default()
38//!     .with_authorization(Authorization::api_key("your_api_key"));
39//! ```
40//!
41//! ### Custom Configuration
42//!
43//! ```no_run
44//! # use sumup::{Authorization, Client};
45//! use std::time::Duration;
46//!
47//! let client = Client::default()
48//!     .with_authorization(Authorization::api_key("your_api_key"))
49//!     .with_timeout(Duration::from_secs(30));
50//! ```
51//!
52//! ## Making API Calls
53//!
54//! The SDK organizes endpoints by tags:
55//!
56//! ```no_run
57//! # use sumup::{Client, Currency, checkouts};
58//! # async fn example(client: Client) {
59//! // Create a checkout
60//! let checkout = client.checkouts().create(checkouts::CheckoutCreateRequest {
61//!     checkout_reference: "unique-ref".to_string(),
62//!     amount: 10.0,
63//!     currency: Currency::EUR,
64//!     merchant_code: "MCODE".to_string(),
65//!     description: None,
66//!     return_url: None,
67//!     customer_id: None,
68//!     purpose: None,
69//!     valid_until: None,
70//!     redirect_url: None,
71//! })
72//! .await
73//! .expect("create checkout");
74//! println!("created checkout {}", checkout.id.unwrap_or_default());
75//!
76//! // Transactions with query parameters
77//! use sumup::resources::transactions::ListParams;
78//! let transactions = client
79//!     .transactions()
80//!     .list(
81//!         "MERCHANT_CODE",
82//!         ListParams {
83//!             limit: Some(10),
84//!             ..Default::default()
85//!         },
86//!     )
87//!     .await
88//!     .expect("list transactions");
89//! let count = transactions.items.as_ref().map_or(0, |items| items.len());
90//! println!("fetched {} historical transactions", count);
91//! # }
92//! ```
93//!
94//! ## DateTime Support
95//!
96//! The SDK supports both [`chrono`](https://docs.rs/chrono) (default) and
97//! [`jiff`](https://docs.rs/jiff) for datetime types:
98//!
99//! ```toml
100//! # Use chrono (default)
101//! [dependencies]
102//! sumup = "0.0.1"
103//!
104//! # Use jiff instead
105//! [dependencies]
106//! sumup = { version = "0.0.1", default-features = false, features = ["jiff"] }
107//! ```
108//!
109//! ## Error Handling
110//!
111//! All SDK calls return a [`SdkResult`] whose error side is a [`SdkError`]. When the
112//! SumUp API responds with a non-success status, the SDK builds an
113//! `SdkError::Api` containing an endpoint-specific payload (e.g. a `Unauthorized`
114//! enum variant). Any undocumented status codes fall back to
115//! `SdkError::Unexpected`, which preserves the HTTP status and best-effort body
116//! parsing. You can inspect failures like this:
117//!
118//! ```no_run
119//! # use sumup::{Client, error::SdkError};
120//! # use sumup::resources::checkouts::ListErrorBody;
121//! # async fn example() {
122//! let client = Client::default();
123//! match client.checkouts().list(Default::default()).await {
124//!     Ok(checkouts) => println!("retrieved {} checkouts", checkouts.len()),
125//!     Err(SdkError::Api(body)) => match body {
126//!         ListErrorBody::Unauthorized(details) => eprintln!("unauthorized: {:?}", details),
127//!     },
128//!     Err(SdkError::Unexpected(status, body)) => {
129//!         eprintln!("unexpected {} response: {}", status, body);
130//!     }
131//!     Err(SdkError::Network(err)) => panic!("network error: {}", err),
132//! }
133//! # }
134//! ```
135//!
136//! ## Features
137//!
138//! - **chrono** (default): Use chrono for datetime types
139//! - **jiff**: Use jiff for datetime types (mutually exclusive with chrono)
140//!
141//! ## Resources
142//!
143//! - [API Documentation](https://developer.sumup.com/docs/)
144//! - [GitHub Repository](https://github.com/sumup/sumup-rs)
145
146#![forbid(unsafe_code)]
147
148mod string_or_number;
149
150pub mod api_version;
151pub mod auth;
152pub mod client;
153pub mod datetime;
154pub mod error;
155pub mod nullable;
156pub mod secret;
157pub mod version;
158
159#[allow(deprecated)]
160#[allow(clippy::large_enum_variant)]
161pub mod resources;
162
163pub use crate::resources::*;
164pub use auth::Authorization;
165pub use client::Client;
166pub use error::{SdkError, SdkResult, UnknownApiBody};
167pub use nullable::Nullable;
168pub use secret::Secret;
169pub use version::VERSION;
sumup/lib.rs

sumup/
lib.rs
