universal-parcel-scraper 0.49.2-main.559 → 0.49.2-main.562

package/dist/carriers/posti/adapter.js

@@ -4,12 +4,14 @@ import { runSteps } from '../../core/runner/index.js';
 import { explicitOffsetTime } from '../../core/time/index.js';
 import { clean, fetchBounded, parseJsonBytes, userAgentOf } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
+import { isPostiAbroadLabel } from './identity.js';
 import { postiEventStage, postiStatus } from './status.js';
 const TOKEN_URL = 'https://auth-service.posti.fi/api/v1/anonymous_token';
 const GRAPHQL_URL = 'https://graphql.posti.fi/graphql';
 const DEFAULT_TIMEOUT_MS = 15_000;
 // The public tracking page uses this operation with PUBLIC_SHIPMENTS. Select
-// only tracking fields; no account, recipient, address, payment or pickup code.
+// only tracking fields and the pickup point's own address; no account,
+// recipient address, payment or pickup code.
 const QUERY = `query SearchShipments($searchTerms: [String!]!, $locale: String) {
   consumerSearchShipments(page: 1, pageSize: 20, type: PUBLIC_SHIPMENTS, searchTerms: $searchTerms, locale: $locale) {
     totalHits
@@ -17,7 +19,7 @@ const QUERY = `query SearchShipments($searchTerms: [String!]!, $locale: String)
       displayId
       status { main subStatus }
       measurements { weight { unit value } height { unit value } width { unit value } length { unit value } }
-      pickupPoint { address { publicName city } }
+      pickupPoint { type address { publicName streetAddress postcode city } }
       events { city eventDescription reasonDescription timestamp }
       packages { trackingNumber }
     }
@@ -47,6 +49,39 @@ function assertGraphql(payload) {
     if (payload.errors != null && !Array.isArray(payload.errors))
         throw new SchemaError('Posti');
 }
+// Pickup point types whose address is a public business's: Posti's lockers and
+// service points. A private locker stands in the recipient's building.
+const PUBLIC_POINTS = new Set(['LOCKER', 'LOCKER_OUTDOOR', 'POSTI_SERVICE_POINT']);
+/**
+ * The pickup point's name, then its street and "postcode city", as Posti's
+ * tracker lays them out. A private locker, or a point of unknown type, keeps
+ * only its town after the name: its street could be the recipient's.
+ */
+function pickupPoint(raw) {
+    const point = isRecord(raw) ? raw : {};
+    const address = isRecord(point.address) ? point.address : {};
+    const name = clean(address.publicName, 160);
+    if (!name)
+        return null;
+    const street = clean(address.streetAddress, 120);
+    const city = clean(address.city, 80);
+    if (street && city && typeof point.type === 'string' && PUBLIC_POINTS.has(point.type)) {
+        return [name, street, [clean(address.postcode, 16), city].filter(Boolean).join(' ')].join('\n');
+    }
+    return [name, city].filter(Boolean).join('\n');
+}
+/**
+ * Whether the parcel waits at its pickup point, or was collected there: its
+ * last movement before the delivery made it ready for pickup. Notices prove
+ * no movement.
+ */
+function atPickupPoint(stage, events) {
+    if (stage === 'ready_for_pickup')
+        return true;
+    if (stage !== 'delivered')
+        return false;
+    return events.find((event) => !['pending', 'delivered'].includes(event.stage ?? ''))?.stage === 'ready_for_pickup';
+}
 function measurement(raw, units) {
     if (!isRecord(raw) || typeof raw.unit !== 'string' || !Object.hasOwn(units, raw.unit.toLowerCase()))
         return null;
@@ -87,17 +122,17 @@ export function parse(payload, trackingNumber) {
         if (!isRecord(event) || typeof event.eventDescription !== 'string')
             throw new SchemaError('Posti');
         const description = clean(event.eventDescription);
+        const city = clean(event.city, 160);
         return {
             description: [description, clean(event.reasonDescription)].filter(Boolean).join(' '),
             time: explicitOffsetTime(event.timestamp)?.iso ?? '',
-            location: clean(event.city, 160),
+            location: isPostiAbroadLabel(city) ? '' : city,
             stage: postiEventStage(description),
         };
     }).sort((left, right) => (Date.parse(right.time || '') || 0) - (Date.parse(left.time || '') || 0)).slice(0, 100);
     const current = postiStatus(hit.status.main, hit.status.subStatus);
     const measurements = isRecord(hit.measurements) ? hit.measurements : {};
     const dimensions = ['length', 'width', 'height'].map((field) => measurement(measurements[field], { cm: 1, mm: 0.1, m: 100 }));
