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.1 KB
Raw Blame
import { fetchAllVideos } from './youtube/youtubeVideos.ts';
import { fetchChannelData } from './youtube/youtubeChannels.ts';
import { computeVideoAnalytics } from './youtube/youtubeAnalytics.ts';
import { channelMetrics, accountComparison } from './youtube/youtubeLibrary.ts';
import { NO_YOUTUBE_KEY_MESSAGE } from './accountService.ts';
import { NotConfiguredError, NotFoundError, ValidationError } from '../lib/errors.ts';
import { errorFields } from '../lib/logger.ts';
import { safeAccount } from '../lib/safeAccount.ts';
import { UNMETERED_YOUTUBE_QUOTA } from './youtubeQuotaService.ts';
import type { AccountRepository } from '../repositories/accountRepository.ts';
import type { AnalyticsCacheRepository } from '../repositories/analyticsCacheRepository.ts';
import type { AppConfig } from '../lib/config.ts';
import type { YouTubeQuotaService } from './youtubeQuotaService.ts';
import type { YouTubeKey } from './youtube/youtubeApi.ts';
import type { RequestContext } from '../types/context.ts';
import type { Account, SafeAccount } from '../../shared/types/domain.ts';
import type {
    VideoAnalytics, YouTubeAccountComparison, YouTubeChannelMetrics, YouTubeVideo,
} from '../../shared/types/youtube.ts';

export interface YouTubeAnalyticsDeps {
    accounts: AccountRepository;
    cache: AnalyticsCacheRepository;
    config: AppConfig;
    context: RequestContext;
    youtubeQuota?: YouTubeQuotaService;
}

export interface ChannelAnalytics {
    channel: SafeAccount & YouTubeChannelMetrics;
    analytics: VideoAnalytics;
    videoCount: number;
}

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

export interface YouTubeAnalyticsService {
    channelAnalytics(userId: string, accountId: string): Promise<ChannelAnalytics>;
    channelVideos(userId: string, accountId: string, options?: { fresh?: boolean }): Promise<ChannelVideos>;
    comparison(userId: string): Promise<YouTubeAccountComparison<SafeAccount> | null>;
}

const MAX_PLAYLIST_PAGES = 10;
const NO_PLAYLIST_MESSAGE = 'No uploads playlist stored - delete this channel and add it again';

export function createYouTubeAnalyticsService({ accounts, cache, config, context, youtubeQuota = UNMETERED_YOUTUBE_QUOTA }: YouTubeAnalyticsDeps): YouTubeAnalyticsService {
    const { signal, log } = context;

    function youtubeKey(): string {
        if (!config.youtubeApiKey) throw new NotConfiguredError(NO_YOUTUBE_KEY_MESSAGE);
        return config.youtubeApiKey;
    }

    async function findChannel(userId: string, accountId: string): Promise<Account & { uploadsPlaylistId: string }> {
        const account = await accounts.findForUser(accountId, userId);
        if (!account || account.platform !== 'youtube') throw new NotFoundError('YouTube channel not found');
        if (!account.uploadsPlaylistId) throw new ValidationError(NO_PLAYLIST_MESSAGE);
        return { ...account, uploadsPlaylistId: account.uploadsPlaylistId };
    }

    async function fetchAndCacheVideos(userId: string, accountId: string, playlistId: string, apiKey: YouTubeKey): Promise<ChannelVideos> {
        const videos = await fetchAllVideos(playlistId, apiKey, MAX_PLAYLIST_PAGES, signal);
        const fetchedAt = new Date().toISOString();
        await cache.setVideos(userId, accountId, { videos, fetchedAt });
        return { videos, fetchedAt };
    }

    // fills creation dates on older accounts once; a failure only skips the extras
    async function backfillChannelData(userId: string, account: Account, apiKey: YouTubeKey): Promise<Account> {
        if (!account.channelId) return account;
        try {
            const channelData = await fetchChannelData(account.channelId, apiKey, signal);
            const updates: Partial<Account> = {
                publishedAt: channelData.publishedAt,
                subscriberCount: channelData.subscriberCount,
                viewCount: channelData.viewCount,
                videoCount: channelData.videoCount,
                title: channelData.title,
                thumbnails: channelData.thumbnails,
                customUrl: channelData.customUrl,
                country: channelData.country,
                lastUpdated: new Date().toISOString(),
            };
            await accounts.updateForUser(account.id, updates, userId);
            return { ...account, ...updates };
        } catch (err) {
            log.warn('channel backfill skipped', { accountId: account.id, ...errorFields(err) });
            return account;
        }
    }

    return {
        async channelAnalytics(userId, accountId) {
            const apiKey = youtubeKey();
            const account = await findChannel(userId, accountId);
            return youtubeQuota.run(userId, apiKey, async key => {
                const { videos } = await fetchAndCacheVideos(userId, accountId, account.uploadsPlaylistId, key);
                const analytics = computeVideoAnalytics(videos);
                const channel = account.publishedAt ? account : await backfillChannelData(userId, account, key);
                return { channel: { ...safeAccount(channel), ...channelMetrics(channel) }, analytics, videoCount: videos.length };
            });
        },

        // served from the cache when it has the channel, without spending quota, unless a person asked for fresh data
        async channelVideos(userId, accountId, { fresh = false } = {}) {
            if (!fresh) {
                const cached = await cache.getVideos(userId, accountId);
                if (cached?.videos) return { videos: cached.videos, fetchedAt: cached.fetchedAt };
            }
            const apiKey = youtubeKey();
            const account = await findChannel(userId, accountId);
            return youtubeQuota.run(userId, apiKey, key => fetchAndCacheVideos(userId, accountId, account.uploadsPlaylistId, key));
        },

        // only channels have the counts being ranked, and stored secrets never leave the Worker
        async comparison(userId) {
            const channels = (await accounts.listForUser(userId)).filter(account => account.platform === 'youtube').map(safeAccount);
            return channels.length === 0 ? null : accountComparison(channels);
        },

    };
}