Skip to content

Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.

6.6 KB
Raw Blame
import type { Account, ChannelThumbnails, SafeAccount } from './domain.ts';

// a video as normalizeYouTubeVideo() stores it in the videos: cache
export interface YouTubeVideo {
    videoId: string;
    title: string;
    description: string;
    publishedAt: string;
    channelTitle: string;
    thumbnails: { default: string; medium: string; high: string };
    tags: string[];
    categoryId: string;
    liveBroadcastContent: string;
    defaultAudioLanguage: string;
    duration: string;
    dimension: string;
    definition: string;
    caption: boolean;
    licensedContent: boolean;
    projection: string;
    viewCount: number;
    // null when the owner hides likes or turns comments off
    likeCount: number | null;
    commentCount: number | null;
    privacyStatus: string;
    embeddable: boolean;
    madeForKids: boolean;
}

export interface VideosCacheData {
    videos: YouTubeVideo[];
    fetchedAt: string;
}

// a channel as fetchChannelData() returns it; new accounts copy most of these fields
export interface YouTubeChannelData {
    channelId: string;
    title: string;
    description: string;
    customUrl: string;
    publishedAt: string;
    country: string;
    thumbnails: ChannelThumbnails;
    subscriberCount: number;
    viewCount: number;
    videoCount: number;
    hiddenSubscriberCount: boolean;
    uploadsPlaylistId: string;
    keywords: string;
    bannerUrl: string;
    madeForKids: boolean;
    topicCategories: string[];
    isLinked: boolean;
}

// a tracked YouTube video as fetchTrackedYouTubeData() returns it
export interface YouTubeTrackedVideoData {
    contentType: 'youtube';
    title: string;
    channelTitle: string;
    channelId: string;
    thumbnail: string;
    publishedAt: string;
    viewCount: number;
    likeCount: number | null;
    commentCount: number | null;
    isShort: boolean;
    permalink: string;
    lastFetchedAt: string;
}

// rates and percentages come from toFixed(), so they are strings, or the number 0 when there is nothing to divide by
export type FormattedRate = string | number;

export interface YouTubeVideoSummary {
    videoId: string;
    title: string;
    viewCount: number;
    likeCount: number | null;
    commentCount: number | null;
    publishedAt: string;
    thumbnail: string;
    engagementRate: FormattedRate;
    durationSeconds: number;
}

export interface YouTubeDurationDistribution {
    short: number;
    medium: number;
    long: number;
    veryLong: number;
}

export interface YouTubeTagCount {
    tag: string;
    count: number;
}

export interface YouTubeViewsDistribution {
    ranges: string[];
    counts: number[];
}

export interface YouTubeMonthlyViews {
    month: string;
    value: number;
    count: number;
}

export interface YouTubeMonthlyRate {
    month: string;
    value: FormattedRate;
}

export interface YouTubeMonthlyTrends {
    viewsTrend: YouTubeMonthlyViews[];
    engagementTrend: YouTubeMonthlyRate[];
    likeRateTrend: YouTubeMonthlyRate[];
}

// computeVideoAnalytics() output; the optional fields are missing when the channel has no videos
export interface VideoAnalytics extends YouTubeMonthlyTrends {
    totalVideos: number;
    totalViews: number;
    totalLikes: number;
    totalComments: number;
    avgViews: number;
    avgLikes: number;
    avgComments: number;
    medianViews: number;
    totalEngagement: number;
    overallEngagementRate: FormattedRate;
    avgDurationSeconds: number;
    avgDurationFormatted: string;
    totalDurationSeconds: number;
    totalDurationFormatted: string;
    estimatedTotalWatchTimeHours: number;
    bestByViews: YouTubeVideoSummary | null;
    bestByLikes: YouTubeVideoSummary | null;
    bestByComments: YouTubeVideoSummary | null;
    bestByEngagement: YouTubeVideoSummary | null;
    worstByViews: YouTubeVideoSummary | null;
    mostRecent: YouTubeVideoSummary | null;
    oldest: YouTubeVideoSummary | null;
    top10ByViews: YouTubeVideoSummary[];
    top10ByLikes: YouTubeVideoSummary[];
    top10ByComments: YouTubeVideoSummary[];
    top10ByEngagement: YouTubeVideoSummary[];
    shortsCount: number;
    regularCount: number;
    avgShortViews: number;
    avgRegularViews: number;
    avgShortLikes: number;
    avgRegularLikes: number;
    hdCount: number;
    sdCount: number;
    hdPercentage: string;
    captionCount: number;
    captionPercentage: string;
    licensedCount: number;
    licensedPercentage: string;
    madeForKidsCount: number;
    embeddableCount: number;
    embeddablePercentage: string;
    // keyed by day name and by UTC hour
    publishDayDistribution: Record<string, number>;
    publishHourDistribution: Record<string, number>;
    peakPublishDay: string;
    peakPublishHour: number;
    durationDistribution: YouTubeDurationDistribution;
    // keyed by YouTube category id, 'Unknown' when a video has none
    categoryDistribution: Record<string, number>;
    tagFrequency: YouTubeTagCount[];
    videosLast7Days: number;
    videosLast30Days: number;
    videosLast90Days: number;
    videosLast365Days: number;
    uploadFrequencyPerWeek: string;
    uploadFrequencyPerMonth: string;
    consistencyScore: number;
    viralityScore: number;
    viewsDistribution: YouTubeViewsDistribution;
}

// derived from the stored account by channelMetrics()
export interface YouTubeChannelMetrics {
    channelAge: number;
    channelAgeYears: string;
    viewsPerSubscriber: number;
    subscriberToViewRatio: number;
    avgViewsPerVideo: number;
    avgSubGainPerDay: number;
    avgViewsPerDay: number;
    estimatedMonthlyViews: number;
    estimatedMonthlySubGain: number;
    estimatedYearlyViews: number;
    estimatedYearlySubGain: number;
}

// GET /api/accounts/:id/analytics
export interface YouTubeAnalyticsPayload {
    success: true;
    channel: SafeAccount & YouTubeChannelMetrics;
    analytics: VideoAnalytics;
    videoCount: number;
}

export interface YouTubeAccountRankings<TAccount = Account> {
    bySubscribers: TAccount[];
    byViews: TAccount[];
    byVideos: TAccount[];
}

// accountComparison() output, which the MCP compare tool summarises
export interface YouTubeAccountComparison<TAccount = Account> {
    rankings: YouTubeAccountRankings<TAccount>;
    totals: { subscribers: number; views: number; videos: number };
    accountCount: number;
    bestBySubscribers: TAccount | null;
    bestByViews: TAccount | null;
    bestByVideos: TAccount | null;
}

// POST /api/resolve-channel
export interface ResolveChannelResponse {
    success: true;
    data: YouTubeChannelData;
}

// GET /api/accounts/:id/videos
export interface YouTubeVideosResponse {
    success: true;
    videos: YouTubeVideo[];
    fetchedAt: string;
}