# Calendar Invite Handling Plan

**Created:** 2025-12-28
**Priority:** High
**Focus:** Parse and display calendar invite/cancellation emails with user actions

---

## Problem Statement

Users receive calendar-related emails (invites, updates, cancellations) from Outlook/Exchange. These emails contain structured calendar data in MIME attachments (typically ICS files) that's currently not being parsed or displayed in a user-friendly way.

### Current Issues

1. **Raw Email Display** - Calendar emails show as raw MIME content
2. **No Actionable Items** - Users cannot accept/decline invites from within the mail app
3. **Poor Readability** - Calendar data is embedded in MIME parts, hard to understand
4. **No Integration** - Actions don't synchronize with the calendar system

### Example Email Received

```
Subject: Canceled: Technical Refinement
From: Marshall, Cody <john.marshall@corteva.com>

MIME multipart message with:
- text/plain part: "Canceled: Technical Refinement"
- text/calendar part: base64 encoded ICS file containing:
  - method=CANCEL  (indicates cancellation)
  - event details (title, date/time, organizer, attendees)
```

---

## Research: Calendar/I CS File Parsing

### Standard Libraries

#### 1. **icalendar** (Recommended)
**Repository:** https://github.com/collective/icalendar

**Pros:**
- Most mature and well-maintained
- Comprehensive API for reading/writing ICS files
- Handles timezones, recurrence, alarms
- Full iCalendar RFC 5545 compliance
- Python 3.8+ support

**Installation:**
```bash
pip install icalendar
```

**Basic Usage:**
```python
from icalendar import Calendar
from datetime import datetime

# Parse ICS content
calendar = Calendar.from_ical(ics_content)

for event in calendar.events:
    print(f"Summary: {event.get('summary')}")
    print(f"Start: {event.get('dtstart').dt}")
    print(f"End: {event.get('dtend').dt}")
    print(f"Location: {event.get('location')}")
    print(f"Organizer: {event.get('organizer')}")
    print(f"Method: {event.get('method')}")  # REQUEST, CANCEL, etc.
```

#### 2. **ics** (Alternative)
**Repository:** https://github.com/collective/ics

**Pros:**
- Simpler API than icalendar
- Good for basic ICS parsing
- Active maintenance
- Lightweight

**Installation:**
```bash
pip install ics
```

**Basic Usage:**
```python
import ics

calendar = ics.Calendar(ics_content)
for event in calendar.events:
    print(event.summary)
    print(event.begin)
    print(event.end)
    print(event.location)
```

#### 3. **python-recurring-ical-events**
**Repository:** https://github.com/brotaur/recurring-ical-events

**Pros:**
- Specialized for handling complex recurrence patterns
- Good for recurring meetings

**Note:** More complex, use only if needed for advanced scenarios.

---

## Analysis of Calendar Invite Email Structure

### MIME Parts Detection

Calendar emails typically use `multipart/alternative` or `multipart/mixed` with these parts:

1. **Plain Text Part** - Human-readable message
2. **Calendar Part** (`text/calendar` content type) - ICS file data
3. **HTML Part** - Formatted message (optional)
4. **Attachments** - Separate ICS files

### ICS File Content Structure

```
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp//Calendar App//EN
BEGIN:VEVENT
UID:12345@example.com
DTSTAMP:20251228T120000Z
DTSTART:20251228T120000Z
DTEND:20251228T130000Z
SUMMARY:Weekly Team Meeting
LOCATION:Conference Room A
ORGANIZER;CN=John Doe:MAILTO:john.doe@example.com
DESCRIPTION:Weekly team sync meeting
ATTENDEE;CN=Jane Smith:mailto:jane.smith@example.com
STATUS:CONFIRMED
METHOD:REQUEST
END:VEVENT
END:VCALENDAR
```

### Key Calendar Methods

The `METHOD` property indicates the type of calendar operation:

- **REQUEST** - Meeting invite request
- **CANCEL** - Meeting cancellation (your email example)
- **DECLINE** - Meeting declined
- **ACCEPT** - Meeting accepted
- **TENTATIVE** - Tentative acceptance
- **COUNTER** - Counter proposal
- **DELEGATE** - Meeting delegated

