universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/c-chez-vous/carrier.json

@@ -0,0 +1,69 @@
+{
+  "id": "c-chez-vous",
+  "displayName": "C Chez Vous",
+  "aliases": [
+    "CChezVous"
+  ],
+  "region": {
+    "countries": [
+      "FR"
+    ]
+  },
+  "brand": {
+    "color": "#e50046"
+  },
+  "selectable": true,
+  "timezone": "Europe/Paris",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "c-chez-vous",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "eta"
+  ],
+  "portal": {
+    "url": "https://www.cchezvous.fr/suivi-colis/{trackingNumber}",
+    "canaryUrl": "https://www.cchezvous.fr/suivi-colis",
+    "shows": [
+      "status",
+      "eta",
+      "eta_window",
+      "sender_name",
+      "recipient_name",
+      "recipient_address",
+      "recipient_contact",
+      "order_contents"
+    ],
+    "scraped": [
+      "status",
+      "eta"
+    ],
+    "discarded": [
+      "eta_window",
+      "sender_name",
+      "recipient_name",
+      "recipient_address",
+      "recipient_contact",
+      "order_contents"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "cchezvous.fr"
+      ],
+      "path": "^/suivi-colis/([^/?#]+)/?$"
+    }
+  ],
+  "detection": [
+    {
+      "id": "c-chez-vous-1",
+      "pattern": "^[A-Z]{4}\\d{2}[A-Z0-9]{4}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/c-chez-vous/numbers.json

@@ -0,0 +1,31 @@
+{
+  "carrier": "c-chez-vous",
+  "records": [
+    {
+      "number": "4TZKO156790--59600",
+      "role": "composite",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://www.cchezvous.fr/suivi-colis"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none"
+      },
+      "note": "Official documentation example, not a real shipment. Agency and shipment numbers as printed on the label. The source attributes it to C Chez Vous; no rule matches this shape."
+    },
+    {
+      "number": "FGRC45BKLM",
+      "role": "composite",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://www.cchezvous.fr/suivi-colis"
+      },
+      "expect": {
+        "carrier": "c-chez-vous",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment. Agency and shipment numbers as printed on the label."
+    }
+  ]
+}

package/dist/carriers/c-chez-vous/status.d.ts

@@ -0,0 +1,27 @@
+/**
+ * C Chez Vous order steps.
+ *
+ * The tracking page is a five-step progress bar, and the JSON it embeds reports
+ * that step per parcel as `parcelStep`. There is no wording and no scan
+ * history: the step is the whole status vocabulary, and the French descriptions
+ * below are the ones the page prints beside each step.
+ *
+ * A value outside 1–5 is a step this map does not know. It is reported as
+ * `UNKNOWN_STEP` rather than clamped to a documented step, so the sync
+ * classifies it and records it for review instead of us claiming an order has
+ * not started.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../generated/catalog.js';
+export interface StepDetails {
+    status: CarrierStatus;
+    stage: Stage;
+    description: string;
+}
+/** Sorts below every documented step, so an unknown parcel makes the order unknown. */
+export declare const UNKNOWN_STEP = 0;
+export declare const UNKNOWN_STEP_DESCRIPTION = "Suivi C Chez Vous";
+export declare const STEP_DETAILS: Record<number, StepDetails>;
+/** The documented step of one parcel, or `UNKNOWN_STEP` when it is not one of the five. */
+export declare function parcelStep(value: unknown): number;
+export declare function stepDetails(step: number): StepDetails | null;

package/dist/carriers/c-chez-vous/status.js

@@ -0,0 +1,19 @@
+/** Sorts below every documented step, so an unknown parcel makes the order unknown. */
+export const UNKNOWN_STEP = 0;
+export const UNKNOWN_STEP_DESCRIPTION = 'Suivi C Chez Vous';
+export const STEP_DETAILS = {
+    1: { status: 'pending', stage: 'registered', description: 'Commande enregistrée' },
+    2: { status: 'pending', stage: 'registered', description: 'Prise de rendez-vous' },
+    3: { status: 'in_transit', stage: 'in_transit', description: 'Commande en préparation' },
+    4: { status: 'out_for_delivery', stage: 'out_for_delivery', description: 'Commande en livraison' },
+    5: { status: 'delivered', stage: 'delivered', description: 'Commande livrée' },
+};
+/** The documented step of one parcel, or `UNKNOWN_STEP` when it is not one of the five. */
+export function parcelStep(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 5
+        ? value
+        : UNKNOWN_STEP;
+}
+export function stepDetails(step) {
+    return STEP_DETAILS[step] ?? null;
+}

package/dist/carriers/c-chez-vous/statuses.json

@@ -0,0 +1,10 @@
+{
+  "carrier": "c-chez-vous",
+  "entries": [
+    { "code": "1", "wording": "Commande enregistrée", "language": "fr", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "First step of the page's progress bar." },
+    { "code": "2", "wording": "Prise de rendez-vous", "language": "fr", "stage": "registered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "The appointment is being booked; nothing has shipped yet." },
+    { "code": "3", "wording": "Commande en préparation", "language": "fr", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "4", "wording": "Commande en livraison", "language": "fr", "stage": "out_for_delivery", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "5", "wording": "Commande livrée", "language": "fr", "stage": "delivered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Last step; the delivery estimate is dropped once it is reached." }
+  ]
+}

package/dist/carriers/canada-post/adapter.d.ts

@@ -0,0 +1,40 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export { normalizeCanadaPostNumber, parseCanadaPostTrackingResponse } from './parser.js';
+export declare function canadaPostTrackingUrl(trackingNumber: string): string;
+export interface CanadaPostTrackerOptions {
+    timeoutMs?: number;
+    fetcher?: typeof fetch;
+    recorder?: StepRecorder;
+}
+export declare class CanadaPostTracker {
+    #private;
+    readonly timeoutMs: number;
+    constructor(options?: number | CanadaPostTrackerOptions);
+    fetch(rawTrackingNumber: string, context?: TrackingContext): Promise<{
+        tracking_url: string;
+        tracking_source: string;
+        canonical_tracking_number?: string;
+        status?: import("../../index.js").CarrierStatus;
+        current_stage?: string;
+        last_status_text?: string | null;
+        last_update?: string | null;
+        expected_delivery?: string | null;
+        expected_delivery_from?: string | null;
+        sender_name?: string | null;
+        receiver_name?: string | null;
+        pickup_point?: string | null;
+        delivered_at?: string | null;
+        weight_kg?: number | null;
+        dimensions_text?: string | null;
+        delivery_carrier?: string;
+        destination_country?: string;
+        destination_country_name?: string;
+        delivery_tracking_number?: string;
+        international_tracking_number?: string;
+        timezone?: string;
+        summary_only?: boolean;
+        events?: import("../../index.js").CarrierEvent[];
+    }>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/canada-post/adapter.js

@@ -0,0 +1,78 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { BudgetExceededError, SchemaError, TransportError, UpstreamHttpError } 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 { canadaPostLookupKind, normalizeCanadaPostNumber, parseCanadaPostTrackingResponse, resolveCanadaPostPin } from './parser.js';
+export { normalizeCanadaPostNumber, parseCanadaPostTrackingResponse } from './parser.js';
+const API_BASE = 'https://www.canadapost-postescanada.ca/track-reperage/rs/track/json/package';
+const DEFAULT_TIMEOUT_MS = 15_000;
+export function canadaPostTrackingUrl(trackingNumber) {
+    const url = new URL('https://www.canadapost-postescanada.ca/track-reperage/en/search');
+    url.searchParams.set('searchFor', normalizeCanadaPostNumber(trackingNumber));
+    return url.toString();
+}
+export class CanadaPostTracker {
+    timeoutMs;
+    #options;
+    constructor(options = {}) {
+        this.#options = typeof options === 'number' ? { timeoutMs: options } : options;
+        this.timeoutMs = this.#options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0)
+            throw new TypeError('Canada Post timeout must be positive');
+    }
+    async fetch(rawTrackingNumber, context = {}) {
+        const number = normalizeCanadaPostNumber(rawTrackingNumber);
+        const budgetMs = context.budgetMs ?? this.timeoutMs;
+        return runSteps({ carrier: 'canada-post', budgetMs, signal: context.signal,
+            recorder: this.#options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    const deadline = performance.now() + remainingMs;
+                    const request = async (url) => {
+                        const requestBudget = deadline - performance.now();
+                        if (requestBudget <= 0)
+                            throw new BudgetExceededError('canada-post', budgetMs);
+                        signal.throwIfAborted();
+                        let bytes;
+                        try {
+                            ({ bytes } = await fetchBounded(url, { signal, headers: {
+                                    Accept: 'application/json, text/plain, */*',
+                                    'Accept-Language': 'en-CA,en;q=0.9',
+                                    // The public tracking application's interceptor sends empty Basic credentials.
+                                    Authorization: 'Basic Og==',
+                                    Referer: 'https://www.canadapost-postescanada.ca/track-reperage/en/home',
+                                    'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+                                    'X-Requested-With': 'XMLHttpRequest',
+                                } }, { provider: 'canada-post', timeoutMs: Math.max(1, Math.floor(requestBudget)),
+                                maxBytes: 1_000_000, fetcher: this.#options.fetcher }));
+                        }
+                        catch (error) {
+                            if (error instanceof UpstreamHttpError && [404, 410].includes(error.status)) {
+                                throw new TransportError('canada-post', 'Canada Post tracking endpoint is unavailable', { cause: error });
+                            }
+                            throw error;
+                        }
+                        try {
+                            return parseJsonBytes(bytes, 'canada-post');
+                        }
+                        catch (cause) {
+                            throw new SchemaError('canada-post', 'Canada Post returned invalid tracking JSON', { cause });
+                        }
+                    };
+                    const kind = canadaPostLookupKind(number);
+                    let pin = number;
+                    if (kind !== 'pin') {
+                        const url = new URL(API_BASE);
+                        url.searchParams.set(kind === 'dnc' ? 'dncs' : 'refNbrs', number);
+                        pin = resolveCanadaPostPin(await request(url), number, kind);
+                    }
+                    const result = parseCanadaPostTrackingResponse(await request(new URL(`${API_BASE}/${encodeURIComponent(pin)}/detail`)), pin);
+                    return { ...result, ...(pin !== number ? { canonical_tracking_number: pin } : {}),
+                        tracking_url: canadaPostTrackingUrl(number), tracking_source: 'structured-web-response' };
+                } }]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new CanadaPostTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'canada-post', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeCanadaPostNumber(number))) };
+};

package/dist/carriers/canada-post/carrier.json

@@ -0,0 +1,77 @@
+{
+  "id": "canada-post",
+  "displayName": "Canada Post",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "CA"
+    ]
+  },
+  "brand": {
+    "color": "#e4002b"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "canada-post",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 15
+    },
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta",
+    "delivered_at"
+  ],
+  "portal": {
+    "url": "https://www.canadapost-postescanada.ca/track-reperage/en/search?searchFor={trackingNumber}",
+    "canaryUrl": "https://www.canadapost-postescanada.ca/track-reperage/en/home",
+    "shows": [
+      "status",
+      "history",
+      "eta",
+      "location",
+      "delivered_at"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "eta",
+      "location",
+      "delivered_at"
+    ],
+    "discarded": [
+      "service type",
+      "delivery options",
+      "recipient details",
+      "postal addresses",
+      "signatures",
+      "delivery images"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "canadapost-postescanada.ca",
+        "canadapost.ca"
+      ],
+      "params": [
+        "searchFor"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "canada-post-1",
+      "pattern": "^\\d{16}$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/canada-post/numbers.json

@@ -0,0 +1,81 @@
+{
+  "carrier": "canada-post",
+  "records": [
+    {
+      "number": "0073938000549297",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/canadapost.json"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl-ecommerce",
+          "correos-express",
+          "canada-post",
+          "tnt"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Canada Post, which stays one candidate among several."
+    },
+    {
+      "number": "4002847016405018",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/canadapost.json"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl-ecommerce",
+          "correos-express",
+          "canada-post",
+          "tnt"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Canada Post, which stays one candidate among several."
+    },
+    {
+      "number": "7023210039414604",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/karrioapi/karrio/blob/deea10f8568b2d48c71bbcc11ec11c62cdaf2a6a/modules/connectors/canadapost/tests/canadapost/test_tracking.py"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl-ecommerce",
+          "correos-express",
+          "canada-post",
+          "tnt"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Canada Post, which stays one candidate among several."
+    },
+    {
+      "number": "7035114477138472",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/jkeen/tracking_number_data/blob/main/couriers/canadapost.json"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl-ecommerce",
+          "correos-express",
+          "canada-post",
+          "tnt"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Canada Post, which stays one candidate among several."
+    }
+  ]
+}

package/dist/carriers/canada-post/parser.d.ts

@@ -0,0 +1,5 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeCanadaPostNumber(raw: string): string;
+export declare function canadaPostLookupKind(number: string): 'pin' | 'dnc' | 'reference';
+export declare function resolveCanadaPostPin(payload: unknown, requested: string, kind: 'dnc' | 'reference'): string;
+export declare function parseCanadaPostTrackingResponse(payload: unknown, trackingNumber: string): CarrierResult;

package/dist/carriers/canada-post/parser.js

@@ -0,0 +1,202 @@
+import { DateTime } from 'luxon';
+import { isValidS10TrackingNumber } from '../../core/detection/s10.js';
+import { IndeterminateError, SchemaError } from '../../core/errors/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { canadaPostPackageStage, canadaPostScanStage, canadaPostStage, statusForStage } from './status.js';
+export function normalizeCanadaPostNumber(raw) {
+    const value = raw.toUpperCase().replace(/[\s.-]/g, '');
+    if (!/^\d{11,24}$/.test(value) && !(value.endsWith('CA') && isValidS10TrackingNumber(value))) {
+        throw new TypeError('Canada Post requires a parcel PIN, numeric reference or valid Canadian postal tracking number');
+    }
+    return value;
+}
+export function canadaPostLookupKind(number) {
+    if (/^(?:\d{11,12}|\d{16}|[A-Z]{2}\d{9}CA)$/.test(number))
+        return 'pin';
+    return /^\d{15}$/.test(number) ? 'dnc' : 'reference';
+}
+function sameNumber(value, requested) {
+    return typeof value === 'string' && value.trim().toUpperCase() === requested;
+}
+function checkError(item) {
+    if (!Object.hasOwn(item, 'error'))
+        return;
+    if (!isRecord(item.error) || typeof item.error.cd !== 'string' || !item.error.cd.trim())
+        throw new SchemaError('canada-post');
+    // The same 004 envelope is used for unknown and expired public parcels.
+    // It cannot distinguish a new reference from history that has been removed.
+    throw new IndeterminateError('canada-post', 'Canada Post returned no usable parcel history');
+}
+export function resolveCanadaPostPin(payload, requested, kind) {
+    if (!Array.isArray(payload) || payload.length > 100 || !payload.every(isRecord))
+        throw new SchemaError('canada-post', 'Canada Post returned invalid alias results');
+    if (!payload.length || payload.length > 1)
+        throw new IndeterminateError('canada-post', 'Canada Post did not resolve one parcel for this reference');
+    const item = payload[0];
+    const bound = kind === 'dnc' ? sameNumber(item.dnc, requested)
+        : sameNumber(item.refNbr1, requested) || sameNumber(item.refNbr2, requested);
+    if (!bound)
+        throw new SchemaError('canada-post', 'Canada Post returned another reference');
+    checkError(item);
+    if (typeof item.pin !== 'string')
+        throw new SchemaError('canada-post', 'Canada Post omitted the parcel PIN');
+    let pin;
+    try {
+        pin = normalizeCanadaPostNumber(item.pin.trim());
+    }
+    catch (cause) {
+        throw new SchemaError('canada-post', 'Canada Post returned an invalid parcel PIN', { cause });
+    }
+    // Returned identities may trim/case-fold, but never gain stripped separators.
+    if (!sameNumber(item.pin, pin) || canadaPostLookupKind(pin) !== 'pin')
+        throw new SchemaError('canada-post', 'Canada Post returned an invalid parcel PIN');
+    return pin;
+}
+function textField(item, key, limit) {
+    if (item[key] != null && typeof item[key] !== 'string')
+        throw new SchemaError('canada-post', 'Canada Post returned an invalid text field');
+    return clean(item[key], limit);
+}
+function calendarDate(value) {
+    if (value != null && typeof value !== 'string')
+        throw new SchemaError('canada-post', 'Canada Post returned an invalid date field');
+    const raw = clean(value, 64);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(raw))
+        return null;
+    const parsed = DateTime.fromISO(raw, { zone: 'UTC' });
+    return parsed.isValid ? parsed.toISODate() : null;
+}
+function eventClock(value) {
+    if (value == null)
+        return {};
+    if (!isRecord(value))
+        throw new SchemaError('canada-post', 'Canada Post returned an invalid scan clock');
+    const date = textField(value, 'date', 32);
+    const time = textField(value, 'time', 32);
+    const offset = textField(value, 'zoneOffset', 16);
+    const raw = [date, time, offset].filter(Boolean).join(' ');
+    if (/^\d{4}-\d{2}-\d{2}$/.test(date) && /^(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/.test(time)) {
+        const local = `${date}T${time.length === 5 ? `${time}:00` : time}`;
+        if (/^(?:Z|[+-](?:(?:0\d|1[0-3]):[0-5]\d|14:00))$/i.test(offset)) {
+            const parsed = explicitOffsetTime(`${local}${offset}`);
+            if (parsed)
+                return { time: parsed.iso };
+        }
+        else if (!offset) {
+            // UTC validates the calendar only; no timezone is attached to local digits.
+            const parsed = DateTime.fromISO(local, { zone: 'UTC' });
+            const valid = parsed.isValid ? parsed.toISO({ includeOffset: false, suppressMilliseconds: true }) : null;
+            if (valid)
+                return { local_time: valid };
+        }
+    }
+    return raw ? { provider_time_text: raw } : {};
+}
+function returnStarted(text) {
+    if (/\b(?:will|may|might|would)\b.*\breturn(?:ed)?\b/i.test(text))
+        return false;
+    return /\b(?:being returned|returning|en\s?route|in transit)\b.*\bsender\b|\breturned to (?:the )?sender\b/i.test(text);
+}
+export function parseCanadaPostTrackingResponse(payload, trackingNumber) {
+    const number = normalizeCanadaPostNumber(trackingNumber);
+    if (!isRecord(payload) || !sameNumber(payload.pin, number))
+        throw new SchemaError('canada-post', 'Canada Post returned another parcel or an invalid detail response');
+    checkError(payload);
+    const summary = textField(payload, 'status', 64);
+    for (const flag of ['returnedToSender', 'returnPinIndicator', 'delivered']) {
+        if (payload[flag] != null && typeof payload[flag] !== 'boolean')
+            throw new SchemaError('canada-post', 'Canada Post returned an invalid parcel flag');
+    }
+    if (!Array.isArray(payload.events) || payload.events.length > 500)
+        throw new SchemaError('canada-post', 'Canada Post returned invalid parcel history');
+    if (!payload.events.length)
+        throw new IndeterminateError('canada-post', 'Canada Post returned empty parcel history');
+    const rows = payload.events.map(raw => {
+        if (!isRecord(raw))
+            throw new SchemaError('canada-post', 'Canada Post returned an invalid scan');
+        const code = textField(raw, 'cd', 40);
+        const description = textField(raw, 'descEn', 500);
+        const type = textField(raw, 'type', 64);
+        if (!code || !/^[A-Za-z0-9_-]+$/.test(code) || !description)
+            throw new SchemaError('canada-post', 'Canada Post returned an incomplete scan');
+        if (raw.locationAddr != null && !isRecord(raw.locationAddr))
+            throw new SchemaError('canada-post', 'Canada Post returned an invalid scan location');
+        const location = isRecord(raw.locationAddr)
+            ? [textField(raw.locationAddr, 'city', 160), textField(raw.locationAddr, 'regionCd', 40)].filter(Boolean).join(', ') : '';
+        const stage = type === 'Signature' || code === '20' ? null : canadaPostScanStage(code) ?? canadaPostStage(description);
+        const event = { ...eventClock(raw.datetime), description: stage === 'delivered' ? 'Delivered' : description,
+            provider_code: code, ...(stage ? { stage } : {}), ...(location ? { location } : {}) };
+        return { event, type, sourceDate: isRecord(raw.datetime) ? calendarDate(raw.datetime.date) : null,
+            returnCue: returnStarted(description) || type === 'RtsLabelProc' };
+    });
+    // Native detail history is newest first. Compare instants only when every
+    // row resolves; an unresolved latest row must not fall behind old scans.
+    if (rows.every(row => row.event.time))
+        rows.sort((a, b) => Date.parse(b.event.time) - Date.parse(a.event.time));
+    let returning = false;
+    for (const row of [...rows].reverse()) {
+        if (row.returnCue)
+            returning = true;
+        if (returning) {
+            row.event.provider_leg = 'return';
+            if (row.event.stage === 'delivered') {
+                row.event.stage = 'returned';
+                row.event.description = 'Returned to sender';
+            }
+        }
+    }
+    const latest = rows[0];
+    const explicitReturn = latest.event.provider_leg === 'return';
+    const currentReturn = explicitReturn || payload.returnedToSender === true;
+    const summaryStage = canadaPostPackageStage(summary);
+    const delivery = rows.find(row => row.event.stage === (currentReturn ? 'returned' : 'delivered'));
+    const matchingDelivery = delivery?.event.time && latest.event.time === delivery.event.time
+        && (latest === delivery || latest.type === 'Signature') ? delivery : undefined;
+    let current = latest.event.stage ?? summaryStage;
+    let snapshot = null;
+    if (currentReturn && !explicitReturn) {
+        // A summary flag can announce a return before a return scan exists. Its
+        // timing cannot relabel an old outbound delivery as sender completion.
+        current = 'exception';
+        snapshot = 'return';
+    }
+    else if (summaryStage === 'delivered' && !currentReturn) {
+        current = 'delivered';
+        snapshot = matchingDelivery ? null : 'delivery';
+    }
+    else if (currentReturn && !latest.event.stage) {
+        current = matchingDelivery ? 'returned' : summaryStage === 'delivered' ? null : summaryStage;
+    }
+    const seen = new Set();
+    const events = rows.map(row => row.event).filter(event => {
+        const key = JSON.stringify(event);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    if (snapshot === 'delivery')
+        events.unshift({ description: 'Delivered', stage: 'delivered', summary_snapshot: true });
+    if (snapshot === 'return')
+        events.unshift({ description: 'Return to sender', stage: 'exception', provider_leg: 'return', summary_snapshot: true });
+    const estimate = payload.expectedDlvryDateTime;
+    if (estimate != null && !isRecord(estimate))
+        throw new SchemaError('canada-post', 'Canada Post returned an invalid delivery estimate');
+    const revised = isRecord(estimate) ? calendarDate(estimate.revisedDate) : null;
+    const standard = isRecord(estimate) ? calendarDate(estimate.dlvryDate) : null;
+    const actualDay = calendarDate(payload.actualDlvryDate);
+    const actualEventDay = delivery?.event.time?.slice(0, 10);
+    const deliveredAt = current === 'delivered' && matchingDelivery && (!actualDay || actualDay === actualEventDay) ? matchingDelivery.event.time : null;
+    const candidate = isRecord(estimate) && clean(estimate.revisedDate, 64) ? revised : standard;
+    const expected = !currentReturn && current !== 'delivered' && current !== 'returned' && current !== 'exception' && current !== 'failed_attempt'
+        && summary !== 'FullProgressAlert' && summary !== 'InTransitAlert' && canadaPostScanStage(latest.event.provider_code)
+        && candidate && latest.sourceDate && candidate >= latest.sourceDate ? candidate : null;
+    return { status: current ? statusForStage(current) : 'unknown', ...(current ? { current_stage: current } : {}),
+        last_status_text: snapshot === 'return' ? 'Return to sender' : current === 'delivered' ? 'Delivered'
+            : current === 'returned' ? 'Returned to sender' : latest.event.description,
+        last_update: snapshot ? null : latest.event.time ?? null,
+        ...(!snapshot && latest.event.local_time ? { last_update_local: latest.event.local_time } : {}),
+        expected_delivery: expected, ...(deliveredAt ? { delivered_at: deliveredAt } : {}), events: events.slice(0, 100) };
+}

package/dist/carriers/canada-post/status.d.ts

@@ -0,0 +1,9 @@
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../core/status/index.js';
+/** The official client's package enum and English translations. */
+export declare const CANADA_POST_STATUS_STAGE: Readonly<Record<string, Stage>>;
+export declare function canadaPostPackageStage(code: string): Stage | null;
+export declare function canadaPostScanStage(code: string): Stage | null;
+export declare function canadaPostStage(text: string): Stage | null;
+export declare function statusForStage(stage: Stage): CarrierStatus;
+export declare function canadaPostStatus(code: string, text: string): CarrierStatus;