linger-openai-sdk 0.1.1

use crate::error::LingerError;
use crate::RequestId;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::BTreeMap;

/// EN: Request body for `POST /v1/threads`.
/// 中文：`POST /v1/threads` 的请求体。
#[derive(Clone, Debug, Default, Serialize, PartialEq)]
#[non_exhaustive]
pub struct CreateThreadRequest {
    /// EN: Initial messages for the thread.
    /// 中文：线程的初始消息。
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub messages: Vec<Value>,
    /// EN: Optional tool resources.
    /// 中文：可选的工具资源。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_resources: Option<Value>,
    /// EN: Optional metadata.
    /// 中文：可选元数据。
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, String>,
}

impl CreateThreadRequest {
    /// EN: Starts building a thread creation request.
    /// 中文：开始构建线程创建请求。
    pub fn builder() -> CreateThreadRequestBuilder {
        CreateThreadRequestBuilder::default()
    }
}

/// EN: Builder for thread creation requests.
/// 中文：线程创建请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateThreadRequestBuilder {
    messages: Vec<Value>,
    tool_resources: Option<Value>,
    metadata: BTreeMap<String, String>,
}

impl CreateThreadRequestBuilder {
    /// EN: Adds an initial message descriptor.
    /// 中文：添加一个初始消息描述。
    pub fn message(mut self, message: Value) -> Self {
        self.messages.push(message);
        self
    }

    /// EN: Replaces the initial message list.
    /// 中文：替换初始消息列表。
    pub fn messages(mut self, messages: impl IntoIterator<Item = Value>) -> Self {
        self.messages = messages.into_iter().collect();
        self
    }

    /// EN: Sets optional tool resources.
    /// 中文：设置可选的工具资源。
    pub fn tool_resources(mut self, tool_resources: Value) -> Self {
        self.tool_resources = Some(tool_resources);
        self
    }

    /// EN: Adds a metadata key/value pair.
    /// 中文：添加一个元数据键值对。
    pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateThreadRequest, LingerError> {
        validate_messages(&self.messages)?;
        validate_metadata(&self.metadata)?;
        if self.tool_resources.as_ref().is_some_and(Value::is_null) {
            return Err(LingerError::invalid_config(
                "tool_resources must not be null",
            ));
        }
        Ok(CreateThreadRequest {
            messages: self.messages,
            tool_resources: self.tool_resources,
            metadata: self.metadata,
        })
    }
}

/// EN: Request body for `POST /v1/threads/{thread_id}`.
/// 中文：`POST /v1/threads/{thread_id}` 的请求体。
#[derive(Clone, Debug, Default, Serialize, PartialEq)]
#[non_exhaustive]
pub struct ModifyThreadRequest {
    /// EN: Optional tool resources.
    /// 中文：可选的工具资源。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_resources: Option<Value>,
    /// EN: Optional metadata.
    /// 中文：可选元数据。
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, String>,
}

impl ModifyThreadRequest {
    /// EN: Starts building a thread modification request.
    /// 中文：开始构建线程修改请求。
    pub fn builder() -> ModifyThreadRequestBuilder {
        ModifyThreadRequestBuilder::default()
    }
}

/// EN: Builder for thread modification requests.
/// 中文：线程修改请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct ModifyThreadRequestBuilder {
    tool_resources: Option<Value>,
    metadata: BTreeMap<String, String>,
}

impl ModifyThreadRequestBuilder {
    /// EN: Sets optional tool resources.
    /// 中文：设置可选的工具资源。
    pub fn tool_resources(mut self, tool_resources: Value) -> Self {
        self.tool_resources = Some(tool_resources);
        self
    }

    /// EN: Adds a metadata key/value pair.
    /// 中文：添加一个元数据键值对。
    pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<ModifyThreadRequest, LingerError> {
        validate_metadata(&self.metadata)?;
        if self.tool_resources.as_ref().is_some_and(Value::is_null) {
            return Err(LingerError::invalid_config(
                "tool_resources must not be null",
            ));
        }
        Ok(ModifyThreadRequest {
            tool_resources: self.tool_resources,
            metadata: self.metadata,
        })
    }
}

/// EN: Request body for `POST /v1/threads/{thread_id}/messages`.
/// 中文：`POST /v1/threads/{thread_id}/messages` 的请求体。
#[derive(Clone, Debug, Serialize, PartialEq)]
#[non_exhaustive]
pub struct CreateThreadMessageRequest {
    /// EN: Message role.
    /// 中文：消息角色。
    pub role: String,
    /// EN: Message content.
    /// 中文：消息内容。
    pub content: Value,
    /// EN: Optional file attachments.
    /// 中文：可选文件附件。
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub attachments: Vec<Value>,
    /// EN: Optional metadata.
    /// 中文：可选元数据。
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, String>,
}

impl CreateThreadMessageRequest {
    /// EN: Starts building a thread message creation request.
    /// 中文：开始构建线程消息创建请求。
    pub fn builder() -> CreateThreadMessageRequestBuilder {
        CreateThreadMessageRequestBuilder::default()
    }
}

/// EN: Builder for thread message creation requests.
/// 中文：线程消息创建请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateThreadMessageRequestBuilder {
    role: Option<String>,
    content: Option<Value>,
    attachments: Vec<Value>,
    metadata: BTreeMap<String, String>,
}

impl CreateThreadMessageRequestBuilder {
    /// EN: Sets the message role.
    /// 中文：设置消息角色。
    pub fn role(mut self, role: impl Into<String>) -> Self {
        self.role = Some(role.into());
        self
    }

    /// EN: Sets text content.
    /// 中文：设置文本内容。
    pub fn content(mut self, content: impl Into<String>) -> Self {
        self.content = Some(Value::String(content.into()));
        self
    }

    /// EN: Sets raw JSON content.
    /// 中文：设置原始 JSON 内容。
    pub fn content_json(mut self, content: Value) -> Self {
        self.content = Some(content);
        self
    }

    /// EN: Adds an attachment descriptor.
    /// 中文：添加一个附件描述。
    pub fn attachment(mut self, attachment: Value) -> Self {
        self.attachments.push(attachment);
        self
    }

