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

# 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:

# 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

# 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:

# 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:

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:

  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:

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