# 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
```