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
//! # Versa Protocol Rust SDK
//!
//! The official Rust implementation of the Versa Protocol, providing types and utilities
//! for developing Versa client applications.
//!
//! ## Overview
//!
//! Versa is an open protocol that allows any service to send itemized receipts, invoices,
//! and other transaction records directly to their customers in a structured, machine-readable
//! format. This crate provides:
//!
//! - **Schema Types**: Strongly-typed representations of Versa receipts and itineraries
//! - **Protocol Types**: Core protocol messages for customer registration, webhooks, and misuse reporting
//! - **Client Utilities**: Helper functions for sending and receiving Versa documents
//! - **Validation**: Schema validation for ensuring document compliance
//!
//! ## Feature Flags
//!
//! This crate uses feature flags to minimize dependencies:
//!
//! - `client`: Core client functionality (HTTP requests, encryption, HMAC)
//! - `client_sender`: Utilities for services sending receipts
//! - `client_receiver`: Utilities for services receiving receipts
//! - `validator`: JSON Schema validation support
//!
//! ## Quick Start
//!
//! ### As a Sender (Merchant/Service)
//!
//! ```rust,no_run
//! use versa::schema::receipt::{Receipt, Header, Currency};
//! use versa::schema::current::SCHEMA_VERSION;
//! use std::str::FromStr;
//!
//! # fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // Create a receipt
//! let receipt = Receipt {
//! schema_version: SCHEMA_VERSION.parse()?,
//! header: Header {
//! total: 10000, // $100.00 in cents
//! currency: Currency::from_str("usd")?,
//! subtotal: 10000,
//! invoiced_at: 1234567890,
//! paid: 10000,
//! customer: None,
//! invoice_asset_id: None,
//! invoice_number: None,
//! location: None,
//! mcc: None,
//! receipt_asset_id: None,
//! third_party: None,
//! booked_at: None,
//! lifecycle_status: None,
//! trip: None,
//! },
//! itemization: versa::schema::receipt::Itemization::builder().try_into()?,
//! payments: None,
//! footer: None,
//! };
//!
//! // Send to customer using client_sender feature
//! # /*
//! #[cfg(feature = "client_sender")]
//! {
//! use versa::client_sender::send_receipt;
//! // send_receipt(&receipt, "customer@example.com").await?;
//! }
//! # */
//! # Ok(())
//! # }
//! ```
//!
//! ### As a Receiver (Inbox/Aggregator)
//!
//! ```rust,no_run
//! use versa::protocol::webhook::{WebhookEvent, WebhookEventType};
//! use versa::schema::receipt::Receipt;
//!
//! # fn example(signature: &str, body: &str) -> Result<(), Box<dyn std::error::Error>> {
//! // Parse incoming webhook
//! let webhook_event: WebhookEvent<Receipt> = serde_json::from_str(&body)?;
//!
//! // Verify and process the receipt using client_receiver feature
//! # /*
//! #[cfg(feature = "client_receiver")]
//! {
//! use versa::client_receiver::verify_webhook;
//! if verify_webhook(&signature, &body, &"webhook_secret")? {
//! match webhook_event.event {
//! WebhookEventType::Receipt => {
//! println!("Received receipt: ${:.2}", webhook_event.data.header.total as f64 / 100.0);
//! }
//! _ => {
//! println!("Received other webhook event");
//! }
//! }
//! }
//! }
//! # */
//! # Ok(())
//! # }
//! ```
//!
//! ## Architecture
//!
//! The crate is organized into several modules:
//!
//! - [`protocol`]: Core protocol types for Versa communication
//! - [`schema`]: Document schemas (receipts, itineraries) with full type definitions
//! - [`client`]: Common client functionality (available with `client` feature)
//! - [`client_sender`]: Sender-specific utilities (available with `client_sender` feature)
//! - [`client_receiver`]: Receiver-specific utilities (available with `client_receiver` feature)
//!
//! ## Schema Versions
//!
//! This crate supports multiple schema versions:
//! - **2.0.0**: Current version with nullable array support
//! - **1.11.0**: Legacy version
//!
//! For more information about the Versa Protocol, visit [https://versa.org](https://versa.org).
/// Protocol types for Versa communication including customer registration, webhooks, and misuse reporting.
/// Document schemas for receipts and itineraries with full type definitions.
/// Common client functionality for interacting with the Versa registry.
///
/// This module provides utilities for checking registry availability and
/// managing HTTP communications with Versa services.
/// Sender-specific utilities for services that send receipts.
///
/// This module includes functions for sending receipts to customers,
/// managing encryption, and handling customer registration.
/// Receiver-specific utilities for services that receive receipts.
///
/// This module includes webhook verification, receipt decryption,
/// and utilities for processing incoming Versa documents.