use std::time::{Duration, Instant};
use rand::Rng;
use reqwest::{header, Method, RequestBuilder, StatusCode};
use serde::de::DeserializeOwned;
use serde::Deserialize;
use crate::error::{Error, Result};
use crate::stream::EventStream;
use crate::types::{
AnswerInput, Balance, CreateIntent, CreateProfile, CreateSession, CreateTopup, Customer, CustomerList,
CustomerParams, EventList, Intent, IntentList, IntentStatus, ListCustomers, ListEvents, ListIntents, ListProfiles,
ListSessions, Profile, ProfileLease, ProfileList, Session, SessionCommand, SessionCommandResult, SessionList,
Topup,
};
use crate::types_v1::{
CreatePortalSession, CreateSecret, CreateSecretRequest, CreateSignIn, CreateWebhookEndpoint, ListSecrets, LiveLink,
Page, PortalSession, RateLimit, Secret, SecretList, SecretRequest, SecretRequestCreated, SecretUseList, SignIn,
UpdateWebhookEndpoint, WebhookDelivery, WebhookDeliveryList, WebhookEndpoint, WebhookEndpointList,
};
pub const DEFAULT_BASE_URL: &str = "https://api.openintents.io/v1";
const VERSION: &str = env!("CARGO_PKG_VERSION");
const MAX_HOLD_SECS: u32 = 50;
const STREAM_IDLE_TIMEOUT: Duration = Duration::from_secs(60);
#[derive(Debug, Clone)]
pub struct Client {
http: reqwest::Client,
api_key: String,
base_url: String,
timeout: Duration,
pub(crate) max_retries: u32,
}
#[derive(Debug, Clone, Copy)]
pub struct WaitOptions {
pub timeout: Duration,
pub interval: Duration,
pub return_on_payment: bool,
pub return_on_sign_in: bool,
pub return_on_input: bool,
}
impl Default for WaitOptions {
fn default() -> Self {
Self {
timeout: Duration::from_secs(300),
interval: Duration::from_secs(2),
return_on_payment: true,
return_on_sign_in: true,
return_on_input: true,
}
}
}
#[derive(Deserialize)]
struct ErrorBody {
error: Option<ErrorDetail>,
}
#[derive(Deserialize)]
struct ErrorDetail {
#[serde(rename = "type")]
kind: Option<String>,
code: Option<String>,
message: Option<String>,
param: Option<String>,
lease: Option<ProfileLease>,
}
impl Client {
pub fn new(api_key: impl Into<String>) -> Self {
Self::builder(api_key).build()
}
pub fn from_env() -> Result<Self> {
let key = std::env::var("OPENINTENTS_API_KEY")
.ok()
.filter(|k| !k.trim().is_empty())
.ok_or(Error::MissingApiKey)?;
let mut builder = Self::builder(key);
if let Ok(url) = std::env::var("OPENINTENTS_BASE_URL") {
builder = builder.base_url(url);
}
Ok(builder.build())
}
pub fn builder(api_key: impl Into<String>) -> ClientBuilder {
ClientBuilder {
api_key: api_key.into(),
base_url: DEFAULT_BASE_URL.to_string(),
timeout: Duration::from_secs(30),
max_retries: 2,
}
}
pub async fn create_intent(&self, params: CreateIntent) -> Result<Intent> {
self.create_intent_idempotent(params, &uuid::Uuid::new_v4().to_string())
.await
}
pub async fn create_intent_idempotent(&self, params: CreateIntent, idempotency_key: &str) -> Result<Intent> {
self.send(Method::POST, "/intents", Some(idempotency_key), |r| r.json(¶ms))
.await
}
pub async fn get_intent(&self, id: &str) -> Result<Intent> {
self.send(Method::GET, &format!("/intents/{id}"), None, |r| r).await
}
pub async fn create_intent_waiting(&self, params: CreateIntent, wait_secs: u32) -> Result<Intent> {
let key = uuid::Uuid::new_v4().to_string();
self.send(Method::POST, "/intents", Some(&key), |r| {
self.hold(r, wait_secs).json(¶ms)
})
.await
}
pub async fn get_intent_waiting(&self, id: &str, wait_secs: u32) -> Result<Intent> {
self.send(Method::GET, &format!("/intents/{id}"), None, |r| {
self.hold(r, wait_secs)
})
.await
}
pub async fn list_intents(&self, params: &ListIntents) -> Result<IntentList> {
self.send(Method::GET, "/intents", None, |r| r.query(params)).await
}
pub async fn cancel_intent(&self, id: &str) -> Result<Intent> {
let key = uuid::Uuid::new_v4().to_string();
self.send(Method::POST, &format!("/intents/{id}/cancel"), Some(&key), |r| r)
.await
}
pub async fn answer_intent_input(&self, id: &str, answer: AnswerInput) -> Result<Intent> {
let key = uuid::Uuid::new_v4().to_string();
self.send(Method::POST, &format!("/intents/{id}/input"), Some(&key), |r| {
r.json(&answer)
})
.await
}
pub async fn balance(&self) -> Result<Balance> {
self.send(Method::GET, "/balance", None, |r| r).await
}
pub async fn balance_for(&self, customer: &str) -> Result<Balance> {
self.send(Method::GET, "/balance", None, |r| r.query(&[("customer", customer)]))
.await
}
pub async fn create_customer(&self, params: CustomerParams) -> Result<Customer> {
self.create_customer_idempotent(params, &uuid::Uuid::new_v4().to_string())
.await
}
pub async fn create_customer_idempotent(&self, params: CustomerParams, idempotency_key: &str) -> Result<Customer> {
self.send(Method::POST, "/customers", Some(idempotency_key), |r| r.json(¶ms))
.await
}
pub async fn get_customer(&self, id: &str) -> Result<Customer> {
self.send(Method::GET, &format!("/customers/{id}"), None, |r| r).await
}
pub async fn update_customer(&self, id: &str, params: CustomerParams) -> Result<Customer> {
self.send(Method::PATCH, &format!("/customers/{id}"), None, |r| r.json(¶ms))
.await
}
pub async fn list_customers(&self, params: &ListCustomers) -> Result<CustomerList> {
self.send(Method::GET, "/customers", None, |r| r.query(params)).await
}
pub async fn create_topup(&self, params: CreateTopup) -> Result<Topup> {
self.create_topup_idempotent(params, &uuid::Uuid::new_v4().to_string())
.await
}
pub async fn create_topup_idempotent(&self, params: CreateTopup, idempotency_key: &str) -> Result<Topup> {
self.send(Method::POST, "/topups", Some(idempotency_key), |r| r.json(¶ms))
.await
}
pub async fn get_topup(&self, id: &str) -> Result<Topup> {
self.send(Method::GET, &format!("/topups/{id}"), None, |r| r).await
}
pub async fn list_intent_events(&self, id: &str, params: &ListEvents) -> Result<EventList> {
self.send(Method::GET, &format!("/intents/{id}/events"), None, |r| r.query(params))
.await
}
pub fn stream_intent_events(&self, id: &str, last_event_id: Option<&str>) -> EventStream {
EventStream::new(self.clone(), format!("/intents/{id}/events"), last_event_id)
}
pub async fn list_profiles(&self, params: &ListProfiles) -> Result<ProfileList> {
self.send(Method::GET, "/profiles", None, |r| r.query(params)).await
}
pub async fn create_profile(&self, params: CreateProfile) -> Result<Profile> {
self.send(Method::POST, "/profiles", None, |r| r.json(¶ms)).await
}
pub async fn get_profile(&self, id: &str) -> Result<Profile> {
self.send(Method::GET, &format!("/profiles/{id}"), None, |r| r).await
}
pub async fn forget_profile(&self, id: &str) -> Result<Profile> {
self.send(Method::DELETE, &format!("/profiles/{id}"), None, |r| r).await
}
pub async fn create_session(&self, params: CreateSession) -> Result<Session> {
self.create_session_idempotent(params, &uuid::Uuid::new_v4().to_string())
.await
}
pub async fn create_session_idempotent(&self, params: CreateSession, idempotency_key: &str) -> Result<Session> {
self.send(Method::POST, "/sessions", Some(idempotency_key), |r| r.json(¶ms))
.await
}
pub async fn get_session(&self, id: &str) -> Result<Session> {
self.send(Method::GET, &format!("/sessions/{id}"), None, |r| r).await
}
pub async fn list_sessions(&self, params: &ListSessions) -> Result<SessionList> {
self.send(Method::GET, "/sessions", None, |r| r.query(params)).await
}
pub async fn release_session(&self, id: &str) -> Result<Session> {
let key = uuid::Uuid::new_v4().to_string();
self.send(Method::POST, &format!("/sessions/{id}/release"), Some(&key), |r| r)
.await
}
pub async fn run_session_command(&self, id: &str, command: SessionCommand) -> Result<SessionCommandResult> {
self.run_session_command_idempotent(id, command, &uuid::Uuid::new_v4().to_string())
.await
}
pub async fn run_session_command_idempotent(
&self,
id: &str,
command: SessionCommand,
idempotency_key: &str,
) -> Result<SessionCommandResult> {
self.send(
Method::POST,
&format!("/sessions/{id}/commands"),
Some(idempotency_key),
|r| r.json(&command),
)
.await
}
pub async fn get_session_command(&self, id: &str, command_id: &str) -> Result<SessionCommandResult> {
self.send(
Method::GET,
&format!("/sessions/{id}/commands/{command_id}"),
None,
|r| r,
)
.await
}
pub async fn session_screenshot(&self, id: &str) -> Result<Vec<u8>> {
let res = self
.send_raw(
Method::GET,
&format!("/sessions/{id}/screenshot"),
None,
"image/jpeg",
|r| r,
)
.await?;
Ok(res.bytes().await?.to_vec())
}
pub async fn list_session_events(&self, id: &str, params: &ListEvents) -> Result<EventList> {
self.send(Method::GET, &format!("/sessions/{id}/events"), None, |r| {
r.query(params)
})
.await
}
pub fn stream_session_events(&self, id: &str, last_event_id: Option<&str>) -> EventStream {
EventStream::new(self.clone(), format!("/sessions/{id}/events"), last_event_id)
}
pub async fn create_live_link(&self, session: &str) -> Result<LiveLink> {
let key = uuid::Uuid::new_v4().to_string();
self.send(
Method::POST,
&format!("/sessions/{session}/live_links"),
Some(&key),
|r| r,
)
.await
}
pub async fn create_portal_session(&self, customer: &str, params: CreatePortalSession) -> Result<PortalSession> {
let key = uuid::Uuid::new_v4().to_string();
self.send(
Method::POST,
&format!("/customers/{customer}/portal_sessions"),
Some(&key),
|r| r.json(¶ms),
)
.await
}
pub async fn create_secret_request(
&self,
customer: &str,
params: CreateSecretRequest,
) -> Result<SecretRequestCreated> {
let key = uuid::Uuid::new_v4().to_string();
self.send(
Method::POST,
&format!("/customers/{customer}/secret_requests"),
Some(&key),
|r| r.json(¶ms),
)
.await
}
pub async fn get_secret_request(&self, id: &str) -> Result<SecretRequest> {
self.send(Method::GET, &format!("/secret_requests/{id}"), None, |r| r)
.await
}
pub async fn create_secret(&self, params: CreateSecret) -> Result<Secret> {
let key = uuid::Uuid::new_v4().to_string();
self.send(Method::POST, "/secrets", Some(&key), |r| r.json(¶ms))
.await
}
pub async fn list_secrets(&self, params: &ListSecrets) -> Result<SecretList> {
self.send(Method::GET, "/secrets", None, |r| r.query(params)).await
}
pub async fn get_secret(&self, id: &str) -> Result<Secret> {
self.send(Method::GET, &format!("/secrets/{id}"), None, |r| r).await
}
pub async fn replace_secret(&self, id: &str, params: CreateSecret) -> Result<Secret> {
let key = uuid::Uuid::new_v4().to_string();
self.send(Method::PUT, &format!("/secrets/{id}"), Some(&key), |r| r.json(¶ms))
.await
}
pub async fn delete_secret(&self, id: &str) -> Result<()> {
self.send_raw(
Method::DELETE,
&format!("/secrets/{id}"),
None,
"application/json",
|r| r,
)
.await?;
Ok(())
}
pub async fn list_secret_uses(&self, id: &str, page: &Page) -> Result<SecretUseList> {
self.send(Method::GET, &format!("/secrets/{id}/uses"), None, |r| r.query(page))
.await
}
pub async fn create_sign_in(&self, params: CreateSignIn) -> Result<SignIn> {
let key = uuid::Uuid::new_v4().to_string();
self.send(Method::POST, "/sign_ins", Some(&key), |r| r.json(¶ms))
.await
}
pub async fn get_sign_in(&self, id: &str) -> Result<SignIn> {
self.send(Method::GET, &format!("/sign_ins/{id}"), None, |r| r).await
}
pub async fn create_webhook_endpoint(&self, params: CreateWebhookEndpoint) -> Result<WebhookEndpoint> {
let key = uuid::Uuid::new_v4().to_string();
self.send(Method::POST, "/webhook_endpoints", Some(&key), |r| r.json(¶ms))
.await
}
pub async fn list_webhook_endpoints(&self, page: &Page) -> Result<WebhookEndpointList> {
self.send(Method::GET, "/webhook_endpoints", None, |r| r.query(page))
.await
}
pub async fn get_webhook_endpoint(&self, id: &str) -> Result<WebhookEndpoint> {
self.send(Method::GET, &format!("/webhook_endpoints/{id}"), None, |r| r)
.await
}
pub async fn update_webhook_endpoint(&self, id: &str, params: UpdateWebhookEndpoint) -> Result<WebhookEndpoint> {
self.send(Method::PATCH, &format!("/webhook_endpoints/{id}"), None, |r| {
r.json(¶ms)
})
.await
}
pub async fn delete_webhook_endpoint(&self, id: &str) -> Result<()> {
self.send_raw(
Method::DELETE,
&format!("/webhook_endpoints/{id}"),
None,
"application/json",
|r| r,
)
.await?;
Ok(())
}
pub async fn rotate_webhook_secret(&self, id: &str) -> Result<WebhookEndpoint> {
self.send(
Method::POST,
&format!("/webhook_endpoints/{id}/rotate_secret"),
None,
|r| r,
)
.await
}
pub async fn test_webhook_endpoint(&self, id: &str) -> Result<WebhookDelivery> {
self.send(Method::POST, &format!("/webhook_endpoints/{id}/test"), None, |r| r)
.await
}
pub async fn list_webhook_deliveries(&self, id: &str, page: &Page) -> Result<WebhookDeliveryList> {
self.send(Method::GET, &format!("/webhook_endpoints/{id}/deliveries"), None, |r| {
r.query(page)
})
.await
}
pub async fn redeliver_webhook(&self, endpoint: &str, delivery: &str) -> Result<WebhookDelivery> {
self.send(
Method::POST,
&format!("/webhook_endpoints/{endpoint}/deliveries/{delivery}/redeliver"),
None,
|r| r,
)
.await
}
pub async fn wait(&self, id: &str, opts: WaitOptions) -> Result<Intent> {
let deadline = Instant::now() + opts.timeout;
loop {
let intent = self.get_intent(id).await?;
let waits_on_person = (opts.return_on_payment && intent.status == IntentStatus::RequiresPayment)
|| (opts.return_on_sign_in && intent.status == IntentStatus::RequiresLogin)
|| (opts.return_on_input && intent.status == IntentStatus::RequiresInput);
if intent.status.is_final() || waits_on_person {
return Ok(intent);
}
if Instant::now() + opts.interval > deadline {
return Err(Error::WaitTimeout {
intent_id: id.to_string(),
timeout: opts.timeout,
});
}
tokio::time::sleep(opts.interval).await;
}
}
fn hold(&self, req: RequestBuilder, wait_secs: u32) -> RequestBuilder {
let hold = Duration::from_secs(u64::from(wait_secs.min(MAX_HOLD_SECS)) + 10);
req.header("Prefer", format!("wait={wait_secs}"))
.timeout(self.timeout.max(hold))
}
async fn send<T: DeserializeOwned>(
&self,
method: Method,
path: &str,
idempotency_key: Option<&str>,
build: impl Fn(RequestBuilder) -> RequestBuilder,
) -> Result<T> {
let res = self
.send_raw(method, path, idempotency_key, "application/json", build)
.await?;
Ok(res.json().await?)
}
async fn send_raw(
&self,
method: Method,
path: &str,
idempotency_key: Option<&str>,
accept: &str,
build: impl Fn(RequestBuilder) -> RequestBuilder,
) -> Result<reqwest::Response> {
let mut attempt = 0;
loop {
let req = self
.request(method.clone(), path, accept, idempotency_key)
.timeout(self.timeout);
let res = match build(req).send().await {
Ok(res) => res,
Err(err) if attempt < self.max_retries && (err.is_connect() || err.is_timeout()) => {
tokio::time::sleep(backoff(attempt, None)).await;
attempt += 1;
continue;
}
Err(err) => return Err(err.into()),
};
let status = res.status();
if status.is_success() {
return Ok(res);
}
if retryable(status) && attempt < self.max_retries {
tokio::time::sleep(backoff(attempt, retry_after(&res))).await;
attempt += 1;
continue;
}
return Err(api_error(res).await);
}
}
pub(crate) fn request(
&self,
method: Method,
path: &str,
accept: &str,
idempotency_key: Option<&str>,
) -> RequestBuilder {
let mut req = self
.http
.request(method, format!("{}{}", self.base_url, path))
.bearer_auth(&self.api_key)
.header(header::ACCEPT, accept);
if let Some(key) = idempotency_key {
req = req.header("Idempotency-Key", key);
}
req
}
}
pub(crate) fn retryable(status: StatusCode) -> bool {
status == StatusCode::TOO_MANY_REQUESTS || status.is_server_error()
}
pub(crate) fn retry_after(res: &reqwest::Response) -> Option<f64> {
res.headers()
.get(header::RETRY_AFTER)
.and_then(|v| v.to_str().ok())
.and_then(|v| v.parse::<f64>().ok())
}
pub(crate) async fn api_error(res: reqwest::Response) -> Error {
let status = res.status();
let request_id = res
.headers()
.get("request-id")
.and_then(|v| v.to_str().ok())
.map(str::to_string);
let retry_after = header_int(&res, "retry-after");
let rate_limit = rate_limit(&res);
let detail = res.json::<ErrorBody>().await.ok().and_then(|b| b.error);
let (kind, code, param, message, lease) = match detail {
Some(d) => (d.kind, d.code, d.param, d.message, d.lease),
None => (None, None, None, None, None),
};
Error::Api {
status: status.as_u16(),
kind: kind.unwrap_or_else(|| {
if status.is_server_error() {
"api_error"
} else {
"invalid_request"
}
.into()
}),
code,
param,
message: message.unwrap_or_else(|| format!("HTTP {}", status.as_u16())),
lease,
request_id,
retry_after,
rate_limit,
}
}
fn header_int(res: &reqwest::Response, name: &str) -> Option<u64> {
res.headers()
.get(name)
.and_then(|v| v.to_str().ok())
.and_then(|v| v.trim().parse::<u64>().ok())
}
fn rate_limit(res: &reqwest::Response) -> Option<RateLimit> {
let int = |name: &str| header_int(res, name).and_then(|v| u32::try_from(v).ok());
Some(RateLimit {
limit: int("ratelimit-limit")?,
remaining: int("ratelimit-remaining")?,
reset: int("ratelimit-reset")?,
})
}
pub(crate) fn backoff(attempt: u32, retry_after: Option<f64>) -> Duration {
if let Some(secs) = retry_after.filter(|s| *s > 0.0) {
return Duration::from_secs_f64(secs);
}
let base = (0.5 * 2f64.powi(attempt as i32)).min(8.0);
Duration::from_secs_f64(base * rand::thread_rng().gen_range(0.75..1.25))
}
#[derive(Debug, Clone)]
pub struct ClientBuilder {
api_key: String,
base_url: String,
timeout: Duration,
max_retries: u32,
}
impl ClientBuilder {
pub fn base_url(mut self, url: impl Into<String>) -> Self {
self.base_url = url.into().trim_end_matches('/').to_string();
self
}
pub fn timeout(mut self, timeout: Duration) -> Self {
self.timeout = timeout;
self
}
pub fn max_retries(mut self, n: u32) -> Self {
self.max_retries = n;
self
}
pub fn build(self) -> Client {
let http = reqwest::Client::builder()
.connect_timeout(self.timeout)
.read_timeout(self.timeout.max(STREAM_IDLE_TIMEOUT))
.user_agent(format!("openintents-rust/{VERSION}"))
.build()
.expect("reqwest client with rustls builds");
Client {
http,
api_key: self.api_key,
base_url: self.base_url,
timeout: self.timeout,
max_retries: self.max_retries,
}
}
}