universal-parcel-scraper 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,24 @@
+import type { Recognition } from '../adapter/index.js';
+import type { RecognitionCandidate } from '../catalog/recognition.js';
+export { MAX_RECOGNITIONS, recognitionCandidates, type RecognitionCandidate, } from '../catalog/recognition.js';
+export type RecognitionStatus = 'known' | 'unknown' | 'failed';
+export interface RecognitionOutcome extends RecognitionCandidate {
+    status: RecognitionStatus;
+    lastActivityAt: string | null;
+}
+/**
+ * Ask every candidate at once. A candidate that throws, or has not answered
+ * when the budget runs out, is `failed`; its lookup may still finish in the
+ * background, but its answer is ignored.
+ */
+export declare function recognizeAll(candidates: readonly RecognitionCandidate[], recognize: (carrier: string) => Promise<Recognition>, budgetMs: number): Promise<RecognitionOutcome[]>;
+/**
+ * The carrier the answers settle on: the only recent one, else the only one
+ * number evidence backs, else, when every answer comes from one brand's
+ * networks, the most popular of them. Unrelated carriers that all know the
+ * number stay a choice for the user.
+ */
+export declare function settleRecognition(outcomes: readonly RecognitionOutcome[], now?: Date): {
+    carrier?: string;
+    choices: string[];
+};

package/dist/core/recognition/index.js

