universal-parcel-scraper 0.120.0-main.1067 → 0.121.0-main.1069

package/README.md

@@ -13,7 +13,7 @@ The engine behind [Peek](https://peektracker.com) ([GitHub](https://github.com/p
 [![License: Apache-2.0](https://img.shields.io/badge/core-Apache--2.0-blue.svg)](LICENSE)
 
 <!-- GENERATED:summary -->
-**3,500+ carriers** through **179 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **180 dedicated adapters** and **5 universal fallbacks**
 
 <sub>208 catalog entries · 66 countries represented</sub>
 <!-- /GENERATED:summary -->
@@ -155,7 +155,7 @@ createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', '
 <!-- GENERATED:stages -->
 <img src="docs/assets/stages.svg" alt="DHL: Die Sendung wurde in das Zustellfahrzeug geladen.; Mondial Relay: En cours de livraison; Correios Brazil: Objeto saiu para entrega ao destinatário; Correos Express: EN REPARTO; Yamato Transport: 配達中; La Poste / Colissimo: DISTOU. All are filed under out_for_delivery." width="760">
 
-The carrier folders record 5,312 such statuses, each filed under one stage.
+The carrier folders record 5,319 such statuses, each filed under one stage.
 <!-- /GENERATED:stages -->
 
 Wording nobody recorded yet goes through a classifier that reads seven European languages.

package/data/catalog.json

@@ -7649,7 +7649,9 @@
     "timezone": "America/Chicago",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "osm-worldwide",
+      "recognitionRank": 75,
+      "localClocks": true
     },
     "canaryUrl": "https://www.osmworldwide.com/tracking/",
     "trackingUrlTemplate": "https://www.osmworldwide.com/tracking/?trackingIds={trackingNumber}",
@@ -7670,6 +7672,10 @@
       {
         "pattern": "^A\\d{10}[A-Z]{3}\\d{8}$",
         "confidence": "high"
+      },
+      {
+        "pattern": "^OSM[0-9A-Z]{14}$",
+        "confidence": "high"
       }
     ]
   },

package/data/coverage-summary.json

