Grocery — same-day delivery

# (1) Push a new order as a stop as soon as it lands in your OMS.
#     external_id = OMS order ID. cold-chain SKUs add requires=["frozen"].
curl -X POST "https://api.routal.com/v2/stops?private_key=YOUR_KEY&plan_id=PLAN_ID&project_id=YOUR_PROJECT_ID" \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "external_id": "ORD-DKS-22301",
      "label": "B. Garcia — 18 Sant Pere més Alt",
      "location": { "lat": 41.3870, "lng": 2.1741, "address": "Sant Pere més Alt 18, 08003 Barcelona" },
      "duration": 120,
      "time_windows": [[51000, 58200]],
      "phone": "+34699111222",
      "email": "garcia@example.com",
      "weight": 4.2,
      "requires": ["refrigerated"]
    }
  ]'

# (2) Wave optimize — fires from a cron every N minutes. Always pass
#     keep_current_assignment=true to protect drivers on the road.
curl -X POST "https://api.routal.com/v2/plan/PLAN_ID/optimize?private_key=YOUR_KEY&keep_current_assignment=true"

# (3) Dispatch each route that's not already in_transit.
#     Use GET /v2/plan/{id}/routes to enumerate and check status.
curl -X POST "https://api.routal.com/v2/route/ROUTE_ID/dispatch?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 GroceryOrder = {
  id: string;
  customer: string;
  lat: number;
  lng: number;
  address: string;
  phoneE164: string;
  email: string;
  weightKg: number;
  windowFromSec: number;        // promised slot start (seconds from midnight)
  windowToSec: number;          // promised slot end
  coldChain: 'ambient' | 'refrigerated' | 'frozen';
};

/** Push a single order as soon as it lands in the OMS. */
export async function pushOrder(planId: string, order: GroceryOrder) {
  const { error } = await routal.POST('/v2/stops', {
    params: { query: { private_key: ROUTAL_API_KEY, plan_id: planId, project_id: PROJECT_ID } },
    body: [
      {
        external_id: order.id,
        label: `${order.customer} — ${order.address}`,
        location: { lat: order.lat, lng: order.lng, address: order.address },
        duration: 120,
        time_windows: [[order.windowFromSec, order.windowToSec]],
        phone: order.phoneE164,
        email: order.email,
        weight: order.weightKg,
        requires: order.coldChain === 'ambient' ? [] : [order.coldChain],
      },
    ] as never,
  });
  if (error) throw error;
}

/** Wave optimize. Fires from cron every N minutes. */
export async function waveOptimize(planId: string) {
  const { error } = await routal.POST('/v2/plan/{id}/optimize', {
    params: {
      path: { id: planId },
      query: { private_key: ROUTAL_API_KEY, keep_current_assignment: true },
    },
  });
  if (error) {
    // sync_optimization_already_progress is expected if a wave overlaps —
    // just skip this tick; the next one will catch up.
    if ((error as { message_id?: string }).message_id === 'highway.optimization.error.sync_optimization_already_progress') {
      return { skipped: 'overlap' };
    }
    throw error;
  }
  return { skipped: null };
}

/** Dispatch every route that isn't already in_transit. */
export async function dispatchNewRoutes(planId: string) {
  const { data } = await routal.GET('/v2/plan/{id}/routes', {
    params: { path: { id: planId }, query: { private_key: ROUTAL_API_KEY } },
  });
  const routes = (data as Array<{ id: string; status: string }>) ?? [];
  for (const route of routes) {
    if (route.status === 'not_started') {
      await routal.POST('/v2/route/{id}/dispatch', {
        params: { path: { id: route.id }, query: { private_key: ROUTAL_API_KEY } },
      });
    }
  }
}

import os, requests

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


def push_order(plan_id: str, order: dict) -> None:
    """order: {id, customer, address, lat, lng, phone, email, weight_kg, window_from_sec, window_to_sec, cold_chain}"""
    requires = [] if order["cold_chain"] == "ambient" else [order["cold_chain"]]
    payload = [{
        "external_id": order["id"],
        "label": f"{order['customer']} — {order['address']}",
        "location": {"lat": order["lat"], "lng": order["lng"], "address": order["address"]},
        "duration": 120,
        "time_windows": [[order["window_from_sec"], order["window_to_sec"]]],
        "phone": order["phone"],
        "email": order["email"],
        "weight": order["weight_kg"],
        "requires": requires,
    }]
    requests.post(
        f"{BASE}/v2/stops",
        params={"private_key": ROUTAL_API_KEY, "plan_id": plan_id, "project_id": PROJECT_ID},
        json=payload,
        timeout=30,
    ).raise_for_status()


def wave_optimize(plan_id: str) -> dict:
    resp = requests.post(
        f"{BASE}/v2/plan/{plan_id}/optimize",
        params={"private_key": ROUTAL_API_KEY, "keep_current_assignment": "true"},
        timeout=120,
    )
    if not resp.ok:
        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
        if body.get("message_id") == "highway.optimization.error.sync_optimization_already_progress":
            return {"skipped": "overlap"}
        resp.raise_for_status()
    return {"skipped": None}


def dispatch_new_routes(plan_id: str) -> None:
    resp = requests.get(
        f"{BASE}/v2/plan/{plan_id}/routes",
        params={"private_key": ROUTAL_API_KEY},
        timeout=30,
    )
    resp.raise_for_status()
    for route in resp.json():
        if route.get("status") == "not_started":
            requests.post(
                f"{BASE}/v2/route/{route['id']}/dispatch",
                params={"private_key": ROUTAL_API_KEY},
                timeout=30,
            ).raise_for_status()