@teralabs/shipstack 1.2.0

package/docs/errors.md

@@ -0,0 +1,150 @@
+# Error Handling in Shipstack
+
+Shipstack provides a unified, predictable error-handling system across USPS, FedEx, and UPS.  
+All Shipstack-specific errors extend from `ShipstackError`.
+
+---
+
+## Overview
+
+Shipstack errors fall into two main categories:
+
+1. **ShipstackError** for normalized library failures
+2. **ThrottlingError** when a carrier enforces rate limits
+
+Carrier-specific details are preserved on the error's `cause` property when available.
+
+---
+
+## Base Error: `ShipstackError`
+
+```ts
+class ShipstackError extends Error {
+  carrier: "usps" | "fedex" | "ups";
+  cause?: unknown;
+}
+```
+
+### Fields
+
+| Field | Description |
+|-------|-------------|
+| `message` | Human-readable error message |
+| `carrier` | The carrier associated with the failure |
+| `cause` | Raw upstream error, response, or context when available |
+
+---
+
+## Example: Catching Errors
+
+```ts
+try {
+  await client.getRates(request);
+} catch (err) {
+  if (err instanceof ShipstackError) {
+    console.error("Carrier:", err.carrier);
+    console.error("Message:", err.message);
+    console.error("Cause:", err.cause);
+  }
+}
+```
+
+---
+
+## `ThrottlingError`
+
+UPS and FedEx may enforce rate limits. Shipstack throws a `ThrottlingError` when this happens.
+
+```ts
+class ThrottlingError extends ShipstackError {
+  retryAfter?: number;
+}
+```
+
+### When It Occurs
+
+- Too many UPS tracking requests in a short period
+- FedEx rate-limit enforcement
+- Carrier-side retry-after signals
+
+### Example
+
+```ts
+try {
+  await trackShipment(numbers, "ups", config);
+} catch (err) {
+  if (err instanceof ThrottlingError) {
+    console.log("Carrier is rate limiting. Retry after:", err.retryAfter);
+  }
+}
+```
+
+---
+
+## Error Behavior by Workflow
+
+### Rates
+
+- Missing or invalid ZIP codes
+- Unsupported service combinations
+- Carrier downtime
+
+### Tracking
+
+- Invalid tracking numbers
+- Carrier throttling
+- Upstream authentication or network failures
+
+### Address Validation
+
+- Missing required fields
+- Invalid postal codes
+- Ambiguous addresses
+
+### Shipments
+
+#### Staged Shipments
+Errors occur only if request data is incomplete or invalid.
+
+#### Actual Shipments
+Errors may occur due to authentication failures, invalid shipment payloads, carrier downtime, or billing issues.
+
+---
+
+## Best Practices
+
+### Always Catch `ShipstackError`
+
+```ts
+try {
+  await createShipment(request, config);
+} catch (err) {
+  if (err instanceof ShipstackError) {
+    // handle gracefully
+  }
+}
+```
+
+### Log `carrier` and `cause`
+
+These are the most useful fields for debugging carrier-specific failures.
+
+### Do Not Expose Raw Upstream Errors to End Users
+Prefer logging `cause` internally and returning a safe application-level message to the frontend.
+
+Use `message` for user‑facing output.  
+Use `cause` for internal logging.
+
+---
+
+## Summary
+
+Shipstack’s error system provides:
+
+- A unified error interface  
+- Normalized carrier errors  
+- Specialized throttling detection  
+- Consistent behavior across all workflows  
+- Strong typing for safe error handling  
+
+---

package/docs/examples/actual-shipment.ts

