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
}
}
#[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");
}
}