pkg-track 1.0.0 → 1.0.2

package/README.md

@@ -1,4 +1,4 @@
-# 📦 pkg-tracker
+# 📦 pkg-track
 
 **Track all your packages in one place.** No more digging through emails!
 
@@ -29,50 +29,65 @@ Interactive CLI that scans your Gmail for shipping confirmations and lets you tr
 
 ## 📋 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
+- **Gmail account**
 
 **Supported Platforms:**
 - ✅ macOS (10.15+)
 - ✅ Linux (Ubuntu, Debian, Fedora, etc.)
 - ✅ Windows 10/11 (with Node.js)
 
-## 🚀 Installation
+## 🚀 Quick Start
+
+### 1. Install
 
-**Option 1: NPM (Recommended)**
+**From npm (recommended):**
 ```bash
-npm install -g pkg-tracker
+npm install -g pkg-track
 ```
 
-**Option 2: From Source**
+**From git (for development):**
 ```bash
-git clone https://github.com/vvanessaww/pkg-tracker.git
-cd pkg-tracker
-npm install
-npm link
+# Requires build tools (python, make, gcc/clang)
+npm install -g git+https://github.com/vvanessaww/pkg-track.git
 ```
 
-**Verify installation:**
+> ⚠️ **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. One-Time Gmail Setup (~5 minutes)
+
+**Quick Google Cloud setup** (sounds scary, but it's just clicking through):
+
 ```bash
-pkg --version
-```
+# 1. Create the config directory
+mkdir -p ~/.pkg-tracker
 
-## Setup
+# 2. Follow these steps to get your credentials:
+```
 
-### 1. Get Gmail API Credentials
+**Google Cloud Console** (one-time):
+1. Go to https://console.cloud.google.com/apis/credentials
+2. **Create Project** → Name: `pkg-track` (or anything) → **Create**
+3. **Enable APIs** → Search **"Gmail API"** → **Enable**
+4. **Configure Consent Screen**:
+   - User Type: **External** → **Create**
+   - App name: `pkg-track`
+   - User support email: (your email)
+   - Developer contact: (your email)
+   - **Save and Continue** (skip scopes/test users)
+5. **Credentials** → **Create Credentials** → **OAuth client ID**:
+   - Application type: **Desktop app**
+   - Name: `pkg-track`
+   - **Create**
+6. **Download JSON** (click the download icon ⬇️)
+7. **Move the file**:
+   ```bash
+   mv ~/Downloads/client_secret_*.json ~/.pkg-tracker/credentials.json
+   ```
 
-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`
+**Why this setup?** Google requires each user to create their own OAuth app for Gmail access. This ensures your data stays private and you control the permissions. Your credentials never leave your computer.
 
-### 2. Initialize
+### 3. Initialize
 
 ```bash
 pkg init
@@ -80,9 +95,11 @@ pkg init
 
 This will:
 - Open your browser for Gmail authorization
-- Save access token for future use
+- Save access token locally
 - Create local database
 
+**That's it!** You only need to do this once.
+
 ## Usage
 
 ### Scan email for packages
@@ -220,18 +237,31 @@ Perfect for cleaning up delivered packages or removing things you're no longer t
 - `~/.pkg-tracker/packages.db` - SQLite database of your packages
 
 **Revoking access:**
-If you want to stop using pkg-tracker:
+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 credentials not found"
 
 **Problem:** You see `⚠️ Gmail OAuth credentials not found.`
 
 **Solution:**
-1. Make sure you've created OAuth credentials in Google Cloud Console
+1. Make sure you've created OAuth credentials in Google Cloud Console (see [Quick Start](#-quick-start))
 2. Download the credentials JSON file
 3. Save it to the correct location:
    ```bash
@@ -276,13 +306,9 @@ If you want to stop using pkg-tracker:
 
 **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
+npm uninstall -g pkg-track
+npm install -g pkg-track
 ```
 
 ### "Permission denied" on macOS/Linux
@@ -355,7 +381,7 @@ pkg sync
    ```
 
 3. **Open an issue:**
-   - Visit: https://github.com/vvanessaww/pkg-tracker/issues
+   - Visit: https://github.com/vvanessaww/pkg-track/issues
    - Include: OS, Node.js version, error message, steps to reproduce
 
 ## Roadmap

package/bin/cli.js

@@ -13,7 +13,7 @@ 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'));
+  console.error(chalk.cyan('https://github.com/vvanessaww/pkg-track/issues\n'));
   process.exit(1);
 });
 
@@ -21,7 +21,7 @@ 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'));
+  console.error(chalk.cyan('https://github.com/vvanessaww/pkg-track/issues\n'));
   process.exit(1);
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pkg-track",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Track all your packages in one place - UPS, FedEx, USPS, Amazon. Interactive CLI with Gmail integration.",
   "main": "src/index.js",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "scripts": {
     "start": "node bin/cli.js",
-    "test": "node test/parser.test.js"
+    "test": "node test/parser.test.js",
+    "install": "node -e \"console.log('Installing pkg-track...')\" || true"
   },
   "keywords": [
     "package",
@@ -32,22 +33,22 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/vvanessaww/pkg-tracker.git"
+    "url": "https://github.com/vvanessaww/pkg-track.git"
   },
-  "homepage": "https://github.com/vvanessaww/pkg-tracker#readme",
+  "homepage": "https://github.com/vvanessaww/pkg-track#readme",
   "bugs": {
-    "url": "https://github.com/vvanessaww/pkg-tracker/issues"
+    "url": "https://github.com/vvanessaww/pkg-track/issues"
   },
   "engines": {
     "node": ">=14.0.0"
   },
   "dependencies": {
+    "better-sqlite3": "^12.6.2",
+    "chalk": "^4.1.2",
     "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"
+    "open": "^8.4.2",
+    "ora": "^5.4.1"
   }
 }