Nightly batch — B2B distribution

# This recipe orchestrates 4 calls in sequence. The cURL form is useful for
# debugging individual steps — for the full nightly job, see the TS or Python
# tabs. Run these at 18:05 against tomorrow's execution_date.

EXEC_DATE="2026-05-22"     # tomorrow, in the project's local time zone

# (1) Create tomorrow's plan (or fetch it if it already exists from a retry).
curl -X POST "https://api.routal.com/v2/plan?private_key=YOUR_KEY&project_id=YOUR_PROJECT_ID" \
  -H 'Content-Type: application/json' \
  -d "{ \"label\": \"${EXEC_DATE} nightly\", \"execution_date\": \"${EXEC_DATE}\" }"
# → { "id": "PLAN_ID", "status": "planning", "total_stops": 0, ... }

# (2) Bulk-add the day's orders. Each one carries the source order number as
#     external_id so a retry of step 2 is a no-op for stops already created.
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": "ORDER-9001",
      "label": "Acme Restaurant — Centre",
      "location": { "lat": 41.20, "lng": 2.05, "address": "123 Industrial Park, Unit B" },
      "duration": 600,
      "time_windows": [[28800, 43200]],
      "weight": 32,
      "volume": 0.4,
      "phone": "+10000000001"
    },
    {
      "external_id": "ORDER-9002",
      "label": "Beta Bakery Supply",
      "location": { "lat": 41.25, "lng": 2.10 },
      "duration": 480,
      "time_windows": [[32400, 50400]],
      "weight": 12,
      "volume": 0.15
    }
  ]'

# (3) Optimize. Not safe to retry blindly — see Production hardening.
curl -X POST "https://api.routal.com/v2/plan/PLAN_ID/optimize?private_key=YOUR_KEY"

# (4) For each route the optimizer produced, dispatch (sends magic-link email).
curl -G "https://api.routal.com/v2/plan/PLAN_ID/routes" \
  --data-urlencode 'private_key=YOUR_KEY'
# → list of routes. For each: dispatch.
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 SourceOrder = {
  id: string;            // order number from your ERP/WMS
  customer: string;
  lat: number;
  lng: number;
  address?: string;
  serviceMinutes: number;
  windowFromSec: number;
  windowToSec: number;
  weightKg?: number;
  volumeM3?: number;
  phone?: string;
};

/**
 * Run the nightly batch for a given execution date.
 * Designed to be called from a scheduler at the order cutoff hour.
 * Idempotent on (PROJECT_ID, executionDate).
 */
export async function runNightlyBatch(
  executionDate: string,                      // 'YYYY-MM-DD'
  orders: SourceOrder[],
  log = console,
): Promise<{ planId: string; stopsCreated: number; routesDispatched: number }> {
  const label = `${executionDate} nightly`;
  const planId = await ensurePlan(executionDate, label);
  log.info('nightly_batch.plan_ready', { planId, executionDate, orderCount: orders.length });

  // Reconcile: only push stops whose external_id is not already on the plan.
  const alreadyThere = await findExistingExternalIds(planId, orders.map((o) => o.id));
  const newOrders = orders.filter((o) => !alreadyThere.has(o.id));
  if (newOrders.length > 0) {
    await bulkAddStops(planId, newOrders);
  }
  log.info('nightly_batch.stops_added', {
    planId,
    new: newOrders.length,
    skipped: orders.length - newOrders.length,
  });

  await optimizeOnce(planId);
  log.info('nightly_batch.optimized', { planId });

  const dispatched = await dispatchAllRoutes(planId);
  log.info('nightly_batch.dispatched', { planId, routes: dispatched });

  return { planId, stopsCreated: newOrders.length, routesDispatched: dispatched };
}

async function ensurePlan(executionDate: string, label: string): Promise<string> {
  // Plans are listed in reverse chrono — paginate just enough to find today's.
  // If your project produces many plans/day, narrow with a search by label.
  const { data, error } = await routal.GET('/v2/plans', {
    params: {
      query: {
        private_key: ROUTAL_API_KEY,
        project_id: PROJECT_ID,
        limit: 50,
        sort: 'created_at:desc',
      },
    },
  });
  if (error) throw error;
  const existing = data!.docs?.find(
    (p) => p.label === label && p.execution_date?.startsWith(executionDate),
  );
  if (existing) return existing.id!;

  const { data: created, error: createErr } = await routal.POST('/v2/plan', {
    params: { query: { private_key: ROUTAL_API_KEY, project_id: PROJECT_ID } },
    body: { label, execution_date: executionDate } as never,
  });
  if (createErr) throw createErr;
  return created!.id!;
}

async function findExistingExternalIds(planId: string, orderIds: string[]): Promise<Set<string>> {
  if (orderIds.length === 0) return new Set();
  const { data, error } = await routal.POST('/v2/stops/search', {
    params: { query: { private_key: ROUTAL_API_KEY, project_id: PROJECT_ID } },
    body: {
      limit: 1000,
      predicates: [
        { field: 'plan_id', operator: 'eq', value: planId, type: 'string' },
        { field: 'external_id', operator: 'in', value: orderIds, type: 'string' },
      ],
    } as never,
  });
  if (error) throw error;
  return new Set((data!.docs ?? []).map((s) => s.external_id!).filter(Boolean));
}

