# Calendar Integration - Google Calendar & Outlook Calendar

## Overview
This document describes the calendar integration feature that allows users to sync CRM events with their Google Calendar and Outlook Calendar accounts.

## Features
- ✅ OAuth 2.0 authentication for Google Calendar
- ✅ OAuth 2.0 authentication for Outlook Calendar (Microsoft Graph API)
- ✅ Automatic event synchronization when events are created in CRM
- ✅ Token refresh handling for long-term access
- ✅ User-specific calendar connections
- ✅ Disconnect functionality

## Setup Requirements

### Google Calendar Setup
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing
3. Enable "Google Calendar API"
4. Create OAuth 2.0 credentials:
   - Application type: Web application
   - Authorized redirect URIs: `https://arvelobuilt.com/api/calendar/google/callback.php`
5. Set environment variables:
   ```bash
   export GOOGLE_CALENDAR_CLIENT_ID="your-client-id"
   export GOOGLE_CALENDAR_CLIENT_SECRET="your-client-secret"
   ```

### Outlook Calendar Setup
1. Go to [Azure Portal](https://portal.azure.com/)
2. Register a new application
3. Add redirect URI: `https://arvelobuilt.com/api/calendar/outlook/callback.php`
4. Grant permissions: `Calendars.ReadWrite`, `offline_access`
5. Set environment variables:
   ```bash
   export OUTLOOK_CLIENT_ID="your-client-id"
   export OUTLOOK_CLIENT_SECRET="your-client-secret"
   ```

## Database Schema

### calendar_integrations Table
Stores OAuth tokens and connection information:
- `id` - UUID primary key
- `tenant_id` - Tenant identifier
- `user_id` - User identifier
- `provider` - 'GOOGLE' or 'OUTLOOK'
- `email` - Connected email address
- `access_token` - Encrypted access token
- `refresh_token` - Encrypted refresh token
- `token_expires_at` - Token expiration datetime
- `is_active` - Connection status
- `sync_enabled` - Whether sync is enabled

### calendar_events Table Updates
Added columns for external calendar IDs:
- `google_event_id` - Google Calendar event ID
- `outlook_event_id` - Outlook Calendar event ID
- `last_synced_at` - Last sync timestamp

## API Endpoints

### `/api/calendar/connect.php`
- `GET ?action=connect&provider=google|outlook` - Get OAuth URL
- `POST action=disconnect` - Disconnect calendar
- `GET ?action=list` - List user's calendar connections

### `/api/calendar/google/callback.php`
OAuth callback handler for Google Calendar

### `/api/calendar/outlook/callback.php`
OAuth callback handler for Outlook Calendar

## Usage

### Connecting a Calendar
1. Navigate to Admin → System Settings tab
2. Click "Connect Google Calendar" or "Connect Outlook Calendar"
3. Authorize the application
4. Calendar is now connected and will sync events automatically

### Event Synchronization
When a user creates an event in the CRM (via "New Event" button on lead detail page):
1. Event is created in CRM's `calendar_events` table
2. System checks for active calendar integrations for that user
3. Event is automatically synced to:
   - Google Calendar (if connected)
   - Outlook Calendar (if connected)
4. External calendar event IDs are stored for future updates/deletes

### Disconnecting a Calendar
1. Go to Admin → System Settings tab
2. Find the calendar connection
3. Click "Disconnect"
4. Events will no longer sync to that calendar

## Security
- OAuth tokens are stored encrypted in database
- Tenant isolation enforced (users can only see their own connections)
- CSRF protection on all API endpoints
- Token refresh handled automatically
- Tokens expire after 1 hour and are refreshed using refresh tokens

## Files Created/Modified

### New Files
- `includes/classes/GoogleCalendarService.php` - Google Calendar integration
- `includes/classes/OutlookCalendarService.php` - Outlook Calendar integration
- `api/calendar/connect.php` - Calendar connection API
- `api/calendar/google/callback.php` - Google OAuth callback
- `api/calendar/outlook/callback.php` - Outlook OAuth callback
- `php/database/add_calendar_integration.sql` - Database migration

### Modified Files
- `admin.php` - Added calendar integration UI in System Settings tab
- `api/activities.php` - Added automatic calendar sync when events are created

## Next Steps (Future Enhancements)
- [ ] Two-way sync (sync external calendar events to CRM)
- [ ] Calendar selection (choose which calendar to sync to)
- [ ] Sync status indicators
- [ ] Manual sync button
- [ ] Event update/delete sync
- [ ] Recurring event support