    /// EN: Adds a metadata key/value pair.
    /// 中文：添加一个元数据键值对。
    pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateThreadMessageRequest, LingerError> {
        let role = required_string("role", self.role)?;
        let content = self
            .content
            .filter(|value| !value.is_null())
            .ok_or_else(|| LingerError::invalid_config("content is required"))?;
        if self.attachments.iter().any(Value::is_null) {
            return Err(LingerError::invalid_config(
                "attachments must not contain null",
            ));
        }
        validate_metadata(&self.metadata)?;
        Ok(CreateThreadMessageRequest {
            role,
            content,
            attachments: self.attachments,
            metadata: self.metadata,
        })
    }
}

/// EN: Request body for `POST /v1/threads/{thread_id}/messages/{message_id}`.
/// 中文：`POST /v1/threads/{thread_id}/messages/{message_id}` 的请求体。
#[derive(Clone, Debug, Default, Serialize, PartialEq)]
#[non_exhaustive]
pub struct ModifyThreadMessageRequest {
    /// EN: Optional metadata.
    /// 中文：可选元数据。
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, String>,
}

impl ModifyThreadMessageRequest {
    /// EN: Starts building a thread message modification request.
    /// 中文：开始构建线程消息修改请求。
    pub fn builder() -> ModifyThreadMessageRequestBuilder {
        ModifyThreadMessageRequestBuilder::default()
    }
}

/// EN: Builder for thread message modification requests.
/// 中文：线程消息修改请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct ModifyThreadMessageRequestBuilder {
    metadata: BTreeMap<String, String>,
}

impl ModifyThreadMessageRequestBuilder {
    /// EN: Adds a metadata key/value pair.
    /// 中文：添加一个元数据键值对。
    pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<ModifyThreadMessageRequest, LingerError> {
        validate_metadata(&self.metadata)?;
        Ok(ModifyThreadMessageRequest {
            metadata: self.metadata,
        })
    }
}

/// EN: Request body for `POST /v1/threads/runs`.
/// 中文：`POST /v1/threads/runs` 的请求体。
#[derive(Clone, Debug, Serialize, PartialEq)]
#[non_exhaustive]
pub struct CreateThreadAndRunRequest {
    /// EN: Assistant id used to execute the run.
    /// 中文：用于执行 Run 的 Assistant ID。
    pub assistant_id: String,
    /// EN: Optional thread descriptor created with the run.
    /// 中文：随 Run 一起创建的可选线程描述。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub thread: Option<Value>,
    /// EN: Optional model override for this run.
    /// 中文：此 Run 的可选模型覆盖值。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub model: Option<String>,
    /// EN: Optional instruction override for this run.
    /// 中文：此 Run 的可选指令覆盖值。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub instructions: Option<String>,
    /// EN: Optional tool overrides for this run.
    /// 中文：此 Run 的可选工具覆盖值。
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub tools: Vec<Value>,
    /// EN: Optional metadata.
    /// 中文：可选元数据。
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, String>,
    /// EN: Forward-compatible optional fields not yet covered by handwritten types.
    /// 中文：手写类型尚未覆盖的前向兼容可选字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
}

impl CreateThreadAndRunRequest {
    /// EN: Starts building a create-thread-and-run request.
    /// 中文：开始构建创建线程并运行的请求。
    pub fn builder() -> CreateThreadAndRunRequestBuilder {
        CreateThreadAndRunRequestBuilder::default()
    }
}

/// EN: Builder for create-thread-and-run requests.
/// 中文：创建线程并运行请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateThreadAndRunRequestBuilder {
    assistant_id: Option<String>,
    thread: Option<Value>,
    model: Option<String>,
    instructions: Option<String>,
    tools: Vec<Value>,
    metadata: BTreeMap<String, String>,
    extra: BTreeMap<String, Value>,
}

impl CreateThreadAndRunRequestBuilder {
    /// EN: Sets the Assistant id.
    /// 中文：设置 Assistant ID。
    pub fn assistant_id(mut self, assistant_id: impl Into<String>) -> Self {
        self.assistant_id = Some(assistant_id.into());
        self
    }

    /// EN: Sets the thread descriptor to create.
    /// 中文：设置要创建的线程描述。
    pub fn thread(mut self, thread: Value) -> Self {
        self.thread = Some(thread);
        self
    }

    /// EN: Sets an optional model override.
    /// 中文：设置可选模型覆盖值。
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = Some(model.into());
        self
    }

    /// EN: Sets optional run instructions.
    /// 中文：设置可选 Run 指令。
    pub fn instructions(mut self, instructions: impl Into<String>) -> Self {
        self.instructions = Some(instructions.into());
        self
    }

    /// EN: Adds a tool descriptor.
    /// 中文：添加一个工具描述。
    pub fn tool(mut self, tool: Value) -> Self {
        self.tools.push(tool);
        self
    }

    /// EN: Adds a metadata key/value pair.
    /// 中文：添加一个元数据键值对。
    pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// EN: Adds a forward-compatible JSON field.
    /// 中文：添加前向兼容的 JSON 字段。
    pub fn extra(mut self, name: impl Into<String>, value: Value) -> Self {
        self.extra.insert(name.into(), value);
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateThreadAndRunRequest, LingerError> {
        let assistant_id = required_string("assistant_id", self.assistant_id)?;
        if self.thread.as_ref().is_some_and(Value::is_null) {
            return Err(LingerError::invalid_config("thread must not be null"));
        }
        validate_optional_string("model", &self.model)?;
        validate_optional_string("instructions", &self.instructions)?;
        validate_json_items("tools", &self.tools)?;
        validate_metadata(&self.metadata)?;
        validate_extra_fields(&self.extra)?;
        Ok(CreateThreadAndRunRequest {
            assistant_id,
            thread: self.thread,
            model: self.model,
            instructions: self.instructions,
            tools: self.tools,
            metadata: self.metadata,
            extra: self.extra,
        })
    }
}

/// EN: Request body for `POST /v1/threads/{thread_id}/runs`.
/// 中文：`POST /v1/threads/{thread_id}/runs` 的请求体。
#[derive(Clone, Debug, Serialize, PartialEq)]
#[non_exhaustive]
pub struct CreateThreadRunRequest {
    /// EN: Assistant id used to execute the run.
    /// 中文：用于执行 Run 的 Assistant ID。
    pub assistant_id: String,
    /// EN: Optional model override for this run.
    /// 中文：此 Run 的可选模型覆盖值。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub model: Option<String>,
    /// EN: Optional instruction override for this run.
    /// 中文：此 Run 的可选指令覆盖值。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub instructions: Option<String>,
    /// EN: Optional additional instructions appended for this run.
    /// 中文：此 Run 追加的可选补充指令。
    #[serde(skip_serializing_if = "Option::is_none")]
    pub additional_instructions: Option<String>,
    /// EN: Optional additional messages inserted before creating the run.
    /// 中文：创建 Run 前插入的可选补充消息。
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub additional_messages: Vec<Value>,
    /// EN: Optional tool overrides for this run.
    /// 中文：此 Run 的可选工具覆盖值。
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub tools: Vec<Value>,
    /// EN: Optional metadata.
    /// 中文：可选元数据。
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, String>,
    /// EN: Forward-compatible optional fields not yet covered by handwritten types.
    /// 中文：手写类型尚未覆盖的前向兼容可选字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
    #[serde(skip)]
    include_file_search_result_content: bool,
}

