Build a Shipping Rate Calculator

// src/shipping/calculator.ts — Multi-carrier rate shopping with dim weight and zone pricing
import { pool } from "../db";
import { Redis } from "ioredis";

const redis = new Redis(process.env.REDIS_URL!);

interface ShipmentRequest {
  origin: Address;
  destination: Address;
  packages: Package[];
  options: {
    signatureRequired: boolean;
    insurance: boolean;
    insuredValue: number;
    saturdayDelivery: boolean;
    residential: boolean;
  };
}

interface Address {
  name: string;
  street1: string;
  street2?: string;
  city: string;
  state: string;
  postalCode: string;
  country: string;             // ISO 2-letter
}

interface Package {
  weight: number;              // oz
  length: number;              // inches
  width: number;
  height: number;
  declaredValue: number;       // cents
}

interface ShippingRate {
  carrier: string;
  service: string;
  serviceCode: string;
  rate: number;                // cents
  currency: string;
  estimatedDays: number;
  deliveryDate: string | null;
  isGuaranteed: boolean;
  billedWeight: number;        // actual or dim, whichever is greater
  surcharges: Array<{ name: string; amount: number }>;
}

interface ShippingQuote {
  rates: ShippingRate[];
  cheapest: ShippingRate;
  fastest: ShippingRate;
  recommended: ShippingRate;
  cachedAt: string;
}

// Dimensional weight divisors (cubic inches / divisor = dim weight in lbs)
const DIM_DIVISORS: Record<string, number> = {
  ups: 139,
  fedex: 139,
  usps: 166,
  dhl: 139,
};

// Get rates from all carriers
export async function getRates(request: ShipmentRequest): Promise<ShippingQuote> {
  // Check cache (same route + weight combo)
  const cacheKey = buildCacheKey(request);
  const cached = await redis.get(cacheKey);
  if (cached) return JSON.parse(cached);

  // Calculate billed weights per carrier
  const billedWeights = calculateBilledWeights(request.packages);

  // Fetch rates from all carriers in parallel
  const [upsRates, fedexRates, uspsRates] = await Promise.all([
    fetchUPSRates(request, billedWeights.ups),
    fetchFedExRates(request, billedWeights.fedex),
    fetchUSPSRates(request, billedWeights.usps),
  ]);

  const allRates = [...upsRates, ...fedexRates, ...uspsRates]
    .filter((r) => r.rate > 0)
    .sort((a, b) => a.rate - b.rate);

  if (allRates.length === 0) {
    throw new Error("No shipping rates available for this route");
  }

  // Apply business rules
  const adjustedRates = applyShippingRules(allRates, request);

  const cheapest = adjustedRates[0];
  const fastest = [...adjustedRates].sort((a, b) => a.estimatedDays - b.estimatedDays)[0];

  // Recommended: best value (cheapest among fast options)
  const fastEnough = adjustedRates.filter((r) => r.estimatedDays <= 5);
  const recommended = fastEnough.length > 0 ? fastEnough[0] : cheapest;

  const quote: ShippingQuote = {
    rates: adjustedRates,
    cheapest, fastest, recommended,
    cachedAt: new Date().toISOString(),
  };

  // Cache for 15 minutes
  await redis.setex(cacheKey, 900, JSON.stringify(quote));

  return quote;
}

// Calculate dimensional weight for each carrier
function calculateBilledWeights(packages: Package[]): Record<string, number> {
  const result: Record<string, number> = {};

  for (const carrier of ["ups", "fedex", "usps"]) {
    let totalBilled = 0;

    for (const pkg of packages) {
      const actualWeight = pkg.weight / 16; // oz to lbs
      const cubicInches = pkg.length * pkg.width * pkg.height;
      const dimWeight = cubicInches / DIM_DIVISORS[carrier];
      totalBilled += Math.max(actualWeight, dimWeight);
    }

    result[carrier] = Math.ceil(totalBilled);
  }

  return result;
}

// Apply shipping rules (free shipping thresholds, markups, etc.)
function applyShippingRules(rates: ShippingRate[], request: ShipmentRequest): ShippingRate[] {
  return rates.map((rate) => {
    const surcharges: Array<{ name: string; amount: number }> = [...rate.surcharges];

    // Residential surcharge
    if (request.options.residential) {
      surcharges.push({ name: "Residential delivery", amount: 495 }); // $4.95
      rate.rate += 495;
    }

    // Signature surcharge
    if (request.options.signatureRequired) {
      surcharges.push({ name: "Signature confirmation", amount: 299 });
      rate.rate += 299;
    }

    // Insurance
    if (request.options.insurance && request.options.insuredValue > 10000) {
      const insuranceCost = Math.round(request.options.insuredValue * 0.02); // 2%
      surcharges.push({ name: "Shipping insurance", amount: insuranceCost });
      rate.rate += insuranceCost;
    }

    // International customs
    if (request.destination.country !== request.origin.country) {
      surcharges.push({ name: "International processing", amount: 999 });
      rate.rate += 999;
    }

    return { ...rate, surcharges };
  });
}