@@ -1,6 +1,6 @@
 {
   "catalog": 208,
-  "activeAdapters": 179,
+  "activeAdapters": 180,
   "countries": 66,
   "referenceCarriers": 100,
   "comparison": {

package/data/detection-golden.json

@@ -32841,6 +32841,22 @@
     "confidence": "none",
     "candidates": []
   },
+  {
+    "input": "OSM000000LM0060VO",
+    "carrier": "osm-worldwide",
+    "confidence": "high",
+    "candidates": [
+      "osm-worldwide"
+    ]
+  },
+  {
+    "input": "OSM000000LM00B0LO",
+    "carrier": "osm-worldwide",
+    "confidence": "high",
+    "candidates": [
+      "osm-worldwide"
+    ]
+  },
   {
     "input": "P2Q5J87J96",
     "carrier": "unknown",

package/dist/browser/scraper.js

@@ -6067,7 +6067,9 @@ var De = {
 		timezone: "America/Chicago",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "osm-worldwide",
+			recognitionRank: 75,
+			localClocks: !0
 		},
 		canaryUrl: "https://www.osmworldwide.com/tracking/",
 		trackingUrlTemplate: "https://www.osmworldwide.com/tracking/?trackingIds={trackingNumber}",
@@ -6080,6 +6082,9 @@ var De = {
 		detectionRules: [{
 			pattern: "^A\\d{10}[A-Z]{3}\\d{8}$",
 			confidence: "high"
+		}, {
+			pattern: "^OSM[0-9A-Z]{14}$",
+			confidence: "high"
 		}]
 	},
 	paquetexpress: {
@@ -7363,7 +7368,7 @@ var De = {
 		"omniva-s10"
 	],
 	"orlen-paczka": ["orlen-paczka-1"],
-	"osm-worldwide": ["osm-worldwide-1"],
+	"osm-worldwide": ["osm-worldwide-1", "osm-worldwide-2"],
 	paquetexpress: [],
 	passport: ["passport-1"],
 	"post-luxembourg": ["post-luxembourg-s10"],
@@ -12383,6 +12388,7 @@ var Qc = {
 	omniva: 300,
 	ontrac: 650,
 	"orlen-paczka": 495,
+	"osm-worldwide": 75,
 	"poczta-polska": 750,
 	"post-luxembourg": 80,
 	"posta-slovenije": 130,

package/dist/carriers/osm-worldwide/adapter.d.ts

@@ -0,0 +1,16 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare const OSM_ENDPOINT = "https://prod.track-pub.osmworldwide.com/tracking/tracking-request";
+/** The address the tracker asks for one number; without an account it takes one at a time. */
+export declare function osmTrackingUrl(raw: string): string;
+export declare class OsmWorldwideTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+        userAgent?: string;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/osm-worldwide/adapter.js

@@ -0,0 +1,81 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { ChallengeError, IndeterminateError, InvalidInputError, RateLimitedError, SchemaError, TransportError, } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { firstAttemptMs, networkRetryStep } from '../../core/runner/networkRetry.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
+import { isUspsNumber, normalizeOsmNumber, OSM_MAX_BYTES, parseOsmWorldwide, PROVIDER } from './parser.js';
+// The service the tracking component on osmworldwide.com/tracking/ asks,
+// without an account, key, cookie or CAPTCHA token.
+export const OSM_ENDPOINT = 'https://prod.track-pub.osmworldwide.com/tracking/tracking-request';
+// A missing route is not a missing parcel: an unknown number is the service's own `not-found`.
+const GONE = [404, 410];
+// CloudFront's or a firewall's block page instead of the service's JSON.
+const CHALLENGE = /<title>\s*(?:Just a moment|Attention Required|Access denied|403 Forbidden|ERROR: The request could not be satisfied)|cf-turnstile|_cf_chl_opt|captcha/i;
+function retryAfterMs(response) {
+    const header = response.headers.get('retry-after')?.trim();
+    return header && /^\d{1,6}$/.test(header) ? Number(header) * 1000 : undefined;
+}
+/** The address the tracker asks for one number; without an account it takes one at a time. */
+export function osmTrackingUrl(raw) {
+    const url = new URL(OSM_ENDPOINT);
+    url.searchParams.set('ids', normalizeOsmNumber(raw));
+    return url.href;
+}
+export class OsmWorldwideTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const url = osmTrackingUrl(raw);
+        const read = async (signal, timeoutMs) => {
+            // The service holds an anonymous reply for a few seconds before it answers.
+            const { response, bytes } = await fetchBounded(url, { method: 'GET', signal, headers: {
+                    Accept: 'application/json', 'User-Agent': userAgentOf(this.options.userAgent),
+                } }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(timeoutMs)), maxBytes: OSM_MAX_BYTES,
+                fetcher: this.options.fetcher, allowHttpStatuses: [400, ...GONE, 429] });
+            const text = decodeText(bytes);
+            if (response.status === 429)
+                throw new RateLimitedError(PROVIDER, retryAfterMs(response));
+            if (GONE.includes(response.status))
+                throw new TransportError(PROVIDER, 'OSM Worldwide tracking service is unavailable');
+            let payload;
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (cause) {
+                if (CHALLENGE.test(text.slice(0, 64_000)))
+                    throw new ChallengeError(PROVIDER, 'OSM Worldwide answered with a block page', { cause });
+                throw new SchemaError(PROVIDER, 'OSM Worldwide returned a reply that is not JSON', { cause });
+            }
+            // The service refuses a request it cannot read, such as more numbers than
+            // an anonymous visitor may ask for, with HTTP 400; it says nothing about the number.
+            if (response.status === 400)
+                throw new IndeterminateError(PROVIDER, 'OSM Worldwide refused the tracking request');
+            return parseOsmWorldwide(payload, raw);
+        };
+        // A request that fails to reach OSM Worldwide, or hangs, gets one more try:
+        // the first gets half of the budget, so the retry fits in the rest.
+        return runSteps({ carrier: 'osm-worldwide', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [
+            { id: 'direct', run: ({ signal, remainingMs }) => read(signal, firstAttemptMs(remainingMs)) },
+            networkRetryStep(({ signal, remainingMs }) => read(signal, remainingMs)),
+        ]);
+    }
+}
+/** Recognition never claims a USPS barcode: USPS issues it, whoever carries the parcel first. */
+function recognizable(raw) {
+    const number = normalizeOsmNumber(raw);
+    if (isUspsNumber(number))
+        throw new InvalidInputError(PROVIDER, 'USPS barcodes belong to USPS');
+    return number;
+}
+export const adapter = (environment) => {
+    const tracker = new OsmWorldwideTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'osm-worldwide', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => recognizable(number))),
+    };
+};

