@teralabs/shipstack 1.2.0

package/docs/rates.md

@@ -0,0 +1,145 @@
+# Rates in Shipstack
+
+Shipstack provides a unified interface for fetching shipping rates from USPS, FedEx, and UPS.  
+All rate responses are normalized into a consistent structure, regardless of carrier-specific formats.
+
+---
+
+## Rate Request Structure
+
+```ts
+type RateRequest = {
+  carrier: "usps" | "fedex" | "ups";
+  originZip: string;
+  destZip: string;
+  weightOz: number;
+  lengthInches: number;
+  widthInches: number;
+  heightInches: number;
+  destCountryCode?: string;
+};
+```
+
+Carrier-specific optional fields such as `mailClass`, `pickupType`, `packagingType`, and `rateRequestType` are also supported when needed.
+
+---
+
+## Fetching Rates
+
+### Using `ShippingClient`
+
+```ts
+const rates = await client.getRates({
+  carrier: "usps",
+  originZip: "90210",
+  destZip: "10001",
+  weightOz: 16,
+  lengthInches: 10,
+  widthInches: 5,
+  heightInches: 5
+});
+```
+
+### Using the Functional API
+
+```ts
+import { getRates } from "@teralabs/shipstack";
+
+const rates = await getRates(request, config);
+```
+
+Both methods return the same normalized structure.
+
+---
+
+## Ranking Across Carriers
+
+Use `ShippingManager` when you want Shipstack to fetch from multiple carriers and rank the results for you.
+
+```ts
+const ranked = await manager.getRankedRates(
+  {
+    originZip: "90210",
+    destZip: "10001",
+    weightOz: 16,
+    lengthInches: 10,
+    widthInches: 5,
+    heightInches: 5
+  },
+  ["usps", "fedex", "ups"]
+);
+```
+
+---
+
+## Normalized Rate Structure
+
+```ts
+type NormalizedRate = {
+  carrier: "usps" | "fedex" | "ups";
+  serviceCode: string;
+  serviceName: string;
+  deliveryDays?: number;
+  estimatedArrival?: string;
+  isFastest?: boolean;
+  isCheapest?: boolean;
+  guaranteed?: boolean;
+  cost: {
+    amount: number;
+    currency: string;
+  };
+  raw?: unknown;
+};
+```
+
+### Field Notes
+
+- `deliveryDays` is optional when a carrier does not provide an estimate.
+- `estimatedArrival` is typically an ISO-8601 string when available.
+- `isCheapest` and `isFastest` are added by `ShippingManager#getRankedRates`.
+- `cost.amount` is always numeric.
+
+---
+
+## Best Value and Fastest Helpers
+
+These helpers work on a single-carrier `RateRequest`.
+
+```ts
+import { getBestValueRate, getFastestService } from "@teralabs/shipstack";
+
+const cheapest = await getBestValueRate(request, config);
+const fastest = await getFastestService(request, config);
+```
+
+Both helpers return `null` when no valid rates are available.
+
+---
+
+## Carrier-Specific Notes
+
+### USPS
+- Delivery estimates may be missing for some services.
+- USPS-specific flags such as `mailClass` and `nonStandard` are supported.
+
+### FedEx
+- Requires `accountNumber` in config.
+- Supports FedEx-specific options such as `pickupType`, `dropoffType`, and `rateRequestType`.
+
+### UPS
+- Requires `accountNumber` in config.
+- Dimensions are especially important for many UPS services.
+
+---
+
+## Summary
+
+Shipstack's rate system provides:
+
+- A unified request format
+- A normalized response structure
+- Single-carrier helper methods
+- Multi-carrier ranking through `ShippingManager`
+- Full support for USPS, FedEx, and UPS
+
+---

package/docs/shipments.md

