# Calendar Integration Setup Guide

## ✅ Implementation Complete

Google Calendar and Outlook Calendar integration has been fully implemented and deployed.

## 🔧 Required Configuration

### Google Calendar OAuth Setup

1. **Create Google Cloud Project:**
   - Go to https://console.cloud.google.com/
   - Create new project or select existing
   - Enable "Google Calendar API"

2. **Create OAuth 2.0 Credentials:**
   - Go to "APIs & Services" → "Credentials"
   - Click "Create Credentials" → "OAuth 2.0 Client ID"
   - Application type: **Web application**
   - Authorized redirect URIs: `https://arvelobuilt.com/api/calendar/google/callback.php`
   - Save Client ID and Client Secret

3. **Set Environment Variables on Server:**
   ```bash
   # SSH to server
   ssh -i ~/arvelobuilt-key.pem ec2-user@54.163.198.244
   
   # Add to /etc/environment or ~/.bashrc
   export GOOGLE_CALENDAR_CLIENT_ID="your-client-id-here"
   export GOOGLE_CALENDAR_CLIENT_SECRET="your-client-secret-here"
   ```

### Outlook Calendar OAuth Setup

1. **Register Azure Application:**
   - Go to https://portal.azure.com/
   - Navigate to "Azure Active Directory" → "App registrations"
   - Click "New registration"
   - Name: "ArveloBuilt Calendar Integration"
   - Redirect URI: `https://arvelobuilt.com/api/calendar/outlook/callback.php`
   - Register

2. **Configure API Permissions:**
   - Go to "API permissions"
   - Add permission → Microsoft Graph → Delegated permissions
   - Add: `Calendars.ReadWrite`, `offline_access`
   - Click "Grant admin consent"

3. **Get Client Credentials:**
   - Go to "Certificates & secrets"
   - Create new client secret
   - Copy Application (client) ID and Client secret

4. **Set Environment Variables on Server:**
   ```bash
   export OUTLOOK_CLIENT_ID="your-client-id-here"
   export OUTLOOK_CLIENT_SECRET="your-client-secret-here"
   ```

## 📋 Database Migration

The database migration has been run successfully. The following tables/columns were created:

- ✅ `calendar_integrations` table
- ✅ `calendar_events.google_event_id` column
- ✅ `calendar_events.outlook_event_id` column
- ✅ `calendar_events.last_synced_at` column

## 🎯 How It Works

1. **User connects calendar:**
   - Admin → System Settings → Calendar Integration
   - Click "Connect Google Calendar" or "Connect Outlook Calendar"
   - Authorize application
   - OAuth tokens stored securely in database

2. **Automatic event sync:**
   - When user creates event via "New Event" button on lead detail page
   - Event is created in CRM
   - System automatically syncs to connected calendars
   - External calendar event IDs stored for future updates

3. **Token management:**
   - Access tokens expire after 1 hour
   - System automatically refreshes using refresh tokens
   - No user intervention needed

## 🔒 Security Features

- OAuth 2.0 secure authentication
- Tokens stored in database (should be encrypted in production)
- Tenant isolation enforced
- CSRF protection on all endpoints
- Automatic token refresh

## 📝 Next Steps

1. **Configure OAuth credentials** (see above)
2. **Test connection:**
   - Go to Admin → System Settings
   - Click "Connect Google Calendar" or "Connect Outlook Calendar"
   - Complete OAuth flow
   - Verify connection appears in list

3. **Test event sync:**
   - Go to any lead detail page
   - Click "New Event" button
   - Create an event
   - Check your Google/Outlook calendar to verify event appears

## ⚠️ Important Notes

- OAuth credentials must be set as environment variables on the server
- Redirect URIs must match exactly (including https://)
- Users can connect multiple calendars (one Google, one Outlook)
- Events sync automatically - no manual sync button needed yet
- Future enhancements: two-way sync, event updates/deletes, calendar selection