thejlifex / simple-caldav-client

Simple Caldav Client. Get, Save and Edit your calendar events from a nodejs server!.

Simple Caldav Client

Simple Caldav Client is a easy way to connect to a caldav server(owncloud, nextcloud, ...). It is the typescript implementation of this document that explain how to build a CalDAV client. The document is language-agnostic, and considering the massive scope of CalDAV, not complete.

You need only:

• username
• password.
• calendarUrl

Get a demo owncloud account here!

• Create some Events.
• Get this events from your Simple Caldav Client in the next step ↓ .

Example Usage

const startDate = new Date('December 17, 2018 03:24:00');
const calendarUrl = 'https://owncloud10.ocloud.de/remote.php/dav/calendars/admin/personal/';
const username = 'admin';
const password = 'demo123';

const calendarClient = new CalendarClient(calendarUrl, username, password);

calendarClient.getEvents(startDate).then((calendarEvents) => {
    console.log(calendarEvents);
}, (error) => {
    console.error(error);
});

API

/**
 * Get events from `startDate` up to optional `endDate`.
 * if you don't enter a endDate, if will return all events from `startDate`.
 */
CalendarClient.getEvents(startDate: Date, endDate?: Date): Promise<CalendarEvent[]>

/**
 * if the event already exits - it means same `event.uid` - the event will be updated
 * else it will be added.
 * @param event - the event you want to add or update.
 */
CalendarClient.addOrUpdateEvent(event: CalendarEvent): Promise<void>

/**
 * Remove the event in caldav server with the same uid like `event`.
 * @param event - the event you want to remove.
 */
CalendarClient.removeEvent(event: CalendarEvent): Promise<void>

export interface CalendarEvent {
    /**
     * unique ID of the event, needs to be unique and can be used to edit the event in the future
     * EXAMPLE: "eventid01"
     */
    uid: string;

    /**
     * The title of the event
     */
    summary: string;

    /**
     * Description of the event, optional.
     */
    description?: string;

    /**
     * Location of the event, optional.
     */
    location?: string;

    /**
     * Any timeformat handled by moment.js
     * EXAMPLE: new Date('Juni 20, 2019 11:24:00')
     */
    startDate: Date;

    /**
     * Any timeformat handled by moment.js
     * EXAMPLE: new Date('Juni 20, 2019 14:24:00')
     */
    endDate: Date;

    /**
     * time zone in the format
     * EXAMPLE: "Europe/Berlin"
     */
    tzid: string;

    /**
     * specify allDayEvent (no time just date) / note no timezone for allDayEvents
     */
    allDayEvent: boolean;

    /**
     * The source iCalendar data for this event.
     */
    iCalendarData: string;

    duration?: CalendarEventDuration;

    organizer?: string;

    attendees?: string[] | string[][];

    recurrenceId?: number;
}

Installation

Simple Caldav Client requires Node.js to run.

Clone this project.

$ git clone https://github.com/TheJLifeX/simple-caldav-client.git
$ cd simple-caldav-client

Install the dependencies and devDependencies.

$ npm install

Start the server.

$ npm run serve

Tech

Simple Caldav Client uses a number of open source projects to work properly:

• dependencies
  • expressjs Fast, unopinionated, minimalist web framework for Node.js
  • ical.js Javascript parser for calendar and vcard data.
  • moment Parse, validate, manipulate, and display dates and times in JavaScript.
  • xml2js XML to JavaScript object converter.
• devDependencies
  • typescript typescript is a typed javascript
  • @types/node typescript types for nodejs

Todos

• Get all calendar urls of a given user.

License

MIT