@@ -0,0 +1,65 @@
+import { carrierBrand } from '../catalog/networks.js';
+import { CARRIER_RECOGNITION_RANKS } from '../../generated/recognition.js';
+export { MAX_RECOGNITIONS, recognitionCandidates, } from '../catalog/recognition.js';
+/**
+ * Carrier recognition: when a number's shape fits several carriers, ask the
+ * ones that can answer cheaply whether they know it. The Add sheet runs it
+ * while the user is still in the form, the first sync runs it again after
+ * saving, and routing keeps retrying it while the filed carrier cannot track
+ * the number. Which carriers qualify is shared with the Add sheets
+ * (`@carriers/core/catalog/recognition`), which name them while they answer.
+ */
+/** An answer for a parcel quiet this long is taken for an older parcel that reused the number. */
+const RECENT_ACTIVITY_MS = 60 * 24 * 3_600_000;
+/**
+ * Ask every candidate at once. A candidate that throws, or has not answered
+ * when the budget runs out, is `failed`; its lookup may still finish in the
+ * background, but its answer is ignored.
+ */
+export async function recognizeAll(candidates, recognize, budgetMs) {
+    const outcomes = candidates.map((candidate) => ({ ...candidate, status: 'failed', lastActivityAt: null }));
+    let timer;
+    const deadline = new Promise((resolve) => { timer = setTimeout(resolve, budgetMs); });
+    const asked = candidates.map(async (candidate, index) => {
+        try {
+            const answer = await recognize(candidate.carrier);
+            outcomes[index] = { ...candidate, status: answer.known ? 'known' : 'unknown', lastActivityAt: answer.lastActivityAt ?? null };
+        }
+        catch {
+            // Stays failed: an outage is no answer about the number.
+        }
+    });
+    try {
+        await Promise.race([Promise.all(asked), deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return outcomes.map((outcome) => ({ ...outcome }));
+}
+function recent(outcome, now) {
+    const at = Date.parse(outcome.lastActivityAt ?? '');
+    return !Number.isFinite(at) || now.getTime() - at < RECENT_ACTIVITY_MS;
+}
+/**
+ * The carrier the answers settle on: the only recent one, else the only one
+ * number evidence backs, else, when every answer comes from one brand's
+ * networks, the most popular of them. Unrelated carriers that all know the
+ * number stay a choice for the user.
+ */
+export function settleRecognition(outcomes, now = new Date()) {
+    const known = outcomes.filter((outcome) => outcome.status === 'known' && recent(outcome, now));
+    if (known.length === 0)
+        return { choices: [] };
+    if (known.length === 1)
+        return { carrier: known[0].carrier, choices: [] };
+    const backed = known.filter((outcome) => outcome.preferred);
+    if (backed.length === 1)
+        return { carrier: backed[0].carrier, choices: [] };
+    const brands = new Set(known.map((outcome) => carrierBrand(outcome.carrier) ?? outcome.carrier));
+    if (brands.size === 1) {
+        const [best] = [...known].sort((left, right) => (CARRIER_RECOGNITION_RANKS[right.carrier] ?? 0) - (CARRIER_RECOGNITION_RANKS[left.carrier] ?? 0));
+        return { carrier: best.carrier, choices: [] };
+    }
+    return { choices: known.map((outcome) => outcome.carrier) };
+}

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

@@ -0,0 +1,57 @@
+/**
+ * The result every adapter and provider returns, and its normalization.
+ *
+ * What it is: the shape contract between the carrier package and the host
+ * (status, stage, estimate, sender/pickup names, weight, and the projected
+ * events). What it is not: it does not classify wording or touch the
+ * database; the host's sync does that after `normalizeCarrierResult`.
+ * An event with no `stage` means "no explicit mapping" (see
+ * ARCHITECTURE.md § Status model).
+ */
+import { type JsonObject } from '../types.js';
+export type CarrierStatus = 'pending' | 'in_transit' | 'out_for_delivery' | 'delivered' | 'exception' | 'unknown';
+export interface CarrierEvent extends JsonObject {
+    time?: string;
+    location?: string;
+    description?: string;
+    stage?: string;
+    provider_code?: string;
+    /**
+     * Where the carrier itself puts the scanning facility, when it says so. The
+     * map uses it only where it agrees with the town in `location`.
+     */
+    point?: EventPoint;
+}
+export interface EventPoint extends JsonObject {
+    latitude: number;
+    longitude: number;
+}
+export interface CarrierResult extends JsonObject {
+    status?: CarrierStatus;
+    current_stage?: string;
+    last_status_text?: string | null;
+    last_update?: string | null;
+    expected_delivery?: string | null;
+    expected_delivery_from?: string | null;
+    sender_name?: string | null;
+    receiver_name?: string | null;
+    pickup_point?: string | null;
+    delivered_at?: string | null;
+    weight_kg?: number | null;
+    dimensions_text?: string | null;
+    /** A declared delivery partner, still subject to direct identity/progress confirmation. */
+    delivery_carrier?: string;
+    destination_country?: string;
+    /** Preserve provider country labels when no verified ISO mapping is available. */
+    destination_country_name?: string;
+    delivery_tracking_number?: string;
+    canonical_tracking_number?: string;
+    international_tracking_number?: string;
+    timezone?: string;
+    /** An identity-bound current status without a scan history. */
+    summary_only?: boolean;
+    events?: CarrierEvent[];
+}
+/** A carrier's coordinates for a scan, or null when they are not a usable point. */
+export declare function eventPoint(latitude: unknown, longitude: unknown): EventPoint | null;
+export declare function normalizeCarrierResult(value: unknown): CarrierResult;

package/dist/core/result/index.js

@@ -0,0 +1,114 @@
+/**
+ * The result every adapter and provider returns, and its normalization.
+ *
+ * What it is: the shape contract between the carrier package and the host
+ * (status, stage, estimate, sender/pickup names, weight, and the projected
+ * events). What it is not: it does not classify wording or touch the
+ * database; the host's sync does that after `normalizeCarrierResult`.
+ * An event with no `stage` means "no explicit mapping" (see
+ * ARCHITECTURE.md § Status model).
+ */
+import { isRecord } from '../types.js';
+import { CARRIER_CATALOG, STAGES } from '../../generated/catalog.js';
+const STATUSES = new Set([
+    'pending',
+    'in_transit',
+    'out_for_delivery',
+    'delivered',
+    'exception',
+    'unknown',
+]);
+const CURRENT_STAGES = new Set(STAGES);
+const OPTIONAL_TEXT_FIELDS = [
+    'last_status_text',
+    'last_update',
+    'expected_delivery',
+    'expected_delivery_from',
+    'sender_name',
+    'receiver_name',
+    'pickup_point',
+    'delivered_at',
+    'dimensions_text',
+    'canonical_tracking_number',
+    'international_tracking_number',
+    'timezone',
+];
+const EVENT_TEXT_FIELDS = ['time', 'location', 'description', 'stage'];
+/** A carrier's coordinates for a scan, or null when they are not a usable point. */
+export function eventPoint(latitude, longitude) {
+    const number = (value) => typeof value === 'string' && value.trim() ? Number(value) : value;
+    const lat = number(latitude);
+    const lon = number(longitude);
+    if (typeof lat !== 'number' || typeof lon !== 'number' || !Number.isFinite(lat) || !Number.isFinite(lon))
+        return null;
+    // 0,0 is a missing value, not a scan in the Gulf of Guinea.
+    if (Math.abs(lat) > 90 || Math.abs(lon) > 180 || (lat === 0 && lon === 0))
+        return null;
+    // Four decimals is about ten metres: a building, not a desk.
+    return { latitude: Math.round(lat * 1e4) / 1e4, longitude: Math.round(lon * 1e4) / 1e4 };
+}
+export function normalizeCarrierResult(value) {
+    if (!isRecord(value))
+        throw new TypeError('The carrier adapter returned an invalid response');
+    const normalized = { ...value };
+    normalized.status = typeof value.status === 'string' && STATUSES.has(value.status)
+        ? value.status
+        : 'unknown';
+    if (value.current_stage !== undefined) {
+        if (typeof value.current_stage !== 'string' || !CURRENT_STAGES.has(value.current_stage)) {
+            throw new TypeError('The carrier adapter returned an invalid current stage');
+        }
+        normalized.current_stage = value.current_stage;
+    }
+    for (const field of OPTIONAL_TEXT_FIELDS) {
+        const fieldValue = normalized[field];
+        if (fieldValue != null && typeof fieldValue !== 'string') {
+            throw new TypeError(`The carrier adapter returned an invalid ${field.replaceAll('_', ' ')}`);
+        }
+    }
+    const weight = normalized.weight_kg;
+    if (weight != null && (typeof weight !== 'number' || !Number.isFinite(weight) || weight < 0)) {
+        throw new TypeError('The carrier adapter returned an invalid parcel weight');
+    }
+    // Optional routing evidence must not discard otherwise valid tracking history.
+    // A carrier can report a verified downstream reference without naming the
+    // operator. Preserve that independent evidence for catalog-based discovery.
+    if ((normalized.delivery_carrier != null && (typeof normalized.delivery_carrier !== 'string'
+        || !Object.hasOwn(CARRIER_CATALOG, normalized.delivery_carrier)))
+        || (normalized.delivery_tracking_number != null && (typeof normalized.delivery_tracking_number !== 'string'
+            || !/^[A-Z0-9]{4,40}$/.test(normalized.delivery_tracking_number)))) {
+        delete normalized.delivery_carrier;
+        delete normalized.delivery_tracking_number;
+    }
+    if (typeof normalized.destination_country !== 'string' || !/^[A-Z]{2}$/.test(normalized.destination_country)) {
+        delete normalized.destination_country;
+    }
+    if (typeof normalized.destination_country_name !== 'string' || normalized.destination_country_name.length > 80) {
+        delete normalized.destination_country_name;
+    }
+    const rawEvents = normalized.events ?? [];
+    if (!Array.isArray(rawEvents)) {
+        throw new TypeError('The carrier adapter returned invalid tracking events');
+    }
+    normalized.events = rawEvents.map((rawEvent) => {
+        if (!isRecord(rawEvent)) {
+            throw new TypeError('The carrier adapter returned an invalid tracking event');
+        }
+        for (const field of EVENT_TEXT_FIELDS) {
+            const fieldValue = rawEvent[field];
+            if (fieldValue != null && typeof fieldValue !== 'string') {
+                throw new TypeError('The carrier adapter returned an invalid tracking event');
+            }
+        }
+        const event = { ...rawEvent };
+        if (event.point !== undefined) {
+            const point = isRecord(event.point) ? eventPoint(event.point.latitude, event.point.longitude) : null;
+            if (point)
+                event.point = point;
+            else
+                delete event.point;
+        }
+        return event;
+    });
+    return normalized;
+}

package/dist/core/result/resolve.d.ts

@@ -0,0 +1,18 @@
+import { type Stage } from '../../generated/catalog.js';
+import { type CarrierEvent, type CarrierResult } from './index.js';
+export declare function resultStage(result: CarrierResult): Stage | null;
+export declare function resultHasUpdate(result: CarrierResult): boolean;
+export declare function classifyStage(text: string, fallback?: string): import("../status/wording.js").ClassifiedWording;
+export declare function inferStage(text: string, fallback?: string): string;
+export declare function stageSource(declaredStage: string, description: string): string;
+export interface ResolvedEvent extends CarrierEvent {
+    stage: Stage;
+    stage_source: string;
+    /** Null for a date or local clock whose offset the feed did not establish. */
+    instant: string | null;
+}
+export interface ResolvedResult extends CarrierResult {
+    events: ResolvedEvent[];
+}
+/** Classify wording and expose verified instants while retaining the feed's clocks. */
+export declare function resolveResult(input: unknown): ResolvedResult;

package/dist/core/result/resolve.js

@@ -0,0 +1,49 @@
+import { STAGES } from '../../generated/catalog.js';
+import { classifyWording } from '../status/index.js';
+import { explicitOffsetTime } from '../time/index.js';
+import { normalizeCarrierResult } from './index.js';
+const stages = new Set(STAGES);
+export function resultStage(result) {
+    if (stages.has(result.current_stage ?? ''))
+        return result.current_stage;
+    const fallback = {
+        pending: 'pending', in_transit: 'in_transit', out_for_delivery: 'out_for_delivery',
+        delivered: 'delivered', exception: 'failed_attempt',
+    };
+    const base = fallback[result.status ?? 'unknown'];
+    if (!base)
+        return null;
+    const stage = classifyWording(result.last_status_text ?? '', base).stage;
+    const first = result.events?.[0]?.stage;
+    return stage === 'pending' && stages.has(first ?? '') ? first : stage;
+}
+export function resultHasUpdate(result) {
+    const stage = resultStage(result);
+    return Boolean(stage && stage !== 'pending') || (result.events ?? []).some(event => {
+        const declared = stages.has(event.stage ?? '') ? event.stage : undefined;
+        return Boolean(declared && declared !== 'pending')
+            || Boolean(event.description && classifyWording(event.description, 'pending').stage !== 'pending');
+    });
+}
+export function classifyStage(text, fallback = 'in_transit') {
+    return classifyWording(text, fallback);
+}
+export function inferStage(text, fallback = 'in_transit') {
+    return classifyStage(text, fallback).stage;
+}
+export function stageSource(declaredStage, description) {
+    return stages.has(declaredStage) ? 'carrier_map' : classifyStage(description).source;
+}
+/** Classify wording and expose verified instants while retaining the feed's clocks. */
+export function resolveResult(input) {
+    const result = normalizeCarrierResult(input);
+    const current = resultStage(result);
+    const events = (result.events ?? []).map((event) => {
+        const declared = stages.has(event.stage ?? '') ? event.stage : undefined;
+        const classified = classifyWording(event.description ?? '', 'in_transit');
+        return { ...event, stage: declared ?? classified.stage,
+            stage_source: declared ? 'carrier_map' : classified.source,
+            instant: explicitOffsetTime(event.time)?.iso ?? null };
+    });
+    return { ...result, ...(current ? { current_stage: current } : {}), events };
+}

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

@@ -0,0 +1,33 @@
+import { type StepRecorder } from '../telemetry/index.js';
+export interface StepContext {
+    /** Aborts when the lookup budget or the caller's signal expires. */
+    signal: AbortSignal;
+    /** Milliseconds left in the lookup budget when the step started. */
+    remainingMs: number;
+    attempt: number;
+    /** The error that made the previous step fail, when this step is a recovery. */
+    previousError: unknown;
+}
+export interface StepSpec<T> {
+    id: string;
+    run: (context: StepContext) => Promise<T>;
+    /** Skipped when false, for example when the browser service is not configured. */
+    enabled?: boolean;
+    /** Whether this step may run after the previous one failed with `error`. Defaults to `recoverableByDefault`. */
+    recovers?: (error: unknown) => boolean;
+}
+export interface RunOptions {
+    carrier: string;
+    budgetMs: number;
+    recorder?: StepRecorder;
+    signal?: AbortSignal;
+    now?: () => number;
+}
+/** A later tier may retry after a challenge, a transport failure, an inconclusive answer or an unclassified error; never after a definite answer. */
+export declare function recoverableByDefault(error: unknown): boolean;
+export declare function runSteps<T>(options: RunOptions, steps: readonly StepSpec<T>[]): Promise<T>;
+/**
+ * Serialize calls through one adapter instance so a shared session (cookies,
+ * CSRF tokens, version handles) is never refreshed by two lookups at once.
+ */
+export declare function singleFlight(): <T>(operation: () => Promise<T>) => Promise<T>;

package/dist/core/runner/index.js

@@ -0,0 +1,109 @@
+/**
+ * Tiered execution for adapters that have more than one way to reach a
+ * provider (for example a direct HTTP request, then a browser service when the
+ * direct path is challenged).
+ *
+ * `runSteps()` runs the declared steps in order, decides from the error kind
+ * whether the next step may recover, enforces one time budget across all
+ * steps, and reports every attempt plus the final outcome through the
+ * `StepRecorder`. Adapters describe their tiers; they do not time or count
+ * them.
+ */
+import { BudgetExceededError, carrierErrorKind } from '../errors/index.js';
+import { NOOP_RECORDER, errorTypeOf, outcomeOf, safeRecorder } from '../telemetry/index.js';
+const RECOVERABLE = new Set(['challenge', 'transport', 'indeterminate', 'error']);
+/** A later tier may retry after a challenge, a transport failure, an inconclusive answer or an unclassified error; never after a definite answer. */
+export function recoverableByDefault(error) {
+    return RECOVERABLE.has(outcomeOf(error));
+}
+function combinedSignal(external, timeoutMs) {
+    const timeout = AbortSignal.timeout(Math.max(1, Math.floor(timeoutMs)));
+    if (!external)
+        return timeout;
+    const any = AbortSignal.any;
+    return typeof any === 'function' ? any.call(AbortSignal, [external, timeout]) : timeout;
+}
+export async function runSteps(options, steps) {
+    const recorder = safeRecorder(options.recorder ?? NOOP_RECORDER);
+    const now = options.now ?? (() => performance.now());
+    const started = now();
+    const enabled = steps.filter((step) => step.enabled !== false);
+    let attempt = 0;
+    let previousError;
+    let previousStep = null;
+    let lastStep = null;
+    const finish = (outcome, error) => {
+        recorder.lookup({
+            carrier: options.carrier, finalStep: lastStep, outcome, errorType: error === undefined ? null : errorTypeOf(error),
+            durationMs: Math.max(0, now() - started), attempts: attempt, stepsAvailable: enabled.length,
+            ...(error === undefined ? {} : { error }),
+        });
+    };
+    const fallback = () => (previousStep === null
+        ? { fallbackFrom: null, fallbackReason: null, fallbackErrorType: null }
+        : { fallbackFrom: previousStep, fallbackReason: outcomeOf(previousError), fallbackErrorType: errorTypeOf(previousError), fallbackError: previousError });
+    for (const step of enabled) {
+        if (previousStep !== null && !(step.recovers ?? recoverableByDefault)(previousError))
+            continue;
+        const remainingMs = options.budgetMs - (now() - started);
+        if (remainingMs <= 0) {
+            const error = new BudgetExceededError(options.carrier, options.budgetMs, { cause: previousError });
+            finish('budget', error);
+            throw error;
+        }
+        attempt += 1;
+        lastStep = step.id;
+        const stepStarted = now();
+        try {
+            const value = await step.run({
+                signal: combinedSignal(options.signal, remainingMs), remainingMs, attempt, previousError,
+            });
+            recorder.step({
+                carrier: options.carrier, step: step.id, attempt, outcome: 'ok', errorType: null,
+                durationMs: Math.max(0, now() - stepStarted), ...fallback(),
+            });
+            finish('ok');
+            return value;
+        }
+        catch (error) {
+            recorder.step({
+                carrier: options.carrier, step: step.id, attempt, outcome: outcomeOf(error), errorType: errorTypeOf(error),
+                durationMs: Math.max(0, now() - stepStarted), ...fallback(), error,
+            });
+            previousError = error;
+            previousStep = step.id;
+            // A definite answer (not found, rate limited, schema...) ends the lookup here.
+            if (carrierErrorKind(error) !== null && !recoverableByDefault(error)
+                && !enabled.slice(enabled.indexOf(step) + 1).some((next) => next.recovers?.(error))) {
+                finish(outcomeOf(error), error);
+                throw error;
+            }
+        }
+    }
+    if (attempt === 0) {
+        const error = new BudgetExceededError(options.carrier, options.budgetMs);
+        finish('budget', error);
+        throw error;
+    }
+    finish(outcomeOf(previousError), previousError);
+    throw previousError;
+}
+/**
+ * Serialize calls through one adapter instance so a shared session (cookies,
+ * CSRF tokens, version handles) is never refreshed by two lookups at once.
+ */
+export function singleFlight() {
+    let tail = Promise.resolve();
+    return async (operation) => {
+        const previous = tail;
+        let release;
+        tail = new Promise((resolve) => { release = resolve; });
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Status vocabulary and the shared wording classifier.
+ *
+ * What it is: the product `Stage` vocabulary re-exported for adapters, the
+ * `ClassifiedStatus` pair every carrier status map produces, and the
+ * multilingual wording → stage rules used as a fallback when a carrier has no
+ * explicit map for an event. What it is not: it never talks to a provider and
+ * never persists anything; the host's sync decides precedence and records
+ * where each stage came from.
+ */
+import type { CarrierStatus } from '../result/index.js';
+import type { Stage } from '../../generated/catalog.js';
+export type { Stage };
+export { STAGES } from '../../generated/catalog.js';
+export { trackingLanguageStage, languageStageStatus } from './language.js';
+export { classifyWording, wordingStage } from './wording.js';
+export type { ClassifiedWording } from './wording.js';
+/** What a carrier's explicit status map yields for one raw code or wording. */
+export interface ClassifiedStatus {
+    status: CarrierStatus;
+    stage: Stage;
+}

package/dist/core/status/index.js

@@ -0,0 +1,3 @@
+export { STAGES } from '../../generated/catalog.js';
+export { trackingLanguageStage, languageStageStatus } from './language.js';
+export { classifyWording, wordingStage } from './wording.js';

package/dist/core/status/language.d.ts

@@ -0,0 +1,11 @@
+import type { Stage } from '../../generated/catalog.js';
+import type { CarrierStatus } from '../result/index.js';
+/** Instructions, uncertainty and a return in progress do not prove sender delivery. */
+export declare function nonterminalEnglishReturn(description: string): boolean;
+/**
+ * INFERRED language rules, not captured carrier codes. EN/FR/DE/IT/ES/PT/PL equivalents
+ * are intuitive and overridable: an adapter must resolve verified codes and
+ * carrier-specific semantics before consulting this fallback. No fixture import.
+ */
+export declare function trackingLanguageStage(description: string): Stage | undefined;
+export declare function languageStageStatus(stage: Stage): CarrierStatus;