impl CreateThreadRunRequest {
    /// EN: Starts building a thread-run creation request.
    /// 中文：开始构建线程 Run 创建请求。
    pub fn builder() -> CreateThreadRunRequestBuilder {
        CreateThreadRunRequestBuilder::default()
    }

    pub(crate) fn path(&self, thread_id: &str) -> String {
        path_with_query(
            &format!("/v1/threads/{thread_id}/runs"),
            ThreadListQuery {
                limit: None,
                order: None,
                after: None,
                before: None,
                run_id: None,
                include_file_search_result_content: self.include_file_search_result_content,
            },
        )
    }
}

/// EN: Builder for thread-run creation requests.
/// 中文：线程 Run 创建请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct CreateThreadRunRequestBuilder {
    assistant_id: Option<String>,
    model: Option<String>,
    instructions: Option<String>,
    additional_instructions: Option<String>,
    additional_messages: Vec<Value>,
    tools: Vec<Value>,
    metadata: BTreeMap<String, String>,
    extra: BTreeMap<String, Value>,
    include_file_search_result_content: bool,
}

impl CreateThreadRunRequestBuilder {
    /// EN: Sets the Assistant id.
    /// 中文：设置 Assistant ID。
    pub fn assistant_id(mut self, assistant_id: impl Into<String>) -> Self {
        self.assistant_id = Some(assistant_id.into());
        self
    }

    /// EN: Sets an optional model override.
    /// 中文：设置可选模型覆盖值。
    pub fn model(mut self, model: impl Into<String>) -> Self {
        self.model = Some(model.into());
        self
    }

    /// EN: Sets optional run instructions.
    /// 中文：设置可选 Run 指令。
    pub fn instructions(mut self, instructions: impl Into<String>) -> Self {
        self.instructions = Some(instructions.into());
        self
    }

    /// EN: Sets optional additional run instructions.
    /// 中文：设置可选的补充 Run 指令。
    pub fn additional_instructions(mut self, additional_instructions: impl Into<String>) -> Self {
        self.additional_instructions = Some(additional_instructions.into());
        self
    }

    /// EN: Adds an additional message descriptor.
    /// 中文：添加一个补充消息描述。
    pub fn additional_message(mut self, message: Value) -> Self {
        self.additional_messages.push(message);
        self
    }

    /// EN: Replaces the additional message list.
    /// 中文：替换补充消息列表。
    pub fn additional_messages(mut self, messages: impl IntoIterator<Item = Value>) -> Self {
        self.additional_messages = messages.into_iter().collect();
        self
    }

    /// EN: Adds a tool descriptor.
    /// 中文：添加一个工具描述。
    pub fn tool(mut self, tool: Value) -> Self {
        self.tools.push(tool);
        self
    }

    /// EN: Replaces the tool descriptor list.
    /// 中文：替换工具描述列表。
    pub fn tools(mut self, tools: impl IntoIterator<Item = Value>) -> Self {
        self.tools = tools.into_iter().collect();
        self
    }

    /// EN: Adds a metadata key/value pair.
    /// 中文：添加一个元数据键值对。
    pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// EN: Adds a forward-compatible JSON field.
    /// 中文：添加前向兼容的 JSON 字段。
    pub fn extra(mut self, name: impl Into<String>, value: Value) -> Self {
        self.extra.insert(name.into(), value);
        self
    }

    /// EN: Includes file search result content in step details for the created run.
    /// 中文：在创建的 Run 的 step details 中包含 file search 结果内容。
    pub fn include_file_search_result_content(mut self) -> Self {
        self.include_file_search_result_content = true;
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<CreateThreadRunRequest, LingerError> {
        let assistant_id = required_string("assistant_id", self.assistant_id)?;
        validate_optional_string("model", &self.model)?;
        validate_optional_string("instructions", &self.instructions)?;
        validate_optional_string("additional_instructions", &self.additional_instructions)?;
        validate_json_items("additional_messages", &self.additional_messages)?;
        validate_json_items("tools", &self.tools)?;
        validate_metadata(&self.metadata)?;
        validate_extra_fields(&self.extra)?;
        Ok(CreateThreadRunRequest {
            assistant_id,
            model: self.model,
            instructions: self.instructions,
            additional_instructions: self.additional_instructions,
            additional_messages: self.additional_messages,
            tools: self.tools,
            metadata: self.metadata,
            extra: self.extra,
            include_file_search_result_content: self.include_file_search_result_content,
        })
    }
}

/// EN: Request body for `POST /v1/threads/{thread_id}/runs/{run_id}`.
/// 中文：`POST /v1/threads/{thread_id}/runs/{run_id}` 的请求体。
#[derive(Clone, Debug, Default, Serialize, PartialEq)]
#[non_exhaustive]
pub struct ModifyThreadRunRequest {
    /// EN: Optional metadata.
    /// 中文：可选元数据。
    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
    pub metadata: BTreeMap<String, String>,
}

impl ModifyThreadRunRequest {
    /// EN: Starts building a thread-run modification request.
    /// 中文：开始构建线程 Run 修改请求。
    pub fn builder() -> ModifyThreadRunRequestBuilder {
        ModifyThreadRunRequestBuilder::default()
    }
}

/// EN: Builder for thread-run modification requests.
/// 中文：线程 Run 修改请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct ModifyThreadRunRequestBuilder {
    metadata: BTreeMap<String, String>,
}

impl ModifyThreadRunRequestBuilder {
    /// EN: Adds a metadata key/value pair.
    /// 中文：添加一个元数据键值对。
    pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<ModifyThreadRunRequest, LingerError> {
        validate_metadata(&self.metadata)?;
        Ok(ModifyThreadRunRequest {
            metadata: self.metadata,
        })
    }
}

