@memberjunction/actions-bizapps-social 2.61.0

package/src/providers/tiktok/actions/create-video-post.action.ts

@@ -0,0 +1,234 @@
+import { RegisterClass } from '@memberjunction/global';
+import { TikTokBaseAction } from '../tiktok-base.action';
+import { ActionParam, ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+
+/**
+ * Action to create a video post on TikTok
+ * Note: This requires special API approval from TikTok
+ */
+@RegisterClass(TikTokBaseAction, 'CreateVideoPostAction')
+export class CreateVideoPostAction extends TikTokBaseAction {
+    
+    /**
+     * Create a video post on TikTok
+     */
+    protected async InternalRunAction(params: RunActionParams): Promise<ActionResultSimple> {
+        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 parameters
+            const videoUrl = this.getParamValue(Params, 'VideoURL');
+            const title = this.getParamValue(Params, 'Title');
+            const description = this.getParamValue(Params, 'Description');
+            const hashtags = this.getParamValue(Params, 'Hashtags') || [];
+            const privacyLevel = this.getParamValue(Params, 'PrivacyLevel') || 'PUBLIC';
+            const allowComments = this.getParamValue(Params, 'AllowComments') !== false;
+            const allowDuet = this.getParamValue(Params, 'AllowDuet') !== false;
+            const allowStitch = this.getParamValue(Params, 'AllowStitch') !== false;
+            const scheduleTime = this.getParamValue(Params, 'ScheduleTime');
+            
+            // Validate required parameters
+            if (!videoUrl && !this.getParamValue(Params, 'VideoFile')) {
+                throw new Error('Either VideoURL or VideoFile is required');
+            }
+            
+            // Build description with hashtags
+            const hashtagString = hashtags.map((tag: string) => 
+                tag.startsWith('#') ? tag : `#${tag}`
+            ).join(' ');
+            const fullDescription = description ? `${description} ${hashtagString}`.trim() : hashtagString;
+            
+            // Check if we have video upload approval
+            const hasUploadApproval = this.getCustomAttribute(3) === 'approved';
+            
+            if (!hasUploadApproval) {
+                // Return informative message about TikTok limitations
+                const alternativeSteps = {
+                    manualProcess: [
+                        '1. Download the TikTok mobile app',
+                        '2. Log in to your TikTok account',
+                        '3. Tap the + button to create a new video',
+                        '4. Upload your video or record a new one',
+                        `5. Add title: "${title || 'Your video title'}"`,
+                        `6. Add description: "${fullDescription}"`,
+                        '7. Set privacy and interaction settings',
+                        '8. Post immediately or save as draft'
+                    ],
+                    businessSolution: 'For automated posting, apply for TikTok Marketing API access at https://ads.tiktok.com/marketing_api/',
+                    thirdPartyTools: [
+                        'TikTok Creator Studio (web interface)',
+                        'Buffer (with TikTok integration)',
+                        'Hootsuite (business plans)'
+                    ]
+                };
+                
+                // Update output parameters with alternative instructions
+                const outputParams = [...Params];
+                const postIdParam = outputParams.find(p => p.Name === 'PostID');
+                if (postIdParam) postIdParam.Value = null;
+                const postUrlParam = outputParams.find(p => p.Name === 'PostURL');
+                if (postUrlParam) postUrlParam.Value = null;
+                const alternativesParam = outputParams.find(p => p.Name === 'Alternatives');
+                if (alternativesParam) alternativesParam.Value = alternativeSteps;
+                
+                return {
+                    Success: false,
+                    ResultCode: 'API_LIMITATION',
+                    Message: 'TikTok video upload requires special API approval. See Alternatives output for manual posting instructions.',
+                    Params: outputParams
+                };
+            }
+            
+            // If we have approval, attempt to create the post
+            // This is the theoretical implementation if approval is granted
+            const createPostData = {
+                video_url: videoUrl,
+                title: title,
+                description: fullDescription,
+                privacy_level: privacyLevel,
+                allow_comments: allowComments,
+                allow_duet: allowDuet,
+                allow_stitch: allowStitch,
+                scheduled_publish_time: scheduleTime ? new Date(scheduleTime).toISOString() : undefined
+            };
+            
+            const response = await this.makeTikTokRequest<any>(
+                '/v2/video/upload/',
+                'POST',
+                createPostData
+            );
+            
+            const postData = response.data;
+            
+            // Update output parameters
+            const outputParams = [...Params];
+            const postIdParam = outputParams.find(p => p.Name === 'PostID');
+            if (postIdParam) postIdParam.Value = postData.video_id;
+            const postUrlParam = outputParams.find(p => p.Name === 'PostURL');
+            if (postUrlParam) postUrlParam.Value = postData.share_url;
+            const statusParam = outputParams.find(p => p.Name === 'Status');
+            if (statusParam) statusParam.Value = postData.status;
+            
+            return {
+                Success: true,
+                ResultCode: 'SUCCESS',
+                Message: `Successfully created TikTok video post: ${postData.video_id}`,
+                Params: outputParams
+            };
+            
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            
+            // Check for specific TikTok error codes
+            if (errorMessage.includes('insufficient_permissions')) {
+                return {
+                    Success: false,
+                    ResultCode: 'INSUFFICIENT_PERMISSIONS',
+                    Message: 'This action requires TikTok Marketing API approval. Contact TikTok for Business.',
+                    Params
+                };
+            }
+            
+            return {
+                Success: false,
+                ResultCode: this.isAuthError(error) ? 'INVALID_TOKEN' : 'ERROR',
+                Message: `Failed to create TikTok video post: ${errorMessage}`,
+                Params
+            };
+        }
+    }
+    
+    /**
+     * Define the parameters this action expects
+     */
+    public get Params(): ActionParam[] {
+        return [
+            ...this.commonSocialParams,
+            {
+                Name: 'VideoURL',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'VideoFile',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'Title',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'Description',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'Hashtags',
+                Type: 'Input',
+                Value: []
+            },
+            {
+                Name: 'PrivacyLevel',
+                Type: 'Input',
+                Value: 'PUBLIC'
+            },
+            {
+                Name: 'AllowComments',
+                Type: 'Input',
+                Value: true
+            },
+            {
+                Name: 'AllowDuet',
+                Type: 'Input',
+                Value: true
+            },
+            {
+                Name: 'AllowStitch',
+                Type: 'Input',
+                Value: true
+            },
+            {
+                Name: 'ScheduleTime',
+                Type: 'Input',
+                Value: null
+            },
+            {
+                Name: 'PostID',
+                Type: 'Output',
+                Value: null
+            },
+            {
+                Name: 'PostURL',
+                Type: 'Output',
+                Value: null
+            },
+            {
+                Name: 'Status',
+                Type: 'Output',
+                Value: null
+            },
+            {
+                Name: 'Alternatives',
+                Type: 'Output',
+                Value: null
+            }
+        ];
+    }
+    
+    /**
+     * Metadata about this action
+     */
+    public get Description(): string {
+        return 'Creates a video post on TikTok (requires special API approval from TikTok)';
+    }
+}

