universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/ctt/adapter.js

@@ -0,0 +1,320 @@
+import { IndeterminateError, MaintenanceError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { isValidS10TrackingNumber } from '../../core/detection/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean, decodeText, escapeRegExp, fetchBounded, parseJsonBytes, UpstreamHttpError, } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyCttStatus } from './status.js';
+// Protocol provenance:
+// - Prior art (full session mechanics + vocabulary, verified step by step
+//   below, MIT): https://github.com/ha-parcel-integrations/ha-ctt (api.py,
+//   parcels.py, tests).
+// - CTT's tracker is an OutSystems Reactive app, so there is ceremony: the
+//   endpoint answers 403 Invalid Login to a cookie-less request while setting
+//   the nr2Users session cookie on that same response (the 403 is the
+//   bootstrap, not an error); every data action then needs the cookie plus an
+//   X-CSRFToken derived from it, plus moduleVersion/apiVersion tokens that CTT
+//   rotates on every frontend deploy (derived at runtime from keyless version
+//   endpoints and the screen bundle — never pinned). A browser User-Agent is
+//   mandatory (Cloudflare error 1010 otherwise).
+// - Live verification 2026-09-10, including a delivered parcel whose whole
+//   history mapped: Found:true carries ObjectEventsFromQuery; Found:false is
+//   BOTH genuine unknown and backend outage, told apart only via the sibling
+//   DataActionCheckIPLocked call (made solely on Found:false — a found parcel
+//   already proves health).
+// - StateId is the stable integer key (never the Portuguese State text); the
+//   map lives in status.ts.
+const BASE_URL = 'https://appserver.ctt.pt';
+const SCREEN_PATH = '/CustomerArea/screenservices/CustomerArea/CustomerArea/PublicArea_Detail';
+const VIEW_NAME = 'CustomerArea.PublicArea_Detail';
+const TRACK_ACTION = 'DataActionGetObjectEventsByInputObjectCode';
+const MAINTENANCE_ACTION = 'DataActionCheckIPLocked';
+const MODULE_VERSION_URL = `${BASE_URL}/CustomerArea/moduleservices/moduleversioninfo`;
+const SCREEN_SCRIPT_PATH = '/CustomerArea/scripts/CustomerArea.CustomerArea.PublicArea_Detail.mvc.js';
+const BROWSER_USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 2_000_000;
+const MAX_SCRIPT_BYTES = 2_000_000;
+const MAX_EVENTS_TO_RETURN = 20;
+/** A CTT maintenance window: the backend is up but refuses to answer lookups. */
+export class CttMaintenanceError extends MaintenanceError {
+    constructor() {
+        super('CTT', 'CTT tracking is temporarily unavailable');
+        this.name = 'CttMaintenanceError';
+    }
+}
+/** The OutSystems ceremony broke down (session, version tokens, body shape). */
+export class CttApiError extends IndeterminateError {
+    constructor(detail) {
+        super('CTT', `CTT tracking request failed: ${detail}`);
+        this.name = 'CttApiError';
+    }
+}
+export function normalizeCttTrackingNumber(raw) {
+    // Mirrors number detection: checksum-valid S10 PT. Anything else stays with
+    // the generic postal fallback — those routes were never sampled here.
+    const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!/^[A-Z]{2}\d{9}PT$/.test(value) || !isValidS10TrackingNumber(value)) {
+        throw new TypeError('CTT tracking requires a valid 13-character S10 number ending in PT');
+    }
+    return value;
+}
+export function cttTrackingUrl(rawTrackingNumber) {
+    // Legacy objectSearch page: the address users recognise, stable across
+    // appserver host changes, and the one CTT itself links from its site.
+    const url = new URL('https://www.ctt.pt/feapl_2/app/open/objectSearch/objectSearch.jspx');
+    url.searchParams.set('objects', normalizeCttTrackingNumber(rawTrackingNumber));
+    return url.toString();
+}
+function sessionFromSetCookie(response) {
+    const getSetCookie = typeof response.headers.getSetCookie === 'function'
+        ? response.headers.getSetCookie.bind(response.headers)
+        : null;
+    const rawCookies = getSetCookie ? getSetCookie() : [];
+    const header = rawCookies.find((value) => value.startsWith('nr2Users='))
+        ?? response.headers.get('set-cookie') ?? '';
+    const value = /^nr2Users=([^;]*)/.exec(header)?.[1] ?? '';
+    if (!value)
+        return null;
+    // Decoded shape: crf=<TOKEN>;uid=0;unm= — the crf field is the CSRF token.
+    const csrfToken = /crf=([^;]+)/.exec(decodeURIComponent(value))?.[1] ?? '';
+    if (!csrfToken)
+        return null;
+    return { cookie: `nr2Users=${value}`, csrfToken };
+}
+export function parseCttTrackingResponse(payload, trackingNumber) {
+    const requested = normalizeCttTrackingNumber(trackingNumber);
+    if (!isRecord(payload))
+        throw new SchemaError('CTT', 'CTT returned an invalid tracking response');
+    const data = isRecord(payload.data) ? payload.data : null;
+    if (!data)
+        throw new SchemaError('CTT', 'CTT returned an invalid tracking response');
+    const record = data.ObjectEventsFromQuery;
+    if (!isRecord(record))
+        throw new SchemaError('CTT', 'CTT returned an invalid tracking response');
+    const returned = clean(record.ObjectCode, 64).toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!returned)
+        throw new SchemaError('CTT', 'CTT did not return a shipment identifier');
+    if (returned !== requested)
+        throw new SchemaError('CTT', 'CTT returned a different shipment');
+    const rawEvents = record.Events;
+    const eventsList = isRecord(rawEvents) && Array.isArray(rawEvents.List) ? rawEvents.List : null;
+    if (eventsList === null)
+        throw new SchemaError('CTT', 'CTT returned invalid tracking history');
+    const parsed = [];
+    const seen = new Set();
+    eventsList.filter(isRecord).slice(0, 500).forEach((rawEvent, index) => {
+        const stateId = typeof rawEvent.StateId === 'number' ? rawEvent.StateId : Number.NaN;
+        const description = clean(rawEvent.Event, 500) || clean(rawEvent.State, 200);
+        // Observed event datetimes carry explicit offsets; require them rather than
+        // stamping a zone onto a cross-border lane.
+        const time = explicitOffsetTime(rawEvent.DateTime);
+        if (!time || !description)
+            return;
+        const identity = `${time.iso}\u0000${description}\u0000${Number.isSafeInteger(stateId) ? stateId : ''}`;
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        const classified = classifyCttStatus(stateId);
+        parsed.push({
+            // Local mixes depot codes and point names (operational locations, kept
+            // coarse). Sender/recipient identity, contact and address blocks travel
+            // on the record but are deliberately never retained.
+            // An unmapped state keeps no stage: the sync classifies the wording and
+            // records where the stage came from instead of assuming movement here.
+            event: {
+                time: time.iso,
+                location: clean(rawEvent.Local, 160),
+                description,
+                ...(classified ? { stage: classified.stage } : {}),
+                ...(Number.isSafeInteger(stateId) ? { provider_code: String(stateId) } : {}),
+            },
+            classified: classified ?? undefined,
+            timestamp: time.timestamp,
+            index,
+        });
+    });
+    parsed.sort((left, right) => right.timestamp - left.timestamp || left.index - right.index);
+    const events = parsed.slice(0, MAX_EVENTS_TO_RETURN).map(({ event }) => event);
+    const latest = parsed.find((item) => item.classified);
+    if (!latest) {
+        return {
+            status: 'unknown',
+            last_status_text: events[0]?.description ?? 'Tracking information received',
+            last_update: events[0]?.time ?? null,
+            expected_delivery: null,
+            events,
+        };
+    }
+    return {
+        status: latest.classified.status,
+        current_stage: latest.classified.stage,
+        last_status_text: latest.event.description,
+        last_update: latest.event.time ?? null,
+        expected_delivery: null,
+        events,
+    };
+}
+export class CttTracker {
+    timeoutMs;
+    fetcher;
+    moduleVersion = null;
+    apiVersions = new Map();
+    screenScript = null;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetcher = options.fetcher;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new TypeError('CTT timeout must be positive');
+        }
+    }
+    async fetch(rawTrackingNumber) {
+        const trackingNumber = normalizeCttTrackingNumber(rawTrackingNumber);
+        const payload = await this.callAction(TRACK_ACTION, {
+            ObjectCodeInput: trackingNumber,
+            SearchInput: trackingNumber,
+            IsFromPublicArea: true,
+            IPClient: '',
+        }, null, true, true);
+        const record = isRecord(payload.data) ? payload.data.ObjectEventsFromQuery : undefined;
+        if (!isRecord(record) || !record.Found) {
+            // Found:false is both genuine unknown and backend outage: a found parcel
+            // already proves health, so the sibling check runs solely on negatives.
+            if (await this.isMaintenance())
+                throw new CttMaintenanceError();
+            throw new NotFoundError('CTT');
+        }
+        return parseCttTrackingResponse(payload, trackingNumber);
+    }
+    async isMaintenance() {
+        const payload = await this.callAction(MAINTENANCE_ACTION, {}, null, true, true);
+        const data = isRecord(payload.data) ? payload.data : {};
+        return data.IsMaintenance === true;
+    }
+    async callAction(action, variables, session, retrySession, retryVersion) {
+        const apiVersion = await this.ensureApiVersion(action);
+        const headers = {
+            Accept: 'application/json',
+            'Content-Type': 'application/json; charset=UTF-8',
+            'User-Agent': BROWSER_USER_AGENT,
+        };
+        if (session) {
+            headers.Cookie = session.cookie;
+            headers['X-CSRFToken'] = session.csrfToken;
+        }
+        const { response, bytes } = await fetchBounded(`${BASE_URL}${SCREEN_PATH}/${action}`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                versionInfo: { moduleVersion: this.moduleVersion, apiVersion },
+                viewName: VIEW_NAME,
+                screenData: { variables },
+            }),
+        }, {
+            provider: 'CTT tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            retryTransient: true,
+            allowHttpError: true,
+            fetcher: this.fetcher,
+        });
+        if (response.status === 403) {
+            const bootstrapped = sessionFromSetCookie(response);
+            if (retrySession && bootstrapped) {
+                return this.callAction(action, variables, bootstrapped, false, retryVersion);
+            }
+            throw new CttApiError('anonymous session bootstrap failed');
+        }
+        if (!response.ok)
+            throw new UpstreamHttpError('CTT tracking', response.status);
+        const payload = parseJsonBytes(bytes, 'CTT tracking');
+        if (!isRecord(payload))
+            throw new CttApiError('unexpected body (not a JSON object)');
+        const versionInfo = isRecord(payload.versionInfo) ? payload.versionInfo : {};
+        if ((versionInfo.hasModuleVersionChanged === true || versionInfo.hasApiVersionChanged === true) && retryVersion) {
+            this.moduleVersion = null;
+            this.screenScript = null;
+            this.apiVersions.delete(action);
+            return this.callAction(action, variables, session, retrySession, false);
+        }
+        return payload;
+    }
+    async ensureApiVersion(action) {
+        const cached = this.apiVersions.get(action);
+        if (cached !== undefined)
+            return cached;
+        await this.ensureModuleVersion();
+        const script = await this.ensureScreenScript();
+        const version = new RegExp(`callDataAction\\("${escapeRegExp(action)}",\\s*"[^"]*",\\s*"([^"]+)"`).exec(script)?.[1];
+        if (!version)
+            throw new CttApiError(`could not derive apiVersion for ${action}`);
+        this.apiVersions.set(action, version);
+        return version;
+    }
+    async ensureModuleVersion() {
+        if (this.moduleVersion !== null)
+            return;
+        const { response, bytes } = await fetchBounded(MODULE_VERSION_URL, {
+            headers: { Accept: 'application/json', 'User-Agent': BROWSER_USER_AGENT },
+        }, {
+            provider: 'CTT tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            retryTransient: true,
+            allowHttpError: true,
+            fetcher: this.fetcher,
+        });
+        if (!response.ok)
+            throw new UpstreamHttpError('CTT tracking', response.status);
+        const payload = parseJsonBytes(bytes, 'CTT tracking');
+        const token = isRecord(payload) && typeof payload.versionToken === 'string' ? payload.versionToken : '';
+        if (!token)
+            throw new CttApiError('moduleversioninfo returned no versionToken');
+        this.moduleVersion = token;
+    }
+    async ensureScreenScript() {
+        if (this.screenScript !== null)
+            return this.screenScript;
+        // The version token carries +/= characters: it must travel percent-encoded
+        // or the manifest endpoint answers an unrelated shape.
+        const manifestUrl = `${BASE_URL}/CustomerArea/moduleservices/moduleinfo?${encodeURIComponent(this.moduleVersion ?? '')}`;
+        const manifest = await this.fetchJson(manifestUrl);
+        const versions = isRecord(manifest) && isRecord(manifest.manifest) && isRecord(manifest.manifest.urlVersions)
+            ? manifest.manifest.urlVersions
+            : {};
+        const scriptToken = versions[SCREEN_SCRIPT_PATH];
+        if (typeof scriptToken !== 'string' || !scriptToken) {
+            throw new CttApiError("module manifest missing the screen script's version token");
+        }
+        const script = decodeText((await this.fetchBytes(`${BASE_URL}${SCREEN_SCRIPT_PATH}?${scriptToken}`)).bytes);
+        this.screenScript = script;
+        return script;
+    }
+    async fetchJson(url) {
+        return parseJsonBytes((await this.fetchBytes(url)).bytes, 'CTT tracking');
+    }
+    async fetchBytes(url) {
+        const { response, bytes } = await fetchBounded(url, {
+            headers: { Accept: 'application/json, text/plain, */*', 'User-Agent': BROWSER_USER_AGENT },
+        }, {
+            provider: 'CTT tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_SCRIPT_BYTES,
+            retryTransient: true,
+            allowHttpError: true,
+            fetcher: this.fetcher,
+        });
+        if (!response.ok)
+            throw new UpstreamHttpError('CTT tracking', response.status);
+        return { bytes };
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new CttTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'ctt',
+        // The OutSystems session bootstrap and the version-token refresh are part
+        // of the direct call, not separate tiers: they never change the transport.
+        steps: ['direct'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};

package/dist/carriers/ctt/carrier.json

@@ -0,0 +1,72 @@
+{
+  "id": "ctt",
+  "displayName": "CTT Portugal",
+  "aliases": [
+    "CTT Correios de Portugal",
+    "Correios de Portugal"
+  ],
+  "region": {
+    "countries": [
+      "PT"
+    ]
+  },
+  "brand": {
+    "color": "#df0024"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "ctt",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://www.ctt.pt/feapl_2/app/open/objectSearch/objectSearch.jspx?objects={trackingNumber}",
+    "canaryUrl": "https://www.ctt.pt/",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "sender_name",
+      "recipient_name",
+      "recipient_address"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "provider_code"
+    ],
+    "discarded": [
+      "sender_name",
+      "recipient_name",
+      "recipient_address"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "ctt.pt"
+      ],
+      "params": [
+        "objects"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "ctt-1",
+      "pattern": "^[A-Z]{2}\\d{9}PT$",
+      "confidence": "high",
+      "checksum": "s10"
+    }
+  ]
+}

