📦 pkg-track

Track all your packages in one place. No more digging through emails!

Interactive CLI that scans your Gmail for shipping confirmations and lets you track UPS, FedEx, USPS, and Amazon packages with arrow-key selection and one-click browser opening.

   ┌──────────────────────────────────────────────────────┐
   │   📦  PKG TRACK                                       │
   │      Track all your packages in one place 📦          │
   └──────────────────────────────────────────────────────┘

   🌐 Open all packages in browser
   🚚 Running shoes (UPS - In Transit) · today
   📦 Laptop stand (FedEx - Pending) · 2d ago
   ⏳ Phone case (USPS - Pending) · yesterday

✨ Features

• 🔍 Auto-scan Gmail - Securely search your email for shipping confirmations
• 🎮 Interactive menu - Arrow-key selection, auto-opens tracking in browser
• 🚚 Smart parsing - Automatically extracts tracking numbers from emails
• 🎯 4 major carriers - UPS, FedEx, USPS, Amazon Logistics
• 💾 Local-only storage - Your data never leaves your machine
• ⚡ Fast & simple - Quick CLI, no browser extension needed
• 🌐 One-click tracking - No more copy/pasting tracking numbers
• 🔒 Secure - Read-only Gmail access, revocable anytime

📋 Prerequisites

• Node.js 14 or higher (Download)
• Gmail account

Supported Platforms:

• ✅ macOS (10.15+)
• ✅ Linux (Ubuntu, Debian, Fedora, etc.)
• ✅ Windows 10/11 (with Node.js)

🚀 Quick Start

1. Install

From npm (recommended):

npm install -g pkg-track

From git (for development):

# Requires build tools (python, make, gcc/clang)
npm install -g git+https://github.com/vvanessaww/pkg-track.git

⚠️ Installing from git requires build tools for compiling native modules (better-sqlite3). On macOS, install Xcode Command Line Tools: xcode-select --install. On Ubuntu/Debian: sudo apt-get install build-essential python3

2. Initialize

pkg init

What happens:

1. Opens your browser to a secure authorization page
2. You click "Sign in with Gmail"
3. Grant read-only access to your Gmail
4. Token is saved locally on your computer

That's it! Simple one-click setup, no Google Cloud configuration needed.

Privacy: We use read-only Gmail access (gmail.readonly scope). Your credentials and package data stay on your computer. You can revoke access anytime at https://myaccount.google.com/permissions

Usage

Scan email for packages

pkg sync
pkg sync --days 7   # Scan last 7 days only

Options:

• --days <number> - Number of days to scan back (default: 30, max: 30)

Note: Maximum 30 days to avoid Gmail API rate limits and keep results relevant.

Open package tracking

pkg open

Interactive menu to open tracking pages in your browser:

• ⬆️⬇️ Arrow keys to select a package
• ⏎ Enter to open tracking page
• 🌐 "Open all" option to open all packages at once
• Automatically opens UPS.com, FedEx.com, or USPS.com

Example:

📦 Open Package Tracking

Select a package to track:
❯ 🌐 Open all packages in browser
  🚚 Running shoes (UPS - In Transit)
  📦 Laptop stand (FedEx - Pending)
  ⏳ Phone case (USPS - Pending)
  ❌ Exit

Manually add a package

pkg add 1Z999AA10123456784

Interactive prompts will ask for:

• Package description (e.g., "Running shoes")
• Carrier selection (auto-detected when possible)
• Retailer/store name (optional)

Example:

📦 Adding package manually...

✓ Valid tracking number detected
  Carrier: UPS
  Tracking: 1Z999AA10123456784

? What is this package? Running shoes
? Select carrier: UPS (detected)
? Where did you order from? Nike

✓ Package added successfully!
  Running shoes
  UPS · 1Z999AA10123456784

Clean up packages

pkg clean

Interactively remove packages you no longer want to track:

• 📋 Shows all packages (including delivered)
• ☑️ Checkbox selection (Space to select, Enter when done)
• ✅ Confirms before deleting

Example:

🗑️  Select packages to remove

Select packages to remove (Space to select, Enter when done):
❯ ◯ Running shoes (UPS - Delivered)
  ◯ Laptop stand (FedEx - Pending)
  ◉ Old package from 2025 (USPS - Delivered)

Perfect for cleaning up delivered packages or removing things you're no longer tracking.

Supported Carriers

• ✅ UPS (auto-detection + tracking)
• ✅ FedEx (auto-detection + tracking)
• ✅ USPS (auto-detection + tracking)
• ✅ Amazon Logistics (auto-detection + tracking)

Tracking number formats:

• UPS: 1Z followed by 16 alphanumeric characters
• USPS: 20-22 digit numbers starting with 9, 92, 94, or 82
• Amazon: TBA followed by 12 digits
• FedEx: 12, 15, or 20 digit numbers (with "fedex" in email)

How it Works

1. Gmail API searches for emails with keywords like "shipped", "tracking", "delivered"
2. Regex patterns extract tracking numbers from email content
3. Carrier detection identifies which shipping service based on tracking format
4. Retailer detection identifies store based on sender email
5. SQLite database stores everything locally
6. Interactive menu (powered by inquirer) lets you select and open tracking pages instantly

🔒 Security & Privacy

Your data stays on your machine:

• All package data stored locally in ~/.pkg-tracker/
• OAuth credentials stored with 0600 permissions (user read/write only)
• Database files secured with 0700 directory permissions

Gmail Access:

• Read-only scope: gmail.readonly - cannot send, delete, or modify emails
• Local authentication: OAuth tokens stored on your computer only
• Secure storage: Credentials never logged or transmitted to third parties
• Revocable: You can revoke access anytime at https://myaccount.google.com/permissions

What we access:

• ✅ Email headers and body text to find tracking numbers
• ✅ Only emails matching shipping keywords (last 30 days max)
• ❌ No access to send, delete, or modify emails
• ❌ No data sent to external servers or analytics
• ❌ No telemetry or tracking

Data stored locally:

• ~/.pkg-tracker/credentials.json - Your Gmail OAuth credentials
• ~/.pkg-tracker/gmail-token.json - Authentication token (auto-refresh)
• ~/.pkg-tracker/packages.db - SQLite database of your packages

Revoking access: If you want to stop using pkg-track:

1. Revoke OAuth access: https://myaccount.google.com/permissions
2. Delete local data: rm -rf ~/.pkg-tracker

🔧 Troubleshooting

"This app isn't verified" warning during OAuth

What you'll see: When authorizing Gmail access, Google shows a warning: "Google hasn't verified this app"

This is normal! You created the app yourself, so Google hasn't verified it. This is expected and safe.

To continue:

1. Click "Advanced"
2. Click "Go to [your-app-name] (unsafe)"
3. Click "Allow"

Why it's safe: You created the OAuth credentials yourself - it's YOUR app accessing YOUR Gmail. No one else has access.

"Gmail not authorized"

Problem: Error says Gmail not authorized or token missing

Solution:

1. Run pkg init to authenticate
2. Make sure you complete the OAuth flow in your browser
3. If stuck, delete old token and re-authenticate:

   rm ~/.pkg-tracker/gmail-token.json
   pkg init

"No packages found"

Problem: pkg sync completes but finds 0 packages

Possible causes:

1. No shipping emails in date range - Try expanding the range:

   pkg sync --days 30

2. Emails don't contain tracking numbers - Some order confirmations don't include tracking yet
3. Unsupported carrier - Only UPS, FedEx, USPS, Amazon supported
4. Tracking number format - Some international carriers use different formats

Debug:

• Check if pkg sync shows "X emails had no tracking numbers"
• Those emails likely are order confirmations without tracking yet

"Module not found" errors

Problem: Error when running pkg command

Solution:

# If installed globally, reinstall
npm uninstall -g pkg-track
npm install -g pkg-track

"Permission denied" on macOS/Linux

Problem: Cannot write to ~/.pkg-tracker/

Solution:

# Fix directory permissions
mkdir -p ~/.pkg-tracker
chmod 700 ~/.pkg-tracker

OAuth browser doesn't open

Problem: pkg init says "Opening browser..." but nothing happens

Solution:

1. Manually copy the URL from the terminal
2. Paste it into your browser
3. Complete the OAuth flow
4. The terminal should detect the authorization

"Invalid tracking number"

Problem: pkg add rejects your tracking number

Solution:

• UPS: Must be 1Z followed by 16 characters (e.g., 1Z999AA10123456784)
• USPS: 20-22 digits starting with 9, 92, 94, or 82
• FedEx: 12, 15, or 20 digits (email must mention "fedex")
• Amazon: TBA followed by 12 digits (e.g., TBA123456789012)

Remove spaces and special characters - tracking numbers are alphanumeric only.

Database is corrupted

Problem: SQLite errors or weird behavior

Solution:

# Backup current database
cp ~/.pkg-tracker/packages.db ~/.pkg-tracker/packages.db.backup

# Delete and resync
rm ~/.pkg-tracker/packages.db
pkg sync

Rate limiting / Too many requests

Problem: Gmail API quota exceeded

Solution:

• Gmail API has daily quotas (usually generous)
• Wait a few hours and try again
• Don't run pkg sync in a loop
• Default 30-day scan is usually fine

Still having issues?

1. Check Node.js version:

   node --version  # Should be 14.0.0 or higher

2. Enable debug mode (check for errors):

   NODE_ENV=development pkg sync

3. Open an issue:

   • Visit: https://github.com/vvanessaww/pkg-track/issues
   • Include: OS, Node.js version, error message, steps to reproduce

Known Issues

npm deprecation warning during installation

What you might see:

npm warn deprecated [email protected]: No longer maintained

What it means:

• This warning comes from a dependency (better-sqlite3) that we use for local database storage
• It's a cosmetic warning and does not affect functionality
• The package works perfectly fine
• We're waiting for the upstream maintainer to update their dependencies

Action required: None. You can safely ignore this warning.

Roadmap

• [ ] Live tracking updates via AfterShip/TrackingMore API
• [ ] Desktop notifications when packages arrive
• [ ] Return window tracking - never miss a return deadline
• [ ] Price tracking - monitor order prices
• [ ] Web dashboard - visual interface
• [ ] AI extraction - better parsing for non-standard shipments

Development

# Run locally
npm start -- list

# Link for testing
npm link

# Run tests
npm test

License

MIT

Contributing

PRs welcome! This is a fun side project.

Why?

Because juggling packages from Amazon, Target, Etsy, random eBay sellers is chaos. One command should show you everything.