package/dist/carriers/osm-worldwide/carrier.json

@@ -17,18 +17,59 @@
   "timezone": "America/Chicago",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "osm-worldwide",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "recognition": {
+      "rank": 75
+    },
+    "localClocks": true
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location",
+    "eta",
+    "provider_code",
+    "delivery_partner"
+  ],
   "portal": {
     "url": "https://www.osmworldwide.com/tracking/?trackingIds={trackingNumber}",
     "searchUrl": "https://www.osmworldwide.com/tracking/",
     "canaryUrl": "https://www.osmworldwide.com/tracking/",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "estimated_delivery",
+      "customer_reference",
+      "postcodes",
+      "delivery_instructions"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "estimated_delivery",
+      "provider_code"
+    ],
+    "discarded": [
+      "customer_reference",
+      "postcodes",
+      "delivery_instructions"
+    ],
+    "unavailable": [
+      "offset_timestamps",
+      "service_name",
+      "weight",
+      "dimensions",
+      "sender_name",
+      "recipient_name",
+      "recipient_address",
+      "proof_of_delivery",
+      "delivery_tracking_number"
+    ]
   },
   "links": [
     {
@@ -47,6 +88,11 @@
       "id": "osm-worldwide-1",
       "pattern": "^A\\d{10}[A-Z]{3}\\d{8}$",
       "confidence": "high"
+    },
+    {
+      "id": "osm-worldwide-2",
+      "pattern": "^OSM[0-9A-Z]{14}$",
+      "confidence": "high"
     }
   ]
 }

package/dist/carriers/osm-worldwide/numbers.json

@@ -115,6 +115,44 @@
       },
       "note": "Looked up on OSM Worldwide's own tracker, as an archived address shows; the capture was not opened."
     },
