ghl-sdk 0.5.2

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

#![allow(clippy::too_many_arguments)]

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

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

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

/// Query parameters for [`VoiceAiService::delete_agent_action`].
#[derive(Debug, Clone, Default)]
pub struct DeleteAgentActionParams {
    /// Location ID
    /// Required by the API.
    pub location_id: String,
    /// Agent ID the action is attached to
    /// Required by the API.
    pub agent_id: String,
}

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

    fn to_query(&self) -> Vec<(String, String)> {
        let q: Vec<(String, String)> = vec![
            ("locationId".into(), self.location_id.clone()),
            ("agentId".into(), self.agent_id.clone()),
        ];
        q
    }
}

/// Query parameters for [`VoiceAiService::get_agent_action`].
#[derive(Debug, Clone, Default)]
pub struct GetAgentActionParams {
    /// Location ID
    /// Required by the API.
    pub location_id: String,
}

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

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

/// Query parameters for [`VoiceAiService::list_agents`].
#[derive(Debug, Clone, Default)]
pub struct ListAgentsParams {
    /// Page number starting from 1
    pub page: Option<f64>,
    /// Number of items per page
    pub page_size: Option<f64>,
    /// Location ID
    /// Required by the API.
    pub location_id: String,
    /// Query
    pub query: Option<String>,
}

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

    /// Page number starting from 1
    pub fn page(mut self, v: f64) -> Self {
        self.page = Some(v);
        self
    }

    /// Number of items per page
    pub fn page_size(mut self, v: f64) -> Self {
        self.page_size = Some(v);
        self
    }

    /// Query
    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![("locationId".into(), self.location_id.clone())];
        if let Some(v) = &self.page {
            q.push(("page".into(), v.to_string()));
        }
        if let Some(v) = &self.page_size {
            q.push(("pageSize".into(), v.to_string()));
        }
        if let Some(v) = &self.query {
            q.push(("query".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`VoiceAiService::delete_agent`].
#[derive(Debug, Clone, Default)]
pub struct DeleteAgentParams {
    /// Location ID
    /// Required by the API.
    pub location_id: 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(),
        }
    }

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

/// Query parameters for [`VoiceAiService::get_agent`].
#[derive(Debug, Clone, Default)]
pub struct GetAgentParams {
    /// Location ID
    /// Required by the API.
    pub location_id: 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(),
        }
    }

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

/// Query parameters for [`VoiceAiService::patch_agent`].
#[derive(Debug, Clone, Default)]
pub struct PatchAgentParams {
    /// Location ID
    /// Required by the API.
    pub location_id: String,
}

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

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

