app

DHL Tracker

Unreviewed

by Kyle Bergstedt

Internal Adom tool for tracking DHL freight + duty/VAT invoices, auto-pulling them from Gmail, and surfacing customs HS codes from freight PDFs.

Overview Files Versions Dependencies Discussions Activity
app / dhl-tracker
!

Not installable via adompkg

This app has no published release. adompkg install kyle/dhl-tracker will not work until a maintainer publishes a tarball with install.sh and uninstall.sh.

See the publishing docs for the package.json schema and tarball layout required to ship this app.

DHL Tracker

Internal Adom ERP tool for tracking DHL Express freight + duty/VAT invoices, auto-pulling them from Gmail, extracting HS codes from freight PDFs, and managing IEEPA tariff refund claims.

What it does

  • Invoice tracking: Pairs DHL's parallel invoice streams (freight + duty/VAT) by waybill. Surfaces payment status, overdue amounts, and spend breakdown.
  • Auto-pull from Gmail: Apps Script poller watches the [email protected] group for MyBill exports. New invoices arrive automatically — no manual CSV uploads needed.
  • HS code extraction: Parses freight invoice PDFs (pdftotext) for Description of Contents + HTS tables. Classifies shipments by product category (PCB, optical, electronics, etc.) and computes true tariff rates.
  • DHL Tracking API: Background cron syncs tracking status every 10 minutes (rate-budgeted to stay under the 250 calls/day free tier).
  • IEEPA Refund Tracker: Dashboard for managing tariff refund claims following the Supreme Court ruling. Auto-populates claims from eligible duty invoices, classifies by IOR/track/phase, tracks forms and action-plan checklist.
  • Tariff analysis: Spend-by-period breakdowns, duty-per-kg by origin, true tariff rate from declared customs values.

Stack

Fastify 4 + better-sqlite3 + vanilla ES modules (no build step). Runs on port 8852 in the user's Adom container. UI is a Hydrogen webview tab.

Install

git clone [email protected]:adom-inc/dhl-tracker.git ~/project/dhl-tracker
cd ~/project/dhl-tracker
npm install
./bin/dhl-tracker.mjs install

Then configure .env with your DHL Tracking API key and inbound token.

CLI

dhl-tracker install         Symlink into ~/.local/bin
dhl-tracker serve            Run server in foreground
dhl-tracker start            Daemonise (writes data/dhl-tracker.pid)
dhl-tracker stop             POST /api/shutdown
dhl-tracker status           Print server state
dhl-tracker open             Print proxy URL or add Hydrogen tab
dhl-tracker sync-tracking    POST /api/tracking/sync
dhl-tracker import-zip       POST a MyBill DocumentDownload.zip
dhl-tracker tail-console     Stream UI console buffer

Key views

  • By shipment (AWB): One row per waybill with freight + duty inline. Click to expand line breakdown.
  • Invoices: One row per invoice. Filter by type (shipping/duty) and status.
  • Refunds: IEEPA tariff refund claims dashboard. KPI cards, breakdown by phase/track/IOR/status, claims table with inline editing, action-plan checklist, forms tracker.
  • Stats: Open AR, overdue, paid last 30d, shipping vs duty split, top senders.
  • Tariffs: Duty burden by origin, true tariff rate, spend-by-period table.

Data sources

Source Method
MyBill CSV/XLSX/ZIP Manual upload or Gmail auto-pull
Freight PDFs HS code + goods description extraction via pdftotext
DHL Tracking API Background cron (10-min interval, rate-budgeted)
Customs duty PDFs Entry number + entry type extraction

Repo

Private: adom-inc/dhl-tracker