@teralabs/shipstack 1.2.0

package/docs/API.md

@@ -0,0 +1,176 @@
+# Shipstack API Reference
+
+This document covers the public Shipstack surface shipped through the npm entrypoint: `ShippingClient`, `ShippingManager`, the functional API, exported rate clients, and the core types.
+
+---
+
+## ShippingClient
+
+The `ShippingClient` is the primary stateful API for direct per-carrier operations.
+
+### Constructor
+
+```ts
+new ShippingClient(config: ShippingConfig)
+```
+
+### Methods
+
+#### `getRates(request: RateRequest): Promise<NormalizedRate[]>`
+Fetches normalized rates for the carrier specified on `request.carrier`.
+
+#### `validateAddress(request: AddressValidationRequest): Promise<AddressValidationResult>`
+Validates an address using the selected carrier.
+
+#### `track(trackingNumbers: string | string[], carrier: Carrier): Promise<NormalizedTracking[]>`
+Tracks one or more shipments with automatic batching and normalization.
+
+#### `getBestValue(request: RateRequest): Promise<NormalizedRate | null>`
+Returns the cheapest rate for the selected carrier.
+
+#### `getFastest(request: RateRequest): Promise<NormalizedRate | null>`
+Returns the fastest rate for the selected carrier.
+
+#### `buildShipment(request: ShipmentRequest): Promise<StagedShipment>`
+Builds a carrier-specific shipment payload without purchasing a label.
+
+#### `createShipment(request: ShipmentRequest): Promise<NormalizedShipment>`
+Creates an actual shipment and purchases a real label.
+
+#### `ShippingClient.predict(trackingNumber: string): Carrier | "unknown"`
+Static helper that predicts the carrier from a tracking number pattern.
+
+---
+
+## ShippingManager
+
+`ShippingManager` is the advanced stateful helper for cross-carrier checkout workflows.
+
+### Constructor
+
+```ts
+new ShippingManager(config: ShippingConfig)
+```
+
+### Methods
+
+#### `getRankedRates(request: Omit<RateRequest, "carrier">, carriers: Carrier[]): Promise<NormalizedRate[]>`
+Queries multiple carriers, merges the results, sorts by price, and marks `isCheapest` and `isFastest` when available.
+
+#### `validateAddress(request: AddressValidationRequest): Promise<AddressValidationResult>`
+Convenience wrapper around the address API using the manager's config.
+
+#### `track(trackingNumbers: string | string[], carrier: Carrier): Promise<NormalizedTracking[]>`
+Convenience wrapper around the tracking API using the manager's config.
+
+---
+
+## Functional API
+
+The functional API exposes stateless helpers when you do not want to retain a client instance.
+
+```ts
+getRates(request: RateRequest, config: ShippingConfig): Promise<NormalizedRate[]>
+validateAddress(request: AddressValidationRequest, config: ShippingConfig): Promise<AddressValidationResult>
+trackShipment(trackingNumbers: string | string[], carrier: Carrier, config: ShippingConfig): Promise<NormalizedTracking[]>
+getBestValueRate(request: RateRequest, config: ShippingConfig): Promise<NormalizedRate | null>
+getFastestService(request: RateRequest, config: ShippingConfig): Promise<NormalizedRate | null>
+predictCarrier(trackingNumber: string): Carrier | "unknown"
+buildShipment(request: ShipmentRequest, config: ShippingConfig): Promise<StagedShipment>
+createShipment(request: ShipmentRequest, config: ShippingConfig): Promise<NormalizedShipment>
+```
+
+---
+
+## Direct Carrier Access
+
+Only the low-level rate clients are exported directly from the package entrypoint.
+
+```ts
+createUspsRatesClient(config: UspsConfig)
+createFedexRatesClient(config: FedexConfig)
+createUpsRatesClient(config: UpsConfig)
+```
+
+---
+
+## Core Types
+
+### `ShippingConfig`
+
+```ts
+type ShippingConfig = {
+  environment?: "sandbox" | "production";
+  usps?: {
+    enabled: boolean;
+    clientId: string;
+    clientSecret: string;
+    apiKey?: string;
+    baseUrl?: string;
+    authUrl?: string;
+    labelsBaseUrl?: string;
+  };
+  fedex?: {
+    enabled: boolean;
+    clientId: string;
+    clientSecret: string;
+    accountNumber: string;
+    baseUrl?: string;
+  };
+  ups?: {
+    enabled: boolean;
+    clientId: string;
+    clientSecret: string;
+    accountNumber: string;
+    baseUrl?: string;
+  };
+};
+```
+
+### `RateRequest`
+Origin, destination, weight, and package dimensions for a single-carrier rate lookup.
+
+### `AddressValidationRequest`
+Carrier plus a structured postal address using `streetLines`, `stateOrProvinceCode`, and `countryCode`.
+
+### `AddressValidationResult`
+Top-level address validation response with `isValid`, optional `normalizedAddress`, and optional `messages`.
+
+### `NormalizedRate`
+Unified rate object returned by all carriers.
+
+### `NormalizedTracking`
+Normalized tracking status and event history.
+
+### `ShipmentRequest`
+Carrier, service, from/to addresses, and package details required to build or purchase a shipment.
+
+### `StagedShipment`
+Carrier-specific payload returned by `buildShipment`.
+
+### `NormalizedShipment`
+Unified shipment result returned by `createShipment`.
+
+---
+
+## Error Types
+
+### `ShipstackError`
+Base error type for Shipstack operations.
+
+Properties include:
+
+- `message`
+- `carrier` (`"usps" | "fedex" | "ups"`)
+- `cause`
+
+### `ThrottlingError`
+Extends `ShipstackError` and adds `retryAfter?: number` when a carrier returns a throttling signal.
+
+---
+
+## Full Type Definitions
+
+The published package exposes its full TypeScript surface through `dist/index.d.ts` and `dist/index.d.mts`.
+
+---

