hh-shipments 0.1.0 → 0.3.0

package/README.md

@@ -52,15 +52,37 @@ The app must stay running 24/7 for scheduled tracking checks. It needs HTTPS
 ```bash
 docker build -t hh-shipments .
 docker run -d -p 3000:3000 -v hh-data:/data \
-  -e TRACKING_PROVIDER=17track \
-  -e SEVENTEEN_TRACK_API_KEY=your-key \
-  -e SEVENTEEN_TRACK_WEBHOOK_SECRET=pick-a-secret \
+  -e TRACKING_PROVIDER=direct \
+  -e UPS_CLIENT_ID=<id> -e UPS_CLIENT_SECRET=<secret> \
+  -e FEDEX_CLIENT_ID=<id> -e FEDEX_CLIENT_SECRET=<secret> \
+  -e USPS_CLIENT_ID=<id> -e USPS_CLIENT_SECRET=<secret> \
   hh-shipments
 ```
 
 Put it behind HTTPS (Caddy/Cloudflare Tunnel/your host's TLS).
 
-## Real tracking with 17Track (recommended)
+## Real tracking with direct carrier APIs (current plan)
+
+Verified 2026-10-12. Free developer signups, no per-tracking fee. DHL is not
+wired (skipped by choice — add later if needed).
+
+1. **UPS** — developer.ups.com → Create Application → enable the **Tracking**
+   product → copy Client ID + Client Secret.
+2. **FedEx** — developer.fedex.com → My Projects → new project → add the
+   **Track** API → copy API Key + Secret Key (test credentials work immediately;
+   production may need approval).
+3. **USPS** — developer.usps.com → register → create an application → copy
+   Client ID + Client Secret.
+4. Set `TRACKING_PROVIDER=direct` plus the six `*_CLIENT_ID`/`*_CLIENT_SECRET`
+   env vars on the server. Each number is auto-routed to the right carrier by
+   its format (1Z… → UPS, 9400…/AA…US → USPS, FedEx digit patterns → FedEx).
+   Or force one carrier for all numbers with `TRACKING_PROVIDER=ups|fedex|usps`.
+
+Endpoint/field details verified 2026-10-12 against official docs (UPS
+UPS-API/api-documentation Tracking.yaml, FedEx Track API reference,
+USPS/api-examples).
+
+## Real tracking with 17Track (alternative)
 
 Verified 2026-10-12. 17Track's API covers UPS/USPS/FedEx/DHL with auto carrier
 detection and webhooks.

package/package.json

@@ -7,7 +7,7 @@
     "node-cron": "^3.0.3",
     "web-push": "^3.6.7"
   },
-  "description": "HH Electronics shipment tracker \u2014 intake tracking numbers from seller messages/screenshots, auto-track via 17Track, push notifications, archive.",
+  "description": "HH Electronics shipment tracker — intake tracking numbers from seller messages/screenshots, auto-track via 17Track, push notifications, archive.",
   "engines": {
     "node": ">=22.5"
   },
@@ -15,10 +15,10 @@
   "name": "hh-shipments",
   "scripts": {
     "start": "node server.js",
-    "test": "node test/run-tests.js"
+    "test": "node test/run-tests.js && node test/run-carriers-tests.js"
   },
   "type": "commonjs",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "bin": {
     "hh-shipments": "server.js"
   },

package/public/app.js

@@ -160,9 +160,7 @@ async function ocrFile(file, statusEl) {
   return data.text || '';
 }
 