/// EN: Tool output item submitted to a waiting run.
/// 中文：提交给等待中 Run 的工具输出项。
#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct SubmitToolOutput {
    /// EN: Tool call id returned by the run.
    /// 中文：Run 返回的工具调用 ID。
    pub tool_call_id: String,
    /// EN: Tool output string.
    /// 中文：工具输出字符串。
    pub output: String,
}

/// EN: Request body for `POST /v1/threads/{thread_id}/runs/{run_id}/submit_tool_outputs`.
/// 中文：`POST /v1/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` 的请求体。
#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct SubmitToolOutputsRequest {
    /// EN: Tool outputs required by the run.
    /// 中文：Run 所需的工具输出。
    pub tool_outputs: Vec<SubmitToolOutput>,
}

impl SubmitToolOutputsRequest {
    /// EN: Starts building a submit-tool-outputs request.
    /// 中文：开始构建提交工具输出请求。
    pub fn builder() -> SubmitToolOutputsRequestBuilder {
        SubmitToolOutputsRequestBuilder::default()
    }
}

/// EN: Builder for submit-tool-outputs requests.
/// 中文：提交工具输出请求的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct SubmitToolOutputsRequestBuilder {
    tool_outputs: Vec<SubmitToolOutput>,
}

impl SubmitToolOutputsRequestBuilder {
    /// EN: Adds a tool output.
    /// 中文：添加一个工具输出。
    pub fn tool_output(
        mut self,
        tool_call_id: impl Into<String>,
        output: impl Into<String>,
    ) -> Self {
        self.tool_outputs.push(SubmitToolOutput {
            tool_call_id: tool_call_id.into(),
            output: output.into(),
        });
        self
    }

    /// EN: Builds and validates the request.
    /// 中文：构建并校验请求。
    pub fn build(self) -> Result<SubmitToolOutputsRequest, LingerError> {
        if self.tool_outputs.is_empty() {
            return Err(LingerError::invalid_config(
                "tool_outputs must not be empty",
            ));
        }
        for output in &self.tool_outputs {
            if output.tool_call_id.trim().is_empty() {
                return Err(LingerError::invalid_config("tool_call_id is required"));
            }
        }
        Ok(SubmitToolOutputsRequest {
            tool_outputs: self.tool_outputs,
        })
    }
}

/// EN: Thread object returned by the Threads API.
/// 中文：Threads API 返回的 Thread 对象。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct Thread {
    /// EN: Thread id.
    /// 中文：Thread ID。
    pub id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Unix timestamp for creation.
    /// 中文：创建时间的 Unix 时间戳。
    pub created_at: u64,
    /// EN: Tool resources returned by the API, when present.
    /// 中文：API 返回的工具资源，如存在。
    #[serde(default)]
    pub tool_resources: Option<Value>,
    /// EN: Metadata returned by the API.
    /// 中文：API 返回的元数据。
    #[serde(default)]
    pub metadata: BTreeMap<String, String>,
    /// EN: Additional fields preserved for forward compatibility.
    /// 中文：为前向兼容保留的额外字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

/// EN: Thread message object returned by the Thread Messages API.
/// 中文：Thread Messages API 返回的线程消息对象。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct ThreadMessage {
    /// EN: Message id.
    /// 中文：消息 ID。
    pub id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Unix timestamp for creation.
    /// 中文：创建时间的 Unix 时间戳。
    pub created_at: u64,
    /// EN: Parent thread id.
    /// 中文：父线程 ID。
    pub thread_id: String,
    /// EN: Message role.
    /// 中文：消息角色。
    pub role: String,
    /// EN: Message content items.
    /// 中文：消息内容项。
    #[serde(default)]
    pub content: Vec<Value>,
    /// EN: Message status, when returned.
    /// 中文：消息状态，如响应中存在。
    #[serde(default)]
    pub status: Option<String>,
    /// EN: Incomplete details, when returned.
    /// 中文：未完成详情，如响应中存在。
    #[serde(default)]
    pub incomplete_details: Option<Value>,
    /// EN: Completed timestamp, when returned.
    /// 中文：完成时间戳，如响应中存在。
    #[serde(default)]
    pub completed_at: Option<u64>,
    /// EN: Incomplete timestamp, when returned.
    /// 中文：未完成时间戳，如响应中存在。
    #[serde(default)]
    pub incomplete_at: Option<u64>,
    /// EN: Assistant id, when returned.
    /// 中文：Assistant ID，如响应中存在。
    #[serde(default)]
    pub assistant_id: Option<String>,
    /// EN: Run id, when returned.
    /// 中文：Run ID，如响应中存在。
    #[serde(default)]
    pub run_id: Option<String>,
    /// EN: Attachment descriptors returned by the API.
    /// 中文：API 返回的附件描述。
    #[serde(default)]
    pub attachments: Vec<Value>,
    /// EN: Metadata returned by the API.
    /// 中文：API 返回的元数据。
    #[serde(default)]
    pub metadata: BTreeMap<String, String>,
    /// EN: Additional fields preserved for forward compatibility.
    /// 中文：为前向兼容保留的额外字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

