universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/core/detection/gls.js

@@ -0,0 +1,21 @@
+/**
+ * GLS parcel number check digit.
+ *
+ * What it is: the check used by the `"gls"` detection rules on 12-digit
+ * numbers, which are otherwise shared with FedEx, Mondial Relay, SF Express
+ * and others.
+ * What it is not: no carrier lookup and no provider I/O. The caller passes an
+ * already-normalized number; anything else fails the digits-only shape test.
+ */
+/**
+ * 11 digits and a modulo-10 check digit: weights 3, 1, 3, … from the right,
+ * plus one (paketda.de's "Paket-Prüfziffern"; GLS ShipIT answers a 12-digit
+ * number with its first 11 digits). An 11-digit number is the same parcel
+ * number without its check digit and has nothing to verify.
+ */
+export function isValidGlsParcelNumber(value) {
+    if (!/^\d{12}$/.test(value))
+        return false;
+    const sum = [...value.slice(0, 11)].reverse().reduce((total, digit, i) => total + Number(digit) * (i % 2 === 0 ? 3 : 1), 1);
+    return (10 - (sum % 10)) % 10 === Number(value[11]);
+}

package/dist/core/detection/hermes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Hermes Germany legacy parcel number check digit.
+ *
+ * What it is: the check used by the `"hermes"` detection rule on 14-digit
+ * numbers, which are otherwise shared with DPD, BRT, SEUR and others.
+ * What it is not: no carrier lookup and no provider I/O. The caller passes an
+ * already-normalized number; anything else fails the digits-only shape test.
+ */
+/**
+ * 13 digits and a modulo-10 check digit, weighted 3, 1, 3, … from the left
+ * (the EAN scheme). Documented by paketda.de ("Paket-Prüfziffern"); every
+ * publicly reported 14-digit Hermes number in the corpus passes it.
+ */
+export declare function isValidHermesParcelNumber(value: string): boolean;

package/dist/core/detection/hermes.js