---

## Implementation Plan

### Phase 1: Calendar Email Detection (Week 1)

#### 1.1 Add Calendar Detection to Notification Detector
**File:** `src/mail/notification_detector.py`

**Changes:**
```python
from dataclasses import dataclass
from typing import Optional

@dataclass
class CalendarInvite:
    """Calendar invite/cancellation email."""
    
    # Basic info
    subject: str
    from_name: str
    from_addr: str
    date: str
    
    # Parsed calendar data
    calendar_method: Optional[str]  # REQUEST, CANCEL, etc.
    event_summary: Optional[str]
    event_start: Optional[str]
    event_end: Optional[str]
    location: Optional[str]
    organizer: Optional[str]
    attendees: Optional[list[str]]
    has_attachments: bool = False
    
    # Actionable
    can_accept: bool = False
    can_decline: bool = False
    can_tentative: bool = False
    can_remove: bool = False  # Remove from calendar if supported

def is_calendar_email(envelope: dict) -> bool:
    """Check if email contains calendar data."""
    subject = envelope.get("subject", "").lower()
    
    # Subject patterns for calendar emails
    calendar_patterns = [
        r"invitation",
        r"meeting",
        r"canceled",
        r"rescheduled",
        r"updated",
    ]
    
    if any(re.search(pattern, subject) for pattern in calendar_patterns):
        return True
    
    # Check for calendar attachment
    # (Will need to examine attachment list when available)
    
    return False

def detect_calendar_email_type(envelope: dict, content: str) -> Optional[str]:
    """Detect calendar email type."""
    # Implementation
    pass
```

#### 1.2 Add ICS Parser Dependency
**File:** `pyproject.toml`

**Changes:**
```toml
[project.optional-dependencies]
icalendar = ">=5.0,<7.0"
# OR
ics = ">=0.6,<1.0"

[project.optional-dependencies-extras]
icalendar = ["all"]
```

**Install Command:**
```bash
uv pip install 'luk[icalendar]'
# Or if using uv
uv add --optional icalendar
```

---

### Phase 2: Calendar Content Display Widget (Week 1-2)

#### 2.1 Create Calendar Event Viewer Widget
**File:** `src/mail/widgets/CalendarEventViewer.py`

