xai_rust/

client.rs

//! xAI API client implementation.

use httpdate::parse_http_date;
use reqwest::header::{HeaderMap, HeaderValue, AUTHORIZATION, USER_AGENT};
use reqwest::{RequestBuilder, Response, StatusCode};
use std::sync::Arc;
use std::time::Duration;
use std::time::{SystemTime, UNIX_EPOCH};
use tokio::time::sleep;
#[cfg(feature = "telemetry")]
use tracing::{debug, warn};

#[cfg(feature = "files")]
use crate::api::FilesApi;
#[cfg(feature = "realtime")]
use crate::api::RealtimeApi;
use crate::api::{
    AuthApi, BatchApi, ChatApi, CollectionsApi, DocumentsApi, EmbeddingsApi, ImagesApi, ModelsApi,
    ResponsesApi, TokenizerApi, VideosApi,
};
use crate::config::{ClientConfig, RetryPolicy, XaiClientBuilder};
use crate::sync::SyncXaiClient;
use crate::{Error, Result};

const SDK_USER_AGENT: &str = concat!(env!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_VERSION"));
const HEX_UPPER: &[u8; 16] = b"0123456789ABCDEF";

/// The main xAI API client.
///
/// Use this client to interact with all xAI API endpoints.
///
/// # Example
///
/// ```rust,no_run
/// use xai_rust::XaiClient;
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// // Create from API key
/// let client = XaiClient::new("your-api-key")?;
///
/// // Or use the builder
/// let client = XaiClient::builder()
///     .api_key("your-api-key")
///     .timeout_secs(300)
///     .build()?;
///
/// // Or load from XAI_API_KEY environment variable
/// let client = XaiClient::from_env()?;
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
pub struct XaiClient {
    inner: Arc<ClientInner>,
}

#[derive(Debug)]
struct ClientInner {
    config: ClientConfig,
    http: reqwest::Client,
    retry_policy: RetryPolicy,
}

impl XaiClient {
    /// Create a new client with the given API key.
    ///
    /// Uses default configuration (global endpoint, 120s timeout).
    ///
    /// # Errors
    ///
    /// Returns an error if the API key contains invalid header characters
    /// or the HTTP client cannot be created.
    pub fn new(api_key: impl Into<String>) -> Result<Self> {
        let config = ClientConfig::new(api_key);
        Self::with_config(config)
    }

    /// Create a new client from the XAI_API_KEY environment variable.
    pub fn from_env() -> Result<Self> {
        let config = ClientConfig::from_env()
            .map_err(|_| Error::Config("XAI_API_KEY environment variable not set".to_string()))?;
        Self::with_config(config)
    }

    /// Create a new client builder.
    pub fn builder() -> XaiClientBuilder {
        XaiClientBuilder::new()
    }

    /// Create a blocking/sync facade from this async client.
    ///
    /// The sync facade is intended for non-async applications and should not be
    /// used from inside an active async runtime.
    pub fn sync(&self) -> Result<SyncXaiClient> {
        SyncXaiClient::with_async_client(self.clone())
    }

    /// Convert this async client into a blocking/sync facade.
    ///
    /// The sync facade is intended for non-async applications and should not be
    /// used from inside an active async runtime.
    pub fn into_sync(self) -> Result<SyncXaiClient> {
        SyncXaiClient::with_async_client(self)
    }

    /// Create a client with the given configuration.
    pub fn with_config(config: ClientConfig) -> Result<Self> {
        Self::with_config_and_retry(config, RetryPolicy::default())
    }

    pub(crate) fn with_config_and_retry(
        config: ClientConfig,
        retry_policy: RetryPolicy,
    ) -> Result<Self> {
        let mut headers = HeaderMap::new();
        headers.insert(
            AUTHORIZATION,
            HeaderValue::from_str(&format!("Bearer {}", config.api_key.expose()))
                .map_err(|_| Error::Config("Invalid API key format".to_string()))?,
        );
        headers.insert(USER_AGENT, HeaderValue::from_static(SDK_USER_AGENT));

        let http = reqwest::Client::builder()
            .default_headers(headers)
            .timeout(config.timeout)
            .build()?;

        Ok(Self {
            inner: Arc::new(ClientInner {
                config,
                http,
                retry_policy,
            }),
        })
    }

    /// Get the base URL for API requests.
    pub fn base_url(&self) -> &str {
        &self.inner.config.base_url
    }

    /// Get a reference to the HTTP client.
    pub(crate) fn http(&self) -> &reqwest::Client {
        &self.inner.http
    }

    pub(crate) fn retry_policy(&self) -> RetryPolicy {
        self.inner.retry_policy
    }

    pub(crate) async fn send(&self, request: RequestBuilder) -> Result<Response> {
        self.send_with_retry_policy(request, None).await
    }

    pub(crate) async fn send_with_retry_policy(
        &self,
        request: RequestBuilder,
        retry_policy_override: Option<RetryPolicy>,
    ) -> Result<Response> {
        let retry_policy = retry_policy_override.unwrap_or(self.inner.retry_policy);

        #[cfg(feature = "telemetry")]
        let (request_method, request_url) = request_telemetry_fields(&request);

        let mut current = Some(request);

        for attempt in 0..=retry_policy.max_retries {
            #[cfg(feature = "telemetry")]
            debug!(
                attempt,
                max_retries = retry_policy.max_retries,
                method = %request_method,
                url = %request_url,
                "xai-rust request attempt"
            );

            let req = current
                .take()
                .ok_or_else(|| Error::Config("Request cannot be retried".to_string()))?;
            let retry_clone = req.try_clone();

            match req.send().await {
                Ok(response) => {
                    if attempt < retry_policy.max_retries
                        && is_retryable_status(response.status())
                        && retry_clone.is_some()
                    {
                        let delay = retry_delay_from_response(
                            &retry_policy,
                            attempt,
                            response.status(),
                            response.headers().get("retry-after"),
                        );
                        let delay = apply_jitter(delay, retry_policy.jitter_factor);
                        #[cfg(feature = "telemetry")]
                        warn!(
                            attempt,
                            status = response.status().as_u16(),
                            delay_ms = delay.as_millis() as u64,
                            method = %request_method,
                            url = %request_url,
                            "xai-rust retrying request after retryable status"
                        );
                        sleep(delay).await;
                        current = retry_clone;
                        continue;
                    }
                    return Ok(response);
                }
                Err(err) => {
                    if attempt < retry_policy.max_retries && is_retryable_transport_error(&err) {
                        if let Some(next) = retry_clone {
                            let delay = exponential_backoff_delay(&retry_policy, attempt);
                            let delay = apply_jitter(delay, retry_policy.jitter_factor);
                            #[cfg(feature = "telemetry")]
                            warn!(
                                attempt,
                                delay_ms = delay.as_millis() as u64,
                                error = %err,
                                method = %request_method,
                                url = %request_url,
                                "xai-rust retrying request after transport error"
                            );
                            sleep(delay).await;
                            current = Some(next);
                            continue;
                        }
                    }
                    #[cfg(feature = "telemetry")]
                    warn!(
                        error = %err,
                        method = %request_method,
                        url = %request_url,
                        "xai-rust request failed"
                    );
                    return Err(Error::Http(err));
                }
            }
        }

        Err(Error::Timeout)
    }

    /// Get the API key.
    #[cfg(any(feature = "realtime", test))]
    pub(crate) fn api_key(&self) -> &str {
        self.inner.config.api_key.expose()
    }

    /// URL-encode a path segment for safe interpolation into API URLs.
    pub(crate) fn encode_path(segment: &str) -> String {
        if is_unreserved_path_segment(segment.as_bytes()) {
            return segment.to_owned();
        }
        encode_path_segment_slow(segment.as_bytes())
    }

    // API namespaces

    /// Access the Responses API.
    ///
    /// The Responses API is the primary endpoint for chat interactions.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use xai_rust::{XaiClient, Role};
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    ///
    /// let response = client.responses()
    ///     .create("grok-4")
    ///     .message(Role::User, "Hello!")
    ///     .send()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn responses(&self) -> ResponsesApi {
        ResponsesApi::new(self.clone())
    }

    /// Access the Auth API.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use xai_rust::XaiClient;
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    /// let key = client.auth().api_key().await?;
    /// println!("Authenticated as: {}", key.api_key);
    /// # Ok(())
    /// # }
    /// ```
    pub fn auth(&self) -> AuthApi {
        AuthApi::new(self.clone())
    }

    /// Access the Chat Completions API (legacy).
    ///
    /// Note: The Chat Completions API is deprecated. Use `responses()` instead.
    pub fn chat(&self) -> ChatApi {
        ChatApi::new(self.clone())
    }

    /// Access the Images API.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use xai_rust::XaiClient;
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    ///
    /// let response = client.images()
    ///     .generate("grok-2-image", "A cat in a tree")
    ///     .send()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn images(&self) -> ImagesApi {
        ImagesApi::new(self.clone())
    }

    /// Access the Videos API.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use xai_rust::XaiClient;
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    /// let video = client.videos().get("video-123").await?;
    /// println!("Video: {:?}", video.id);
    /// # Ok(())
    /// # }
    /// ```
    pub fn videos(&self) -> VideosApi {
        VideosApi::new(self.clone())
    }

    /// Access the Files API.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use xai_rust::XaiClient;
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    ///
    /// let files = client.files().list().await?;
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(feature = "files")]
    pub fn files(&self) -> FilesApi {
        FilesApi::new(self.clone())
    }

    /// Access the Models API.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use xai_rust::XaiClient;
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    ///
    /// let models = client.models().list().await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn models(&self) -> ModelsApi {
        ModelsApi::new(self.clone())
    }

    /// Access the Realtime API for voice interactions.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use xai_rust::{XaiClient, Voice, AudioFormat};
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    ///
    /// let session = client.realtime()
    ///     .connect("grok-4")
    ///     .voice(Voice::Ara)
    ///     .audio_format(AudioFormat::Pcm16)
    ///     .start()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(feature = "realtime")]
    pub fn realtime(&self) -> RealtimeApi {
        RealtimeApi::new(self.clone())
    }

    /// Access the Batch API for processing multiple requests.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use xai_rust::XaiClient;
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    ///
    /// let batch = client.batch().create("my-batch").await?;
    /// println!("Created batch: {}", batch.id);
    /// # Ok(())
    /// # }
    /// ```
    pub fn batch(&self) -> BatchApi {
        BatchApi::new(self.clone())
    }

    /// Access the Collections API for document storage and retrieval.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use xai_rust::XaiClient;
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    ///
    /// let collection = client.collections().create_named("my-docs").await?;
    /// println!("Created collection: {}", collection.id);
    /// # Ok(())
    /// # }
    /// ```
    pub fn collections(&self) -> CollectionsApi {
        CollectionsApi::new(self.clone())
    }

    /// Access the Documents API.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use xai_rust::api::DocumentsSearchRequest;
    /// use xai_rust::XaiClient;
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    /// let response = client.documents().search(DocumentsSearchRequest::new("query")).await?;
    /// println!("Found {} results", response.results.len());
    /// # Ok(())
    /// # }
    /// ```
    pub fn documents(&self) -> DocumentsApi {
        DocumentsApi::new(self.clone())
    }

    /// Access the Embeddings API.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use serde_json::json;
    /// use xai_rust::api::EmbeddingsRequest;
    /// use xai_rust::XaiClient;
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    /// let response = client
    ///     .embeddings()
    ///     .create(EmbeddingsRequest::new("text-embedding", json!("Hello")))
    ///     .await?;
    /// println!("embedding result {}",
    ///     response.data.len());
    /// # Ok(())
    /// # }
    /// ```
    pub fn embeddings(&self) -> EmbeddingsApi {
        EmbeddingsApi::new(self.clone())
    }

    /// Access the Tokenizer API for counting tokens.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use xai_rust::XaiClient;
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = XaiClient::from_env()?;
    ///
    /// let count = client.tokenizer()
    ///     .count_tokens("grok-4", "Hello, world!")
    ///     .await?;
    ///
    /// println!("Token count: {}", count);
    /// # Ok(())
    /// # }
    /// ```
    pub fn tokenizer(&self) -> TokenizerApi {
        TokenizerApi::new(self.clone())
    }
}

