universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/yunexpress/carrier.json

@@ -0,0 +1,69 @@
+{
+  "id": "yunexpress",
+  "displayName": "YunExpress",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "CN"
+    ]
+  },
+  "brand": {
+    "color": "#008284"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "yunexpress",
+    "steps": [
+      "browser",
+      "trawl"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location"
+  ],
+  "portal": {
+    "url": "https://www.yuntrack.com/parcelTracking?id={trackingNumber}",
+    "canaryUrl": "https://www.yuntrack.com/",
+    "shows": [
+      "status",
+      "history",
+      "location"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "www.yuntrack.com",
+        "yuntrack.com"
+      ],
+      "params": [
+        "id"
+      ]
+    },
+    {
+      "domains": [
+        "www.yuntrack.com",
+        "yuntrack.com"
+      ],
+      "path": "/Track/Detail/([A-Z0-9]+)"
+    }
+  ],
+  "detection": [
+    {
+      "id": "yunexpress-1",
+      "pattern": "^YT\\d{16}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/yunexpress/numbers.json

@@ -0,0 +1,32 @@
+{
+  "carrier": "yunexpress",
+  "records": [
+    {
+      "number": "YT2621200705470145",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.reddit.com/r/AirReps/comments/1vfhh53/please_help_yunexpress_alibaba_tracking_stuck_on/"
+      },
+      "expect": {
+        "carrier": "yunexpress",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "YT2623100700785323",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a9c1d3f497adcfb20e6f16e",
+        "date": "2026-09-05"
+      },
+      "expect": {
+        "carrier": "yunexpress",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    }
+  ]
+}

package/dist/carriers/yunexpress/status.d.ts

@@ -0,0 +1,2 @@
+import type { ClassifiedStatus } from '../../core/status/index.js';
+export declare function yunExpressStatus(description: string, code?: unknown): ClassifiedStatus | undefined;

package/dist/carriers/yunexpress/status.js

@@ -0,0 +1,23 @@
+const WORDING = new Map([
+    ['Shipment information received', { status: 'pending', stage: 'registered' }],
+    ['Shipment picked up', { status: 'in_transit', stage: 'accepted' }],
+    ['Arrived at origin facility', { status: 'in_transit', stage: 'in_transit' }],
+    ['Departed from sort facility', { status: 'in_transit', stage: 'in_transit' }],
+    ['Shipment is in transit to next facility', { status: 'in_transit', stage: 'in_transit' }],
+    ['The country of origin commences customs declaration.', { status: 'in_transit', stage: 'customs' }],
+    ['Arrived at the origin international airport', { status: 'in_transit', stage: 'in_transit' }],
+    ['Clearence processing completed - Export', { status: 'in_transit', stage: 'in_transit' }],
+    ['International flight has departed', { status: 'in_transit', stage: 'in_transit' }],
+    ['International flight has arrived', { status: 'in_transit', stage: 'in_transit' }],
+    ['Start Customs Clearence', { status: 'in_transit', stage: 'customs' }],
+    ['Collected at Cargo Terminal', { status: 'in_transit', stage: 'in_transit' }],
+    ['Clearance processing completed - Import', { status: 'in_transit', stage: 'in_transit' }],
+    ['Customs inspection - Import', { status: 'in_transit', stage: 'customs' }],
+]);
+export function yunExpressStatus(description, code) {
+    // The latest event's explicit delivered code also covers partner wording
+    // containing variable delivery notes. It is never inherited by older scans.
+    if (code === 50)
+        return { status: 'delivered', stage: 'delivered' };
+    return WORDING.get(description);
+}

package/dist/carriers/yunexpress/statuses.json

@@ -0,0 +1,112 @@
+{
+  "carrier": "yunexpress",
+  "entries": [
+    {
+      "wording": "Customs inspection - Import",
+      "stage": "customs",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Clearance processing completed - Import",
+      "stage": "in_transit",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Collected at Cargo Terminal",
+      "stage": "in_transit",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Start Customs Clearence",
+      "stage": "customs",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "International flight has arrived",
+      "stage": "in_transit",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "International flight has departed",
+      "stage": "in_transit",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Clearence processing completed - Export",
+      "stage": "in_transit",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Arrived at the origin international airport",
+      "stage": "in_transit",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "The country of origin commences customs declaration.",
+      "stage": "customs",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Shipment is in transit to next facility",
+      "stage": "in_transit",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Departed from sort facility",
+      "stage": "in_transit",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Arrived at origin facility",
+      "stage": "in_transit",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Shipment picked up",
+      "stage": "accepted",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "wording": "Shipment information received",
+      "stage": "registered",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "50",
+      "wording": "Delivered by Mailbox",
+      "stage": "delivered",
+      "language": "en",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28",
+      "note": "The exact latest event declares delivered; variable partner delivery notes remain descriptive."
+    }
+  ]
+}

package/dist/carriers/zto/carrier.json

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

package/dist/carriers/zto/numbers.json

@@ -0,0 +1,30 @@
+{
+  "carrier": "zto",
+  "records": [
+    {
+      "number": "778564698005",
+      "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",
+          "mondial-relay",
+          "colis-prive",
+          "mrw",
+          "sf-express",
+          "sto",
+          "zto",
+          "yamato",
+          "j-and-t"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to ZTO Express, which stays one candidate among several."
+    }
+  ]
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[], env?: NodeJS.ProcessEnv): Promise<number>;

package/dist/cli/index.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { createTracker, TrackingError } from '../facade/index.js';
+import { CARRIER_CATALOG } from '../generated/catalog.js';
+import { createTrackingServer } from '../server/index.js';
+const help = `Universal Parcel Scraper
+
+  parcel-scraper detect <number, link or text>
+  parcel-scraper recognize <number>
+  parcel-scraper track <number> [--carrier <id>] [--postcode <value>] [--tracking-url <url>]
+  parcel-scraper carriers
+  parcel-scraper serve [--host <address>] [--port <port>]
+
+SCRAPER_PROVIDERS selects comma-separated providers; default: UPU.
+FLARESOLVERR_URL and TRACKING_CHROMIUM_PATH enable browser transports.
+SCRAPER_TOKEN protects the HTTP API. SCRAPER_DEMO_PAGE=true enables its one-off page.`;
+export async function main(argv = process.argv.slice(2), env = process.env) {
+    const [command, ...args] = argv;
+    if (!command || ['--help', '-h', 'help'].includes(command)) {
+        console.log(help);
+        return 0;
+    }
+    const values = {};
+    const positional = [];
+    const allowed = command === 'track' ? ['carrier', 'postcode', 'tracking-url'] : command === 'serve' ? ['host', 'port'] : [];
+    for (let i = 0; i < args.length; i++) {
+        const argument = args[i];
+        if (!argument.startsWith('--')) {
+            positional.push(argument);
+            continue;
+        }
+        const name = argument.slice(2);
+        if (!allowed.includes(name) || !args[i + 1] || args[i + 1].startsWith('--'))
+            throw new TypeError('Unknown or incomplete command option');
+        values[name] = args[++i];
+    }
+    const providers = env.SCRAPER_PROVIDERS === undefined ? undefined
+        : env.SCRAPER_PROVIDERS.split(',').map(value => value.trim()).filter(Boolean);
+    const options = { providers, trawlUrl: env.FLARESOLVERR_URL, chromiumPath: env.TRACKING_CHROMIUM_PATH, env };
+    const tracker = createTracker(options);
+    const print = (value) => console.log(JSON.stringify(value, null, 2));
+    if (command === 'carriers' && positional.length === 0) {
+        print(CARRIER_CATALOG);
+        return 0;
+    }
+    if (command === 'serve' && positional.length === 0) {
+        const port = Number(values.port ?? env.PORT ?? 8080);
+        if (!Number.isInteger(port) || port < 1 || port > 65535)
+            throw new TypeError('Invalid port');
+        const host = values.host ?? env.HOST ?? '127.0.0.1';
+        const server = createTrackingServer({ ...options, token: env.SCRAPER_TOKEN, demoPage: env.SCRAPER_DEMO_PAGE === 'true',
+            log: record => console.error(JSON.stringify(record)) });
+        await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, host, resolve); });
+        console.error(`Parcel tracking server listening on ${host}:${port}`);
+        for (const signal of ['SIGINT', 'SIGTERM'])
+            process.once(signal, () => server.close());
+        return 0;
+    }
+    const input = positional.join(' ');
+    if (!input)
+        throw new TypeError('Supply a tracking input');
+    if (command === 'detect')
+        print(tracker.detect(input));
+    else if (command === 'recognize')
+        print(await tracker.recognize(input));
+    else if (command === 'track')
+        print(await tracker.track({ number: input, carrier: values.carrier, postcode: values.postcode, trackingUrl: values['tracking-url'] }));
+    else
+        throw new TypeError('Unknown command; use --help');
+    return 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    try {
+        process.exitCode = await main();
+    }
+    catch (error) {
+        console.error(error instanceof TrackingError ? JSON.stringify({ error: error.message, attempts: error.attempts, hint: error.hint })
+            : error instanceof TypeError ? 'Invalid input or command; use --help' : 'Tracking could not be completed');
+        process.exitCode = 1;
+    }
+}

