migrated all pawprint work

artery/veins/google/README.md

@@ -0,0 +1,90 @@
+# 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`).