-    const pickup = isRecord(hit.pickupPoint) && isRecord(hit.pickupPoint.address) ? hit.pickupPoint.address : {};
     return {
         status: current?.status ?? 'unknown',
         ...(current ? { current_stage: current.stage } : {}),
@@ -106,7 +141,8 @@ export function parse(payload, trackingNumber) {
         provider_status: hit.status.main,
         weight_kg: measurement(measurements.weight, { kg: 1, g: 0.001 }),
         dimensions_text: dimensions.every((value) => value !== null) ? `${dimensions.join(' × ')} cm` : null,
-        pickup_point: [clean(pickup.publicName, 160), clean(pickup.city, 80)].filter(Boolean).join(', ') || null,
+        // Posti's tracker shows the point at any status, a planned one in transit included.
+        pickup_point: atPickupPoint(current?.stage, events) ? pickupPoint(hit.pickupPoint) : null,
         timezone: 'Europe/Helsinki',
         events,
     };

package/dist/carriers/posti/identity.d.ts

@@ -0,0 +1,8 @@
+import type { SameInstantIdentityPolicy } from '../../core/catalog/eventIdentity.js';
+/**
+ * Whether a scan's town is Posti's "ULKOMAILLA" ("abroad"), which it gives,
+ * untranslated, to scans outside Finland. It names no place, and the public
+ * reply carries no country to put in its stead.
+ */
+export declare function isPostiAbroadLabel(location: string): boolean;
+export declare const sameInstantIdentityPolicy: SameInstantIdentityPolicy;

package/dist/carriers/posti/identity.js

@@ -0,0 +1,15 @@
+import { matchesDroppedLocation } from '../../core/catalog/locationIdentity.js';
+/**
+ * Whether a scan's town is Posti's "ULKOMAILLA" ("abroad"), which it gives,
+ * untranslated, to scans outside Finland. It names no place, and the public
+ * reply carries no country to put in its stead.
+ */
+export function isPostiAbroadLabel(location) {
+    return location.replace(/\s+/g, ' ').trim().toLocaleUpperCase('fi-FI') === 'ULKOMAILLA';
+}
+// Scans stored with that label as their location lose it and keep their row.
+export const sameInstantIdentityPolicy = {
+    sourceCarrierId: 'posti', storedSources: ['posti'], requireProviderCode: false,
+    matchEachScan: true,
+    matches: (incoming, stored) => matchesDroppedLocation(incoming, stored, isPostiAbroadLabel),
+};

package/dist/core/catalog/eventIdentity.js

@@ -5,10 +5,11 @@ import { sameInstantIdentityPolicy as dpd } from '../../carriers/dpd/app.js';
 import { sameInstantIdentityPolicy as dpdFrance } from '../../carriers/dpd-fr/identity.js';
 import { sameInstantIdentityPolicy as indiaPost } from '../../carriers/india-post/app.js';
 import { sameInstantIdentityPolicy as mondialRelay } from '../../carriers/mondial-relay/identity.js';
+import { sameInstantIdentityPolicy as posti } from '../../carriers/posti/identity.js';
 import { sameInstantIdentityPolicy as ups } from '../../carriers/ups/app.js';
 import { sameInstantIdentityPolicy as swissPost } from '../../carriers/swiss-post/app.js';
 import { sameInstantIdentityPolicy as universal } from '../../providers/shared/app.js';
-const policies = new Map([aliexpress, australiaPost, chronopost, dpd, dpdFrance, indiaPost, mondialRelay, ups, swissPost, universal].map((policy) => [policy.sourceCarrierId, policy]));
+const policies = new Map([aliexpress, australiaPost, chronopost, dpd, dpdFrance, indiaPost, mondialRelay, posti, ups, swissPost, universal].map((policy) => [policy.sourceCarrierId, policy]));
 /** Unlisted sources cannot identify a reworded scan by its instant alone. */
 export function sameInstantIdentityPolicy(sourceCarrierId, options = {}) {
     const policy = policies.get(sourceCarrierId);

package/dist/providers/parcelsapp/adapter.js

@@ -10,6 +10,7 @@
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import timers from 'node:timers/promises';
+import { isPostiAbroadLabel } from '../../carriers/posti/identity.js';
 import { carrierTimezone } from '../../core/catalog/index.js';
 import { brandTimeZones, carrierIdFromName, carrierNameCountryZone } from '../../core/catalog/hints.js';
 import { CarrierError, carrierErrorKind, ChallengeError, IndeterminateError, InputRequiredError, NoHistoryError, SchemaError, UpstreamHttpError, UpstreamNetworkError } from '../../core/errors/index.js';
@@ -236,8 +237,9 @@ function parseHistory(payload, trackingNumber, timezone = null) {
         }
         if (parsed) {
             const location = typeof raw.location === 'string' ? raw.location.replace(/\s+/g, ' ').trim().slice(0, 200) : '';
-            // Some Chronopost rows put the service label in the location field.
-            if (location && !/^Type de livraison\s*:/i.test(location))
+            // Some Chronopost rows put the service label in the location field, and
+            // Posti names scans outside Finland "ULKOMAILLA" (abroad).
+            if (location && !/^Type de livraison\s*:/i.test(location) && !isPostiAbroadLabel(location))
                 parsed.location = location;
             events.push(parsed);
             scanCarriers.add(name);

package/dist/providers/shared/app.js

@@ -1,6 +1,9 @@
-import { matchesLocationEnrichment } from '../../core/catalog/locationIdentity.js';
+import { matchesDroppedLocation, matchesLocationEnrichment } from '../../core/catalog/locationIdentity.js';
+import { isPostiAbroadLabel } from '../../carriers/posti/identity.js';
+// A copy may add a place, or drop Posti's "abroad" label it was once stored with.
 export const sameInstantIdentityPolicy = {
     sourceCarrierId: 'unknown', storedSources: ['unknown'], requireProviderCode: false,
     matchEachScan: true,
-    matches: matchesLocationEnrichment,
+    matches: (incoming, stored) => matchesLocationEnrichment(incoming, stored)
+        || matchesDroppedLocation(incoming, stored, isPostiAbroadLabel),
 };

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

@@ -5,7 +5,10 @@ export declare function numberOf(raw: string): string;
 export declare function text(value: unknown): string;
 export declare function isNotice(description: string): boolean;
 export declare function hasPrivateDeliveryDetails(description: string): boolean;
-/** The place a provider reports for a scan, unless it holds private delivery details. */
+/**
+ * The place a provider reports for a scan, unless it holds private delivery
+ * details or is Posti's "abroad" label.
+ */
 export declare function place(value: unknown): string;
 export declare function eventStage(description: string): Stage | undefined;
 /** Retain the decision before delivery wording is redacted or a stage is projected. */

package/dist/providers/shared/result.js

@@ -12,6 +12,7 @@ import { DateTime } from 'luxon';
 import { trackingLanguageStage } from '../../core/status/index.js';
 import { deliveryForecastRemainder, nonterminalEnglishReturn } from '../../core/status/language.js';
 import { IndeterminateError, InvalidInputError } from '../../core/errors/index.js';
+import { isPostiAbroadLabel } from '../../carriers/posti/identity.js';
 const STAGES = {
     InfoReceived: 'registered', InTransit: 'in_transit', AvailableForPickup: 'ready_for_pickup',
     OutForDelivery: 'out_for_delivery', DeliveryFailure: 'failed_attempt', Delivered: 'delivered',
@@ -35,10 +36,13 @@ export function isNotice(description) {
 export function hasPrivateDeliveryDetails(description) {
     return /\bpin\s*:|(?:access|security|pickup|collection) code|(?:door|house) (?:no\b|number)|signed (?:for )?by|signature|numero civico|firmato da|signe par|signé par|code (?:de retrait|d['’]acc[eè]s)|num[eé]ro de (?:rue|maison)|abholcode|zugangscode|hausnummer|unterschrieben von|codice (?:di ritiro|di accesso)|c[oó]digo (?:pin|secreto|de (?:recogida|retirada|retiro|acceso|acesso|entrega|seguridad|seguran[cç]a|levantamento|recolha|desbloqueo|desbloqueio|apertura|abertura))|firmad[oa] por|firma del destinatari|assinad[oa] por|assinatura|n[uú]mero (?:de (?:portal|puerta|casa|piso|vivienda|pol[ií]cia)|da (?:porta|casa))|(?:porta|puerta) n\.?\s?[º°]|n\.?\s?[º°] (?:de |da )?porta/i.test(description);
 }
-/** The place a provider reports for a scan, unless it holds private delivery details. */
+/**
+ * The place a provider reports for a scan, unless it holds private delivery
+ * details or is Posti's "abroad" label.
+ */
 export function place(value) {
     const location = text(value).slice(0, 200);
-    return location && !hasPrivateDeliveryDetails(location) ? location : '';
+    return location && !hasPrivateDeliveryDetails(location) && !isPostiAbroadLabel(location) ? location : '';
 }
 function sourceEventStage(description, includeBroadMovement = true) {
     // Public aggregators retain the carrier's French wording even in English.

package/package.json

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