universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/providers/universal.js

@@ -0,0 +1,95 @@
+import { NOOP_RECORDER } from '../core/telemetry/index.js';
+import { TrawlClient } from '../core/transport/index.js';
+import { adapter as parcelsAppAdapter } from './parcelsapp/adapter.js';
+import { adapter as postalNinjaAdapter } from './postal-ninja/adapter.js';
+import { adapter as seventeenTrackAdapter } from './seventeentrack/adapter.js';
+import { adapter as ship24Adapter } from './ship24/adapter.js';
+import { adapter as upuAdapter } from './upu/adapter.js';
+import { numberOf } from './shared/result.js';
+export { parse17TrackResponse, SeventeenTrackLookupError, SeventeenTrackNoHistoryError, SeventeenTrackVerificationError } from './seventeentrack/adapter.js';
+export { parseParcelsAppHtml, parseParcelsAppResponse } from './parcelsapp/adapter.js';
+export { parsePostalNinjaResponse } from './postal-ninja/adapter.js';
+export { parseShip24Response } from './ship24/adapter.js';
+export { TrackingCaptureError } from './shared/capture.js';
+export * from './plan.js';
+import { universalSources, universalSourceBudget } from './plan.js';
+const FACTORIES = {
+    'Ship24': ship24Adapter,
+    'ParcelsApp': parcelsAppAdapter,
+    'Postal Ninja': postalNinjaAdapter,
+    '17TRACK': seventeenTrackAdapter,
+    'UPU': upuAdapter,
+};
+export class UniversalTrackingError extends AggregateError {
+    failures;
+    constructor(failures) {
+        super(failures.map(({ error }) => error), `Automatic carrier lookup could not retrieve tracking history. ${failures.map(({ source, reason }) => `${source}: ${reason}`).join('; ')}`);
+        this.failures = failures;
+        this.name = 'UniversalTrackingError';
+    }
+}
+export class UniversalTracker {
+    options;
+    instances = new Map();
+    constructor(options = {}) {
+        this.options = options;
+        if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
+            throw new TypeError('Universal tracking timeout must be positive');
+        }
+    }
+    /**
+     * Look up one number through the whole chain. `postcode` is the parcel's
+     * stored delivery postcode, if the user supplied one: it is forwarded into
+     * every provider's track input. ParcelsApp submits it as extra[zipcode] on
+     * its direct API request; the other providers currently do not consume it.
+     */
+    async fetch(trackingNumber, postcode) {
+        numberOf(trackingNumber);
+        const failures = [];
+        const sources = universalSources(this.options.enablePostalNinja, trackingNumber).filter(source => (this.options.providers ?? ['UPU']).includes(source));
+        for (const source of sources) {
+            try {
+                return await this.fetchSource(source, trackingNumber, undefined, postcode);
+            }
+            catch (error) {
+                failures.push({ source, reason: 'history unavailable; try again later or open the tracking website', error });
+            }
+        }
+        throw new UniversalTrackingError(failures);
+    }
+    async fetchSource(source, trackingNumber, timeoutMs = this.options.timeoutMs ?? universalSourceBudget(source), postcode, timezone, signal) {
+        const number = numberOf(trackingNumber);
+        if (this.options.browserLookup && (source === 'Postal Ninja' || source === 'Ship24')) {
+            return await this.options.browserLookup(source, number);
+        }
+        return await this.provider(source).track({ number, postcode: postcode ?? null, timezone: timezone ?? null }, { budgetMs: timeoutMs, signal });
+    }
+    /** One provider adapter, built from this tracker's environment. */
+    provider(source) {
+        let instance = this.instances.get(source);
+        if (!instance) {
+            instance = FACTORIES[source](this.environment());
+            this.instances.set(source, instance);
+        }
+        return instance;
+    }
+    environment() {
+        const partial = this.options.environment ?? {};
+        const fetcher = partial.fetcher ?? this.options.fetcher;
+        return {
+            fetcher,
+            trawl: this.trawl(fetcher, partial),
+            browserExecutablePath: partial.browserExecutablePath ?? this.options.executablePath ?? null,
+            recorder: partial.recorder ?? NOOP_RECORDER,
+            env: partial.env ?? {},
+        };
+    }
+    trawl(fetcher, partial) {
+        const configured = this.options.trawlUrl;
+        if (configured !== undefined)
+            return configured ? new TrawlClient(configured, fetcher) : null;
+        if (partial.trawl !== undefined)
+            return partial.trawl;
+        return TrawlClient.fromEnvironment(partial.env ?? {}, fetcher);
+    }
+}

