videosdk-server-sdk 0.1.0

//! Inbound and outbound SIP trunks.

use std::collections::HashMap;
use std::sync::Arc;

use futures_util::Stream;
use reqwest::Method;
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};

use crate::client::{CallOptions, Client};
use crate::common::MessageResponse;
use crate::error::Result;
use crate::pagination::{auto_page, paginate, ListParams, Page, PageFetcher};
use crate::query::QueryBuilder;
use crate::resources::escape;
use crate::resources::sip::{SipAuth, SipMediaEncryption, SipRegion, SipTransport};

const INBOUND_PATH: &str = "/v2/sip/inbound-gateways";
const OUTBOUND_PATH: &str = "/v2/sip/outbound-gateways";

/// An inbound or outbound SIP trunk.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SipTrunk {
    /// The trunk id.
    pub id: String,
    /// The trunk's display name.
    pub name: Option<String>,
    /// The SIP host, for outbound trunks.
    pub address: Option<String>,
    /// The E.164 numbers this trunk handles.
    #[serde(default, deserialize_with = "crate::common::null_to_default")]
    pub numbers: Vec<String>,
    /// The allowed source IPs and CIDRs.
    #[serde(default, deserialize_with = "crate::common::null_to_default")]
    pub allowed_addresses: Vec<String>,
    /// The allowed caller-number patterns.
    #[serde(default, deserialize_with = "crate::common::null_to_default")]
    pub allowed_numbers: Vec<String>,
    /// Whether media is encrypted.
    pub media_encryption: Option<SipMediaEncryption>,
    /// The SIP transport.
    pub transport: Option<SipTransport>,
    /// Whether calls on this trunk are recorded.
    pub record: Option<bool>,
    /// Free-form tags.
    #[serde(default, deserialize_with = "crate::common::null_to_default")]
    pub tags: Vec<String>,
    /// The SIP credentials.
    pub auth: Option<SipAuth>,
    /// The SIP region.
    pub geo_region: Option<SipRegion>,
    /// Free-form metadata.
    #[serde(default, deserialize_with = "crate::common::null_to_default")]
    pub metadata: HashMap<String, String>,
    /// Whether noise cancellation is applied.
    pub noise_cancellation: Option<bool>,
    /// Whether DTMF is enabled.
    pub enable_dtmf: Option<bool>,
    /// Any fields the server returned that this SDK does not model yet.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// The parameters for [`InboundTrunkResource::create`].
#[derive(Debug, Clone, Default, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CreateInboundTrunkParams {
    /// The display name. Required.
    pub name: String,
    /// The E.164 numbers this trunk handles. Required, non-empty.
    pub numbers: Vec<String>,
    /// The SIP credentials.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub auth: Option<SipAuth>,
    /// The allowed source IPs and CIDRs.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub allowed_addresses: Vec<String>,
    /// The allowed caller-number patterns, e.g. `+91*`.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub allowed_numbers: Vec<String>,
    /// Whether to encrypt media.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub media_encryption: Option<SipMediaEncryption>,
    /// Whether to record calls on this trunk.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub record: Option<bool>,
    /// Whether to apply noise cancellation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub noise_cancellation: Option<bool>,
    /// Whether to enable DTMF.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub enable_dtmf: Option<bool>,
    /// Free-form metadata.
    #[serde(skip_serializing_if = "HashMap::is_empty")]
    pub metadata: HashMap<String, String>,
    /// Free-form tags.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
    /// The SIP region.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub geo_region: Option<SipRegion>,
}

/// The parameters for [`InboundTrunkResource::update`].
///
/// Omitted fields keep their current value, **except** `record`,
/// `noise_cancellation` and `enable_dtmf`, which reset to `false` when omitted,
/// and `geo_region`, which is cleared. Send the complete desired state.
#[derive(Debug, Clone, Default, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UpdateInboundTrunkParams {
    /// The display name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// The E.164 numbers this trunk handles.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub numbers: Vec<String>,
    /// The SIP credentials.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub auth: Option<SipAuth>,
    /// The allowed source IPs and CIDRs.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub allowed_addresses: Vec<String>,
    /// The allowed caller-number patterns.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub allowed_numbers: Vec<String>,
    /// Whether to encrypt media.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub media_encryption: Option<SipMediaEncryption>,
    /// Whether to record calls. Resets to `false` when omitted.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub record: Option<bool>,
    /// Whether to apply noise cancellation. Resets to `false` when omitted.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub noise_cancellation: Option<bool>,
    /// Whether to enable DTMF. Resets to `false` when omitted.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub enable_dtmf: Option<bool>,
    /// Free-form metadata.
    #[serde(skip_serializing_if = "HashMap::is_empty")]
    pub metadata: HashMap<String, String>,
    /// Free-form tags.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
    /// The SIP region. Cleared when omitted.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub geo_region: Option<SipRegion>,
}

