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

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

/// Identifies the protocol and version that originated canonical data.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ProtocolDescriptor {
    pub name: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,
}

impl ProtocolDescriptor {
    /// Creates a protocol descriptor for ACP.
    #[must_use]
    pub fn acp(version: impl Into<String>) -> Self {
        Self { name: "acp".to_string(), version: Some(version.into()) }
    }

    /// Creates a protocol descriptor for AP2.
    #[must_use]
    pub fn ap2(version: impl Into<String>) -> Self {
        Self { name: "ap2".to_string(), version: Some(version.into()) }
    }

    /// Creates a protocol descriptor for any named protocol.
    #[must_use]
    pub fn new(name: impl Into<String>, version: Option<String>) -> Self {
        Self { name: name.into(), version }
    }
}

/// Opaque reference to a stored evidence artifact.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct EvidenceReference {
    pub evidence_id: String,
    pub protocol: ProtocolDescriptor,
    pub artifact_kind: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub digest: Option<String>,
}

/// Lossless protocol-specific fields preserved alongside canonical state.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ProtocolExtensionEnvelope {
    pub protocol: ProtocolDescriptor,
    #[serde(default, skip_serializing_if = "Map::is_empty")]
    pub fields: Map<String, Value>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub evidence_refs: Vec<EvidenceReference>,
}

impl ProtocolExtensionEnvelope {
    /// Creates an empty extension envelope for one protocol source.
    #[must_use]
    pub fn new(protocol: ProtocolDescriptor) -> Self {
        Self { protocol, fields: Map::new(), evidence_refs: Vec::new() }
    }

    /// Appends one raw protocol field without discarding its original shape.
    #[must_use]
    pub fn with_field(mut self, key: impl Into<String>, value: Value) -> Self {
        self.fields.insert(key.into(), value);
        self
    }

    /// Appends one evidence reference associated with the extension envelope.
    #[must_use]
    pub fn with_evidence_ref(mut self, evidence_ref: EvidenceReference) -> Self {
        self.evidence_refs.push(evidence_ref);
        self
    }

    /// Returns `true` when the envelope carries neither fields nor evidence
    /// references.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.fields.is_empty() && self.evidence_refs.is_empty()
    }
}

/// Collection of preserved protocol extension envelopes.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(transparent)]
pub struct ProtocolExtensions(pub Vec<ProtocolExtensionEnvelope>);

impl ProtocolExtensions {
    /// Returns `true` when no protocol-specific envelopes are attached.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// Adds one protocol envelope to the collection.
    pub fn push(&mut self, envelope: ProtocolExtensionEnvelope) {
        self.0.push(envelope);
    }

    /// Returns all attached envelopes.
    #[must_use]
    pub fn as_slice(&self) -> &[ProtocolExtensionEnvelope] {
        &self.0
    }
}

impl From<Vec<ProtocolExtensionEnvelope>> for ProtocolExtensions {
    fn from(value: Vec<ProtocolExtensionEnvelope>) -> Self {
        Self(value)
    }
}