package/src/providers/tiktok/actions/get-account-analytics.action.ts

@@ -0,0 +1,255 @@
+import { RegisterClass } from '@memberjunction/global';
+import { TikTokBaseAction, TikTokUser } from '../tiktok-base.action';
+import { ActionParam, ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+
+/**
+ * Action to get analytics for a TikTok account
+ */
+@RegisterClass(TikTokBaseAction, 'GetAccountAnalyticsAction')
+export class GetAccountAnalyticsAction extends TikTokBaseAction {
+    
+    /**
+     * Get account-level analytics from TikTok
+     */
+    protected async InternalRunAction(params: RunActionParams): Promise<ActionResultSimple> {
+        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 parameters
+            const dateRange = this.getParamValue(Params, 'DateRange') || '30d';
+            const includeVideoStats = this.getParamValue(Params, 'IncludeVideoStats') !== false;
+            const includeAudienceData = this.getParamValue(Params, 'IncludeAudienceData') !== false;
+            
+            // Get current user info
+            const userInfo = await this.getCurrentUser();
+            
+            // Get user's videos for aggregate stats
+            let videoStats = null;
+            if (includeVideoStats) {
+                const videos = await this.getUserVideos();
+                
+                // Calculate video statistics
+                videoStats = {
+                    totalVideos: videos.length,
+                    totalViews: videos.reduce((sum, v) => sum + v.view_count, 0),
+                    totalLikes: videos.reduce((sum, v) => sum + v.like_count, 0),
+                    totalComments: videos.reduce((sum, v) => sum + v.comment_count, 0),
+                    totalShares: videos.reduce((sum, v) => sum + v.share_count, 0),
+                    averageViewsPerVideo: videos.length > 0 
+                        ? Math.round(videos.reduce((sum, v) => sum + v.view_count, 0) / videos.length)
+                        : 0,
+                    averageEngagementRate: videos.length > 0
+                        ? this.calculateAverageEngagementRate(videos)
+                        : 0,
+                    topVideos: videos
+                        .sort((a, b) => b.view_count - a.view_count)
+                        .slice(0, 5)
+                        .map(v => ({
+                            id: v.id,
+                            title: v.title,
+                            views: v.view_count,
+                            likes: v.like_count,
+                            url: v.share_url
+                        }))
+                };
+            }
+            
+            // Build account analytics
+            const accountAnalytics = {
+                accountInfo: {
+                    userId: userInfo.open_id,
+                    username: userInfo.display_name,
+                    isVerified: userInfo.is_verified,
+                    profileUrl: userInfo.profile_deep_link,
+                    avatarUrl: userInfo.avatar_url,
+                    bio: userInfo.bio_description
+                },
+                metrics: {
+                    followers: userInfo.follower_count,
+                    following: userInfo.following_count,
+                    totalLikes: userInfo.likes_count,
+                    engagementRate: this.calculateAccountEngagementRate(userInfo, videoStats),
+                    growthRate: null // Would need historical data
+                },
+                videoStats,
+                dateRange,
+                generatedAt: new Date()
+            };
+            
+            // Build audience data if requested (placeholder - TikTok API limitations)
+            let audienceData = null;
+            if (includeAudienceData) {
+                audienceData = {
+                    demographics: {
+                        message: 'Detailed audience demographics require TikTok For Business account'
+                    },
+                    topCountries: [],
+                    topCities: [],
+                    ageGroups: [],
+                    genderSplit: {}
+                };
+            }
+            
+            // Create summary
+            const summary = {
+                accountLevel: {
+                    followers: userInfo.follower_count,
+                    engagement: accountAnalytics.metrics.engagementRate,
+                    verified: userInfo.is_verified
+                },
+                contentPerformance: videoStats ? {
+                    totalContent: videoStats.totalVideos,
+                    totalReach: videoStats.totalViews,
+                    avgEngagement: videoStats.averageEngagementRate
+                } : null,
+                recommendations: this.generateRecommendations(accountAnalytics)
+            };
+            
+            // Update output parameters
+            const outputParams = [...Params];
+            const analyticsParam = outputParams.find(p => p.Name === 'AccountAnalytics');
+            if (analyticsParam) analyticsParam.Value = accountAnalytics;
+            const audienceParam = outputParams.find(p => p.Name === 'AudienceData');
+            if (audienceParam) audienceParam.Value = audienceData;
+            const summaryParam = outputParams.find(p => p.Name === 'Summary');
+            if (summaryParam) summaryParam.Value = summary;
+            
+            return {
+                Success: true,
+                ResultCode: 'SUCCESS',
+                Message: `Successfully retrieved analytics for TikTok account @${userInfo.display_name}`,
+                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 get TikTok account analytics: ${errorMessage}`,
+                Params
+            };
+        }
+    }
+    
+    /**
+     * Calculate average engagement rate for videos
+     */
+    private calculateAverageEngagementRate(videos: any[]): number {
+        if (videos.length === 0) return 0;
+        
+        const totalEngagements = videos.reduce((sum, v) => 
+            sum + v.like_count + v.comment_count + v.share_count, 0
+        );
+        const totalViews = videos.reduce((sum, v) => sum + v.view_count, 0);
+        
+        return totalViews > 0 
+            ? parseFloat(((totalEngagements / totalViews) * 100).toFixed(2))
+            : 0;
+    }
+    
+    /**
+     * Calculate account-level engagement rate
+     */
+    private calculateAccountEngagementRate(user: TikTokUser, videoStats: any): number {
+        if (!videoStats || !user.follower_count) return 0;
+        
+        const avgEngagementsPerVideo = videoStats.totalVideos > 0
+            ? (videoStats.totalLikes + videoStats.totalComments + videoStats.totalShares) / videoStats.totalVideos
+            : 0;
+            
+        return parseFloat(((avgEngagementsPerVideo / user.follower_count) * 100).toFixed(2));
+    }
+    
+    /**
+     * Generate recommendations based on analytics
+     */
+    private generateRecommendations(analytics: any): string[] {
+        const recommendations: string[] = [];
+        
+        // Engagement rate recommendations
+        if (analytics.metrics.engagementRate < 1) {
+            recommendations.push('Consider improving content quality to boost engagement rate above 1%');
+        } else if (analytics.metrics.engagementRate > 5) {
+            recommendations.push('Excellent engagement rate! Consider posting more frequently to capitalize on audience interest');
+        }
+        
+        // Follower recommendations
+        if (analytics.accountInfo.followers < 1000) {
+            recommendations.push('Focus on consistent posting and trending hashtags to grow your follower base');
+        }
+        
+        // Video performance recommendations
+        if (analytics.videoStats) {
+            if (analytics.videoStats.averageViewsPerVideo < analytics.accountInfo.followers) {
+                recommendations.push('Your videos are reaching less than your follower count. Try posting at peak times');
+            }
+            
+            if (analytics.videoStats.totalVideos < 10) {
+                recommendations.push('Post more videos to build a stronger content library');
+            }
+        }
+        
+        // Verification recommendation
+        if (!analytics.accountInfo.isVerified && analytics.accountInfo.followers > 10000) {
+            recommendations.push('Consider applying for TikTok verification to build trust with your audience');
+        }
+        
+        return recommendations;
+    }
+    
+    /**
+     * Define the parameters this action expects
+     */
+    public get Params(): ActionParam[] {
+        return [
+            ...this.commonSocialParams,
+            {
+                Name: 'DateRange',
+                Type: 'Input',
+                Value: '30d'
+            },
+            {
+                Name: 'IncludeVideoStats',
+                Type: 'Input',
+                Value: true
+            },
+            {
+                Name: 'IncludeAudienceData',
+                Type: 'Input',
+                Value: true
+            },
+            {
+                Name: 'AccountAnalytics',
+                Type: 'Output',
+                Value: null
+            },
+            {
+                Name: 'AudienceData',
+                Type: 'Output',
+                Value: null
+            },
+            {
+                Name: 'Summary',
+                Type: 'Output',
+                Value: null
+            }
+        ];
+    }
+    
+    /**
+     * Metadata about this action
+     */
+    public get Description(): string {
+        return 'Retrieves comprehensive analytics for a TikTok account including followers, engagement rates, and content performance';
+    }
+}