package/dist/providers/upu/adapter.d.ts

@@ -0,0 +1,5 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const UPU_BUDGET_MS = 8000;
+export declare function parseUpuResponse(payload: unknown, trackingNumber: string): CarrierResult;
+export declare const adapter: AdapterFactory;

package/dist/providers/upu/adapter.js

@@ -0,0 +1,107 @@
+import { DateTime } from 'luxon';
+import { isValidS10TrackingNumber } from '../../core/detection/s10.js';
+import { NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { decodeText, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { eventStage, hasPrivateDeliveryDetails, isNotice, numberOf, result, text } from '../shared/result.js';
+const SOURCE = 'UPU';
+export const UPU_BUDGET_MS = 8_000;
+const MAX_EVENTS = 1_000;
+const STAGES = {
+    EMA: 'accepted', EMB: 'in_transit', EMC: 'in_transit', EMD: 'in_transit',
+    EDA: 'customs', EDB: 'customs', EDC: 'in_transit',
+    EXA: 'customs', EXB: 'customs', EXC: 'in_transit', EMI: 'delivered',
+};
+/** The wire offset was contradicted by a destination operator; retain wall time only. */
+function localTime(value) {
+    if (typeof value !== 'string')
+        throw new SchemaError(SOURCE, 'UPU event has no date');
+    const wcf = /^\/Date\((-?\d+)([+-])(\d{2})(\d{2})\)\/$/.exec(value);
+    let date;
+    if (wcf) {
+        const hours = Number(wcf[3]);
+        const minutes = Number(wcf[4]);
+        if (hours > 14 || minutes > 59 || (hours === 14 && minutes !== 0)) {
+            throw new SchemaError(SOURCE, 'UPU event has an invalid offset');
+        }
+        const offset = (wcf[2] === '+' ? 1 : -1) * (hours * 60 + minutes);
+        date = DateTime.fromMillis(Number(wcf[1]), { zone: 'UTC' }).plus({ minutes: offset });
+    }
+    else {
+        // Documented ISO replies still do not establish the event's true zone.
+        if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})?$/.test(value)) {
+            throw new SchemaError(SOURCE, 'UPU event has an invalid date');
+        }
+        date = DateTime.fromISO(value, { setZone: true, zone: 'UTC' });
+    }
+    if (!date.isValid || date.year < 1900 || date.year > 2200)
+        throw new SchemaError(SOURCE, 'UPU event has an invalid date');
+    return date.toFormat("yyyy-MM-dd'T'HH:mm:ss");
+}
+export function parseUpuResponse(payload, trackingNumber) {
+    const number = numberOf(trackingNumber);
+    if (Array.isArray(payload) && payload.length === 0)
+        throw new NotFoundError(SOURCE, 'UPU has no available history');
+    if (!Array.isArray(payload) || payload.length !== 1 || !isRecord(payload[0]) || payload[0].ID !== number
+        || !Array.isArray(payload[0].Events) || payload[0].Events.length > MAX_EVENTS) {
+        throw new SchemaError(SOURCE, 'UPU has no matching shipment history');
+    }
+    const events = [];
+    for (const raw of payload[0].Events) {
+        if (!isRecord(raw) || typeof raw.EventCd !== 'string' || !/^[A-Z0-9]{2,8}$/.test(raw.EventCd)) {
+            throw new SchemaError(SOURCE, 'UPU returned an invalid event');
+        }
+        const description = text(raw.EventNm);
+        // DLV means a forecast, not final delivery. Do not let it advance freshness.
+        if (raw.EventCd === 'DLV' || /\b(?:estimated|expected|predicted) delivery\b/i.test(description))
+            continue;
+        if (!description || isNotice(description))
+            throw new SchemaError(SOURCE, 'UPU returned no event label');
+        const stage = STAGES[raw.EventCd] ?? eventStage(description) ?? 'pending';
+        if (stage !== 'delivered' && hasPrivateDeliveryDetails(description))
+            continue;
+        const location = text(raw.EventLocation);
+        events.push({ local_time: localTime(raw.EventDT), provider_code: raw.EventCd,
+            description: stage === 'delivered' ? 'Delivered' : description, stage,
+            ...(location && !hasPrivateDeliveryDetails(location) ? { location } : {}),
+        });
+    }
+    if (!events.length)
+        throw new NotFoundError(SOURCE, 'UPU has no actual tracking scans');
+    // The response is oldest first. Sort within this feed only; never compare its
+    // wall times with another provider's instants. Numeric State is not a scan.
+    const unique = [...new Map(events.map((event) => [JSON.stringify([
+                event.local_time, event.provider_code, event.location, event.description,
+            ]), event])).values()].sort((a, b) => String(b.local_time).localeCompare(String(a.local_time)));
+    const projected = { ...result(unique, SOURCE, true), events: unique };
+    return { ...projected, last_update_local: projected.events?.[0]?.local_time,
+        tracking_source: 'structured-web-response' };
+}
+export const adapter = (environment) => ({
+    id: SOURCE,
+    steps: ['direct'],
+    async track(input, context) {
+        const number = numberOf(input.number);
+        if (!isValidS10TrackingNumber(number))
+            throw new TypeError('UPU requires a checksum-valid postal S10 number');
+        const budgetMs = Math.min(context?.budgetMs ?? UPU_BUDGET_MS, UPU_BUDGET_MS);
+        if (!Number.isFinite(budgetMs) || budgetMs < 1)
+            throw new TypeError('UPU timeout must be positive');
+        context?.signal?.throwIfAborted();
+        return runSteps({ carrier: SOURCE, budgetMs, signal: context?.signal, recorder: environment.recorder }, [{
+                id: 'direct',
+                run: async ({ remainingMs, signal }) => {
+                    const { bytes } = await fetchBounded(`https://globaltracktrace.ptc.post/gtt.api/service.svc/rest/ItemTTWithTrans/${number}/EN`, {}, { provider: SOURCE, timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: 2_000_000,
+                        fetcher: (url, init) => (environment.fetcher ?? fetch)(url, {
+                            ...init, signal: AbortSignal.any([signal, ...(init?.signal ? [init.signal] : [])]),
+                        }),
+                    });
+                    // The observed unknown/expired lookup is HTTP 200 with no body.
+                    if (!decodeText(bytes).trim())
+                        throw new NotFoundError(SOURCE, 'UPU has no available history');
+                    return parseUpuResponse(parseJsonBytes(bytes, SOURCE), number);
+                },
+            }]);
+    },
+});

