universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/providers/postal-ninja/adapter.js

@@ -0,0 +1,200 @@
+/**
+ * Postal Ninja (postal.ninja), an opt-in universal aggregator.
+ *
+ * Transport: TRAWL verifies through the embedded widget on `/en/tools`, then
+ * opens the normal results page for its verified handle and captures the full
+ * `/track/get` response. Local Chromium without TRAWL retains compact widget
+ * capture. The main entry form has a separate verification gate.
+ * The provider is disabled by default;
+ * `TRACKING_ENABLE_POSTAL_NINJA=true` puts it in the chain before 17TRACK.
+ */
+import { DateTime } from 'luxon';
+import { ChallengeError, NoHistoryError, SchemaError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { scrapeUniversalPage } from '../../core/transport/browser.js';
+import { isRecord } from '../../core/types.js';
+import { capturedBodies, captureFailure, loadCapture } from '../shared/capture.js';
+import { event, eventStage, hasPrivateDeliveryDetails, isNotice, numberOf, result, text } from '../shared/result.js';
+const SOURCE = 'Postal Ninja';
+const GET_API = 'https://postal.ninja/track/get';
+const CHECK_API = 'https://postal.ninja/track/check';
+const MAX_EVENTS = 1000;
+/** The states whose history the provider considers established. */
+const TRACKED_STATES = ['TRACKING', 'FINISHED', 'STOPPED', 'ARCHIVED'];
+function isMatchingResultPage(page, number) {
+    return page.capturedResponses.some((entry) => {
+        if (entry.url !== GET_API || entry.status !== 200 || !entry.body || entry.truncated || entry.base64Encoded)
+            return false;
+        let payload;
+        try {
+            payload = JSON.parse(entry.body);
+        }
+        catch {
+            return false;
+        }
+        return isRecord(payload) && payload.status === 'FOUND' && isRecord(payload.track)
+            && payload.track.tc === number && payload.track.hid === payload.hid
+            && typeof payload.hid === 'string' && /^[A-Za-z0-9_-]{1,100}$/.test(payload.hid)
+            && page.url === `https://postal.ninja/en/track#/${payload.hid}`;
+    });
+}
+export function parsePostalNinjaResponse(payload, trackingNumber) {
+    const number = numberOf(trackingNumber);
+    if (!isRecord(payload) || payload.status !== 'FOUND' || !isRecord(payload.track)
+        || payload.track.tc !== number || payload.track.hid !== payload.hid
+        || typeof payload.hid !== 'string' || !payload.hid
+        || !TRACKED_STATES.includes(String(payload.track.state))) {
+        throw new SchemaError(SOURCE, 'Postal Ninja has no matching shipment history');
+    }
+    // The embedded widget requests compact:true, which supplies only the first
+    // and latest scan. Full /track/get responses instead carry events[].
+    const rawEvents = payload.track.events === undefined
+        ? [payload.track.firstEv, payload.track.lastEv].filter((value) => value != null)
+        : payload.track.events;
+    if (!Array.isArray(rawEvents) || rawEvents.length > MAX_EVENTS)
+        throw new SchemaError(SOURCE, 'Postal Ninja returned invalid events');
+    const events = [];
+    // Postal Ninja supplies events oldest first. Its dt values are local wall
+    // times without a zone, even when multiple countries are involved. Preserve
+    // them as local_time, but never invent UTC scans or use the destination zone
+    // for the whole journey. Explicit offsets, when present, can be persisted.
+    for (const raw of [...rawEvents].reverse()) {
+        if (!isRecord(raw))
+            throw new SchemaError(SOURCE, 'Postal Ninja returned an invalid event');
+        const description = text(raw.dsc);
+        if (!description || isNotice(description))
+            continue;
+        if (typeof raw.dt !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?/.test(raw.dt)
+            || !DateTime.fromISO(raw.dt, { zone: 'UTC' }).isValid)
+            throw new SchemaError(SOURCE, 'Postal Ninja returned an invalid event date');
+        if (/(?:Z|[+-]\d{2}:\d{2})$/.test(raw.dt)) {
+            const parsed = event(raw.dt, description);
+            if (parsed)
+                events.push(parsed);
+        }
+        else {
+            const stage = eventStage(description) ?? 'pending';
+            if (stage !== 'delivered' && hasPrivateDeliveryDetails(description))
+                continue;
+            events.push({ local_time: raw.dt, description: stage === 'delivered' ? 'Delivered' : description, stage });
+        }
+    }
+    return result(events, SOURCE, true);
+}
+export class PostalNinjaTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(trackingNumber, budgetMs) {
+        const number = numberOf(trackingNumber);
+        const timeoutMs = budgetMs ?? this.options.timeoutMs ?? 45_000;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 60_000)
+            throw new TypeError('Postal Ninja timeout must be between 1 and 60000 ms');
+        let handle;
+        const responseError = (payload) => {
+            if (!isRecord(payload))
+                return;
+            if (payload.tc === number && payload.status === 'PROCESSING' && typeof payload.hid === 'string' && payload.hid) {
+                handle = payload.hid;
+            }
+            if (payload.status === 'CHLNG_REQ' && (payload.tc === number || (handle && payload.hid === handle))) {
+                return new ChallengeError(SOURCE, 'Postal Ninja browser verification did not complete');
+            }
+            if (payload.status === 'UNTRACEABLE' && payload.tc === number) {
+                return new NoHistoryError(SOURCE, 'Postal Ninja cannot track this number');
+            }
+            if (payload.status === 'FOUND' && isRecord(payload.track) && payload.track.tc === number
+                && typeof payload.hid === 'string' && payload.hid && payload.track.hid === payload.hid
+                && payload.track.state === 'NO_INFO' && !payload.inProgress) {
+                return new NoHistoryError(SOURCE, 'Postal Ninja has no available tracking history');
+            }
+        };
+        return runSteps({ carrier: SOURCE, budgetMs: timeoutMs, recorder: this.options.recorder }, [{
+                id: 'trawl', enabled: Boolean(this.options.trawl),
+                run: async ({ remainingMs }) => {
+                    const spec = {
+                        source: SOURCE, url: `https://postal.ninja/en/tools#trawl-number=${number}`,
+                        apiUrl: GET_API, additionalApiUrls: [CHECK_API], budgetMs: remainingMs, fetcher: this.options.fetcher,
+                        acceptResultPage: (page) => isMatchingResultPage(page, number),
+                    };
+                    const page = await loadCapture(this.options.trawl ?? null, spec);
+                    // Learn the submission's handle before interpreting a handle-only
+                    // retrieval challenge. Read history newest first to skip polling.
+                    let submissionError;
+                    for (const body of [...capturedBodies(page, { ...spec, apiUrl: CHECK_API })].reverse()) {
+                        let payload;
+                        try {
+                            payload = JSON.parse(body);
+                        }
+                        catch {
+                            continue;
+                        }
+                        submissionError = responseError(payload) ?? submissionError;
+                    }
+                    let pending;
+                    for (const body of capturedBodies(page, spec)) {
+                        let payload;
+                        try {
+                            payload = JSON.parse(body);
+                        }
+                        catch {
+                            continue;
+                        }
+                        const error = responseError(payload);
+                        if (error)
+                            throw error;
+                        // The compact widget response establishes the parcel's handle. A
+                        // TRAWL success must include the normal page's full history; otherwise
+                        // fallback providers should get a chance to return the missing scans.
+                        if (isRecord(payload) && isRecord(payload.track) && !Array.isArray(payload.track.events))
+                            continue;
+                        try {
+                            return parsePostalNinjaResponse(payload, number);
+                        }
+                        catch (error) {
+                            if (error instanceof SchemaError)
+                                pending ??= error;
+                            else
+                                throw error;
+                        }
+                    }
+                    throw submissionError ?? pending ?? captureFailure(page, spec);
+                },
+            }, {
+                id: 'browser',
+                // A failed TRAWL attempt proceeds to the next universal provider. Do
+                // not spend another browser budget on the known-unreliable Chromium path.
+                enabled: !this.options.trawl,
+                run: ({ remainingMs }) => scrapeUniversalPage({ executablePath: this.options.executablePath, timeoutMs: Math.max(1, Math.floor(remainingMs)) }, {
+                    name: SOURCE, url: 'https://postal.ninja/en/tools', responseUrl: 'https://postal.ninja/track/get',
+                    responseErrors: {
+                        'https://postal.ninja/track/check': responseError,
+                        'https://postal.ninja/track/get': responseError,
+                    },
+                    submit: async (page) => {
+                        // The official embedded widget uses an automatic browser check. The
+                        // main tracking page can instead require an interactive challenge.
+                        const form = page.frameLocator('iframe[title="Package tracking widget"]').locator('form.tracker');
+                        await form.locator('input[type="text"]').fill(number);
+                        const save = form.locator('input[type="checkbox"]');
+                        if (await save.count())
+                            await save.uncheck();
+                        await form.locator('button[type="submit"]').click();
+                    },
+                }, (payload) => parsePostalNinjaResponse(payload, number)),
+            }]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new PostalNinjaTracker({
+        trawl: environment.trawl, fetcher: environment.fetcher,
+        executablePath: environment.browserExecutablePath ?? undefined,
+        recorder: environment.recorder,
+    });
+    return {
+        id: SOURCE,
+        steps: [environment.trawl ? 'trawl' : 'browser'],
+        track: (input, context) => tracker.fetch(input.number, context?.budgetMs),
+    };
+};

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

@@ -0,0 +1,50 @@
+/**
+ * 17TRACK (t.17track.net), a universal aggregator with richer China Post history.
+ *
+ * Transport: the browser service loads the public tracking page and captures
+ * the page's own `restapi` response; unsigned direct probes answer HTTP 200
+ * with a rejection code instead of history (verified 2026-09-10). The parser
+ * keeps only history whose shipment number equals the requested one, and turns
+ * the provider's own rejection codes into typed errors so routing can tell a
+ * verification wall from an outage.
+ */
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import { ChallengeError, NoHistoryError, TransportError } from '../../core/errors/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import type { StepRecorder } from '../../core/telemetry/index.js';
+import type { TrawlClient } from '../../core/transport/index.js';
+/** The provider answered, but its lookup did not produce history for this shipment. */
+export declare class SeventeenTrackLookupError extends TransportError {
+    readonly reason: 'lookup_unavailable' | 'lookup_pending';
+    readonly providerCode: number;
+    readonly providerMessage?: string | undefined;
+    constructor(reason: 'lookup_unavailable' | 'lookup_pending', providerCode: number, providerMessage?: string | undefined);
+}
+/** A matching code-400/null-shipment reply supplies no history, not a network failure or a proven invalid number. */
+export declare class SeventeenTrackNoHistoryError extends NoHistoryError {
+    readonly reason = "no_history";
+    readonly providerCode = 400;
+    constructor();
+}
+/** The provider asked for an interactive verification the unattended lookup cannot pass. */
+export declare class SeventeenTrackVerificationError extends ChallengeError {
+    readonly providerCode: number;
+    readonly providerMessage?: string | undefined;
+    readonly reason = "verification_required";
+    constructor(providerCode: number, providerMessage?: string | undefined);
+}
+/** Structured replies without usable history; polling may still produce a later success. */
+export declare function isSeventeenTrackLookupError(error: unknown): error is SeventeenTrackLookupError | SeventeenTrackNoHistoryError | SeventeenTrackVerificationError;
+export declare function parse17TrackResponse(payload: unknown, trackingNumber: string): CarrierResult;
+export interface SeventeenTrackOptions {
+    trawl?: TrawlClient | null;
+    fetcher?: typeof fetch;
+    recorder?: StepRecorder;
+    timeoutMs?: number;
+}
+export declare class SeventeenTrackTracker {
+    readonly options: SeventeenTrackOptions;
+    constructor(options?: SeventeenTrackOptions);
+    fetch(trackingNumber: string, budgetMs?: number): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/providers/seventeentrack/adapter.js

@@ -0,0 +1,165 @@
+import { ChallengeError, NoHistoryError, NotFoundError, SchemaError, TransportError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { isRecord } from '../../core/types.js';
+import { universalCarrierHints } from '../shared/hints.js';
+import { capturedBodies, captureFailure, loadCapture } from '../shared/capture.js';
+import { numberOf, result, text } from '../shared/result.js';
+import { seventeenTrackEvent } from './events.js';
+const SOURCE = '17TRACK';
+const API_URL = 'https://t.17track.net/track/restapi';
+/** Codes the provider returns when it wants an interactive verification. */
+const VERIFICATION_CODES = [-11, -13, -14];
+const MAX_PROVIDERS = 20;
+const MAX_EVENTS = 1000;
+/** The provider answered, but its lookup did not produce history for this shipment. */
+export class SeventeenTrackLookupError extends TransportError {
+    reason;
+    providerCode;
+    providerMessage;
+    constructor(reason, providerCode, providerMessage) {
+        super(SOURCE, describeLookup(reason, providerCode, providerMessage));
+        this.reason = reason;
+        this.providerCode = providerCode;
+        this.providerMessage = providerMessage;
+        this.name = 'SeventeenTrackLookupError';
+    }
+}
+/** A matching code-400/null-shipment reply supplies no history, not a network failure or a proven invalid number. */
+export class SeventeenTrackNoHistoryError extends NoHistoryError {
+    reason = 'no_history';
+    providerCode = 400;
+    constructor() {
+        super(SOURCE, describeLookup('no_history', 400));
+        this.name = 'SeventeenTrackNoHistoryError';
+    }
+}
+/** The provider asked for an interactive verification the unattended lookup cannot pass. */
+export class SeventeenTrackVerificationError extends ChallengeError {
+    providerCode;
+    providerMessage;
+    reason = 'verification_required';
+    constructor(providerCode, providerMessage) {
+        super(SOURCE, describeLookup('verification_required', providerCode, providerMessage));
+        this.providerCode = providerCode;
+        this.providerMessage = providerMessage;
+        this.name = 'SeventeenTrackVerificationError';
+    }
+}
+function describeLookup(reason, providerCode, providerMessage) {
+    return `${SOURCE}: ${reason} (code ${providerCode}${providerMessage ? `: ${providerMessage}` : ''})`;
+}
+/** Structured replies without usable history; polling may still produce a later success. */
+export function isSeventeenTrackLookupError(error) {
+    return error instanceof SeventeenTrackLookupError || error instanceof SeventeenTrackNoHistoryError || error instanceof SeventeenTrackVerificationError;
+}
+function lookupError(code, providerMessage) {
+    return VERIFICATION_CODES.includes(code)
+        ? new SeventeenTrackVerificationError(code, providerMessage)
+        : new SeventeenTrackLookupError('lookup_unavailable', code, providerMessage);
+}
+export function parse17TrackResponse(payload, trackingNumber) {
+    const number = numberOf(trackingNumber);
+    if (!isRecord(payload) || !isRecord(payload.meta) || !Number.isInteger(payload.meta.code)) {
+        throw new SchemaError(SOURCE, '17TRACK lookup unavailable');
+    }
+    if (payload.meta.code !== 200) {
+        const code = Number(payload.meta.code);
+        // Keep the provider's short reason (e.g. for the intermittent code 400) visible in Sentry.
+        const message = typeof payload.meta.message === 'string' ? text(payload.meta.message).slice(0, 120) : undefined;
+        throw lookupError(code, message);
+    }
+    if (!Array.isArray(payload.shipments))
+        throw new SchemaError(SOURCE, '17TRACK lookup unavailable');
+    const matches = payload.shipments.filter((s) => isRecord(s) && s.number === number);
+    if (matches.length === 1 && isRecord(matches[0]) && Number.isInteger(matches[0].code) && matches[0].code !== 200) {
+        // A shipment-level code is the lookup's own progress, never a verification wall.
+        const code = Number(matches[0].code);
+        // Observed repeatedly for valid references whose other providers have history.
+        // Scope this to the matching shipment; envelope errors and unknown shapes remain failures.
+        if (code === 400 && matches[0].shipment === null)
+            throw new SeventeenTrackNoHistoryError();
+        throw new SeventeenTrackLookupError(code === 100 ? 'lookup_pending' : 'lookup_unavailable', code);
+    }
+    if (matches.length !== 1 || !isRecord(matches[0]) || matches[0].code !== 200 || !isRecord(matches[0].shipment)) {
+        throw new SchemaError(SOURCE, '17TRACK has no matching shipment history');
+    }
+    const shipment = matches[0].shipment;
+    const tracking = shipment.tracking;
+    if (!isRecord(tracking) || !Array.isArray(tracking.providers) || tracking.providers.length > MAX_PROVIDERS) {
+        throw new SchemaError(SOURCE, '17TRACK returned invalid providers');
+    }
+    const events = [];
+    let count = 0;
+    let undated = 0;
+    for (const provider of tracking.providers) {
+        if (!isRecord(provider) || !Array.isArray(provider.events))
+            throw new SchemaError(SOURCE, '17TRACK returned invalid provider history');
+        const reported = isRecord(provider.provider) ? provider.provider : {};
+        const name = universalCarrierHints([reported.name]).reported_carriers[0];
+        const operator = { ...(name ? { reporting_carrier: name } : {}),
+            ...(typeof reported.key === 'number' && Number.isSafeInteger(reported.key) ? { reporting_carrier_key: reported.key } : {}) };
+        for (const raw of provider.events) {
+            if (++count > MAX_EVENTS || !isRecord(raw))
+                throw new SchemaError(SOURCE, '17TRACK returned invalid events');
+            if (raw.time_utc == null && raw.time_iso == null)
+                undated++;
+            let parsed;
+            try {
+                parsed = seventeenTrackEvent(raw, operator);
+            }
+            catch (cause) {
+                throw new SchemaError(SOURCE, '17TRACK returned an invalid tracking event', { cause });
+            }
+            if (parsed)
+                events.push(parsed);
+        }
+    }
+    if (count === 0 && isRecord(shipment.latest_status) && shipment.latest_status.status === 'NotFound') {
+        throw new NotFoundError(SOURCE);
+    }
+    return { ...result(events, SOURCE), ...(undated ? { undated_event_count: undated } : {}),
+        ...universalCarrierHints(tracking.providers.map((provider) => isRecord(provider) && isRecord(provider.provider) ? provider.provider.name : undefined), number) };
+}
+export class SeventeenTrackTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(trackingNumber, budgetMs = this.options.timeoutMs ?? 30_000) {
+        const number = numberOf(trackingNumber);
+        const spec = (remainingMs) => ({
+            source: SOURCE, url: `https://t.17track.net/en#nums=${number}`, apiUrl: API_URL,
+            budgetMs: remainingMs, fetcher: this.options.fetcher,
+        });
+        return runSteps({ carrier: SOURCE, budgetMs, recorder: this.options.recorder }, [{
+                id: 'trawl',
+                run: async ({ remainingMs }) => {
+                    const capture = spec(remainingMs);
+                    const page = await loadCapture(this.options.trawl ?? null, capture);
+                    let pending;
+                    for (const body of capturedBodies(page, capture)) {
+                        try {
+                            return parse17TrackResponse(JSON.parse(body), number);
+                        }
+                        catch (error) {
+                            // Continue past polling replies and unrelated/demo numbers, but retain
+                            // the latest structured failure if no matching history follows.
+                            if (isSeventeenTrackLookupError(error) || error instanceof NotFoundError || error instanceof SchemaError)
+                                pending ??= error;
+                        }
+                    }
+                    throw pending ?? captureFailure(page, capture);
+                },
+            }]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new SeventeenTrackTracker({
+        trawl: environment.trawl, fetcher: environment.fetcher, recorder: environment.recorder,
+    });
+    return {
+        id: SOURCE,
+        steps: ['trawl'],
+        track: (input, context) => tracker.fetch(input.number, context?.budgetMs),
+    };
+};

package/dist/providers/seventeentrack/events.d.ts

@@ -0,0 +1,4 @@
+import type { CarrierEvent } from '../../core/result/index.js';
+import { type JsonObject } from '../../core/types.js';
+/** Keep scan codes/operator and the origin of 17TRACK's converted timestamp. */
+export declare function seventeenTrackEvent(raw: JsonObject, operator: JsonObject): CarrierEvent | null;

package/dist/providers/seventeentrack/events.js

@@ -0,0 +1,56 @@
+import { isRecord } from '../../core/types.js';
+import { event, text } from '../shared/result.js';
+// Official v2 status vocabulary, plus TransportArrived/Departed observed in
+// public China Post histories. Expired describes tracking age, not a scan.
+const SUB_STAGES = {
+    InfoReceived: 'registered',
+    InTransit_PickedUp: 'accepted', InTransit_Other: 'in_transit',
+    InTransit_Departure: 'in_transit', InTransit_Arrival: 'in_transit',
+    InTransit_TransportArrived: 'in_transit', InTransit_TransportDeparted: 'in_transit',
+    InTransit_CustomsProcessing: 'customs', InTransit_CustomsReleased: 'in_transit',
+    InTransit_CustomsRequiringInformation: 'customs',
+    AvailableForPickup_Other: 'ready_for_pickup', OutForDelivery_Other: 'out_for_delivery',
+    DeliveryFailure_Other: 'failed_attempt', DeliveryFailure_NoBody: 'failed_attempt',
+    DeliveryFailure_Security: 'failed_attempt', DeliveryFailure_Rejected: 'failed_attempt',
+    DeliveryFailure_InvalidAddress: 'failed_attempt', Delivered_Other: 'delivered',
+    Exception_Other: 'exception', Exception_Returning: 'exception', Exception_Returned: 'returned',
+    Exception_NoBody: 'exception', Exception_Security: 'exception', Exception_Damage: 'exception',
+    Exception_Rejected: 'exception', Exception_Delayed: 'exception', Exception_Lost: 'exception',
+    Exception_Destroyed: 'exception', Exception_Cancel: 'exception',
+};
+/** Keep scan codes/operator and the origin of 17TRACK's converted timestamp. */
+export function seventeenTrackEvent(raw, operator) {
+    // Some completed responses contain undated explanatory rows alongside real
+    // scans. Skip only absent dates; malformed nonempty timestamps still fail.
+    const time = raw.time_utc ?? raw.time_iso;
+    if (time === null || time === undefined)
+        return null;
+    const code = text(raw.sub_status);
+    const mapped = Object.hasOwn(SUB_STAGES, code) ? SUB_STAGES[code] : undefined;
+    const parsed = event(time, raw.description, raw.stage ?? (mapped ? code.split('_')[0] : undefined));
+    if (!parsed)
+        return null;
+    // Preserve the shared delivered/negation/handoff safeguards. The specific
+    // code otherwise supplies semantics that Chinese wording cannot provide.
+    const genericTransit = code === 'InTransit_Other' && parsed.stage !== 'pending';
+    if (mapped && !genericTransit && (mapped !== 'delivered' || parsed.stage === 'delivered'))
+        parsed.stage = mapped;
+    // 17TRACK's generic transit bucket loses Swiss Post's delivery-round scan.
+    // Refine only that operator's precise native label; keep its original code.
+    if (code === 'InTransit_Other' && operator.reporting_carrier === 'Swiss Post'
+        && text(raw.description).toLowerCase() === 'loading into delivery vehicle')
+        parsed.stage = 'out_for_delivery';
+    if (parsed.stage === 'delivered')
+        parsed.description = 'Delivered';
+    const timeRaw = isRecord(raw.time_raw) ? raw.time_raw : null;
+    return {
+        ...parsed,
+        ...(code && /^[A-Za-z_]{1,80}$/.test(code) ? { provider_code: code } : {}),
+        ...operator,
+        ...(typeof raw.time_iso === 'string' ? { provider_time_iso: raw.time_iso } : {}),
+        // An inferred offset remains provider-converted time, not independent
+        // evidence that China Post knows the destination's local timezone.
+        time_provenance: timeRaw?.timezone === null ? 'provider_inferred'
+            : typeof timeRaw?.timezone === 'string' ? 'carrier_reported' : 'unspecified',
+    };
+}

package/dist/providers/shared/capture.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The browser capture the two TRAWL-backed providers share.
+ *
+ * ParcelsApp and 17TRACK both render their history from an in-page API call,
+ * so the browser service loads the public tracking page and hands back the
+ * responses it saw for that one API URL. This module performs that call,
+ * yields the readable bodies newest first, and turns the service's own answers
+ * (a redirect, a rejected status, an unreadable body) into the shared error
+ * taxonomy. Parsing stays with each provider.
+ */
+import { IndeterminateError } from '../../core/errors/index.js';
+import type { TrawlClient, TrawlScrapeResponse } from '../../core/transport/index.js';
+import type { UniversalSource } from './result.js';
+export interface CaptureSpec {
+    source: UniversalSource;
+    /** The public tracking page the browser loads. */
+    url: string;
+    /** The in-page API URL whose responses are captured. */
+    apiUrl: string;
+    /** Related protocol replies needed to diagnose submission or polling. */
+    additionalApiUrls?: readonly string[];
+    /** A provider may bind its observed results-page redirect to a captured identity. */
+    acceptResultPage?: (page: TrawlScrapeResponse) => boolean;
+    budgetMs: number;
+    fetcher?: typeof fetch;
+}
+/**
+ * The browser answered, but no shipment history came back with it: the service
+ * captured nothing (`capture_missing`), could not read the body it captured
+ * (`capture_unreadable`), or captured only replies without history
+ * (`history_missing`). None of them prove anything about the shipment.
+ */
+export declare class TrackingCaptureError extends IndeterminateError {
+    readonly reason: 'capture_missing' | 'capture_unreadable' | 'history_missing';
+    constructor(reason: 'capture_missing' | 'capture_unreadable' | 'history_missing', provider?: string);
+}
+/** Load the provider's tracking page in the browser service, capturing its API call. */
+export declare function loadCapture(trawl: TrawlClient | null, spec: CaptureSpec): Promise<TrawlScrapeResponse>;
+/**
+ * The captured bodies for the provider's API, newest first. Lazily generated:
+ * a rejected status only ends the lookup when no newer body parsed first,
+ * which keeps a completed reply usable after an intermediate failure.
+ */
+export declare function capturedBodies(page: TrawlScrapeResponse, spec: CaptureSpec): Generator<string>;
+/** Why a captured page carried no usable history, once every body has been tried. */
+export declare function captureFailure(page: TrawlScrapeResponse, spec: CaptureSpec): TrackingCaptureError;

package/dist/providers/shared/capture.js

@@ -0,0 +1,92 @@
+/**
+ * The browser capture the two TRAWL-backed providers share.
+ *
+ * ParcelsApp and 17TRACK both render their history from an in-page API call,
+ * so the browser service loads the public tracking page and hands back the
+ * responses it saw for that one API URL. This module performs that call,
+ * yields the readable bodies newest first, and turns the service's own answers
+ * (a redirect, a rejected status, an unreadable body) into the shared error
+ * taxonomy. Parsing stays with each provider.
+ */
+import { IndeterminateError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+/** How many responses the browser may have captured before the newest is meaningless. */
+const MAX_CAPTURED = 20;
+/** How long the browser waits for the in-page API call after the page settles. */
+const SETTLE_TIMEOUT_MS = 15_000;
+const MAX_PAGE_BYTES = 10_000_000;
+/**
+ * The browser answered, but no shipment history came back with it: the service
+ * captured nothing (`capture_missing`), could not read the body it captured
+ * (`capture_unreadable`), or captured only replies without history
+ * (`history_missing`). None of them prove anything about the shipment.
+ */
+export class TrackingCaptureError extends IndeterminateError {
+    reason;
+    constructor(reason, provider = 'Tracking browser') {
+        super(provider, `Tracking browser: ${reason}`);
+        this.reason = reason;
+        this.name = 'TrackingCaptureError';
+    }
+}
+function retryAfterMs(headers) {
+    const raw = headers['retry-after'];
+    if (typeof raw !== 'string')
+        return undefined;
+    return /^\d+$/.test(raw) ? Number(raw) * 1000 : Date.parse(raw) - Date.now();
+}
+/** Load the provider's tracking page in the browser service, capturing its API call. */
+export async function loadCapture(trawl, spec) {
+    if (!trawl)
+        throw new TransportError(spec.source, 'Automatic carrier lookup requires the tracking browser service');
+    const budgetMs = Math.max(1, Math.floor(spec.budgetMs));
+    const page = await trawl.scrape({
+        url: spec.url, skipHttp: true, maxTier: 3, maxTimeout: budgetMs,
+        captureResponses: [spec.apiUrl, ...spec.additionalApiUrls ?? []], settleTimeout: SETTLE_TIMEOUT_MS,
+    }, {
+        provider: `${spec.source} tracking browser`, timeoutMs: budgetMs,
+        maxBytes: MAX_PAGE_BYTES, fetcher: spec.fetcher,
+        // A 304 page still carries a fresh captured API reply (observed on
+        // 17TRACK 2026-09-13), so the solved-page gate below allows it: the caller
+        // validates through the captured bodies (identity, demo and polling
+        // rejection) instead of the page status. Without a usable capture the
+        // caller still fails closed with a typed capture error.
+        requireSolved: false,
+    });
+    // Results-page navigation must be bound to a captured identity. Arbitrary
+    // redirects and interstitials are never accepted as this shipment's page.
+    if (page.url !== spec.url && !spec.acceptResultPage?.(page))
+        throw new SchemaError(spec.source, 'Tracking browser returned an incomplete page');
+    // Preserve the solved-tier requirement for capture flows: only a browser
+    // tier (2/3) with a fresh (200) or not-modified (304) page may carry a
+    // usable capture. Anything else stays an unsolved page, as before.
+    if (![2, 3].includes(page.tier) || (page.statusCode !== 200 && page.statusCode !== 304)) {
+        throw new TransportError(spec.source, 'Tracking browser: page unsolved');
+    }
+    return page;
+}
+/**
+ * The captured bodies for the provider's API, newest first. Lazily generated:
+ * a rejected status only ends the lookup when no newer body parsed first,
+ * which keeps a completed reply usable after an intermediate failure.
+ */
+export function* capturedBodies(page, spec) {
+    for (const entry of page.capturedResponses.slice(0, MAX_CAPTURED).reverse()) {
+        if (entry.url !== spec.apiUrl)
+            continue;
+        // Preserve the provider's own status for the router's backoff policy.
+        if (entry.status === 429)
+            throw new UpstreamHttpError(spec.source, 429, retryAfterMs(entry.headers));
+        if (entry.status >= 400)
+            throw new UpstreamHttpError(spec.source, entry.status);
+        if (entry.status !== 200 || entry.truncated || entry.base64Encoded || entry.body === null)
+            continue;
+        yield entry.body;
+    }
+}
+/** Why a captured page carried no usable history, once every body has been tried. */
+export function captureFailure(page, spec) {
+    if (!Array.isArray(page.raw.capturedResponses))
+        return new TrackingCaptureError('capture_missing', spec.source);
+    const unreadable = page.capturedResponses.some((entry) => entry.url === spec.apiUrl && (entry.error || entry.body === null));
+    return new TrackingCaptureError(unreadable ? 'capture_unreadable' : 'history_missing', spec.source);
+}

package/dist/providers/shared/hints.d.ts

@@ -0,0 +1,16 @@
+export { isKnownCarrierName } from '../../core/catalog/hints.js';
+/**
+ * A bare brand ("DPD Group") names several catalog networks; the number can
+ * still pick one. Keep the networks whose detection rules match it, then the
+ * one a preferred rule backs, such as a DPD depot range. Anything else stays
+ * unresolved rather than guessed.
+ */
+export declare function brandCarrierForNumber(name: string, trackingNumber: string): string | undefined;
+/**
+ * Names are hints only. A direct adapter must confirm the shipment before
+ * adoption. The looked-up number resolves a bare brand name.
+ */
+export declare function universalCarrierHints(raw: unknown[], trackingNumber?: string): {
+    reported_carriers: string[];
+    discovered_carrier?: string;
+};