xai_rust/

sync.rs

//! Blocking (sync-style) client facade built on top of the async SDK.
//!
//! This module is intended for applications that cannot use `async/await`.
//! It runs SDK futures on an internal Tokio runtime and exposes blocking
//! request methods across the SDK API namespaces.

use std::future::Future;
use std::sync::Arc;
use std::time::Duration;
use tokio::runtime::{Builder, Runtime};

use crate::api::chat::{ChatCompletion, ChatCompletionBuilder};
#[cfg(feature = "files")]
use crate::api::files::UploadFileBuilder;
use crate::api::images::ImageGenerationBuilder;
use crate::api::models::{Model, ModelListResponse};
use crate::api::responses::{CreateResponseBuilder, DeferredResponsePoller, StatefulChat};
use crate::models::auth::ApiKeyInfo;
use crate::models::batch::{
    Batch, BatchListResponse, BatchRequest, BatchRequestListResponse, BatchResult,
    BatchResultListResponse,
};
use crate::models::collection::{
    AddDocumentsResponse, BatchGetDocumentsRequest, Collection, CollectionListResponse,
    CreateCollectionRequest, Document, DocumentListResponse, SearchRequest, SearchResponse,
    UpdateCollectionRequest,
};
#[cfg(feature = "files")]
use crate::models::file::{
    DeleteFileResponse, FileDownloadRequest, FileListResponse, FileObject, FilePurpose,
    FileUploadChunksRequest, FileUploadChunksResponse, FileUploadInitializeRequest,
    FileUploadInitializeResponse,
};
use crate::models::image::{ImageGenerationResponse, ImageResponseFormat};
use crate::models::message::{Message, MessageContent, Role};
use crate::models::response::{Response, ResponseFormat};
use crate::models::tokenizer::{TokenizeRequest, TokenizeResponse};
use crate::models::tool::{Tool, ToolCall, ToolChoice};
use crate::models::videos::Video;
use crate::{Error, Result, XaiClient};

const ASYNC_RUNTIME_GUARD_MESSAGE: &str =
    "SyncXaiClient cannot run inside an async runtime; use XaiClient for async contexts";
const DEFAULT_SYNC_TOOL_LOOP_MAX_ROUNDS: u32 = 8;

/// Blocking/sync facade for the xAI SDK.
#[derive(Clone)]
pub struct SyncXaiClient {
    client: XaiClient,
    runtime: Arc<Runtime>,
}

impl std::fmt::Debug for SyncXaiClient {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SyncXaiClient")
            .field("base_url", &self.base_url())
            .finish()
    }
}

impl SyncXaiClient {
    /// Create a blocking client from an API key.
    pub fn new(api_key: impl Into<String>) -> Result<Self> {
        Self::with_async_client(XaiClient::new(api_key)?)
    }

    /// Create a blocking client from the `XAI_API_KEY` environment variable.
    pub fn from_env() -> Result<Self> {
        Self::with_async_client(XaiClient::from_env()?)
    }

    /// Create a blocking facade from an existing async client.
    pub fn with_async_client(client: XaiClient) -> Result<Self> {
        let runtime = Builder::new_multi_thread().enable_all().build()?;
        Ok(Self {
            client,
            runtime: Arc::new(runtime),
        })
    }

    /// Get the wrapped async client.
    pub fn as_async_client(&self) -> &XaiClient {
        &self.client
    }

    /// Get the configured API base URL.
    pub fn base_url(&self) -> &str {
        self.client.base_url()
    }

    /// Access blocking Responses API helpers.
    pub fn responses(&self) -> SyncResponsesApi {
        SyncResponsesApi {
            client: self.clone(),
        }
    }

    /// Access blocking Auth API helpers.
    pub fn auth(&self) -> SyncAuthApi {
        SyncAuthApi {
            client: self.clone(),
        }
    }

    /// Access blocking Models API helpers.
    pub fn models(&self) -> SyncModelsApi {
        SyncModelsApi {
            client: self.clone(),
        }
    }

    /// Access blocking legacy Chat Completions API helpers.
    pub fn chat(&self) -> SyncChatApi {
        SyncChatApi {
            client: self.clone(),
        }
    }

    /// Access blocking Images API helpers.
    pub fn images(&self) -> SyncImagesApi {
        SyncImagesApi {
            client: self.clone(),
        }
    }

    /// Access blocking Videos API helpers.
    pub fn videos(&self) -> SyncVideosApi {
        SyncVideosApi {
            client: self.clone(),
        }
    }

    /// Access blocking Batch API helpers.
    pub fn batch(&self) -> SyncBatchApi {
        SyncBatchApi {
            client: self.clone(),
        }
    }

    /// Access blocking Collections API helpers.
    pub fn collections(&self) -> SyncCollectionsApi {
        SyncCollectionsApi {
            client: self.clone(),
        }
    }

    /// Access blocking Files API helpers.
    #[cfg(feature = "files")]
    pub fn files(&self) -> SyncFilesApi {
        SyncFilesApi {
            client: self.clone(),
        }
    }

    /// Access blocking Tokenizer API helpers.
    pub fn tokenizer(&self) -> SyncTokenizerApi {
        SyncTokenizerApi {
            client: self.clone(),
        }
    }

    /// Run an SDK future to completion on the internal runtime.
    ///
    /// This can be used for endpoints that do not yet have dedicated blocking wrappers.
    pub fn run<T, F>(&self, future: F) -> Result<T>
    where
        F: Future<Output = Result<T>>,
    {
        if tokio::runtime::Handle::try_current().is_ok() {
            return Err(Error::Config(ASYNC_RUNTIME_GUARD_MESSAGE.to_string()));
        }
        self.runtime.block_on(future)
    }
}

/// Blocking wrapper for `ResponsesApi`.
#[derive(Debug, Clone)]
pub struct SyncResponsesApi {
    client: SyncXaiClient,
}

impl SyncResponsesApi {
    /// Create a blocking response request builder.
    pub fn create(&self, model: impl Into<String>) -> SyncCreateResponseBuilder {
        SyncCreateResponseBuilder {
            client: self.client.clone(),
            inner: self.client.client.responses().create(model),
        }
    }

    /// Create a blocking deferred-response poller.
    pub fn deferred(&self, response_id: impl Into<String>) -> SyncDeferredResponsePoller {
        SyncDeferredResponsePoller {
            client: self.client.clone(),
            inner: self.client.client.responses().deferred(response_id),
        }
    }

    /// Create a blocking stateful chat handle.
    pub fn chat(&self, model: impl Into<String>) -> SyncStatefulChat {
        SyncStatefulChat {
            client: self.client.clone(),
            inner: self.client.client.responses().chat(model),
        }
    }

    /// Get a response by ID.
    pub fn get(&self, response_id: &str) -> Result<Response> {
        self.client
            .run(self.client.client.responses().get(response_id))
    }

    /// Delete a response by ID.
    pub fn delete(&self, response_id: &str) -> Result<()> {
        self.client
            .run(self.client.client.responses().delete(response_id))
    }

    /// Poll until output is available or attempts are exhausted.
    pub fn poll_until_ready(&self, response_id: &str, max_attempts: u32) -> Result<Response> {
        self.client.run(
            self.client
                .client
                .responses()
                .poll_until_ready(response_id, max_attempts),
        )
    }
}

/// Blocking wrapper for `ModelsApi`.
#[derive(Debug, Clone)]
pub struct SyncModelsApi {
    client: SyncXaiClient,
}

impl SyncModelsApi {
    /// List available models.
    pub fn list(&self) -> Result<ModelListResponse> {
        self.client.run(self.client.client.models().list())
    }

    /// Get a specific model by ID.
    pub fn get(&self, model_id: &str) -> Result<Model> {
        self.client.run(self.client.client.models().get(model_id))
    }
}

/// Blocking wrapper for `AuthApi`.
#[derive(Debug, Clone)]
pub struct SyncAuthApi {
    client: SyncXaiClient,
}

impl SyncAuthApi {
    /// Retrieve API key info.
    pub fn api_key(&self) -> Result<ApiKeyInfo> {
        self.client.run(self.client.client.auth().api_key())
    }
}

/// Blocking wrapper for `VideosApi`.
#[derive(Debug, Clone)]
pub struct SyncVideosApi {
    client: SyncXaiClient,
}

impl SyncVideosApi {
    /// Get a video by ID.
    pub fn get(&self, video_id: impl AsRef<str>) -> Result<Video> {
        self.client
            .run(self.client.client.videos().get(video_id.as_ref()))
    }
}

/// Blocking wrapper for `TokenizerApi`.
#[derive(Debug, Clone)]
pub struct SyncTokenizerApi {
    client: SyncXaiClient,
}

impl SyncTokenizerApi {
    /// Tokenize using a full request object.
    pub fn tokenize(&self, request: TokenizeRequest) -> Result<TokenizeResponse> {
        self.client
            .run(self.client.client.tokenizer().tokenize(request))
    }

    /// Tokenize using model and text values.
    pub fn tokenize_text(
        &self,
        model: impl Into<String>,
        text: impl Into<String>,
    ) -> Result<TokenizeResponse> {
        self.client
            .run(self.client.client.tokenizer().tokenize_text(model, text))
    }