+    {
+      "number": "OSM000000LM00B0LO",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.parcelpanel.com/couriers/osmworldwide/",
+        "date": "2026-10-12",
+        "dateKind": "capture",
+        "access": "full_page"
+      },
+      "context": {
+        "assessment": "confirmed"
+      },
+      "expect": {
+        "carrier": "osm-worldwide",
+        "confidence": "high"
+      },
+      "note": "ParcelPanel's OSM Worldwide page offered it as a sample to try on 12 Oct 2026. OSM Worldwide's tracking service answers it as its own package id, with scans from the label to the delivery."
+    },
+    {
+      "number": "OSM000000LM0060VO",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.parcelpanel.com/couriers/osmworldwide/",
+        "date": "2026-10-12",
+        "dateKind": "capture",
+        "access": "full_page"
+      },
+      "context": {
+        "assessment": "candidate"
+      },
+      "expect": {
+        "carrier": "osm-worldwide",
+        "confidence": "high"
+      },
+      "note": "ParcelPanel's OSM Worldwide page offered it as a sample to try on 12 Oct 2026; OSM Worldwide's tracking service no longer knows it."
+    },
     {
       "number": "BBSIPA00031503",
       "role": "shipment",

package/dist/carriers/osm-worldwide/parser.d.ts

@@ -0,0 +1,20 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "OSM Worldwide";
+export declare const OSM_MAX_BYTES: number;
+/**
+ * A number as the tracker looks it up. A USPS routing barcode opens with the
+ * recipient's ZIP code, so only the package identifier after it is sent; one
+ * without a clean identifier is refused.
+ */
+export declare function normalizeOsmNumber(raw: string): string;
+/** Whether the number is a whole USPS package barcode, which USPS delivers. */
+export declare function isUspsNumber(number: string): boolean;
+/**
+ * The reply of `GET /tracking/tracking-request?ids={number}`: one entry per
+ * number asked for, here one. The entry names the number it answers, upper
+ * case, and is `found` with the parcel's scans newest first, or `not-found`.
+ * The customer package id beside it is the shipper's reference and is never
+ * read. A USPS package barcode is a parcel USPS delivers, so the result names
+ * USPS as the delivery partner, which tracks it under the same number.
+ */
+export declare function parseOsmWorldwide(payload: unknown, raw: string): CarrierResult;

package/dist/carriers/osm-worldwide/parser.js

@@ -0,0 +1,156 @@
+import { normalizeTrackingNumber, uspsPackageIdentifier } from '../../core/detection/index.js';
+import { USPS_ROUTING_BARCODE } from '../../core/detection/usps.js';
+import { IndeterminateError, InvalidInputError, NoHistoryError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { calendarDay, explicitOffsetTime } from '../../core/time/index.js';
+import { cleanScalar } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { osmStage } from './status.js';
+export const PROVIDER = 'OSM Worldwide';
+// A parcel's reply is a few kilobytes: a dozen short scans.
+export const OSM_MAX_BYTES = 512 * 1024;
+// The tracker takes any letters and digits: OSM's own package ids and the
+// partner numbers it labels parcels with, most of them USPS barcodes.
+const NUMBER = /^[A-Z0-9]{4,40}$/;
+// A scan's clock as the service sends it, a wall time without an offset.
+const WALL_CLOCK = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,7})?$/;
+// An expected day, alone or at midnight.
+const DAY = /^(\d{4})-(\d{2})-(\d{2})(?:T00:00:00(?:\.0{1,7})?)?$/;
+const MAX_ROWS = 500;
+const MAX_EVENTS = 100;
+// The page shows no estimate once the parcel is delivered or after a failed attempt.
+const NO_ESTIMATE = new Set(['delivered', 'returned', 'failed_attempt']);
+/**
+ * A number as the tracker looks it up. A USPS routing barcode opens with the
+ * recipient's ZIP code, so only the package identifier after it is sent; one
+ * without a clean identifier is refused.
+ */
+export function normalizeOsmNumber(raw) {
+    const compact = raw.length <= 64 ? normalizeTrackingNumber(raw) : '';
+    const number = USPS_ROUTING_BARCODE.test(compact) ? uspsPackageIdentifier(compact) ?? '' : compact;
+    if (!NUMBER.test(number))
+        throw new InvalidInputError(PROVIDER, 'OSM Worldwide tracks four to forty letters and digits');
+    return number;
+}
+/** Whether the number is a whole USPS package barcode, which USPS delivers. */
+export function isUspsNumber(number) {
+    return uspsPackageIdentifier(number) === number;
+}
+/** An optional text field; an object, array or other value is a changed reply. */
+function text(row, key, maxLength = 500) {
+    const value = row[key];
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value !== 'string' && typeof value !== 'number')
+        throw new SchemaError(PROVIDER, `OSM Worldwide returned an invalid ${key}`);
+    return cleanScalar(value, maxLength);
+}
+/** An optional flag: absent is false, anything but a boolean is a changed reply. */
+function flag(row, key) {
+    const value = row[key];
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value !== 'boolean')
+        throw new SchemaError(PROVIDER, `OSM Worldwide returned an invalid ${key}`);
+    return value;
+}
+/** A scan's clock: an instant when it carries an offset, else its wall time. */
+function clockOf(value) {
+    const instant = explicitOffsetTime(value);
+    if (instant)
+        return { time: instant.iso };
+    const match = WALL_CLOCK.exec(value);
+    if (!match)
+        return null;
+    const [, year, month, day, hour, minute, second] = match;
+    // Only the calendar fields are checked; no offset is assigned. Luxon accepts hour 24.
+    if (!calendarDay(Number(year), Number(month), Number(day)) || Number(hour) > 23 || Number(minute) > 59 || Number(second) > 59)
+        return null;
+    return { local_time: `${year}-${month}-${day}T${hour}:${minute}:${second}` };
+}
+/** The scan's town, state and country. A part holding a digit could be a street or a postcode, so it is left out. */
+function placeOf(row) {
+    return ['city', 'state', 'country'].map((key) => text(row, key, 100))
+        .filter((part) => part && !/\d/.test(part)).join(', ');
+}
+/**
+ * One scan: its clock, wording, code, place and the tracker's flags. The
+ * postcode, the place line built with it and the scan's id, which the page
+ * sends back with delivery instructions, are never read.
+ */
+function scanOf(row) {
+    if (!isRecord(row))
+        throw new SchemaError(PROVIDER, 'OSM Worldwide returned an invalid scan');
+    const description = text(row, 'description');
+    const clock = clockOf(text(row, 'datetime', 40));
+    if (!description || !clock)
+        throw new SchemaError(PROVIDER, 'OSM Worldwide returned a scan without its wording or clock');
+    const code = text(row, 'eventCode', 16);
+    const group = row.group === undefined || row.group === null ? 0 : row.group;
+    if (typeof group !== 'number' || !Number.isInteger(group))
+        throw new SchemaError(PROVIDER, 'OSM Worldwide returned an invalid group');
+    const location = placeOf(row);
+    const staged = osmStage(code, description, { group, instructionsNeeded: flag(row, 'instructionsNeeded'), isException: flag(row, 'isException') });
+    return { ...clock, description, ...(location ? { location } : {}), ...(code ? { provider_code: code } : {}),
+        ...(staged ? { stage: staged.stage, stage_source: staged.source } : {}) };
+}
+/** The expected day the page shows, while the parcel is still to be delivered. */
+function expectedDay(value, stage) {
+    const match = DAY.exec(value);
+    if (!match || (stage && NO_ESTIMATE.has(stage)))
+        return null;
+    return calendarDay(Number(match[1]), Number(match[2]), Number(match[3]));
+}
+/**
+ * The reply of `GET /tracking/tracking-request?ids={number}`: one entry per
+ * number asked for, here one. The entry names the number it answers, upper
+ * case, and is `found` with the parcel's scans newest first, or `not-found`.
+ * The customer package id beside it is the shipper's reference and is never
+ * read. A USPS package barcode is a parcel USPS delivers, so the result names
+ * USPS as the delivery partner, which tracks it under the same number.
+ */
+export function parseOsmWorldwide(payload, raw) {
+    const number = normalizeOsmNumber(raw);
+    if (!Array.isArray(payload) || payload.length !== 1 || !isRecord(payload[0])) {
+        throw new SchemaError(PROVIDER, 'OSM Worldwide returned an unexpected reply');
+    }
+    const entry = payload[0];
+    if (text(entry, 'id', 64).toUpperCase() !== number)
+        throw new SchemaError(PROVIDER, 'OSM Worldwide answered for another number');
+    const result = text(entry, 'result', 32);
+    if (result === 'not-found')
+        throw new NotFoundError(PROVIDER);
+    if (result !== 'found')
+        throw new IndeterminateError(PROVIDER, 'OSM Worldwide returned an unknown lookup result');
+    const rows = entry.history ?? [];
+    if (!Array.isArray(rows) || rows.length > MAX_ROWS)
+        throw new SchemaError(PROVIDER, 'OSM Worldwide returned an invalid parcel history');
+    // The reply lists scans newest first. Their clocks have no offset and come
+    // from several places, so its order stands; identical rows are kept once.
+    const seen = new Set();
+    const events = [];
+    for (const row of rows) {
+        const event = scanOf(row);
+        const key = JSON.stringify(event);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        events.push(event);
+    }
+    if (!events.length)
+        throw new NoHistoryError(PROVIDER);
+    const newest = events[0];
+    const decider = events.find((event) => event.stage);
+    const stage = decider?.stage;
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: decider.stage_source } : {}),
+        last_status_text: newest.description,
+        last_update: newest.time ?? null,
+        ...(newest.local_time ? { last_update_local: newest.local_time } : {}),
+        expected_delivery: expectedDay(text(entry, 'estDelivery', 40), stage),
+        ...(isUspsNumber(number) ? { delivery_carrier: 'usps' } : {}),
+        events: events.slice(0, MAX_EVENTS),
+        ...(events.length > MAX_EVENTS ? { history_truncated: true } : {}),
+    };
+}