/// EN: Run object returned by the Thread Runs API.
/// 中文：Thread Runs API 返回的 Run 对象。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct ThreadRun {
    /// EN: Run id.
    /// 中文：Run ID。
    pub id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Unix timestamp for creation.
    /// 中文：创建时间的 Unix 时间戳。
    pub created_at: u64,
    /// EN: Parent thread id.
    /// 中文：父线程 ID。
    pub thread_id: String,
    /// EN: Assistant id used by this run.
    /// 中文：此 Run 使用的 Assistant ID。
    pub assistant_id: String,
    /// EN: Run status.
    /// 中文：Run 状态。
    pub status: String,
    /// EN: Required action details, when the run is waiting for action.
    /// 中文：Run 等待操作时的必需操作详情。
    #[serde(default)]
    pub required_action: Option<Value>,
    /// EN: Last run error, when returned.
    /// 中文：API 返回的最后一个 Run 错误。
    #[serde(default)]
    pub last_error: Option<Value>,
    /// EN: Expiration timestamp, when returned.
    /// 中文：过期时间戳，如响应中存在。
    #[serde(default)]
    pub expires_at: Option<u64>,
    /// EN: Start timestamp, when returned.
    /// 中文：开始时间戳，如响应中存在。
    #[serde(default)]
    pub started_at: Option<u64>,
    /// EN: Cancellation timestamp, when returned.
    /// 中文：取消时间戳，如响应中存在。
    #[serde(default)]
    pub cancelled_at: Option<u64>,
    /// EN: Failure timestamp, when returned.
    /// 中文：失败时间戳，如响应中存在。
    #[serde(default)]
    pub failed_at: Option<u64>,
    /// EN: Completion timestamp, when returned.
    /// 中文：完成时间戳，如响应中存在。
    #[serde(default)]
    pub completed_at: Option<u64>,
    /// EN: Incomplete details, when returned.
    /// 中文：未完成详情，如响应中存在。
    #[serde(default)]
    pub incomplete_details: Option<Value>,
    /// EN: Model used by this run.
    /// 中文：此 Run 使用的模型。
    pub model: String,
    /// EN: Run instructions, when returned.
    /// 中文：Run 指令，如响应中存在。
    #[serde(default)]
    pub instructions: Option<String>,
    /// EN: Tool descriptors returned by the API.
    /// 中文：API 返回的工具描述。
    #[serde(default)]
    pub tools: Vec<Value>,
    /// EN: Metadata returned by the API.
    /// 中文：API 返回的元数据。
    #[serde(default)]
    pub metadata: BTreeMap<String, String>,
    /// EN: Usage details, when returned.
    /// 中文：用量详情，如响应中存在。
    #[serde(default)]
    pub usage: Option<Value>,
    /// EN: Additional fields preserved for forward compatibility.
    /// 中文：为前向兼容保留的额外字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

/// EN: Paginated thread-run list.
/// 中文：分页线程 Run 列表。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct ThreadRunPage {
    /// EN: API list object type.
    /// 中文：API 列表对象类型。
    pub object: String,
    /// EN: Runs on this page.
    /// 中文：本页的 Run。
    #[serde(default)]
    pub data: Vec<ThreadRun>,
    /// EN: First run id on this page.
    /// 中文：本页第一个 Run ID。
    #[serde(default)]
    pub first_id: Option<String>,
    /// EN: Last run id on this page.
    /// 中文：本页最后一个 Run ID。
    #[serde(default)]
    pub last_id: Option<String>,
    /// EN: Whether more runs are available.
    /// 中文：是否还有更多 Run。
    pub has_more: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

/// EN: Run step object returned by the Run Steps API.
/// 中文：Run Steps API 返回的 Run Step 对象。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct RunStep {
    /// EN: Run step id.
    /// 中文：Run Step ID。
    pub id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Unix timestamp for creation.
    /// 中文：创建时间的 Unix 时间戳。
    pub created_at: u64,
    /// EN: Assistant id associated with this step.
    /// 中文：此 Step 关联的 Assistant ID。
    pub assistant_id: String,
    /// EN: Parent thread id.
    /// 中文：父线程 ID。
    pub thread_id: String,
    /// EN: Parent run id.
    /// 中文：父 Run ID。
    pub run_id: String,
    /// EN: Run step type.
    /// 中文：Run Step 类型。
    #[serde(rename = "type")]
    pub kind: String,
    /// EN: Run step status.
    /// 中文：Run Step 状态。
    pub status: String,
    /// EN: Run step details.
    /// 中文：Run Step 详情。
    pub step_details: Value,
    /// EN: Last step error, when returned.
    /// 中文：API 返回的最后一个 Step 错误。
    #[serde(default)]
    pub last_error: Option<Value>,
    /// EN: Expiration timestamp, when returned.
    /// 中文：过期时间戳，如响应中存在。
    #[serde(default)]
    pub expired_at: Option<u64>,
    /// EN: Cancellation timestamp, when returned.
    /// 中文：取消时间戳，如响应中存在。
    #[serde(default)]
    pub cancelled_at: Option<u64>,
    /// EN: Failure timestamp, when returned.
    /// 中文：失败时间戳，如响应中存在。
    #[serde(default)]
    pub failed_at: Option<u64>,
    /// EN: Completion timestamp, when returned.
    /// 中文：完成时间戳，如响应中存在。
    #[serde(default)]
    pub completed_at: Option<u64>,
    /// EN: Metadata returned by the API.
    /// 中文：API 返回的元数据。
    #[serde(default)]
    pub metadata: BTreeMap<String, String>,
    /// EN: Usage details, when returned.
    /// 中文：用量详情，如响应中存在。
    #[serde(default)]
    pub usage: Option<Value>,
    /// EN: Additional fields preserved for forward compatibility.
    /// 中文：为前向兼容保留的额外字段。
    #[serde(flatten)]
    pub extra: BTreeMap<String, Value>,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

