ical-generator 10.2.0-develop.1 → 10.2.0-develop.3

package/package.json

@@ -133,5 +133,5 @@
         "test": "mocha"
     },
     "type": "module",
-    "version": "10.2.0-develop.1"
+    "version": "10.2.0-develop.3"
 }

package/src/event.ts

@@ -15,12 +15,14 @@ import {
     generateCustomAttributes,
     isRRule,
     toDate,
+    toDurationString,
     toJSON,
 } from './tools.ts';
 import {
     type ICalDateTimeValue,
     type ICalDescription,
     ICalEventRepeatingFreq,
+    type ICalEventTravelTime,
     type ICalLocation,
     type ICalOrganizer,
     type ICalRepeatingOptions,
@@ -78,6 +80,7 @@ export interface ICalEventData {
     summary?: string;
     timezone?: null | string;
     transparency?: ICalEventTransparency | null;
+    travelTime?: ICalEventTravelTime | null;
     url?: null | string;
     x?:
         | [string, string][]
@@ -110,6 +113,7 @@ export interface ICalEventJSONData {
     summary: string;
     timezone: null | string;
     transparency: ICalEventTransparency | null;
+    travelTime: ICalEventTravelTime | null;
     url: null | string;
     x: { key: string; value: string }[];
 }
@@ -153,6 +157,7 @@ interface ICalEventInternalData {
     summary: string;
     timezone: null | string;
     transparency: ICalEventTransparency | null;
+    travelTime: ICalEventTravelTime | null;
     url: null | string;
     x: [string, string][];
 }
@@ -203,6 +208,7 @@ export default class ICalEvent {
             summary: '',
             timezone: null,
             transparency: null,
+            travelTime: null,
             url: null,
             x: [],
         };
@@ -237,6 +243,7 @@ export default class ICalEvent {
         if (data.attachments !== undefined) this.attachments(data.attachments);
         if (data.transparency !== undefined)
             this.transparency(data.transparency);
+        if (data.travelTime !== undefined) this.travelTime(data.travelTime);
         if (data.created !== undefined) this.created(data.created);
         if (data.lastModified !== undefined)
             this.lastModified(data.lastModified);
@@ -1781,6 +1788,99 @@ export default class ICalEvent {
                 '\r\n';
         }
 
+        // Travel time
+        if (this.data.travelTime) {
+            g +=
+                'X-APPLE-TRAVEL-DURATION;VALUE=DURATION:' +
+                toDurationString(this.data.travelTime.seconds) +
+                '\r\n';
+
+            if (this.data.location) {
+                if (this.data.travelTime.suggestionBehavior) {
+                    g +=
+                        'X-APPLE-TRAVEL-ADVISORY-BEHAVIOR:' +
+                        this.data.travelTime.suggestionBehavior +
+                        '\r\n';
+                }
+                if (this.data.travelTime.startFrom) {
+                    g += 'X-APPLE-TRAVEL-START;';
+
+                    const travelStartParameters: string[] = [];
+
+                    travelStartParameters.push(
+                        'ROUTING=' +
+                            this.data.travelTime.startFrom.transportation,
+                    );
+                    travelStartParameters.push('VALUE=URI');
+
+                    if (
+                        'address' in this.data.travelTime.startFrom.location &&
+                        this.data.travelTime.startFrom.location.address
+                    ) {
+                        travelStartParameters.push(
+                            'X-ADDRESS=' +
+                                escape(
+                                    this.data.travelTime.startFrom.location
+                                        .address,
+                                    false,
+                                ),
+                        );
+                    }
+
+                    if (
+                        'radius' in this.data.travelTime.startFrom.location &&
+                        this.data.travelTime.startFrom.location.radius
+                    ) {
+                        travelStartParameters.push(
+                            'X-APPLE-RADIUS=' +
+                                escape(
+                                    this.data.travelTime.startFrom.location
+                                        .radius,
+                                    false,
+                                ),
+                        );
+                    }
+
+                    if (
+                        'title' in this.data.travelTime.startFrom.location &&
+                        this.data.travelTime.startFrom.location.title
+                    ) {
+                        travelStartParameters.push(
+                            'X-TITLE=' +
+                                escape(
+                                    this.data.travelTime.startFrom.location
+                                        .title,
+                                    false,
+                                ),
+                        );
+                    }
+
+                    g += travelStartParameters.join(';');
+
+                    if (
+                        'geo' in this.data.travelTime.startFrom.location &&
+                        this.data.travelTime.startFrom.location.geo
+                    ) {
+                        g +=
+                            ':geo:' +
+                            escape(
+                                this.data.travelTime.startFrom.location.geo
+                                    ?.lat,
+                                false,
+                            ) +
+                            ',' +
+                            escape(
+                                this.data.travelTime.startFrom.location.geo
+                                    ?.lon,
+                                false,
+                            );
+                    }
+
+                    g += '\r\n';
+                }
+            }
+        }
+
         // DESCRIPTION
         if (this.data.description) {
             g +=
@@ -1942,6 +2042,81 @@ export default class ICalEvent {
         return this;
     }
 
+    /**
+     * Get the event's travel time
+     * @returns {null|ICalEventTravelTime}
+     */
+    travelTime(): ICalEventTravelTime | null;
+    /**
+     * Use this method to set the event's travel time. \
+     * (Only supported on Apple calendar clients)
+     *
+     * ```typescript
+     * // Set fixed travel time in seconds, doesn't recalculate if traffic conditions change
+     * event.travelTime(60 * 30) // 30 minutes travel time
+     * ```
+     *
+     * @param {null|number} travelTime Travel time in seconds
+     */
+    travelTime(travelTime: null | number): this;
+    /**
+     * Use this method to set the event's travel time. \
+     * (Only supported on Apple calendar clients)
+     *
+     * NOTE: suggestionBehavior and travelStart will only be set if the event has a location
+     *
+     * ```typescript
+     * // Set travel time in seconds, if startFrom is present it adapts if traffic conditions change
+     * event.travelTime({
+     *   seconds: 60 * 30, // 30 minutes travel time
+     *   suggestionBehavior: ICalEventTravelTimeSuggestion.AUTOMATIC, // Let Apple Calendar client decide how to handle suggestions
+     *   startFrom: {
+     *     location: {
+     *       geo: {
+     *         lat: 50.000000,
+     *         lon: 10.000000
+     *       },
+     *       title: "Private address"
+     *     },
+     *     transportation: ICalEventTravelTimeTransportation.BICYCLE // Use bicycle routes for travel time recalculation
+     *   }
+     * })
+     * ```
+     *
+     * @param {null|ICalEventTravelTime} travelTime Travel time object
+     */
+    travelTime(travelTime: ICalEventTravelTime | null): this;
+    travelTime(
+        travelTime?: ICalEventTravelTime | null | number,
+    ): ICalEventTravelTime | null | number | this {
+        if (travelTime === undefined) {
+            return this.data.travelTime;
+        }
+
+        if (typeof travelTime === 'number' && travelTime <= 0) {
+            throw new Error('`travelTime` has to be more than 0!');
+        }
+
+        if (
+            travelTime &&
+            typeof travelTime === 'object' &&
+            'seconds' in travelTime &&
+            travelTime.seconds <= 0
+        ) {
+            throw new Error('`travelTime.seconds` has to be more than 0!');
+        }
+
+        if (typeof travelTime === 'number') {
+            this.data.travelTime = {
+                seconds: travelTime,
+            };
+            return this;
+        }
+
+        this.data.travelTime = travelTime;
+        return this;
+    }
+
     /**
      * Get the event's ID
      * @since 0.2.0

package/src/index.ts

@@ -102,6 +102,9 @@ export {
     type ICalDayJsStub,
     type ICalDescription,
     ICalEventRepeatingFreq,
+    type ICalEventTravelTime,
+    ICalEventTravelTimeSuggestion,
+    ICalEventTravelTimeTransportation,
     type ICalGeo,
     type ICalLocation,
     type ICalLocationWithoutTitle,

package/src/types.ts

@@ -8,6 +8,29 @@ export enum ICalEventRepeatingFreq {
     YEARLY = 'YEARLY',
 }
 
+/**
+ * Used in ICalEvent.travelTime()
+ *
+ * Controls whether Apple clients give suggestions like "Time to leave" notifications, route prompts in Apple Maps, etc.
+ */
+export enum ICalEventTravelTimeSuggestion {
+    AUTOMATIC = 'AUTOMATIC',
+    DISABLED = 'DISABLED',
+    ENABLED = 'ENABLED',
+}
+
+/**
+ * Used in ICalEvent.travelTime()
+ *
+ * Controls which mode of transportation is used by Apple Calendar clients for calculating travel time and suggesting routes
+ */
+export enum ICalEventTravelTimeTransportation {
+    BICYCLE = 'BICYCLE',
+    CAR = 'CAR',
+    TRANSIT = 'TRANSIT',
+    WALKING = 'WALKING',
+}
+
 export enum ICalWeekday {
     FR = 'FR',
     MO = 'MO',
@@ -50,6 +73,15 @@ export interface ICalDescription {
     plain: string;
 }
 
+export interface ICalEventTravelTime {
+    seconds: number;
+    startFrom?: {
+        location: ICalLocation;
+        transportation: ICalEventTravelTimeTransportation;
+    };
+    suggestionBehavior?: ICalEventTravelTimeSuggestion;
+}
+
 export interface ICalGeo {
     lat: number;
     lon: number;