server/protocols/jmap-draft/doc/specs/spec/calendarevent.mdwn

## Calendar Events
<aside class="warning">
Not implemented
</aside>

A CalendarEvent contains information about an event, or recurring series of events, that takes place at a particular time. The object is designed to be easily convertible to/from iCalendar format ([RFC 5545](https://tools.ietf.org/html/rfc5545)) for compatibility with existing calendaring systems.

A **CalendarEvent** object has the following properties:

- **id**: `String`
  The id of the event. This property is immutable.
- **calendarId**: `String`
  The id of the calendar this event belongs to.
- **summary**: `String`
  A short summary of the event. This maps to the SUMMARY property in iCalendar.
- **description**: `String`
  A longer form description of the event. This is plain text, not HTML, but
  a client *should* attempt to mark up URLs. This maps to the DESCRIPTION property in iCalendar.
- **location**: `String`
  Where the event is to take place. This maps to the LOCATION property in iCalendar.
- **showAsFree**: `Boolean`
  If true, the even should be ignored when calculating free/busy data for the
  user. This maps to the TRANSP property in iCalendar (`false <=> OPAQUE`, `true <=> TRANSPARENT`).
- **isAllDay**: `Boolean`
  Is the event an all day event, such as a birthday or public holiday? This corresponds to the type (DATE or DATE-TIME) of the DTSTART property in iCalendar.
- **start**: `LocalDate`
  The date/time the event would start in the event's time zone. This corresponds to the DTSTART property in iCalendar.
- **end**: `LocalDate`
  The date/time the event would end in the event's time zone. This corresponds to the DTSTART/DURATION or DTEND property in iCalendar.
- **startTimeZone**: `String|null`
  The [Olsen Time Zone Database](http://www.iana.org/time-zones) name for the timezone the start of the event is actually in, or `null` for floating time. This corresponds to the TZID part of the DTSTART property; if the underlying iCalendar file does not use an Olsen name, the server SHOULD try to guess the correct time zone based on the VTIMEZONE information, or fallback to floating time.
- **endTimeZone**: `String|null`
  The [Olsen Time Zone Database](http://www.iana.org/time-zones) name for the timezone the end of the event is actually in, or `null` for floating time. This corresponds to the TZID part of the DTEND property (or DTSTART if not present); if the underlying iCalendar file does not use an Olsen name, the server SHOULD try to guess the correct time zone based on the VTIMEZONE information, or fallback to floating time.
- **recurrence**: `Recurrence|null`
  The recurrence rule for the event, or `null` if it does not recur. This corresponds to the RRULE property in iCalendar.
- **inclusions**: `LocalDate[]|null`
  List of extra **local** start times to recur on. The list MUST be sorted in date order (oldest first). This corresponds to the RDATE property in iCalendar.
- **exceptions**: `LocalDate[null|CalendarEvent]|null`
  An object mapping an occurrence start time (in **local time**, not UTC) to either:
  - `null`: The occurrence has been deleted. This corresponds to the EXDATE property in iCalendar.
  - `CalendarEvent`: A partial CalendarEvent object. Any properties in the object override the property of the same name for this occurrence. This corresponds to extra VEVENTs with RECURRENCE-IDs in iCalendar. Allowed properties are:
    - summary
    - description
    - location
    - showAsFree
    - start
    - end
    - startTimeZone
    - endTimeZone
    - alerts
    - organizer
    - attendees
- **alerts**: `Alert[]|null`
  A list of alerts to display or send the user for this event. This maps to the VALARM property in iCalendar.
- **organizer**: `Participant|null`
  The organizer of the event. This maps to the ORGANIZER property in iCalendar
- **attendees**: `Participant[]|null`
  A list of attendees at the event. This maps to the ATTENDEE property in iCalendar.
- **attachments**: `File[]|null`
  A list of file attachments to the event. This maps to the ATTACH property in iCalendar.

Conditions:

- The *end* date MUST be equal to or after the *start* date when both are converted to UTC time (the event MUST NOT have a negative duration).
- if *isAllDay* is `true`, the *start*/*end* properties MUST have a time component of `T00:00:00` and *startTimeZone*/*endTimeZone* properties MUST be `null`.
- if *recurrence* is `null`, *inclusions* and *exceptions* MUST also be `null`.
- either both organizer and attendees are `null`, or neither are.
- any `null`able array/object property MUST be `null` rather than an empty array or object.

A **Recurrence** object is a JSON object mapping of a RECUR value type in iCalendar. To make it easier to check if two recurrence rules are identical, optional properties MUST NOT be included if the value is the default. A Recurrence object has the following properties:

- **frequency**: `String`
  This MUST be one of the following values:
  - `"yearly"`
  - `"monthly"`
  - `"weekly"`
  - `"daily"`
  - `"hourly"`
  - `"minutely"`
  - `"secondly"`
  To convert from iCal, simply lower-case the FREQ part.
- **interval**: `Number` (optional)
  The INTERVAL part from iCal. Defaults to `1` if not present. This MUST NOT be included if the interval == 1, to ensure a canonical representation. If included, it MUST be an integer `x > 1`.
- **firstDayOfWeek**: `Number` (optional)
  The WKST part from iCal. Defaults to `1` (Monday) if not present. This MUST NOT be included if == 1 (Monday), to ensure a canonical representation. It MUST be an integer in the range (0,6), where SU => 0, TU => 2, WE => 3 etc.
- **byDay**: `Number[]` (optional)
  The BYDAY part from iCal. The array MUST have at least one entry if included and MUST be sorted in ascending order. To convert from the iCal string format (e.g. SU,+1MO):
  1. Convert SU/MO/TU… <-> 0/1/2…
  2. If it has a number attached (+1, -2 etc.), add on 7 * the attached number.
  e.g. `+1MO => 1 + (7 * +1) => 8`, `-2TH => 4 + (7 * -2) => -10`
- **byDate**: `Number[]` (optional)
  The BYMONTHDAY part from iCal. The array MUST have at least one entry if included and MUST be sorted in ascending order.
- **byMonth**: `Number[]` (optional)
  The BYMONTH part from iCal, but with Jan == 0, Feb == 1 etc. (Jan == 1 in iCal). The array MUST have at least one entry if included and MUST be sorted in ascending order.
- **byYearDay**: `Number[]` (optional)
  The BYYEARDAY part from iCal. The array MUST have at least one entry if included and MUST be sorted in ascending order.
- **byWeekNo**: `Number[]` (optional)
  The BYWEEKNO part from iCal. The array MUST have at least one entry if included and MUST be sorted in ascending order.
- **byHour**: `Number[]` (optional)
  The BYHOUR part from iCal. The array MUST have at least one entry if included and MUST be sorted in ascending order.
- **byMinute**: `Number[]` (optional)
  The BYMINUTE part from iCal. The array MUST have at least one entry if included and MUST be sorted in ascending order.
- **bySecond**: `Number[]` (optional)
  The BYSECOND part from iCal. The array MUST have at least one entry if included and MUST be sorted in ascending order.
- **bySetPosition**: `Number[]` (optional)
  The BYSETPOS part from iCal. The array MUST have at least one entry if included and MUST be sorted in ascending order.
- **count**: `Number` (optional)
  The COUNT part from iCal. This MUST NOT be included if an *until* property is specified.
- **until**: `LocalDate` (optional)
  The UNTIL part from iCal. This MUST NOT be included if a *count* property is specified.

An **Alert** Object has the following properties:

- **minutesBefore**: `Number`
  The number of minutes before the start time of the event to show the alert. The number MAY be negative for an alert after the event start. Note, if the event is in floating time (including all-day events), the server SHOULD use the user's default time zone when determining the start time.
- **type**: `String`
  The value MUST be one of the following:
  - `"email"` – the server will send an email to the user at the specified time. The format of this email is service-specific.
  - `"alert"` – a message should be shown to the user on any client connected to this account at the specified time.

A **Participant** Object has the following properties:

- **name**: `String`
  The name of the participant.
- **email**: `String`
  The email address of the participant.
- **isYou**: `Boolean`
  This is `true` if the participant is the logged in user (determining this is not defined and is server dependent).
- **rsvp**: `String`
  The value MUST be one of:
  - `""`: no RSVP made.
  - `"yes"`: the participant is attending
  - `"maybe"`: the participant may be attending
  - `"no"`: the participant is not attending

A **File** Object has the following properties:

- **blobId**: `String`
  The id of the binary data.
- **type**: `String|null`
  The content-type of the attachment, if known.
- **name**: `String|null`
  The full file name, if known. e.g. "myworddocument.doc"
- **size**: `Number|null`
  The size, in bytes, of the attachment when fully decoded (i.e. the number of bytes in the file the user would download), if known.

### getCalendarEvents

CalendarEvents can only be fetched explicitly by id. To fetch events, make a call to `getCalendarEvents`. It takes the following arguments:

- **accountId**: `String|null`
  The id of the account to use for this call. If not given, defaults to the primary account.
- **ids**: `String[]`
  An array of ids for the events to fetch.
- **properties**: `String[]|null`
  A list of properties to fetch for each event. If `null`, all properties will be fetched.

The `id` property is always returned, regardless of whether it is in the list of requested properties. The possible values for `properties` can be found above in the description of the CalendarEvent object.

The response to *getCalendarEvents* is called *calendarEvents*. It has the following arguments:

- **accountId**: `String`
  The id of the account used for the call.
- **state**: `String`
  A string encoding the current state on the server. This string will change
  if any events change (that is, an event is created, updated or deleted). It can be passed to *getCalendarEventUpdates* to efficiently get the list of changes from the previous state.
- **list**: `CalendarEvent[]`
  An array of CalendarEvent objects for the requested event ids. This may not be in the same order as the ids were in the request.
- **notFound**: `String[]|null`
  An array of calendar event ids requested which could not be found, or `null` if all ids were found.

The following errors may be returned instead of the *events* response:

`accountNotFound`: Returned if an *accountId* was explicitly included with the request, but it does not correspond to a valid account.

`accountNoCalendars`: Returned if the *accountId* given corresponds to a valid account, but does not contain any calendar data.

`invalidArguments`: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A *description* property MAY be present on the response object to help debug with an explanation of what the problem was.

### getCalendarEventUpdates

The *getCalendarEventUpdates* call allows a client to efficiently update the state of its cached calendar events to match the new state on the server. It takes the following arguments:

- **accountId**: `String|null`
  The id of the account to use for this call. If `null`, the primary account will be used.
- **sinceState**: `String`
  The current state of the client. This is the string that was returned as the *state* argument in the *calendarEvents* response. The server will return the changes made since this state.
- **maxChanges**: `Number|null`
  The maximum number of CalendarEvent ids to return in the response. The server MAY choose to clamp this value to a particular maximum or set a maximum if none is given by the client. If supplied by the client, the value MUST be a positive integer greater than 0. If a value outside of this range is given, the server MUST reject the call with an `invalidArguments` error.
- **fetchRecords**: `Boolean|null`
  If `true`, after outputting a *calendarEventUpdates* response, an implicit call will be made to *getCalendarEvents* with the *changed* property of the response as the *ids* argument, and the *fetchRecordProperties* argument as the *properties* argument. If `false` or `null`, no implicit call will be made.
- **fetchRecordProperties**: `String[]|null`
  Passed through as the *properties* argument to any implicit *getCalendarEvents* call.

The response to *getCalendarEventUpdates* is called *calendarEventUpdates*. It has the following arguments:

- **accountId**: `String`
  The id of the account used for the call.
- **oldState**: `String`
  This is the *sinceState* argument echoed back; the state from which the server is returning changes.
- **newState**: `String`
  This is the state the client will be in after applying the set of changes to the old state.
- **hasMoreUpdates**: `Boolean`
  If `true`, the client may call *getCalendarEventUpdates* again with the *newState* returned to get further updates. If `false`, *newState* is the current server state.
- **changed**: `String[]`
  An array of CalendarEvent ids where a property of the event has changed between the old state and the new state, or the event has been created, and the event has not been destroyed.
- **removed**: `String[]`
  An array of CalendarEvent ids for events which have been destroyed since the old state.

If a *maxChanges* is supplied, or set automatically by the server, the server must try to limit the number of ids across *changed* and *removed* to the number given. If there are more changes than this between the client's state and the current server state, the update returned MUST take the client to an intermediate state, from which the client can continue to call *getCalendarEventUpdates* until it is fully up to date. The server MAY return more ids than the *maxChanges* total if this is required for it to be able to produce an update to an intermediate state, but it SHOULD try to keep it close to the maximum requested.

If an event has been modified AND deleted since the oldState, the server should just return the id in the *removed* array, but MAY return it in the *changed* array as well. If an event has been created AND deleted since the oldState, the server SHOULD remove the event id from the response entirely, but MAY include it in the *removed* array, and optionally the *changed* array as well.

The following errors may be returned instead of the `calendarEventUpdates` response:

`accountNotFound`: Returned if an *accountId* was explicitly included with the request, but it does not correspond to a valid account.

`accountNoCalendars`: Returned if the *accountId* given corresponds to a valid account, but does not contain any calendar data.

`invalidArguments`: Returned if the request does not include one of the required arguments, or one of the arguments is of the wrong type, or otherwise invalid. A `description` property MAY be present on the response object to help debug with an explanation of what the problem was.

`cannotCalculateChanges`: Returned if the server cannot calculate the changes from the state string given by the client. Usually due to the client's state being too old, or the server being unable to produce an update to an intermediate state when there are too many updates. The client MUST invalidate its CalendarEvent cache. The error object MUST also include a `newState: String` property with the current state for the type.

### setCalendarEvents

Modifying the state of CalendarEvent objects on the server is done via the *setCalendarEvents* method. This encompasses creating, updating and destroying CalendarEvent records.

The *setCalendarEvents* method takes the following arguments:

- **accountId**: `String|null`
  The id of the account to use for this call. If `null`, the primary account will be used.
- **ifInState**: `String|null`
  This is a state string as returned by the *getCalendarEvents* method. If supplied, the string must match the current state, otherwise the method will be aborted and a `stateMismatch` error returned. If `null`, the change will be applied to the current state.
- **create**: `String[CalendarEvent]|null`
  A map of *creation id* (an arbitrary string set by the client) to CalendarEvent objects (containing all properties except the id).
- **update**: `String[CalendarEvent]|null`
  A map of id to a CalendarEvent object. The object may omit any property; only properties that have changed need be included.
- **destroy**: `String[]|null`
  A list of ids for CalendarEvent objects to permanently delete.

Each create, update or destroy is considered an atomic unit. It is permissible for the server to commit some of the changes but not others, however it is not permissible to only commit part of an update to a single event (e.g. update the *start* property but not the *startTimeZone* property if both are supplied in the update object).

If a create, update or destroy is rejected, the appropriate error should be added to the notCreated/notUpdated/notDestroyed property of the response and the server MUST continue to the next create/update/destroy. It does not terminate the method.

If an id given cannot be found, the update or destroy MUST be rejected with a `notFound` set error.

CalendarEvents reference a Calendar object. When events are created or modified, they may reference a calendar being created *in the same API request* by using the creation id prefixed with a `#`. The order of the method calls in the request by the client MUST be such that the calendar being referenced is created in an earlier call. The server thus never has to look ahead. Instead, while processing a request (a series of method calls), the server MUST keep a simple map for the duration of the request of creation id to Calendar id for each newly created calendar, so it can substitute in the correct value if necessary in later method calls.

To add new attachments, the file must first be uploaded using the standard upload mechanism (see the File Uploads section of this spec). This will give the client a valid blobId/size/type to use.

When an event is created, updated or destroyed, the server MUST also ensure the following:

- Any alerts are scheduled/cancelled correctly..
- If `organizer.isYou == true`:
  - If an event is created with attendees, send a REQUEST iMIP email with the
    event as an ICS attachment to all attendees with `isYou == false`.
  - When an event is updated, email all attendees with `isYou == false` the
    change with an appropriate iMIP email.
  - When an event is destroyed, if it is in the future, then email all
    attendees with `isYou == false` to inform them that the event has been cancelled. If it is in the past, the server SHOULD NOT send a message.
- If `organizer.isYou != true` and one of the attendees of the event has `isYou == true`, then changing the RSVP status of this attendee MUST send the appropriate email to the organizer to inform them of the change in status, as per the iMIP standard.

Note, for compatibility with CalDAV clients, when updating an attendee, the server SHOULD maintain any ROLE, CUTYPE, MEMBER, DELEGATED-TO, DELEGATED-FROM, SENT-BY etc. parameters currently in the iCalendar object for that attendee, even though this API does not currently care about it.

The response to *setCalendarEvents* is called *calendarEventsSet*. It has the following arguments:

- **accountId**: `String`
  The id of the account used for the call.
- **oldState**: `String|null`
  The state string that would have been returned by *getCalendarEvents* before making the requested changes, or `null` if the server doesn't know what the previous state string was.
- **newState**: `String`
  The state string that will now be returned by *getCalendarEvents*.
- **created**: `String[CalendarEvent]`
  A map of the creation id to an object containing the **id** property for all successfully created events
- **updated**: `String[]`
  A list of ids for events that were successfully updated.
- **destroyed**: `String[]`
  A list of ids for events that were successfully destroyed.
- **notCreated**: `String[SetError]`
  A map of creation id to a SetError object for each event that failed to be created. The possible errors are defined in the description of the method for specific data types.
- **notUpdated**: `String[SetError]`
  A map of CalendarEvent id to a SetError object for each event that failed to be updated. The possible errors are defined in the description of the method for specific data types.
- **notDestroyed**: `String[SetError]`
  A map of CalendarEvent id to a SetError object for each event that failed to be destroyed. The possible errors are defined in the description of the method for specific data types.

A **SetError** object has the following properties:

- **type**: `String`
  The type of error.
- **description**: `String|null`
  A description of the error to display to the user.

If any of the properties in a create or update are invalid (immutable and different to the current server value, wrong type, invalid value for the property – like a *calendarId* for a non-existent calendar), the server MUST reject the create/update with a SetError of type `invalidProperties`. The SetError object SHOULD contain a property called *properties* of type `String[]` that lists **all** the properties that were invalid. The object MAY also contain a *description* property of type `String` with a user-friendly description of the problems.

The following errors may be returned instead of the *calendarEventsSet* response:

`accountNotFound`: Returned if an *accountId* was explicitly included with the request, but it does not correspond to a valid account.

`accountNoCalendars`: Returned if the *accountId* given corresponds to a valid account, but does not contain any calendar data.

`accountReadOnly`: Returned if the account has `isReadOnly == true`.

`invalidArguments`: Returned if one of the arguments is of the wrong type, or otherwise invalid. A *description* property MAY be present on the response object to help debug with an explanation of what the problem was.

`stateMismatch`: Returned if an *ifInState* argument was supplied and it does not match the current state.