Feat/242

[ali-ahnaf]

closes #242

Summary by CodeRabbit

• New Features
  • Added Gmail integration for automatically detecting transaction emails and creating transactions.
  • Added Google OAuth credential setup, Gmail connection status, label browsing, and watch monitoring.
  • Added per-vault Gmail watchers with subject filters, tags, customizable parsing scripts, and sample-email testing.
  • Added automatic Gmail watch renewal and duplicate-message protection.
• Changes
  • Removed Google sign-in from the sign-in and sign-up pages; email and password remain available.
• Documentation
  • Added deployment and Gmail integration setup guides.

[github-actions]

Greetings, @ali-ahnaf. Thy scroll hath arrived unblemished — the runes align and no conflict bars the path. The council shall now convene over its contents, weighing each incantation by candlelight. Tarry a while, brave adventurer; we shall investigate and return to thee with our verdict.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a83107dc-416d-466b-9b83-2f4f5e1ec5c9

📥 Commits

Reviewing files that changed from the base of the PR and between 970e460 and 5f2af51.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (73)

• .agents/rules/loop-engineering.md
• .agents/skills/gmail-parse-script/SKILL.md
• .gitignore
• documentation/deployment.md
• documentation/gmail-integration.md
• packages/api/.env.example
• packages/api/package.json
• packages/api/src/data-source.ts
• packages/api/src/entities/ProcessedGmailMessage.entity.ts
• packages/api/src/entities/User.entity.ts
• packages/api/src/entities/UserOAuthCredential.entity.ts
• packages/api/src/entities/VaultGmailWatcher.entity.ts
• packages/api/src/index.ts
• packages/api/src/middleware/auth.ts
• packages/api/src/migrations/1784395274749-AddUserOAuthCredentials.ts
• packages/api/src/migrations/1784459811702-AddGmailTokensToUserOAuthCredential.ts
• packages/api/src/migrations/1784480567265-Migration.ts
• packages/api/src/migrations/1784541914604-Migration.ts
• packages/api/src/migrations/1784546344887-Migration.ts
• packages/api/src/migrations/1784547526916-Migration.ts
• packages/api/src/repositories/index.ts
• packages/api/src/repositories/processed-gmail-message.repository.ts
• packages/api/src/repositories/user-oauth-credential.repository.ts
• packages/api/src/repositories/users.repository.ts
• packages/api/src/repositories/vault-gmail-watchers.repository.ts
• packages/api/src/routes/auth.routes.ts
• packages/api/src/routes/auth/google-callback.route.ts
• packages/api/src/routes/auth/google-sign-in.route.ts
• packages/api/src/routes/oauth-credentials.routes.ts
• packages/api/src/routes/oauth-credentials/authorize-oauth-credentials.route.ts
• packages/api/src/routes/oauth-credentials/get-gmail-labels.route.ts
• packages/api/src/routes/oauth-credentials/get-gmail-watch.route.ts
• packages/api/src/routes/oauth-credentials/get-oauth-credentials.route.ts
• packages/api/src/routes/oauth-credentials/put-oauth-credentials.route.ts
• packages/api/src/routes/oauth.routes.ts
• packages/api/src/routes/oauth/gmail-webhook.route.ts
• packages/api/src/routes/oauth/google-callback.route.ts
• packages/api/src/routes/vault-watchers.routes.ts
• packages/api/src/routes/vault-watchers/delete-vault-watcher.route.ts
• packages/api/src/routes/vault-watchers/get-vault-watchers.route.ts
• packages/api/src/routes/vault-watchers/put-vault-watcher.route.ts
• packages/api/src/routes/vault-watchers/test-parse-script.route.ts
• packages/api/src/scheduler/gmail-watch-scheduler.ts
• packages/api/src/services/auth.service.ts
• packages/api/src/services/gmail-script-runner.service.ts
• packages/api/src/services/gmail.service.ts
• packages/api/src/services/index.ts
• packages/api/src/services/user-oauth-credential.service.ts
• packages/api/src/services/vault-watchers.service.ts
• packages/api/src/tests/auth.service.google.test.ts
• packages/api/src/tests/gmail-script-runner.service.test.ts
• packages/api/src/tests/gmail-watch-scheduler.test.ts
• packages/api/src/tests/gmail-webhook.util.test.ts
• packages/api/src/tests/gmail.service.test.ts
• packages/api/src/tests/user-oauth-credential.service.test.ts
• packages/api/src/tests/vault-watchers.service.test.ts
• packages/api/src/tests/vaults.service.test.ts
• packages/api/src/utils/gmail-message.util.ts
• packages/api/src/utils/gmail-webhook.util.ts
• packages/api/src/utils/google-oauth.util.ts
• packages/api/src/utils/oauth-credentials-encryption.util.ts
• packages/shared/src/contracts/index.ts
• packages/shared/src/contracts/oauth-credentials.ts
• packages/shared/src/contracts/vault-watchers.ts
• packages/ui/.env.example
• packages/ui/src/app/settings/google-oauth/VaultWatcherCard.tsx
• packages/ui/src/app/settings/google-oauth/page.tsx
• packages/ui/src/app/settings/page.tsx
• packages/ui/src/app/signin/page.tsx
• packages/ui/src/app/signup/page.tsx
• packages/ui/src/components/Dropdown.tsx
• packages/ui/src/components/GoogleSignInButton.tsx
• packages/ui/src/lib/api/ProfileApi.ts

