ICS Standard Builder

This package is a standards compliant generator of ICS files.

In the end, you will be able to use this package to generate events, to-dos, journal entries, and free/busy entries.

Table of Contents

1. Examples
2. Api
       2.1 Builders
           2.1.1 Calendar Builder
           2.1.2 Event Builder
           2.1.3 Timespan Builder
       2.2 Objects
           2.2.1 Attendee
           2.2.2 Conference
           2.2.3 Organizer
       2.3 Constants
           2.3.1 Availability
           2.3.2 Calendar User Type
           2.3.3 Display
           2.3.4 Feature Type
           2.3.5 Role
           2.3.6 Rsvp Type
       2.4 Utility Methods
           2.4.1 formatDate
           2.4.2 validateEmail

Examples

Simple Event

const {
    CalendarBuilder,
    EventBuilder,
    Attendee,
    Organizer,
    Role,
    CalendarUserType,
    RSVPType
} = require('ics-standard-builder')

/*

    The Calendar Builder is the container and the actual generator of the *.ics file

*/
var c = new CalendarBuilder()
    .setUrl('http://www.mycalendar.com')
    .setSource('http://www.mycalendar.com/test.ics')
    .setColor('red')
    .addCategory('Meeting')
    .addCategories('my meeting, you meeting')
    .setName('HOME')

/*

    Now lets build a single event by instantiating an Event Builder
    We can create the bare minimum required for an event

*/
var eb = new EventBuilder()
eb.setDescription('Here is a test description')
    .addOrganizer(new Organizer('[email protected]', 'Test Organizer', null, '[email protected]'))
    .addAttendee(
        new Attendee(
            '[email protected]',
            'Test Attendee',
            null,
            '[email protected]',
            '[email protected]',
            '[email protected]',
            '[email protected]',
            Role.CHAIR,
            CalendarUserType.INDIVIDUAL,
            RSVPType.TRUE
        )
    )
    .setStart(new Date(2021, 0, 1, 20, 00))
    .setEnd(new Date(2021, 0, 2, 20, 00))
    .setSummary('Party Time')
    .setDescription("We're having a pool party")
    .setImageUrl('http://www.myimage.com/thumbnail.jpg')
    .addConferenceInfo(new Conference(FeatureType.AUDIO, 'Moderator dial-in:tel:+1-412-555-0123,,,654321'))
    .addConferenceInfo(
        new Conference([FeatureType.AUDIO, FeatureType.MODERATOR], 'Moderator dial-in:tel:+1-412-555-0123,,,654321')
    )

//Now that we have described our event, we can add it to the Calendar Builder
c.addEventBuilder(eb)

//All that is left is to call the build the file contents
let icsContent = c.build()

//At this point you use which ever method you want to use to create the file
//For testing I just pushed the console output to a file
console.log(icsContent)

//The call from the terminal then becomes:
// node index.js > test.ics

Builders

Calendar Builder

Reference https://tools.ietf.org/html/rfc5545#section-3.4

Methods

addEventBuilder
builder represents a single event that has been constructed using the Event Builder
Params:
Name | Type | Required for Calendar |
---- | ---- | -------- |
builder | EventBuilder | Yes |

build
Compiles configuration and returns a ICalendar compliant string
Params: None
  

addCategory
Adds the category for the calendar
Params:
Name | Type | Required for Calendar |
---- | ---- | -------- |
category | string | No |

addCategories
Adds 1 or more categories for the calendar
Params:
Name | Type | Required for Calendar |
---- | ---- | -------- |
categories | string array | No |

setColor Sets the color of the calendar in the client
Params:
Name | Type | Required for Calendar | ---- | ---- | -------- | cssColorName | string array | No |

  
NOTE: This string value must be a valid CSS3 Color Name
Reference: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value   

setDescription
Sets the description of the calendar that can be shown in the client
Params:
Name | Type | Required for Calendar |
---- | ---- | -------- |
description | string | No |

setLastModified
Sets the last modified date, allowing the client to check for more recent versions
Params:
Name | Type | Required for Calendar |
---- | ---- | -------- |
date | Date | No |

setName
Sets the name of the calendar that can be shown in the client
Params:
Name | Type | Required for Calendar |
---- | ---- | -------- |
name | string | No |

setSource
Sets the SOURCE property for the ICalendar core object Params:
Name | Type | Required for Calendar |
---- | ---- | -------- |
url | string | No |

setRefreshInterval
Sets the refresh interval determines the frequency of update checking
Params:
Name | Type | Required for Calendar |
---- | ---- | -------- |
intervalType | Timespan | No |
value | integer | No |

setUrl Sets the URL property for the ICalendar core object Params:
Name | Type | Required for Calendar |
---- | ---- | -------- |
url | string | No |

Event Builder

Reference: https://tools.ietf.org/html/rfc5545#section-3.6.1