package/dist/carriers/ctt/numbers.json

@@ -0,0 +1,33 @@
+{
+  "carrier": "ctt",
+  "records": [
+    {
+      "number": "LA136353435PT",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://portaldaqueixa.com/brands/ctt/complaints/ctt-atraso-na-entrega-377-163329926",
+        "date": "2026-09-28"
+      },
+      "expect": {
+        "carrier": "ctt",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "RL402552798PT",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.altroconsumo.it/reclamare/bacheca-dei-reclami/ritardo-consegna-raccomandata/f9bc9dea8c8224161d",
+        "date": "2025-11-03"
+      },
+      "expect": {
+        "carrier": "ctt",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    }
+  ]
+}

package/dist/carriers/ctt/status.d.ts

@@ -0,0 +1,16 @@
+/**
+ * CTT Portugal status vocabulary.
+ *
+ * `StateId` is the stable integer key of an event; the Portuguese `State` text
+ * next to it is display prose and is never mapped. The vocabulary is explicitly
+ * still being observed, so an unmapped id yields no stage at all: the sync then
+ * classifies the raw wording and records where the stage came from, rather than
+ * this map inventing movement.
+ *
+ * Provenance: derived from the prior-art client
+ * https://github.com/ha-parcel-integrations/ha-ctt (MIT) and confirmed live on
+ * 2026-09-10 against a delivered parcel whose whole history mapped.
+ */
+import type { ClassifiedStatus } from '../../core/status/index.js';
+/** The stage and status for a CTT `StateId`, or undefined when the id is not mapped. */
+export declare function classifyCttStatus(stateId: unknown): ClassifiedStatus | undefined;

