# 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:
   ```bash
   cp .env.example .env
   # Edit .env with your credentials
   ```

3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

4. Run standalone:
   ```bash
   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`).