universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/server/openapi.json

@@ -0,0 +1,487 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Universal Parcel Scraper",
+    "version": "0.1.0"
+  },
+  "paths": {
+    "/health": {
+      "get": {
+        "operationId": "health",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Health"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid or required input"
+          },
+          "401": {
+            "description": "Bearer token required"
+          },
+          "429": {
+            "description": "Rate limit or concurrency reached"
+          },
+          "502": {
+            "description": "No enabled upstream answered"
+          }
+        },
+        "security": []
+      }
+    },
+    "/v1/carriers": {
+      "get": {
+        "operationId": "carriers",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Catalog"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid or required input"
+          },
+          "401": {
+            "description": "Bearer token required"
+          },
+          "429": {
+            "description": "Rate limit or concurrency reached"
+          },
+          "502": {
+            "description": "No enabled upstream answered"
+          }
+        },
+        "security": [
+          {},
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/v1/detect": {
+      "post": {
+        "operationId": "detect",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Detection"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid or required input"
+          },
+          "401": {
+            "description": "Bearer token required"
+          },
+          "429": {
+            "description": "Rate limit or concurrency reached"
+          },
+          "502": {
+            "description": "No enabled upstream answered"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "text": {
+                    "type": "string",
+                    "maxLength": 16384
+                  }
+                },
+                "required": [
+                  "text"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "security": [
+          {},
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/v1/recognize": {
+      "post": {
+        "operationId": "recognize",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Recognition"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid or required input"
+          },
+          "401": {
+            "description": "Bearer token required"
+          },
+          "429": {
+            "description": "Rate limit or concurrency reached"
+          },
+          "502": {
+            "description": "No enabled upstream answered"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "number": {
+                    "type": "string"
+                  },
+                  "budgetMs": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 120000
+                  }
+                },
+                "required": [
+                  "number"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "security": [
+          {},
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
+    "/v1/track": {
+      "post": {
+        "operationId": "track",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TrackingResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid or required input"
+          },
+          "401": {
+            "description": "Bearer token required"
+          },
+          "429": {
+            "description": "Rate limit or concurrency reached"
+          },
+          "502": {
+            "description": "No enabled upstream answered"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ParcelInput"
+              }
+            }
+          }
+        },
+        "security": [
+          {},
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer"
+      }
+    },
+    "schemas": {
+      "ParcelInput": {
+        "type": "object",
+        "properties": {
+          "number": {
+            "type": "string",
+            "minLength": 4,
+            "maxLength": 80
+          },
+          "carrier": {
+            "type": "string"
+          },
+          "postcode": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "trackingUrl": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "budgetMs": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 120000
+          }
+        },
+        "required": [
+          "number"
+        ],
+        "additionalProperties": false
+      },
+      "Health": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "ok"
+        ],
+        "additionalProperties": false
+      },
+      "Catalog": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object"
+        }
+      },
+      "Detection": {
+        "type": "object",
+        "required": [
+          "trackingNumber",
+          "carrier",
+          "confidence",
+          "candidates",
+          "source"
+        ],
+        "properties": {
+          "trackingNumber": {
+            "type": "string"
+          },
+          "carrier": {
+            "type": "string"
+          },
+          "confidence": {
+            "type": "string",
+            "enum": [
+              "high",
+              "low",
+              "none"
+            ]
+          },
+          "candidates": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "preferred": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "source": {
+            "type": "string",
+            "enum": [
+              "number",
+              "link",
+              "text",
+              "none"
+            ]
+          },
+          "trackingUrl": {
+            "type": "string"
+          }
+        }
+      },
+      "Recognition": {
+        "type": "object",
+        "properties": {
+          "carrier": {
+            "type": "string"
+          },
+          "choices": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "asked": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "unanswered": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "choices",
+          "asked",
+          "unanswered"
+        ],
+        "additionalProperties": false
+      },
+      "TrackingResponse": {
+        "type": "object",
+        "required": [
+          "carrier",
+          "source",
+          "result",
+          "attempts"
+        ],
+        "properties": {
+          "carrier": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string"
+          },
+          "result": {
+            "$ref": "#/components/schemas/CarrierResult"
+          },
+          "attempts": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "source",
+                "kind",
+                "durationMs"
+              ],
+              "properties": {
+                "source": {
+                  "type": "string"
+                },
+                "kind": {
+                  "type": "string"
+                },
+                "durationMs": {
+                  "type": "integer"
+                }
+              }
+            }
+          },
+          "handoff": {
+            "type": "object"
+          }
+        }
+      },
+      "CarrierResult": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string"
+          },
+          "current_stage": {
+            "type": "string"
+          },
+          "last_status_text": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "last_update": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "expected_delivery": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "events": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "stage",
+                "stage_source",
+                "instant"
+              ],
+              "properties": {
+                "time": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": "string"
+                },
+                "location": {
+                  "type": "string"
+                },
+                "stage": {
+                  "type": "string"
+                },
+                "stage_source": {
+                  "type": "string"
+                },
+                "instant": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              },
+              "additionalProperties": true
+            }
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  }
+}

