@memberjunction/actions-bizapps-social 2.61.0

package/dist/providers/tiktok/actions/search-videos.action.js

@@ -0,0 +1,653 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchVideosAction = void 0;
+const global_1 = require("@memberjunction/global");
+const tiktok_base_action_1 = require("../tiktok-base.action");
+/**
+ * Action to search for videos on TikTok
+ * Note: TikTok API only allows searching within authenticated user's own videos
+ */
+let SearchVideosAction = class SearchVideosAction extends tiktok_base_action_1.TikTokBaseAction {
+    /**
+     * Search for videos on TikTok
+     */
+    async InternalRunAction(params) {
+        const { Params } = params;
+        try {
+            // Initialize OAuth
+            const companyIntegrationId = this.getParamValue(Params, 'CompanyIntegrationID');
+            if (!companyIntegrationId) {
+                throw new Error('CompanyIntegrationID is required');
+            }
+            await this.initializeOAuth(companyIntegrationId);
+            // Extract search parameters
+            const query = this.getParamValue(Params, 'Query');
+            const hashtags = this.getParamValue(Params, 'Hashtags') || [];
+            const startDate = this.getParamValue(Params, 'StartDate');
+            const endDate = this.getParamValue(Params, 'EndDate');
+            const minViews = this.getParamValue(Params, 'MinViews');
+            const minEngagement = this.getParamValue(Params, 'MinEngagement');
+            const sortBy = this.getParamValue(Params, 'SortBy') || 'date';
+            const sortOrder = this.getParamValue(Params, 'SortOrder') || 'desc';
+            const limit = this.getParamValue(Params, 'Limit') || 50;
+            const offset = this.getParamValue(Params, 'Offset') || 0;
+            // Build search params
+            const searchParams = {
+                query,
+                hashtags,
+                startDate: startDate ? new Date(startDate) : undefined,
+                endDate: endDate ? new Date(endDate) : undefined,
+                limit,
+                offset
+            };
+            // Note about TikTok limitations
+            const apiLimitation = {
+                notice: 'TikTok API only allows searching within your own videos',
+                recommendation: 'For broader search capabilities, use TikTok\'s web interface or mobile app',
+                alternativeApproach: 'This search filters your own video library based on the provided criteria'
+            };
+            // Get all user videos to search through
+            const allVideos = await this.getUserVideos();
+            // Apply search filters
+            let filteredVideos = this.filterVideos(allVideos, {
+                query,
+                hashtags,
+                startDate,
+                endDate,
+                minViews,
+                minEngagement
+            });
+            // Sort results
+            filteredVideos = this.sortVideos(filteredVideos, sortBy, sortOrder);
+            // Apply pagination
+            const paginatedVideos = filteredVideos.slice(offset, offset + limit);
+            // Convert to social posts
+            const socialPosts = paginatedVideos.map(video => this.normalizePost(video));
+            // Analyze search results
+            const searchAnalytics = this.analyzeSearchResults(filteredVideos, paginatedVideos);
+            // Create time-based insights for historical analysis
+            const historicalInsights = this.generateHistoricalInsights(filteredVideos, startDate, endDate);
+            // Generate content insights
+            const contentInsights = this.generateContentInsights(filteredVideos, query, hashtags);
+            // Create summary
+            const summary = {
+                totalResults: filteredVideos.length,
+                returnedResults: paginatedVideos.length,
+                searchCriteria: {
+                    query,
+                    hashtags,
+                    dateRange: startDate && endDate ? {
+                        start: startDate,
+                        end: endDate,
+                        daysSpanned: Math.ceil((new Date(endDate).getTime() - new Date(startDate).getTime()) / (1000 * 60 * 60 * 24))
+                    } : null,
+                    filters: {
+                        minViews,
+                        minEngagement
+                    }
+                },
+                analytics: searchAnalytics,
+                historicalInsights,
+                contentInsights,
+                apiLimitation,
+                pagination: {
+                    offset,
+                    limit,
+                    hasMore: offset + limit < filteredVideos.length,
+                    totalPages: Math.ceil(filteredVideos.length / limit)
+                }
+            };
+            // Update output parameters
+            const outputParams = [...Params];
+            const videosParam = outputParams.find(p => p.Name === 'Videos');
+            if (videosParam)
+                videosParam.Value = socialPosts;
+            const summaryParam = outputParams.find(p => p.Name === 'Summary');
+            if (summaryParam)
+                summaryParam.Value = summary;
+            const rawDataParam = outputParams.find(p => p.Name === 'RawData');
+            if (rawDataParam)
+                rawDataParam.Value = paginatedVideos;
+            return {
+                Success: true,
+                ResultCode: 'SUCCESS',
+                Message: `Found ${filteredVideos.length} videos matching search criteria (showing ${paginatedVideos.length})`,
+                Params: outputParams
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            return {
+                Success: false,
+                ResultCode: this.isAuthError(error) ? 'INVALID_TOKEN' : 'ERROR',
+                Message: `Failed to search TikTok videos: ${errorMessage}`,
+                Params
+            };
+        }
+    }
+    /**
+     * Filter videos based on search criteria
+     */
+    filterVideos(videos, filters) {
+        return videos.filter(video => {
+            // Query filter
+            if (filters.query) {
+                const query = filters.query.toLowerCase();
+                const matchesQuery = video.title.toLowerCase().includes(query) ||
+                    video.description.toLowerCase().includes(query);
+                if (!matchesQuery)
+                    return false;
+            }
+            // Hashtag filter
+            if (filters.hashtags && filters.hashtags.length > 0) {
+                const videoHashtags = this.extractHashtags(video.description);
+                const hasMatchingHashtag = filters.hashtags.some((tag) => {
+                    const cleanTag = tag.replace('#', '').toLowerCase();
+                    return videoHashtags.includes(cleanTag);
+                });
+                if (!hasMatchingHashtag)
+                    return false;
+            }
+            // Date range filter
+            if (filters.startDate) {
+                const startTime = new Date(filters.startDate).getTime() / 1000;
+                if (video.create_time < startTime)
+                    return false;
+            }
+            if (filters.endDate) {
+                const endTime = new Date(filters.endDate).getTime() / 1000;
+                if (video.create_time > endTime)
+                    return false;
+            }
+            // View count filter
+            if (filters.minViews && video.view_count < filters.minViews) {
+                return false;
+            }
+            // Engagement filter
+            if (filters.minEngagement) {
+                const engagement = video.like_count + video.comment_count + video.share_count;
+                if (engagement < filters.minEngagement)
+                    return false;
+            }
+            return true;
+        });
+    }
+    /**
+     * Sort videos based on criteria
+     */
+    sortVideos(videos, sortBy, order) {
+        const sorted = [...videos];
+        sorted.sort((a, b) => {
+            let aValue;
+            let bValue;
+            switch (sortBy) {
+                case 'views':
+                    aValue = a.view_count;
+                    bValue = b.view_count;
+                    break;
+                case 'likes':
+                    aValue = a.like_count;
+                    bValue = b.like_count;
+                    break;
+                case 'comments':
+                    aValue = a.comment_count;
+                    bValue = b.comment_count;
+                    break;
+                case 'shares':
+                    aValue = a.share_count;
+                    bValue = b.share_count;
+                    break;
+                case 'engagement':
+                    aValue = a.like_count + a.comment_count + a.share_count;
+                    bValue = b.like_count + b.comment_count + b.share_count;
+                    break;
+                case 'date':
+                default:
+                    aValue = a.create_time;
+                    bValue = b.create_time;
+                    break;
+            }
+            return order === 'desc' ? bValue - aValue : aValue - bValue;
+        });
+        return sorted;
+    }
+    /**
+     * Analyze search results
+     */
+    analyzeSearchResults(allResults, displayedResults) {
+        if (allResults.length === 0) {
+            return {
+                totalViews: 0,
+                totalEngagement: 0,
+                averageViews: 0,
+                averageEngagement: 0,
+                topPerformer: null
+            };
+        }
+        const totalViews = allResults.reduce((sum, v) => sum + v.view_count, 0);
+        const totalEngagement = allResults.reduce((sum, v) => sum + v.like_count + v.comment_count + v.share_count, 0);
+        return {
+            totalViews,
+            totalEngagement,
+            averageViews: Math.round(totalViews / allResults.length),
+            averageEngagement: Math.round(totalEngagement / allResults.length),
+            engagementRate: totalViews > 0 ? ((totalEngagement / totalViews) * 100).toFixed(2) + '%' : '0%',
+            topPerformer: allResults.reduce((best, current) => current.view_count > best.view_count ? current : best),
+            performanceDistribution: this.calculatePerformanceDistribution(allResults)
+        };
+    }
+    /**
+     * Generate historical insights
+     */
+    generateHistoricalInsights(videos, startDate, endDate) {
+        if (videos.length === 0)
+            return null;
+        // Group videos by time period
+        const timeGroups = this.groupVideosByTimePeriod(videos);
+        // Calculate trends
+        const viewTrend = this.calculateTrend(timeGroups, 'views');
+        const engagementTrend = this.calculateTrend(timeGroups, 'engagement');
+        // Find best performing periods
+        const bestPeriods = Object.entries(timeGroups)
+            .map(([period, vids]) => ({
+            period,
+            totalViews: vids.reduce((sum, v) => sum + v.view_count, 0),
+            videoCount: vids.length
+        }))
+            .sort((a, b) => b.totalViews - a.totalViews)
+            .slice(0, 3);
+        return {
+            timeRange: {
+                start: startDate || new Date(Math.min(...videos.map(v => v.create_time)) * 1000),
+                end: endDate || new Date(Math.max(...videos.map(v => v.create_time)) * 1000)
+            },
+            totalVideosInPeriod: videos.length,
+            trends: {
+                views: viewTrend,
+                engagement: engagementTrend
+            },
+            bestPerformingPeriods: bestPeriods,
+            postingFrequency: this.calculatePostingFrequency(videos),
+            seasonalPatterns: this.identifySeasonalPatterns(timeGroups)
+        };
+    }
+    /**
+     * Generate content insights
+     */
+    generateContentInsights(videos, query, hashtags) {
+        if (videos.length === 0)
+            return null;
+        // Analyze content themes
+        const commonHashtags = this.findCommonHashtags(videos);
+        const contentLength = this.analyzeContentLength(videos);
+        return {
+            searchRelevance: {
+                query: query || 'all content',
+                matchingVideos: videos.length,
+                averageRelevanceScore: this.calculateRelevanceScore(videos, query, hashtags)
+            },
+            contentPatterns: {
+                commonHashtags: commonHashtags.slice(0, 10),
+                averageDescriptionLength: contentLength.average,
+                optimalLength: contentLength.optimal,
+                titlePatterns: this.analyzeTitlePatterns(videos)
+            },
+            performanceCorrelations: {
+                hashtagsToViews: this.correlateHashtagsToPerformance(videos),
+                lengthToEngagement: contentLength.correlation,
+                timeOfDayImpact: this.analyzeTimeOfDayImpact(videos)
+            }
+        };
+    }
+    /**
+     * Group videos by time period
+     */
+    groupVideosByTimePeriod(videos) {
+        const groups = {};
+        videos.forEach(video => {
+            const date = new Date(video.create_time * 1000);
+            const monthKey = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
+            if (!groups[monthKey]) {
+                groups[monthKey] = [];
+            }
+            groups[monthKey].push(video);
+        });
+        return groups;
+    }
+    /**
+     * Calculate performance trend
+     */
+    calculateTrend(timeGroups, metric) {
+        const periods = Object.keys(timeGroups).sort();
+        if (periods.length < 2)
+            return 'insufficient_data';
+        const recentPeriod = periods[periods.length - 1];
+        const previousPeriod = periods[periods.length - 2];
+        let recentValue;
+        let previousValue;
+        if (metric === 'views') {
+            recentValue = timeGroups[recentPeriod].reduce((sum, v) => sum + v.view_count, 0);
+            previousValue = timeGroups[previousPeriod].reduce((sum, v) => sum + v.view_count, 0);
+        }
+        else {
+            recentValue = timeGroups[recentPeriod].reduce((sum, v) => sum + v.like_count + v.comment_count + v.share_count, 0);
+            previousValue = timeGroups[previousPeriod].reduce((sum, v) => sum + v.like_count + v.comment_count + v.share_count, 0);
+        }
+        const changePercent = previousValue > 0
+            ? ((recentValue - previousValue) / previousValue) * 100
+            : 100;
+        if (changePercent > 20)
+            return 'increasing';
+        if (changePercent < -20)
+            return 'decreasing';
+        return 'stable';
+    }
+    /**
+     * Calculate posting frequency
+     */
+    calculatePostingFrequency(videos) {
+        if (videos.length < 2)
+            return { average: 0, pattern: 'insufficient_data' };
+        const timestamps = videos.map(v => v.create_time).sort();
+        const daysBetweenPosts = [];
+        for (let i = 1; i < timestamps.length; i++) {
+            const daysDiff = (timestamps[i] - timestamps[i - 1]) / (60 * 60 * 24);
+            daysBetweenPosts.push(daysDiff);
+        }
+        const avgDaysBetween = daysBetweenPosts.reduce((sum, days) => sum + days, 0) / daysBetweenPosts.length;
+        let pattern;
+        if (avgDaysBetween < 1)
+            pattern = 'multiple_daily';
+        else if (avgDaysBetween <= 1.5)
+            pattern = 'daily';
+        else if (avgDaysBetween <= 3.5)
+            pattern = 'every_few_days';
+        else if (avgDaysBetween <= 7.5)
+            pattern = 'weekly';
+        else
+            pattern = 'irregular';
+        return {
+            averageDaysBetween: avgDaysBetween.toFixed(1),
+            pattern,
+            postsPerWeek: (7 / avgDaysBetween).toFixed(1)
+        };
+    }
+    /**
+     * Find common hashtags
+     */
+    findCommonHashtags(videos) {
+        const hashtagCount = new Map();
+        videos.forEach(video => {
+            const hashtags = this.extractHashtags(video.description);
+            hashtags.forEach(tag => {
+                hashtagCount.set(tag, (hashtagCount.get(tag) || 0) + 1);
+            });
+        });
+        return Array.from(hashtagCount.entries())
+            .map(([tag, count]) => ({ hashtag: `#${tag}`, count, percentage: (count / videos.length * 100).toFixed(1) }))
+            .sort((a, b) => b.count - a.count);
+    }
+    /**
+     * Analyze content length
+     */
+    analyzeContentLength(videos) {
+        const lengths = videos.map(v => (v.description || '').length);
+        const avgLength = lengths.reduce((sum, len) => sum + len, 0) / lengths.length;
+        // Find optimal length (videos with above-average performance)
+        const avgViews = videos.reduce((sum, v) => sum + v.view_count, 0) / videos.length;
+        const highPerformers = videos.filter(v => v.view_count > avgViews);
+        const optimalLength = highPerformers.length > 0
+            ? highPerformers.reduce((sum, v) => sum + (v.description || '').length, 0) / highPerformers.length
+            : avgLength;
+        return {
+            average: Math.round(avgLength),
+            optimal: Math.round(optimalLength),
+            correlation: optimalLength > avgLength ? 'longer_performs_better' : 'shorter_performs_better'
+        };
+    }
+    /**
+     * Calculate relevance score
+     */
+    calculateRelevanceScore(videos, query, hashtags) {
+        if (!query && (!hashtags || hashtags.length === 0))
+            return 100;
+        let totalScore = 0;
+        videos.forEach(video => {
+            let score = 0;
+            if (query) {
+                const queryLower = query.toLowerCase();
+                if (video.title.toLowerCase().includes(queryLower))
+                    score += 50;
+                if (video.description.toLowerCase().includes(queryLower))
+                    score += 30;
+            }
+            if (hashtags && hashtags.length > 0) {
+                const videoHashtags = this.extractHashtags(video.description);
+                const matchingHashtags = hashtags.filter(tag => videoHashtags.includes(tag.replace('#', '').toLowerCase()));
+                score += (matchingHashtags.length / hashtags.length) * 20;
+            }
+            totalScore += score;
+        });
+        return videos.length > 0 ? Math.round(totalScore / videos.length) : 0;
+    }
+    /**
+     * Analyze title patterns
+     */
+    analyzeTitlePatterns(videos) {
+        const patterns = {
+            questions: videos.filter(v => v.title.includes('?')).length,
+            exclamations: videos.filter(v => v.title.includes('!')).length,
+            emojis: videos.filter(v => /[\u{1F600}-\u{1F64F}]/u.test(v.title)).length,
+            numbers: videos.filter(v => /\d/.test(v.title)).length,
+            allCaps: videos.filter(v => v.title === v.title.toUpperCase() && v.title.length > 3).length
+        };
+        return {
+            ...patterns,
+            mostCommonPattern: Object.entries(patterns)
+                .sort(([, a], [, b]) => b - a)[0][0]
+        };
+    }
+    /**
+     * Correlate hashtags to performance
+     */
+    correlateHashtagsToPerformance(videos) {
+        const hashtagPerformance = new Map();
+        videos.forEach(video => {
+            const hashtags = this.extractHashtags(video.description);
+            hashtags.forEach(tag => {
+                const current = hashtagPerformance.get(tag) || { views: 0, count: 0 };
+                current.views += video.view_count;
+                current.count += 1;
+                hashtagPerformance.set(tag, current);
+            });
+        });
+        return Array.from(hashtagPerformance.entries())
+            .map(([tag, data]) => ({
+            hashtag: `#${tag}`,
+            averageViews: Math.round(data.views / data.count),
+            usageCount: data.count
+        }))
+            .sort((a, b) => b.averageViews - a.averageViews)
+            .slice(0, 5);
+    }
+    /**
+     * Analyze time of day impact
+     */
+    analyzeTimeOfDayImpact(videos) {
+        const hourBuckets = {};
+        videos.forEach(video => {
+            const hour = new Date(video.create_time * 1000).getHours();
+            if (!hourBuckets[hour]) {
+                hourBuckets[hour] = { views: 0, count: 0 };
+            }
+            hourBuckets[hour].views += video.view_count;
+            hourBuckets[hour].count += 1;
+        });
+        const hourlyPerformance = Object.entries(hourBuckets)
+            .map(([hour, data]) => ({
+            hour: parseInt(hour),
+            averageViews: Math.round(data.views / data.count),
+            postCount: data.count
+        }))
+            .sort((a, b) => b.averageViews - a.averageViews);
+        return {
+            bestHours: hourlyPerformance.slice(0, 3).map(h => h.hour),
+            worstHours: hourlyPerformance.slice(-3).map(h => h.hour),
+            recommendation: this.generateTimeRecommendation(hourlyPerformance)
+        };
+    }
+    /**
+     * Generate time posting recommendation
+     */
+    generateTimeRecommendation(hourlyPerformance) {
+        if (hourlyPerformance.length === 0)
+            return 'Insufficient data for recommendations';
+        const bestHour = hourlyPerformance[0].hour;
+        const timeOfDay = bestHour < 12 ? 'morning' : bestHour < 17 ? 'afternoon' : 'evening';
+        return `Best posting time appears to be ${bestHour}:00 (${timeOfDay}) based on historical performance`;
+    }
+    /**
+     * Calculate performance distribution
+     */
+    calculatePerformanceDistribution(videos) {
+        const viewBuckets = {
+            '0-1k': 0,
+            '1k-10k': 0,
+            '10k-100k': 0,
+            '100k-1M': 0,
+            '1M+': 0
+        };
+        videos.forEach(video => {
+            const views = video.view_count;
+            if (views < 1000)
+                viewBuckets['0-1k']++;
+            else if (views < 10000)
+                viewBuckets['1k-10k']++;
+            else if (views < 100000)
+                viewBuckets['10k-100k']++;
+            else if (views < 1000000)
+                viewBuckets['100k-1M']++;
+            else
+                viewBuckets['1M+']++;
+        });
+        return viewBuckets;
+    }
+    /**
+     * Identify seasonal patterns
+     */
+    identifySeasonalPatterns(timeGroups) {
+        const patterns = [];
+        // Simple seasonal analysis
+        const monthlyAvgs = {};
+        Object.entries(timeGroups).forEach(([period, videos]) => {
+            const month = parseInt(period.split('-')[1]);
+            if (!monthlyAvgs[month])
+                monthlyAvgs[month] = [];
+            const avgViews = videos.reduce((sum, v) => sum + v.view_count, 0) / videos.length;
+            monthlyAvgs[month].push(avgViews);
+        });
+        // Find high-performing months
+        const monthPerformance = Object.entries(monthlyAvgs)
+            .map(([month, avgs]) => ({
+            month: parseInt(month),
+            avgPerformance: avgs.reduce((sum, avg) => sum + avg, 0) / avgs.length
+        }))
+            .sort((a, b) => b.avgPerformance - a.avgPerformance);
+        if (monthPerformance.length > 0) {
+            const bestMonth = monthPerformance[0].month;
+            const monthNames = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+            patterns.push(`${monthNames[bestMonth - 1]} shows strongest performance historically`);
+        }
+        return patterns;
+    }
+    /**
+     * Define the parameters this action expects
+     */
+    get Params() {
+        return [
+            ...this.commonSocialParams,
+            {
+                Name: 'Query',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'Hashtags',
+                Type: 'Input',
+                Value: []
+            },
+            {
+                Name: 'StartDate',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'EndDate',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'MinViews',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'MinEngagement',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'SortBy',
+                Type: 'Input',
+                Value: 'date'
+            },
+            {
+                Name: 'SortOrder',
+                Type: 'Input',
+                Value: 'desc'
+            },
+            {
+                Name: 'Limit',
+                Type: 'Input',
+                Value: 50
+            },
+            {
+                Name: 'Offset',
+                Type: 'Input',
+                Value: 0
+            },
+            {
+                Name: 'Videos',
+                Type: 'Output',
+                Value: null
+            },
+            {
+                Name: 'Summary',
+                Type: 'Output',
+                Value: null
+            },
+            {
+                Name: 'RawData',
+                Type: 'Output',
+                Value: null
+            }
+        ];
+    }
+    /**
+     * Metadata about this action
+     */
+    get Description() {
+        return 'Searches historical TikTok videos with advanced filtering, date ranges, and performance analytics (searches within your own videos only due to API limitations)';
+    }
+};
+exports.SearchVideosAction = SearchVideosAction;
+exports.SearchVideosAction = SearchVideosAction = __decorate([
+    (0, global_1.RegisterClass)(tiktok_base_action_1.TikTokBaseAction, 'SearchVideosAction')
+], SearchVideosAction);
+//# sourceMappingURL=search-videos.action.js.map