Feature Request: Add field-based update methods for calendar objects #2

New issue

Closed

opened 2025-10-25 14:04:07 +00:00 by PhilflowIO · 0 comments

PhilflowIO commented

2025-10-25 14:04:07 +00:00

(Migrated from github.com)

Problem

Currently, updating a calendar event with tsdav requires providing the complete iCalendar string with all properties, timezones, and proper formatting. This creates several challenges:

Current Approach

await client.updateCalendarObject({
  calendarObject: {
    url: eventUrl,
    etag: eventEtag,
    data: "BEGIN:VCALENDAR\nVERSION:2.0\n..." // Full iCal string (often 500+ lines)
  }
});

Issues with Current Approach

Complex iCal Generation: Applications need to correctly generate valid iCal strings with proper timezone definitions, encoding, and structure
Error-Prone: Common issues include:
- Duplicate VTIMEZONE blocks
- Missing END tags
- Incorrect line folding
- Timezone data corruption
Unnecessary Overhead: To change just the event title, the entire iCal structure must be rebuilt
AI/LLM Integration Challenges: Language models struggle with generating valid iCal syntax, leading to frequent validation errors

Proposed Solution

Add field-based update methods that handle the iCal generation internally:

Option 1: Patch-style Updates

await client.patchCalendarObject({
  url: eventUrl,
  etag: eventEtag,
  updates: {
    summary: "Updated Title",
    dtstart: "2025-01-15T10:00:00Z",
    location: "New Location"
    // Only include fields to update
  }
});

Option 2: Full Field-based API

await client.updateCalendarObjectFields({
  url: eventUrl,
  etag: eventEtag,
  fields: {
    // Standard RFC 5545 properties
    summary: "Meeting",
    dtstart: "2025-01-15T10:00:00Z",
    dtend: "2025-01-15T11:00:00Z",
    description: "Team sync",
    location: "Office",
    
    // Extended properties (RFC 7986)
    color: "#FF5733",
    conference: ["https://meet.example.com/123"],
    
    // Raw properties for edge cases
    rawProperties: [
      "X-CUSTOM-FIELD:Value",
      "X-VENDOR-SPECIFIC:Data"
    ]
  }
});

Benefits

Simpler API: Developers work with plain JavaScript objects instead of iCal strings
Reduced Errors: Library handles proper iCal formatting and structure
Better DX: Clearer what fields can be updated
Preserve Unknown Properties: Fetch existing event, merge changes, maintain vendor-specific fields
AI/LLM Friendly: Structured data is much easier for AI systems to generate correctly

Implementation Approach

Fetch the existing calendar object
Parse iCal to internal representation
Merge the provided updates
Rebuild valid iCal string
Call existing updateCalendarObject with new data

This would be backwards compatible - the existing updateCalendarObject method would remain unchanged.

Use Cases

Simple field updates without dealing with iCal complexity
AI/LLM integrations that need reliable event updates
Applications that need to preserve vendor-specific properties
Bulk updates where only specific fields change

Similar APIs for Reference

Google Calendar API: Uses field-based updates
Microsoft Graph API: Patch operations with JSON
CalDAV servers internally parse and rebuild iCal anyway

Would love to contribute this feature. Happy to discuss the API design further!

## Problem Currently, updating a calendar event with tsdav requires providing the complete iCalendar string with all properties, timezones, and proper formatting. This creates several challenges: ### Current Approach ```javascript await client.updateCalendarObject({ calendarObject: { url: eventUrl, etag: eventEtag, data: "BEGIN:VCALENDAR\nVERSION:2.0\n..." // Full iCal string (often 500+ lines) } }); ``` ### Issues with Current Approach 1. **Complex iCal Generation**: Applications need to correctly generate valid iCal strings with proper timezone definitions, encoding, and structure 2. **Error-Prone**: Common issues include: - Duplicate VTIMEZONE blocks - Missing END tags - Incorrect line folding - Timezone data corruption 3. **Unnecessary Overhead**: To change just the event title, the entire iCal structure must be rebuilt 4. **AI/LLM Integration Challenges**: Language models struggle with generating valid iCal syntax, leading to frequent validation errors ## Proposed Solution Add field-based update methods that handle the iCal generation internally: ### Option 1: Patch-style Updates ```javascript await client.patchCalendarObject({ url: eventUrl, etag: eventEtag, updates: { summary: "Updated Title", dtstart: "2025-01-15T10:00:00Z", location: "New Location" // Only include fields to update } }); ``` ### Option 2: Full Field-based API ```javascript await client.updateCalendarObjectFields({ url: eventUrl, etag: eventEtag, fields: { // Standard RFC 5545 properties summary: "Meeting", dtstart: "2025-01-15T10:00:00Z", dtend: "2025-01-15T11:00:00Z", description: "Team sync", location: "Office", // Extended properties (RFC 7986) color: "#FF5733", conference: ["https://meet.example.com/123"], // Raw properties for edge cases rawProperties: [ "X-CUSTOM-FIELD:Value", "X-VENDOR-SPECIFIC:Data" ] } }); ``` ## Benefits 1. **Simpler API**: Developers work with plain JavaScript objects instead of iCal strings 2. **Reduced Errors**: Library handles proper iCal formatting and structure 3. **Better DX**: Clearer what fields can be updated 4. **Preserve Unknown Properties**: Fetch existing event, merge changes, maintain vendor-specific fields 5. **AI/LLM Friendly**: Structured data is much easier for AI systems to generate correctly ## Implementation Approach 1. Fetch the existing calendar object 2. Parse iCal to internal representation 3. Merge the provided updates 4. Rebuild valid iCal string 5. Call existing updateCalendarObject with new data This would be backwards compatible - the existing updateCalendarObject method would remain unchanged. ## Use Cases - Simple field updates without dealing with iCal complexity - AI/LLM integrations that need reliable event updates - Applications that need to preserve vendor-specific properties - Bulk updates where only specific fields change ## Similar APIs for Reference - Google Calendar API: Uses field-based updates - Microsoft Graph API: Patch operations with JSON - CalDAV servers internally parse and rebuild iCal anyway Would love to contribute this feature. Happy to discuss the API design further!