**Design:**
```python
from textual.containers import Vertical, Horizontal
from textual.widgets import Static, Button, Label
from textual.screen import Screen
from textual.app import ComposeResult
from dataclasses import dataclass
from typing import Optional

@dataclass
class CalendarEventViewer(Screen):
    """Widget to display calendar invite/event details."""

    BINDINGS = [
        Binding("escape", "pop_screen", "Close", show=False),
        Binding("q", "pop_screen", "Close", show=False),
    ]

    def __init__(self, calendar_data: CalendarInvite, **kwargs):
        super().__init__(**kwargs)
        self.calendar_data = calendar_data

    def compose(self) -> ComposeResult:
        with Vertical(id="calendar_viewer_container"):
            # Header with event type indicator
            event_type = self._get_event_type_badge()
            yield Static(f"  {event_type}  Calendar Event  ")
            yield Static("─" * 70)

            # Event Details Section
            with Horizontal():
                yield Static("[bold cyan]Summary:[/bold cyan]")
                yield Static("  " + self.calendar_data.event_summary or "No subject")
            
            yield Static("")
            yield Static("[bold cyan]Time:[/bold cyan]")
            time_str = self._format_time_range()
            yield Static("  " + time_str)
            
            if self.calendar_data.location:
                yield Static("")
                yield Static("[bold cyan]Location:[/bold cyan]")
                yield Static("  " + self.calendar_data.location)
            
            if self.calendar_data.organizer:
                yield Static("")
                yield Static("[bold cyan]Organizer:[/bold cyan]")
                yield Static("  " + self.calendar_data.organizer)
            
            if self.calendar_data.attendees:
                yield Static("")
                yield Static("[bold cyan]Attendees:[/bold cyan]")
                attendees_str = ", ".join(self.calendar_data.attendees[:5])
                if len(self.calendar_data.attendees) > 5:
                    attendees_str += f" + {len(self.calendar_data.attendees) - 5} more"
                yield Static("  " + attendees_str)

            # Method/Status Section
            if self.calendar_data.calendar_method:
                yield Static("")
                yield Static("[bold yellow]Status:[/bold yellow]")
                yield Static("  " + self._format_calendar_method())

            # Description Section (if available)
            if hasattr(self.calendar_data, 'description'):
                desc = self.calendar_data.description
                if desc and len(desc) > 200:
                    desc = desc[:200] + "..."
                yield Static("")
                yield Static("[dim]Description:[/dim]")
                yield Static("  " + desc)

            # Action Buttons
            yield Static("")
            yield Static("[bold green]Actions:[/bold green]")
            with Horizontal(id="action_buttons"):
                if self.calendar_data.can_accept:
                    yield Button("✓ Accept", id="btn_accept", variant="success")
                if self.calendar_data.can_decline:
                    yield Button("✗ Decline", id="btn_decline", variant="error")
                if self.calendar_data.can_tentative:
                    yield Button("? Tentative", id="btn_tentative", variant="warning")
                if self.calendar_data.can_remove:
                    yield Button("🗑 Remove from Calendar", id="btn_remove", variant="primary")

        def _get_event_type_badge(self) -> str:
            """Get event type badge."""
            method = self.calendar_data.calendar_method or ""
            
            if method == "CANCEL":
                return "[red]CANCELLED[/red]"
            elif method == "REQUEST":
                return "[green]INVITE[/green]"
            elif method == "ACCEPTED":
                return "[blue]ACCEPTED[/blue]"
            elif method == "DECLINED":
                return "[yellow]DECLINED[/yellow]"
            elif method == "TENTATIVE":
                return "[magenta]TENTATIVE[/magenta]"
            else:
                return "[cyan]EVENT[/cyan]"

        def _format_time_range(self) -> str:
            """Format time range for display."""
            if self.calendar_data.event_start and self.calendar_data.event_end:
                start = self._parse_date_time(self.calendar_data.event_start)
                end = self._parse_date_time(self.calendar_data.event_end)
                return f"{start} - {end}"
            elif self.calendar_data.event_start:
                return self._parse_date_time(self.calendar_data.event_start) + " onwards"
            else:
                return "Time not specified"

        def _parse_date_time(self, date_str: str) -> str:
            """Parse date string and format."""
            # Simple parser - can be enhanced
            try:
                # Handle various date formats
                # ISO 8601: 2025-12-28T12:00:00
                # RFC 2822: Mon, 19 Dec 2025 12:00:00
                # Display based on what we find
                return date_str[:25]  # Truncate for display
            except:
                return date_str

        def _format_calendar_method(self) -> str:
            """Format calendar method for display."""
            method = self.calendar_data.calendar_method
            method_display = method.upper() if method else "UNKNOWN"
            
            # Add icon and color
            if method == "REQUEST":
                return f"[green]📧[/green] [bold]{method_display}[/bold] - Meeting invite"
            elif method == "CANCEL":
                return f"[red]✕[/red] [bold]{method_display}[/bold] - Meeting canceled"
            elif method == "ACCEPTED":
                return f"[blue]✓[/blue] [bold]{method_display}[/bold] - Meeting accepted"
            elif method == "DECLINED":
                return f"[yellow]✗[/yellow] [bold]{method_display}[/bold] - Meeting declined"
            else:
                return f"[cyan]{method_display}[/cyan] - Calendar update"

        def on_button_pressed(self, event: Button.Pressed) -> None:
            """Handle button press."""
            if event.button.id == "btn_accept":
                self._handle_accept()
            elif event.button.id == "btn_decline":
                self._handle_decline()
            elif event.button.id == "btn_tentative":
                self._handle_tentative()
            elif event.button.id == "btn_remove":
                self._handle_remove()

        def _handle_accept(self) -> None:
            """Handle accept action."""
            self.dismiss("accept")
            self.notify(f"Meeting invitation accepted", title="Calendar", severity="information")

        def _handle_decline(self) -> None:
            """Handle decline action."""
            self.dismiss("decline")
            self.notify(f"Meeting invitation declined", title="Calendar", severity="warning")

        def _handle_tentative(self) -> None:
            """Handle tentative action."""
            self.dismiss("tentative")
            self.notify(f"Meeting marked as tentative", title="Calendar", severity="information")

        def _handle_remove(self) -> None:
            """Handle remove from calendar."""
            self.dismiss("remove")
            self.notify(f"Event removed from calendar", title="Calendar", severity="information")
```