package/dist/server/page.d.ts

@@ -0,0 +1 @@
+export declare const demoPage = "<!doctype html>\n<html lang=\"en\"><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>Universal Parcel Scraper</title>\n<style>body{max-width:44rem;margin:10vh auto;padding:1.5rem;font:16px system-ui;color:#173a36;background:#f4f6ef}h1{font-size:2.5rem}form{display:grid;gap:.8rem}input,select,button{font:inherit;padding:.8rem;border:1px solid #a0b8ae;border-radius:.5rem}button{background:#173a36;color:white;cursor:pointer}pre{white-space:pre-wrap;overflow-wrap:anywhere}small{color:#516862}</style>\n<h1>A parcel. One timeline.</h1><p>Look up a parcel with the sources enabled on this server.</p>\n<form><input id=\"number\" placeholder=\"Tracking number or carrier link\" required aria-label=\"Tracking input\">\n<select id=\"carrier\" aria-label=\"Carrier\"><option value=\"\">Detect carrier</option></select>\n<input id=\"postcode\" placeholder=\"Delivery postcode, if required\" aria-label=\"Delivery postcode\">\n<input id=\"token\" type=\"password\" placeholder=\"Server token, if required\" aria-label=\"Server token\">\n<button>Track parcel</button></form><p id=\"detection\" role=\"status\"></p><pre id=\"result\"></pre>\n<small>Detection runs in your browser. Tracking sends the number and any required inputs to this server and its enabled sources.</small>\n<script type=\"module\">\nimport { parseTrackingInput, CARRIER_CATALOG } from '/assets/scraper.js';\nconst field = id => document.getElementById(id);\nfor (const [id, carrier] of Object.entries(CARRIER_CATALOG)) {\n if (!carrier.selectable) continue;\n const option = document.createElement('option'); option.value = id; option.textContent = carrier.displayName; field('carrier').append(option);\n}\nfield('number').addEventListener('input', () => {\n const match = parseTrackingInput(field('number').value);\n field('detection').textContent = match.confidence === 'high' ? CARRIER_CATALOG[match.carrier].displayName : 'Choose a carrier if detection is uncertain.';\n});\ndocument.querySelector('form').addEventListener('submit', async event => {\n event.preventDefault(); const button = document.querySelector('button'); button.disabled = true; field('result').textContent = 'Looking up history\u2026';\n try {\n  const match = parseTrackingInput(field('number').value);\n  const token = field('token').value;\n  const response = await fetch('/v1/track', { method:'POST', headers:{'Content-Type':'application/json', ...(token ? {Authorization:'Bearer '+token} : {})}, body:JSON.stringify({number:match.trackingNumber, carrier:field('carrier').value || undefined, postcode:field('postcode').value || undefined, trackingUrl:match.trackingUrl}) });\n  field('result').textContent = JSON.stringify(await response.json(), null, 2);\n } catch { field('result').textContent = 'The tracking server could not be reached.'; }\n finally { button.disabled = false; }\n});\n</script></html>";

package/dist/server/page.js

