adk-payments 0.5.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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

//! AP2 mandate types aligned to `v0.1-alpha` as of `2026-03-22`.
//!
//! Three mandate kinds model the progressive authorization chain:
//! [`IntentMandate`] → [`CartMandate`] → [`PaymentMandate`].

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

use crate::domain::{Money, ProtocolExtensions};

use super::roles::Ap2Role;

// ---------------------------------------------------------------------------
// Mandate status
// ---------------------------------------------------------------------------

/// Lifecycle status shared by all AP2 mandate types.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MandateStatus {
    Pending,
    Active,
    Executed,
    Expired,
    Revoked,
}

// ---------------------------------------------------------------------------
// Authority constraints (human-not-present flows)
// ---------------------------------------------------------------------------

/// Constraints required for human-not-present flows per Requirement 6.8.
///
/// An [`IntentMandate`] operating in human-not-present mode **must** carry
/// explicit expiration and authority constraints before a payment can progress
/// to execution.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct AuthorityConstraints {
    /// Maximum amount the mandate may authorize.
    pub max_amount: Money,
    /// Merchants allowed under this mandate.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allowed_merchants: Vec<String>,
    /// Product classes allowed under this mandate.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allowed_product_classes: Vec<String>,
    /// Hard expiration for the authority grant.
    pub expires_at: DateTime<Utc>,
}

// ---------------------------------------------------------------------------
// IntentMandate
// ---------------------------------------------------------------------------

/// Pre-authorization mandate with constraints.
///
/// For human-not-present transactions, `authority_constraints` **must** be
/// present with an explicit expiration (Requirement 6.8).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct IntentMandate {
    /// Unique mandate identifier.
    pub id: String,
    /// Role that issued this mandate.
    pub issuer_role: Ap2Role,
    /// Role this mandate targets.
    pub target_role: Ap2Role,
    /// Merchant identifier constraint.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub merchant: Option<String>,
    /// Maximum amount constraint.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub amount: Option<Money>,
    /// Product class constraint.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub product_class: Option<String>,
    /// Authority constraints for human-not-present flows.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub authority_constraints: Option<AuthorityConstraints>,
    /// Current lifecycle status.
    pub status: MandateStatus,
    /// Signature placeholder for future cryptographic verification.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub signature: Option<String>,
    /// When this mandate was created.
    pub created_at: DateTime<Utc>,
    /// When this mandate expires.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expires_at: Option<DateTime<Utc>>,
    /// Protocol-specific extension fields.
    #[serde(default, skip_serializing_if = "ProtocolExtensions::is_empty")]
    pub extensions: ProtocolExtensions,
}

// ---------------------------------------------------------------------------
// CartMandate
// ---------------------------------------------------------------------------

/// Merchant-signed cart authorization mandate.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CartMandate {
    /// Unique mandate identifier.
    pub id: String,
    /// Role that issued this mandate.
    pub issuer_role: Ap2Role,
    /// Role this mandate targets.
    pub target_role: Ap2Role,
    /// Cart identifier being authorized.
    pub cart_id: String,
    /// Total amount for the cart.
    pub amount: Money,
    /// Current lifecycle status.
    pub status: MandateStatus,
    /// Signature placeholder for future cryptographic verification.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub signature: Option<String>,
    /// When this mandate was created.
    pub created_at: DateTime<Utc>,
    /// When this mandate expires.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expires_at: Option<DateTime<Utc>>,
    /// Protocol-specific extension fields.
    #[serde(default, skip_serializing_if = "ProtocolExtensions::is_empty")]
    pub extensions: ProtocolExtensions,
}

// ---------------------------------------------------------------------------
// PaymentMandate
// ---------------------------------------------------------------------------

/// Payment execution authorization mandate.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PaymentMandate {
    /// Unique mandate identifier.
    pub id: String,
    /// Role that issued this mandate.
    pub issuer_role: Ap2Role,
    /// Role this mandate targets.
    pub target_role: Ap2Role,
    /// Reference to the cart mandate being executed.
    pub cart_mandate_id: String,
    /// Payment method identifier.
    pub payment_method: String,
    /// Amount to execute.
    pub amount: Money,
    /// Current lifecycle status.
    pub status: MandateStatus,
    /// Signature placeholder for future cryptographic verification.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub signature: Option<String>,
    /// When this mandate was created.
    pub created_at: DateTime<Utc>,
    /// When this mandate expires.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expires_at: Option<DateTime<Utc>>,
    /// Protocol-specific extension fields.
    #[serde(default, skip_serializing_if = "ProtocolExtensions::is_empty")]
    pub extensions: ProtocolExtensions,
}