scripts/README.md

# OAuth Credential Refresh Scripts

Automated scripts to keep Google OAuth credentials fresh for VoiceCal.ai deployed on HuggingFace Spaces.

## Quick Start

### 1. Install Dependencies

```bash
# Install Playwright and dependencies
pip install -r scripts/requirements.txt

# Install Playwright browsers
playwright install chromium
```

### 2. Configure Environment Variables

Add to your `.env` file:

```bash
# Option 1: Use dedicated Google credentials
GOOGLE_EMAIL=your-google-email@gmail.com
GOOGLE_PASSWORD=your-google-password

# Option 2: Reuse SMTP credentials (script will use these as fallback)
SMTP_USERNAME=your-google-email@gmail.com
SMTP_PASSWORD=your-smtp-app-password

# Optional: For email notifications on failure
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
```

**Note:** If you already have `SMTP_USERNAME` and `SMTP_PASSWORD` set, you don't need to set `GOOGLE_EMAIL` and `GOOGLE_PASSWORD` separately - the script will use your SMTP credentials for OAuth login.

**Security Note**: Use app-specific passwords for Gmail SMTP, not your main password.

### 3. Run the Script

```bash
# Headed mode (visible browser) - recommended for first run
python scripts/refresh_oauth_credentials.py

# Headless mode (no UI) - for automated runs
python scripts/refresh_oauth_credentials.py --headless

# With email notification on failure
python scripts/refresh_oauth_credentials.py --headless --notify-email admin@example.com
```

## How It Works

The script automates the Google OAuth flow:

1. Fetches OAuth authorization URL from `/auth/login`
2. Navigates to Google's consent page
3. Enters your Google credentials
4. Grants consent (if needed)
5. Waits for redirect to `/auth/callback`
6. Verifies credentials were saved to HuggingFace Secrets

All actions are logged to `logs/oauth_refresh_YYYYMMDD_HHMMSS.log`

## Scheduling Options

### Option 1: Cron Job (Unix/Linux/Mac)

Run daily at noon:

```bash
# Edit crontab
crontab -e

# Add this line (adjust paths as needed)
0 12 * * * cd /path/to/voiceCal-ai-v3 && /path/to/python scripts/refresh_oauth_credentials.py --headless --notify-email your@email.com >> logs/cron.log 2>&1
```

### Option 2: GitHub Actions (Cloud-based)

Create `.github/workflows/refresh-oauth.yml`:

```yaml
name: Refresh OAuth Credentials

on:
  schedule:
    - cron: '0 12 * * *'  # Daily at noon UTC
  workflow_dispatch:  # Allow manual trigger

jobs:
  refresh:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install -r scripts/requirements.txt
          playwright install chromium --with-deps

      - name: Refresh OAuth credentials
        env:
          GOOGLE_EMAIL: ${{ secrets.GOOGLE_EMAIL }}
          GOOGLE_PASSWORD: ${{ secrets.GOOGLE_PASSWORD }}
          SMTP_HOST: ${{ secrets.SMTP_HOST }}
          SMTP_USER: ${{ secrets.SMTP_USER }}
          SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
        run: |
          python scripts/refresh_oauth_credentials.py --headless --notify-email ${{ secrets.NOTIFY_EMAIL }}

      - name: Upload logs on failure
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: oauth-refresh-logs
          path: logs/
```

**Setup GitHub Actions**:
1. Go to your GitHub repository → Settings → Secrets and variables → Actions
2. Add secrets: `GOOGLE_EMAIL`, `GOOGLE_PASSWORD`, `NOTIFY_EMAIL`, etc.
3. Push the workflow file to your repository
4. GitHub will run it daily at noon UTC

## Troubleshooting

### Script fails with "Timeout"

- Check your Google credentials are correct
- Ensure you don't have 2FA enabled (or add 2FA support)
- Try running in headed mode to see what's happening:
  ```bash
  python scripts/refresh_oauth_credentials.py
  ```

### "SMTP credentials not configured" warning

This is normal if you haven't set up email notifications. The script will still work.

### Credentials not updating in HuggingFace

- Check the logs for HuggingFace Secrets update messages
- Verify `HF_TOKEN` is set in your HuggingFace Space secrets
- The OAuth callback handler should automatically update secrets

### Screenshots on error

When an error occurs, the script saves a screenshot to `logs/error_screenshot_*.png` for debugging.

## Logs

All runs are logged to `logs/oauth_refresh_YYYYMMDD_HHMMSS.log`

View the latest log:
```bash
ls -t logs/oauth_refresh_*.log | head -1 | xargs cat
```

## Security Considerations

- Never commit `.env` file with real credentials
- Use app-specific passwords for SMTP, not your main password
- Store secrets in GitHub Actions Secrets, not in code
- Review logs for any leaked credentials before sharing
- Consider using a dedicated Google account for automation

## Manual Refresh Alternative

If the script fails, you can always manually refresh by visiting:
https://pgits-voicecal-ai-v3.hf.space/auth/login