universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/core/catalog/inputs.js

@@ -0,0 +1,89 @@
+/** Validate parcel credentials against the catalog and pure carrier URL validators. */
+import { activeRequirements, carrierDefinition } from './index.js';
+import { isValidMondialRelayBarcode } from '../detection/index.js';
+import { validateDachserTrackingUrl } from './urls.js';
+import { validatePlanzerSharedUrl } from './urls.js';
+export { AUTOMATIC_CARRIER_IDS, CARRIER_NAMES, activeRequirements, carrierAdapter, carrierDefinition, carrierTimezone, requiredRequirements, } from './index.js';
+export { isValidS10TrackingNumber, supportsSwissPostHandoff, } from '../detection/index.js';
+export function normalizeCarrierInputs(carrierId, trackingNumber, trackingUrl, dpdPostcode) {
+    const supplied = {
+        trackingUrl: trackingUrl.trim() || null,
+        dpdPostcode: dpdPostcode.trim() || null,
+    };
+    const mondialBarcode = carrierId === 'mondial-relay' && /^\d{26}$/.test(trackingNumber);
+    if (mondialBarcode && !isValidMondialRelayBarcode(trackingNumber)) {
+        throw new TypeError('Invalid Mondial Relay barcode');
+    }
+    const requirements = new Map(activeRequirements(carrierId, trackingNumber).map((item) => [item.field, item]));
+    // Older clients may still supply a postcode for label barcodes. Validate it
+    // when present, while allowing the public alias to work without one.
+    if (mondialBarcode && supplied.dpdPostcode) {
+        requirements.set('dpdPostcode', { field: 'dpdPostcode', validator: 'francePostcode' });
+    }
+    for (const [field, value] of Object.entries(supplied)) {
+        if (value !== null && !requirements.has(field)) {
+            if (field === 'trackingUrl') {
+                throw new TypeError('A tracking URL is not used for this carrier or tracking number');
+            }
+            throw new TypeError('A delivery postcode is not used for this carrier');
+        }
+    }
+    for (const [field, requirement] of requirements) {
+        const value = supplied[field];
+        if (!value) {
+            // An optional input only unlocks extra detail; a supplied one is still checked below.
+            if (requirement.optional)
+                continue;
+            if (field === 'trackingUrl') {
+                throw new TypeError(`${carrierDefinition(carrierId).displayName} requires its complete tracking URL`);
+            }
+            if (requirement.validator === 'swissPostcode') {
+                throw new TypeError(`${carrierDefinition(carrierId).displayName} requires the four-digit delivery postcode`);
+            }
+            if (requirement.validator === 'francePostcode') {
+                throw new TypeError(`${carrierDefinition(carrierId).displayName} requires the five-digit delivery postcode`);
+            }
+            if (requirement.validator === 'swissOrFrancePostcode') {
+                throw new TypeError(`${carrierDefinition(carrierId).displayName} requires a four- or five-digit delivery postcode`);
+            }
+            if (requirement.validator === 'paackPostcode') {
+                throw new TypeError('Paack requires the delivery postcode');
+            }
+            throw new TypeError(`${carrierDefinition(carrierId).displayName} requires the delivery postcode`);
+        }
+        switch (requirement.validator) {
+            case 'planzerSharedUrl':
+                supplied[field] = validatePlanzerSharedUrl(value, trackingNumber);
+                break;
+            case 'dachserCapabilityUrl':
+                supplied[field] = validateDachserTrackingUrl(value, trackingNumber);
+                break;
+            case 'swissPostcode':
+                if (!/^\d{4}$/.test(value)) {
+                    throw new TypeError(`${carrierDefinition(carrierId).displayName} requires the four-digit delivery postcode`);
+                }
+                break;
+            case 'francePostcode':
+                if (!/^\d{5}$/.test(value)) {
+                    throw new TypeError(`${carrierDefinition(carrierId).displayName} requires the five-digit delivery postcode`);
+                }
+                break;
+            case 'swissOrFrancePostcode':
+                if (!/^\d{4,5}$/.test(value)) {
+                    throw new TypeError(`${carrierDefinition(carrierId).displayName} requires a four- or five-digit delivery postcode`);
+                }
+                break;
+            case 'paackPostcode': {
+                const rawPostcode = value.toLocaleUpperCase('en-US');
+                if (!/^(?=.{3,10}$)(?=.*\d)[A-Z0-9]+(?:[ -][A-Z0-9]+)*$/.test(rawPostcode)) {
+                    throw new TypeError('Paack requires a valid delivery postcode');
+                }
+                supplied[field] = rawPostcode.replace(/\s+/g, '');
+                break;
+            }
+            default:
+                requirement.validator;
+        }
+    }
+    return supplied;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Compiled tracking-link rules.
+ *
+ * What it is: every carrier's `linkRules` with their regexes compiled once, so
+ * a pasted URL can be matched against the whole catalog.
+ * What it is not: no fetching, no URL following, no provider I/O. Matching a
+ * URL against these rules lives in `core/detection`.
+ */
+import type { CarrierId } from '../../generated/catalog.js';
+export interface TrackingLinkRule {
+    carrier: CarrierId;
+    domains: string[];
+    params?: string[];
+    path?: RegExp;
+    pathPattern?: RegExp;
+    fragment?: RegExp;
+    detectFromNumber?: boolean;
+    keepsCapabilityUrl?: boolean;
+}
+export declare const TRACKING_LINK_RULES: TrackingLinkRule[];
+/** The compiled link rules declared by one carrier. */
+export declare function carrierLinkRules(carrierId: CarrierId): TrackingLinkRule[];
+/** A hostname matches a rule domain exactly or as one of its subdomains. */
+export declare function matchesDomain(hostname: string, domain: string): boolean;

package/dist/core/catalog/linkRules.js

@@ -0,0 +1,20 @@
+import { CARRIER_DEFINITIONS } from './definitions.js';
+export const TRACKING_LINK_RULES = Object.entries(CARRIER_DEFINITIONS)
+    .flatMap(([carrier, definition]) => definition.linkRules.map((rule) => ({
+    carrier: carrier,
+    domains: [...rule.domains],
+    params: rule.params ? [...rule.params] : undefined,
+    path: rule.path ? new RegExp(rule.path, 'i') : undefined,
+    pathPattern: rule.pathPattern ? new RegExp(rule.pathPattern, 'i') : undefined,
+    fragment: rule.fragment ? new RegExp(rule.fragment, 'i') : undefined,
+    detectFromNumber: rule.detectFromNumber,
+    keepsCapabilityUrl: rule.keepsCapabilityUrl,
+})));
+/** The compiled link rules declared by one carrier. */
+export function carrierLinkRules(carrierId) {
+    return TRACKING_LINK_RULES.filter((rule) => rule.carrier === carrierId);
+}
+/** A hostname matches a rule domain exactly or as one of its subdomains. */
+export function matchesDomain(hostname, domain) {
+    return hostname === domain || hostname.endsWith(`.${domain}`);
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Brands that run several catalog networks ("DPD" is `dpd` and `dpd-fr`).
+ *
+ * Kept apart from the provider-name hints so browser code can use it without
+ * their country tables.
+ */
+export declare const NETWORK_BRANDS: readonly string[];
+/** The multi-network brand a catalog carrier belongs to ("dpd" for `dpd-fr`), if any. */
+export declare function carrierBrand(id: string): string | undefined;

package/dist/core/catalog/networks.js

@@ -0,0 +1,13 @@
+/**
+ * Brands that run several catalog networks ("DPD" is `dpd` and `dpd-fr`).
+ *
+ * Kept apart from the provider-name hints so browser code can use it without
+ * their country tables.
+ */
+// Brands whose other networks keep the brand in front ("DHL Express", "GLS
+// Italy"). "post" is left out: it also starts unrelated names.
+export const NETWORK_BRANDS = ['dhl', 'dpd', 'gls', 'hermes'];
+/** The multi-network brand a catalog carrier belongs to ("dpd" for `dpd-fr`), if any. */
+export function carrierBrand(id) {
+    return NETWORK_BRANDS.find((brand) => id === brand || id.startsWith(`${brand}-`));
+}

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

@@ -0,0 +1,22 @@
+import type { CarrierInputField } from './types.js';
+/** Carriers asked at once. */
+export declare const MAX_RECOGNITIONS = 5;
+export interface RecognitionCandidate {
+    carrier: string;
+    /** The first input the carrier needs before it can track, if any. */
+    needsInput: CarrierInputField | null;
+    /** A preferred detection rule backs it with number evidence. */
+    preferred: boolean;
+}
+/**
+ * The low-confidence candidates worth asking, best first: the carrier a
+ * universal provider named, then the ones number evidence backs, then the
+ * catalog's popularity rank. Only carriers that declare `tracking.recognition`
+ * qualify. A high-confidence number needs no recognition.
+ */
+export declare function recognitionCandidates(number: string, options?: {
+    hint?: string;
+    skip?: (carrier: string) => boolean;
+}): RecognitionCandidate[];
+/** The carriers the detect route asks about a number, best first; empty when none can answer. */
+export declare function recognitionAskedCarriers(number: string): string[];

package/dist/core/catalog/recognition.js

@@ -0,0 +1,52 @@
+/**
+ * Which carriers recognition asks about an ambiguous number.
+ *
+ * What it is: the ranked candidates whose adapter can cheaply say whether it
+ * knows a number. The detect route and routing ask them; the Add sheets name
+ * them while the answer is on its way.
+ * What it is not: no provider I/O. Asking the carriers is the server's job
+ * (`src/server/carrierRecognition.ts`).
+ */
+import { CARRIER_RECOGNITION_RANKS } from '../../generated/recognition.js';
+import { detectCarrierMatch } from '../detection/detect.js';
+import { AUTOMATIC_CARRIER_IDS, carrierAdapter, requiredRequirements } from './definitions.js';
+import { carrierBrand } from './networks.js';
+/** Carriers asked at once. */
+export const MAX_RECOGNITIONS = 5;
+/**
+ * The low-confidence candidates worth asking, best first: the carrier a
+ * universal provider named, then the ones number evidence backs, then the
+ * catalog's popularity rank. Only carriers that declare `tracking.recognition`
+ * qualify. A high-confidence number needs no recognition.
+ */
+export function recognitionCandidates(number, options = {}) {
+    const detected = detectCarrierMatch(number);
+    if (detected.confidence !== 'low')
+        return [];
+    // A carrier the number points to but that cannot be asked (DPD France) keeps
+    // its brand's other networks out: DPD's guest API also answers for DPD
+    // France parcels, and would file one under DPD Switzerland.
+    const shadowed = new Set(detected.preferred
+        .filter((carrier) => CARRIER_RECOGNITION_RANKS[carrier] === undefined)
+        .map((carrier) => carrierBrand(carrier)).filter(Boolean));
+    const score = (carrier) => [
+        carrier === options.hint ? 1 : 0,
+        detected.preferred.includes(carrier) ? 1 : 0,
+        CARRIER_RECOGNITION_RANKS[carrier] ?? 0,
+    ];
+    return detected.candidates
+        .filter((carrier) => CARRIER_RECOGNITION_RANKS[carrier] !== undefined && AUTOMATIC_CARRIER_IDS.has(carrier)
+        && carrierAdapter(carrier) !== 'universal' && !shadowed.has(carrierBrand(carrier)) && !options.skip?.(carrier))
+        .map((carrier) => ({ carrier, score: score(carrier) }))
+        // Array#sort is stable: equal scores keep the catalog order.
+        .sort((left, right) => right.score[0] - left.score[0] || right.score[1] - left.score[1] || right.score[2] - left.score[2])
+        .map(({ carrier }) => ({
+        carrier,
+        needsInput: requiredRequirements(carrier, number)[0]?.field ?? null,
+        preferred: detected.preferred.includes(carrier),
+    }));
+}
+/** The carriers the detect route asks about a number, best first; empty when none can answer. */
+export function recognitionAskedCarriers(number) {
+    return recognitionCandidates(number).slice(0, MAX_RECOGNITIONS).map(({ carrier }) => carrier);
+}

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

@@ -0,0 +1,135 @@
+/**
+ * Catalog vocabulary.
+ *
+ * What it is: the shape of a merged `carrier.json` entry and the typed views
+ * the application consumes (carrier info, capabilities, input requirements,
+ * tracking links).
+ * What it is not: no data, no behaviour and no provider I/O; every declaration
+ * here is erased at build time.
+ */
+import type { CarrierId } from '../../generated/catalog.js';
+import type { DetectionConfidence } from '../detection/types.js';
+export type CarrierTrackingMode = 'automatic' | 'link-only';
+export type CarrierInputField = 'trackingUrl' | 'dpdPostcode';
+export type CarrierInputValidator = 'planzerSharedUrl' | 'dachserCapabilityUrl' | 'swissPostcode' | 'francePostcode' | 'swissOrFrancePostcode' | 'paackPostcode';
+/** What the "add a parcel" forms render for a carrier that needs extra input. */
+export interface CarrierInputRequirement {
+    field: CarrierInputField;
+    whenTrackingNumber?: string;
+    /** The form may be submitted without it; a supplied value is still checked. */
+    optional?: boolean;
+    label: string;
+    type: 'text' | 'url';
+    placeholder?: string;
+    help?: string;
+    pattern?: string;
+    maxLength?: number;
+    inputMode?: 'numeric' | 'text' | 'url';
+    autoComplete?: string;
+}
+/** What the server checks that extra input against. */
+export interface CarrierRequirementRule {
+    field: CarrierInputField;
+    validator: CarrierInputValidator;
+    whenTrackingNumber?: string;
+    optional?: boolean;
+}
+export interface CarrierCatalogRequirement extends CarrierInputRequirement, CarrierRequirementRule {
+}
+export interface CarrierCapabilities {
+    tracking: {
+        mode: CarrierTrackingMode;
+        adapter: string | null;
+        requirements: CarrierInputRequirement[];
+    };
+    selectable: boolean;
+    timezone: string;
+}
+export interface CarrierInfo {
+    id: CarrierId;
+    name: string;
+    /** Other names the carrier is known by, searched by the carrier pickers. */
+    aliases: readonly string[];
+    /** ISO codes of the countries it delivers in under its own name, home first. */
+    countries: readonly string[];
+    trackingSiteName?: string;
+    /** Accent used for the carrier chip in the UI. */
+    color: string;
+    trackingUrl?: (trackingNumber: string) => string;
+    capabilities: CarrierCapabilities;
+}
+export interface DetectionRule {
+    pattern: string;
+    /** Additional condition on the input before separators are removed. */
+    rawPattern?: string;
+    confidence: Exclude<DetectionConfidence, 'none'>;
+    checksum?: 's10' | 'mondial-relay' | 'hermes' | 'gls';
+    /** Low confidence only: number evidence that lists this carrier first among suggestions. */
+    preferred?: boolean;
+}
+/** A link rule as it is written in the catalog, before its regexes compile. */
+export interface RawTrackingLinkRule {
+    domains: readonly string[];
+    params?: readonly string[];
+    path?: string;
+    pathPattern?: string;
+    fragment?: string;
+    detectFromNumber?: boolean;
+    keepsCapabilityUrl?: boolean;
+}
+/** One merged catalog entry: everything the app knows about a carrier. */
+export interface CarrierDefinition {
+    displayName: string;
+    displayNames?: Record<string, string>;
+    aliases?: readonly string[];
+    countries?: readonly string[];
+    trackingSiteName?: string;
+    color: string;
+    selectable: boolean;
+    timezone: string;
+    canaryUrl?: string;
+    tracking: {
+        mode: CarrierTrackingMode;
+        adapter: string | null;
+        upstreamName?: string;
+        requirements?: readonly CarrierCatalogRequirement[];
+        /** Present when the adapter can recognize a number; higher is asked first. */
+        recognitionRank?: number;
+        refresh?: {
+            minMinutes: number;
+            afterFailureMinutes?: number;
+        };
+        localClocks?: boolean;
+    };
+    trackingUrlTemplate?: string;
+    linkRules: readonly RawTrackingLinkRule[];
+    detectionRules: readonly DetectionRule[];
+}
+export interface ParcelTrackingLink {
+    carrier: CarrierInfo;
+    name: string;
+    url: string;
+    active: boolean;
+    ready: boolean;
+    role: 'active' | 'waiting' | 'history';
+}
+/**
+ * The parcel fields the tracking-link helpers read. Structurally a subset of
+ * the application's `Parcel`, restated here so the package stays independent.
+ */
+export interface TrackedParcel {
+    carrier: CarrierId;
+    trackingNumber: string;
+    trackingUrl?: string;
+    /** Carrier currently supplying automatic updates for a multi-carrier journey. */
+    trackingSource?: CarrierId;
+    trackingProvider?: string;
+    /** The carrier answered the check the provider's result came from; links stay with the carrier. */
+    carrierAnswered?: boolean;
+    activeTrackingNumber?: string;
+    /** Whether Swiss Post has announced a Swiss-issued inbound shipment. */
+    swissPostReady?: boolean;
+    originalCarrier?: CarrierId;
+    originalTrackingNumber?: string;
+    originalTrackingUrl?: string;
+}

package/dist/core/catalog/types.js

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

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

@@ -0,0 +1,2 @@
+export declare function validatePlanzerSharedUrl(rawUrl: string, trackingNumber: string): string;
+export declare function validateDachserTrackingUrl(rawUrl: string, trackingNumber: string): string;

package/dist/core/catalog/urls.js

@@ -0,0 +1,125 @@
+import { normalizeTrackingNumber } from '../detection/index.js';
+const PLANZER_SHARED_HOST = 'trackandtrace.planzergroup.com';
+const PLANZER_SHARED_PATH = /^\/shared\/sendungen\/([^/]+)\/?$/;
+const PLANZER_ACCESS_KEY = /^[A-Za-z0-9_-]{32,256}$/;
+const DACHSER_HOST = 'customeriberia.dachser.com';
+const DACHSER_PAGE_PATH = '/customerarea/utilidades/seguimiento-publico/detalle';
+const CAPABILITY_VALUE = /^[A-Za-z0-9_-]{4,256}$/;
+const CONTROL_CHARACTER = /[\x00-\x1f\x7f]/;
+const ALLOWED_QUERY_KEYS = new Set([
+    'hash',
+    'cliente',
+    'numeroUnico',
+    'referencia',
+    'fecha',
+    'clave',
+    'user',
+    'idioma',
+    'expedicion',
+    'tipoMail',
+    'error',
+    'origen',
+    'usuario',
+]);
+export function validatePlanzerSharedUrl(rawUrl, trackingNumber) {
+    const value = rawUrl.trim();
+    if (value.length < 1 || value.length > 4_096) {
+        throw new TypeError('Paste the complete Planzer tracking URL');
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch (error) {
+        throw new TypeError('Paste a valid Planzer tracking URL', { cause: error });
+    }
+    if (url.protocol !== 'https:'
+        || url.hostname.toLowerCase() !== PLANZER_SHARED_HOST
+        || url.username
+        || url.password
+        || (url.port && url.port !== '443')
+        || url.hash) {
+        throw new TypeError(`Planzer shared links must use https://${PLANZER_SHARED_HOST}`);
+    }
+    let pathname;
+    try {
+        pathname = decodeURIComponent(url.pathname);
+    }
+    catch (error) {
+        throw new TypeError('Paste a valid Planzer tracking URL', { cause: error });
+    }
+    const match = PLANZER_SHARED_PATH.exec(pathname);
+    if (!match)
+        throw new TypeError('Paste a Planzer shared shipment URL');
+    if (normalizeTrackingNumber(match[1]) !== normalizeTrackingNumber(trackingNumber)) {
+        throw new TypeError('The Planzer URL belongs to a different tracking number');
+    }
+    const accessKeys = url.searchParams.getAll('accessKey');
+    if (accessKeys.length !== 1 || !PLANZER_ACCESS_KEY.test(accessKeys[0])) {
+        throw new TypeError('The Planzer URL must include its accessKey');
+    }
+    return url.toString();
+}
+export function validateDachserTrackingUrl(rawUrl, trackingNumber) {
+    const value = rawUrl.trim();
+    if (value.length < 1 || value.length > 4_096) {
+        throw new TypeError('Paste the complete Dachser tracking URL');
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch (error) {
+        throw new TypeError('Paste a valid Dachser tracking URL', { cause: error });
+    }
+    if (url.protocol !== 'https:'
+        || url.hostname.toLowerCase() !== DACHSER_HOST
+        || url.username
+        || url.password
+        || (url.port && url.port !== '443')
+        || url.hash)
+        throw new TypeError(`Dachser links must use https://${DACHSER_HOST}`);
+    let pathname;
+    try {
+        pathname = decodeURIComponent(url.pathname);
+    }
+    catch (error) {
+        throw new TypeError('Paste a valid Dachser tracking URL', { cause: error });
+    }
+    if (pathname !== DACHSER_PAGE_PATH && pathname !== `${DACHSER_PAGE_PATH}/`) {
+        throw new TypeError('Paste a Dachser public shipment detail URL');
+    }
+    const values = new Map();
+    for (const [name, parameter] of url.searchParams) {
+        if (!ALLOWED_QUERY_KEYS.has(name)) {
+            throw new TypeError('The Dachser URL contains an unsupported parameter');
+        }
+        if (values.has(name))
+            throw new TypeError('The Dachser URL contains a duplicate parameter');
+        if (!parameter || parameter.length > 256 || CONTROL_CHARACTER.test(parameter)) {
+            throw new TypeError('The Dachser URL contains an invalid parameter');
+        }
+        values.set(name, parameter);
+    }
+    const uniqueNumber = values.get('numeroUnico');
+    if (!uniqueNumber)
+        throw new TypeError('The Dachser URL must include its shipment number');
+    if (normalizeTrackingNumber(uniqueNumber) !== normalizeTrackingNumber(trackingNumber)) {
+        throw new TypeError('The Dachser URL belongs to a different tracking number');
+    }
+    const capabilityHash = values.get('hash');
+    const capabilityKey = values.get('clave');
+    const capabilityDate = values.get('fecha');
+    const hasHash = Boolean(capabilityHash && CAPABILITY_VALUE.test(capabilityHash));
+    const hasKey = Boolean(capabilityKey
+        && capabilityDate
+        && CAPABILITY_VALUE.test(capabilityKey)
+        && /^\d{8}$/.test(capabilityDate));
+    if (!hasHash && !hasKey) {
+        throw new TypeError('The Dachser URL must include its access parameters');
+    }
+    url.protocol = 'https:';
+    url.hostname = DACHSER_HOST;
+    url.port = '';
+    return url.toString();
+}

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

@@ -0,0 +1,2 @@
+export declare const AMAZON_NUMBER_PATTERN: "^(?:(?:FR|DE|BE|UK|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)[0-9]{10}|TBA[0-9]{12})$";
+export declare function isAmazonTrackingNumber(raw: string): boolean;

package/dist/core/detection/amazon.js

@@ -0,0 +1,14 @@
+/**
+ * Amazon tracking-number recognition.
+ *
+ * What it is: the Amazon number shape, read from the catalog so the pattern has
+ * exactly one source of truth, and the predicate built on it.
+ * What it is not: no Amazon account state, no eligibility check, no provider
+ * I/O; whether a parcel needs the customer's Amazon account is a catalog
+ * concern and lives in `core/catalog/amazon`.
+ */
+import { CARRIER_CATALOG } from '../../generated/catalog.js';
+export const AMAZON_NUMBER_PATTERN = CARRIER_CATALOG['amazon-logistics'].detectionRules[0].pattern;
+export function isAmazonTrackingNumber(raw) {
+    return new RegExp(AMAZON_NUMBER_PATTERN).test(raw.replace(/[\s.-]/g, '').toUpperCase());
+}

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

@@ -0,0 +1,5 @@
+export declare const TRACKING_CANDIDATE_PATTERNS: RegExp[];
+/** The first candidate in the text that one carrier claims confidently. */
+export declare function recognizedNumberInText(raw: string): string | undefined;
+/** Last resort: a number introduced by a "tracking number:" style label. */
+export declare function keywordNumberInText(raw: string): string | undefined;

package/dist/core/detection/candidates.js

@@ -0,0 +1,41 @@
+/**
+ * Candidate numbers inside free text.
+ *
+ * What it is: the shapes worth testing when a whole shipping message, or a URL
+ * with no matching link rule, is pasted, and the two scans over them.
+ * What it is not: no carrier decision of its own (it defers to the detection
+ * engine) and no provider I/O.
+ */
+import { AMAZON_NUMBER_PATTERN } from './amazon.js';
+import { detectCarrierMatch } from './detect.js';
+import { validTrackingNumber } from './normalize.js';
+export const TRACKING_CANDIDATE_PATTERNS = [
+    new RegExp(`\\b${AMAZON_NUMBER_PATTERN.slice(1, -1).replaceAll('[0-9]', '(?:[\\s.-]*[0-9])')}\\b`, 'gi'),
+    // NACEX agency/shipment composites keep their slash boundary (never stripped).
+    /\b\d{4}\/\d{8}\b/g,
+    /\b\d{26}\b/g,
+    /\bH\d{15,19}\b/gi,
+    /\b1Z[A-Z0-9]{16}\b/gi,
+    /\b1G[A-Z0-9]{10}\b/gi,
+    /\b[A-Z]{2}\s*\d(?:[\s.-]?\d){8}\s*[A-Z]{2}\b/gi,
+    /\b(?:JJD|JVGL)[A-Z0-9]{8,}\b/gi,
+    /\b\d(?:[\s.-]?\d){9,19}\b/g,
+];
+/** The first candidate in the text that one carrier claims confidently. */
+export function recognizedNumberInText(raw) {
+    for (const pattern of TRACKING_CANDIDATE_PATTERNS) {
+        pattern.lastIndex = 0;
+        for (const match of raw.matchAll(pattern)) {
+            const candidate = match[0].trim();
+            if (detectCarrierMatch(candidate).confidence === 'high')
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/** Last resort: a number introduced by a "tracking number:" style label. */
+export function keywordNumberInText(raw) {
+    const match = raw.match(/(?:(?:tracking|track(?:ing)?\s*(?:number|no\.?|id)?)|(?:parcel|shipment)(?:\s+(?:tracking|number|no\.?|id))?)\s*[:#-]?\s*([A-Z0-9][A-Z0-9.-]{3,39})/i);
+    const candidate = match?.[1]?.trim();
+    return candidate && validTrackingNumber(candidate) ? candidate : undefined;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * The detection engine.
+ *
+ * What it is: matches a tracking number against every carrier's catalog
+ * detection rules and their checksums. Exactly one high-confidence match
+ * selects a carrier; zero or several keep the number as a low-confidence
+ * suggestion and return the candidates.
+ * What it is not: no network lookup, no provider I/O, no carrier ranking by
+ * popularity — only the rules declared in the catalog decide. A `preferred`
+ * rule only moves its carrier to the front of the suggestions.
+ */
+import type { CarrierId } from '../../generated/catalog.js';
+import type { CarrierDetection } from './types.js';
+/** Return only a high-confidence carrier; preserve ambiguous candidates for the UI. */
+export declare function detectCarrierMatch(raw: string): CarrierDetection;
+/** Guess only when the tracking-number shape identifies one carrier confidently. */
+export declare function detectCarrier(raw: string): CarrierId;

package/dist/core/detection/detect.js

@@ -0,0 +1,52 @@
+import { CARRIER_DEFINITIONS } from '../catalog/definitions.js';
+import { isValidGlsParcelNumber } from './gls.js';
+import { isValidHermesParcelNumber } from './hermes.js';
+import { isValidMondialRelayBarcode } from './mondialRelay.js';
+import { normalizeTrackingNumber } from './normalize.js';
+import { isValidS10TrackingNumber } from './s10.js';
+function checksumPasses(rule, trackingNumber) {
+    if (rule.checksum === 'mondial-relay')
+        return isValidMondialRelayBarcode(trackingNumber);
+    if (rule.checksum === 's10')
+        return isValidS10TrackingNumber(trackingNumber);
+    if (rule.checksum === 'hermes')
+        return isValidHermesParcelNumber(trackingNumber);
+    if (rule.checksum === 'gls')
+        return isValidGlsParcelNumber(trackingNumber);
+    return true;
+}
+/** Return only a high-confidence carrier; preserve ambiguous candidates for the UI. */
+export function detectCarrierMatch(raw) {
+    const printed = raw.trim().toUpperCase();
+    const trackingNumber = normalizeTrackingNumber(raw);
+    if (!trackingNumber) {
+        return { carrier: 'unknown', confidence: 'none', candidates: [], preferred: [] };
+    }
+    const matches = [];
+    for (const [carrier, definition] of Object.entries(CARRIER_DEFINITIONS)) {
+        // A carrier's first matching rule decides its confidence and preference.
+        const rule = definition.detectionRules.find((candidate) => new RegExp(candidate.pattern).test(trackingNumber)
+            && (!candidate.rawPattern || new RegExp(candidate.rawPattern).test(printed))
+            && checksumPasses(candidate, trackingNumber));
+        if (rule)
+            matches.push({ carrier: carrier, confidence: rule.confidence, preferred: rule.preferred === true });
+    }
+    const highConfidence = matches.filter((match) => match.confidence === 'high');
+    const ranked = highConfidence.length > 0 ? highConfidence : matches;
+    // Number evidence first; catalog order otherwise.
+    const preferred = ranked.filter((match) => match.preferred).map((match) => match.carrier);
+    const candidates = [...preferred, ...ranked.filter((match) => !match.preferred).map((match) => match.carrier)];
+    if (highConfidence.length === 1) {
+        return { carrier: highConfidence[0].carrier, confidence: 'high', candidates, preferred };
+    }
+    return {
+        carrier: 'unknown',
+        confidence: matches.length > 0 ? 'low' : 'none',
+        candidates,
+        preferred,
+    };
+}
+/** Guess only when the tracking-number shape identifies one carrier confidently. */
+export function detectCarrier(raw) {
+    return detectCarrierMatch(raw).carrier;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function isValidGlsParcelNumber(value: string): boolean;