delopay 0.20.0

Official Rust SDK for the DeloPay payments API
Documentation
//! The `relay` resource: forward an operation (refund, capture, incremental
//! authorization, void) straight to a connector for a resource DeloPay did
//! not create.

use std::sync::Arc;

use serde::{Deserialize, Serialize};
use serde_json::Value;

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

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

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

    /// Relay an operation to a connector.
    pub async fn create(&self, params: &RelayRequest) -> Result<Value> {
        let body = to_json_vec(params)?;
        self.inner
            .request(HttpMethod::Post, "/relay", Some(&body), &[], None)
            .await
    }

    /// Retrieve a previously created relay by ID.
    pub async fn retrieve(&self, relay_id: &str) -> Result<Value> {
        let path = format!("/relay/{}", encode_segment(relay_id));
        self.inner
            .request(HttpMethod::Get, &path, None, &[], None)
            .await
    }
}

/// The operation being relayed to the connector.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RelayType {
    /// Refund the connector resource.
    Refund,
    /// Capture a previously authorized amount.
    Capture,
    /// Increase the authorized amount.
    IncrementalAuthorization,
    /// Void the authorization.
    Void,
}

/// Refund details for a [`RelayType::Refund`] relay.
#[derive(Debug, Clone, Default, Serialize)]
pub struct RelayRefundData {
    /// Amount to refund, in minor units. Omit for a full refund.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub amount: Option<i64>,
    /// Currency of `amount`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub currency: Option<Currency>,
    /// Reason recorded against the refund.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
}

/// Capture details for a [`RelayType::Capture`] relay.
#[derive(Debug, Clone, Default, Serialize)]
pub struct RelayCaptureData {
    /// Amount to capture, in minor units. Omit to capture in full.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub amount: Option<i64>,
}

/// Details for a [`RelayType::IncrementalAuthorization`] relay.
#[derive(Debug, Clone, Default, Serialize)]
pub struct RelayIncrementalAuthorizationData {
    /// New total authorized amount, in minor units.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub amount: Option<i64>,
    /// Reason for the increment.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
}

/// Details for a [`RelayType::Void`] relay.
#[derive(Debug, Clone, Default, Serialize)]
pub struct RelayVoidData {
    /// Reason recorded against the cancellation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cancellation_reason: Option<String>,
}

/// Per-operation payload for a relay. Set the member matching the request's
/// [`RelayRequest::relay_type`].
#[derive(Debug, Clone, Default, Serialize)]
pub struct RelayData {
    /// Details for a refund relay.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub refund: Option<RelayRefundData>,
    /// Details for a capture relay.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub capture: Option<RelayCaptureData>,
    /// Details for an incremental-authorization relay.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub incremental_authorization: Option<RelayIncrementalAuthorizationData>,
    /// Details for a void relay.
    #[serde(rename = "void", skip_serializing_if = "Option::is_none")]
    pub void_data: Option<RelayVoidData>,
}

/// Parameters for [`Relay::create`].
#[derive(Debug, Clone, Serialize)]
pub struct RelayRequest {
    /// The connector's own ID for the resource being operated on.
    pub connector_resource_id: String,
    /// The merchant connector account to relay through.
    pub connector_id: String,
    /// Which operation to relay.
    #[serde(rename = "type")]
    pub relay_type: RelayType,
    /// Operation-specific payload.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub data: Option<RelayData>,
}

impl RelayRequest {
    /// A relay of `relay_type` against `connector_resource_id` on
    /// `connector_id`, with no operation payload.
    pub fn new(
        connector_resource_id: impl Into<String>,
        connector_id: impl Into<String>,
        relay_type: RelayType,
    ) -> Self {
        Self {
            connector_resource_id: connector_resource_id.into(),
            connector_id: connector_id.into(),
            relay_type,
            data: None,
        }
    }

    /// Attach the operation-specific payload.
    #[must_use]
    pub fn data(mut self, data: RelayData) -> Self {
        self.data = Some(data);
        self
    }
}

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

    const RELAY_JSON: &str = r#"{
        "id": "relay_1",
        "status": "created",
        "connector_resource_id": "ch_1",
        "connector_id": "mca_1",
        "profile_id": "pro_1",
        "type": "refund"
    }"#;

    #[tokio::test]
    async fn create_posts_to_the_relay_root_with_the_operation_payload() {
        let (client, mock) = client_with(vec![Step::ok(RELAY_JSON)]);
        let req = RelayRequest::new("ch_1", "mca_1", RelayType::Refund).data(RelayData {
            refund: Some(RelayRefundData {
                amount: Some(500),
                currency: Some("EUR".to_string()),
                reason: Some("duplicate".to_string()),
            }),
            ..Default::default()
        });
        client.relay().create(&req).await.unwrap();

        let seen = mock.seen.lock().unwrap();
        assert_eq!(seen[0].method, "POST");
        assert_eq!(seen[0].url, "https://api.test/relay");
        let body = seen[0].body_json();
        assert_eq!(body["type"], "refund");
        assert_eq!(body["connector_resource_id"], "ch_1");
        assert_eq!(body["connector_id"], "mca_1");
        assert_eq!(body["data"]["refund"]["amount"], 500);
        assert_eq!(body["data"]["refund"]["currency"], "EUR");
    }

    #[tokio::test]
    async fn create_omits_data_when_unset() {
        // Pins `skip_serializing_if` on `data`: the backend rejects an explicit
        // `"data": null` for operations that take no payload.
        let (client, mock) = client_with(vec![Step::ok(RELAY_JSON)]);
        let req = RelayRequest::new("ch_1", "mca_1", RelayType::Void);
        client.relay().create(&req).await.unwrap();

        let seen = mock.seen.lock().unwrap();
        let body = seen[0].body_json();
        assert_eq!(body["type"], "void");
        assert!(body.get("data").is_none(), "data must be omitted, not null");
    }

    #[tokio::test]
    async fn void_data_serializes_under_the_void_key() {
        // `void` is a Rust keyword-adjacent field renamed from `void_data`;
        // dropping the `rename` would emit `void_data` and fail here.
        let (client, mock) = client_with(vec![Step::ok(RELAY_JSON)]);
        let req = RelayRequest::new("ch_1", "mca_1", RelayType::Void).data(RelayData {
            void_data: Some(RelayVoidData {
                cancellation_reason: Some("customer_request".to_string()),
            }),
            ..Default::default()
        });
        client.relay().create(&req).await.unwrap();

        let seen = mock.seen.lock().unwrap();
        assert_eq!(
            seen[0].body_json()["data"]["void"]["cancellation_reason"],
            "customer_request"
        );
    }

    #[tokio::test]
    async fn retrieve_encodes_the_relay_id_into_the_path() {
        let (client, mock) = client_with(vec![Step::ok(RELAY_JSON)]);
        client.relay().retrieve("relay/1 a").await.unwrap();

        let seen = mock.seen.lock().unwrap();
        assert_eq!(seen[0].method, "GET");
        assert_eq!(seen[0].url, "https://api.test/relay/relay%2F1%20a");
    }
}