universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/amazon-shipping/carrier.json

@@ -0,0 +1,96 @@
+{
+  "id": "amazon-shipping",
+  "displayName": "Amazon Shipping",
+  "aliases": [
+    "Shipping with Amazon",
+    "SWA"
+  ],
+  "region": {
+    "countries": [
+      "FR",
+      "DE",
+      "BE",
+      "GB",
+      "IT",
+      "ES",
+      "NL",
+      "AT",
+      "IE",
+      "PL",
+      "SE",
+      "PT",
+      "LU",
+      "DK",
+      "FI",
+      "CZ",
+      "SK",
+      "HU",
+      "RO",
+      "BG",
+      "HR",
+      "SI",
+      "EE",
+      "LV",
+      "LT",
+      "GR",
+      "CY",
+      "MT",
+      "CH",
+      "NO",
+      "IS",
+      "LI",
+      "TR",
+      "US"
+    ]
+  },
+  "brand": {
+    "color": "#ff9900"
+  },
+  "selectable": false,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "amazon-shipping",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://track.amazon.fr/tracking/{trackingNumber}",
+    "canaryUrl": "https://track.amazon.fr/",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "sender_name",
+      "recipient_name",
+      "recipient_address",
+      "signature",
+      "delivery_photo"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "provider_code"
+    ],
+    "discarded": [
+      "sender_name",
+      "recipient_name",
+      "recipient_address",
+      "signature",
+      "delivery_photo"
+    ],
+    "unavailable": []
+  },
+  "links": [],
+  "detection": []
+}

package/dist/carriers/amazon-shipping/eligibility.d.ts

@@ -0,0 +1,3 @@
+import { type AmazonShippingOptions } from './adapter.js';
+/** A public eligibility check; transport errors remain errors for the consumer to report. */
+export declare function amazonShippingEligibility(number: string, options?: AmazonShippingOptions): Promise<'available' | 'expired' | 'not-found'>;

package/dist/carriers/amazon-shipping/eligibility.js

@@ -0,0 +1,16 @@
+import { AmazonShippingTracker } from './adapter.js';
+import { CarrierError } from '../../core/errors/index.js';
+/** A public eligibility check; transport errors remain errors for the consumer to report. */
+export async function amazonShippingEligibility(number, options = {}) {
+    try {
+        await new AmazonShippingTracker({ ...options, timeoutMs: options.timeoutMs ?? 5_000 }).fetch(number);
+        return 'available';
+    }
+    catch (error) {
+        if (error instanceof CarrierError && error.reason === 'history_expired')
+            return 'expired';
+        if (error instanceof CarrierError && error.reason === 'shipment_not_found')
+            return 'not-found';
+        throw error;
+    }
+}

package/dist/carriers/amazon-shipping/numbers.json

@@ -0,0 +1,67 @@
+{
+  "carrier": "amazon-shipping",
+  "records": [
+    {
+      "number": "FR0000000001",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "amazon-logistics",
+        "confidence": "high"
+      },
+      "note": "Invented placeholder used by the Amazon Shipping tests. Filed under Amazon Shipping; detection selects Amazon Logistics."
+    },
+    {
+      "number": "TBA000000000001",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "amazon-logistics",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format. Filed under Amazon Shipping; detection selects Amazon Logistics."
+    },
+    {
+      "number": "UK3000000001",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "amazon-logistics",
+        "confidence": "high"
+      },
+      "note": "Invented placeholder used by the Amazon Shipping tests. Filed under Amazon Shipping; detection selects Amazon Logistics."
+    },
+    {
+      "number": "UK3962812222",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://uk.trustpilot.com/reviews/69b20895f0f919dee98325b1"
+      },
+      "expect": {
+        "carrier": "amazon-logistics",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Quoted in a merchant's reply with an Amazon tracking link. Filed under Amazon Shipping; detection selects Amazon Logistics."
+    },
+    {
+      "number": "UK4696062386",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer-docs.shipping.amazon.com/apis/docs/tutorial-deliver-to-counter-via-amazon-shipping"
+      },
+      "expect": {
+        "carrier": "amazon-logistics",
+        "confidence": "high"
+      },
+      "note": "Example from Amazon Shipping's own API tutorial. Filed under Amazon Shipping; detection selects Amazon Logistics."
+    }
+  ]
+}