package/docs/address-validation.md

@@ -0,0 +1,114 @@
+# Address Validation in Shipstack
+
+Shipstack provides a unified interface for validating addresses across USPS, FedEx, and UPS.  
+All carrier responses are normalized into a consistent structure, regardless of the underlying API.
+
+---
+
+## Request Structure
+
+```ts
+type AddressValidationRequest = {
+  carrier: "usps" | "fedex" | "ups";
+  address: {
+    streetLines: string[];
+    city: string;
+    stateOrProvinceCode: string;
+    postalCode: string;
+    countryCode: string;
+  };
+};
+```
+
+### Notes
+
+- `streetLines` supports multiple address lines.
+- `countryCode` should be an ISO-3166-1 alpha-2 code such as `US`.
+- USPS, FedEx, and UPS may each return different levels of correction detail, but Shipstack normalizes the top-level response shape.
+
+---
+
+## Example
+
+```ts
+const result = await client.validateAddress({
+  carrier: "fedex",
+  address: {
+    streetLines: ["123 Main St"],
+    city: "New York",
+    stateOrProvinceCode: "NY",
+    postalCode: "10001",
+    countryCode: "US"
+  }
+});
+```
+
+---
+
+## Using the Functional API
+
+```ts
+import { validateAddress } from "@teralabs/shipstack";
+
+const result = await validateAddress(request, config);
+```
+
+---
+
+## Address Validation Result
+
+```ts
+type AddressValidationResult = {
+  isValid: boolean;
+  normalizedAddress?: {
+    street1: string;
+    street2?: string;
+    city: string;
+    state: string;
+    postalCode: string;
+    country: string;
+    isValid: boolean;
+    classification?: "RESIDENTIAL" | "COMMERCIAL" | "UNKNOWN";
+    isPoBox: boolean;
+    raw?: unknown;
+  };
+  messages?: string[];
+  raw?: unknown;
+};
+```
+
+### Field Notes
+
+- `isValid` indicates whether the carrier considers the address deliverable.
+- `normalizedAddress` is included when the carrier returns a standardized address shape.
+- `messages` may include warnings, suggestions, or correction notes.
+
+---
+
+## Carrier-Specific Behavior
+
+### USPS
+- Often returns corrected addresses.
+- May normalize abbreviations and formatting.
+
+### FedEx
+- Provides detailed validation messages.
+- May classify an address as residential or commercial.
+
+### UPS
+- Uses stricter validation rules for some addresses.
+- May require more complete postal information in edge cases.
+
+---
+
+## Summary
+
+Shipstack's address validation system provides:
+
+- A unified request format
+- A normalized top-level result
+- Optional corrected address data
+- Carrier-specific messages when available
+- Compatibility with both stateful and functional APIs
+
+---

