feat(140): TrackingModule + Track17Provider (Provider-Interface) #219

Merged

admin-mrrm merged 1 commit from feat-140-17track-client into main

2026-05-11 23:55:05 +02:00

admin-mrrm commented

2026-05-11 23:25:27 +02:00

Owner

Closes #140

Legt TrackingModule mit TrackingProvider-Interface an, damit Tracking-Aggregatoren austauschbar sind (17track jetzt, AfterShip im Folge-PR, später ggf. weitere).

Was drin ist

tracking-provider.ts: TrackingProvider-Interface, TrackingRequest/TrackingInfo/TrackingRegisterResult-Types, TRACKING_PROVIDER-Token
providers/track17.provider.ts: erste Implementation gegen api.17track.net/track/v2.2
Module bindet Track17Provider als TRACKING_PROVIDER (per useExisting)
Env: TRACK17_API_KEY (Pflicht für Aufrufe), TRACK17_BASE_URL (optional)

Carrier-Mapping

Unsere Slugs → 17track Numeric-IDs (dhl: 100002, ups: 100007, hermes: 100015, dpd: 100009). Unbekannte/leere Carrier → Auto-Detect bei 17track.

Test plan

9 Unit-Tests grün (Auth, Header, Carrier-Mapping, Accepted/Rejected, Error-Pfade, getTrackInfo)
Typecheck + Lint clean
Drone CI grün

Folge-Arbeiten

AfterShipProvider (eigener PR direkt im Anschluss) → Free-Tier 50/Monat passt für private Volumen
Provider-Auswahl per Env (TRACKING_PROVIDER=17track|aftership)

Closes #140 Legt `TrackingModule` mit `TrackingProvider`-Interface an, damit Tracking-Aggregatoren austauschbar sind (17track jetzt, AfterShip im Folge-PR, später ggf. weitere). ## Was drin ist - `tracking-provider.ts`: `TrackingProvider`-Interface, `TrackingRequest`/`TrackingInfo`/`TrackingRegisterResult`-Types, `TRACKING_PROVIDER`-Token - `providers/track17.provider.ts`: erste Implementation gegen `api.17track.net/track/v2.2` - Module bindet `Track17Provider` als `TRACKING_PROVIDER` (per `useExisting`) - Env: `TRACK17_API_KEY` (Pflicht für Aufrufe), `TRACK17_BASE_URL` (optional) ## Carrier-Mapping Unsere Slugs → 17track Numeric-IDs (`dhl: 100002`, `ups: 100007`, `hermes: 100015`, `dpd: 100009`). Unbekannte/leere Carrier → Auto-Detect bei 17track. ## Test plan - [x] 9 Unit-Tests grün (Auth, Header, Carrier-Mapping, Accepted/Rejected, Error-Pfade, getTrackInfo) - [x] Typecheck + Lint clean - [ ] Drone CI grün ## Folge-Arbeiten - AfterShipProvider (eigener PR direkt im Anschluss) → Free-Tier 50/Monat passt für private Volumen - Provider-Auswahl per Env (`TRACKING_PROVIDER=17track|aftership`)

admin-mrrm added 1 commit

2026-05-11 23:25:27 +02:00

feat(140): TrackingModule mit Provider-Interface und Track17Provider

continuous-integration/drone/push Build is passing

Details

continuous-integration/drone/pr Build is passing

Details

9b738ab92e

TrackingProvider-Interface (TrackingRequest, TrackingRegisterResult,
TrackingInfo, TRACKING_PROVIDER-Token) trennt Vertrag von Implementation,
damit Aggregatoren (17track, AfterShip, ...) austauschbar sind.

Track17Provider als erste Implementation:
- register / gettrackinfo gegen api.17track.net/track/v2.2
- Carrier-Slug → 17track Numeric-ID Mapping (dhl/ups/hermes/dpd)
- Auto-Detect wenn Carrier unbekannt
- ServiceUnavailableException ohne TRACK17_API_KEY
- BadGatewayException bei API-Fehlern (HTTP oder code != 0)

Env: TRACK17_API_KEY + optional TRACK17_BASE_URL.