hh-shipments 0.3.28 → 0.3.29

package/package.json

@@ -19,7 +19,7 @@
     "test": "node test/run-extract-tests.js && node test/run-tests.js && node test/run-carriers-tests.js"
   },
   "type": "commonjs",
-  "version": "0.3.28",
+  "version": "0.3.29",
   "bin": {
     "hh-shipments": "server.js"
   },

package/public/app.js

@@ -154,10 +154,16 @@ async function runQuick(text, targetEl, preset) {
 }
 
 // When OCR finds no tracking number, show the raw read so the user can
-// spot the misread and type it in manually.
-function showOcrRead(targetEl, text) {
+// spot the misread and type it in manually. Includes which OCR stage
+// produced the text and the app build, so a failure is diagnosable from
+// the screenshot itself — no more blind "it didn't work".
+function appBuild() {
+  return (document.querySelector('meta[name="app-version"]') || {}).content || '?';
+}
+function showOcrRead(targetEl, text, stage) {
   const t = (text || '').trim();
-  targetEl.innerHTML += `<details class="ocr-read"><summary>What I read from the picture</summary><pre>${esc(t || '(nothing readable)')}</pre></details>`;
+  const diag = stage ? ` <span class="muted">· read via ${esc(stage)} · build ${esc(appBuild())}</span>` : '';
+  targetEl.innerHTML += `<details class="ocr-read"><summary>What I read from the picture</summary>${diag}<pre>${esc(t || '(nothing readable)')}</pre></details>`;
 }
 async function loadDashCounts() { /* counts refresh on next dashboard visit */ }
 
@@ -179,17 +185,22 @@ function loadTesseract() {
 // - Chat screenshots (dark): invert, PSM 6 (uniform block)
 // - Labels (light): crop to tracking zone, upscale, PSM 6
 // - Falls back to full-image PSM 3 if targeted fails
+// Returns { text, stage } — the stage that produced the text is surfaced in
+// the UI so a failed read is diagnosable from a screenshot (which pass ran,
+// which build), instead of another blind "it didn't work".
 async function ocrFile(file, statusEl) {
   await loadTesseract();
-  statusEl.textContent = 'Reading screenshot…';
+  if (statusEl) statusEl.textContent = 'Reading screenshot…';
   const isDark = await isDarkImage(file);
   file = isDark ? await invertImage(file) : file;
 
   const log = (m) => { if (m.status === 'recognizing text' && statusEl) statusEl.textContent = `Reading… ${Math.round(m.progress * 100)}%`; };
+  const ANCHOR = /(1Z|12|IZ|17)\s*[0-9A-Z)\]}(\[{|!]/i;
 
   // Pass 1: targeted — for labels, crop to the tracking-number zone (bottom 45%)
   // and upscale for Tesseract. For chats, use the full image.
-  let bestText = '';
+  let bestText = '', bestStage = 'none';
+  const consider = (t, stage) => { if (t && t.length > bestText.length) { bestText = t; bestStage = stage; } };
   if (!isDark) {
     try {
       const zoned = await cropAndUpscale(file, 0, 0.55, 1, 0.45, 2);
@@ -197,36 +208,61 @@ async function ocrFile(file, statusEl) {
         logger: log,
         tessedit_pageseg_mode: '6', // uniform block of text
       });
-      bestText = r1.data.text || '';
+      const t1 = r1.data.text || '';
+      consider(t1, 'zone');
       // If the zone has a plausible tracking number, we're done
-      if (/(1Z|12|IZ|17)\s*[0-9A-Z)\]}(\[{|!]/i.test(bestText)) {
+      if (ANCHOR.test(t1)) {
         if (statusEl) statusEl.textContent = '';
-        return bestText;
+        return { text: t1, stage: 'zone' };
       }
     } catch (e) {}
   }
 
+  // Pass 1b: tracking-line band SWEEP — the printed "TRACKING #:" line sits
+  // in a narrow band whose vertical position shifts with photo framing and
+  // angle. A single fixed band missed real labels, so sweep overlapping
+  // bands; the first whose OCR contains the tracking anchor wins.
+  // Verified on a real label: the center band alone read
+  // "TRACKING # 12 GE2 384 03 3726 7306" off a photo the other passes
+  // scored as "1 1 (1".
+  if (!isDark) {
+    const bands = [0.50, 0.44, 0.56, 0.38, 0.62];
+    for (const fy of bands) {
+      try {
+        const band = await cropAndUpscale(file, 0.03, fy, 0.87, 0.12, 3);
+        const rb = await Tesseract.recognize(band, 'eng', {
+          logger: log,
+          tessedit_pageseg_mode: '6',
+        });
+        const tb = rb.data.text || '';
+        consider(tb, 'band');
+        if (ANCHOR.test(tb)) {
+          if (statusEl) statusEl.textContent = '';
+          return { text: tb, stage: 'band' };
+        }
+      } catch (e) {}
+    }
+  }
+
   // Pass 2: full image with PSM 6
   try {
     const r2 = await Tesseract.recognize(file, 'eng', {
       logger: log,
       tessedit_pageseg_mode: '6',
     });
-    const t2 = r2.data.text || '';
-    if (t2.length > bestText.length) bestText = t2;
+    consider(r2.data.text || '', 'full');
   } catch (e) {}
 
   // Pass 3: fallback to default PSM 3 if we got nothing useful
   if (!bestText || bestText.trim().length < 10) {
     try {
       const r3 = await Tesseract.recognize(file, 'eng', { logger: log });
-      const t3 = r3.data.text || '';
-      if (t3.length > bestText.length) bestText = t3;
+      consider(r3.data.text || '', 'psm3');
     } catch (e) {}
   }
 
   if (statusEl) statusEl.textContent = '';
-  return bestText;
+  return { text: bestText, stage: bestStage };
 }
 
 async function isDarkImage(file) {
@@ -300,7 +336,7 @@ async function handlePhotoFile(f) {
     target.innerHTML = `<div class="review"><img src="${url}" style="max-width:100%;border-radius:10px"><p class="muted" id="ocr-live-photo">📷 Scanning barcode…</p></div>`;
     const live = $('ocr-live-photo');
     const barcode = await decodeBarcode(f);
-    let text, preset, topText = null, upIdPhoto = null;
+    let text, preset, topText = null, upIdPhoto = null, ocrStage = null;
     if (barcode) {
       text = barcode;
       if (live) live.textContent = '📷 Barcode read — reading sender…';
@@ -315,7 +351,9 @@ async function handlePhotoFile(f) {
       preset = topText ? { labelText: topText } : undefined;
     } else {
       if (live) live.textContent = '📖 Reading screenshot…';
-      text = await ocrFile(f, $('ocr-status'));
+      const ocrRes = await ocrFile(f, $('ocr-status'));
+      text = ocrRes.text;
+      ocrStage = ocrRes.stage;
       // Upload original for reference, then run the quick flow on OCR text
       const fd = new FormData();
       fd.append('image', f);
@@ -330,7 +368,7 @@ async function handlePhotoFile(f) {
     if (upIdPhoto) api.patch('/api/intake/' + upIdPhoto, { state: 'reviewed' }).catch(() => {});
     if (looksLikeAppScreenshot(topText || text)) $('photo-result').insertAdjacentHTML('afterbegin', '<p class="warn">⚠️ This looks like a screenshot of the app itself — choose the label photo directly for best results.</p>');
     if (barcode && r && r.added.length) $('photo-result').insertAdjacentHTML('afterbegin', '<p class="muted">📷 Read from the barcode — checksum verified.</p>');
-    if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead($('photo-result'), text);
+    if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead($('photo-result'), text, barcode ? 'barcode' : ocrStage);
     loadPending();
   } catch (err) { $('ocr-status').textContent = ''; $('photo-result').innerHTML = `<p class="error">${esc(err.message)}</p>`; }
 }
@@ -419,7 +457,7 @@ async function ocrTopStrip(origFile, statusEl) {
     bmp.close();
     const blob = await new Promise((res) => canvas.toBlob(res, 'image/jpeg', 0.92));
     if (!blob) return null;
-    const p = ocrFile(new File([blob], 'top.jpg', { type: 'image/jpeg' }), statusEl);
+    const p = ocrFile(new File([blob], 'top.jpg', { type: 'image/jpeg' }), statusEl).then((r) => r.text);
     return await Promise.race([p, new Promise((_, rej) => setTimeout(() => rej(new Error('top-strip timeout')), 25000))]);
   } catch (e) { return null; }
 }
@@ -537,7 +575,7 @@ async function handlePastedImageFile(f) {
     const live = $('ocr-live');
     // 1) Barcode first: checksum-verified, essentially never wrong
     const barcode = await decodeBarcode(f);
-    let text;
+    let text, ocrStage = null;
     if (barcode) {
       text = barcode;
       if (live) live.textContent = '📷 Barcode read — reading sender…';
@@ -557,17 +595,18 @@ async function handlePastedImageFile(f) {
       if (upId) api.patch('/api/intake/' + upId, { state: 'reviewed' }).catch(() => {});
       if (looksLikeAppScreenshot(topText)) target.insertAdjacentHTML('afterbegin', '<p class="warn">⚠️ This looks like a screenshot of the app itself — paste the label photo directly for best results.</p>');
       if (r && r.added.length) target.insertAdjacentHTML('afterbegin', '<p class="muted">📷 Read from the barcode — checksum verified.</p>');
-      if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead(target, text);
+      if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead(target, text, 'barcode');
       return;
     }
     // 2) Fallback: OCR the printed text (+ the sender strip for the name,
     // in parallel — the number crop usually excludes the sender block)
     if (live) live.textContent = '📖 Reading screenshot…';
-    const [ocrText, topTextFb] = await Promise.all([
+    const [ocrRes, topTextFb] = await Promise.all([
       ocrFile(f, $('ocr-status-paste')),
       ocrTopStrip(orig, $('ocr-status-paste')),
     ]);
-    text = ocrText;
+    text = ocrRes.text;
+    ocrStage = ocrRes.stage;
     if (live) live.textContent = '⬆️ Uploading…';
     const fd = new FormData();
     fd.append('image', f);
@@ -581,7 +620,7 @@ async function handlePastedImageFile(f) {
     // Paste flow already handled this image — don't leave it nagging in the review queue.
     if (upId2) api.patch('/api/intake/' + upId2, { state: 'reviewed' }).catch(() => {});
     if (looksLikeAppScreenshot(text)) target.insertAdjacentHTML('afterbegin', '<p class="warn">⚠️ This looks like a screenshot of the app itself — paste the label photo directly for best results.</p>');
-    if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead(target, text);
+    if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead(target, text, ocrStage);
   } catch (err) { $('ocr-status-paste').textContent = ''; target.innerHTML = `<p class="error">${esc(err.message)}</p>`; }
 }
 
@@ -638,7 +677,7 @@ async function reviewPendingImage(id) {
     const resp = await fetch(`/api/intake/image/${id}`);
     const blob = await resp.blob();
     const file = new File([blob], 'pending.jpg', { type: blob.type || 'image/jpeg' });
-    const text = await ocrFile(file, null);
+    const { text } = await ocrFile(file, null);
     await api.patch('/api/intake/' + id, { state: 'reviewed' });
     await runQuick(text, $('photo-result'));
     loadPending();

package/public/extract.js

@@ -81,11 +81,48 @@
       var num = /^1Z[0-9A-Z]{16}$/.test(ups) ? ups : repairUpsZ(ups);
       if (num && !seen[num]) {
         seen[num] = true;
-        found.push({ number: num, carrier: 'ups', confidence: conf, ocr_fixed: num !== ups });
+        found.push({ number: num, carrier: 'ups', confidence: conf, ocr_fixed: num !== ups, ocr_path: true });
       }
     }
   }
 
+  // ---- UPS Mod-10 check digit ----
+  // Every real 1Z number carries a check digit (last char). This is the
+  // arbiter when blurry OCR produces 2↔Z / O↔0 style ambiguity: the wrong
+  // read fails the check, the right one passes. Verified against two real
+  // shipped labels (1Z1XJ5390328621735, 1ZGE23840337267306).
+  // Letter values: (alphabetical index + 1) mod 10 → A=2 … I=0, J=1 … Z=7.
+  var UPS_LETTER_VAL = {};
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('').forEach(function (ch, i) { UPS_LETTER_VAL[ch] = (i + 2) % 10; });
+  function upsCheckDigitOk(num) {
+    var n = String(num).toUpperCase();
+    if (!/^1Z[0-9A-Z]{16}$/.test(n)) return false;
+    var body = n.slice(2, 17); // 15 chars after 1Z, excluding check digit
+    var vals = [];
+    for (var i = 0; i < body.length; i++) {
+      var ch = body[i];
+      vals.push(ch >= '0' && ch <= '9' ? +ch : UPS_LETTER_VAL[ch]);
+    }
+    var odd = 0, even = 0;
+    for (var j = 0; j < vals.length; j++) { if (j % 2 === 0) odd += vals[j]; else even += vals[j]; }
+    var check = (10 - ((odd + even * 2) % 10)) % 10;
+    return check === +n[17];
+  }
+  // Try single-character OCR-confusion swaps until the check digit passes.
+  // A repair that validates is error correction, not invention.
+  var UPS_CHECK_CONFUSIONS = { 'Z': '2', '2': 'Z', 'O': '0', '0': 'O', 'I': '1', '1': 'I', 'S': '5', '5': 'S', 'B': '8', '8': 'B', 'G': '6', '6': 'G', 'A': '4', '4': 'A' };
+  function repairUpsCheckDigit(num) {
+    var upper = String(num).toUpperCase();
+    for (var i = 2; i < 18; i++) {
+      var rep = UPS_CHECK_CONFUSIONS[upper[i]];
+      if (!rep) continue;
+      var cand = upper.slice(0, i) + rep + upper.slice(i + 1);
+      if (!UPS_STRICT.test(cand)) continue;
+      if (upsCheckDigitOk(cand)) return cand;
+    }
+    return null;
+  }
+
   function extractTrackingNumbers(text) {
     var found = [];
     var seen = {};
@@ -107,6 +144,21 @@
     spacedDigitGroupsIn(text, found, seen, 'medium');
     // 2) OCR-tolerant recovery pass
     extractOcrTolerant(text, found, seen);
+    // 3) UPS check-digit gate: a 1Z candidate that fails the Mod-10 check is
+    // an OCR misread (2↔Z etc.). Repair it via confusion swaps when one
+    // validates; otherwise demote to review — never auto-add a wrong number.
+    for (var i = 0; i < found.length; i++) {
+      var c = found[i];
+      if (c.carrier !== 'ups' || c.confidence === 'low') continue;
+      if (!/^1Z[0-9A-Z]{16}$/i.test(c.number)) continue;
+      if (upsCheckDigitOk(c.number)) continue;
+      var fixed = (c.ocr_fixed || c.ocr_path) ? repairUpsCheckDigit(c.number) : null;
+      if (fixed) {
+        if (seen[fixed]) { found.splice(i, 1); i--; } // another pass already found it
+        else { seen[fixed] = true; c.number = fixed; c.ocr_fixed = true; }
+      }
+      else c.confidence = 'medium';
+    }
     var rank = { high: 0, medium: 1, low: 2 };
     found.sort(function (a, b) { return rank[a.confidence] - rank[b.confidence]; });
     return found;

package/public/index.html

@@ -4,7 +4,7 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
 <meta name="theme-color" content="#0a84ff">
-<meta name="app-version" content="0.3.25">
+<meta name="app-version" content="__APP_VERSION__">
 <title>HH Shipments</title>
 <link rel="manifest" href="/manifest.webmanifest">
 <link rel="apple-touch-icon" href="/icon-192.png">

package/server.js

@@ -599,7 +599,18 @@ app.get('/sw.js', (req, res) => {
     res.type('application/javascript').set('Cache-Control', 'no-cache').send(src.replace(/__APP_VERSION__/g, APP_VERSION));
   });
 });
+// Serve index.html dynamically with the real build version injected — the
+// Settings "app v" line reads this meta tag, and it was hardcoded at 0.3.25
+// for days, making every "confirm the version" check unverifiable. The
+// version line must never lie about the build on the phone.
+function serveIndex(req, res) {
+  fs.readFile(path.join(__dirname, 'public', 'index.html'), 'utf8', (err, src) => {
+    if (err) return res.sendStatus(404);
+    res.type('text/html').set('Cache-Control', 'no-cache').send(src.replace(/__APP_VERSION__/g, APP_VERSION));
+  });
+}
+app.get(['/', '/index.html'], serveIndex);
 app.use(express.static(path.join(__dirname, 'public')));
-app.get('*', (req, res) => res.sendFile(path.join(__dirname, 'public', 'index.html')));
+app.get('*', serveIndex);
 
 app.listen(PORT, () => console.log(`[hh-shipments] listening on :${PORT}`));

package/src/extract.js

@@ -189,7 +189,7 @@
         var num = repairUpsTail(expanded.slice(2)) || expanded;
         if (num && UPS_STRICT.test(num) && /[A-Z]/.test(num.slice(2, 8)) && !seen[num]) {
           seen[num] = true;
-          found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: true });
+          found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: true, ocr_path: true });
         }
       }
     }