package/docs/architecture.md

@@ -0,0 +1,220 @@
+# Shipstack Architecture
+
+Shipstack is built around a layered, modular architecture designed for reliability, type‑safety, and framework‑agnostic operation.  
+This document explains how the system is structured internally and how each layer interacts with the others.
+
+---
+
+## Overview
+
+Shipstack consists of four major layers:
+
+1. **Generated Clients** (OpenAPI‑based, carrier‑specific)  
+2. **API Layer** (request builders + converters)  
+3. **Aggregators** (unified workflows)  
+4. **Public API** (stateful + functional interfaces)
+
+This structure ensures:
+
+- Strong type‑safety  
+- Predictable behavior  
+- Easy extensibility  
+- Clear separation of concerns  
+- Zero framework assumptions  
+
+---
+
+## 1. Generated Clients
+
+Location:  
+```
+src/usps/generated/
+src/fedex/generated/
+src/ups/generated/
+```
+
+These clients are auto‑generated from official OpenAPI specifications.
+
+### Responsibilities
+
+- Define raw request/response types  
+- Handle low‑level HTTP calls  
+- Match carrier API behavior exactly  
+- Never contain business logic  
+
+### Notes
+
+- These files should never be edited manually.  
+- Regenerate using `npm run generate:*`.
+
+---
+
+## 2. API Layer
+
+Location:  
+```
+src/usps/
+src/fedex/
+src/ups/
+src/api/
+```
+
+This layer wraps the generated clients and provides:
+
+### Request Builders
+Convert normalized Shipstack requests into carrier‑specific formats.
+
+Examples:
+- `buildUspsRateRequest`
+- `buildFedexShipRequest`
+- `buildUpsTrackingRequest`
+
+### Converters
+Normalize carrier responses into Shipstack’s unified types.
+
+Examples:
+- `convertUspsRateResponse`
+- `convertFedexTrackingResponse`
+- `convertUpsShipResponse`
+
+### Responsibilities
+
+- Authentication  
+- Request shaping  
+- Response normalization  
+- Error mapping  
+- Carrier‑specific quirks  
+
+This layer ensures all carriers behave consistently from the outside.
+
+---
+
+## 3. Aggregators
+
+Location:  
+```
+src/aggregator/
+```
+
+Aggregators orchestrate multi‑step workflows and unify behavior across carriers.
+
+### Types of Aggregators
+
+#### Address Aggregator
+- Calls the correct carrier validation API  
+- Normalizes results  
+- Handles corrections and messages  
+
+#### Rates Aggregator
+- Calls the correct carrier rate API  
+- Normalizes rates  
+- Supports ranking helpers  
+
+#### Tracking Aggregator
+- Handles batching (USPS 35, FedEx 30)  
+- Handles UPS single‑inquiry limits  
+- Normalizes tracking events  
+
+#### Shipment Aggregator
+- **Staged mode** → builds carrier payloads  
+- **Actual mode** → purchases labels  
+- Normalizes shipment results  
+
+### Responsibilities
+
+- Multi‑carrier orchestration  
+- Concurrency control  
+- Error handling  
+- Workflow consistency  
+
+Aggregators are the “brains” of Shipstack.
+
+---
+
+## 4. Public API
+
+Shipstack exposes two public interfaces:
+
+### Stateful API
+
+```ts
+const client = new ShippingClient(config);
+const manager = new ShippingManager(config);
+
+client.getRates(...)
+client.track(...)
+client.buildShipment(...)
+client.createShipment(...)
+manager.getRankedRates(...)
+```
+
+### Functional API
+
+```ts
+getRates(request, config)
+validateAddress(request, config)
+trackShipment(numbers, carrier, config)
+buildShipment(request, config)
+createShipment(request, config)
+```
+
+Both APIs call into the same aggregator layer.
+
+---
+
+## Data Flow
+
+Here’s how a typical request moves through the system:
+
+```
+User Request
+   ↓
+Public API (stateful or functional)
+   ↓
+Aggregator (rates, tracking, address, shipment)
+   ↓
+API Layer (request builder + converter)
+   ↓
+Generated Client (raw HTTP)
+   ↓
+Carrier API (USPS/FedEx/UPS)
+   ↓
+Response normalized and returned
+```
+
+---
+
+## Why This Architecture?
+
+### Predictability
+Every carrier behaves differently — Shipstack makes them behave the same.
+
+### Extensibility
+Adding a new carrier only requires:
+- Generated client  
+- Request builders  
+- Converters  
+- Aggregator hooks  
+
+### Safety
+Staged shipments allow safe, frontend‑compatible workflows.
+
+### Performance
+Batching, concurrency limits, and request shaping ensure efficient API usage.
+
+### Portability
+No reliance on Node.js APIs — works in any JS runtime.
+
+---
+
+## Summary
+
+Shipstack’s architecture provides:
+
+- A clean separation between raw carrier APIs and normalized workflows  
+- A consistent developer experience across USPS, FedEx, and UPS  
+- Safe and advanced shipment modes  
+- Strong type‑safety at every layer  
+- A runtime‑agnostic design suitable for modern web platforms  
+
+---