---

📝 Walkthrough

Walkthrough

Adds a Gmail integration with encrypted per-user OAuth, Pub/Sub notifications, Gmail history processing, per-vault scripted transaction watchers, persistence, API routes, renewal scheduling, and a settings UI. It also removes the former Google sign-in flow and adds deployment, Gmail setup, and agent workflow documentation.

Changes

Gmail integration

Layer / File(s)	Summary
Contracts and persistence packages/shared/src/contracts/*, packages/api/src/entities/*, packages/api/src/migrations/*, packages/api/src/data-source.ts	Adds OAuth, Gmail watch, parsed-email, and watcher contracts; stores credentials, watchers, and processed-message records with corresponding migrations and ORM registration.
OAuth credential flow packages/api/src/services/user-oauth-credential.service.ts, packages/api/src/utils/google-oauth.util.ts, packages/api/src/utils/oauth-credentials-encryption.util.ts, packages/api/src/routes/oauth*, packages/api/src/repositories/*oauth*	Adds encrypted credential storage, signed OAuth state, token exchange and refresh, authenticated Google requests, callback handling, and credential endpoints while removing the former Google sign-in flow.
Gmail watch and processing pipeline packages/api/src/services/gmail.service.ts, packages/api/src/utils/gmail-*.util.ts, packages/api/src/routes/oauth/gmail-webhook.route.ts, packages/api/src/scheduler/gmail-watch-scheduler.ts	Adds label-based watch lifecycle management, OIDC webhook verification, Gmail history processing, message extraction, watcher matching, transaction creation, idempotency, and watch renewal.
Vault watcher configuration and parsing packages/api/src/services/vault-watchers.service.ts, packages/api/src/services/gmail-script-runner.service.ts, packages/api/src/routes/vault-watchers/*, packages/api/src/repositories/vault-gmail-watchers.repository.ts, packages/api/src/tests/*watcher*	Adds per-vault watcher CRUD, ownership checks, subject filtering, tag persistence, sandboxed parse-script execution, dry-run testing, and behavioral test coverage.
Settings UI and client API packages/ui/src/app/settings/google-oauth/*, packages/ui/src/lib/api/ProfileApi.ts, packages/ui/src/components/Dropdown.tsx	Adds the OAuth and Gmail watch settings page, watcher editor cards, typed API methods, parse-script testing UI, and dropdown click-away handling.
Operational documentation and configuration documentation/*, .agents/*, packages/api/.env.example, .gitignore, packages/ui/.env.example, packages/api/package.json	Documents deployment and Gmail Pub/Sub setup, defines new environment variables, removes the obsolete OAuth dependency and UI variable, ignores production environment files, and adds agent workflow and parse-script guidance.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related PRs

• ali-ahnaf/pocket_pixel#252 — Both changes modify the earlier Google OAuth sign-in and user identity schema integration.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/242

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

The quest is sealed, @ali-ahnaf! Thy incantations have been woven into the main path. The realm grows stronger for thy contribution — accept the gratitude of this humble keeper of the codex. May thy commits forever merge cleanly, brave adventurer 💰