package/dist/carriers/osm-worldwide/status.d.ts

@@ -0,0 +1,23 @@
+import { type ClassifiedWording, type Stage } from '../../core/status/index.js';
+import { type CarrierStatusMap } from '../../core/status/statusMap.js';
+/** The stage the map gives a scan's code, if it knows it. */
+export declare function osmCodeStage(code: string): Stage | undefined;
+/** The stage of a tracker milestone group, if the scan is in one. */
+export declare function osmGroupStage(group: number): Stage | undefined;
+/** The stage the map gives wording that came without a code it knows. */
+export declare function osmWordingStage(wording: string): Stage | undefined;
+/** What the tracker says about one scan besides its code and wording. */
+export interface OsmScanFlags {
+    readonly group: number;
+    /** An attempted delivery the recipient can give instructions for. */
+    readonly instructionsNeeded: boolean;
+    readonly isException: boolean;
+}
+/**
+ * A scan's stage: its code, then the tracker's own flags and milestone group,
+ * then OSM's wording, then the shared wording rules. Wording none of them
+ * knows stays without a stage, so it remains visible for review.
+ */
+export declare function osmStage(code: string, wording: string, flags: OsmScanFlags): ClassifiedWording | null;
+/** What the map says about one scan, by its code, or by its wording when it has none. */
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/osm-worldwide/status.js