    /// Count tokens for model and text.
    pub fn count_tokens(&self, model: impl Into<String>, text: impl Into<String>) -> Result<usize> {
        self.client
            .run(self.client.client.tokenizer().count_tokens(model, text))
    }
}

/// Blocking wrapper for the legacy `ChatApi`.
#[derive(Debug, Clone)]
pub struct SyncChatApi {
    client: SyncXaiClient,
}

impl SyncChatApi {
    /// Create a blocking chat completion request builder.
    #[allow(deprecated)]
    pub fn create(&self, model: impl Into<String>) -> SyncChatCompletionBuilder {
        SyncChatCompletionBuilder {
            client: self.client.clone(),
            inner: self.client.client.chat().create(model),
        }
    }
}

/// Blocking wrapper for `ChatCompletionBuilder`.
#[derive(Debug)]
pub struct SyncChatCompletionBuilder {
    client: SyncXaiClient,
    inner: ChatCompletionBuilder,
}

impl SyncChatCompletionBuilder {
    /// Add messages to the conversation.
    pub fn messages(mut self, messages: Vec<Message>) -> Self {
        self.inner = self.inner.messages(messages);
        self
    }

    /// Add a single message.
    pub fn message(mut self, message: Message) -> Self {
        self.inner = self.inner.message(message);
        self
    }

    /// Add tools.
    pub fn tools(mut self, tools: Vec<Tool>) -> Self {
        self.inner = self.inner.tools(tools);
        self
    }

    /// Set tool choice.
    pub fn tool_choice(mut self, choice: ToolChoice) -> Self {
        self.inner = self.inner.tool_choice(choice);
        self
    }

    /// Set temperature.
    pub fn temperature(mut self, temperature: f32) -> Self {
        self.inner = self.inner.temperature(temperature);
        self
    }

    /// Set top-p.
    pub fn top_p(mut self, top_p: f32) -> Self {
        self.inner = self.inner.top_p(top_p);
        self
    }

    /// Set max tokens.
    pub fn max_tokens(mut self, max_tokens: u32) -> Self {
        self.inner = self.inner.max_tokens(max_tokens);
        self
    }

    /// Set response format.
    pub fn response_format(mut self, format: ResponseFormat) -> Self {
        self.inner = self.inner.response_format(format);
        self
    }

    /// Set number of completions.
    pub fn n(mut self, n: u32) -> Self {
        self.inner = self.inner.n(n);
        self
    }

    /// Set stop sequences.
    pub fn stop(mut self, stop: Vec<String>) -> Self {
        self.inner = self.inner.stop(stop);
        self
    }

    /// Set presence penalty.
    pub fn presence_penalty(mut self, penalty: f32) -> Self {
        self.inner = self.inner.presence_penalty(penalty);
        self
    }

    /// Set frequency penalty.
    pub fn frequency_penalty(mut self, penalty: f32) -> Self {
        self.inner = self.inner.frequency_penalty(penalty);
        self
    }

    /// Send the request and return a chat completion.
    pub fn send(self) -> Result<ChatCompletion> {
        self.client.run(self.inner.send())
    }
}

/// Blocking wrapper for `ImagesApi`.
#[derive(Debug, Clone)]
pub struct SyncImagesApi {
    client: SyncXaiClient,
}

impl SyncImagesApi {
    /// Create a blocking image generation request builder.
    pub fn generate(
        &self,
        model: impl Into<String>,
        prompt: impl Into<String>,
    ) -> SyncImageGenerationBuilder {
        SyncImageGenerationBuilder {
            client: self.client.clone(),
            inner: self.client.client.images().generate(model, prompt),
        }
    }
}

/// Blocking wrapper for `ImageGenerationBuilder`.
#[derive(Debug)]
pub struct SyncImageGenerationBuilder {
    client: SyncXaiClient,
    inner: ImageGenerationBuilder,
}

impl SyncImageGenerationBuilder {
    /// Set number of images (1-10).
    pub fn n(mut self, n: u8) -> Self {
        self.inner = self.inner.n(n);
        self
    }

    /// Set response format.
    pub fn response_format(mut self, format: ImageResponseFormat) -> Self {
        self.inner = self.inner.response_format(format);
        self
    }

    /// Request URL format.
    pub fn url_format(mut self) -> Self {
        self.inner = self.inner.url_format();
        self
    }

    /// Request base64 format.
    pub fn base64_format(mut self) -> Self {
        self.inner = self.inner.base64_format();
        self
    }

    /// Send the request and return generated images.
    pub fn send(self) -> Result<ImageGenerationResponse> {
        self.client.run(self.inner.send())
    }
}

/// Blocking wrapper for `BatchApi`.
#[derive(Debug, Clone)]
pub struct SyncBatchApi {
    client: SyncXaiClient,
}

impl SyncBatchApi {
    /// Create a batch.
    pub fn create(&self, name: impl Into<String>) -> Result<Batch> {
        self.client.run(self.client.client.batch().create(name))
    }

    /// Get batch metadata by ID.
    pub fn get(&self, batch_id: impl AsRef<str>) -> Result<Batch> {
        self.client.run(self.client.client.batch().get(batch_id))
    }

    /// List batches.
    pub fn list(&self) -> Result<BatchListResponse> {
        self.client.run(self.client.client.batch().list())
    }

    /// List batches with pagination options.
    pub fn list_with_options(
        &self,
        limit: Option<u32>,
        next_token: Option<&str>,
    ) -> Result<BatchListResponse> {
        self.client.run(
            self.client
                .client
                .batch()
                .list_with_options(limit, next_token),
        )
    }

    /// Cancel a batch.
    pub fn cancel(&self, batch_id: impl AsRef<str>) -> Result<Batch> {
        self.client.run(self.client.client.batch().cancel(batch_id))
    }

    /// Add requests to a batch.
    pub fn add_requests(
        &self,
        batch_id: impl AsRef<str>,
        requests: Vec<BatchRequest>,
    ) -> Result<()> {
        self.client
            .run(self.client.client.batch().add_requests(batch_id, requests))
    }

    /// List requests in a batch.
    pub fn list_requests(&self, batch_id: impl AsRef<str>) -> Result<BatchRequestListResponse> {
        self.client
            .run(self.client.client.batch().list_requests(batch_id))
    }

    /// List requests in a batch with pagination options.
    pub fn list_requests_with_options(
        &self,
        batch_id: impl AsRef<str>,
        limit: Option<u32>,
        next_token: Option<&str>,
    ) -> Result<BatchRequestListResponse> {
        self.client.run(
            self.client
                .client
                .batch()
                .list_requests_with_options(batch_id, limit, next_token),
        )
    }

    /// List results for a batch.
    pub fn list_results(&self, batch_id: impl AsRef<str>) -> Result<BatchResultListResponse> {
        self.client
            .run(self.client.client.batch().list_results(batch_id))
    }

    /// List results for a batch with pagination options.
    pub fn list_results_with_options(
        &self,
        batch_id: impl AsRef<str>,
        limit: Option<u32>,
        next_token: Option<&str>,
    ) -> Result<BatchResultListResponse> {
        self.client.run(
            self.client
                .client
                .batch()
                .list_results_with_options(batch_id, limit, next_token),
        )
    }

    /// Get a specific request result.
    pub fn get_result(
        &self,
        batch_id: impl AsRef<str>,
        request_id: impl AsRef<str>,
    ) -> Result<BatchResult> {
        self.client
            .run(self.client.client.batch().get_result(batch_id, request_id))
    }
}

/// Blocking wrapper for `CollectionsApi`.
#[derive(Debug, Clone)]
pub struct SyncCollectionsApi {
    client: SyncXaiClient,
}

impl SyncCollectionsApi {
    /// Create a collection from a request object.
    pub fn create(&self, request: CreateCollectionRequest) -> Result<Collection> {
        self.client
            .run(self.client.client.collections().create(request))
    }

    /// Create a collection with only a name.
    pub fn create_named(&self, name: impl Into<String>) -> Result<Collection> {
        self.client
            .run(self.client.client.collections().create_named(name))
    }

    /// Get a collection by ID.
    pub fn get(&self, collection_id: impl AsRef<str>) -> Result<Collection> {
        self.client
            .run(self.client.client.collections().get(collection_id))
    }

    /// List collections.
    pub fn list(&self) -> Result<CollectionListResponse> {
        self.client.run(self.client.client.collections().list())
    }

    /// List collections with pagination options.
    pub fn list_with_options(
        &self,
        limit: Option<u32>,
        next_token: Option<&str>,
    ) -> Result<CollectionListResponse> {
        self.client.run(
            self.client
                .client
                .collections()
                .list_with_options(limit, next_token),
        )
    }

    /// Delete a collection.
    pub fn delete(&self, collection_id: impl AsRef<str>) -> Result<()> {
        self.client
            .run(self.client.client.collections().delete(collection_id))
    }

    /// Add documents to a collection.
    pub fn add_documents(
        &self,
        collection_id: impl AsRef<str>,
        documents: Vec<Document>,
    ) -> Result<AddDocumentsResponse> {
        self.client.run(
            self.client
                .client
                .collections()
                .add_documents(collection_id, documents),
        )
    }