fn is_retryable_status(status: StatusCode) -> bool {
    matches!(status.as_u16(), 408 | 429 | 500 | 502 | 503 | 504)
}

fn is_retryable_transport_error(err: &reqwest::Error) -> bool {
    err.is_timeout() || err.is_connect() || err.is_request()
}

fn exponential_backoff_delay(policy: &RetryPolicy, attempt: u32) -> Duration {
    let max_millis = policy.max_backoff.as_millis();
    let initial_millis = policy.initial_backoff.as_millis();
    if max_millis == 0 || initial_millis == 0 {
        return Duration::ZERO;
    }

    let factor_shift = attempt.min(16);
    let factor = 1u128 << factor_shift;
    let delayed = initial_millis.saturating_mul(factor).min(max_millis);
    Duration::from_millis(delayed as u64)
}

fn retry_delay_from_response(
    policy: &RetryPolicy,
    attempt: u32,
    status: StatusCode,
    retry_after: Option<&HeaderValue>,
) -> Duration {
    if is_retryable_status(status) {
        if let Some(delay) = retry_after.and_then(parse_retry_after_delay) {
            return delay.min(policy.max_backoff);
        }
    }

    exponential_backoff_delay(policy, attempt)
}

fn parse_retry_after_delay(retry_after: &HeaderValue) -> Option<Duration> {
    let value = retry_after.to_str().ok()?.trim();
    if value.is_empty() {
        return None;
    }

    if let Ok(seconds) = value.parse::<u64>() {
        return Some(Duration::from_secs(seconds));
    }

    let retry_at = parse_http_date(value).ok()?;
    Some(
        retry_at
            .duration_since(SystemTime::now())
            .unwrap_or(Duration::ZERO),
    )
}