@@ -216,7 +216,7 @@
       }
       if (num && !seen[num]) {
         seen[num] = true;
-        found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: num !== ups });
+        found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: num !== ups, ocr_path: true });
       }
     }
   }
@@ -250,11 +250,48 @@
       if (num && !seen[num]) {
         seen[num] = true;
         // repairUpsTail only returns strict-validated numbers: trust them.
-        found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: true });
+        found.push({ number: num, carrier: 'ups', confidence: 'high', ocr_fixed: true, ocr_path: true });
       }
     }
   }
 
+  // ---- UPS Mod-10 check digit ----
+  // Every real 1Z number carries a check digit (last char). This is the
+  // arbiter when blurry OCR produces 2↔Z / O↔0 style ambiguity: the wrong
+  // read fails the check, the right one passes. Verified against two real
+  // shipped labels (1Z1XJ5390328621735, 1ZGE23840337267306).
+  // Letter values: (alphabetical index + 1) mod 10 → A=2 … I=0, J=1 … Z=7.
+  var UPS_LETTER_VAL = {};
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('').forEach(function (ch, i) { UPS_LETTER_VAL[ch] = (i + 2) % 10; });
+  function upsCheckDigitOk(num) {
+    var n = String(num).toUpperCase();
+    if (!/^1Z[0-9A-Z]{16}$/.test(n)) return false;
+    var body = n.slice(2, 17); // 15 chars after 1Z, excluding check digit
+    var vals = [];
+    for (var i = 0; i < body.length; i++) {
+      var ch = body[i];
+      vals.push(ch >= '0' && ch <= '9' ? +ch : UPS_LETTER_VAL[ch]);
+    }
+    var odd = 0, even = 0;
+    for (var j = 0; j < vals.length; j++) { if (j % 2 === 0) odd += vals[j]; else even += vals[j]; }
+    var check = (10 - ((odd + even * 2) % 10)) % 10;
+    return check === +n[17];
+  }
+  // Try single-character OCR-confusion swaps until the check digit passes.
+  // A repair that validates is error correction, not invention.
+  var UPS_CHECK_CONFUSIONS = { 'Z': '2', '2': 'Z', 'O': '0', '0': 'O', 'I': '1', '1': 'I', 'S': '5', '5': 'S', 'B': '8', '8': 'B', 'G': '6', '6': 'G', 'A': '4', '4': 'A' };
+  function repairUpsCheckDigit(num) {
+    var upper = String(num).toUpperCase();
+    for (var i = 2; i < 18; i++) {
+      var rep = UPS_CHECK_CONFUSIONS[upper[i]];
+      if (!rep) continue;
+      var cand = upper.slice(0, i) + rep + upper.slice(i + 1);
+      if (!UPS_STRICT.test(cand)) continue;
+      if (upsCheckDigitOk(cand)) return cand;
+    }
+    return null;
+  }
+
   function extractTrackingNumbers(text) {
     var found = [];
     var seen = {};
@@ -278,6 +315,23 @@
     spacedDigitGroupsIn(text, found, seen, 'medium');
     // 2) OCR-tolerant recovery pass
     extractOcrTolerant(text, found, seen);
+    // 3) UPS check-digit gate: a 1Z candidate that fails the Mod-10 check is
+    // an OCR misread (2↔Z etc.). On OCR-path candidates, repair it via
+    // confusion swaps when one validates; otherwise demote to review.
+    // Clean (non-OCR) reads are never rewritten — a typed typo goes to
+    // review, not silently "fixed" into a different number.
+    for (var i = 0; i < found.length; i++) {
+      var c = found[i];
+      if (c.carrier !== 'ups' || c.confidence === 'low') continue;
+      if (!/^1Z[0-9A-Z]{16}$/i.test(c.number)) continue;
+      if (upsCheckDigitOk(c.number)) continue;
+      var fixed = (c.ocr_fixed || c.ocr_path) ? repairUpsCheckDigit(c.number) : null;
+      if (fixed) {
+        if (seen[fixed]) { found.splice(i, 1); i--; } // another pass already found it
+        else { seen[fixed] = true; c.number = fixed; c.ocr_fixed = true; }
+      }
+      else c.confidence = 'medium';
+    }
     var rank = { high: 0, medium: 1, low: 2 };
     found.sort(function (a, b) { return rank[a.confidence] - rank[b.confidence]; });
     return found;
@@ -422,7 +476,7 @@
       var num = '1Z' + token;
       if (seen[num]) continue;
       seen[num] = true;
-      found.push({ number: num, carrier: 'ups', confidence: 'medium', ocr_fixed: true });
+      found.push({ number: num, carrier: 'ups', confidence: 'medium', ocr_fixed: true, ocr_path: true });
     }
   }