ghl-sdk 0.5.2

// @generated by xtask/generate_services.py — do not edit by hand.
//! `agent-studio` — typed methods for all 11 API v3 operations
//! in this module.
//!
//! Access via [`Ghl::v3`](crate::Ghl::v3)`().agent_studio()`. These endpoints send `Version: v3`.
//!
//! Request and response types come from [`ghl_models::v3::agent_studio`](https://docs.rs/ghl-models/latest/ghl_models/v3/agent_studio/); every endpoint is also documented in the
//! [`agent-studio` API reference](https://github.com/Shahroz/ghl-rs/blob/main/docs/api/agent-studio.md).
//!
//! Enable with `features = ["agent-studio"]`.

#![allow(clippy::too_many_arguments)]

use crate::client::Ghl;
use crate::error::Result;
use ghl_models::v3::agent_studio as models;

/// Typed access to the `agent-studio` API v3 surface (11 operations). Obtained via
/// [`Ghl::v3`](crate::Ghl::v3)`().agent_studio()`.
#[derive(Debug, Clone)]
pub struct AgentStudioService {
    pub(crate) client: Ghl,
}

impl AgentStudioService {
    pub(crate) fn new(client: Ghl) -> Self {
        Self { client }
    }
}

/// Query parameters for [`AgentStudioService::list_agents`].
#[derive(Debug, Clone, Default)]
pub struct ListAgentsParams {
    /// `locationId` query parameter.
    /// Required by the API.
    pub location_id: String,
    /// Optional filter to return only agents with a published production version
    pub is_published: Option<String>,
    /// `limit` query parameter.
    /// Required by the API.
    pub limit: String,
    /// `offset` query parameter.
    /// Required by the API.
    pub offset: String,
    /// `source` query parameter.
    pub source: Option<String>,
}

impl ListAgentsParams {
    /// Start from the parameters the API requires.
    pub fn new(
        location_id: impl Into<String>,
        limit: impl Into<String>,
        offset: impl Into<String>,
    ) -> Self {
        Self {
            location_id: location_id.into(),
            limit: limit.into(),
            offset: offset.into(),
            ..Default::default()
        }
    }

    /// Optional filter to return only agents with a published production version
    pub fn is_published(mut self, v: impl Into<String>) -> Self {
        self.is_published = Some(v.into());
        self
    }