fn apply_jitter(delay: Duration, factor: f64) -> Duration {
    if delay.is_zero() || factor <= 0.0 {
        return delay;
    }

    let clamped_factor = factor.clamp(0.0, 1.0);
    let delay_secs = delay.as_secs_f64();
    let half_range = delay_secs * clamped_factor * 0.5;
    if half_range <= f64::EPSILON {
        return delay;
    }

    let min = (delay_secs - half_range).max(0.0);
    let max = delay_secs + half_range;
    let sample = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.subsec_nanos() as f64 / 1_000_000_000.0)
        .unwrap_or(0.5);
    Duration::from_secs_f64(min + (max - min) * sample)
}

#[inline]
fn is_unreserved_path_segment(segment: &[u8]) -> bool {
    let mut i = 0;
    while i < segment.len() {
        let b = segment[i];
        if !matches!(
            b,
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~'
        ) {
            return false;
        }
        i += 1;
    }
    true
}

#[inline]
fn encode_path_segment_slow(segment: &[u8]) -> String {
    let mut encoded = String::with_capacity(segment.len() + 8);
    for &b in segment {
        if should_percent_encode_path_byte(b) {
            encoded.push('%');
            encoded.push(HEX_UPPER[(b >> 4) as usize] as char);
            encoded.push(HEX_UPPER[(b & 0x0F) as usize] as char);
        } else {
            encoded.push(b as char);
        }
    }
    encoded
}