    /// Add a single document to a collection.
    pub fn add_document(
        &self,
        collection_id: impl AsRef<str>,
        document: Document,
    ) -> Result<String> {
        self.client.run(
            self.client
                .client
                .collections()
                .add_document(collection_id, document),
        )
    }

    /// Update a collection.
    pub fn update(
        &self,
        collection_id: impl AsRef<str>,
        request: UpdateCollectionRequest,
    ) -> Result<Collection> {
        self.client.run(
            self.client
                .client
                .collections()
                .update(collection_id, request),
        )
    }

    /// Add or replace a document by ID.
    pub fn upsert_document(
        &self,
        collection_id: impl AsRef<str>,
        document: Document,
    ) -> Result<Document> {
        self.client.run(
            self.client
                .client
                .collections()
                .upsert_document(collection_id, document),
        )
    }

    /// Get multiple documents by IDs.
    pub fn batch_get_documents(
        &self,
        collection_id: impl AsRef<str>,
        request: BatchGetDocumentsRequest,
    ) -> Result<DocumentListResponse> {
        self.client.run(
            self.client
                .client
                .collections()
                .batch_get_documents(collection_id, request),
        )
    }

    /// List documents in a collection.
    pub fn list_documents(&self, collection_id: impl AsRef<str>) -> Result<DocumentListResponse> {
        self.client.run(
            self.client
                .client
                .collections()
                .list_documents(collection_id),
        )
    }

    /// List documents in a collection with pagination options.
    pub fn list_documents_with_options(
        &self,
        collection_id: impl AsRef<str>,
        limit: Option<u32>,
        next_token: Option<&str>,
    ) -> Result<DocumentListResponse> {
        self.client.run(
            self.client
                .client
                .collections()
                .list_documents_with_options(collection_id, limit, next_token),
        )
    }

    /// Get a document by ID.
    pub fn get_document(
        &self,
        collection_id: impl AsRef<str>,
        document_id: impl AsRef<str>,
    ) -> Result<Document> {
        self.client.run(
            self.client
                .client
                .collections()
                .get_document(collection_id, document_id),
        )
    }

    /// Delete a document from a collection.
    pub fn delete_document(
        &self,
        collection_id: impl AsRef<str>,
        document_id: impl AsRef<str>,
    ) -> Result<()> {
        self.client.run(
            self.client
                .client
                .collections()
                .delete_document(collection_id, document_id),
        )
    }

    /// Search a collection with a request object.
    pub fn search(
        &self,
        collection_id: impl AsRef<str>,
        request: SearchRequest,
    ) -> Result<SearchResponse> {
        self.client.run(
            self.client
                .client
                .collections()
                .search(collection_id, request),
        )
    }

    /// Search a collection with a query string.
    pub fn search_query(
        &self,
        collection_id: impl AsRef<str>,
        query: impl Into<String>,
    ) -> Result<SearchResponse> {
        self.client.run(
            self.client
                .client
                .collections()
                .search_query(collection_id, query),
        )
    }
}

/// Blocking wrapper for `FilesApi`.
#[cfg(feature = "files")]
#[derive(Debug, Clone)]
pub struct SyncFilesApi {
    client: SyncXaiClient,
}

#[cfg(feature = "files")]
impl SyncFilesApi {
    /// List uploaded files.
    pub fn list(&self) -> Result<FileListResponse> {
        self.client.run(self.client.client.files().list())
    }

    /// Get file metadata by ID.
    pub fn get(&self, file_id: &str) -> Result<FileObject> {
        self.client.run(self.client.client.files().get(file_id))
    }

    /// Get raw file bytes by ID.
    pub fn content(&self, file_id: &str) -> Result<Vec<u8>> {
        self.client.run(self.client.client.files().content(file_id))
    }

    /// Delete a file by ID.
    pub fn delete(&self, file_id: &str) -> Result<DeleteFileResponse> {
        self.client.run(self.client.client.files().delete(file_id))
    }

    /// Create a blocking file upload request builder.
    pub fn upload(&self, filename: impl Into<String>, data: Vec<u8>) -> SyncUploadFileBuilder {
        SyncUploadFileBuilder {
            client: self.client.clone(),
            inner: self.client.client.files().upload(filename, data),
        }
    }

    /// Download file bytes with the explicit download endpoint.
    pub fn download(&self, request: FileDownloadRequest) -> Result<Vec<u8>> {
        self.client
            .run(self.client.client.files().download(request))
    }

    /// Initialize a multi-part upload session.
    pub fn initialize_upload(
        &self,
        request: FileUploadInitializeRequest,
    ) -> Result<FileUploadInitializeResponse> {
        self.client
            .run(self.client.client.files().initialize_upload(request))
    }

    /// Upload a file chunk.
    pub fn upload_chunks(
        &self,
        request: FileUploadChunksRequest,
    ) -> Result<FileUploadChunksResponse> {
        self.client
            .run(self.client.client.files().upload_chunks(request))
    }
}

/// Blocking wrapper for `UploadFileBuilder`.
#[cfg(feature = "files")]
#[derive(Debug)]
pub struct SyncUploadFileBuilder {
    client: SyncXaiClient,
    inner: UploadFileBuilder,
}

#[cfg(feature = "files")]
impl SyncUploadFileBuilder {
    /// Set the file purpose.
    pub fn purpose(mut self, purpose: FilePurpose) -> Self {
        self.inner = self.inner.purpose(purpose);
        self
    }

    /// Send the upload request and return file metadata.
    pub fn send(self) -> Result<FileObject> {
        self.client.run(self.inner.send())
    }
}

/// Blocking wrapper for `CreateResponseBuilder`.
#[derive(Debug)]
pub struct SyncCreateResponseBuilder {
    client: SyncXaiClient,
    inner: CreateResponseBuilder,
}

impl SyncCreateResponseBuilder {
    /// Add a message.
    pub fn message(mut self, role: Role, content: impl Into<MessageContent>) -> Self {
        self.inner = self.inner.message(role, content);
        self
    }

    /// Add a system message.
    pub fn system(mut self, content: impl Into<String>) -> Self {
        self.inner = self.inner.system(content);
        self
    }

    /// Add a user message.
    pub fn user(mut self, content: impl Into<MessageContent>) -> Self {
        self.inner = self.inner.user(content);
        self
    }

    /// Add an assistant message.
    pub fn assistant(mut self, content: impl Into<String>) -> Self {
        self.inner = self.inner.assistant(content);
        self
    }

    /// Add a user message with image content.
    pub fn user_with_image(
        mut self,
        text: impl Into<String>,
        image_url: impl Into<String>,
    ) -> Self {
        self.inner = self.inner.user_with_image(text, image_url);
        self
    }

    /// Add pre-built messages.
    pub fn messages(mut self, messages: Vec<Message>) -> Self {
        self.inner = self.inner.messages(messages);
        self
    }

    /// Add a tool.
    pub fn tool(mut self, tool: Tool) -> Self {
        self.inner = self.inner.tool(tool);
        self
    }

    /// Add multiple tools.
    pub fn tools(mut self, tools: Vec<Tool>) -> Self {
        self.inner = self.inner.tools(tools);
        self
    }

    /// Set tool choice.
    pub fn tool_choice(mut self, choice: ToolChoice) -> Self {
        self.inner = self.inner.tool_choice(choice);
        self
    }

    /// Set temperature.
    pub fn temperature(mut self, temperature: f32) -> Self {
        self.inner = self.inner.temperature(temperature);
        self
    }

    /// Set top-p.
    pub fn top_p(mut self, top_p: f32) -> Self {
        self.inner = self.inner.top_p(top_p);
        self
    }

    /// Set max tokens.
    pub fn max_tokens(mut self, max_tokens: u32) -> Self {
        self.inner = self.inner.max_tokens(max_tokens);
        self
    }

    /// Override retry attempts for this request.
    pub fn max_retries(mut self, max_retries: u32) -> Self {
        self.inner = self.inner.max_retries(max_retries);
        self
    }

    /// Disable retries for this request.
    pub fn disable_retries(mut self) -> Self {
        self.inner = self.inner.disable_retries();
        self
    }

    /// Override retry backoff for this request.
    pub fn retry_backoff(mut self, initial: Duration, max: Duration) -> Self {
        self.inner = self.inner.retry_backoff(initial, max);
        self
    }

    /// Override retry jitter for this request.
    pub fn retry_jitter(mut self, factor: f64) -> Self {
        self.inner = self.inner.retry_jitter(factor);
        self
    }

    /// Set response format.
    pub fn response_format(mut self, format: ResponseFormat) -> Self {
        self.inner = self.inner.response_format(format);
        self
    }

    /// Request JSON output.
    pub fn json_output(mut self) -> Self {
        self.inner = self.inner.json_output();
        self
    }

    /// Include additional response fields.
    pub fn include(mut self, fields: Vec<String>) -> Self {
        self.inner = self.inner.include(fields);
        self
    }

    /// Include inline citations.
    pub fn with_inline_citations(mut self) -> Self {
        self.inner = self.inner.with_inline_citations();
        self
    }

    /// Include verbose streaming metadata.
    pub fn with_verbose_streaming(mut self) -> Self {
        self.inner = self.inner.with_verbose_streaming();
        self
    }

    /// Set response storage behavior.
    pub fn store(mut self, store: bool) -> Self {
        self.inner = self.inner.store(store);
        self
    }