package/dist/core/adapter/index.d.ts

@@ -0,0 +1,90 @@
+import type { CarrierResult } from '../result/index.js';
+import type { StepRecorder } from '../telemetry/index.js';
+import type { TrawlClient } from '../transport/trawl.js';
+export interface TrackingInput {
+    /** The tracking number as stored on the parcel, validated at the API boundary. */
+    number: string;
+    /** A capability URL for carriers that need one (shared Planzer links, Dachser). */
+    trackingUrl?: string | null;
+    /** The delivery postcode for carriers that need one; part of the tracking credential. */
+    postcode?: string | null;
+    /**
+     * The zone of the carrier the parcel is filed under, for universal providers
+     * whose scan times name no zone they can be trusted with. When that
+     * carrier's catalog zone is UTC, the zone of the carrier a direct lookup
+     * confirmed for the same number. Never a guess: absent when neither has one.
+     */
+    timezone?: string | null;
+}
+export interface TrackingContext {
+    signal?: AbortSignal;
+    /** Overrides the adapter's default lookup budget. */
+    budgetMs?: number;
+}
+export interface AdapterEnvironment {
+    /** Test seam; production uses the global fetch. */
+    fetcher?: typeof fetch;
+    /** The private browser service, or null when not configured. */
+    trawl: TrawlClient | null;
+    /** A Chromium executable for adapters that must run a browser locally, or null. */
+    browserExecutablePath: string | null;
+    recorder: StepRecorder;
+    /** Provider-specific configuration (feature flags, optional endpoints). */
+    env: Readonly<Record<string, string | undefined>>;
+}
+/** Whether a carrier knows a tracking number, from a cheap check. */
+export interface Recognition {
+    known: boolean;
+    /** The newest activity the check saw, when it reports one; old parcels can share a reused number. */
+    lastActivityAt?: string | null;
+}
+export interface CarrierAdapter {
+    readonly id: string;
+    /** The tiers this adapter can go through, in order; telemetry labels use these ids. */
+    readonly steps: readonly string[];
+    /** The adapter records its own steps, including single-step protocols. */
+    readonly recordsSteps?: boolean;
+    track(input: TrackingInput, context?: TrackingContext): Promise<CarrierResult>;
+    /**
+     * Required when carrier.json declares `tracking.recognition`: whether the
+     * carrier knows the number, without the user's inputs, through plain HTTP
+     * only (never a browser tier). A positive not-found is `known: false`; any
+     * other failure throws.
+     */
+    recognize?(number: string, context?: TrackingContext): Promise<Recognition>;
+}
+export type AdapterFactory = (environment: AdapterEnvironment) => CarrierAdapter;
+/**
+ * `recognize()` for an adapter whose ordinary lookup is already cheap: a
+ * result with scans, or a status past pending, is known; a positive not-found
+ * is unknown; any other failure is thrown. `accepts` is the adapter's own
+ * number check: a form it cannot look up is unknown without a request. Only
+ * for lookups without a browser tier.
+ */
+/** Whether a number check passes: false when it throws its TypeError. */
+export declare function accepted(check: () => unknown): boolean;
+export declare function recognizeFromLookup(lookup: () => Promise<CarrierResult>, accepts?: () => boolean): Promise<Recognition>;
+/** Registered adapter factories plus the carrier → adapter mapping, as generated. */
+export interface RegistryDefinition {
+    factories: Readonly<Record<string, AdapterFactory>>;
+    /** Carrier id → adapter id (a key of `factories`), 'universal', or null for link-only carriers. */
+    carriers: Readonly<Record<string, string | null>>;
+}
+/**
+ * One adapter instance per adapter id for the process lifetime, created on
+ * first use so a broken provider module cannot prevent unrelated carriers
+ * from syncing.
+ */
+export declare class AdapterRegistry {
+    private readonly definition;
+    private readonly environment;
+    private readonly instances;
+    constructor(definition: RegistryDefinition, environment: AdapterEnvironment);
+    /** The adapter id that serves this carrier, 'universal', or null. */
+    adapterIdFor(carrierId: string): string | null;
+    /** Whether a dedicated adapter module serves this carrier. */
+    has(carrierId: string): boolean;
+    for(carrierId: string): CarrierAdapter | null;
+    /** Every dedicated adapter id, for canaries and documentation. */
+    adapterIds(): string[];
+}

