flexport-upgrade-migration

# Flexport Upgrade & Migration ## Overview Guide for migrating between Flexport API versions. The main API uses `Flexport-Version` header (currently `2`). The Logistics API has dated versions (`2023-10`, `2024-04`). Breaking changes are versioned -- old versions remain available during deprecation windows. ## Instructions ### Step 1: Identify Current API Usage ```bash # Find all Flexport API calls in your codebase grep -rn "Flexport-Version\|api.flexport.com\|logistics-api.flexport.com" src/ --include="*.ts" --include="*.py" # Check which version header you're sending grep -rn "Flexport-Version" src/ --include="*.ts" ``` ### Step 2: API v1 to v2 Migration | Change | v1 | v2 | |--------|----|----| | Header | `Flexport-Version: 1` | `Flexport-Version: 2` | | Response wrapper | `{ "_object": "Shipment", ... }` | `{ "data": { ... } }` | | Pagination | `{ "next": "/shipments?page=2" }` | `{ "data": { "records": [], "total_count": N } }` | | Error format | `{ "errors": [...] }` | `{ "error": { "code": "...", "message": "..." } }` | | Date format | Mixed | ISO 8601 consistently | ```typescript // v1 pattern (deprecated) const res = await fetch(`${BASE}/shipments`, { headers: { 'Flexport-Version': '1' } }); const { _object, id, status } = await res.json(); // v2 pattern (current) const res = await fetch(`${BASE}/shipments`, { headers: { 'Flexport-Version': '2' } }); const { data } = await res.json(); data.records.forEach(s => console.log(s.id, s.status)); ``` ### Step 3: L...