{"_id":"@alfayad/gmail-cleaner","_rev":"2-91735dd39edbd4b8030599cbe6ee5e33","name":"@alfayad/gmail-cleaner","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@alfayad/gmail-cleaner","version":"1.0.0","keywords":["gmail","email","cleaner","inbox","bulk-delete","google","cli"],"author":{"name":"Alfayad-s"},"license":"MIT","_id":"@alfayad/gmail-cleaner@1.0.0","maintainers":[{"name":"alfayad","email":"alfayadshameer056@gmail.com"}],"homepage":"https://github.com/Alfayad-s/gmail-cleaner#readme","bugs":{"url":"https://github.com/Alfayad-s/gmail-cleaner/issues"},"bin":{"gmail-cleaner":"dist/cli.cjs"},"dist":{"shasum":"3258ea5be41b7e0e90740d83d046dd0da5be601c","tarball":"https://registry.npmjs.org/@alfayad/gmail-cleaner/-/gmail-cleaner-1.0.0.tgz","fileCount":15,"integrity":"sha512-vrJgGPyneHafNLxdCIcDDAun9L+ARF0ZHH+w40i8vZgI6m3IP/fV94cqaeTE+W/jK2wO6fHU4G66J4v7MBtZ3A==","signatures":[{"sig":"MEUCIEc9pcdsZZ/lszJhVGGHiSjc8jSzPgQk0pAgXx14RG+9AiEAqjiDK2cAhZx0c/TnHW/8NiLpg7It1FpDU89T2Nfi7Ew=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":240001},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./package.json":"./package.json"},"gitHead":"80a0eae79a1fe7a1e50c83245addcca0897ad7d7","scripts":{"dev":"tsup --watch","build":"tsup","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && chmod +x dist/cli.cjs dist/cli.js"},"_npmUser":{"name":"alfayad","email":"alfayadshameer056@gmail.com"},"repository":{"url":"git+https://github.com/Alfayad-s/gmail-cleaner.git","type":"git"},"_npmVersion":"11.11.0","description":"Securely clean your Gmail inbox by searching and bulk trashing or deleting emails","directories":{},"_nodeVersion":"25.8.0","dependencies":{"ora":"^8.2.0","zod":"^3.24.2","chalk":"^5.4.1","inquirer":"^12.4.2","commander":"^13.1.0","googleapis":"^148.0.0","cli-progress":"^3.12.0","@google-cloud/local-auth":"^3.0.1"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","typescript":"^5.8.2","@types/node":"^22.13.10"},"_npmOperationalInternal":{"tmp":"tmp/gmail-cleaner_1.0.0_1781636356043_0.06164290470258793","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@alfayad/gmail-cleaner","version":"1.0.1","description":"Securely clean your Gmail inbox by searching and bulk trashing or deleting emails","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","bin":{"gmail-cleaner":"dist/cli.cjs"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./package.json":"./package.json"},"scripts":{"build":"tsup && node scripts/add-cli-shebang.mjs","dev":"tsup --watch","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && chmod +x dist/cli.cjs dist/cli.js"},"engines":{"node":">=18"},"keywords":["gmail","email","cleaner","inbox","bulk-delete","google","cli"],"author":{"name":"Alfayad-s"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Alfayad-s/gmail-cleaner.git"},"bugs":{"url":"https://github.com/Alfayad-s/gmail-cleaner/issues"},"homepage":"https://github.com/Alfayad-s/gmail-cleaner#readme","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"dependencies":{"@google-cloud/local-auth":"^3.0.1","chalk":"^5.4.1","cli-progress":"^3.12.0","commander":"^13.1.0","googleapis":"^148.0.0","inquirer":"^12.4.2","ora":"^8.2.0","zod":"^3.24.2"},"devDependencies":{"@types/node":"^22.13.10","tsup":"^8.4.0","typescript":"^5.8.2"},"gitHead":"fbf00bcae75160c8a2810a3674ce67f7795d2bb4","_id":"@alfayad/gmail-cleaner@1.0.1","_nodeVersion":"25.8.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-ssOseHfgTbGXVxNztp9G1CmSQMewY/74EU9E2Lek5tsAlik+cWuHE07krlSrDJALR/61xQgF6mFSCN9uF8cCfw==","shasum":"ac91208712eae6268f247745dbbbb27a57bda8d0","tarball":"https://registry.npmjs.org/@alfayad/gmail-cleaner/-/gmail-cleaner-1.0.1.tgz","fileCount":15,"unpackedSize":247747,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCjARNPaDpK0a/I+V+oMvNZHBGHNE2rewVTBTIKv0z99AIgC+V4pHZCIctoKDawcU5rZkG+HErEy7rTJRGnQhiIH5Q="}]},"_npmUser":{"name":"alfayad","email":"alfayadshameer056@gmail.com"},"directories":{},"maintainers":[{"name":"alfayad","email":"alfayadshameer056@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gmail-cleaner_1.0.1_1781781062884_0.3633211038578281"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-16T18:59:15.846Z","modified":"2026-06-18T11:11:03.142Z","1.0.0":"2026-06-16T18:59:16.263Z","1.0.1":"2026-06-18T11:11:03.018Z"},"bugs":{"url":"https://github.com/Alfayad-s/gmail-cleaner/issues"},"author":{"name":"Alfayad-s"},"license":"MIT","homepage":"https://github.com/Alfayad-s/gmail-cleaner#readme","keywords":["gmail","email","cleaner","inbox","bulk-delete","google","cli"],"repository":{"type":"git","url":"git+https://github.com/Alfayad-s/gmail-cleaner.git"},"description":"Securely clean your Gmail inbox by searching and bulk trashing or deleting emails","maintainers":[{"name":"alfayad","email":"alfayadshameer056@gmail.com"}],"readme":"# @alfayad/gmail-cleaner\n\nSecurely clean your Gmail inbox by searching and bulk trashing or permanently deleting emails using [Gmail search queries](https://support.google.com/mail/answer/7190).\n\n> **Warning:** Always run with `--dry-run` first (the default). Permanent `DELETE` cannot be undone. Prefer `TRASH` when possible — messages stay recoverable from Gmail Trash for about 30 days.\n\n## Features\n\n- Gmail search query support (same syntax as the Gmail search box)\n- **Dry-run by default** — preview matching message counts before any changes\n- Trash (`TRASH`) or permanently delete (`DELETE`)\n- OAuth 2.0 authentication with token persistence\n- Paginated search, batch processing, rate limiting, and retry on quota errors\n- Beautiful CLI with spinner, progress bar, and interactive confirmation\n- Programmatic API for use in scripts\n\n## Prerequisites\n\n- Node.js 18+\n- A Google Cloud project with the Gmail API enabled\n- OAuth 2.0 Desktop client credentials\n\n## Google Cloud setup\n\n### 1. Create a project\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com/).\n2. Create a new project (or select an existing one).\n\n### 2. Enable the Gmail API\n\n1. Open **APIs & Services → Library**.\n2. Search for **Gmail API** and click **Enable**.\n\n### 3. Configure OAuth consent screen\n\n1. Go to **APIs & Services → OAuth consent screen**.\n2. Choose **External** (unless you use Google Workspace internally).\n3. Fill in the required app information.\n4. On **Scopes**, add: `https://www.googleapis.com/auth/gmail.modify`\n5. On **Test users**, add your Gmail address (required while the app is in Testing mode).\n6. Save.\n\n### 4. Create OAuth credentials\n\n1. Go to **APIs & Services → Credentials**.\n2. Click **Create Credentials → OAuth client ID**.\n3. Application type: **Desktop app**.\n4. Download the JSON file and save it to your config directory:\n\n```bash\nmkdir -p ~/.config/gmail-cleaner\ncp ~/Downloads/client_secret_*.json ~/.config/gmail-cleaner/credentials.json\n```\n\nFor local development you can also keep `credentials.json` in the project folder and pass `--credentials ./credentials.json`.\n\n> **Redirect URI:** Desktop credentials should include `http://localhost:3000/oauth2callback` (used by `@google-cloud/local-auth`). If missing, add it under your OAuth client's authorized redirect URIs.\n\n### 5. First-time authentication\n\nOn first run, a browser window opens for Google sign-in. The OAuth token is saved to `token.json` for subsequent runs.\n\nTo re-authenticate (e.g. after `invalid_grant` errors), delete `token.json` and run again.\n\n## Installation\n\n```bash\n# From npm (when published)\nnpm install -g @alfayad/gmail-cleaner\n\n# From source\ngit clone <repo-url>\ncd gmail-inbox-cleaner\nnpm install\nnpm run build\nnpm link   # optional: install CLI globally\n```\n\n## Configuration\n\nCopy `.env.example` to `.env` or set environment variables:\n\n```bash\nGMAIL_CLEANER_CREDENTIALS_PATH=~/.config/gmail-cleaner/credentials.json\nGMAIL_CLEANER_TOKEN_PATH=~/.config/gmail-cleaner/token.json\nGMAIL_CLEANER_BATCH_DELAY_MS=250\n```\n\nCLI flags `--credentials` and `--token` override these paths.\n\n## CLI usage\n\n### Preview (dry-run — default)\n\n```bash\ngmail-cleaner clean --query=\"older_than:1y label:promotions\"\n```\n\n### Trash matching emails\n\n```bash\ngmail-cleaner clean \\\n  --query=\"category:promotions older_than:6m\" \\\n  --no-dry-run\n```\n\n### Permanently delete (irreversible)\n\n```bash\ngmail-cleaner clean \\\n  --query=\"from:newsletter@example.com\" \\\n  --action=DELETE \\\n  --no-dry-run \\\n  --yes\n```\n\n### All options\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-q, --query <string>` | Gmail search query | **required** |\n| `-a, --action <TRASH\\|DELETE>` | Trash or permanently delete | `TRASH` |\n| `--dry-run` | Preview without modifying | `true` |\n| `--no-dry-run` | Apply changes | — |\n| `-y, --yes` | Skip interactive confirmation | `false` |\n| `-b, --batch-size <n>` | Messages per API batch (max 1000) | `500` |\n| `-m, --max-results <n>` | Cap messages processed | unlimited |\n| `--credentials <path>` | OAuth credentials JSON | `~/.config/gmail-cleaner/credentials.json` |\n| `--token <path>` | Saved OAuth token JSON | `~/.config/gmail-cleaner/token.json` |\n\n### Safe query cookbook\n\n| Goal | Example query |\n|------|---------------|\n| Old promotions | `older_than:1y label:promotions` |\n| Promotions category | `category:promotions older_than:6m` |\n| Social updates | `category:social older_than:1y` |\n| Specific sender | `from:newsletter@example.com` |\n| Large attachments | `larger:10M older_than:1y` |\n| Read mail older than 2 years | `is:read older_than:2y` |\n| Unread newsletters | `is:unread label:newsletters` |\n\nAlways preview with `--dry-run` before using `--no-dry-run`.\n\n## Programmatic usage\n\n```typescript\nimport { cleanGmail } from '@alfayad/gmail-cleaner';\n\n// Preview\nconst preview = await cleanGmail({\n  query: 'older_than:1y label:promotions',\n  dryRun: true,\n});\n\nconsole.log(`Matched ${preview.matched} messages`);\n\n// Trash (after verifying count)\nconst result = await cleanGmail({\n  query: 'older_than:1y label:promotions',\n  action: 'TRASH',\n  dryRun: false,\n  batchSize: 500,\n  onProgress: (info) => console.log(info.message),\n});\n\nconsole.log(`Processed ${result.processed}, failed ${result.failed}`);\n```\n\n### API reference\n\n```typescript\ncleanGmail(options: CleanOptions): Promise<CleanResult>\ngetGmailClient(options?): Promise<Gmail>\nlistMessageIds(gmail, query, options?): Promise<{ ids: string[]; total: number }>\n```\n\n`CleanOptions`:\n\n- `query` — Gmail search string (required)\n- `action` — `'TRASH'` | `'DELETE'` (default: `'TRASH'`)\n- `dryRun` — default `true`\n- `batchSize` — default `500`, max `1000`\n- `maxResults` — optional cap\n- `credentialsPath`, `tokenPath` — optional path overrides\n- `onProgress` — progress callback\n\n## Security\n\n- **Never commit** `credentials.json` or `token.json` — they are listed in `.gitignore`.\n- Keep OAuth credentials out of version control and CI logs.\n- Use the minimum scope needed (`gmail.modify`).\n- While your OAuth app is in **Testing** mode, only added test users can authenticate.\n\n## Troubleshooting\n\n### `Credentials file not found`\n\nDownload OAuth Desktop client JSON from Google Cloud Console and save to `~/.config/gmail-cleaner/credentials.json`:\n\n```bash\nmkdir -p ~/.config/gmail-cleaner\ncp ~/Downloads/client_secret_*.json ~/.config/gmail-cleaner/credentials.json\n```\n\nOr pass `--credentials /path/to/file.json`.\n\n### `invalid_grant` or token errors\n\nDelete `token.json` and run again to re-authenticate:\n\n```bash\nrm token.json\ngmail-cleaner clean --query=\"older_than:1y\" --dry-run\n```\n\n### Quota / rate limit errors\n\nThe tool retries with exponential backoff automatically. If errors persist:\n\n- Reduce `--batch-size`\n- Increase `GMAIL_CLEANER_BATCH_DELAY_MS`\n- Wait a few minutes and retry\n\n### `Access blocked: app has not been verified`\n\nYour OAuth app is in Testing mode. Add your account under **OAuth consent screen → Test users**, or publish the app (requires Google verification for sensitive scopes).\n\n### `@google-cloud/local-auth` deprecation\n\nGoogle has deprecated `@google-cloud/local-auth` in favor of `google-auth-library` directly. This package still uses it for the interactive local OAuth flow. Re-authenticate by deleting `token.json` if you encounter auth issues.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm run typecheck\nnode dist/cli.js clean --help\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}