nsrbandCursor
ec3b683786
Point agents at the CLI safety rules, mailbox defaults, and the split usage/development guides. Co-authored-by: Cursor <cursoragent@cursor.com>
69 lines
2.5 KiB
Markdown
69 lines
2.5 KiB
Markdown
# Agent notes — gmail-hook
|
||
|
||
npm workspaces: `apps/api`, `apps/web`, `apps/watcher`.
|
||
|
||
Two jobs:
|
||
|
||
1. **E-receipt pipeline** — Gmail Pub/Sub → match/parse → PocketBase `spendings`.
|
||
2. **Agent Gmail toolbox** — CLI to list/read/summarize, archive, label, and create drafts (never send).
|
||
|
||
## Layout
|
||
|
||
| App | Role |
|
||
|---|---|
|
||
| `apps/api` | Google OAuth (`gmail.modify`), session cookie, read-only Gmail HTTP API. Tokens in SQLite `apps/api/data/app.db`. |
|
||
| `apps/web` | React login / inbox UI (Vite). UI is read-only; mutations are CLI-only. |
|
||
| `apps/watcher` | Pub/Sub receipt consumer (gated by `WATCHER_MAILBOXES`) + `npm run gmail` CLI. Reuses the same SQLite tokens. |
|
||
|
||
## Safety (CLI)
|
||
|
||
- **Never send** (`messages.send` / `drafts.send` must not exist in this repo).
|
||
- **Never trash/delete**.
|
||
- Mutating commands (`label`, `archive`, `draft`, `forward`) **require `--reason`**.
|
||
- Confirm with the user before bulk archive (e.g. more than ~20 ids).
|
||
- Google’s consent screen for `gmail.modify` says the app can send/delete; that is Google’s wording — the app still must not.
|
||
|
||
## Default mailbox
|
||
|
||
Resolution order for every script (`--user` optional):
|
||
|
||
1. `--user <email|id>`
|
||
2. `GMAIL_DEFAULT_USER` env
|
||
3. `users.is_default = 1`
|
||
4. Sole connected account
|
||
5. Else fail — set default: `npm run gmail -- accounts --default you@gmail.com`
|
||
|
||
## CLI cheat sheet
|
||
|
||
```bash
|
||
npm run gmail -- accounts
|
||
npm run gmail -- accounts --default you@gmail.com
|
||
npm run gmail -- list --query 'is:unread newer_than:7d' --max 50
|
||
npm run gmail -- read MESSAGE_ID
|
||
npm run gmail -- summarize --query 'in:inbox newer_than:7d' --max 20
|
||
npm run gmail -- labels
|
||
npm run gmail -- label ID1,ID2 --add receipts --reason "tag receipts"
|
||
npm run gmail -- archive ID1,ID2 --reason "newsletter noise"
|
||
npm run gmail -- draft --to a@b.com --subject "Hi" --body "…" --reason "reply draft"
|
||
npm run gmail -- forward MESSAGE_ID --to a@b.com --note "FYI" --reason "forward to accounting"
|
||
npm run gmail -- audit --limit 50
|
||
npm run process-messages -- --query 'newer_than:2d' --dry-run
|
||
```
|
||
|
||
Shared flags: `--user`, `--json`, `--dry-run` (mutations: no Gmail write; audit `status=dry-run`).
|
||
|
||
## Docs
|
||
|
||
- [docs/usage.md](docs/usage.md) — how agents use Gmail (commands, audit, recipes, ideas).
|
||
- [docs/development.md](docs/development.md) — receipt pipeline, parsers, PocketBase, Google scope change, adding providers.
|
||
|
||
## Run
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev # api + web
|
||
# sign in once per Gmail account (re-consent after scope change)
|
||
npm run dev:watcher
|
||
npm test -w watcher
|
||
```
|