pkg-track 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-02-21
+
+### 🎉 Initial Release
+
+**Features:**
+- 📧 Gmail integration with OAuth - scan emails for shipping confirmations
+- 📦 Support for UPS, FedEx, USPS, and Amazon Logistics tracking
+- 🎮 Interactive CLI with ASCII art banner
+- 🔍 Smart tracking number extraction from emails
+- 🌐 Auto-open tracking pages in browser
+- 🗑️ Interactive package cleanup (remove old/delivered packages)
+- ➕ Manual package entry with carrier auto-detection
+- 📄 Pagination (5 packages per page) for easy navigation
+- 📅 Shows last email date for each package
+
+**Commands:**
+- `pkg init` - Set up Gmail OAuth (one-time)
+- `pkg sync` - Scan Gmail for packages (customizable date range)
+- `pkg open` - Interactive menu to select and track packages
+- `pkg add` - Manually add tracking numbers
+- `pkg clean` - Remove packages interactively
+
+**Security:**
+- 🔒 Read-only Gmail access (cannot send/delete emails)
+- 💾 All data stored locally in `~/.pkg-tracker/`
+- 🔐 Secure file permissions (0600/0700)
+- ✅ Input validation and sanitization
+- 🚫 No telemetry or external data transmission
+
+**Privacy:**
+- Local-only storage
+- No external tracking or analytics
+- Revocable OAuth access
+- Secure credential handling
+
+### Technical Details
+- Node.js 14+ required
+- Dependencies: commander, googleapis, better-sqlite3, chalk, ora, inquirer, open
+- Cross-platform support (macOS, Linux, Windows)
+- SQLite database for local package storage
+
+---
+
+## Future Releases
+
+See [GitHub Issues](https://github.com/vvanessaww/pkg-tracker/issues) for planned features and improvements.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to providing a friendly, safe, and welcoming environment for all contributors, regardless of experience level, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other similar characteristics.
+
+## Our Standards
+
+**Examples of behavior that contributes to a positive environment:**
+
+- Being respectful and considerate in communication
+- Welcoming newcomers and helping them get started
+- Accepting constructive criticism gracefully
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+**Examples of unacceptable behavior:**
+
+- Harassment, trolling, insulting/derogatory comments
+- Publishing others' private information without permission
+- Personal or political attacks
+- Any conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by:
+- Opening an issue with the "conduct" label
+- Contacting the project maintainer directly
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Scope
+
+This Code of Conduct applies within all project spaces (GitHub issues, pull requests, discussions) and in public spaces when an individual is representing the project or its community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.0.
+
+---
+
+**TL;DR:** Be kind, be helpful, be professional. We're all here to build something useful together. 🤝

package/CONTRIBUTING.md

@@ -0,0 +1,157 @@
+# Contributing to pkg-tracker
+
+First off, thanks for taking the time to contribute! 🎉
+
+## How Can I Contribute?
+
+### 🐛 Reporting Bugs
+
+Before creating bug reports, please check existing issues to avoid duplicates.
+
+**When submitting a bug report, include:**
+- **OS & Node.js version** (`node --version`)
+- **Steps to reproduce** the issue
+- **Expected vs actual behavior**
+- **Error messages** (if any)
+- **Screenshots** (if relevant)
+
+### 💡 Suggesting Features
+
+Feature suggestions are welcome! Please:
+- Check existing issues first
+- Explain the use case clearly
+- Describe how it would work
+- Consider if it fits the project's scope (simple, focused CLI)
+
+### 🔧 Pull Requests
+
+**Good first issues:**
+- Bug fixes
+- Documentation improvements
+- Additional carrier support (DHL, OnTrac, etc.)
+- Better error messages
+- Test coverage
+
+**Before submitting a PR:**
+
+1. **Fork** the repo and create your branch from `master`
+2. **Install** dependencies: `npm install`
+3. **Test** your changes thoroughly
+4. **Commit** with clear messages (see [Commit Guidelines](#commit-guidelines))
+5. **Push** to your fork and submit a PR
+
+### 📝 Commit Guidelines
+
+Use clear, descriptive commit messages:
+
+```
+Add support for DHL tracking numbers
+
+- Added DHL regex pattern to parser.js
+- Updated README with DHL info
+- Added tests for DHL validation
+```
+
+**Format:**
+- First line: Brief summary (50 chars max)
+- Blank line
+- Detailed description (if needed)
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR-USERNAME/pkg-tracker.git
+cd pkg-tracker
+
+# Install dependencies
+npm install
+
+# Link for local testing
+npm link
+
+# Test your changes
+pkg sync
+pkg open
+```
+
+## Code Style
+
+- Use **descriptive variable names**
+- Add **comments** for complex logic
+- Follow existing **code structure**
+- Keep functions **focused and small**
+- Use **async/await** over callbacks
+
+## Project Structure
+
+```
+pkg-tracker/
+├── bin/
+│   └── cli.js          # Main CLI entry point
+├── src/
+│   ├── banner.js       # ASCII art banner
+│   ├── db.js           # SQLite database layer
+│   ├── gmail.js        # Gmail OAuth & sync
+│   ├── open.js         # Interactive package opener
+│   ├── parser.js       # Tracking number extraction
+│   └── tracker.js      # Manual package entry
+├── README.md
+├── QUICKSTART.md
+└── package.json
+```
+
+## Adding a New Carrier
+
+Want to add support for DHL, OnTrac, or another carrier?
+
+1. **Add regex pattern** in `src/parser.js`:
+   ```javascript
+   dhl: {
+     pattern: /\b(\d{10,11})\b/g,
+     carrier: 'DHL'
+   }
+   ```
+
+2. **Add validation** in `isValidTrackingNumber()`:
+   ```javascript
+   if (carrierKey === 'dhl') {
+     return number.length === 10 || number.length === 11;
+   }
+   ```
+
+3. **Add tracking URL** in `src/open.js`:
+   ```javascript
+   'DHL': `https://www.dhl.com/track?tracking-id=${trackingNumber}`
+   ```
+
+4. **Update supported carriers** in all modules (open.js, tracker.js, db.js)
+
+5. **Test** with real tracking numbers
+
+6. **Update docs** (README.md)
+
+## Testing
+
+Currently manual testing. We'd love help adding automated tests!
+
+**Test checklist:**
+- [ ] `pkg init` - OAuth flow works
+- [ ] `pkg sync` - Finds packages in Gmail
+- [ ] `pkg open` - Interactive menu works, opens browser
+- [ ] `pkg add` - Manual entry with validation
+- [ ] `pkg clean` - Package removal works
+- [ ] Edge cases: no packages, invalid tracking numbers, no credentials
+
+## Questions?
+
+- Open an issue with the "question" label
+- Tag @vvanessaww in discussions
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+**Thank you for contributing!** 🎉📦

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vanessa Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISH.md

@@ -0,0 +1,188 @@
+# 📦 Publishing to npm - Step by Step Guide
+
+## ✅ Pre-publish Checklist (COMPLETED)
+
+- ✅ Security audit passed
+- ✅ `.npmignore` configured
+- ✅ Secure file permissions
+- ✅ Input validation
+- ✅ Privacy documentation
+- ✅ Package metadata complete
+- ✅ LICENSE added (MIT)
+- ✅ CHANGELOG.md created
+- ✅ README polished with troubleshooting
+- ✅ CONTRIBUTING.md added
+- ✅ CODE_OF_CONDUCT.md added
+- ✅ Tests written and passing (13/13)
+- ✅ Global error handlers
+- ✅ Dry run successful (20.5 KB package)
+- ✅ Git tag v1.0.0 created
+
+## 🚀 Publishing Steps
+
+### Step 1: Create npm Account (if you don't have one)
+
+1. Go to https://www.npmjs.com/signup
+2. Create account with email/password
+3. Verify your email address
+
+### Step 2: Login to npm CLI
+
+```bash
+npm login
+```
+
+You'll be prompted for:
+- Username
+- Password
+- Email (public)
+- One-time password (if 2FA enabled)
+
+**Verify you're logged in:**
+```bash
+npm whoami
+```
+
+### Step 3: Check Package Name Availability
+
+```bash
+npm search pkg-tracker
+```
+
+If `pkg-tracker` is already taken, you have two options:
+1. Choose a different name (e.g., `package-tracker-cli`)
+2. Use a scoped package: `@yourusername/pkg-tracker`
+
+**To use scoped package:**
+Edit `package.json`:
+```json
+{
+  "name": "@yourusername/pkg-tracker",
+  ...
+}
+```
+
+### Step 4: Final Verification
+
+**Test the package locally:**
+```bash
+# Test from tarball
+npm install -g ./pkg-tracker-1.0.0.tgz
+pkg --version
+pkg --help
+
+# Uninstall test version
+npm uninstall -g pkg-tracker
+```
+
+**Run tests:**
+```bash
+npm test
+```
+
+### Step 5: Publish to npm! 🎉
+
+**For public package (FREE):**
+```bash
+npm publish
+```
+
+**For scoped package:**
+```bash
+npm publish --access public
+```
+
+### Step 6: Verify Publication
+
+1. Visit: https://www.npmjs.com/package/pkg-tracker
+2. Check that README displays correctly
+3. Verify version is 1.0.0
+4. Test installation:
+   ```bash
+   npm install -g pkg-tracker
+   pkg --version
+   ```
+
+## 🎊 Post-Publication
+
+### Update README with npm badge
+
+Add to top of README.md:
+```markdown
+[![npm version](https://badge.fury.io/js/pkg-tracker.svg)](https://www.npmjs.com/package/pkg-tracker)
+[![downloads](https://img.shields.io/npm/dm/pkg-tracker.svg)](https://www.npmjs.com/package/pkg-tracker)
+```
+
+### Announce it!
+
+- Tweet about it
+- Post on Reddit (r/node, r/javascript)
+- Share on Hacker News
+- LinkedIn post
+- Add to your portfolio
+
+### Monitor
+
+- Watch for issues on GitHub
+- Check npm download stats
+- Respond to user feedback
+
+## 🔄 Future Updates
+
+When you make changes:
+
+1. Update code
+2. Update CHANGELOG.md
+3. Bump version in package.json:
+   ```bash
+   npm version patch  # 1.0.0 -> 1.0.1 (bug fixes)
+   npm version minor  # 1.0.0 -> 1.1.0 (new features)
+   npm version major  # 1.0.0 -> 2.0.0 (breaking changes)
+   ```
+4. Push changes + tags:
+   ```bash
+   git push && git push --tags
+   ```
+5. Publish update:
+   ```bash
+   npm publish
+   ```
+
+## 🆘 Troubleshooting
+
+### "You do not have permission to publish"
+
+- Check you're logged in: `npm whoami`
+- Check package name isn't taken: `npm info pkg-tracker`
+- Use scoped package if name is taken
+
+### "npm ERR! 403 Forbidden"
+
+- Package name is taken - choose different name
+- Or use scoped package: `@yourusername/pkg-tracker`
+
+### "npm ERR! need auth"
+
+- Run `npm login` first
+- Make sure you verified your email
+
+### Want to unpublish?
+
+**Within 72 hours:**
+```bash
+npm unpublish pkg-tracker@1.0.0
+```
+
+**After 72 hours:**
+- Can only deprecate: `npm deprecate pkg-tracker@1.0.0 "Message"`
+- Contact npm support for removal
+
+## 📊 Package Stats
+
+After publishing, track stats at:
+- npm page: https://www.npmjs.com/package/pkg-tracker
+- npm stats: https://npm-stat.com/charts.html?package=pkg-tracker
+
+---
+
+**Good luck! 🚀📦**

package/QUICKSTART.md

@@ -0,0 +1,136 @@
+# 📦 Quick Start Guide
+
+Get up and running with pkg-tracker in 5 minutes!
+
+## Prerequisites
+
+- Node.js 14+ ([Download here](https://nodejs.org/))
+- Gmail account
+- Google Cloud account (free tier)
+
+## Installation
+
+```bash
+npm install -g pkg-tracker
+```
+
+## First Time Setup (5 minutes)
+
+### 1. Get Gmail API Credentials
+
+**a) Create Google Cloud Project:**
+1. Visit https://console.cloud.google.com/
+2. Click "Select a project" → "New Project"
+3. Name it "pkg-tracker" → Create
+
+**b) Enable Gmail API:**
+1. In the project, go to "APIs & Services" → "Library"
+2. Search for "Gmail API"
+3. Click it → Enable
+
+**c) Create OAuth Credentials:**
+1. Go to "APIs & Services" → "Credentials"
+2. Click "Create Credentials" → "OAuth client ID"
+3. If prompted, configure OAuth consent screen:
+   - User Type: External
+   - App name: pkg-tracker
+   - User support email: your email
+   - Developer contact: your email
+   - Save
+4. Back to "Create OAuth client ID":
+   - Application type: **Desktop app**
+   - Name: pkg-tracker
+   - **Authorized redirect URIs**: Add `http://localhost:3000`
+   - Create
+5. Download the JSON file (click download icon)
+6. Save it as `~/.pkg-tracker/credentials.json`:
+   ```bash
+   mkdir -p ~/.pkg-tracker
+   mv ~/Downloads/client_secret_*.json ~/.pkg-tracker/credentials.json
+   ```
+
+### 2. Initialize pkg
+
+```bash
+pkg init
+```
+
+This will:
+1. Open your browser
+2. Ask you to authorize Gmail access (read-only)
+3. Automatically capture the authorization (no code to paste!)
+4. Save the token for future use
+
+The browser will show a success page when done.
+
+### 3. Scan Your Email
+
+```bash
+pkg sync
+```
+
+This searches your last 30 days of email for shipping confirmations and extracts tracking numbers.
+
+### 4. Open Your Packages
+
+```bash
+pkg open
+```
+
+## Daily Usage
+
+```bash
+# Scan for new packages
+pkg sync
+
+# Open packages interactively (select and track in browser)
+pkg open
+
+# Manually add a tracking number (interactive)
+pkg add 1Z999AA10123456784
+
+# Remove old/delivered packages
+pkg clean
+```
+
+## Troubleshooting
+
+**"Gmail credentials not found"**
+- Make sure `~/.pkg-tracker/credentials.json` exists
+- Run `pkg init` again
+
+**"No packages found"**
+- Your emails might not match the search terms
+- Try `pkg sync --days 90` to scan further back
+- Check if you have shipping confirmation emails in Gmail
+
+**"Invalid tracking number"**
+- Not all carriers are supported yet
+- Use `pkg add` to manually add if auto-detection fails
+
+## What Gets Scanned?
+
+The tool searches for emails with these terms:
+- "shipped"
+- "tracking"
+- "delivered"  
+- "out for delivery"
+- "order confirmation"
+
+From senders like:
+- Amazon
+- Target
+- Walmart
+- Etsy
+- eBay
+- Best Buy
+- Nike
+- Adidas
+- And many more!
+
+## Privacy Note
+
+- All data stays on your computer (`~/.pkg-tracker/`)
+- Gmail token is read-only (can't send/delete emails)
+- No external tracking APIs called (yet)
+- No data sent to any server