# Integration Design Documents

Design documents for optional integrations (email, calendar, smart home).

## Overview

These integrations are marked as "optional" and can be implemented after MVP. They require:
- External API access (with privacy considerations)
- Confirmation flows (high-risk actions)
- Boundary enforcement (work vs family separation)

## Email Integration (TICKET-036)

### Design Considerations

**Privacy**: 
- Email access requires explicit user consent
- Consider local email server (IMAP/SMTP) vs cloud APIs
- Family agent should NOT access work email

**Confirmation Required**: 
- Sending emails is CRITICAL risk
- Always require explicit confirmation
- Show email preview before sending

**Tools**:
- `list_recent_emails` - List recent emails (read-only)
- `read_email` - Read specific email
- `draft_email` - Create draft (no send)
- `send_email` - Send email (requires confirmation token)

**Implementation**:
- Use IMAP for reading (local email server)
- Use SMTP for sending (with authentication)
- Or use email API (Gmail, Outlook) with OAuth

## Calendar Integration (TICKET-037)

### Design Considerations

**Privacy**:
- Calendar access requires explicit user consent
- Separate calendars for work vs family
- Family agent should NOT access work calendar

**Confirmation Required**:
- Creating/modifying/deleting events is HIGH risk
- Always require explicit confirmation
- Show event details before confirming

**Tools**:
- `list_events` - List upcoming events
- `get_event` - Get event details
- `create_event` - Create event (requires confirmation)
- `update_event` - Update event (requires confirmation)
- `delete_event` - Delete event (requires confirmation)

**Implementation**:
- Use CalDAV for local calendar server
- Or use calendar API (Google Calendar, Outlook) with OAuth
- Support iCal format

## Smart Home Integration (TICKET-038)

### Design Considerations

**Privacy**:
- Smart home control is HIGH risk
- Require explicit confirmation for all actions
- Log all smart home actions

**Confirmation Required**:
- All smart home actions are CRITICAL risk
- Always require explicit confirmation
- Show action details before confirming

**Tools**:
- `list_devices` - List available devices
- `get_device_status` - Get device status
- `toggle_device` - Toggle device on/off (requires confirmation)
- `set_scene` - Set smart home scene (requires confirmation)
- `adjust_thermostat` - Adjust temperature (requires confirmation)

**Implementation**:
- Use Home Assistant API (if available)
- Or use device-specific APIs (Philips Hue, etc.)
- Abstract interface for multiple platforms

## Common Patterns

### Confirmation Flow

All high-risk integrations follow this pattern:

1. **Agent proposes action**: "I'll send an email to..."
2. **User confirms**: "Yes" or "No"
3. **Confirmation token generated**: Signed token with action details
4. **Tool validates token**: Before executing
5. **Action logged**: All actions logged for audit

### Boundary Enforcement

- **Family Agent**: Can only access family email/calendar
- **Work Agent**: Can access work email/calendar
- **Smart Home**: Both can access, but with confirmation

### Error Handling

- Network errors: Retry with backoff
- Authentication errors: Re-authenticate
- Permission errors: Log and notify user

## Implementation Priority

1. **Smart Home** (if Home Assistant available) - Most useful
2. **Calendar** - Useful for reminders and scheduling
3. **Email** - Less critical, can use web interface

## Security Considerations

- **OAuth Tokens**: Store securely, never in code
- **API Keys**: Use environment variables
- **Rate Limiting**: Respect API rate limits
- **Audit Logging**: Log all actions
- **Token Expiration**: Handle expired tokens gracefully

## Future Enhancements

- Voice confirmation ("Yes, send it")
- Batch operations
- Templates for common actions
- Integration with memory system (remember preferences)