zaccl 3.0.18 → 4.1.0

package/src/shared/helpers/genVisitEndpoint.ts

@@ -28,6 +28,11 @@ 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.minMsBetweenPageRequests] minimum time (in ms) to wait between
+   * paginated requests, for custom throttle control
    * @returns response body
    */
   return async (
@@ -44,7 +49,9 @@ const genVisitEndpoint = (zoomAPIConfig: ZoomAPIConfig): VisitEndpointFunc => {
         )
       },
       params?: { [k: string]: any },
-      postProcessor?: (response: any) => any,
+      itemKey?: string,
+      onNewPage?: (page: any) => void,
+      minMsBetweenPageRequests?: number,
     },
   ): Promise<any> => {
     const {
@@ -52,101 +59,160 @@ const genVisitEndpoint = (zoomAPIConfig: ZoomAPIConfig): VisitEndpointFunc => {
       params,
       action,
       errorMap,
-      postProcessor,
+      itemKey,
+      onNewPage,
+      minMsBetweenPageRequests
     } = opts;
     const method = (opts.method ?? 'GET');
 
-    /* ---------- Send Request ---------- */
-
-    const { status, headers, body } = await sendZoomRequest({
-      path,
-      method,
-      params,
-      zoomAPIConfig,
-    });
+    // Paging state
+    let nextPageToken: string | undefined = undefined;
+    let isFirstPage = true;
+    let isPaginated = false; // Inferred by responses, always starts false
+    const allItems: any[] = [];
+    let lastPageRequestTimestamp = 0;
+
+    // Fetch page by page
+    while (nextPageToken || isFirstPage) {
+      // Don't fetch another page unless we get a token
+      isFirstPage = false;
+
+      /* ---------- Send Request ---------- */
+
+      // If minMsBetweenPageRequests is set, ensure we wait at least that long between requests
+      if (minMsBetweenPageRequests) {
+        // Check how long since the last request
+        const now = Date.now();
+        const timeSinceLastRequest = now - lastPageRequestTimestamp;
+
+        // Wait extra time if we haven't waited long enough yet
+        if (timeSinceLastRequest < minMsBetweenPageRequests) {
+          await new Promise((resolve) => {
+            setTimeout(resolve, minMsBetweenPageRequests - timeSinceLastRequest);
+          });
+        }
 
-    /* ----------- Rate Error ----------- */
+        // Update timestamp of last page request
+        lastPageRequestTimestamp = Date.now();
+      }
 
-    if (status === 429) {
-      // Case-insensitive header lookup
-      const [rateLimitTypeHeader] = Object.keys(headers).filter((header) => {
-        return (header.toLowerCase() === 'x-ratelimit-type');
+      // Send the 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,12 @@ 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,
+      // Minimum time (in ms) to wait between paginated requests, for custom throttle control (for paginated endpoints)
+      minMsBetweenPageRequests?: number,
     },
   ) => 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/ZoomMeetingTranscript.ts

@@ -0,0 +1,28 @@
+/**
+ * Transcript for a specific zoom meeting instance
+ * @author Gabe Abrams
+ */
+type ZoomMeetingTranscript = {
+  // The meeting ID
+  meeting_id: string,
+  // The user account's unique identifier.
+  account_id: string,
+  // The meeting topic.
+  meeting_topic: string,
+  // ID of the user set as the host of the meeting.
+  host_id: string,
+  // The date and time that the meeting's transcript was created.
+  transcript_created_time: string,
+  // Whether the meeting transcript is available for download.
+  can_download: boolean,
+  // Auto-delete status of a meeting's transcript
+  auto_delete: boolean,
+  // The date when the recording will be auto-deleted when `auto_delete` is true.
+  auto_delete_date: string,
+  // The URL to download the transcript. Present only when `can_download` is `true`.
+  download_url: string | null,
+  // The reason why the transcript cannot be downloaded when `can_download` is `false`.
+  download_restriction_reason: 'DELETED_OR_TRASHED' | 'UNSUPPORTED' | 'NO_TRANSCRIPT_DATA' | 'NOT_READY' | null,
+};
+
+export default ZoomMeetingTranscript;

package/src/types/ZoomPastMeetingDetails.ts

@@ -0,0 +1,38 @@
+/**
+ * Details about a past meeting
+ * @author Gabe Abrams
+ */
+type ZoomPastMeetingDetails = {
+  // The meeting ID,
+  id: number,
+  // The meeting's UUID
+  uuid: string,
+  // The meeting's duration, in minutes
+  duration: number,
+  // The meeting's start date and time
+  start_time: string,
+  // The meeting's end date and time
+  end_time: string,
+  // The host's ID
+  host_id: string,
+  // The meeting host's department
+  dept: string,
+  // The number of meeting participants
+  participants_count: number,
+  // Whether the meeting was created directly through Zoom or via an API request
+  source: string,
+  // The meeting's topic
+  topic: string,
+  // The total number of minutes attended by the meeting's host and participants
+  total_minutes: number,
+  // The meeting type (0-4, 7-8)
+  type: 0 | 1 | 2 | 3 | 4 | 7 | 8,
+  // The user's email address
+  user_email: string,
+  // The user's display name
+  user_name: string,
+  // Whether the summary feature was used in the meeting
+  has_meeting_summary: boolean,
+};
+
+export default ZoomPastMeetingDetails;

package/src/types/ZoomPastMeetingParticipant.ts

@@ -0,0 +1,30 @@
+/**
+ * Represents a participant in a Zoom past meeting.
+ * @author Gabe Abrams
+ */
+type ZoomPastMeetingParticipant = {
+  // Unique identifier for the participant
+  id?: string;
+  // Display name of the participant
+  name?: string;
+  // Zoom user ID of the participant
+  user_id?: string;
+  // Registration ID if participant registered beforehand
+  registrant_id?: string;
+  // Email address of the participant
+  user_email?: string;
+  // ISO 8601 timestamp when participant joined the meeting
+  join_time?: string;
+  // ISO 8601 timestamp when participant left the meeting
+  leave_time?: string;
+  // Duration in seconds that the participant was in the meeting
+  duration?: number;
+  // Indicates if participant connected via failover
+  failover?: boolean;
+  // Current status of the participant in the meeting
+  status?: 'in_meeting' | 'in_waiting_room';
+  // Indicates if the participant is an internal Zoom user
+  internal_user?: boolean;
+};
+
+export default ZoomPastMeetingParticipant;

package/src/types/ZoomRecordingInAccount.ts

@@ -0,0 +1,38 @@
+import ZoomRecordingFile from './ZoomRecordingFile';
+
+/**
+ * A single recording in an account
+ * @author Gabe Abrams
+ */
+type ZoomRecordingInAccount = {
+  // The meeting's scheduled duration
+  duration: number,
+  // The meeting host's user ID
+  host_id: string,
+  // The meeting's ID
+  id: number,
+  // The total number of recordings retrieved from the account
+  recording_count: number,
+  // The information about the recording files
+  recording_files: ZoomRecordingFile[],
+  // The date and time when the meeting started
+  start_time: string,
+  // The meeting's topic
+  topic: string,
+  // The total size of the recording file, in bytes
+  total_size: number,
+  // The recording's associated type of meeting or webinar
+  type: number,
+  // The meeting's universally unique ID
+  uuid: string,
+  // Recording zone used in the Zoom Node Platform
+  rc_zone?: string,
+  // The unique ID for the hybrid recorder or recording connector
+  instance_id?: string,
+  // The name of the Zoom Node Service
+  service_name?: string,
+  // NFS address
+  external_storage_addr?: string,
+};
+
+export default ZoomRecordingInAccount;