/// EN: Paginated run-step list.
/// 中文：分页 Run Step 列表。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct RunStepPage {
    /// EN: API list object type.
    /// 中文：API 列表对象类型。
    pub object: String,
    /// EN: Run steps on this page.
    /// 中文：本页的 Run Step。
    #[serde(default)]
    pub data: Vec<RunStep>,
    /// EN: First run-step id on this page.
    /// 中文：本页第一个 Run Step ID。
    #[serde(default)]
    pub first_id: Option<String>,
    /// EN: Last run-step id on this page.
    /// 中文：本页最后一个 Run Step ID。
    #[serde(default)]
    pub last_id: Option<String>,
    /// EN: Whether more run steps are available.
    /// 中文：是否还有更多 Run Step。
    pub has_more: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl ThreadMessage {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

impl ThreadRun {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

impl ThreadRunPage {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Sort order for thread run list pagination.
/// 中文：thread run 列表分页的排序方向。
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum ThreadRunListOrder {
    /// EN: Ascending order.
    /// 中文：升序。
    Asc,
    /// EN: Descending order.
    /// 中文：降序。
    Desc,
}

impl ThreadRunListOrder {
    pub(crate) fn as_query_value(self) -> &'static str {
        match self {
            Self::Asc => "asc",
            Self::Desc => "desc",
        }
    }
}

/// EN: Query parameters for `GET /v1/threads/{thread_id}/runs`.
/// 中文：`GET /v1/threads/{thread_id}/runs` 的查询参数。
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct ThreadRunListRequest {
    /// EN: Maximum number of runs to retrieve.
    /// 中文：要获取的最大 run 数量。
    pub limit: Option<u8>,
    /// EN: Sort order by creation timestamp.
    /// 中文：按创建时间戳排序的方向。
    pub order: Option<ThreadRunListOrder>,
    /// EN: Cursor after which the next page starts.
    /// 中文：下一页开始位置之前的游标。
    pub after: Option<String>,
    /// EN: Cursor before which the previous page starts.
    /// 中文：上一页开始位置之后的游标。
    pub before: Option<String>,
}

impl ThreadRunListRequest {
    /// EN: Starts building thread run list query parameters.
    /// 中文：开始构建 thread run 列表查询参数。
    pub fn builder() -> ThreadRunListRequestBuilder {
        ThreadRunListRequestBuilder::default()
    }

    pub(crate) fn path(&self, thread_id: &str) -> String {
        path_with_query(
            &format!("/v1/threads/{thread_id}/runs"),
            ThreadListQuery {
                limit: self.limit,
                order: self.order.map(ThreadRunListOrder::as_query_value),
                after: self.after.as_deref(),
                before: self.before.as_deref(),
                run_id: None,
                include_file_search_result_content: false,
            },
        )
    }
}

/// EN: Builder for thread run list query parameters.
/// 中文：thread run 列表查询参数的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct ThreadRunListRequestBuilder {
    limit: Option<u8>,
    order: Option<ThreadRunListOrder>,
    after: Option<String>,
    before: Option<String>,
}

impl ThreadRunListRequestBuilder {
    /// EN: Sets the maximum number of runs to retrieve.
    /// 中文：设置要获取的最大 run 数量。
    pub fn limit(mut self, limit: u8) -> Self {
        self.limit = Some(limit);
        self
    }

    /// EN: Sets the sort order by creation timestamp.
    /// 中文：设置按创建时间戳排序的方向。
    pub fn order(mut self, order: ThreadRunListOrder) -> Self {
        self.order = Some(order);
        self
    }

    /// EN: Sets the cursor after which the next page starts.
    /// 中文：设置下一页开始位置之前的游标。
    pub fn after(mut self, after: impl Into<String>) -> Self {
        self.after = Some(after.into());
        self
    }

    /// EN: Sets the cursor before which the previous page starts.
    /// 中文：设置上一页开始位置之后的游标。
    pub fn before(mut self, before: impl Into<String>) -> Self {
        self.before = Some(before.into());
        self
    }

    /// EN: Builds and validates the query parameters.
    /// 中文：构建并校验查询参数。
    pub fn build(self) -> Result<ThreadRunListRequest, LingerError> {
        if let Some(limit) = self.limit {
            if limit == 0 || limit > 100 {
                return Err(LingerError::invalid_config(
                    "limit must be between 1 and 100",
                ));
            }
        }
        validate_optional_cursor("after", self.after.as_deref())?;
        validate_optional_cursor("before", self.before.as_deref())?;
        Ok(ThreadRunListRequest {
            limit: self.limit,
            order: self.order,
            after: self.after,
            before: self.before,
        })
    }
}

impl RunStep {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

impl RunStepPage {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Sort order for run step list pagination.
/// 中文：run step 列表分页的排序方向。
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum RunStepListOrder {
    /// EN: Ascending order.
    /// 中文：升序。
    Asc,
    /// EN: Descending order.
    /// 中文：降序。
    Desc,
}

impl RunStepListOrder {
    pub(crate) fn as_query_value(self) -> &'static str {
        match self {
            Self::Asc => "asc",
            Self::Desc => "desc",
        }
    }
}

/// EN: Query parameters for `GET /v1/threads/{thread_id}/runs/{run_id}/steps`.
/// 中文：`GET /v1/threads/{thread_id}/runs/{run_id}/steps` 的查询参数。
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct RunStepListRequest {
    /// EN: Maximum number of run steps to retrieve.
    /// 中文：要获取的最大 run step 数量。
    pub limit: Option<u8>,
    /// EN: Sort order by creation timestamp.
    /// 中文：按创建时间戳排序的方向。
    pub order: Option<RunStepListOrder>,
    /// EN: Cursor after which the next page starts.
    /// 中文：下一页开始位置之前的游标。
    pub after: Option<String>,
    /// EN: Cursor before which the previous page starts.
    /// 中文：上一页开始位置之后的游标。
    pub before: Option<String>,
    include_file_search_result_content: bool,
}

impl RunStepListRequest {
    /// EN: Starts building run step list query parameters.
    /// 中文：开始构建 run step 列表查询参数。
    pub fn builder() -> RunStepListRequestBuilder {
        RunStepListRequestBuilder::default()
    }

    pub(crate) fn path(&self, thread_id: &str, run_id: &str) -> String {
        path_with_query(
            &format!("/v1/threads/{thread_id}/runs/{run_id}/steps"),
            ThreadListQuery {
                limit: self.limit,
                order: self.order.map(RunStepListOrder::as_query_value),
                after: self.after.as_deref(),
                before: self.before.as_deref(),
                run_id: None,
                include_file_search_result_content: self.include_file_search_result_content,
            },
        )
    }
}

/// EN: Builder for run step list query parameters.
/// 中文：run step 列表查询参数的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct RunStepListRequestBuilder {
    limit: Option<u8>,
    order: Option<RunStepListOrder>,
    after: Option<String>,
    before: Option<String>,
    include_file_search_result_content: bool,
}

impl RunStepListRequestBuilder {
    /// EN: Sets the maximum number of run steps to retrieve.
    /// 中文：设置要获取的最大 run step 数量。
    pub fn limit(mut self, limit: u8) -> Self {
        self.limit = Some(limit);
        self
    }

    /// EN: Sets the sort order by creation timestamp.
    /// 中文：设置按创建时间戳排序的方向。
    pub fn order(mut self, order: RunStepListOrder) -> Self {
        self.order = Some(order);
        self
    }

    /// EN: Sets the cursor after which the next page starts.
    /// 中文：设置下一页开始位置之前的游标。
    pub fn after(mut self, after: impl Into<String>) -> Self {
        self.after = Some(after.into());
        self
    }

    /// EN: Sets the cursor before which the previous page starts.
    /// 中文：设置上一页开始位置之后的游标。
    pub fn before(mut self, before: impl Into<String>) -> Self {
        self.before = Some(before.into());
        self
    }

    /// EN: Includes file search result content in step details.
    /// 中文：在 step details 中包含 file search 结果内容。
    pub fn include_file_search_result_content(mut self) -> Self {
        self.include_file_search_result_content = true;
        self
    }

    /// EN: Builds and validates the query parameters.
    /// 中文：构建并校验查询参数。
    pub fn build(self) -> Result<RunStepListRequest, LingerError> {
        if let Some(limit) = self.limit {
            if limit == 0 || limit > 100 {
                return Err(LingerError::invalid_config(
                    "limit must be between 1 and 100",
                ));
            }
        }
        validate_optional_cursor("after", self.after.as_deref())?;
        validate_optional_cursor("before", self.before.as_deref())?;
        Ok(RunStepListRequest {
            limit: self.limit,
            order: self.order,
            after: self.after,
            before: self.before,
            include_file_search_result_content: self.include_file_search_result_content,
        })
    }
}

/// EN: Query parameters for `GET /v1/threads/{thread_id}/runs/{run_id}/steps/{step_id}`.
/// 中文：`GET /v1/threads/{thread_id}/runs/{run_id}/steps/{step_id}` 的查询参数。
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct RunStepRetrieveRequest {
    include_file_search_result_content: bool,
}

impl RunStepRetrieveRequest {
    /// EN: Starts building run step retrieve query parameters.
    /// 中文：开始构建 run step 获取查询参数。
    pub fn builder() -> RunStepRetrieveRequestBuilder {
        RunStepRetrieveRequestBuilder::default()
    }

    pub(crate) fn path(&self, thread_id: &str, run_id: &str, step_id: &str) -> String {
        path_with_query(
            &format!("/v1/threads/{thread_id}/runs/{run_id}/steps/{step_id}"),
            ThreadListQuery {
                limit: None,
                order: None,
                after: None,
                before: None,
                run_id: None,
                include_file_search_result_content: self.include_file_search_result_content,
            },
        )
    }
}

/// EN: Builder for run step retrieve query parameters.
/// 中文：run step 获取查询参数的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct RunStepRetrieveRequestBuilder {
    include_file_search_result_content: bool,
}