package/docs/carriers.md

@@ -0,0 +1,180 @@
+# Carrier‑Specific Behavior in Shipstack
+
+Shipstack provides a unified API across USPS, FedEx, and UPS — but each carrier has unique rules, quirks, and constraints.  
+This document explains those differences and how Shipstack handles them internally.
+
+---
+
+# Overview
+
+Shipstack normalizes:
+
+- Rate structures  
+- Tracking events  
+- Address validation responses  
+- Shipment payloads  
+- Error formats  
+
+But each carrier still has its own behaviors that developers should understand.
+
+This guide covers:
+
+- USPS  
+- FedEx  
+- UPS  
+- How Shipstack smooths out inconsistencies  
+
+---
+
+# USPS
+
+USPS is the most rigid and rule‑driven carrier.  
+It has strict formatting requirements and limited metadata in some APIs.
+
+## Strengths
+
+- Excellent address correction  
+- Fast, lightweight APIs  
+- Strong support for small parcels  
+- Predictable service codes  
+
+## Limitations
+
+- Tracking events may lack timestamps  
+- Delivery estimates are not always provided  
+- Bulk tracking limit: **35 items**  
+- Some services ignore dimensions  
+
+## Shipstack Behavior
+
+- Automatically chunks tracking requests into 35‑item batches  
+- Normalizes missing timestamps to `null`  
+- Maps USPS service names to consistent `serviceCode` values  
+- Normalizes address corrections into a unified structure  
+
+---
+
+# FedEx
+
+FedEx provides the richest data across all carriers, especially for tracking and shipments.
+
+## Strengths
+
+- Detailed tracking events  
+- Reliable delivery estimates  
+- Strong international support  
+- Rich shipment metadata  
+
+## Limitations
+
+- Requires `accountNumber` for almost all operations  
+- Rate requests may require dimensions even for small parcels  
+- Tracking batch limit: **30 items**  
+
+## Shipstack Behavior
+
+- Automatically chunks tracking requests into 30‑item batches  
+- Normalizes FedEx’s verbose response structure  
+- Maps FedEx service codes to unified names  
+- Converts FedEx timestamps into ISO strings  
+
+---
+
+# UPS
+
+UPS is the strictest carrier in terms of authentication and rate limiting.
+
+## Strengths
+
+- Reliable tracking  
+- Strong commercial shipping support  
+- Good dimensional pricing  
+
+## Limitations
+
+- Tracking is **single‑inquiry only**  
+- Aggressive rate limiting  
+- Requires `accountNumber` for most services  
+- OAuth tokens expire quickly  
+
+## Shipstack Behavior
+
+- Automatically throttles UPS tracking to avoid lockouts  
+- Ensures single‑inquiry tracking is respected  
+- Normalizes UPS’s deeply nested response structure  
+- Converts UPS error codes into `ShipstackError`  
+
+---
+
+# Comparison Table
+
+| Feature | USPS | FedEx | UPS |
+|--------|------|--------|------|
+| Tracking batch size | 35 | 30 | 1 |
+| Address correction | Strong | Moderate | Moderate |
+| Delivery estimates | Inconsistent | Strong | Strong |
+| Requires account number | No | Yes | Yes |
+| Rate limiting | Low | Moderate | High |
+| International support | Limited | Strong | Strong |
+
+---
+
+# How Shipstack Normalizes Carrier Differences
+
+Shipstack smooths out inconsistencies by:
+
+### 1. Normalizing Field Names  
+All carriers return:
+
+- `serviceCode`  
+- `serviceName`  
+- `deliveryDays`  
+- `cost.amount`  
+- `cost.currency`  
+
+### 2. Normalizing Tracking Events  
+Regardless of carrier, tracking events become:
+
+```ts
+{
+  description: string;
+  dateTime: string;
+  city?: string;
+  stateOrProvinceCode?: string;
+  postalCode?: string;
+  countryCode?: string;
+}
+```
+
+### 3. Handling Concurrency and Batching  
+Shipstack automatically:
+
+- Chunks USPS and FedEx tracking  
+- Throttles UPS tracking  
+- Ensures safe parallel execution  
+
+### 4. Mapping Errors  
+All carrier errors become `ShipstackError` with:
+
+- `carrier`  
+- `message`  
+- `cause`  
+
+### 5. Unifying Shipment Workflows  
+Both staged and actual shipments use the same request structure, regardless of carrier.
+
+---
+
+# Summary
+
+Shipstack abstracts away the differences between USPS, FedEx, and UPS by:
+
+- Normalizing data  
+- Handling batching and throttling  
+- Mapping errors  
+- Providing consistent request/response structures  
+- Supporting both staged and actual shipments  
+
+This allows you to build multi‑carrier workflows without worrying about carrier‑specific quirks.
+
+---

package/docs/config.example.ts

@@ -0,0 +1,32 @@
+import type { ShippingConfig } from "@teralabs/shipstack";
+
+/**
+ * Shipstack Example Configuration
+ *
+ * This file demonstrates the configuration structure required
+ * for USPS, FedEx, and UPS. All values shown here are placeholders.
+ */
+
+export const config: ShippingConfig = {
+  environment: "sandbox",
+  usps: {
+    enabled: true,
+    clientId: "YOUR_USPS_CLIENT_ID",
+    clientSecret: "YOUR_USPS_CLIENT_SECRET",
+    baseUrl: "https://sandbox.api.usps.com"
+  },
+
+  fedex: {
+    enabled: true,
+    clientId: "YOUR_FEDEX_CLIENT_ID",
+    clientSecret: "YOUR_FEDEX_CLIENT_SECRET",
+    accountNumber: "YOUR_FEDEX_ACCOUNT_NUMBER"
+  },
+
+  ups: {
+    enabled: true,
+    clientId: "YOUR_UPS_CLIENT_ID",
+    clientSecret: "YOUR_UPS_CLIENT_SECRET",
+    accountNumber: "YOUR_UPS_ACCOUNT_NUMBER"
+  }
+};