#[inline]
fn should_percent_encode_path_byte(b: u8) -> bool {
    b >= 0x80
        || matches!(
            b,
            0x00..=0x20
                | b'"'
                | b'#'
                | b'%'
                | b'/'
                | b'<'
                | b'>'
                | b'?'
                | b'['
                | b'\\'
                | b']'
                | b'^'
                | b'`'
                | b'{'
                | b'|'
                | b'}'
        )
}

#[cfg(feature = "opt-bench-internals")]
#[doc(hidden)]
pub fn __opt_bench_encode_path(segment: &str) -> String {
    XaiClient::encode_path(segment)
}

#[cfg(feature = "telemetry")]
fn request_telemetry_fields(request: &RequestBuilder) -> (String, String) {
    request
        .try_clone()
        .and_then(|builder| builder.build().ok())
        .map(|built| (built.method().to_string(), built.url().to_string()))
        .unwrap_or_else(|| ("unknown".to_string(), "unknown".to_string()))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::DEFAULT_BASE_URL;
    use httpdate::fmt_http_date;
    use serde_json::json;
    use std::sync::{
        atomic::{AtomicUsize, Ordering},
        Arc,
    };
    use wiremock::matchers::{header, method, path};
    use wiremock::{Mock, MockServer, ResponseTemplate};

    // ── XaiClient::new ──────────────────────────────────────────────

    #[test]
    fn client_new_returns_ok() {
        let client = XaiClient::new("test-api-key-1234");
        assert!(client.is_ok());
    }

    #[test]
    fn client_new_sets_base_url() {
        let client = XaiClient::new("test-key").unwrap();
        assert_eq!(client.base_url(), DEFAULT_BASE_URL);
    }

    #[test]
    fn client_new_preserves_api_key() {
        let client = XaiClient::new("my-secret-key").unwrap();
        assert_eq!(client.api_key(), "my-secret-key");
    }

    #[test]
    fn client_clone_shares_inner() {
        let client1 = XaiClient::new("key").unwrap();
        let client2 = client1.clone();
        assert_eq!(client1.base_url(), client2.base_url());
        assert_eq!(client1.api_key(), client2.api_key());
    }

    // ── XaiClient::builder ──────────────────────────────────────────

    #[test]
    fn client_builder_returns_builder() {
        let builder = XaiClient::builder();
        // Just ensure it compiles and returns something
        let debug = format!("{:?}", builder);
        assert!(debug.contains("XaiClientBuilder"));
    }

    #[test]
    fn client_from_builder() {
        let client = XaiClient::builder().api_key("builder-key").build().unwrap();
        assert_eq!(client.api_key(), "builder-key");
        assert_eq!(client.base_url(), DEFAULT_BASE_URL);
    }

    #[test]
    fn client_from_builder_custom_url() {
        let client = XaiClient::builder()
            .api_key("key")
            .base_url("https://custom.api.com/v2")
            .build()
            .unwrap();
        assert_eq!(client.base_url(), "https://custom.api.com/v2");
    }

    #[test]
    fn client_from_builder_custom_url_trims_trailing_slash() {
        let client = XaiClient::builder()
            .api_key("key")
            .base_url("https://custom.api.com/v2/")
            .build()
            .unwrap();
        assert_eq!(client.base_url(), "https://custom.api.com/v2");
    }

    // ── XaiClient::with_config ──────────────────────────────────────

    #[test]
    fn client_with_config() {
        let config = ClientConfig::new("config-key");
        let client = XaiClient::with_config(config).unwrap();
        assert_eq!(client.api_key(), "config-key");
    }

    #[tokio::test]
    async fn client_sets_default_user_agent_header() {
        let server = MockServer::start().await;
        Mock::given(method("GET"))
            .and(path("/models"))
            .and(header("user-agent", SDK_USER_AGENT))
            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                "object": "list",
                "data": []
            })))
            .expect(1)
            .mount(&server)
            .await;

        let client = XaiClient::builder()
            .api_key("test-key")
            .base_url(server.uri())
            .build()
            .unwrap();

        let response = client.models().list().await.unwrap();
        assert_eq!(response.object, "list");
        assert!(response.data.is_empty());
    }

    #[tokio::test]
    async fn client_retries_transient_http_statuses() {
        let server = MockServer::start().await;
        let call_count = Arc::new(AtomicUsize::new(0));
        let responder_count = Arc::clone(&call_count);

        Mock::given(method("GET"))
            .and(path("/models"))
            .respond_with(move |_req: &wiremock::Request| {
                let count = responder_count.fetch_add(1, Ordering::SeqCst);
                if count == 0 {
                    ResponseTemplate::new(503).set_body_json(json!({
                        "error": {"message": "temporary", "type": "server_error"}
                    }))
                } else {
                    ResponseTemplate::new(200).set_body_json(json!({
                        "object": "list",
                        "data": []
                    }))
                }
            })
            .mount(&server)
            .await;

        let client = XaiClient::builder()
            .api_key("test-key")
            .base_url(server.uri())
            .max_retries(1)
            .retry_backoff(Duration::ZERO, Duration::ZERO)
            .build()
            .unwrap();

        let list = client.models().list().await.unwrap();
        assert_eq!(list.object, "list");
        assert_eq!(call_count.load(Ordering::SeqCst), 2);
    }

    #[tokio::test]
    async fn client_disable_retries_returns_first_error_response() {
        let server = MockServer::start().await;

        Mock::given(method("GET"))
            .and(path("/models"))
            .respond_with(ResponseTemplate::new(503).set_body_json(json!({
                "error": {"message": "service unavailable", "type": "server_error"}
            })))
            .expect(1)
            .mount(&server)
            .await;

        let client = XaiClient::builder()
            .api_key("test-key")
            .base_url(server.uri())
            .disable_retries()
            .build()
            .unwrap();

        let err = client.models().list().await.unwrap_err();
        assert!(matches!(err, Error::Api { status: 503, .. }));
    }

    // ── XaiClient::encode_path ──────────────────────────────────────

    #[test]
    fn encode_path_no_special_chars() {
        let encoded = XaiClient::encode_path("simple-path");
        assert_eq!(encoded, "simple-path");
    }

    #[test]
    fn encode_path_with_spaces() {
        let encoded = XaiClient::encode_path("path with spaces");
        assert_eq!(encoded, "path%20with%20spaces");
    }

    #[test]
    fn encode_path_with_slashes() {
        let encoded = XaiClient::encode_path("a/b/c");
        assert_eq!(encoded, "a%2Fb%2Fc");
    }

    #[test]
    fn encode_path_with_special_chars() {
        let encoded = XaiClient::encode_path("file@name#1");
        assert!(encoded.contains("%40") || encoded.contains("@")); // @ may be encoded
        assert!(encoded.contains("%23")); // # is always encoded
    }

    #[test]
    fn encode_path_with_unicode() {
        let encoded = XaiClient::encode_path("héllo world");
        assert_eq!(encoded, "h%C3%A9llo%20world");
    }

    #[test]
    fn encode_path_empty_string() {
        let encoded = XaiClient::encode_path("");
        assert_eq!(encoded, "");
    }

    #[test]
    fn encode_path_with_percent() {
        let encoded = XaiClient::encode_path("100%done");
        assert!(encoded.contains("%25")); // % gets encoded as %25
    }

    #[test]
    fn apply_jitter_zero_factor_returns_same_delay() {
        let delay = Duration::from_millis(800);
        assert_eq!(apply_jitter(delay, 0.0), delay);
    }

    #[test]
    fn apply_jitter_stays_within_expected_bounds() {
        let delay = Duration::from_millis(1000);
        let jittered = apply_jitter(delay, 0.2);
        assert!(jittered >= Duration::from_millis(900));
        assert!(jittered <= Duration::from_millis(1100));
    }

    #[test]
    fn retry_delay_from_response_uses_retry_after_seconds_for_retryable_status() {
        let policy = RetryPolicy {
            max_retries: 2,
            initial_backoff: Duration::from_millis(200),
            max_backoff: Duration::from_secs(10),
            jitter_factor: 0.0,
        };
        let retry_after = HeaderValue::from_static("7");

        let delay = retry_delay_from_response(
            &policy,
            0,
            StatusCode::SERVICE_UNAVAILABLE,
            Some(&retry_after),
        );
        assert_eq!(delay, Duration::from_secs(7));
    }

    #[test]
    fn retry_delay_from_response_parses_http_date_retry_after() {
        let policy = RetryPolicy {
            max_retries: 2,
            initial_backoff: Duration::from_millis(200),
            max_backoff: Duration::from_secs(5),
            jitter_factor: 0.0,
        };
        let retry_after =
            HeaderValue::from_str(&fmt_http_date(SystemTime::now() + Duration::from_secs(600)))
                .unwrap();

        let delay = retry_delay_from_response(
            &policy,
            0,
            StatusCode::TOO_MANY_REQUESTS,
            Some(&retry_after),
        );
        assert_eq!(delay, policy.max_backoff);
    }

    #[test]
    fn retry_delay_from_response_with_past_http_date_returns_zero() {
        let policy = RetryPolicy {
            max_retries: 2,
            initial_backoff: Duration::from_millis(200),
            max_backoff: Duration::from_secs(5),
            jitter_factor: 0.0,
        };
        let retry_after = HeaderValue::from_str(&fmt_http_date(UNIX_EPOCH)).unwrap();

        let delay = retry_delay_from_response(
            &policy,
            1,
            StatusCode::TOO_MANY_REQUESTS,
            Some(&retry_after),
        );
        assert_eq!(delay, Duration::ZERO);
    }

    #[test]
    fn retry_delay_from_response_invalid_retry_after_falls_back_to_exponential() {
        let policy = RetryPolicy {
            max_retries: 2,
            initial_backoff: Duration::from_millis(250),
            max_backoff: Duration::from_secs(10),
            jitter_factor: 0.0,
        };
        let retry_after = HeaderValue::from_static("invalid");

        let delay = retry_delay_from_response(
            &policy,
            2,
            StatusCode::TOO_MANY_REQUESTS,
            Some(&retry_after),
        );
        assert_eq!(delay, Duration::from_millis(1000));
    }

    #[cfg(feature = "telemetry")]
    #[test]
    fn request_telemetry_fields_extract_method_and_url() {
        let http = reqwest::Client::new();
        let request = http.post("https://example.com/v1/test");
        let (method, url) = request_telemetry_fields(&request);
        assert_eq!(method, "POST");
        assert_eq!(url, "https://example.com/v1/test");
    }

    // ── API namespace accessors ─────────────────────────────────────

    #[test]
    fn client_responses_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.responses(); // Should not panic
    }

    #[test]
    fn client_auth_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.auth();
    }

    #[test]
    fn client_sync_facade_from_ref() {
        let client = XaiClient::new("key").unwrap();
        let sync = client.sync().unwrap();
        assert_eq!(sync.base_url(), client.base_url());
    }

    #[test]
    fn client_into_sync_facade() {
        let client = XaiClient::new("key").unwrap();
        let sync = client.into_sync().unwrap();
        assert_eq!(sync.base_url(), DEFAULT_BASE_URL);
    }

    #[test]
    fn client_chat_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.chat();
    }

    #[test]
    fn client_images_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.images();
    }

    #[test]
    fn client_videos_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.videos();
    }

    #[test]
    fn client_models_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.models();
    }

    #[test]
    fn client_batch_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.batch();
    }

    #[test]
    fn client_collections_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.collections();
    }

    #[test]
    fn client_documents_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.documents();
    }

    #[test]
    fn client_embeddings_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.embeddings();
    }

    #[test]
    fn client_tokenizer_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.tokenizer();
    }

    #[cfg(feature = "files")]
    #[test]
    fn client_files_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.files();
    }

    #[cfg(feature = "realtime")]
    #[test]
    fn client_realtime_api() {
        let client = XaiClient::new("key").unwrap();
        let _api = client.realtime();
    }
}