ghl-sdk 0.5.1

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

#![allow(clippy::too_many_arguments)]

use crate::client::Ghl;
use crate::error::Result;
use ghl_models::v2::conversation_ai as models;

/// Typed access to the `conversation-ai` API v2 surface (12 operations). Obtained via
/// [`Ghl::conversation_ai`](crate::Ghl::conversation_ai).
#[derive(Debug, Clone)]
pub struct ConversationAiService {
    pub(crate) client: Ghl,
}

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

/// Query parameters for [`ConversationAiService::search_agents`].
#[derive(Debug, Clone, Default)]
pub struct SearchAgentsParams {
    /// Start after is the agent id to start after, Serving as skip, send empty when first
    /// page
    pub start_after: Option<String>,
    /// Records per page
    pub limit: Option<f64>,
    /// query to search on agent name, must be provided in lowercase
    pub query: Option<String>,
}

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

    /// Start after is the agent id to start after, Serving as skip, send empty when first
    /// page
    pub fn start_after(mut self, v: impl Into<String>) -> Self {
        self.start_after = Some(v.into());
        self
    }

    /// Records per page
    pub fn limit(mut self, v: f64) -> Self {
        self.limit = Some(v);
        self
    }

    /// query to search on agent name, must be provided in lowercase
    pub fn query(mut self, v: impl Into<String>) -> Self {
        self.query = Some(v.into());
        self
    }

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

/// Query parameters for [`ConversationAiService::get_the_generation_details`].
#[derive(Debug, Clone, Default)]
pub struct GetTheGenerationDetailsParams {
    /// Message Id
    /// Required by the API.
    pub message_id: String,
    /// `source` query parameter.
    /// Allowed values: `conversation`, `workflow`.
    /// Required by the API.
    pub source: String,
}

impl GetTheGenerationDetailsParams {
    /// Start from the parameters the API requires.
    pub fn new(message_id: impl Into<String>, source: impl Into<String>) -> Self {
        Self {
            message_id: message_id.into(),
            source: source.into(),
        }
    }

    fn to_query(&self) -> Vec<(String, String)> {
        let q: Vec<(String, String)> = vec![
            ("messageId".into(), self.message_id.clone()),
            ("source".into(), self.source.clone()),
        ];
        q
    }
}