package/dist/core/adapter/index.js

@@ -0,0 +1,103 @@
+/**
+ * The contract between the host and a carrier adapter.
+ *
+ * A carrier folder exports an `AdapterFactory`; the generated registry lists
+ * every factory by carrier id, and the host creates one adapter instance per
+ * process through an `AdapterRegistry`. An adapter owns its sessions and
+ * declares its steps; it reaches the network only through what the
+ * `AdapterEnvironment` provides, and it reports through the `StepRecorder`.
+ */
+import { carrierErrorKind } from '../errors/index.js';
+import { explicitOffsetTime } from '../time/index.js';
+/**
+ * `recognize()` for an adapter whose ordinary lookup is already cheap: a
+ * result with scans, or a status past pending, is known; a positive not-found
+ * is unknown; any other failure is thrown. `accepts` is the adapter's own
+ * number check: a form it cannot look up is unknown without a request. Only
+ * for lookups without a browser tier.
+ */
+/** Whether a number check passes: false when it throws its TypeError. */
+export function accepted(check) {
+    try {
+        check();
+        return true;
+    }
+    catch (error) {
+        if (error instanceof TypeError)
+            return false;
+        throw error;
+    }
+}
+export async function recognizeFromLookup(lookup, accepts = () => true) {
+    if (!accepts())
+        return { known: false };
+    let result;
+    try {
+        result = await lookup();
+    }
+    catch (error) {
+        if (carrierErrorKind(error) === 'not_found')
+            return { known: false };
+        throw error;
+    }
+    // Local clocks and malformed dates cannot rank reuse of a tracking number.
+    const iso = (value) => {
+        if (typeof value !== 'string')
+            return Number.NaN;
+        const raw = value.trim();
+        // Luxon normalizes impossible offsets such as +02:99 or +99:00.
+        // Those are unresolved clocks, not instants that can rank a match.
+        return /^\d{4}-\d{2}-\d{2}T/.test(raw) && /(?:Z|[+-](?:[01]\d|2[0-3]):?[0-5]\d)$/i.test(raw)
+            ? explicitOffsetTime(raw)?.timestamp ?? Number.NaN : Number.NaN;
+    };
+    const times = (result.events ?? []).map((event) => iso(event.time)).filter(Number.isFinite);
+    // A pending status without a scan is no evidence: some carriers answer any number that way.
+    const known = (result.events?.length ?? 0) > 0 || !['unknown', 'pending', undefined].includes(result.status);
+    const updated = iso(result.last_update);
+    return {
+        known,
+        lastActivityAt: !known ? null : times.length ? new Date(Math.max(...times)).toISOString()
+            : Number.isFinite(updated) ? new Date(updated).toISOString() : null,
+    };
+}
+/**
+ * One adapter instance per adapter id for the process lifetime, created on
+ * first use so a broken provider module cannot prevent unrelated carriers
+ * from syncing.
+ */
+export class AdapterRegistry {
+    definition;
+    environment;
+    instances = new Map();
+    constructor(definition, environment) {
+        this.definition = definition;
+        this.environment = environment;
+    }
+    /** The adapter id that serves this carrier, 'universal', or null. */
+    adapterIdFor(carrierId) {
+        return this.definition.carriers[carrierId] ?? null;
+    }
+    /** Whether a dedicated adapter module serves this carrier. */
+    has(carrierId) {
+        const adapterId = this.adapterIdFor(carrierId);
+        return adapterId !== null && adapterId !== 'universal' && Object.hasOwn(this.definition.factories, adapterId);
+    }
+    for(carrierId) {
+        const adapterId = this.adapterIdFor(carrierId);
+        if (adapterId === null || adapterId === 'universal')
+            return null;
+        const factory = this.definition.factories[adapterId];
+        if (!factory)
+            return null;
+        let instance = this.instances.get(adapterId);
+        if (!instance) {
+            instance = factory(this.environment);
+            this.instances.set(adapterId, instance);
+        }
+        return instance;
+    }
+    /** Every dedicated adapter id, for canaries and documentation. */
+    adapterIds() {
+        return Object.keys(this.definition.factories);
+    }
+}

