inboxd 1.0.0 → 1.0.2

package/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - run: npm test
+
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CLAUDE.md

@@ -0,0 +1,73 @@
+# inboxd
+
+CLI tool for Gmail monitoring with multi-account support and macOS notifications.
+
+## Quick Reference
+
+```bash
+npm test                    # Run tests
+npm run test:watch          # Watch mode
+inbox setup                 # First-time setup wizard
+inbox auth -a <name>        # Add account
+inbox summary               # Check all inboxes
+inbox check -q              # Background check
+inbox install-service       # Install launchd service (macOS only)
+```
+
+## Architecture
+
+```
+src/
+├── cli.js            # Entry point, command definitions (commander)
+├── gmail-auth.js     # OAuth2 flow, token storage, multi-account management
+├── gmail-monitor.js  # Gmail API: fetch, count, trash, restore
+├── state.js          # Tracks seen emails per account
+├── deletion-log.js   # Logs deleted emails for restore capability
+└── notifier.js       # macOS notifications (node-notifier)
+
+tests/                # Vitest tests with mocked Google APIs
+__mocks__/            # Manual mocks for googleapis, @google-cloud/local-auth
+```
+
+## Tech Stack
+
+- **Runtime**: Node.js 18+ (CommonJS)
+- **Gmail API**: `googleapis`, `@google-cloud/local-auth`
+- **CLI**: `commander`
+- **UI**: `chalk`, `boxen` (ESM packages, loaded via dynamic import)
+- **Notifications**: `node-notifier`
+- **Testing**: `vitest`
+
+## Data Storage
+
+All user data lives in `~/.config/inboxd/`:
+
+| File | Content |
+|------|---------|
+| `credentials.json` | OAuth client ID/secret from Google Cloud |
+| `accounts.json` | `[{ name, email }]` for each linked account |
+| `token-<name>.json` | OAuth refresh/access tokens |
+| `state-<name>.json` | `{ seenEmailIds, lastCheck, lastNotifiedAt }` |
+| `deletion-log.json` | Audit log for deleted emails |
+
+## Code Patterns
+
+- **CommonJS** for all source files
+- **Dynamic import** for ESM-only deps (`chalk`, `boxen`)
+- **Functional style**, no classes
+- **Retry with backoff** in `gmail-monitor.js` for API calls
+- **Silent fail** for missing config files (returns defaults)
+
+## Key Behaviors
+
+- `inbox setup` guides first-time users through credentials and auth
+- `inbox check` marks emails as seen after notifying
+- `inbox delete` logs to `deletion-log.json` before trashing
+- `inbox restore` moves from Trash to Inbox, removes log entry
+- `install-service` generates launchd plist dynamically (macOS only, warns on other platforms)
+
+## OAuth Notes
+
+- Gmail API requires OAuth consent screen with test users for external accounts
+- Tokens auto-refresh; delete token file to force re-auth
+- Credentials can be in project root (dev) or `~/.config/inboxd/` (installed)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Paredes
+
+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/README.md