// Zone calculation (simplified)
function getZone(originZip: string, destZip: string): number {
  const origPrefix = parseInt(originZip.slice(0, 3));
  const destPrefix = parseInt(destZip.slice(0, 3));
  const diff = Math.abs(origPrefix - destPrefix);

  if (diff < 10) return 2;
  if (diff < 50) return 3;
  if (diff < 100) return 4;
  if (diff < 200) return 5;
  if (diff < 400) return 6;
  if (diff < 600) return 7;
  return 8;
}

// Carrier API integrations (simplified — real implementation uses carrier SDKs)
async function fetchUPSRates(request: ShipmentRequest, billedWeight: number): Promise<ShippingRate[]> {
  const zone = getZone(request.origin.postalCode, request.destination.postalCode);
  const services = [
    { code: "03", name: "UPS Ground", baseDays: zone + 1 },
    { code: "02", name: "UPS 2nd Day Air", baseDays: 2 },
    { code: "01", name: "UPS Next Day Air", baseDays: 1 },
  ];

  return services.map((svc) => ({
    carrier: "UPS",
    service: svc.name,
    serviceCode: svc.code,
    rate: calculateBaseRate("ups", billedWeight, zone, svc.code),
    currency: "USD",
    estimatedDays: svc.baseDays,
    deliveryDate: addBusinessDays(svc.baseDays),
    isGuaranteed: svc.code !== "03",
    billedWeight,
    surcharges: [],
  }));
}

async function fetchFedExRates(request: ShipmentRequest, billedWeight: number): Promise<ShippingRate[]> {
  const zone = getZone(request.origin.postalCode, request.destination.postalCode);
  const services = [
    { code: "GROUND", name: "FedEx Ground", baseDays: zone + 1 },
    { code: "EXPRESS", name: "FedEx Express", baseDays: 2 },
    { code: "OVERNIGHT", name: "FedEx Overnight", baseDays: 1 },
  ];

  return services.map((svc) => ({
    carrier: "FedEx",
    service: svc.name,
    serviceCode: svc.code,
    rate: calculateBaseRate("fedex", billedWeight, zone, svc.code),
    currency: "USD",
    estimatedDays: svc.baseDays,
    deliveryDate: addBusinessDays(svc.baseDays),
    isGuaranteed: svc.code !== "GROUND",
    billedWeight,
    surcharges: [],
  }));
}

async function fetchUSPSRates(request: ShipmentRequest, billedWeight: number): Promise<ShippingRate[]> {
  const zone = getZone(request.origin.postalCode, request.destination.postalCode);
  if (billedWeight > 70) return []; // USPS max 70 lbs

  return [
    { carrier: "USPS", service: "Priority Mail", serviceCode: "PM", rate: calculateBaseRate("usps", billedWeight, zone, "PM"), currency: "USD", estimatedDays: 3, deliveryDate: addBusinessDays(3), isGuaranteed: false, billedWeight, surcharges: [] },
    { carrier: "USPS", service: "Priority Mail Express", serviceCode: "PME", rate: calculateBaseRate("usps", billedWeight, zone, "PME"), currency: "USD", estimatedDays: 1, deliveryDate: addBusinessDays(1), isGuaranteed: true, billedWeight, surcharges: [] },
  ];
}

function calculateBaseRate(carrier: string, weight: number, zone: number, service: string): number {
  // Simplified rate table (real implementation pulls from carrier APIs)
  const base: Record<string, number> = { ups: 899, fedex: 879, usps: 799 };
  const perLb: Record<string, number> = { ups: 55, fedex: 50, usps: 45 };
  const zoneMultiplier = 1 + (zone - 2) * 0.12;
  const serviceMultiplier = service.includes("Next") || service.includes("OVERNIGHT") || service.includes("PME") ? 3.5 : service.includes("2nd") || service.includes("Express") ? 2.0 : 1.0;

  return Math.round((base[carrier] + weight * perLb[carrier]) * zoneMultiplier * serviceMultiplier);
}

function addBusinessDays(days: number): string {
  const date = new Date();
  let remaining = days;
  while (remaining > 0) {
    date.setDate(date.getDate() + 1);
    if (date.getDay() !== 0 && date.getDay() !== 6) remaining--;
  }
  return date.toISOString().slice(0, 10);
}

function buildCacheKey(req: ShipmentRequest): string {
  const totalWeight = req.packages.reduce((s, p) => s + p.weight, 0);
  return `ship:${req.origin.postalCode}:${req.destination.postalCode}:${totalWeight}:${req.destination.country}`;
}