package/dist/carriers/ctt/status.js

@@ -0,0 +1,16 @@
+const EVENT_STATUS = {
+    1: { status: 'pending', stage: 'registered' },
+    2: { status: 'in_transit', stage: 'in_transit' },
+    5: { status: 'exception', stage: 'returned' },
+    7: { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    8: { status: 'in_transit', stage: 'in_transit' },
+    10: { status: 'in_transit', stage: 'in_transit' },
+    11: { status: 'in_transit', stage: 'in_transit' },
+    12: { status: 'delivered', stage: 'delivered' },
+    13: { status: 'exception', stage: 'failed_attempt' },
+    14: { status: 'out_for_delivery', stage: 'ready_for_pickup' },
+};
+/** The stage and status for a CTT `StateId`, or undefined when the id is not mapped. */
+export function classifyCttStatus(stateId) {
+    return typeof stateId === 'number' && Number.isSafeInteger(stateId) ? EVENT_STATUS[stateId] : undefined;
+}

package/dist/carriers/ctt/statuses.json

@@ -0,0 +1,15 @@
+{
+  "carrier": "ctt",
+  "entries": [
+    { "code": "1", "language": "pt", "stage": "registered", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "Shipment announced, not yet accepted." },
+    { "code": "2", "language": "pt", "wording": "Aceite", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-09-10", "note": "Accepted; seen on the delivered parcel checked live." },
+    { "code": "5", "language": "pt", "stage": "returned", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "7", "language": "pt", "stage": "out_for_delivery", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "8", "language": "pt", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "10", "language": "pt", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "11", "language": "pt", "wording": "Em trânsito", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "12", "language": "pt", "wording": "Entregue", "stage": "delivered", "confirmedBy": "live", "firstSeen": "2026-09-10", "note": "Delivered; seen on the delivered parcel checked live." },
+    { "code": "13", "language": "pt", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "14", "language": "pt", "stage": "ready_for_pickup", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" }
+  ]
+}

package/dist/carriers/ctt-express/adapter.d.ts

@@ -0,0 +1,11 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class CttExpressTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/ctt-express/adapter.js

@@ -0,0 +1,41 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { IndeterminateError, SchemaError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { normalizeCttExpressNumber, parseCttExpress } from './parser.js';
+const ENDPOINT = 'https://wct.cttexpress.com/p_track_redis_v2.php';
+export class CttExpressTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    fetch(raw, context = {}) {
+        const number = normalizeCttExpressNumber(raw);
+        return runSteps({ carrier: 'ctt-express', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    signal.throwIfAborted();
+                    const url = new URL(ENDPOINT);
+                    url.searchParams.set('sc', number);
+                    const { response, bytes } = await fetchBounded(url, { signal, headers: { Accept: 'application/json',
+                            Origin: 'https://shipping-tracking.production.cloud2.cttexpress.com',
+                        } }, { provider: 'CTT Express', timeoutMs: Math.max(1, Math.floor(remainingMs)), maxBytes: 1_000_000,
+                        allowHttpStatuses: [404, 410], fetcher: this.options.fetcher });
+                    if (response.status !== 200)
+                        throw new IndeterminateError('CTT Express', 'CTT Express tracking endpoint is unavailable');
+                    let payload;
+                    try {
+                        payload = parseJsonBytes(bytes, 'CTT Express');
+                    }
+                    catch (cause) {
+                        throw new SchemaError('CTT Express', 'CTT Express returned invalid tracking JSON', { cause });
+                    }
+                    return parseCttExpress(payload, number);
+                } }]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new CttExpressTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'ctt-express', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeCttExpressNumber(number))) };
+};

