🎬 Open-source, self-hosted AI agent that runs a YouTube channel end to end: researches topics, writes scripts, generates narration, visuals and video, optimizes SEO, and publishes after your approval, then learns from analytics. Works with Gemini, OpenAI, OpenRouter, DeepSeek and more.
JavaScript ai-agentsautomationcontent-automationcontent-creationcontent-strategygoogle-geminijavascriptnodejsopenaiself-hostedseo-optimizationsocial-media-automationthumbnail-generatorvideo-generationyoutube-apiyoutube-automationyoutube-botyoutube-channelyoutube-shortsyoutube-uploader
const { google } = require('googleapis');
const { Logger } = require('../utils/logger');
const { ChannelLearningEngine } = require('../utils/channel-learning-engine');
const CHANNEL_SNAPSHOT_CACHE_MS = 3 * 60 * 1000;
// Explains a googleapis failure in operator terms. A Google Cloud project must
// enable each API separately; OAuth consent alone is not enough.
function describeGoogleApiError(error, apiName) {
const body = error?.response?.data?.error || {};
const message = String(body.message || error?.message || 'Unknown error');
const reasons = (body.errors || []).map(item => item.reason).concat(body.status || []);
const activationUrl = (message.match(/https:\/\/console\.(?:developers|cloud)\.google\.com\/[^\s"']+/) || [])[0] || null;
if (activationUrl || reasons.some(reason => /accessNotConfigured|SERVICE_DISABLED/i.test(reason)) || /has not been used|is disabled/i.test(message)) {
return { reason: `${apiName} is not enabled for your Google Cloud project. Enable it, wait a minute, then refresh.`, activationUrl };
}
if (/insufficient.*scope/i.test(message) || reasons.some(reason => /insufficientPermissions|ACCESS_TOKEN_SCOPE_INSUFFICIENT/i.test(reason))) {
return { reason: `YouTube was connected without ${apiName} access. Reconnect YouTube with npm run walkthrough and approve every requested permission.`, activationUrl: null };
}
if (/invalid_grant/i.test(message)) {
return { reason: 'The YouTube authorization expired or was revoked. Reconnect YouTube with npm run walkthrough.', activationUrl: null };
}
return { reason: `${apiName} request failed: ${message.slice(0, 240)}`, activationUrl: null };
}
class AnalyticsOptimizationAgent {
constructor(db, credentials) {
this.db = db;
this.credentials = credentials;
this.logger = new Logger('AnalyticsOptimization');
this.youtubeAnalytics = null;
this.youtube = null;
this.performanceData = new Map();
this.learning = new ChannelLearningEngine(db);
}
async initialize() {
this.logger.info('Initializing Analytics & Optimization Agent...');
await this.setupAnalyticsAPI();
await this.loadHistoricalData();
return true;
}
async setupAnalyticsAPI() {
try {
const auth = this.credentials.getYouTubeAuth();
this.youtubeAnalytics = google.youtubeAnalytics({ version: 'v2', auth });
this.youtube = google.youtube({ version: 'v3', auth });
this.logger.info('YouTube Analytics API initialized');
} catch (error) {
this.logger.error('Failed to initialize Analytics API:', error);
throw error;
}
}
async loadHistoricalData() {
try {
const history = await this.db.getAnalyticsHistory();
history.forEach(record => {
const normalized = {
...record,
videoId: record.videoId || record.video_id,
analyzedAt: record.analyzedAt || record.analyzed_at,
performance: record.performance || {
score: record.performance_score || 0,
grade: record.performance_grade || 'N/A'
}
};
this.performanceData.set(normalized.videoId, normalized);
});
this.logger.info(`Loaded ${this.performanceData.size} historical records`);
} catch (error) {
this.logger.warn('No historical analytics data found');
}
}
async analyzeVideoPerformance(videoId, options = {}) {
try {
this.logger.info(`Analyzing performance for video: ${videoId}`);
// Get video details
const videoDetails = await this.getVideoDetails(videoId);
const measurementWindow = options.measurementWindow || 'rolling';
const period = this.learning.measurementPeriod(videoDetails.publishedAt, measurementWindow);
// Get analytics data
const channelStrategy = this.db.getChannelStrategy ? await this.db.getChannelStrategy() : null;
const analytics = await this.getVideoAnalytics(videoId, period, {
currency: channelStrategy?.outcome_currency || 'USD'
});
const context = await this.db.getPublishedContentContext(videoId);
// Fetch the granular retention curve separately so its absence never
// converts otherwise-real channel analytics into simulated data.
const retention = analytics.simulated
? { available: false, simulated: true, reason: 'base_analytics_unavailable', points: [] }
: await this.getAudienceRetention(videoId, period, videoDetails.duration);
// Analyze thumbnail performance
const thumbnailMetrics = await this.analyzeThumbnailPerformance(videoId, period);
// Analyze title and SEO performance
const seoMetrics = await this.analyzeSEOPerformance(videoDetails, analytics);
// Generate insights and recommendations
const insights = await this.generateInsights(videoDetails, analytics, thumbnailMetrics, seoMetrics);
const performanceReport = {
videoId,
videoDetails,
analytics,
retention,
thumbnailMetrics,
seoMetrics,
insights,
performance: this.calculatePerformanceScore(analytics),
measurementWindow,
analyzedAt: new Date().toISOString()
};
// Store in performance data
this.performanceData.set(videoId, performanceReport);
// Save to database
await this.db.saveAnalyticsReport(performanceReport);
performanceReport.learningSnapshot = await this.learning.capture(
performanceReport,
context,
measurementWindow
);
if (retention.available) {
performanceReport.retentionSnapshot = await this.learning.captureRetention(
{
...retention,
videoId,
title: videoDetails.title,
publishedAt: videoDetails.publishedAt
},
context,
measurementWindow,
{
views: analytics.views?.totalViews,
impressions: analytics.views?.totalImpressions
}
);
}
this.logger.info(`Analysis complete. Performance score: ${performanceReport.performance.score}/100`);
return performanceReport;
} catch (error) {
this.logger.error(`Failed to analyze video ${videoId}:`, error);
throw error;
}
}
async getVideoDetails(videoId) {
const response = await this.youtube.videos.list({
part: 'snippet,statistics,contentDetails',
id: videoId
});
if (!response.data.items.length) {
throw new Error(`Video not found: ${videoId}`);
}
const video = response.data.items[0];
return {
id: videoId,
title: video.snippet.title,
description: video.snippet.description,
tags: video.snippet.tags || [],
publishedAt: video.snippet.publishedAt,
duration: video.contentDetails.duration,
statistics: {
viewCount: parseInt(video.statistics.viewCount) || 0,
likeCount: parseInt(video.statistics.likeCount) || 0,
commentCount: parseInt(video.statistics.commentCount) || 0
}
};
}
async getVideoAnalytics(videoId, period = null, options = {}) {
const endDate = period?.endDate || new Date().toISOString().split('T')[0];
const startDate = period?.startDate || new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
try {
// Get various analytics metrics
const [
viewsData,
watchTimeData,
demographicsData,
trafficSourcesData,
deviceData,
outcomeData
] = await Promise.all([
this.getViewsAnalytics(videoId, startDate, endDate),
this.getWatchTimeAnalytics(videoId, startDate, endDate),
this.getDemographicsAnalytics(videoId, startDate, endDate),
this.getTrafficSourcesAnalytics(videoId, startDate, endDate),
this.getDeviceAnalytics(videoId, startDate, endDate),
this.getOutcomeAnalytics(videoId, startDate, endDate, options.currency || 'USD')
]);
return {
simulated: false,
period: { startDate, endDate },
views: viewsData,
watchTime: watchTimeData,
demographics: demographicsData,
trafficSources: trafficSourcesData,
devices: deviceData,
outcomes: outcomeData,
engagement: await this.calculateEngagementMetrics(videoId)
};
} catch (error) {
this.logger.error(`Failed to get analytics for ${videoId}:`, error);
return this.getSimulatedAnalytics(videoId);
}
}
async getViewsAnalytics(videoId, startDate, endDate) {
const response = await this.youtubeAnalytics.reports.query({
ids: 'channel==MINE',
startDate,
endDate,
metrics: 'views,impressions,impressionClickThroughRate',
dimensions: 'day',
filters: `video==${videoId}`
});
return {
totalViews: response.data.rows?.reduce((sum, row) => sum + row[1], 0) || 0,
totalImpressions: response.data.rows?.reduce((sum, row) => sum + row[2], 0) || 0,
averageCTR: this.calculateAverage(response.data.rows?.map(row => row[3]) || []),
dailyData: response.data.rows || []
};
}
async getWatchTimeAnalytics(videoId, startDate, endDate) {
const response = await this.youtubeAnalytics.reports.query({
ids: 'channel==MINE',
startDate,
endDate,
metrics: 'estimatedMinutesWatched,averageViewDuration,averageViewPercentage',
filters: `video==${videoId}`
});
const data = response.data.rows?.[0] || [0, 0, 0];
return {
totalWatchTime: data[0] || 0,
averageViewDuration: data[1] || 0,
averageViewPercentage: data[2] || 0,
retentionQuality: this.assessRetentionQuality(data[2])
};
}
async getDemographicsAnalytics(videoId, startDate, endDate) {
try {
const [ageResponse, genderResponse] = await Promise.all([
this.youtubeAnalytics.reports.query({
ids: 'channel==MINE',
startDate,
endDate,
metrics: 'viewerPercentage',
dimensions: 'ageGroup',
filters: `video==${videoId}`
}),
this.youtubeAnalytics.reports.query({
ids: 'channel==MINE',
startDate,
endDate,
metrics: 'viewerPercentage',
dimensions: 'gender',
filters: `video==${videoId}`
})
]);
return {
ageGroups: ageResponse.data.rows || [],
gender: genderResponse.data.rows || [],
primaryAudience: this.identifyPrimaryAudience(ageResponse.data.rows, genderResponse.data.rows)
};
} catch (error) {
return this.getSimulatedDemographics();
}
}
async getTrafficSourcesAnalytics(videoId, startDate, endDate) {
const response = await this.youtubeAnalytics.reports.query({
ids: 'channel==MINE',
startDate,
endDate,
metrics: 'views',
dimensions: 'insightTrafficSourceType',
filters: `video==${videoId}`
});
const sources = response.data.rows || [];
const totalViews = sources.reduce((sum, row) => sum + row[1], 0);
return {
sources: sources.map(row => ({
source: row[0],
views: row[1],
percentage: ((row[1] / totalViews) * 100).toFixed(1)
})),
topSource: sources.length > 0 ? sources[0][0] : 'unknown',
organicPercentage: this.calculateOrganicPercentage(sources)
};
}
async getDeviceAnalytics(videoId, startDate, endDate) {
const response = await this.youtubeAnalytics.reports.query({
ids: 'channel==MINE',
startDate,
endDate,
metrics: 'views',
dimensions: 'deviceType',
filters: `video==${videoId}`
});
const devices = response.data.rows || [];
const totalViews = devices.reduce((sum, row) => sum + row[1], 0);
return {
devices: devices.map(row => ({
device: row[0],
views: row[1],
percentage: ((row[1] / totalViews) * 100).toFixed(1)
})),
mobilePercentage: this.calculateMobilePercentage(devices)
};
}
async getOutcomeAnalytics(videoId, startDate, endDate, currency = 'USD') {
const query = (metrics, includeCurrency = false) => this.youtubeAnalytics.reports.query({
ids: 'channel==MINE',
startDate,
endDate,
metrics,
filters: `video==${videoId}`,
...(includeCurrency ? { currency } : {})
});
const [subscriberResult, revenueResult] = await Promise.allSettled([
query('subscribersGained,subscribersLost'),
query('estimatedRevenue,monetizedPlaybacks,playbackBasedCpm', true)
]);
const subscribers = subscriberResult.status === 'fulfilled'
? subscriberResult.value.data.rows?.[0] || [0, 0]
: null;
const revenue = revenueResult.status === 'fulfilled'
? revenueResult.value.data.rows?.[0] || [0, 0, 0]
: null;
if (!subscribers) this.logger.warn(`Subscriber outcomes unavailable for ${videoId}: ${subscriberResult.reason?.message || 'unknown error'}`);
if (!revenue) this.logger.info(`Revenue outcomes unavailable for ${videoId}; monetization data will remain unavailable`);
return {
subscribersAvailable: Boolean(subscribers),
subscribersGained: subscribers ? Number(subscribers[0] || 0) : null,
subscribersLost: subscribers ? Number(subscribers[1] || 0) : null,
netSubscribers: subscribers ? Number(subscribers[0] || 0) - Number(subscribers[1] || 0) : null,
revenueAvailable: Boolean(revenue),
currency: revenue ? currency : null,
estimatedRevenue: revenue ? Number(revenue[0] || 0) : null,
monetizedPlaybacks: revenue ? Number(revenue[1] || 0) : null,
playbackBasedCpm: revenue ? Number(revenue[2] || 0) : null
};
}
async calculateEngagementMetrics(videoId) {
const videoDetails = await this.getVideoDetails(videoId);
const stats = videoDetails.statistics;
const views = stats.viewCount || 0;
const likes = stats.likeCount || 0;
const comments = stats.commentCount || 0;
const interactions = likes + comments;
const engagementRate = views > 0 ? (interactions / views) * 100 : 0;
const likeRatio = interactions > 0 ? (likes / interactions) * 100 : 0;
const commentsPerView = views > 0 ? (comments / views) * 100 : 0;
return {
engagementRate: parseFloat(engagementRate.toFixed(2)),
likeRatio: parseFloat(likeRatio.toFixed(2)),
commentsPerView: commentsPerView.toFixed(4),
engagementQuality: this.assessEngagementQuality(engagementRate)
};
}
async analyzeThumbnailPerformance(videoId, period = null) {
// Analyze thumbnail click-through rate and impressions
try {
const response = await this.youtubeAnalytics.reports.query({
ids: 'channel==MINE',
startDate: period?.startDate || new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString().split('T')[0],
endDate: period?.endDate || new Date().toISOString().split('T')[0],
metrics: 'impressions,impressionClickThroughRate',
filters: `video==${videoId}`
});
const data = response.data.rows?.[0] || [0, 0];
const ctr = data[1] || 0;
return {
impressions: data[0] || 0,
clickThroughRate: ctr,
ctrQuality: this.assessCTRQuality(ctr),
recommendations: this.generateThumbnailRecommendations(ctr)
};
} catch (error) {
return {
impressions: 0,
clickThroughRate: 0,
ctrQuality: 'unknown',
recommendations: ['Unable to analyze thumbnail performance']
};
}
}
async analyzeSEOPerformance(videoDetails, analytics) {
const title = videoDetails.title;
const description = videoDetails.description;
const tags = videoDetails.tags;
// Analyze title effectiveness
const titleScore = this.scoreTitleEffectiveness(title, analytics.views.totalViews);
// Analyze description optimization
const descriptionScore = this.scoreDescriptionOptimization(description);
// Analyze tag relevance
const tagScore = this.scoreTagRelevance(tags, title);
// Search performance
const searchPerformance = this.analyzeSearchPerformance(analytics.trafficSources);
return {
titleScore,
descriptionScore,
tagScore,
searchPerformance,
overallSEOScore: Math.round((titleScore + descriptionScore + tagScore) / 3),
recommendations: this.generateSEORecommendations(titleScore, descriptionScore, tagScore, searchPerformance)
};
}
async generateInsights(videoDetails, analytics, thumbnailMetrics, seoMetrics) {
const insights = [];
// Performance insights
if (analytics.views.totalViews > 10000) {
insights.push({
type: 'success',
category: 'views',
message: 'Video is performing above average in terms of views',
impact: 'high'
});
} else if (analytics.views.totalViews < 1000) {
insights.push({
type: 'warning',
category: 'views',
message: 'Video views are below expected threshold',
impact: 'high',
recommendation: 'Consider promoting the video or optimizing SEO'
});
}
// Retention insights
if (analytics.watchTime.averageViewPercentage > 50) {
insights.push({
type: 'success',
category: 'retention',
message: 'Excellent audience retention rate',
impact: 'medium'
});
} else if (analytics.watchTime.averageViewPercentage < 30) {
insights.push({
type: 'critical',
category: 'retention',
message: 'Poor audience retention - viewers are dropping off early',
impact: 'high',
recommendation: 'Review content structure and pacing'
});
}
// Thumbnail insights
if (thumbnailMetrics.clickThroughRate > 8) {
insights.push({
type: 'success',
category: 'thumbnail',
message: 'Thumbnail is highly effective at driving clicks',
impact: 'high'
});
} else if (thumbnailMetrics.clickThroughRate < 3) {
insights.push({
type: 'warning',
category: 'thumbnail',
message: 'Thumbnail may not be compelling enough',
impact: 'high',
recommendation: 'Consider A/B testing different thumbnail designs'
});
}
// SEO insights
if (seoMetrics.overallSEOScore > 80) {
insights.push({
type: 'success',
category: 'seo',
message: 'Video is well-optimized for search',
impact: 'medium'
});
} else if (seoMetrics.overallSEOScore < 50) {
insights.push({
type: 'warning',
category: 'seo',
message: 'SEO optimization needs improvement',
impact: 'medium',
recommendation: 'Optimize title, description, and tags'
});
}
// Engagement insights
if (analytics.engagement.engagementRate > 5) {
insights.push({
type: 'success',
category: 'engagement',
message: 'High audience engagement',
impact: 'medium'
});
} else if (analytics.engagement.engagementRate < 1) {
insights.push({
type: 'warning',
category: 'engagement',
message: 'Low audience engagement',
impact: 'medium',
recommendation: 'Encourage more interaction in future videos'
});
}
return insights;
}
calculatePerformanceScore(analytics) {
let score = 0;
let maxScore = 0;
// Views score (30 points max)
const viewsScore = Math.min(30, (analytics.views.totalViews / 10000) * 30);
score += viewsScore;
maxScore += 30;
// Retention score (25 points max)
const retentionScore = (analytics.watchTime.averageViewPercentage / 100) * 25;
score += retentionScore;
maxScore += 25;
// Engagement score (25 points max)
const engagementScore = Math.min(25, analytics.engagement.engagementRate * 5);
score += engagementScore;
maxScore += 25;
// CTR score (20 points max)
const ctrScore = Math.min(20, analytics.views.averageCTR * 2);
score += ctrScore;
maxScore += 20;
const finalScore = Math.round((score / maxScore) * 100);
return {
score: finalScore,
breakdown: {
views: Math.round(viewsScore),
retention: Math.round(retentionScore),
engagement: Math.round(engagementScore),
ctr: Math.round(ctrScore)
},
grade: this.getPerformanceGrade(finalScore)
};
}
getPerformanceGrade(score) {
if (score >= 90) return 'A+';
if (score >= 80) return 'A';
if (score >= 70) return 'B';
if (score >= 60) return 'C';
if (score >= 50) return 'D';
return 'F';
}
// Helper methods
calculateAverage(values) {
if (!values.length) return 0;
return values.reduce((sum, val) => sum + val, 0) / values.length;
}
assessRetentionQuality(percentage) {
if (percentage > 60) return 'excellent';
if (percentage > 40) return 'good';
if (percentage > 25) return 'average';
return 'poor';
}
assessEngagementQuality(rate) {
if (rate > 8) return 'excellent';
if (rate > 5) return 'good';
if (rate > 2) return 'average';
return 'poor';
}
assessCTRQuality(ctr) {
if (ctr > 10) return 'excellent';
if (ctr > 6) return 'good';
if (ctr > 3) return 'average';
return 'poor';
}
scoreTitleEffectiveness(title, views) {
let score = 0;
// Length check
if (title.length >= 50 && title.length <= 70) score += 20;
else if (title.length >= 40 && title.length <= 80) score += 15;
else score += 10;
// Power words
const powerWords = ['ultimate', 'complete', 'secret', 'amazing', 'shocking', 'incredible'];
if (powerWords.some(word => title.toLowerCase().includes(word))) score += 15;
// Numbers
if (/\d+/.test(title)) score += 10;
// Emotional triggers
const emotionalWords = ['how', 'why', 'what', 'best', 'worst', 'never', 'always'];
if (emotionalWords.some(word => title.toLowerCase().includes(word))) score += 15;
// Performance correlation
if (views > 10000) score += 20;
else if (views > 1000) score += 10;
return Math.min(100, score);
}
scoreDescriptionOptimization(description) {
let score = 0;
if (description.length > 200) score += 20;
if (description.includes('http')) score += 15; // Has links
if (description.includes('TIMESTAMP') || description.includes('00:')) score += 15; // Has timestamps
if (description.split('\n').length > 5) score += 15; // Well formatted
if (description.length > 500) score += 10; // Comprehensive
// Keyword density check (simplified)
const wordCount = description.split(' ').length;
if (wordCount > 100) score += 15;
return Math.min(100, score);
}
scoreTagRelevance(tags, title) {
let score = 0;
if (tags.length >= 10) score += 20;
if (tags.length >= 5) score += 10;
// Tag-title relevance
const titleWords = title.toLowerCase().split(' ');
const relevantTags = tags.filter(tag =>
titleWords.some(word => tag.toLowerCase().includes(word))
);
if (relevantTags.length > 0) {
score += (relevantTags.length / tags.length) * 30;
}
// Long-tail keywords
const longTailTags = tags.filter(tag => tag.split(' ').length > 2);
if (longTailTags.length > 0) score += 20;
return Math.min(100, score);
}
analyzeSearchPerformance(trafficSources) {
const searchSources = trafficSources.sources.filter(source =>
['SEARCH', 'YOUTUBE_SEARCH'].includes(source.source)
);
const searchPercentage = searchSources.reduce((sum, source) =>
sum + parseFloat(source.percentage), 0
);
return {
searchPercentage,
searchQuality: searchPercentage > 20 ? 'good' : searchPercentage > 10 ? 'average' : 'poor',
organicDiscovery: searchPercentage > 30
};
}
generateThumbnailRecommendations(ctr) {
if (ctr > 8) return ['Thumbnail is performing excellently', 'Consider using similar design elements in future thumbnails'];
if (ctr > 5) return ['Good thumbnail performance', 'Minor optimizations may help'];
if (ctr > 3) return ['Average performance', 'Test brighter colors or more contrasting text'];
return ['Poor thumbnail performance', 'Consider A/B testing', 'Use more compelling imagery', 'Increase text contrast'];
}
generateSEORecommendations(titleScore, descriptionScore, tagScore, searchPerformance) {
const recommendations = [];
if (titleScore < 70) {
recommendations.push('Optimize title with power words and emotional triggers');
}
if (descriptionScore < 60) {
recommendations.push('Improve description with timestamps, links, and detailed content');
}
if (tagScore < 50) {
recommendations.push('Use more relevant tags and long-tail keywords');
}
if (searchPerformance.searchPercentage < 15) {
recommendations.push('Focus on search optimization to improve organic discovery');
}
return recommendations;
}
// Simulation methods for when API is not available
getSimulatedAnalytics(_videoId) {
return {
simulated: true,
views: { totalViews: Math.floor(Math.random() * 50000), averageCTR: Math.random() * 10 },
watchTime: { averageViewPercentage: Math.random() * 100 },
engagement: { engagementRate: Math.random() * 10 },
trafficSources: { sources: [{ source: 'SEARCH', percentage: '30' }] },
outcomes: {
subscribersAvailable: false, subscribersGained: null, subscribersLost: null,
netSubscribers: null, revenueAvailable: false, estimatedRevenue: null,
monetizedPlaybacks: null, playbackBasedCpm: null
}
};
}
getSimulatedDemographics() {
return {
ageGroups: [['18-24', 30], ['25-34', 40], ['35-44', 20]],
gender: [['male', 60], ['female', 40]],
primaryAudience: 'Males 25-34'
};
}
identifyPrimaryAudience(ageGroups, gender) {
const topAge = ageGroups?.[0]?.[0] || '25-34';
const topGender = gender?.[0]?.[0] || 'male';
return `${topGender}s ${topAge}`;
}
calculateOrganicPercentage(sources) {
const organicSources = ['SEARCH', 'YOUTUBE_SEARCH', 'SUGGESTED_VIDEO'];
return sources
.filter(row => organicSources.includes(row[0]))
.reduce((sum, row) => sum + row[1], 0);
}
calculateMobilePercentage(devices) {
const mobileDevices = devices.filter(row =>
['MOBILE', 'TABLET'].includes(row[0])
);
const total = devices.reduce((sum, row) => sum + row[1], 0);
const mobile = mobileDevices.reduce((sum, row) => sum + row[1], 0);
return total > 0 ? ((mobile / total) * 100).toFixed(1) : '0';
}
async getRecentAnalytics(days = 7) {
const recentReports = Array.from(this.performanceData.values())
.filter(report => {
const reportDate = new Date(report.analyzedAt);
const cutoffDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
return reportDate > cutoffDate;
})
.sort((a, b) => new Date(b.analyzedAt) - new Date(a.analyzedAt));
return {
totalVideos: recentReports.length,
averagePerformanceScore: this.calculateAverageScore(recentReports),
topPerformers: recentReports.slice(0, 5),
insights: this.generateChannelInsights(recentReports)
};
}
// Channel-wide totals read straight from YouTube, whichever tool published
// the videos. getRecentAnalytics only covers videos this agent analyzed, which
// reads as "0" for an established channel. Unavailable data is reported with
// a reason and null values, never as a zero.
async getChannelSnapshot({ refresh = false } = {}) {
const cached = this.channelSnapshotCache;
if (!refresh && cached && Date.now() - cached.cachedAt < CHANNEL_SNAPSHOT_CACHE_MS) return cached.value;
if (!this.youtube) {
return { available: false, reason: 'Connect YouTube with npm run walkthrough to see channel statistics.' };
}
let channel;
try {
const response = await this.youtube.channels.list({ part: ['snippet', 'statistics'], mine: true });
channel = response.data.items?.[0];
} catch (error) {
return { available: false, reason: describeGoogleApiError(error, 'YouTube Data API').reason };
}
if (!channel) {
return { available: false, reason: 'The connected Google account does not own a YouTube channel.' };
}
const stats = channel.statistics || {};
const count = value => (value === undefined || value === null ? null : Number(value));
const value = {
available: true,
fetchedAt: new Date().toISOString(),
channel: {
id: channel.id,
title: channel.snippet?.title || null,
subscribers: stats.hiddenSubscriberCount ? null : count(stats.subscriberCount),
subscribersHidden: Boolean(stats.hiddenSubscriberCount),
views: count(stats.viewCount),
videos: count(stats.videoCount)
},
recent: await this.getChannelRecentMetrics()
};
this.channelSnapshotCache = { cachedAt: Date.now(), value };
return value;
}
async getChannelRecentMetrics() {
// YouTube Analytics lags about two days, so the 28-day window ends two days ago.
const day = 24 * 60 * 60 * 1000;
const end = new Date(Date.now() - 2 * day);
const startDate = new Date(end.getTime() - 27 * day).toISOString().split('T')[0];
const endDate = end.toISOString().split('T')[0];
try {
const response = await this.youtubeAnalytics.reports.query({
ids: 'channel==MINE',
startDate,
endDate,
metrics: 'views,estimatedMinutesWatched,subscribersGained,subscribersLost'
});
const headers = (response.data.columnHeaders || []).map(header => header.name);
const row = response.data.rows?.[0] || [];
const metric = name => {
const position = headers.indexOf(name);
return position >= 0 ? Number(row[position] || 0) : 0;
};
const gained = metric('subscribersGained');
const lost = metric('subscribersLost');
return {
available: true,
startDate,
endDate,
views: metric('views'),
watchHours: Math.round(metric('estimatedMinutesWatched') / 6) / 10,
subscribersGained: gained,
subscribersLost: lost,
netSubscribers: gained - lost
};
} catch (error) {
const { reason, activationUrl } = describeGoogleApiError(error, 'YouTube Analytics API');
this.logger.warn(`Channel analytics unavailable: ${reason}`);
return { available: false, startDate, endDate, reason, activationUrl };
}
}
async getAudienceRetention(videoId, period = null, isoDuration = null) {
const endDate = period?.endDate || new Date().toISOString().split('T')[0];
const startDate = period?.startDate || new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
try {
const response = await this.youtubeAnalytics.reports.query({
ids: 'channel==MINE',
startDate,
endDate,
metrics: 'audienceWatchRatio,relativeRetentionPerformance,startedWatching,stoppedWatching,totalSegmentImpressions',
dimensions: 'elapsedVideoTimeRatio',
filters: `video==${videoId}`
});
const headers = (response.data.columnHeaders || []).map(header => header.name);
const index = name => headers.indexOf(name);
const value = (row, name) => {
const position = index(name);
return position >= 0 ? Number(row[position] || 0) : 0;
};
const points = (response.data.rows || []).map(row => ({
elapsedRatio: value(row, 'elapsedVideoTimeRatio'),
audienceWatchRatio: value(row, 'audienceWatchRatio'),
relativeRetentionPerformance: value(row, 'relativeRetentionPerformance'),
startedWatching: value(row, 'startedWatching'),
stoppedWatching: value(row, 'stoppedWatching'),
totalSegmentImpressions: value(row, 'totalSegmentImpressions')
})).filter(point => point.elapsedRatio > 0);
return {
available: points.length > 0,
simulated: false,
reason: points.length ? null : 'no_retention_rows',
period: { startDate, endDate },
durationSeconds: this.parseISODurationSeconds(isoDuration),
points
};
} catch (error) {
this.logger.warn(`Audience retention curve unavailable for ${videoId}: ${error.message}`);
return { available: false, simulated: false, reason: 'retention_api_unavailable', points: [] };
}
}
parseISODurationSeconds(value) {
const match = String(value || '').match(/^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/);
if (!match) return 0;
return Number(match[1] || 0) * 86400 + Number(match[2] || 0) * 3600 + Number(match[3] || 0) * 60 + Number(match[4] || 0);
}
getLearningSummary() {
return this.learning.getSummary();
}
getDueMeasurementWindows(video) {
return this.learning.getDueMeasurementWindows(video);
}
calculateAverageScore(reports) {
if (!reports.length) return 0;
const total = reports.reduce((sum, report) => sum + report.performance.score, 0);
return Math.round(total / reports.length);
}
generateChannelInsights(reports) {
if (!reports.length) return [];
const insights = [];
const avgScore = this.calculateAverageScore(reports);
if (avgScore > 80) {
insights.push('Channel is performing excellently across all metrics');
} else if (avgScore < 50) {
insights.push('Channel performance needs significant improvement');
}
// Analyze common issues
const lowRetentionVideos = reports.filter(r =>
r.analytics.watchTime.averageViewPercentage < 30
).length;
if (lowRetentionVideos > reports.length * 0.5) {
insights.push('Multiple videos showing poor retention - review content quality');
}
return insights;
}
}
module.exports = { AnalyticsOptimizationAgent };