simple-caldav

caldav in JavaScript; made easy.

Note on Completeness

The caldav and ICS specifications are large. Additionally, I'm not sure I ever want to implement them completely. But I saw the need to a simple module that works with e.g. radicale and provides decent developer experience. simple-caldav is that attempt.

Installation

$ npm i --save simple-caldav

Usage

const SimpleCalDAV = require("simple-caldav");
const URI = "https://example.com/cal/";

const dav = new SimpleCalDAV(URI, { credentials: "include", mode: "cors"});
const evt = dav.getEvent("abc")
  .then(console.log)
  .catch(console.log);

For now, see tests.

Notes

We translate a VEVENT's STATUS & LOCATION in the whole library to the name _status & _location to make sure we're not violating any reserved words rules of JavaScript.
When initializing new SimpleCalDAV fetch request options can be supplied on the second parameter (type object).

Usage and CORS

When using simple-caldav in combination with a remote server and CORS starts to become an issue, make sure you allow the following CORS properties:

methods that need to be allowed: GET, POST, PUT, DELETE, REPORT, PROPFIND, OPTIONS
headers that need to be allowed: Content-Type, If-None-Match, Depth

Contributing

$ git clone git@github.com:TimDaub/simple-caldav.git
$ cd simple-caldav && npm i
$ npm run test

The process outlined in PUBLISH.md SHOULD be followed when releasing a new version of simple-caldav.

Changelog

0.8.0

Add ;LANGUAGE=locale to VEVENT & VALARM description, summary, location. Function interfaces and return values have changed therefore. Instead of strings, an object of the shape { value: "string, language: "locale"} is now required. The language prop is optional.
In some cases subject was wrongly used instead of summary. All occurrences have been changed to summary.
Some internal code now uses optional chaining, which is why node requires a version > 14 now.

0.7.1 (came after 0.8.0, branch)

Bump a few dependencies' versions to fix vulnerabilities

0.7.0

Instead of passing fetch's credentials option as "include" by default, it's now possible to add fetch request options when initializing the SimpleCalDAV class.
credentials: "include" aren't passed as default anymore.

0.6.0

For all fetch requests, allow passing credentials by using credentials: true
Add note on CORS

0.5.0

Remove xpath and xmldom dependencies for smaller builds.
Remove getETags method.

0.4.7 (after 0.5.0, branch)

Upgrade xmldom to v0.5.0

0.4.6

Add static applyDuration(date, duration) that allows applying an specifically-shaped duration to a JavaScript Date.

0.4.5

Add VALUE=DATE-TIME to absolute-time trigger in VALARM.
Add support for relative triggers. RELATED= syntax not yet supported.

0.4.4

When updating an event, alarm's attendee would wrongly collect action prefixes like mailto: or sms:, e.g. mailto:mailto:mailto:email@examlple.com.

0.4.3

Include href to event when calling getEvent or listEvents.

0.4.2

Add LOCATION property to VEVENT.
Add ORGANIZER;CN=:mailto property to VEVENT.

0.4.1

Fix UTC time zone shift calculation in formatDateTime.

0.4.0

Switched out moment.js with date-fns. Breaking change is that formatDateTime now only accepts Date objects, or throws otherwise.

0.3.5

Bug fix: When adding multiple alarms, ,BEGIN:VALARM would show up in VEVENT text.

0.3.4

Bug fix: When adding a status to an event, in its ical representation status statement didn't add new \n new line instruction.

0.3.3

Add static SimpleCalDAV.extractUid(href) method.

0.3.2

Add _status property to event.

0.3.1

Bug fix: syncCollection wasn't able to detect a single VEVENT deletion event and simply returned an empty array.

0.3.0

Bug fix: Stop attempting to parse relative-time VALARMS, as ical.js isn't capable of doing that either. Relative-time VALARMS are now ignored instead. Previously they threw.

0.2.2

Bug fix: Ensure correct order of etag and href properties returned from syncCollection.

0.2.1

Introduce new method for retrieving single events with uid: getEvent(uid).
Parse and include VALARMs in getEvent and listEvents.

0.2.0

Removed TraversalError from code base entirely.
listEvents now returns an empty array when no events are found or an invalid xml gets passed.
Instead of throwing TraversalError, SimpleCalDAV.traverseXML now returns an empty array when path couldn't be found.
Added getSyncToken method to retrieve a sync token from a server.
Added syncCollection to receive a diff of an entire collection with a sync token.
Added ServerError that is thrown when there are problems with the server.

0.1.3

Fix bug in VALARM construction.

0.1.2

Fix bug in VEVENT construction.

0.1.1

Allow adding VALARMS to VEVENTS.

0.1.0

Transform ical.js events to simple JSON objects and all customizable transformation parameter on listEvents method.

lxg/simple-caldav