hh-shipments 0.3.26 → 0.3.28

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.26",
+  "version": "0.3.28",
   "bin": {
     "hh-shipments": "server.js"
   },

package/public/app.js

@@ -400,13 +400,15 @@ function loadZxing() {
   return zxingPromise;
 }
 
-// OCR just the top strip of a label (sender block) for the seller name.
+// OCR the top strip of a label (sender block) for the seller name.
 // Works from the ORIGINAL full-resolution image, upscaled — small text
-// reads far better than on the shrunk copy. Returns text or null.
+// reads far better than on the shrunk copy. Top 45%: covers the sender
+// block on USPS labels (~35-40%) as well as UPS/FedEx (top). Returns text
+// or null.
 async function ocrTopStrip(origFile, statusEl) {
   try {
     const bmp = await createImageBitmap(origFile);
-    const sw = bmp.width, sh = Math.max(60, Math.round(bmp.height * 0.35));
+    const sw = bmp.width, sh = Math.max(60, Math.round(bmp.height * 0.45));
     const targetW = 1400, scale = targetW / sw;
     const canvas = document.createElement('canvas');
     canvas.width = targetW;
@@ -448,6 +450,18 @@ async function decodeOne(reader, url, ms = 9000) {
   } catch (e) { return null; }
 }
 
+// Rank barcode candidates by format specificity: a 1Z UPS read or a
+// 22-digit USPS read is unambiguous, while a 10-digit "DHL" read off a
+// label is often a fragment of another carrier's number (or a routing
+// barcode). Weak hits never beat strong ones.
+function barcodeRank(num) {
+  if (/^1Z/i.test(num)) return 0;                              // UPS
+  if (/^9[1-5]\d{18,20}$/.test(num)) return 1;                 // USPS
+  if (/^96\d{20}$/.test(num) || /^\d{15}$/.test(num) || /^\d{20}$/.test(num)) return 2; // FedEx long
+  if (/^\d{12}$/.test(num)) return 3;                          // FedEx 12 (weak: may be routing)
+  return 4;                                                    // DHL 10/11 (weakest)
+}
+
 // Whole-label decode usually fails (barcodes too small in frame), so try
 // horizontal region strips, upscaled — the 1Z barcode lives low on UPS labels.
 async function decodeBarcode(file) {
@@ -465,6 +479,11 @@ async function decodeBarcode(file) {
     [0, 0.60, 1, 0.35],
     [0.05, 0.55, 0.90, 0.40],
   ];
+  // Collect every candidate across the sweep and take the strongest —
+  // never let the first weak hit (e.g. a 10-digit routing barcode read as
+  // DHL) win over the real tracking barcode. Unambiguous reads (UPS/USPS)
+  // still return immediately on the fast path.
+  let best = null, bestRank = 99;
   try {
     for (const [fx, fy, fw, fh] of regions) {
       for (const scale of [1, 1.5, 2]) {
@@ -489,11 +508,15 @@ async function decodeBarcode(file) {
         const url = canvas.toDataURL('image/png');
         const text = await decodeOne(reader, url);
         const num = strictTracking(text);
-        if (num) return num;
+        if (num) {
+          const r = barcodeRank(num);
+          if (r < bestRank) { best = num; bestRank = r; }
+          if (r <= 1) return num; // UPS or USPS: unambiguous, fast path
+        }
       }
     }
   } finally { bmp.close(); }
-  return null;
+  return best;
 }
 // Detect when the pasted image is a screenshot OF THE APP itself (its own
 // header/buttons/tab bar get OCR'd) — the label inside is too small to read
@@ -537,9 +560,14 @@ async function handlePastedImageFile(f) {
       if (r && !r.added.length && !r.duplicates.length && !r.needs_review.some((c) => c.carrier && c.carrier !== 'unknown')) showOcrRead(target, text);
       return;
     }
-    // 2) Fallback: OCR the printed text
+    // 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…';
-    text = await ocrFile(f, $('ocr-status-paste'));
+    const [ocrText, topTextFb] = await Promise.all([
+      ocrFile(f, $('ocr-status-paste')),
+      ocrTopStrip(orig, $('ocr-status-paste')),
+    ]);
+    text = ocrText;
     if (live) live.textContent = '⬆️ Uploading…';
     const fd = new FormData();
     fd.append('image', f);
@@ -549,7 +577,7 @@ async function handlePastedImageFile(f) {
     if (!up.ok) throw new Error('upload failed');
     const upId2 = await up.json().then((j) => j.id).catch(() => null);
     if (live) live.textContent = '🔍 Finding tracking number…';
-    const r = await runQuick(text, target);
+    const r = await runQuick(text, target, topTextFb ? { labelText: topTextFb } : undefined);
     // 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>');

package/public/extract.js

@@ -59,13 +59,14 @@
   // Strict UPS structure: 1Z + 6-char shipper number + 2-digit service + 8-digit serial.
   var UPS_STRICT = /^1Z[0-9A-Z]{6}[0-9]{2}[0-9]{8}$/;
   function repairUpsZ(ups) {
-    // Tesseract often reads the "1Z" anchor as "12" (or "IZ"). Repair it
-    // only when the rest has strict UPS structure AND the shipper segment
-    // contains a letter — real UPS shipper numbers do, random digit runs
-    // don't. Never invent numbers from thin air.
+    // Tesseract often reads the "1Z" anchor as "12" (or "IZ", or "17" —
+    // 7→Z confusion). Repair it only when the rest has strict UPS structure
+    // AND the shipper segment contains a letter — real UPS shipper numbers
+    // do, random digit runs don't. Never invent numbers from thin air.
     var cand = null;
     if (/^12[0-9A-Z]{16}$/.test(ups)) cand = '1Z' + ups.slice(2);
     else if (/^IZ[0-9A-Z]{16}$/i.test(ups)) cand = '1Z' + ups.slice(2);
+    else if (/^17[0-9A-Z]{16}$/.test(ups)) cand = '1Z' + ups.slice(2);
     if (!cand || !UPS_STRICT.test(cand)) return null;
     if (!/[A-Z]/.test(cand.slice(2, 8))) return null;
     return cand;
@@ -73,7 +74,8 @@
 
   // UPS number split by spaces/dashes: "1Z 9999 99 ..." (or "12 ..."/"IZ ..." misreads)
   function spacedUpsIn(text, found, seen, conf) {
-    var m, re = /\b(?:1Z|12|IZ)[\s-]?(?:[0-9A-Z][\s-]?){16}\b/gi;
+    // Anchor covers common 1Z misreads: 12, IZ, 17 (7→Z confusion)
+    var m, re = /\b(?:1Z|12|IZ|17)[\s-]?(?:[0-9A-Z][\s-]?){16}\b/gi;
     while ((m = re.exec(text)) !== null) {
       var ups = normalize(m[0]);
       var num = /^1Z[0-9A-Z]{16}$/.test(ups) ? ups : repairUpsZ(ups);

package/src/extract.js

@@ -66,24 +66,43 @@
       var m2 = text.match(/(?:from|seller)\s*:\s*([A-Z][a-z]+(?:\s+[A-Z][a-z]+)?)/);
       if (m2) out.seller_name = m2[1].trim();
     }
-    // Shipping labels: the sender name is the first or second line
-    // ("MOHAMMED SALEM"). Only take it when it's clearly a name — never
-    // digits, never address fragments, never OCR garbage like "EE SS",
-    // and never the app's own UI words when a screenshot of the app itself
-    // gets pasted ("Back Shipment").
+    // Shipping-label name test, shared by the address-anchor rule and the
+    // first-two-lines fallback below.
+    var labelWords = function (s) { return String(s).trim().split(/\s+/); };
+    var looksLikeLabelName = function (s) {
+      var words = labelWords(s);
+      if (words.length < 2 || words.length > 3) return false;
+      // Real shipping labels print names in ALL CAPS; app UI chrome
+      // ("Back Shipment") and OCR fragments ("Eg NTT") don't.
+      if (s !== s.toUpperCase()) return false;
+      // First word 4+ letters (a real first name — rejects "EE SS");
+      // later words 4+ letters or a single initial ("MOHAMED A").
+      if (!/^[A-Z]{4,}$/.test(words[0])) return false;
+      for (var wi = 1; wi < words.length; wi++) if (!/^([A-Z]{4,}|[A-Z])$/.test(words[wi])) return false;
+      if (/\b(UPS|FEDEX|USPS|DHL|GROUND|EXPRESS|PRIORITY|BILLING|SHIP\b|FROM|TRACKING|POSTAGE|LABEL|BACK|SHIPMENT|HOME|ARCHIVE|SETTINGS|SCREENSHOT|READING|FINDING|UPLOADING|EXTRACT|PASTE|DETAILS|SAVE|TAP|CLIPBOARD|NUMBER|HUNTER|HILLS)\b/.test(s)) return false;
+      return true;
+    };
+    // Shipping labels: the sender name sits on the line directly above the
+    // street-address line ("MOHAMED A" above "2507 GLACIER ST"). Find that
+    // anchor anywhere in the text — far more reliable than line position,
+    // since OCR crops don't always start at the label's first line. The
+    // first such block wins (sender prints above recipient).
+    if (!out.seller_name) {
+      var alines = String(text).split(/\r?\n/);
+      for (var ai = 0; ai < alines.length; ai++) {
+        var addr = alines[ai].trim();
+        if (!/^\d{1,6}\s+[A-Z0-9][A-Z0-9 .'-]*$/.test(addr)) continue;
+        if (!/\b(ST|STREET|AVE|AVENUE|RD|ROAD|DR|DRIVE|LN|LANE|BLVD|PL|PLACE|CT|COURT|WAY|TER|TERRACE|PKWY|PARKWAY)\b/.test(addr)) continue;
+        if (ai === 0) continue;
+        var cand = alines[ai - 1].replace(/[^A-Za-z ]/g, ' ').replace(/\s+/g, ' ').trim();
+        if (looksLikeLabelName(cand)) { out.seller_name = cand; break; }
+      }
+    }
+    // Fallback: sender name is the first or second line ("MOHAMMED SALEM").
+    // Only take it when it's clearly a name — never digits, never address
+    // fragments, never OCR garbage like "EE SS", and never the app's own UI
+    // words when a screenshot of the app itself gets pasted ("Back Shipment").
     if (!out.seller_name) {
-      var labelWords = function (s) { return String(s).trim().split(/\s+/); };
-      var looksLikeLabelName = function (s) {
-        var words = labelWords(s);
-        if (words.length < 2 || words.length > 3) return false;
-        // Real shipping labels print names in ALL CAPS; app UI chrome
-        // ("Back Shipment") and OCR fragments ("Eg NTT") don't.
-        if (s !== s.toUpperCase()) return false;
-        // every word 4+ letters: OCR garbage ("EE SS") never qualifies.
-        for (var i = 0; i < words.length; i++) if (!/^[A-Z]{4,}$/.test(words[i])) return false;
-        if (/\b(UPS|FEDEX|USPS|DHL|GROUND|EXPRESS|PRIORITY|BILLING|SHIP\b|FROM|TRACKING|POSTAGE|LABEL|BACK|SHIPMENT|HOME|ARCHIVE|SETTINGS|SCREENSHOT|READING|FINDING|UPLOADING|EXTRACT|PASTE|DETAILS|SAVE|TAP|CLIPBOARD|NUMBER)\b/.test(s)) return false;
-        return true;
-      };
       var lines = String(text).split(/\r?\n/);
       for (var li = 0; li < Math.min(2, lines.length); li++) {
         var cleaned = lines[li].replace(/[^A-Za-z ]/g, ' ').replace(/\s+/g, ' ').trim();
@@ -248,7 +267,8 @@
       runPatterns(z.text, found, seen, z.carrier);
       spacedUpsIn(z.text, found, seen, 'high');
       looseUpsIn(z.text, found, seen, 'high');
-      spacedDigitGroupsIn(z.text, found, seen, 'high');
+      spacedDigitGroupsIn(z.text, found, seen, 'high', z.carrier);
+      if (z.carrier === 'ups') upsAnchorlessRecovery(z.text, found, seen);
     });
     // 1) Whole-text strict patterns
     runPatterns(text, found, seen, false);
@@ -286,7 +306,10 @@
       // anchor line + the two lines under it (the number is printed below)
       var slice = lines.slice(i, Math.min(lines.length, i + 3));
       var carrier = null;
-      slice.forEach(function (sl) { carrier = carrier || anchorCarrier(sl); });
+      // Scan the slice AND the line above it: "UPS GROUND" typically sits
+      // directly above the "TRACKING #:" line, and the zone needs to know.
+      var scan = slice.concat(i > 0 ? [lines[i - 1]] : []);
+      scan.forEach(function (sl) { carrier = carrier || anchorCarrier(sl); });
       zones.push({ text: slice.join('\n'), carrier: carrier });
     }
     return zones;
@@ -358,7 +381,11 @@
   // contains a separator (contiguous runs are already covered by PATTERNS).
   // Joined candidates must validate against a carrier format; IMpb barcodes
   // yield their tracking number, never the routing.
-  function spacedDigitGroupsIn(text, found, seen, conf) {
+  // zoneCarrier: when the anchor zone names a carrier ("UPS GROUND"), a
+  // candidate of any OTHER carrier is a fragment of the real number
+  // ("03 3985 0416" off a UPS label is not a DHL shipment) — demote it to
+  // low so it can only ever surface for review, never auto-add.
+  function spacedDigitGroupsIn(text, found, seen, conf, zoneCarrier) {
     var re = /\b\d(?:[\s-]?\d){9,33}\b/g, m;
     while ((m = re.exec(text)) !== null) {
       if (!/[\s-]/.test(m[0])) continue;
@@ -368,13 +395,34 @@
       var impb = parseImpb(num);
       if (impb) {
         seen[num] = true;
-        if (!seen[impb]) { seen[impb] = true; found.push({ number: impb, carrier: 'usps', confidence: conf }); }
+        var ic = (zoneCarrier && zoneCarrier !== 'usps') ? 'low' : conf;
+        if (!seen[impb]) { seen[impb] = true; found.push({ number: impb, carrier: 'usps', confidence: ic }); }
         continue;
       }
       var carrier = guessCarrier(num);
       if (carrier === 'unknown') { seen[num] = true; continue; }
       seen[num] = true;
-      found.push({ number: num, carrier: carrier, confidence: conf });
+      var c = (zoneCarrier && carrier !== zoneCarrier) ? 'low' : conf;
+      found.push({ number: num, carrier: carrier, confidence: c });
+    }
+  }
+
+  // Last resort for UPS zones: the "1Z" anchor itself was unreadable, so the
+  // number survives only as a 16-char alphanumeric tail ("X01 48H 03 3985
+  // 0416"). If it validates as strict UPS tail structure, offer 1Z+tail at
+  // medium (review-only, never auto-add) — far better than a DHL fragment.
+  var UPS_TAIL_STRICT = /^[0-9A-Z]{6}[0-9]{2}[0-9]{8}$/;
+  function upsAnchorlessRecovery(text, found, seen) {
+    var re = /\b([0-9A-Z](?:[\s-]?[0-9A-Z]){15})\b/gi, m;
+    while ((m = re.exec(text)) !== null) {
+      var token = normalize(m[1]);
+      if (/^(1Z|12|IZ|17)/i.test(token)) continue; // anchored — handled elsewhere
+      if (!UPS_TAIL_STRICT.test(token)) continue;
+      if (!/[A-Z]/.test(token.slice(0, 6))) continue; // real shipper codes have a letter
+      var num = '1Z' + token;
+      if (seen[num]) continue;
+      seen[num] = true;
+      found.push({ number: num, carrier: 'ups', confidence: 'medium', ocr_fixed: true });
     }
   }