/// The parameters for [`OutboundTrunkResource::create`].
#[derive(Debug, Clone, Default, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CreateOutboundTrunkParams {
    /// The display name. Required.
    pub name: String,
    /// The SIP host, e.g. `sip.telnyx.com:5061`. Required.
    pub address: String,
    /// The E.164 numbers for this trunk. The server rejects an outbound trunk
    /// without numbers.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub numbers: Vec<String>,
    /// The SIP transport. Defaults to TLS.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub transport: Option<SipTransport>,
    /// The SIP credentials.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub auth: Option<SipAuth>,
    /// Whether to encrypt media.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub media_encryption: Option<SipMediaEncryption>,
    /// Whether to record calls on this trunk.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub record: Option<bool>,
    /// Whether to apply noise cancellation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub noise_cancellation: Option<bool>,
    /// Whether to enable DTMF.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub enable_dtmf: Option<bool>,
    /// Free-form metadata.
    #[serde(skip_serializing_if = "HashMap::is_empty")]
    pub metadata: HashMap<String, String>,
    /// Free-form tags.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
    /// The SIP region.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub geo_region: Option<SipRegion>,
}

/// The parameters for [`OutboundTrunkResource::update`]. The same reset
/// semantics as [`UpdateInboundTrunkParams`] apply.
#[derive(Debug, Clone, Default, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UpdateOutboundTrunkParams {
    /// The display name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// The E.164 numbers for this trunk.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub numbers: Vec<String>,
    /// The SIP host.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub address: Option<String>,
    /// The SIP transport.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub transport: Option<SipTransport>,
    /// The SIP credentials.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub auth: Option<SipAuth>,
    /// Whether to encrypt media.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub media_encryption: Option<SipMediaEncryption>,
    /// Whether to record calls. Resets to `false` when omitted.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub record: Option<bool>,
    /// Whether to apply noise cancellation. Resets to `false` when omitted.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub noise_cancellation: Option<bool>,
    /// Whether to enable DTMF. Resets to `false` when omitted.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub enable_dtmf: Option<bool>,
    /// Free-form metadata.
    #[serde(skip_serializing_if = "HashMap::is_empty")]
    pub metadata: HashMap<String, String>,
    /// Free-form tags.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
    /// The SIP region. Cleared when omitted.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub geo_region: Option<SipRegion>,
    /// The allowed caller-number patterns. Outbound trunks accept this on update.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub allowed_numbers: Vec<String>,
}

/// The query parameters for listing trunks.
#[derive(Debug, Clone, Default)]
pub struct SipTrunkListParams {
    /// The 1-based page number.
    pub page: Option<u32>,
    /// Items per page.
    pub per_page: Option<u32>,
    /// An opaque cursor from a previous page.
    pub cursor: Option<String>,
    /// Filters by trunk id.
    pub id: Option<String>,
    /// A case-insensitive search on the trunk's name.
    pub search: Option<String>,
}

impl SipTrunkListParams {
    fn pagination(&self) -> ListParams {
        ListParams {
            page: self.page,
            per_page: self.per_page,
            cursor: self.cursor.clone(),
        }
    }
}

fn trunk_fetcher(client: &Client, path: &'static str, params: &SipTrunkListParams) -> PageFetcher {
    let client = client.clone();
    let params = params.clone();
    Arc::new(move |page, per_page| {
        let client = client.clone();
        let params = params.clone();
        Box::pin(async move {
            let query = QueryBuilder::new()
                .opt("page", page)
                .opt("perPage", per_page)
                .opt_str("id", params.id.as_deref())
                .opt_str("search", params.search.as_deref())
                .into_pairs();
            client
                .json::<Value>(Method::GET, path, CallOptions::new().query(query))
                .await
        })
    })
}

/// Inbound SIP trunks: connections that receive calls for a set of numbers.
/// Reached via [`SipTrunksResource::inbound`].
#[derive(Debug, Clone, Copy)]
pub struct InboundTrunkResource<'a> {
    client: &'a Client,
}

impl<'a> InboundTrunkResource<'a> {
    /// Creates an inbound trunk.
    pub async fn create(&self, params: CreateInboundTrunkParams) -> Result<SipTrunk> {
        self.client
            .json(Method::POST, INBOUND_PATH, CallOptions::json(&params)?)
            .await
    }

