Capacitated distribution

# (1) Onboard the fleet — bulk-create vehicles with default_max_* + provides.
curl -X POST "https://api.routal.com/v3/vehicles?private_key=YOUR_KEY&project_id=PROJECT_ID" \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "external_id": "TRUCK-FROZEN-001",
      "label": "Truck 001 — Frozen 8t",
      "default_provides": ["frozen", "refrigerated", "ambient"],
      "default_max_weight": 8000,
      "default_max_volume": 35,
      "default_max_services": 30,
      "default_time_window": [21600, 64800]
    },
    {
      "external_id": "TRUCK-AMBIENT-002",
      "label": "Truck 002 — Ambient 3.5t",
      "default_provides": ["ambient"],
      "default_max_weight": 3500,
      "default_max_volume": 18,
      "default_max_services": 35,
      "default_time_window": [21600, 64800]
    }
  ]'

# (2) Bulk-add stops with weight, volume, requires. Stops requiring "frozen"
#     can only land on the frozen truck.
curl -X POST "https://api.routal.com/v2/stops?private_key=YOUR_KEY&plan_id=PLAN_ID&project_id=PROJECT_ID" \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "external_id": "ORDER-9001",
      "label": "FrozenFoods Restaurant — A",
      "location": { "lat": 41.20, "lng": 2.05 },
      "duration": 600,
      "time_windows": [[28800, 43200]],
      "weight": 120,
      "volume": 0.8,
      "requires": ["frozen"]
    },
    {
      "external_id": "ORDER-9002",
      "label": "Beta Hardware Store",
      "location": { "lat": 41.18, "lng": 2.07 },
      "duration": 480,
      "time_windows": [[28800, 50400]],
      "weight": 240,
      "volume": 1.4,
      "requires": []
    }
  ]'

# (3) Optimize. Returns no_result_found if there's no feasible assignment.
curl -X POST "https://api.routal.com/v2/plan/PLAN_ID/optimize?private_key=YOUR_KEY"

import createClient from 'openapi-fetch';
import type { paths } from './routal';

const routal = createClient<paths>({ baseUrl: 'https://api.routal.com' });
const ROUTAL_API_KEY = process.env.ROUTAL_API_KEY!;
const PROJECT_ID = process.env.ROUTAL_PROJECT_ID!;

type CapacitatedOrder = {
  id: string;
  customer: string;
  lat: number;
  lng: number;
  serviceMinutes: number;
  windowFromSec: number;
  windowToSec: number;
  weightKg: number;            // explicit — never omit on a capacitated plan
  volumeM3: number;            // explicit — never omit on a capacitated plan
  requires: string[];          // ['frozen'], ['adr-class-3'], etc.
};

type CapacitatedVehicle = {
  id: string;
  label: string;
  provides: string[];          // superset of what stops can require
  maxWeightKg: number;
  maxVolumeM3: number;
  maxServices?: number;
  startSec: number;            // working window start, seconds from midnight
  endSec: number;
};

/** Onboard the fleet once — typically run during initial integration setup. */
export async function syncCapacitatedFleet(vehicles: CapacitatedVehicle[]): Promise<void> {
  const { error } = await routal.POST('/v3/vehicles', {
    params: { query: { private_key: ROUTAL_API_KEY, project_id: PROJECT_ID } },
    body: vehicles.map((v) => ({
      external_id: v.id,
      label: v.label,
      default_provides: v.provides,
      default_max_weight: v.maxWeightKg,
      default_max_volume: v.maxVolumeM3,
      default_max_services: v.maxServices,
      default_time_window: [v.startSec, v.endSec],
    })) as never,
  });
  if (error) throw error;
}

/** Bulk-add capacitated stops to a plan. */
export async function bulkAddCapacitatedStops(
  planId: string,
  orders: CapacitatedOrder[],
): Promise<void> {
  if (orders.length === 0) return;
  const { error } = await routal.POST('/v2/stops', {
    params: { query: { private_key: ROUTAL_API_KEY, plan_id: planId, project_id: PROJECT_ID } },
    body: orders.map((o) => ({
      external_id: o.id,
      label: o.customer,
      location: { lat: o.lat, lng: o.lng },
      duration: o.serviceMinutes * 60,
      time_windows: [[o.windowFromSec, o.windowToSec]],
      weight: o.weightKg,         // always present, even if 0
      volume: o.volumeM3,         // always present, even if 0
      requires: o.requires,
    })) as never,
  });
  if (error) throw error;
}