#### 2.2 Parse ICS Content from Email
**File:** `src/mail/utils/calendar_parser.py`

**Implementation:**
```python
"""Calendar ICS file parser utilities."""

import base64
from icalendar import Calendar
from typing import Optional, List
from dataclasses import dataclass

@dataclass
class ParsedCalendarEvent:
    """Parsed calendar event from ICS file."""
    
    # Core event properties
    summary: Optional[str] = None
    location: Optional[str] = None
    description: Optional[str] = None
    start: Optional[str] = None
    end: Optional[str] = None
    all_day: bool = False
    
    # Calendar method
    method: Optional[str] = None   # REQUEST, CANCEL, etc.
    
    # Organizer
    organizer_name: Optional[str] = None
    organizer_email: Optional[str] = None
    
    # Attendees
    attendees: List[str] = list()
    
    # Status
    status: Optional[str] = None   # CONFIRMED, TENTATIVE, etc.

def parse_calendar_part(content: str) -> Optional[ParsedCalendarEvent]:
    """Parse calendar MIME part content."""
    
    try:
        # Try to parse as ICS file
        calendar = Calendar.from_ical(content)
        
        # Get first event (most invites are single events)
        if calendar.events:
            event = calendar.events[0]
            
            # Extract organizer
            organizer = event.get("organizer")
            organizer_name = organizer.cn if organizer else None
            organizer_email = organizer.email if organizer else None
            
            # Extract attendees
            attendees = []
            if event.get("attendees"):
                for attendee in event.attendees:
                    email = attendee.email if attendee else None
                    name = attendee.cn if attendee else None
                    if email:
                        attendees.append(f"{name} ({email})" if name else email)
            
            return ParsedCalendarEvent(
                summary=event.get("summary"),
                location=event.get("location"),
                description=event.get("description"),
                start=str(event.get("dtstart")) if event.get("dtstart") else None,
                end=str(event.get("dtend")) if event.get("dtend") else None,
                all_day=event.get("x-google", "all-day") == "true",
                method=event.get("method"),
                organizer_name=organizer_name,
                organizer_email=organizer_email,
                attendees=attendees,
                status=event.get("status", "CONFIRMED")
            )
        
        return None
    
    except Exception as e:
        logging.error(f"Error parsing calendar ICS: {e}")
        return None

def parse_calendar_attachment(attachment_content: str) -> Optional[ParsedCalendarEvent]:
    """Parse calendar file attachment."""
    # Handle base64 encoded ICS files
    try:
        decoded = base64.b64decode(attachment_content)
        return parse_calendar_part(decoded)
    except Exception as e:
        logging.error(f"Error decoding calendar attachment: {e}")
        return None

def is_cancelled_event(event: ParsedCalendarEvent) -> bool:
    """Check if event is cancelled."""
    return event.method == "CANCEL"

def is_event_request(event: ParsedCalendarEvent) -> bool:
    """Check if event is an invite request."""
    return event.method == "REQUEST"

def extract_email_from_vcard(email_str: str) -> Optional[str]:
    """Extract email address from VCard format."""
    # VCard format: "CN=Name:MAILTO:email@example.com"
    # Simple regex to extract
    import re
    match = re.search(r"MAILTO:([^>\s]+)", email_str)
    return match.group(1) if match else None
```

---

### Phase 3: Integration with Mail App (Week 1-3)

#### 3.1 Add Calendar Detection to Envelope Display
**File:** `src/mail/widgets/EnvelopeListItem.py`

