Feature Request: Extend field-based updates for Events and Todos #5

New issue

Open

opened 2025-10-26 12:07:55 +00:00 by PhilflowIO · 0 comments

PhilflowIO commented

2025-10-26 12:07:55 +00:00

(Migrated from github.com)

Summary

Currently, field-based updates for Events (updateEventFields) and Todos (updateTodoFields) only support SUMMARY and DESCRIPTION fields, while vCard updates (updateVCardFields) support 8+ fields. This creates an imbalanced API where contact updates are much more capable than calendar/todo updates.

Current State

✅ Fully Implemented (VCardFields)

FN (Formatted Name)
N (Structured Name)
EMAIL
TEL (Phone)
ORG (Organization)
TITLE (Job Title)
NOTE
URL

⚠️ MVP Only (EventFields)

SUMMARY ✅
DESCRIPTION ✅
LOCATION ❌ (commented as "future")
DTSTART ❌ (commented as "future")
DTEND ❌ (commented as "future")
RRULE ❌ (commented as "future")

⚠️ MVP Only (TodoFields)

SUMMARY ✅
DESCRIPTION ✅
STATUS ❌ (commented as "future")
PRIORITY ❌ (commented as "future")
PERCENT_COMPLETE ❌ (commented as "future")
DUE ❌ (commented as "future")

Proposed Implementation

EventFields Priority

High Priority:

LOCATION - Simple string field, easy to implement
DTSTART - Essential for event updates, needs timezone handling
DTEND - Essential for event updates, needs timezone handling

Medium Priority:

RRULE - Complex but very useful for recurring events

TodoFields Priority

High Priority:

STATUS - Enum field (NEEDS-ACTION | IN-PROCESS | COMPLETED | CANCELLED)
DUE - DateTime field, similar to DTSTART/DTEND
PRIORITY - Integer 0-9

Medium Priority:

PERCENT_COMPLETE - Integer 0-100

Use Cases

Event Updates

// Currently: Only title/description
updateEventFields(event, {
  SUMMARY: "Team Meeting",
  DESCRIPTION: "Q1 Planning"
});

// Desired: Location and time updates
updateEventFields(event, {
  SUMMARY: "Team Meeting",
  LOCATION: "Conference Room A",
  DTSTART: "20250115T100000Z",
  DTEND: "20250115T110000Z"
});

Todo Updates

// Currently: Only title/description
updateTodoFields(todo, {
  SUMMARY: "Fix login bug"
});

// Desired: Status and priority updates
updateTodoFields(todo, {
  SUMMARY: "Fix login bug",
  STATUS: "IN-PROCESS",
  PRIORITY: 1,
  DUE: "20250120T170000Z"
});

Technical Considerations

DateTime Handling

Need to support both UTC (Z suffix) and timezone-specific formats
All-day events use YYYYMMDD format (no time component)
Must preserve VTIMEZONE components

Status Validation

Todo STATUS must validate against RFC 5545 allowed values
Consider using TypeScript enums for type safety

Recurrence Rules (RRULE)

Most complex field to implement
Could be implemented as string first, validated later
Full RRULE parsing can be deferred to phase 2

Benefits

API Consistency: Events/Todos would have similar capabilities as vCards
Developer Experience: Reduces need for raw iCal string manipulation
LLM-Friendly: AI agents can update events without understanding iCal format
MCP Integration: Better integration with Model Context Protocol tools

Implementation Approach

Phase 1 (Simple Fields):

LOCATION (string)
STATUS (enum)
PRIORITY (number)

Phase 2 (DateTime Fields):

DTSTART, DTEND, DUE
Timezone handling
All-day event support

Phase 3 (Complex Fields):

RRULE parsing and validation
PERCENT_COMPLETE

References

RFC 5545: iCalendar specification
src/types/fieldUpdates.ts: Type definitions with commented future fields
src/util/calendarFieldUpdater.ts: Event field updater implementation
src/util/todoFieldUpdater.ts: Todo field updater implementation
src/util/vCardFieldUpdater.ts: Complete vCard implementation (reference)