addAttendee
Add an attendee to the event object Params:
Name | Type | Required for Event |
---- | ---- | -------- |
attendee | Attendee | No |

addAttendees
Add 1 or more attendees to the event object Params:
Name | Type | Required for Event | ---- | ---- | -------- | attendees | Attendee array | No |

addCategory
Adds the category for the calendar
Params:
Name | Type | Required for Event | ---- | ---- | -------- | category | string | No |

addCategories
Adds 1 or more categories for the calendar
Params:
Name | Type | Required for Event | ---- | ---- | -------- | categories | string array | No |

addConferenceInfo
Adds conference reference to the event
Params:
Name | Type | Required for Event | ---- | ---- | -------- | conference |Conference | No |

addOrganizer
Adds an organizer to the event
Params:
Name | Type | Required for Event | ---- | ---- | -------- | organizer |Organizer | No |

addOrganizers
Adds an organizer to the event
Params:
Name | Type | Required for Event | ---- | ---- | -------- | organizers |Organizer array | No |

setColor Sets the color of the event in the client
Params:
Name | Type | Required for Calendar | ---- | ---- | -------- | cssColorName | string | No |

  
NOTE: This string value must be a valid CSS3 Color Name
Reference: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value   

setDescription Sets a description of the event Params:
Name | Type | Required for Event | ---- | ---- | -------- | description |string | No |

setDuration
Sets a duration of the event Params:
Name | Type | Required for Event |
---- | ---- | -------- |
description |string | No |

NOTE: You cannot specify a duration and a end date time, you must choose 1
  
  
setEnd
Sets the end date of the event Params:
Name | Type | Required for Event |
---- | ---- | -------- |
date |Date | No |

NOTE: You cannot specify a duration and a end date time, you must choose 1

setLastModified
Allows to override the last modified date which is defaulted to new Date()
Params:
Name | Type | Required for Event |
---- | ---- | -------- |
date |Date | No |

setStart
Sets the start date for the event Params:
Name | Type | Required for Event |
---- | ---- | -------- |
date |Date | Yes |

setSummary Sets a summary of the event Params:
Name | Type | Required for Event |
---- | ---- | -------- |
summary |string| No |

Timespan Builder

Reference https://tools.ietf.org/html/rfc5545#section-3.3.6

Methods

addSeconds
Add seconds to the timespan Params:
Name | Type |
---- | ---- |
second | integer |

addMinutes
Add minutes to the timespan
Params:
Name | Type |
---- | ---- |
minutes | integer |

addHours
Add hours to the timespan Params:
Name | Type |
---- | ---- |
hours | integer |

addDays
Add days to the timespan
Params:
Name | Type |
---- | ---- |
days | integer |

addWeeks
Add weeks to the timespan
Params:
Name | Type |
---- | ---- |
weeks | integer |

Objects

Attendee

Properties | Name | Type | ------- | ------ email | string
cn | string
directoryEntry | string
delegateFromEmail |string
delegateToEmail | string
member | string
sentBy | string
userType| CalendarUserType
role | Role
rsvpType | RSVPType

Conference

Properties | Name | Type | | ------- | ------ | feature | string array label | string

Organizer

Properties | Name | Type | | ------- | ------ | email | string
cn | string
directoryEntry | string
sentBy | string

Constants

Availability

| Name | Value | | --------------- | ---------------- | | FREE | FREE | | BUSY | BUSY | | BUSYUNAVAILABLE | BUSY-UNAVAILABLE | | BUSYTENTATIVE | BUSY-TENTATIVE |

CalendarUserType

| Name | Value | | ---------- | ---------- | | INDIVIDUAL | INDIVIDUAL | | GROUP | GROUP | | RESOURCE | RESOURCE | | ROOM | ROOM | | UNKNOWN | UNKNOWN |

DisplayType

| Name | Value | | --------- | --------- | | BADGE | BADGE | | GRAPHIC | GRAPHIC | | FULLSIZE | FULLSIZE | | THUMBNAIL | THUMBNAIL |

FeatureType

| Name | Value | | --------- | --------- | | AUDIO | AUDIO | | CHAT | CHAT | | FEED | FEED | | MODERATOR | MODERATOR | | PHONE | PHONE | | SCREEN | SCREEN | | VIDEO | VIDEO |

Role

| Name | Value | | -------------- | --------------- | | CHAIR | CHAIR | | REQPARTICIPANT | REQ-PARTICIPANT | | OPTPARTICIPANT | OPT-PARTICIPANT | | NONPARTICIPANT | NON-PARTICIPANT |

RSVPType

| Name | Value | | ----- | ----- | | TRUE | TRUE | | FALSE | FALSE |

Utilities

formatDate Formats a valid date to the required date format
Params:
Name | Type |
---- | ---- | date | Date |

isValidEmail Validates an email Params:
Name | Type |
---- | ---- | email | string |