@@ -0,0 +1,66 @@
+import { classifyWording } from '../../core/status/index.js';
+import { normalizeStatusWording } from '../../core/status/statusMap.js';
+/**
+ * The codes (`eventCode`) on OSM Worldwide's scans. The tracker gives the last
+ * mile partner's scans OSM codes of their own, "courier partner" in the
+ * wording. A partner that leaves with the parcel is on its way, not yet out
+ * for delivery: the same scan can come days before the delivery.
+ */
+const CODES = {
+    OSM02: 'registered',
+    OSM04: 'in_transit',
+    OSM05: 'in_transit',
+    OSM06: 'in_transit',
+    OSM13: 'in_transit',
+    OSM01: 'delivered',
+};
+/**
+ * The tracker's milestone groups, as it names them: label created, in transit,
+ * out for delivery and delivered. Group 0 is a scan in none of them.
+ */
+const GROUPS = {
+    1: 'registered',
+    2: 'in_transit',
+    3: 'out_for_delivery',
+    4: 'delivered',
+};
+/**
+ * OSM's FAQ says this scan is made when the shipper uploads the label, before
+ * OSM has the parcel; the shared rules would read it as a pickup.
+ */
+const WORDINGS = [
+    [/^picked up by shipping partner$/, 'registered'],
+];
+/** The stage the map gives a scan's code, if it knows it. */
+export function osmCodeStage(code) {
+    return Object.hasOwn(CODES, code) ? CODES[code] : undefined;
+}
+/** The stage of a tracker milestone group, if the scan is in one. */
+export function osmGroupStage(group) {
+    return Object.hasOwn(GROUPS, group) ? GROUPS[group] : undefined;
+}
+/** The stage the map gives wording that came without a code it knows. */
+export function osmWordingStage(wording) {
+    const normalized = normalizeStatusWording(wording);
+    return WORDINGS.find(([pattern]) => pattern.test(normalized))?.[1];
+}
+/**
+ * A scan's stage: its code, then the tracker's own flags and milestone group,
+ * then OSM's wording, then the shared wording rules. Wording none of them
+ * knows stays without a stage, so it remains visible for review.
+ */
+export function osmStage(code, wording, flags) {
+    const mapped = osmCodeStage(code)
+        ?? (flags.instructionsNeeded ? 'failed_attempt' : flags.isException ? 'exception' : undefined)
+        ?? osmGroupStage(flags.group)
+        ?? osmWordingStage(wording);
+    if (mapped)
+        return { stage: mapped, source: 'carrier_map' };
+    const worded = classifyWording(wording, 'in_transit');
+    return worded.source === 'none' ? null : worded;
+}
+/** What the map says about one scan, by its code, or by its wording when it has none. */
+export const statusMap = {
+    stage: (code, wording) => (code ? osmCodeStage(code) : osmWordingStage(wording)),
+    gaps: [],
+};

package/dist/carriers/osm-worldwide/statuses.json

