# HeavyHaul Agent × AI Backend — Integration Brief

**To:** the developer of the AI/extraction backend (order agent, estimator, extractors)
**From:** HeavyHaul Agent frontend team
**Purpose:** connect your existing AI products to the new HeavyHaul Agent trip-workspace SaaS over HTTP. No rewrites — we call your API from our server.

---

## 1. What HeavyHaul Agent is (30-second context)

A multi-user web app where a broker, dispatcher, and driver share one **Trip Workspace** per load: rate confirmation, state permits, participants, warnings, a shared chat room, and an AI assistant. Our stack is Next.js + Supabase (Postgres + file storage). All calls to you come **from our server only** (never the browser), authenticated with a Bearer token.

## 2. What we already have working

- Accounts, login, per-trip roles (broker/dispatcher/driver/pilot/shipper)
- Broker intake page (public link, rate-con upload, "buy permits vs. upload own")
- Trip workspace: documents, participants/invitations, status flow, audit history
- Shared trip chat room (participant messages work; AI answers are stubbed until you're connected)
- Warnings engine (dimension mismatch, expiry, curfew, escort — waiting on real extraction data)
- File storage for all uploaded PDFs (we can send you the file bytes or a signed URL)

## 3. What we need from you — 4 endpoints (MVP)

Our adapter is one file and can remap paths/shapes easily, so if your existing routes differ, just send us your actual spec. The shapes below are what our app consumes.

**Auth for all endpoints:** `Authorization: Bearer <API_KEY>` — give us a key.

### 3.1 Permit extraction
`POST /api/extract/permit` — multipart form, field `file` (PDF/image)
```json
{
  "state_code": "TX", "permit_number": "123", 
  "effective_date": "YYYY-MM-DD", "expiration_date": "YYYY-MM-DD",
  "length_in": 0, "width_in": 0, "height_in": 0, "weight_lbs": 0,
  "route_description": "...", 
  "restrictions": ["..."], "curfews": ["..."], "escorts": ["..."],
  "raw": {}
}
```

### 3.2 Rate confirmation extraction
`POST /api/extract/rate-confirmation` — multipart form, field `file`
```json
{
  "origin": "...", "destination": "...", "commodity": "...",
  "carrier_name": "...", "broker_name": "...",
  "pickup_date": "...", "delivery_date": "...",
  "length_in": 0, "width_in": 0, "height_in": 0, "weight_lbs": 0,
  "raw": {}
}
```

### 3.3 Trip AI chat (your order agent)
`POST /api/ai/ask` — JSON. We send the question **plus the full trip context** (trip data + all its permits' extractions) so you don't need our database. One trip = one context; never mix trips.
```json
// request
{
  "question": "Can I drive at night in Ohio?",
  "state_code": "OH",            // null = whole-trip question
  "language": "en",              // en initially; ~4 languages later
  "trip": { "ref_code": "...", "origin": "...", "destination": "...", "commodity": "...",
            "load_dims": { "length_in": 0, "width_in": 0, "height_in": 0, "weight_lbs": 0 } },
  "permits": [ { "state_code": "TX", "permit_number": "...", "effective_date": "...",
                 "expiration_date": "...", "extraction": {} } ]
}
// response
{ "answer": "...", "confidence": "high|partial|low", "sources": ["TX permit 123", "TX provisions"] }
```

### 3.4 Synchron order creation
`POST /api/synchron/orders` — JSON: `{ type: "permit"|"route", trip_ref, state_code?, carrier_name, contact_email, notes?, document_urls? }` → `{ "order_id": "..." }`
`document_urls` are short-lived signed URLs to the uploaded PDFs.

## 4. Nice-to-have soon after MVP (tell us what already exists)

- **Async extraction callback:** if extraction is slow, return `202 { job_id }` and POST the result to a callback URL we provide — otherwise we wait synchronously (we time out at 120s).
- **More extractors** you already have: truck permit, trailer permit, state permits, IFTA, COI — same multipart pattern as 3.1; send us the response shapes.
- **Estimator agent:** endpoint + request/response spec so we can add an estimate tab/chat.
- **Voice:** does your side expose speech-to-text/text-to-speech, or should we handle voice in the browser and send you text?
- **Synchron status webhook:** notify us when a permit/route order is fulfilled (we'll give you a callback URL + secret).

## 5. What we need to receive from you (checklist)

1. Base URL of the API (staging + production)
2. API key (Bearer)
3. Confirmation of the 4 endpoint paths above, or your actual paths/shapes so we remap
4. Response time expectations per endpoint (sync vs. needs-async)
5. Spec for the extra extractors + estimator when ready
6. A sample permit PDF + its expected extraction JSON (for our tests)

Once we have items 1–3, integration on our side is a same-day task: we set two env vars and, if needed, adjust one adapter file.