pkg-track 1.0.0

package/README.md

@@ -0,0 +1,393 @@
+# 📦 pkg-tracker
+
+**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
+
+Before installing, you'll need:
+
+- **Node.js 14 or higher** ([Download](https://nodejs.org/))
+- **Gmail account** - For scanning shipping emails
+- **Google Cloud Project** - Free tier (for OAuth credentials)
+  - See [Setup](#setup) for detailed instructions
+
+**Supported Platforms:**
+- ✅ macOS (10.15+)
+- ✅ Linux (Ubuntu, Debian, Fedora, etc.)
+- ✅ Windows 10/11 (with Node.js)
+
+## 🚀 Installation
+
+**Option 1: NPM (Recommended)**
+```bash
+npm install -g pkg-tracker
+```
+
+**Option 2: From Source**
+```bash
+git clone https://github.com/vvanessaww/pkg-tracker.git
+cd pkg-tracker
+npm install
+npm link
+```
+
+**Verify installation:**
+```bash
+pkg --version
+```
+
+## Setup
+
+### 1. Get Gmail API Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+2. Create a new project (or select existing)
+3. Enable **Gmail API**
+4. Create **OAuth 2.0 Client ID** (Application type: Desktop app)
+5. Download the credentials JSON file
+6. Save it as `~/.pkg-tracker/credentials.json`
+
+### 2. Initialize
+
+```bash
+pkg init
+```
+
+This will:
+- Open your browser for Gmail authorization
+- Save access token for future use
+- Create local database
+
+## Usage
+
+### Scan email for packages
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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-tracker:
+1. Revoke OAuth access: https://myaccount.google.com/permissions
+2. Delete local data: `rm -rf ~/.pkg-tracker`
+
+## 🔧 Troubleshooting
+
+### "Gmail credentials not found"
+
+**Problem:** You see `⚠️ Gmail OAuth credentials not found.`
+
+**Solution:**
+1. Make sure you've created OAuth credentials in Google Cloud Console
+2. Download the credentials JSON file
+3. Save it to the correct location:
+   ```bash
+   mkdir -p ~/.pkg-tracker
+   mv ~/Downloads/client_secret_*.json ~/.pkg-tracker/credentials.json
+   ```
+4. Run `pkg init` again
+
+### "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:
+   ```bash
+   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:
+   ```bash
+   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:**
+```bash
+# Reinstall dependencies
+cd /path/to/pkg-tracker
+npm install
+
+# If installed globally, reinstall
+npm uninstall -g pkg-tracker
+npm install -g pkg-tracker
+```
+
+### "Permission denied" on macOS/Linux
+
+**Problem:** Cannot write to `~/.pkg-tracker/`
+
+**Solution:**
+```bash
+# 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:**
+```bash
+# 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:**
+   ```bash
+   node --version  # Should be 14.0.0 or higher
+   ```
+
+2. **Enable debug mode** (check for errors):
+   ```bash
+   NODE_ENV=development pkg sync
+   ```
+
+3. **Open an issue:**
+   - Visit: https://github.com/vvanessaww/pkg-tracker/issues
+   - Include: OS, Node.js version, error message, steps to reproduce
+
+## 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
+
+```bash
+# 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.

package/bin/cli.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const pkg = require('../package.json');
+const { initGmail, syncPackages } = require('../src/gmail');
+const { addPackage } = require('../src/tracker');
+const { openPackages } = require('../src/open');
+const { getAllPackages } = require('../src/db');
+
+// Global error handler
+process.on('unhandledRejection', (reason, promise) => {
+  console.error(chalk.red('\n✗ Unexpected error occurred:'));
+  console.error(chalk.gray(reason.message || reason));
+  console.error(chalk.yellow('\nIf this persists, please report it:'));
+  console.error(chalk.cyan('https://github.com/vvanessaww/pkg-tracker/issues\n'));
+  process.exit(1);
+});
+
+process.on('uncaughtException', (error) => {
+  console.error(chalk.red('\n✗ Fatal error:'));
+  console.error(chalk.gray(error.message));
+  console.error(chalk.yellow('\nIf this persists, please report it:'));
+  console.error(chalk.cyan('https://github.com/vvanessaww/pkg-tracker/issues\n'));
+  process.exit(1);
+});
+
+const program = new Command();
+
+program
+  .name('pkg')
+  .description('Track all your packages in one place')
+  .version(pkg.version);
+
+program
+  .command('init')
+  .description('Set up Gmail OAuth and initialize database')
+  .action(async () => {
+    try {
+      await initGmail();
+      console.log(chalk.green('✓ Setup complete! Run `pkg sync` to scan your emails.'));
+    } catch (error) {
+      console.error(chalk.red('Error during setup:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('sync')
+  .description('Scan Gmail for shipping confirmations')
+  .option('-d, --days <number>', 'Number of days to scan back (max 30)', '30')
+  .action(async (options) => {
+    try {
+      let days = parseInt(options.days, 10);
+      
+      // Validate input
+      if (isNaN(days)) {
+        console.log(chalk.red('⚠️  Days must be a valid number'));
+        process.exit(1);
+      }
+      
+      // Enforce max of 30 days
+      if (days > 30) {
+        console.log(chalk.yellow(`⚠️  Maximum 30 days allowed. Using 30 instead of ${days}.`));
+        days = 30;
+      }
+      
+      if (days < 1) {
+        console.log(chalk.red('⚠️  Days must be at least 1'));
+        process.exit(1);
+      }
+      
+      await syncPackages(days);
+    } catch (error) {
+      console.error(chalk.red('Error syncing:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('add <tracking-number>')
+  .description('Manually add a tracking number (interactive)')
+  .action(async (trackingNumber) => {
+    try {
+      await addPackage(trackingNumber);
+    } catch (error) {
+      console.error(chalk.red('\nError adding package:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('open')
+  .description('Interactively open package tracking in browser')
+  .action(async () => {
+    try {
+      await openPackages();
+    } catch (error) {
+      console.error(chalk.red('Error opening packages:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('clean')
+  .description('Interactively remove packages from tracking')
+  .action(async () => {
+    try {
+      const inquirer = require('inquirer');
+      const allPackages = getAllPackages(true); // Include delivered
+      
+      if (allPackages.length === 0) {
+        console.log(chalk.yellow('\n📭 No packages to clean\n'));
+        return;
+      }
+      
+      console.log(chalk.blue('\n🗑️  Package Cleanup\n'));
+      console.log(chalk.gray('Remove old or delivered packages from your tracking list'));
+      console.log(chalk.gray('Use Space to select multiple, Enter when done\n'));
+      
+      // Build choices
+      const choices = allPackages.map(pkg => {
+        const description = pkg.description || 'Package';
+        const shortDesc = description.length > 40 ? description.substring(0, 37) + '...' : description;
+        const status = pkg.delivered_at ? '✅ Delivered' : pkg.status || 'Pending';
+        
+        return {
+          name: `${shortDesc} (${pkg.carrier} - ${status})`,
+          value: pkg.tracking_number,
+          short: shortDesc
+        };
+      });
+      
+      const { selected } = await inquirer.prompt([{
+        type: 'checkbox',
+        name: 'selected',
+        message: 'Select packages to remove (Space to select, Enter when done):',
+        choices,
+        pageSize: 15
+      }]);
+      
+      if (selected.length === 0) {
+        console.log(chalk.yellow('\nNo packages selected. Nothing removed.\n'));
+        return;
+      }
+      
+      // Confirm deletion
+      const { confirm } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'confirm',
+        message: `Delete ${selected.length} package(s)?`,
+        default: false
+      }]);
+      
+      if (!confirm) {
+        console.log(chalk.yellow('\nCancelled\n'));
+        return;
+      }
+      
+      // Delete selected packages
+      const { deletePackage } = require('../src/db');
+      for (const trackingNumber of selected) {
+        deletePackage(trackingNumber);
+      }
+      
+      console.log(chalk.green(`\n✓ Removed ${selected.length} package(s)\n`));
+      
+    } catch (error) {
+      console.error(chalk.red('Error cleaning:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "pkg-track",
+  "version": "1.0.0",
+  "description": "Track all your packages in one place - UPS, FedEx, USPS, Amazon. Interactive CLI with Gmail integration.",
+  "main": "src/index.js",
+  "bin": {
+    "pkg": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node test/parser.test.js"
+  },
+  "keywords": [
+    "package",
+    "tracking",
+    "cli",
+    "shipping",
+    "ups",
+    "fedex",
+    "usps",
+    "amazon",
+    "delivery",
+    "gmail",
+    "logistics",
+    "parcel",
+    "track-package",
+    "package-tracker",
+    "shipment",
+    "interactive-cli"
+  ],
+  "author": "Vanessa Wang",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vvanessaww/pkg-tracker.git"
+  },
+  "homepage": "https://github.com/vvanessaww/pkg-tracker#readme",
+  "bugs": {
+    "url": "https://github.com/vvanessaww/pkg-tracker/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "commander": "^11.1.0",
+    "googleapis": "^128.0.0",
+    "better-sqlite3": "^9.2.2",
+    "chalk": "^4.1.2",
+    "ora": "^5.4.1",
+    "inquirer": "^8.2.6",
+    "open": "^8.4.2"
+  }
+}

package/src/banner.js

@@ -0,0 +1,34 @@
+const chalk = require('chalk');
+
+/**
+ * Display banner with ASCII art
+ */
+function showBanner() {
+  const banner = `
+   ┌──────────────────────────────────────────────────────┐
+   │                                                      │
+   │   📦  ██████╗ ██╗  ██╗ ██████╗                      │
+   │      ██╔══██╗██║ ██╔╝██╔════╝                       │
+   │      ██████╔╝█████╔╝ ██║  ███╗                      │
+   │      ██╔═══╝ ██╔═██╗ ██║   ██║                      │
+   │      ██║     ██║  ██╗╚██████╔╝                      │
+   │      ╚═╝     ╚═╝  ╚═╝ ╚═════╝                       │
+   │                                                      │
+   │      ████████╗██████╗  █████╗  ██████╗██╗  ██╗      │
+   │      ╚══██╔══╝██╔══██╗██╔══██╗██╔════╝██║ ██╔╝      │
+   │         ██║   ██████╔╝███████║██║     █████╔╝       │
+   │         ██║   ██╔══██╗██╔══██║██║     ██╔═██╗       │
+   │         ██║   ██║  ██║██║  ██║╚██████╗██║  ██╗      │
+   │         ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝      │
+   │                                                      │
+   │      Track all your packages in one place 📦         │
+   │                                                      │
+   └──────────────────────────────────────────────────────┘
+  `;
+  
+  console.log(chalk.cyan(banner));
+}
+
+module.exports = {
+  showBanner
+};