@@ -0,0 +1,159 @@
+# inboxd
+
+[![npm version](https://img.shields.io/npm/v/inboxd.svg)](https://www.npmjs.com/package/inboxd)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A CLI tool for monitoring Gmail inboxes with multi-account support and macOS notifications.
+
+## Features
+
+- **Multi-account support** - Monitor multiple Gmail accounts from one command
+- **macOS notifications** - Get notified when new emails arrive
+- **Background monitoring** - Run as a launchd service
+- **Delete & restore** - Safely trash emails with undo capability
+- **AI-ready output** - JSON mode for integration with AI agents
+- **Interactive setup** - Guided wizard for first-time configuration
+
+## Installation
+
+```bash
+npm install -g inboxd
+```
+
+## Quick Start
+
+Run the interactive setup wizard:
+
+```bash
+inbox setup
+```
+
+The wizard will guide you through:
+1. Opening Google Cloud Console to create OAuth credentials
+2. Validating and installing your credentials file
+3. Authenticating your first Gmail account
+
+That's it! You're ready to go.
+
+## Manual Setup
+
+If you prefer to set up manually:
+
+### 1. Get Gmail API Credentials
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project and enable the **Gmail API**
+3. Configure OAuth consent screen (add yourself as test user)
+4. Create OAuth credentials (Desktop app)
+5. Download and save as `~/.config/inboxd/credentials.json`:
+
+```bash
+mkdir -p ~/.config/inboxd
+mv ~/Downloads/client_secret_*.json ~/.config/inboxd/credentials.json
+```
+
+### 2. Authenticate
+
+```bash
+inbox auth --account personal
+```
+
+### 3. Check Your Inbox
+
+```bash
+inbox summary
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `inbox setup` | Interactive setup wizard |
+| `inbox auth -a <name>` | Authenticate a Gmail account |
+| `inbox accounts` | List configured accounts |
+| `inbox summary` | Show inbox summary for all accounts |
+| `inbox check` | Check for new emails + send notifications |
+| `inbox check -q` | Silent check (for background use) |
+| `inbox delete --ids <ids>` | Move emails to trash |
+| `inbox restore --last 1` | Restore last deleted email |
+| `inbox deletion-log` | View deletion history |
+| `inbox logout --all` | Remove all accounts |
+| `inbox install-service` | Install background monitoring (macOS) |
+
+## Configuration
+
+All configuration is stored in `~/.config/inboxd/`:
+
+| File | Purpose |
+|------|---------|
+| `credentials.json` | Your OAuth client credentials |
+| `accounts.json` | List of configured accounts |
+| `token-<account>.json` | OAuth tokens per account |
+| `state-<account>.json` | Seen email tracking per account |
+| `deletion-log.json` | Record of deleted emails |
+
+## Background Monitoring
+
+Install as a macOS launchd service to check for new emails periodically:
+
+```bash
+# Install with default 5-minute interval
+inbox install-service
+
+# Or customize the interval
+inbox install-service --interval 10
+```
+
+Manage the service:
+
+```bash
+# Check status
+launchctl list | grep inboxd
+
+# View logs
+tail -f /tmp/inboxd.log
+
+# Stop service
+launchctl unload ~/Library/LaunchAgents/com.danielparedes.inboxd.plist
+```
+
+**Note:** `install-service` is macOS-only. For Linux, use cron:
+```bash
+*/5 * * * * /path/to/node /path/to/inbox check --quiet
+```
+
+## JSON Output
+
+For AI agent integration, use the `--json` flag:
+
+```bash
+inbox summary --json
+```
+
+Or use the `analyze` command for structured output:
+
+```bash
+inbox analyze --count 20
+```
+
+## Troubleshooting
+
+**"credentials.json not found"**
+Run `inbox setup` or manually download OAuth credentials from Google Cloud Console and save to `~/.config/inboxd/credentials.json`.
+
+**"Token expired"**
+Delete the token file and re-authenticate:
+```bash
+rm ~/.config/inboxd/token-<account>.json
+inbox auth -a <account>
+```
+
+**No notifications appearing**
+Check macOS notification settings for Terminal/Node.js in System Preferences > Notifications.
+
+**"install-service is only supported on macOS"**
+The launchd service is macOS-specific. For other platforms, set up a cron job or scheduled task manually.
+
+## License
+
+MIT

package/__mocks__/@google-cloud/local-auth.js

@@ -0,0 +1,11 @@
+const { vi } = require('vitest');
+
+module.exports = {
+  authenticate: vi.fn().mockResolvedValue({
+    credentials: {
+      refresh_token: 'mock-refresh-token',
+      access_token: 'mock-access-token',
+      expiry_date: Date.now() + 3600000
+    }
+  })
+};

package/__mocks__/googleapis.js

@@ -0,0 +1,42 @@
+const { vi } = require('vitest');
+
+const mockGmail = {
+  users: {
+    messages: {
+      list: vi.fn().mockResolvedValue({ data: { messages: [] } }),
+      get: vi.fn().mockResolvedValue({
+        data: {
+          id: '123',
+          threadId: 'thread123',
+          labelIds: ['INBOX'],
+          snippet: 'snippet',
+          payload: { headers: [] }
+        }
+      }),
+      trash: vi.fn().mockResolvedValue({ data: { id: '123', labelIds: ['TRASH'] } }),
+      untrash: vi.fn().mockResolvedValue({ data: { id: '123', labelIds: ['INBOX'] } }),
+      modify: vi.fn().mockResolvedValue({ data: { id: '123' } }),
+    },
+    labels: {
+      get: vi.fn().mockResolvedValue({ data: { messagesUnread: 5 } }),
+      list: vi.fn().mockResolvedValue({ data: { labels: [] } }),
+    },
+    getProfile: vi.fn().mockResolvedValue({ data: { emailAddress: 'test@example.com' } }),
+  }
+};
+
+const mockAuth = {
+  fromJSON: vi.fn().mockReturnValue({}),
+  OAuth2: vi.fn().mockImplementation(() => ({
+    generateAuthUrl: vi.fn().mockReturnValue('http://mock-auth-url'),
+    getToken: vi.fn().mockResolvedValue({ tokens: {} }),
+    setCredentials: vi.fn(),
+  })),
+};
+
+module.exports = {
+  google: {
+    gmail: vi.fn().mockReturnValue(mockGmail),
+    auth: mockAuth,
+  }
+};

package/eslint.config.js

@@ -0,0 +1,75 @@
+/** @type {import('eslint').Linter.Config[]} */
+module.exports = [
+  {
+    files: ['src/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'commonjs',
+      globals: {
+        // Node.js globals
+        require: 'readonly',
+        module: 'readonly',
+        exports: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        process: 'readonly',
+        console: 'readonly',
+        Buffer: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+      },
+    },
+    rules: {
+      // Possible errors
+      'no-undef': 'error',
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' }],
+      'no-constant-condition': 'error',
+      'no-dupe-keys': 'error',
+      'no-duplicate-case': 'error',
+      'no-empty': ['error', { allowEmptyCatch: true }],
+      'no-extra-semi': 'error',
+      'no-unreachable': 'error',
+
+      // Best practices
+      'eqeqeq': ['error', 'always', { null: 'ignore' }],
+      'no-eval': 'error',
+      'no-implied-eval': 'error',
+      'no-return-await': 'error',
+      'no-throw-literal': 'error',
+      'prefer-promise-reject-errors': 'error',
+
+      // Style (minimal)
+      'no-trailing-spaces': 'error',
+      'semi': ['error', 'always'],
+    },
+  },
+  {
+    // Test files use ESM via vitest
+    files: ['tests/**/*.js', '**/*.test.js'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      globals: {
+        describe: 'readonly',
+        it: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+        vi: 'readonly',
+        jest: 'readonly',
+        console: 'readonly',
+        process: 'readonly',
+      },
+    },
+    rules: {
+      'no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    ignores: ['node_modules/**', 'coverage/**', 'dist/**', '__mocks__/**'],
+  },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inboxd",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CLI assistant for Gmail monitoring with multi-account support and AI-ready JSON output",
   "main": "src/cli.js",
   "bin": {
@@ -10,9 +10,17 @@
     "type": "git",
     "url": "git+https://github.com/dparedesi/inboxd.git"
   },
+  "bugs": {
+    "url": "https://github.com/dparedesi/inboxd/issues"
+  },
+  "homepage": "https://github.com/dparedesi/inboxd#readme",
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
+    "lint": "eslint src tests",
     "inbox": "node src/cli.js"
   },
   "keywords": [
@@ -35,9 +43,11 @@
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "googleapis": "^169.0.0",
-    "node-notifier": "^10.0.1"
+    "node-notifier": "^10.0.1",
+    "open": "^10.1.0"
   },
   "devDependencies": {
+    "eslint": "^9.39.2",
     "vitest": "^4.0.16"
   }
 }