package/dist/core/adapter/track.d.ts

@@ -0,0 +1,10 @@
+import { type CarrierResult } from '../result/index.js';
+import { type StepRecorder } from '../telemetry/index.js';
+import type { UniversalTracker } from '../../providers/universal.js';
+import type { AdapterRegistry, TrackingContext, TrackingInput } from './index.js';
+/** One carrier lookup, leaving provider selection and scheduling to the consumer. */
+export declare function trackCarrier(carrier: string, input: TrackingInput, options: TrackingContext & {
+    registry: AdapterRegistry;
+    universal: UniversalTracker;
+    recorder?: StepRecorder;
+}): Promise<CarrierResult>;

package/dist/core/adapter/track.js

@@ -0,0 +1,20 @@
+import { normalizeCarrierResult } from '../result/index.js';
+import { runSteps } from '../runner/index.js';
+import { NOOP_RECORDER } from '../telemetry/index.js';
+/** One carrier lookup, leaving provider selection and scheduling to the consumer. */
+export async function trackCarrier(carrier, input, options) {
+    const registered = options.registry.for(carrier);
+    if (registered) {
+        const context = { signal: options.signal, budgetMs: options.budgetMs === undefined ? undefined : Math.min(60_000, options.budgetMs) };
+        const result = registered.recordsSteps || registered.steps.length > 1
+            ? await registered.track(input, ...(options.signal || options.budgetMs !== undefined ? [context] : []))
+            : await runSteps({ carrier, budgetMs: options.budgetMs ?? 120_000, signal: options.signal,
+                recorder: options.recorder ?? NOOP_RECORDER }, [{ id: registered.steps[0] ?? 'direct',
+                    run: ({ signal, remainingMs }) => registered.track(input, ...(options.signal || options.budgetMs !== undefined ? [{ signal, budgetMs: context.budgetMs === undefined ? undefined : Math.min(context.budgetMs, remainingMs) }] : [])) }]);
+        return normalizeCarrierResult(result);
+    }
+    if (options.registry.adapterIdFor(carrier) === 'universal') {
+        return normalizeCarrierResult(await options.universal.fetch(input.number, input.postcode));
+    }
+    throw new RangeError(`No tracking adapter is registered for ${carrier}`);
+}

