# Zoho OAuth Setup Instructions

## Prerequisites

- Zoho CRM account
- Admin access to create OAuth applications
- Access to staging server terminal

## Step 1: Create Zoho OAuth Application

1. Go to [Zoho API Console](https://api-console.zoho.com/)
2. Click "Add Client" or "Create New Client"
3. Choose "Web Based" application type
4. Fill in the details:
   - **Client Name**: HVAC Community Events
   - **Homepage URL**: https://upskillhvac.com
   - **Authorized Redirect URIs**: http://localhost:8080/callback
   - **Description**: WordPress integration for HVAC event management

5. Click "Create" and save the credentials:
   - Client ID
   - Client Secret

## Step 2: Configure Environment Variables

Add to your `.env` file:
```
ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
```

## Step 3: Run OAuth Setup

From your terminal:

```bash
cd /Users/ben/dev/upskill-event-manager/wordpress-dev
./bin/zoho-setup-complete.sh
```

This script will:
1. Start a local callback server
2. Generate the authorization URL
3. Open your browser for Zoho login
4. Handle the OAuth callback
5. Save the tokens

## Step 4: Complete Authorization

1. When the browser opens, log in to Zoho
2. Review the permissions requested:
   - CRM Settings access
   - CRM Modules access  
   - CRM Users access
   - CRM Organization access
3. Click "Accept" or "Allow"
4. You'll be redirected to localhost:8080/callback
5. Copy the authorization code from the page
6. Return to terminal and paste the code

## Step 5: Verify Setup

The script will:
- Exchange the code for tokens
- Test the connection
- Save configuration to `zoho-config.php`
- Display success message

## Manual Setup (Alternative)

If the automated script doesn't work:

1. Start callback server:
```bash
cd wordpress/wp-content/plugins/hvac-community-events/includes/zoho
php -S localhost:8080 callback-server.php
```

2. Generate authorization URL:
```bash
php test-integration.php
```

3. Open the URL in your browser
4. Complete authorization
5. Copy the code and paste when prompted

## Testing the Integration

After setup, test on staging:

1. Go to WordPress Admin
2. Navigate to HVAC Community Events → Zoho CRM Sync
3. Click "Test Connection"
4. In staging mode, you'll see simulation results only

## Troubleshooting

### Common Issues

1. **"Client authentication failed"**
   - Double-check Client ID and Secret
   - Ensure no extra spaces in .env file

2. **"Invalid redirect URI"**
   - Make sure redirect URI in Zoho matches exactly: http://localhost:8080/callback
   - No trailing slash

3. **Connection refused on localhost:8080**
   - Ensure no other service is using port 8080
   - Try a different port if needed

4. **Token expired**
   - Tokens auto-refresh, but if issues persist, re-run setup

### Debug Mode

Enable debug logging:
```php
define('ZOHO_DEBUG_MODE', true);
define('ZOHO_LOG_FILE', '/path/to/debug.log');
```

## Security Notes

- Never commit .env or zoho-config.php to version control
- Tokens are stored encrypted in WordPress options
- Refresh tokens are used for long-term access
- Staging mode prevents accidental production syncs

## Support

For issues:
1. Check debug logs
2. Verify OAuth application settings
3. Review Zoho API documentation
4. Contact development team