@@ -0,0 +1,59 @@
+/**
+ * Actual Shipment Example
+ *
+ * Demonstrates how to use Shipstack's advanced shipment workflow.
+ * This calls the carrier API and PURCHASES a real shipping label.
+ *
+ * IMPORTANT:
+ * - Only run this in a secure backend environment.
+ * - This will generate a real tracking number and label.
+ */
+
+import { createShipment } from "@teralabs/shipstack";
+import { config } from "../config.example";
+
+async function exampleActualShipment() {
+  const shipment = await createShipment(
+    {
+      carrier: "ups",
+      serviceCode: "UPS_GROUND",
+
+      fromAddress: {
+        name: "Sender Name",
+        streetLines: ["123 Warehouse Rd"],
+        city: "Los Angeles",
+        stateOrProvinceCode: "CA",
+        postalCode: "90001",
+        countryCode: "US"
+      },
+
+      toAddress: {
+        name: "Customer Name",
+        streetLines: ["55 W 46th St"],
+        city: "New York",
+        stateOrProvinceCode: "NY",
+        postalCode: "10036",
+        countryCode: "US"
+      },
+
+      package: {
+        weightOz: 48,
+        lengthInches: 14,
+        widthInches: 10,
+        heightInches: 6
+      }
+    },
+    config
+  );
+
+  console.log("Carrier:", shipment.carrier);
+  console.log("Tracking Number:", shipment.trackingNumber);
+  console.log("Service Code:", shipment.serviceCode);
+  console.log("Charges:", shipment.charges);
+
+  // Label is returned as base64
+  console.log("Label Format:", shipment.label.format);
+  console.log("Label Base64 (first 100 chars):", shipment.label.base64.slice(0, 100));
+}
+
+exampleActualShipment();

package/docs/examples/basic.ts

@@ -0,0 +1,131 @@
+/**
+ * Basic Shipstack Examples
+ *
+ * Demonstrates:
+ * - Fetching rates
+ * - Ranking rates across carriers
+ * - Tracking shipments
+ * - Validating addresses
+ * - Using ShippingClient, ShippingManager, and the functional API
+ */
+
+import {
+  ShippingClient,
+  ShippingManager,
+  getRates,
+  trackShipment,
+  validateAddress
+} from "@teralabs/shipstack";
+
+import { config } from "../config.example";
+
+// ---------------------------------------------
+// Stateful API (ShippingClient + ShippingManager)
+// ---------------------------------------------
+
+const client = new ShippingClient(config);
+const manager = new ShippingManager(config);
+
+async function exampleStateful() {
+  // 1. Get Rates
+  const rates = await client.getRates({
+    carrier: "usps",
+    originZip: "90210",
+    destZip: "10001",
+    weightOz: 16,
+    lengthInches: 10,
+    widthInches: 5,
+    heightInches: 5
+  });
+
+  console.log("USPS Rates:", rates);
+
+  // 2. Rank Rates Across Carriers
+  const rankedRates = await manager.getRankedRates(
+    {
+      originZip: "90210",
+      destZip: "10001",
+      weightOz: 16,
+      lengthInches: 10,
+      widthInches: 5,
+      heightInches: 5
+    },
+    ["usps", "fedex", "ups"]
+  );
+
+  console.log("Ranked Rates:", rankedRates);
+
+  // 3. Track a Shipment
+  const tracking = await client.track(
+    ["9400100000000000000000"],
+    "usps"
+  );
+
+  console.log("Tracking:", tracking);
+
+  // 4. Validate an Address
+  const address = await client.validateAddress({
+    carrier: "fedex",
+    address: {
+      streetLines: ["123 Main St"],
+      city: "New York",
+      stateOrProvinceCode: "NY",
+      postalCode: "10001",
+      countryCode: "US"
+    }
+  });
+
+  console.log("Address Validation:", address);
+}
+
+// ---------------------------------------------
+// Functional API
+// ---------------------------------------------
+
+async function exampleFunctional() {
+  // 1. Get Rates
+  const rates = await getRates(
+    {
+      carrier: "ups",
+      originZip: "94103",
+      destZip: "10001",
+      weightOz: 32,
+      lengthInches: 12,
+      widthInches: 8,
+      heightInches: 6
+    },
+    config
+  );
+
+  console.log("UPS Rates:", rates);
+
+  // 2. Track a Shipment
+  const tracking = await trackShipment(
+    ["1Z9999999999999999"],
+    "ups",
+    config
+  );
+
+  console.log("Tracking:", tracking);
+
+  // 3. Validate an Address
+  const address = await validateAddress(
+    {
+      carrier: "usps",
+      address: {
+        streetLines: ["1600 Amphitheatre Pkwy"],
+        city: "Mountain View",
+        stateOrProvinceCode: "CA",
+        postalCode: "94043",
+        countryCode: "US"
+      }
+    },
+    config
+  );
+
+  console.log("Address Validation:", address);
+}
+
+// Run examples
+exampleStateful();
+exampleFunctional();

