adk-payments 0.6.0

Protocol-neutral agentic commerce and payment orchestration for ADK-Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

use adk_guardrail::Severity;

use crate::domain::{ProtocolDescriptor, TransactionRecord};

use super::{PaymentPolicyDecision, PaymentPolicyFinding, PaymentPolicyGuardrail};

/// Restricts payment execution to explicit protocol name and version combinations.
pub struct ProtocolVersionGuardrail {
    allowed_protocols: Vec<ProtocolDescriptor>,
}

impl ProtocolVersionGuardrail {
    /// Creates a protocol-version guardrail.
    #[must_use]
    pub fn new<I>(allowed_protocols: I) -> Self
    where
        I: IntoIterator<Item = ProtocolDescriptor>,
    {
        Self { allowed_protocols: allowed_protocols.into_iter().collect() }
    }

    fn allows(&self, protocol: &ProtocolDescriptor) -> bool {
        self.allowed_protocols.iter().any(|allowed| {
            allowed.name == protocol.name
                && match &allowed.version {
                    Some(version) => protocol.version.as_ref() == Some(version),
                    None => true,
                }
        })
    }
}

impl PaymentPolicyGuardrail for ProtocolVersionGuardrail {
    fn name(&self) -> &str {
        "protocol_version"
    }

    fn evaluate(
        &self,
        _record: &TransactionRecord,
        protocol: &ProtocolDescriptor,
    ) -> PaymentPolicyDecision {
        if self.allows(protocol) {
            PaymentPolicyDecision::allow()
        } else {
            let version = protocol.version.as_deref().unwrap_or("unspecified");
            PaymentPolicyDecision::deny(vec![PaymentPolicyFinding::new(
                self.name(),
                format!(
                    "protocol `{}` version `{version}` is not allowed by the configured baseline policy",
                    protocol.name
                ),
                Severity::High,
            )])
        }
    }
}

#[cfg(test)]
mod tests {
    use chrono::{TimeZone, Utc};

    use super::*;
    use crate::domain::{
        Cart, CartLine, CommerceActor, CommerceActorRole, CommerceMode, MerchantRef, Money,
        ProtocolExtensions, TransactionId,
    };

    fn sample_record() -> TransactionRecord {
        TransactionRecord::new(
            TransactionId::from("tx-protocol"),
            CommerceActor {
                actor_id: "shopper-agent".to_string(),
                role: CommerceActorRole::AgentSurface,
                display_name: Some("shopper".to_string()),
                tenant_id: Some("tenant-1".to_string()),
                extensions: ProtocolExtensions::default(),
            },
            MerchantRef {
                merchant_id: "merchant-1".to_string(),
                legal_name: "Merchant Example LLC".to_string(),
                display_name: Some("Merchant Example".to_string()),
                statement_descriptor: None,
                country_code: Some("US".to_string()),
                website: Some("https://merchant.example".to_string()),
                extensions: ProtocolExtensions::default(),
            },
            CommerceMode::HumanPresent,
            Cart {
                cart_id: Some("cart-1".to_string()),
                lines: vec![CartLine {
                    line_id: "line-1".to_string(),
                    merchant_sku: Some("sku-1".to_string()),
                    title: "Widget".to_string(),
                    quantity: 1,
                    unit_price: Money::new("USD", 1_500, 2),
                    total_price: Money::new("USD", 1_500, 2),
                    product_class: Some("widgets".to_string()),
                    extensions: ProtocolExtensions::default(),
                }],
                subtotal: Some(Money::new("USD", 1_500, 2)),
                adjustments: Vec::new(),
                total: Money::new("USD", 1_500, 2),
                affiliate_attribution: None,
                extensions: ProtocolExtensions::default(),
            },
            Utc.with_ymd_and_hms(2026, 3, 22, 15, 40, 0).unwrap(),
        )
    }

    #[test]
    fn protocol_version_guardrail_denies_unknown_version() {
        let guardrail = ProtocolVersionGuardrail::new([ProtocolDescriptor::acp("2026-01-30")]);
        let decision = guardrail.evaluate(&sample_record(), &ProtocolDescriptor::acp("2025-12-01"));

        assert!(decision.is_deny());
        assert_eq!(decision.findings()[0].guardrail, "protocol_version");
    }
}