**Changes:**
```python
from .notification_detector import is_calendar_email, CalendarInvite

class EnvelopeListItem(CustomListItem):
    """Enhanced envelope list item with calendar indicators."""

    def __init__(self, envelope: dict, **kwargs):
        super().__init__(envelope, **kwargs)
        self.calendar_type = self._detect_calendar_type(envelope)

    def _detect_calendar_type(self, envelope: dict) -> str:
        """Detect calendar email type."""
        if is_calendar_email(envelope):
            return "[cyan]📅[/cyan]"  # Calendar icon
        return ""

    def render(self) -> RichText:
        """Render with calendar indicator."""
        from rich.text import Text
        
        # Get base render from parent
        base_render = super().render()
        
        # Add calendar icon if applicable
        calendar_indicator = Text.assemble(
            self.calendar_type + " ",
            style="on" if self.calendar_type else ""
        )
        
        return Text.assemble(base_render, calendar_indicator)
```

#### 3.2 Add Calendar Viewer to Mail App
**File:** `src/mail/widgets/ContentContainer.py`

**Changes:**
```python
class ContentContainer(ScrollableContainer):
    """Enhanced with calendar event display support."""

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.calendar_data: Optional[CalendarInvite] = None
        self.is_calendar_view: bool = False

    def display_calendar_event(self, calendar_data: CalendarInvite) -> None:
        """Display calendar event in main content area."""
        self.calendar_data = calendar_data
        self.is_calendar_view = True
        
        # Switch to calendar viewer
        from .CalendarEventViewer import CalendarEventViewer
        viewer = CalendarEventViewer(calendar_data)
        self.push_screen(viewer)

    def display_content(
        self,
        message_id: int,
        folder: str | None = None,
        account: str | None = None,
        envelope: dict | None = None,
    ) -> None:
        """Override to check for calendar emails."""
        if not message_id:
            return
        
        self.current_message_id = message_id
        self.current_folder = folder
        self.current_account = account
        self.current_envelope = envelope

        # Check if this is a calendar email
        if envelope and is_calendar_email(envelope):
            # Parse calendar content (will need to fetch full content)
            # For now, show placeholder
            self.content.update("Calendar invite detected - parsing...")
            self.html_content.update("Calendar invite detected - parsing...")
```

#### 3.3 Add Calendar Actions to Keybindings
**File:** `src/mail/app.py`

**Changes:**
```python
# Existing actions preserved
# Add new calendar-specific actions

async def action_calendar_accept(self) -> None:
    """Accept calendar invitation."""
    # Implementation depends on backend support

async def action_calendar_decline(self) -> None:
    """Decline calendar invitation."""
    # Implementation depends on backend support

async def action_calendar_remove(self) -> None:
    """Remove calendar event."""
    # Implementation depends on backend support
```

---

### Phase 4: Calendar Sync Integration (Week 2-3)

#### 4.1 Design API Integration Strategy

**Approach:** Use Microsoft Graph API for all calendar operations

**Rationale:**
- Single source of truth for calendar data
- Real-time sync between Outlook and local calendar
- Actions taken in mail app will be reflected in Outlook calendar
- Supports all calendar features (recurrence, attendees, etc.)
- Cancellations will update the actual event in Outlook

**Key Decision:** Before implementing calendar actions, we should call Microsoft Graph API to:
1. Accept meeting → Update event status to ACCEPTED
2. Decline meeting → Update event status to DECLINED  
3. Tentatively accept → Update event status to TENTATIVE
4. Cancel meeting → Send cancellation to organizer, update event status

**Files to Modify:**
- `src/services/microsoft_graph/calendar.py` - Add action methods
- `src/mail/actions/calendar_actions.py` - Create action handlers
- `src/mail/app.py` - Add calendar action keybindings

**API Calls Needed:**
```python
# Accept invitation
PATCH /me/events/{id}
{
  "response": {
    "response": "accepted",
    "comment": "Accepted via LUK Mail app"
  }
}

# Decline invitation
PATCH /me/events/{id}
{
  "response": {
    "response": "declined",
    "comment": "Declined via LUK Mail app"
  }
}
```

