gmail-hook/AGENTS.md

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

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 — how agents use Gmail (commands, audit, recipes, ideas).
• docs/development.md — receipt pipeline, parsers, PocketBase, Google scope change, adding providers.

Run

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