impl RunStepRetrieveRequestBuilder {
    /// EN: Includes file search result content in step details.
    /// 中文：在 step details 中包含 file search 结果内容。
    pub fn include_file_search_result_content(mut self) -> Self {
        self.include_file_search_result_content = true;
        self
    }

    /// EN: Builds the query parameters.
    /// 中文：构建查询参数。
    pub fn build(self) -> RunStepRetrieveRequest {
        RunStepRetrieveRequest {
            include_file_search_result_content: self.include_file_search_result_content,
        }
    }
}

/// EN: Paginated thread message list.
/// 中文：分页线程消息列表。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
#[non_exhaustive]
pub struct ThreadMessagePage {
    /// EN: API list object type.
    /// 中文：API 列表对象类型。
    pub object: String,
    /// EN: Messages on this page.
    /// 中文：本页消息。
    #[serde(default)]
    pub data: Vec<ThreadMessage>,
    /// EN: First message id on this page.
    /// 中文：本页第一个消息 ID。
    #[serde(default)]
    pub first_id: Option<String>,
    /// EN: Last message id on this page.
    /// 中文：本页最后一个消息 ID。
    #[serde(default)]
    pub last_id: Option<String>,
    /// EN: Whether more messages are available.
    /// 中文：是否还有更多消息。
    pub has_more: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl ThreadMessagePage {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Sort order for thread message list pagination.
/// 中文：thread message 列表分页的排序方向。
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum ThreadMessageListOrder {
    /// EN: Ascending order.
    /// 中文：升序。
    Asc,
    /// EN: Descending order.
    /// 中文：降序。
    Desc,
}

impl ThreadMessageListOrder {
    pub(crate) fn as_query_value(self) -> &'static str {
        match self {
            Self::Asc => "asc",
            Self::Desc => "desc",
        }
    }
}

/// EN: Query parameters for `GET /v1/threads/{thread_id}/messages`.
/// 中文：`GET /v1/threads/{thread_id}/messages` 的查询参数。
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct ThreadMessageListRequest {
    /// EN: Maximum number of messages to retrieve.
    /// 中文：要获取的最大 message 数量。
    pub limit: Option<u8>,
    /// EN: Sort order by creation timestamp.
    /// 中文：按创建时间戳排序的方向。
    pub order: Option<ThreadMessageListOrder>,
    /// EN: Cursor after which the next page starts.
    /// 中文：下一页开始位置之前的游标。
    pub after: Option<String>,
    /// EN: Cursor before which the previous page starts.
    /// 中文：上一页开始位置之后的游标。
    pub before: Option<String>,
    /// EN: Optional run id used to filter generated messages.
    /// 中文：用于过滤生成消息的可选 run ID。
    pub run_id: Option<String>,
}

impl ThreadMessageListRequest {
    /// EN: Starts building thread message list query parameters.
    /// 中文：开始构建 thread message 列表查询参数。
    pub fn builder() -> ThreadMessageListRequestBuilder {
        ThreadMessageListRequestBuilder::default()
    }

    pub(crate) fn path(&self, thread_id: &str) -> String {
        path_with_query(
            &format!("/v1/threads/{thread_id}/messages"),
            ThreadListQuery {
                limit: self.limit,
                order: self.order.map(ThreadMessageListOrder::as_query_value),
                after: self.after.as_deref(),
                before: self.before.as_deref(),
                run_id: self.run_id.as_deref(),
                include_file_search_result_content: false,
            },
        )
    }
}

/// EN: Builder for thread message list query parameters.
/// 中文：thread message 列表查询参数的构建器。
#[derive(Clone, Debug, Default)]
#[non_exhaustive]
pub struct ThreadMessageListRequestBuilder {
    limit: Option<u8>,
    order: Option<ThreadMessageListOrder>,
    after: Option<String>,
    before: Option<String>,
    run_id: Option<String>,
}

impl ThreadMessageListRequestBuilder {
    /// EN: Sets the maximum number of messages to retrieve.
    /// 中文：设置要获取的最大 message 数量。
    pub fn limit(mut self, limit: u8) -> Self {
        self.limit = Some(limit);
        self
    }

    /// EN: Sets the sort order by creation timestamp.
    /// 中文：设置按创建时间戳排序的方向。
    pub fn order(mut self, order: ThreadMessageListOrder) -> Self {
        self.order = Some(order);
        self
    }

    /// EN: Sets the cursor after which the next page starts.
    /// 中文：设置下一页开始位置之前的游标。
    pub fn after(mut self, after: impl Into<String>) -> Self {
        self.after = Some(after.into());
        self
    }

