whmcs 0.1.1

Rust client for the WHMCS API
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

#![deny(missing_docs)]
#![deny(missing_debug_implementations)]
#![cfg_attr(not(test), warn(unused_crate_dependencies))]
#![cfg_attr(test, deny(warnings))]
#![warn(clippy::pedantic)]
#![warn(clippy::cargo)]
#![warn(clippy::nursery)]
#![allow(clippy::multiple_crate_versions)]

//! # whmcs
//!
//! Async HTTP client for the [WHMCS][whmcs-api] remote API (`includes/api.php`).
//! It sends `application/x-www-form-urlencoded` bodies, asks WHMCS for JSON
//! (`responsetype=json`), and maps the envelope `result: success | error` to `Result<T, WhmcsError>`
//! ([`WhmcsError`]).
//!
//! Typical use looks like this:
//!
//! - Build a [`WhmcsClient`] (usually with [`WhmcsBuilder`] when the **`builder`** feature is enabled, which is the default).
//! - Call typed helpers such as [`WhmcsClient::get_clients`], or the generic [`WhmcsClient::request`] for any WHMCS action.
//! - Use types from [`models`] for request parameters and deserialized responses.
//!
//! ## Quick start
//!
//! ```no_run
//! use whmcs::{WhmcsBuilder, WhmcsError};
//! use whmcs::models::clients::{GetClientParams, GetClientsResponse};
//!
//! async fn example() -> Result<(), WhmcsError> {
//!     let client = WhmcsBuilder::new()
//!         .url("https://billing.example.com/includes/api.php")
//!         .api_identifier("your-api-identifier")
//!         .api_secret("your-api-secret")
//!         .timeout(30_u64)
//!         .build()?;
//!
//!     let list: GetClientsResponse = client
//!         .get_clients(GetClientParams::default().search("user@example.com"))
//!         .await?;
//!
//!     println!("total matches: {}", list.total_results);
//!     Ok(())
//! }
//! ```
//!
//! ## Building a client
//!
//! With the default **`builder`** feature, use [`WhmcsBuilder`] to set the API URL, credentials,
//! and optional timeout, then call [`WhmcsBuilder::build`]. Any field you omit on the builder is
//! filled from environment variables when `build` runs:
//!
//! | Builder field | Environment variable |
//! |---------------|------------------------|
//! | URL | `WHMCS_URL` |
//! | Identifier | `WHMCS_API_IDENTIFIER` |
//! | Secret | `WHMCS_API_SECRET` |
//! | Timeout (seconds) | `WHMCS_TIMEOUT` (falls back to `30`) |
//!
//! If the URL path does not end with `api.php`, the builder normalizes it so requests target
//! `.../includes/api.php` under your WHMCS base path.
//!
//! With **`default-features = false`** (disabling **`builder`**), construct [`WhmcsClient`] with
//! [`WhmcsClient::new`] and supply URL and secrets yourself.
//!
//! ## Requests and responses
//!
//! - **Typed helpers** — Methods on [`WhmcsClient`] (implemented in this crate’s `resources`
//!   modules) call [`WhmcsClient::request`] with the correct WHMCS `action` name and serde types.
//! - **Generic access** — [`WhmcsClient::request`] accepts any `P` that implements `serde::Serialize`
//!   into a JSON **object** (flat key/value pairs), and any success body type `T` that implements
//!   `serde::de::DeserializeOwned` for the payload after the `result` field is handled by [`WhmcsRawResponse`].
//!
//! WHMCS often encodes booleans and nested lists in non-standard ways; this crate uses custom
//! deserializers in [`models`] where needed.
//!
//! ## Errors
//!
//! See [`WhmcsError`] for request, JSON, and WHMCS-level failures. Configuration problems when
//! using the builder are reported as [`BuilderError`].
//!
//! ## Cargo features
//!
//! | Feature | Default | Description |
//! |---------|---------|-------------|
//! | **`builder`** | yes | [`WhmcsBuilder`], [`BuilderError`], and `BuilderError` inside [`WhmcsError`]. |
//!
//! ## Further reading
//!
//! - [WHMCS API index][whmcs-api] — official action names, parameters, and behaviour.
//!
//! [whmcs-api]: https://developers.whmcs.com/api/

pub mod models;

#[cfg(feature = "builder")]
mod builder;
mod client;
mod error;
mod resources;
#[cfg(test)]
mod test;

#[cfg(feature = "builder")]
pub use crate::{builder::WhmcsBuilder, error::BuilderError};
pub use client::WhmcsClient;
pub use error::WhmcsError;
pub use models::{WhmcsRawResponse, WhmcsSorting};