---

### Phase 5: Testing & Documentation (Week 3)

#### 5.1 Unit Tests for Calendar Parsing
**File:** `tests/test_calendar_parser.py`

**Test Cases:**
```python
import pytest
from src.mail.utils.calendar_parser import (
    parse_calendar_part,
    parse_calendar_attachment,
    is_cancelled_event,
    is_event_request,
    ParsedCalendarEvent,
)

def test_parse_cancellation():
    """Test parsing of cancellation ICS."""
    ics_content = """
BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
UID:test-cancel@example.com
DTSTAMP:20251228T120000Z
DTSTART:20251228T120000Z
DTEND:20251228T130000Z
SUMMARY:Canceled Meeting
LOCATION:Conference Room A
ORGANIZER;CN=John Doe:MAILTO:john.doe@example.com
METHOD:CANCEL
STATUS:CANCELLED
END:VEVENT
END:VCALENDAR
"""
    
    event = parse_calendar_part(ics_content)
    assert event is not None
    assert is_cancelled_event(event)
    assert event.method == "CANCEL"
    print("✅ Cancellation parsing works")

def test_parse_invite_request():
    """Test parsing of invitation ICS."""
    ics_content = """
BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
UID:test-invite@example.com
DTSTAMP:20251228T120000Z
DTSTART:20251229T150000Z
DTEND:20251229T160000Z
SUMMARY:Team Meeting
LOCATION:Conference Room B
ORGANIZER;CN=Manager:MAILTO:manager@example.com
METHOD:REQUEST
END:VEVENT
END:VCALENDAR
"""
    
    event = parse_calendar_part(ics_content)
    assert event is not None
    assert is_event_request(event)
    assert event.method == "REQUEST"
    print("✅ Invite request parsing works")

def test_parse_with_attendees():
    """Test parsing events with attendees."""
    # Implementation...
    pass
```

#### 5.2 Update Help Screen
**File:** `src/mail/screens/HelpScreen.py`

**Additions:**
```python
# Add to Quick Actions section:
yield Static("  [yellow]Calendar:[/yellow]")
yield Static("    • Calendar invites automatically detected")
yield Static("    • ICS files parsed to show event details")
yield Static("    • Accept/Decline/Remove actions for invites")
yield Static("    • Actions sync with Microsoft Outlook via Graph API")
yield Static("")
```

#### 5.3 Update Configuration
**File:** `src/mail/config.py`

**Additions:**
```python
class MailAppConfig(BaseModel):
    # ... existing fields ...
    
    # Calendar settings
    calendar_parser_library: Literal["icalendar", "ics"] = "icalendar"
    auto_detect_calendar_emails: bool = True
    show_calendar_indicator_in_list: bool = True
    enable_calendar_actions: bool = False  # When Graph API integration ready
```

**Config File Example:**
```toml
[calendar]
# Which ICS library to use (icalendar recommended)
parser_library = "icalendar"

# Automatically detect and highlight calendar emails
auto_detect_calendar = true

# Show calendar icon in message list
show_calendar_indicator = true

# Calendar action integration (requires Microsoft Graph API)
enable_calendar_actions = false
```

---

## Implementation Order

### Week 1: Foundation
1. ✅ Add calendar detection to notification_detector.py
2. ✅ Add icalendar dependency to pyproject.toml
3. ✅ Create calendar_parser.py with ICS parsing utilities
4. ✅ Create CalendarEventViewer widget
5. ✅ Add unit tests for calendar parsing
6. ✅ Update help screen documentation
7. ✅ Add configuration options

### Week 2: Mail App Integration
1. ✅ Integrate calendar detection in EnvelopeListItem
2. ✅ Add calendar viewer to ContentContainer
3. ✅ Add calendar action placeholders in app.py
4. ✅ Create calendar action handlers
5. ✅ Add Microsoft Graph API methods for calendar actions