/** Diagnostic — call before optimize to detect obviously infeasible plans. */
export async function preflightCapacityCheck(planId: string): Promise<{
  totalWeight: number;
  totalVolume: number;
  fleetWeight: number;
  fleetVolume: number;
  feasible: boolean;
  unmatchedSkills: string[];
}> {
  const { data: stops } = await routal.GET('/v2/plan/{id}/stops', {
    params: { path: { id: planId }, query: { private_key: ROUTAL_API_KEY } },
  });
  const { data: vehicles } = await routal.GET('/v2/vehicles', {
    params: { query: { private_key: ROUTAL_API_KEY, project_id: PROJECT_ID, limit: 500 } },
  });
  const stopList = (stops as Array<{ weight?: number; volume?: number; requires?: string[] }>) ?? [];
  const vehList = (vehicles?.docs ?? []) as Array<{
    enabled?: boolean;
    default_max_weight?: number;
    default_max_volume?: number;
    default_provides?: string[];
  }>;

  const totalWeight = stopList.reduce((s, x) => s + (x.weight ?? 0), 0);
  const totalVolume = stopList.reduce((s, x) => s + (x.volume ?? 0), 0);
  const activeVeh = vehList.filter((v) => v.enabled !== false);
  const fleetWeight = activeVeh.reduce((s, v) => s + (v.default_max_weight ?? 0), 0);
  const fleetVolume = activeVeh.reduce((s, v) => s + (v.default_max_volume ?? 0), 0);

  const provided = new Set<string>(activeVeh.flatMap((v) => v.default_provides ?? []));
  const unmatchedSkills = Array.from(
    new Set(
      stopList.flatMap((s) => s.requires ?? []).filter((skill) => !provided.has(skill)),
    ),
  );

  return {
    totalWeight,
    totalVolume,
    fleetWeight,
    fleetVolume,
    unmatchedSkills,
    feasible:
      totalWeight <= fleetWeight &&
      totalVolume <= fleetVolume &&
      unmatchedSkills.length === 0,
  };
}

import os
import requests

ROUTAL_API_KEY = os.environ["ROUTAL_API_KEY"]
PROJECT_ID = os.environ["ROUTAL_PROJECT_ID"]
BASE = "https://api.routal.com"


def sync_capacitated_fleet(vehicles: list[dict]) -> None:
    payload = [
        {
            "external_id": v["id"],
            "label": v["label"],
            "default_provides": v["provides"],
            "default_max_weight": v["max_weight_kg"],
            "default_max_volume": v["max_volume_m3"],
            "default_max_services": v.get("max_services"),
            "default_time_window": [v["start_sec"], v["end_sec"]],
        }
        for v in vehicles
    ]
    resp = requests.post(
        f"{BASE}/v3/vehicles",
        params={"private_key": ROUTAL_API_KEY, "project_id": PROJECT_ID},
        json=payload,
        timeout=60,
    )
    resp.raise_for_status()


def bulk_add_capacitated_stops(plan_id: str, orders: list[dict]) -> None:
    if not orders:
        return
    payload = [
        {
            "external_id": o["id"],
            "label": o["customer"],
            "location": {"lat": o["lat"], "lng": o["lng"]},
            "duration": o["service_minutes"] * 60,
            "time_windows": [[o["window_from_sec"], o["window_to_sec"]]],
            "weight": o["weight_kg"],
            "volume": o["volume_m3"],
            "requires": o["requires"],
        }
        for o in orders
    ]
    resp = requests.post(
        f"{BASE}/v2/stops",
        params={"private_key": ROUTAL_API_KEY, "plan_id": plan_id,
                "project_id": PROJECT_ID},
        json=payload,
        timeout=60,
    )
    resp.raise_for_status()


def preflight_capacity_check(plan_id: str) -> dict:
    """
    Diagnostic — call before optimize to detect obviously infeasible plans.
    Returns aggregate stop demand vs aggregate fleet supply, plus any required
    skills that no vehicle provides.
    """
    stops = requests.get(
        f"{BASE}/v2/plan/{plan_id}/stops",
        params={"private_key": ROUTAL_API_KEY},
        timeout=30,
    ).json()
    vehicles = requests.get(
        f"{BASE}/v2/vehicles",
        params={"private_key": ROUTAL_API_KEY, "project_id": PROJECT_ID, "limit": 500},
        timeout=30,
    ).json().get("docs", [])

    total_weight = sum(s.get("weight") or 0 for s in stops)
    total_volume = sum(s.get("volume") or 0 for s in stops)
    active = [v for v in vehicles if v.get("enabled") is not False]
    fleet_weight = sum(v.get("default_max_weight") or 0 for v in active)
    fleet_volume = sum(v.get("default_max_volume") or 0 for v in active)

    provided = {p for v in active for p in (v.get("default_provides") or [])}
    required = {r for s in stops for r in (s.get("requires") or [])}
    unmatched = sorted(required - provided)

    return {
        "total_weight": total_weight,
        "total_volume": total_volume,
        "fleet_weight": fleet_weight,
        "fleet_volume": fleet_volume,
        "unmatched_skills": unmatched,
        "feasible": (
            total_weight <= fleet_weight
            and total_volume <= fleet_volume
            and not unmatched
        ),
    }