leash_sdk/
lib.rs

1//! # leash-sdk
2//!
3//! Rust SDK for the [Leash](https://leash.build) platform — one unified async
4//! client for authentication, runtime env vars, and integrations.
5//!
6//! ## Quick start
7//!
8//! ```no_run
9//! use leash_sdk::{Leash, GmailListParams};
10//!
11//! # async fn example(req: http::Request<()>) -> leash_sdk::Result<()> {
12//! // Construct from any framework request (axum, actix-web, plain http::Request,
13//! // anything implementing `LeashRequest`).
14//! let leash = Leash::new(&req)?;
15//!
16//! // Identity
17//! let user = leash.auth().user().await?;
18//!
19//! // Runtime env vars (60s TTL cache, dedicated get_fresh for cache-bypass)
20//! let openai_key = leash.env().get("OPENAI_API_KEY").await?;
21//!
22//! // Integrations
23//! let msgs = leash.integrations().gmail().list_messages(GmailListParams {
24//!     max_results: Some(5),
25//!     ..Default::default()
26//! }).await?;
27//! # let _ = (user, openai_key, msgs);
28//! # Ok(()) }
29//! ```
30//!
31//! ## Constructors
32//!
33//! | Use case | Constructor |
34//! |---|---|
35//! | Request-bound (axum, actix, plain http::Request) | [`Leash::new`] |
36//! | Server-to-server | [`Leash::from_api_key`] |
37//! | CLI / agent with a user JWT | [`Leash::from_token`] |
38//!
39//! ## Auth precedence
40//!
41//! 1. `LEASH_API_KEY` env var (or [`Leash::with_api_key`])
42//! 2. `Authorization: Bearer <jwt>` header — used for identity and, when no
43//!    API key is configured, as a fallback for env-fetch. **Never** forwarded
44//!    on integration POSTs.
45//! 3. `leash-auth` cookie — forwarded to the platform for integration calls.
46//!
47//! ## Errors
48//!
49//! [`LeashError`] is a structured enum with convenience predicates:
50//!
51//! ```no_run
52//! # fn handle(err: leash_sdk::LeashError) {
53//! if err.is_plan_block() { /* show upgrade UI */ }
54//! if err.is_connection_required() { /* show "connect Gmail" CTA */ }
55//! if err.is_unauthorized() { /* re-auth */ }
56//! # }
57//! ```
58
59#![warn(missing_docs)]
60#![cfg_attr(docsrs, feature(doc_cfg))]
61
62mod auth;
63mod client;
64mod env;
65mod errors;
66pub mod integrations;
67mod request;
68mod transport;
69
70// ---------------------------------------------------------------------------
71// Public surface — kept flat so consumers can `use leash_sdk::{Leash, Result, ...}`
72// ---------------------------------------------------------------------------
73
74pub use auth::{decode_user, get_leash_user, is_authenticated, Auth, LeashUser, LEASH_AUTH_COOKIE};
75pub use client::{Leash, DEFAULT_PLATFORM_URL};
76pub use env::{Env, ENV_CACHE_TTL};
77pub use errors::{LeashError, Result};
78pub use integrations::{Calendar, Drive, Gmail, Integrations, Linear, Provider};
79pub use request::LeashRequest;
80
81// Re-export integration types at the crate root so callers can write
82// `use leash_sdk::GmailListParams;` instead of going through the submodule.
83pub use integrations::types::{
84    CalendarAttendee, CalendarCreateEventParams, CalendarEvent, CalendarEventList, CalendarList,
85    CalendarListEntry, CalendarListEventsParams, ConnectionStatus, DriveFile, DriveFileList,
86    DriveListFilesParams, DriveUploadFileParams, EventDateTime, GmailLabel, GmailLabelList,
87    GmailListParams, GmailMessage, GmailMessageFormat, GmailMessageList, GmailSendMessageParams,
88    Headers, LinearComment, LinearCreateIssueInput, LinearIssue, LinearListIssuesFilter,
89    LinearListIssuesResult, LinearListProjectsFilter, LinearProject, LinearStateRef, LinearTeam,
90    LinearTeamRef, LinearUpdateIssuePatch, LinearUserRef,
91};
92
93/// Convenience marker for callers who want to write
94/// `leash.env().get(key, EnvFresh)` style code — see [`Env::get_fresh`] for
95/// the actual cache-bypass entry point. Kept as a unit struct for parity with
96/// the brief and to give docs a single anchor.
97#[derive(Debug, Clone, Copy, Default)]
98pub struct EnvFresh;
leash_sdk/lib.rs

leash_sdk/
lib.rs
