delopay 0.4.0

Official Rust SDK for the DeloPay payments API
Documentation
//! The `analytics` resource: scoped dashboard drill-downs, cross-index search
//! and the event log feeds. Response shapes are open — see the API reference.

use std::sync::Arc;

use serde_json::Value;

use crate::core::encoding::{encode_segment, to_json_vec};
use crate::core::error::Result;
use crate::http::client::Inner;
use crate::http::transport::HttpMethod;

/// The `analytics` resource, obtained via [`crate::Delopay::analytics`].
#[derive(Debug, Clone)]
pub struct Analytics {
    inner: Arc<Inner>,
}

impl Analytics {
    pub(crate) fn new(inner: Arc<Inner>) -> Self {
        Self { inner }
    }

    /// Scoped, drill-level analytics for the authenticated merchant.
    ///
    /// The server ignores `merchant_id` — it always scopes to your merchant,
    /// and to your single shop for profile-scoped users — so pass only
    /// `project_id` / `shop_id` to drill, plus the window and `sections`
    /// fields. Returns one drill level: the scope's daily series and previous
    /// window, processor mix and direct children.
    pub async fn scope(&self, params: Option<&AnalyticsScopeParams>) -> Result<Value> {
        let query = params
            .map(AnalyticsScopeParams::to_query)
            .unwrap_or_default();
        self.inner
            .request(HttpMethod::Get, "/analytics/scope", None, &query, None)
            .await
    }

    /// Global search across every supported index. The body shape is open —
    /// see [`crate::Search::global`] for the named request form.
    pub async fn search(&self, params: &Value) -> Result<Value> {
        let body = to_json_vec(params)?;
        self.inner
            .request(
                HttpMethod::Post,
                "/analytics/search",
                Some(&body),
                &[],
                None,
            )
            .await
    }

    /// Domain-specific search, e.g. `"payment_intents"`. The body shape is
    /// open — see the API reference.
    pub async fn search_domain(&self, domain: &str, params: &Value) -> Result<Value> {
        let path = format!("/analytics/search/{}", encode_segment(domain));
        let body = to_json_vec(params)?;
        self.inner
            .request(HttpMethod::Post, &path, Some(&body), &[], None)
            .await
    }

    /// Describe the filters and columns a search domain supports.
    pub async fn info(&self, domain: &str) -> Result<Value> {
        let path = format!("/analytics/{}/info", encode_segment(domain));
        self.inner
            .request(HttpMethod::Get, &path, None, &[], None)
            .await
    }

    /// API event logs. Query keys are open — pass `&[]` for none.
    pub async fn api_event_logs(&self, query: &[(&str, String)]) -> Result<Value> {
        self.inner
            .request(
                HttpMethod::Get,
                "/analytics/api-event-logs",
                None,
                query,
                None,
            )
            .await
    }

    /// SDK event logs. The body shape is open — see the API reference.
    pub async fn sdk_event_logs(&self, params: &Value) -> Result<Value> {
        let body = to_json_vec(params)?;
        self.inner
            .request(
                HttpMethod::Post,
                "/analytics/sdk-event-logs",
                Some(&body),
                &[],
                None,
            )
            .await
    }

    /// Connector event logs. Query keys are open — pass `&[]` for none.
    pub async fn connector_event_logs(&self, query: &[(&str, String)]) -> Result<Value> {
        self.inner
            .request(
                HttpMethod::Get,
                "/analytics/connector-event-logs",
                None,
                query,
                None,
            )
            .await
    }

    /// Routing event logs. Query keys are open — pass `&[]` for none.
    pub async fn routing_event_logs(&self, query: &[(&str, String)]) -> Result<Value> {
        self.inner
            .request(
                HttpMethod::Get,
                "/analytics/routing-event-logs",
                None,
                query,
                None,
            )
            .await
    }

    /// Outgoing webhook event logs. Query keys are open — pass `&[]` for none.
    pub async fn outgoing_webhook_event_logs(&self, query: &[(&str, String)]) -> Result<Value> {
        self.inner
            .request(
                HttpMethod::Get,
                "/analytics/outgoing-webhook-event-logs",
                None,
                query,
                None,
            )
            .await
    }
}

/// Window and scope parameters for [`Analytics::scope`].
#[derive(Debug, Clone, Default)]
pub struct AnalyticsScopeParams {
    /// Trailing days for a rolling window ending now. Defaults to 7 server-side,
    /// capped at 90.
    pub days: Option<i64>,
    /// Naive ISO 8601 datetime for the window start (custom range, span ≤ 90 days).
    pub start_date: Option<String>,
    /// Naive ISO 8601 datetime for the inclusive last day. Defaults to now.
    pub end_date: Option<String>,
    /// Scope to a single merchant. Ignored (server-pinned) on this endpoint.
    pub merchant_id: Option<String>,
    /// Scope to one project's shops.
    pub project_id: Option<String>,
    /// Scope to a single shop; wins over [`project_id`](Self::project_id).
    pub shop_id: Option<String>,
    /// Comma-separated selector for which response blocks the server computes:
    /// `series`, `previous`, `connectors`, `children`. Omit for all of them;
    /// unrequested blocks come back as empty arrays.
    pub sections: Option<String>,
    /// Filter by test mode: `false` returns only live payments, `true` only
    /// test/sandbox payments. Omit to include both.
    pub test_mode: Option<bool>,
}

