babelforce_manager_sdk/resources/

agents.rs

use crate::error::{map_manager_err, ManagerError};
use crate::gen::manager::apis::configuration::Configuration;
use crate::gen::manager::apis::{agent_api, agent_group_api, manager_api};
use crate::gen::manager::models;
use crate::http::{collect_all, fetch_page, Page};
use crate::resources::raw::get_json;
use crate::retry::{with_retry, RetryPolicy};
use crate::token::SharedCfg;

/// Optional server-side filters for the agents list surfaces ([`AgentsResource::list`] /
/// [`AgentsResource::list_page`]). All fields combine; the default filters nothing.
#[derive(Debug, Clone, Default)]
pub struct ListAgentsQuery {
    /// Free-text search across name, group name, number, email, sourceId and integration label.
    pub q: Option<String>,
    /// Only enabled (`true`) or only disabled (`false`) agents.
    pub enabled: Option<bool>,
    /// Filter by agent name.
    pub name: Option<String>,
    /// Filter by the agent's number.
    pub number: Option<String>,
    /// Filter by integration source id.
    pub source_id: Option<String>,
    /// Filter by line status.
    pub state: Option<models::AgentLineStatus>,
    /// Filter by source integration.
    pub source: Option<String>,
    /// Restrict to agents in these group id(s). A hyphenated UUID is normalized to the API's
    /// unhyphenated form, so a listed group id round-trips as a filter.
    pub group_ids: Vec<String>,
    /// Restrict to agents in these group name(s).
    pub groups: Vec<String>,
    /// Filter by tag(s).
    pub tags: Vec<String>,
}

impl ListAgentsQuery {
    /// Serialize as `/api/v2/agents?...` with the spec's form/explode semantics — array filters
    /// travel as repeated `key=value` pairs.
    fn to_path(&self, page: i32, max: Option<i32>) -> String {
        let mut ser = url::form_urlencoded::Serializer::new(String::new());
        ser.append_pair("page", &page.to_string());
        if let Some(max) = max {
            ser.append_pair("max", &max.to_string());
        }
        if let Some(v) = &self.q {
            ser.append_pair("q", v);
        }
        if let Some(v) = self.enabled {
            ser.append_pair("enabled", if v { "true" } else { "false" });
        }
        if let Some(v) = &self.name {
            ser.append_pair("name", v);
        }
        if let Some(v) = &self.number {
            ser.append_pair("number", v);
        }
        if let Some(v) = &self.source_id {
            ser.append_pair("sourceId", v);
        }
        if let Some(v) = &self.state {
            ser.append_pair("state", &v.to_string());
        }
        if let Some(v) = &self.source {
            ser.append_pair("source", v);
        }
        for id in &self.group_ids {
            ser.append_pair("groupIds", &normalize_entity_id(id));
        }
        for g in &self.groups {
            ser.append_pair("groups", g);
        }
        for t in &self.tags {
            ser.append_pair("tags", t);
        }
        format!("/api/v2/agents?{}", ser.finish())
    }
}

/// babelforce entity ids are unhyphenated 32-char hex; normalize a hyphenated UUID the same way
/// the generated path helper does. Non-UUID values pass through unchanged.
fn normalize_entity_id(v: &str) -> String {
    match uuid::Uuid::parse_str(v) {
        Ok(u) => u.simple().to_string(),
        Err(_) => v.to_string(),
    }
}

/// Agent management — `/api/v2/agents`, with a nested `groups` sub-resource.
pub struct AgentsResource {
    pub(crate) cfg: SharedCfg<Configuration>,
    pub(crate) retry: RetryPolicy,
    /// Agent groups — `/api/v2/agents/groups`.
    pub groups: AgentGroupsResource,
}

