use std::fmt;
use serde::{Deserialize, Serialize};
use tracing::instrument;
use crate::core::client::UspsClient;
use crate::core::error::{Result, UspsError};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum TrackingExpand {
#[default]
Detail,
Summary,
}
impl fmt::Display for TrackingExpand {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Detail => write!(f, "detail"),
Self::Summary => write!(f, "summary"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct TrackingEvent {
#[serde(default)]
pub event_type: Option<String>,
#[serde(default)]
pub event_timestamp: Option<String>,
#[serde(default)]
pub event_city: Option<String>,
#[serde(default)]
pub event_state: Option<String>,
#[serde(rename = "eventZIP", default)]
pub event_zip: Option<String>,
#[serde(default)]
pub event_country: Option<String>,
#[serde(default)]
pub name: Option<String>,
#[serde(default)]
pub event_code: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct TrackingResponse {
pub tracking_number: String,
#[serde(default)]
pub delivery_eta: Option<String>,
#[serde(default)]
pub guaranteed_delivery_date: Option<String>,
#[serde(default)]
pub mail_class: Option<String>,
#[serde(default)]
pub origin_city: Option<String>,
#[serde(default)]
pub origin_state: Option<String>,
#[serde(rename = "originZIP", default)]
pub origin_zip: Option<String>,
#[serde(default)]
pub destination_city: Option<String>,
#[serde(default)]
pub destination_state: Option<String>,
#[serde(rename = "destinationZIP", default)]
pub destination_zip: Option<String>,
#[serde(default)]
pub status: Option<String>,
#[serde(default)]
pub status_category: Option<String>,
#[serde(default)]
pub status_summary: Option<String>,
#[serde(default)]
pub tracking_events: Vec<TrackingEvent>,
}
#[derive(Debug, Clone)]
pub struct TrackingService {
client: UspsClient,
}
impl TrackingService {
#[must_use]
pub(crate) fn new(client: UspsClient) -> Self {
Self { client }
}
#[instrument(skip(self), name = "track_package")]
pub async fn track(&self, tracking_number: &str) -> Result<TrackingResponse> {
self.track_with_expand(tracking_number, TrackingExpand::Detail)
.await
}
#[instrument(skip(self), name = "track_package_with_expand")]
pub async fn track_with_expand(
&self,
tracking_number: &str,
expand: TrackingExpand,
) -> Result<TrackingResponse> {
let clean_number = tracking_number.trim();
if clean_number.is_empty() {
return Err(UspsError::InvalidInput(
"El número de seguimiento no puede estar vacío".to_string(),
));
}
if clean_number.contains(['/', '?', '&', '#', ' ']) {
return Err(UspsError::InvalidInput(
"El número de seguimiento contiene caracteres inválidos".to_string(),
));
}
let endpoint = format!("/tracking/v3/tracking/{clean_number}");
let query = [("expand", expand.to_string())];
self.client.get_with_query(&endpoint, &query).await
}
#[instrument(skip(self, tracking_numbers), name = "track_batch")]
pub async fn track_batch(
&self,
tracking_numbers: &[impl AsRef<str>],
expand: TrackingExpand,
) -> Result<Vec<TrackingResponse>> {
if tracking_numbers.is_empty() {
return Err(UspsError::InvalidInput(
"Debe indicarse al menos un número de seguimiento para la consulta por lotes"
.to_string(),
));
}
if tracking_numbers.len() > 35 {
return Err(UspsError::InvalidInput(
"USPS admite un máximo de 35 números de seguimiento por consulta por lotes"
.to_string(),
));
}
let cleaned: Vec<String> = tracking_numbers
.iter()
.map(|n| n.as_ref().trim().to_string())
.collect();
for n in &cleaned {
if n.is_empty() || n.contains(['/', '?', '&', '#', ' ']) {
return Err(UspsError::InvalidInput(format!(
"Número de seguimiento inválido: '{n}'"
)));
}
}
let joined = cleaned.join(",");
let endpoint = "/tracking/v3/tracking";
let query = [("trackingNumbers", joined), ("expand", expand.to_string())];
self.client.get_with_query(endpoint, &query).await
}
#[instrument(skip(self), name = "request_proof_of_delivery")]
pub async fn request_proof_of_delivery(
&self,
req: &ProofOfDeliveryRequest,
) -> Result<ProofOfDeliveryResponse> {
let clean_number = req.tracking_number.trim();
if clean_number.is_empty() || clean_number.contains(['/', '?', '&', '#', ' ']) {
return Err(UspsError::InvalidInput(
"El número de seguimiento no puede estar vacío ni contener caracteres especiales"
.to_string(),
));
}
let clean_email = req.email.trim();
if clean_email.is_empty() || !clean_email.contains('@') {
return Err(UspsError::InvalidInput(
"Debe proporcionar una dirección de correo electrónico válida para recibir el comprobante".to_string(),
));
}
if req.first_name.trim().is_empty() || req.last_name.trim().is_empty() {
return Err(UspsError::InvalidInput(
"El nombre y apellido del solicitante son obligatorios".to_string(),
));
}
let endpoint = "/tracking/v3/proof-of-delivery";
self.client.post_json(endpoint, req).await
}
}
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum ProofOfDeliveryFormat {
Letter,
Signature,
}
impl fmt::Display for ProofOfDeliveryFormat {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Letter => write!(f, "LETTER"),
Self::Signature => write!(f, "SIGNATURE"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ProofOfDeliveryRequest {
pub tracking_number: String,
pub email: String,
pub first_name: String,
pub last_name: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub format: Option<ProofOfDeliveryFormat>,
}
impl ProofOfDeliveryRequest {
#[must_use]
pub fn new(
tracking_number: impl Into<String>,
email: impl Into<String>,
first_name: impl Into<String>,
last_name: impl Into<String>,
) -> Self {
Self {
tracking_number: tracking_number.into(),
email: email.into(),
first_name: first_name.into(),
last_name: last_name.into(),
format: None,
}
}
#[must_use]
pub fn format(mut self, format: ProofOfDeliveryFormat) -> Self {
self.format = Some(format);
self
}
}
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ProofOfDeliveryResponse {
pub tracking_number: String,
#[serde(default)]
pub request_id: Option<String>,
#[serde(default)]
pub status: Option<String>,
#[serde(default)]
pub email: Option<String>,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn tracking_response_deserialization() {
let json = r#"{
"trackingNumber": "9400100000000000000000",
"status": "In Transit",
"statusCategory": "In Transit",
"statusSummary": "Your package is moving within the USPS network.",
"originCity": "DALLAS",
"originState": "TX",
"originZIP": "75201",
"destinationCity": "SEATTLE",
"destinationState": "WA",
"destinationZIP": "98101",
"trackingEvents": [
{
"eventType": "10",
"eventTimestamp": "2026-09-15T08:30:00",
"eventCity": "DALLAS",
"eventState": "TX",
"eventZIP": "75201",
"name": "Accepted at USPS Origin Facility"
}
]
}"#;
let res: TrackingResponse = serde_json::from_str(json).unwrap();
assert_eq!(res.tracking_number, "9400100000000000000000");
assert_eq!(res.status.as_deref(), Some("In Transit"));
assert_eq!(res.tracking_events.len(), 1);
assert_eq!(
res.tracking_events[0].name.as_deref(),
Some("Accepted at USPS Origin Facility")
);
}
#[test]
fn tracking_expand_display() {
assert_eq!(TrackingExpand::Detail.to_string(), "detail");
assert_eq!(TrackingExpand::Summary.to_string(), "summary");
}
#[tokio::test]
async fn track_batch_validation_should_fail_when_empty() {
let client = UspsClient::builder()
.credentials("test", "secret")
.build()
.unwrap();
let empty: [&str; 0] = [];
let err = client
.tracking()
.track_batch(&empty, TrackingExpand::Summary)
.await
.unwrap_err();
assert!(matches!(err, UspsError::InvalidInput(_)));
}
#[tokio::test]
async fn track_batch_validation_should_fail_when_over_35_items() {
let client = UspsClient::builder()
.credentials("test", "secret")
.build()
.unwrap();
let mut nums = Vec::new();
for i in 0..36 {
nums.push(format!("94001000000000000000{i:02}"));
}
let err = client
.tracking()
.track_batch(&nums, TrackingExpand::Summary)
.await
.unwrap_err();
assert!(matches!(err, UspsError::InvalidInput(_)));
}
#[test]
fn proof_of_delivery_request_builder() {
let req = ProofOfDeliveryRequest::new(
"9400100000000000000000",
"shipper@example.com",
"Jane",
"Doe",
)
.format(ProofOfDeliveryFormat::Letter);
assert_eq!(req.tracking_number, "9400100000000000000000");
assert_eq!(req.email, "shipper@example.com");
assert_eq!(req.first_name, "Jane");
assert_eq!(req.last_name, "Doe");
assert_eq!(req.format, Some(ProofOfDeliveryFormat::Letter));
assert_eq!(ProofOfDeliveryFormat::Letter.to_string(), "LETTER");
assert_eq!(ProofOfDeliveryFormat::Signature.to_string(), "SIGNATURE");
}
#[test]
fn proof_of_delivery_response_deserialization() {
let json = r#"{
"trackingNumber": "9400100000000000000000",
"requestId": "POD-998877",
"status": "Request Processed",
"email": "shipper@example.com"
}"#;
let res: ProofOfDeliveryResponse = serde_json::from_str(json).unwrap();
assert_eq!(res.tracking_number, "9400100000000000000000");
assert_eq!(res.request_id.as_deref(), Some("POD-998877"));
assert_eq!(res.status.as_deref(), Some("Request Processed"));
assert_eq!(res.email.as_deref(), Some("shipper@example.com"));
}
#[tokio::test]
async fn proof_of_delivery_validation_should_fail_on_bad_inputs() {
let client = UspsClient::builder()
.credentials("test", "secret")
.build()
.unwrap();
let req1 = ProofOfDeliveryRequest::new("", "user@example.com", "Jane", "Doe");
let err1 = client
.tracking()
.request_proof_of_delivery(&req1)
.await
.unwrap_err();
assert!(matches!(err1, UspsError::InvalidInput(_)));
let req2 =
ProofOfDeliveryRequest::new("9400100000000000000000", "invalid-email", "Jane", "Doe");
let err2 = client
.tracking()
.request_proof_of_delivery(&req2)
.await
.unwrap_err();
assert!(matches!(err2, UspsError::InvalidInput(_)));
let req3 =
ProofOfDeliveryRequest::new("9400100000000000000000", "user@example.com", "", "Doe");
let err3 = client
.tracking()
.request_proof_of_delivery(&req3)
.await
.unwrap_err();
assert!(matches!(err3, UspsError::InvalidInput(_)));
}
}