Documentation

type Provider = "easypost" | "shippo" | "shipengine";

interface RateShipOptions {
  providers: ProviderAdapter[];
}

interface ProviderAdapter {
  readonly name: Provider;
  getRates(request: RateRequest): Promise<NormalizedRate[]>;
  createLabel(rate: NormalizedRate): Promise<Label>;
  verifyWebhook(
    rawBody: string | Buffer,
    signature: string,
    secret: string,
  ): NormalizedEvent;
}

interface EasyPostOptions {
  apiKey: string;
  baseUrl?: string;
  timeoutMs?: number;
}

interface ShippoOptions {
  apiKey: string;
  baseUrl?: string;
  timeoutMs?: number;
}

interface ShipEngineOptions {
  apiKey: string;
  baseUrl?: string;
  timeoutMs?: number;
}

interface Address {
  name: string;
  street1: string;
  street2?: string;
  city: string;
  state: string;
  zip: string;
  country: "US";               // v2.0 locked to US; widens in v2.1+
  phone?: string;
  email?: string;
}

interface Parcel {
  weight: number;
  weight_unit: "lb" | "oz";
  length: number;
  width: number;
  height: number;
  distance_unit: "in";
}

interface RateRequest {
  from: Address;
  to: Address;
  parcel: Parcel;
}

interface NormalizedRate {
  provider: Provider;
  carrier: string;
  service: string;
  price_cents: number;
  currency: "USD";
  estimated_days: number | null;
  estimated_delivery: string | null;
  rate_id: string;
  raw: object;
}

interface ProviderError {
  provider: Provider;
  code: ErrorCode;
  message: string;
}

interface RatesResponse {
  rates: NormalizedRate[];
  errors: ProviderError[];
}

interface Label {
  provider: Provider;
  carrier: string;
  service: string;
  price_cents: number;
  currency: "USD";
  tracking_number: string;
  label_url: string;
  label_id: string;
  rate_id: string;
  created_at: string;
  raw: object;
}

interface WebhookVerifyInput {
  provider: Provider;
  rawBody: string | Buffer;
  signature: string;
  secret: string;
}

type TrackingStatus =
  | "pre_transit"
  | "in_transit"
  | "out_for_delivery"
  | "failure"
  | "unknown";

interface EventLocation {
  city?: string;
  state?: string;
  zip?: string;
  country?: string;
}

interface TrackingUpdatedEvent {
  type: "tracking.updated";
  provider: Provider;
  tracking_number: string;
  carrier: string;
  status: TrackingStatus;
  status_detail?: string;
  location?: EventLocation;
  estimated_delivery?: string;
  occurred_at: string;
  raw: object;
}

interface TrackingDeliveredEvent {
  type: "tracking.delivered";
  provider: Provider;
  tracking_number: string;
  carrier: string;
  delivered_at: string;
  location?: EventLocation;
  signed_by?: string;
  raw: object;
}

type NormalizedEvent = TrackingUpdatedEvent | TrackingDeliveredEvent;

type ErrorCode =
  | "AUTH_FAILED"
  | "TIMEOUT"
  | "PROVIDER_ERROR"
  | "NETWORK_ERROR"
  | "VALIDATION_ERROR"
  | "CONFIGURATION_ERROR"
  | "WEBHOOK_VERIFICATION_FAILED"
  | "UNKNOWN";

interface RateShipErrorOptions {
  provider?: Provider;
  cause?: unknown;
}

class RateShipError extends Error {
  readonly code: ErrorCode;
  readonly provider?: Provider;
  readonly cause?: unknown;
}

class WebhookVerificationError extends RateShipError {
  // code is always "WEBHOOK_VERIFICATION_FAILED"
}

type Provider = "easypost" | "shippo" | "shipengine";

interface RateShipOptions {
  providers: ProviderAdapter[];
}

interface ProviderAdapter {
  readonly name: Provider;
  getRates(request: RateRequest): Promise<NormalizedRate[]>;
  createLabel(rate: NormalizedRate): Promise<Label>;
  verifyWebhook(
    rawBody: string | Buffer,
    signature: string,
    secret: string,
  ): NormalizedEvent;
}

interface EasyPostOptions {
  apiKey: string;
  baseUrl?: string;
  timeoutMs?: number;
}

interface ShippoOptions {
  apiKey: string;
  baseUrl?: string;
  timeoutMs?: number;
}

interface ShipEngineOptions {
  apiKey: string;
  baseUrl?: string;
  timeoutMs?: number;
}

interface Address {
  name: string;
  street1: string;
  street2?: string;
  city: string;
  state: string;
  zip: string;
  country: "US";               // v2.0 locked to US; widens in v2.1+
  phone?: string;
  email?: string;
}

interface Parcel {
  weight: number;
  weight_unit: "lb" | "oz";
  length: number;
  width: number;
  height: number;
  distance_unit: "in";
}

interface RateRequest {
  from: Address;
  to: Address;
  parcel: Parcel;
}

interface NormalizedRate {
  provider: Provider;
  carrier: string;
  service: string;
  price_cents: number;
  currency: "USD";
  estimated_days: number | null;
  estimated_delivery: string | null;
  rate_id: string;
  raw: object;
}

interface ProviderError {
  provider: Provider;
  code: ErrorCode;
  message: string;
}

interface RatesResponse {
  rates: NormalizedRate[];
  errors: ProviderError[];
}

interface Label {
  provider: Provider;
  carrier: string;
  service: string;
  price_cents: number;
  currency: "USD";
  tracking_number: string;
  label_url: string;
  label_id: string;
  rate_id: string;
  created_at: string;
  raw: object;
}

interface WebhookVerifyInput {
  provider: Provider;
  rawBody: string | Buffer;
  signature: string;
  secret: string;
}

type TrackingStatus =
  | "pre_transit"
  | "in_transit"
  | "out_for_delivery"
  | "failure"
  | "unknown";

interface EventLocation {
  city?: string;
  state?: string;
  zip?: string;
  country?: string;
}

interface TrackingUpdatedEvent {
  type: "tracking.updated";
  provider: Provider;
  tracking_number: string;
  carrier: string;
  status: TrackingStatus;
  status_detail?: string;
  location?: EventLocation;
  estimated_delivery?: string;
  occurred_at: string;
  raw: object;
}

interface TrackingDeliveredEvent {
  type: "tracking.delivered";
  provider: Provider;
  tracking_number: string;
  carrier: string;
  delivered_at: string;
  location?: EventLocation;
  signed_by?: string;
  raw: object;
}

type NormalizedEvent = TrackingUpdatedEvent | TrackingDeliveredEvent;

type ErrorCode =
  | "AUTH_FAILED"
  | "TIMEOUT"
  | "PROVIDER_ERROR"
  | "NETWORK_ERROR"
  | "VALIDATION_ERROR"
  | "CONFIGURATION_ERROR"
  | "WEBHOOK_VERIFICATION_FAILED"
  | "UNKNOWN";

interface RateShipErrorOptions {
  provider?: Provider;
  cause?: unknown;
}

class RateShipError extends Error {
  readonly code: ErrorCode;
  readonly provider?: Provider;
  readonly cause?: unknown;
}

class WebhookVerificationError extends RateShipError {
  // code is always "WEBHOOK_VERIFICATION_FAILED"
}