@memberjunction/actions-bizapps-social 2.61.0

package/src/providers/youtube/actions/get-video-analytics.action.ts

@@ -0,0 +1,298 @@
+import { RegisterClass } from '@memberjunction/global';
+import { YouTubeBaseAction } from '../youtube-base.action';
+import { ActionParam, ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+
+/**
+ * Action to get analytics for YouTube videos
+ */
+@RegisterClass(YouTubeBaseAction, 'YouTubeGetVideoAnalyticsAction')
+export class YouTubeGetVideoAnalyticsAction extends YouTubeBaseAction {
+    /**
+     * Get analytics for YouTube videos
+     */
+    protected async InternalRunAction(params: RunActionParams): Promise<ActionResultSimple> {
+        const { Params, ContextUser } = params;
+        
+        try {
+            // Initialize OAuth
+            const companyIntegrationId = this.getParamValue(Params, 'CompanyIntegrationID');
+            if (!companyIntegrationId) {
+                throw new Error('CompanyIntegrationID is required');
+            }
+
+            const initialized = await this.initializeOAuth(companyIntegrationId);
+            if (!initialized) {
+                throw new Error('Failed to initialize YouTube OAuth connection');
+            }
+
+            // Extract parameters
+            const videoIds = this.getParamValue(Params, 'VideoIDs');
+            const metricsRequested = this.getParamValue(Params, 'Metrics') || ['views', 'likes', 'comments', 'shares'];
+            const startDate = this.getParamValue(Params, 'StartDate');
+            const endDate = this.getParamValue(Params, 'EndDate');
+            const dimensions = this.getParamValue(Params, 'Dimensions');
+
+            // Validate parameters
+            if (!videoIds || (Array.isArray(videoIds) && videoIds.length === 0)) {
+                throw new Error('VideoIDs parameter is required');
+            }
+
+            // Convert single video ID to array
+            const videoIdArray = Array.isArray(videoIds) ? videoIds : [videoIds];
+            
+            // YouTube Data API provides basic statistics
+            // For advanced analytics, YouTube Analytics API would be needed
+            const videoDetails = await this.getVideoStatistics(videoIdArray, ContextUser);
+
+            // Process analytics for each video
+            const analyticsData = videoDetails.map((video: any) => {
+                const stats = video.statistics || {};
+                const snippet = video.snippet || {};
+                
+                return {
+                    videoId: video.id,
+                    title: snippet.title,
+                    publishedAt: snippet.publishedAt,
+                    metrics: {
+                        views: parseInt(stats.viewCount || '0'),
+                        likes: parseInt(stats.likeCount || '0'),
+                        dislikes: parseInt(stats.dislikeCount || '0'),
+                        comments: parseInt(stats.commentCount || '0'),
+                        favorites: parseInt(stats.favoriteCount || '0'),
+                        // Engagement rate calculation
+                        engagementRate: this.calculateEngagementRate(stats),
+                        // Like/dislike ratio
+                        likeRatio: this.calculateLikeRatio(stats)
+                    },
+                    // Additional metadata
+                    duration: video.contentDetails?.duration,
+                    privacyStatus: video.status?.privacyStatus,
+                    categoryId: snippet.categoryId,
+                    tags: snippet.tags || [],
+                    // Thumbnail for reference
+                    thumbnail: snippet.thumbnails?.high?.url || snippet.thumbnails?.default?.url
+                };
+            });
+
+            // Calculate aggregate metrics
+            const aggregateMetrics = this.calculateAggregateMetrics(analyticsData);
+
+            // If YouTube Analytics API was available, we could get:
+            // - Watch time
+            // - Average view duration
+            // - Impressions
+            // - Click-through rate
+            // - Revenue data
+            // - Geographic data
+            // - Traffic sources
+            // - Device types
+            // - Audience retention
+
+            // Create summary
+            const summary = {
+                totalVideos: analyticsData.length,
+                dateRange: {
+                    start: startDate || 'N/A',
+                    end: endDate || 'N/A'
+                },
+                aggregateMetrics: aggregateMetrics,
+                topPerformers: this.getTopPerformers(analyticsData),
+                quotaCost: this.getQuotaCost('videos.list') * Math.ceil(videoIdArray.length / 50)
+            };
+
+            // Update output parameters
+            const outputParams = [...Params];
+            const analyticsParam = outputParams.find(p => p.Name === 'Analytics');
+            if (analyticsParam) analyticsParam.Value = analyticsData;
+            const summaryParam = outputParams.find(p => p.Name === 'Summary');
+            if (summaryParam) summaryParam.Value = summary;
+
+            return {
+                Success: true,
+                ResultCode: 'SUCCESS',
+                Message: `Retrieved analytics for ${analyticsData.length} videos`,
+                Params: outputParams
+            };
+
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            
+            return {
+                Success: false,
+                ResultCode: this.getErrorCode(errorMessage),
+                Message: `Failed to get video analytics: ${errorMessage}`,
+                Params
+            };
+        }
+    }
+
+    /**
+     * Get video statistics from YouTube Data API
+     */
+    private async getVideoStatistics(videoIds: string[], contextUser?: any): Promise<any[]> {
+        const results: any[] = [];
+        
+        // YouTube allows up to 50 video IDs per request
+        const chunks = this.chunkArray(videoIds, 50);
+        
+        for (const chunk of chunks) {
+            const response = await this.makeYouTubeRequest<any>(
+                '/videos',
+                'GET',
+                undefined,
+                {
+                    part: 'snippet,statistics,contentDetails,status',
+                    id: chunk.join(',')
+                },
+                contextUser
+            );
+            
+            if (response.items) {
+                results.push(...response.items);
+            }
+        }
+        
+        return results;
+    }
+
+    /**
+     * Calculate engagement rate
+     */
+    private calculateEngagementRate(stats: any): number {
+        const views = parseInt(stats.viewCount || '0');
+        if (views === 0) return 0;
+        
+        const engagements = parseInt(stats.likeCount || '0') + 
+                           parseInt(stats.dislikeCount || '0') + 
+                           parseInt(stats.commentCount || '0');
+        
+        return Math.round((engagements / views) * 10000) / 100; // Percentage with 2 decimals
+    }
+
+    /**
+     * Calculate like ratio
+     */
+    private calculateLikeRatio(stats: any): number {
+        const likes = parseInt(stats.likeCount || '0');
+        const dislikes = parseInt(stats.dislikeCount || '0');
+        const total = likes + dislikes;
+        
+        if (total === 0) return 0;
+        return Math.round((likes / total) * 10000) / 100; // Percentage with 2 decimals
+    }
+
+    /**
+     * Calculate aggregate metrics across all videos
+     */
+    private calculateAggregateMetrics(analyticsData: any[]): any {
+        const totals = analyticsData.reduce((acc, video) => {
+            acc.views += video.metrics.views;
+            acc.likes += video.metrics.likes;
+            acc.dislikes += video.metrics.dislikes;
+            acc.comments += video.metrics.comments;
+            acc.favorites += video.metrics.favorites;
+            return acc;
+        }, { views: 0, likes: 0, dislikes: 0, comments: 0, favorites: 0 });
+
+        const avgEngagement = analyticsData.reduce((sum, v) => sum + v.metrics.engagementRate, 0) / analyticsData.length;
+        const avgLikeRatio = analyticsData.reduce((sum, v) => sum + v.metrics.likeRatio, 0) / analyticsData.length;
+
+        return {
+            total: totals,
+            average: {
+                views: Math.round(totals.views / analyticsData.length),
+                likes: Math.round(totals.likes / analyticsData.length),
+                dislikes: Math.round(totals.dislikes / analyticsData.length),
+                comments: Math.round(totals.comments / analyticsData.length),
+                engagementRate: Math.round(avgEngagement * 100) / 100,
+                likeRatio: Math.round(avgLikeRatio * 100) / 100
+            }
+        };
+    }
+
+    /**
+     * Get top performing videos
+     */
+    private getTopPerformers(analyticsData: any[]): any {
+        return {
+            byViews: [...analyticsData].sort((a, b) => b.metrics.views - a.metrics.views).slice(0, 5),
+            byEngagement: [...analyticsData].sort((a, b) => b.metrics.engagementRate - a.metrics.engagementRate).slice(0, 5),
+            byLikes: [...analyticsData].sort((a, b) => b.metrics.likes - a.metrics.likes).slice(0, 5)
+        };
+    }
+
+    /**
+     * Chunk array into smaller arrays
+     */
+    private chunkArray<T>(array: T[], size: number): T[][] {
+        const chunks: T[][] = [];
+        for (let i = 0; i < array.length; i += size) {
+            chunks.push(array.slice(i, i + size));
+        }
+        return chunks;
+    }
+
+    /**
+     * Get error code from error message
+     */
+    private getErrorCode(message: string): string {
+        if (message.includes('quota')) return 'QUOTA_EXCEEDED';
+        if (message.includes('401') || message.includes('unauthorized')) return 'INVALID_TOKEN';
+        if (message.includes('403') || message.includes('forbidden')) return 'INSUFFICIENT_PERMISSIONS';
+        if (message.includes('404')) return 'NOT_FOUND';
+        if (message.includes('rate limit')) return 'RATE_LIMIT';
+        return 'ERROR';
+    }
+
+    /**
+     * Define the parameters this action expects
+     */
+    public get Params(): ActionParam[] {
+        const baseParams = this.commonSocialParams;
+        const specificParams: ActionParam[] = [
+            {
+                Name: 'VideoIDs',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'Metrics',
+                Type: 'Input',
+                Value: ['views', 'likes', 'comments', 'shares']
+            },
+            {
+                Name: 'StartDate',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'EndDate',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'Dimensions',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'Analytics',
+                Type: 'Output',
+                Value: null
+            },
+            {
+                Name: 'Summary',
+                Type: 'Output',
+                Value: null
+            }
+        ];
+        return [...baseParams, ...specificParams];
+    }
+
+    /**
+     * Metadata about this action
+     */
+    public get Description(): string {
+        return 'Gets analytics data for YouTube videos including views, engagement, and performance metrics';
+    }
+}

package/src/providers/youtube/actions/index.ts

@@ -0,0 +1,9 @@
+export * from './upload-video.action';
+export * from './get-channel-videos.action';
+export * from './get-video-analytics.action';
+export * from './update-video-metadata.action';
+export * from './create-playlist.action';
+export * from './schedule-video.action';
+export * from './get-comments.action';
+export * from './get-channel-analytics.action';
+export * from './search-videos.action';

package/src/providers/youtube/actions/schedule-video.action.ts

@@ -0,0 +1,246 @@
+import { RegisterClass } from '@memberjunction/global';
+import { YouTubeBaseAction } from '../youtube-base.action';
+import { ActionParam, ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+
+/**
+ * Action to schedule a YouTube video for publishing
+ */
+@RegisterClass(YouTubeBaseAction, 'YouTubeScheduleVideoAction')
+export class YouTubeScheduleVideoAction extends YouTubeBaseAction {
+    /**
+     * Schedule a video for publishing on YouTube
+     */
+    protected async InternalRunAction(params: RunActionParams): Promise<ActionResultSimple> {
+        const { Params, ContextUser } = params;
+        
+        try {
+            // Initialize OAuth
+            const companyIntegrationId = this.getParamValue(Params, 'CompanyIntegrationID');
+            if (!companyIntegrationId) {
+                throw new Error('CompanyIntegrationID is required');
+            }
+
+            const initialized = await this.initializeOAuth(companyIntegrationId);
+            if (!initialized) {
+                throw new Error('Failed to initialize YouTube OAuth connection');
+            }
+
+            // Extract parameters
+            const videoId = this.getParamValue(Params, 'VideoID');
+            const publishAt = this.getParamValue(Params, 'PublishAt');
+            const notifySubscribers = this.getParamValue(Params, 'NotifySubscribers') ?? true;
+            const premiereTiming = this.getParamValue(Params, 'PremiereTiming');
+            const enableChat = this.getParamValue(Params, 'EnableChat') ?? false;
+
+            // Validate required parameters
+            if (!videoId) {
+                throw new Error('VideoID is required');
+            }
+            if (!publishAt) {
+                throw new Error('PublishAt date/time is required');
+            }
+
+            // Validate publish date is in the future
+            const publishDate = new Date(publishAt);
+            if (publishDate <= new Date()) {
+                throw new Error('PublishAt must be a future date/time');
+            }
+
+            // Get current video details
+            const currentVideo = await this.makeYouTubeRequest<any>(
+                '/videos',
+                'GET',
+                undefined,
+                {
+                    part: 'snippet,status',
+                    id: videoId
+                },
+                ContextUser
+            );
+
+            if (!currentVideo.items || currentVideo.items.length === 0) {
+                throw new Error(`Video not found: ${videoId}`);
+            }
+
+            const video = currentVideo.items[0];
+            
+            // Verify video is currently private
+            if (video.status.privacyStatus !== 'private') {
+                throw new Error(`Video must be private to schedule. Current status: ${video.status.privacyStatus}`);
+            }
+
+            // Prepare update data
+            const updateData: any = {
+                id: videoId,
+                status: {
+                    privacyStatus: 'private', // Keep private until publish time
+                    publishAt: this.formatDate(publishDate),
+                    selfDeclaredMadeForKids: video.status.selfDeclaredMadeForKids,
+                    notifySubscribers: notifySubscribers
+                }
+            };
+
+            // Handle premiere settings
+            if (premiereTiming === 'premiere') {
+                // Set up as a premiere
+                updateData.status.privacyStatus = 'unlisted'; // Premieres start as unlisted
+                updateData.liveStreamingDetails = {
+                    scheduledStartTime: this.formatDate(publishDate),
+                    enableLowLatency: false,
+                    enableAutoStart: true,
+                    enableDvr: true
+                };
+                
+                if (enableChat) {
+                    updateData.liveStreamingDetails.enableClosedCaptions = false;
+                    updateData.liveStreamingDetails.enableContentEncryption = false;
+                    updateData.liveStreamingDetails.enableEmbed = true;
+                }
+            }
+
+            // Update the video
+            const updateResponse = await this.makeYouTubeRequest<any>(
+                '/videos',
+                'PUT',
+                updateData,
+                {
+                    part: 'status' + (premiereTiming === 'premiere' ? ',liveStreamingDetails' : '')
+                },
+                ContextUser
+            );
+
+            // Get updated video details
+            const updatedVideo = await this.makeYouTubeRequest<any>(
+                '/videos',
+                'GET',
+                undefined,
+                {
+                    part: 'snippet,status,contentDetails' + (premiereTiming === 'premiere' ? ',liveStreamingDetails' : ''),
+                    id: videoId
+                },
+                ContextUser
+            );
+
+            const finalVideo = updatedVideo.items[0];
+
+            // Calculate time until publish
+            const timeUntilPublish = publishDate.getTime() - Date.now();
+            const hoursUntilPublish = Math.floor(timeUntilPublish / (1000 * 60 * 60));
+            const minutesUntilPublish = Math.floor((timeUntilPublish % (1000 * 60 * 60)) / (1000 * 60));
+
+            // Prepare result
+            const result = {
+                videoId: finalVideo.id,
+                videoUrl: `https://www.youtube.com/watch?v=${finalVideo.id}`,
+                title: finalVideo.snippet.title,
+                scheduledFor: finalVideo.status.publishAt,
+                scheduledForLocal: new Date(finalVideo.status.publishAt).toLocaleString(),
+                timeUntilPublish: {
+                    hours: hoursUntilPublish,
+                    minutes: minutesUntilPublish,
+                    formatted: `${hoursUntilPublish}h ${minutesUntilPublish}m`
+                },
+                privacyStatus: finalVideo.status.privacyStatus,
+                notifySubscribers: notifySubscribers,
+                isPremiere: premiereTiming === 'premiere',
+                premiereDetails: premiereTiming === 'premiere' ? {
+                    scheduledStartTime: finalVideo.liveStreamingDetails?.scheduledStartTime,
+                    chatEnabled: enableChat
+                } : null,
+                thumbnails: finalVideo.snippet.thumbnails,
+                duration: finalVideo.contentDetails.duration,
+                quotaCost: this.getQuotaCost('videos.update')
+            };
+
+            // Update output parameters
+            const outputParams = [...Params];
+            const scheduleDetailsParam = outputParams.find(p => p.Name === 'ScheduleDetails');
+            if (scheduleDetailsParam) scheduleDetailsParam.Value = result;
+            const scheduledTimeParam = outputParams.find(p => p.Name === 'ScheduledTime');
+            if (scheduledTimeParam) scheduledTimeParam.Value = result.scheduledFor;
+
+            return {
+                Success: true,
+                ResultCode: 'SUCCESS',
+                Message: `Video scheduled successfully for ${result.scheduledForLocal} (${result.timeUntilPublish.formatted} from now)`,
+                Params: outputParams
+            };
+
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            
+            return {
+                Success: false,
+                ResultCode: this.getErrorCode(errorMessage),
+                Message: `Failed to schedule video: ${errorMessage}`,
+                Params
+            };
+        }
+    }
+
+    /**
+     * Get error code from error message
+     */
+    private getErrorCode(message: string): string {
+        if (message.includes('quota')) return 'QUOTA_EXCEEDED';
+        if (message.includes('401') || message.includes('unauthorized')) return 'INVALID_TOKEN';
+        if (message.includes('403') || message.includes('forbidden')) return 'INSUFFICIENT_PERMISSIONS';
+        if (message.includes('404')) return 'NOT_FOUND';
+        if (message.includes('rate limit')) return 'RATE_LIMIT';
+        if (message.includes('future')) return 'INVALID_DATE';
+        if (message.includes('private')) return 'INVALID_STATUS';
+        return 'ERROR';
+    }
+
+    /**
+     * Define the parameters this action expects
+     */
+    public get Params(): ActionParam[] {
+        const baseParams = this.commonSocialParams;
+        const specificParams: ActionParam[] = [
+            {
+                Name: 'VideoID',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'PublishAt',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'NotifySubscribers',
+                Type: 'Input',
+                Value: true
+            },
+            {
+                Name: 'PremiereTiming',
+                Type: 'Input',
+                Value: 'standard'
+            },
+            {
+                Name: 'EnableChat',
+                Type: 'Input',
+                Value: false
+            },
+            {
+                Name: 'ScheduleDetails',
+                Type: 'Output',
+                Value: null
+            },
+            {
+                Name: 'ScheduledTime',
+                Type: 'Output',
+                Value: null
+            }
+        ];
+        return [...baseParams, ...specificParams];
+    }
+
+    /**
+     * Metadata about this action
+     */
+    public get Description(): string {
+        return 'Schedules a private YouTube video to be published at a specific date/time with optional premiere settings';
+    }
+}