bulltrackers-module 1.0.733 → 1.0.734

package/functions/computation-system-v2/rules/social.js

@@ -0,0 +1,562 @@
+/**
+ * @fileoverview Social & Engagement Business Rules
+ * 
+ * For extracting and analyzing social data:
+ * - social_post_snapshots (posts, engagement)
+ * - pi_ratings (reviews, ratings)
+ * - pi_page_views (profile views)
+ * 
+ * Usage in computation:
+ * ```javascript
+ * const posts = rules.social.extractPosts(row);
+ * const engagement = rules.social.calculateEngagement(posts);
+ * const rating = rules.social.getAverageRating(ratingsRow);
+ * ```
+ */
+
+// =============================================================================
+// POSTS - social_post_snapshots
+// =============================================================================
+
+/**
+ * Extract posts from a social_post_snapshots row.
+ * @param {Object} row - social_post_snapshots row
+ * @returns {Array} Array of post objects
+ */
+function extractPosts(row) {
+    if (!row) return [];
+    
+    let data = row.posts_data;
+    
+    if (typeof data === 'string') {
+        try {
+            data = JSON.parse(data);
+        } catch (e) {
+            return [];
+        }
+    }
+    
+    // Posts are in a map keyed by post ID
+    const postsMap = data?.posts;
+    if (!postsMap || typeof postsMap !== 'object') return [];
+    
+    return Object.values(postsMap);
+}
+
+/**
+ * Get user ID from posts row.
+ * @param {Object} row - social_post_snapshots row
+ * @returns {string|null}
+ */
+function getPostsUserId(row) {
+    if (!row) return null;
+    
+    if (row.user_id) return String(row.user_id);
+    
+    let data = row.posts_data;
+    if (typeof data === 'string') {
+        try {
+            data = JSON.parse(data);
+        } catch (e) {
+            return null;
+        }
+    }
+    
+    return data?.cid ? String(data.cid) : null;
+}
+
+/**
+ * Get post count from row.
+ * @param {Object} row - social_post_snapshots row
+ * @returns {number}
+ */
+function getPostCount(row) {
+    if (!row) return 0;
+    
+    let data = row.posts_data;
+    if (typeof data === 'string') {
+        try {
+            data = JSON.parse(data);
+        } catch (e) {
+            return 0;
+        }
+    }
+    
+    return data?.postCount ?? 0;
+}
+
+/**
+ * Get post text.
+ * @param {Object} post - Post object
+ * @returns {string}
+ */
+function getPostText(post) {
+    return post?.text || '';
+}
+
+/**
+ * Get post creation date.
+ * @param {Object} post - Post object
+ * @returns {Date|null}
+ */
+function getPostDate(post) {
+    return post?.createdAt ? new Date(post.createdAt) : null;
+}
+
+/**
+ * Get post likes count.
+ * @param {Object} post - Post object
+ * @returns {number}
+ */
+function getPostLikes(post) {
+    return post?.stats?.likes ?? 0;
+}
+
+/**
+ * Get post comments count.
+ * @param {Object} post - Post object
+ * @returns {number}
+ */
+function getPostComments(post) {
+    return post?.stats?.comments ?? 0;
+}
+
+/**
+ * Get total engagement (likes + comments).
+ * @param {Object} post - Post object
+ * @returns {number}
+ */
+function getPostEngagement(post) {
+    return getPostLikes(post) + getPostComments(post);
+}
+
+/**
+ * Get post ID.
+ * @param {Object} post - Post object
+ * @returns {string|null}
+ */
+function getPostId(post) {
+    return post?.id || null;
+}
+
+/**
+ * Extract mentioned tickers from post text.
+ * Looks for $TICKER patterns.
+ * @param {Object} post - Post object
+ * @returns {string[]}
+ */
+function extractMentionedTickers(post) {
+    const text = getPostText(post);
+    const matches = text.match(/\$([A-Z0-9.]+)/g) || [];
+    return [...new Set(matches.map(m => m.substring(1)))];
+}
+
+/**
+ * Calculate total engagement for all posts.
+ * @param {Array} posts - Array of posts
+ * @returns {Object}
+ */
+function calculateEngagement(posts) {
+    if (!posts || posts.length === 0) {
+        return {
+            totalPosts: 0,
+            totalLikes: 0,
+            totalComments: 0,
+            totalEngagement: 0,
+            avgLikesPerPost: 0,
+            avgCommentsPerPost: 0,
+            avgEngagementPerPost: 0
+        };
+    }
+    
+    const totalLikes = posts.reduce((sum, p) => sum + getPostLikes(p), 0);
+    const totalComments = posts.reduce((sum, p) => sum + getPostComments(p), 0);
+    
+    return {
+        totalPosts: posts.length,
+        totalLikes,
+        totalComments,
+        totalEngagement: totalLikes + totalComments,
+        avgLikesPerPost: totalLikes / posts.length,
+        avgCommentsPerPost: totalComments / posts.length,
+        avgEngagementPerPost: (totalLikes + totalComments) / posts.length
+    };
+}
+
+/**
+ * Get most engaged posts.
+ * @param {Array} posts - Array of posts
+ * @param {number} count - Number to return
+ * @returns {Array}
+ */
+function getMostEngagedPosts(posts, count = 5) {
+    return [...posts]
+        .sort((a, b) => getPostEngagement(b) - getPostEngagement(a))
+        .slice(0, count);
+}
+
+/**
+ * Get recent posts.
+ * @param {Array} posts - Array of posts
+ * @param {number} count - Number to return
+ * @returns {Array}
+ */
+function getRecentPosts(posts, count = 5) {
+    return [...posts]
+        .sort((a, b) => {
+            const dateA = getPostDate(a);
+            const dateB = getPostDate(b);
+            return (dateB || 0) - (dateA || 0);
+        })
+        .slice(0, count);
+}
+
+/**
+ * Calculate posting frequency (posts per week).
+ * @param {Array} posts - Array of posts
+ * @returns {number}
+ */
+function calculatePostFrequency(posts) {
+    if (!posts || posts.length < 2) return 0;
+    
+    const dates = posts
+        .map(getPostDate)
+        .filter(d => d)
+        .sort((a, b) => a - b);
+    
+    if (dates.length < 2) return 0;
+    
+    const daySpan = (dates[dates.length - 1] - dates[0]) / (1000 * 60 * 60 * 24);
+    if (daySpan === 0) return posts.length; // All same day
+    
+    return (posts.length / daySpan) * 7;
+}
+
+// =============================================================================
+// RATINGS - pi_ratings
+// =============================================================================
+
+/**
+ * Get average rating from pi_ratings row.
+ * @param {Object} row - pi_ratings row
+ * @returns {number}
+ */
+function getAverageRating(row) {
+    return row?.average_rating ?? 0;
+}
+
+/**
+ * Get total ratings count.
+ * @param {Object} row - pi_ratings row
+ * @returns {number}
+ */
+function getTotalRatings(row) {
+    return row?.total_ratings ?? 0;
+}
+
+/**
+ * Extract reviews from pi_ratings row.
+ * @param {Object} row - pi_ratings row
+ * @returns {Array}
+ */
+function extractReviews(row) {
+    if (!row) return [];
+    
+    let reviews = row.reviews;
+    
+    if (typeof reviews === 'string') {
+        try {
+            reviews = JSON.parse(reviews);
+        } catch (e) {
+            return [];
+        }
+    }
+    
+    return Array.isArray(reviews) ? reviews : [];
+}
+
+/**
+ * Get ratings by user map.
+ * @param {Object} row - pi_ratings row
+ * @returns {Object} Map of userId -> rating
+ */
+function getRatingsByUser(row) {
+    if (!row) return {};
+    
+    let ratings = row.ratings_by_user;
+    
+    if (typeof ratings === 'string') {
+        try {
+            ratings = JSON.parse(ratings);
+        } catch (e) {
+            return {};
+        }
+    }
+    
+    return ratings || {};
+}
+
+/**
+ * Get review comment.
+ * @param {Object} review - Review object
+ * @returns {string}
+ */
+function getReviewComment(review) {
+    return review?.comment || '';
+}
+
+/**
+ * Get review rating (1-5).
+ * @param {Object} review - Review object
+ * @returns {number}
+ */
+function getReviewRating(review) {
+    return review?.rating ?? 0;
+}
+
+/**
+ * Get review date.
+ * @param {Object} review - Review object
+ * @returns {Date|null}
+ */
+function getReviewDate(review) {
+    return review?.createdAt ? new Date(review.createdAt) : null;
+}
+
+/**
+ * Get reviewer username.
+ * @param {Object} review - Review object
+ * @returns {string|null}
+ */
+function getReviewerUsername(review) {
+    return review?.reviewerUsername || null;
+}
+
+/**
+ * Check if review is anonymous.
+ * @param {Object} review - Review object
+ * @returns {boolean}
+ */
+function isReviewAnonymous(review) {
+    return review?.isAnonymous === true;
+}
+
+/**
+ * Calculate rating distribution.
+ * @param {Array} reviews - Array of reviews
+ * @returns {Object} Map of rating -> count
+ */
+function calculateRatingDistribution(reviews) {
+    const distribution = { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 };
+    
+    for (const review of reviews) {
+        const rating = getReviewRating(review);
+        if (rating >= 1 && rating <= 5) {
+            distribution[rating]++;
+        }
+    }
+    
+    return distribution;
+}
+
+/**
+ * Get recent reviews.
+ * @param {Array} reviews - Array of reviews
+ * @param {number} count - Number to return
+ * @returns {Array}
+ */
+function getRecentReviews(reviews, count = 5) {
+    return [...reviews]
+        .sort((a, b) => {
+            const dateA = getReviewDate(a);
+            const dateB = getReviewDate(b);
+            return (dateB || 0) - (dateA || 0);
+        })
+        .slice(0, count);
+}
+
+// =============================================================================
+// PAGE VIEWS - pi_page_views
+// =============================================================================
+
+/**
+ * Get total views from pi_page_views row.
+ * @param {Object} row - pi_page_views row
+ * @returns {number}
+ */
+function getTotalViews(row) {
+    return row?.total_views ?? 0;
+}
+
+/**
+ * Get unique viewers count.
+ * @param {Object} row - pi_page_views row
+ * @returns {number}
+ */
+function getUniqueViewers(row) {
+    return row?.unique_viewers ?? 0;
+}
+
+/**
+ * Extract views by user map.
+ * @param {Object} row - pi_page_views row
+ * @returns {Object} Map of userId -> viewData
+ */
+function extractViewsByUser(row) {
+    if (!row) return {};
+    
+    let views = row.views_by_user;
+    
+    if (typeof views === 'string') {
+        try {
+            views = JSON.parse(views);
+        } catch (e) {
+            return {};
+        }
+    }
+    
+    return views || {};
+}
+
+/**
+ * Get view count for a specific user.
+ * @param {Object} viewsByUser - views_by_user map
+ * @param {string} userId - User ID
+ * @returns {number}
+ */
+function getViewCountForUser(viewsByUser, userId) {
+    return viewsByUser?.[userId]?.viewCount ?? 0;
+}
+
+/**
+ * Get last viewed timestamp for a specific user.
+ * @param {Object} viewsByUser - views_by_user map
+ * @param {string} userId - User ID
+ * @returns {Date|null}
+ */
+function getLastViewedForUser(viewsByUser, userId) {
+    const lastViewed = viewsByUser?.[userId]?.lastViewed;
+    if (!lastViewed) return null;
+    
+    // Handle Firestore timestamp format
+    if (lastViewed._seconds) {
+        return new Date(lastViewed._seconds * 1000 + (lastViewed._nanoseconds || 0) / 1000000);
+    }
+    
+    return new Date(lastViewed);
+}
+
+/**
+ * Calculate view metrics.
+ * @param {Object} row - pi_page_views row
+ * @returns {Object}
+ */
+function calculateViewMetrics(row) {
+    const total = getTotalViews(row);
+    const unique = getUniqueViewers(row);
+    const viewsByUser = extractViewsByUser(row);
+    
+    const userIds = Object.keys(viewsByUser);
+    const viewCounts = userIds.map(id => getViewCountForUser(viewsByUser, id));
+    
+    return {
+        totalViews: total,
+        uniqueViewers: unique,
+        avgViewsPerViewer: unique > 0 ? total / unique : 0,
+        maxViewsByUser: viewCounts.length > 0 ? Math.max(...viewCounts) : 0,
+        repeatViewers: viewCounts.filter(c => c > 1).length
+    };
+}
+
+// =============================================================================
+// COMBINED SOCIAL SCORE
+// =============================================================================
+
+/**
+ * Calculate a social engagement score (0-100).
+ * @param {Object} options - Data sources
+ * @param {Object} [options.postsRow] - social_post_snapshots row
+ * @param {Object} [options.ratingsRow] - pi_ratings row
+ * @param {Object} [options.viewsRow] - pi_page_views row
+ * @returns {number}
+ */
+function calculateSocialScore(options = {}) {
+    let score = 50;  // Base score
+    
+    // Posts engagement (+/- 15)
+    if (options.postsRow) {
+        const posts = extractPosts(options.postsRow);
+        const engagement = calculateEngagement(posts);
+        
+        if (engagement.avgEngagementPerPost >= 5) score += 15;
+        else if (engagement.avgEngagementPerPost >= 2) score += 7;
+        else if (engagement.totalPosts === 0) score -= 10;
+    }
+    
+    // Ratings (+/- 20)
+    if (options.ratingsRow) {
+        const avgRating = getAverageRating(options.ratingsRow);
+        const totalRatings = getTotalRatings(options.ratingsRow);
+        
+        if (avgRating >= 4.5 && totalRatings >= 5) score += 20;
+        else if (avgRating >= 4.0 && totalRatings >= 3) score += 10;
+        else if (avgRating < 3.0 && totalRatings >= 3) score -= 15;
+        else if (totalRatings === 0) score -= 5;
+    }
+    
+    // Page views (+/- 15)
+    if (options.viewsRow) {
+        const metrics = calculateViewMetrics(options.viewsRow);
+        
+        if (metrics.uniqueViewers >= 50) score += 15;
+        else if (metrics.uniqueViewers >= 20) score += 7;
+        else if (metrics.uniqueViewers < 5) score -= 5;
+        
+        // Repeat viewers bonus
+        if (metrics.repeatViewers >= 10) score += 5;
+    }
+    
+    return Math.max(0, Math.min(100, score));
+}
+
+module.exports = {
+    // Posts
+    extractPosts,
+    getPostsUserId,
+    getPostCount,
+    getPostText,
+    getPostDate,
+    getPostLikes,
+    getPostComments,
+    getPostEngagement,
+    getPostId,
+    extractMentionedTickers,
+    calculateEngagement,
+    getMostEngagedPosts,
+    getRecentPosts,
+    calculatePostFrequency,
+    
+    // Ratings
+    getAverageRating,
+    getTotalRatings,
+    extractReviews,
+    getRatingsByUser,
+    getReviewComment,
+    getReviewRating,
+    getReviewDate,
+    getReviewerUsername,
+    isReviewAnonymous,
+    calculateRatingDistribution,
+    getRecentReviews,
+    
+    // Page views
+    getTotalViews,
+    getUniqueViewers,
+    extractViewsByUser,
+    getViewCountForUser,
+    getLastViewedForUser,
+    calculateViewMetrics,
+    
+    // Combined
+    calculateSocialScore
+};