feat(config): adds support for attendees

Adds an array of CalendarAttendee objects to each calendar type which
describes attendee name, email, and ICS-specific options.

Implements jshor#131

src/CalendarBase.ts

@@ -2,6 +2,7 @@ import ICalendarBase from './types/ICalendarBase'
 import CalendarRecurrence from './types/CalendarRecurrence'
 import CalendarOptions from './types/CalendarOptions'
 import time from './utils/time'
+import CalendarAttendee from './types/CalendarAttendee'
 
 /**
  * Base calendar class. This class can be extended to add new calendar services.
@@ -31,9 +32,22 @@ abstract class CalendarBase implements ICalendarBase {
   /** Calendar service query string params. */
   protected params: Record<string, string | null> = {}
 
+  /**
+   * An array of event attendees. See {@link CalendarAttendee}
+   *
+   * @type {Array<CalendarAttendee>}
+   */
+  attendees: Array<CalendarAttendee> = []
+
+  /**
+   * Constructor.
+   *
+   * @param {CalendarOptions} options
+   */
   constructor (options: CalendarOptions) {
     this.setText(options)
     this.setTimestamps(options)
+    this.setAttendees(options)
   }
 
   /**
@@ -66,6 +80,52 @@ abstract class CalendarBase implements ICalendarBase {
     this.recurrence = options.recurrence
   }
 
+  /**
+   * Sets the attendees array if attendees are supplied.
+   * Extend this method in child classes if additional manipulation
+   * must occur.
+   *
+   * @param {CalendarOptions} options
+   */
+  public setAttendees (options: CalendarOptions): void {
+    if (Array.isArray(options.attendees)) {
+      this.attendees = options.attendees
+    } else {
+      this.attendees = []
+    }
+  }
+
+  /**
+   * Transforms the array of attendee objects into an array of attendee
+   * strings. Extend this method in child classes if additional manipulation
+   * must occur (i.e. ICalendar)
+   */
+  public renderAttendeesArr (): Array<string> {
+    if (this.attendees.length === 0) {
+      throw new Error('No attendees')
+    }
+    return this.attendees.map(({
+      name,
+      email,
+    }) => {
+      const mailTo = `<${email}>`
+      let commonName = email
+      if (name) {
+        commonName = name
+      }
+      return `${commonName} ${mailTo}`
+    })
+  }
+
+  /**
+   * Joins the results of `this.renderAttendeesArr` using a join character.
+   * Extend this method in child classes if a different join character is
+   * neeeded.
+   */
+  public renderAttendees (): string {
+    return this.renderAttendeesArr().join(',')
+  }
+
   /**
    * Sets additional calendar service properties.
    * May be used to override existing query string params if necessary.

src/GoogleCalendar.ts

@@ -40,6 +40,10 @@ export default class GoogleCalendar extends CalendarBase {
     if (this.recurrence) {
       this.setParam('recur', `RRULE:${ics.getRrule(this.recurrence)}`)
     }
+
+    if (this.attendees.length > 0) {
+      this.setParam('add', this.renderAttendees())
+    }
   }
 
   /**

src/YahooCalendar.ts

@@ -28,6 +28,9 @@ export default class YahooCalendar extends CalendarBase {
 
     this.setTimeParams()
     this.setRecurrenceParams()
+    if (this.attendees.length > 0) {
+      this.setParam('inv_list', this.renderAttendees())
+    }
   }
 
   /**

src/__tests__/CalendarBase.spec.ts

@@ -147,4 +147,36 @@ describe('Calendar Base', () => {
       })
     })
   })
+
+  describe('setAttendees()', () => {
+    let calendarObj: CalendarBase
+
+    beforeEach(() => {
+      calendarObj = new CalendarBase(baseOpts)
+    })
+
+    describe('with no attendees property', () => {
+      it('should set an empty array', () => {
+        calendarObj.setAttendees(baseOpts)
+
+        expect(calendarObj.attendees).toEqual([])
+      })
+    })
+
+    describe('with no elements in attendees array', () => {
+      it('should set an empty array', () => {
+        const testOpts = {
+          ...baseOpts,
+          attendees: []
+        }
+        calendarObj.setAttendees(testOpts)
+
+        expect(calendarObj.attendees).toEqual([])
+      })
+    })
+
+    describe('with attendees provided', () => {
+      xit('should set the attendees (no transformation)', () => {})
+    })
+  })
 })

src/types/CalendarAttendee.ts

@@ -0,0 +1,15 @@
+import ICSAttendeeOptions from './ICSAttendeeOptions'
+/**
+ * Basic Attendee Object
+ */
+
+type CalendarAttendee = {
+    /** The attendee's email address */
+    email: string
+    /** The attendee's name (optional) */
+    name?: string
+    /** Advanced options for use with ics format (optional). See {@link ICSAttendeeOptions}. */
+    icsOptions?: ICSAttendeeOptions
+}
+
+export default CalendarAttendee

src/types/CalendarOptions.ts

@@ -1,4 +1,5 @@
 import CalendarRecurrence from './CalendarRecurrence'
+import CalendarAttendee from './CalendarAttendee'
 
 /**
  * Basic config options.
@@ -16,6 +17,8 @@ type CalendarOptions = {
   end?: Date
   /** The recurrence of an event is how often the event is supposed to occur. See {@link CalendarRecurrence}. */
   recurrence?: CalendarRecurrence
+  /** An array of attendee objects, representing people who will be invited to the event (optional). See {@link CalendarAttendee}.  */
+  attendees?: Array<CalendarAttendee>
 }
 
 export default CalendarOptions

src/types/ICSAttendeeOptions.ts

@@ -0,0 +1,15 @@
+/**
+ * advanced attendee options for use with the ics format
+ */
+
+ // TODO comments on props
+ // TODO: Consult @jshor about modifications to this hierarchy to accommodate OWA
+type ICSAttendeeOptions = {
+    partStat?: string
+    role?: string
+    rsvp?: boolean
+    delegatedFrom?: string
+    sentBy?: string
+}
+
+export default ICSAttendeeOptions