package/dist/carriers/amazon-shipping/status.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Amazon Shipping status classification.
+ *
+ * The tracker sends several loosely related signals per row — a localized
+ * string id (`swa_rex_detail_delivered`), an `eventCode` (`Delivered`), a
+ * `subReasonCode`, and at shipment level a `trackingStatus`, a `status` and
+ * `containerStatusTags`. They are folded into one lower-case, punctuation-free
+ * key and matched as substrings, so `OUT_FOR_DELIVERY`, `outForDelivery` and
+ * `swa_rex_ofd` all land on the same rule.
+ *
+ * Order matters: returns and failures are decided before the broad "delivered"
+ * substring they contain, and delays before the transit words.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../generated/catalog.js';
+export interface ClassifiedStatus {
+    status: CarrierStatus;
+    stage: Stage;
+    description: string;
+}
+export declare const UNKNOWN_STATUS: ClassifiedStatus;
+/** Fold any provider signal into the comparison key: lower case, letters and digits only. */
+export declare function statusKey(value: unknown): string;
+/** Classify one or more provider signals; the first matching rule wins. */
+export declare function classifyStatus(...values: unknown[]): ClassifiedStatus;
+export declare function amazonShippingStatus(value: unknown): CarrierStatus;

package/dist/carriers/amazon-shipping/status.js

@@ -0,0 +1,118 @@
+export const UNKNOWN_STATUS = {
+    status: 'unknown',
+    stage: 'in_transit',
+    description: 'Amazon Shipping update',
+};
+/** Fold any provider signal into the comparison key: lower case, letters and digits only. */
+export function statusKey(value) {
+    if (typeof value !== 'string' && typeof value !== 'number')
+        return '';
+    return String(value).replace(/\s+/g, ' ').trim().slice(0, 200)
+        .toLocaleLowerCase('en-US').replace(/[^a-z0-9]+/g, '');
+}
+function includesAny(value, candidates) {
+    return candidates.some((candidate) => value.includes(candidate));
+}
+/** Classify one or more provider signals; the first matching rule wins. */
+export function classifyStatus(...values) {
+    const key = values.map(statusKey).filter(Boolean).join(' ');
+    if (includesAny(key, [
+        'returnedtoretailer',
+        'returnedtomerchant',
+        'returnedtoshopper',
+        'returnedtoshipper',
+        'returntosender',
+        'returningtosender',
+        'returnedtosender',
+        'lostonreturn',
+    ])) {
+        return { status: 'exception', stage: 'returned', description: 'Returning to sender' };
+    }
+    if (includesAny(key, [
+        'informationneeded',
+        'addressproblem',
+        'damaged',
+        'destroyed',
+        'rejected',
+        'cancelled',
+        'canceled',
+        'lost',
+    ])) {
+        return { status: 'exception', stage: 'exception', description: 'Shipment exception' };
+    }
+    if (includesAny(key, [
+        'deliveryattempted',
+        'failedattempt',
+        'unabletodeliver',
+        'undeliverable',
+    ])) {
+        return { status: 'exception', stage: 'failed_attempt', description: 'Delivery issue' };
+    }
+    if (includesAny(key, ['delayed', 'late'])) {
+        return { status: 'in_transit', stage: 'in_transit', description: 'Delivery delayed' };
+    }
+    if (includesAny(key, ['delivered'])) {
+        return { status: 'delivered', stage: 'delivered', description: 'Delivered' };
+    }
+    if (includesAny(key, [
+        'readyforpickup',
+        'readyforcollection',
+        'holdforpickup',
+        'awaitingcustomerpickup',
+    ])) {
+        return {
+            status: 'out_for_delivery',
+            stage: 'ready_for_pickup',
+            description: 'Ready for pickup',
+        };
+    }
+    if (includesAny(key, ['outfordelivery', 'swarexofd'])) {
+        return {
+            status: 'out_for_delivery',
+            stage: 'out_for_delivery',
+            description: 'Out for delivery',
+        };
+    }
+    if (includesAny(key, ['customs', 'clearance'])) {
+        return { status: 'in_transit', stage: 'customs', description: 'In customs clearance' };
+    }
+    if (includesAny(key, [
+        'pickupdone',
+        'pickedup',
+        'receivedfromseller',
+        'receivedfromshipper',
+        'acceptedbycarrier',
+    ])) {
+        return { status: 'in_transit', stage: 'accepted', description: 'Shipment picked up' };
+    }
+    if (includesAny(key, [
+        'creationconfirmed',
+        'labelcreated',
+        'shippinglabelcreated',
+        'shipmentcreated',
+        'informationreceived',
+        'registered',
+    ])) {
+        return {
+            status: 'pending',
+            stage: 'registered',
+            description: 'Shipment information received',
+        };
+    }
+    if (includesAny(key, [
+        'intransit',
+        'swarexintransit',
+        'received',
+        'departed',
+        'arrived',
+        'sortcenter',
+        'deliverycenter',
+        'transport',
+    ])) {
+        return { status: 'in_transit', stage: 'in_transit', description: 'In transit' };
+    }
+    return UNKNOWN_STATUS;
+}
+export function amazonShippingStatus(value) {
+    return classifyStatus(value).status;
+}