package/dist/scripts/canary-report.d.mts

@@ -0,0 +1,22 @@
+/**
+ * @param {{ title: string, totals: string, rows: { result: 'failed' | 'unverified', check: string, reason: string }[] }} report
+ * @param {Record<string, string | undefined>} [env]
+ */
+export function writeCanaryReport({ title, totals, rows }: {
+    title: string;
+    totals: string;
+    rows: {
+        result: "failed" | "unverified";
+        check: string;
+        reason: string;
+    }[];
+}, env?: Record<string, string | undefined>): void;
+/**
+ * Vitest reporter for the live carrier suites. A skip with a note (bot
+ * protection, an unsolved challenge) is inconclusive, not a pass, so it is
+ * listed; a skip without one is a check gated on private input or a solver.
+ */
+export default class CanaryReporter {
+    /** @param {ReadonlyArray<import('vitest/node').TestModule>} testModules */
+    onTestRunEnd(testModules: ReadonlyArray<import("vitest/node").TestModule>, unhandledErrors: any): void;
+}

package/dist/scripts/canary-report.mjs

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
+
+// Daily carrier canary reporting for GitHub Actions. Every failed or
+// inconclusive live check is listed with its reason in the job summary, and
+// failures become the `failures` step output read by the issue job. Outside
+// Actions (no GITHUB_STEP_SUMMARY or GITHUB_OUTPUT) nothing is written.
+
+function cell(text) {
+  return String(text).replace(/\s+/g, ' ').replace(/\|/g, '\\|').replace(/`/g, "'").trim().slice(0, 240);
+}
+
+/**
+ * @param {{ title: string, totals: string, rows: { result: 'failed' | 'unverified', check: string, reason: string }[] }} report
+ * @param {Record<string, string | undefined>} [env]
+ */
+export function writeCanaryReport({ title, totals, rows }, env = process.env) {
+  if (env.GITHUB_STEP_SUMMARY) {
+    let summary = `### ${title}\n\n${totals}\n`;
+    if (rows.length) {
+      summary += '\n| Result | Check | Reason |\n| --- | --- | --- |\n';
+      for (const row of rows) {
+        summary += `| ${row.result === 'failed' ? '❌ failed' : '⚠️ unverified'} | ${cell(row.check)} | ${cell(row.reason)} |\n`;
+      }
+    }
+    fs.appendFileSync(env.GITHUB_STEP_SUMMARY, `${summary}\n`);
+  }
+  const failures = rows.filter((row) => row.result === 'failed');
+  if (env.GITHUB_OUTPUT && failures.length) {
+    const delimiter = `EOF_${randomUUID()}`;
+    const lines = failures.map((row) => `- \`${cell(row.check)}\`: ${cell(row.reason)}`);
+    fs.appendFileSync(env.GITHUB_OUTPUT, `failures<<${delimiter}\n${lines.join('\n')}\n${delimiter}\n`);
+  }
+}
+
+/**
+ * Vitest reporter for the live carrier suites. A skip with a note (bot
+ * protection, an unsolved challenge) is inconclusive, not a pass, so it is
+ * listed; a skip without one is a check gated on private input or a solver.
+ */
+export default class CanaryReporter {
+  /** @param {ReadonlyArray<import('vitest/node').TestModule>} testModules */
+  onTestRunEnd(testModules, unhandledErrors) {
+    /** @type {{ result: 'failed' | 'unverified', check: string, reason: string }[]} */
+    const rows = [];
+    let passed = 0;
+    let gated = 0;
+    const reason = (error) => `${error?.name ?? 'Error'}: ${error?.message ?? 'failed'}`;
+    for (const testModule of testModules) {
+      for (const error of testModule.errors()) {
+        rows.push({ result: 'failed', check: testModule.relativeModuleId, reason: reason(error) });
+      }
+      for (const test of testModule.children.allTests()) {
+        const result = test.result();
+        if (result.state === 'passed') passed += 1;
+        else if (result.state === 'failed') rows.push({ result: 'failed', check: test.fullName, reason: reason(result.errors?.[0]) });
+        else if (result.state === 'skipped' && result.note) rows.push({ result: 'unverified', check: test.fullName, reason: result.note });
+        else gated += 1;
+      }
+    }
+    for (const error of unhandledErrors) rows.push({ result: 'failed', check: 'Unhandled error', reason: reason(error) });
+    const failed = rows.filter((row) => row.result === 'failed').length;
+    writeCanaryReport({
+      title: process.env.CANARY_SUMMARY_TITLE || 'Live carrier checks',
+      totals: `${passed} passed · ${failed} failed · ${rows.length - failed} unverified · ${gated} not run (need private input or a challenge solver)`,
+      rows,
+    });
+  }
+}