@@ -0,0 +1,33 @@
+export const demoPage = `<!doctype html>
+<html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Universal Parcel Scraper</title>
+<style>body{max-width:44rem;margin:10vh auto;padding:1.5rem;font:16px system-ui;color:#173a36;background:#f4f6ef}h1{font-size:2.5rem}form{display:grid;gap:.8rem}input,select,button{font:inherit;padding:.8rem;border:1px solid #a0b8ae;border-radius:.5rem}button{background:#173a36;color:white;cursor:pointer}pre{white-space:pre-wrap;overflow-wrap:anywhere}small{color:#516862}</style>
+<h1>A parcel. One timeline.</h1><p>Look up a parcel with the sources enabled on this server.</p>
+<form><input id="number" placeholder="Tracking number or carrier link" required aria-label="Tracking input">
+<select id="carrier" aria-label="Carrier"><option value="">Detect carrier</option></select>
+<input id="postcode" placeholder="Delivery postcode, if required" aria-label="Delivery postcode">
+<input id="token" type="password" placeholder="Server token, if required" aria-label="Server token">
+<button>Track parcel</button></form><p id="detection" role="status"></p><pre id="result"></pre>
+<small>Detection runs in your browser. Tracking sends the number and any required inputs to this server and its enabled sources.</small>
+<script type="module">
+import { parseTrackingInput, CARRIER_CATALOG } from '/assets/scraper.js';
+const field = id => document.getElementById(id);
+for (const [id, carrier] of Object.entries(CARRIER_CATALOG)) {
+ if (!carrier.selectable) continue;
+ const option = document.createElement('option'); option.value = id; option.textContent = carrier.displayName; field('carrier').append(option);
+}
+field('number').addEventListener('input', () => {
+ const match = parseTrackingInput(field('number').value);
+ field('detection').textContent = match.confidence === 'high' ? CARRIER_CATALOG[match.carrier].displayName : 'Choose a carrier if detection is uncertain.';
+});
+document.querySelector('form').addEventListener('submit', async event => {
+ event.preventDefault(); const button = document.querySelector('button'); button.disabled = true; field('result').textContent = 'Looking up history…';
+ try {
+  const match = parseTrackingInput(field('number').value);
+  const token = field('token').value;
+  const response = await fetch('/v1/track', { method:'POST', headers:{'Content-Type':'application/json', ...(token ? {Authorization:'Bearer '+token} : {})}, body:JSON.stringify({number:match.trackingNumber, carrier:field('carrier').value || undefined, postcode:field('postcode').value || undefined, trackingUrl:match.trackingUrl}) });
+  field('result').textContent = JSON.stringify(await response.json(), null, 2);
+ } catch { field('result').textContent = 'The tracking server could not be reached.'; }
+ finally { button.disabled = false; }
+});
+</script></html>`;

package/package.json

@@ -1,6 +1,104 @@
 {
   "name": "universal-parcel-scraper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Self-hosted parcel tracking: carrier detection, dedicated scrapers and optional universal providers.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Paul-Louis HERY",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plhery/universal-parcel-scraper.git"
+  },
+  "bugs": {
+    "url": "https://github.com/plhery/universal-parcel-scraper/issues"
+  },
+  "homepage": "https://github.com/plhery/universal-parcel-scraper#readme",
+  "keywords": [
+    "parcel",
+    "tracking",
+    "scraper",
+    "carriers",
+    "home-assistant",
+    "self-hosted"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
+    "./places": {
+      "types": "./dist/places/index.d.ts",
+      "import": "./dist/places/index.js"
+    },
+    "./data/*": "./data/*"
+  },
+  "bin": {
+    "parcel-scraper": "dist/cli/index.js",
+    "universal-parcel-scraper": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "data",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --max-warnings=0",
+    "test": "vitest run",
+    "test:scripts": "node --test trawl/*.test.mjs scripts/*.test.mjs",
+    "generate": "node scripts/generate-catalog.mjs && node scripts/generate-registry.mjs --strict && node scripts/generate-region-towns.mjs && node scripts/coverage-tables.mjs && node scripts/generate-readme.mjs",
+    "test:generated": "node scripts/generate-catalog.mjs --check && node scripts/generate-registry.mjs --strict --check && node scripts/generate-region-towns.mjs --check && node scripts/coverage-tables.mjs --check && node scripts/generate-readme.mjs --check",
+    "test:package": "node scripts/test-package.mjs",
+    "test:carriers:live": "vitest run --config vitest.carriers-live.config.ts",
+    "test:carriers:canary": "vitest run --config vitest.carriers-live.config.ts --exclude testing/trackingLinks.live.test.ts",
+    "test:tracking-links": "vitest run --config vitest.carriers-live.config.ts testing/trackingLinks.live.test.ts",
+    "canary": "node dist/scripts/carrier-canary.js",
+    "carrier:new": "node scripts/new-carrier.mjs"
+  },
+  "dependencies": {
+    "luxon": "^3.7.2",
+    "cheerio": "^1.2.0",
+    "tough-cookie": "^6.0.2",
+    "fetch-cookie": "^3.2.0"
+  },
+  "peerDependencies": {
+    "playwright-core": "1.63.0",
+    "sharp": "0.35.5",
+    "onnxruntime-web": "1.30.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    },
+    "sharp": {
+      "optional": true
+    },
+    "onnxruntime-web": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "playwright-core": "1.63.0",
+    "sharp": "0.35.5",
+    "onnxruntime-web": "1.30.0",
+    "vitest": "^5.0.2",
+    "vite": "^8.3.1",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "@types/node": "^26.6.3",
+    "@types/luxon": "^3.7.5",
+    "ajv": "^8.20.0",
+    "eslint": "^9.39.5",
+    "@typescript-eslint/parser": "^8.71.0"
+  }
+}