package/dist/carriers/amazon-shipping/statuses.json

@@ -0,0 +1,19 @@
+{
+  "carrier": "amazon-shipping",
+  "entries": [
+    { "code": "RETURNED_TO_SENDER / RETURNED_TO_RETAILER / RETURNED_TO_MERCHANT / RETURNED_TO_SHOPPER / RETURNED_TO_SHIPPER / RETURNING_TO_SENDER / RETURN_TO_SENDER / LOST_ON_RETURN", "stage": "returned", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "Checked before the broad 'delivered' substring." },
+    { "code": "DELIVERY_ATTEMPTED / FAILED_ATTEMPT / UNABLE_TO_DELIVER / UNDELIVERABLE…", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "Reported as 'Delivery issue'." },
+    { "code": "INFORMATION_NEEDED / ADDRESS_PROBLEM / DAMAGED / DESTROYED / REJECTED / CANCELLED / CANCELED / LOST", "stage": "exception", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "Reported as 'Shipment exception'. Reclassified to exception 2026-09-12." },
+    { "code": "DELAYED… / LATE…", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "Reported as 'Delivery delayed'; a delay is not an exception." },
+    { "code": "DELIVERED", "wording": "swa_rex_detail_delivered", "language": "en", "stage": "delivered", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "READY_FOR_PICKUP / READY_FOR_COLLECTION / HOLD_FOR_PICKUP / AWAITING_CUSTOMER_PICKUP", "stage": "ready_for_pickup", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "OUT_FOR_DELIVERY / swa_rex_ofd", "stage": "out_for_delivery", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "CUSTOMS… / CLEARANCE…", "stage": "customs", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "PICKUP_DONE / PICKED_UP / RECEIVED_FROM_SELLER / RECEIVED_FROM_SHIPPER / ACCEPTED_BY_CARRIER", "stage": "accepted", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "Reported as 'Shipment picked up'." },
+    { "code": "CREATION_CONFIRMED / LABEL_CREATED / SHIPPING_LABEL_CREATED / SHIPMENT_CREATED / INFORMATION_RECEIVED / REGISTERED", "wording": "swa_rex_detail_creation_confirmed", "language": "en", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "Reported as 'Shipment information received'." },
+    { "code": "IN_TRANSIT / swa_rex_in_transit / RECEIVED / DEPARTED / ARRIVED / SORT_CENTER / DELIVERY_CENTER / TRANSPORT", "wording": "swa_rex_detail_departed", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "Event descriptions are refined to 'Departed facility', 'Arrived at sorting center' or 'Arrived at delivery center' where the code says so." },
+    { "code": "TRACKING_ID_NOT_FOUND / INVALID_TRACKING_ID", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "Error code, not a stage: HTTP 200 body meaning the id is unknown. Reported as not found." },
+    { "code": "SHIPMENT_OLDER_THAN_SUPPORTED_AGE", "confirmedBy": "fixture", "firstSeen": "2026-09-10", "note": "Error code, not a stage: the shipment exists but its history is past the retention limit. The accompanying IN_TRANSIT summary is a placeholder and is deliberately not mapped." },
+    { "code": "any other status", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "Left unmapped: the shipment falls back to the newest event that does classify, and is reported as unknown if none does." }
+  ]
+}

package/dist/carriers/an-post/carrier.json

@@ -0,0 +1,38 @@
+{
+  "id": "an-post",
+  "displayName": "An Post",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "IE"
+    ]
+  },
+  "brand": {
+    "color": "#00a76a"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "universal",
+    "steps": []
+  },
+  "capabilities": [],
+  "portal": {
+    "url": "https://track.anpost.ie/",
+    "canaryUrl": "https://t.17track.net/",
+    "shows": [],
+    "scraped": [],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [],
+  "detection": [
+    {
+      "id": "an-post-1",
+      "pattern": "^[A-Z]{2}\\d{9}IE$",
+      "confidence": "high",
+      "checksum": "s10"
+    }
+  ]
+}

package/dist/carriers/an-post/numbers.json

@@ -0,0 +1,33 @@
+{
+  "carrier": "an-post",
+  "records": [
+    {
+      "number": "CD009466316IE",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6ab509af46eee3df19b6496d",
+        "date": "2026-09-24"
+      },
+      "expect": {
+        "carrier": "an-post",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "CP476340265IE",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/review/www.anpost.com",
+        "date": "2026-08-31"
+      },
+      "expect": {
+        "carrier": "an-post",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    }
+  ]
+}

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