package/docs/examples/nextjs-route.ts

@@ -0,0 +1,22 @@
+import { getRates, type RateRequest } from "@teralabs/shipstack";
+
+import { config } from "../config.example";
+
+export async function POST(request: Request) {
+	const body = (await request.json()) as Partial<RateRequest>;
+
+	const rateRequest: RateRequest = {
+		carrier: body.carrier ?? "usps",
+		originZip: body.originZip ?? "90210",
+		destZip: body.destZip ?? "10001",
+		weightOz: body.weightOz ?? 16,
+		lengthInches: body.lengthInches ?? 10,
+		widthInches: body.widthInches ?? 5,
+		heightInches: body.heightInches ?? 5,
+		destCountryCode: body.destCountryCode
+	};
+
+	const rates = await getRates(rateRequest, config);
+
+	return Response.json({ rates });
+}

package/docs/examples/staged-shipment.md

@@ -0,0 +1,46 @@
+# Staged Shipment Example
+
+This example demonstrates Shipstack's safe shipment builder. It generates a carrier-specific payload without purchasing a label.
+
+```ts
+import { buildShipment } from "@teralabs/shipstack";
+import { config } from "../config.example";
+
+async function exampleStagedShipment() {
+  const staged = await buildShipment(
+    {
+      carrier: "fedex",
+      serviceCode: "FEDEX_GROUND",
+      fromAddress: {
+        name: "Sender Name",
+        streetLines: ["123 Warehouse Rd"],
+        city: "Los Angeles",
+        stateOrProvinceCode: "CA",
+        postalCode: "90001",
+        countryCode: "US"
+      },
+      toAddress: {
+        name: "Customer Name",
+        streetLines: ["55 W 46th St"],
+        city: "New York",
+        stateOrProvinceCode: "NY",
+        postalCode: "10036",
+        countryCode: "US"
+      },
+      package: {
+        weightOz: 32,
+        lengthInches: 12,
+        widthInches: 8,
+        heightInches: 4
+      }
+    },
+    config
+  );
+
+  console.log("Carrier:", staged.carrier);
+  console.log("Service Code:", staged.serviceCode);
+  console.log("Payload:", staged.payload);
+}
+
+exampleStagedShipment();
+```

package/docs/index.md