@@ -1,4 +1,12 @@
 {
   "carrier": "osm-worldwide",
-  "entries": []
+  "entries": [
+    {"code": "OSM02", "wording": "Shipping label created - OSM awaiting item", "language": "en", "stage": "registered", "confirmedBy": "live", "firstSeen": "2026-10-12", "note": "The shipper's label, before OSM has the parcel."},
+    {"code": "OSM04", "wording": "Arrived at OSM facility", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-10-12", "note": "Each OSM facility the parcel reaches, the first as well."},
+    {"code": "OSM05", "wording": "Departed OSM facility", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-10-12"},
+    {"code": "OSM06", "wording": "Package arrived at courier partner", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-10-12", "note": "The hand-over to the last mile partner, which the tracker does not name."},
+    {"code": "OSM13", "wording": "Package left courier partner and is on its way", "language": "en", "stage": "in_transit", "confirmedBy": "live", "firstSeen": "2026-10-12", "note": "A last mile partner's scan. It can come days before the delivery, so it is not taken as out for delivery."},
+    {"code": "OSM01", "wording": "Package delivered", "language": "en", "stage": "delivered", "confirmedBy": "live", "firstSeen": "2026-10-12"},
+    {"wording": "Picked Up by Shipping Partner", "language": "en", "stage": "registered", "confirmedBy": "documentation", "note": "OSM's FAQ says this scan is made when the label is uploaded and does not mean OSM has the parcel."}
+  ]
 }

package/dist/core/catalog/statusMaps.js

@@ -71,6 +71,7 @@ import { statusMap as oldDominion } from '../../carriers/old-dominion/status.js'
 import { statusMap as omgo } from '../../carriers/omgo/status.js';
 import { statusMap as omniva } from '../../carriers/omniva/status.js';
 import { statusMap as orlenPaczka } from '../../carriers/orlen-paczka/status.js';
+import { statusMap as osmWorldwide } from '../../carriers/osm-worldwide/status.js';
 import { statusMap as postLuxembourg } from '../../carriers/post-luxembourg/status.js';
 import { statusMap as postaSlovenije } from '../../carriers/posta-slovenije/status.js';
 import { statusMap as postaSrbije } from '../../carriers/posta-srbije/status.js';
@@ -109,7 +110,8 @@ export const STATUS_MAPS = {
     'gofo-fr': gofoFr, 'gofo-it': gofoIt, helthjem, 'hrvatska-posta': hrvatskaPosta, 'j-and-t': jAndT, 'j-and-t-cargo': jntCargo, jitsu,
     'kuehne-nagel': kuehneNagel, 'la-poste': laPoste, 'latvijas-pasts': latvijasPasts, 'lietuvos-pastas': lietuvosPastas,
     'loomis-express': loomisExpress, maltapost, matkahuolto, meest, 'mng-kargo': mngKargo, nationex, 'old-dominion': oldDominion, omgo, omniva,
-    'orlen-paczka': orlenPaczka, 'post-luxembourg': postLuxembourg, 'posta-slovenije': postaSlovenije, 'posta-srbije': postaSrbije, postlogistics, ppl,
+    'orlen-paczka': orlenPaczka, 'osm-worldwide': osmWorldwide,
+    'post-luxembourg': postLuxembourg, 'posta-slovenije': postaSlovenije, 'posta-srbije': postaSrbije, postlogistics, ppl,
     ptt, sagawa, sameday, 'slovak-parcel-service': slovakParcelService, 'slovenska-posta': slovenskaPosta, speedx, speedy,
     'stallion-express': stallionExpress, sto, 'swiss-post': swissPost, 'thailand-post': thailandPost, tnt, ups, venipak, 'vinted-go': vintedGo,
     whistl, xdp, yunexpress, 'yurtici-kargo': yurticiKargo, zeleris,

package/dist/data/catalog.json

@@ -7649,7 +7649,9 @@
         "timezone": "America/Chicago",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "osm-worldwide",
+            "recognitionRank": 75,
+            "localClocks": true
         },
         "canaryUrl": "https://www.osmworldwide.com/tracking/",
         "trackingUrlTemplate": "https://www.osmworldwide.com/tracking/?trackingIds={trackingNumber}",
@@ -7670,6 +7672,10 @@
             {
                 "pattern": "^A\\d{10}[A-Z]{3}\\d{8}$",
                 "confidence": "high"
+            },
+            {
+                "pattern": "^OSM[0-9A-Z]{14}$",
+                "confidence": "high"
             }
         ]
     },

package/dist/generated/catalog.d.ts

@@ -5148,7 +5148,9 @@ export declare const CARRIER_CATALOG: {
         readonly timezone: "America/Chicago";
         readonly tracking: {
             readonly mode: "automatic";
-            readonly adapter: "universal";
+            readonly adapter: "osm-worldwide";
+            readonly recognitionRank: 75;
+            readonly localClocks: true;
         };
         readonly canaryUrl: "https://www.osmworldwide.com/tracking/";
         readonly trackingUrlTemplate: "https://www.osmworldwide.com/tracking/?trackingIds={trackingNumber}";
@@ -5161,6 +5163,9 @@ export declare const CARRIER_CATALOG: {
         readonly detectionRules: readonly [{
             readonly pattern: "^A\\d{10}[A-Z]{3}\\d{8}$";
             readonly confidence: "high";
+        }, {
+            readonly pattern: "^OSM[0-9A-Z]{14}$";
+            readonly confidence: "high";
         }];
     };
     readonly paquetexpress: {

package/dist/generated/catalog.js

@@ -7650,7 +7650,9 @@ export const CARRIER_CATALOG = {
         "timezone": "America/Chicago",
         "tracking": {
             "mode": "automatic",
-            "adapter": "universal"
+            "adapter": "osm-worldwide",
+            "recognitionRank": 75,
+            "localClocks": true
         },
         "canaryUrl": "https://www.osmworldwide.com/tracking/",
         "trackingUrlTemplate": "https://www.osmworldwide.com/tracking/?trackingIds={trackingNumber}",
@@ -7671,6 +7673,10 @@ export const CARRIER_CATALOG = {
             {
                 "pattern": "^A\\d{10}[A-Z]{3}\\d{8}$",
                 "confidence": "high"
+            },
+            {
+                "pattern": "^OSM[0-9A-Z]{14}$",
+                "confidence": "high"
             }
         ]
     },
@@ -9195,7 +9201,7 @@ export const DETECTION_RULE_IDS = {
     "omgo": ["omgo-1"],
     "omniva": ["omniva-1", "omniva-2", "omniva-s10"],
     "orlen-paczka": ["orlen-paczka-1"],
-    "osm-worldwide": ["osm-worldwide-1"],
+    "osm-worldwide": ["osm-worldwide-1", "osm-worldwide-2"],
     "paquetexpress": [],
     "passport": ["passport-1"],
     "post-luxembourg": ["post-luxembourg-s10"],

package/dist/generated/recognition.js

@@ -79,6 +79,7 @@ export const CARRIER_RECOGNITION_RANKS = {
     "omniva": 300,
     "ontrac": 650,
     "orlen-paczka": 495,
+    "osm-worldwide": 75,
     "poczta-polska": 750,
     "post-luxembourg": 80,
     "posta-slovenije": 130,

package/dist/generated/registry.js

@@ -123,6 +123,7 @@ import { adapter as omgo } from '../carriers/omgo/adapter.js';
 import { adapter as omniva } from '../carriers/omniva/adapter.js';
 import { adapter as ontrac } from '../carriers/ontrac/adapter.js';
 import { adapter as orlenPaczka } from '../carriers/orlen-paczka/adapter.js';
+import { adapter as osmWorldwide } from '../carriers/osm-worldwide/adapter.js';
 import { adapter as paack } from '../carriers/paack/adapter.js';
 import { adapter as packeta } from '../carriers/packeta/adapter.js';
 import { adapter as planzer } from '../carriers/planzer/adapter.js';
@@ -304,6 +305,7 @@ export const REGISTRY = {
         "omniva": omniva,
         "ontrac": ontrac,
         "orlen-paczka": orlenPaczka,
+        "osm-worldwide": osmWorldwide,
         "paack": paack,
         "packeta": packeta,
         "planzer": planzer,
@@ -498,7 +500,7 @@ export const REGISTRY = {
         "omniva": "omniva",
         "ontrac": "ontrac",
         "orlen-paczka": "orlen-paczka",
-        "osm-worldwide": "universal",
+        "osm-worldwide": "osm-worldwide",
         "paack": "paack",
         "packeta": "packeta",
         "paquetexpress": "universal",

package/dist/server/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Universal Parcel Scraper",
-    "version": "0.120.0"
+    "version": "0.121.0"
   },
   "paths": {
     "/health": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-parcel-scraper",
-  "version": "0.120.0-main.1067",
+  "version": "0.121.0-main.1069",
   "description": "Self-hosted parcel tracking: carrier detection, dedicated scrapers and optional universal providers.",
   "type": "module",
   "license": "Apache-2.0",