impl AgentsResource {
    /// List agents matching `query`, auto-paginated across pages.
    ///
    /// Stands in for the generated `list_agents`, whose `groupIds`/`groups`/`tags` parameters
    /// (anyOf string-or-array types) are JSON-serialized into the query — a single id would be
    /// sent as `?groupIds="…"` with literal quotes, which the server does not match. The facade
    /// builds the form/explode query itself and decodes into the same generated response model.
    pub async fn list(&self, query: ListAgentsQuery) -> Result<Vec<models::Agent>, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        let query = &query;
        collect_all(
            &self.retry,
            |e| e,
            |page| async move {
                let v = get_json(cfg, &query.to_path(page, None)).await?;
                let r: models::PaginatedAgentResponse =
                    serde_json::from_value(v).map_err(|e| ManagerError::Decode(e.to_string()))?;
                Ok((
                    r.items,
                    r.pagination.pages.unwrap_or(1),
                    r.pagination.current.unwrap_or(1),
                ))
            },
        )
        .await
    }

    /// List all agents (unfiltered, auto-paginated) — [`AgentsResource::list`] with no filters.
    pub async fn list_all(&self) -> Result<Vec<models::Agent>, ManagerError> {
        self.list(ListAgentsQuery::default()).await
    }

    /// List one page of agents, optionally filtered server-side.
    pub async fn list_page(
        &self,
        page: i32,
        per_page: Option<i32>,
        query: ListAgentsQuery,
    ) -> Result<Page<models::Agent>, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        let query = &query;
        fetch_page(
            &self.retry,
            |e| e,
            || async move {
                let v = get_json(cfg, &query.to_path(page, per_page)).await?;
                let r: models::PaginatedAgentResponse =
                    serde_json::from_value(v).map_err(|e| ManagerError::Decode(e.to_string()))?;
                Ok((
                    r.items,
                    r.pagination.pages.unwrap_or(1),
                    r.pagination.current.unwrap_or(1),
                    r.pagination.total,
                ))
            },
        )
        .await
    }

    /// Create an agent.
    pub async fn create(
        &self,
        body: models::RestCreateAgent,
    ) -> Result<models::AgentItemResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_api::create_agent(cfg, body.clone())
        })
        .await
        .map_err(map_manager_err)
    }

    /// Get an agent by id.
    pub async fn get(&self, id: &str) -> Result<models::AgentItemResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, true, || agent_api::get_agent(cfg, id))
            .await
            .map_err(map_manager_err)
    }

    /// Update an agent.
    pub async fn update(
        &self,
        id: &str,
        body: models::RestUpdateAgent,
    ) -> Result<models::AgentItemResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_api::update_agent(cfg, id, body.clone())
        })
        .await
        .map_err(map_manager_err)
    }

    /// Delete an agent.
    pub async fn delete(&self, id: &str) -> Result<(), ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || agent_api::delete_agent(cfg, id))
            .await
            .map_err(map_manager_err)?;
        Ok(())
    }

    /// Update an agent's status.
    pub async fn update_status(
        &self,
        id: &str,
        status: models::UpdateAgentStatusRequest,
    ) -> Result<models::AgentStatus, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            manager_api::update_agent_status(cfg, id, Some(status.clone()))
        })
        .await
        .map_err(map_manager_err)
    }

    /// List agent presences.
    pub async fn presences(&self) -> Result<models::AgentPresenceListResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, true, || agent_api::list_agent_presences(cfg))
            .await
            .map_err(map_manager_err)
    }

    /// Get an agent presence by name.
    pub async fn get_presence(
        &self,
        name: &str,
    ) -> Result<models::AgentPresenceItemResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, true, || {
            agent_api::get_agent_presence(cfg, name)
        })
        .await
        .map_err(map_manager_err)
    }

    /// Create an agent presence.
    pub async fn create_presence(
        &self,
        body: models::AgentPresenceWriteBody,
    ) -> Result<models::AgentPresenceItemResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_api::create_agent_presence(cfg, body.clone())
        })
        .await
        .map_err(map_manager_err)
    }

    /// Update an agent presence.
    pub async fn update_presence(
        &self,
        name: &str,
        body: models::AgentPresenceWriteBody,
    ) -> Result<models::AgentPresenceItemResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_api::update_agent_presence(cfg, name, body.clone())
        })
        .await
        .map_err(map_manager_err)
    }

    /// Delete an agent presence.
    pub async fn delete_presence(
        &self,
        name: &str,
    ) -> Result<models::DefaultV2MessageResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_api::delete_agent_presence(cfg, name)
        })
        .await
        .map_err(map_manager_err)
    }

    /// Get an agent's total status by id.
    pub async fn get_status(
        &self,
        id: &str,
    ) -> Result<models::AgentTotalStatusResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, true, || agent_api::get_agent_status(cfg, id))
            .await
            .map_err(map_manager_err)
    }

    /// List available agent statuses.
    pub async fn available_statuses(
        &self,
    ) -> Result<models::AgentAvailabilityListResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, true, || {
            agent_api::list_available_agent_statuses(cfg)
        })
        .await
        .map_err(map_manager_err)
    }

    /// Enable an agent.
    pub async fn enable(&self, id: &str) -> Result<models::DefaultV2MessageResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || agent_api::enable_agent(cfg, id))
            .await
            .map_err(map_manager_err)
    }

    /// Disable an agent.
    pub async fn disable(
        &self,
        id: &str,
    ) -> Result<models::DefaultV2MessageResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || agent_api::disable_agent(cfg, id))
            .await
            .map_err(map_manager_err)
    }

    /// Hang up an agent's active call.
    pub async fn hangup_call(
        &self,
        id: &str,
    ) -> Result<models::DefaultV2MessageResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || agent_api::hangup_agent_call(cfg, id))
            .await
            .map_err(map_manager_err)
    }

    /// Perform a bulk action (e.g. `enable`, `disable`, `delete`) on multiple agents.
    pub async fn bulk_action(
        &self,
        action: &str,
        body: models::AgentBulkRequest,
    ) -> Result<models::AgentBulkResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_api::bulk_agent_action(cfg, action, body.clone())
        })
        .await
        .map_err(map_manager_err)
    }

    /// Export all agents in the given format.
    pub async fn export(&self, format: &str) -> Result<String, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, true, || agent_api::export_agents(cfg, format))
            .await
            .map_err(map_manager_err)
    }

    /// Import agents from a file in the given format.
    #[allow(clippy::too_many_arguments)]
    pub async fn import_agents(
        &self,
        format: &str,
        file: std::path::PathBuf,
        r#async: Option<bool>,
        create_only: Option<bool>,
        update_only: Option<bool>,
        delete_unlisted: Option<bool>,
    ) -> Result<models::AgentImportValidationResults, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_api::import_agents(
                cfg,
                format,
                file.clone(),
                r#async,
                create_only,
                update_only,
                delete_unlisted,
            )
        })
        .await
        .map_err(map_manager_err)
    }

    /// Validate an agent import file without applying it.
    pub async fn validate_import(
        &self,
        file: std::path::PathBuf,
    ) -> Result<models::AgentImportValidationResults, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_api::validate_agent_import(cfg, file.clone())
        })
        .await
        .map_err(map_manager_err)
    }

    /// Get an agent import job by id.
    pub async fn get_import_job(
        &self,
        id: &str,
    ) -> Result<models::AgentImportJobItemResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, true, || {
            agent_api::get_agent_import_job(cfg, id)
        })
        .await
        .map_err(map_manager_err)
    }

    /// List an agent's logs (auto-paginated), optionally filtered by a `from`/`to` range.
    pub async fn logs(
        &self,
        id: &str,
        from: Option<i32>,
        to: Option<i32>,
    ) -> Result<Vec<models::AgentLogEntry>, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        collect_all(&self.retry, map_manager_err, |page| async move {
            let r = agent_api::list_agent_logs(cfg, id, Some(page), None, from, to).await?;
            let (pages, current) = r
                .pagination
                .as_ref()
                .map(|p| (p.pages.unwrap_or(1), p.current.unwrap_or(1)))
                .unwrap_or((1, 1));
            Ok((r.items, pages, current))
        })
        .await
    }

    /// List logs across all agents (auto-paginated).
    pub async fn all_logs(&self) -> Result<Vec<models::AgentLogEntry>, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        collect_all(&self.retry, map_manager_err, |page| async move {
            let r = agent_api::list_all_agent_logs(cfg, Some(page), None).await?;
            let (pages, current) = r
                .pagination
                .as_ref()
                .map(|p| (p.pages.unwrap_or(1), p.current.unwrap_or(1)))
                .unwrap_or((1, 1));
            Ok((r.items, pages, current))
        })
        .await
    }

    /// Push a message to an agent (or broadcast to all agents).
    pub async fn push(
        &self,
        body: models::AgentPushRequest,
    ) -> Result<models::DefaultV2MessageResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_api::push_to_agent(cfg, body.clone())
        })
        .await
        .map_err(map_manager_err)
    }

    /// Update an agent's password.
    pub async fn update_password(
        &self,
        id: &str,
        body: models::AgentPasswordUpdateRequest,
    ) -> Result<models::DefaultV2MessageResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_api::update_agent_password(cfg, id, body.clone())
        })
        .await
        .map_err(map_manager_err)
    }
}