@@ -0,0 +1,286 @@
+# Shipstack Documentation
+
+Welcome to Shipstack. This documentation will help you get started, integrate, and extend Shipstack in any JavaScript or TypeScript environment.
+
+---
+
+## Table of Contents
+- [What is Shipstack?](#what-is-shipstack)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Usage Examples](#usage-examples)
+- [Advanced Workflows](#advanced-workflows)
+- [Error Handling](#error-handling)
+- [API Reference](#api-reference)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+- [License](#license)
+
+---
+
+## What is Shipstack?
+
+Shipstack is a high‑performance, type‑safe, and framework‑agnostic shipping SDK for orchestrating logistics across USPS, FedEx, and UPS.  
+It provides a unified API for:
+
+- Address validation  
+- Rate comparison  
+- Tracking  
+- Staged shipment generation  
+- Actual label creation (backend‑only)
+
+Shipstack works in Node.js, Deno, Bun, Cloudflare Workers, and any modern JavaScript runtime.
+
+---
+
+## Features
+
+- Unified orchestration for USPS, FedEx, and UPS  
+- Standardized data models for rates, tracking, and addresses  
+- Batch tracking with automatic carrier‑specific chunking  
+- Staged shipment system for safe, frontend‑compatible workflows  
+- Actual shipment creation for backend automation  
+- Auto‑generated OpenAPI clients for accuracy and compliance  
+- Fully framework‑agnostic and open source  
+
+---
+
+## Installation
+
+```bash
+npm install @teralabs/shipstack
+```
+
+---
+
+## Quick Start
+
+```ts
+import { ShippingClient, ShippingManager } from "@teralabs/shipstack";
+
+const config = {
+  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"
+  }
+};
+
+const client = new ShippingClient(config);
+const manager = new ShippingManager(config);
+```
+
+---
+
+## Configuration
+
+Shipstack does not rely on environment variables.  
+All configuration is passed as plain objects.
+
+See `docs/config.example.ts` for a complete template.
+
+---
+
+## Usage Examples
+
+### Get Rates
+
+```ts
+const rates = await client.getRates({
+  carrier: "usps",
+  originZip: "90210",
+  destZip: "10001",
+  weightOz: 16,
+  lengthInches: 10,
+  widthInches: 5,
+  heightInches: 5
+});
+```
+
+### Rank Rates Across Carriers
+
+```ts
+const rankedRates = await manager.getRankedRates(
+  {
+    originZip: "90210",
+    destZip: "10001",
+    weightOz: 16,
+    lengthInches: 10,
+    widthInches: 5,
+    heightInches: 5
+  },
+  ["usps", "fedex", "ups"]
+);
+```
+
+### Track Shipments
+
+```ts
+const tracking = await client.track(["9400100000000000000000"], "usps");
+```
+
+### Validate Address
+
+```ts
+const result = await client.validateAddress({
+  carrier: "fedex",
+  address: {
+    streetLines: ["123 Main St"],
+    city: "New York",
+    stateOrProvinceCode: "NY",
+    postalCode: "10001",
+    countryCode: "US"
+  }
+});
+```
+
+### Direct Carrier Access
+
+```ts
+import { createUspsRatesClient } from "@teralabs/shipstack";
+
+const usps = createUspsRatesClient(config.usps);
+const raw = await usps.getRates({ ... });
+```
+
+---
+
+## Advanced Workflows
+
+### Functional API
+
+```ts
+import { getRates, validateAddress, trackShipment } from "@teralabs/shipstack";
+
+const rates = await getRates(
+  {
+    carrier: "usps",
+    originZip: "90210",
+    destZip: "10001",
+    weightOz: 16,
+    lengthInches: 10,
+    widthInches: 5,
+    heightInches: 5
+  },
+  config
+);
+```
+
+### ShippingManager
+
+`ShippingManager` is the class-only helper for ranked multi-carrier checkout workflows.
+
+```ts
+const ranked = await manager.getRankedRates(
+  {
+    originZip: "90210",
+    destZip: "10001",
+    weightOz: 16,
+    lengthInches: 10,
+    widthInches: 5,
+    heightInches: 5
+  },
+  ["usps", "fedex", "ups"]
+);
+```
+
+### Staged Shipments (Safe Mode)
+
+Generates a carrier‑specific payload without purchasing a label.
+
+```ts
+import { buildShipment } from "@teralabs/shipstack";
+
+const staged = await buildShipment({ /* ShipmentRequest */ }, config);
+```
+
+### Actual Shipments (Backend Only)
+
+Purchases a real label.
+
+```ts
+import { createShipment } from "@teralabs/shipstack";
+
+const shipment = await createShipment({ /* ShipmentRequest */ }, config);
+```
+
+---
+
+## Error Handling
+
+All errors are standardized as `ShipstackError`.
+
+```ts
+import { ShipstackError } from "@teralabs/shipstack";
+
+try {
+  await client.getRates({
+    carrier: "usps",
+    originZip: "90210",
+    destZip: "10001",
+    weightOz: 16,
+    lengthInches: 10,
+    widthInches: 5,
+    heightInches: 5
+  });
+} catch (error) {
+  if (error instanceof ShipstackError) {
+    // handle
+  }
+}
+```
+
+---
+
+## API Reference
+
+See `API.md` for detailed type and method documentation.
+
+---
+
+## Testing
+
+Shipstack uses Vitest for unit and integration tests.
+
+Run tests:
+
+```bash
+npm run test
+```
+
+---
+
+## Contributing
+
+See `CONTRIBUTING.md` for guidelines.
+
+---
+
+## Changelog
+
+See `CHANGELOG.md`.
+
+---
+
+## License
+
+ISC License
+
+---