    /// Send the request and return a response.
    pub fn send(self) -> Result<Response> {
        self.client.run(self.inner.send())
    }
}

/// Blocking wrapper for `DeferredResponsePoller`.
#[derive(Debug, Clone)]
pub struct SyncDeferredResponsePoller {
    client: SyncXaiClient,
    inner: DeferredResponsePoller,
}

impl SyncDeferredResponsePoller {
    /// Set max polling attempts.
    pub fn max_attempts(mut self, max_attempts: u32) -> Self {
        self.inner = self.inner.max_attempts(max_attempts);
        self
    }

    /// Set a fixed polling interval.
    pub fn poll_interval(mut self, interval: Duration) -> Self {
        self.inner = self.inner.poll_interval(interval);
        self
    }

    /// Set exponential polling backoff bounds.
    pub fn poll_backoff(mut self, initial: Duration, max: Duration) -> Self {
        self.inner = self.inner.poll_backoff(initial, max);
        self
    }

    /// Wait until response output becomes available.
    pub fn wait(self) -> Result<Response> {
        self.client.run(self.inner.wait())
    }
}

/// Blocking wrapper for stateful chat interactions.
#[derive(Debug, Clone)]
pub struct SyncStatefulChat {
    client: SyncXaiClient,
    inner: StatefulChat,
}

impl SyncStatefulChat {
    /// Append a message to local state.
    pub fn append(&mut self, role: Role, content: impl Into<MessageContent>) -> &mut Self {
        self.inner.append(role, content);
        self
    }

    /// Append a system message.
    pub fn append_system(&mut self, content: impl Into<String>) -> &mut Self {
        self.inner.append_system(content);
        self
    }

    /// Append a user message.
    pub fn append_user(&mut self, content: impl Into<MessageContent>) -> &mut Self {
        self.inner.append_user(content);
        self
    }

    /// Append an assistant message.
    pub fn append_assistant(&mut self, content: impl Into<String>) -> &mut Self {
        self.inner.append_assistant(content);
        self
    }

    /// Append a tool result message.
    pub fn append_tool_result(
        &mut self,
        tool_call_id: impl Into<String>,
        content: impl Into<String>,
    ) -> &mut Self {
        self.inner.append_tool_result(tool_call_id, content);
        self
    }

    /// Append a pre-built message.
    pub fn append_message(&mut self, message: Message) -> &mut Self {
        self.inner.append_message(message);
        self
    }

    /// Get local message history.
    pub fn messages(&self) -> &[Message] {
        self.inner.messages()
    }

    /// Get pending tool calls from the latest sampled response.
    pub fn pending_tool_calls(&self) -> &[ToolCall] {
        self.inner.pending_tool_calls()
    }

    /// Take and clear pending tool calls.
    pub fn take_pending_tool_calls(&mut self) -> Vec<ToolCall> {
        self.inner.take_pending_tool_calls()
    }

    /// Clear local chat state.
    pub fn clear(&mut self) -> &mut Self {
        self.inner.clear();
        self
    }

    /// Sample with current local message history.
    pub fn sample(&self) -> Result<Response> {
        self.client.run(self.inner.sample())
    }

    /// Append assistant text from a sampled response.
    pub fn append_response_text(&mut self, response: &Response) -> &mut Self {
        self.inner.append_response_text(response);
        self
    }

    /// Append response semantics and pending tool calls to local state.
    pub fn append_response_semantics(&mut self, response: &Response) -> &mut Self {
        self.inner.append_response_semantics(response);
        self
    }

    /// Sample and append response semantics.
    pub fn sample_and_append(&mut self) -> Result<Response> {
        self.client.run(self.inner.sample_and_append())
    }

    /// Run a blocking tool loop with default max rounds.
    pub fn sample_with_tool_loop<H>(&mut self, handler: H) -> Result<Response>
    where
        H: FnMut(ToolCall) -> Result<String>,
    {
        self.sample_with_tool_handler(DEFAULT_SYNC_TOOL_LOOP_MAX_ROUNDS, handler)
    }

    /// Run a blocking tool loop with explicit max rounds.
    pub fn sample_with_tool_handler<H>(
        &mut self,
        max_rounds: u32,
        mut handler: H,
    ) -> Result<Response>
    where
        H: FnMut(ToolCall) -> Result<String>,
    {
        self.client.run(
            self.inner
                .sample_with_tool_handler(max_rounds, move |call| {
                    let next = handler(call);
                    async move { next }
                }),
        )
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;
    use std::env;
    use std::sync::atomic::{AtomicUsize, Ordering};
    use wiremock::matchers::{body_partial_json, method, path};
    use wiremock::{Mock, MockServer, ResponseTemplate};

    #[test]
    fn sync_responses_create_send_returns_text() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/responses"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "resp_sync",
                    "model": "grok-4",
                    "output": [{
                        "type": "message",
                        "role": "assistant",
                        "content": [{"type": "text", "text": "sync hello"}]
                    }],
                    "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let response = client
            .responses()
            .create("grok-4")
            .user("hello")
            .send()
            .unwrap();

        assert_eq!(response.output_text().as_deref(), Some("sync hello"));
    }

    #[test]
    fn sync_responses_create_builder_forwards_extended_request_fields() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/responses"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();

                    assert_eq!(body["model"], "grok-4");
                    assert_eq!(body["input"].as_array().unwrap().len(), 4);
                    assert_eq!(body["input"][0]["role"], "system");
                    assert_eq!(body["input"][1]["role"], "user");
                    assert_eq!(body["input"][2]["role"], "assistant");
                    assert_eq!(body["input"][3]["role"], "user");
                    assert_eq!(body["input"][3]["content"][0]["type"], "text");
                    assert_eq!(body["input"][3]["content"][1]["type"], "image_url");
                    assert_eq!(body["top_p"], 1.0);
                    assert_eq!(body["temperature"], 2.0);
                    assert_eq!(body["max_tokens"], 64);
                    assert_eq!(body["tool_choice"]["function"]["name"], "get_weather");
                    assert_eq!(body["tools"].as_array().unwrap().len(), 2);
                    assert_eq!(body["response_format"]["type"], "json_object");
                    assert_eq!(body["store"], false);
                    assert_eq!(
                        body["include"],
                        serde_json::json!(["custom", "inline_citations", "verbose_streaming"])
                    );

