91 lines
2.5 KiB
Markdown
91 lines
2.5 KiB
Markdown
# 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`).
|