package/dist/carriers/ctt-express/carrier.json

@@ -0,0 +1,64 @@
+{
+  "id": "ctt-express",
+  "displayName": "CTT Express",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "ES",
+      "PT"
+    ]
+  },
+  "brand": {
+    "color": "#df0024"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "ctt-express",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 35
+    },
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "eta"
+  ],
+  "portal": {
+    "url": "https://shipping-tracking.production.cloud2.cttexpress.com/?sc={trackingNumber}",
+    "canaryUrl": "https://shipping-tracking.production.cloud2.cttexpress.com/",
+    "shows": [
+      "status",
+      "history",
+      "estimated_delivery"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "estimated_delivery"
+    ],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "shipping-tracking.production.cloud2.cttexpress.com"
+      ],
+      "params": [
+        "sc"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "ctt-express-1",
+      "pattern": "^00\\d{20}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/ctt-express/numbers.json

@@ -0,0 +1,59 @@
+{
+  "carrier": "ctt-express",
+  "records": [
+    {
+      "number": "0082800011298638008391",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ocu.org/reclamar/lista-reclamaciones-publicas/reclamaci-C3-B3n-por-p-C3-A9rdida-de-mer/da714ccf4d8f261583",
+        "date": "2024-08-12"
+      },
+      "expect": {
+        "carrier": "ctt-express",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "0082800082809771393048",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ocu.org/reclamar/empresas/ctt-express/3C8C0C39-1EAE90226"
+      },
+      "expect": {
+        "carrier": "ctt-express",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "0082800082809771598159",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ocu.org/reclamar/empresas/ctt-express/3C8C0C39-1EAE90226"
+      },
+      "expect": {
+        "carrier": "ctt-express",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "0082900082909841703487",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6ab578d8357bf7e8557625dc",
+        "date": "2026-09-24"
+      },
+      "expect": {
+        "carrier": "ctt-express",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    }
+  ]
+}

package/dist/carriers/ctt-express/parser.d.ts

@@ -0,0 +1,3 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeCttExpressNumber(raw: string): string;
+export declare function parseCttExpress(payload: unknown, number: string): CarrierResult;