[NO-ISSUE] feat: allow to query multiple users (freebusy)

scheduler/clients/javascript/lib/baseClient.ts

@@ -62,6 +62,9 @@ export abstract class NettuBaseClient {
   }
 }
 
+/**
+ * Response from the API
+ */
 export class APIResponse<T> {
   readonly data?: T // Could be a failed response and therefore nullable
   readonly status: number
@@ -74,6 +77,9 @@ export class APIResponse<T> {
   }
 }
 
+/**
+ * Credentials for the API for end users (usually frontend)
+ */
 export class UserCreds implements ICredentials {
   private readonly nettuAccount: string
   private readonly token?: string
@@ -95,6 +101,9 @@ export class UserCreds implements ICredentials {
   }
 }
 
+/**
+ * Credentials for the API for admins (usually backend)
+ */
 export class AccountCreds implements ICredentials {
   private readonly apiKey: string
 

scheduler/clients/javascript/lib/calendarClient.ts

@@ -14,46 +14,117 @@ import type {
 import type { Timespan } from './eventClient'
 import { convertInstanceDates } from './helpers/datesConverters'
 
+/**
+ * Request for creating a calendar
+ */
 type CreateCalendarRequest = {
+  /**
+   * Timezone used in the calendar
+   */
   timezone: string
+  /**
+   * Start of the week used in the calendar
+   * @format 0-6 - 0 is Monday, 1 is Tuesday, etc.
+   * @default 0
+   */
   weekStart?: number
+  /**
+   * Possible metadata
+   */
   metadata?: {
     key: string
     value: string
   }
 }
 
+/**
+ * Request for updating a calendar
+ */
 type UpdateCalendarRequest = CreateCalendarRequest
 
+/**
+ * Response for getting the events of a calendar
+ */
 type GetCalendarEventsResponse = {
+  /**
+   * Calendar object
+   */
   calendar: Calendar
+  /**
+   * List of events with their instances
+   */
   events: {
+    /**
+     * Event object
+     */
     event: CalendarEvent
+    /**
+     * List of instances of the event
+     * Especially useful for recurring events
+     */
     instances: CalendarEventInstance[]
   }[]
 }
 
+/**
+ * Response for getting a calendar
+ */
 type CalendarResponse = {
+  /**
+   * Calendar object
+   */
   calendar: Calendar
 }
 
+/**
+ * Payload sent for enabling the sync of a calendar with an external calendar
+ */
 type SyncCalendarInput = {
+  /**
+   * Uuid of the user
+   */
   userId: string
+  /**
+   * Uuid of the calendar
+   */
   calendarId: string
+  /**
+   * Uuid of the external calendar
+   */
   extCalendarId: string
+  /**
+   * Provider of the external calendar
+   * @format IntegrationProvider (Google, Outlook)
+   */
   provider: IntegrationProvider
 }
 
+/**
+ * Payload sent for disabling the sync of a calendar with an external calendar
+ */
 type StopCalendarSyncInput = {
+  /**
+   * Uuid of the user
+   */
   userId: string
+  /**
+   * Uuid of the calendar
+   */
   calendarId: string
+  /**
+   * Uuid of the external calendar
+   */
   extCalendarId: string
+  /**
+   * Provider of the external calendar
+   * @format IntegrationProvider (Google, Outlook)
+   */
   provider: IntegrationProvider
 }
 
 /**
  * Client for the calendar endpoints
- * This is an admin client
+ * This is an admin client (usually backend)
  */
 export class NettuCalendarClient extends NettuBaseClient {
   /**
@@ -66,10 +137,22 @@ export class NettuCalendarClient extends NettuBaseClient {
     return this.post<CalendarResponse>(`/user/${userId}/calendar`, data)
   }
 
+  /**
+   * Find a calendar by id
+   * @param calendarId - uuid of the calendar to find
+   * @returns CalendarResponse - found calendar, if any
+   */
   public findById(calendarId: string) {
     return this.get<CalendarResponse>(`/user/calendar/${calendarId}`)
   }
 
+  /**
+   * Find calendars by metadata
+   * @param meta - metadata to search for
+   * @param skip - number of calendars to skip
+   * @param limit - number of calendars to return
+   * @returns CalendarResponse - found calendars
+   */
   public findByMeta(
     meta: {
       key: string
@@ -86,6 +169,12 @@ export class NettuCalendarClient extends NettuBaseClient {
     })
   }
 
+  /**
+   * Find Google calendars for an user
+   * @param userId - uuid of the user to find the calendars for
+   * @param minAccessRole - minimum access role required
+   * @returns - found Google calendars
+   */
   async findGoogle(userId: string, minAccessRole: GoogleCalendarAccessRole) {
     return this.get<{ calendars: GoogleCalendarListEntry[] }>(
       `/user/${userId}/calendar/provider/google`,
@@ -95,17 +184,34 @@ export class NettuCalendarClient extends NettuBaseClient {
     )
   }
 
+  /**
+   * Find Outlook calendars for an user
+   * @param userId - uuid of the user to find the calendars for
+   * @param minAccessRole - minimum access role required
+   * @returns - found Outlook calendars
+   */
   async findOutlook(userId: string, minAccessRole: OutlookCalendarAccessRole) {
     return this.get<{ calendars: OutlookCalendar[] }>(
       `/user/${userId}/calendar/provider/outlook`,
       { minAccessRole }
     )
   }
 
+  /**
+   * Remove the calendar with the given id
+   * @param calendarId - uuid of the calendar to remove
+   * @returns CalendarResponse - removed calendar
+   */
   public remove(calendarId: string) {
     return this.delete<CalendarResponse>(`/user/calendar/${calendarId}`)
   }
 
+  /**
+   * Update the calendar with the given id
+   * @param calendarId - uuid of the calendar to update
+   * @param data - data to update the calendar with
+   * @returns CalendarResponse - updated calendar
+   */
   public update(calendarId: string, data: UpdateCalendarRequest) {
     return this.put<CalendarResponse>(`/user/calendar/${calendarId}`, {
       settings: {
@@ -116,6 +222,13 @@ export class NettuCalendarClient extends NettuBaseClient {
     })
   }
 
+  /**
+   * Get the events for a calendar within a timespan
+   * @param calendarId - uuid of the calendar to get the events for
+   * @param startTime - start of the timespan
+   * @param endTime - end of the timespan
+   * @returns GetCalendarEventsResponse - events within the timespan
+   */
   public async getEvents(
     calendarId: string,
     startTime: Date,
@@ -140,16 +253,17 @@ export class NettuCalendarClient extends NettuBaseClient {
         calendar: res.data.calendar,
         events: res.data.events.map(event => ({
           event: event.event,
-          instances: event.instances.map(instance => ({
-            startTime: new Date(instance.startTime),
-            endTime: new Date(instance.endTime),
-            busy: instance.busy,
-          })),
+          instances: event.instances.map(convertInstanceDates),
         })),
       },
     }
   }
 
+  /**
+   * Enable automated sync of a calendar with an external calendar
+   * @param input - data for syncing the calendar
+   * @returns - void
+   */
   public syncCalendar(input: SyncCalendarInput) {
     const body = {
       calendarId: input.calendarId,
@@ -159,6 +273,11 @@ export class NettuCalendarClient extends NettuBaseClient {
     return this.put(`user/${input.userId}/calendar/sync`, body)
   }
 
+  /**
+   * Disable automated sync of a calendar with an external calendar
+   * @param input - data for stopping the calendar sync
+   * @returns - void
+   */
   public stopCalendarSync(input: StopCalendarSyncInput) {
     const body = {
       calendarId: input.calendarId,
@@ -171,7 +290,7 @@ export class NettuCalendarClient extends NettuBaseClient {
 
 /**
  * Client for the calendar endpoints
- * This is a user client
+ * This is an end user client (usually frontend)
  */
 export class NettuCalendarUserClient extends NettuBaseClient {
   public create(data: CreateCalendarRequest) {

scheduler/clients/javascript/lib/eventClient.ts

@@ -10,11 +10,25 @@ import {
   convertInstanceDates,
 } from './helpers/datesConverters'
 
+/**
+ * Reminder for an event
+ */
 interface EventReminder {
+  /**
+   * Time before the event to trigger the reminder
+   * @format minutes
+   */
   delta: number
+  /**
+   * Identifier of the reminder
+   * @format uuid
+   */
   identifier: string
 }
 
+/**
+ * Request for creating a calendar event
+ */
 type CreateCalendarEventReq = {
   calendarId: string
   startTime: Date
@@ -26,6 +40,9 @@ type CreateCalendarEventReq = {
   metadata?: Metadata
 }
 
+/**
+ * Request for updating a calendar event
+ */
 type UpdateCalendarEventReq = {
   startTime?: Date
   duration?: number
@@ -37,43 +54,32 @@ type UpdateCalendarEventReq = {
   metadata?: Metadata
 }
 
+/**
+ * Timespan for getting event instances
+ */
 export type Timespan = {
   startTime: Date
   endTime: Date
 }
 
+/**
+ * Response for getting event instances
+ */
 type GetEventInstancesResponse = {
   instances: CalendarEventInstance[]
 }
 
+/**
+ * Response for an event
+ */
 type EventReponse = {
   event: CalendarEvent
 }
 
-function convertEventDates(event: CalendarEvent): CalendarEvent {
-  if (!event) {
-    return event
-  }
-  return {
-    ...event,
-    startTime: new Date(event.startTime),
-    exdates: event.exdates.map(date => new Date(date)),
-  }
-}
-
-export function convertInstanceDates(
-  instance: CalendarEventInstance
-): CalendarEventInstance {
-  if (!instance) {
-    return instance
-  }
-  return {
-    ...instance,
-    startTime: new Date(instance.startTime),
-    endTime: new Date(instance.endTime),
-  }
-}
-
+/**
+ * Client for the events' endpoints
+ * This is an admin client (usually backend)
+ */
 export class NettuEventClient extends NettuBaseClient {
   public async update(
     eventId: string,
@@ -187,6 +193,10 @@ export class NettuEventClient extends NettuBaseClient {
   }
 }
 
+/**
+ * Client for the event endpoints
+ * This is an end user client (usually frontend)
+ */
 export class NettuEventUserClient extends NettuBaseClient {
   public async update(
     eventId: string,