ical-generator
Version:
ical-generator is a small piece of code which generates ical calendar files
1,745 lines (1,741 loc) • 68.6 kB
text/typescript
declare enum ICalAttendeeRole {
CHAIR = "CHAIR",
NON = "NON-PARTICIPANT",
OPT = "OPT-PARTICIPANT",
REQ = "REQ-PARTICIPANT"
}
declare enum ICalAttendeeScheduleAgent {
CLIENT = "CLIENT",
NONE = "NONE",
SERVER = "SERVER"
}
declare enum ICalAttendeeStatus {
ACCEPTED = "ACCEPTED",
DECLINED = "DECLINED",
DELEGATED = "DELEGATED",
NEEDSACTION = "NEEDS-ACTION",
TENTATIVE = "TENTATIVE"
}
declare enum ICalAttendeeType {
GROUP = "GROUP",
INDIVIDUAL = "INDIVIDUAL",
RESOURCE = "RESOURCE",
ROOM = "ROOM",
UNKNOWN = "UNKNOWN"
}
interface ICalAttendeeData {
delegatedFrom?: ICalAttendee | ICalAttendeeData | null | string;
delegatedTo?: ICalAttendee | ICalAttendeeData | null | string;
delegatesFrom?: ICalAttendee | ICalAttendeeData | null | string;
delegatesTo?: ICalAttendee | ICalAttendeeData | null | string;
email: string;
mailto?: null | string;
name?: null | string;
role?: ICalAttendeeRole;
rsvp?: boolean | null;
scheduleAgent?: ICalAttendeeScheduleAgent | ICalXName | null;
sentBy?: null | string;
status?: ICalAttendeeStatus | null;
type?: ICalAttendeeType | null;
x?: [string, string][] | Record<string, string> | {
key: string;
value: string;
}[];
}
interface ICalAttendeeJSONData {
delegatedFrom: null | string;
delegatedTo: null | string;
email: string;
mailto: null | string;
name: null | string;
role: ICalAttendeeRole;
rsvp: boolean | null;
sentBy: null | string;
status: ICalAttendeeStatus | null;
type: ICalAttendeeType | null;
x: {
key: string;
value: string;
}[];
}
type ICalXName = `X-${string}`;
/**
* Usually you get an {@link ICalAttendee} object like this:
*
* ```javascript
* import ical from 'ical-generator';
* const calendar = ical();
* const event = calendar.createEvent();
* const attendee = event.createAttendee({ email: 'mail@example.com' });
* ```
*
* You can also use the {@link ICalAttendee} object directly:
*
* ```javascript
* import ical, {ICalAttendee} from 'ical-generator';
* const attendee = new ICalAttendee({ email: 'mail@example.com' });
* event.attendees([attendee]);
* ```
*/
declare class ICalAttendee {
private readonly data;
private readonly parent;
/**
* Constructor of {@link ICalAttendee}. The event reference is
* required to query the calendar's timezone when required.
*
* @param data Attendee Data
* @param parent Reference to ICalEvent object
*/
constructor(data: ICalAttendeeData, parent: ICalAlarm | ICalEvent);
/**
* Get the attendee's delegated-from field
* @since 0.2.0
*/
delegatedFrom(): ICalAttendee | null;
/**
* Set the attendee's delegated-from field
*
* Creates a new Attendee if the passed object is not already a
* {@link ICalAttendee} object. Will set the `delegatedTo` and
* `delegatedFrom` attributes.
*
* @param delegatedFrom
*/
delegatedFrom(delegatedFrom: ICalAttendee | ICalAttendeeData | null | string): this;
/**
* Get the attendee's delegated-to value.
* @since 0.2.0
*/
delegatedTo(): ICalAttendee | null;
/**
* Set the attendee's delegated-to field.
*
* Creates a new Attendee if the passed object is not already a
* {@link ICalAttendee} object. Will set the `delegatedTo` and
* `delegatedFrom` attributes.
*
* Will also set the `status` to `DELEGATED`, if attribute is set.
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
* const attendee = cal.createAttendee();
*
* attendee.delegatesTo({email: 'foo@bar.com', name: 'Foo'});
```
*
* @since 0.2.0
*/
delegatedTo(delegatedTo: ICalAttendee | ICalAttendeeData | null | string): this;
/**
* Create a new attendee this attendee delegates from and returns
* this new attendee. Creates a new attendee if the passed object
* is not already an {@link ICalAttendee}.
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
* const attendee = cal.createAttendee();
*
* attendee.delegatesFrom({email: 'foo@bar.com', name: 'Foo'});
* ```
*
* @since 0.2.0
*/
delegatesFrom(options: ICalAttendee | ICalAttendeeData | string): ICalAttendee;
/**
* Create a new attendee this attendee delegates to and returns
* this new attendee. Creates a new attendee if the passed object
* is not already an {@link ICalAttendee}.
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
* const attendee = cal.createAttendee();
*
* attendee.delegatesTo({email: 'foo@bar.com', name: 'Foo'});
* ```
*
* @since 0.2.0
*/
delegatesTo(options: ICalAttendee | ICalAttendeeData | string): ICalAttendee;
/**
* Get the attendee's email address
* @since 0.2.0
*/
email(): string;
/**
* Set the attendee's email address
* @since 0.2.0
*/
email(email: string): this;
/**
* Get the attendee's email address
* @since 1.3.0
*/
mailto(): null | string;
/**
* Set the attendee's email address
* @since 1.3.0
*/
mailto(mailto: null | string): this;
/**
* Get the attendee's name
* @since 0.2.0
*/
name(): null | string;
/**
* Set the attendee's name
* @since 0.2.0
*/
name(name: null | string): this;
/**
* Get attendee's role
* @since 0.2.0
*/
role(): ICalAttendeeRole;
/**
* Set the attendee's role, defaults to `REQ` / `REQ-PARTICIPANT`.
* Checkout {@link ICalAttendeeRole} for available roles.
*
* @since 0.2.0
*/
role(role: ICalAttendeeRole): this;
/**
* Get attendee's RSVP expectation
* @since 0.2.1
*/
rsvp(): boolean | null;
/**
* Set the attendee's RSVP expectation
* @since 0.2.1
*/
rsvp(rsvp: boolean | null): this;
/**
* Get attendee's schedule agent
* @since 9.0.0
*/
scheduleAgent(): ICalAttendeeScheduleAgent | ICalXName;
/**
* Set attendee's schedule agent
* See {@link ICalAttendeeScheduleAgent} for available values.
* You can also use custom X-* values.
*
* @since 9.0.0
*/
scheduleAgent(scheduleAgent: ICalAttendeeScheduleAgent | ICalXName | null): this;
/**
* Get the acting user's email adress
* @since 3.3.0
*/
sentBy(): null | string;
/**
* Set the acting user's email adress
* @since 3.3.0
*/
sentBy(email: null | string): this;
/**
* Get attendee's status
* @since 0.2.0
*/
status(): ICalAttendeeStatus | null;
/**
* Set the attendee's status. See {@link ICalAttendeeStatus}
* for available status options.
*
* @since 0.2.0
*/
status(status: ICalAttendeeStatus | null): this;
/**
* Return a shallow copy of the attendee's options for JSON stringification.
* Can be used for persistence.
*
* @since 0.2.4
*/
toJSON(): ICalAttendeeJSONData;
/**
* Return generated attendee as a string.
*
* ```javascript
* console.log(attendee.toString()); // → ATTENDEE;ROLE=…
* ```
*/
toString(): string;
/**
* Get attendee's type (a.k.a. CUTYPE)
* @since 0.2.3
*/
type(): ICalAttendeeType;
/**
* Set attendee's type (a.k.a. CUTYPE).
* See {@link ICalAttendeeType} for available status options.
*
* @since 0.2.3
*/
type(type: ICalAttendeeType | null): this;
/**
* Set X-* attributes. Woun't filter double attributes,
* which are also added by another method (e.g. status),
* so these attributes may be inserted twice.
*
* ```javascript
* attendee.x([
* {
* key: "X-MY-CUSTOM-ATTR",
* value: "1337!"
* }
* ]);
*
* attendee.x([
* ["X-MY-CUSTOM-ATTR", "1337!"]
* ]);
*
* attendee.x({
* "X-MY-CUSTOM-ATTR": "1337!"
* });
* ```
*
* @since 1.9.0
*/
x(keyOrArray: [string, string][] | Record<string, string> | {
key: string;
value: string;
}[]): this;
/**
* Set a X-* attribute. Woun't filter double attributes,
* which are also added by another method (e.g. status),
* so these attributes may be inserted twice.
*
* ```javascript
* attendee.x("X-MY-CUSTOM-ATTR", "1337!");
* ```
*
* @since 1.9.0
*/
x(keyOrArray: string, value: string): this;
/**
* Get all custom X-* attributes.
* @since 1.9.0
*/
x(): {
key: string;
value: string;
}[];
}
declare enum ICalEventRepeatingFreq {
DAILY = "DAILY",
HOURLY = "HOURLY",
MINUTELY = "MINUTELY",
MONTHLY = "MONTHLY",
SECONDLY = "SECONDLY",
WEEKLY = "WEEKLY",
YEARLY = "YEARLY"
}
declare enum ICalWeekday {
FR = "FR",
MO = "MO",
SA = "SA",
SU = "SU",
TH = "TH",
TU = "TU",
WE = "WE"
}
/**
* ical-generator supports [native Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date),
* [moment.js](https://momentjs.com/) (and [moment-timezone](https://momentjs.com/timezone/), [Day.js](https://day.js.org/en/) and
* [Luxon](https://moment.github.io/luxon/)'s [DateTime](https://moment.github.io/luxon/docs/class/src/datetime.js~DateTime.html)
* objects. You can also pass a string which is then passed to javascript's Date internally.
*/
type ICalDateTimeValue = Date | ICalDayJsStub | ICalLuxonDateTimeStub | ICalMomentStub | ICalMomentTimezoneStub | string;
interface ICalDayJsStub {
format(format?: string): string;
isValid(): boolean;
toDate(): Date;
toJSON(): string;
tz(zone?: string): ICalDayJsStub;
utc(): ICalDayJsStub;
}
interface ICalDescription {
html?: string;
plain: string;
}
interface ICalGeo {
lat: number;
lon: number;
}
type ICalLocation = ICalLocationWithoutTitle | ICalLocationWithTitle;
interface ICalLocationWithoutTitle {
geo: ICalGeo;
}
interface ICalLocationWithTitle {
address?: string;
geo?: ICalGeo;
radius?: number;
title: string;
}
interface ICalLuxonDateTimeStub {
get isValid(): boolean;
setZone(zone?: string): ICalLuxonDateTimeStub;
toFormat(fmt: string): string;
toJSDate(): Date;
toJSON(): null | string;
zone: {
type: string;
};
}
interface ICalMomentDurationStub {
asSeconds(): number;
}
interface ICalMomentStub {
clone(): ICalMomentStub;
format(format?: string): string;
isValid(): boolean;
toDate(): Date;
toJSON(): string;
utc(): ICalMomentStub;
}
interface ICalMomentTimezoneStub extends ICalMomentStub {
clone(): ICalMomentTimezoneStub;
tz(): string | undefined;
tz(timezone: string): ICalMomentTimezoneStub;
utc(): ICalMomentTimezoneStub;
}
interface ICalOrganizer {
email?: string;
mailto?: string;
name: string;
sentBy?: string;
}
interface ICalRepeatingOptions {
byDay?: ICalWeekday | ICalWeekday[];
byMonth?: number | number[];
byMonthDay?: number | number[];
bySetPos?: number | number[];
count?: number;
exclude?: ICalDateTimeValue | ICalDateTimeValue[];
freq: ICalEventRepeatingFreq;
interval?: number;
startOfWeek?: ICalWeekday;
until?: ICalDateTimeValue;
}
interface ICalRRuleStub {
between(after: Date, before: Date, inc?: boolean, iterator?: (d: Date, len: number) => boolean): Date[];
toString(): string;
}
interface ICalTimezone {
generator?: (timezone: string) => null | string;
name: null | string;
}
interface ICalTZDateStub extends Date {
timeZone?: string;
withTimeZone(timezone?: null | string): ICalTZDateStub;
}
declare enum ICalAlarmType {
audio = "audio",
display = "display",
email = "email"
}
interface ICalAlarmBaseData {
attach?: ICalAttachment | null | string;
attendees?: ICalAttendee[] | ICalAttendeeData[];
description?: null | string;
relatesTo?: ICalAlarmRelatesTo | null;
repeat?: ICalAlarmRepeatData | null;
summary?: null | string;
type?: ICalAlarmType;
x?: [string, string][] | Record<string, string> | {
key: string;
value: string;
}[];
}
type ICalAlarmData = ICalAlarmBaseData | ICalAlarmTriggerAfterData | ICalAlarmTriggerBeforeData | ICalAlarmTriggerData;
interface ICalAlarmJSONData {
attach: ICalAttachment | null;
attendees: ICalAttendee[];
description: null | string;
interval: null | number;
relatesTo: ICalAlarmRelatesTo | null;
repeat: ICalAlarmRepeatData | null;
summary: null | string;
trigger: number | string;
type: ICalAlarmType;
x: {
key: string;
value: string;
}[];
}
declare const ICalAlarmRelatesTo: {
readonly end: "END";
readonly start: "START";
};
type ICalAlarmRelatesTo = (typeof ICalAlarmRelatesTo)[keyof typeof ICalAlarmRelatesTo];
interface ICalAlarmRepeatData {
interval: number;
times: number;
}
type ICalAlarmTriggerAfterData = ICalAlarmBaseData & {
triggerAfter: ICalDateTimeValue | number;
};
type ICalAlarmTriggerBeforeData = ICalAlarmBaseData & {
triggerBefore: ICalDateTimeValue | number;
};
type ICalAlarmTriggerData = ICalAlarmBaseData & {
trigger: ICalDateTimeValue | number;
};
type ICalAlarmTypeValue = keyof ICalAlarmType;
interface ICalAttachment {
mime: null | string;
uri: string;
}
/**
* Usually you get an {@link ICalAlarm} object like this:
*
* ```javascript
* import ical from 'ical-generator';
* const calendar = ical();
* const event = calendar.createEvent();
* const alarm = event.createAlarm();
* ```
*
* You can also use the {@link ICalAlarm} object directly:
*
* ```javascript
* import ical, {ICalAlarm} from 'ical-generator';
* const alarm = new ICalAlarm();
* event.alarms([alarm]);
* ```
*/
declare class ICalAlarm {
private readonly data;
private readonly event;
/**
* Constructor of {@link ICalAttendee}. The event reference is required
* to query the calendar's timezone and summary when required.
*
* @param data Alarm Data
* @param event Reference to ICalEvent object
*/
constructor(data: ICalAlarmData, event: ICalEvent);
/**
* Get Attachment
* @since 0.2.1
*/
attach(): null | {
mime: null | string;
uri: string;
};
/**
* Set Alarm attachment. Used to set the alarm sound
* if alarm type is audio. Defaults to "Basso".
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
*
* event.createAlarm({
* attach: 'https://example.com/notification.aud'
* });
*
* // OR
*
* event.createAlarm({
* attach: {
* uri: 'https://example.com/notification.aud',
* mime: 'audio/basic'
* }
* });
* ```
*
* @since 0.2.1
*/
attach(attachment: null | string | {
mime?: null | string;
uri: string;
}): this;
/**
* Get all attendees
* @since 7.0.0
*/
attendees(): ICalAttendee[];
/**
* Add multiple attendees to your event
*
* @since 7.0.0
*/
attendees(attendees: (ICalAttendee | ICalAttendeeData | string)[]): this;
/**
* Creates a new {@link ICalAttendee} and returns it. Use options to prefill
* the attendee's attributes. Calling this method without options will create
* an empty attendee.
*
* @since 7.0.0
*/
createAttendee(data: ICalAttendee | ICalAttendeeData | string): ICalAttendee;
/**
* Get the alarm description. Used to set the alarm message
* if alarm type is `display`. If the alarm type is `email`, it's
* used to set the email body. Defaults to the event's summary.
*
* @since 0.2.1
*/
description(): null | string;
/**
* Set the alarm description. Used to set the alarm message
* if alarm type is `display`. If the alarm type is `email`, it's
* used to set the email body. Defaults to the event's summary.
*
* @since 0.2.1
*/
description(description: null | string): this;
/**
* Get to which time alarm trigger relates to.
* Can be either `START` or `END`. If the value is
* `START` the alarm is triggerd relative to the event start time.
* If the value is `END` the alarm is triggerd relative to the event end time
*
* @since 4.0.1
*/
relatesTo(): ICalAlarmRelatesTo | null;
/**
* Use this method to set to which time alarm trigger relates to.
* Works only if trigger is a `number`
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
* const alarm = cal.createAlarm();
*
* alarm.trigger(600); // -> 10 minutes before event starts
*
* alarm.relatesTo('START'); // -> 10 minutes before event starts
* alarm.relatesTo('END'); // -> 10 minutes before event ends
*
* alarm.trigger(-600); // -> 10 minutes after event starts
*
* alarm.relatesTo('START'); // -> 10 minutes after event starts
* alarm.relatesTo('END'); // -> 10 minutes after event ends
* ```
* @since 4.0.1
*/
relatesTo(relatesTo: ICalAlarmRelatesTo | null): this;
/**
* Get Alarm Repetitions
* @since 0.2.1
*/
repeat(): ICalAlarmRepeatData | null;
/**
* Set Alarm Repetitions. Use this to repeat the alarm.
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
*
* // repeat the alarm 4 times every 5 minutes…
* cal.createAlarm({
* repeat: {
* times: 4,
* interval: 300
* }
* });
* ```
*
* @since 0.2.1
*/
repeat(repeat: ICalAlarmRepeatData | null): this;
/**
* Get the alarm summary. Used to set the email subject
* if alarm type is `email`. Defaults to the event's summary.
*
* @since 7.0.0
*/
summary(): null | string;
/**
* Set the alarm summary. Used to set the email subject
* if alarm type is display. Defaults to the event's summary.
*
* @since 0.2.1
*/
summary(summary: null | string): this;
/**
* Return a shallow copy of the alarm's options for JSON stringification.
* Third party objects like moment.js values are stringified as well. Can
* be used for persistence.
*
* @since 0.2.4
*/
toJSON(): ICalAlarmJSONData;
/**
* Return generated event as a string.
*
* ```javascript
* const alarm = event.createAlarm();
* console.log(alarm.toString()); // → BEGIN:VALARM…
* ```
*/
toString(): string;
/**
* Get the trigger time for the alarm. Can either
* be a date and time value ({@link ICalDateTimeValue}) or
* a number, which will represent the seconds between
* alarm and event start. The number is negative, if the
* alarm is triggered after the event started.
*
* @since 0.2.1
*/
trigger(): ICalDateTimeValue | number;
/**
* Use this method to set the alarm time.
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
* const alarm = cal.createAlarm();
*
* alarm.trigger(600); // -> 10 minutes before event starts
* alarm.trigger(new Date()); // -> now
* ```
*
* You can use any supported date object, see
* [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
* for details about supported values and timezone handling.
*
* @since 0.2.1
*/
trigger(trigger: Date | ICalDateTimeValue | number): this;
/**
* Get the trigger time for the alarm. Can either
* be a date and time value ({@link ICalDateTimeValue}) or
* a number, which will represent the seconds between
* alarm and event start. The number is negative, if the
* alarm is triggered before the event started.
*
* @since 0.2.1
*/
triggerAfter(): ICalDateTimeValue | number;
/**
* Use this method to set the alarm time. Unlike `trigger`, this time
* the alarm takes place after the event has started.
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
* const alarm = cal.createAlarm();
*
* alarm.trigger(600); // -> 10 minutes after event starts
* ```
*
* You can use any supported date object, see
* [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
* for details about supported values and timezone handling.
*
* @since 0.2.1
*/
triggerAfter(trigger: ICalDateTimeValue | number): this;
/**
* Get the trigger time for the alarm. Can either
* be a date and time value ({@link ICalDateTimeValue}) or
* a number, which will represent the seconds between
* alarm and event start. The number is negative, if the
* alarm is triggered after the event started.
*
* @since 0.2.1
* @see {@link trigger}
* @see {@link triggerAfter}
*/
triggerBefore(trigger: ICalDateTimeValue | number): this;
/**
* Use this method to set the alarm time.
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
* const alarm = cal.createAlarm();
*
* alarm.trigger(600); // -> 10 minutes before event starts
* alarm.trigger(new Date()); // -> now
* ```
*
* You can use any supported date object, see
* [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
* for details about supported values and timezone handling.
*
* @since 0.2.1
* @see {@link trigger}
* @see {@link triggerAfter}
*/
triggerBefore(): ICalDateTimeValue | number;
/**
* Get the alarm type
* @since 0.2.1
*/
type(type: ICalAlarmType): this;
/**
* Set the alarm type. See {@link ICalAlarmType}
* for available status options.
* @since 0.2.1
*/
type(): ICalAlarmType;
/**
* Set X-* attributes. Woun't filter double attributes,
* which are also added by another method (e.g. type),
* so these attributes may be inserted twice.
*
* ```javascript
* alarm.x([
* {
* key: "X-MY-CUSTOM-ATTR",
* value: "1337!"
* }
* ]);
*
* alarm.x([
* ["X-MY-CUSTOM-ATTR", "1337!"]
* ]);
*
* alarm.x({
* "X-MY-CUSTOM-ATTR": "1337!"
* });
* ```
*
* @since 1.9.0
*/
x(keyOrArray: [string, string][] | Record<string, string> | {
key: string;
value: string;
}[]): this;
/**
* Set a X-* attribute. Woun't filter double attributes,
* which are also added by another method (e.g. type),
* so these attributes may be inserted twice.
*
* ```javascript
* alarm.x("X-MY-CUSTOM-ATTR", "1337!");
* ```
*
* @since 1.9.0
*/
x(keyOrArray: string, value: string): this;
/**
* Get all custom X-* attributes.
* @since 1.9.0
*/
x(): {
key: string;
value: string;
}[];
}
interface ICalCategoryData {
name: string;
}
type ICalCategoryInternalData = ICalCategoryJSONData;
interface ICalCategoryJSONData {
name: string;
}
/**
* Usually you get an {@link ICalCategory} object like this:
*
* ```javascript
* import ical from 'ical-generator';
* const calendar = ical();
* const event = calendar.createEvent();
* const category = event.createCategory();
* ```
*
* You can also use the {@link ICalCategory} object directly:
*
* ```javascript
* import ical, {ICalCategory} from 'ical-generator';
* const category = new ICalCategory();
* event.categories([category]);
* ```
*/
declare class ICalCategory {
private readonly data;
/**
* Constructor of {@link ICalCategory}.
* @param data Category Data
*/
constructor(data: ICalCategoryData);
/**
* Get the category name
* @since 0.3.0
*/
name(): string;
/**
* Set the category name
* @since 0.3.0
*/
name(name: string): this;
/**
* Return a shallow copy of the category's options for JSON stringification.
* Can be used for persistence.
*
* @since 0.2.4
*/
toJSON(): ICalCategoryInternalData;
/**
* Return generated category name as a string.
*
* ```javascript
* console.log(category.toString());
* ```
*/
toString(): string;
}
declare enum ICalEventBusyStatus {
BUSY = "BUSY",
FREE = "FREE",
OOF = "OOF",
TENTATIVE = "TENTATIVE"
}
declare enum ICalEventClass {
CONFIDENTIAL = "CONFIDENTIAL",
PRIVATE = "PRIVATE",
PUBLIC = "PUBLIC"
}
declare enum ICalEventStatus {
CANCELLED = "CANCELLED",
CONFIRMED = "CONFIRMED",
TENTATIVE = "TENTATIVE"
}
declare enum ICalEventTransparency {
OPAQUE = "OPAQUE",
TRANSPARENT = "TRANSPARENT"
}
interface ICalEventData {
alarms?: ICalAlarm[] | ICalAlarmData[];
allDay?: boolean;
attachments?: string[];
attendees?: ICalAttendee[] | ICalAttendeeData[];
busystatus?: ICalEventBusyStatus | null;
categories?: ICalCategory[] | ICalCategoryData[];
class?: ICalEventClass | null;
created?: ICalDateTimeValue | null;
description?: ICalDescription | null | string;
end?: ICalDateTimeValue | null;
floating?: boolean;
id?: null | number | string;
lastModified?: ICalDateTimeValue | null;
location?: ICalLocation | null | string;
organizer?: ICalOrganizer | null | string;
priority?: null | number;
recurrenceId?: ICalDateTimeValue | null;
repeating?: ICalRepeatingOptions | ICalRRuleStub | null | string;
sequence?: number;
stamp?: ICalDateTimeValue;
start: ICalDateTimeValue;
status?: ICalEventStatus | null;
summary?: string;
timezone?: null | string;
transparency?: ICalEventTransparency | null;
url?: null | string;
x?: [string, string][] | Record<string, string> | {
key: string;
value: string;
}[];
}
interface ICalEventJSONData {
alarms: ICalAlarm[];
allDay: boolean;
attachments: string[];
attendees: ICalAttendee[];
busystatus: ICalEventBusyStatus | null;
categories: ICalCategory[];
created: null | string;
description: ICalDescription | null;
end: null | string;
floating: boolean;
id: string;
lastModified: null | string;
location: ICalLocation | null;
organizer: ICalOrganizer | null;
priority?: null | number;
recurrenceId: null | string;
repeating: ICalEventJSONRepeatingData | null | string;
sequence: number;
stamp: string;
start: string;
status: ICalEventStatus | null;
summary: string;
timezone: null | string;
transparency: ICalEventTransparency | null;
url: null | string;
x: {
key: string;
value: string;
}[];
}
interface ICalEventJSONRepeatingData {
byDay?: ICalWeekday[];
byMonth?: number[];
byMonthDay?: number[];
bySetPos?: number[];
count?: number;
exclude?: ICalDateTimeValue[];
freq: ICalEventRepeatingFreq;
interval?: number;
startOfWeek?: ICalWeekday;
until?: ICalDateTimeValue;
}
/**
* Usually you get an {@link ICalEvent} object like this:
* ```javascript
* import ical from 'ical-generator';
* const calendar = ical();
* const event = calendar.createEvent();
* ```
*/
declare class ICalEvent {
private readonly calendar;
private readonly data;
/**
* Constructor of [[`ICalEvent`]. The calendar reference is
* required to query the calendar's timezone when required.
*
* @param data Calendar Event Data
* @param calendar Reference to ICalCalendar object
*/
constructor(data: ICalEventData, calendar: ICalCalendar);
/**
* Get all alarms
* @since 0.2.0
*/
alarms(): ICalAlarm[];
/**
* Add one or multiple alarms
*
* ```javascript
* const event = ical().createEvent();
*
* cal.alarms([
* {type: ICalAlarmType.display, trigger: 600},
* {type: ICalAlarmType.audio, trigger: 300}
* ]);
*
* cal.alarms(); // --> [ICalAlarm, ICalAlarm]
```
*
* @since 0.2.0
*/
alarms(alarms: ICalAlarm[] | ICalAlarmData[]): this;
/**
* Get the event's allDay flag
* @since 0.2.0
*/
allDay(): boolean;
/**
* Set the event's allDay flag.
*
* ```javascript
* event.allDay(true); // → appointment is for the whole day
* ```
*
* ```typescript
* import ical from 'ical-generator';
*
* const cal = ical();
*
* cal.createEvent({
* start: new Date('2020-01-01'),
* summary: 'Very Important Day',
* allDay: true
* });
*
* cal.toString();
* ```
*
* ```text
* BEGIN:VCALENDAR
* VERSION:2.0
* PRODID:-//sebbo.net//ical-generator//EN
* BEGIN:VEVENT
* UID:1964fe8d-32c5-4f2a-bd62-7d9d7de5992b
* SEQUENCE:0
* DTSTAMP:20240212T191956Z
* DTSTART;VALUE=DATE:20200101
* X-MICROSOFT-CDO-ALLDAYEVENT:TRUE
* X-MICROSOFT-MSNCALENDAR-ALLDAYEVENT:TRUE
* SUMMARY:Very Important Day
* END:VEVENT
* END:VCALENDAR
* ```
*
* @since 0.2.0
*/
allDay(allDay: boolean): this;
/**
* Get all attachment urls
* @since 3.2.0-develop.1
*/
attachments(): string[];
/**
* Add one or multiple alarms
*
* ```javascript
* const event = ical().createEvent();
*
* cal.attachments([
* 'https://files.sebbo.net/calendar/attachments/foo',
* 'https://files.sebbo.net/calendar/attachments/bar'
* ]);
*
* cal.attachments(); // --> [string, string]
```
*
* 3.2.0-develop.1
*/
attachments(attachments: string[]): this;
/**
* Get all attendees
* @since 0.2.0
*/
attendees(): ICalAttendee[];
/**
* Add multiple attendees to your event
*
* ```javascript
* const event = ical().createEvent();
*
* cal.attendees([
* {email: 'a@example.com', name: 'Person A'},
* {email: 'b@example.com', name: 'Person B'}
* ]);
*
* cal.attendees(); // --> [ICalAttendee, ICalAttendee]
* ```
*
* @since 0.2.0
*/
attendees(attendees: (ICalAttendee | ICalAttendeeData | string)[]): this;
/**
* Get the event's busy status
* @since 1.0.2
*/
busystatus(): ICalEventBusyStatus | null;
/**
* Set the event's busy status. Will add the
* [`X-MICROSOFT-CDO-BUSYSTATUS`](https://docs.microsoft.com/en-us/openspecs/exchange_server_protocols/ms-oxcical/cd68eae7-ed65-4dd3-8ea7-ad585c76c736)
* attribute to your event.
*
* ```javascript
* import ical, {ICalEventBusyStatus} from 'ical-generator';
* event.busystatus(ICalEventBusyStatus.BUSY);
* ```
*
* @since 1.0.2
*/
busystatus(busystatus: ICalEventBusyStatus | null): this;
/**
* Get all categories
* @since 0.3.0
*/
categories(): ICalCategory[];
/**
* Add categories to the event or return all selected categories.
*
* ```javascript
* const event = ical().createEvent();
*
* cal.categories([
* {name: 'APPOINTMENT'},
* {name: 'MEETING'}
* ]);
*
* cal.categories(); // --> [ICalCategory, ICalCategory]
* ```
*
* @since 0.3.0
*/
categories(categories: (ICalCategory | ICalCategoryData)[]): this;
/**
* Get the event's class
* @since 2.0.0
*/
class(): ICalEventClass | null;
/**
* Set the event's class
*
* ```javascript
* import ical, { ICalEventClass } from 'ical-generator';
* event.class(ICalEventClass.PRIVATE);
* ```
*
* @since 2.0.0
*/
class(class_: ICalEventClass | null): this;
/**
* Creates a new {@link ICalAlarm} and returns it. Use options to prefill
* the alarm's attributes. Calling this method without options will create
* an empty alarm.
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
* const alarm = event.createAlarm({type: ICalAlarmType.display, trigger: 300});
*
* // add another alarm
* event.createAlarm({
* type: ICalAlarmType.audio,
* trigger: 300, // 5min before event
* });
* ```
*
* @since 0.2.1
*/
createAlarm(data: ICalAlarm | ICalAlarmData): ICalAlarm;
/**
* Adds an attachment to the event by adding the file URL to the calendar.
*
* `ical-generator` only supports external attachments. File attachments that
* are directly included in the file are not supported, because otherwise the
* calendar file could easily become unfavourably large.
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
* event.createAttachment('https://files.sebbo.net/calendar/attachments/foo');
* ```
*
* @since 3.2.0-develop.1
*/
createAttachment(url: string): this;
/**
* Creates a new {@link ICalAttendee} and returns it. Use options to prefill
* the attendee's attributes. Calling this method without options will create
* an empty attendee.
*
* ```javascript
* import ical from 'ical-generator';
*
* const cal = ical();
* const event = cal.createEvent({
* start: new Date()
* });
*
* event.createAttendee({email: 'hui@example.com', name: 'Hui'});
*
* // add another attendee
* event.createAttendee('Buh <buh@example.net>');
* ```
*
* ```text
* BEGIN:VCALENDAR
* VERSION:2.0
* PRODID:-//sebbo.net//ical-generator//EN
* BEGIN:VEVENT
* UID:b4944f07-98e4-4581-ac80-2589bb20273d
* SEQUENCE:0
* DTSTAMP:20240212T194232Z
* DTSTART:20240212T194232Z
* SUMMARY:
* ATTENDEE;ROLE=REQ-PARTICIPANT;CN="Hui":MAILTO:hui@example.com
* ATTENDEE;ROLE=REQ-PARTICIPANT;CN="Buh":MAILTO:buh@example.net
* END:VEVENT
* END:VCALENDAR
* ```
*
* As with the organizer, you can also add an explicit `mailto` address.
*
* ```javascript
* event.createAttendee({email: 'hui@example.com', name: 'Hui', mailto: 'another@mailto.com'});
*
* // overwrite an attendee's mailto address
* attendee.mailto('another@mailto.net');
* ```
*
* @since 0.2.0
*/
createAttendee(data: ICalAttendee | ICalAttendeeData | string): ICalAttendee;
/**
* Creates a new {@link ICalCategory} and returns it. Use options to prefill the category's attributes.
* Calling this method without options will create an empty category.
*
* ```javascript
* const cal = ical();
* const event = cal.createEvent();
* const category = event.createCategory({name: 'APPOINTMENT'});
*
* // add another category
* event.createCategory({
* name: 'MEETING'
* });
* ```
*
* @since 0.3.0
*/
createCategory(data: ICalCategory | ICalCategoryData): ICalCategory;
/**
* Get the event's creation date
* @since 0.3.0
*/
created(): ICalDateTimeValue | null;
/**
* Set the event's creation date
* @since 0.3.0
*/
created(created: ICalDateTimeValue | null): this;
/**
* Get the event's description as an {@link ICalDescription} object.
* @since 0.2.0
*/
description(): ICalDescription | null;
/**
* Set the events description by passing a plaintext string or
* an object containing both a plaintext and a html description.
* Only a few calendar apps support html descriptions and like in
* emails, supported HTML tags and styling is limited.
*
* ```javascript
* event.description({
* plain: 'Hello World!',
* html: '<p>Hello World!</p>'
* });
* ```
*
* ```text
* DESCRIPTION:Hello World!
* X-ALT-DESC;FMTTYPE=text/html:<p>Hello World!</p>
* ```
*
* @since 0.2.0
*/
description(description: ICalDescription | null | string): this;
/**
* Get the event end time which is currently
* set. Can be any supported date object.
*
* @since 0.2.0
*/
end(): ICalDateTimeValue | null;
/**
* Set the appointment date of end. You can use any supported date object, see
* [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
* for details about supported values and timezone handling.
*
* @since 0.2.0
*/
end(end: ICalDateTimeValue | null): this;
/**
* Get the event's floating flag.
* @since 0.2.0
*/
floating(): boolean;
floating(floating: boolean): this;
/**
* Get the event's ID
* @since 0.2.0
*/
id(): string;
/**
* Use this method to set the event's ID.
* If not set, a UUID will be generated randomly.
*
* @param id Event ID you want to set
*/
id(id: number | string): this;
/**
* Get the event's last modification date
* @since 0.3.0
*/
lastModified(): ICalDateTimeValue | null;
/**
* Set the event's last modification date
* @since 0.3.0
*/
lastModified(lastModified: ICalDateTimeValue | null): this;
/**
* Get the event's location
* @since 0.2.0
*/
location(): ICalLocation | null;
/**
* Set the event's location by passing a string (minimum) or
* an {@link ICalLocationWithTitle} object which will also fill the iCal
* `GEO` attribute and Apple's `X-APPLE-STRUCTURED-LOCATION`.
*
* ```javascript
* event.location({
* title: 'Apple Store Kurfürstendamm',
* address: 'Kurfürstendamm 26, 10719 Berlin, Deutschland',
* radius: 141.1751386318387,
* geo: {
* lat: 52.503630,
* lon: 13.328650
* }
* });
* ```
*
* ```text
* LOCATION:Apple Store Kurfürstendamm\nKurfürstendamm 26\, 10719 Berlin\,
* Deutschland
* X-APPLE-STRUCTURED-LOCATION;VALUE=URI;X-ADDRESS=Kurfürstendamm 26\, 10719
* Berlin\, Deutschland;X-APPLE-RADIUS=141.1751386318387;X-TITLE=Apple Store
* Kurfürstendamm:geo:52.50363,13.32865
* GEO:52.50363;13.32865
* ```
*
* Since v6.1.0 you can also pass a {@link ICalLocationWithoutTitle} object to pass
* the geolocation only. This will only fill the iCal `GEO` attribute.
*
* ```javascript
* event.location({
* geo: {
* lat: 52.503630,
* lon: 13.328650
* }
* });
* ```
*
* ```text
* GEO:52.50363;13.32865
* ```
*
* @since 0.2.0
*/
location(location: ICalLocation | null | string): this;
/**
* Get the event's organizer
* @since 0.2.0
*/
organizer(): ICalOrganizer | null;
/**
* Set the event's organizer
*
* ```javascript
* event.organizer({
* name: 'Organizer\'s Name',
* email: 'organizer@example.com'
* });
*
* // OR
*
* event.organizer('Organizer\'s Name <organizer@example.com>');
* ```
*
* You can also add an explicit `mailto` email address or or the sentBy address.
*
* ```javascript
* event.organizer({
* name: 'Organizer\'s Name',
* email: 'organizer@example.com',
* mailto: 'explicit@mailto.com',
* sentBy: 'substitute@example.com'
* })
* ```
*
* @since 0.2.0
*/
organizer(organizer: ICalOrganizer | null | string): this;
/**
* Get the event's priority. A value of 1 represents
* the highest priority, 9 the lowest. 0 specifies an undefined
* priority.
*
* @since v2.0.0-develop.7
*/
priority(): null | number;
/**
* Set the event's priority. A value of 1 represents
* the highest priority, 9 the lowest. 0 specifies an undefined
* priority.
*
* @since v2.0.0-develop.7
*/
priority(priority: null | number): this;
/**
* Get the event's recurrence id
* @since 0.2.0
*/
recurrenceId(): ICalDateTimeValue | null;
/**
* Set the event's recurrence id. You can use any supported date object, see
* [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
* for details about supported values and timezone handling.
*
* @since 0.2.0
*/
recurrenceId(recurrenceId: ICalDateTimeValue | null): this;
/**
* Get the event's repeating options
* @since 0.2.0
*/
repeating(): ICalEventJSONRepeatingData | ICalRRuleStub | null | string;
/**
* Set the event's repeating options by passing an {@link ICalRepeatingOptions} object.
*
* ```javascript
* event.repeating({
* freq: 'MONTHLY', // required
* count: 5,
* interval: 2,
* until: new Date('Jan 01 2014 00:00:00 UTC'),
* byDay: ['su', 'mo'], // repeat only sunday and monday
* byMonth: [1, 2], // repeat only in january and february,
* byMonthDay: [1, 15], // repeat only on the 1st and 15th
* bySetPos: 3, // repeat every 3rd sunday (will take the first element of the byDay array)
* exclude: [new Date('Dec 25 2013 00:00:00 UTC')], // exclude these dates
* excludeTimezone: 'Europe/Berlin', // timezone of exclude
* wkst: 'SU' // Start the week on Sunday, default is Monday
* });
* ```
*
* **Example:**
*
*```typescript
* import ical, { ICalEventRepeatingFreq } from 'ical-generator';
*
* const cal = ical();
*
* const event = cal.createEvent({
* start: new Date('2020-01-01T20:00:00Z'),
* summary: 'Repeating Event'
* });
* event.repeating({
* freq: ICalEventRepeatingFreq.WEEKLY,
* count: 4
* });
*
* cal.toString();
* ```
*
* ```text
* BEGIN:VCALENDAR
* VERSION:2.0
* PRODID:-//sebbo.net//ical-generator//EN
* BEGIN:VEVENT
* UID:b80e6a68-c2cd-48f5-b94d-cecc7ce83871
* SEQUENCE:0
* DTSTAMP:20240212T193646Z
* DTSTART:20200101T200000Z
* RRULE:FREQ=WEEKLY;COUNT=4
* SUMMARY:Repeating Event
* END:VEVENT
* END:VCALENDAR
* ```
*
* @since 0.2.0
*/
repeating(repeating: ICalRepeatingOptions | null): this;
/**
* Set the event's repeating options by passing an [RRule object](https://github.com/jakubroztocil/rrule).
* @since 2.0.0-develop.5
*
* ```typescript
* import ical from 'ical-generator';
* import { datetime, RRule } from 'rrule';
*
* const cal = ical();
*
* const event = cal.createEvent({
* start: new Date('2020-01-01T20:00:00Z'),
* summary: 'Repeating Event'
* });
*
* const rule = new RRule({
* freq: RRule.WEEKLY,
* interval: 5,
* byweekday: [RRule.MO, RRule.FR],
* dtstart: datetime(2012, 2, 1, 10, 30),
* until: datetime(2012, 12, 31)
* })
* event.repeating(rule);
*
* cal.toString();
* ```
*
* ```text
* BEGIN:VCALENDAR
* VERSION:2.0
* PRODID:-//sebbo.net//ical-generator//EN
* BEGIN:VEVENT
* UID:36585e40-8fa8-460d-af0c-88b6f434030b
* SEQUENCE:0
* DTSTAMP:20240212T193827Z
* DTSTART:20200101T200000Z
* RRULE:FREQ=WEEKLY;INTERVAL=5;BYDAY=MO,FR;UNTIL=20121231T000000Z
* SUMMARY:Repeating Event
* END:VEVENT
* END:VCALENDAR
* ```
*/
repeating(repeating: ICalRRuleStub | null): this;
/**
* Set the events repeating options by passing a string which is inserted in the ical file.
* @since 2.0.0-develop.5
*/
repeating(repeating: null | string): this;
/**
* @internal
*/
repeating(repeating: ICalRepeatingOptions | ICalRRuleStub | null | string): this;
/**
* Get the event's SEQUENCE number. Use this method to get the event's
* revision sequence number of the calendar component within a sequence of revisions.
*
* @since 0.2.6
*/
sequence(): number;
/**
* Set the event's SEQUENCE number. For a new event, this should be zero.
* Each time the organizer makes a significant revision, the sequence
* number should be incremented.
*
* @param sequence Sequence number or null to unset it
*/
sequence(sequence: number): this;
/**
* Get the event's timestamp
* @since 0.2.0
* @see {@link timestamp}
*/
stamp(): ICalDateTimeValue;
/**
* Set the appointment date of creation. Defaults to the current time and date (`new Date()`). You can use
* any supported date object, see [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
* for details about supported values and timezone handling.
*
* @since 0.2.0
* @see {@link timestamp}
*/
stamp(stamp: ICalDateTimeValue): this;
/**
* Get the event start time which is currently
* set. Can be any supported date object.
*
* @since 0.2.0
*/
start(): ICalDateTimeValue;
/**
* Set the appointment date of beginning, which is required for all events.
* You can use any supported date object, see
* [Readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
* for details about supported values and timezone handling.
*
* ```typescript
* import ical from 'ical-generator';
*
* const cal = ical();
*
* const event = cal.createEvent({
* start: new Date('2020-01-01')
* });
*
* // overwrites old start date
* event.start(new Date('2024-02-01'));
*
* cal.toString();
* ```
*
* ```text
* BEGIN:VCALENDAR
* VERSION:2.0
* PRODID:-//sebbo.net//ical-generator//EN
* BEGIN:VEVENT
* UID:7e2aee64-b07a-4256-9b3e-e9eaa452bac8
* SEQUENCE:0
* DTSTAMP:20240212T190915Z
* DTSTART:20240201T000000Z
* SUMMARY:
* END:VEVENT
* END:VCALENDAR
* ```
*
* @since 0.2.0
*/
start(start: ICalDateTimeValue): this;
/**
* Get the event's status
* @since 0.2.0
*/
status(): ICalEventStatus | null;
/**
* Set the event's status
*
* ```javascript
* import ical, {ICalEventStatus} from 'ical-generator';
* event.status(ICalEventStatus.CONFIRMED);
* ```
*
* @since 0.2.0
*/
status(status: ICalEventStatus | null): this;
/**
* Get the event's summary
* @since 0.2.0
*/
summary(): string;
/**
* Set the event's summary.
* Defaults to an empty string if nothing is set.
*
* @since 0.2.0
*/
summary(summary: string): this;
/**
* Get the event's timestamp
* @since 0.2.0
* @see {@link stamp}
*/
timestamp(): ICalDateTimeValue;
/**
* Set the appointment date of creation. Defaults to the current time and date (`new Date()`). You can use
* any supported date object, see [readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones)
* for details about supported values and timezone handling.
*
* @since 0.2.0
* @see {@link stamp}
*/
timestamp(stamp: ICalDateTimeValue): this;
/**
* Get the event's timezone.
* @since 0.2.6
*/
timezone(): null | string;
/**
* Sets the time zone to be used for this event. If a time zone has been
* defined in both the event and the calendar, the time zone of the event
* is used.
*
* Please note that if the time zone is set, ical-generator assumes
* that all times are already in the correct time zone. Alternatively,
* a `moment-timezone` or a Luxon object can be passed with `setZone`,
* ical-generator will then set the time zone itself.
*
* This and the 'floating' flag (see below) are mutually exclusive, and setting a timezone will unset the
* 'floating' flag. If neither 'timezone' nor 'floating' are set, the date will be output with in UTC format
* (see [date-time form #2 in section 3.3.5 of RFC 554](https://tools.ietf.org/html/rfc5545#section-3.3.5)).
*
* See [Readme](https://github.com/sebbo2002/ical-generator#-date-time--timezones) for details about
* supported values and timezone handling.
*
* ```javascript
* event.timezone('America/New_York');
* ```
*
* @see https://github.com/sebbo2002/ical-generator#-date-time--timezones
* @since 0.2.6
*/
timezone(timezone: null | string): this;
/**
* Return a shallow copy of the events's options for JSON stringification.
* Third party objects like moment.js values or RRule objects are stringified
* as well. Can be used for persistence.
*
* ```javascript
* const event = ical().createEvent();
* const json = JSON.stringify(event);
*
* // later: restore event data
* const calendar = ical().createEvent(JSON.parse(json));
* ```
*
* @since 0.2.4
*/
toJSON(): ICalEventJSONData;
/**
* Return generated event as a string.
*
* ```javascript
* const event = ical().createEvent();
* console.log(event.toSt