-$('photo-input').addEventListener('change', async (e) => {
-  const f = e.target.files[0];
-  if (!f) return;
+async function handlePhotoFile(f) {
   try {
     const text = await ocrFile(f, $('ocr-status'));
     // Upload original for reference, then run the quick flow on OCR text
@@ -173,7 +171,30 @@ $('photo-input').addEventListener('change', async (e) => {
     await runQuick(text, $('photo-result'));
     loadPending();
   } catch (err) { $('ocr-status').textContent = ''; $('photo-result').innerHTML = `<p class="error">${esc(err.message)}</p>`; }
+}
+
+$('photo-input').addEventListener('change', async (e) => {
+  const f = e.target.files[0];
   e.target.value = '';
+  if (!f) return;
+  await handlePhotoFile(f);
+});
+
+// Paste a screenshot straight from the clipboard (iOS: tap the paste zone, long-press → Paste)
+$('tab-photo').addEventListener('paste', async (e) => {
+  const dt = e.clipboardData;
+  if (!dt) return;
+  const files = [];
+  if (dt.items) for (const it of dt.items) {
+    if (it.type && it.type.startsWith('image/')) { const f = it.getAsFile(); if (f) files.push(f); }
+  }
+  if (!files.length && dt.files) for (const f of dt.files) {
+    if (f.type && f.type.startsWith('image/')) files.push(f);
+  }
+  if (!files.length) return; // let text pastes behave normally
+  e.preventDefault();
+  $('paste-zone').innerHTML = '📋 <span class="muted">or tap here, then paste your screenshot</span>';
+  for (const f of files) await handlePhotoFile(f);
 });
 
 async function loadPending() {
@@ -293,6 +314,7 @@ function urlB64(s) {
 function activateTab(name) {
   document.querySelectorAll('.tab').forEach((t) => t.classList.toggle('active', t.dataset.tab === name));
   ['paste', 'photo', 'manual'].forEach((n) => ($('tab-' + n).hidden = n !== name));
+  if (name === 'photo') { try { $('paste-zone').focus({ preventScroll: true }); } catch (_) {} }
 }
 document.querySelectorAll('.tab').forEach((t) => (t.onclick = () => activateTab(t.dataset.tab)));
 document.querySelectorAll('#tabbar button').forEach((b) => {

package/public/index.html

@@ -67,6 +67,7 @@
     </div>
     <div id="tab-photo" class="tabpanel" hidden>
       <label class="filebtn">📷 Choose screenshot<input id="photo-input" type="file" accept="image/*" hidden></label>
+      <div id="paste-zone" class="pastezone" contenteditable="true" spellcheck="false" aria-label="Paste a screenshot here">📋 <span class="muted">or tap here, then paste your screenshot</span></div>
       <div id="ocr-status" class="muted"></div>
       <div id="photo-result"></div>
       <h3>Pending screenshots</h3>

package/public/styles.css

@@ -42,6 +42,8 @@ h2 { font-size: 17px; margin: 18px 0 8px; }
 .tab.active { background: var(--blue); color: #fff; }
 .tabpanel { margin-bottom: 12px; }
 .filebtn { display: block; text-align: center; background: #e5e5ea; border-radius: 12px; padding: 16px; font-weight: 600; cursor: pointer; }
+.pastezone { margin-top: 10px; border: 2px dashed #c7c7cc; border-radius: 12px; padding: 18px; text-align: center; font-size: 15px; min-height: 24px; outline: none; caret-color: transparent; }
+.pastezone:focus { border-color: #007aff; background: #f2f8ff; }
 .statusline { font-size: 17px; font-weight: 600; margin: 8px 0; }
 .timeline { border-left: 2px solid #d1d1d6; margin-left: 6px; padding-left: 14px; }
 .timeline .ev { margin-bottom: 12px; font-size: 14px; }

package/server.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /* HH Electronics shipment tracker — server.
  * Mobile-first PWA + JSON API. SQLite storage. VAPID web push.
- * Tracking providers: simulated (default, clearly labeled) | 17track.
+ * Tracking providers: simulated (default, clearly labeled) | 17track |
+ *                     direct (auto-route UPS/FedEx/USPS) | ups | fedex | usps.
  */
 const express = require('express');
 const path = require('path');

package/src/carriers.js

@@ -0,0 +1,431 @@
+/* Direct carrier tracking providers: UPS, FedEx, USPS.
+ *
+ * Chosen over the 17Track route: Hunter prefers free options, and each
+ * carrier's Tracking API is free with a developer signup (DHL skipped).
+ *
+ * Env vars:
+ *   UPS_CLIENT_ID / UPS_CLIENT_SECRET       (developer.ups.com app, Tracking product)
+ *   FEDEX_CLIENT_ID / FEDEX_CLIENT_SECRET   (developer.fedex.com project, Track API)
+ *   USPS_CLIENT_ID / USPS_CLIENT_SECRET     (developer.usps.com app)
+ *   TRACKING_PROVIDER=direct                 -> auto-route each number by format
+ *   TRACKING_PROVIDER=ups|fedex|usps         -> force one carrier for all numbers
+ *
+ * All adapters normalize to the provider interface in providers.js:
+ *   { number, ok, status, status_detail, latest_event_text, latest_event_at,
+ *     estimated_delivery, events:[{ts,status,text,location}], simulated:false, error }
+ * Canonical statuses: pending | in_transit | out_for_delivery | delivered |
+ *                     exception | invalid
+ *
+ * Endpoint/field details verified 2026-10-12 against:
+ *   UPS:  UPS-API/api-documentation Tracking.yaml + n8n-ups-node integration notes
+ *   FedEx: developer.fedex.com Track API + goshippo/vibe-hub API references
+ *   USPS:  USPS/api-examples (official) + developer.usps.com v3 docs
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+/* ---------------- carrier number-format detection ----------------
+ * Same patterns as src/extract.js isValidFormat (ups/usps/fedex). dhl is
+ * not wired (skipped per user choice) — those numbers route as unconfigured.
+ */
+function detectCarrier(number) {
+  const n = String(number || '').trim().toUpperCase().replace(/[\s-]/g, '');
+  if (/^1Z[0-9A-Z]{16}$/.test(n)) return 'ups';
+  if (/^9[2-5]\d{18,20}$/.test(n) || /^[A-Z]{2}\d{9}US$/.test(n)) return 'usps';
+  if (/^(96\d{20}|\d{12}|\d{15}|\d{20})$/.test(n)) return 'fedex';
+  return null;
+}
+
+/* ---------------- shared helpers ---------------- */
+
+function canonicalize(description) {
+  const d = String(description || '');
+  if (/out for delivery|out-for-delivery|on (the )?vehicle for delivery/i.test(d)) return 'out_for_delivery';
+  if (/delivered/i.test(d)) return 'delivered';
+  if (/exception|unable to deliver|delivery attempted|undeliverable|returned to sender|cancel/i.test(d)) return 'exception';
+  if (/label created|pre-?shipment|order processed|manifest|pickup/i.test(d)) return 'pending';
+  return 'in_transit';
+}
+
+function fmtLocation(parts) {
+  const p = parts.filter(Boolean);
+  return p.length ? p.join(', ') : '';
+}
+
+function isoOrNull(...vals) {
+  for (const v of vals) {
+    if (v && !Number.isNaN(Date.parse(v))) return new Date(v).toISOString();
+  }
+  return null;
+}
+
+/* In-memory OAuth token cache: carrier -> { token, expiresAt } */
+const tokenCache = new Map();
+
+async function fetchJson(url, opts = {}) {
+  const res = await fetch(url, opts);
+  const text = await res.text();
+  let json = null;
+  try { json = JSON.parse(text); } catch (_) { /* non-JSON body */ }
+  return { status: res.status, ok: res.ok, json, text };
+}
+
+async function getToken(carrier) {
+  const cached = tokenCache.get(carrier);
+  if (cached && cached.expiresAt > Date.now() + 60_000) return cached.token;
+
+  const id = process.env[`${carrier.toUpperCase()}_CLIENT_ID`];
+  const secret = process.env[`${carrier.toUpperCase()}_CLIENT_SECRET`];
+  if (!id || !secret) {
+    throw new Error(`${carrier.toUpperCase()}_CLIENT_ID / ${carrier.toUpperCase()}_CLIENT_SECRET not set`);
+  }
+
+  let url, body, headers;
+  if (carrier === 'ups') {
+    url = 'https://onlinetools.ups.com/security/v1/oauth/token';
+    headers = {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      'Authorization': 'Basic ' + Buffer.from(`${id}:${secret}`).toString('base64'),
+    };
+    body = 'grant_type=client_credentials';
+  } else if (carrier === 'fedex') {
+    url = 'https://apis.fedex.com/oauth/token';
+    headers = { 'Content-Type': 'application/x-www-form-urlencoded' };
+    body = `grant_type=client_credentials&client_id=${encodeURIComponent(id)}&client_secret=${encodeURIComponent(secret)}`;
+  } else { // usps
+    url = 'https://apis.usps.com/oauth2/v3/token';
+    headers = { 'Content-Type': 'application/json' };
+    body = JSON.stringify({ client_id: id, client_secret: secret, grant_type: 'client_credentials' });
+  }
+
+  const r = await fetchJson(url, { method: 'POST', headers, body });
+  if (!r.ok || !r.json || !r.json.access_token) {
+    throw new Error(`${carrier} auth failed (HTTP ${r.status})`);
+  }
+  const ttl = Math.max(60, Number(r.json.expires_in) || 3600);
+  tokenCache.set(carrier, { token: r.json.access_token, expiresAt: Date.now() + ttl * 1000 });
+  return r.json.access_token;
+}
+
+/* ---------------- UPS ---------------- */
+
+function mapUpsStatus(code, description) {
+  const c = String(code || '').toUpperCase();
+  if (c === 'D') return 'delivered';
+  if (c === 'M') return 'out_for_delivery';
+  if (c === 'P') return 'pending';
+  if (c === 'X' || c === 'E') return 'exception';
+  return canonicalize(description);
+}
+
+function upsEventDate(date, time) {
+  // UPS returns date "YYYYMMDD" and time "HHMMSS" (facility local). Build ISO.
+  if (!date || !/^\d{8}$/.test(String(date))) return isoOrNull(date);
+  const t = /^\d{6}$/.test(String(time || '')) ? String(time) : '120000';
+  const s = `${String(date).slice(0, 4)}-${String(date).slice(4, 6)}-${String(date).slice(6, 8)}T${t.slice(0, 2)}:${t.slice(2, 4)}:${t.slice(4, 6)}`;
+  return isoOrNull(s);
+}
+
+async function upsTrackOne(number) {
+  const token = await getToken('ups');
+  const url = `https://onlinetools.ups.com/api/track/v1/details/${encodeURIComponent(number)}?locale=en_US&returnSignature=false`;
+  let r = await fetchJson(url, {
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'transId': crypto.randomUUID(),
+      'transactionSrc': 'HHShipments',
+    },
+  });
+  if (r.status === 401) {
+    tokenCache.delete('ups');
+    const token2 = await getToken('ups');
+    r = await fetchJson(url, {
+      headers: { 'Authorization': `Bearer ${token2}`, 'transId': crypto.randomUUID(), 'transactionSrc': 'HHShipments' },
+    });
+  }
+  if (!r.ok) {
+    const msg = (r.json && (r.json.response && r.json.response.errors || []).map((e) => e.message).join('; ')) || r.text.slice(0, 200);
+    if (r.status === 404 || /invalid|not found/i.test(msg)) {
+      return { number, ok: false, error: `Invalid UPS tracking number`, simulated: false };
+    }
+    throw new Error(`UPS track failed (HTTP ${r.status}): ${msg}`);
+  }
+  const shipment = (r.json.trackResponse && r.json.trackResponse.shipment || [])[0] || {};
+  const pkg = (shipment.package || [])[0] || {};
+  const current = pkg.currentStatus || {};
+  const activities = pkg.activity || [];
+
+  const events = activities.map((a) => {
+    const loc = (a.location && a.location.address) || {};
+    return {
+      ts: upsEventDate(a.date, a.time),
+      status: mapUpsStatus(a.status && a.status.code, a.status && a.status.description),
+      text: (a.status && a.status.description) || '',
+      location: fmtLocation([loc.city, loc.stateProvinceCode || loc.postalCode]),
+    };
+  }).filter((e) => e.text).sort((x, y) => String(x.ts).localeCompare(String(y.ts)));
+
+  // planned delivery date: shipment.deliveryDate[] {type:'PLD'|'DEL', date:'YYYYMMDD'}
+  let eta = null;
+  for (const d of shipment.deliveryDate || []) {
+    if (/^PLD/i.test(d.type || '')) { eta = upsEventDate(d.date); break; }
+  }
+
+  const latest = events.length ? events[events.length - 1] : null;
+  const status = mapUpsStatus(current.code, current.description);
+  return {
+    number,
+    ok: true,
+    status: latest && latest.status === 'pending' && events.length > 1 ? 'in_transit' : status,
+    status_detail: current.description || '',
+    latest_event_text: latest ? latest.text : (current.description || ''),
+    latest_event_at: latest ? latest.ts : null,
+    estimated_delivery: eta,
+    events,
+    simulated: false,
+  };
+}
+
+async function upsTrack(numbers) {
+  const out = [];
+  for (const n of numbers) {
+    try {
+      out.push(await upsTrackOne(n));
+    } catch (e) {
+      out.push({ number: n, ok: false, error: e.message.slice(0, 300), simulated: false });
+    }
+  }
+  return out;
+}
+
+/* ---------------- FedEx ---------------- */
+
+const FEDEX_CODE_MAP = {
+  DL: 'delivered', OD: 'out_for_delivery', IT: 'in_transit', PU: 'in_transit',
+  DE: 'exception', OC: 'exception', OX: 'exception', SE: 'exception',
+  CA: 'exception', DY: 'exception', RS: 'exception',
+};
+
+function mapFedexStatus(derivedCode, description) {
+  const c = String(derivedCode || '').toUpperCase();
+  if (FEDEX_CODE_MAP[c]) return FEDEX_CODE_MAP[c];
+  return canonicalize(description);
+}
+
+async function fedexTrackBatch(numbers) {
+  const token = await getToken('fedex');
+  const url = 'https://apis.fedex.com/track/v1/trackingnumbers';
+  const call = (t) => fetchJson(url, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${t}`,
+      'Content-Type': 'application/json',
+      'X-locale': 'en_US',
+    },
+    body: JSON.stringify({
+      includeDetailedScans: true,
+      trackingInfo: numbers.map((n) => ({ trackingNumberInfo: { trackingNumber: n } })),
+    }),
+  });
+  let r = await call(token);
+  if (r.status === 401) {
+    tokenCache.delete('fedex');
+    r = await call(await getToken('fedex'));
+  }
+  if (!r.ok) throw new Error(`FedEx track failed (HTTP ${r.status}): ${r.text.slice(0, 200)}`);
+  return (r.json.output && r.json.output.completeTrackResults) || [];
+}
+
+function fedexNormalize(trackingNumber, tr) {
+  const base = { number: trackingNumber, simulated: false };
+  if (!tr) return { ...base, ok: false, error: 'No FedEx track result' };
+  if (tr.error && tr.error.code) {
+    const invalid = /NOTFOUND|INVALID/i.test(tr.error.code);
+    return { ...base, ok: false, error: (invalid ? 'Invalid FedEx tracking number' : tr.error.message || tr.error.code) };
+  }
+  const lsd = tr.latestStatusDetail || {};
+  const scans = tr.scanEvents || [];
+  const events = scans.map((s) => {
+    const loc = s.scanLocation || {};
+    return {
+      ts: isoOrNull(s.date),
+      status: mapFedexStatus(s.derivedStatusCode || s.derivedStatus, s.eventDescription),
+      text: s.eventDescription || '',
+      location: fmtLocation([loc.city, loc.stateOrProvinceCode || loc.postalCode]),
+    };
+  }).filter((e) => e.text).sort((x, y) => String(x.ts).localeCompare(String(y.ts)));
+
+  let eta = null;
+  for (const d of tr.dateAndTimes || []) {
+    if (/^ESTIMATED_DELIVERY$/i.test(d.type || '')) { eta = isoOrNull(d.dateTime); break; }
+  }
+
+  const latest = events.length ? events[events.length - 1] : null;
+  const status = mapFedexStatus(lsd.derivedCode || lsd.code, lsd.description);
+  return {
+    ...base,
+    ok: true,
+    status: status === 'pending' && events.length > 1 ? 'in_transit' : status,
+    status_detail: lsd.description || '',
+    latest_event_text: latest ? latest.text : (lsd.description || ''),
+    latest_event_at: latest ? latest.ts : null,
+    estimated_delivery: eta,
+    events,
+  };
+}
+
+async function fedexTrack(numbers) {
+  const out = [];
+  // FedEx allows up to 30 tracking numbers per call.
+  for (let i = 0; i < numbers.length; i += 30) {
+    const chunk = numbers.slice(i, i + 30);
+    try {
+      const results = await fedexTrackBatch(chunk);
+      const byNum = new Map();
+      for (const cr of results) {
+        for (const tr of cr.trackResults || []) {
+          byNum.set(tr.trackingNumber, tr);
+        }
+      }
+      for (const n of chunk) out.push(fedexNormalize(n, byNum.get(n)));
+    } catch (e) {
+      for (const n of chunk) out.push({ number: n, ok: false, error: e.message.slice(0, 300), simulated: false });
+    }
+  }
+  return out;
+}
+
+/* ---------------- USPS ---------------- */
+
+function mapUspsStatus(category, eventType) {
+  const s = `${category || ''} ${eventType || ''}`;
+  if (/out for delivery/i.test(s)) return 'out_for_delivery';
+  if (/delivered/i.test(s)) return 'delivered';
+  if (/alert|exception|undeliverable|returned/i.test(s)) return 'exception';
+  if (/pre-?shipment|label created|shipping label/i.test(s)) return 'pending';
+  if (/in transit|accepted|departed|arrived|processed/i.test(s)) return 'in_transit';
+  return canonicalize(eventType);
+}
+
+async function uspsTrackOne(number) {
+  const token = await getToken('usps');
+  const clean = String(number).replace(/[\s-]/g, '');
+  const url = `https://apis.usps.com/tracking/v3/tracking/${encodeURIComponent(clean)}?expand=DETAIL`;
+  const call = (t) => fetchJson(url, {
+    headers: { 'Authorization': `Bearer ${t}`, 'Accept': 'application/json' },
+  });
+  let r = await call(token);
+  if (r.status === 401) {
+    tokenCache.delete('usps');
+    r = await call(await getToken('usps'));
+  }
+  if (!r.ok) {
+    if (r.status === 404) return { number, ok: false, error: 'Invalid USPS tracking number', simulated: false };
+    throw new Error(`USPS track failed (HTTP ${r.status}): ${r.text.slice(0, 200)}`);
+  }
+  const d = r.json || {};
+  const summary = d.statusSummary || {};
+  const rawEvents = d.trackingEvents || [];
+
+  const events = rawEvents.map((e) => ({
+    ts: isoOrNull(e.eventDateTime),
+    status: mapUspsStatus(e.statusCategory, e.eventType || e.eventDescription),
+    text: e.eventDescription || e.eventType || '',
+    location: fmtLocation([e.eventCity, e.eventState || e.eventZIPCode]),
+  })).filter((e) => e.text).sort((x, y) => String(x.ts).localeCompare(String(y.ts)));
+
+  const latest = events.length ? events[events.length - 1] : null;
+  const status = mapUspsStatus(summary.statusCategory, summary.eventType);
+  const eta = isoOrNull(d.expectedDeliveryDate, d.expectedDeliveryTime, d.guaranteedDeliveryDate)
+    || (summary && isoOrNull(summary.expectedDeliveryDate));
+
+  return {
+    number,
+    ok: true,
+    status: status === 'pending' && events.length > 1 ? 'in_transit' : status,
+    status_detail: summary.eventDescription || summary.eventType || '',
+    latest_event_text: latest ? latest.text : (summary.eventDescription || ''),
+    latest_event_at: latest ? latest.ts : null,
+    estimated_delivery: eta,
+    events,
+    simulated: false,
+  };
+}
+
+async function uspsTrack(numbers) {
+  const out = [];
+  for (const n of numbers) {
+    try {
+      out.push(await uspsTrackOne(n));
+    } catch (e) {
+      out.push({ number: n, ok: false, error: e.message.slice(0, 300), simulated: false });
+    }
+  }
+  return out;
+}
+
+/* ---------------- adapters ---------------- */
+
+const ADAPTERS = {
+  ups: {
+    track: upsTrack,
+    register: async (items) => items.map((i) => ({ number: i.number, ok: true, simulated: false })),
+  },
+  fedex: {
+    track: fedexTrack,
+    register: async (items) => items.map((i) => ({ number: i.number, ok: true, simulated: false })),
+  },
+  usps: {
+    track: uspsTrack,
+    register: async (items) => items.map((i) => ({ number: i.number, ok: true, simulated: false })),
+  },
+};
+
+/* direct: route each number to the adapter matching its format */
+async function directTrack(numbers) {
+  const groups = new Map();
+  const order = [];
+  for (const n of numbers) {
+    const c = detectCarrier(n);
+    order.push({ n, c });
+    if (c && ADAPTERS[c]) {
+      if (!groups.has(c)) groups.set(c, []);
+      groups.get(c).push(n);
+    }
+  }
+  const merged = new Map();
+  for (const [c, nums] of groups) {
+    const res = await ADAPTERS[c].track(nums);
+    for (const r of res) merged.set(r.number, r);
+  }
+  return order.map(({ n, c }) => {
+    if (!c) return { number: n, ok: false, error: 'Could not detect carrier for this tracking number', simulated: false };
+    if (!ADAPTERS[c]) return { number: n, ok: false, error: `Carrier ${c.toUpperCase()} is not wired (only UPS/FedEx/USPS)`, simulated: false };
+    return merged.get(n) || { number: n, ok: false, error: 'No result returned', simulated: false };
+  });
+}
+
+function getCarrierProvider(name) {
+  const n = String(name || '').toLowerCase();
+  if (ADAPTERS[n]) {
+    return {
+      name: n,
+      simulated: false,
+      register: ADAPTERS[n].register,
+      track: ADAPTERS[n].track,
+    };
+  }
+  if (n === 'direct') {
+    return {
+      name: 'direct',
+      simulated: false,
+      register: async (items) => items.map((i) => ({ number: i.number, ok: true, simulated: false })),
+      track: directTrack,
+    };
+  }
+  return null;
+}
+
+module.exports = { getCarrierProvider, detectCarrier, mapUpsStatus, mapFedexStatus, mapUspsStatus, ADAPTERS };

package/src/providers.js

@@ -5,9 +5,14 @@
  * TRACKING_PROVIDER=17track     -> 17Track API v2 (needs SEVENTEEN_TRACK_API_KEY).
  *                                 Verify endpoint/field details against
  *                                 https://www.17track.net/en/api before going live.
+ * TRACKING_PROVIDER=direct      -> direct carrier APIs, auto-routing each number
+ *                                 by format. Needs UPS_/FEDEX_/USPS_CLIENT_ID+SECRET.
+ * TRACKING_PROVIDER=ups|fedex|usps -> force one direct carrier for all numbers.
+ * Direct adapters live in src/carriers.js.
  */
 
 const crypto = require('crypto');
+const { getCarrierProvider } = require('./carriers');
 
 const SIM_STAGES = ['pending', 'in_transit', 'in_transit', 'out_for_delivery', 'delivered'];
 const SIM_EVENTS = {
@@ -134,6 +139,9 @@ function getProvider() {
       track: t17Track,
     };
   }
+  // Direct carrier APIs (UPS / FedEx / USPS), or the 'direct' auto-router.
+  const carrier = getCarrierProvider(name);
+  if (carrier) return carrier;
   // simulated default — safe, clearly labeled, costs nothing
   const polls = new Map();
   return {