latch_billing/
lib.rs

1//! `latch-billing` - Pure synchronous token billing core library.
2//!
3//! This crate defines the core types, traits, and pricing models for
4//! token-based billing. It is **purely synchronous** and has **zero I/O**
5//! dependencies.
6//!
7//! # Architecture
8//!
9//! - **Types**: `UsageObservation`, `MeterSet`, `BillingSubject`, etc.
10//! - **Traits**: `PricingSource`, `RatingEngine`, `ObservationStore`,
11//!   `RatedRecordStore`, `RatedRecordExporter`, `QuotaAuthorizer`, etc.
12//! - **Design principle**: Runtime-agnostic sync library. Async I/O should be
13//!   implemented by downstream consumers (e.g., gateway applications).
14//!
15//! # Quick start
16//!
17//! ```rust,ignore
18//! use latch_billing::*;
19//!
20//! // 1. Create an observation
21//! let mut meter_set = MeterSet::new();
22//! meter_set.accumulate(MeterKind::InputTokens, 1000).unwrap();
23//!
24//! let observation = UsageObservation {
25//!     event_id: UsageEventId::from_attempt("req-123", 0, "openai").unwrap(),
26//!     subject: BillingSubject::default(),
27//!     meter_set,
28//!     model_ref: ModelRef { ... },
29//!     provider_ref: Some(ProviderRef { provider_id: "openai".to_string() }),
30//!     source: UsageSource::ProviderReported,
31//!     outcome: UsageOutcome::Success,
32//!     timing: UsageTiming { ... },
33//!     correlation: CorrelationIds::default(),
34//!     attributes: Attributes::new(),
35//! };
36//!
37//! // 2. Get a price snapshot (push mode - caller fethes)
38//! let snapshot = ...; // fetched by caller (e.e., from DB)
39//!
40//! // 3. Create rating context (for tier-based pricing)
41//! let context = RatingContext::default();
42//!
43//! // 4. Rate the observation
44//! let engine = DefaultRatingEngine::new();
45//! let rated = engine.rate(&observation, &snapshot, &context)?;
46//! println!("Cost: {} {}", rated.rating.total_cost, rated.rating.currency.0);
47//! ```
48//!
49//! # Module structure
50//!
51//! - `observation`: `UsageObservation`, `MeterSet`, `MeterKind`, `UsageSource`, `UsageOutcome`, `Attributes`
52//! - `identity`: `BillingSubject`, `UsageEventId`, `UsageEventIdBuilder`, `CorrelationIds`
53//! - `pricing`: `ModelRef`, `ProviderRef`, `PriceSnapshot`, `PricingSource` trait, `TierConfig`, `TierBaseline`
54//! - `rating`: `RatedUsageRecord`, `RatingResult`, `RatedLineItem`, `RatingEngine` trait, `RatingContext`
55//! - `storage`: `ObservationStore` trait, `RatedRecordStore` trait, `StoreResult`
56//! - `quota`: `QuotaAuthorizer` trait, `QuotaReservator` trait (Phase 2)
57//! - `export`: `RatedRecordExporter` trait
58
59// ============================================================================
60// Re-exports
61// ============================================================================
62
63// Core types
64pub use chrono;
65pub use rust_decimal;
66
67// Observation module
68pub mod observation;
69pub use observation::{
70    Attributes, AttributeError, CurrencyCode, CurrencyCodeError, MeterKind,
71    MeterSet, MeterSetError, UsageObservation, UsageOutcome, UsageSource,
72    UsageTiming,
73};
74
75// Identity module
76pub mod identity;
77pub use identity::{
78    BillingSubject, CorrelationIds, UsageEventId, UsageEventIdBuilder,
79    UsageEventIdError,
80};
81
82// Pricing module
83pub mod pricing;
84pub use pricing::{
85    AccumulationScope, MeterPrice, ModelRef, PriceSnapshot, PricingError,
86    PricingSource, ProviderRef, TierBaseline, TierBoundary, TierConfig,
87};
88
89// Rating module
90pub mod rating;
91pub use rating::{
92    RatedLineItem, RatedUsageRecord, RatingContext, RatingEngine, RatingError,
93    RatingResult,
94};
95
96// Storage module
97pub mod storage;
98pub use storage::{ObservationStore, RatedRecordStore, StoreError, StoreResult};
99
100// Quota module
101pub mod quota;
102pub use quota::{
103    QuotaAuthorizer, QuotaDecision, QuotaError, QuotaRequest, QuotaReservator,
104    Reservation, ReservationRequest, UsageAmount,
105};
106
107// Export module
108pub mod export;
109pub use export::{ExportError, RatedRecordExporter};
110
111// ============================================================================
112// Conditional modules
113// ============================================================================
114
115/// TOML pricing source (requires `toml` feature).
116#[cfg(feature = "toml")]
117pub mod toml_source;
118#[cfg(feature = "toml")]
119pub use toml_source::TomlPricingSource;
latch_billing/lib.rs

latch_billing/
lib.rs
