use std::collections::HashMap;
use std::env;
use std::fmt;
use std::time::Duration;
use reqwest::header::{HeaderMap, HeaderName, HeaderValue, ACCEPT, AUTHORIZATION, RETRY_AFTER};
use reqwest::{Client as HttpClient, Method, StatusCode};
use serde_json::Value;
use crate::error::{ErrorKind, Result, TypeSafeError};
use crate::questions::{validate_questions, Question};
use crate::retry::{jitter_seed, RetryPolicy};
use crate::types::{
ListModelsResponse, SetRawBody, SetRequestId, SystemOneRequest, SystemOneResponse,
};
const DEFAULT_BASE_URL: &str = "https://api.typesafe.ai";
const DEFAULT_MODEL: &str = "jev-latest";
const DEFAULT_TIMEOUT: Duration = Duration::from_secs(10);
const SDK_USER_AGENT: &str = concat!("typesafe-sdk/", env!("CARGO_PKG_VERSION"));
const SYSTEM_ONE_PATH: &str = "/v1/systemone";
const MODELS_PATH: &str = "/v1/models";
const RETRY_AFTER_MS_HEADER: &str = "retry-after-ms";
const REQUEST_ID_HEADER: &str = "x-typesafe-request-id";
const MAX_ERROR_BODY_CHARS: usize = 512;
#[derive(Clone)]
#[non_exhaustive]
pub struct ClientConfig {
pub api_key: String,
pub base_url: String,
pub default_model: String,
pub timeout: Duration,
pub retry: RetryPolicy,
}
impl Default for ClientConfig {
fn default() -> Self {
Self {
api_key: String::new(),
base_url: DEFAULT_BASE_URL.to_string(),
default_model: DEFAULT_MODEL.to_string(),
timeout: DEFAULT_TIMEOUT,
retry: RetryPolicy::default(),
}
}
}
impl ClientConfig {
#[must_use]
pub fn new(api_key: impl Into<String>) -> Self {
Self {
api_key: api_key.into(),
..Self::default()
}
}
#[must_use]
pub fn with_api_key(mut self, api_key: impl Into<String>) -> Self {
self.api_key = api_key.into();
self
}
#[must_use]
pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
self.base_url = base_url.into();
self
}
#[must_use]
pub fn with_default_model(mut self, default_model: impl Into<String>) -> Self {
self.default_model = default_model.into();
self
}
#[must_use]
pub fn with_timeout(mut self, timeout: Duration) -> Self {
self.timeout = timeout;
self
}
#[must_use]
pub fn with_retry(mut self, retry: RetryPolicy) -> Self {
self.retry = retry;
self
}
}
impl fmt::Debug for ClientConfig {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("ClientConfig")
.field("api_key", &"<redacted>")
.field("base_url", &self.base_url)
.field("default_model", &self.default_model)
.field("timeout", &self.timeout)
.field("retry", &self.retry)
.finish()
}
}
#[derive(Clone)]
#[non_exhaustive]
pub struct TypeSafeClient {
config: ClientConfig,
http: HttpClient,
}
impl fmt::Debug for TypeSafeClient {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("TypeSafeClient")
.field("config", &self.config)
.finish_non_exhaustive()
}
}
struct Failure {
error: TypeSafeError,
retry_after: Option<Duration>,
}
impl From<TypeSafeError> for Failure {
fn from(error: TypeSafeError) -> Self {
Self {
error,
retry_after: None,
}
}
}
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct SystemOneOpts {
pub(crate) model: Option<String>,
pub(crate) state: Option<Value>,
pub(crate) extra_body: Option<Value>,
}
impl SystemOneOpts {
pub fn new() -> Self {
Self::default()
}
#[must_use = "the returned SystemOneOpts should be used"]
pub fn with_model(mut self, model: Option<String>) -> Self {
self.model = model;
self
}
#[must_use = "the returned SystemOneOpts should be used"]
pub fn with_state(mut self, state: impl Into<Value>) -> Self {
self.state = Some(state.into());
self
}
#[must_use = "the returned SystemOneOpts should be used"]
pub fn with_extra_body(mut self, extra: Value) -> Self {
self.extra_body = Some(extra);
self
}
}
impl TypeSafeClient {
#[must_use = "the returned client should be used to make API calls"]
pub fn new(api_key: impl Into<String>) -> Result<Self> {
let config = ClientConfig {
api_key: api_key.into(),
..ClientConfig::default()
};
Self::from_config(config)
}
#[must_use = "the returned client should be used to make API calls"]
pub fn from_config(mut config: ClientConfig) -> Result<Self> {
config.api_key = config.api_key.trim().to_string();
if config.api_key.is_empty() {
return Err(TypeSafeError::new(ErrorKind::Validation(
"No API key was provided. Pass an API key to `TypeSafeClient::new` or set the `TYPESAFE_API_KEY` environment variable."
.to_string(),
)));
}
config.base_url = config.base_url.trim().trim_end_matches('/').to_string();
validate_base_url(&config.base_url)?;
if config.default_model.trim().is_empty() {
return Err(TypeSafeError::new(ErrorKind::Validation(
"Default model name cannot be empty.".to_string(),
)));
}
let mut auth =
HeaderValue::from_str(&format!("Bearer {}", config.api_key)).map_err(|_| {
TypeSafeError::new(ErrorKind::Validation(
"The API key contains characters that are not valid in an HTTP header."
.to_string(),
))
})?;
auth.set_sensitive(true);
let mut headers = HeaderMap::new();
headers.insert(AUTHORIZATION, auth);
headers.insert(ACCEPT, HeaderValue::from_static("application/json"));
headers.insert(
HeaderName::from_static("x-typesafe-sdk"),
HeaderValue::from_static(SDK_USER_AGENT),
);
let http = HttpClient::builder()
.timeout(config.timeout)
.user_agent(SDK_USER_AGENT)
.default_headers(headers)
.build()
.map_err(|e| TypeSafeError::new(ErrorKind::Transport(e)))?;
Ok(Self { config, http })
}
#[must_use = "the returned client should be used to make API calls"]
pub fn from_env() -> Result<Self> {
let api_key = env::var("TYPESAFE_API_KEY").unwrap_or_default();
let mut config = ClientConfig {
api_key,
..ClientConfig::default()
};
if let Ok(base) = env::var("TYPESAFE_BASE_URL") {
if !base.trim().is_empty() {
config.base_url = base;
}
}
if let Ok(model) = env::var("TYPESAFE_DEFAULT_MODEL") {
if !model.trim().is_empty() {
config.default_model = model;
}
}
Self::from_config(config)
}
pub fn base_url(&self) -> &str {
&self.config.base_url
}
pub fn default_model(&self) -> &str {
&self.config.default_model
}
pub async fn system_one(
&self,
state: impl Into<Value>,
questions: HashMap<String, Question>,
) -> Result<SystemOneResponse> {
self.system_one_with_model(state, questions, None).await
}
pub async fn system_one_with_model(
&self,
state: impl Into<Value>,
questions: HashMap<String, Question>,
model: Option<&str>,
) -> Result<SystemOneResponse> {
let opts = SystemOneOpts::new()
.with_model(model.map(|m| m.to_string()))
.with_state(state);
self.system_one_with_opts(questions, opts).await
}
pub async fn system_one_with_opts(
&self,
questions: HashMap<String, Question>,
opts: SystemOneOpts,
) -> Result<SystemOneResponse> {
validate_questions(&questions)?;
let model_name = opts
.model
.unwrap_or_else(|| self.config.default_model.clone());
if model_name.trim().is_empty() {
return Err(TypeSafeError::new(ErrorKind::Validation(
"Model name cannot be empty.".to_string(),
)));
}
let request = SystemOneRequest {
state: opts.state.unwrap_or(Value::Null),
model: model_name,
questions,
extra_body: opts.extra_body,
};
let mut body = serde_json::to_value(&request)?;
if let Some(extra) = &request.extra_body {
if let (Some(obj), Some(extra_obj)) = (body.as_object_mut(), extra.as_object()) {
for (k, v) in extra_obj {
if !obj.contains_key(k) {
obj.insert(k.clone(), v.clone());
}
}
}
}
self.request_with_retry(Method::POST, SYSTEM_ONE_PATH, Some(body))
.await
}
pub async fn list_models(&self) -> Result<ListModelsResponse> {
self.request_with_retry(Method::GET, MODELS_PATH, None)
.await
}
async fn request_with_retry<T: serde::de::DeserializeOwned + 'static>(
&self,
method: Method,
path: &str,
body: Option<Value>,
) -> Result<T> {
let url = format!("{}{}", self.config.base_url, path);
let retry = &self.config.retry;
let started = std::time::Instant::now();
let mut attempt = 0;
loop {
match self.attempt_request(&method, &url, body.as_ref()).await {
Ok(resp) => return Ok(resp),
Err(failure) => {
if !failure.error.is_retryable() || attempt >= retry.max_retries {
return Err(failure.error);
}
let delay = match failure.retry_after {
Some(hint) => match retry.delay_for_retry_after(attempt, hint) {
Some(delay) => delay,
None => return Err(failure.error),
},
None => retry.delay_for_with_jitter(attempt, jitter_seed()),
};
if retry.budget_exceeded(started.elapsed(), delay) {
return Err(failure.error);
}
tokio::time::sleep(delay).await;
attempt += 1;
}
}
}
}
async fn attempt_request<T: serde::de::DeserializeOwned + 'static>(
&self,
method: &Method,
url: &str,
body: Option<&Value>,
) -> std::result::Result<T, Failure> {
let mut request = self.http.request(method.clone(), url);
if let Some(b) = body {
request = request.json(b);
}
let response = request
.send()
.await
.map_err(|e| map_reqwest_error(e, self.config.timeout))?;
self.parse_response(response).await
}
async fn parse_response<T: serde::de::DeserializeOwned + 'static>(
&self,
response: reqwest::Response,
) -> std::result::Result<T, Failure> {
let status = response.status();
let headers = response.headers();
let request_id = headers
.get(REQUEST_ID_HEADER)
.and_then(|v| v.to_str().ok())
.map(|s| s.to_string());
let retry_after = headers
.get(RETRY_AFTER_MS_HEADER)
.and_then(|v| v.to_str().ok())
.and_then(parse_retry_after_ms)
.or_else(|| {
headers
.get(RETRY_AFTER)
.and_then(|v| v.to_str().ok())
.and_then(parse_retry_after)
});
let text = response.text().await.map_err(map_body_error)?;
if status.is_success() {
let mut result: T = serde_json::from_str(&text).map_err(|e| {
Failure::from(TypeSafeError::new(ErrorKind::ResponseValidation {
message: format!(
"Failed to parse response body: {e}\nBody: {}",
truncate(&text, MAX_ERROR_BODY_CHARS)
),
field_path: None,
}))
})?;
let raw = serde_json::from_str::<Value>(&text).ok();
inject_metadata(&mut result, request_id.clone(), raw);
return Ok(result);
}
let message = Self::extract_error_message(&text)
.unwrap_or_else(|| truncate(&text, MAX_ERROR_BODY_CHARS));
let kind = match status {
StatusCode::UNAUTHORIZED => ErrorKind::Authentication(message),
StatusCode::BAD_REQUEST => ErrorKind::BadRequest(message),
StatusCode::NOT_FOUND => ErrorKind::NotFound(message),
StatusCode::UNPROCESSABLE_ENTITY => ErrorKind::UnprocessableEntity(message),
StatusCode::TOO_MANY_REQUESTS => ErrorKind::RateLimit(message),
StatusCode::INTERNAL_SERVER_ERROR
| StatusCode::BAD_GATEWAY
| StatusCode::SERVICE_UNAVAILABLE
| StatusCode::GATEWAY_TIMEOUT => ErrorKind::InternalServer(message),
s if s.as_u16() == 529 => ErrorKind::Overloaded(message),
_ => ErrorKind::Api {
status: status.as_u16(),
message,
},
};
Err(Failure {
error: TypeSafeError::with_request_id(kind, request_id),
retry_after,
})
}
fn extract_error_message(text: &str) -> Option<String> {
let value: Value = serde_json::from_str(text).ok()?;
let obj = value.as_object()?;
if let Some(error) = obj.get("error") {
if let Some(msg) = error.get("message").and_then(|m| m.as_str()) {
return Some(msg.to_string());
}
if let Some(msg) = error.as_str() {
return Some(msg.to_string());
}
}
if let Some(detail) = obj.get("detail").and_then(|d| d.as_str()) {
return Some(detail.to_string());
}
if let Some(message) = obj.get("message").and_then(|m| m.as_str()) {
return Some(message.to_string());
}
None
}
}
fn inject_metadata<T: 'static>(value: &mut T, request_id: Option<String>, raw: Option<Value>) {
use std::any::Any;
if let Some(resp) = (value as &mut dyn Any).downcast_mut::<SystemOneResponse>() {
resp.set_request_id(request_id);
resp.set_raw(raw);
} else if let Some(resp) = (value as &mut dyn Any).downcast_mut::<ListModelsResponse>() {
resp.set_request_id(request_id);
resp.set_raw(raw);
}
}
fn map_reqwest_error(e: reqwest::Error, timeout: Duration) -> TypeSafeError {
if e.is_timeout() {
TypeSafeError::new(ErrorKind::Timeout(timeout))
} else if e.is_connect() {
TypeSafeError::new(ErrorKind::Connection(e.to_string()))
} else {
TypeSafeError::new(ErrorKind::Transport(e))
}
}
fn map_body_error(e: reqwest::Error) -> TypeSafeError {
TypeSafeError::new(ErrorKind::Transport(e))
}
fn parse_retry_after(value: &str) -> Option<Duration> {
value.trim().parse::<u64>().ok().map(Duration::from_secs)
}
fn parse_retry_after_ms(value: &str) -> Option<Duration> {
value.trim().parse::<u64>().ok().map(Duration::from_millis)
}
fn truncate(s: &str, max_chars: usize) -> String {
match s.char_indices().nth(max_chars) {
Some((idx, _)) => format!("{}...", &s[..idx]),
None => s.to_string(),
}
}
fn validate_base_url(raw: &str) -> Result<()> {
let url = reqwest::Url::parse(raw).map_err(|e| {
TypeSafeError::new(ErrorKind::Validation(format!(
"Base URL is not a valid URL: {e}"
)))
})?;
if !url.username().is_empty()
|| url.password().is_some()
|| url.query().is_some()
|| url.fragment().is_some()
{
return Err(TypeSafeError::new(ErrorKind::Validation(
"Base URL must not contain credentials, query parameters, or fragments.".to_string(),
)));
}
match (url.scheme(), url.host_str()) {
("https", Some(_)) => Ok(()),
("http", Some("localhost" | "127.0.0.1" | "::1" | "[::1]")) => Ok(()),
(scheme, _) => Err(TypeSafeError::new(ErrorKind::Validation(format!(
"Base URL must use https:// (or http:// for localhost/127.0.0.1/::1 during development); got scheme `{scheme}` and an unsupported host."
)))),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn new_requires_api_key() {
let result = TypeSafeClient::new("");
assert!(result.is_err());
}
#[test]
fn from_config_requires_api_key() {
let config = ClientConfig::default();
let result = TypeSafeClient::from_config(config);
assert!(result.is_err());
}
#[test]
fn extract_error_message_from_nested_object() {
let text = r#"{"error":{"message":"Invalid API key"}}"#;
let msg = TypeSafeClient::extract_error_message(text).unwrap();
assert_eq!(msg, "Invalid API key");
}
#[test]
fn extract_error_message_from_detail() {
let text = r#"{"detail":"Not found"}"#;
let msg = TypeSafeClient::extract_error_message(text).unwrap();
assert_eq!(msg, "Not found");
}
#[test]
fn extract_error_message_returns_none_for_plain_text() {
let text = "plain text error";
assert!(TypeSafeClient::extract_error_message(text).is_none());
}
#[test]
fn debug_redacts_api_key() {
let config = ClientConfig {
api_key: "secret_key_123".to_string(),
..ClientConfig::default()
};
let debug_str = format!("{config:?}");
assert!(!debug_str.contains("secret_key_123"));
assert!(debug_str.contains("<redacted>"));
}
#[test]
fn client_debug_does_not_leak_api_key() {
let client = TypeSafeClient::new("secret_key_123").unwrap();
let debug_str = format!("{client:?}");
assert!(!debug_str.contains("secret_key_123"));
}
#[test]
fn trims_api_key_whitespace() {
let client = TypeSafeClient::new(" apikey_test \n").unwrap();
assert_eq!(client.config.api_key, "apikey_test");
}
#[test]
fn rejects_api_key_that_is_not_a_valid_header_value() {
let err = TypeSafeClient::new("bad\nkey").unwrap_err();
assert!(
matches!(err.kind(), ErrorKind::Validation(_)),
"got {err:?}"
);
}
#[test]
fn rejects_http_base_url() {
let config = ClientConfig {
api_key: "test".to_string(),
base_url: "http://api.typesafe.ai".to_string(),
..ClientConfig::default()
};
assert!(TypeSafeClient::from_config(config).is_err());
}
#[test]
fn allows_localhost_http() {
let config = ClientConfig {
api_key: "test".to_string(),
base_url: "http://localhost:8080".to_string(),
..ClientConfig::default()
};
assert!(TypeSafeClient::from_config(config).is_ok());
}
#[test]
fn trims_trailing_slash_from_base_url() {
let config = ClientConfig {
api_key: "test".to_string(),
base_url: "https://api.typesafe.ai/".to_string(),
..ClientConfig::default()
};
let client = TypeSafeClient::from_config(config).unwrap();
assert_eq!(client.base_url(), "https://api.typesafe.ai");
}
#[test]
fn trailing_slash_does_not_produce_double_slash() {
let config = ClientConfig {
api_key: "test".to_string(),
base_url: "https://api.typesafe.ai/v1/".to_string(),
..ClientConfig::default()
};
let client = TypeSafeClient::from_config(config).unwrap();
let url = format!("{}{}", client.base_url(), "/v1/systemone");
assert_eq!(url, "https://api.typesafe.ai/v1/v1/systemone");
assert!(!url.contains("//v1"), "double slash in URL: {url}");
}
#[test]
fn base_url_rejects_localhost_lookalikes() {
for bad in [
"http://localhost.evil.example",
"http://127.0.0.1.evil.example/v1",
"http://localhost@evil.example",
"http://localhostevil.example",
"ftp://localhost",
"not a url",
"",
] {
assert!(
validate_base_url(bad).is_err(),
"{bad:?} should be rejected"
);
}
}
#[test]
fn base_url_accepts_valid_urls() {
for good in [
"https://api.typesafe.ai",
"HTTPS://API.TYPESAFE.AI",
"https://api.typesafe.ai/prefix",
"http://localhost",
"http://localhost:8080",
"http://LOCALHOST:8080",
"http://127.0.0.1:9000",
"http://[::1]:9000",
] {
assert!(
validate_base_url(good).is_ok(),
"{good:?} should be accepted"
);
}
}
#[test]
fn truncate_shortens_long_strings() {
let long = "x".repeat(600);
let truncated = truncate(&long, 512);
assert_eq!(truncated.len(), 515); assert!(truncated.ends_with("..."));
}
#[test]
fn truncate_leaves_short_strings_alone() {
assert_eq!(truncate("hello", 512), "hello");
assert_eq!(truncate("exactly", 7), "exactly");
}
#[test]
fn truncate_handles_multibyte_characters() {
let long = "€".repeat(600);
let truncated = truncate(&long, 512);
assert_eq!(truncated.chars().count(), 515); assert!(truncated.ends_with("..."));
let mixed = "héllo wörld 日本語 🙂".repeat(20);
for max in 0..mixed.chars().count() + 2 {
let _ = truncate(&mixed, max); }
}
#[test]
fn parse_retry_after_seconds() {
assert_eq!(parse_retry_after("5"), Some(Duration::from_secs(5)));
assert_eq!(parse_retry_after(" 10 "), Some(Duration::from_secs(10)));
assert_eq!(parse_retry_after("not a number"), None);
assert_eq!(parse_retry_after("Wed, 21 Oct 2026 07:28:00 GMT"), None);
}
#[test]
fn parse_retry_after_ms_parses_milliseconds() {
assert_eq!(
parse_retry_after_ms("500"),
Some(Duration::from_millis(500))
);
assert_eq!(
parse_retry_after_ms(" 1500 "),
Some(Duration::from_millis(1500))
);
assert_eq!(parse_retry_after_ms("not a number"), None);
}
#[test]
fn builder_errors_are_not_retryable() {
let err = reqwest::Client::new().get("not a url").build().unwrap_err();
let mapped = map_reqwest_error(err, Duration::from_secs(1));
assert!(
matches!(mapped.kind(), ErrorKind::Transport(_)),
"got {mapped:?}"
);
assert!(!mapped.is_retryable());
}
#[test]
fn base_url_accepts_ipv6_loopback() {
assert!(validate_base_url("http://[::1]:8080").is_ok());
assert!(validate_base_url("http://[::1]").is_ok());
}
#[test]
fn from_config_rejects_empty_default_model() {
let config = ClientConfig {
api_key: "test".to_string(),
default_model: " ".to_string(),
..ClientConfig::default()
};
let err = TypeSafeClient::from_config(config).unwrap_err();
assert!(
matches!(err.kind(), ErrorKind::Validation(ref m) if m.contains("model")),
"got {err:?}"
);
}
#[test]
fn timeout_error_preserves_subsecond_duration() {
let err = TypeSafeError::new(ErrorKind::Timeout(Duration::from_millis(150)));
let msg = err.to_string();
assert!(
msg.contains("150ms"),
"expected 150ms in message, got: {msg}"
);
}
#[test]
fn base_url_rejects_credentials() {
assert!(validate_base_url("https://user:password@api.typesafe.ai").is_err());
assert!(validate_base_url("https://user@api.typesafe.ai").is_err());
}
#[test]
fn base_url_rejects_query_and_fragment() {
assert!(validate_base_url("https://api.typesafe.ai?foo=bar").is_err());
assert!(validate_base_url("https://api.typesafe.ai#fragment").is_err());
}
#[test]
fn base_url_accepts_path() {
assert!(validate_base_url("https://api.typesafe.ai/api").is_ok());
assert!(validate_base_url("https://api.typesafe.ai/v1/").is_ok());
}
}