feat: Gmail Integration

[research-developer]

Overview

Add Gmail integration via Cloud Pub/Sub for email-triggered actions.

Push Notifications via Pub/Sub

Gmail uses Google Cloud Pub/Sub (not traditional webhooks):

Setup

1. Create Pub/Sub topic
2. Grant gmail-api-push@system.gserviceaccount.com publish rights
3. Call users.watch() to start notifications
4. Watch expires after 7 days (refresh daily)

Payload Structure

{
  "message": {
    "data": "base64_encoded_data",
    "messageId": "xxx",
    "publishTime": "2024-01-01T00:00:00Z"
  },
  "subscription": "projects/xxx/subscriptions/xxx"
}

Decoded Data

{
  "emailAddress": "user@example.com",
  "historyId": "123456789"
}

Polling via History API

Efficient incremental sync:

• GET /gmail/v1/users/me/history?startHistoryId=xxx
• Filter by historyTypes: messageAdded, labelAdded
• Store historyId between polls

OAuth Scopes

• gmail.readonly - Read only
• gmail.modify - Read + modify labels
• gmail.send - Send emails

Tasks

• Implement GmailPoller using History API
• Add Pub/Sub webhook handler
• OAuth 2.0 flow for Gmail access
• Watch for PR notification emails
• Extract PR URLs from emails

Use Cases

1. Email Triggers: Process PR review request emails
2. Digest: Summarize PR emails into daily digest
3. Auto-Reply: Draft PR review responses
4. Notifications: Email summaries of PR activity