zaccl 3.0.17 → 4.0.0

package/src/endpoints/ECatMeeting.ts

@@ -22,10 +22,13 @@ import ZoomPollStatus from '../types/ZoomPollStatus';
 import ZoomPollQuestion from '../types/ZoomPollQuestion';
 import ZoomMeetingDetails from '../types/ZoomMeetingDetails';
 import ZoomMeetingIdAndStartTime from '../types/ZoomMeetingIdAndStartTime';
+import ZoomMeetingTranscript from '../types/ZoomMeetingTranscript';
+import ZoomPastMeetingParticipant from '../types/ZoomPastMeetingParticipant';
+import ZoomPastMeetingDetails from '../types/ZoomPastMeetingDetails';
 
 class ECatMeeting extends EndpointCategory {
   /**
-   * Get info on a meeting
+   * Get info on a meeting (Light)
    * @author Gabe Abrams
    * @author Aryan Pandey
    * @instance
@@ -36,7 +39,7 @@ class ECatMeeting extends EndpointCategory {
    * @param [opts.occurrenceId] ID for the meeting occurrence
    * @param [opts.showAllOccurrences=false] if truthy,
    *   retrieves all past occurrences
-   * @returns Zoom meeting object {@link https://marketplace.zoom.us/docs/api-reference/zoom-api/meetings/meeting#responses}
+   * @returns Zoom meeting object
    */
   async get(
     opts: {
@@ -78,7 +81,7 @@ class ECatMeeting extends EndpointCategory {
   }
 
   /**
-   * Create a new meeting
+   * Create a new meeting (Light)
    * @author Gabe Abrams
    * @author Aryan Pandey
    * @instance
@@ -110,7 +113,7 @@ class ECatMeeting extends EndpointCategory {
   }
 
   /**
-   * Update a meeting
+   * Update a meeting (Light)
    * @author Gabe Abrams
    * @author Aryan Pandey
    * @instance
@@ -154,7 +157,7 @@ class ECatMeeting extends EndpointCategory {
   }
 
   /**
-   * Delete a meeting
+   * Delete a meeting (Light)
    * @author Gabe Abrams
    * @author Aryan Pandey
    * @instance
@@ -212,7 +215,7 @@ class ECatMeeting extends EndpointCategory {
   }
 
   /**
-   * Get a list of ended meeting instances
+   * Get a list of ended meeting instances (Medium)
    * @author Gabe Abrams
    * @author Aryan Pandey
    * @instance
@@ -234,11 +237,12 @@ class ECatMeeting extends EndpointCategory {
       errorMap: {
         404: `We could not find a meeting with the ID ${opts.meetingId}`,
       },
+      itemKey: 'meetings',
     });
   }
 
   /**
-   * Get details of a past meeting instance
+   * Get details of a past meeting instance (Light)
    * @author Yuen Ler Chow
    * @instance
    * @memberof api.meeting
@@ -270,7 +274,7 @@ class ECatMeeting extends EndpointCategory {
   }
 
   /**
-   * List past poll occurrences
+   * List past poll occurrences (Medium)
    * @author Yuen Ler Chow
    * @instance
    * @memberof api.meeting
@@ -394,7 +398,7 @@ class ECatMeeting extends EndpointCategory {
   }
 
   /**
-   * Get poll info
+   * Get poll info (Light)
    * @author Yuen Ler Chow
    * @instance
    * @memberof api.meeting
@@ -554,7 +558,7 @@ class ECatMeeting extends EndpointCategory {
    *   user is added as the only alt-host. This is because Zoom doesn't give us
    *   enough information to determine which user is deactivated, and thus,
    *   the only way to resolve the issue is to remove all previously existing
-   *   alt-hosts.
+   *   alt-hosts. (Light)
    * @author Gabe Abrams
    * @author Aryan Pandey
    * @instance
@@ -631,6 +635,73 @@ class ECatMeeting extends EndpointCategory {
     // return updated meeting object
     return meetingObj;
   }
+
+  /**
+   * Get meeting transcript (Medium)
+   * @author Gabe Abrams
+   * @instance
+   * @memberof api.meeting
+   * @method getTranscript
+   * @param opts object containing all arguments
+   * @param opts.meetingId the Zoom ID of the meeting (or UUID of a past meeting instance)
+   * @returns meeting transcript
+   */
+  async getTranscript(
+    opts: {
+      meetingId: number,
+    },
+  ): Promise<ZoomMeetingTranscript> {
+    return this.visitEndpoint({
+      path: `/meetings/${opts.meetingId}/transcript`,
+      action: 'get the meeting transcript',
+      method: 'GET',
+      errorMap: {
+        400: 'Invalid meeting ID',
+        403: 'You do not have permission to access the transcript for this meeting',
+        404: {
+          3322: 'The meeting transcript does not exist',
+        },
+      },
+    });
+  }
+
+  /**
+   * Get list of participants in a past meeting (Medium)
+   * @author Gabe Abrams
+   * @instance
+   * @memberof api.meeting
+   * @method listPastMeetingParticipants
+   * @param opts object containing all arguments
+   * @param opts.meetingId the Zoom UUID of the past meeting instance
+   * @param [opts.onNewPage] callback function that is called when a new page of results is received.
+   * @returns list of past meeting participants
+   */
+  async listPastMeetingParticipants(
+    opts: {
+      meetingId: string,
+      onNewPage?: (participants: ZoomPastMeetingParticipant[]) => void, 
+    },
+  ): Promise<ZoomPastMeetingParticipant[]> {
+    return this.visitEndpoint({
+      path: `/past_meetings/${opts.meetingId}/participants`,
+      action: 'get the list of participants in a past meeting',
+      method: 'GET',
+      params: {
+        page_size: 300, // max allowed page size
+      },
+      itemKey: 'participants',
+      onNewPage: opts.onNewPage,
+      errorMap: {
+        400: {
+          200: 'You need a paid account to access the participant list of a past meeting.',
+          12702: 'You are not allowed to access information about meetings that occurred more than 1 year ago.',
+        },
+        404: {
+          3001: 'The meeting ID is invalid or the meeting has not ended.',
+        },
+      },
+    });
+  }
 }
 
 /*------------------------------------------------------------------------*/

package/src/endpoints/ECatUser.ts

@@ -12,7 +12,7 @@ import ZoomUser from '../types/ZoomUser';
 
 class ECatUser extends EndpointCategory {
   /**
-   * Retrieve a user's ZAK token
+   * Retrieve a user's ZAK token (Light)
    * @author Aryan Pandey
    * @instance
    * @memberof api.user
@@ -33,21 +33,18 @@ class ECatUser extends EndpointCategory {
       params: {
         type: 'zak',
       },
+      itemKey: 'token',
       errorMap: {
         404: {
           1001: `We could not retrieve a token for Zoom user ${opts.userId} since this user does not exist`,
         },
       },
-      postProcessor: (body) => {
-        // extract zak token from the response object
-        return body.token;
-      },
     });
   }
 
   /**
    * (Re)activate a user and promote them to a "licensed" user (unless
-   *   dontPromoteToLicensed is true)
+   *   dontPromoteToLicensed is true) (Light)
    * @author Gabe Abrams
    * @instance
    * @memberof api.user
@@ -98,7 +95,7 @@ class ECatUser extends EndpointCategory {
   }
 
   /**
-   * Add a webinar license to the user of interest
+   * Add a webinar license to the user of interest (Medium)
    * @author Gabe Abrams
    * @instance
    * @memberof api.user
@@ -136,7 +133,7 @@ class ECatUser extends EndpointCategory {
   }
 
   /**
-   * Get a user
+   * Get a user (Light)
    * @author Gabe Abrams
    * @instance
    * @memberof api.user
@@ -163,7 +160,7 @@ class ECatUser extends EndpointCategory {
   }
 
   /**
-   * Promote a user to "licensed" type
+   * Promote a user to "licensed" type (Light)
    * @author Gabe Abrams
    * @instance
    * @memberof api.user

package/src/endpoints/ECatWebinar.ts

@@ -13,7 +13,7 @@ import ZoomWebinar from '../types/ZoomWebinar';
 
 class ECatWebinar extends EndpointCategory {
   /**
-   * Get info on a Webinar
+   * Get info on a Webinar (Light)
    * @author Gabe Abrams
    * @instance
    * @memberof api.webinar
@@ -64,7 +64,7 @@ class ECatWebinar extends EndpointCategory {
   }
 
   /**
-   * Create a webinar
+   * Create a webinar (Light)
    * @author Gabe Abrams
    * @instance
    * @memberof api.webinar
@@ -101,7 +101,7 @@ class ECatWebinar extends EndpointCategory {
   }
 
   /**
-   * Add one panelist if not already in the list
+   * Add one panelist if not already in the list (Medium)
    * @author Gabe Abrams
    * @instance
    * @memberof api.webinar
@@ -144,7 +144,7 @@ class ECatWebinar extends EndpointCategory {
   }
 
   /**
-   * Get a list of panelists for a webinar
+   * Get a list of panelists for a webinar (Medium)
    * @author Gabe Abrams
    * @instance
    * @memberof api.webinar
@@ -171,6 +171,7 @@ class ECatWebinar extends EndpointCategory {
           3001: `Webinar ${opts.webinarId} could not be found or has expired`,
         },
       },
+      itemKey: 'panelists',
     });
 
     // Just keep list of panelists

package/src/index.ts

@@ -9,6 +9,7 @@ import ECatCloudRecording from './endpoints/ECatCloudRecording';
 import ECatMeeting from './endpoints/ECatMeeting';
 import ECatUser from './endpoints/ECatUser';
 import ECatWebinar from './endpoints/ECatWebinar';
+import ECatGroup from './endpoints/ECatGroup';
 
 // Import shared types
 import ZoomAPIConfig from './types/ZoomAPIConfig';
@@ -17,6 +18,29 @@ import ZACCLError from './shared/classes/ZACCLError';
 import ErrorCode from './shared/types/ErrorCode';
 import ZoomAPIConfigType from './types/ZoomAPIConfigType';
 
+// Import all Zoom types
+import ZoomPanelist from './types/ZoomPanelist';
+import ZoomPollInfo from './types/ZoomPollInfo';
+import ZoomPollOccurrence from './types/ZoomPollOccurrence';
+import ZoomFileType from './types/ZoomFileType';
+import ZoomPollQuestion from './types/ZoomPollQuestion';
+import ZoomPollQuestionAndAnswerType from './types/ZoomPollQuestionAndAnswerType';
+import ZoomPollStatus from './types/ZoomPollStatus';
+import ZoomLoginMethod from './types/ZoomLoginMethod';
+import ZoomPollType from './types/ZoomPollType';
+import ZoomRecordingFile from './types/ZoomRecordingFile';
+import ZoomRecordingType from './types/ZoomRecordingType';
+import ZoomMeetingIdAndStartTime from './types/ZoomMeetingIdAndStartTime';
+import ZoomRecurrenceInfo from './types/ZoomRecurrenceInfo';
+import ZoomMeetingOrWebinarType from './types/ZoomMeetingOrWebinarType';
+import ZoomMeetingRecordings from './types/ZoomMeetingRecordings';
+import ZoomUserAnswer from './types/ZoomUserAnswer';
+import ZoomMeetingTranscript from './types/ZoomMeetingTranscript';
+import ZoomUsersAnswersToQuestion from './types/ZoomUsersAnswersToQuestion';
+import ZoomMeetingType from './types/ZoomMeetingType';
+import ZoomWebinar from './types/ZoomWebinar';
+import ZoomPastMeetingParticipant from './types/ZoomPastMeetingParticipant';
+
 // Import shared constants
 import DEFAULT_ZOOM_HOSTNAME from './shared/constants/DEFAULT_ZOOM_HOSTNAME';
 
@@ -137,9 +161,38 @@ const initZoomAPI = (
   api.meeting = new ECatMeeting(initPack);
   api.user = new ECatUser(initPack);
   api.webinar = new ECatWebinar(initPack);
+  api.group = new ECatGroup(initPack);
 
   // Return api instance
   return api;  
 };
 
 export default initZoomAPI;
+
+/*----------------------------------------*/
+/* ---------------- Types --------------- */
+/*----------------------------------------*/
+
+export {
+  ZoomPanelist,
+  ZoomPollInfo,
+  ZoomPollOccurrence,
+  ZoomFileType,
+  ZoomPollQuestion,
+  ZoomPollQuestionAndAnswerType,
+  ZoomPollStatus,
+  ZoomLoginMethod,
+  ZoomPollType,
+  ZoomRecordingFile,
+  ZoomRecordingType,
+  ZoomMeetingIdAndStartTime,
+  ZoomRecurrenceInfo,
+  ZoomMeetingOrWebinarType,
+  ZoomMeetingRecordings,
+  ZoomUserAnswer,
+  ZoomMeetingTranscript,
+  ZoomUsersAnswersToQuestion,
+  ZoomMeetingType,
+  ZoomWebinar,
+  ZoomPastMeetingParticipant,
+};

package/src/shared/helpers/genVisitEndpoint.ts

@@ -28,6 +28,10 @@ const genVisitEndpoint = (zoomAPIConfig: ZoomAPIConfig): VisitEndpointFunc => {
    * @param [opts.postProcessor] function that processes the response before
    *   returning
    * @param [opts.params] Parameters/args/body to send with request
+   * @param [opts.onNewPage] callback function that is called when a
+   * new page of results is received
+   * @param [opts.itemKey] the key in the response body where the list of items can be found
+   * @param [opts.onNewPage] callback function that is called when a new page of results is received
    * @returns response body
    */
   return async (
@@ -44,7 +48,8 @@ const genVisitEndpoint = (zoomAPIConfig: ZoomAPIConfig): VisitEndpointFunc => {
         )
       },
       params?: { [k: string]: any },
-      postProcessor?: (response: any) => any,
+      itemKey?: string,
+      onNewPage?: (page: any) => void,
     },
   ): Promise<any> => {
     const {
@@ -52,101 +57,140 @@ const genVisitEndpoint = (zoomAPIConfig: ZoomAPIConfig): VisitEndpointFunc => {
       params,
       action,
       errorMap,
-      postProcessor,
+      itemKey,
+      onNewPage,
     } = opts;
     const method = (opts.method ?? 'GET');
 
-    /* ---------- Send Request ---------- */
-
-    const { status, headers, body } = await sendZoomRequest({
-      path,
-      method,
-      params,
-      zoomAPIConfig,
-    });
-
-    /* ----------- Rate Error ----------- */
-
-    if (status === 429) {
-      // Case-insensitive header lookup
-      const [rateLimitTypeHeader] = Object.keys(headers).filter((header) => {
-        return (header.toLowerCase() === 'x-ratelimit-type');
+    // Paging state
+    let nextPageToken: string | undefined = undefined;
+    let isFirstPage = true;
+    let isPaginated = false; // Inferred by responses, always starts false
+    const allItems: any[] = [];
+
+    // Fetch page by page
+    while (nextPageToken || isFirstPage) {
+      // Don't fetch another page unless we get a token
+      isFirstPage = false;
+
+      /* ---------- Send Request ---------- */
+
+      const { status, headers, body } = await sendZoomRequest({
+        path,
+        method,
+        params: {
+          ...params,
+          next_page_token: nextPageToken,
+        },
+        zoomAPIConfig,
       });
 
-      // Case-insensitive limit type lookup
-      const rateLimitType = (
-        headers[rateLimitTypeHeader]
-        && headers[rateLimitTypeHeader].toLowerCase()
-      );
+      /* ----------- Rate Error ----------- */
 
-      if (rateLimitType === ThrottleHeader.DailyLimitHeader) {
-        // Daily limit
-        throw new ZACCLError({
-          message: 'Zoom is very busy today. Please try this operation again tomorrow.',
-          code: ErrorCode.DailyLimitError,
-        });
-      } else if (rateLimitType === ThrottleHeader.RateLimitHeader) {
-        // Rate limit
-        throw new ZACCLError({
-          message: 'Zoom is very busy right now. Please try this operation again later.',
-          code: ErrorCode.RateLimitError,
-        });
-      } else {
-        // Unknown rate limit
-        throw new ZACCLError({
-          message: 'Zoom is very busy right now. Please try this operation again.',
-          code: ErrorCode.UnknownLimitError,
+      if (status === 429) {
+        // Case-insensitive header lookup
+        const [rateLimitTypeHeader] = Object.keys(headers).filter((header) => {
+          return (header.toLowerCase() === 'x-ratelimit-type');
         });
+
+        // Case-insensitive limit type lookup
+        const rateLimitType = (
+          headers[rateLimitTypeHeader]
+          && headers[rateLimitTypeHeader].toLowerCase()
+        );
+
+        if (rateLimitType === ThrottleHeader.DailyLimitHeader) {
+          // Daily limit
+          throw new ZACCLError({
+            message: 'Zoom is very busy today. Please try this operation again tomorrow.',
+            code: ErrorCode.DailyLimitError,
+          });
+        } else if (rateLimitType === ThrottleHeader.RateLimitHeader) {
+          // Rate limit
+          throw new ZACCLError({
+            message: 'Zoom is very busy right now. Please try this operation again later.',
+            code: ErrorCode.RateLimitError,
+          });
+        } else {
+          // Unknown rate limit
+          throw new ZACCLError({
+            message: 'Zoom is very busy right now. Please try this operation again.',
+            code: ErrorCode.UnknownLimitError,
+          });
+        }
       }
-    }
-
-    /* -------- Custom Error Code ------- */
-
-    if (status < 200 || status >= 300) {
-      // A Zoom error occurred
-
-      // Check status to see if its in the error map
-      let zoomErrorMessage = 'An unknown Zoom error occurred.';
-      if (errorMap[status]) {
-        if (typeof errorMap[status] === 'string') {
-          // Found the error message
-          zoomErrorMessage = (errorMap[status] as string);
-        } else if (body.code) {
-          // Check for nested error message
-          if (typeof errorMap[status][body.code] === 'string') {
-            // Found nested error message
-            zoomErrorMessage = errorMap[status][body.code];
-          } else if (body.message) {
-            // errorMap[status][code] did not return err message
-            // so we check body
-            if (typeof body.message === 'string') {
-              zoomErrorMessage = body.message;
+
+      /* -------- Custom Error Code ------- */
+
+      if (status < 200 || status >= 300) {
+        // A Zoom error occurred
+
+        // Check status to see if its in the error map
+        let zoomErrorMessage = 'An unknown Zoom error occurred.';
+        if (errorMap[status]) {
+          if (typeof errorMap[status] === 'string') {
+            // Found the error message
+            zoomErrorMessage = (errorMap[status] as string);
+          } else if (body.code) {
+            // Check for nested error message
+            if (typeof errorMap[status][body.code] === 'string') {
+              // Found nested error message
+              zoomErrorMessage = errorMap[status][body.code];
+            } else if (body.message) {
+              // errorMap[status][code] did not return err message
+              // so we check body
+              if (typeof body.message === 'string') {
+                zoomErrorMessage = body.message;
+              }
             }
           }
+        } else if (body.message) {
+          // Error message not in the error map so check body
+          if (typeof body.message === 'string') {
+            zoomErrorMessage = body.message;
+          }
         }
-      } else if (body.message) {
-        // Error message not in the error map so check body
-        if (typeof body.message === 'string') {
-          zoomErrorMessage = body.message;
-        }
+
+        const errorMessage = `We couldn't ${action} because an error occurred: ${zoomErrorMessage}`;
+        const errorCode = `ZOOM${status}${body.code ? `-${body.code}` : ''}`;
+
+        throw new ZACCLError({
+          message: errorMessage,
+          code: errorCode,
+        });
       }
 
-      const errorMessage = `We couldn't ${action} because an error occurred: ${zoomErrorMessage}`;
-      const errorCode = `ZOOM${status}${body.code ? `-${body.code}` : ''}`;
+      /* ----------- Postprocess ---------- */
 
-      throw new ZACCLError({
-        message: errorMessage,
-        code: errorCode,
-      });
-    }
+      // Extract results
+      let results = itemKey ? body[itemKey] : body;
 
-    /* ----- Post-process and Return ---- */
+      // Update next page token
+      nextPageToken = body.next_page_token;
+      if (nextPageToken) {
+        isPaginated = true;
+      }
 
-    if (postProcessor) {
-      return postProcessor(body);
-    }
+      // End if not paginated
+      if (!isPaginated) {
+        return results;
+      }
+
+      /* --------- Paging Handling -------- */
+
+      // Add items to allItems if paginated
+      if (Array.isArray(results)) {
+        allItems.push(...results);
+      }
+
+      // Call onNewPage callback if it exists
+      if (onNewPage) {
+        onNewPage(results);
+      }
+    };
 
-    return body;
+    // Return all items (if we got here, response is paginated)
+    return allItems;
   };
 };
 

package/src/shared/types/VisitEndpointFunc.ts

@@ -22,8 +22,10 @@ type VisitEndpointFunc = (
       },
       // Parameters/args/body to send with request
       params?: { [k: string]: any },
-      // Function that processes the response before returning
-      postProcessor?: (response: any) => any,
+      // The key in the response body where the list of items can be found (for paginated endpoints)
+      itemKey?: string,
+      // Callback function that is called when a new page of results is received (for paginated endpoints)
+      onNewPage?: (items: any[]) => void,
     },
   ) => Promise<any>
 );

package/src/types/ZoomAPI.ts

@@ -1,4 +1,5 @@
 import ECatCloudRecording from '../endpoints/ECatCloudRecording';
+import ECatGroup from '../endpoints/ECatGroup';
 import ECatMeeting from '../endpoints/ECatMeeting';
 import ECatUser from '../endpoints/ECatUser';
 import ECatWebinar from '../endpoints/ECatWebinar';
@@ -12,6 +13,7 @@ interface ZoomAPI {
   meeting: ECatMeeting,
   user: ECatUser,
   webinar: ECatWebinar,
+  group: ECatGroup,
 };
 
 export default ZoomAPI;

package/src/types/ZoomGroup.ts

@@ -0,0 +1,14 @@
+/**
+ * Zoom user group
+ * @author Gabe Abrams
+ */
+type ZoomGroup = {
+  // Unique id for the group
+  id: string,
+  // Name of the group
+  name: string,
+  // Total number of members in the group
+  total_members: number,
+};
+
+export default ZoomGroup;

package/src/types/ZoomGroupMember.ts

@@ -0,0 +1,20 @@
+/**
+ * A single group member within a Zoom group
+ * @author Gabe Abrams
+ */
+type ZoomGroupMember = {
+  // User's email address
+  email: string,
+  // First name of the user
+  first_name: string,
+  // Unique Identifier of the user
+  id: string,
+  // Last name of the user
+  last_name: string,
+  // User type:
+  //   1 - Basic
+  //   2 - Licensed
+  type: (1 | 2),
+};
+
+export default ZoomGroupMember;

package/src/types/ZoomMeetingRecordings.ts

@@ -32,6 +32,8 @@ type ZoomMeetingRecordings = {
   uuid: string,
   // Recording file List
   recording_files?: ZoomRecordingFile[],
+  // JWT download access token that can be used to download the recording files. Only included if requested
+  download_access_token?: string,
 };
 
 export default ZoomMeetingRecordings;