runbeam_sdk/
lib.rs

1//! Runbeam SDK
2//!
3//! A Rust library for integrating with the Runbeam Cloud API.
4//!
5//! This SDK provides:
6//! - JWT token validation with RS256 and JWKS caching
7//! - Laravel Sanctum API token support
8//! - Runbeam Cloud API client for gateway authorization
9//! - Secure token storage via OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager)
10//! - Type definitions for API requests/responses and error handling
11//!
12//! # Authentication Methods
13//!
14//! The SDK supports two authentication methods:
15//!
16//! ## JWT Tokens (Legacy)
17//!
18//! JWT tokens with RS256 signature validation. The SDK performs local validation
19//! using public keys fetched from JWKS endpoints. Use this method when you need
20//! local token validation and claim extraction.
21//!
22//! ## Laravel Sanctum API Tokens
23//!
24//! Laravel Sanctum API tokens (format: `{id}|{token}`) are passed directly to the
25//! server for validation. Use this method for simpler authentication flows where
26//! local token validation is not required.
27//!
28//! # Example (JWT Authentication)
29//!
30//! ```no_run
31//! use runbeam_sdk::{
32//!     RunbeamClient,
33//!     validate_jwt_token,
34//!     save_token,
35//!     load_token,
36//!     MachineToken,
37//!     storage::{KeyringStorage, StorageBackend},
38//! };
39//!
40//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
41//! // Validate a user JWT token
42//! let claims = validate_jwt_token("eyJhbGci...", 24).await?;
43//!
44//! // Create API client from JWT issuer
45//! let client = RunbeamClient::new(claims.api_base_url());
46//!
47//! // Authorize a gateway and get machine token
48//! let response = client.authorize_gateway(
49//!     "eyJhbGci...",
50//!     "gateway-123",
51//!     None,
52//!     None
53//! ).await?;
54//!
55//! // Save machine token securely
56//! let storage = KeyringStorage::new("runbeam");
57//! let machine_token = MachineToken::new(
58//!     response.machine_token,
59//!     response.expires_at,
60//!     response.gateway.id,
61//!     response.gateway.code,
62//!     response.abilities,
63//! );
64//! save_token(&storage, &machine_token).await?;
65//! # Ok(())
66//! # }
67//! ```
68//!
69//! # Example (Sanctum Authentication)
70//!
71//! ```no_run
72//! use runbeam_sdk::{
73//!     RunbeamClient,
74//!     save_token,
75//!     MachineToken,
76//!     storage::{KeyringStorage, StorageBackend},
77//! };
78//!
79//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
80//! // Create API client with base URL
81//! let client = RunbeamClient::new("https://api.runbeam.io");
82//!
83//! // Authorize a gateway with Sanctum token (no validation needed)
84//! let response = client.authorize_gateway(
85//!     "1|abc123def456...",  // Sanctum API token
86//!     "gateway-123",
87//!     None,
88//!     None
89//! ).await?;
90//!
91//! // Save machine token securely
92//! let storage = KeyringStorage::new("runbeam");
93//! let machine_token = MachineToken::new(
94//!     response.machine_token,
95//!     response.expires_at,
96//!     response.gateway.id,
97//!     response.gateway.code,
98//!     response.abilities,
99//! );
100//! save_token(&storage, &machine_token).await?;
101//! # Ok(())
102//! # }
103//! ```
104
105pub mod runbeam_api;
106pub mod storage;
107
108// Re-export commonly used types and functions
109pub use runbeam_api::{
110    client::RunbeamClient,
111    jwt::{extract_bearer_token, validate_jwt_token, JwtClaims},
112    resources::{
113        AcknowledgeChangesRequest, Authentication, Backend, BaseUrlResponse, Change,
114        ChangeFailedRequest, Endpoint, Gateway, GatewayConfiguration, Middleware, Network,
115        PaginatedResponse, PaginationLinks, PaginationMeta, Pipeline, Policy, ResourceResponse,
116        Service, Transform,
117    },
118    token_storage::{clear_token, load_token, save_token, MachineToken},
119    types::{ApiError, AuthorizeResponse, GatewayInfo, RunbeamError, TeamInfo, UserInfo},
120};
runbeam_sdk/lib.rs

runbeam_sdk/
lib.rs