/// Query parameters for [`VoiceAiService::list_call_logs`].
#[derive(Debug, Clone, Default)]
pub struct ListCallLogsParams {
    /// Location identifier. Filters results to this location.
    /// Required by the API.
    pub location_id: String,
    /// Agent identifier. When provided, returns logs for this agent only.
    pub agent_id: Option<String>,
    /// Contact IDs (comma-separated) to filter by.
    pub contact_id: Option<String>,
    /// Call type filter.
    /// Allowed values: `LIVE`, `TRIAL`.
    pub call_type: Option<String>,
    /// Start date filter (Unix timestamp). Must be less than endDate. Both startDate and
    /// endDate must be provided together.
    pub start_date: Option<f64>,
    /// End date filter (Unix timestamp). Must be greater than startDate. Both startDate and
    /// endDate must be provided together.
    pub end_date: Option<f64>,
    /// Action type filter for call logs (comma-separated ACTION_TYPE values)
    /// Allowed values: `CALL_TRANSFER`, `DATA_EXTRACTION`, `IN_CALL_DATA_EXTRACTION`,
    /// `WORKFLOW_TRIGGER`, `SMS`, `APPOINTMENT_BOOKING`, `CUSTOM_ACTION`, `KNOWLEDGE_BASE`.
    pub action_type: Option<String>,
    /// Field to sort by. Defaults to newest if omitted.
    /// Allowed values: `duration`, `createdAt`.
    pub sort_by: Option<String>,
    /// Sort direction. Applies only when sortBy is provided.
    /// Allowed values: `ascend`, `descend`.
    pub sort: Option<String>,
    /// Page number (1-based).
    pub page: Option<f64>,
    /// Page size (max 50).
    pub page_size: Option<f64>,
}

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

    /// Agent identifier. When provided, returns logs for this agent only.
    pub fn agent_id(mut self, v: impl Into<String>) -> Self {
        self.agent_id = Some(v.into());
        self
    }

    /// Contact IDs (comma-separated) to filter by.
    pub fn contact_id(mut self, v: impl Into<String>) -> Self {
        self.contact_id = Some(v.into());
        self
    }

    /// Call type filter.
    pub fn call_type(mut self, v: impl Into<String>) -> Self {
        self.call_type = Some(v.into());
        self
    }

    /// Start date filter (Unix timestamp). Must be less than endDate. Both startDate and
    /// endDate must be provided together.
    pub fn start_date(mut self, v: f64) -> Self {
        self.start_date = Some(v);
        self
    }

    /// End date filter (Unix timestamp). Must be greater than startDate. Both startDate and
    /// endDate must be provided together.
    pub fn end_date(mut self, v: f64) -> Self {
        self.end_date = Some(v);
        self
    }

    /// Action type filter for call logs (comma-separated ACTION_TYPE values)
    pub fn action_type(mut self, v: impl Into<String>) -> Self {
        self.action_type = Some(v.into());
        self
    }

    /// Field to sort by. Defaults to newest if omitted.
    pub fn sort_by(mut self, v: impl Into<String>) -> Self {
        self.sort_by = Some(v.into());
        self
    }

    /// Sort direction. Applies only when sortBy is provided.
    pub fn sort(mut self, v: impl Into<String>) -> Self {
        self.sort = Some(v.into());
        self
    }

    /// Page number (1-based).
    pub fn page(mut self, v: f64) -> Self {
        self.page = Some(v);
        self
    }

    /// Page size (max 50).
    pub fn page_size(mut self, v: f64) -> Self {
        self.page_size = Some(v);
        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.agent_id {
            q.push(("agentId".into(), v.to_string()));
        }
        if let Some(v) = &self.contact_id {
            q.push(("contactId".into(), v.to_string()));
        }
        if let Some(v) = &self.call_type {
            q.push(("callType".into(), v.to_string()));
        }
        if let Some(v) = &self.start_date {
            q.push(("startDate".into(), v.to_string()));
        }
        if let Some(v) = &self.end_date {
            q.push(("endDate".into(), v.to_string()));
        }
        if let Some(v) = &self.action_type {
            q.push(("actionType".into(), v.to_string()));
        }
        if let Some(v) = &self.sort_by {
            q.push(("sortBy".into(), v.to_string()));
        }
        if let Some(v) = &self.sort {
            q.push(("sort".into(), v.to_string()));
        }
        if let Some(v) = &self.page {
            q.push(("page".into(), v.to_string()));
        }
        if let Some(v) = &self.page_size {
            q.push(("pageSize".into(), v.to_string()));
        }
        q
    }
}

/// Query parameters for [`VoiceAiService::get_call_log`].
#[derive(Debug, Clone, Default)]
pub struct GetCallLogParams {
    /// Location ID
    /// Required by the API.
    pub location_id: String,
}

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

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