@@ -0,0 +1,157 @@
+# Shipments in Shipstack
+
+Shipstack supports two distinct shipment workflows:
+
+1. **Staged Shipments (Safe Mode)**
+2. **Actual Shipments (Advanced Mode)**
+
+Understanding the difference is essential for building secure and flexible shipping systems.
+
+---
+
+## 1. Staged Shipments (Safe Mode)
+
+Staged shipments generate a **carrier-specific shipment payload** without calling the carrier API or purchasing a label.
+
+This mode is ideal for:
+
+- Storefronts
+- Serverless and edge environments
+- Email-based label workflows
+- Custom dashboards
+- Platforms where merchants finalize labels later
+- Any environment where you cannot expose carrier credentials
+
+### Example
+
+```ts
+import { buildShipment } from "@teralabs/shipstack";
+
+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(staged.payload);
+```
+
+### What Staged Shipments Provide
+
+```ts
+type StagedShipment = {
+  carrier: "usps" | "fedex" | "ups";
+  serviceCode: string;
+  payload: unknown;
+};
+```
+
+### What Staged Shipments Do Not Do
+
+- Do not call USPS, FedEx, or UPS
+- Do not purchase postage
+- Do not generate a label
+- Do not require backend security
+
+This makes staged shipments safe for any environment, including the browser.
+
+---
+
+## 2. Actual Shipments (Advanced Mode)
+
+Actual shipments call the carrier API and purchase a real label.  
+This workflow must only be used in secure backend environments.
+
+### Example
+
+```ts
+import { createShipment } from "@teralabs/shipstack";
+
+const shipment = await createShipment(request, config);
+
+console.log(shipment.label.base64);
+console.log(shipment.trackingNumber);
+```
+
+### What Actual Shipments Provide
+
+```ts
+type NormalizedShipment = {
+  carrier: "usps" | "fedex" | "ups";
+  trackingNumber: string;
+  serviceCode: string;
+  serviceName: string;
+  label: {
+    format: "PDF" | "PNG" | "ZPL" | "GIF";
+    base64: string;
+  };
+  charges?: {
+    amount: number;
+    currency: string;
+  };
+  raw?: unknown;
+};
+```
+
+### What Actual Shipments Require
+
+- Secure backend environment
+- Valid carrier credentials
+- Merchant authorization to purchase labels
+
+---
+
+## Safe vs Advanced Comparison
+
+| Feature | Staged (`buildShipment`) | Actual (`createShipment`) |
+|--------|---------------------------|---------------------------|
+| Generates carrier payload | Yes | Yes |
+| Purchases a label | No | Yes |
+| Safe for frontend | Yes | No |
+| Requires backend | No | Yes |
+| Calls carrier API | No | Yes |
+| Good for email workflows | Yes | Limited |
+| Good for automation | Limited | Yes |
+
+---
+
+## When to Use Each Mode
+
+### Use **Staged Shipments** when:
+- You want to preview or store the carrier payload
+- You want to send the payload to a merchant for approval
+- You are running in a serverless or edge environment
+- You want to avoid accidental label purchases
+- You are building a storefront or checkout flow
+
+### Use **Actual Shipments** when:
+- You are ready to purchase a label
+- You are running in a secure backend
+- You need a real tracking number and label file
+- You are automating fulfillment
+
+---

package/docs/tracking.md