## Summary Currently, field-based updates for Events (`updateEventFields`) and Todos (`updateTodoFields`) only support `SUMMARY` and `DESCRIPTION` fields, while vCard updates (`updateVCardFields`) support 8+ fields. This creates an imbalanced API where contact updates are much more capable than calendar/todo updates. ## Current State ### ✅ Fully Implemented (VCardFields) - `FN` (Formatted Name) - `N` (Structured Name) - `EMAIL` - `TEL` (Phone) - `ORG` (Organization) - `TITLE` (Job Title) - `NOTE` - `URL` ### ⚠️ MVP Only (EventFields) - `SUMMARY` ✅ - `DESCRIPTION` ✅ - `LOCATION` ❌ (commented as "future") - `DTSTART` ❌ (commented as "future") - `DTEND` ❌ (commented as "future") - `RRULE` ❌ (commented as "future") ### ⚠️ MVP Only (TodoFields) - `SUMMARY` ✅ - `DESCRIPTION` ✅ - `STATUS` ❌ (commented as "future") - `PRIORITY` ❌ (commented as "future") - `PERCENT_COMPLETE` ❌ (commented as "future") - `DUE` ❌ (commented as "future") ## Proposed Implementation ### EventFields Priority **High Priority:** - `LOCATION` - Simple string field, easy to implement - `DTSTART` - Essential for event updates, needs timezone handling - `DTEND` - Essential for event updates, needs timezone handling **Medium Priority:** - `RRULE` - Complex but very useful for recurring events ### TodoFields Priority **High Priority:** - `STATUS` - Enum field (`NEEDS-ACTION | IN-PROCESS | COMPLETED | CANCELLED`) - `DUE` - DateTime field, similar to DTSTART/DTEND - `PRIORITY` - Integer 0-9 **Medium Priority:** - `PERCENT_COMPLETE` - Integer 0-100 ## Use Cases ### Event Updates ```typescript // Currently: Only title/description updateEventFields(event, { SUMMARY: "Team Meeting", DESCRIPTION: "Q1 Planning" }); // Desired: Location and time updates updateEventFields(event, { SUMMARY: "Team Meeting", LOCATION: "Conference Room A", DTSTART: "20250115T100000Z", DTEND: "20250115T110000Z" }); ``` ### Todo Updates ```typescript // Currently: Only title/description updateTodoFields(todo, { SUMMARY: "Fix login bug" }); // Desired: Status and priority updates updateTodoFields(todo, { SUMMARY: "Fix login bug", STATUS: "IN-PROCESS", PRIORITY: 1, DUE: "20250120T170000Z" }); ``` ## Technical Considerations ### DateTime Handling - Need to support both UTC (Z suffix) and timezone-specific formats - All-day events use YYYYMMDD format (no time component) - Must preserve VTIMEZONE components ### Status Validation - Todo STATUS must validate against RFC 5545 allowed values - Consider using TypeScript enums for type safety ### Recurrence Rules (RRULE) - Most complex field to implement - Could be implemented as string first, validated later - Full RRULE parsing can be deferred to phase 2 ## Benefits 1. **API Consistency**: Events/Todos would have similar capabilities as vCards 2. **Developer Experience**: Reduces need for raw iCal string manipulation 3. **LLM-Friendly**: AI agents can update events without understanding iCal format 4. **MCP Integration**: Better integration with Model Context Protocol tools ## Implementation Approach **Phase 1 (Simple Fields):** - `LOCATION` (string) - `STATUS` (enum) - `PRIORITY` (number) **Phase 2 (DateTime Fields):** - `DTSTART`, `DTEND`, `DUE` - Timezone handling - All-day event support **Phase 3 (Complex Fields):** - `RRULE` parsing and validation - `PERCENT_COMPLETE` ## References - RFC 5545: iCalendar specification - `src/types/fieldUpdates.ts`: Type definitions with commented future fields - `src/util/calendarFieldUpdater.ts`: Event field updater implementation - `src/util/todoFieldUpdater.ts`: Todo field updater implementation - `src/util/vCardFieldUpdater.ts`: Complete vCard implementation (reference)