scripts/SETUP_GUIDE.md

# OAuth Token Refresh Setup Guide

This guide will help you set up automated daily OAuth token refresh for VoiceCal.ai.

## Quick Summary

**Problem:** Google OAuth tokens in testing mode expire after 24 hours.

**Solution:** Automatically refresh tokens daily using:
1. **Local Cron Job** (runs on your machine)
2. **GitHub Actions** (runs in the cloud)

## Prerequisites

You've already completed this! ✅
- ✅ Manually authenticated via `http://localhost:8080/auth/login`
- ✅ Fresh refresh token saved to `.env`
- ✅ Tested refresh script successfully

---

## Option 1: Cron Job (Local Machine)

**Runs on your Mac daily at noon**

### Setup

```bash
# Run the automated setup script
./scripts/setup_cron.sh
```

This will:
- Add a cron job that runs daily at 12:00 PM
- Log output to `logs/cron.log`
- Send email notification if refresh fails

### Verify

```bash
# List current cron jobs
crontab -l

# Check logs
tail -f logs/cron.log
```

### Manual Test

```bash
# Test the cron job command manually
cd /Users/petergits/dev/voiceCal-ai-v3 && python3 scripts/refresh_token_only.py --notify-email pgits.job@gmail.com
```

### Remove

```bash
# Edit crontab
crontab -e

# Delete the line containing 'refresh_token_only.py'
```

---

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

**Runs in GitHub's cloud daily at noon UTC**

### Setup

1. **Push the workflow file** (already created):
   ```bash
   git add .github/workflows/refresh-oauth-tokens.yml
   git commit -m "Add OAuth token refresh workflow"
   git push
   ```

2. **Add GitHub Secrets** (go to your repository → Settings → Secrets and variables → Actions):

   Required secrets:
   ```
   GOOGLE_CLIENT_ID          = (from your .env file)
   GOOGLE_CLIENT_SECRET      = (from your .env file)
   GOOGLE_REFRESH_TOKEN      = (from your .env file)
   HF_TOKEN                  = (your HuggingFace token)
   ```

   Optional (for email notifications):
   ```
   SMTP_HOST                 = smtp.gmail.com
   SMTP_PORT                 = 587
   SMTP_USERNAME             = pgits.job@gmail.com
   SMTP_PASSWORD             = (your Gmail app password)
   NOTIFY_EMAIL              = pgits.job@gmail.com
   ```

3. **Test the workflow**:
   - Go to your repository → Actions tab
   - Click "Refresh OAuth Tokens" workflow
   - Click "Run workflow" → "Run workflow"
   - Watch it run and verify success ✅

### Verify

- Go to repository → Actions tab
- Check workflow runs daily at noon UTC
- View logs for each run
- Failed runs will upload logs as artifacts

---

## Which Option to Choose?

### Use Cron Job if:
- ✅ Your Mac is always running (or on at noon daily)
- ✅ You want local control
- ✅ You don't want to depend on GitHub

### Use GitHub Actions if:
- ✅ You want it to run even when your Mac is off
- ✅ You prefer cloud-based automation
- ✅ You want workflow run history in GitHub

### Use Both if:
- ✅ You want redundancy (if one fails, the other succeeds)
- ⚠️ Tokens refresh every hour, so both running is fine

---

## Troubleshooting

### "Token has been expired or revoked"

**Cause:** Your refresh token is older than 7 days (testing mode limit)

**Solution:** Re-authenticate manually:
```bash
# Start local server
uvicorn app.api.main:app --reload --port 8080

# Visit in browser
http://localhost:8080/auth/login

# Complete OAuth flow
# New refresh token will be saved automatically
```

### "Failed to refresh token: 400 Bad Request"

**Cause:** Invalid client ID, client secret, or refresh token

**Solution:** Check `.env` file has correct values:
```bash
grep -E "GOOGLE_CLIENT_ID|GOOGLE_CLIENT_SECRET|GOOGLE_REFRESH_TOKEN" .env
```

### Cron job not running

**Check if cron service is running:**
```bash
# macOS
sudo launchctl list | grep cron

# View cron logs
log show --predicate 'process == "cron"' --last 1h
```

**Verify cron job is installed:**
```bash
crontab -l
```

### GitHub Actions not running

**Check workflow file:**
```bash
# Validate YAML syntax
cat .github/workflows/refresh-oauth-tokens.yml
```

**Check repository settings:**
- Settings → Actions → General
- Ensure "Allow all actions" is enabled

---

## Manual Refresh Anytime

```bash
# Local refresh
python3 scripts/refresh_token_only.py

# With email notification
python3 scripts/refresh_token_only.py --notify-email your@email.com

# Verbose output for debugging
python3 scripts/refresh_token_only.py --verbose
```

---

## Monitoring

### View Recent Logs

```bash
# Latest refresh log
ls -t logs/token_refresh_*.log | head -1 | xargs cat

# Cron job log
tail -f logs/cron.log
```

### Check Token Expiry

```bash
grep GOOGLE_TOKEN_EXPIRY .env
```

### Test Refresh Manually

```bash
# Run refresh script
python3 scripts/refresh_token_only.py

# Should see:
# ✅ SUCCESS
# Status: ✅ SUCCESS
```

---

## Production Mode (Future)

When your OAuth app goes to production mode:
- Refresh tokens don't expire every 7 days
- You can reduce refresh frequency (weekly instead of daily)
- Update cron schedule: `0 12 * * 0` (weekly on Sunday)
- Update GitHub Actions cron: `0 12 * * 0`

---

## Questions?

- Cron not working? Check `logs/cron.log`
- GitHub Actions failing? Check Actions tab → Workflow run → Logs
- Need help? Contact support or file an issue

---

**You're all set! 🎉**

Your OAuth tokens will now refresh automatically every day at noon.