CyberShip Carrier Service

CyberShip is a carrier-agnostic shipping rate aggregation library I built in TypeScript. The core idea is simple: every shipping carrier has a different API format, authentication method, and pricing model. CyberShip normalises all of them behind a single interface so consuming applications can query rates from any carrier with one function call.

The architecture uses the Adapter pattern with a CarrierRegistry. Each carrier implements a Carrier interface with a getRates method that takes a standardised RateRequest and returns RateQuote objects. The registry stores carriers by code in a Map, and the ShippingService orchestrates queries.

The UPS integration is the most complete adapter. Authentication uses OAuth 2.0 client-credentials flow with smart token caching. Tokens get cached in memory with a 60-second expiry buffer, so the system refreshes tokens before they expire rather than after a 401 response. The UpsMapper handles shape translation: converting RateRequest objects into UPS-specific payloads and mapping UPS responses back to normalised RateQuote objects, including unit conversions between imperial (IN/LBS) and metric (CM/KG).

The HttpClient wraps Node.js fetch with timeout handling via AbortController, JSON parsing with error recovery, form-encoded body support for OAuth, and consistent error mapping to a typed CarrierError with codes like AUTH_FAILED, RATE_LIMIT, TIMEOUT, and MALFORMED_RESPONSE.

The ShippingService exposes two methods: getRates for a single carrier, and getRatesFromAll that queries every registered carrier in parallel using Promise.allSettled. This means one carrier failing does not block results from others.

Validation uses Zod schemas on every input. The RateRequestSchema validates origin and destination addresses, and the PackageSchema validates dimensions and weight with unit enums. Invalid requests fail fast with clear error messages before any API call is made.

Tests use Vitest with nock for HTTP mocking. Every carrier interaction, token refresh, error path, and validation rule is covered.