soleprint/artery/veins/google/README.md

Google Vein

OAuth2-based connector for Google APIs (Sheets, Drive).

Status: DEVELOPMENT

Setup

1. Create Google Cloud project and OAuth2 credentials:

   • Go to https://console.cloud.google.com/apis/credentials
   • Create OAuth 2.0 Client ID (Web application)
   • Add authorized redirect URI: https://artery.mcrn.ar/google/oauth/callback
   • Enable Google Sheets API and Google Drive API

2. Copy .env.example to .env and fill in credentials:

   cp .env.example .env
   # Edit .env with your credentials
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Run standalone:

   python run.py
   

OAuth Flow

Unlike Jira/Slack (simple token auth), Google uses OAuth2:

1. Start: Visit /google/oauth/start - redirects to Google login
2. Callback: Google redirects to /google/oauth/callback with code
3. Exchange: Code exchanged for access_token + refresh_token
4. Storage: Tokens saved to storage/tokens_{user_id}.json
5. Use: Subsequent requests use stored tokens
6. Refresh: Expired tokens auto-refreshed using refresh_token

Endpoints

Authentication

• GET /google/health - Check auth status
• GET /google/oauth/start - Start OAuth flow
• GET /google/oauth/callback - OAuth callback (called by Google)
• GET /google/oauth/logout - Clear stored tokens

Google Sheets

• GET /google/spreadsheets/{id} - Get spreadsheet metadata
• GET /google/spreadsheets/{id}/sheets - List all sheets
• GET /google/spreadsheets/{id}/values?range=Sheet1!A1:D10 - Get cell values

All endpoints support ?text=true for LLM-friendly text output.

Architecture

core/               # Isolated - can run without FastAPI
├── oauth.py        # Google OAuth2 client
├── sheets.py       # Google Sheets API client
└── config.py       # Settings

api/                # FastAPI wrapper
└── routes.py       # Endpoints

models/             # Data models
├── spreadsheet.py  # Pydantic models
└── formatter.py    # Text output

storage/            # Token persistence (gitignored)

Token Storage

For development/demo: File-based storage in storage/

For production: Override TokenStorage in vein/oauth.py:

• Redis for scalability
• Database for audit trail
• Per-user tokens when integrated with auth system

Future APIs

• Google Drive (file listing, download)
• Gmail (read messages)
• Calendar (events)

Each API gets its own client in core/ (e.g., core/drive.py).