@@ -0,0 +1,11 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class AramexTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/aramex/adapter.js

@@ -0,0 +1,49 @@
+import { BudgetExceededError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded } from '../../core/transport/index.js';
+import { aramexDetailRedirect, aramexDetailUrl, normalizeAramexNumber, parseAramex } from './parser.js';
+export class AramexTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    fetch(raw, context = {}) {
+        const number = normalizeAramexNumber(raw);
+        return runSteps({ carrier: 'aramex', budgetMs: context.budgetMs ?? 20_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    const started = performance.now();
+                    const get = async (url, regionalRedirect = false) => {
+                        signal.throwIfAborted();
+                        const left = remainingMs - (performance.now() - started);
+                        if (left <= 0)
+                            throw new BudgetExceededError('Aramex', context.budgetMs ?? 20_000);
+                        try {
+                            // The edge rejects Node's default user agent on server networks.
+                            const { response, bytes } = await fetchBounded(url, { signal, headers: {
+                                    Accept: 'text/html', 'User-Agent': 'SwissDeliveryTracker/1.0',
+                                } }, {
+                                provider: 'Aramex', timeoutMs: Math.max(1, Math.floor(left)), maxBytes: 1_500_000,
+                                fetcher: this.options.fetcher, ...(regionalRedirect ? { redirect: 'manual', allowHttpStatuses: [301, 302, 303, 307, 308] } : {}),
+                            });
+                            if (regionalRedirect && [301, 302, 303, 307, 308].includes(response.status)) {
+                                return await get(aramexDetailRedirect(response.headers.get('location') ?? '', url));
+                            }
+                            return decodeText(bytes);
+                        }
+                        catch (error) {
+                            if (error instanceof UpstreamHttpError && [404, 410].includes(error.status))
+                                throw new TransportError('Aramex', 'Aramex tracking endpoint is unavailable', { cause: error });
+                            throw error;
+                        }
+                    };
+                    const overview = await get(`https://www.aramex.com/us/en/track/shipments?ShipmentNumber=${number}`);
+                    const detail = aramexDetailUrl(overview, number);
+                    return parseAramex(await get(detail, true), number);
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new AramexTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'aramex', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
+};

package/dist/carriers/aramex/carrier.json

@@ -0,0 +1,62 @@
+{
+  "id": "aramex",
+  "displayName": "Aramex",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "AE",
+      "SA",
+      "EG",
+      "JO"
+    ]
+  },
+  "brand": {
+    "color": "#dc291e"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "aramex",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history"
+  ],
+  "portal": {
+    "url": "https://www.aramex.com/us/en/track/shipments?ShipmentNumber={trackingNumber}",
+    "canaryUrl": "https://www.aramex.com/us/en/track/shipments",
+    "shows": [
+      "status",
+      "history"
+    ],
+    "scraped": [
+      "status",
+      "history"
+    ],
+    "discarded": [
+      "recipient"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "aramex.com"
+      ],
+      "params": [
+        "ShipmentNumber"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "aramex-1",
+      "pattern": "^\\d{11}$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/aramex/numbers.json

@@ -0,0 +1,71 @@
+{
+  "carrier": "aramex",
+  "records": [
+    {
+      "number": "30109165494",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "postlogistics",
+          "gls-ch",
+          "gls-fr",
+          "gls-de",
+          "blue-dart",
+          "aramex"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Aramex, which stays one candidate among several."
+    },
+    {
+      "number": "34913932303",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6aa34217e4eabf7830d01a11",
+        "date": "2026-09-11"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "postlogistics",
+          "gls-ch",
+          "gls-fr",
+          "gls-de",
+          "blue-dart",
+          "aramex"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Aramex, which stays one candidate among several."
+    },
+    {
+      "number": "52594815954",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6ab224d5d826a3a9645a808f",
+        "date": "2026-09-22"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "postlogistics",
+          "gls-ch",
+          "gls-fr",
+          "gls-de",
+          "blue-dart",
+          "aramex"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Aramex, which stays one candidate among several. Domestic delivery in the UAE."
+    }
+  ]
+}

package/dist/carriers/aramex/parser.d.ts

@@ -0,0 +1,5 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeAramexNumber(raw: string): string;
+export declare function aramexDetailUrl(html: string, number: string): string;
+export declare function aramexDetailRedirect(location: string, original: string): string;
+export declare function parseAramex(html: string, number: string): CarrierResult;