@@ -0,0 +1,19 @@
+/**
+ * Hermes Germany legacy parcel number check digit.
+ *
+ * What it is: the check used by the `"hermes"` detection rule on 14-digit
+ * numbers, which are otherwise shared with DPD, BRT, SEUR and others.
+ * What it is not: no carrier lookup and no provider I/O. The caller passes an
+ * already-normalized number; anything else fails the digits-only shape test.
+ */
+/**
+ * 13 digits and a modulo-10 check digit, weighted 3, 1, 3, … from the left
+ * (the EAN scheme). Documented by paketda.de ("Paket-Prüfziffern"); every
+ * publicly reported 14-digit Hermes number in the corpus passes it.
+ */
+export function isValidHermesParcelNumber(value) {
+    if (!/^\d{14}$/.test(value))
+        return false;
+    const sum = [...value.slice(0, 13)].reduce((total, digit, i) => total + Number(digit) * (i % 2 === 0 ? 3 : 1), 0);
+    return (10 - (sum % 10)) % 10 === Number(value[13]);
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Tracking-number detection.
+ *
+ * What it is: the one engine that normalizes a number, validates its checksum,
+ * decides which carrier it belongs to, and parses whatever a user pastes. The
+ * web client, the server and the corpus sweep all import it from here.
+ * What it is not: no provider I/O, no HTTP, no Node APIs, no application or
+ * framework code — it bundles for the browser unchanged.
+ */
+export type { CarrierDetection, DetectionConfidence, TrackingInputMatch, } from './types.js';
+export { AMAZON_NUMBER_PATTERN, isAmazonTrackingNumber } from './amazon.js';
+export { TRACKING_CANDIDATE_PATTERNS, keywordNumberInText, recognizedNumberInText, } from './candidates.js';
+export { detectCarrier, detectCarrierMatch } from './detect.js';
+export { isValidGlsParcelNumber } from './gls.js';
+export { isValidHermesParcelNumber } from './hermes.js';
+export { isValidMondialRelayBarcode } from './mondialRelay.js';
+export { formatTrackingNumber, isPlanzerSharedTrackingNumber, normalizeTrackingNumber, validTrackingNumber, } from './normalize.js';
+export { parseTrackingInput } from './parse.js';
+export { isValidS10TrackingNumber, supportsSwissPostHandoff } from './s10.js';

package/dist/core/detection/index.js

@@ -0,0 +1,9 @@
+export { AMAZON_NUMBER_PATTERN, isAmazonTrackingNumber } from './amazon.js';
+export { TRACKING_CANDIDATE_PATTERNS, keywordNumberInText, recognizedNumberInText, } from './candidates.js';
+export { detectCarrier, detectCarrierMatch } from './detect.js';
+export { isValidGlsParcelNumber } from './gls.js';
+export { isValidHermesParcelNumber } from './hermes.js';
+export { isValidMondialRelayBarcode } from './mondialRelay.js';
+export { formatTrackingNumber, isPlanzerSharedTrackingNumber, normalizeTrackingNumber, validTrackingNumber, } from './normalize.js';
+export { parseTrackingInput } from './parse.js';
+export { isValidS10TrackingNumber, supportsSwissPostHandoff } from './s10.js';

package/dist/core/detection/mondialRelay.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Mondial Relay label barcode checksum.
+ *
+ * What it is: the 26-digit label check used by the `"mondial-relay"` detection
+ * rule and by input validation.
+ * What it is not: no carrier lookup and no provider I/O. The caller passes an
+ * already-normalized number; anything else fails the digits-only shape test.
+ */
+/** Mondial Relay label specification v2.4, pages 5–7 (July 2024).
+ * https://storage.mondialrelay.fr/etiquette-mondial-relay-v-24.pdf
+ * Brand(2), shipment(8), sequence(2), count(2), check(1), routing(10), check(1).
+ */
+export declare function isValidMondialRelayBarcode(value: string): boolean;

package/dist/core/detection/mondialRelay.js

@@ -0,0 +1,25 @@
+/**
+ * Mondial Relay label barcode checksum.
+ *
+ * What it is: the 26-digit label check used by the `"mondial-relay"` detection
+ * rule and by input validation.
+ * What it is not: no carrier lookup and no provider I/O. The caller passes an
+ * already-normalized number; anything else fails the digits-only shape test.
+ */
+/** Mondial Relay label specification v2.4, pages 5–7 (July 2024).
+ * https://storage.mondialrelay.fr/etiquette-mondial-relay-v-24.pdf
+ * Brand(2), shipment(8), sequence(2), count(2), check(1), routing(10), check(1).
+ */
+export function isValidMondialRelayBarcode(value) {
+    if (!/^\d{26}$/.test(value))
+        return false;
+    const check = (digits) => {
+        const sum = [...digits].reverse().reduce((total, digit, i) => total + Number(digit) * (2 + i % 6), 0);
+        const remainder = 11 - sum % 11;
+        return String(remainder >= 10 ? 0 : remainder);
+    };
+    const sequence = Number(value.slice(10, 12));
+    const count = Number(value.slice(12, 14));
+    return sequence > 0 && sequence <= count
+        && check(value.slice(0, 14)) === value[14] && check(value.slice(15, 25)) === value[25];
+}

package/dist/core/detection/normalize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tracking-number normalization and display formatting.
+ *
+ * What it is: the one place that decides what "the same number" means, plus
+ * the printed grouping carriers use on their labels.
+ * What it is not: no carrier lookup, no checksum validation, no provider I/O.
+ */
+/** Uppercase and strip spaces, dots and dashes (Swiss Post prints 99.34.…). */
+export declare function normalizeTrackingNumber(raw: string): string;
+/** Capability-link shipment numbers look like 999.90.########. */
+export declare function isPlanzerSharedTrackingNumber(raw: string): boolean;
+/** Swiss carriers show 18-digit barcodes as 99.34.123456.12345678. */
+export declare function formatTrackingNumber(raw: string, carrier?: string): string;
+/** Shape gate applied to anything pulled out of a link or pasted prose. */
+export declare function validTrackingNumber(raw: string): boolean;

package/dist/core/detection/normalize.js

@@ -0,0 +1,39 @@
+import { postlogisticsIdentifier } from '../../carriers/postlogistics/number.js';
+/**
+ * Tracking-number normalization and display formatting.
+ *
+ * What it is: the one place that decides what "the same number" means, plus
+ * the printed grouping carriers use on their labels.
+ * What it is not: no carrier lookup, no checksum validation, no provider I/O.
+ */
+/** Uppercase and strip spaces, dots and dashes (Swiss Post prints 99.34.…). */
+export function normalizeTrackingNumber(raw) {
+    return raw.toUpperCase().replace(/[\s.-]/g, '');
+}
+/** Capability-link shipment numbers look like 999.90.########. */
+export function isPlanzerSharedTrackingNumber(raw) {
+    return /^99990\d{8}$/.test(normalizeTrackingNumber(raw));
+}
+/** Swiss carriers show 18-digit barcodes as 99.34.123456.12345678. */
+export function formatTrackingNumber(raw, carrier) {
+    if (carrier === 'postlogistics')
+        return postlogisticsIdentifier(raw);
+    const value = normalizeTrackingNumber(raw);
+    if (isPlanzerSharedTrackingNumber(value)) {
+        return `${value.slice(0, 3)}.${value.slice(3, 5)}.${value.slice(5)}`;
+    }
+    if (/^\d{18}$/.test(value)) {
+        return `${value.slice(0, 2)}.${value.slice(2, 4)}.${value.slice(4, 10)}.${value.slice(10)}`;
+    }
+    return value;
+}
+/** Shape gate applied to anything pulled out of a link or pasted prose. */
+export function validTrackingNumber(raw) {
+    const normalized = normalizeTrackingNumber(raw);
+    return normalized.length >= 4
+        && normalized.length <= 40
+        // The NACEX agency/shipment composite is the only tracking shape allowed
+        // to keep punctuation; everything else stays strict alphanumeric.
+        && (/^[A-Z0-9]+$/.test(normalized) || /^\d{4}\/\d{8}$/.test(normalized))
+        && /\d/.test(normalized);
+}

package/dist/core/detection/parse.d.ts

@@ -0,0 +1,6 @@
+import type { TrackingInputMatch } from './types.js';
+/**
+ * Pull a tracking number and carrier out of a number, carrier URL, or pasted
+ * shipping message. Number shape disambiguates links shared by multiple brands.
+ */
+export declare function parseTrackingInput(raw: string): TrackingInputMatch;

package/dist/core/detection/parse.js

@@ -0,0 +1,112 @@
+/**
+ * Pasted-input parsing.
+ *
+ * What it is: turns whatever a user pastes — a bare number, a carrier link, or
+ * a whole shipping message — into a tracking number plus a carrier, using the
+ * catalog link rules and then the detection engine.
+ * What it is not: it never fetches the pasted URL and performs no provider I/O;
+ * every decision comes from the string and the catalog.
+ */
+import { TRACKING_LINK_RULES, matchesDomain } from '../catalog/linkRules.js';
+import { keywordNumberInText, recognizedNumberInText } from './candidates.js';
+import { detectCarrierMatch } from './detect.js';
+import { validTrackingNumber } from './normalize.js';
+function trimPastedUrl(raw) {
+    return raw.replace(/^[\s<'"(\x5b]+/, '').replace(/[\s>'")\],;.!?]+$/, '');
+}
+function cleanLinkTrackingNumber(raw) {
+    return raw.split(/[,|]/, 1)[0].trim();
+}
+function queryParam(url, names) {
+    const wanted = new Set(names.map((name) => name.toLowerCase()));
+    for (const [name, value] of url.searchParams) {
+        if (wanted.has(name.toLowerCase()) && value.trim())
+            return value;
+    }
+    return undefined;
+}
+function numberFromRule(url, rule) {
+    const fromQuery = rule.params ? queryParam(url, rule.params) : undefined;
+    const fromPath = rule.path?.exec(url.pathname)?.[1];
+    const fromFragment = rule.fragment?.exec(decodeURIComponent(url.hash.slice(1)))?.[1];
+    const candidate = cleanLinkTrackingNumber(fromQuery ?? fromPath ?? fromFragment ?? '');
+    return validTrackingNumber(candidate) ? candidate : undefined;
+}
+function trackingMatch(trackingNumber, source) {
+    return { trackingNumber, source, ...detectCarrierMatch(trackingNumber) };
+}
+/**
+ * Pull a tracking number and carrier out of a number, carrier URL, or pasted
+ * shipping message. Number shape disambiguates links shared by multiple brands.
+ */
+export function parseTrackingInput(raw) {
+    const input = raw.trim();
+    if (!input) {
+        return {
+            trackingNumber: '',
+            carrier: 'unknown',
+            confidence: 'none',
+            candidates: [],
+            preferred: [],
+            source: 'none',
+        };
+    }
+    const pastedUrls = input.match(/https?:\/\/[^\s<>"']+/gi) ?? [];
+    for (const pastedUrl of pastedUrls) {
+        const trackingUrl = trimPastedUrl(pastedUrl);
+        try {
+            const url = new URL(trackingUrl);
+            const rules = TRACKING_LINK_RULES.filter((candidate) => candidate.domains.some((domain) => matchesDomain(url.hostname.toLowerCase(), domain))
+                && (!candidate.pathPattern || candidate.pathPattern.test(url.pathname)));
+            const specificity = (rule) => Math.max(...rule.domains.filter((domain) => matchesDomain(url.hostname.toLowerCase(), domain)).map((domain) => domain.length));
+            rules.sort((a, b) => specificity(b) - specificity(a));
+            for (const firstRule of rules) {
+                const trackingNumber = numberFromRule(url, firstRule);
+                if (trackingNumber) {
+                    const detected = detectCarrierMatch(trackingNumber);
+                    if (firstRule.detectFromNumber && detected.confidence === 'high') {
+                        return { trackingNumber, ...detected, source: 'link' };
+                    }
+                    const suggestedRules = rules.filter((candidate) => detected.candidates.includes(candidate.carrier));
+                    const suggestedCarriers = new Set(suggestedRules.map((candidate) => candidate.carrier));
+                    const rule = detected.confidence === 'high'
+                        ? rules.find((candidate) => candidate.carrier === detected.carrier) ?? firstRule
+                        : suggestedCarriers.size === 1 ? suggestedRules[0] : firstRule;
+                    return {
+                        trackingNumber,
+                        carrier: rule.carrier,
+                        confidence: 'high',
+                        candidates: [rule.carrier],
+                        preferred: [],
+                        trackingUrl: rule.keepsCapabilityUrl ? trackingUrl : undefined,
+                        source: 'link',
+                    };
+                }
+            }
+            const trackingNumber = recognizedNumberInText(decodeURIComponent(url.href));
+            if (trackingNumber)
+                return trackingMatch(trackingNumber, 'link');
+        }
+        catch {
+            // Keep looking: pasted prose can contain a truncated or malformed URL.
+        }
+    }
+    const recognized = recognizedNumberInText(input);
+    if (recognized) {
+        return trackingMatch(recognized, input === recognized ? 'number' : 'text');
+    }
+    const keywordNumber = keywordNumberInText(input);
+    if (keywordNumber)
+        return trackingMatch(keywordNumber, 'text');
+    if (!input.includes('://') && validTrackingNumber(input)) {
+        return trackingMatch(input, 'number');
+    }
+    return {
+        trackingNumber: '',
+        carrier: 'unknown',
+        confidence: 'none',
+        candidates: [],
+        preferred: [],
+        source: 'none',
+    };
+}

package/dist/core/detection/s10.d.ts

@@ -0,0 +1,4 @@
+/** Validate the UPU S10 check digit, not only its broad A2-N9-A2 shape. */
+export declare function isValidS10TrackingNumber(raw: string): boolean;
+/** Swiss-issued tracked letter-post can move from Cainiao to Swiss Post. */
+export declare function supportsSwissPostHandoff(raw: string): boolean;

package/dist/core/detection/s10.js

@@ -0,0 +1,25 @@
+/**
+ * UPU S10 check digit.
+ *
+ * What it is: the single S10 validator used by the client, the server adapters
+ * and the detection rules that declare `"checksum": "s10"`.
+ * What it is not: no carrier lookup and no provider I/O. Input is normalized
+ * here, so callers may pass a raw or an already-normalized number.
+ */
+import { normalizeTrackingNumber } from './normalize.js';
+/** Validate the UPU S10 check digit, not only its broad A2-N9-A2 shape. */
+export function isValidS10TrackingNumber(raw) {
+    const value = normalizeTrackingNumber(raw);
+    if (!/^[A-Z]{2}\d{9}[A-Z]{2}$/.test(value))
+        return false;
+    const weights = [8, 6, 4, 2, 3, 5, 9, 7];
+    const sum = weights.reduce((total, weight, index) => total + Number(value[index + 2]) * weight, 0);
+    const rawCheckDigit = 11 - (sum % 11);
+    const expected = rawCheckDigit === 10 ? 0 : rawCheckDigit === 11 ? 5 : rawCheckDigit;
+    return Number(value[10]) === expected;
+}
+/** Swiss-issued tracked letter-post can move from Cainiao to Swiss Post. */
+export function supportsSwissPostHandoff(raw) {
+    const value = normalizeTrackingNumber(raw);
+    return /^L[A-Z]\d{9}CH$/.test(value) && isValidS10TrackingNumber(value);
+}

package/dist/core/detection/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Detection vocabulary.
+ *
+ * What it is: the result shapes the detection engine returns and its callers
+ * pass around (confidence, candidate carriers, parsed input).
+ * What it is not: no provider I/O, no application or framework types. These
+ * declarations are erased at build time and safe to import from anywhere.
+ */
+import type { CarrierId } from '../../generated/catalog.js';
+export type DetectionConfidence = 'high' | 'low' | 'none';
+export interface CarrierDetection {
+    carrier: CarrierId;
+    confidence: DetectionConfidence;
+    candidates: CarrierId[];
+    /** Candidates a `preferred` rule backs with number evidence, listed first. */
+    preferred: CarrierId[];
+}
+export interface TrackingInputMatch extends CarrierDetection {
+    trackingNumber: string;
+    trackingUrl?: string;
+    source: 'number' | 'link' | 'text' | 'none';
+}

package/dist/core/detection/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/errors/hint.d.ts

@@ -0,0 +1,7 @@
+import { type CarrierErrorKind } from './index.js';
+export interface FailureHint {
+    kind: CarrierErrorKind;
+    retryAfterMs?: number;
+}
+/** The upstream's advice; consumers own their refresh cadence and backoff. */
+export declare function failureHint(error: unknown): FailureHint;

package/dist/core/errors/hint.js

@@ -0,0 +1,7 @@
+import { carrierErrorKind, retryAfterMsOf } from './index.js';
+/** The upstream's advice; consumers own their refresh cadence and backoff. */
+export function failureHint(error) {
+    const kind = carrierErrorKind(error) ?? 'transport';
+    const retryAfterMs = retryAfterMsOf(error);
+    return { kind, ...(retryAfterMs === undefined ? {} : { retryAfterMs }) };
+}

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

@@ -0,0 +1,98 @@
+/**
+ * The single error taxonomy for carrier adapters, universal providers, routing
+ * and telemetry.
+ *
+ * Adapters throw one of the classes below (or let `fetchBounded` throw its
+ * `UpstreamHttpError` / `UpstreamNetworkError`). Routing, the sync worker and
+ * the telemetry sinks never inspect messages or class names: they call
+ * `carrierErrorKind()`, which walks the `cause` chain so wrapped errors keep
+ * their meaning.
+ *
+ * `status` mirrors the HTTP-like convention older code still inspects (404 not
+ * found, 429 rate limited, 403 challenge, 502 indeterminate, 503 maintenance),
+ * which keeps the migration behavior-preserving.
+ */
+import type { UpstreamHttpDiagnostics } from '../transport/upstreamHttpDiagnostics.js';
+export type { UpstreamHttpDiagnostics };
+export type CarrierErrorKind = 'not_found' | 'indeterminate' | 'challenge' | 'rate_limited' | 'maintenance' | 'schema' | 'input_required' | 'transport' | 'budget';
+export interface CarrierErrorOptions {
+    cause?: unknown;
+    status?: number;
+    retryAfterMs?: number;
+    /** Stable detail within an error kind, such as `history_expired`. */
+    reason?: string;
+}
+export declare class CarrierError extends Error {
+    readonly kind: CarrierErrorKind;
+    readonly provider: string;
+    readonly status?: number;
+    readonly retryAfterMs?: number;
+    readonly reason?: string;
+    constructor(kind: CarrierErrorKind, provider: string, message: string, options?: CarrierErrorOptions);
+}
+export declare class NotFoundError extends CarrierError {
+    constructor(provider: string, message?: string, options?: CarrierErrorOptions);
+}
+export declare class IndeterminateError extends CarrierError {
+    constructor(provider: string, message?: string, options?: CarrierErrorOptions);
+}
+/**
+ * A universal provider looked the number up and has no history for it yet (not
+ * announced, not handed over). An answer about the parcel, not an outage.
+ */
+export declare class NoHistoryError extends IndeterminateError {
+    constructor(provider: string, message?: string, options?: CarrierErrorOptions);
+}
+export declare class ChallengeError extends CarrierError {
+    constructor(provider: string, message?: string, options?: CarrierErrorOptions);
+}
+export declare class RateLimitedError extends CarrierError {
+    constructor(provider: string, retryAfterMs?: number, message?: string, options?: CarrierErrorOptions);
+}
+export declare class MaintenanceError extends CarrierError {
+    constructor(provider: string, message?: string, options?: CarrierErrorOptions);
+}
+export declare class SchemaError extends CarrierError {
+    constructor(provider: string, message?: string, options?: CarrierErrorOptions);
+}
+export declare class InputRequiredError extends CarrierError {
+    readonly field: string;
+    constructor(provider: string, field: string, message?: string, options?: CarrierErrorOptions);
+}
+export declare class TransportError extends CarrierError {
+    constructor(provider: string, message?: string, options?: CarrierErrorOptions);
+}
+export declare class BudgetExceededError extends CarrierError {
+    constructor(provider: string, budgetMs: number, options?: CarrierErrorOptions);
+}
+/** Request details kept on transport errors for diagnostics. Bodies are truncated. */
+export interface UpstreamRequestDiagnostics {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    body_truncated?: boolean;
+    timeout_ms: number;
+}
+/** A rejected HTTP response from a provider. Kind is derived from the status. */
+export declare class UpstreamHttpError extends CarrierError {
+    readonly diagnostics?: UpstreamHttpDiagnostics | undefined;
+    readonly request?: UpstreamRequestDiagnostics | undefined;
+    /** Always present for HTTP errors; narrowed from the optional base field. */
+    readonly status: number;
+    constructor(provider: string, status: number, retryAfterMs?: number, diagnostics?: UpstreamHttpDiagnostics | undefined, request?: UpstreamRequestDiagnostics | undefined);
+}
+/** A network failure (DNS, TLS, timeout, interrupted body) while talking to a provider. */
+export declare class UpstreamNetworkError extends CarrierError {
+    readonly request?: UpstreamRequestDiagnostics | undefined;
+    constructor(provider: string, cause: unknown, request?: UpstreamRequestDiagnostics | undefined);
+}
+/**
+ * Classify any error, walking `cause` chains. Returns null for errors that are
+ * not part of the taxonomy so callers can apply their own fallback.
+ */
+export declare function carrierErrorKind(error: unknown): CarrierErrorKind | null;
+/** The retry window a rate-limiting provider asked for, when any error in the chain carries one. */
+export declare function retryAfterMsOf(error: unknown): number | undefined;
+/** A stable, low-cardinality name for an error, safe as a metric label. */
+export declare function errorTypeOf(error: unknown): string;

package/dist/core/errors/index.js

@@ -0,0 +1,178 @@
+/**
+ * The single error taxonomy for carrier adapters, universal providers, routing
+ * and telemetry.
+ *
+ * Adapters throw one of the classes below (or let `fetchBounded` throw its
+ * `UpstreamHttpError` / `UpstreamNetworkError`). Routing, the sync worker and
+ * the telemetry sinks never inspect messages or class names: they call
+ * `carrierErrorKind()`, which walks the `cause` chain so wrapped errors keep
+ * their meaning.
+ *
+ * `status` mirrors the HTTP-like convention older code still inspects (404 not
+ * found, 429 rate limited, 403 challenge, 502 indeterminate, 503 maintenance),
+ * which keeps the migration behavior-preserving.
+ */
+const STATUS_BY_KIND = {
+    not_found: 404,
+    indeterminate: 502,
+    challenge: 403,
+    rate_limited: 429,
+    maintenance: 503,
+};
+export class CarrierError extends Error {
+    kind;
+    provider;
+    status;
+    retryAfterMs;
+    reason;
+    constructor(kind, provider, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'CarrierError';
+        this.kind = kind;
+        this.provider = provider;
+        if (options.reason !== undefined)
+            this.reason = options.reason;
+        const status = options.status ?? STATUS_BY_KIND[kind];
+        if (status !== undefined)
+            this.status = status;
+        if (options.retryAfterMs !== undefined && Number.isFinite(options.retryAfterMs)) {
+            this.retryAfterMs = Math.max(0, options.retryAfterMs);
+        }
+    }
+}
+export class NotFoundError extends CarrierError {
+    constructor(provider, message = `${provider} could not locate the shipment`, options) {
+        super('not_found', provider, message, options);
+        this.name = 'NotFoundError';
+    }
+}
+export class IndeterminateError extends CarrierError {
+    constructor(provider, message = `${provider} returned an inconclusive response`, options) {
+        super('indeterminate', provider, message, options);
+        this.name = 'IndeterminateError';
+    }
+}
+/**
+ * A universal provider looked the number up and has no history for it yet (not
+ * announced, not handed over). An answer about the parcel, not an outage.
+ */
+export class NoHistoryError extends IndeterminateError {
+    constructor(provider, message = `${provider} has no history for the shipment`, options) {
+        super(provider, message, options);
+        this.name = 'NoHistoryError';
+    }
+}
+export class ChallengeError extends CarrierError {
+    constructor(provider, message = `${provider} requires a browser challenge`, options) {
+        super('challenge', provider, message, options);
+        this.name = 'ChallengeError';
+    }
+}
+export class RateLimitedError extends CarrierError {
+    constructor(provider, retryAfterMs, message = `${provider} is rate limiting tracking requests`, options) {
+        super('rate_limited', provider, message, { ...options, retryAfterMs });
+        this.name = 'RateLimitedError';
+    }
+}
+export class MaintenanceError extends CarrierError {
+    constructor(provider, message = `${provider} tracking is under maintenance`, options) {
+        super('maintenance', provider, message, options);
+        this.name = 'MaintenanceError';
+    }
+}
+export class SchemaError extends CarrierError {
+    constructor(provider, message = `${provider} returned an invalid tracking response`, options) {
+        super('schema', provider, message, options);
+        this.name = 'SchemaError';
+    }
+}
+export class InputRequiredError extends CarrierError {
+    field;
+    constructor(provider, field, message = `${provider} tracking requires ${field}`, options) {
+        super('input_required', provider, message, options);
+        this.name = 'InputRequiredError';
+        this.field = field;
+    }
+}
+export class TransportError extends CarrierError {
+    constructor(provider, message = `${provider} is unreachable`, options) {
+        super('transport', provider, message, options);
+        this.name = 'TransportError';
+    }
+}
+export class BudgetExceededError extends CarrierError {
+    constructor(provider, budgetMs, options) {
+        super('budget', provider, `${provider} lookup exceeded its ${budgetMs} ms budget`, options);
+        this.name = 'BudgetExceededError';
+    }
+}
+function kindForStatus(status) {
+    if (status === 404 || status === 410)
+        return 'not_found';
+    if (status === 429)
+        return 'rate_limited';
+    if (status === 401 || status === 403)
+        return 'challenge';
+    if (status === 503)
+        return 'maintenance';
+    if (status >= 500)
+        return 'indeterminate';
+    return 'transport';
+}
+/** A rejected HTTP response from a provider. Kind is derived from the status. */
+export class UpstreamHttpError extends CarrierError {
+    diagnostics;
+    request;
+    constructor(provider, status, retryAfterMs, diagnostics, request) {
+        super(kindForStatus(status), provider, `${provider} returned HTTP ${status}`, { status, retryAfterMs });
+        this.diagnostics = diagnostics;
+        this.request = request;
+        this.name = 'UpstreamHttpError';
+    }
+}
+/** A network failure (DNS, TLS, timeout, interrupted body) while talking to a provider. */
+export class UpstreamNetworkError extends CarrierError {
+    request;
+    constructor(provider, cause, request) {
+        super('transport', provider, `${provider} is unreachable`, { cause });
+        this.request = request;
+        this.name = 'UpstreamNetworkError';
+    }
+}
+const MAX_CAUSE_DEPTH = 8;
+/**
+ * Classify any error, walking `cause` chains. Returns null for errors that are
+ * not part of the taxonomy so callers can apply their own fallback.
+ */
+export function carrierErrorKind(error) {
+    const seen = new Set();
+    let current = error;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && current instanceof Error && !seen.has(current); depth += 1) {
+        seen.add(current);
+        if (current instanceof CarrierError)
+            return current.kind;
+        current = current.cause;
+    }
+    return null;
+}
+/** The retry window a rate-limiting provider asked for, when any error in the chain carries one. */
+export function retryAfterMsOf(error) {
+    const seen = new Set();
+    let current = error;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && current instanceof Error && !seen.has(current); depth += 1) {
+        seen.add(current);
+        if (current instanceof CarrierError && current.retryAfterMs !== undefined)
+            return current.retryAfterMs;
+        current = current.cause;
+    }
+    return undefined;
+}
+/** A stable, low-cardinality name for an error, safe as a metric label. */
+export function errorTypeOf(error) {
+    if (error instanceof Error && /^(?:Error|[A-Z][A-Za-z0-9_.-]{0,80}(?:Error|Exception))$/.test(error.name.trim())) {
+        return error.name.trim();
+    }
+    if (error instanceof Error)
+        return 'Error';
+    return typeof error;
+}