universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/correos-spain/adapter.js

@@ -0,0 +1,191 @@
+import { NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { zonedTime } from '../../core/time/index.js';
+import { clean, fetchBounded, parseJsonBytes, UpstreamHttpError } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyCorreosSpainStatus } from './status.js';
+// Protocol provenance:
+// - Prior art (structure + vocabulary, verified independently below, MIT):
+//   https://github.com/ha-parcel-integrations/ha-correos (api.py, parcels.py,
+//   tests/payloads.py — keyless localizador endpoint, codError envelope,
+//   event shape, Europe/Madrid split timestamps, full status map).
+// - Live verification 2026-09-10: unknown codes answer HTTP 200 with
+//   [0].error.codError "3" (Sin Trazabilidad en Minerva) and eventos:null.
+//   The transport status is always 200; only the envelope decides.
+// - Success shape confirmed against a real ES parcel 2026-08-24 by the
+//   prior-art client (admitted → classified → out-for-delivery → failed
+//   attempt → office hold → collected); the map lives in status.ts.
+const TRACKING_ENDPOINT = 'https://localizador.correos.es/canonico/eventos_envio_servicio';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 1_000_000;
+const MAX_EVENTS_TO_RETURN = 20;
+function parsedTime(dateValue, timeValue) {
+    const date = clean(dateValue, 16);
+    if (!date)
+        return null;
+    // Correos splits timestamps into fecEvento (DD/MM/YYYY) and horEvento
+    // (HH:MM:SS, midnight when absent) in Spanish local time. Mainland Spain is
+    // Europe/Madrid; Canary Islands scans stamped the same way can be off by one
+    // hour — documented here rather than solved, as events carry no locality.
+    return zonedTime(`${date} ${clean(timeValue, 16) || '00:00:00'}`, 'dd/MM/yyyy HH:mm:ss', 'Europe/Madrid', { locale: 'es-ES' });
+}
+export function normalizeCorreosSpainTrackingNumber(raw) {
+    // The localizador accepts any Correos-issued code (S10 ES, PQ domestic,
+    // PR-prefixed); the codError envelope — not the shape — decides unknown.
+    const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!/^[A-Z0-9]{4,40}$/.test(value) || !/\d/.test(value)) {
+        throw new TypeError('Correos tracking requires a tracking code with letters, numbers and a digit');
+    }
+    return value;
+}
+export function correosSpainTrackingUrl(rawTrackingNumber) {
+    const url = new URL('https://www.correos.es/es/es/herramientas/localizador/envios/detalle');
+    url.searchParams.set('tracking-number', normalizeCorreosSpainTrackingNumber(rawTrackingNumber));
+    return url.toString();
+}
+export function parseCorreosSpainTrackingResponse(payload, trackingNumber) {
+    const requested = normalizeCorreosSpainTrackingNumber(trackingNumber);
+    // The endpoint answers a single-element array; bare objects are accepted too
+    // since some error bodies come back unwrapped.
+    const envelope = Array.isArray(payload) ? payload[0] : payload;
+    if (!isRecord(envelope))
+        throw new SchemaError('Correos', 'Correos returned an invalid tracking response');
+    const returned = clean(envelope.codEnvio, 64).toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!returned)
+        throw new SchemaError('Correos', 'Correos did not return a shipment identifier');
+    if (returned !== requested)
+        throw new SchemaError('Correos', 'Correos returned a different shipment');
+    const error = envelope.error;
+    if (!isRecord(error) || error.codError == null) {
+        throw new SchemaError('Correos', 'Correos returned a response without a result envelope');
+    }
+    // Any non-zero codError (e.g. "3" Sin Trazabilidad) means unknown or
+    // not-yet-scanned: a domain outcome, never a transport failure.
+    if (String(error.codError) !== '0')
+        throw new NotFoundError('Correos');
+    const rawEvents = envelope.eventos;
+    if (rawEvents !== undefined && !Array.isArray(rawEvents)) {
+        throw new SchemaError('Correos', 'Correos returned invalid tracking history');
+    }
+    const parsed = [];
+    const seen = new Set();
+    (Array.isArray(rawEvents) ? rawEvents : []).filter(isRecord).slice(0, 500).forEach((rawEvent, index) => {
+        const code = clean(rawEvent.codEvento, 32).toLocaleUpperCase('en-US');
+        // desTextoResumen is the backend's fixed Spanish wording.
+        const description = clean(rawEvent.desTextoResumen, 500) || code;
+        const time = parsedTime(rawEvent.fecEvento, rawEvent.horEvento);
+        if (!time || !description)
+            return;
+        const identity = `${time.iso}\u0000${description}\u0000${code}`;
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        const classified = classifyCorreosSpainStatus(code);
+        parsed.push({
+            // An unmapped code 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: '',
+                description,
+                ...(classified ? { stage: classified.stage } : {}),
+            },
+            classified,
+            timestamp: time.timestamp,
+            index,
+        });
+    });
+    // The localizador lists oldest first; the parcel state is the latest entry.
+    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[0];
+    // Office name (nom_codired), weight (peso grams) and dimensions travel on
+    // the envelope. The office is only a pickup signal when the parcel is
+    // actually awaiting collection; weight/dims are operational parcel data.
+    const office = clean(envelope.nom_codired, 300) || null;
+    const grams = Number(envelope.peso);
+    const weightKg = Number.isFinite(grams) && grams > 0 ? Math.round((grams / 1000) * 1000) / 1000 : null;
+    const dims = [envelope.largo, envelope.ancho, envelope.alto].map((value) => Number(value));
+    const dimensionsText = dims.every((value) => Number.isFinite(value) && value > 0)
+        ? `${dims[0]} x ${dims[1]} x ${dims[2]} cm` : null;
+    // nombre_cliente names a person in the doorstep case, so it is never
+    // projected; weight and dimensions are operational parcel data.
+    const extras = {
+        ...(weightKg != null ? { weight_kg: weightKg } : {}),
+        ...(dimensionsText ? { dimensions_text: dimensionsText } : {}),
+    };
+    const pickupExtras = (stage) => (stage === 'ready_for_pickup' && office ? { pickup_point: office } : {});
+    if (!latest) {
+        return {
+            status: 'unknown',
+            last_status_text: clean(envelope.resumen_ultimo, 500) || 'Tracking information received',
+            last_update: null,
+            expected_delivery: null,
+            ...extras,
+            events,
+        };
+    }
+    if (!latest.classified) {
+        return {
+            status: 'unknown',
+            last_status_text: latest.event.description,
+            last_update: latest.event.time ?? null,
+            expected_delivery: null,
+            ...extras,
+            ...pickupExtras(latest.event.stage),
+            events,
+        };
+    }
+    const deliveredAt = latest.classified.status === 'delivered' ? latest.event.time ?? null : null;
+    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,
+        ...extras,
+        ...pickupExtras(latest.classified.stage),
+        ...(deliveredAt ? { delivered_at: deliveredAt } : {}),
+        events,
+    };
+}
+export class CorreosSpainTracker {
+    timeoutMs;
+    fetcher;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetcher = options.fetcher;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new TypeError('Correos tracking timeout must be positive');
+        }
+    }
+    async fetch(rawTrackingNumber) {
+        const trackingNumber = normalizeCorreosSpainTrackingNumber(rawTrackingNumber);
+        const url = `${TRACKING_ENDPOINT}/${encodeURIComponent(trackingNumber)}`
+            + '?codAplicacion=60&codCanal=3&codIdioma=ES&indUltEvento=N';
+        const { response, bytes } = await fetchBounded(url, {
+            headers: {
+                Accept: 'application/json, text/plain, */*',
+                'Accept-Language': 'en-US,en;q=0.9',
+                'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+            },
+        }, {
+            provider: 'Correos tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            retryTransient: true,
+            allowHttpError: true,
+            fetcher: this.fetcher,
+        });
+        if (!response.ok)
+            throw new UpstreamHttpError('Correos tracking', response.status);
+        return parseCorreosSpainTrackingResponse(parseJsonBytes(bytes, 'Correos tracking'), trackingNumber);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new CorreosSpainTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'correos-spain',
+        steps: ['direct'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};

package/dist/carriers/correos-spain/carrier.json

@@ -0,0 +1,92 @@
+{
+  "id": "correos-spain",
+  "displayName": "Correos",
+  "aliases": [
+    "Correos España",
+    "Correos y Telégrafos",
+    "Sociedad Estatal Correos y Telégrafos"
+  ],
+  "region": {
+    "countries": [
+      "ES"
+    ]
+  },
+  "brand": {
+    "color": "#ffcd00"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "correos-spain",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "pickup_point",
+    "weight",
+    "dimensions",
+    "delivered_at"
+  ],
+  "portal": {
+    "url": "https://www.correos.es/es/es/herramientas/localizador/envios/detalle?tracking-number={trackingNumber}",
+    "canaryUrl": "https://www.correos.es/",
+    "shows": [
+      "status",
+      "history",
+      "recipient_name",
+      "recipient_address",
+      "signature",
+      "weight",
+      "dimensions",
+      "pickup_point"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "weight",
+      "dimensions",
+      "pickup_point",
+      "delivered_at"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address",
+      "signature"
+    ],
+    "unavailable": [
+      "eta",
+      "location"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "correos.es"
+      ],
+      "params": [
+        "tracking-number"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "correos-spain-1",
+      "pattern": "^PR\\d{15}C$",
+      "confidence": "high"
+    },
+    {
+      "id": "correos-spain-2",
+      "pattern": "^[PD][A-Z][A-Z0-9]{4}\\d{16}[A-Z]$",
+      "confidence": "high"
+    },
+    {
+      "id": "correos-spain-3",
+      "pattern": "^[A-Z]{2}\\d{9}ES$",
+      "confidence": "high",
+      "checksum": "s10"
+    }
+  ]
+}

package/dist/carriers/correos-spain/numbers.json

@@ -0,0 +1,149 @@
+{
+  "carrier": "correos-spain",
+  "records": [
+    {
+      "number": "DQ0DK20000034530118220Z",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ocu.org/reclamar/lista-reclamaciones-publicas/devolucion-en-curso-1-mes/d12130a56a293035f0",
+        "date": "2026-03-31"
+      },
+      "expect": {
+        "carrier": "correos-spain",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. A return shipment."
+    },
+    {
+      "number": "LX309102212ES",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ocu.org/reclamar/lista-reclamaciones-publicas/entrega-de-paquete-abierto-y-s/bb3c389c2b30f513a5",
+        "date": "2026-09-18"
+      },
+      "expect": {
+        "carrier": "correos-spain",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. International letter-post item issued by Correos."
+    },
+    {
+      "number": "PHAS9C0419962810128017D",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://es.trustpilot.com/reviews/6a83008bf44f16ad720a6d32",
+        "date": "2026-08-17"
+      },
+      "expect": {
+        "carrier": "correos-spain",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Paq Ligero prefix."
+    },
+    {
+      "number": "PK0DLC0000085800128009G",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ocu.org/reclamar/lista-reclamaciones-publicas/carta-urgente-con-retraso/4085cbb5c6bb1990ab",
+        "date": "2026-09-15"
+      },
+      "expect": {
+        "carrier": "correos-spain",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "PK6R2M0723409010146529C",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ocu.org/reclamar/lista-reclamaciones-publicas/reparto-fallido-y-falsos-inten/fbad5e616abcfdb591",
+        "date": "2025-07-25"
+      },
+      "expect": {
+        "carrier": "correos-spain",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. One of three packages of one order; the three codes differ only in the package digit and the final check letter."
+    },
+    {
+      "number": "PK6R2M0723409020146529K",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ocu.org/reclamar/lista-reclamaciones-publicas/reparto-fallido-y-falsos-inten/fbad5e616abcfdb591",
+        "date": "2025-07-25"
+      },
+      "expect": {
+        "carrier": "correos-spain",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Second package of the same order."
+    },
+    {
+      "number": "PK6R2M0723409030146529E",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ocu.org/reclamar/lista-reclamaciones-publicas/reparto-fallido-y-falsos-inten/fbad5e616abcfdb591",
+        "date": "2025-07-25"
+      },
+      "expect": {
+        "carrier": "correos-spain",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Third package of the same order."
+    },
+    {
+      "number": "PQ0DK20000034530151002K",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ocu.org/reclamar/lista-reclamaciones-publicas/devolucion-en-curso-1-mes/d12130a56a293035f0",
+        "date": "2026-03-31"
+      },
+      "expect": {
+        "carrier": "correos-spain",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. A return shipment."
+    },
+    {
+      "number": "PR110604670130400C",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.htcmania.com/archive/index.php/t-964137.html",
+        "date": "2015-06-02"
+      },
+      "expect": {
+        "carrier": "correos-spain",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "CV000562646ES",
+      "role": "quarantined",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The S10 check digit does not validate. The source attributes it to Correos, which no rule claims."
+    }
+  ]
+}

package/dist/carriers/correos-spain/status.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Correos (Spain) status vocabulary.
+ *
+ * `codEvento` is the stable key of a localizador event; the Spanish
+ * `desTextoResumen` next to it is display prose and is never mapped. The
+ * vocabulary is explicitly still being observed, so an unmapped code yields no
+ * stage at all: the event keeps its raw wording, the result reports `unknown`,
+ * and the sync classifies and records it.
+ *
+ * Provenance: derived from the prior-art client
+ * https://github.com/ha-parcel-integrations/ha-correos (MIT) and confirmed
+ * against a real ES parcel on 2026-08-24 (admitted → classified →
+ * out for delivery → failed attempt → office hold → collected).
+ */
+import type { ClassifiedStatus } from '../../core/status/index.js';
+/** The stage and status for a Correos `codEvento`, or undefined when unmapped. */
+export declare function classifyCorreosSpainStatus(code: string): ClassifiedStatus | undefined;

package/dist/carriers/correos-spain/status.js

@@ -0,0 +1,51 @@
+const EVENT_STATUS = {
+    'A010000V': { status: 'pending', stage: 'registered' },
+    'A090000V': { status: 'pending', stage: 'registered' },
+    'X010000V': { status: 'pending', stage: 'registered' },
+    'P040000V': { status: 'in_transit', stage: 'in_transit' },
+    'P100000V': { status: 'in_transit', stage: 'in_transit' },
+    'P110000V': { status: 'in_transit', stage: 'in_transit' },
+    'P101110V': { status: 'in_transit', stage: 'in_transit' },
+    'P101120V': { status: 'in_transit', stage: 'in_transit' },
+    'P090000V': { status: 'in_transit', stage: 'in_transit' },
+    'G01L010V': { status: 'in_transit', stage: 'in_transit' },
+    'H01I360V': { status: 'in_transit', stage: 'in_transit' },
+    'X020000V': { status: 'in_transit', stage: 'in_transit' },
+    'X040000V': { status: 'in_transit', stage: 'in_transit' },
+    'X060000V': { status: 'in_transit', stage: 'in_transit' },
+    'X070000V': { status: 'in_transit', stage: 'in_transit' },
+    'X110100V': { status: 'in_transit', stage: 'in_transit' },
+    'H020000V': { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    'X080000V': { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    'H01I350V': { status: 'out_for_delivery', stage: 'ready_for_pickup' },
+    'X380000V': { status: 'out_for_delivery', stage: 'ready_for_pickup' },
+    'X390000V': { status: 'out_for_delivery', stage: 'ready_for_pickup' },
+    // Community-integration reconstructions, not yet re-observed: kept, but an
+    // unmapped code elsewhere still reports unknown rather than guessing.
+    'L010000V': { status: 'out_for_delivery', stage: 'ready_for_pickup' },
+    'I01H210V': { status: 'delivered', stage: 'delivered' },
+    'X120000V': { status: 'delivered', stage: 'delivered' },
+    'I010000V': { status: 'delivered', stage: 'delivered' },
+    'H010930R': { status: 'exception', stage: 'failed_attempt' },
+    'H06P010V': { status: 'exception', stage: 'failed_attempt' },
+    'X090100R': { status: 'exception', stage: 'failed_attempt' },
+    'X090060R': { status: 'exception', stage: 'failed_attempt' },
+    'X130000R': { status: 'exception', stage: 'failed_attempt' },
+    'M01E020R': { status: 'exception', stage: 'failed_attempt' },
+    'EOL.9001': { status: 'exception', stage: 'failed_attempt' },
+    'O140000V': { status: 'exception', stage: 'returned' },
+    // Observed live on public parcels in the number corpus.
+    'C010000V': { status: 'in_transit', stage: 'in_transit' },
+    'F010000V': { status: 'in_transit', stage: 'in_transit' },
+    'G200000V': { status: 'in_transit', stage: 'in_transit' },
+    'H250000V': { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    'ADV0000V': { status: 'in_transit', stage: 'accepted' },
+    'H01R390V': { status: 'exception', stage: 'failed_attempt' },
+    'H01R420V': { status: 'exception', stage: 'failed_attempt' },
+    // The pickup window closed: the parcel goes back to the sender.
+    'L03D320R': { status: 'exception', stage: 'returned' },
+};
+/** The stage and status for a Correos `codEvento`, or undefined when unmapped. */
+export function classifyCorreosSpainStatus(code) {
+    return EVENT_STATUS[code];
+}

package/dist/carriers/correos-spain/statuses.json

@@ -0,0 +1,46 @@
+{
+  "carrier": "correos-spain",
+  "entries": [
+    { "code": "A010000V", "language": "es", "stage": "registered", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "A090000V", "wording": "Admitido", "language": "es", "stage": "registered", "confirmedBy": "prior-art", "firstSeen": "2026-08-24", "note": "Seen on the real ES parcel checked by the prior-art client." },
+    { "code": "X010000V", "language": "es", "stage": "registered", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "P040000V", "wording": "Clasificado", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-08-24", "note": "Seen on the real ES parcel checked by the prior-art client." },
+    { "code": "P090000V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "P100000V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "P101110V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "P101120V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "P110000V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "G01L010V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "H01I360V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "X020000V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "X040000V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "X060000V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "X070000V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "X110100V", "language": "es", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "H020000V", "wording": "En reparto", "language": "es", "stage": "out_for_delivery", "confirmedBy": "prior-art", "firstSeen": "2026-08-24", "note": "Seen on the real ES parcel checked by the prior-art client." },
+    { "code": "X080000V", "language": "es", "stage": "out_for_delivery", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "H01I350V", "wording": "En oficina", "language": "es", "stage": "ready_for_pickup", "confirmedBy": "prior-art", "firstSeen": "2026-08-24", "note": "Office hold; the only state where the office name is exposed as a pickup point." },
+    { "code": "X380000V", "language": "es", "stage": "ready_for_pickup", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "X390000V", "language": "es", "stage": "ready_for_pickup", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "L010000V", "language": "es", "stage": "ready_for_pickup", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "Community-integration reconstruction, not re-observed since." },
+    { "code": "I01H210V", "wording": "Entregado", "language": "es", "stage": "delivered", "confirmedBy": "prior-art", "firstSeen": "2026-08-24", "note": "Collected; seen on the real ES parcel checked by the prior-art client." },
+    { "code": "I010000V", "language": "es", "stage": "delivered", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "Community-integration reconstruction, not re-observed since." },
+    { "code": "X120000V", "language": "es", "stage": "delivered", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "Community-integration reconstruction, not re-observed since." },
+    { "code": "H010930R", "language": "es", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-08-24", "note": "Failed delivery attempt." },
+    { "code": "H06P010V", "language": "es", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "X090100R", "language": "es", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "X090060R", "language": "es", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "X130000R", "language": "es", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "M01E020R", "language": "es", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "EOL.9001", "language": "es", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "Carried over from the prior-art map; shape does not match the other Correos codes and has not been re-observed." },
+    { "code": "O140000V", "language": "es", "stage": "returned", "confirmedBy": "prior-art", "firstSeen": "2026-09-10", "note": "" },
+    { "code": "C010000V", "wording": "Salida de oficina de cambio", "language": "es", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-09-26", "note": "Left the origin international exchange office." },
+    { "code": "F010000V", "wording": "Salida de oficina de cambio de destino", "language": "es", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-09-26", "note": "Left the destination international exchange office." },
+    { "code": "G200000V", "wording": "Alta en la unidad de reparto", "language": "es", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-09-26", "note": "Same wording as G01L010V, on an international letter-post item." },
+    { "code": "H250000V", "wording": "En reparto", "language": "es", "stage": "out_for_delivery", "confirmedBy": "live", "firstSeen": "2026-09-26", "note": "Same wording as H020000V, on an international letter-post item." },
+    { "code": "ADV0000V", "wording": "Devolución admitida", "language": "es", "stage": "accepted", "confirmedBy": "live", "firstSeen": "2026-09-26", "note": "First movement of a return shipment's own code, after the pre-registration." },
+    { "code": "H01R390V", "wording": "Realizado intento de entrega", "language": "es", "stage": "failed_attempt", "confirmedBy": "live", "firstSeen": "2026-09-26", "note": "" },
+    { "code": "H01R420V", "wording": "Intento de entrega. Ausente", "language": "es", "stage": "failed_attempt", "confirmedBy": "live", "firstSeen": "2026-09-26", "note": "Recipient absent." },
+    { "code": "L03D320R", "wording": "Finalizado plazo retirada", "language": "es", "stage": "returned", "confirmedBy": "live", "firstSeen": "2026-09-26", "note": "Pickup window closed; the parcel goes back to the sender. Reported as status 'exception', like other carriers' uncollected codes." }
+  ]
+}

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

@@ -0,0 +1,34 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import { IndeterminateError, MaintenanceError } from '../../core/errors/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+/** A CTT maintenance window: the backend is up but refuses to answer lookups. */
+export declare class CttMaintenanceError extends MaintenanceError {
+    constructor();
+}
+/** The OutSystems ceremony broke down (session, version tokens, body shape). */
+export declare class CttApiError extends IndeterminateError {
+    constructor(detail: string);
+}
+export declare function normalizeCttTrackingNumber(raw: string): string;
+export declare function cttTrackingUrl(rawTrackingNumber: string): string;
+export declare function parseCttTrackingResponse(payload: unknown, trackingNumber: string): CarrierResult;
+export declare class CttTracker {
+    readonly timeoutMs: number;
+    readonly fetcher: typeof fetch | undefined;
+    private moduleVersion;
+    private apiVersions;
+    private screenScript;
+    constructor(options?: {
+        timeoutMs?: number;
+        fetcher?: typeof fetch;
+    });
+    fetch(rawTrackingNumber: string): Promise<CarrierResult>;
+    private isMaintenance;
+    private callAction;
+    private ensureApiVersion;
+    private ensureModuleVersion;
+    private ensureScreenScript;
+    private fetchJson;
+    private fetchBytes;
+}
+export declare const adapter: AdapterFactory;