1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
// Copyright 2026 César A Vergara Buenaventura <cesarvergarab@gmail.com>
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//! # usps_v3_api
//!
//! SDK en Rust idiomático, fuertemente tipado, asíncrono y listo para producción
//! para interactuar con el ecosistema de APIs REST v3 del Servicio Postal de los
//! Estados Unidos (USPS - United States Postal Service).
//!
//! ## Características Principales
//!
//! - **Arquitectura Modular en Capas:** Separación limpia entre infraestructura transversal ([`core`])
//! y catálogo de servicios de negocio ([`services`]).
//! - **Gestión Inteligente de Autenticación OAuth 2.0:** Manejo automático del ciclo de vida del token
//! Bearer (`POST /oauth2/v3/token`), con almacenamiento seguro en memoria mediante [`tokio::sync::RwLock`],
//! renovación transparente con margen de expiración y patrón double-checked lock.
//! - **Seguridad en Producción:** Protección de credenciales confidenciales (`client_secret`) contra fugas
//! accidentales en logs de depuración (`[REDACTED]`).
//! - **Servicio de Direcciones (`Addresses v3`):** Estandarización de direcciones, validación de entrega DPV,
//! búsqueda de códigos postales (ZIP Lookup) y resolución de ciudad/estado.
//! - **Servicio de Seguimiento (`Tracking v3`):** Consulta individual y por lotes (hasta 35 paquetes) de envíos en tránsito,
//! detalle de eventos históricos, estados y fechas estimadas de entrega.
//! - **Servicio de Precios y Tarifas (`Prices v3`):** Cotización de tarifas postales nacionales e internacionales
//! por peso, dimensiones y clases postales (`Priority Mail`, `USPS Ground Advantage`, `Global Express Guaranteed`, etc.).
//! - **Servicio de Estándares de Entrega (`Service Standards v3`):** Cálculo de compromisos de entrega, fechas estimadas
//! (Expected Delivery Date - EDD) y días de tránsito entre códigos postales origen y destino.
//! - **Servicio de Etiquetas (`Labels v3`):** Emisión y cancelación de etiquetas postales con código de barras en
//! formatos PDF, PNG, TIFF, SVG o Base64 (`POST /labels/v3/label`, `DELETE /labels/v3/label/{id}`).
//! - **Servicio de Manifiestos (`Manifests v3`):** Consolidación de envíos masivos en un Formulario SCAN Form
//! (PS Form 5630) con código de barras maestro (`POST /manifests/v3/manifest`, `GET /manifests/v3/manifest/{id}`).
//! - **Servicio de Recolección (`Pickup v3`):** Verificación de disponibilidad, programación y cancelación de recolección
//! de paquetes por cartero a domicilio (`Carrier Pickup`).
//! - **Servicio de Ubicaciones (`Locations v3`):** Búsqueda de oficinas postales, buzones de depósito y quioscos
//! por código postal o geocordenadas, consulta de horarios semanales y servicios (pasaportes, casilleros).
//! - **Servicio de Webhooks (`Subscriptions v3`):** Registro, consulta y cancelación de callbacks HTTP en tiempo real
//! para eventos de rastreo y entrega (`POST /subscriptions/v3/subscription`, `DELETE /subscriptions/v3/subscription/{id}`).
//! - **Servicio de Pagos EPS (`Payments v3`):** Consulta de saldos y autorizaciones en el Enterprise Payment System de USPS.
//! - **Declaraciones Aduaneras (`Customs v3`):** Modelado de formularios CN22 y CP72, partidas arancelarias HTS y exenciones AES/ITN.
//! - **Resiliencia y Reintentos:** Política de backoff exponencial con jitter ([`RetryPolicy`]) ante respuestas transitorias
//! HTTP 429 (Rate Limit), 500, 502, 503 y 504.
//! - **Manejo Exhaustivo de Errores:** Jerarquía fuertemente tipada con [`UspsError`] y deserialización
//! de errores estructurados devueltos por la pasarela de USPS.
//!
//! ## Ejemplo de Uso Rápido
//!
//! ```no_run
//! use usps_v3_api::{
//! UspsClient, UspsEnvironment,
//! AddressStandardizationRequest, TrackingExpand,
//! };
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // 1. Inicializar el cliente SDK
//! let client = UspsClient::builder()
//! .credentials("TU_CLIENT_ID", "TU_CLIENT_SECRET")
//! .environment(UspsEnvironment::Sandbox)
//! .build()?;
//!
//! // 2. Estandarizar una dirección postal
//! let address_req = AddressStandardizationRequest::new("475 L'Enfant Plaza SW")
//! .city_state("Washington", "DC")
//! .zip_code("20260");
//!
//! let address_info = client.addresses().standardize(&address_req).await?;
//! println!("Dirección estandarizada: {:?}", address_info.address);
//!
//! // 3. Rastrear un paquete
//! let tracking = client.tracking().track("9400100000000000000000").await?;
//! println!("Estado del paquete: {:?}", tracking.status);
//!
//! Ok(())
//! }
//! ```
// Re-exportaciones públicas de la capa central (core)
pub use ;
// Re-exportaciones públicas del catálogo de servicios
pub use ;
// Módulos públicos canónicos para acceso granular
pub use auth;
pub use client;
pub use config;
pub use error;
pub use retry;
pub use addresses;
pub use customs;
pub use labels;
pub use locations;
pub use manifests;
pub use payments;
pub use pickup;
pub use prices;
pub use standards;
pub use tracking;
pub use webhooks;