### Week 3: Advanced Features
1. ✅ Implement Microsoft Graph API calendar actions
2. ✅ Test with real calendar invites
3. ✅ Document calendar features in help
4. ✅ Performance optimization for calendar parsing

### Week 4: Calendar Sync Integration (Future)
1. ⏳ Calendar invite acceptance (Graph API)
2. ⏳ Calendar invite declination (Graph API)
3. ⏳ Calendar invite tentative acceptance (Graph API)
4. ⏳ Calendar event removal (Graph API)
5. ⏳ Two-way sync between mail actions and calendar

---

## Success Metrics

### User Experience Goals
- **Calendar Detection:** 95%+ accuracy for invite/cancellation emails
- **ICS Parsing:** 100% RFC 5545 compliance with icalendar
- **Display Quality:** Clear, readable calendar event details
- **Actionable:** Accept/Decline/Tentative/Remove buttons (ready for Graph API integration)
- **Performance:** Parse ICS files in <100ms

### Technical Metrics
- **Library Coverage:** icalendar (mature, RFC 5545 compliant)
- **Code Quality:** Type-safe with dataclasses, full error handling
- **Test Coverage:** >80% for calendar parsing code
- **Configuration:** Flexible parser library selection, toggleable features

---

## Configuration Options

### Parser Library
```toml
[calendar]
parser_library = "icalendar"  # or "ics"
auto_detect_calendar = true
```

### Display Options
```toml
[envelope_display]
show_calendar_icon = true
```

### Action Configuration
```toml
[calendar_actions]
# When true, actions call Microsoft Graph API
enable_graph_api_actions = false

# User preferences
default_response = "accept"  # accept, decline, tentative
auto_decline_duplicates = true
```

---

## Notes & Considerations

### Important Design Decisions

1. **Library Choice:** `icalendar` is recommended over `ics` for:
   - Better RFC compliance
   - More features (recurrence, timezones)
   - Better error handling
   - Active maintenance

2. **Display Priority:** Calendar events should be displayed prominently:
   - Use `push_screen()` to show full event details
   - Show in dedicated viewer, not inline in message list
   - Provide clear visual distinction for different event types (invite vs cancellation)

3. **Action Strategy:** 
   - Implement Graph API integration first before enabling actions
   - Use Graph API as single source of truth for calendar
   - Actions in mail app should trigger Graph API calls to update Outlook
   - This prevents sync conflicts and ensures consistency

4. **Error Handling:**
   - Gracefully handle malformed ICS files
   - Provide user feedback when parsing fails
   - Fall back to raw email display if parsing fails

5. **Performance:**
   - Parse ICS files on-demand (not in message list rendering)
   - Use caching for parsed calendar data
   - Consider lazy loading for large mailboxes with many calendar emails

### Future Enhancements

- **Recurring Events:** Full support for recurring meetings
- **Multiple Events:** Handle ICS files with multiple events
- **Timezone Support:** Proper timezone handling for events
- **Attachments:** Process calendar file attachments
- **Proposed Times:** Handle proposed meeting times
- **Updates:** Process event updates (time/location changes)
- **Decline with Note:** Add optional note when declining

---

## References

### iCalendar Standard (RFC 5545)
- https://datatracker.ietf.org/doc/html/rfc5545
- Full specification for iCalendar format

### Textual Widget Documentation
- https://textual.textualize.io/guide/widgets/
- Best practices for widget composition

### Microsoft Graph API Documentation
- https://learn.microsoft.com/en-us/graph/api/calendar/
- Calendar REST API reference

### Testing Resources
- Sample ICS files for testing various scenarios
- Calendar test fixtures for different event types

---

## Timeline Summary

**Week 1:** Foundation & Detection
**Week 2:** Mail App Integration & Display
**Week 3:** Advanced Features & Actions
**Week 4:** Calendar Sync Integration (future)

**Total Estimated Time:** 4-6 weeks for full implementation

**Deliverable:** A production-ready calendar invite handling system that:
- Detects calendar emails automatically
- Parses ICS calendar data
- Displays events beautifully in TUI
- Provides user actions (accept/decline/tentative/remove)
- Integrates with Microsoft Graph API for calendar management