package/dist/core/catalog/amazon.d.ts

@@ -0,0 +1,5 @@
+export declare function requiresAmazonAccount(carrier: string, trackingNumber?: string): boolean;
+export declare function amazonMarketplace(raw: string): string;
+export declare function amazonOrdersUrl(raw: string): string;
+export declare function amazonShippingOrigin(raw: string): string;
+export declare function amazonShippingUrl(raw: string): string;

package/dist/core/catalog/amazon.js

@@ -0,0 +1,33 @@
+/**
+ * Amazon portal links.
+ *
+ * What it is: the marketplace mapping behind Amazon's order-history and public
+ * Amazon Shipping URLs, and the rule that decides when a parcel can only be
+ * followed inside the customer's Amazon account.
+ * What it is not: no account state, no eligibility probe, no provider I/O; the
+ * server checks public availability separately.
+ */
+import { isAmazonTrackingNumber } from '../detection/amazon.js';
+export function requiresAmazonAccount(carrier, trackingNumber = '') {
+    return carrier !== 'amazon-shipping' && (carrier === 'amazon-logistics' || isAmazonTrackingNumber(trackingNumber));
+}
+export function amazonMarketplace(raw) {
+    const prefix = raw.replace(/[\s.-]/g, '').toUpperCase().slice(0, 2);
+    const marketplaces = {
+        FR: 'fr', DE: 'de', AT: 'de', BE: 'com.be', UK: 'co.uk', GB: 'co.uk',
+        IT: 'it', ES: 'es', PT: 'es', NL: 'nl', IE: 'ie', PL: 'pl', SE: 'se', TR: 'com.tr',
+    };
+    return marketplaces[prefix] ?? 'com';
+}
+export function amazonOrdersUrl(raw) {
+    return `https://www.amazon.${amazonMarketplace(raw)}/gp/your-account/order-history`;
+}
+// These public portals share Amazon's European tracker; DE/BE have no portal of their own.
+export function amazonShippingOrigin(raw) {
+    const prefix = raw.replace(/[\s.-]/g, '').toUpperCase().slice(0, 2);
+    const domains = { IT: 'it', ES: 'es', UK: 'co.uk', GB: 'co.uk', TB: 'com' };
+    return `https://track.amazon.${domains[prefix] ?? 'fr'}`;
+}
+export function amazonShippingUrl(raw) {
+    return `${amazonShippingOrigin(raw)}/tracking/${encodeURIComponent(raw.replace(/[\s.-]/g, '').toUpperCase())}`;
+}