versa/
lib.rs

1//! # Versa Protocol Rust SDK
2//!
3//! The official Rust implementation of the Versa Protocol, providing types and utilities
4//! for developing Versa client applications.
5//!
6//! ## Overview
7//!
8//! Versa is an open protocol that allows any service to send itemized receipts, invoices,
9//! and other transaction records directly to their customers in a structured, machine-readable
10//! format. This crate provides:
11//!
12//! - **Schema Types**: Strongly-typed representations of Versa receipts and itineraries
13//! - **Protocol Types**: Core protocol messages for customer registration, webhooks, and misuse reporting
14//! - **Client Utilities**: Helper functions for sending and receiving Versa documents
15//! - **Validation**: Schema validation for ensuring document compliance
16//!
17//! ## Feature Flags
18//!
19//! This crate uses feature flags to minimize dependencies:
20//!
21//! - `client`: Core client functionality (HTTP requests, encryption, HMAC)
22//! - `client_sender`: Utilities for services sending receipts
23//! - `client_receiver`: Utilities for services receiving receipts
24//! - `validator`: JSON Schema validation support
25//!
26//! ## Quick Start
27//!
28//! ### As a Sender (Merchant/Service)
29//!
30//! ```rust,no_run
31//! use versa::schema::receipt::{Receipt, Header, Currency};
32//! use versa::schema::current::SCHEMA_VERSION;
33//! use std::str::FromStr;
34//!
35//! # fn example() -> Result<(), Box<dyn std::error::Error>> {
36//! // Create a receipt
37//! let receipt = Receipt {
38//!     schema_version: SCHEMA_VERSION.parse()?,
39//!     header: Header {
40//!         total: 10000, // $100.00 in cents
41//!         currency: Currency::from_str("usd")?,
42//!         subtotal: 10000,
43//!         invoiced_at: 1234567890,
44//!         paid: 10000,
45//!         customer: None,
46//!         invoice_asset_id: None,
47//!         invoice_number: None,
48//!         location: None,
49//!         mcc: None,
50//!         receipt_asset_id: None,
51//!         third_party: None,
52//!     },
53//!     itemization: versa::schema::receipt::Itemization::builder().try_into()?,
54//!     payments: vec![],
55//!     footer: versa::schema::receipt::Footer::builder().try_into()?,
56//! };
57//!
58//! // Send to customer using client_sender feature
59//! # /*
60//! #[cfg(feature = "client_sender")]
61//! {
62//!     use versa::client_sender::send_receipt;
63//!     // send_receipt(&receipt, "customer@example.com").await?;
64//! }
65//! # */
66//! # Ok(())
67//! # }
68//! ```
69//!
70//! ### As a Receiver (Inbox/Aggregator)
71//!
72//! ```rust,no_run
73//! use versa::protocol::webhook::{WebhookEvent, WebhookEventType};
74//! use versa::schema::receipt::Receipt;
75//!
76//! # fn example(signature: &str, body: &str) -> Result<(), Box<dyn std::error::Error>> {
77//! // Parse incoming webhook
78//! let webhook_event: WebhookEvent<Receipt> = serde_json::from_str(&body)?;
79//!
80//! // Verify and process the receipt using client_receiver feature
81//! # /*
82//! #[cfg(feature = "client_receiver")]
83//! {
84//!     use versa::client_receiver::verify_webhook;
85//!     if verify_webhook(&signature, &body, &"webhook_secret")? {
86//!         match webhook_event.event {
87//!             WebhookEventType::Receipt => {
88//!                 println!("Received receipt: ${:.2}", webhook_event.data.header.total as f64 / 100.0);
89//!             }
90//!             _ => {
91//!                 println!("Received other webhook event");
92//!             }
93//!         }
94//!     }
95//! }
96//! # */
97//! # Ok(())
98//! # }
99//! ```
100//!
101//! ## Architecture
102//!
103//! The crate is organized into several modules:
104//!
105//! - [`protocol`]: Core protocol types for Versa communication
106//! - [`schema`]: Document schemas (receipts, itineraries) with full type definitions
107//! - [`client`]: Common client functionality (available with `client` feature)
108//! - [`client_sender`]: Sender-specific utilities (available with `client_sender` feature)
109//! - [`client_receiver`]: Receiver-specific utilities (available with `client_receiver` feature)
110//!
111//! ## Schema Versions
112//!
113//! This crate supports multiple schema versions:
114//! - **2.0.0**: Current version with nullable array support
115//! - **1.11.0**: Legacy version
116//!
117//! For more information about the Versa Protocol, visit [https://versa.org](https://versa.org).
118
119/// Protocol types for Versa communication including customer registration, webhooks, and misuse reporting.
120pub mod protocol;
121
122/// Document schemas for receipts and itineraries with full type definitions.
123pub mod schema;
124
125#[cfg(any(feature = "client_sender", feature = "client_receiver"))]
126mod encryption;
127
128#[cfg(any(feature = "client_sender", feature = "client_receiver"))]
129mod hmac_util;
130
131/// Common client functionality for interacting with the Versa registry.
132///
133/// This module provides utilities for checking registry availability and
134/// managing HTTP communications with Versa services.
135#[cfg(feature = "client")]
136pub mod client;
137
138/// Sender-specific utilities for services that send receipts.
139///
140/// This module includes functions for sending receipts to customers,
141/// managing encryption, and handling customer registration.
142#[cfg(feature = "client_sender")]
143pub mod client_sender;
144
145/// Receiver-specific utilities for services that receive receipts.
146///
147/// This module includes webhook verification, receipt decryption,
148/// and utilities for processing incoming Versa documents.
149#[cfg(feature = "client_receiver")]
150pub mod client_receiver;
versa/lib.rs

versa/
lib.rs