impl AnalyticsScopeParams {
    fn to_query(&self) -> Vec<(&'static str, String)> {
        let mut q = Vec::new();
        if let Some(v) = self.days {
            q.push(("days", v.to_string()));
        }
        if let Some(v) = &self.start_date {
            q.push(("start_date", v.clone()));
        }
        if let Some(v) = &self.end_date {
            q.push(("end_date", v.clone()));
        }
        if let Some(v) = &self.merchant_id {
            q.push(("merchant_id", v.clone()));
        }
        if let Some(v) = &self.project_id {
            q.push(("project_id", v.clone()));
        }
        if let Some(v) = &self.shop_id {
            q.push(("shop_id", v.clone()));
        }
        if let Some(v) = &self.sections {
            q.push(("sections", v.clone()));
        }
        if let Some(v) = self.test_mode {
            q.push(("test_mode", v.to_string()));
        }
        q
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::http::mock::{Step, client_with};
    use serde_json::json;

    #[tokio::test]
    async fn scope_serializes_every_named_param_in_order() {
        let (client, mock) = client_with(vec![Step::ok(r#"{"series":[]}"#)]);
        let params = AnalyticsScopeParams {
            days: Some(30),
            start_date: Some("2026-01-01T00:00:00".to_string()),
            end_date: Some("2026-01-31T00:00:00".to_string()),
            merchant_id: Some("mer_1".to_string()),
            project_id: Some("pro_1".to_string()),
            shop_id: Some("shop_1".to_string()),
            sections: Some("series,previous".to_string()),
            test_mode: Some(false),
        };
        client.analytics().scope(Some(&params)).await.unwrap();

        let seen = mock.seen.lock().unwrap();
        assert_eq!(seen[0].method, "GET");
        assert_eq!(
            seen[0].url,
            "https://api.test/analytics/scope?days=30&start_date=2026-01-01T00:00:00\
             &end_date=2026-01-31T00:00:00&merchant_id=mer_1&project_id=pro_1\
             &shop_id=shop_1&sections=series,previous&test_mode=false"
        );
    }

    #[tokio::test]
    async fn scope_without_params_sends_no_query() {
        let (client, mock) = client_with(vec![Step::ok("{}")]);
        client.analytics().scope(None).await.unwrap();

        let seen = mock.seen.lock().unwrap();
        assert_eq!(seen[0].url, "https://api.test/analytics/scope");
    }

    #[tokio::test]
    async fn search_posts_the_body_to_analytics_search() {
        let (client, mock) = client_with(vec![Step::ok("[]")]);
        client
            .analytics()
            .search(&json!({"query": "pay_abc"}))
            .await
            .unwrap();

        let seen = mock.seen.lock().unwrap();
        assert_eq!(seen[0].method, "POST");
        assert_eq!(seen[0].url, "https://api.test/analytics/search");
        assert_eq!(seen[0].body_json()["query"], "pay_abc");
    }

    #[tokio::test]
    async fn search_domain_encodes_the_domain_segment() {
        let (client, mock) = client_with(vec![Step::ok("{}")]);
        client
            .analytics()
            .search_domain("payment intents/v2", &json!({"query": "x"}))
            .await
            .unwrap();

        let seen = mock.seen.lock().unwrap();
        assert_eq!(seen[0].method, "POST");
        assert_eq!(
            seen[0].url,
            "https://api.test/analytics/search/payment%20intents%2Fv2"
        );
        assert_eq!(seen[0].body_json()["query"], "x");
    }

    #[tokio::test]
    async fn info_encodes_the_domain_segment() {
        let (client, mock) = client_with(vec![Step::ok("{}")]);
        client.analytics().info("payment intents").await.unwrap();

        let seen = mock.seen.lock().unwrap();
        assert_eq!(seen[0].method, "GET");
        assert_eq!(
            seen[0].url,
            "https://api.test/analytics/payment%20intents/info"
        );
    }

    #[tokio::test]
    async fn event_log_feeds_hit_their_own_paths() {
        let (client, mock) = client_with(vec![
            Step::ok("{}"),
            Step::ok("{}"),
            Step::ok("{}"),
            Step::ok("{}"),
            Step::ok("{}"),
        ]);
        client
            .analytics()
            .api_event_logs(&[("limit", "5".to_string())])
            .await
            .unwrap();
        client
            .analytics()
            .sdk_event_logs(&json!({"payment_id": "pay_1"}))
            .await
            .unwrap();
        client
            .analytics()
            .connector_event_logs(&[("payment_id", "pay_1".to_string())])
            .await
            .unwrap();
        client.analytics().routing_event_logs(&[]).await.unwrap();
        client
            .analytics()
            .outgoing_webhook_event_logs(&[])
            .await
            .unwrap();

        let seen = mock.seen.lock().unwrap();
        assert_eq!(
            (seen[0].method, seen[0].url.as_str()),
            ("GET", "https://api.test/analytics/api-event-logs?limit=5")
        );
        assert_eq!(
            (seen[1].method, seen[1].url.as_str()),
            ("POST", "https://api.test/analytics/sdk-event-logs")
        );
        assert_eq!(seen[1].body_json()["payment_id"], "pay_1");
        assert_eq!(
            (seen[2].method, seen[2].url.as_str()),
            (
                "GET",
                "https://api.test/analytics/connector-event-logs?payment_id=pay_1"
            )
        );
        assert_eq!(
            (seen[3].method, seen[3].url.as_str()),
            ("GET", "https://api.test/analytics/routing-event-logs")
        );
        assert_eq!(
            (seen[4].method, seen[4].url.as_str()),
            (
                "GET",
                "https://api.test/analytics/outgoing-webhook-event-logs"
            )
        );
    }
}