@memberjunction/actions-bizapps-social 2.112.0 → 2.113.1

package/src/providers/instagram/instagram-base.action.ts

@@ -1,6 +1,6 @@
 import { RegisterClass } from '@memberjunction/global';
 import { BaseSocialMediaAction, MediaFile } from '../../base/base-social.action';
-import { UserInfo, LogStatus, LogError } from '@memberjunction/global';
+import { UserInfo, LogStatus, LogError } from '@memberjunction/core';
 import axios, { AxiosInstance, AxiosError } from 'axios';
 import { BaseAction } from '@memberjunction/actions';
 
@@ -11,396 +11,421 @@ import { BaseAction } from '@memberjunction/actions';
  */
 @RegisterClass(BaseAction, 'InstagramBaseAction')
 export abstract class InstagramBaseAction extends BaseSocialMediaAction {
-  protected get platformName(): string {
-    return 'Instagram';
-  }
-
-  protected get apiBaseUrl(): string {
-    return 'https://graph.facebook.com/v18.0';
-  }
-
-  /**
-   * Instagram Business Account ID (stored in CustomAttribute1)
-   */
-  protected get instagramBusinessAccountId(): string {
-    return this.getCustomAttribute(1) || '';
-  }
-
-  /**
-   * Facebook Page ID (stored in CustomAttribute2) - required for Instagram Business API
-   */
-  protected get facebookPageId(): string {
-    return this.getCustomAttribute(2) || '';
-  }
-
-  /**
-   * Axios instance for API calls
-   */
-  private _axiosInstance: AxiosInstance | null = null;
-
-  /**
-   * Get or create axios instance with authentication
-   */
-  protected get axios(): AxiosInstance {
-    if (!this._axiosInstance) {
-      this._axiosInstance = axios.create({
-        baseURL: this.apiBaseUrl,
-        headers: this.buildHeaders(),
-      });
-
-      // Add response interceptor for error handling
-      this._axiosInstance.interceptors.response.use(
-        (response) => response,
-        async (error) => {
-          if (error.response?.status === 401 && this.isAuthError(error)) {
-            LogStatus('Instagram token appears invalid, attempting refresh...');
-            await this.refreshAccessToken();
-
-            // Retry the request with new token
-            error.config.headers.Authorization = `Bearer ${this.getAccessToken()}`;
-            return axios.request(error.config);
-          }
-          throw error;
-        }
-      );
+    protected get platformName(): string {
+        return 'Instagram';
     }
-    return this._axiosInstance;
-  }
-
-  /**
-   * Refresh the Instagram/Facebook access token
-   */
-  protected async refreshAccessToken(): Promise<void> {
-    try {
-      // Instagram uses Facebook's OAuth system
-      // Long-lived tokens need to be exchanged periodically
-      const currentToken = this.getAccessToken();
-      if (!currentToken) {
-        throw new Error('No access token available to refresh');
-      }
-
-      // Exchange for a new long-lived token
-      const response = await axios.get(`${this.apiBaseUrl}/oauth/access_token`, {
-        params: {
-          grant_type: 'fb_exchange_token',
-          client_id: this.getCustomAttribute(3), // App ID stored in CustomAttribute3
-          client_secret: this.getCustomAttribute(4), // App Secret stored in CustomAttribute4
-          fb_exchange_token: currentToken,
-        },
-      });
-
-      if (response.data.access_token) {
-        await this.updateStoredTokens(
-          response.data.access_token,
-          undefined, // Instagram doesn't use refresh tokens
-          response.data.expires_in || 5184000 // Default to 60 days
-        );
 
-        // Reset axios instance to use new token
-        this._axiosInstance = null;
-      }
-    } catch (error) {
-      LogError('Failed to refresh Instagram access token', error);
-      throw new Error('Failed to refresh Instagram access token');
-    }
-  }
-
-  /**
-   * Make an Instagram Graph API request
-   */
-  protected async makeInstagramRequest<T = any>(
-    endpoint: string,
-    method: 'GET' | 'POST' | 'DELETE' = 'GET',
-    data?: any,
-    params?: any
-  ): Promise<T> {
-    try {
-      this.logApiRequest(method, `${this.apiBaseUrl}/${endpoint}`, data || params);
-
-      const response = await this.axios.request<T>({
-        url: endpoint,
-        method,
-        data,
-        params,
-      });
-
-      this.logApiResponse(response.data);
-      return response.data;
-    } catch (error) {
-      if (axios.isAxiosError(error)) {
-        this.handleInstagramError(error);
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * Handle Instagram-specific errors
-   */
-  protected handleInstagramError(error: AxiosError): void {
-    const response = error.response;
-    if (!response) {
-      throw new Error('Network error occurred while calling Instagram API');
+    protected get apiBaseUrl(): string {
+        return 'https://graph.facebook.com/v18.0';
     }
 
-    const errorData = response.data as any;
-    const errorMessage = errorData?.error?.message || 'Unknown Instagram API error';
-    const errorCode = errorData?.error?.code;
-    const errorSubcode = errorData?.error?.error_subcode;
+    /**
+     * Instagram Business Account ID (stored in CustomAttribute1)
+     */
+    protected get instagramBusinessAccountId(): string {
+        return this.getCustomAttribute(1) || '';
+    }
 
-    // Check for rate limiting
-    if (errorCode === 32 || errorCode === 4 || response.status === 429) {
-      const retryAfter = response.headers['x-app-usage'] ? this.parseAppUsage(response.headers['x-app-usage']) : 3600; // Default to 1 hour
+    /**
+     * Facebook Page ID (stored in CustomAttribute2) - required for Instagram Business API
+     */
+    protected get facebookPageId(): string {
+        return this.getCustomAttribute(2) || '';
+    }
 
-      throw {
-        code: 'RATE_LIMIT',
-        message: 'Instagram API rate limit exceeded',
-        retryAfter,
-      };
+    /**
+     * Axios instance for API calls
+     */
+    private _axiosInstance: AxiosInstance | null = null;
+
+    /**
+     * Get or create axios instance with authentication
+     */
+    protected get axios(): AxiosInstance {
+        if (!this._axiosInstance) {
+            this._axiosInstance = axios.create({
+                baseURL: this.apiBaseUrl,
+                headers: this.buildHeaders()
+            });
+
+            // Add response interceptor for error handling
+            this._axiosInstance.interceptors.response.use(
+                response => response,
+                async error => {
+                    if (error.response?.status === 401 && this.isAuthError(error)) {
+                        LogStatus('Instagram token appears invalid, attempting refresh...');
+                        await this.refreshAccessToken();
+                        
+                        // Retry the request with new token
+                        error.config.headers.Authorization = `Bearer ${this.getAccessToken()}`;
+                        return axios.request(error.config);
+                    }
+                    throw error;
+                }
+            );
+        }
+        return this._axiosInstance;
     }
 
-    // Check for permission errors
-    if (errorCode === 10 || errorSubcode === 460) {
-      throw {
-        code: 'INSUFFICIENT_PERMISSIONS',
-        message: 'Insufficient permissions for this Instagram operation',
-      };
+    /**
+     * Refresh the Instagram/Facebook access token
+     */
+    protected async refreshAccessToken(): Promise<void> {
+        try {
+            // Instagram uses Facebook's OAuth system
+            // Long-lived tokens need to be exchanged periodically
+            const currentToken = this.getAccessToken();
+            if (!currentToken) {
+                throw new Error('No access token available to refresh');
+            }
+
+            // Exchange for a new long-lived token
+            const response = await axios.get(`${this.apiBaseUrl}/oauth/access_token`, {
+                params: {
+                    grant_type: 'fb_exchange_token',
+                    client_id: this.getCustomAttribute(3), // App ID stored in CustomAttribute3
+                    client_secret: this.getCustomAttribute(4), // App Secret stored in CustomAttribute4
+                    fb_exchange_token: currentToken
+                }
+            });
+
+            if (response.data.access_token) {
+                await this.updateStoredTokens(
+                    response.data.access_token,
+                    undefined, // Instagram doesn't use refresh tokens
+                    response.data.expires_in || 5184000 // Default to 60 days
+                );
+
+                // Reset axios instance to use new token
+                this._axiosInstance = null;
+            }
+        } catch (error) {
+            LogError('Failed to refresh Instagram access token', error);
+            throw new Error('Failed to refresh Instagram access token');
+        }
     }
 
-    // Media errors
-    if (errorCode === 100 && errorMessage.toLowerCase().includes('media')) {
-      throw {
-        code: 'INVALID_MEDIA',
-        message: errorMessage,
-      };
+    /**
+     * Make an Instagram Graph API request
+     */
+    protected async makeInstagramRequest<T = any>(
+        endpoint: string,
+        method: 'GET' | 'POST' | 'DELETE' = 'GET',
+        data?: any,
+        params?: any
+    ): Promise<T> {
+        try {
+            this.logApiRequest(method, `${this.apiBaseUrl}/${endpoint}`, data || params);
+
+            const response = await this.axios.request<T>({
+                url: endpoint,
+                method,
+                data,
+                params
+            });
+
+            this.logApiResponse(response.data);
+            return response.data;
+        } catch (error) {
+            if (axios.isAxiosError(error)) {
+                this.handleInstagramError(error);
+            }
+            throw error;
+        }
     }
 
-    // Post not found
-    if (errorCode === 100 && errorSubcode === 33) {
-      throw {
-        code: 'POST_NOT_FOUND',
-        message: 'Instagram post not found',
-      };
+    /**
+     * Handle Instagram-specific errors
+     */
+    protected handleInstagramError(error: AxiosError): void {
+        const response = error.response;
+        if (!response) {
+            throw new Error('Network error occurred while calling Instagram API');
+        }
+
+        const errorData = response.data as any;
+        const errorMessage = errorData?.error?.message || 'Unknown Instagram API error';
+        const errorCode = errorData?.error?.code;
+        const errorSubcode = errorData?.error?.error_subcode;
+
+        // Check for rate limiting
+        if (errorCode === 32 || errorCode === 4 || response.status === 429) {
+            const retryAfter = response.headers['x-app-usage'] 
+                ? this.parseAppUsage(response.headers['x-app-usage']) 
+                : 3600; // Default to 1 hour
+            
+            throw {
+                code: 'RATE_LIMIT',
+                message: 'Instagram API rate limit exceeded',
+                retryAfter
+            };
+        }
+
+        // Check for permission errors
+        if (errorCode === 10 || errorSubcode === 460) {
+            throw {
+                code: 'INSUFFICIENT_PERMISSIONS',
+                message: 'Insufficient permissions for this Instagram operation'
+            };
+        }
+
+        // Media errors
+        if (errorCode === 100 && errorMessage.toLowerCase().includes('media')) {
+            throw {
+                code: 'INVALID_MEDIA',
+                message: errorMessage
+            };
+        }
+
+        // Post not found
+        if (errorCode === 100 && errorSubcode === 33) {
+            throw {
+                code: 'POST_NOT_FOUND',
+                message: 'Instagram post not found'
+            };
+        }
+
+        throw {
+            code: 'PLATFORM_ERROR',
+            message: errorMessage,
+            details: errorData
+        };
     }
 
-    throw {
-      code: 'PLATFORM_ERROR',
-      message: errorMessage,
-      details: errorData,
-    };
-  }
-
-  /**
-   * Parse Facebook's app usage header to determine rate limit status
-   */
-  private parseAppUsage(appUsage: string): number {
-    try {
-      const usage = JSON.parse(appUsage);
-      const callCount = usage.call_count || 0;
-      const totalTime = usage.total_time || 0;
-      const totalCputime = usage.total_cputime || 0;
-
-      // If any metric is above 90%, implement backoff
-      if (callCount > 90 || totalTime > 90 || totalCputime > 90) {
-        return 3600; // Wait 1 hour
-      }
-      return 0;
-    } catch {
-      return 0;
+    /**
+     * Parse Facebook's app usage header to determine rate limit status
+     */
+    private parseAppUsage(appUsage: string): number {
+        try {
+            const usage = JSON.parse(appUsage);
+            const callCount = usage.call_count || 0;
+            const totalTime = usage.total_time || 0;
+            const totalCputime = usage.total_cputime || 0;
+
+            // If any metric is above 90%, implement backoff
+            if (callCount > 90 || totalTime > 90 || totalCputime > 90) {
+                return 3600; // Wait 1 hour
+            }
+            return 0;
+        } catch {
+            return 0;
+        }
     }
-  }
-
-  /**
-   * Upload media to Instagram (returns container ID)
-   */
-  protected async uploadSingleMedia(file: MediaFile): Promise<string> {
-    try {
-      // For Instagram, media must be hosted at a public URL
-      // This is a simplified version - in production, you'd upload to a CDN first
-      const mediaUrl = await this.uploadMediaToCDN(file);
-
-      let containerParams: any = {
-        access_token: this.getAccessToken(),
-      };
-
-      // Determine media type and set appropriate parameters
-      if (file.mimeType.startsWith('image/')) {
-        containerParams.image_url = mediaUrl;
-
-        // Check if it's a carousel
-        if (file.filename.includes('carousel')) {
-          containerParams.is_carousel_item = true;
+
+    /**
+     * Upload media to Instagram (returns container ID)
+     */
+    protected async uploadSingleMedia(file: MediaFile): Promise<string> {
+        try {
+            // For Instagram, media must be hosted at a public URL
+            // This is a simplified version - in production, you'd upload to a CDN first
+            const mediaUrl = await this.uploadMediaToCDN(file);
+
+            let containerParams: any = {
+                access_token: this.getAccessToken()
+            };
+
+            // Determine media type and set appropriate parameters
+            if (file.mimeType.startsWith('image/')) {
+                containerParams.image_url = mediaUrl;
+                
+                // Check if it's a carousel
+                if (file.filename.includes('carousel')) {
+                    containerParams.is_carousel_item = true;
+                }
+            } else if (file.mimeType.startsWith('video/')) {
+                containerParams.video_url = mediaUrl;
+                containerParams.media_type = 'REELS'; // or 'VIDEO' for feed videos
+            }
+
+            // Add caption if provided in metadata
+            const metadata = (file as any).metadata;
+            if (metadata?.caption) {
+                containerParams.caption = metadata.caption;
+            }
+
+            // Create media container
+            const response = await this.makeInstagramRequest<{ id: string }>(
+                `${this.instagramBusinessAccountId}/media`,
+                'POST',
+                containerParams
+            );
+
+            return response.id;
+        } catch (error) {
+            LogError('Failed to upload media to Instagram', error);
+            throw error;
         }
-      } else if (file.mimeType.startsWith('video/')) {
-        containerParams.video_url = mediaUrl;
-        containerParams.media_type = 'REELS'; // or 'VIDEO' for feed videos
-      }
-
-      // Add caption if provided in metadata
-      const metadata = (file as any).metadata;
-      if (metadata?.caption) {
-        containerParams.caption = metadata.caption;
-      }
-
-      // Create media container
-      const response = await this.makeInstagramRequest<{ id: string }>(`${this.instagramBusinessAccountId}/media`, 'POST', containerParams);
-
-      return response.id;
-    } catch (error) {
-      LogError('Failed to upload media to Instagram', error);
-      throw error;
     }
-  }
-
-  /**
-   * Upload media to a CDN (placeholder - implement based on your CDN)
-   */
-  private async uploadMediaToCDN(file: MediaFile): Promise<string> {
-    // In a real implementation, this would upload to S3, Cloudinary, etc.
-    // For now, throw an error indicating this needs implementation
-    throw new Error('Media CDN upload not implemented. Instagram requires media to be hosted at a public URL.');
-  }
-
-  /**
-   * Publish a media container
-   */
-  protected async publishMediaContainer(containerId: string): Promise<string> {
-    const response = await this.makeInstagramRequest<{ id: string }>(`${this.instagramBusinessAccountId}/media_publish`, 'POST', {
-      creation_id: containerId,
-      access_token: this.getAccessToken(),
-    });
-
-    return response.id;
-  }
-
-  /**
-   * Get insights for a media object or account
-   */
-  protected async getInsights(objectId: string, metrics: string[], period?: 'lifetime' | 'day' | 'week' | 'days_28'): Promise<any> {
-    const params: any = {
-      metric: metrics.join(','),
-      access_token: this.getAccessToken(),
-    };
-
-    if (period) {
-      params.period = period;
+
+    /**
+     * Upload media to a CDN (placeholder - implement based on your CDN)
+     */
+    private async uploadMediaToCDN(file: MediaFile): Promise<string> {
+        // In a real implementation, this would upload to S3, Cloudinary, etc.
+        // For now, throw an error indicating this needs implementation
+        throw new Error('Media CDN upload not implemented. Instagram requires media to be hosted at a public URL.');
+    }
+
+    /**
+     * Publish a media container
+     */
+    protected async publishMediaContainer(containerId: string): Promise<string> {
+        const response = await this.makeInstagramRequest<{ id: string }>(
+            `${this.instagramBusinessAccountId}/media_publish`,
+            'POST',
+            {
+                creation_id: containerId,
+                access_token: this.getAccessToken()
+            }
+        );
+
+        return response.id;
     }
 
-    const response = await this.makeInstagramRequest<{ data: any[] }>(`${objectId}/insights`, 'GET', null, params);
-
-    return response.data;
-  }
-
-  /**
-   * Search for posts (limited to business account's own posts)
-   */
-  protected async searchPosts(params: any): Promise<any[]> {
-    // Instagram doesn't have a general search API
-    // We can only search within the business account's own posts
-    const fields = 'id,caption,media_type,media_url,permalink,timestamp,like_count,comments_count';
-
-    let endpoint = `${this.instagramBusinessAccountId}/media`;
-    const queryParams: any = {
-      fields,
-      access_token: this.getAccessToken(),
-      limit: params.limit || 25,
-    };
-
-    // Add date filtering if provided
-    if (params.startDate) {
-      queryParams.since = Math.floor(new Date(params.startDate).getTime() / 1000);
+    /**
+     * Get insights for a media object or account
+     */
+    protected async getInsights(
+        objectId: string,
+        metrics: string[],
+        period?: 'lifetime' | 'day' | 'week' | 'days_28'
+    ): Promise<any> {
+        const params: any = {
+            metric: metrics.join(','),
+            access_token: this.getAccessToken()
+        };
+
+        if (period) {
+            params.period = period;
+        }
+
+        const response = await this.makeInstagramRequest<{ data: any[] }>(
+            `${objectId}/insights`,
+            'GET',
+            null,
+            params
+        );
+
+        return response.data;
     }
-    if (params.endDate) {
-      queryParams.until = Math.floor(new Date(params.endDate).getTime() / 1000);
+
+    /**
+     * Search for posts (limited to business account's own posts)
+     */
+    protected async searchPosts(params: any): Promise<any[]> {
+        // Instagram doesn't have a general search API
+        // We can only search within the business account's own posts
+        const fields = 'id,caption,media_type,media_url,permalink,timestamp,like_count,comments_count';
+        
+        let endpoint = `${this.instagramBusinessAccountId}/media`;
+        const queryParams: any = {
+            fields,
+            access_token: this.getAccessToken(),
+            limit: params.limit || 25
+        };
+
+        // Add date filtering if provided
+        if (params.startDate) {
+            queryParams.since = Math.floor(new Date(params.startDate).getTime() / 1000);
+        }
+        if (params.endDate) {
+            queryParams.until = Math.floor(new Date(params.endDate).getTime() / 1000);
+        }
+
+        const posts: any[] = [];
+        let hasNext = true;
+
+        while (hasNext && posts.length < (params.limit || 100)) {
+            const response = await this.makeInstagramRequest<{
+                data: any[];
+                paging?: { next: string };
+            }>(endpoint, 'GET', null, queryParams);
+
+            if (response.data) {
+                // Filter by caption if query is provided
+                const filtered = params.query
+                    ? response.data.filter(post => 
+                        post.caption?.toLowerCase().includes(params.query.toLowerCase()))
+                    : response.data;
+                
+                posts.push(...filtered);
+            }
+
+            if (response.paging?.next) {
+                // Parse next URL for pagination
+                const nextUrl = new URL(response.paging.next);
+                queryParams.after = nextUrl.searchParams.get('after');
+            } else {
+                hasNext = false;
+            }
+        }
+
+        return posts.slice(0, params.limit || 100);
     }
 
-    const posts: any[] = [];
-    let hasNext = true;
-
-    while (hasNext && posts.length < (params.limit || 100)) {
-      const response = await this.makeInstagramRequest<{
-        data: any[];
-        paging?: { next: string };
-      }>(endpoint, 'GET', null, queryParams);
-
-      if (response.data) {
-        // Filter by caption if query is provided
-        const filtered = params.query
-          ? response.data.filter((post) => post.caption?.toLowerCase().includes(params.query.toLowerCase()))
-          : response.data;
-
-        posts.push(...filtered);
-      }
-
-      if (response.paging?.next) {
-        // Parse next URL for pagination
-        const nextUrl = new URL(response.paging.next);
-        queryParams.after = nextUrl.searchParams.get('after');
-      } else {
-        hasNext = false;
-      }
+    /**
+     * Normalize Instagram post to common format
+     */
+    protected normalizePost(instagramPost: any): any {
+        return {
+            id: instagramPost.id,
+            platform: 'Instagram',
+            profileId: this.instagramBusinessAccountId,
+            content: instagramPost.caption || '',
+            mediaUrls: instagramPost.media_url ? [instagramPost.media_url] : [],
+            publishedAt: new Date(instagramPost.timestamp),
+            analytics: {
+                impressions: instagramPost.impressions_count || 0,
+                engagements: (instagramPost.like_count || 0) + (instagramPost.comments_count || 0),
+                clicks: 0, // Not available in basic metrics
+                shares: 0, // Instagram doesn't track shares
+                comments: instagramPost.comments_count || 0,
+                likes: instagramPost.like_count || 0,
+                reach: instagramPost.reach || 0,
+                saves: instagramPost.saved || 0,
+                videoViews: instagramPost.video_views || 0,
+                platformMetrics: instagramPost
+            },
+            platformSpecificData: {
+                mediaType: instagramPost.media_type,
+                permalink: instagramPost.permalink,
+                isCarousel: instagramPost.media_type === 'CAROUSEL_ALBUM'
+            }
+        };
     }
 
-    return posts.slice(0, params.limit || 100);
-  }
-
-  /**
-   * Normalize Instagram post to common format
-   */
-  protected normalizePost(instagramPost: any): any {
-    return {
-      id: instagramPost.id,
-      platform: 'Instagram',
-      profileId: this.instagramBusinessAccountId,
-      content: instagramPost.caption || '',
-      mediaUrls: instagramPost.media_url ? [instagramPost.media_url] : [],
-      publishedAt: new Date(instagramPost.timestamp),
-      analytics: {
-        impressions: instagramPost.impressions_count || 0,
-        engagements: (instagramPost.like_count || 0) + (instagramPost.comments_count || 0),
-        clicks: 0, // Not available in basic metrics
-        shares: 0, // Instagram doesn't track shares
-        comments: instagramPost.comments_count || 0,
-        likes: instagramPost.like_count || 0,
-        reach: instagramPost.reach || 0,
-        saves: instagramPost.saved || 0,
-        videoViews: instagramPost.video_views || 0,
-        platformMetrics: instagramPost,
-      },
-      platformSpecificData: {
-        mediaType: instagramPost.media_type,
-        permalink: instagramPost.permalink,
-        isCarousel: instagramPost.media_type === 'CAROUSEL_ALBUM',
-      },
-    };
-  }
-
-  /**
-   * Check if media container is ready for publishing
-   */
-  protected async isMediaContainerReady(containerId: string): Promise<boolean> {
-    const response = await this.makeInstagramRequest<{ status_code: string }>(containerId, 'GET', null, {
-      fields: 'status_code',
-      access_token: this.getAccessToken(),
-    });
-
-    return response.status_code === 'FINISHED';
-  }
-
-  /**
-   * Wait for media container to be ready
-   */
-  protected async waitForMediaContainer(containerId: string, maxWaitTime: number = 60000): Promise<void> {
-    const startTime = Date.now();
-    const pollInterval = 2000; // 2 seconds
-
-    while (Date.now() - startTime < maxWaitTime) {
-      if (await this.isMediaContainerReady(containerId)) {
-        return;
-      }
-      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    /**
+     * Check if media container is ready for publishing
+     */
+    protected async isMediaContainerReady(containerId: string): Promise<boolean> {
+        const response = await this.makeInstagramRequest<{ status_code: string }>(
+            containerId,
+            'GET',
+            null,
+            {
+                fields: 'status_code',
+                access_token: this.getAccessToken()
+            }
+        );
+
+        return response.status_code === 'FINISHED';
     }
 
-    throw new Error('Media container processing timeout');
-  }
-}
+    /**
+     * Wait for media container to be ready
+     */
+    protected async waitForMediaContainer(containerId: string, maxWaitTime: number = 60000): Promise<void> {
+        const startTime = Date.now();
+        const pollInterval = 2000; // 2 seconds
+
+        while (Date.now() - startTime < maxWaitTime) {
+            if (await this.isMediaContainerReady(containerId)) {
+                return;
+            }
+            await new Promise(resolve => setTimeout(resolve, pollInterval));
+        }
+
+        throw new Error('Media container processing timeout');
+    }
+}