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

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

# 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

```bash
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](https://github.com/adom-inc/dhl-tracker)