use std::fmt;
use serde::{Deserialize, Serialize};
use tracing::instrument;
use crate::core::client::UspsClient;
use crate::core::error::{Result, UspsError};
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum MailClass {
UspsGroundAdvantage,
PriorityMail,
PriorityMailExpress,
MediaMail,
LibraryMail,
FirstClassMail,
}
impl fmt::Display for MailClass {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::UspsGroundAdvantage => write!(f, "USPS_GROUND_ADVANTAGE"),
Self::PriorityMail => write!(f, "PRIORITY_MAIL"),
Self::PriorityMailExpress => write!(f, "PRIORITY_MAIL_EXPRESS"),
Self::MediaMail => write!(f, "MEDIA_MAIL"),
Self::LibraryMail => write!(f, "LIBRARY_MAIL"),
Self::FirstClassMail => write!(f, "FIRST_CLASS_MAIL"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum ProcessingCategory {
Letters,
Flats,
Machinable,
NonMachinable,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DomesticRateRequest {
#[serde(rename = "originZIPCode")]
pub origin_zip_code: String,
#[serde(rename = "destinationZIPCode")]
pub destination_zip_code: String,
pub weight: f64,
#[serde(skip_serializing_if = "Option::is_none")]
pub length: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub width: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub height: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub mail_class: Option<MailClass>,
#[serde(skip_serializing_if = "Option::is_none")]
pub processing_category: Option<ProcessingCategory>,
#[serde(skip_serializing_if = "Option::is_none")]
pub mailing_date: Option<String>,
}
impl DomesticRateRequest {
#[must_use]
pub fn new(
origin_zip_code: impl Into<String>,
destination_zip_code: impl Into<String>,
weight_lbs: f64,
) -> Self {
Self {
origin_zip_code: origin_zip_code.into(),
destination_zip_code: destination_zip_code.into(),
weight: weight_lbs,
length: None,
width: None,
height: None,
mail_class: None,
processing_category: None,
mailing_date: None,
}
}
#[must_use]
pub fn dimensions(mut self, length: f64, width: f64, height: f64) -> Self {
self.length = Some(length);
self.width = Some(width);
self.height = Some(height);
self
}
#[must_use]
pub fn mail_class(mut self, mail_class: MailClass) -> Self {
self.mail_class = Some(mail_class);
self
}
#[must_use]
pub fn processing_category(mut self, category: ProcessingCategory) -> Self {
self.processing_category = Some(category);
self
}
#[must_use]
pub fn mailing_date(mut self, date: impl Into<String>) -> Self {
self.mailing_date = Some(date.into());
self
}
}
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RateItem {
#[serde(default)]
pub mail_class: Option<String>,
pub price: f64,
#[serde(default)]
pub description: Option<String>,
#[serde(default)]
pub sku: Option<String>,
#[serde(default)]
pub zone: Option<String>,
#[serde(default)]
pub nonstandard_fee: Option<f64>,
}
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct DomesticRateResponse {
#[serde(default)]
pub total_base_price: Option<f64>,
#[serde(default)]
pub rates: Vec<RateItem>,
#[serde(default)]
pub warnings: Vec<String>,
}
#[derive(Debug, Clone)]
pub struct PricesService {
client: UspsClient,
}
impl PricesService {
#[must_use]
pub(crate) fn new(client: UspsClient) -> Self {
Self { client }
}
#[instrument(skip(self), name = "calculate_domestic_rates")]
pub async fn calculate_domestic_rates(
&self,
req: &DomesticRateRequest,
) -> Result<DomesticRateResponse> {
let origin = req.origin_zip_code.trim();
let dest = req.destination_zip_code.trim();
if origin.len() != 5 || !origin.chars().all(|c| c.is_ascii_digit()) {
return Err(UspsError::InvalidInput(
"El código postal de origen debe tener exactamente 5 dígitos".to_string(),
));
}
if dest.len() != 5 || !dest.chars().all(|c| c.is_ascii_digit()) {
return Err(UspsError::InvalidInput(
"El código postal de destino debe tener exactamente 5 dígitos".to_string(),
));
}
if req.weight <= 0.0 {
return Err(UspsError::InvalidInput(
"El peso del paquete debe ser estrictamente mayor a 0 libras".to_string(),
));
}
let endpoint = "/prices/v3/base-rates/search";
self.client.post_json(endpoint, req).await
}
#[instrument(skip(self), name = "calculate_international_rates")]
pub async fn calculate_international_rates(
&self,
req: &InternationalRateRequest,
) -> Result<InternationalRateResponse> {
let origin = req.origin_zip_code.trim();
let country = req.destination_country_code.trim();
if origin.len() != 5 || !origin.chars().all(|c| c.is_ascii_digit()) {
return Err(UspsError::InvalidInput(
"El código postal de origen debe tener exactamente 5 dígitos".to_string(),
));
}
if country.len() != 2 {
return Err(UspsError::InvalidInput(
"El código del país de destino debe ser un código ISO de 2 caracteres (ej. 'CA', 'GB', 'MX')".to_string(),
));
}
if req.weight <= 0.0 {
return Err(UspsError::InvalidInput(
"El peso del paquete debe ser estrictamente mayor a 0 libras".to_string(),
));
}
let endpoint = "/prices/v3/international-base-rates/search";
self.client.post_json(endpoint, req).await
}
#[instrument(skip(self), name = "calculate_extra_services")]
pub async fn calculate_extra_services(
&self,
req: &ExtraServicesRateRequest,
) -> Result<ExtraServicesRateResponse> {
if req.price < 0.0 {
return Err(UspsError::InvalidInput(
"El precio de franqueo base no puede ser negativo".to_string(),
));
}
if req.weight <= 0.0 {
return Err(UspsError::InvalidInput(
"El peso del paquete debe ser estrictamente mayor a 0 libras".to_string(),
));
}
if let Some(val) = req.declared_value {
if val < 0.0 {
return Err(UspsError::InvalidInput(
"El valor declarado no puede ser negativo".to_string(),
));
}
}
let endpoint = "/prices/v3/extra-services";
self.client.post_json(endpoint, req).await
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum InternationalMailClass {
GlobalExpressGuaranteed,
PriorityMailExpressInternational,
PriorityMailInternational,
FirstClassPackageInternationalService,
FirstClassMailInternational,
}
impl fmt::Display for InternationalMailClass {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::GlobalExpressGuaranteed => write!(f, "GLOBAL_EXPRESS_GUARANTEED"),
Self::PriorityMailExpressInternational => {
write!(f, "PRIORITY_MAIL_EXPRESS_INTERNATIONAL")
}
Self::PriorityMailInternational => write!(f, "PRIORITY_MAIL_INTERNATIONAL"),
Self::FirstClassPackageInternationalService => {
write!(f, "FIRST_CLASS_PACKAGE_INTERNATIONAL_SERVICE")
}
Self::FirstClassMailInternational => write!(f, "FIRST_CLASS_MAIL_INTERNATIONAL"),
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct InternationalRateRequest {
#[serde(rename = "originZIPCode")]
pub origin_zip_code: String,
pub destination_country_code: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub foreign_postal_code: Option<String>,
pub weight: f64,
#[serde(skip_serializing_if = "Option::is_none")]
pub length: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub width: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub height: Option<f64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub mail_class: Option<InternationalMailClass>,
#[serde(skip_serializing_if = "Option::is_none")]
pub mailing_date: Option<String>,
}
impl InternationalRateRequest {
#[must_use]
pub fn new(
origin_zip_code: impl Into<String>,
destination_country_code: impl Into<String>,
weight_lbs: f64,
) -> Self {
Self {
origin_zip_code: origin_zip_code.into(),
destination_country_code: destination_country_code.into(),
foreign_postal_code: None,
weight: weight_lbs,
length: None,
width: None,
height: None,
mail_class: None,
mailing_date: None,
}
}
#[must_use]
pub fn dimensions(mut self, length: f64, width: f64, height: f64) -> Self {
self.length = Some(length);
self.width = Some(width);
self.height = Some(height);
self
}
#[must_use]
pub fn foreign_postal_code(mut self, postal_code: impl Into<String>) -> Self {
self.foreign_postal_code = Some(postal_code.into());
self
}
#[must_use]
pub fn mail_class(mut self, mail_class: InternationalMailClass) -> Self {
self.mail_class = Some(mail_class);
self
}
}
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct InternationalRateResponse {
#[serde(default)]
pub total_base_price: Option<f64>,
#[serde(default)]
pub rates: Vec<RateItem>,
#[serde(default)]
pub warnings: Vec<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum ExtraServiceType {
CertifiedMail,
Insurance,
SignatureConfirmation,
AdultSignatureRequired,
AdultSignatureRestrictedDelivery,
ReturnReceipt,
RegisteredMail,
CollectOnDelivery,
SpecialHandling,
RestrictedDelivery,
}
impl fmt::Display for ExtraServiceType {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::CertifiedMail => write!(f, "CERTIFIED_MAIL"),
Self::Insurance => write!(f, "INSURANCE"),
Self::SignatureConfirmation => write!(f, "SIGNATURE_CONFIRMATION"),
Self::AdultSignatureRequired => write!(f, "ADULT_SIGNATURE_REQUIRED"),
Self::AdultSignatureRestrictedDelivery => {
write!(f, "ADULT_SIGNATURE_RESTRICTED_DELIVERY")
}
Self::ReturnReceipt => write!(f, "RETURN_RECEIPT"),
Self::RegisteredMail => write!(f, "REGISTERED_MAIL"),
Self::CollectOnDelivery => write!(f, "COLLECT_ON_DELIVERY"),
Self::SpecialHandling => write!(f, "SPECIAL_HANDLING"),
Self::RestrictedDelivery => write!(f, "RESTRICTED_DELIVERY"),
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ExtraServicesRateRequest {
pub mail_class: MailClass,
pub price: f64,
pub weight: f64,
#[serde(skip_serializing_if = "Option::is_none")]
pub declared_value: Option<f64>,
#[serde(skip_serializing_if = "Vec::is_empty", default)]
pub extra_services: Vec<ExtraServiceType>,
}
impl ExtraServicesRateRequest {
#[must_use]
pub fn new(mail_class: MailClass, base_price: f64, weight_lbs: f64) -> Self {
Self {
mail_class,
price: base_price,
weight: weight_lbs,
declared_value: None,
extra_services: Vec::new(),
}
}
#[must_use]
pub fn declared_value(mut self, value_usd: f64) -> Self {
self.declared_value = Some(value_usd);
self
}
#[must_use]
pub fn add_extra_service(mut self, service: ExtraServiceType) -> Self {
self.extra_services.push(service);
self
}
}
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ExtraServiceRateItem {
pub name: String,
#[serde(default)]
pub service_id: Option<String>,
pub price: f64,
#[serde(default)]
pub description: Option<String>,
#[serde(default)]
pub warnings: Vec<String>,
}
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ExtraServicesRateResponse {
#[serde(default)]
pub extra_services: Vec<ExtraServiceRateItem>,
#[serde(default)]
pub warnings: Vec<String>,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn domestic_rate_request_builder() {
let req = DomesticRateRequest::new("90210", "10001", 3.25)
.dimensions(12.0, 8.0, 4.5)
.mail_class(MailClass::PriorityMail)
.processing_category(ProcessingCategory::Machinable);
assert_eq!(req.origin_zip_code, "90210");
assert_eq!(req.destination_zip_code, "10001");
assert_eq!(req.weight, 3.25);
assert_eq!(req.length, Some(12.0));
assert_eq!(req.mail_class, Some(MailClass::PriorityMail));
assert_eq!(
req.processing_category,
Some(ProcessingCategory::Machinable)
);
}
#[test]
fn domestic_rate_response_deserialization() {
let json = r#"{
"totalBasePrice": 9.65,
"rates": [
{
"mailClass": "PRIORITY_MAIL",
"price": 9.65,
"description": "Priority Mail 2-Day",
"zone": "Zone 8",
"sku": "PM-D-08"
},
{
"mailClass": "USPS_GROUND_ADVANTAGE",
"price": 7.15,
"description": "USPS Ground Advantage",
"zone": "Zone 8"
}
],
"warnings": []
}"#;
let res: DomesticRateResponse = serde_json::from_str(json).unwrap();
assert_eq!(res.total_base_price, Some(9.65));
assert_eq!(res.rates.len(), 2);
assert_eq!(res.rates[0].mail_class.as_deref(), Some("PRIORITY_MAIL"));
assert_eq!(res.rates[0].price, 9.65);
assert_eq!(res.rates[0].zone.as_deref(), Some("Zone 8"));
assert_eq!(res.rates[1].price, 7.15);
}
#[test]
fn mail_class_display() {
assert_eq!(MailClass::PriorityMail.to_string(), "PRIORITY_MAIL");
assert_eq!(
MailClass::UspsGroundAdvantage.to_string(),
"USPS_GROUND_ADVANTAGE"
);
assert_eq!(
InternationalMailClass::PriorityMailInternational.to_string(),
"PRIORITY_MAIL_INTERNATIONAL"
);
}
#[test]
fn international_rate_request_builder() {
let req = InternationalRateRequest::new("90210", "CA", 4.5)
.foreign_postal_code("M5V 2T6")
.dimensions(10.0, 8.0, 6.0)
.mail_class(InternationalMailClass::PriorityMailInternational);
assert_eq!(req.origin_zip_code, "90210");
assert_eq!(req.destination_country_code, "CA");
assert_eq!(req.foreign_postal_code.as_deref(), Some("M5V 2T6"));
assert_eq!(req.weight, 4.5);
assert_eq!(
req.mail_class,
Some(InternationalMailClass::PriorityMailInternational)
);
}
#[test]
fn international_rate_response_deserialization() {
let json = r#"{
"totalBasePrice": 34.50,
"rates": [
{
"mailClass": "PRIORITY_MAIL_INTERNATIONAL",
"price": 34.50,
"description": "Priority Mail International 6-10 Days",
"sku": "PMI-CA-01"
}
],
"warnings": []
}"#;
let res: InternationalRateResponse = serde_json::from_str(json).unwrap();
assert_eq!(res.total_base_price, Some(34.50));
assert_eq!(res.rates.len(), 1);
assert_eq!(
res.rates[0].mail_class.as_deref(),
Some("PRIORITY_MAIL_INTERNATIONAL")
);
assert_eq!(res.rates[0].price, 34.50);
}
#[test]
fn extra_services_rate_request_builder() {
let req = ExtraServicesRateRequest::new(MailClass::PriorityMail, 10.50, 2.0)
.declared_value(250.0)
.add_extra_service(ExtraServiceType::Insurance)
.add_extra_service(ExtraServiceType::SignatureConfirmation);
assert_eq!(req.mail_class, MailClass::PriorityMail);
assert_eq!(req.price, 10.50);
assert_eq!(req.weight, 2.0);
assert_eq!(req.declared_value, Some(250.0));
assert_eq!(req.extra_services.len(), 2);
assert_eq!(req.extra_services[0], ExtraServiceType::Insurance);
assert_eq!(
req.extra_services[1],
ExtraServiceType::SignatureConfirmation
);
assert_eq!(ExtraServiceType::Insurance.to_string(), "INSURANCE");
assert_eq!(
ExtraServiceType::CertifiedMail.to_string(),
"CERTIFIED_MAIL"
);
}
#[test]
fn extra_services_rate_response_deserialization() {
let json = r#"{
"extraServices": [
{
"name": "Insurance",
"serviceId": "100",
"price": 4.20,
"description": "Coverage up to $300.00"
},
{
"name": "Signature Confirmation",
"serviceId": "108",
"price": 3.65,
"description": "Recipient signature required"
}
],
"warnings": []
}"#;
let res: ExtraServicesRateResponse = serde_json::from_str(json).unwrap();
assert_eq!(res.extra_services.len(), 2);
assert_eq!(res.extra_services[0].name, "Insurance");
assert_eq!(res.extra_services[0].price, 4.20);
assert_eq!(res.extra_services[0].service_id.as_deref(), Some("100"));
assert_eq!(res.extra_services[1].name, "Signature Confirmation");
assert_eq!(res.extra_services[1].price, 3.65);
}
}