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

use serde::{Deserialize, Serialize};

use crate::domain::ProtocolExtensions;
use crate::kernel::PaymentsKernelError;

/// Canonical order lifecycle state.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum OrderState {
    Draft,
    PendingPayment,
    Authorized,
    FulfillmentPending,
    Fulfilled,
    Completed,
    Canceled,
    Refunded,
    PartiallyRefunded,
    Failed,
}

impl OrderState {
    /// Returns `true` when the transition is allowed by the canonical order
    /// state machine.
    #[must_use]
    pub fn can_transition_to(self, next: Self) -> bool {
        use OrderState::{
            Authorized, Canceled, Completed, Draft, Failed, Fulfilled, FulfillmentPending,
            PartiallyRefunded, PendingPayment, Refunded,
        };

        match (self, next) {
            (from, to) if from == to => true,
            (Draft, PendingPayment | Canceled | Failed) => true,
            (PendingPayment, Authorized | Canceled | Failed) => true,
            (Authorized, FulfillmentPending | Completed | Canceled | Failed) => true,
            (FulfillmentPending, Fulfilled | Completed | Failed) => true,
            (Fulfilled, Completed | PartiallyRefunded | Refunded | Failed) => true,
            (Completed, PartiallyRefunded | Refunded) => true,
            (PartiallyRefunded, PartiallyRefunded | Refunded) => true,
            _ => false,
        }
    }
}

/// Canonical receipt or settlement lifecycle state.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ReceiptState {
    NotRequested,
    Pending,
    Authorized,
    Settled,
    Failed,
    PartiallyRefunded,
    Refunded,
    Voided,
}

impl ReceiptState {
    /// Returns `true` when the transition is allowed by the canonical receipt
    /// state machine.
    #[must_use]
    pub fn can_transition_to(self, next: Self) -> bool {
        use ReceiptState::{
            Authorized, Failed, NotRequested, PartiallyRefunded, Pending, Refunded, Settled, Voided,
        };

        match (self, next) {
            (from, to) if from == to => true,
            (NotRequested, Pending | Authorized | Failed) => true,
            (Pending, Authorized | Settled | Failed | Voided) => true,
            (Authorized, Settled | Failed | Voided) => true,
            (Settled, PartiallyRefunded | Refunded) => true,
            (PartiallyRefunded, PartiallyRefunded | Refunded) => true,
            _ => false,
        }
    }
}

/// Canonical order and receipt summary attached to a transaction.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct OrderSnapshot {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub order_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub receipt_id: Option<String>,
    pub state: OrderState,
    pub receipt_state: ReceiptState,
    #[serde(default, skip_serializing_if = "ProtocolExtensions::is_empty")]
    pub extensions: ProtocolExtensions,
}

impl OrderSnapshot {
    /// Applies one canonical order-state transition.
    ///
    /// # Errors
    ///
    /// Returns an error when the requested transition would skip or rewind the
    /// canonical order lifecycle.
    pub fn transition_order_state(
        &mut self,
        next: OrderState,
    ) -> std::result::Result<(), PaymentsKernelError> {
        if !self.state.can_transition_to(next) {
            return Err(PaymentsKernelError::InvalidOrderTransition { from: self.state, to: next });
        }

        self.state = next;
        Ok(())
    }

    /// Applies one canonical receipt-state transition.
    ///
    /// # Errors
    ///
    /// Returns an error when the requested transition would skip or rewind the
    /// canonical receipt lifecycle.
    pub fn transition_receipt_state(
        &mut self,
        next: ReceiptState,
    ) -> std::result::Result<(), PaymentsKernelError> {
        if !self.receipt_state.can_transition_to(next) {
            return Err(PaymentsKernelError::InvalidReceiptTransition {
                from: self.receipt_state,
                to: next,
            });
        }

        self.receipt_state = next;
        Ok(())
    }
}