Shipment tracker

Shipment tracker

Shipping booth gear and swag to an event eats hours: a dozen boxes, four carriers, a venue dock with its own deadline. This kit turns a messy list into one table sorted by what needs attention, with a link for every package. It works offline and never contacts a carrier; the user opens the links and reports back.

When to use

• "Here are our tracking numbers", "track the booth shipments", "is anything going to be late?"
• The days before an event, daily. Also after the event, for return shipments.
• Not for buying labels or filing claims. Point the user to the carrier for those.

Inputs

1. The shipments. A CSV at data/shipments.csv, or a pasted list. Only the tracking number is required. Useful columns (names are flexible): tracking, item, destination, needed_by, carrier, status, eta, notes.

   • Pasted list: one shipment per line, fields split by |, tab, or comma, in the order tracking, item, destination, needed-by. Save it to data/shipments.txt.
2. Needed-by dates. Ask for them if missing. Use the date the box must be in hand, not the event date. Venue and advance warehouse deadlines are often 3 to 5 days before the show; ask if there is one.
3. Today's date (the script defaults to the system date). Use --as-of when planning ahead.

Steps

1. Load the list. If the user pasted it, write it to data/shipments.txt. Once statuses start coming in, convert it to data/shipments.csv with a status and eta column so updates have a home.

2. Build the tracker.

   node scripts/track.mjs data/shipments.csv out --as-of 2026-11-04 --risk-days 3

   It writes out/shipments.md (the table), out/shipments.csv (for a spreadsheet), and out/shipments.json. Rows are sorted: late, at risk, check number, no date, on track, delivered.

3. Show the summary line and the table. Lead with anything LATE or AT RISK.

4. Walk through status updates, worst first, one at a time:

   • Give the item, the tracking link, and ask: "Open this and tell me the latest status and expected delivery date." Accept a pasted status line or a screenshot.
   • Map what they say to one of: label created, in transit, out for delivery, delivered, exception. Put the expected date in eta.
   • Update that row in data/shipments.csv. After the batch, run the script again and show what changed.

5. For every LATE or AT RISK row, suggest one next action:

   • Label created but not moving 2+ days: call the shipper; the box may never have been picked up.
   • Exception or customs hold: call the carrier with the tracking number; ask about address correction or hold for pickup.
   • ETA after the needed-by date: ask the carrier about rerouting to the hotel or a pickup location near the venue, or plan a local backup (print shop, local swag vendor).
   • Unknown carrier or CHECK #: confirm the number with whoever shipped it; photos of labels often swap 0 and O.
6. Offer a daily rerun until everything is delivered, and a return-shipment list after the event.

Output format

# Shipment tracker (as of 2026-11-04)

7 shipments: 1 late, 1 at risk, 1 need a number check, 3 on track, 1 delivered.

| Flag | Item | Destination | Needed by | Days left | Carrier | Status | Tracking | Why |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| LATE | Demo laptops | Dock B | 2026-11-03 | -1 | DHL | in transit | [1234567890](link) | needed 1 day(s) ago |

Next actions
1. Demo laptops: call DHL about rerouting to the hotel. Backup: rent two laptops locally.

Carrier detection

UPS 1Z plus 16 characters. FedEx 12 or 15 digits, or 22 digits starting 96. USPS 20 to 22 digits starting 92 to 95, 420 plus ZIP prefixes, or XX123456789US. DHL Express 10 digits, DHL eCommerce GM, JJD, or JVGL. Formats overlap (a 10 or 20 digit number can be more than one carrier), so a carrier column always wins over detection, and the script flags a mismatch.

Guardrails

• Never contact carrier websites or APIs yourself. The user opens the links.
• Never guess a status. Unknown stays "not checked".
• Tracking numbers and addresses are shared with nobody; keep them in data/ and out/.
• Do not change needed-by dates without the user saying so; they are the whole point.

Shipment tracker

Paste your tracking numbers and get one clear table of every box headed to your event: carrier, tracking link, days left, and a loud flag on anything that might not make it. No logins, no carrier APIs.

Who it is for: event and field marketing teams, founders running their own booth, anyone who has ever stood at a venue dock asking "where are the banners?"

Example

Input (data/shipments.csv, or just paste it):

tracking,item,destination,needed_by,status
1Z999AA10123456784,Booth backdrop,Expo hall dock B,2026-11-10,in transit
123456789012,Swag: 300 t-shirts,Expo hall dock B,2026-11-06,label created
1234567890,Demo laptops,Expo hall dock B,2026-11-03,in transit

Output (out/shipments.md):

Every tracking number links to the carrier's tracking page. Claude then walks you through the at-risk ones, updates statuses as you report them, and suggests what to do (reroute, call, backup plan). Also writes out/shipments.csv for your spreadsheet. Try examples/shipments.csv.

What it can access

• Reads and updates data/shipments.csv or data/shipments.txt.
• Writes out/shipments.md, out/shipments.csv, and out/shipments.json.
• Runs one script, scripts/track.mjs (Node, no dependencies). No network: it builds tracking links but never opens them.

Setup

None. Needs Node 18 or newer.