Google Integrations - Quick Start Guide

Synced from the source repositories. Do not edit by hand.

For detailed implementation plan, see: GOOGLE_INTEGRATIONS_PLAN.md

🎯 Goal

Enable Gmail and Google Drive integrations that feed into workflow automation.

📅 Timeline: 7 Days (Nov 18-24)

🏗️ Architecture Overview

Frontend (turfai-sandbox)
  ↓ API Calls
Backend (turfai/dms)
  ↓ OAuth 2.0
Google Cloud Platform (Drive API, Gmail API)

Key Components:

• OAuth service for authentication
• Drive/Gmail services for API calls
• Webhook handlers for auto-triggers
• Workflow integration for file sources

🔐 OAuth Flow

1. User clicks "Connect Google Drive"
2. Frontend opens OAuth popup → Google login
3. User authorizes → Google redirects to callback
4. Backend exchanges code for tokens
5. Tokens stored encrypted in database
6. Frontend shows "Connected" ✅

📁 Google Drive Features

User Can:

• Browse Drive folders
• Search files
• Import PDFs/images to workflows
• Auto-process new files (webhook)

Use Cases:

• Import contracts from shared folder
• Process invoices uploaded to Drive
• Extract data from archived documents

📧 Gmail Features

User Can:

• View emails with attachments
• Import email attachments (PDFs, images)
• Auto-process incoming emails (webhook)
• Filter by sender/subject

Use Cases:

• Process invoice emails automatically
• Extract data from receipts sent via email
• Monitor vendor communications

🔄 Workflow Integration

New Features:

1. External File Input Node

   • Source selector: Upload | Drive | Gmail
   • File picker for each source
   • Auto-download to GCS

2. Workflow Triggers

   • Gmail: "When email from X arrives with attachment"
   • Drive: "When file added to folder Y"
   • Auto-execute workflows

🛠️ Tech Stack

Backend:

• googleapis - Google APIs client
• @google-cloud/storage - GCS uploads
• @google-cloud/pubsub - Webhooks
• Strapi content types for data

Frontend:

• React components for pickers
• OAuth popup handler
• Integration status UI

📦 Database Schema

New Content Types:

1. integrations - Registry of available integrations
2. user-integrations - User connections & tokens
3. workflow-triggers - Auto-execution rules

🔒 Security Checklist

• Tokens encrypted at rest
• OAuth state parameter (CSRF protection)
• Private token fields in API
• Webhook signature verification
• User-scoped access control
• Rate limiting
• HTTPS only

🧪 Testing Plan

Must Test:

• OAuth authorization flow
• Token refresh mechanism
• Drive file import
• Gmail attachment import
• Workflow execution with external files
• Webhook auto-triggers
• Error handling (revoked access, API errors)

📝 Day 1 Checklist (Tomorrow)

Morning

• Review full plan document
• Answer open questions (file size limits, cleanup policy)
• Create/configure GCP project
• Enable Drive & Gmail APIs
• Create OAuth credentials
• Add env variables to .env

Afternoon

• Create Strapi content types (integrations, user-integrations)
• Install googleapis package
• Create GoogleOAuthService
• Create OAuth API routes
• Test OAuth flow with Postman

Evening

• Start GoogleDriveService
• Implement file listing
• Test Drive API calls
• Commit progress

💡 Quick Commands

Start backend:

cd ../turfai/dms
npm run develop

Start frontend:

cd turfai-sandbox
npm run dev

Test OAuth flow:

curl http://localhost:1338/api/oauth/google/authorize

📚 Key Files to Create

Backend (turfai/dms):

src/
  services/
    google-oauth.js         # OAuth flow
    google-drive.js         # Drive API
    gmail.js                # Gmail API
    webhook.js              # Webhook handler
  api/
    oauth/
      routes/google.js
      controllers/google.js
    integrations/
      routes/google-drive.js
      routes/gmail.js
      controllers/google-drive.js
      controllers/gmail.js
    webhooks/
      routes/google.js
      controllers/google.js

Frontend (turfai-sandbox):

src/
  components/
    integrations/
      GoogleOAuthButton.tsx
      GoogleDrivePicker.tsx
      GmailPicker.tsx
      IntegrationCard.tsx
  pages/
    Integrations.tsx (update)
  lib/
    api.ts (add integration APIs)

🎯 Success Criteria

After 7 days, users should be able to:

1. ✅ Connect Google account via OAuth
2. ✅ Browse and import Drive files in workflows
3. ✅ Browse and import Gmail attachments in workflows
4. ✅ Create workflows that auto-execute on new emails
5. ✅ See integration status and manage connections
6. ✅ Disconnect and revoke access

🚀 Let's Ship It!

Tomorrow we start with OAuth setup. Get some rest! 😊