    /// EN: Sets the cursor before which the previous page starts.
    /// 中文：设置上一页开始位置之后的游标。
    pub fn before(mut self, before: impl Into<String>) -> Self {
        self.before = Some(before.into());
        self
    }

    /// EN: Filters messages by the run id that generated them.
    /// 中文：按生成这些 message 的 run ID 过滤。
    pub fn run_id(mut self, run_id: impl Into<String>) -> Self {
        self.run_id = Some(run_id.into());
        self
    }

    /// EN: Builds and validates the query parameters.
    /// 中文：构建并校验查询参数。
    pub fn build(self) -> Result<ThreadMessageListRequest, LingerError> {
        if let Some(limit) = self.limit {
            if limit == 0 || limit > 100 {
                return Err(LingerError::invalid_config(
                    "limit must be between 1 and 100",
                ));
            }
        }
        validate_optional_cursor("after", self.after.as_deref())?;
        validate_optional_cursor("before", self.before.as_deref())?;
        validate_optional_cursor("run_id", self.run_id.as_deref())?;
        Ok(ThreadMessageListRequest {
            limit: self.limit,
            order: self.order,
            after: self.after,
            before: self.before,
            run_id: self.run_id,
        })
    }
}

/// EN: Deletion result returned by the Thread Messages API.
/// 中文：Thread Messages API 返回的删除结果。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct ThreadMessageDeletion {
    /// EN: Deleted message id.
    /// 中文：已删除的消息 ID。
    pub id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Whether the message was deleted.
    /// 中文：消息是否已删除。
    pub deleted: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl ThreadMessageDeletion {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

impl Thread {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

/// EN: Deletion result returned by the Threads API.
/// 中文：Threads API 返回的删除结果。
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct ThreadDeletion {
    /// EN: Deleted Thread id.
    /// 中文：已删除的 Thread ID。
    pub id: String,
    /// EN: API object type.
    /// 中文：API 对象类型。
    pub object: String,
    /// EN: Whether the Thread was deleted.
    /// 中文：Thread 是否已删除。
    pub deleted: bool,
    /// EN: OpenAI request id from response headers.
    /// 中文：响应头中的 OpenAI 请求 ID。
    #[serde(skip)]
    request_id: Option<RequestId>,
}

impl ThreadDeletion {
    pub(crate) fn with_request_id(mut self, request_id: Option<RequestId>) -> Self {
        self.request_id = request_id;
        self
    }

    /// EN: Returns the OpenAI request id, when present.
    /// 中文：返回 OpenAI 请求 ID，如存在。
    pub fn request_id(&self) -> Option<&RequestId> {
        self.request_id.as_ref()
    }
}

fn validate_messages(messages: &[Value]) -> Result<(), LingerError> {
    if messages.iter().any(Value::is_null) {
        return Err(LingerError::invalid_config(
            "messages must not contain null",
        ));
    }
    Ok(())
}

fn validate_json_items(name: &str, values: &[Value]) -> Result<(), LingerError> {
    if values.iter().any(Value::is_null) {
        return Err(LingerError::invalid_config(format!(
            "{name} must not contain null"
        )));
    }
    Ok(())
}

fn validate_metadata(metadata: &BTreeMap<String, String>) -> Result<(), LingerError> {
    for key in metadata.keys() {
        if key.trim().is_empty() {
            return Err(LingerError::invalid_config(
                "metadata keys must not be empty",
            ));
        }
    }
    Ok(())
}

fn validate_extra_fields(extra: &BTreeMap<String, Value>) -> Result<(), LingerError> {
    for (key, value) in extra {
        if key.trim().is_empty() {
            return Err(LingerError::invalid_config(
                "extra field names must not be empty",
            ));
        }
        if value.is_null() {
            return Err(LingerError::invalid_config(format!(
                "extra field {key} must not be null"
            )));
        }
    }
    Ok(())
}

fn validate_optional_string(name: &str, value: &Option<String>) -> Result<(), LingerError> {
    if value.as_ref().is_some_and(|value| value.trim().is_empty()) {
        return Err(LingerError::invalid_config(format!(
            "{name} must not be empty"
        )));
    }
    Ok(())
}

fn required_string(name: &str, value: Option<String>) -> Result<String, LingerError> {
    value
        .filter(|value| !value.trim().is_empty())
        .ok_or_else(|| LingerError::invalid_config(format!("{name} is required")))
}

fn validate_optional_cursor(name: &str, value: Option<&str>) -> Result<(), LingerError> {
    if value.is_some_and(|value| value.trim().is_empty()) {
        return Err(LingerError::invalid_config(format!(
            "{name} must not be empty"
        )));
    }
    Ok(())
}

struct ThreadListQuery<'a> {
    limit: Option<u8>,
    order: Option<&'static str>,
    after: Option<&'a str>,
    before: Option<&'a str>,
    run_id: Option<&'a str>,
    include_file_search_result_content: bool,
}

fn path_with_query(base: &str, params: ThreadListQuery<'_>) -> String {
    let mut query = Vec::new();
    if let Some(limit) = params.limit {
        query.push(format!("limit={limit}"));
    }
    if let Some(order) = params.order {
        query.push(format!("order={order}"));
    }
    if let Some(after) = params.after {
        query.push(format!("after={}", encode_query_value(after)));
    }
    if let Some(before) = params.before {
        query.push(format!("before={}", encode_query_value(before)));
    }
    if let Some(run_id) = params.run_id {
        query.push(format!("run_id={}", encode_query_value(run_id)));
    }
    if params.include_file_search_result_content {
        query.push(format!(
            "include[]={}",
            encode_include_query_value("step_details.tool_calls[*].file_search.results[*].content")
        ));
    }
    if query.is_empty() {
        base.to_string()
    } else {
        format!("{base}?{}", query.join("&"))
    }
}

fn encode_query_value(value: &str) -> String {
    encode_query_value_inner(value, false)
}

fn encode_include_query_value(value: &str) -> String {
    encode_query_value_inner(value, true)
}

fn encode_query_value_inner(value: &str, preserve_wildcards: bool) -> String {
    let mut encoded = String::new();
    for byte in value.bytes() {
        match byte {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
                encoded.push(byte as char);
            }
            b'*' if preserve_wildcards => encoded.push('*'),
            _ => {
                const HEX: &[u8; 16] = b"0123456789ABCDEF";
                encoded.push('%');
                encoded.push(HEX[(byte >> 4) as usize] as char);
                encoded.push(HEX[(byte & 0x0F) as usize] as char);
            }
        }
    }
    encoded
}