impl ConversationAiService {
    /// Create an Agent
    ///
    /// Creates a new AI agent for the location. The agent will be created with the
    /// specified configuration including name, role, actions, and behavior settings.
    ///
    /// `POST /conversation-ai/agents`
    ///
    /// Requires scope: `conversation-ai.write`.
    pub async fn create_an_agent(
        &self,
        body: &models::CreateEmployeeDto,
    ) -> Result<models::EmployeeResponseDTO> {
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::POST,
                "/conversation-ai/agents",
                &query,
                Some(body),
                Some("2021-04-15"),
            )
            .await
    }

    /// Search Agents
    ///
    /// Searches for AI agents based on various criteria including name, status, and
    /// configuration. Supports advanced filtering and full-text search capabilities.
    ///
    /// `GET /conversation-ai/agents/search`
    ///
    /// Requires scope: `conversation-ai.readonly`.
    pub async fn search_agents(
        &self,
        params: &SearchAgentsParams,
    ) -> Result<models::SearchEmployeeResponseDTO> {
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::GET,
                "/conversation-ai/agents/search",
                &query,
                None::<&()>,
                Some("2021-04-15"),
            )
            .await
    }

    /// Delete Agent
    ///
    /// Deletes an AI agent permanently. This action cannot be undone. All associated
    /// configurations and conversation history will be removed.
    ///
    /// `DELETE /conversation-ai/agents/{agentId}`
    ///
    /// Requires scope: `conversation-ai.write`.
    pub async fn delete_agent(&self, agent_id: &str) -> Result<models::DeleteEmployeeResponseDTO> {
        let path = format!(
            "/conversation-ai/agents/{}",
            crate::services::encode(agent_id)
        );
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::DELETE,
                &path,
                &query,
                None::<&()>,
                Some("2021-04-15"),
            )
            .await
    }

    /// Get Agent
    ///
    /// Retrieves a specific AI agent by its ID. Returns the complete agent configuration
    /// including name, status, actions, and settings.
    ///
    /// `GET /conversation-ai/agents/{agentId}`
    ///
    /// Requires scope: `conversation-ai.readonly`.
    pub async fn get_agent(&self, agent_id: &str) -> Result<models::EmployeeResponseDTO> {
        let path = format!(
            "/conversation-ai/agents/{}",
            crate::services::encode(agent_id)
        );
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::GET,
                &path,
                &query,
                None::<&()>,
                Some("2021-04-15"),
            )
            .await
    }

    /// Update Agent
    ///
    /// Updates an existing AI agent's configuration. All fields in the agent configuration
    /// can be updated including name, status, actions, and behavior settings.
    ///
    /// `PUT /conversation-ai/agents/{agentId}`
    ///
    /// Requires scope: `conversation-ai.write`.
    pub async fn update_agent(
        &self,
        agent_id: &str,
        body: &models::UpdateEmployeeDto,
    ) -> Result<models::EmployeeResponseDTO> {
        let path = format!(
            "/conversation-ai/agents/{}",
            crate::services::encode(agent_id)
        );
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::PUT,
                &path,
                &query,
                Some(body),
                Some("2021-04-15"),
            )
            .await
    }

    /// Attach Action to Agent
    ///
    /// Creates and attach a new action for an AI agent. Actions define specific tasks or
    /// behaviors that the agent can perform, such as booking appointments, sending
    /// follow-ups, or collecting information.
    ///
    /// `POST /conversation-ai/agents/{agentId}/actions`
    ///
    /// Requires scope: `conversation-ai.write`.
    pub async fn attach_action_to_agent(
        &self,
        agent_id: &str,
        body: &models::CreateActionDTO,
    ) -> Result<models::CreateActionResponseDTO> {
        let path = format!(
            "/conversation-ai/agents/{}/actions",
            crate::services::encode(agent_id)
        );
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::POST,
                &path,
                &query,
                Some(body),
                Some("2021-04-15"),
            )
            .await
    }

    /// List Actions for an Agent
    ///
    /// List for actions for an agent
    ///
    /// `GET /conversation-ai/agents/{agentId}/actions/list`
    ///
    /// Requires scope: `conversation-ai.readonly`.
    pub async fn list_actions_for_an_agent(
        &self,
        agent_id: &str,
    ) -> Result<models::FetchActionsForEmployeeResponseDTO> {
        let path = format!(
            "/conversation-ai/agents/{}/actions/list",
            crate::services::encode(agent_id)
        );
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::GET,
                &path,
                &query,
                None::<&()>,
                Some("2021-04-15"),
            )
            .await
    }

    /// Remove Action from Agent
    ///
    /// Permanently deletes an action. This will remove the action from all associated
    /// agents and cannot be undone.
    ///
    /// `DELETE /conversation-ai/agents/{agentId}/actions/{actionId}`
    ///
    /// Requires scope: `conversation-ai.write`.
    pub async fn remove_action_from_agent(
        &self,
        agent_id: &str,
        action_id: &str,
    ) -> Result<models::DeleteActionResponseDTO> {
        let path = format!(
            "/conversation-ai/agents/{}/actions/{}",
            crate::services::encode(agent_id),
            crate::services::encode(action_id)
        );
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::DELETE,
                &path,
                &query,
                None::<&()>,
                Some("2021-04-15"),
            )
            .await
    }

    /// Get Action by ID
    ///
    /// Retrieves detailed information about a specific action using its unique identifier.
    /// Returns the action configuration, associated agents, and performance metrics.
    ///
    /// `GET /conversation-ai/agents/{agentId}/actions/{actionId}`
    ///
    /// Requires scope: `conversation-ai.readonly`.
    pub async fn get_action_by_id(
        &self,
        agent_id: &str,
        action_id: &str,
    ) -> Result<models::FetchActionDetailsResponseDTO> {
        let path = format!(
            "/conversation-ai/agents/{}/actions/{}",
            crate::services::encode(agent_id),
            crate::services::encode(action_id)
        );
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::GET,
                &path,
                &query,
                None::<&()>,
                Some("2021-04-15"),
            )
            .await
    }

    /// Update Action
    ///
    /// Updates an existing action's configuration. This includes modifying the action name,
    /// description, trigger conditions, and behavior settings.
    ///
    /// `PUT /conversation-ai/agents/{agentId}/actions/{actionId}`
    ///
    /// Requires scope: `conversation-ai.write`.
    pub async fn update_action(
        &self,
        agent_id: &str,
        action_id: &str,
        body: &models::CreateActionDTO,
    ) -> Result<models::UpdateActionResponseDTO> {
        let path = format!(
            "/conversation-ai/agents/{}/actions/{}",
            crate::services::encode(agent_id),
            crate::services::encode(action_id)
        );
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::PUT,
                &path,
                &query,
                Some(body),
                Some("2021-04-15"),
            )
            .await
    }

    /// Update Followup Settings
    ///
    /// Update the followup settings for an action
    ///
    /// `PATCH /conversation-ai/agents/{agentId}/followup-settings`
    ///
    /// Requires scope: `conversation-ai.write`.
    pub async fn update_followup_settings(
        &self,
        agent_id: &str,
        body: &models::UpdateFollowupSettingsDTO,
    ) -> Result<models::UpdateActionResponseDTO> {
        let path = format!(
            "/conversation-ai/agents/{}/followup-settings",
            crate::services::encode(agent_id)
        );
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::PATCH,
                &path,
                &query,
                Some(body),
                Some("2021-04-15"),
            )
            .await
    }

    /// Get the generation details
    ///
    /// Retrieves detailed information about AI responses including the System Prompt,
    /// Conversation history, Knowledge base, website, FAQ chunks, and Rich Text chunks.
    ///
    /// `GET /conversation-ai/generations`
    ///
    /// Requires scope: `conversation-ai.readonly`.
    pub async fn get_the_generation_details(
        &self,
        params: &GetTheGenerationDetailsParams,
    ) -> Result<models::FetchAIResponseDetailsResponseDTO> {
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::GET,
                "/conversation-ai/generations",
                &query,
                None::<&()>,
                Some("2021-04-15"),
            )
            .await
    }
}