package/dist/scripts/carrier-canary.d.ts

@@ -0,0 +1,50 @@
+export interface CanaryTarget {
+    carrierId: string;
+    displayName: string;
+    url: string;
+}
+export interface CanaryResult {
+    target: CanaryTarget;
+    status: number | null;
+    error?: string;
+}
+interface CanaryError {
+    name: string;
+    code?: string;
+    syscall?: string;
+    address?: string;
+    port?: number;
+    cause?: CanaryError;
+    errors?: CanaryError[];
+    truncated?: boolean;
+}
+interface CanaryAttempt {
+    attempt: number;
+    maxAttempts: number;
+    timeoutMs: number;
+    durationMs: number;
+    status: number | null;
+    error?: CanaryError;
+}
+export declare function canaryHealthy(result: CanaryResult): boolean;
+export declare function automaticCanaryTargets(definitions?: unknown): CanaryTarget[];
+export declare function requestCanaryStatus(url: string, timeoutMs: number): Promise<number>;
+export declare function probeCanaryTarget(target: CanaryTarget, options?: {
+    timeoutMs?: number;
+    attempts?: number;
+    fetchStatus?: (url: string, timeoutMs: number) => Promise<number>;
+    onAttempt?: (target: CanaryTarget, result: CanaryAttempt) => void;
+}): Promise<CanaryResult>;
+export declare function runCanaries(targets: CanaryTarget[], options?: Parameters<typeof probeCanaryTarget>[1]): Promise<CanaryResult[]>;
+/**
+ * Probes each target that got no HTTP answer again after a pause, for up to
+ * `rechecks` rounds. A front door on rotating DNS can hand out an edge this
+ * network cannot reach (YTO's CDN does), and an immediate retry meets the
+ * same address.
+ */
+export declare function recheckUnanswered(results: CanaryResult[], options?: NonNullable<Parameters<typeof probeCanaryTarget>[1]> & {
+    rechecks?: number;
+    pauseMs?: number;
+}): Promise<CanaryResult[]>;
+export declare function carrierCanaryMain(argv?: string[]): Promise<number>;
+export {};

