Files
API/src/models/calendar/events/icalgenerator.service.ts
T
PaddyandClaude Opus 5.5 a574e93359 Escape and fold the iCal export, serve it as text/calendar, add subscription links
- iCal export: RFC 5545 text escaping for SUMMARY, DESCRIPTION and LOCATION,
  line folding at 75 octets (UTF-8 aware), CRLF line endings, and
  Content-Type text/calendar instead of the inferred text/html. A line break
  in a description used to end the property early; the new calendar
  frontend has a multi-line description field.
- formatDate no longer shifts the event's end date in place.
- GET /calendar/events/subscriptions: the iCal URL of every calendar, with
  its shared password where needed, for the calendar app's "Abonnieren"
  dialog. Editors only (requireAppAccess('calendar')), the shared password
  is not accepted there, never cached; calendars without a configured
  credential are left out.
- Tests for both; documented in docs/calendar-ical.md.

Backwards compatible with the current Angular calendar app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 22:15:59 +02:00

251 lines
7.3 KiB
TypeScript

import {Event} from './event.interface.js';
/**
* Interface to external classes - Turns the given events into an ical string
* @param events
*/
export const convertToIcal = async (events: Event[]): Promise<string> => {
try {
let ical: iCalFile = {body: []};
generateHeaderInfo(ical);
generateFooterInfo(ical);
for (let event of events) {
addEventToFile(ical, event);
}
return toContentLines(serializeIcalFile(ical));
} catch (err) {
throw err;
}
};
/**
* Method to serialize an iCalFile object into an ical string
* @param ical
*/
const serializeIcalFile = (ical: iCalFile): string => {
let returnString = '';
returnString += ical.header;
for (let event of ical.body) {
returnString += serializeIcalEvent(event);
}
returnString += ical.footer;
return returnString;
};
/**
* Method to serialize a single ical event into an ical event string
* @param icalevent
*/
const serializeIcalEvent = (icalevent: iCalEvent): string => {
let returnString = '';
returnString += icalevent.header;
returnString += 'UID:' + icalevent.uid;
returnString += 'DTSTAMP:' + icalevent.created;
returnString += 'ORGANIZER:' + icalevent.organizer;
if(icalevent.wholeDay) {
returnString += 'DTSTART;VALUE=DATE:' + icalevent.start;
returnString += 'DTEND;VALUE=DATE:' + icalevent.end;
} else {
returnString += 'DTSTART;TZID=Europe/Berlin:' + icalevent.start;
returnString += 'DTEND;TZID=Europe/Berlin:' + icalevent.end;
}
if(!isNullOrBlank(icalevent.repeatFrequency)) returnString += 'RRULE:FREQ=' + icalevent.repeatFrequency;
returnString += 'SUMMARY:' + icalevent.summary;
if(!isNullOrBlank(icalevent.description)) returnString += 'DESCRIPTION:' + icalevent.description;
if(!isNullOrBlank(icalevent.location)) returnString += 'LOCATION:' + icalevent.location;
if(!isNullOrBlank(icalevent.url)) returnString += 'URL:' + icalevent.url;
returnString += icalevent.footer;
return returnString;
};
/**
* Method to generate the ical header string
* @param ical
*/
const generateHeaderInfo = (ical: iCalFile) => {
ical.header = 'BEGIN:VCALENDAR\n' +
'VERSION:2.0\n' +
'PRODID:-//Nachklang e.V./Nachklang Calendar//NONSGML v1.0//EN\n' +
'CALSCALE:GREGORIAN\n' +
'BEGIN:VTIMEZONE\n' +
'TZID:Europe/Berlin\n' +
'LAST-MODIFIED:20201011T015911Z\n' +
'TZURL:http://tzurl.org/zoneinfo-outlook/Europe/Berlin\n' +
'X-LIC-LOCATION:Europe/Berlin\n' +
'BEGIN:DAYLIGHT\n' +
'TZNAME:CEST\n' +
'TZOFFSETFROM:+0100\n' +
'TZOFFSETTO:+0200\n' +
'DTSTART:19700329T020000\n' +
'RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU\n' +
'END:DAYLIGHT\n' +
'BEGIN:STANDARD\n' +
'TZNAME:CET\n' +
'TZOFFSETFROM:+0200\n' +
'TZOFFSETTO:+0100\n' +
'DTSTART:19701025T030000\n' +
'RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU\n' +
'END:STANDARD\n' +
'END:VTIMEZONE\n';
};
/**
* Method to generate the ical footer info
* @param ical
*/
const generateFooterInfo = (ical: iCalFile) => {
ical.footer = 'END:VCALENDAR';
};
/**
* Method to add events to the iCalFile object
* @param ical
* @param event
*/
const addEventToFile = (ical: iCalFile, event: Event) => {
ical.body.push(createIcalEvent(event));
};
/**
* Method to turn an event object into an iCalEvent object
* @param event
*/
const createIcalEvent = (event: Event): iCalEvent => {
// Free text is escaped (see escapeText); the URL is a URI value, which has
// no escapes - it only must not break the line.
let description = event.description ? escapeText(event.description) + '\n' : '';
let location = event.location ? escapeText(event.location) + '\n' : '';
let url = event.url ? event.url.replace(/[\r\n]+/g, '') + '\n' : '';
return {
header: 'BEGIN:VEVENT\n',
uid: event.uuid + '\n',
created: formatDate(event.createdDate) + 'Z\n',
organizer: event.createdBy + '\n',
start: formatDate(event.startDateTime, event.wholeDay) + '\n',
end: formatDate(event.endDateTime, event.wholeDay, true) + '\n',
repeatFrequency: event.repeatFrequency ? event.repeatFrequency + '\n' : '',
summary: escapeText(event.name) + '\n',
description: description,
location: location,
url: url,
wholeDay: event.wholeDay,
footer: 'END:VEVENT\n'
};
};
/**
* Helper method to format dates in a valid iCal format
* @param date
* @param wholeDayFormat
* @param isEndDate
*/
const formatDate = (input: Date, wholeDayFormat: boolean = false, isEndDate: boolean = false): string => {
let returnString = '';
// A copy: this used to shift the caller's Date in place, so the event object
// came out of the export with its end a day later than it went in.
const date = new Date(input);
// We need to do this for whole day events as otherwise the event ends one day too early
if(wholeDayFormat && isEndDate) date.setDate(date.getDate() + 1)
returnString += date.getFullYear();
returnString += (date.getMonth() + 1).toString().padStart(2, '0'); // +1 Because JS sucks
returnString += date.getDate().toString().padStart(2, '0');
if(!wholeDayFormat) {
returnString += 'T';
returnString += date.getHours().toString().padStart(2, '0');
returnString += date.getMinutes().toString().padStart(2, '0');
returnString += date.getSeconds().toString().padStart(2, '0');
}
return returnString;
};
export interface iCalFile {
header?: string;
body: iCalEvent[];
footer?: string;
}
export interface iCalEvent {
header: string;
uid: string;
created: string;
organizer: string;
start: string;
end: string;
summary: string;
description: string;
location: string;
url: string;
wholeDay: boolean;
repeatFrequency: string;
footer: string;
}
/**
* RFC 5545 §3.3.11 TEXT escaping. Without it a description with a line break
* ended the DESCRIPTION property early and the rest of the text was read as a
* new (garbage) property, and an unescaped `,` or `;` is invalid in the value.
* The backslash goes first, or the escapes added after it would be doubled.
*/
export const escapeText = (value: string): string =>
value
.replace(/\\/g, '\\\\')
.replace(/;/g, '\\;')
.replace(/,/g, '\\,')
.replace(/\r\n|\r|\n/g, '\\n');
const MAX_LINE_OCTETS = 75;
/**
* RFC 5545 §3.1 line folding: no content line longer than 75 octets, a longer
* one continues on the next line after a single leading space. Counts UTF-8
* octets, not characters, and never splits inside a character - "ü" is two
* octets and a fold between them corrupts it.
*/
export const foldLine = (line: string): string => {
const parts: string[] = [];
let current = '';
let octets = 0;
for (const char of line) {
const size = Buffer.byteLength(char, 'utf8');
// A continuation line's leading space counts towards its 75.
const limit = parts.length === 0 ? MAX_LINE_OCTETS : MAX_LINE_OCTETS - 1;
if (octets + size > limit) {
parts.push(current);
current = '';
octets = 0;
}
current += char;
octets += size;
}
parts.push(current);
return parts.join('\r\n ');
};
/**
* The generator builds the file with bare `\n` line ends; the format wants
* every content line folded and terminated by CRLF (RFC 5545 §3.1).
*/
const toContentLines = (ical: string): string =>
ical
.split('\n')
.filter((line) => line !== '')
.map(foldLine)
.join('\r\n') + '\r\n';
/**
* Checks if a given string is null, undefined or blank
* @param str The string to check
*/
function isNullOrBlank(str: string | null): boolean {
return str === null || str === undefined || str.trim() === '';
}