impl VoiceAiService {
    /// Create Agent Action
    ///
    /// Create a new action for a voice AI agent. Actions define specific behaviors and
    /// capabilities for the agent during calls.
    ///
    /// `POST /voice-ai/actions`
    ///
    /// Requires scope: `voice-ai-agent-goals.write`.
    pub async fn create_agent_action(
        &self,
        body: &models::CreateSingleActionDTO,
    ) -> Result<models::CreateActionResponseDTO> {
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::POST,
                "/voice-ai/actions",
                &query,
                Some(body),
                Some("v3"),
            )
            .await
    }

    /// Delete Agent Action
    ///
    /// Delete an existing action from a voice AI agent. This permanently removes the action
    /// and its configuration.
    ///
    /// `DELETE /voice-ai/actions/{actionId}`
    ///
    /// Requires scope: `voice-ai-agent-goals.write`.
    pub async fn delete_agent_action(
        &self,
        action_id: &str,
        params: &DeleteAgentActionParams,
    ) -> Result<serde_json::Value> {
        let path = format!("/voice-ai/actions/{}", crate::services::encode(action_id));
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::DELETE,
                &path,
                &query,
                None::<&()>,
                Some("v3"),
            )
            .await
    }

    /// Get Agent Action
    ///
    /// Retrieve details of a specific action by its ID. Returns the action configuration
    /// including actionParameters.
    ///
    /// `GET /voice-ai/actions/{actionId}`
    ///
    /// Requires scope: `voice-ai-agent-goals.readonly`.
    pub async fn get_agent_action(
        &self,
        action_id: &str,
        params: &GetAgentActionParams,
    ) -> Result<models::GetActionResponseDTO> {
        let path = format!("/voice-ai/actions/{}", crate::services::encode(action_id));
        let query = params.to_query();
        self.client
            .send_versioned(reqwest::Method::GET, &path, &query, None::<&()>, Some("v3"))
            .await
    }

    /// Update Agent Action
    ///
    /// Update an existing action for a voice AI agent. Modifies the behavior and
    /// configuration of an agent action.
    ///
    /// `PUT /voice-ai/actions/{actionId}`
    ///
    /// Requires scope: `voice-ai-agent-goals.write`.
    pub async fn update_agent_action(
        &self,
        action_id: &str,
        body: &models::UpdateSingleActionDTO,
    ) -> Result<models::UpdateActionResponseDTO> {
        let path = format!("/voice-ai/actions/{}", crate::services::encode(action_id));
        let query = Vec::new();
        self.client
            .send_versioned(reqwest::Method::PUT, &path, &query, Some(body), Some("v3"))
            .await
    }

    /// List Agents
    ///
    /// Retrieve a paginated list of agents for given location.
    ///
    /// `GET /voice-ai/agents`
    ///
    /// Requires scope: `voice-ai-agents.readonly`.
    pub async fn list_agents(
        &self,
        params: &ListAgentsParams,
    ) -> Result<models::GetAgentsResponseDTO> {
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::GET,
                "/voice-ai/agents",
                &query,
                None::<&()>,
                Some("v3"),
            )
            .await
    }

    /// Create Agent
    ///
    /// Create a new voice AI agent configuration and settings
    ///
    /// `POST /voice-ai/agents`
    ///
    /// Requires scope: `voice-ai-agents.write`.
    pub async fn create_agent(
        &self,
        body: &models::AgentCreationRequestDTO,
    ) -> Result<models::CreateAgentResponseDTO> {
        let query = Vec::new();
        self.client
            .send_versioned(
                reqwest::Method::POST,
                "/voice-ai/agents",
                &query,
                Some(body),
                Some("v3"),
            )
            .await
    }

    /// Delete Agent
    ///
    /// Delete a voice AI agent and all its configurations
    ///
    /// `DELETE /voice-ai/agents/{agentId}`
    ///
    /// Requires scope: `voice-ai-agents.write`.
    pub async fn delete_agent(
        &self,
        agent_id: &str,
        params: &DeleteAgentParams,
    ) -> Result<serde_json::Value> {
        let path = format!("/voice-ai/agents/{}", 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
    ///
    /// Retrieve detailed configuration and settings for a specific voice AI agent
    ///
    /// `GET /voice-ai/agents/{agentId}`
    ///
    /// Requires scope: `voice-ai-agents.readonly`.
    pub async fn get_agent(
        &self,
        agent_id: &str,
        params: &GetAgentParams,
    ) -> Result<models::GetAgentResponseDTO> {
        let path = format!("/voice-ai/agents/{}", crate::services::encode(agent_id));
        let query = params.to_query();
        self.client
            .send_versioned(reqwest::Method::GET, &path, &query, None::<&()>, Some("v3"))
            .await
    }

    /// Patch Agent
    ///
    /// Partially update an existing voice AI agent
    ///
    /// `PATCH /voice-ai/agents/{agentId}`
    ///
    /// Requires scope: `voice-ai-agents.write`.
    pub async fn patch_agent(
        &self,
        agent_id: &str,
        params: &PatchAgentParams,
        body: &models::PatchAgentDTO,
    ) -> Result<models::PatchAgentResponseDTO> {
        let path = format!("/voice-ai/agents/{}", crate::services::encode(agent_id));
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::PATCH,
                &path,
                &query,
                Some(body),
                Some("v3"),
            )
            .await
    }

    /// List Call Logs
    ///
    /// Returns call logs for Voice AI agents scoped to a location. Supports filtering by
    /// agent, contact, call type, action types, and date range (interpreted in the provided
    /// IANA timezone). Also supports sorting and 1-based pagination.
    ///
    /// `GET /voice-ai/dashboard/call-logs`
    ///
    /// Requires scope: `voice-ai-dashboard.readonly`.
    pub async fn list_call_logs(
        &self,
        params: &ListCallLogsParams,
    ) -> Result<models::CallLogsResponseDTO> {
        let query = params.to_query();
        self.client
            .send_versioned(
                reqwest::Method::GET,
                "/voice-ai/dashboard/call-logs",
                &query,
                None::<&()>,
                Some("v3"),
            )
            .await
    }

    /// Get Call Log
    ///
    /// Returns a call log by callId.
    ///
    /// `GET /voice-ai/dashboard/call-logs/{callId}`
    ///
    /// Requires scope: `voice-ai-dashboard.readonly`.
    pub async fn get_call_log(
        &self,
        call_id: &str,
        params: &GetCallLogParams,
    ) -> Result<models::CallLogDTO> {
        let path = format!(
            "/voice-ai/dashboard/call-logs/{}",
            crate::services::encode(call_id)
        );
        let query = params.to_query();
        self.client
            .send_versioned(reqwest::Method::GET, &path, &query, None::<&()>, Some("v3"))
            .await
    }
}