universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/core/status/language.js

@@ -0,0 +1,149 @@
+/** Instructions, uncertainty and a return in progress do not prove sender delivery. */
+export function nonterminalEnglishReturn(description) {
+    const text = description.toLowerCase().replace(/[’‘]/g, "'").replace(/\s+/g, ' ')
+        .replace(/\bwon't\b/g, 'will not').replace(/\bshan't\b/g, 'shall not')
+        .replace(/\bcan't\b|\bcannot\b/g, 'can not').replace(/\b([a-z]+)n't\b/g, '$1 not');
+    // Bind the negative or modal to this sender-delivery phrase. A previous
+    // failed recipient delivery does not negate an affirmative sender return.
+    if (/\b(?:will|would|should|shall|must|may|might|can|could|ought to|needs? to|to) (?:(?:not|never|yet|still|already|soon|shortly|eventually|possibly|probably) )*(?:be|have been) delivered (?:back )?to (?:the )?(?:sender|shipper)\b|\b(?:not|never)(?: yet| already| still)? (?:(?:have|has|be|been|being) )*delivered (?:back )?to (?:the )?(?:sender|shipper)\b|\bbeing delivered (?:back )?to (?:the )?(?:sender|shipper)\b/.test(text))
+        return true;
+    return /\breturn(?:ing)? to (?:the )?sender\b|\b(?:will|would|should|shall|must|may|might|can|could|ought to|needs? to|to) (?:(?:not|never|yet|still|already|soon|shortly|eventually|possibly|probably) )*(?:be|have been) returned to (?:the )?sender\b|\b(?:not|never)(?: yet| already| still)? (?:(?:have|has|be|been|being) )*returned to (?:the )?sender\b|\bbeing returned to (?:the )?sender\b|\breturn (?:has been )?(?:initiated|requested|started)\b/.test(text);
+}
+/**
+ * INFERRED language rules, not captured carrier codes. EN/FR/DE/IT/ES/PT/PL equivalents
+ * are intuitive and overridable: an adapter must resolve verified codes and
+ * carrier-specific semantics before consulting this fallback. No fixture import.
+ */
+export function trackingLanguageStage(description) {
+    const text = description.toLowerCase().normalize('NFD').replace(/\p{Diacritic}/gu, '')
+        .replace(/[’‘]/g, "'").replace(/ł/g, 'l').replace(/[_–—-]/g, ' ').replace(/\s+/g, ' ').trim().replace(/[.!]+$/, '');
+    if (/^wird zugestellt$/.test(text))
+        return 'out_for_delivery';
+    // Specific negatives, future steps and handoffs precede broad delivery words.
+    if (nonterminalEnglishReturn(text))
+        return 'exception';
+    // Spanish and Portuguese returns still under way, announced or negated.
+    if (/\b(?:en|em) (?:proceso de |processo de )?devolu(?:cion|cao)\b|^devolu(?:cion|cao)$|\bdevolu(?:cion|cao) (?:en curso|em curso|iniciada|solicitada|en transito|em transito)\b|\bdevolu(?:cion|cao) (?:al|ao|a la|a) (?:remitente|remetente|origen|origem)\b(?! (?:completad|finalizad|concluid|entregad|entregue|realizad|efectuad|efetuad))|\ben camino (?:de vuelta |de regreso )?(?:al|hacia el) remitente\b|\b(?:a caminho (?:de volta )?(?:do|ao)|em transito para o) remetente\b|\b(?:siendo|sendo|a ser) (?:(?:devuelt|devolvid)[oa]s?|entregad[oa]s? al remitente|entregues? ao remetente)\b|\b(?:no|nao) (?:(?:ha|han|se|fue|foi|foram|sido|ser|sera|puede|pode|pudo|podido|todavia|aun|ainda|ya|ja) )*(?:(?:devuelt|devolvid)[oa]s?|entregad[oa]s? al remitente|entregues? ao remetente)\b|\b(?:sera|seran|serao|va a ser|vai ser|puede ser|pode ser|debe ser|deve ser|devera ser) (?:(?:pronto|proximamente|en breve|em breve|brevemente) )?(?:(?:devuelt|devolvid)[oa]s?|entregad[oa]s? al remitente|entregues? ao remetente)\b|\bse (?:le )?devolvera\b/.test(text))
+        return 'exception';
+    if (/returned to (?:the )?sender|retour(?:ne)? a l'expediteur|zuruck an (?:den )?absender|an (?:den )?absender zuruck|retour a l'expediteur|reso al mittente|restituit[oa] al mittente|delivered (?:back )?to (?:the )?(?:sender|shipper)/.test(text))
+        return 'returned';
+    if (/^(?:(?:envio|paquete|pedido|objeto|encomenda|pacote|remessa) )?(?:devuelt|devolvid)[oa]$|\b(?:devuelt|devolvid|retornad)[oa]s? (?:al|ao|a la|a) (?:remitente|remetente|origen|origem)\b|\bentregad[oa]s? al remitente\b|\bentregues? ao remetente\b|\bdevolu(?:cion|cao) (?:(?:al|ao|a la|a) (?:remitente|remetente|origen|origem) )?(?:completad|finalizad|concluid|entregad|entregue|realizad|efectuad|efetuad)/.test(text))
+        return 'returned';
+    if (/not (?:yet )?delivered|\bundelivered\b|could not.*deliver|unable to deliver|delivery (?:attempt|failed)|non livre|n'(?:a|avons) (?:pas )?pu.*(?:remis|remettre)|n'a pas pu etre (?:distribue|livre)|livraison (?:impossible|echouee)|tentative de livraison|nicht zugestellt|nicht zugestellt werden|zustellung.*(?:fehlgeschlagen|nicht moglich)|zustellversuch|non consegnat[oa]|non e stato possibile consegnare|consegna (?:fallita|non riuscita)|tentativo di consegna/.test(text))
+        return 'failed_attempt';
+    if (/\bno (?:(?:ha|han|hemos|se|le|lo|la|fue|sido|ser|es|era|pudo|puede|podido|posible|todavia|aun) )*(?:entregad[oa]s?|entregar(?:lo|la|le|se)?|repartid[oa]s?|realizar la entrega|efectuar la entrega)\b|\bsin entregar\b|\b(?:entrega|reparto) (?:fallid[oa]|imposible|no (?:(?:ha|han|se|fue|sido|ser|pudo|puede|podido) )*(?:realizad[oa]|efectuad[oa]|completad[oa]|posible|conseguid[oa]))\b|\bimposible (?:entregar|realizar la entrega|efectuar la entrega)\b|\bfallo (?:en la|de) entrega\b|\bintento fallido\b|\bintento de (?:entrega|reparto)\b(?! (?:programad|previst|para (?:hoy|manana|el)|manana|hoy))|\bnao (?:(?:foi|foram|ser|sera|pode|podemos|conseguimos|conseguiu|se|possivel|e|ainda|tem sido|esta|estava) )*(?:entregues?|entregar|efetuar a entrega|efectuar a entrega|realizar a entrega)\b|\bentrega (?:falhada|sem sucesso|impossivel|nao (?:(?:foi|pode|ser|sera|tem sido) )*(?:efetuada|efectuada|realizada|conseguida|concretizada|possivel))\b|\bfalha (?:na|de) entrega\b|\btentativa (?:de entrega|sem sucesso)\b(?! (?:agendada|prevista|programada|para (?:hoje|amanha)|amanha|hoje))|\bcarteiro nao atendido\b/.test(text))
+        return 'failed_attempt';
+    // Missed rounds worded around the attempt, the absent recipient or a closed
+    // business. A scheduled attempt is not a missed one, nor is a sender pickup.
+    if (!/\bpick ?up (?:attempt|was attempted|unsuccessful|failed)|attempted (?:to )?pick ?up/.test(text)
+        && /(?:attempted|tried) to deliver|\battempted delivery\b(?! (?:is )?(?:scheduled|planned|expected|tomorrow|will)\b)|unsuccessful delivery|delivery (?:was )?unsuccessful|unable to complete (?:the |your |this )?delivery|(?<!\bif (?:the |your )?)\b(?:recipient|addressee|consignee|customer|receiver|user)(?: was| is)? (?:not (?:at home|home|available|present)|unavailable|absent)\b|absence of (?:the )?(?:recipient|addressee|consignee)|\bbusiness (?:was |is )?closed\b|destinataire absent|(?:entreprise|societe) (?:etait |est )?fermee?\b|nicht angetroffen|(?:firma|betrieb|geschaft) (?:war |ist )?geschlossen|destinatario assente|(?:attivita|azienda|ditta) (?:era |e )?chiusa/.test(text))
+        return 'failed_attempt';
+    // The same in Spanish and Portuguese ("Ausente"), where "recogida" and
+    // "recolha" name the sender pickup and "si"/"caso" make absence a condition.
+    if (!/\bintento de recogida\b|\brecogida (?:fallida|no realizada|no efectuada)\b|\btentativa de (?:recolha|coleta)\b|\b(?:recolha|coleta) (?:falhada|sem sucesso|nao (?:realizada|efetuada|efectuada))\b/.test(text)
+        && !/\b(?:si|caso)\b[^.;:]*\b(?:ausen|nadie|ninguem|cerrad|fechad|no (?:esta|se encuentra)|nao (?:esta|se encontra))|\bse (?:o |a )?(?:destinatari[oa] |cliente )?(?:estiver|for|nao estiver)\b/.test(text)
+        && /\bausen(?:te|tes|cia)\b|\b(?:destinatari[oa]|cliente|consignatari[oa]) (?:no (?:esta|estaba|se encuentra|se encontraba|disponible|presente)|nao (?:esta|estava|se encontra|se encontrava|disponivel|presente))\b|\bnadie en (?:casa|el domicilio)\b|\bninguem em casa\b|\b(?:establecimiento|negocio|empresa|comercio|tienda) (?:esta |estaba |se encontraba )?cerrad[oa]\b|\b(?:estabelecimento|empresa|loja|comercio|negocio) (?:esta |estava |se encontrava )?fechad[oa]\b/.test(text))
+        return 'failed_attempt';
+    // Carrier-reported problems that are neither a missed attempt nor a return.
+    if (/\b(?:damaged|broken in transit)\b|endommag|avarie|deterior|beschadigt|danneggiat|danad[oa]|danificad|uszkodzon/.test(text))
+        return 'exception';
+    if (/\blost (?:in transit|package|parcel|shipment)?\b|colis perdu|envoi perdu|egare|verloren|verlust der sendung|smarrit|(?:paquete|envio) perdid|extraviad|zagubion|zaginion/.test(text))
+        return 'exception';
+    if (/refused by (?:the )?(?:recipient|consignee)|\brefused\b|rejected by (?:the )?recipient|refus(?:e|ee)? par le destinataire|refus du destinataire|(?:colis|envoi|pli) refuse|annahme verweigert|verweigert|rifiutat|rechazad|recusad|odmowa przyjecia|odmowiono przyjecia/.test(text))
+        return 'exception';
+    if (/address (?:incomplete|incorrect|invalid|insufficient|unknown)|(?:incorrect|incomplete|insufficient|wrong|invalid) address|(?:updated|correct(?:ed)?|complete) (?:delivery )?address (?:is )?(?:required|needed)|address(?:ee)? (?:unknown|cannot be located)|recipient unknown|adresse (?:incorrecte|incomplete|erronee|invalide|inconnue)|destinataire inconnu|(?:adresse|anschrift) (?:unvollstandig|falsch|unbekannt)|empfanger unbekannt|indirizzo (?:errato|incompleto|insufficiente|sconosciuto)|destinatario sconosciuto|direccion (?:incorrecta|incompleta|erronea|desconocida)|destinatario desconocido|endereco (?:incorreto|incompleto|errado|desconhecido)|destinatario desconhecido|adres (?:niepelny|nieprawidlowy|bledny)|nieznany adresat/.test(text))
+        return 'exception';
+    if (/customs (?:issue|problem|hold)|held (?:by|in|at) customs|detained by customs|probleme de douane|retenu en douane|zollproblem|vom zoll zuruckgehalten|problema doganale|fermo in dogana|problema de aduana|retenido en aduana|problema (?:alfandegario|na alfandega)|retido na alfandega|problem celny|zatrzyman[ay] przez (?:urzad celny|cel)/.test(text))
+        return 'exception';
+    if (/(?:shipment|parcel|package) (?:is )?(?:held|blocked|on hold)|held pending|awaiting (?:your )?instructions|action required|(?:colis|envoi|pli) (?:bloque|retenu)|en attente d'instructions|action requise|sendung (?:blockiert|zuruckgehalten|angehalten)|wartet auf anweisungen|handlung erforderlich|spedizione (?:bloccata|trattenuta)|in attesa di istruzioni|envio (?:bloqueado|retenido)|en espera de instrucciones|accion requerida|encomenda (?:bloqueada|retida)|aguarda instrucoes|acao necessaria|przesylka (?:zatrzymana|wstrzymana)|oczekuje na instrukcje/.test(text))
+        return 'exception';
+    if (/\bincident\b|\banomal(?:y|ie|ia)\b|delivery exception|shipment exception|irregularit|unregelmassigkeit|storung|vorfall|inconveniente|incidencia|nieprawidlowosc/.test(text))
+        return 'exception';
+    // Sender data, not the parcel: "Shipment recorded by sender (data delivered)".
+    if (/\b(?:data|information|details) delivered\b|\bdaten (?:ubermittelt|erhalten)|donnees (?:transmises|recues)/.test(text))
+        return 'registered';
+    if (/\b(?:datos|informacion|dados|informacao|informacoes) (?:del envio |do envio |da encomenda )?(?:entregad[oa]s?|entregues?)\b/.test(text))
+        return 'registered';
+    // "Delivered to" a pickup point or an intermediary is not delivery to the
+    // recipient; a parcel already waiting at its pickup point outranks the
+    // "sera remis" (will be handed over) that follows in La Poste's sentence.
+    if (/delivered (?:to|at|in(?:to)?) [^.;,]*?(?:pick ?up (?:point|location)|parcel ?shop|access point|packstation|parcel locker|relay point|service point|collection point)|livre (?:au|en|dans (?:le|un|votre)) (?:point (?:de )?retrait|point relais|relais|consigne|locker)|(?:est|colis|envoi) disponible (?:dans|au|en) (?:votre |le |un )?(?:point (?:de )?retrait|point relais|relais|consigne|bureau de poste)/.test(text))
+        return 'ready_for_pickup';
+    if (/(?<!\b(?:sera|seran|serao|ser|sea|seja|for|siendo|sendo) )\bentregad[oa]s? (?:en|a|al) (?:el |la |un |una |su |tu )?(?:punto (?:de )?(?:recogida|conveniencia)|punto (?:pack|celeritas|collectt|nacex|inpost|dpd|gls|seur|mrw|ups|correos)|locker|taquilla|consigna|citypaq|parcel ?shop|buzon inteligente)\b|(?<!\b(?:sera|serao|ser|seja|for|sendo) )\bentregues? (?:no|num|na|numa|em|ao|a) (?:ponto (?:de )?(?:recolha|levantamento|pickup|entrega)|ponto (?:ctt|dpd|gls|inpost|ups|payshop)|cacifo|locker|loja ctt|payshop)\b/.test(text))
+        return 'ready_for_pickup';
+    if (/delivered to (?:the |a |an |our )?(?:local |destination |final |next |onward |last mile )?(?:carrier|courier|airline|air carrier|hub|depot|terminal|forwarder|(?:handling )?agent|(?:logistics|transport(?:ation)?|shipping|delivery|courier) (?:company|provider|partner|agent|service)|sorting (?:center|centre|facility)|(?:processing |distribution |transit |delivery |logistics )?(?:center|centre|facility)|post office(?! box)|postal (?:operator|service|office)|destination country)\b|delivered to (?:the )?(?:\w+ )?(?:post|poste|posta)\b(?! box| office box)|delivered to (?:dhl|dpd|gls|ups|fedex|usps|tnt|hermes|evri|colissimo|chronopost|quickpac|planzer)\b|handed (?:over )?to (?:the |a |an |our )?(?:local |last mile )?delivery partner|en cours de livraison (?:au|en|vers (?:le|un|votre)) (?:point (?:de )?retrait|point relais|relais|consigne)|livre au transporteur|remis au transporteur local|an den lokalen zusteller ubergeben|consegnat[oa] al (?:corriere|vettore|trasportatore)/.test(text))
+        return 'in_transit';
+    if (/(?<!\b(?:sera|seran|ser|sea|for) )\bentregad[oa]s? (?:(?:el|su|tu) (?:paquete|envio|pedido|bulto) )?(?:a|al|en) (?:el |la |un |una |nuestr[oa] )?(?:transportista|agencia (?:de )?(?:transporte|colaboradora|destino|origen)|operador(?: postal| logistico)?|mensajer(?:o|ia)|courier|empresa de (?:transporte|mensajeria|paqueteria)|compania (?:aerea|de transporte)|aerolinea|centro (?:de )?(?:clasificacion|distribucion|tratamiento|logistico|operaciones)|almacen|delegacion|plataforma|hub|correos|seur|mrw|nacex|tipsa|ctt|gls|dhl|dpd|ups|fedex|tnt|envialia|zeleris|paack|celeritas|inpost)\b|\bentregad[oa] por el remitente\b|(?<!\b(?:sera|serao|ser|seja|for) )\bentregues? (?:(?:a|o) (?:encomenda|envio|objeto) )?(?:a|ao|aos|as|na|no|nos|em) (?:transportadora|transportador|operador(?: postal| logistico)?|parceiro|companhia aerea|centro (?:de )?(?:distribuicao|tratamento|triagem|operacional|logistico)|armazem|plataforma|hub|ctt|correios|dpd|gls|dhl|ups|fedex|tnt|seur|mrw|nacex|tipsa|inpost)\b|\bentregue pelo remetente\b/.test(text))
+        return 'in_transit';
+    if (/will (?:shortly |soon )?be handed|bientot.*(?:confie|remis)|prochainement.*remis|wird.*(?:kurze|bald).*ubergeben|sara.*(?:breve|presto).*affidat/.test(text))
+        return 'registered';
+    // The sender still has to hand the parcel over: "Pendiente de entregar a TIPSA".
+    if (/\bpendiente de (?:entregar|entrega|recepcion|admision|recibir) (?:a|al|en|por) (?:la |el )?(?:agencia|transportista|operador|correos|seur|mrw|nacex|tipsa|ctt|gls|dhl|dpd|ups|fedex|envialia|zeleris|paack|inpost|celeritas)\b|\bpendiente de (?:recepcion|admision)\b|\baguarda entrada\b|\bpendente de (?:rececao|recepcao|entrada)\b/.test(text))
+        return 'registered';
+    if (/or awaiting processing|ou en attente de traitement|oder wartet auf.*bearbeitung|o in attesa di elaborazione/.test(text))
+        return 'registered';
+    if (/will be transported|sera (?:transporte|achemine)|wird.*transportiert|sara trasportat/.test(text))
+        return 'in_transit';
+    if (/will be available|sera disponible|(?:sera|va etre|doit etre) (?:distribue|remis)|wird.*verfugbar|sara disponibile|to be delivered|a livrer|noch zuzustellen|da consegnare|(?:once|when|as soon as) (?:the |your )?(?:shipment|parcel|package|item) is out for delivery/.test(text))
+        return 'in_transit';
+    if (/\bestara disponi(?:ble|vel)\b|\bpor entregar\b|\bpendiente de (?:entrega|entregar|reparto)\b|\bpendente de entrega\b|\b(?:aguarda|aguardando|a aguardar) (?:a )?entrega\b|\bsera (?:enviad|transportad|expedid|encaminhad)[oa]s?\b/.test(text))
+        return 'in_transit';
+    if (/will be delivered|sera livre|wird.*zugestellt|voraussichtlich.*zugestellt|sara consegnat/.test(text))
+        return 'registered';
+    if (/\b(?:sera|seran|serao|va a ser|vai ser) (?:(?:hoy|manana|hoje|amanha|pronto|proximamente|en breve|em breve|brevemente) )?(?:entregad[oa]s?|repartid[oa]s?|entregues?)\b|\bse (?:le |te |lo |la )?entregara\b/.test(text))
+        return 'registered';
+    if (/ready for (?:pickup|collection)|ready to collect|available for (?:pickup|collection)|awaiting (?:customer |recipient |your )?(?:pickup|collection)|pret.*(?:retrait|retire)|disponible.*(?:retrait|collecte)|vous attend (?:au|en|dans|chez|a)\b|mise? a disposition (?:au|en|dans|a)\b.*(?:point (?:de )?retrait|relais|consigne|locker|bureau de poste|agence)|jours? restants? pour (?:le )?retirer|abholbereit|zur abholung bereit|pront[oa] per il ritiro|disponibile per il ritiro|(?:deposited|depose|hinterlegt|depositat[oa]).*mypost24/.test(text))
+        return 'ready_for_pickup';
+    if (/(?<!\b(?:no|nao|ya no|ja nao) (?:(?:esta|estara|se encuentra|se encontra|e|era|foi) )?)\bdisponi(?:ble|vel) (?:para (?:su |ser )?(?:recoger|recogida|recogid[oa]|retirar|retiro|retirada|retirad[oa]|levantamento|levantar|levantad[oa]|recolha|recolher)|(?:en|no|na|num|numa|em) (?:el |la |un |una |su |tu |nuestr[oa] )?(?:punto|oficina|tienda|locker|taquilla|consigna|citypaq|parcel ?shop|buzon inteligente|agencia|delegacion|sucursal|ponto|loja|cacifo|estacao|balcao|payshop|posto|unidade))\b|\blist[oa] para (?:su |ser )?(?:recoger|recogida|recogid[oa]|retirar|retiro)\b|\bpront[oa] (?:para|a) (?:ser )?(?:levantamento|levantar|levantad[oa]|recolha|recolher|retirada|retirar)\b|\b(?:ya )?(?:puede|puedes|podra|podras) (?:pasar a )?recoger(?:lo|la)?\b|\b(?:aguarda|aguardando|a aguardar) (?:o |a )?(?:levantamento|retirada)\b|\besperando (?:su|tu) recogida\b|\b(?:pendiente de|esperando|a la espera de) (?:ser )?recogid[oa] por (?:el |la )?destinatari[oa]\b/.test(text))
+        return 'ready_for_pickup';
+    // Pre-advice can contain "data delivered", a recipient or a carrier handoff.
+    if (/label (?:created|printed)|(?:created|generated) a (?:new )?(?:shipment |shipping )?label|etiquette.*(?:cree|imprime)|cree une etiquette|versandetikett.*(?:erstellt|gedruckt)|etikett erstellt|etichetta.*(?:creata|stampata)|creato un'etichetta|elektronisch|electroni(?:c|que|sch)|elettronic|pre.?advi[cs]|preannunciat|vorangemeldet|preannonce|data.*entered|donnees.*saisies|daten.*erfasst|dati.*inseriti/.test(text))
+        return 'registered';
+    if (/shipment information (?:received|sent to)|\bdata received\b|(?:package|parcel|shipment) data (?:was |has been )?sent to|\bpre ?notification\b|informations d'expedition recues|sendungsinformationen erhalten|informazioni.*spedizione ricevute|(?:consignment|shipment|parcel|package) recorded by|envoi enregistre par|sendung.*absender.*erfasst|spedizione registrata dal/.test(text))
+        return 'registered';
+    if (/preparation chez.*expediteur|preparation.*expediteur|preparazione.*mittente|being prepared.*sender|(?:shipper|sender)(?: that)? (?:they are|is|are) preparing|beim absender.*vorbereitet|warehouse of the sender|shippers warehouse|entrepot de l'expediteur|lager des absenders|magazzino del mittente|demande d'envoi.*prise en compte|collection request.*(?:received|recorded)|abholauftrag.*erfasst|richiesta.*ritiro.*registrata/.test(text))
+        return 'registered';
+    if (/^(?:reported|recorded|announced|item created|enregistre|annonce|erfasst|angekundigt|registrato|annunciato)$/.test(text))
+        return 'registered';
+    // Completion/release is distinct from pending or explicitly negated clearance.
+    if (/attend d'etre libere|attente de liberation|wartet auf.*freigabe|attesa di svincolo|(?:customs|clearance).*\bnot\b.*(?:clear|complet|releas)|dedouanement.*pas termine|customs (?:not cleared|clearance not completed)|not.*released by customs|dedouanement.*(?:non termine|pas termine)|(?:\bnot|n't|\bnever)(?: yet)?(?: been)? cleared (?:through |by )?customs|\bbe(?:ing)? cleared (?:through |by )?customs|non dedouane|zollabfertigung.*nicht abgeschlossen|nicht.*zoll.*freigegeben|sdoganamento.*non completato|non sdoganat/.test(text))
+        return 'customs';
+    if (/clearance.*(?:has been completed|completed)|clearance (?:complete|success)|(?:leaving|departed from|left) customs|completion of customs|formalites.*(?:terminee|achevee)|released by (?:customs|a government agency)|customs (?:cleared|released)|\bcleared (?:through |by )?customs|dedouanement.*(?:termine|acheve)|fin du dedouanement|libere.*(?:douane|autorite)|douane.*libere|zollabfertigung.*abgeschlossen|(?:zoll|behorde).*freigegeben|sdoganamento.*completato|completamento.*sdoganamento|svincolat.*(?:dogana|autorita)/.test(text))
+        return 'in_transit';
+    if (/customs|clearance|douan|formalites (?:d')?(?:import|export)|zoll|dogan|government agency|autorite gouvernementale|staatliche behorde|autorita governativa/.test(text))
+        return 'customs';
+    if (/out for (?:physical )?delivery|being delivered|in delivery|(?:loading|loaded).*delivery vehicle|on (?:\w+ )?vehicle for delivery|(?:courier|driver|delivery champion) has (?:the|your) (?:shipment|parcel|package|item)|en cours de livraison|en livraison|de la livraison de (?:son|votre) colis ce jour|charg(?:e|ement).*vehicule de livraison|in zustellung|zustellfahrzeug.*(?:geladen|verladen)|(?:beladen|verladung).*zustellfahrzeug|in consegna|caric(?:at|amento).*veicolo.*consegna/.test(text))
+        return 'out_for_delivery';
+    // "Reparto" alone is the round, but not the "unidad de reparto" it leaves from;
+    // "distribuição" is the round, but not the "centro de distribuição".
+    if (/^(?:en )?reparto$|\ben reparto\b|\b(?:siendo|sendo|a ser) (?:entregad[oa]s?|entregues?|repartid[oa]s?|distribuid[oa]s?)\b|\b(?:salida|salio|sale|ha salido) (?:a|para) (?:el )?reparto\b|\bruta de (?:reparto|entrega)\b|\ben proceso de entrega\b|\bvehiculo de reparto\b|\b(?:repartidor|mensajero|cartero|conductor) (?:ya )?(?:tiene|lleva) (?:tu|su|el|la) (?:paquete|envio|pedido|encomienda)\b|\bem distribuicao\b|\bsaiu para (?:a )?(?:entrega|distribuicao)\b|\bem (?:rota|processo|curso) de entrega\b|\bem entrega\b|\bveiculo de (?:entrega|distribuicao)\b|\b(?:carteiro|estafeta|motorista|entregador) (?:ja )?(?:tem|leva) (?:a|o) (?:sua |tua )?(?:encomenda|envio|objeto|pacote|volume)\b/.test(text))
+        return 'out_for_delivery';
+    if (/\bdelivered\b|^final delivery$|delivery complete(?:d)?\b|delivery (?:was )?successful|(?:a ete|est) distribue|^(?:livre|livree)(?:$|[ ,])|(?:colis|envoi|est|a ete) livre|zugestellt|\bconsegnat[oa]\b|livraison effectuee|consegna completata/.test(text))
+        return 'delivered';
+    // A delivery still to come ("una vez entregado", "que se entregue", "quando
+    // for entregue") is not one; Spanish "entregue" is also a subjunctive.
+    if (!/\b(?:una vez|cuando|hasta que|antes de que|para que|en cuanto|tan pronto como|uma vez|quando|assim que|ate que|logo que)\b[^.;:]*\bentreg/.test(text)
+        && /(?<!\b(?:sea|sean|fuera|fuese|ser|seja|sejam|fosse|for|forem|que|se) )\b(?:entregad[oa]s?|entregues?)\b|\bentrega (?:realizada|efectuada|efetuada|completada|concluida|finalizada)\b|\brecogid[oa] por (?:el |la )?destinatari[oa]\b|\b(?:levantad|retirad)[oa] pelo destinatario\b/.test(text))
+        return 'delivered';
+    // Posting/collection by the carrier, not recipient pickup or data submission.
+    if (/^(?:posting\/collection|posted|origin scan)$|received at (?:our |the )?(?:[a-z]+ )?origin (?:office|facility|hub)|dropped off (?:after|before) (?:the )?latest drop ?off time/.test(text))
+        return 'accepted';
+    if (/accepted|picked up|pick up was successful|^drop off$|pick ?up scan|prepared the package for return to ups or pickup by ups|handed (?:over )?to (?:dpd|gls)|package received at dhl|item booked|consignment was mailed|posted at a postal point|pris en charge|prise en charge|collecte.*(?:reussi|effectue)|recupere.*boite aux lettres|depose.*point postal|remis a (?:dpd|gls)|envoi.*depose|abholung.*erfolgreich|eingeliefert|an (?:dpd|gls) ubergeben|paket.*(?:angenommen|ubernommen)|ritiro.*(?:riuscito|effettuato)|pres[oa] in carico|affidat[oa] a (?:dpd|gls)|depositat.*punto postale|spedizione.*impostata/.test(text))
+        return 'accepted';
+    if (/transit|en route|on (?:its|the) way|\bfacility\b|airport|\bleaving\b|\bdispatched\b|^delay(?:ed)?$|received by (?:the )?(?:local )?(?:delivery|logistics) company|received by postnl|notification.*sent to the recipient|delivery option requested|instruction de livraison recue|expedie (?:depuis|du|de)\b|acheminement|unterwegs|transport|trasport|arriv|depart|processed|processing completed|sorted|sorting|\btri\b|trie|traitement|traite|sortier|bearbeitet|bearbeitung|elaborat|elaborazion|smistat|parcel cent(?:er|re)|delivery cent(?:er|re)|centre.*(?:colis|distribution)|paketzentrum|verteilzentrum|centro.*(?:pacchi|distribuzione)|depot|import scan|scan.*import|importscan|scansione.*import|delivery.*delayed|livraison.*retard|zustellung.*verzogert|consegna.*ritard|transferred|transfere|weitergeleitet|inoltrato|left.*(?:point|center)|quitte|verlassen|raggiunto|close bag|fermeture du sac|sack.*geschlossen|chiusura.*sacco|scanned into|scanne dans|eingescannt|scansionat|\bloaded\b|^(?:item|parcel|shipment) distributed$|charg.*vehicule de transport|transportfahrzeug.*geladen|caric.*veicolo.*trasporto/.test(text))
+        return 'in_transit';
+    if (/^enviad[oa]$|\bclasificad[oa]s?\b|\bclasificacion\b|\ben ruta\b|\ben camino\b|\bllegad[oa]s? (?:a|al|en)\b|\bllegada (?:a|al|en|de)\b|\bha llegado\b|\bllego (?:a|al)\b|\bsalida (?:de|del|desde)\b|\b(?:ha )?salido (?:de|del)\b|\bsalio (?:de|del)\b|\ben destino\b|\b(?:agencia|delegacion|plataforma|oficina|franquicia) (?:de )?destino\b|\b(?:unidad|centro|oficina|delegacion|base|agencia|plataforma) de reparto\b|\bcentro (?:de )?(?:clasificacion|distribucion|tratamiento|logistico|operaciones|operativo)\b|\blectura\b|\bleid[oa]s?\b|\brecepcionad[oa]s?\b|\bprocesad[oa]s?\b|\bexpedid[oa]s?\b|\btriagem\b|\btriad[oa]s?\b|\bem tratamento\b|\btratad[oa]s?\b|\bcentro (?:de )?(?:distribuicao|tratamento|triagem|operacional)\b|\bchegad[ao] (?:a|ao|no|na|em)\b|\bchegou (?:a|ao|no|na|em)\b|\bsaida (?:do|da|de|dos|das)\b|\bsaiu (?:do|da|de|dos|das)\b|\bem rota\b|\ba caminho\b|\bencaminhad[oa]s?\b|\b(?:em )?transferencia\b|\btransferid[oa]s?\b|\bprocessad[oa]s?\b|\brecebid[oa] (?:no|na|em) (?:centro|armazem|unidade|plataforma)\b|\brecibid[oa] en (?:el |la |nuestr[oa] )?(?:almacen|centro|delegacion|plataforma|hub|agencia)\b/.test(text))
+        return 'in_transit';
+    return undefined;
+}
+export function languageStageStatus(stage) {
+    if (stage === 'registered' || stage === 'pending')
+        return 'pending';
+    if (stage === 'delivered')
+        return 'delivered';
+    if (stage === 'out_for_delivery' || stage === 'ready_for_pickup')
+        return 'out_for_delivery';
+    if (stage === 'returned' || stage === 'failed_attempt' || stage === 'exception')
+        return 'exception';
+    return 'in_transit';
+}

package/dist/core/status/wording.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The generic wording classifier: multilingual language rules first, then the
+ * broad keyword rules, each with a stable rule id. It is the fallback the sync
+ * uses when a carrier has no explicit map for an event; carrier maps and
+ * provider-declared stages always outrank it (ARCHITECTURE.md § Status model).
+ *
+ * Rule ids are persisted per event as `raw_data.stage_source` and grouped in
+ * `tracking_status_observations`, so renaming one is a data change.
+ */
+import type { Stage } from '../../generated/catalog.js';
+export interface ClassifiedWording {
+    stage: Stage;
+    /**
+     * How the stage was decided: `wording:<rule>` names the rule that matched,
+     * `none` means no rule matched and the caller's fallback was used.
+     */
+    source: string;
+}
+/**
+ * The wording classifier. Rule ids are stable: they are persisted per event as
+ * `raw_data.stage_source` and grouped in `tracking_status_observations`.
+ */
+export declare function classifyWording(text: string, fallback?: Stage): ClassifiedWording;
+/** The stage alone, for callers that do not record provenance. */
+export declare function wordingStage(text: string, fallback?: Stage): Stage;

package/dist/core/status/wording.js

@@ -0,0 +1,91 @@
+import { trackingLanguageStage } from './language.js';
+/**
+ * The wording classifier. Rule ids are stable: they are persisted per event as
+ * `raw_data.stage_source` and grouped in `tracking_status_observations`.
+ */
+export function classifyWording(text, fallback = 'in_transit') {
+    const matched = (stage, rule) => ({ stage, source: `wording:${rule}` });
+    const translated = trackingLanguageStage(text);
+    if (translated)
+        return matched(translated, 'language');
+    const value = text.toLocaleLowerCase('en-US').replaceAll('_', ' ').trim().split(/\s+/).join(' ');
+    if (value.includes('to be delivered'))
+        return matched('in_transit', 'to_be_delivered');
+    if (value === 'reported')
+        return matched('registered', 'reported');
+    if (['will shortly be handed over', 'shipment information received', 'electronic shipment information']
+        .some((term) => value.includes(term)))
+        return matched('registered', 'pre_advice');
+    if (['return to sender', 'returned', 'retour'].some((term) => value.includes(term))) {
+        return matched('returned', 'returned');
+    }
+    if (['not delivered', 'could not be delivered', 'unable to deliver', 'delivery attempt',
+        'failed', 'unsuccessful', 'missed delivery', 'nicht zugestellt',
+        'zustellung nicht möglich', 'non livré', 'livraison impossible',
+        'échec de livraison', 'mancata consegna'].some((term) => value.includes(term))) {
+        return matched('failed_attempt', 'failed_attempt');
+    }
+    // Carrier-reported problems that are not a missed attempt and not a return.
+    if (['damaged', 'endommagé', 'avarie', 'avarié', 'beschädigt', 'danneggiato', 'dañado', 'danificado', 'uszkodzon']
+        .some((term) => value.includes(term)))
+        return matched('exception', 'exception_damaged');
+    if (['lost in transit', 'package lost', 'parcel lost', 'colis perdu', 'envoi perdu', 'égaré',
+        'verloren', 'smarrito', 'extraviado', 'zagubiona'].some((term) => value.includes(term))) {
+        return matched('exception', 'exception_lost');
+    }
+    if (['refused', 'rejected by recipient', 'refusé par le destinataire', 'colis refusé',
+        'annahme verweigert', 'rifiutato', 'rechazado', 'recusado', 'odmowa przyjęcia']
+        .some((term) => value.includes(term)))
+        return matched('exception', 'exception_refused');
+    if (['incorrect address', 'incomplete address', 'insufficient address', 'address unknown',
+        'addressee cannot be located', 'adresse incorrecte', 'adresse incomplète', 'adresse falsch',
+        'empfänger unbekannt', 'indirizzo errato', 'dirección incorrecta', 'endereço incorreto',
+        'nieprawidłowy adres'].some((term) => value.includes(term))) {
+        return matched('exception', 'exception_address');
+    }
+    if (['held by customs', 'customs issue', 'customs problem', 'retenu en douane', 'fermo in dogana',
+        'retenido en aduana', 'retido na alfândega'].some((term) => value.includes(term))) {
+        return matched('exception', 'exception_customs_problem');
+    }
+    // "en souffrance" and "in giacenza" are deliberately absent: in postal
+    // wording they usually mean a parcel waiting for collection, not a problem.
+    if (['action required', 'awaiting instructions', 'shipment held', 'on hold',
+        'en attente d\'instructions', 'zurückgehalten', 'retenido', 'retida']
+        .some((term) => value.includes(term)))
+        return matched('exception', 'exception_held');
+    if (['incident', 'anomalie', 'anomaly', 'delivery exception', 'shipment exception', 'carrier exception',
+        'incidencia', 'irregularität'].some((term) => value.includes(term))) {
+        return matched('exception', 'exception_incident');
+    }
+    if (['ready for pickup', 'ready for collection', 'abholbereit', 'deposited in the mypost24 machine']
+        .some((term) => value.includes(term)))
+        return matched('ready_for_pickup', 'ready_for_pickup');
+    if (['delivered', 'deposited', 'zugestellt', 'confirmation of receipt']
+        .some((term) => value.includes(term)))
+        return matched('delivered', 'delivered');
+    if (['out for delivery', 'in delivery', 'loading into delivery vehicle',
+        'loaded into delivery vehicle', 'zustellung'].some((term) => value.includes(term))) {
+        return matched('out_for_delivery', 'out_for_delivery');
+    }
+    if (['was released by customs', 'has been released by customs', 'has been released by a government agency']
+        .some((term) => value.includes(term)))
+        return matched('in_transit', 'customs_released');
+    if (['customs', 'custom clearance', 'zoll', 'pending release from a government agency']
+        .some((term) => value.includes(term)))
+        return matched('customs', 'customs');
+    if (['accepted', 'received at', 'handed over', 'handed to dpd', 'parcel handed', 'posted']
+        .some((term) => value.includes(term)))
+        return matched('accepted', 'accepted');
+    if (['announced', 'registered', 'label created', 'created a label', 'information received', 'elektronisch angekündigt']
+        .some((term) => value.includes(term)))
+        return matched('registered', 'registered');
+    if (['transit', 'sorted', 'sorting', 'departed', 'arrived', 'transport', 'delivery centre', 'depot',
+        'on the way', 'import scan', 'delivery will be delayed']
+        .some((term) => value.includes(term)))
+        return matched('in_transit', 'in_transit');
+    return { stage: fallback, source: 'none' };
+}
+/** The stage alone, for callers that do not record provenance. */
+export function wordingStage(text, fallback = 'in_transit') {
+    return classifyWording(text, fallback).stage;
+}

package/dist/core/telemetry/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What the package reports about every lookup, and the interface the host
+ * implements to receive it. The package never talks to Sentry, Prometheus or a
+ * database itself: the host wires a `StepRecorder` to whichever sinks it runs.
+ *
+ * Every attempt of every step produces one `StepRecord`; every lookup produces
+ * one `LookupRecord` whose `finalStep` says which tier served the result. That
+ * single field answers "is this fallback tier worth keeping".
+ */
+import { errorTypeOf, type CarrierErrorKind } from '../errors/index.js';
+export type StepOutcome = 'ok' | CarrierErrorKind | 'error';
+export interface StepRecord {
+    carrier: string;
+    step: string;
+    /** 1-based position of this attempt within the lookup. */
+    attempt: number;
+    outcome: StepOutcome;
+    errorType: string | null;
+    durationMs: number;
+    /** The step whose failure caused this one to run, if any. */
+    fallbackFrom: string | null;
+    fallbackReason: StepOutcome | null;
+    fallbackErrorType: string | null;
+    /** The previous step's error when this step is a recovery; for sinks that report before-fallback warnings. */
+    fallbackError?: unknown;
+    /** The original error, for sinks that keep stacks. Never serialize it into metrics. */
+    error?: unknown;
+}
+export interface LookupRecord {
+    carrier: string;
+    /** The step that produced the result, or the last step attempted when the lookup failed. */
+    finalStep: string | null;
+    outcome: StepOutcome;
+    errorType: string | null;
+    durationMs: number;
+    /** Number of step attempts made. */
+    attempts: number;
+    /** Number of enabled steps the lookup could have run; 1 means direct was the only tier. */
+    stepsAvailable?: number;
+    error?: unknown;
+}
+export interface StepRecorder {
+    step(record: StepRecord): void;
+    lookup(record: LookupRecord): void;
+}
+export declare const NOOP_RECORDER: StepRecorder;
+/** Telemetry must never change a tracking result: every sink call is guarded. */
+export declare function safeRecorder(recorder: StepRecorder): StepRecorder;
+/** Combine several recorders (for example Sentry, ledger and Prometheus). */
+export declare function combineRecorders(...recorders: StepRecorder[]): StepRecorder;
+export declare function outcomeOf(error: unknown): StepOutcome;
+export { errorTypeOf };
+/** Metric names and labels emitted by the host's Prometheus sink; listed here so dashboards and code agree. */
+export declare const METRICS: {
+    readonly stepDuration: "carrier_step_duration_seconds";
+    readonly stepTotal: "carrier_step_total";
+    readonly lookupTotal: "carrier_lookup_total";
+    readonly fallbackTotal: "carrier_fallback_total";
+    readonly statusMappingTotal: "carrier_status_mapping_total";
+    readonly detectionTotal: "carrier_detection_total";
+    readonly refreshTotal: "carrier_refresh_total";
+};

package/dist/core/telemetry/index.js

@@ -0,0 +1,55 @@
+/**
+ * What the package reports about every lookup, and the interface the host
+ * implements to receive it. The package never talks to Sentry, Prometheus or a
+ * database itself: the host wires a `StepRecorder` to whichever sinks it runs.
+ *
+ * Every attempt of every step produces one `StepRecord`; every lookup produces
+ * one `LookupRecord` whose `finalStep` says which tier served the result. That
+ * single field answers "is this fallback tier worth keeping".
+ */
+import { carrierErrorKind, errorTypeOf } from '../errors/index.js';
+export const NOOP_RECORDER = {
+    step() { },
+    lookup() { },
+};
+/** Telemetry must never change a tracking result: every sink call is guarded. */
+export function safeRecorder(recorder) {
+    return {
+        step(record) {
+            try {
+                recorder.step(record);
+            }
+            catch { /* sink failures are not lookup failures */ }
+        },
+        lookup(record) {
+            try {
+                recorder.lookup(record);
+            }
+            catch { /* sink failures are not lookup failures */ }
+        },
+    };
+}
+/** Combine several recorders (for example Sentry, ledger and Prometheus). */
+export function combineRecorders(...recorders) {
+    const safe = recorders.map(safeRecorder);
+    return {
+        step(record) { for (const recorder of safe)
+            recorder.step(record); },
+        lookup(record) { for (const recorder of safe)
+            recorder.lookup(record); },
+    };
+}
+export function outcomeOf(error) {
+    return carrierErrorKind(error) ?? 'error';
+}
+export { errorTypeOf };
+/** Metric names and labels emitted by the host's Prometheus sink; listed here so dashboards and code agree. */
+export const METRICS = {
+    stepDuration: 'carrier_step_duration_seconds',
+    stepTotal: 'carrier_step_total',
+    lookupTotal: 'carrier_lookup_total',
+    fallbackTotal: 'carrier_fallback_total',
+    statusMappingTotal: 'carrier_status_mapping_total',
+    detectionTotal: 'carrier_detection_total',
+    refreshTotal: 'carrier_refresh_total',
+};

package/dist/core/time/index.d.ts

@@ -0,0 +1,84 @@
+export interface ParsedTime {
+    /** ISO 8601 with the source offset preserved and no milliseconds. */
+    iso: string;
+    /** Epoch milliseconds, for ordering. */
+    timestamp: number;
+}
+export declare const EXPLICIT_OFFSET_PATTERN: RegExp;
+/**
+ * ISO strings that carry their own offset. Use for cross-border lanes where
+ * stamping a zone would be wrong; offset-less values are rejected.
+ */
+export declare function explicitOffsetTime(value: unknown, maxLength?: number): ParsedTime | null;
+/**
+ * Naive wall-clock strings in one known zone. Use when the provider documents
+ * (or live checks show) a single backend zone; note regional caveats in the
+ * adapter.
+ */
+export declare function zonedTime(value: unknown, format: string, zone: string, options?: {
+    locale?: string;
+    maxLength?: number;
+}): ParsedTime | null;
+/** ISO strings that may or may not carry an offset; offset-less values are read in `zone`. */
+export declare function isoTime(value: unknown, zone: string, maxLength?: number): ParsedTime | null;
+/**
+ * Wall-clock times a provider labels as UTC (or with an offset of its own)
+ * although they are the scan's local time: ParcelsApp and PostNL do this. The
+ * digits of the labeled instant, read in UTC, are re-read in `zone`.
+ * Offset-less values are read in `zone` directly.
+ */
+export declare function mislabeledLocalTime(value: unknown, zone: string, maxLength?: number): ParsedTime | null;
+/** The wall clock `mislabeledLocalTime` re-reads, as an offset-less ISO string. */
+export declare function mislabeledWallTime(value: unknown, maxLength?: number): string | null;
+/**
+ * One zone for several that keep the same clock at `wallIso`, an offset-less
+ * wall time: the first zone when every zone reads it as the same instant.
+ * Null when none is given, a zone or the time is invalid, the time carries an
+ * offset (every zone would agree), or the zones disagree at that moment, as
+ * Zurich and London always do.
+ */
+export declare function sharedClockZone(zones: readonly string[], wallIso: string): string | null;
+/** A scan's instant when the feed states it, else the readings its clock may have, likeliest first. */
+export interface FeedClock {
+    known?: ParsedTime | null;
+    guesses?: readonly (ParsedTime | null)[];
+}
+/**
+ * Settles guessed clocks against the feed itself, given newest first. A guess
+ * stands only if it is not after the lookup (`readAt`, give or take an hour of
+ * skew) and keeps the feed's order: not after the nearest newer scan with a
+ * known instant, not before the nearest older one. Each scan gets its known
+ * instant or its first guess that stands; null when none does.
+ */
+export declare function settleGuessedClocks(scans: readonly FeedClock[], readAt: number): (ParsedTime | null)[];
+/**
+ * The ISO code of any country, whatever its clocks, from the code or its
+ * English name ("South Africa" is ZA, "United States" US); null otherwise.
+ */
+export declare function countryCode(country: unknown): string | null;
+/** The zone of a single-zone country, from an ISO code or its English name; null otherwise. */
+export declare function countryTimeZone(country: unknown): string | null;
+/** The single-zone country keeping this civil time ("Europe/Zurich" is Switzerland's); null for UTC. */
+export declare function timeZoneCountry(zone: string): string | null;
+/**
+ * The zone of a US state or territory from its postal code ("IL"): its
+ * majority zone when it has several; null otherwise.
+ */
+export declare function usStateTimeZone(state: unknown): string | null;
+/** The zone of a Canadian province or territory from its postal code ("ON"): its majority zone; null otherwise. */
+export declare function canadaProvinceTimeZone(province: unknown): string | null;
+/** A town name as the region town lists key it: "St. John's" and "SAINT JOHNS" are both "stjohns". */
+export declare function townKey(name: string): string;
+/**
+ * Whether a town of this name lies in the US state or Canadian province whose
+ * code also names a single-clock country: Chicago is in Illinois, not Israel,
+ * and Koeln is not in Delaware. Only DE, IL, IN, MT, NL and SK have town lists
+ * (generated from GeoNames); false for any other code.
+ */
+export declare function regionHasTown(code: string, town: string): boolean;
+/** Epoch milliseconds (numbers or numeric strings); zero and negatives are rejected. */
+export declare function epochMillisTime(value: unknown): ParsedTime | null;
+/** Epoch seconds, same rules as `epochMillisTime`. */
+export declare function epochSecondsTime(value: unknown): ParsedTime | null;
+/** A local calendar day as `YYYY-MM-DD`, validated; never a timestamp. */
+export declare function calendarDay(year: number, month: number, day: number): string | null;