hh-shipments 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# 📦 HH Shipments — package tracker for HH Electronics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mobile-friendly web app. Paste a seller's message or upload a screenshot → tracking
+numbers are extracted automatically → shipments are tracked (UPS, USPS, FedEx, DHL)
+until delivery, with push alerts and an archive.
+
+## How intake works
+
+Personal Messenger and personal WhatsApp have **no supported API access** (Meta only
+opens inboxes to Facebook Pages and WhatsApp Business numbers), so there's no
+automatic message reading — and no passwords, cookies, or scraping involved.
+
+Instead:
+1. **Paste text** in the app → tracking numbers extracted, seller name + device
+   guessed, added automatically when confidence is high.
+2. **Upload a screenshot** → OCR runs in your browser (free, nothing uploaded
+   for processing), review, one-tap add.
+3. **iOS Shortcut** (recommended) → share a message/screenshot straight from
+   Messenger/WhatsApp into the app. See `public/SHORTCUT.html` (also linked in
+   the app's Settings). Note: a normal website **cannot** appear in the iPhone
+   share sheet — that requires a native app's share extension. The Shortcut is
+   the no-native-code equivalent.
+
+Multiple numbers per submission are supported; duplicates are rejected; uncertain
+results go to a review screen.
+
+## Quick start (local test)
+
+Needs Node.js 22.5+ (uses the built-in SQLite, zero native dependencies).
+
+```bash
+cd hh-shipments
+npm install
+npm start          # -> http://localhost:3000
+```
+
+Open the URL, create your sign-in (first visit), and you're in. Default tracking
+provider is `simulated` — clearly-labeled fake data for testing the whole flow.
+Run `npm test` for the 38-check end-to-end suite.
+
+## Going live
+
+The app must stay running 24/7 for scheduled tracking checks. It needs HTTPS
+(required for Home-Screen install, push notifications, and the Shortcut).
+
+| Option | Approx. cost | Notes |
+|---|---|---|
+| Fly.io (1 small VM + volume) | ~$5/mo | Docker deploy, good fit |
+| Hetzner VPS (CX22) | ~€4.5/mo | Full control, run Docker |
+| Render (paid) | ~$7/mo+ | Free tier sleeps — don't use free |
+
+```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 \
+  hh-shipments
+```
+
+Put it behind HTTPS (Caddy/Cloudflare Tunnel/your host's TLS).
+
+## Real tracking with 17Track (recommended)
+
+Verified 2026-10-12. 17Track's API covers UPS/USPS/FedEx/DHL with auto carrier
+detection and webhooks.
+
+1. Sign up at https://www.17track.net/en/api — Basic tier ≈ **¥299/year (~$42/yr,
+   ~$3.50/mo)** for 10,000 tracking numbers/year (far above ~50/mo need).
+2. Get your API key from the developer dashboard.
+3. Set `TRACKING_PROVIDER=17track` and `SEVENTEEN_TRACK_API_KEY` on the server.
+4. In the 17Track dashboard, add a webhook: `https://YOUR-HOST/api/webhooks/17track?secret=YOUR-SECRET`
+   and set the same value as `SEVENTEEN_TRACK_WEBHOOK_SECRET`.
+5. Verify endpoint/field details against their API docs — the integration was
+   built from public docs and the response mapping is marked for confirmation.
+
+Runner-up: EasyPost tracking API (~$0.50–1.50/mo at this volume, monthly
+billing). Avoid AfterShip (API access starts ~$109/mo). Carrier-direct APIs need
+4 separate integrations and USPS won't track third-party parcels — not viable.
+
+## WhatsApp auto-intake (optional)
+
+If the number sellers message is on the **WhatsApp Business app**, Meta supports
+running the app and the Cloud API side-by-side ("coexistence") when the number is
+onboarded through a partner that supports Business-app-number onboarding. A
+dedicated second number registered directly with the Cloud API also works.
+Personal WhatsApp numbers cannot use this — converting one requires deleting the
+WhatsApp account and the number stops working in the app.
+
+When configured, incoming 1:1 seller messages hit
+`POST /api/webhooks/whatsapp`: text messages are extracted and high-confidence
+tracking numbers are added automatically (sender name captured); photos are
+downloaded and queued for review. Webhook deliveries are idempotent and
+signature-verified. Group chats do not sync to the Cloud API.
+
+Setup:
+1. Create a Meta Business portfolio + WhatsApp Business Account; onboard the
+   number (via a coexistence-supporting partner for a Business-app number).
+2. In Meta's webhook config: callback URL `https://YOUR-HOST/api/webhooks/whatsapp`,
+   verify token = your `WHATSAPP_VERIFY_TOKEN`; subscribe to `messages`.
+3. Set `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_APP_SECRET`, and (for photo download)
+   `WHATSAPP_TOKEN` on the server.
+4. Inbound seller messages and 24h-window replies are free at typical volumes;
+   check Meta's current rate card and any partner platform fee.
+
+## iPhone setup
+
+1. Open the app's HTTPS URL in **Safari** → Share → **Add to Home Screen**.
+2. Open it from the Home Screen icon → Settings → **Enable push notifications**
+   (iOS 16.4+; alerts for out-for-delivery, delivered, exceptions, stalled).
+3. Build the Shortcut (Settings → iOS Shortcut → New token, then follow the
+   in-app guide) for one-tap intake from the share sheet.
+
+## Cost summary
+
+| Item | Cost |
+|---|---|
+| Hosting (always-on) | ~$5/mo |
+| 17Track Basic (annual) | ~$3.50/mo effective |
+| OCR (in-browser Tesseract.js) | $0 |
+| Push notifications (Web Push/VAPID) | $0 |
+| **Total** | **~$8.50/mo** |
+
+## Features
+
+- Paste / screenshot / Shortcut / manual intake; multi-number; dedupe; review queue
+- Auto carrier detection (UPS, USPS, FedEx, DHL)
+- Server-side scheduled checks (configurable interval) + 17Track webhooks
+- Push alerts: out for delivery, delivered, exceptions, no-movement stall (configurable days)
+- Dashboard: active, due today, needs attention; search by seller / number / device
+- Delivered → auto-archived (searchable); separate **Received & checked** flag
+- Optional seller, device, purchase amount, notes per shipment
+- Invalid numbers and API failures surface as clear errors with retry
+- Single-user sign-in (bcrypt), session cookies, API keys server-side only,
+  Shortcut tokens stored as hashes
+
+## Project layout
+
+```
+server.js            Express app + API + cron jobs
+src/db.js            SQLite schema (node:sqlite)
+src/extract.js       tracking-number regexes (shared server + browser)
+src/providers.js     simulated + 17track providers
+src/notify.js        web-push + notification log
+public/              mobile PWA (index.html, app.js, styles.css, sw.js, …)
+test/run-tests.js    end-to-end suite (38 checks, simulated data)
+Dockerfile           deploy image
+```
+
+## Security notes
+
+- Never enter your Facebook/WhatsApp password anywhere in this system — intake is
+  paste/upload/share only.
+- Keep `SEVENTEEN_TRACK_API_KEY` and the webhook secret in server env vars.
+- Shortcut tokens are shown once and stored hashed; revoke anytime in Settings.

package/package.json

@@ -1,6 +1,32 @@
 {
+  "dependencies": {
+    "bcryptjs": "^2.4.3",
+    "cookie-parser": "^1.4.6",
+    "express": "^4.21.2",
+    "multer": "^1.4.5-lts.1",
+    "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.",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "main": "server.js",
   "name": "hh-shipments",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "scripts": {
+    "start": "node server.js",
+    "test": "node test/run-tests.js"
+  },
+  "type": "commonjs",
+  "version": "0.1.0",
+  "bin": {
+    "hh-shipments": "server.js"
+  },
+  "files": [
+    "server.js",
+    "src/",
+    "public/",
+    "README.md",
+    "SHORTCUT.md"
+  ]
+}

package/public/SHORTCUT.html

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>HH Shipments — iOS Shortcut setup</title>
+<link rel="stylesheet" href="/styles.css">
+</head>
+<body>
+<div id="app">
+<section class="view">
+<header class="topbar"><a href="/" class="link">‹ Back</a><h1>Shortcut setup</h1></header>
+<div class="card">
+<h3>Why a Shortcut?</h3>
+<p>iPhones don't let normal websites appear in the share sheet — that requires a native app. This Shortcut does the same job with no native code: share a screenshot or text from any app, and it lands in HH Shipments.</p>
+</div>
+<div class="card">
+<h3>Step 1 — Get a token</h3>
+<p>1. In HH Shipments go to <b>Settings → iOS Shortcut</b>.<br>
+2. Type a name (e.g. <i>iPhone</i>) and tap <b>New token</b>.<br>
+3. <b>Copy the token</b> — it's shown once.</p>
+</div>
+<div class="card">
+<h3>Step 2 — Build the Shortcut</h3>
+<p>1. Open the <b>Shortcuts</b> app → <b>+</b> → name it <b>Send to HH Shipments</b>.<br>
+2. Tap the <b>ⓘ</b> at the bottom → turn on <b>Show in Share Sheet</b> → under accepted types enable <b>Images</b> and <b>Text</b>.<br>
+3. Add action <b>If</b> → set to <i>Shortcut Input</i> <b>is</b> <i>Image</i>.<br>
+4. Inside <b>If</b>: add <b>Get Contents of URL</b>:<br>
+&nbsp;&nbsp;• URL: <code>https://YOUR-HOST/api/intake</code> (your app's address)<br>
+&nbsp;&nbsp;• Method: <b>POST</b><br>
+&nbsp;&nbsp;• Headers → Add: <code>Authorization</code> = <code>Bearer PASTE-YOUR-TOKEN</code><br>
+&nbsp;&nbsp;• Request Body: <b>Form</b> → Add field <code>image</code> (File) = <b>Shortcut Input</b><br>
+5. Inside <b>Otherwise</b>: add another <b>Get Contents of URL</b> with the same URL/method/header, but Request Body Form field <code>text</code> (Text) = <b>Shortcut Input</b>.<br>
+6. After the If block add <b>Show Notification</b> with text <i>Sent to HH Shipments</i>.<br>
+7. Tap <b>Done</b>.</p>
+</div>
+<div class="card">
+<h3>Step 3 — Use it</h3>
+<p>In Messenger or WhatsApp: long-press a tracking-number message → <b>Share</b> → <b>Send to HH Shipments</b>. For a screenshot: take it, open Photos → Share → <b>Send to HH Shipments</b>.</p>
+<p>Then open HH Shipments → you'll see a <b>screenshot waiting for review</b> banner. Tap it, hit extract, confirm — done. Pasted text is extracted and added automatically when the app is confident.</p>
+</div>
+</section>
+</div>
+</body>
+</html>

package/public/app.js

@@ -0,0 +1,358 @@
+/* HH Shipments frontend */
+const $ = (id) => document.getElementById(id);
+const api = {
+  async req(method, url, body) {
+    const r = await fetch(url, {
+      method,
+      headers: body ? { 'Content-Type': 'application/json' } : {},
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    if (r.status === 401 && !url.includes('/login') && !url.includes('/setup')) { showAuth(); return null; }
+    const j = await r.json().catch(() => ({}));
+    if (!r.ok) throw new Error(j.error || ('HTTP ' + r.status));
+    return j;
+  },
+  get: (u) => api.req('GET', u),
+  post: (u, b) => api.req('POST', u, b),
+  patch: (u, b) => api.req('PATCH', u, b),
+  del: (u) => api.req('DELETE', u),
+};
+
+const STATUS_LABEL = { pending: 'Label created', in_transit: 'In transit', out_for_delivery: 'Out for delivery', delivered: 'Delivered', exception: 'Exception', invalid: 'Invalid', unknown: 'Unknown' };
+const CARRIER_LINK = {
+  ups: (n) => `https://www.ups.com/track?tracknum=${n}`,
+  usps: (n) => `https://tools.usps.com/go/TrackConfirmAction?tLabels=${n}`,
+  fedex: (n) => `https://www.fedex.com/fedextrack/?trknbr=${n}`,
+  dhl: (n) => `https://www.dhl.com/us-en/home/tracking/tracking-express.html?submit=1&tracking-id=${n}`,
+};
+
+function shipCard(s) {
+  const b = document.createElement('button');
+  b.className = 'ship';
+  const sim = s.simulated ? ' <span class="sim-badge">SIMULATED</span>' : '';
+  b.innerHTML = `<b>${esc(s.tracking_number)}</b>${sim}
+    <div class="meta">${esc(s.carrier.toUpperCase())}${s.seller_name ? ' · ' + esc(s.seller_name) : ''}${s.device ? ' · ' + esc(s.device) : ''}</div>
+    <div class="meta">${esc(s.latest_event_text || 'Awaiting first tracking update…')}</div>
+    <span class="pill ${esc(s.status)}">${esc(STATUS_LABEL[s.status] || s.status)}</span>
+    ${s.received_checked_at ? '<span class="pill delivered">✓ Received</span>' : ''}`;
+  b.onclick = () => openDetail(s.id);
+  return b;
+}
+function esc(s) { return String(s == null ? '' : s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c])); }
+function money(c) { return c == null ? '' : '$' + (c / 100).toFixed(2); }
+
+/* ---------- views ---------- */
+function showView(id) {
+  document.querySelectorAll('.view').forEach((v) => (v.hidden = true));
+  $(id).hidden = false;
+  document.querySelectorAll('#tabbar button').forEach((b) => b.classList.toggle('active', b.dataset.view === id));
+  window.scrollTo(0, 0);
+}
+function showAuth() {
+  showView('view-auth');
+  $('tabbar').hidden = true;
+}
+function showApp() {
+  $('tabbar').hidden = false;
+  showView('view-dash');
+  loadDash();
+}
+
+/* ---------- auth ---------- */
+async function initAuth() {
+  const { needed } = await api.get('/api/setup-needed');
+  $('auth-setup').hidden = !needed;
+  $('auth-login').hidden = needed;
+  showAuth();
+  $('btn-setup').onclick = async () => {
+    $('auth-err').textContent = '';
+    try { await api.post('/api/setup', { email: $('setup-email').value, password: $('setup-pass').value }); enterApp(); }
+    catch (e) { $('auth-err').textContent = e.message; }
+  };
+  $('btn-login').onclick = async () => {
+    $('auth-err').textContent = '';
+    try { await api.post('/api/login', { email: $('login-email').value, password: $('login-pass').value }); enterApp(); }
+    catch (e) { $('auth-err').textContent = e.message; }
+  };
+}
+async function enterApp() {
+  const me = await api.get('/api/me');
+  if (!me) return initAuth();
+  $('sim-badge').hidden = !me.simulated;
+  showApp();
+}
+
+/* ---------- dashboard ---------- */
+async function loadDash() {
+  const d = await api.get('/api/dashboard');
+  if (!d) return;
+  $('st-active').textContent = d.active;
+  $('st-today').textContent = d.today;
+  $('st-attn').textContent = d.attention;
+  $('st-arch').textContent = d.archived;
+  if (d.pending_intake > 0) {
+    $('intake-nudge').hidden = false;
+    $('intake-nudge').innerHTML = `📸 <b>${d.pending_intake}</b> screenshot${d.pending_intake > 1 ? 's' : ''} waiting for review — <a href="#" id="go-review" class="link">review now</a>`;
+    $('go-review').onclick = (e) => { e.preventDefault(); showView('view-add'); activateTab('photo'); loadPending(); };
+  } else $('intake-nudge').hidden = true;
+
+  const q = $('search').value.trim();
+  const attn = await api.get('/api/shipments?view=attention' + (q ? '&q=' + encodeURIComponent(q) : ''));
+  $('sec-attn-h').hidden = !attn.shipments.length;
+  $('list-attn').innerHTML = '';
+  attn.shipments.forEach((s) => $('list-attn').appendChild(shipCard(s)));
+
+  const act = await api.get('/api/shipments?view=active' + (q ? '&q=' + encodeURIComponent(q) : ''));
+  $('list-active').innerHTML = act.shipments.length ? '' : '<p class="muted">No active shipments.</p>';
+  act.shipments.forEach((s) => $('list-active').appendChild(shipCard(s)));
+}
+
+/* ---------- add: paste ---------- */
+async function runQuick(text, targetEl, preset) {
+  targetEl.innerHTML = '<p class="muted">Extracting…</p>';
+  try {
+    const r = await api.post('/api/intake/quick', { text, seller_name: preset && preset.seller, device: preset && preset.device });
+    let html = '';
+    r.added.forEach((a) => { html += `<div class="review">✅ Added <b>${esc(a.number)}</b> (${esc(a.carrier.toUpperCase())})${r.simulated ? ' <span class="sim-badge">SIMULATED</span>' : ''}</div>`; });
+    r.duplicates.forEach((n) => { html += `<div class="review">⛔ <b>${esc(n)}</b> is already tracked — skipped.</div>`; });
+    r.needs_review.forEach((c, i) => {
+      html += `<div class="review" id="rev-${i}"><span class="warn">Needs review</span> — <b>${esc(c.number)}</b> (${esc(c.carrier.toUpperCase())}, ${esc(c.confidence)} confidence)${c.error ? ' — ' + esc(c.error) : ''}
+        <div class="row"><button class="secondary" data-add="${i}">Add anyway</button></div></div>`;
+    });
+    if (r.context && (r.context.seller_name || r.context.device)) {
+      html = `<div class="review">📝 Detected: ${esc(r.context.seller_name || '—')} · ${esc(r.context.device || '—')}</div>` + html;
+    }
+    if (!r.added.length && !r.needs_review.length && !r.duplicates.length) html = '<div class="review">No tracking numbers found in that text.</div>';
+    targetEl.innerHTML = html;
+    targetEl.querySelectorAll('[data-add]').forEach((btn) => {
+      btn.onclick = async () => {
+        const c = r.needs_review[+btn.dataset.add];
+        try {
+          const s = await api.post('/api/shipments', { tracking_number: c.number, carrier: c.carrier, seller_name: (r.context || {}).seller_name, device: (r.context || {}).device, source: 'paste' });
+          $('rev-' + btn.dataset.add).innerHTML = `✅ Added <b>${esc(s.number)}</b>`;
+        } catch (e) { $('rev-' + btn.dataset.add).innerHTML = `<span class="error">${esc(e.message)}</span>`; }
+      };
+    });
+    loadDashCounts();
+  } catch (e) { targetEl.innerHTML = `<p class="error">${esc(e.message)}</p>`; }
+}
+async function loadDashCounts() { /* counts refresh on next dashboard visit */ }
+
+/* ---------- add: photo / OCR ---------- */
+let tesseractLoading = null;
+function loadTesseract() {
+  if (window.Tesseract) return Promise.resolve();
+  if (tesseractLoading) return tesseractLoading;
+  tesseractLoading = new Promise((resolve, reject) => {
+    const s = document.createElement('script');
+    s.src = 'https://cdn.jsdelivr.net/npm/tesseract.js@6/dist/tesseract.min.js';
+    s.onload = resolve; s.onerror = () => reject(new Error('Could not load OCR engine (need internet once)'));
+    document.head.appendChild(s);
+  });
+  return tesseractLoading;
+}
+
+async function ocrFile(file, statusEl) {
+  await loadTesseract();
+  statusEl.textContent = 'Reading screenshot…';
+  const { data } = await Tesseract.recognize(file, 'eng', { logger: (m) => { if (m.status === 'recognizing text') statusEl.textContent = `Reading… ${Math.round(m.progress * 100)}%`; } });
+  statusEl.textContent = '';
+  return data.text || '';
+}
+
+$('photo-input').addEventListener('change', async (e) => {
+  const f = e.target.files[0];
+  if (!f) return;
+  try {
+    const text = await ocrFile(f, $('ocr-status'));
+    // Upload original for reference, then run the quick flow on OCR text
+    const fd = new FormData();
+    fd.append('image', f);
+    const up = await fetch('/api/intake/image', { method: 'POST', body: fd });
+    if (!up.ok) throw new Error('upload failed');
+    await runQuick(text, $('photo-result'));
+    loadPending();
+  } catch (err) { $('ocr-status').textContent = ''; $('photo-result').innerHTML = `<p class="error">${esc(err.message)}</p>`; }
+  e.target.value = '';
+});
+
+async function loadPending() {
+  const r = await api.get('/api/intake/pending');
+  if (!r) return;
+  $('pending-list').innerHTML = r.items.length ? '' : '<p class="muted">None.</p>';
+  r.items.forEach((it) => {
+    const b = document.createElement('button');
+    b.className = 'ship';
+    b.innerHTML = `<b>📸 Screenshot</b><div class="meta">${esc(it.created_at)}</div><span class="pill pending">Tap to extract</span>`;
+    b.onclick = () => reviewPendingImage(it.id);
+    $('pending-list').appendChild(b);
+  });
+}
+
+async function reviewPendingImage(id) {
+  $('photo-result').innerHTML = `<img src="/api/intake/image/${id}" style="max-width:100%;border-radius:10px"><p class="muted">Extracting…</p>`;
+  try {
+    await loadTesseract();
+    const { data } = await Tesseract.recognize(`/api/intake/image/${id}`, 'eng');
+    await api.patch('/api/intake/' + id, { state: 'reviewed' });
+    await runQuick(data.text || '', $('photo-result'));
+    loadPending();
+  } catch (e) { $('photo-result').innerHTML = `<p class="error">${esc(e.message)}</p>`; }
+}
+
+/* ---------- detail ---------- */
+let detailId = null;
+async function openDetail(id) {
+  detailId = id;
+  const s = await api.get('/api/shipments/' + id);
+  if (!s) return;
+  $('d-number').textContent = s.tracking_number;
+  $('d-sim').hidden = !s.simulated;
+  $('d-carrier').textContent = s.carrier.toUpperCase() + ' · added ' + new Date(s.created_at + 'Z').toLocaleDateString();
+  $('d-status').innerHTML = `<span class="pill ${esc(s.status)}">${esc(STATUS_LABEL[s.status] || s.status)}</span>`;
+  $('d-event').textContent = s.latest_event_text || 'Awaiting first tracking update…';
+  $('d-eta').textContent = s.estimated_delivery ? 'Est. delivery: ' + s.estimated_delivery : '';
+  $('d-checked').textContent = s.last_checked_at ? 'Last checked: ' + new Date(s.last_checked_at + 'Z').toLocaleString() : '';
+  $('d-carrierlink').href = (CARRIER_LINK[s.carrier] || ((n) => '#'))(s.tracking_number);
+  $('d-seller').value = s.seller_name || '';
+  $('d-device').value = s.device || '';
+  $('d-amount').value = s.amount_cents != null ? (s.amount_cents / 100).toFixed(2) : '';
+  $('d-notes').value = s.notes || '';
+  $('btn-received').textContent = s.received_checked_at ? '✅ Received & checked (' + new Date(s.received_checked_at + 'Z').toLocaleDateString() + ') — tap to undo' : '✅ Mark received & checked';
+  $('btn-received').dataset.done = s.received_checked_at ? '1' : '';
+  $('d-events').innerHTML = s.events.length ? '' : '<p class="muted">No events yet.</p>';
+  s.events.forEach((e) => {
+    const d = document.createElement('div');
+    d.className = 'ev';
+    d.innerHTML = `<div>${esc(e.text)}${e.simulated ? ' <span class="sim-badge">SIM</span>' : ''}</div><div class="t">${esc(e.ts)}${e.location ? ' · ' + esc(e.location) : ''}</div>`;
+    $('d-events').appendChild(d);
+  });
+  showView('view-detail');
+}
+
+/* ---------- archive ---------- */
+async function loadArchive() {
+  const q = $('search-arch').value.trim();
+  const r = await api.get('/api/shipments?view=archived' + (q ? '&q=' + encodeURIComponent(q) : ''));
+  if (!r) return;
+  $('list-arch').innerHTML = r.shipments.length ? '' : '<p class="muted">Nothing delivered yet.</p>';
+  r.shipments.forEach((s) => $('list-arch').appendChild(shipCard(s)));
+}
+
+/* ---------- settings ---------- */
+async function loadSettings() {
+  const s = await api.get('/api/settings');
+  if (!s) return;
+  $('s-stale').value = s.stale_days;
+  $('s-poll').value = s.poll_hours;
+  $('s-notif').checked = s.notifications_enabled;
+  const t = await api.get('/api/ingest-tokens');
+  $('token-list').innerHTML = t.tokens.length ? '' : '<p class="muted">No tokens yet.</p>';
+  t.tokens.forEach((tok) => {
+    const d = document.createElement('div');
+    d.className = 'tokenrow';
+    d.innerHTML = `<span>${esc(tok.name)} <span class="muted">${tok.last_used_at ? '· used ' + esc(tok.last_used_at) : '· never used'}</span></span>`;
+    const del = document.createElement('button');
+    del.className = 'link'; del.textContent = 'Delete';
+    del.onclick = async () => { await api.del('/api/ingest-tokens/' + tok.id); loadSettings(); };
+    d.appendChild(del);
+    $('token-list').appendChild(d);
+  });
+  const n = await api.get('/api/notifications');
+  $('notif-list').innerHTML = n.notifications.length ? '' : '<p class="muted">No alerts yet.</p>';
+  n.notifications.slice(0, 10).forEach((x) => {
+    const d = document.createElement('div');
+    d.className = 'review';
+    d.innerHTML = `<b>${esc(x.title)}</b><div class="muted">${esc(x.body)}</div><div class="muted">${esc(x.sent_at)}${x.simulated ? ' · <span class="sim-badge">SIM</span>' : ''} · push ${x.push_ok ? 'sent' : 'not sent (' + esc(x.push_error || '?') + ')'}</div>`;
+    $('notif-list').appendChild(d);
+  });
+}
+
+/* ---------- push ---------- */
+async function enablePush() {
+  $('push-msg').textContent = '';
+  try {
+    if (!('serviceWorker' in navigator) || !('PushManager' in window)) throw new Error('Push not supported in this browser');
+    const reg = await navigator.serviceWorker.ready;
+    const { key } = await api.get('/api/push/vapid-key');
+    const sub = await reg.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: urlB64(key) });
+    await api.post('/api/push/subscribe', sub.toJSON());
+    $('push-msg').textContent = '✅ Notifications enabled on this device.';
+  } catch (e) { $('push-msg').textContent = 'Could not enable: ' + e.message; }
+}
+function urlB64(s) {
+  const pad = '='.repeat((4 - (s.length % 4)) % 4);
+  const b64 = (s + pad).replace(/-/g, '+').replace(/_/g, '/');
+  const raw = atob(b64);
+  const out = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i);
+  return out;
+}
+
+/* ---------- wiring ---------- */
+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));
+}
+document.querySelectorAll('.tab').forEach((t) => (t.onclick = () => activateTab(t.dataset.tab)));
+document.querySelectorAll('#tabbar button').forEach((b) => {
+  b.onclick = () => {
+    showView(b.dataset.view);
+    if (b.dataset.view === 'view-dash') loadDash();
+    if (b.dataset.view === 'view-archive') loadArchive();
+    if (b.dataset.view === 'view-settings') loadSettings();
+    if (b.dataset.view === 'view-add') loadPending();
+  };
+});
+let searchT;
+$('search').addEventListener('input', () => { clearTimeout(searchT); searchT = setTimeout(loadDash, 400); });
+let searchAT;
+$('search-arch').addEventListener('input', () => { clearTimeout(searchAT); searchAT = setTimeout(loadArchive, 400); });
+$('btn-quick').onclick = () => runQuick($('paste-text').value, $('quick-result'));
+$('btn-manual').onclick = async () => {
+  $('manual-err').textContent = '';
+  try {
+    await api.post('/api/shipments', { tracking_number: $('m-number').value, seller_name: $('m-seller').value, device: $('m-device').value, amount: $('m-amount').value, source: 'manual' });
+    $('m-number').value = $('m-seller').value = $('m-device').value = $('m-amount').value = '';
+    showView('view-dash'); loadDash();
+  } catch (e) { $('manual-err').textContent = e.message; }
+};
+$('btn-back').onclick = () => { showView('view-dash'); loadDash(); };
+$('btn-save-detail').onclick = async () => {
+  await api.patch('/api/shipments/' + detailId, { seller_name: $('d-seller').value, device: $('d-device').value, amount: $('d-amount').value, notes: $('d-notes').value });
+  openDetail(detailId);
+};
+$('btn-received').onclick = async () => {
+  await api.patch('/api/shipments/' + detailId, { received_checked: !$('btn-received').dataset.done });
+  openDetail(detailId);
+};
+$('btn-delete').onclick = async () => {
+  if (!confirm('Delete this shipment and its history?')) return;
+  await api.del('/api/shipments/' + detailId);
+  showView('view-dash'); loadDash();
+};
+$('btn-save-settings').onclick = async () => {
+  $('settings-msg').textContent = '';
+  try {
+    await api.patch('/api/settings', { stale_days: $('s-stale').value, poll_hours: $('s-poll').value, notifications_enabled: $('s-notif').checked });
+    $('settings-msg').textContent = 'Saved.';
+  } catch (e) { $('settings-msg').textContent = e.message; }
+};
+$('btn-poll-now').onclick = async () => {
+  $('settings-msg').textContent = 'Checking…';
+  const r = await api.post('/api/poll-now', {});
+  $('settings-msg').textContent = r && r.error ? 'Error: ' + r.error : `Checked ${r.checked || 0} shipment(s).`;
+};
+$('btn-push').onclick = enablePush;
+$('btn-token').onclick = async () => {
+  const name = $('token-name').value.trim();
+  if (!name) return;
+  const r = await api.post('/api/ingest-tokens', { name });
+  $('token-result').innerHTML = `<p><b>Token (copy now — shown once):</b></p><code class="token">${esc(r.token)}</code>`;
+  $('token-name').value = '';
+  loadSettings();
+};
+$('btn-logout').onclick = async () => { await api.post('/api/logout', {}); initAuth(); };
+
+if ('serviceWorker' in navigator) navigator.serviceWorker.register('/sw.js').catch(() => {});
+initAuth();