ics-generator

intent

converts structured event data into RFC 5545-compliant iCalendar (.ics) files that import cleanly into Google Calendar, Outlook, Apple Calendar, or any iCalendar client. use this when you have a schedule, study plan, task list, or event array that needs calendar portability without manual entry or third-party sync services.

inputs

event array (required)

• array of objects, each with:
  • summary (string): event title, required
  • description (string): event details, optional
  • start (ISO-8601 string or JavaScript Date): event start time, required, will be normalized to UTC
  • end (ISO-8601 string or JavaScript Date): event end time, required, will be normalized to UTC
  • colorId (string): Google Calendar color ID (1-11), optional, ignored by non-Google clients

lastDate (optional)

• ISO-8601 string or JavaScript Date marking the end of the previous chunk
• used only when generating sequential event batches
• if supplied, the skill shifts all start and end times forward by exactly one day (86400 seconds)
• if omitted, events use their supplied start/end times as-is

environment / runtime

• Node.js ≥ 20.0.0 (required for crypto.randomUUID())
• no external npm dependencies; uses only Node's built-in crypto module
• no API keys, OAuth tokens, or external service connections needed

procedure

1. validate input array

   • input: event array
   • check that array is non-empty; if empty, return empty VCALENDAR block (see output contract)
   • check that each event has summary (string) and start/end (ISO-8601 or Date)
   • output: validated event array or error thrown if required fields missing

2. normalize timestamps to UTC

   • input: each event's start and end fields
   • parse ISO-8601 string or Date object; convert to UTC if not already
   • format as YYYYMMDDTHHMMSSZ (RFC 5545 UTC format, Z suffix required)
   • output: normalized start and end strings for each event

3. apply lastDate offset (if supplied)

   • input: lastDate parameter, normalized start/end times from step 2
   • if lastDate is provided: calculate offset as the number of days between lastDate and the first event's start; add that offset (in seconds) to all event start and end times in the batch
   • if lastDate is not provided: skip this step
   • output: offset-adjusted start/end times

4. generate unique identifiers

   • input: validated event array
   • for each event, generate a UUID-v4 string using crypto.randomUUID()
   • format as event-<uuid>@calendar.local (ensures globally unique UID per RFC 5545)
   • output: UID for each event

5. build VCALENDAR header

   • input: none
   • output raw iCalendar header string:

     BEGIN:VCALENDAR
     VERSION:2.0
     PRODID:-//Google Inc//Google Calendar 70.6//EN
     CALSCALE:GREGORIAN
     

   • note: PRODID and CALSCALE are Google-specific and required for Google Calendar import; other clients tolerate them

6. build each VEVENT block

   • input: each event object (after normalization and offset), its UID
   • output for each event:

     BEGIN:VEVENT
     UID:<generated-UID>
     SUMMARY:<summary-text>
     DTSTART:<normalized-UTC-start>
     DTEND:<normalized-UTC-end>
     [DESCRIPTION:<description-text>]
     [X-GOOGLE-CALENDAR-COLOR:<colorId>]
     END:VEVENT
     

   • include DESCRIPTION line only if description field is non-empty
   • include X-GOOGLE-CALENDAR-COLOR line only if colorId is supplied
   • note: non-Google clients ignore X-GOOGLE-CALENDAR-COLOR without error

7. build VCALENDAR footer

   • input: none
   • output: END:VCALENDAR

8. concatenate and return

   • input: header (step 5), all VEVENT blocks (step 6), footer (step 7)
   • join with Unix newlines (\n, not CRLF)
   • output: complete .ics file content as string
   • note: string is ready to write to disk or return via HTTP response with content-type text/calendar; charset=utf-8

decision points

if event array is empty:

• return a minimal valid VCALENDAR block:

  BEGIN:VCALENDAR
  VERSION:2.0
  PRODID:-//Google Inc//Google Calendar 70.6//EN
  CALSCALE:GREGORIAN
  END:VCALENDAR
  

• this prevents import errors in calendar clients expecting iCalendar structure

if required field (summary, start, end) is missing or null:

• throw an error with field name and event index
• do not skip the event; the caller must fix the input
• rationale: silent skipping leads to hidden data loss

if start/end timestamp cannot be parsed (malformed ISO-8601 or invalid Date):

• throw an error identifying the field, value, and event index
• do not attempt fallback; invalid time data must be corrected upstream

if start time is after end time:

• throw an error; do not auto-swap
• rationale: swapping hides logic bugs in the event source

if lastDate is supplied:

• calculate day offset and apply to all events in the batch
• if lastDate is invalid or malformed, throw error (do not ignore)
• this ensures sequential batches have a predictable one-day gap

if colorId is supplied but is not a valid Google Calendar color ID (1-11):

• accept it anyway (insert as-is in X-GOOGLE-CALENDAR-COLOR line)
• rationale: Google Calendar's color ID set may expand; non-Google clients ignore the field
• note: if invalid, Google Calendar will display event in default color without error

if the event array is very large (10,000+ events):

• no built-in rate limiting or chunking; the skill generates a single .ics file
• caller should split large datasets into multiple batches before invoking
• output file size scales linearly with event count; filesystem and calendar client limits may apply

output contract

success output: .ics file content

• format: RFC 5545 iCalendar plain-text string (UTF-8)
• encoding: UTF-8 (no BOM)
• line endings: Unix newline (\n)
• structure: one VCALENDAR block containing zero or more VEVENT blocks
• minimum valid output (empty calendar):

  BEGIN:VCALENDAR
  VERSION:2.0
  PRODID:-//Google Inc//Google Calendar 70.6//EN
  CALSCALE:GREGORIAN
  END:VCALENDAR
  

how to write to disk

• use Node's fs.writeFileSync(filename, icsContent, 'utf8') or equivalent
• filename convention: events-<YYYYMMDD>.ics or similar
• file size: typically 200-500 bytes per event plus header/footer overhead

how to serve over HTTP

• set response header: Content-Type: text/calendar; charset=utf-8
• set response header: Content-Disposition: attachment; filename="events.ics"
• send the .ics string as response body
• HTTP 200 on success

validation notes

• the output is valid iCalendar per RFC 5545
• Google Calendar, Outlook, Apple Calendar, Thunderbird, and most third-party clients parse it without error
• the PRODID value is hardcoded to match Google Calendar's expectations; changing it may break Google Calendar import
• all timestamps are in UTC (Z suffix); calendar clients convert to user's local timezone on import

outcome signal

the skill worked if:

• the returned string contains BEGIN:VCALENDAR and END:VCALENDAR
• each event in the input array produces exactly one BEGIN:VEVENT … END:VEVENT block
• all timestamps in the output are formatted as YYYYMMDDTHHMMSSZ (UTC)
• the string can be written to a .ics file without error
• the .ics file imports into Google Calendar, Outlook, Apple Calendar, or equivalent without error messages like "Unable to launch event" or "Invalid calendar data"
• after import, each event appears on the correct date and time (adjusted for the user's local timezone)
• if colorId was supplied, the event displays in the corresponding Google Calendar color (non-Google clients ignore this)
• if lastDate was supplied, the first event of the new batch starts exactly one day after the lastDate value

the skill failed if:

• an error is thrown during execution (validation, parsing, or generation)
• the returned string is missing BEGIN:VCALENDAR or END:VCALENDAR
• event count in output (VEVENT blocks) does not match input array length
• a calendar client rejects the file or shows import errors
• timestamps are formatted incorrectly or are not in UTC
• a required field (UID, SUMMARY, DTSTART, DTEND) is missing from any VEVENT block