@memberjunction/actions-bizapps-social 2.61.0

package/src/providers/facebook/actions/get-page-insights.action.ts

@@ -0,0 +1,427 @@
+import { RegisterClass } from '@memberjunction/global';
+import { FacebookBaseAction, FacebookInsight } from '../facebook-base.action';
+import { ActionParam, ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+import { SocialMediaErrorCode } from '../../../base/base-social.action';
+import { LogStatus, LogError } from '@memberjunction/core';
+import axios from 'axios';
+
+/**
+ * Retrieves comprehensive analytics and insights for a Facebook page.
+ * Provides metrics like page views, likes, engagement, demographics, and more.
+ */
+@RegisterClass(FacebookBaseAction, 'FacebookGetPageInsightsAction')
+export class FacebookGetPageInsightsAction extends FacebookBaseAction {
+    /**
+     * Get action description
+     */
+    public get Description(): string {
+        return 'Retrieves comprehensive analytics for a Facebook page including views, engagement, demographics, and performance metrics';
+    }
+
+    /**
+     * Define the parameters for this action
+     */
+    public get Params(): ActionParam[] {
+        return [
+            ...this.commonSocialParams,
+            {
+                Name: 'PageID',
+                Type: 'Input',
+                Value: null,
+                },
+            {
+                Name: 'MetricTypes',
+                Type: 'Input',
+                Value: null,
+                },
+            {
+                Name: 'Period',
+                Type: 'Input',
+                Value: 'day',
+                },
+            {
+                Name: 'StartDate',
+                Type: 'Input',
+                Value: null,
+                },
+            {
+                Name: 'EndDate',
+                Type: 'Input',
+                Value: null,
+                },
+            {
+                Name: 'IncludeDemographics',
+                Type: 'Input',
+                Value: true,
+                },
+            {
+                Name: 'IncludeVideoMetrics',
+                Type: 'Input',
+                Value: true,
+                },
+            {
+                Name: 'CompareWithPrevious',
+                Type: 'Input',
+                Value: false,
+                }
+        ];
+    }
+
+    /**
+     * Execute the action
+     */
+    protected async InternalRunAction(params: RunActionParams): Promise<ActionResultSimple> {
+        const { Params, ContextUser } = params;
+        
+        try {
+            // Validate required parameters
+            const companyIntegrationId = this.getParamValue(Params, 'CompanyIntegrationID');
+            const pageId = this.getParamValue(Params, 'PageID');
+            
+            if (!companyIntegrationId) {
+                return {
+                Success: false,
+                Message: 'CompanyIntegrationID is required',
+                ResultCode: 'INVALID_TOKEN'
+            };
+            }
+
+            if (!pageId) {
+                return {
+                Success: false,
+                Message: 'PageID is required',
+                ResultCode: 'MISSING_REQUIRED_PARAM'
+            };
+            }
+
+            // Initialize OAuth
+            if (!await this.initializeOAuth(companyIntegrationId)) {
+                return {
+                Success: false,
+                Message: 'Failed to initialize Facebook OAuth connection',
+                ResultCode: 'INVALID_TOKEN'
+            };
+            }
+
+            // Get parameters
+            const metricTypes = this.getParamValue(Params, 'MetricTypes') as string[];
+            const period = this.getParamValue(Params, 'Period') as string || 'day';
+            const startDate = this.getParamValue(Params, 'StartDate') as string;
+            const endDate = this.getParamValue(Params, 'EndDate') as string;
+            const includeDemographics = this.getParamValue(Params, 'IncludeDemographics') !== false;
+            const includeVideoMetrics = this.getParamValue(Params, 'IncludeVideoMetrics') !== false;
+            const compareWithPrevious = this.getParamValue(Params, 'CompareWithPrevious') as boolean;
+
+            LogStatus(`Retrieving insights for Facebook page ${pageId}...`);
+
+            // Get page access token
+            const pageToken = await this.getPageAccessToken(pageId);
+
+            // Build metrics list
+            const metrics = metricTypes && metricTypes.length > 0 
+                ? metricTypes 
+                : this.getDefaultPageMetrics(includeDemographics, includeVideoMetrics);
+
+            // Build date range parameters
+            const dateParams: any = {};
+            if (startDate && endDate) {
+                dateParams.since = new Date(startDate).toISOString();
+                dateParams.until = new Date(endDate).toISOString();
+            } else if (period !== 'lifetime') {
+                // Default to last 30 days if no date range specified
+                const end = new Date();
+                const start = new Date();
+                start.setDate(start.getDate() - 30);
+                dateParams.since = start.toISOString();
+                dateParams.until = end.toISOString();
+            }
+
+            // Get page insights
+            const insightsResponse = await axios.get(
+                `${this.apiBaseUrl}/${pageId}/insights`,
+                {
+                    params: {
+                        access_token: pageToken,
+                        metric: metrics.join(','),
+                        period: period,
+                        ...dateParams
+                    }
+                }
+            );
+
+            const insights: FacebookInsight[] = insightsResponse.data.data || [];
+
+            // Get page info for context
+            const pageInfoResponse = await axios.get(
+                `${this.apiBaseUrl}/${pageId}`,
+                {
+                    params: {
+                        access_token: pageToken,
+                        fields: 'id,name,category,fan_count,followers_count,about,cover,picture'
+                    }
+                }
+            );
+
+            const pageInfo = pageInfoResponse.data;
+
+            // Process insights into categories
+            const processedInsights = this.categorizeInsights(insights);
+
+            // Get comparison data if requested
+            let comparison = null;
+            if (compareWithPrevious && startDate && endDate) {
+                comparison = await this.getComparisonData(
+                    pageId,
+                    pageToken,
+                    metrics,
+                    period,
+                    new Date(startDate),
+                    new Date(endDate)
+                );
+            }
+
+            // Calculate summary metrics
+            const summary = this.calculateSummaryMetrics(processedInsights, pageInfo);
+
+            LogStatus(`Successfully retrieved insights for page ${pageId}`);
+
+            return {
+                Success: true,
+                Message: 'Page insights retrieved successfully',
+                ResultCode: 'SUCCESS',
+                Params
+            };
+
+        } catch (error) {
+            LogError(`Failed to get Facebook page insights: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            
+            if (this.isAuthError(error)) {
+                return this.handleOAuthError(error);
+            }
+
+            return {
+                Success: false,
+                Message: error instanceof Error ? error.message : 'Unknown error occurred',
+                ResultCode: 'ERROR'
+            };
+        }
+    }
+
+    /**
+     * Get default page metrics based on options
+     */
+    private getDefaultPageMetrics(includeDemographics: boolean, includeVideo: boolean): string[] {
+        const metrics = [
+            // Page Views
+            'page_views_total',
+            'page_views_logged_in_unique',
+            'page_views_by_site_logged_in_unique',
+            
+            // Page Likes
+            'page_fan_adds',
+            'page_fan_removes',
+            'page_fan_adds_unique',
+            'page_fans',
+            
+            // Engagement
+            'page_engaged_users',
+            'page_post_engagements',
+            'page_consumptions',
+            'page_consumptions_unique',
+            'page_places_checkin_total',
+            
+            // Impressions
+            'page_impressions',
+            'page_impressions_unique',
+            'page_impressions_paid',
+            'page_impressions_paid_unique',
+            'page_impressions_organic',
+            'page_impressions_organic_unique',
+            
+            // Posts
+            'page_posts_impressions',
+            'page_posts_impressions_unique',
+            
+            // Actions
+            'page_actions_post_reactions_total',
+            'page_actions_post_reactions_like_total',
+            'page_actions_post_reactions_love_total',
+            'page_actions_post_reactions_wow_total',
+            'page_actions_post_reactions_haha_total',
+            'page_actions_post_reactions_sorry_total',
+            'page_actions_post_reactions_anger_total',
+            
+            // CTA Clicks
+            'page_total_actions',
+            'page_cta_clicks_logged_in_total',
+            
+            // Messages
+            'page_messages_total_messaging_connections',
+            'page_messages_new_conversations',
+            
+            // Negative Feedback
+            'page_negative_feedback',
+            'page_negative_feedback_unique'
+        ];
+
+        if (includeDemographics) {
+            metrics.push(
+                'page_fans_gender_age',
+                'page_fans_country',
+                'page_fans_city',
+                'page_fans_locale',
+                'page_impressions_by_age_gender_unique',
+                'page_engaged_users_by_age_gender'
+            );
+        }
+
+        if (includeVideo) {
+            metrics.push(
+                'page_video_views',
+                'page_video_views_paid',
+                'page_video_views_organic',
+                'page_video_views_autoplayed',
+                'page_video_views_click_to_play',
+                'page_video_views_unique',
+                'page_video_repeat_views',
+                'page_video_complete_views_30s',
+                'page_video_complete_views_30s_paid',
+                'page_video_complete_views_30s_organic',
+                'page_video_views_10s',
+                'page_video_views_10s_paid',
+                'page_video_views_10s_organic'
+            );
+        }
+
+        return metrics;
+    }
+
+    /**
+     * Categorize insights by type for better organization
+     */
+    private categorizeInsights(insights: FacebookInsight[]): Record<string, any> {
+        const categories: Record<string, any> = {
+            pageViews: {},
+            engagement: {},
+            likes: {},
+            impressions: {},
+            posts: {},
+            reactions: {},
+            demographics: {},
+            video: {},
+            messages: {},
+            negativeFeedback: {}
+        };
+
+        for (const insight of insights) {
+            const name = insight.name;
+            const value = insight.values?.[0]?.value;
+
+            if (name.includes('page_views')) {
+                categories.pageViews[name] = value;
+            } else if (name.includes('engaged') || name.includes('engagement')) {
+                categories.engagement[name] = value;
+            } else if (name.includes('fan') || name === 'page_fans') {
+                categories.likes[name] = value;
+            } else if (name.includes('impressions')) {
+                categories.impressions[name] = value;
+            } else if (name.includes('posts')) {
+                categories.posts[name] = value;
+            } else if (name.includes('reactions')) {
+                categories.reactions[name] = value;
+            } else if (name.includes('gender') || name.includes('country') || name.includes('city') || name.includes('locale')) {
+                categories.demographics[name] = value;
+            } else if (name.includes('video')) {
+                categories.video[name] = value;
+            } else if (name.includes('messages')) {
+                categories.messages[name] = value;
+            } else if (name.includes('negative')) {
+                categories.negativeFeedback[name] = value;
+            }
+        }
+
+        return categories;
+    }
+
+    /**
+     * Calculate summary metrics
+     */
+    private calculateSummaryMetrics(insights: Record<string, any>, pageInfo: any): any {
+        const summary: any = {
+            totalFans: pageInfo.fan_count || 0,
+            totalFollowers: pageInfo.followers_count || 0,
+            totalPageViews: insights.pageViews.page_views_total || 0,
+            totalEngagements: insights.engagement.page_engaged_users || 0,
+            totalImpressions: insights.impressions.page_impressions || 0,
+            netNewFans: (insights.likes.page_fan_adds || 0) - (insights.likes.page_fan_removes || 0)
+        };
+
+        // Calculate engagement rate if we have the data
+        if (summary.totalImpressions > 0) {
+            summary.engagementRate = (summary.totalEngagements / summary.totalImpressions) * 100;
+        }
+
+        // Add reaction breakdown
+        const reactions = insights.reactions;
+        if (reactions) {
+            summary.reactionBreakdown = {
+                total: reactions.page_actions_post_reactions_total || 0,
+                like: reactions.page_actions_post_reactions_like_total || 0,
+                love: reactions.page_actions_post_reactions_love_total || 0,
+                wow: reactions.page_actions_post_reactions_wow_total || 0,
+                haha: reactions.page_actions_post_reactions_haha_total || 0,
+                sorry: reactions.page_actions_post_reactions_sorry_total || 0,
+                anger: reactions.page_actions_post_reactions_anger_total || 0
+            };
+        }
+
+        return summary;
+    }
+
+    /**
+     * Get comparison data for previous period
+     */
+    private async getComparisonData(
+        pageId: string,
+        pageToken: string,
+        metrics: string[],
+        period: string,
+        startDate: Date,
+        endDate: Date
+    ): Promise<any> {
+        try {
+            const duration = endDate.getTime() - startDate.getTime();
+            const previousStart = new Date(startDate.getTime() - duration);
+            const previousEnd = new Date(startDate.getTime());
+
+            const response = await axios.get(
+                `${this.apiBaseUrl}/${pageId}/insights`,
+                {
+                    params: {
+                        access_token: pageToken,
+                        metric: metrics.join(','),
+                        period: period,
+                        since: previousStart.toISOString(),
+                        until: previousEnd.toISOString()
+                    }
+                }
+            );
+
+            const previousInsights = response.data.data || [];
+            const processedPrevious = this.categorizeInsights(previousInsights);
+
+            return {
+                period: {
+                    start: previousStart.toISOString(),
+                    end: previousEnd.toISOString()
+                },
+                insights: processedPrevious
+            };
+        } catch (error) {
+            LogError(`Failed to get comparison data: ${error}`);
+            return null;
+        }
+    }
+
+
+}

package/src/providers/facebook/actions/get-page-posts.action.ts

@@ -0,0 +1,241 @@
+import { RegisterClass } from '@memberjunction/global';
+import { FacebookBaseAction, GetPagePostsParams } from '../facebook-base.action';
+import { ActionParam, ActionResultSimple, RunActionParams } from '@memberjunction/actions-base';
+import { SocialMediaErrorCode } from '../../../base/base-social.action';
+import { LogStatus, LogError } from '@memberjunction/core';
+
+/**
+ * Retrieves posts from a Facebook page with optional date filtering.
+ * Includes post content, media, and basic engagement metrics.
+ */
+@RegisterClass(FacebookBaseAction, 'FacebookGetPagePostsAction')
+export class FacebookGetPagePostsAction extends FacebookBaseAction {
+    /**
+     * Get action description
+     */
+    public get Description(): string {
+        return 'Retrieves posts from a Facebook page with optional date range filtering and pagination';
+    }
+
+    /**
+     * Define the parameters for this action
+     */
+    public get Params(): ActionParam[] {
+        return [
+            ...this.commonSocialParams,
+            {
+                Name: 'PageID',
+                Type: 'Input',
+                Value: null,
+                },
+            {
+                Name: 'StartDate',
+                Type: 'Input',
+                Value: null,
+                },
+            {
+                Name: 'EndDate',
+                Type: 'Input',
+                Value: null,
+                },
+            {
+                Name: 'Limit',
+                Type: 'Input',
+                Value: 100,
+                },
+            {
+                Name: 'MaxResults',
+                Type: 'Input',
+                Value: null,
+                },
+            {
+                Name: 'IncludeUnpublished',
+                Type: 'Input',
+                Value: false,
+                },
+            {
+                Name: 'IncludeInsights',
+                Type: 'Input',
+                Value: true,
+                }
+        ];
+    }
+
+    /**
+     * Execute the action
+     */
+    protected async InternalRunAction(params: RunActionParams): Promise<ActionResultSimple> {
+        const { Params, ContextUser } = params;
+        
+        try {
+            // Validate required parameters
+            const companyIntegrationId = this.getParamValue(Params, 'CompanyIntegrationID');
+            const pageId = this.getParamValue(Params, 'PageID');
+            
+            if (!companyIntegrationId) {
+                return {
+                Success: false,
+                Message: 'CompanyIntegrationID is required',
+                ResultCode: 'INVALID_TOKEN'
+            };
+            }
+
+            if (!pageId) {
+                return {
+                Success: false,
+                Message: 'PageID is required',
+                ResultCode: 'MISSING_REQUIRED_PARAM'
+            };
+            }
+
+            // Initialize OAuth
+            if (!await this.initializeOAuth(companyIntegrationId)) {
+                return {
+                Success: false,
+                Message: 'Failed to initialize Facebook OAuth connection',
+                ResultCode: 'INVALID_TOKEN'
+            };
+            }
+
+            // Get parameters
+            const startDate = this.getParamValue(Params, 'StartDate') as string;
+            const endDate = this.getParamValue(Params, 'EndDate') as string;
+            const limit = this.getParamValue(Params, 'Limit') as number || 100;
+            const maxResults = this.getParamValue(Params, 'MaxResults') as number;
+            const includeUnpublished = this.getParamValue(Params, 'IncludeUnpublished') as boolean;
+            const includeInsights = this.getParamValue(Params, 'IncludeInsights') as boolean;
+
+            // Build query parameters
+            const queryParams: GetPagePostsParams = {
+                limit: Math.min(limit, 100), // Facebook max is 100 per request
+                published: includeUnpublished ? undefined : true
+            };
+
+            if (startDate) {
+                queryParams.since = new Date(startDate);
+            }
+
+            if (endDate) {
+                queryParams.until = new Date(endDate);
+            }
+
+            LogStatus(`Retrieving posts from Facebook page ${pageId}...`);
+
+            // Get posts with pagination support
+            let allPosts = await this.getPagePosts(pageId, queryParams);
+
+            // If we need more posts and have a maxResults, use pagination
+            if (maxResults && allPosts.length < maxResults && allPosts.length === queryParams.limit) {
+                LogStatus(`Fetching additional pages of posts...`);
+                
+                const pageToken = await this.getPageAccessToken(pageId);
+                const fields = includeInsights ? this.getPostFields() : this.getPostFieldsWithoutInsights();
+                
+                allPosts = await this.getPaginatedResults(
+                    `${this.apiBaseUrl}/${pageId}/posts`,
+                    {
+                        access_token: pageToken,
+                        fields,
+                        ...queryParams,
+                        since: queryParams.since ? Math.floor(queryParams.since.getTime() / 1000) : undefined,
+                        until: queryParams.until ? Math.floor(queryParams.until.getTime() / 1000) : undefined
+                    },
+                    maxResults
+                );
+            }
+
+            // Limit results if maxResults specified
+            if (maxResults && allPosts.length > maxResults) {
+                allPosts = allPosts.slice(0, maxResults);
+            }
+
+            LogStatus(`Retrieved ${allPosts.length} posts from Facebook page`);
+
+            // Normalize posts to common format
+            const normalizedPosts = allPosts.map(post => this.normalizePost(post));
+
+            // Calculate summary statistics
+            const summary = {
+                totalPosts: normalizedPosts.length,
+                dateRange: {
+                    earliest: normalizedPosts.length > 0 
+                        ? normalizedPosts[normalizedPosts.length - 1].publishedAt 
+                        : null,
+                    latest: normalizedPosts.length > 0 
+                        ? normalizedPosts[0].publishedAt 
+                        : null
+                },
+                postTypes: this.categorizePostTypes(allPosts),
+                totalEngagements: normalizedPosts.reduce((sum, post) => 
+                    sum + (post.analytics?.engagements || 0), 0
+                ),
+                totalImpressions: normalizedPosts.reduce((sum, post) => 
+                    sum + (post.analytics?.impressions || 0), 0
+                )
+            };
+
+            // Update output parameters
+            const outputParams = [...Params];
+            // TODO: Set output parameters based on result
+            
+            return {
+                Success: true,
+                Message: `Successfully retrieved ${normalizedPosts.length} posts`,
+                ResultCode: 'SUCCESS',
+                Params: outputParams
+            };
+
+        } catch (error) {
+            LogError(`Failed to get Facebook page posts: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            
+            if (this.isAuthError(error)) {
+                return this.handleOAuthError(error);
+            }
+
+            return {
+                Success: false,
+                Message: error instanceof Error ? error.message : 'Unknown error occurred',
+                ResultCode: 'ERROR'
+            };
+        }
+    }
+
+    /**
+     * Get post fields without insights (for faster queries or when insights not available)
+     */
+    private getPostFieldsWithoutInsights(): string {
+        return 'id,message,created_time,updated_time,from,story,permalink_url,attachments,shares,reactions.summary(true),comments.summary(true)';
+    }
+
+    /**
+     * Categorize posts by type based on attachments
+     */
+    private categorizePostTypes(posts: any[]): Record<string, number> {
+        const types: Record<string, number> = {
+            status: 0,
+            photo: 0,
+            video: 0,
+            link: 0,
+            event: 0,
+            offer: 0,
+            album: 0
+        };
+
+        for (const post of posts) {
+            if (post.attachments?.data?.[0]?.type) {
+                const type = post.attachments.data[0].type.toLowerCase();
+                if (type in types) {
+                    types[type]++;
+                } else {
+                    types.status++;
+                }
+            } else {
+                types.status++;
+            }
+        }
+
+        return types;
+    }
+
+
+}