/// Agent groups — `/api/v2/agents/groups`.
pub struct AgentGroupsResource {
    pub(crate) cfg: SharedCfg<Configuration>,
    pub(crate) retry: RetryPolicy,
}

impl AgentGroupsResource {
    /// List all agent groups (auto-paginated).
    pub async fn list_all(&self) -> Result<Vec<models::AgentGroup>, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        collect_all(&self.retry, map_manager_err, |page| async move {
            let r = agent_group_api::list_agent_groups(cfg, Some(page), None).await?;
            Ok((
                r.items,
                r.pagination.pages.unwrap_or(1),
                r.pagination.current.unwrap_or(1),
            ))
        })
        .await
    }

    /// Create an agent group.
    pub async fn create(
        &self,
        body: models::RestCreateAgentGroup,
    ) -> Result<models::AgentGroupItemResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_group_api::create_agent_group(cfg, body.clone())
        })
        .await
        .map_err(map_manager_err)
    }

    /// Get an agent group by id.
    pub async fn get(&self, id: &str) -> Result<models::AgentGroupItemResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, true, || {
            agent_group_api::get_agent_group(cfg, id)
        })
        .await
        .map_err(map_manager_err)
    }

    /// Update an agent group.
    pub async fn update(
        &self,
        id: &str,
        body: models::RestUpdateAgentGroup,
    ) -> Result<models::AgentGroupItemResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_group_api::update_agent_group(cfg, id, body.clone())
        })
        .await
        .map_err(map_manager_err)
    }

    /// Delete an agent group.
    pub async fn delete(&self, id: &str) -> Result<(), ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_group_api::delete_agent_group(cfg, id)
        })
        .await
        .map_err(map_manager_err)?;
        Ok(())
    }

    /// Add an agent to a group.
    pub async fn add_agent(
        &self,
        group_id: &str,
        agent_id: &str,
    ) -> Result<models::AgentGroupAdditionResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        let id = uuid::Uuid::parse_str(agent_id)
            .map_err(|e| ManagerError::InvalidArgument(format!("agent_id: {e}")))?;
        let body = models::AddAgentToGroupRequest { id };
        with_retry(&self.retry, false, || {
            manager_api::add_agent_to_group(cfg, group_id, Some(body.clone()))
        })
        .await
        .map_err(map_manager_err)
    }

    /// Remove an agent from a group.
    pub async fn remove_agent(
        &self,
        group_id: &str,
        agent_id: &str,
    ) -> Result<models::AgentGroupItemResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        with_retry(&self.retry, false, || {
            agent_group_api::remove_agent_from_group(cfg, group_id, agent_id)
        })
        .await
        .map_err(map_manager_err)
    }

    /// List all agents in a group (auto-paginated).
    pub async fn list_agents(&self, group_id: &str) -> Result<Vec<models::Agent>, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        collect_all(&self.retry, map_manager_err, |page| async move {
            let r = agent_group_api::list_agents_in_group(cfg, group_id, Some(page), None).await?;
            Ok((
                r.items,
                r.pagination.pages.unwrap_or(1),
                r.pagination.current.unwrap_or(1),
            ))
        })
        .await
    }

    /// Bulk-delete agent groups by id.
    pub async fn bulk_delete(
        &self,
        ids: Vec<String>,
    ) -> Result<models::DefaultV2MessageResponse, ManagerError> {
        let cfg = self.cfg.get().await?;
        let cfg = cfg.as_ref();
        let ids = ids
            .iter()
            .map(|id| {
                uuid::Uuid::parse_str(id)
                    .map_err(|e| ManagerError::InvalidArgument(format!("ids: {e}")))
            })
            .collect::<Result<Vec<_>, _>>()?;
        let body = models::BulkIdsRequest { ids };
        with_retry(&self.retry, false, || {
            agent_group_api::bulk_delete_agent_groups(cfg, body.clone())
        })
        .await
        .map_err(map_manager_err)
    }
}