                    ResponseTemplate::new(200).set_body_json(json!({
                        "id": "resp_sync_extended",
                        "model": "grok-4",
                        "output": [{
                            "type": "message",
                            "role": "assistant",
                            "content": [{"type": "text", "text": "extended sync"}]
                        }],
                        "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                    }))
                })
                .mount(&server)
                .await;
        });

        let weather_tool = Tool::function(
            "get_weather",
            "Get weather",
            serde_json::json!({
                "type": "object",
                "properties": {"location": {"type": "string"}}
            }),
        );
        let map_tool = Tool::function(
            "get_map",
            "Get map",
            serde_json::json!({
                "type": "object",
                "properties": {"where": {"type": "string"}}
            }),
        );

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let response = client
            .responses()
            .create("grok-4")
            .system("You are a concise assistant.")
            .user("Hello")
            .assistant("Hi")
            .user_with_image("Look", "https://example.com/image.jpg")
            .tool(weather_tool)
            .tools(vec![map_tool])
            .tool_choice(ToolChoice::function("get_weather"))
            .temperature(2.4)
            .top_p(1.2)
            .max_tokens(64)
            .max_retries(2)
            .retry_backoff(Duration::from_millis(1), Duration::from_millis(2))
            .retry_jitter(0.25)
            .response_format(ResponseFormat::json_object())
            .json_output()
            .include(vec!["custom".to_string()])
            .with_inline_citations()
            .with_verbose_streaming()
            .store(false)
            .send()
            .unwrap();

        assert_eq!(response.output_text().as_deref(), Some("extended sync"));
    }

    #[test]
    fn sync_responses_create_builder_retry_controls_are_honored() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());
        let attempts = Arc::new(AtomicUsize::new(0));
        let attempts_for_responder = Arc::clone(&attempts);

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/responses"))
                .respond_with(move |_req: &wiremock::Request| {
                    let count = attempts_for_responder.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!({
                            "id": "resp_sync_retry",
                            "model": "grok-4",
                            "output": [{
                                "type": "message",
                                "role": "assistant",
                                "content": [{"type": "text", "text": "retried"}]
                            }],
                            "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                        }))
                    }
                })
                .mount(&server)
                .await;
        });

        let async_client = XaiClient::builder()
            .api_key("test-key")
            .base_url(server.uri())
            .disable_retries()
            .retry_backoff(Duration::from_millis(0), Duration::from_millis(0))
            .build()
            .unwrap();

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let response = client
            .responses()
            .create("grok-4")
            .user("hi")
            .max_retries(1)
            .retry_jitter(2.0)
            .send()
            .unwrap();

        assert_eq!(response.output_text().as_deref(), Some("retried"));
        assert_eq!(attempts.load(Ordering::SeqCst), 2);
    }

    #[test]
    fn sync_stateful_chat_builder_operations() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());
        let sample_calls = Arc::new(AtomicUsize::new(0));
        let sample_calls_for_responder = Arc::clone(&sample_calls);

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/responses"))
                .and(body_partial_json(json!({"model": "grok-4"})))
                .respond_with(move |_req: &wiremock::Request| {
                    let call_count = sample_calls_for_responder.fetch_add(1, Ordering::SeqCst);
                    if call_count == 0 {
                        ResponseTemplate::new(200).set_body_json(json!({
                            "id": "resp_sync_state",
                            "model": "grok-4",
                            "output": [{
                                "type": "message",
                                "role": "assistant",
                                "content": [{"type": "text", "text": "first"}]
                            }],
                            "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                        }))
                    } else {
                        ResponseTemplate::new(200).set_body_json(json!({
                            "id": "resp_sync_state_tool",
                            "model": "grok-4",
                            "output": [{
                                "type": "function_call",
                                "id": "tool_1",
                                "function": {
                                    "name": "echo",
                                    "arguments": "{\"text\":\"value\"}"
                                }
                            }],
                            "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                        }))
                    }
                })
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let mut chat = client.responses().chat("grok-4");

        chat.append_system("system prompt")
            .append_user("Hello")
            .append_assistant("seeded")
            .append_message(Message {
                role: Role::User,
                content: MessageContent::Text("injected".to_string()),
                name: None,
                tool_call_id: None,
            });

        let first = chat.sample().unwrap();
        assert_eq!(first.output_text().as_deref(), Some("first"));

        chat.append_response_text(&first);
        assert!(chat
            .messages()
            .iter()
            .any(|m| matches!(m.role, Role::Assistant)));
        assert!(chat.messages().len() >= 5);

        let tool_response = chat.sample_and_append().unwrap();
        assert_eq!(tool_response.output_text().as_deref(), None);
        assert_eq!(chat.pending_tool_calls().len(), 1);

        let pending = chat.take_pending_tool_calls();
        assert_eq!(pending.len(), 1);
        assert_eq!(pending[0].id, "tool_1");

        chat.append_tool_result("tool_1", r#"{"text":"value"}"#);
        assert_eq!(chat.messages().len(), 6);
        assert_eq!(chat.messages().last().map(|m| &m.role), Some(&Role::Tool));
    }

    #[test]
    fn sync_stateful_chat_tool_loop_runs_to_completion() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());
        let call_count = Arc::new(AtomicUsize::new(0));
        let call_count_for_responder = Arc::clone(&call_count);

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/responses"))
                .respond_with(move |_req: &wiremock::Request| {
                    let count = call_count_for_responder.fetch_add(1, Ordering::SeqCst);
                    if count == 0 {
                        ResponseTemplate::new(200).set_body_json(json!({
                            "id": "resp_sync_loop_1",
                            "model": "grok-4",
                            "output": [{
                                "type": "function_call",
                                "id": "loop_tool",
                                "function": {
                                    "name": "calc",
                                    "arguments": "{}"
                                }
                            }],
                            "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                        }))
                    } else {
                        ResponseTemplate::new(200).set_body_json(json!( {
                            "id": "resp_sync_loop_2",
                            "model": "grok-4",
                            "output": [{
                                "type": "message",
                                "role": "assistant",
                                "content": [{"type": "text", "text": "looped"}]
                            }],
                            "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                        }))
                    }
                })
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let mut chat = client.responses().chat("grok-4");
        chat.append_system("loop test").append_user("run");

        let response = chat
            .sample_with_tool_loop(|call| {
                if call.id == "loop_tool" {
                    Ok(r#"{"result":"ok"}"#.to_string())
                } else {
                    Ok("{}".to_string())
                }
            })
            .unwrap();

        assert_eq!(response.output_text().as_deref(), Some("looped"));
        assert_eq!(call_count.load(Ordering::SeqCst), 2);
        assert_eq!(chat.messages().len(), 4);
    }

    #[test]
    fn sync_deferred_response_poller_uses_polling_methods() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());
        let poll_count = Arc::new(AtomicUsize::new(0));
        let poll_count_clone = Arc::clone(&poll_count);
        let poll_backoff_count = Arc::clone(&poll_count);

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/responses/resp_poll_interval"))
                .respond_with(move |_req: &wiremock::Request| {
                    let count = poll_count_clone.fetch_add(1, Ordering::SeqCst);
                    if count == 0 {
                        ResponseTemplate::new(200).set_body_json(json!({
                            "id": "resp_poll_interval",
                            "model": "grok-4",
                            "output": [],
                            "usage": {"prompt_tokens": 1, "completion_tokens": 0, "total_tokens": 1}
                        }))
                    } else {
                        ResponseTemplate::new(200).set_body_json(json!({
                            "id": "resp_poll_interval",
                            "model": "grok-4",
                            "output": [{
                                "type": "message",
                                "role": "assistant",
                                "content": [{"type": "text", "text": "done"}]
                            }],
                            "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                        }))
                    }
                })
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/responses/resp_poll_backoff"))
                .respond_with(move |_req: &wiremock::Request| {
                    let count = poll_backoff_count.fetch_add(1, Ordering::SeqCst);
                    if count == 0 {
                        ResponseTemplate::new(200).set_body_json(json!({
                            "id": "resp_poll_backoff",
                            "model": "grok-4",
                            "output": [],
                            "usage": {"prompt_tokens": 1, "completion_tokens": 0, "total_tokens": 1}
                        }))
                    } else {
                        ResponseTemplate::new(200).set_body_json(json!({
                            "id": "resp_poll_backoff",
                            "model": "grok-4",
                            "output": [{
                                "type": "message",
                                "role": "assistant",
                                "content": [{"type": "text", "text": "ready"}]
                            }],
                            "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                        }))
                    }
                })
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();

        let poll_interval_response = client
            .responses()
            .deferred("resp_poll_interval")
            .max_attempts(3)
            .poll_interval(Duration::from_millis(0))
            .wait()
            .unwrap();
        assert_eq!(
            poll_interval_response.output_text().as_deref(),
            Some("done")
        );

        let poll_backoff_response = client
            .responses()
            .deferred("resp_poll_backoff")
            .poll_backoff(Duration::from_millis(0), Duration::from_millis(0))
            .wait()
            .unwrap();
        assert_eq!(
            poll_backoff_response.output_text().as_deref(),
            Some("ready")
        );
    }

    #[test]
    fn sync_client_new_and_from_env_cover_unused_entry_points() {
        let previous_key = env::var_os("XAI_API_KEY");

        env::set_var("XAI_API_KEY", "sync-env-key");
        let from_env_client = SyncXaiClient::from_env().unwrap();
        let formatted = format!("{from_env_client:?}");
        assert!(formatted.contains("SyncXaiClient"));
        assert_eq!(from_env_client.base_url(), crate::config::DEFAULT_BASE_URL);

        let new_client = SyncXaiClient::new("inline-test-key").unwrap();
        assert_eq!(new_client.base_url(), crate::config::DEFAULT_BASE_URL);

        if let Some(previous_key) = previous_key {
            env::set_var("XAI_API_KEY", previous_key);
        } else {
            env::remove_var("XAI_API_KEY");
        }
    }

    #[test]
    fn sync_models_and_tokenizer_wrappers_cover_missing_methods() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/models/grok-4"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "grok-4",
                    "object": "model",
                    "owned_by": "xai"
                })))
                .mount(&server)
                .await;

            Mock::given(method("POST"))
                .and(path("/tokenize-text"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    match body["text"].as_str().unwrap_or_default() {
                        "sync tokenize" => ResponseTemplate::new(200).set_body_json(json!({
                            "tokens": [9, 8, 7],
                            "token_count": 3
                        })),
                        _ => ResponseTemplate::new(200).set_body_json(json!({
                            "tokens": [1, 2],
                            "token_count": 2
                        })),
                    }
                })
                .mount(&server)
                .await;
        });

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

        let model = client.models().get("grok-4").unwrap();
        assert_eq!(model.id, "grok-4");

        let tokenized = client
            .tokenizer()
            .tokenize(TokenizeRequest::new("grok-4", "sync tokenize"))
            .unwrap();
        assert_eq!(tokenized.token_count, 3);

        let tokenized_text = client
            .tokenizer()
            .tokenize_text("grok-4", "sync tokenize text")
            .unwrap();
        assert_eq!(tokenized_text.token_count, 2);
    }

    #[test]
    fn sync_builder_wrappers_cover_uncovered_paths() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/responses"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    assert_eq!(body["input"][0]["role"], "user");
                    assert_eq!(body["input"][1]["role"], "assistant");
                    assert_eq!(body["response_format"]["type"], "json_object");
                    ResponseTemplate::new(200).set_body_json(json!({
                        "id": "resp_sync_wrappers",
                        "model": "grok-4",
                        "output": [{
                            "type": "message",
                            "role": "assistant",
                            "content": [{"type": "text", "text": "wrapped"}]
                        }],
                        "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                    }))
                })
                .mount(&server)
                .await;

            Mock::given(method("POST"))
                .and(path("/chat/completions"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    assert_eq!(body["model"], "grok-4");
                    assert_eq!(body["top_p"], 0.8);
                    assert_eq!(body["response_format"]["type"], "json_object");
                    assert_eq!(body["messages"].as_array().unwrap().len(), 2);

                    ResponseTemplate::new(200).set_body_json(json!( {
                        "id": "chat_sync_wrappers",
                        "object": "chat.completion",
                        "created": 1700000000,
                        "model": "grok-4",
                        "choices": [{
                            "index": 0,
                            "message": {
                                "role": "assistant",
                                "content": "wrapped"
                            },
                            "finish_reason": "stop"
                        }]
                    }))
                })
                .mount(&server)
                .await;

            Mock::given(method("POST"))
                .and(path("/images/generations"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    assert_eq!(body["response_format"], "url");

                    ResponseTemplate::new(200).set_body_json(json!({
                        "created": 1700000000,
                        "data": [{
                            "url": "https://example.com/wrapped.png"
                        }]
                    }))
                })
                .mount(&server)
                .await;
        });

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

        client
            .responses()
            .create("grok-4")
            .message(Role::User, "hello")
            .messages(vec![Message::assistant("from messages")])
            .disable_retries()
            .response_format(ResponseFormat::json_object())
            .send()
            .unwrap();

        client
            .chat()
            .create("grok-4")
            .messages(vec![Message::system("system"), Message::user("hello")])
            .top_p(0.8)
            .response_format(ResponseFormat::json_object())
            .send()
            .unwrap();

        client
            .images()
            .generate("grok-2-image", "bridge at dusk")
            .response_format(ImageResponseFormat::B64Json)
            .url_format()
            .send()
            .unwrap();
    }

    #[test]
    fn sync_batch_and_collection_wrappers_cover_remaining_paths() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/batches/batch_sync:cancel"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "batch_sync",
                    "name": "wrapped-batch",
                    "status": "cancelled",
                    "request_count": 0,
                    "completed_count": 0,
                    "failed_count": 0
                })))
                .mount(&server)
                .await;

            Mock::given(method("POST"))
                .and(path("/batches/batch_sync/requests"))
                .respond_with(ResponseTemplate::new(200))
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/batches/batch_sync/requests"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "data": [{
                        "id": "batch_req_1",
                        "custom_id": "custom-1",
                        "status": "completed"
                    }],
                    "next_token": "tok_1"
                })))
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/batches/batch_sync/results"))
                .respond_with(move |req: &wiremock::Request| {
                    let query = req.url.query().unwrap_or("");
                    if query.is_empty() {
                        ResponseTemplate::new(200).set_body_json(json!({
                            "data": [{
                                "batch_request_id": "br_1",
                                "custom_id": "custom-1",
                                "error_code": 0,
                                "response": {
                                    "id": "resp_1",
                                    "model": "grok-4",
                                    "output": [{
                                        "type": "message",
                                        "role": "assistant",
                                        "content": [{"type": "text", "text": "result"}]
                                    }]
                                }
                            }]
                        }))
                    } else {
                        ResponseTemplate::new(200).set_body_json(json!({
                            "data": [],
                            "next_token": "tok_2"
                        }))
                    }
                })
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/collections"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "data": [{
                        "id": "col_sync",
                        "name": "Wrapped collection",
                        "document_count": 2
                    }]
                })))
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/collections/col_sync"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "col_sync",
                    "name": "Wrapped collection",
                    "document_count": 2
                })))
                .mount(&server)
                .await;

            Mock::given(method("POST"))
                .and(path("/collections/col_sync/documents"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "ids": ["doc_1", "doc_2"]
                })))
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/collections/col_sync/documents"))
                .respond_with(move |req: &wiremock::Request| {
                    assert_eq!(req.url.query(), Some("limit=2&next_token=tok_doc"));
                    ResponseTemplate::new(200).set_body_json(json!({
                        "data": [
                            {"id": "doc_1", "content": "seeded"}
                        ]
                    }))
                })
                .mount(&server)
                .await;
        });

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

        let request =
            BatchRequest::new("custom-1", "grok-4").message(Message::user("batch payload"));
        client
            .batch()
            .add_requests("batch_sync", vec![request])
            .unwrap();

        let cancelled = client.batch().cancel("batch_sync").unwrap();
        assert_eq!(
            cancelled.status,
            crate::models::batch::BatchStatus::Cancelled
        );
        assert_eq!(
            client
                .batch()
                .list_requests("batch_sync")
                .unwrap()
                .data
                .len(),
            1
        );

        assert!(!client
            .batch()
            .list_results("batch_sync")
            .unwrap()
            .data
            .is_empty());
        assert_eq!(
            client
                .batch()
                .list_results_with_options("batch_sync", Some(2), Some("tok_2"))
                .unwrap()
                .next_token
                .as_deref(),
            Some("tok_2")
        );

        let collection = client.collections().get("col_sync").unwrap();
        assert_eq!(collection.id, "col_sync");
        assert_eq!(client.collections().list().unwrap().data.len(), 1);

        let added_documents = client
            .collections()
            .add_documents("col_sync", vec![Document::new("seeded")])
            .unwrap();
        assert_eq!(added_documents.ids[0], "doc_1");

        let documents = client
            .collections()
            .list_documents_with_options("col_sync", Some(2), Some("tok_doc"))
            .unwrap();
        assert_eq!(documents.data[0].id.as_deref(), Some("doc_1"));
    }

    #[test]
    fn sync_stateful_chat_append_helpers_cover_uncovered_methods() {
        let client = SyncXaiClient::new("test-key").unwrap();
        let mut chat = client.responses().chat("grok-4");

        chat.append(Role::System, "system context");
        chat.append(Role::User, "hello");
        assert_eq!(chat.messages().len(), 2);

        let sample_response: Response = serde_json::from_value(json!({
            "id": "resp_semantic",
            "model": "grok-4",
            "output": [{
                "type": "message",
                "role": "assistant",
                "content": [{"type": "text", "text": "semantic reply"}]
            }]
        }))
        .unwrap();

        chat.append_response_semantics(&sample_response);
        assert_eq!(
            chat.messages().last().map(|m| &m.role),
            Some(&Role::Assistant)
        );
        chat.clear();
        assert!(chat.messages().is_empty());
    }

    #[test]
    fn sync_models_list_returns_models() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/models"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "object": "list",
                    "data": [
                        {"id": "grok-4", "object": "model", "owned_by": "xai"}
                    ]
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let models = client.models().list().unwrap();

        assert_eq!(models.object, "list");
        assert_eq!(models.data.len(), 1);
        assert_eq!(models.data[0].id, "grok-4");
    }

    #[test]
    fn sync_tokenizer_count_tokens_returns_count() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/tokenize-text"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "tokens": [1, 2, 3]
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let count = client
            .tokenizer()
            .count_tokens("grok-4", "count these tokens")
            .unwrap();

        assert_eq!(count, 3);
    }

    #[test]
    fn sync_chat_create_send_returns_text() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/chat/completions"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "chatcmpl_sync",
                    "object": "chat.completion",
                    "created": 1700000000,
                    "model": "grok-4",
                    "choices": [{
                        "index": 0,
                        "message": {
                            "role": "assistant",
                            "content": "legacy sync hello"
                        },
                        "finish_reason": "stop"
                    }]
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let completion = client
            .chat()
            .create("grok-4")
            .message(Message::user("hello"))
            .send()
            .unwrap();

        assert_eq!(completion.text(), Some("legacy sync hello"));
    }

    #[test]
    fn sync_chat_create_forwards_options_and_tools() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/chat/completions"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    assert_eq!(body["model"], "grok-4");
                    assert_eq!(body["temperature"], 0.3);
                    assert_eq!(body["max_tokens"], 42);
                    assert_eq!(body["tool_choice"]["type"], "function");
                    assert_eq!(body["tool_choice"]["function"]["name"], "get_weather");
                    assert_eq!(body["tools"][0]["type"], "function");
                    assert_eq!(body["tools"][0]["function"]["name"], "get_weather");
                    ResponseTemplate::new(200).set_body_json(json!({
                        "id": "chatcmpl_sync_opts",
                        "object": "chat.completion",
                        "created": 1700000000,
                        "model": "grok-4",
                        "choices": [{
                            "index": 0,
                            "message": {
                                "role": "assistant",
                                "content": "options forwarded"
                            },
                            "finish_reason": "stop"
                        }]
                    }))
                })
                .mount(&server)
                .await;
        });

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

        let weather_tool = Tool::function(
            "get_weather",
            "Get weather",
            serde_json::json!({
                "type": "object",
                "properties": {"location": {"type": "string"}}
            }),
        );

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let completion = client
            .chat()
            .create("grok-4")
            .message(Message::user("Weather?"))
            .tools(vec![weather_tool])
            .tool_choice(ToolChoice::function("get_weather"))
            .temperature(0.3)
            .max_tokens(42)
            .send()
            .unwrap();

        assert_eq!(completion.text(), Some("options forwarded"));
    }

    #[test]
    fn sync_images_generate_send_returns_url() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/images/generations"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "created": 1700000000,
                    "data": [{
                        "url": "https://example.com/image.png"
                    }]
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let response = client
            .images()
            .generate("grok-2-image", "a lighthouse at dawn")
            .send()
            .unwrap();

        assert_eq!(response.first_url(), Some("https://example.com/image.png"));
    }

    #[test]
    fn sync_images_generate_base64_forwards_options() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/images/generations"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    assert_eq!(body["model"], "grok-2-image");
                    assert_eq!(body["prompt"], "draw");
                    assert_eq!(body["n"], 2);
                    assert_eq!(body["response_format"], "b64_json");
                    ResponseTemplate::new(200).set_body_json(json!({
                        "created": 1700000000,
                        "data": [{
                            "b64_json": "aGVsbG8="
                        }]
                    }))
                })
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let response = client
            .images()
            .generate("grok-2-image", "draw")
            .n(2)
            .base64_format()
            .send()
            .unwrap();

        assert_eq!(response.first_base64(), Some("aGVsbG8="));
    }

    #[test]
    fn sync_batch_create_returns_batch() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/batches"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "batch_sync_1",
                    "name": "my-sync-batch",
                    "status": "queued"
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let batch = client.batch().create("my-sync-batch").unwrap();

        assert_eq!(batch.id, "batch_sync_1");
        assert_eq!(batch.name, "my-sync-batch");
    }

    #[test]
    fn sync_collections_create_named_returns_collection() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/collections"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "col_sync_1",
                    "name": "my-sync-collection",
                    "document_count": 0
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let collection = client
            .collections()
            .create_named("my-sync-collection")
            .unwrap();

        assert_eq!(collection.id, "col_sync_1");
        assert_eq!(collection.name, "my-sync-collection");
    }

    #[cfg(feature = "files")]
    #[test]
    fn sync_files_list_returns_files() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/files"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "object": "list",
                    "data": [{
                        "id": "file_sync_1",
                        "filename": "notes.txt",
                        "bytes": 42,
                        "created_at": 1700000000,
                        "purpose": "assistants",
                        "object": "file"
                    }]
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let files = client.files().list().unwrap();

        assert_eq!(files.object, "list");
        assert_eq!(files.data.len(), 1);
        assert_eq!(files.data[0].id, "file_sync_1");
    }

    #[test]
    fn sync_batch_list_with_options_and_get_result_use_expected_paths() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/batches"))
                .respond_with(move |req: &wiremock::Request| {
                    assert_eq!(req.url.query(), Some("limit=2&next_token=tok_1"));
                    ResponseTemplate::new(200).set_body_json(json!({
                        "data": [
                            {"id": "batch_sync_2", "name": "batch-two", "status": "processing"}
                        ],
                        "next_token": "tok_2"
                    }))
                })
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/batches/batch%2Fsync/results/req%201"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "batch_request_id": "br_1",
                    "custom_id": "req 1",
                    "error_code": 0,
                    "response": {
                        "id": "resp_sync_batch",
                        "model": "grok-4",
                        "output": [{
                            "type": "message",
                            "role": "assistant",
                            "content": [{"type": "text", "text": "batch result"}]
                        }]
                    }
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();

        let listed = client
            .batch()
            .list_with_options(Some(2), Some("tok_1"))
            .unwrap();
        assert_eq!(listed.data.len(), 1);
        assert_eq!(listed.next_token.as_deref(), Some("tok_2"));

        let result = client.batch().get_result("batch/sync", "req 1").unwrap();
        assert!(result.is_success());
        assert_eq!(result.text().as_deref(), Some("batch result"));
    }

    #[test]
    fn sync_batch_list_requests_with_options_forwards_query() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/batches/batch_sync/requests"))
                .respond_with(move |req: &wiremock::Request| {
                    assert_eq!(req.url.query(), Some("limit=5&next_token=tok_req"));
                    ResponseTemplate::new(200).set_body_json(json!({
                        "data": [{
                            "id": "br_1",
                            "custom_id": "req-1",
                            "status": "completed"
                        }],
                        "next_token": "tok_req_2"
                    }))
                })
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let listed = client
            .batch()
            .list_requests_with_options("batch_sync", Some(5), Some("tok_req"))
            .unwrap();

        assert_eq!(listed.data.len(), 1);
        assert_eq!(listed.data[0].custom_id, "req-1");
        assert_eq!(listed.next_token.as_deref(), Some("tok_req_2"));
    }

    #[test]
    fn sync_collections_document_and_search_paths_are_encoded() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/collections/col%2Fsync/documents/doc%201"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "doc 1",
                    "content": "retrieved content"
                })))
                .mount(&server)
                .await;

            Mock::given(method("POST"))
                .and(path("/collections/col%2Fsync/search"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    assert_eq!(body["query"], "needle");
                    ResponseTemplate::new(200).set_body_json(json!({
                        "results": [{
                            "document": {"id": "doc 1", "content": "needle"},
                            "score": 0.91
                        }]
                    }))
                })
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let document = client
            .collections()
            .get_document("col/sync", "doc 1")
            .unwrap();
        assert_eq!(document.content, "retrieved content");

        let search = client
            .collections()
            .search_query("col/sync", "needle")
            .unwrap();
        assert_eq!(search.results.len(), 1);
        assert_eq!(search.results[0].document.content, "needle");
    }

    #[test]
    fn sync_collections_list_with_options_and_delete_document_forward_correctly() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/collections"))
                .respond_with(move |req: &wiremock::Request| {
                    assert_eq!(req.url.query(), Some("limit=4&next_token=tok_col"));
                    ResponseTemplate::new(200).set_body_json(json!({
                        "data": [{"id": "col_1", "name": "a", "document_count": 1}],
                        "next_token": "tok_col_2"
                    }))
                })
                .mount(&server)
                .await;

            Mock::given(method("DELETE"))
                .and(path("/collections/col%2Fsync/documents/doc%201"))
                .respond_with(ResponseTemplate::new(204))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let listed = client
            .collections()
            .list_with_options(Some(4), Some("tok_col"))
            .unwrap();
        assert_eq!(listed.data.len(), 1);
        assert_eq!(listed.next_token.as_deref(), Some("tok_col_2"));

        client
            .collections()
            .delete_document("col/sync", "doc 1")
            .unwrap();
    }

    #[cfg(feature = "files")]
    #[test]
    fn sync_files_upload_content_and_delete_work() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/files"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = String::from_utf8_lossy(&req.body);
                    assert!(body.contains("name=\"purpose\""));
                    assert!(body.contains("batch"));
                    ResponseTemplate::new(200).set_body_json(json!({
                        "id": "file_sync_uploaded",
                        "filename": "upload.txt",
                        "bytes": 11,
                        "created_at": 1700000000,
                        "purpose": "batch",
                        "object": "file"
                    }))
                })
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/files/file%2Fsync/content"))
                .respond_with(ResponseTemplate::new(200).set_body_bytes(b"hello world".to_vec()))
                .mount(&server)
                .await;

            Mock::given(method("DELETE"))
                .and(path("/files/file%2Fsync"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "file/sync",
                    "deleted": true,
                    "object": "file"
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();

        let uploaded = client
            .files()
            .upload("upload.txt", b"hello world".to_vec())
            .purpose(FilePurpose::Batch)
            .send()
            .unwrap();
        assert_eq!(uploaded.id, "file_sync_uploaded");
        assert_eq!(uploaded.purpose, "batch");

        let bytes = client.files().content("file/sync").unwrap();
        assert_eq!(bytes, b"hello world".to_vec());

        let deleted = client.files().delete("file/sync").unwrap();
        assert!(deleted.deleted);
        assert_eq!(deleted.id, "file/sync");
    }

    #[cfg(feature = "files")]
    #[test]
    fn sync_files_get_uses_encoded_path() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/files/file%2Fsync"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "file/sync",
                    "filename": "notes.txt",
                    "bytes": 42,
                    "created_at": 1700000000,
                    "purpose": "assistants",
                    "object": "file"
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let file = client.files().get("file/sync").unwrap();
        assert_eq!(file.id, "file/sync");
        assert_eq!(file.filename, "notes.txt");
    }

    #[test]
    fn sync_auth_gets_api_key_from_namespace() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/api-key"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "api_key": "k_123",
                    "object": "api_key",
                    "created_at": 1700000000
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let info = client.auth().api_key().unwrap();

        assert_eq!(info.api_key, "k_123");
        assert_eq!(info.created_at, Some(1700000000));
    }

    #[test]
    fn sync_videos_get_uses_encoded_path() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/videos/video%2Fsync"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "video/sync",
                    "status": "ready",
                    "url": "https://example.com/video.mp4"
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let video = client.videos().get("video/sync").unwrap();
        assert_eq!(video.id, "video/sync");
        assert_eq!(video.url.as_deref(), Some("https://example.com/video.mp4"));
    }

    #[cfg(feature = "files")]
    #[test]
    fn sync_files_advanced_endpoints_forward_expected_payloads() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/files:download"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    assert_eq!(body["file_id"], "file-1");
                    ResponseTemplate::new(200).set_body_bytes(b"downloaded-bytes".to_vec())
                })
                .mount(&server)
                .await;

            Mock::given(method("POST"))
                .and(path("/files:initialize"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    assert_eq!(body["filename"], "video.mp4");
                    assert_eq!(body["purpose"], "assistants");
                    ResponseTemplate::new(200).set_body_json(json!({
                        "upload_id": "u-123",
                        "object": "upload_session"
                    }))
                })
                .mount(&server)
                .await;

            Mock::given(method("POST"))
                .and(path("/files:uploadChunks"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    assert_eq!(body["upload_id"], "u-123");
                    assert_eq!(body["part"], 1);
                    ResponseTemplate::new(200).set_body_json(json!({
                        "upload_id": "u-123",
                        "complete": true
                    }))
                })
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let bytes = client
            .files()
            .download(FileDownloadRequest {
                file_id: "file-1".to_string(),
            })
            .unwrap();
        assert_eq!(bytes, b"downloaded-bytes".to_vec());

        let initialize = client
            .files()
            .initialize_upload(FileUploadInitializeRequest::new(
                "video.mp4",
                FilePurpose::Assistants,
            ))
            .unwrap();
        assert_eq!(initialize.upload_id, "u-123");

        let chunk = client
            .files()
            .upload_chunks(FileUploadChunksRequest {
                upload_id: "u-123".to_string(),
                part: 1,
                chunk: "chunk-data".to_string(),
                checksum: None,
            })
            .unwrap();
        assert!(chunk.complete);
    }

    #[test]
    fn sync_collections_update_and_upsert_wrap_async_features() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("PUT"))
                .and(path("/collections/col%2Fsync"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    assert_eq!(body["name"], "updated");
                    ResponseTemplate::new(200).set_body_json(json!({
                        "id": "col/sync",
                        "name": "updated",
                        "document_count": 1
                    }))
                })
                .mount(&server)
                .await;

            Mock::given(method("PATCH"))
                .and(path("/collections/col%2Fsync/documents/doc%201"))
                .respond_with(move |req: &wiremock::Request| {
                    let body = serde_json::from_slice::<serde_json::Value>(&req.body).unwrap();
                    assert_eq!(body["id"], "doc 1");
                    ResponseTemplate::new(200).set_body_json(json!({
                        "id": "doc 1",
                        "content": "updated"
                    }))
                })
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/collections/col%2Fsync/documents:batchGet"))
                .respond_with(move |req: &wiremock::Request| {
                    assert_eq!(req.url.query(), Some("ids=d1&ids=d2"));
                    ResponseTemplate::new(200).set_body_json(json!({
                        "data": [
                            {"id": "d1", "content": "one"},
                            {"id": "d2", "content": "two"}
                        ]
                    }))
                })
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let updated = client
            .collections()
            .update("col/sync", UpdateCollectionRequest::new().name("updated"))
            .unwrap();
        assert_eq!(updated.name, "updated");

        let doc = client
            .collections()
            .upsert_document(
                "col/sync",
                Document {
                    id: Some("doc 1".to_string()),
                    content: "updated".to_string(),
                    metadata: None,
                },
            )
            .unwrap();
        assert_eq!(doc.id.as_deref(), Some("doc 1"));

        let docs = client
            .collections()
            .batch_get_documents(
                "col/sync",
                BatchGetDocumentsRequest::new(vec!["d1".into(), "d2".into()]),
            )
            .unwrap();
        assert_eq!(docs.data.len(), 2);
    }

    #[test]
    fn sync_run_executes_unwrapped_future_outside_async_runtime() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/models"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "object": "list",
                    "data": [{"id": "grok-4", "object": "model", "owned_by": "xai"}]
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let models = client
            .run(client.as_async_client().models().list())
            .unwrap();

        assert_eq!(models.data.len(), 1);
        assert_eq!(models.data[0].id, "grok-4");
    }

    #[test]
    fn sync_models_list_propagates_api_error() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

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

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

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

    #[tokio::test]
    async fn sync_client_errors_inside_async_runtime() {
        let async_client = XaiClient::new("test-key").unwrap();
        let sync = SyncXaiClient::with_async_client(async_client).unwrap();

        let err = sync.responses().get("resp_123").unwrap_err();
        assert!(
            matches!(err, Error::Config(msg) if msg.contains("cannot run inside an async runtime"))
        );

        tokio::task::spawn_blocking(move || drop(sync))
            .await
            .unwrap();
    }

    #[test]
    fn sync_responses_get_delete_and_poll_until_ready() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());
        let poll_count = std::sync::Arc::new(AtomicUsize::new(0));
        let poll_count_clone = std::sync::Arc::clone(&poll_count);

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/responses/resp_sync"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "resp_sync",
                    "model": "grok-4",
                    "output": [{
                        "type": "message",
                        "role": "assistant",
                        "content": [{"type": "text", "text": "from_get" }]
                    }],
                    "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                })))
                .mount(&server)
                .await;

            Mock::given(method("DELETE"))
                .and(path("/responses/resp_sync"))
                .respond_with(ResponseTemplate::new(204))
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/responses/poll"))
                .respond_with(move |_req: &wiremock::Request| {
                    let attempts = poll_count_clone.fetch_add(1, Ordering::SeqCst);
                    if attempts == 0 {
                        ResponseTemplate::new(200).set_body_json(json!({
                            "id": "poll",
                            "model": "grok-4",
                            "output": [],
                            "usage": {"prompt_tokens": 1, "completion_tokens": 0, "total_tokens": 1}
                        }))
                    } else {
                        ResponseTemplate::new(200).set_body_json(json!({
                            "id": "poll",
                            "model": "grok-4",
                            "output": [{
                                "type": "message",
                                "role": "assistant",
                                "content": [{"type": "text", "text": "ready" }]
                            }],
                            "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
                        }))
                    }
                })
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();

        let response = client.responses().get("resp_sync").unwrap();
        assert_eq!(response.output_text().as_deref(), Some("from_get"));

        client.responses().delete("resp_sync").unwrap();

        let polled = client.responses().poll_until_ready("poll", 2).unwrap();
        assert_eq!(polled.output_text().as_deref(), Some("ready"));
        assert_eq!(poll_count.load(Ordering::SeqCst), 2);
    }

    #[test]
    fn sync_batch_and_collections_wrappers_cover_more_paths() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("GET"))
                .and(path("/batches/batch_sync"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "batch_sync",
                    "name": "my-batch",
                    "status": "completed"
                })))
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/batches"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "data": [{
                        "id": "batch_sync",
                        "name": "my-batch",
                        "status": "completed"
                    }]
                })))
                .mount(&server)
                .await;

            Mock::given(method("POST"))
                .and(path("/collections"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "col_sync",
                    "name": "my-collection",
                    "document_count": 0
                })))
                .mount(&server)
                .await;

            Mock::given(method("POST"))
                .and(path("/collections/col_sync/documents"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "ids": ["doc_sync"]
                })))
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/collections/col_sync/documents/doc_1"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "doc_1",
                    "content": "content"
                })))
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/collections/col_sync/documents"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "data": [{
                        "id": "doc_1",
                        "content": "content"
                    }]
                })))
                .mount(&server)
                .await;

            Mock::given(method("POST"))
                .and(path("/collections/col_sync/search"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "results": [{
                        "document": {"id": "doc_1", "content": "content"},
                        "score": 0.95
                    }]
                })))
                .mount(&server)
                .await;

            Mock::given(method("DELETE"))
                .and(path("/collections/col_sync"))
                .respond_with(ResponseTemplate::new(204))
                .mount(&server)
                .await;

            Mock::given(method("GET"))
                .and(path("/collections/col_sync"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "col_sync",
                    "name": "my-collection",
                    "document_count": 1
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();

        let batch = client.batch().get("batch_sync").unwrap();
        assert_eq!(batch.id, "batch_sync");
        assert_eq!(client.batch().list().unwrap().data.len(), 1);

        let created = client
            .collections()
            .create(CreateCollectionRequest::new("my-collection"))
            .unwrap();
        assert_eq!(created.id, "col_sync");

        let added = client
            .collections()
            .add_document("col_sync", Document::with_id("doc_sync", "content"))
            .unwrap();
        assert_eq!(added, "doc_sync");

        let doc = client
            .collections()
            .get_document("col_sync", "doc_1")
            .unwrap();
        assert_eq!(doc.id.as_ref().unwrap(), "doc_1");

        let docs = client.collections().list_documents("col_sync").unwrap();
        assert_eq!(docs.data.len(), 1);

        let search = client
            .collections()
            .search("col_sync", SearchRequest::new("content").limit(1))
            .unwrap();
        assert_eq!(search.results[0].document.id.as_deref(), Some("doc_1"));

        client.collections().delete("col_sync").unwrap();
    }

    #[test]
    fn sync_chat_completion_builder_forwards_optional_fields() {
        let server_rt = tokio::runtime::Runtime::new().unwrap();
        let server = server_rt.block_on(MockServer::start());

        server_rt.block_on(async {
            Mock::given(method("POST"))
                .and(path("/chat/completions"))
                .respond_with(ResponseTemplate::new(200).set_body_json(json!({
                    "id": "chat_sync",
                    "object": "chat.completion",
                    "created": 1700000000,
                    "model": "grok-4",
                    "choices": [{
                        "index": 0,
                        "message": {
                            "role": "assistant",
                            "content": "done"
                        },
                        "finish_reason": "stop"
                    }]
                })))
                .mount(&server)
                .await;
        });

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

        let client = SyncXaiClient::with_async_client(async_client).unwrap();
        let response = client
            .chat()
            .create("grok-4")
            .message(Message::user("hi"))
            .n(2)
            .stop(vec!["STOP".to_string()])
            .presence_penalty(0.2)
            .frequency_penalty(0.3)
            .message(Message::assistant("ignored"))
            .send()
            .unwrap();

        assert_eq!(response.text(), Some("done"));
    }
}