@@ -0,0 +1,115 @@
+# Tracking in Shipstack
+
+Shipstack provides a unified tracking interface for USPS, FedEx, and UPS.  
+All tracking responses are normalized into a consistent structure, regardless of carrier-specific formats.
+
+---
+
+## Tracking Request
+
+```ts
+trackShipment(
+  trackingNumbers: string | string[],
+  carrier: "usps" | "fedex" | "ups",
+  config: ShippingConfig
+)
+```
+
+You may track one or many tracking numbers at once.
+
+---
+
+## Functional Example
+
+```ts
+import { trackShipment } from "@teralabs/shipstack";
+
+const tracking = await trackShipment(
+  ["9400100000000000000000"],
+  "usps",
+  config
+);
+
+console.log(tracking[0]?.status);
+```
+
+---
+
+## Using `ShippingClient`
+
+```ts
+const tracking = await client.track(["1Z9999999999999999"], "ups");
+```
+
+---
+
+## Normalized Tracking Structure
+
+```ts
+type NormalizedTracking = {
+  carrier: "usps" | "fedex" | "ups";
+  trackingNumber: string;
+  status: string;
+  estimatedDelivery?: string;
+  events: Array<{
+    description: string;
+    dateTime: string;
+    city?: string;
+    stateOrProvinceCode?: string;
+    postalCode?: string;
+    countryCode?: string;
+  }>;
+  raw?: unknown;
+};
+```
+
+### Field Notes
+
+- `status` is a normalized high-level tracking state such as `IN_TRANSIT` or `DELIVERED`.
+- `estimatedDelivery` is optional when the carrier provides an ETA.
+- `events` contain the normalized event history returned by the carrier.
+
+---
+
+## Carrier Batch Limits
+
+Shipstack automatically handles batching and concurrency rules:
+
+| Carrier | Limit | Behavior |
+|--------|--------|----------|
+| USPS | 35 per request | Automatically chunks requests |
+| FedEx | 30 per request | Automatically chunks requests |
+| UPS | Single-inquiry only | Concurrency-limited to avoid lockouts |
+
+You do not need to manually chunk tracking numbers. Shipstack handles it for you.
+
+---
+
+## Notes on Carrier Behavior
+
+### USPS
+- Bulk tracking supports up to 35 items.
+- Some events may not include a full timestamp.
+
+### FedEx
+- Provides detailed event history.
+- Supports up to 30 items per request.
+
+### UPS
+- Only supports single-inquiry tracking.
+- Too many rapid requests may trigger rate limiting.
+- Shipstack automatically throttles UPS tracking calls.
+
+---
+
+## Summary
+
+Shipstack's tracking system provides:
+
+- A unified request format
+- A normalized response structure
+- Automatic batching and concurrency control
+- Full support for USPS, FedEx, and UPS
+- Compatibility with both stateful and functional APIs
+
+---

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@teralabs/shipstack",
+  "version": "1.2.0",
+  "description": "Framework-agnostic, type-safe shipping SDK for USPS, FedEx, and UPS with unified orchestration and edge-ready output.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.mjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Thecodergabe/shipstack.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Thecodergabe/shipstack/issues"
+  },
+  "homepage": "https://github.com/Thecodergabe/shipstack#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "docs"
+  ],
+  "keywords": [
+    "shipping",
+    "usps",
+    "fedex",
+    "ups",
+    "logistics",
+    "api",
+    "openapi",
+    "typescript",
+    "framework-agnostic",
+    "serverless"
+  ],
+  "author": "Gabriel Rodriguez",
+  "license": "ISC",
+  "packageManager": "npm@10.0.0",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/Thecodergabe"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "scripts": {
+    "/* --- Build and Lifecycle --- */": "",
+    "prepare": "npm run build",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "example:server": "npm run build && node examples/shipstack-ui/server.mjs",
+    "example:ui": "npm --prefix examples/shipstack-ui run dev",
+    "prepublishOnly": "npm run test && npm run build",
+    "/* --- Core USPS Generation --- */": "",
+    "generate:usps:auth": "openapi --input https://developers.usps.com/sites/default/files/apidoc_specs/oauth2_3_update.yaml --output src/usps/auth/generated --client fetch --name UspsAuthSdk",
+    "generate:usps:rates": "openapi --input https://developers.usps.com/sites/default/files/apidoc_specs/domestic-prices_10.yaml --output src/usps/rates/generated --client fetch --name UspsRatesSdk",
+    "generate:usps:address": "openapi --input https://developers.usps.com/sites/default/files/apidoc_specs/addresses-v3r2_2.yaml --output src/usps/address/generated --client fetch --name UspsAddressSdk",
+    "generate:usps:labels": "openapi --input https://developers.usps.com/sites/default/files/apidoc_specs/labels_update_1.yaml --output src/usps/labels/generated --client fetch --name UspsLabelsSdk",
+    "generate:usps:tracking": "openapi --input https://developers.usps.com/sites/default/files/apidoc_specs/tracking-v3r2_4.yaml --output src/usps/tracking/generated --client fetch --name UspsTrackingSdk",
+    "generate:usps:intl-rates": "openapi --input https://developers.usps.com/sites/default/files/apidoc_specs/international-prices_4.yaml --output src/usps/international/rates/generated --client fetch --name UspsIntlRatesSdk",
+    "generate:usps:intl-labels": "openapi --input https://developers.usps.com/sites/default/files/apidoc_specs/international-labels_8.yaml --output src/usps/international/labels/generated --client fetch --name UspsIntlLabelsSdk",
+    "generate:usps": "npm run generate:usps:auth && npm run generate:usps:rates && npm run generate:usps:address && npm run generate:usps:labels && npm run generate:usps:tracking && npm run generate:usps:intl-rates && npm run generate:usps:intl-labels",
+    "/* --- Core FedEx Generation --- */": "",
+    "generate:fedex:address": "openapi --input specs/fedex/address-validation.json --output src/fedex/address/generated --client fetch --name FedexAddressSdk",
+    "generate:fedex:rates": "openapi --input specs/fedex/rate.json --output src/fedex/rates/generated --client fetch --name FedexRatesSdk",
+    "generate:fedex:ship": "openapi --input specs/fedex/ship.json --output src/fedex/ship/generated --client fetch --name FedexShipSdk",
+    "generate:fedex:tracking": "openapi --input specs/fedex/track.json --output src/fedex/tracking/generated --client fetch --name FedexTrackingSdk",
+    "generate:fedex": "npm run generate:fedex:address && npm run generate:fedex:rates && npm run generate:fedex:ship && npm run generate:fedex:tracking",
+    "/* --- Core UPS Generation --- */": "",
+    "generate:ups:auth": "openapi --input specs/ups/OAuthClientCredentials-Ready.yaml --output src/ups/auth/generated --client fetch --name UpsAuthSdk",
+    "generate:ups:rates": "openapi --input specs/ups/Rating.yaml --output src/ups/rates/generated --client fetch --name UpsRatesSdk",
+    "generate:ups:ship": "openapi --input specs/ups/Shipping.yaml --output src/ups/ship/generated --client fetch --name UpsShipSdk",
+    "generate:ups:tracking": "openapi --input specs/ups/Tracking-Ready.yaml --output src/ups/tracking/generated --client fetch --name UpsTrackingSdk",
+    "generate:ups": "npm run generate:ups:auth && npm run generate:ups:rates && npm run generate:ups:ship && npm run generate:ups:tracking",
+    "/* --- Master Command --- */": "",
+    "generate:all": "npm run generate:usps && npm run generate:fedex && npm run generate:ups"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "openapi-typescript-codegen": "^0.29.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vite-tsconfig-paths": "^6.1.1",
+    "vitest": "^4.0.3"
+  },
+  "dependencies": {
+    "cross-fetch": "^4.1.0"
+  }
+}