async function bulkAddStops(planId: string, orders: SourceOrder[]): Promise<void> {
  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, address: o.address },
      duration: o.serviceMinutes * 60,
      time_windows: [[o.windowFromSec, o.windowToSec]],
      weight: o.weightKg,
      volume: o.volumeM3,
      phone: o.phone,
    })) as never,
  });
  if (error) throw error;
}

async function optimizeOnce(planId: string): Promise<void> {
  const { error } = await routal.POST('/v2/plan/{id}/optimize', {
    params: { path: { id: planId }, query: { private_key: ROUTAL_API_KEY } },
  });
  if (error?.message_id === 'highway.optimization.error.sync_optimization_already_progress') {
    throw new Error(
      'optimization already running for ' + planId +
      ' — wait, then check plan state before re-firing',
    );
  }
  if (error) throw error;
}

async function dispatchAllRoutes(planId: string): Promise<number> {
  const { data: routes, error } = await routal.GET('/v2/plan/{id}/routes', {
    params: { path: { id: planId }, query: { private_key: ROUTAL_API_KEY } },
  });
  if (error) throw error;
  let count = 0;
  for (const route of routes ?? []) {
    const { error: dispatchErr } = await routal.POST('/v2/route/{id}/dispatch', {
      params: { path: { id: route.id! }, query: { private_key: ROUTAL_API_KEY } },
    });
    if (dispatchErr) throw dispatchErr;
    count++;
  }
  return count;
}

import os
import requests
from datetime import date

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

def run_nightly_batch(execution_date: str, orders: list[dict]) -> dict:
    """
    Run the nightly batch for a given execution date.
    Designed to be called from a scheduler at the order cutoff hour.
    Idempotent on (PROJECT_ID, execution_date).
    """
    label = f"{execution_date} nightly"
    plan_id = ensure_plan(execution_date, label)

    already = find_existing_external_ids(plan_id, [o["id"] for o in orders])
    new_orders = [o for o in orders if o["id"] not in already]
    if new_orders:
        bulk_add_stops(plan_id, new_orders)

    optimize_once(plan_id)
    dispatched = dispatch_all_routes(plan_id)
    return {"plan_id": plan_id, "stops_created": len(new_orders),
            "routes_dispatched": dispatched}


def ensure_plan(execution_date: str, label: str) -> str:
    resp = requests.get(
        f"{BASE}/v2/plans",
        params={"private_key": ROUTAL_API_KEY, "project_id": PROJECT_ID,
                "limit": 50, "sort": "created_at:desc"},
        timeout=30,
    )
    resp.raise_for_status()
    for p in resp.json().get("docs", []):
        if p.get("label") == label and (p.get("execution_date") or "").startswith(execution_date):
            return p["id"]
    created = requests.post(
        f"{BASE}/v2/plan",
        params={"private_key": ROUTAL_API_KEY, "project_id": PROJECT_ID},
        json={"label": label, "execution_date": execution_date},
        timeout=30,
    )
    created.raise_for_status()
    return created.json()["id"]


def find_existing_external_ids(plan_id: str, order_ids: list[str]) -> set[str]:
    if not order_ids:
        return set()
    resp = requests.post(
        f"{BASE}/v2/stops/search",
        params={"private_key": ROUTAL_API_KEY, "project_id": PROJECT_ID},
        json={
            "limit": 1000,
            "predicates": [
                {"field": "plan_id", "operator": "eq", "value": plan_id, "type": "string"},
                {"field": "external_id", "operator": "in", "value": order_ids, "type": "string"},
            ],
        },
        timeout=30,
    )
    resp.raise_for_status()
    return {s["external_id"] for s in resp.json().get("docs", []) if s.get("external_id")}


def bulk_add_stops(plan_id: str, orders: list[dict]) -> None:
    payload = [
        {
            "external_id": o["id"],
            "label": o["customer"],
            "location": {"lat": o["lat"], "lng": o["lng"], "address": o.get("address")},
            "duration": o["service_minutes"] * 60,
            "time_windows": [[o["window_from_sec"], o["window_to_sec"]]],
            "weight": o.get("weight_kg"),
            "volume": o.get("volume_m3"),
            "phone": o.get("phone"),
        }
        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 optimize_once(plan_id: str) -> None:
    resp = requests.post(
        f"{BASE}/v2/plan/{plan_id}/optimize",
        params={"private_key": ROUTAL_API_KEY},
        timeout=180,
    )
    if resp.status_code == 400:
        body = resp.json()
        if body.get("message_id") == "highway.optimization.error.sync_optimization_already_progress":
            raise RuntimeError(
                f"optimization already running for {plan_id} — "
                "wait, then check plan state before re-firing"
            )
    resp.raise_for_status()


def dispatch_all_routes(plan_id: str) -> int:
    resp = requests.get(
        f"{BASE}/v2/plan/{plan_id}/routes",
        params={"private_key": ROUTAL_API_KEY},
        timeout=30,
    )
    resp.raise_for_status()
    count = 0
    for r in resp.json():
        requests.post(
            f"{BASE}/v2/route/{r['id']}/dispatch",
            params={"private_key": ROUTAL_API_KEY},
            timeout=30,
        ).raise_for_status()
        count += 1
    return count