    /// Lists inbound trunks, one page at a time.
    pub async fn list(&self, params: SipTrunkListParams) -> Result<Page<SipTrunk>> {
        let fetcher = trunk_fetcher(self.client, INBOUND_PATH, &params);
        paginate(fetcher, &params.pagination(), "data", None).await
    }

    /// Lists inbound trunks, transparently fetching every page.
    pub fn list_stream(
        &self,
        params: SipTrunkListParams,
    ) -> impl Stream<Item = Result<SipTrunk>> + Send {
        let fetcher = trunk_fetcher(self.client, INBOUND_PATH, &params);
        auto_page(fetcher, params.pagination(), "data", None)
    }

    /// Fetches an inbound trunk by id.
    pub async fn get(&self, trunk_id: &str) -> Result<SipTrunk> {
        let path = format!("{INBOUND_PATH}/{}", escape(trunk_id));
        self.client
            .json(Method::GET, &path, CallOptions::new())
            .await
    }

    /// Partially updates an inbound trunk. See [`UpdateInboundTrunkParams`] for
    /// the fields that reset when omitted.
    pub async fn update(
        &self,
        trunk_id: &str,
        params: UpdateInboundTrunkParams,
    ) -> Result<SipTrunk> {
        let path = format!("{INBOUND_PATH}/{}", escape(trunk_id));
        self.client
            .json(Method::PATCH, &path, CallOptions::json(&params)?)
            .await
    }

    /// Deletes an inbound trunk.
    pub async fn delete(&self, trunk_id: &str) -> Result<MessageResponse> {
        let path = format!("{INBOUND_PATH}/{}", escape(trunk_id));
        self.client
            .json(Method::DELETE, &path, CallOptions::new())
            .await
    }
}

/// Outbound SIP trunks: connections used to place calls to a SIP host. Reached
/// via [`SipTrunksResource::outbound`].
#[derive(Debug, Clone, Copy)]
pub struct OutboundTrunkResource<'a> {
    client: &'a Client,
}

impl<'a> OutboundTrunkResource<'a> {
    /// Creates an outbound trunk.
    pub async fn create(&self, params: CreateOutboundTrunkParams) -> Result<SipTrunk> {
        self.client
            .json(Method::POST, OUTBOUND_PATH, CallOptions::json(&params)?)
            .await
    }

    /// Lists outbound trunks, one page at a time.
    pub async fn list(&self, params: SipTrunkListParams) -> Result<Page<SipTrunk>> {
        let fetcher = trunk_fetcher(self.client, OUTBOUND_PATH, &params);
        paginate(fetcher, &params.pagination(), "data", None).await
    }

    /// Lists outbound trunks, transparently fetching every page.
    pub fn list_stream(
        &self,
        params: SipTrunkListParams,
    ) -> impl Stream<Item = Result<SipTrunk>> + Send {
        let fetcher = trunk_fetcher(self.client, OUTBOUND_PATH, &params);
        auto_page(fetcher, params.pagination(), "data", None)
    }

    /// Fetches an outbound trunk by id.
    pub async fn get(&self, trunk_id: &str) -> Result<SipTrunk> {
        let path = format!("{OUTBOUND_PATH}/{}", escape(trunk_id));
        self.client
            .json(Method::GET, &path, CallOptions::new())
            .await
    }

    /// Partially updates an outbound trunk. The same reset semantics as the
    /// inbound update apply.
    pub async fn update(
        &self,
        trunk_id: &str,
        params: UpdateOutboundTrunkParams,
    ) -> Result<SipTrunk> {
        let path = format!("{OUTBOUND_PATH}/{}", escape(trunk_id));
        self.client
            .json(Method::PATCH, &path, CallOptions::json(&params)?)
            .await
    }

    /// Deletes an outbound trunk.
    pub async fn delete(&self, trunk_id: &str) -> Result<MessageResponse> {
        let path = format!("{OUTBOUND_PATH}/{}", escape(trunk_id));
        self.client
            .json(Method::DELETE, &path, CallOptions::new())
            .await
    }
}

/// Groups the inbound and outbound trunk sub-resources. Reached via
/// [`SipResource::trunks`](crate::SipResource::trunks).
#[derive(Debug, Clone, Copy)]
pub struct SipTrunksResource<'a> {
    client: &'a Client,
}

impl<'a> SipTrunksResource<'a> {
    pub(crate) fn new(client: &'a Client) -> Self {
        Self { client }
    }

    /// Inbound trunks: connections that receive calls for a set of numbers.
    pub fn inbound(&self) -> InboundTrunkResource<'a> {
        InboundTrunkResource {
            client: self.client,
        }
    }

    /// Outbound trunks: connections used to place calls to a SIP host.
    pub fn outbound(&self) -> OutboundTrunkResource<'a> {
        OutboundTrunkResource {
            client: self.client,
        }
    }
}