squarecloud/lib.rs
1#![warn(missing_docs)]
2//! Async Rust client for the [SquareCloud](https://squarecloud.app) API.
3//!
4//! # Overview
5//!
6//! This crate provides typed, async access to every endpoint exposed by the
7//! SquareCloud platform: deploying and managing applications, provisioning
8//! databases, organising workspaces, and inspecting account information.
9//!
10//! The main entry point is [`ApiClient`]. It reads the `API_TOKEN`
11//! environment variable (or a `.env` file) on first use, so no explicit
12//! configuration struct is needed.
13//!
14//! # Quick start
15//!
16//! ```no_run
17//! use squarecloud::ApiClient;
18//!
19//! #[tokio::main]
20//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
21//! let client = ApiClient::new();
22//!
23//! // Fetch your account information.
24//! let me = client.me().await?;
25//! println!("Logged in as {} ({})", me.user.name, me.user.email);
26//!
27//! // Inspect a running application.
28//! // Note: `app()` consumes the client, so call account-level
29//! // methods first.
30//! let status = client.app("your-app-id").status().await?;
31//! println!("CPU: {} RAM: {}", status.cpu, status.ram);
32//!
33//! Ok(())
34//! }
35//! ```
36//!
37//! # Crate layout
38//!
39//! | Item | Purpose |
40//! |------|---------|
41//! | [`ApiClient`] | Root entry point; construct with [`ApiClient::new`]. |
42//! | [`resources`] | Resource handles returned by the factory methods on `ApiClient`. |
43//! | [`types`] | Plain data structs deserialised from API responses. |
44//! | [`ApiError`] / [`ApiErrorCode`] | Errors returned by every API call. |
45//! | [`CommitError`] | Error type specific to [`resources::AppResource::commit`]. |
46//!
47//! # Environment variables
48//!
49//! | Variable | Description |
50//! |----------|-------------|
51//! | `API_TOKEN` | Your SquareCloud API key. |
52//!
53//! Read at first use via [`dotenvy`](https://docs.rs/dotenvy), so a `.env`
54//! file in the working directory is supported automatically.
55
56mod http;
57/// Resource handles returned by the factory methods on [`ApiClient`].
58pub mod resources;
59mod settings;
60/// Plain data structs deserialised from API responses.
61pub mod types;
62
63pub(crate) use http::endpoints::Endpoint;
64#[cfg(feature = "test-utils")]
65pub use http::endpoints::EndpointSpec;
66pub use http::errors::{ApiError, ApiErrorCode, CommitError};
67pub use http::http_client::ApiClient;
68pub use types::{CredentialType, DatabaseType, RealtimeEvent, SnapshotScope};
69
70#[cfg(test)]
71mod tests {
72 // use super::*;
73}