package/dist/scripts/carrier-canary.js

@@ -0,0 +1,220 @@
+import { isIP } from 'node:net';
+import { pathToFileURL } from 'node:url';
+import catalog from '../data/catalog.json' with { type: 'json' };
+const contract = { 'x-carriers': catalog };
+import { writeCanaryReport } from './canary-report.mjs';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_ATTEMPTS = 2;
+const MAX_CONCURRENCY = 6;
+const DEFAULT_RECHECKS = 2;
+// Longer than the one-minute DNS answers of the CDNs seen rotating their edges.
+const DEFAULT_RECHECK_PAUSE_MS = 70_000;
+const ERROR_NAMES = new Set([
+    'Error', 'TypeError', 'AggregateError', 'AbortError', 'TimeoutError',
+    'ConnectTimeoutError', 'HeadersTimeoutError', 'BodyTimeoutError', 'SocketError',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function canaryErrorDetails(error, seen = new Set()) {
+    if (!isRecord(error))
+        return { name: typeof error };
+    if (seen.has(error) || seen.size >= 8)
+        return { name: 'Error', truncated: true };
+    seen.add(error);
+    const details = {
+        name: typeof error.name === 'string' && ERROR_NAMES.has(error.name) ? error.name : 'Error',
+    };
+    // Copy only bounded diagnostic fields. Messages, stacks and arbitrary properties
+    // can contain full URLs, credentials or response content.
+    if (typeof error.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(error.code)) {
+        details.code = error.code;
+    }
+    if (typeof error.syscall === 'string' && /^[a-z][a-z0-9]{0,31}$/.test(error.syscall)) {
+        details.syscall = error.syscall;
+    }
+    if (typeof error.address === 'string' && isIP(error.address))
+        details.address = error.address;
+    if (typeof error.port === 'number' && Number.isInteger(error.port) && error.port > 0 && error.port <= 65535) {
+        details.port = error.port;
+    }
+    if (error.cause !== undefined)
+        details.cause = canaryErrorDetails(error.cause, seen);
+    // Node may wrap the connection failures for several resolved IPs in AggregateError.
+    if (Array.isArray(error.errors)) {
+        details.errors = error.errors.slice(0, 8).map((item) => canaryErrorDetails(item, seen));
+        if (error.errors.length > 8)
+            details.truncated = true;
+    }
+    return details;
+}
+export function canaryHealthy(result) {
+    // A challenge or redirect still proves the front door answers. A missing
+    // page means the canary URL, and usually the lookup behind it, has moved.
+    return result.status !== null && result.status < 500 && result.status !== 404 && result.status !== 410;
+}
+export function automaticCanaryTargets(definitions = contract['x-carriers']) {
+    if (!isRecord(definitions))
+        throw new TypeError('Carrier definitions must be an object');
+    const targets = [];
+    for (const [carrierId, value] of Object.entries(definitions)) {
+        if (!isRecord(value) || !isRecord(value.tracking) || value.tracking.mode !== 'automatic') {
+            continue;
+        }
+        if (typeof value.displayName !== 'string' || typeof value.canaryUrl !== 'string') {
+            throw new TypeError(`Automatic carrier ${carrierId} has no canary metadata`);
+        }
+        let url;
+        try {
+            url = new URL(value.canaryUrl);
+        }
+        catch (error) {
+            throw new TypeError(`Automatic carrier ${carrierId} has an unsafe canary URL`, { cause: error });
+        }
+        if (url.protocol !== 'https:' || !url.hostname || url.username || url.password || url.search || url.hash) {
+            throw new TypeError(`Automatic carrier ${carrierId} has an unsafe canary URL`);
+        }
+        targets.push({ carrierId, displayName: value.displayName, url: url.toString() });
+    }
+    return targets;
+}
+export async function requestCanaryStatus(url, timeoutMs) {
+    const response = await fetch(url, {
+        headers: {
+            Accept: 'text/html,application/json;q=0.8,*/*;q=0.5',
+            'User-Agent': 'SwissDeliveryTracker-Canary/1.0',
+        },
+        cache: 'no-store',
+        redirect: 'manual',
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        // The HTTP status is sufficient even if the probe body cannot be cancelled.
+    }
+    return response.status;
+}
+export async function probeCanaryTarget(target, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const attempts = options.attempts ?? DEFAULT_ATTEMPTS;
+    const fetchStatus = options.fetchStatus ?? requestCanaryStatus;
+    if (!Number.isInteger(attempts) || attempts < 1)
+        throw new TypeError('Canary attempts must be positive');
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new TypeError('Canary timeout must be positive');
+    let status = null;
+    let error;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const started = performance.now();
+        let errorDetails;
+        try {
+            status = await fetchStatus(target.url, timeoutMs);
+            error = undefined;
+        }
+        catch (caught) {
+            status = null;
+            errorDetails = canaryErrorDetails(caught);
+            error = errorDetails.name;
+        }
+        options.onAttempt?.(target, {
+            attempt: attempt + 1,
+            maxAttempts: attempts,
+            timeoutMs,
+            durationMs: Math.round(performance.now() - started),
+            status,
+            ...(errorDetails ? { error: errorDetails } : {}),
+        });
+        if (status !== null && status < 500)
+            break;
+    }
+    return { target, status, ...(error ? { error } : {}) };
+}
+export async function runCanaries(targets, options = {}) {
+    const results = new Array(targets.length);
+    let cursor = 0;
+    const runWorker = async () => {
+        while (cursor < targets.length) {
+            const index = cursor;
+            cursor += 1;
+            results[index] = await probeCanaryTarget(targets[index], options);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(MAX_CONCURRENCY, targets.length) }, runWorker));
+    return results;
+}
+/**
+ * Probes each target that got no HTTP answer again after a pause, for up to
+ * `rechecks` rounds. A front door on rotating DNS can hand out an edge this
+ * network cannot reach (YTO's CDN does), and an immediate retry meets the
+ * same address.
+ */
+export async function recheckUnanswered(results, options = {}) {
+    const { rechecks = DEFAULT_RECHECKS, pauseMs = DEFAULT_RECHECK_PAUSE_MS, ...probe } = options;
+    let current = results;
+    for (let round = 0; round < rechecks; round += 1) {
+        const unanswered = current.filter((result) => result.status === null).map((result) => result.target);
+        if (!unanswered.length)
+            break;
+        await new Promise((resolve) => { setTimeout(resolve, pauseMs); });
+        const rechecked = await runCanaries(unanswered, { ...probe, attempts: 1 });
+        current = current.map((result) => rechecked.find((again) => again.target === result.target) ?? result);
+    }
+    return current;
+}
+function optionValue(argv, name, fallback) {
+    const index = argv.indexOf(name);
+    if (index < 0)
+        return fallback;
+    const value = Number(argv[index + 1]);
+    if (!Number.isFinite(value) || value <= 0)
+        throw new TypeError(`${name} must be positive`);
+    return value;
+}
+export async function carrierCanaryMain(argv = process.argv.slice(2)) {
+    const timeoutMs = optionValue(argv, '--timeout', DEFAULT_TIMEOUT_MS / 1_000) * 1_000;
+    const attempts = optionValue(argv, '--attempts', DEFAULT_ATTEMPTS);
+    const pauseMs = optionValue(argv, '--recheck-pause', DEFAULT_RECHECK_PAUSE_MS / 1_000) * 1_000;
+    console.log(`CANARY ${JSON.stringify({
+        node: process.version,
+        undici: process.versions.undici,
+        platform: process.platform,
+        arch: process.arch,
+        timeoutMs,
+        attempts,
+        concurrency: MAX_CONCURRENCY,
+    })}`);
+    // Many carriers share a front door (every universal one uses the same
+    // provider page), so each URL is probed once and reported for all of them.
+    const targets = automaticCanaryTargets();
+    const carriersByUrl = new Map();
+    for (const target of targets)
+        carriersByUrl.set(target.url, [...carriersByUrl.get(target.url) ?? [], target.carrierId]);
+    const options = {
+        timeoutMs,
+        attempts,
+        onAttempt: (target, result) => {
+            console.log(`ATTEMPT ${target.carrierId} ${new URL(target.url).hostname} ${JSON.stringify(result)}`);
+        },
+    };
+    const results = await recheckUnanswered(await runCanaries(targets.filter((target) => carriersByUrl.get(target.url)[0] === target.carrierId), options), { ...options, pauseMs });
+    const failures = [];
+    for (const result of results) {
+        const carriers = carriersByUrl.get(result.target.url).join(',');
+        const hostname = new URL(result.target.url).hostname;
+        const outcome = result.status !== null ? `HTTP ${result.status}` : result.error ?? 'unreachable';
+        console.log(`${canaryHealthy(result) ? 'PASS' : 'FAIL'} ${carriers} ${hostname} ${outcome}`);
+        if (!canaryHealthy(result))
+            failures.push({ result: 'failed', check: `${carriers} (${hostname})`, reason: outcome });
+    }
+    const healthy = results.length - failures.length;
+    const totals = `${healthy}/${results.length} canary URLs reachable for ${targets.length} automatic carriers`;
+    console.log(totals);
+    writeCanaryReport({ title: 'Public carrier reachability', totals, rows: failures });
+    return healthy === results.length ? 0 : 1;
+}
+const executable = process.argv[1] ? pathToFileURL(process.argv[1]).href : '';
+if (import.meta.url === executable) {
+    process.exitCode = await carrierCanaryMain();
+}

package/dist/server/index.d.ts

@@ -0,0 +1,20 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type Tracker, type TrackerOptions } from '../facade/index.js';
+export interface TrackingServerOptions extends TrackerOptions {
+    token?: string;
+    demoPage?: boolean;
+    tracker?: Tracker;
+    rateLimit?: number;
+    cacheMs?: number;
+    maxConcurrent?: number;
+    /** Receives route names and status only; input and error objects never enter logs. */
+    log?: (record: {
+        method: string;
+        route: string;
+        status: number;
+        durationMs: number;
+    }) => void;
+    now?: () => number;
+}
+/** Shared, bounded memory only: no accounts, parcel store, scheduler or database. */
+export declare function createTrackingServer(options?: TrackingServerOptions): import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;