universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/spring-gds/carrier.json

@@ -0,0 +1,90 @@
+{
+  "id": "spring-gds",
+  "displayName": "PostNL",
+  "aliases": [
+    "Spring GDS",
+    "Mailing Technology"
+  ],
+  "region": {
+    "countries": [
+      "NL"
+    ]
+  },
+  "brand": {
+    "color": "#ef7d00"
+  },
+  "selectable": true,
+  "timezone": "Europe/Amsterdam",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "spring-gds",
+    "steps": [
+      "direct"
+    ],
+    "refresh": {
+      "minMinutes": 30
+    },
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "sender_name",
+    "delivered_at"
+  ],
+  "portal": {
+    "url": "https://postnl.post/track?barcodes={trackingNumber}",
+    "canaryUrl": "https://postnl.post/",
+    "shows": [
+      "status",
+      "history",
+      "sender_name"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "sender_name"
+    ],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "postnl.post"
+      ],
+      "pathPattern": "^/track/?$",
+      "params": [
+        "barcodes"
+      ]
+    },
+    {
+      "domains": [
+        "mailingtechnology.com"
+      ],
+      "pathPattern": "^/tracking/?$",
+      "params": [
+        "tn"
+      ]
+    },
+    {
+      "domains": [
+        "postnl.post"
+      ],
+      "path": "/details/([^/?#]+)"
+    }
+  ],
+  "detection": [
+    {
+      "id": "spring-gds-1",
+      "pattern": "^(?!(?:PZ|XU|XW|XY))[A-Z]{2}\\d{9}NL$",
+      "confidence": "high",
+      "checksum": "s10"
+    },
+    {
+      "id": "spring-gds-2",
+      "pattern": "^(?=.{13}$|.{15}$)3S[A-Z]{1,4}\\d+$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/spring-gds/numbers.json

@@ -0,0 +1,224 @@
+{
+  "carrier": "spring-gds",
+  "records": [
+    {
+      "number": "3SA5210528875",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "3SAB83691658823",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "3SABC19149187",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "3SABCD1175003",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "3SABCD3427702",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "3SABCD987446630",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "CC123442066NL",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "CD111208171NL",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "CK089862199NL",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten.php",
+        "date": "2026-04-15"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "CP112251335NL",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "LA599196732NL",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "LA681049820NL",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten.php",
+        "date": "2026-04-15"
+      },
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "LX123456785NL",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "spring-gds",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "LX123456789NL",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Invented placeholder used as a shape check. Filed under PostNL, which no rule claims."
+    },
+    {
+      "number": "RI543495045NL",
+      "role": "quarantined",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The S10 check digit does not validate. The source attributes it to PostNL, which no rule claims."
+    },
+    {
+      "number": "UE597256100NL",
+      "role": "quarantined",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.postnl.nl/integration-with-postnl/api-overview/send-and-track/barcode-webservice/"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The S10 check digit does not validate. The source attributes it to PostNL, which no rule claims."
+    }
+  ]
+}

package/dist/carriers/spring-gds/status.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PostNL status vocabulary.
+ *
+ * Every event carries a `category` token next to its localized
+ * `status_description`. Categories are the primary signal. The English
+ * "The item is out for delivery" label refines the overloaded Processing
+ * category, which also covers sorting and acceptance.
+ * Categories are matched case-insensitively after trimming, because the
+ * international tracker has been seen returning them capitalized
+ * ("Pre-advised") and lower case in the same history.
+ *
+ * `unsuccesfull` is PostNL's own spelling; the corrected spelling is mapped
+ * alongside it so a fix upstream does not silently lose the classification.
+ */
+import type { ClassifiedStatus } from '../../core/status/index.js';
+declare const CATEGORY_STATUS: Map<string, ClassifiedStatus>;
+export { CATEGORY_STATUS as POSTNL_STATUS };
+/** The status and stage for one PostNL event category, or undefined when unmapped. */
+export declare function postNLStatus(category: unknown, description?: unknown): ClassifiedStatus | undefined;

package/dist/carriers/spring-gds/status.js

@@ -0,0 +1,28 @@
+const CATEGORY_STATUS = new Map([
+    ['pre-advised', { status: 'pending', stage: 'registered' }],
+    ['preparing', { status: 'pending', stage: 'registered' }],
+    ['processing', { status: 'in_transit', stage: 'accepted' }],
+    ['departed', { status: 'in_transit', stage: 'in_transit' }],
+    ['arrived', { status: 'in_transit', stage: 'in_transit' }],
+    ['in transit', { status: 'in_transit', stage: 'in_transit' }],
+    ['transit', { status: 'in_transit', stage: 'in_transit' }],
+    ['customs', { status: 'in_transit', stage: 'customs' }],
+    ['out for delivery', { status: 'out_for_delivery', stage: 'out_for_delivery' }],
+    ['pick-up point', { status: 'out_for_delivery', stage: 'ready_for_pickup' }],
+    ['delivered', { status: 'delivered', stage: 'delivered' }],
+    ['unsuccesfull', { status: 'exception', stage: 'failed_attempt' }],
+    ['unsuccessful', { status: 'exception', stage: 'failed_attempt' }],
+    ['undelivered', { status: 'exception', stage: 'failed_attempt' }],
+    ['returned', { status: 'exception', stage: 'returned' }],
+    ['exception', { status: 'exception', stage: 'exception' }],
+]);
+export { CATEGORY_STATUS as POSTNL_STATUS };
+/** The status and stage for one PostNL event category, or undefined when unmapped. */
+export function postNLStatus(category, description) {
+    const code = (typeof category === 'string' ? category : '').trim().toLocaleLowerCase('en-US');
+    if (code === 'processing' && typeof description === 'string'
+        && description.trim().toLocaleLowerCase('en-US') === 'the item is out for delivery') {
+        return { status: 'out_for_delivery', stage: 'out_for_delivery' };
+    }
+    return CATEGORY_STATUS.get(code);
+}

package/dist/carriers/spring-gds/statuses.json

@@ -0,0 +1,140 @@
+{
+  "carrier": "spring-gds",
+  "entries": [
+    {
+      "wording": "pre-advised",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "preparing",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "processing",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "departed",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "arrived",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "in transit",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "transit",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "customs",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "pick-up point",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "unsuccesfull",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "PostNL's own spelling."
+    },
+    {
+      "wording": "unsuccessful",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "The corrected spelling, mapped so an upstream fix loses nothing."
+    },
+    {
+      "wording": "undelivered",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "returned",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming."
+    },
+    {
+      "wording": "exception",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-12",
+      "note": "Event category; matched case-insensitively after trimming. Reclassified to exception 2026-09-12."
+    },
+    {
+      "wording": "The item is out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "note": "Exact English description refines the overloaded Processing category."
+    }
+  ]
+}

package/dist/carriers/sto/carrier.json

@@ -0,0 +1,37 @@
+{
+  "id": "sto",
+  "displayName": "STO Express",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "CN"
+    ]
+  },
+  "brand": {
+    "color": "#ff6700"
+  },
+  "selectable": true,
+  "timezone": "Asia/Shanghai",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "universal",
+    "steps": []
+  },
+  "capabilities": [],
+  "portal": {
+    "url": "https://www.sto.cn/",
+    "canaryUrl": "https://t.17track.net/",
+    "shows": [],
+    "scraped": [],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [],
+  "detection": [
+    {
+      "id": "sto-1",
+      "pattern": "^\\d{12}$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/sto/numbers.json

@@ -0,0 +1,33 @@
+{
+  "carrier": "sto",
+  "records": [
+    {
+      "number": "968754207139",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "gls-ch",
+          "mondial-relay",
+          "gls-fr",
+          "colis-prive",
+          "gls-de",
+          "mrw",
+          "sf-express",
+          "sto",
+          "zto",
+          "yamato",
+          "j-and-t"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to STO Express, which stays one candidate among several."
+    }
+  ]
+}

package/dist/carriers/sunyou/adapter.d.ts

@@ -0,0 +1,18 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+/** Unwraps the JSONP envelope the search page receives. */
+export declare function parseSunYouEnvelope(body: string): unknown;
+/** Projects one unwrapped payload. Pure: the offline tests target this. */
+export declare function parseSunYouTrackingResponse(value: unknown, trackingNumber: string): CarrierResult;
+export declare class SunYouTracker {
+    private readonly fetcher;
+    private readonly timeoutMs;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        timeoutMs?: number;
+    });
+    fetch(trackingNumber: string): Promise<CarrierResult>;
+}
+/** Kept for the host's legacy dispatch chain until it is deleted. */
+export declare function fetchSunYou(trackingNumber: string): Promise<CarrierResult>;
+export declare const adapter: AdapterFactory;