    /// Set the `source` query parameter.
    pub fn source(mut self, v: impl Into<String>) -> Self {
        self.source = Some(v.into());
        self
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let mut q: Vec<(String, String)> = vec![
            ("locationId".into(), self.location_id.clone()),
            ("limit".into(), self.limit.clone()),
            ("offset".into(), self.offset.clone()),
        ];
        if let Some(v) = &self.is_published {
            q.push(("isPublished".into(), v.to_string()));
        }
        if let Some(v) = &self.source {
            q.push(("source".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`AgentStudioService::create_agent`].
#[derive(Debug, Clone, Default)]
pub struct CreateAgentParams {
    /// `source` query parameter.
    pub source: Option<String>,
}

impl CreateAgentParams {
    /// Start from the parameters the API requires.
    pub fn new() -> Self {
        Self {
            ..Default::default()
        }
    }

    /// Set the `source` query parameter.
    pub fn source(mut self, v: impl Into<String>) -> Self {
        self.source = Some(v.into());
        self
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let mut q: Vec<(String, String)> = Vec::new();
        if let Some(v) = &self.source {
            q.push(("source".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`AgentStudioService::update_agent`].
#[derive(Debug, Clone, Default)]
pub struct UpdateAgentParams {
    /// `source` query parameter.
    pub source: Option<String>,
}

impl UpdateAgentParams {
    /// Start from the parameters the API requires.
    pub fn new() -> Self {
        Self {
            ..Default::default()
        }
    }

    /// Set the `source` query parameter.
    pub fn source(mut self, v: impl Into<String>) -> Self {
        self.source = Some(v.into());
        self
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let mut q: Vec<(String, String)> = Vec::new();
        if let Some(v) = &self.source {
            q.push(("source".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`AgentStudioService::promote_to_production`].
#[derive(Debug, Clone, Default)]
pub struct PromoteToProductionParams {
    /// `source` query parameter.
    pub source: Option<String>,
}

impl PromoteToProductionParams {
    /// Start from the parameters the API requires.
    pub fn new() -> Self {
        Self {
            ..Default::default()
        }
    }

    /// Set the `source` query parameter.
    pub fn source(mut self, v: impl Into<String>) -> Self {
        self.source = Some(v.into());
        self
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let mut q: Vec<(String, String)> = Vec::new();
        if let Some(v) = &self.source {
            q.push(("source".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`AgentStudioService::delete_agent`].
#[derive(Debug, Clone, Default)]
pub struct DeleteAgentParams {
    /// `locationId` query parameter.
    /// Required by the API.
    pub location_id: String,
    /// `source` query parameter.
    pub source: Option<String>,
}

impl DeleteAgentParams {
    /// Start from the parameters the API requires.
    pub fn new(location_id: impl Into<String>) -> Self {
        Self {
            location_id: location_id.into(),
            ..Default::default()
        }
    }

    /// Set the `source` query parameter.
    pub fn source(mut self, v: impl Into<String>) -> Self {
        self.source = Some(v.into());
        self
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let mut q: Vec<(String, String)> = vec![("locationId".into(), self.location_id.clone())];
        if let Some(v) = &self.source {
            q.push(("source".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`AgentStudioService::get_agent`].
#[derive(Debug, Clone, Default)]
pub struct GetAgentParams {
    /// `locationId` query parameter.
    /// Required by the API.
    pub location_id: String,
    /// `source` query parameter.
    pub source: Option<String>,
}

impl GetAgentParams {
    /// Start from the parameters the API requires.
    pub fn new(location_id: impl Into<String>) -> Self {
        Self {
            location_id: location_id.into(),
            ..Default::default()
        }
    }

    /// Set the `source` query parameter.
    pub fn source(mut self, v: impl Into<String>) -> Self {
        self.source = Some(v.into());
        self
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let mut q: Vec<(String, String)> = vec![("locationId".into(), self.location_id.clone())];
        if let Some(v) = &self.source {
            q.push(("source".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`AgentStudioService::update_agent_metadata`].
#[derive(Debug, Clone, Default)]
pub struct UpdateAgentMetadataParams {
    /// `source` query parameter.
    pub source: Option<String>,
}

impl UpdateAgentMetadataParams {
    /// Start from the parameters the API requires.
    pub fn new() -> Self {
        Self {
            ..Default::default()
        }
    }

    /// Set the `source` query parameter.
    pub fn source(mut self, v: impl Into<String>) -> Self {
        self.source = Some(v.into());
        self
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let mut q: Vec<(String, String)> = Vec::new();
        if let Some(v) = &self.source {
            q.push(("source".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`AgentStudioService::execute_agent`].
#[derive(Debug, Clone, Default)]
pub struct ExecuteAgentParams {
    /// `source` query parameter.
    pub source: Option<String>,
}

impl ExecuteAgentParams {
    /// Start from the parameters the API requires.
    pub fn new() -> Self {
        Self {
            ..Default::default()
        }
    }

    /// Set the `source` query parameter.
    pub fn source(mut self, v: impl Into<String>) -> Self {
        self.source = Some(v.into());
        self
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let mut q: Vec<(String, String)> = Vec::new();
        if let Some(v) = &self.source {
            q.push(("source".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`AgentStudioService::list_agents_deprecated`].
#[derive(Debug, Clone, Default)]
pub struct ListAgentsDeprecatedParams {
    /// `locationId` query parameter.
    /// Required by the API.
    pub location_id: String,
    /// `limit` query parameter.
    /// Required by the API.
    pub limit: String,
    /// `offset` query parameter.
    /// Required by the API.
    pub offset: String,
    /// `source` query parameter.
    pub source: Option<String>,
}

impl ListAgentsDeprecatedParams {
    /// Start from the parameters the API requires.
    pub fn new(
        location_id: impl Into<String>,
        limit: impl Into<String>,
        offset: impl Into<String>,
    ) -> Self {
        Self {
            location_id: location_id.into(),
            limit: limit.into(),
            offset: offset.into(),
            ..Default::default()
        }
    }

    /// Set the `source` query parameter.
    pub fn source(mut self, v: impl Into<String>) -> Self {
        self.source = Some(v.into());
        self
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let mut q: Vec<(String, String)> = vec![
            ("locationId".into(), self.location_id.clone()),
            ("limit".into(), self.limit.clone()),
            ("offset".into(), self.offset.clone()),
        ];
        if let Some(v) = &self.source {
            q.push(("source".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`AgentStudioService::get_agent_deprecated`].
#[derive(Debug, Clone, Default)]
pub struct GetAgentDeprecatedParams {
    /// `locationId` query parameter.
    /// Required by the API.
    pub location_id: String,
    /// `source` query parameter.
    pub source: Option<String>,
}

impl GetAgentDeprecatedParams {
    /// Start from the parameters the API requires.
    pub fn new(location_id: impl Into<String>) -> Self {
        Self {
            location_id: location_id.into(),
            ..Default::default()
        }
    }

    /// Set the `source` query parameter.
    pub fn source(mut self, v: impl Into<String>) -> Self {
        self.source = Some(v.into());
        self
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let mut q: Vec<(String, String)> = vec![("locationId".into(), self.location_id.clone())];
        if let Some(v) = &self.source {
            q.push(("source".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`AgentStudioService::execute_agent_deprecated`].
#[derive(Debug, Clone, Default)]
pub struct ExecuteAgentDeprecatedParams {
    /// `source` query parameter.
    pub source: Option<String>,
}

impl ExecuteAgentDeprecatedParams {
    /// Start from the parameters the API requires.
    pub fn new() -> Self {
        Self {
            ..Default::default()
        }
    }

    /// Set the `source` query parameter.
    pub fn source(mut self, v: impl Into<String>) -> Self {
        self.source = Some(v.into());
        self
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let mut q: Vec<(String, String)> = Vec::new();
        if let Some(v) = &self.source {
            q.push(("source".into(), v.to_string()));
        }
        q
    }
}

impl AgentStudioService {
    /// List Agents
    ///
    /// Lists all active agents for the specified location. locationId is required parameter
    /// to ensure optimal performance. Supports pagination using limit and offset.
    /// Optionally filter by isPublished=true to return only agents with a published
    /// production version.
    ///
    /// `GET /agent-studio/agent`
    ///
    /// Requires scope: `agent-studio.readonly`.
    pub async fn list_agents(
        &self,
        params: &ListAgentsParams,
    ) -> Result<models::GetPublishedAgentsResponseDTO> {
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::GET,
                "/agent-studio/agent",
                &query,
                None::<&()>,
                Some("v3"),
            )
            .await
    }

    /// Create Agent
    ///
    /// Creates a new agent with staging version. The agent will be created with an initial
    /// staging version that can later be promoted to production.
    ///
    /// `POST /agent-studio/agent`
    ///
    /// Requires scope: `agent-studio.write`.
    pub async fn create_agent(
        &self,
        params: &CreateAgentParams,
        body: &models::CreatePublicAgentDTO,
    ) -> Result<models::CreatePublicAgentResponseDTO> {
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::POST,
                "/agent-studio/agent",
                &query,
                Some(body),
                Some("v3"),
            )
            .await
    }

    /// Update Agent
    ///
    /// Updates a specific agent version by versionId. Supports updating nodes, edges,
    /// variables, and configuration.
    ///
    /// `PATCH /agent-studio/agent/versions/{versionId}`
    ///
    /// Requires scope: `agent-studio.write`.
    pub async fn update_agent(
        &self,
        version_id: &str,
        params: &UpdateAgentParams,
        body: &models::UpdatePublicAgentVersionDTO,
    ) -> Result<models::UpdatePublicAgentResponseDTO> {
        let path = format!(
            "/agent-studio/agent/versions/{}",
            crate::services::encode(version_id)
        );
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::PATCH,
                &path,
                &query,
                Some(body),
                Some("v3"),
            )
            .await
    }

    /// Promote to Production
    ///
    /// Promotes a draft version to production.
    ///
    /// `POST /agent-studio/agent/versions/{versionId}/publish`
    ///
    /// Requires scope: `agent-studio.write`.
    pub async fn promote_to_production(
        &self,
        version_id: &str,
        params: &PromoteToProductionParams,
        body: &models::PromoteAndPublishDTO,
    ) -> Result<models::PromoteAndPublishResponseDTO> {
        let path = format!(
            "/agent-studio/agent/versions/{}/publish",
            crate::services::encode(version_id)
        );
        let query = params.to_query();
        self.client
            .send_versioned(reqwest::Method::POST, &path, &query, Some(body), Some("v3"))
            .await
    }

    /// Delete Agent
    ///
    /// Deletes an agent and all its versions.
    ///
    /// `DELETE /agent-studio/agent/{agentId}`
    ///
    /// Requires scope: `agent-studio.write`.
    pub async fn delete_agent(
        &self,
        agent_id: &str,
        params: &DeleteAgentParams,
    ) -> Result<models::DeletePublicAgentResponseDTO> {
        let path = format!("/agent-studio/agent/{}", crate::services::encode(agent_id));
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::DELETE,
                &path,
                &query,
                None::<&()>,
                Some("v3"),
            )
            .await
    }

    /// Get Agent
    ///
    /// Gets a specific agent by its ID for the specified location with all its versions.
    /// Returns complete agent metadata and all non-deleted versions (draft, staging,
    /// production). locationId is required parameter. The agent must have active status.
    ///
    /// `GET /agent-studio/agent/{agentId}`
    ///
    /// Requires scope: `agent-studio.readonly`.
    pub async fn get_agent(
        &self,
        agent_id: &str,
        params: &GetAgentParams,
    ) -> Result<models::GetAgentByIdResponseDTO> {
        let path = format!("/agent-studio/agent/{}", crate::services::encode(agent_id));
        let query = params.to_query();
        self.client
            .send_versioned(reqwest::Method::GET, &path, &query, None::<&()>, Some("v3"))
            .await
    }

    /// Update Agent Metadata
    ///
    /// Updates agent metadata such as name, description, and status.
    ///
    /// `PATCH /agent-studio/agent/{agentId}`
    ///
    /// Requires scope: `agent-studio.write`.
    pub async fn update_agent_metadata(
        &self,
        agent_id: &str,
        params: &UpdateAgentMetadataParams,
        body: &models::UpdatePublicAgentMetadataDTO,
    ) -> Result<models::UpdatePublicAgentResponseDTO> {
        let path = format!("/agent-studio/agent/{}", crate::services::encode(agent_id));
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::PATCH,
                &path,
                &query,
                Some(body),
                Some("v3"),
            )
            .await
    }

    /// Execute Agent
    ///
    /// Executes the specified agent and returns a non-streaming JSON response with the
    /// complete agent output. The agent must be in active status and belong to the
    /// specified location. locationId is required in the request body. **Session
    /// Management:** - For the first message in a new session, do not include the
    /// `executionId` in the request payload. - The API will return an `executionId` along
    /// with the agent response, which uniquely identifies this conversation session. - To
    /// continue the conversation within the same session, include the `executionId` from
    /// the previous response in subsequent requests. T
    ///
    /// `POST /agent-studio/agent/{agentId}/execute`
    ///
    /// Requires scope: `agent-studio.write`.
    pub async fn execute_agent(
        &self,
        agent_id: &str,
        params: &ExecuteAgentParams,
        body: &models::ExecutePublicAgentDTO,
    ) -> Result<models::ExecutePublicAgentResponseDTO> {
        let path = format!(
            "/agent-studio/agent/{}/execute",
            crate::services::encode(agent_id)
        );
        let query = params.to_query();
        self.client
            .send_versioned(reqwest::Method::POST, &path, &query, Some(body), Some("v3"))
            .await
    }

    /// List Agents (Deprecated)
    ///
    /// **Deprecated endpoint - use GET /agent instead.** Lists all active agents that have
    /// a published production version for the specified location. locationId is required
    /// parameter. Supports pagination using limit and offset.
    ///
    /// `GET /agent-studio/public-api/agents`
    ///
    /// Requires scope: `agent-studio.readonly`.
    pub async fn list_agents_deprecated(
        &self,
        params: &ListAgentsDeprecatedParams,
    ) -> Result<models::GetPublishedAgentsResponseDTO> {
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::GET,
                "/agent-studio/public-api/agents",
                &query,
                None::<&()>,
                Some("v3"),
            )
            .await
    }

    /// Get Agent (Deprecated)
    ///
    /// **Deprecated endpoint - use GET /agent/:agentId instead.** Gets a specific agent by
    /// its ID for the specified location with all its versions. locationId is required
    /// parameter. The agent must have active status.
    ///
    /// `GET /agent-studio/public-api/agents/{agentId}`
    ///
    /// Requires scope: `agent-studio.readonly`.
    pub async fn get_agent_deprecated(
        &self,
        agent_id: &str,
        params: &GetAgentDeprecatedParams,
    ) -> Result<models::GetAgentByIdResponseDTO> {
        let path = format!(
            "/agent-studio/public-api/agents/{}",
            crate::services::encode(agent_id)
        );
        let query = params.to_query();
        self.client
            .send_versioned(reqwest::Method::GET, &path, &query, None::<&()>, Some("v3"))
            .await
    }

    /// Execute Agent (Deprecated)
    ///
    /// **Deprecated endpoint - use POST /agent/:agentId/execute instead.** Executes the
    /// specified agent and returns a non-streaming JSON response with the complete agent
    /// output. The agent must be in active status and belong to the specified location.
    /// locationId is required in the request body. **Session Management:** - For the first
    /// message in a new session, do not include the `executionId` in the request payload. -
    /// The API will return an `executionId` along with the agent response, which uniquely
    /// identifies this conversation session. - To continue the conversation within the same
    /// session, include th
    ///
    /// `POST /agent-studio/public-api/agents/{agentId}/execute`
    ///
    /// Requires scope: `agent-studio.write`.
    pub async fn execute_agent_deprecated(
        &self,
        agent_id: &str,
        params: &ExecuteAgentDeprecatedParams,
        body: &models::ExecutePublicAgentDTO,
    ) -> Result<models::ExecutePublicAgentResponseDTO> {
        let path = format!(
            "/agent-studio/public-api/agents/{}/execute",
            crate::services::encode(agent_id)
        );
        let query = params.to_query();
        self.client
            .send_versioned(reqwest::Method::POST, &path, &query, Some(body), Some("v3"))
            .await
    }
}