@hasna/connectors 0.0.1

package/connectors/connect-zoom/src/api/client.ts

@@ -0,0 +1,177 @@
+import type { ZoomConfig, ZoomTokenResponse } from '../types';
+import { ZoomApiError } from '../types';
+import {
+  getAccessToken,
+  setAccessToken,
+  getTokenExpiry,
+  setTokenExpiry,
+} from '../utils/config';
+
+const ZOOM_API_BASE = 'https://api.zoom.us/v2';
+const ZOOM_OAUTH_URL = 'https://zoom.us/oauth/token';
+
+export interface ZoomRequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Zoom API Client with Server-to-Server OAuth
+ */
+export class ZoomClient {
+  private readonly accountId: string;
+  private readonly clientId: string;
+  private readonly clientSecret: string;
+  private accessToken: string | undefined;
+  private tokenExpiry: number | undefined;
+
+  constructor(config: ZoomConfig) {
+    if (!config.accountId) {
+      throw new Error('Zoom Account ID is required');
+    }
+    if (!config.clientId) {
+      throw new Error('Zoom Client ID is required');
+    }
+    if (!config.clientSecret) {
+      throw new Error('Zoom Client Secret is required');
+    }
+    this.accountId = config.accountId;
+    this.clientId = config.clientId;
+    this.clientSecret = config.clientSecret;
+
+    // Load cached token
+    this.accessToken = getAccessToken();
+    this.tokenExpiry = getTokenExpiry();
+  }
+
+  /**
+   * Get a valid access token, refreshing if necessary
+   */
+  private async getValidToken(): Promise<string> {
+    // Check if we have a valid cached token (with 5 min buffer)
+    if (this.accessToken && this.tokenExpiry && Date.now() < this.tokenExpiry - 300000) {
+      return this.accessToken;
+    }
+
+    // Get new token using Server-to-Server OAuth
+    const credentials = Buffer.from(`${this.clientId}:${this.clientSecret}`).toString('base64');
+
+    const response = await fetch(ZOOM_OAUTH_URL, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Basic ${credentials}`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: `grant_type=account_credentials&account_id=${encodeURIComponent(this.accountId)}`,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      let errorMessage = `OAuth Error: ${response.status} ${response.statusText}`;
+      try {
+        const errorJson = JSON.parse(errorText);
+        errorMessage = errorJson.reason || errorJson.error_description || errorMessage;
+      } catch {
+        // Use default message
+      }
+      throw new ZoomApiError(errorMessage, response.status);
+    }
+
+    const tokenData = await response.json() as ZoomTokenResponse;
+    this.accessToken = tokenData.access_token;
+    this.tokenExpiry = Date.now() + tokenData.expires_in * 1000;
+
+    // Cache the token
+    setAccessToken(this.accessToken);
+    setTokenExpiry(this.tokenExpiry);
+
+    return this.accessToken;
+  }
+
+  /**
+   * Make a request to the Zoom API
+   */
+  async request<T>(path: string, options: ZoomRequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+
+    const token = await this.getValidToken();
+
+    const url = new URL(`${ZOOM_API_BASE}${path}`);
+
+    // Add query params
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    const requestHeaders: Record<string, string> = {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      ...headers,
+    };
+
+    const response = await fetch(url.toString(), {
+      method,
+      headers: requestHeaders,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    // Handle no content responses
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    const contentType = response.headers.get('content-type') || '';
+    let data: unknown;
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    if (!response.ok) {
+      let errorMessage = `Zoom API Error: ${response.status} ${response.statusText}`;
+      let errorCode: number | undefined;
+
+      if (typeof data === 'object' && data !== null) {
+        const errData = data as Record<string, unknown>;
+        errorCode = errData.code as number;
+        errorMessage = (errData.message || errorMessage) as string;
+      }
+
+      throw new ZoomApiError(errorMessage, response.status, errorCode);
+    }
+
+    return data as T;
+  }
+
+  /**
+   * Get the account ID
+   */
+  getAccountId(): string {
+    return this.accountId;
+  }
+
+  /**
+   * Get a preview of the client ID (for display/debugging)
+   */
+  getClientIdPreview(): string {
+    if (this.clientId.length > 8) {
+      return `${this.clientId.substring(0, 4)}...${this.clientId.substring(this.clientId.length - 4)}`;
+    }
+    return '***';
+  }
+}

package/connectors/connect-zoom/src/api/index.ts

@@ -0,0 +1,81 @@
+import type { ZoomConfig } from '../types';
+import { ZoomClient } from './client';
+import { UsersApi } from './users';
+import { MeetingsApi } from './meetings';
+import { WebinarsApi } from './webinars';
+import { RecordingsApi } from './recordings';
+import { ReportsApi } from './reports';
+
+/**
+ * Main Zoom Connector class
+ * Provides access to Users, Meetings, Webinars, Recordings, and Reports APIs
+ */
+export class Zoom {
+  private readonly client: ZoomClient;
+
+  // Service APIs
+  public readonly users: UsersApi;
+  public readonly meetings: MeetingsApi;
+  public readonly webinars: WebinarsApi;
+  public readonly recordings: RecordingsApi;
+  public readonly reports: ReportsApi;
+
+  constructor(config: ZoomConfig) {
+    this.client = new ZoomClient(config);
+    this.users = new UsersApi(this.client);
+    this.meetings = new MeetingsApi(this.client);
+    this.webinars = new WebinarsApi(this.client);
+    this.recordings = new RecordingsApi(this.client);
+    this.reports = new ReportsApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for ZOOM_ACCOUNT_ID, ZOOM_CLIENT_ID, ZOOM_CLIENT_SECRET
+   */
+  static fromEnv(): Zoom {
+    const accountId = process.env.ZOOM_ACCOUNT_ID;
+    const clientId = process.env.ZOOM_CLIENT_ID;
+    const clientSecret = process.env.ZOOM_CLIENT_SECRET;
+
+    if (!accountId) {
+      throw new Error('ZOOM_ACCOUNT_ID environment variable is required');
+    }
+    if (!clientId) {
+      throw new Error('ZOOM_CLIENT_ID environment variable is required');
+    }
+    if (!clientSecret) {
+      throw new Error('ZOOM_CLIENT_SECRET environment variable is required');
+    }
+
+    return new Zoom({ accountId, clientId, clientSecret });
+  }
+
+  /**
+   * Get a preview of the client ID (for debugging)
+   */
+  getClientIdPreview(): string {
+    return this.client.getClientIdPreview();
+  }
+
+  /**
+   * Get the account ID
+   */
+  getAccountId(): string {
+    return this.client.getAccountId();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): ZoomClient {
+    return this.client;
+  }
+}
+
+export { ZoomClient } from './client';
+export { UsersApi } from './users';
+export { MeetingsApi } from './meetings';
+export { WebinarsApi } from './webinars';
+export { RecordingsApi } from './recordings';
+export { ReportsApi } from './reports';

package/connectors/connect-zoom/src/api/meetings.ts

@@ -0,0 +1,126 @@
+import type { ZoomClient } from './client';
+import type {
+  ZoomMeeting,
+  ZoomMeetingListResponse,
+  ZoomMeetingDetail,
+  ZoomMeetingCreateRequest,
+} from '../types';
+
+/**
+ * Zoom Meetings API
+ */
+export class MeetingsApi {
+  private readonly client: ZoomClient;
+
+  constructor(client: ZoomClient) {
+    this.client = client;
+  }
+
+  /**
+   * List meetings for a user
+   */
+  async listMeetings(
+    userId: string = 'me',
+    options: {
+      type?: 'scheduled' | 'live' | 'upcoming' | 'upcoming_meetings' | 'previous_meetings';
+      pageSize?: number;
+      pageNumber?: number;
+      nextPageToken?: string;
+    } = {}
+  ): Promise<ZoomMeetingListResponse> {
+    return this.client.request<ZoomMeetingListResponse>(`/users/${encodeURIComponent(userId)}/meetings`, {
+      params: {
+        type: options.type,
+        page_size: options.pageSize,
+        page_number: options.pageNumber,
+        next_page_token: options.nextPageToken,
+      },
+    });
+  }
+
+  /**
+   * Get meeting details
+   */
+  async getMeeting(meetingId: string | number): Promise<ZoomMeetingDetail> {
+    return this.client.request<ZoomMeetingDetail>(`/meetings/${meetingId}`);
+  }
+
+  /**
+   * Create a meeting
+   */
+  async createMeeting(
+    userId: string = 'me',
+    meeting: ZoomMeetingCreateRequest
+  ): Promise<ZoomMeetingDetail> {
+    // Default to scheduled meeting if not specified
+    const meetingData = {
+      ...meeting,
+      type: meeting.type ?? 2, // 2 = Scheduled meeting
+    };
+
+    return this.client.request<ZoomMeetingDetail>(`/users/${encodeURIComponent(userId)}/meetings`, {
+      method: 'POST',
+      body: meetingData,
+    });
+  }
+
+  /**
+   * Update a meeting
+   */
+  async updateMeeting(
+    meetingId: string | number,
+    updates: Partial<ZoomMeetingCreateRequest>
+  ): Promise<void> {
+    await this.client.request(`/meetings/${meetingId}`, {
+      method: 'PATCH',
+      body: updates,
+    });
+  }
+
+  /**
+   * Delete a meeting
+   */
+  async deleteMeeting(
+    meetingId: string | number,
+    options: {
+      occurrenceId?: string;
+      scheduleForReminder?: boolean;
+      cancelMeetingReminder?: boolean;
+    } = {}
+  ): Promise<void> {
+    await this.client.request(`/meetings/${meetingId}`, {
+      method: 'DELETE',
+      params: {
+        occurrence_id: options.occurrenceId,
+        schedule_for_reminder: options.scheduleForReminder,
+        cancel_meeting_reminder: options.cancelMeetingReminder,
+      },
+    });
+  }
+
+  /**
+   * End a meeting
+   */
+  async endMeeting(meetingId: string | number): Promise<void> {
+    await this.client.request(`/meetings/${meetingId}/status`, {
+      method: 'PUT',
+      body: { action: 'end' },
+    });
+  }
+
+  /**
+   * List past meeting instances
+   */
+  async listPastMeetingInstances(meetingId: string | number): Promise<{ meetings: ZoomMeeting[] }> {
+    return this.client.request<{ meetings: ZoomMeeting[] }>(`/past_meetings/${meetingId}/instances`);
+  }
+
+  /**
+   * Get past meeting details
+   */
+  async getPastMeetingDetails(meetingUuid: string): Promise<ZoomMeetingDetail> {
+    // Double URL encode the UUID as per Zoom API requirements
+    const encodedUuid = encodeURIComponent(encodeURIComponent(meetingUuid));
+    return this.client.request<ZoomMeetingDetail>(`/past_meetings/${encodedUuid}`);
+  }
+}

package/connectors/connect-zoom/src/api/recordings.ts

@@ -0,0 +1,129 @@
+import type { ZoomClient } from './client';
+import type {
+  ZoomRecording,
+  ZoomRecordingListResponse,
+} from '../types';
+
+/**
+ * Zoom Cloud Recordings API
+ */
+export class RecordingsApi {
+  private readonly client: ZoomClient;
+
+  constructor(client: ZoomClient) {
+    this.client = client;
+  }
+
+  /**
+   * List recordings for a user
+   */
+  async listRecordings(
+    userId: string = 'me',
+    options: {
+      from?: string; // YYYY-MM-DD
+      to?: string; // YYYY-MM-DD
+      pageSize?: number;
+      nextPageToken?: string;
+      mc?: string; // Meeting center
+      trash?: boolean;
+      trashType?: 'meeting_recordings' | 'recording_file';
+    } = {}
+  ): Promise<ZoomRecordingListResponse> {
+    return this.client.request<ZoomRecordingListResponse>(`/users/${encodeURIComponent(userId)}/recordings`, {
+      params: {
+        from: options.from,
+        to: options.to,
+        page_size: options.pageSize,
+        next_page_token: options.nextPageToken,
+        mc: options.mc,
+        trash: options.trash,
+        trash_type: options.trashType,
+      },
+    });
+  }
+
+  /**
+   * Get recording details for a meeting
+   */
+  async getRecording(meetingId: string | number): Promise<ZoomRecording> {
+    return this.client.request<ZoomRecording>(`/meetings/${meetingId}/recordings`);
+  }
+
+  /**
+   * Delete all recordings for a meeting
+   */
+  async deleteRecording(
+    meetingId: string | number,
+    options: {
+      action?: 'trash' | 'delete';
+    } = {}
+  ): Promise<void> {
+    await this.client.request(`/meetings/${meetingId}/recordings`, {
+      method: 'DELETE',
+      params: {
+        action: options.action || 'trash',
+      },
+    });
+  }
+
+  /**
+   * Delete a specific recording file
+   */
+  async deleteRecordingFile(
+    meetingId: string | number,
+    recordingId: string,
+    options: {
+      action?: 'trash' | 'delete';
+    } = {}
+  ): Promise<void> {
+    await this.client.request(`/meetings/${meetingId}/recordings/${recordingId}`, {
+      method: 'DELETE',
+      params: {
+        action: options.action || 'trash',
+      },
+    });
+  }
+
+  /**
+   * Recover recordings from trash
+   */
+  async recoverRecordings(meetingUuid: string): Promise<void> {
+    // Double URL encode the UUID as per Zoom API requirements
+    const encodedUuid = encodeURIComponent(encodeURIComponent(meetingUuid));
+    await this.client.request(`/meetings/${encodedUuid}/recordings/status`, {
+      method: 'PUT',
+      body: { action: 'recover' },
+    });
+  }
+
+  /**
+   * Get recording settings
+   */
+  async getRecordingSettings(meetingId: string | number): Promise<Record<string, unknown>> {
+    return this.client.request<Record<string, unknown>>(`/meetings/${meetingId}/recordings/settings`);
+  }
+
+  /**
+   * Update recording settings
+   */
+  async updateRecordingSettings(
+    meetingId: string | number,
+    settings: {
+      share_recording?: 'publicly' | 'internally' | 'none';
+      recording_authentication?: boolean;
+      authentication_option?: string;
+      authentication_domains?: string;
+      viewer_download?: boolean;
+      password?: string;
+      on_demand?: boolean;
+      approval_type?: number;
+      send_email_to_host?: boolean;
+      show_social_share_buttons?: boolean;
+    }
+  ): Promise<void> {
+    await this.client.request(`/meetings/${meetingId}/recordings/settings`, {
+      method: 'PATCH',
+      body: settings,
+    });
+  }
+}

package/connectors/connect-zoom/src/api/reports.ts

@@ -0,0 +1,178 @@
+import type { ZoomClient } from './client';
+import type {
+  ZoomMeetingReport,
+  ZoomReportMeetingsResponse,
+  ZoomParticipantReport,
+  ZoomReportParticipantsResponse,
+} from '../types';
+
+/**
+ * Zoom Reports API
+ */
+export class ReportsApi {
+  private readonly client: ZoomClient;
+
+  constructor(client: ZoomClient) {
+    this.client = client;
+  }
+
+  /**
+   * Get meeting reports for a user
+   */
+  async getMeetingReports(
+    userId: string = 'me',
+    options: {
+      from: string; // YYYY-MM-DD (required)
+      to: string; // YYYY-MM-DD (required)
+      pageSize?: number;
+      nextPageToken?: string;
+      type?: 'past' | 'pastOne' | 'live';
+    }
+  ): Promise<ZoomReportMeetingsResponse> {
+    return this.client.request<ZoomReportMeetingsResponse>(`/report/users/${encodeURIComponent(userId)}/meetings`, {
+      params: {
+        from: options.from,
+        to: options.to,
+        page_size: options.pageSize,
+        next_page_token: options.nextPageToken,
+        type: options.type,
+      },
+    });
+  }
+
+  /**
+   * Get detailed report for a specific meeting
+   */
+  async getMeetingDetail(meetingId: string | number): Promise<ZoomMeetingReport> {
+    return this.client.request<ZoomMeetingReport>(`/report/meetings/${meetingId}`);
+  }
+
+  /**
+   * Get meeting participants report
+   */
+  async getMeetingParticipants(
+    meetingId: string | number,
+    options: {
+      pageSize?: number;
+      nextPageToken?: string;
+      includeFields?: string;
+    } = {}
+  ): Promise<ZoomReportParticipantsResponse> {
+    return this.client.request<ZoomReportParticipantsResponse>(`/report/meetings/${meetingId}/participants`, {
+      params: {
+        page_size: options.pageSize,
+        next_page_token: options.nextPageToken,
+        include_fields: options.includeFields,
+      },
+    });
+  }
+
+  /**
+   * Get webinar reports for a user
+   */
+  async getWebinarReports(
+    userId: string = 'me',
+    options: {
+      from: string; // YYYY-MM-DD (required)
+      to: string; // YYYY-MM-DD (required)
+      pageSize?: number;
+      nextPageToken?: string;
+      type?: 'past' | 'live';
+    }
+  ): Promise<ZoomReportMeetingsResponse> {
+    return this.client.request<ZoomReportMeetingsResponse>(`/report/users/${encodeURIComponent(userId)}/webinars`, {
+      params: {
+        from: options.from,
+        to: options.to,
+        page_size: options.pageSize,
+        next_page_token: options.nextPageToken,
+        type: options.type,
+      },
+    });
+  }
+
+  /**
+   * Get webinar detail report
+   */
+  async getWebinarDetail(webinarId: string | number): Promise<ZoomMeetingReport> {
+    return this.client.request<ZoomMeetingReport>(`/report/webinars/${webinarId}`);
+  }
+
+  /**
+   * Get webinar participants report
+   */
+  async getWebinarParticipants(
+    webinarId: string | number,
+    options: {
+      pageSize?: number;
+      nextPageToken?: string;
+      includeFields?: string;
+    } = {}
+  ): Promise<ZoomReportParticipantsResponse> {
+    return this.client.request<ZoomReportParticipantsResponse>(`/report/webinars/${webinarId}/participants`, {
+      params: {
+        page_size: options.pageSize,
+        next_page_token: options.nextPageToken,
+        include_fields: options.includeFields,
+      },
+    });
+  }
+
+  /**
+   * Get daily usage report
+   */
+  async getDailyUsageReport(options: {
+    year: number;
+    month: number;
+  }): Promise<{
+    year: number;
+    month: number;
+    dates: Array<{
+      date: string;
+      new_users: number;
+      meetings: number;
+      participants: number;
+      meeting_minutes: number;
+    }>;
+  }> {
+    return this.client.request(`/report/daily`, {
+      params: {
+        year: options.year,
+        month: options.month,
+      },
+    });
+  }
+
+  /**
+   * Get account operation logs
+   */
+  async getOperationLogs(options: {
+    from: string; // YYYY-MM-DD
+    to: string; // YYYY-MM-DD
+    pageSize?: number;
+    nextPageToken?: string;
+    categoryType?: string;
+  }): Promise<{
+    from: string;
+    to: string;
+    page_size: number;
+    next_page_token?: string;
+    operation_logs: Array<{
+      time: string;
+      operator: string;
+      category_type: string;
+      action: string;
+      operation_detail: string;
+    }>;
+  }> {
+    return this.client.request(`/report/operationlogs`, {
+      params: {
+        from: options.from,
+        to: options.to,
+        page_size: options.pageSize,
+        next_page_token: options.nextPageToken,
+        category_type: options.categoryType,
+      },
+    });
+  }
+}