@yoonion/mimi-seed-mcp 0.19.13 → 0.19.17

package/dist/video/youtube-publish.d.ts

@@ -4,6 +4,7 @@ import { validateVideo } from './render.js';
 export declare const YOUTUBE_SCOPE = "https://www.googleapis.com/auth/youtube.force-ssl";
 export type YouTubePrivacyStatus = 'private' | 'unlisted' | 'public';
 export interface UploadYouTubeVideoInput {
+    expectedChannelId: string;
     filePath: string;
     title: string;
     description?: string;
@@ -36,7 +37,10 @@ declare function assertShortsCompatible(facts: ReturnType<typeof videoFacts>): v
 export declare function getYouTubeVideoStatus(auth: OAuth2Client, videoId: string): Promise<{
     videoId: string | null;
     title: string | null;
+    channelId: string | null;
+    channelTitle: string | null;
     privacyStatus: string | null;
+    publishAt: string | null;
     uploadStatus: string | null;
     processingStatus: string | null;
     processingProgress: youtube_v3.Schema$VideoProcessingDetailsProcessingProgress | null;
@@ -46,6 +50,10 @@ export declare function getYouTubeVideoStatus(auth: OAuth2Client, videoId: strin
     studioUrl: string | null;
 }>;
 export declare function uploadYouTubeVideo(auth: OAuth2Client, input: UploadYouTubeVideoInput): Promise<{
+    authenticatedChannel: {
+        id: string;
+        title: string;
+    };
     requestedPrivacyStatus: YouTubePrivacyStatus;
     file: {
         width?: number;
@@ -57,7 +65,10 @@ export declare function uploadYouTubeVideo(auth: OAuth2Client, input: UploadYouT
     validationWarnings: string[];
     videoId: string | null;
     title: string | null;
+    channelId: string | null;
+    channelTitle: string | null;
     privacyStatus: string | null;
+    publishAt: string | null;
     uploadStatus: string | null;
     processingStatus: string | null;
     processingProgress: youtube_v3.Schema$VideoProcessingDetailsProcessingProgress | null;
@@ -69,7 +80,10 @@ export declare function uploadYouTubeVideo(auth: OAuth2Client, input: UploadYouT
 export declare function updateYouTubeVideoPrivacy(auth: OAuth2Client, input: UpdateYouTubePrivacyInput): Promise<{
     videoId: string | null;
     title: string | null;
+    channelId: string | null;
+    channelTitle: string | null;
     privacyStatus: string | null;
+    publishAt: string | null;
     uploadStatus: string | null;
     processingStatus: string | null;
     processingProgress: youtube_v3.Schema$VideoProcessingDetailsProcessingProgress | null;

package/dist/video/youtube-publish.js

@@ -1,3 +1,4 @@
+import { verifyYouTubeChannel } from '../auth/youtube-channel.js';
 import { createReadStream, existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { google } from '../lib/googleapis-lite.js';
@@ -57,7 +58,10 @@ function safeStatus(video) {
     return {
         videoId: video.id ?? null,
         title: video.snippet?.title ?? null,
+        channelId: video.snippet?.channelId ?? null,
+        channelTitle: video.snippet?.channelTitle ?? null,
         privacyStatus: video.status?.privacyStatus ?? null,
+        publishAt: video.status?.publishAt ?? null,
         uploadStatus: video.status?.uploadStatus ?? null,
         processingStatus: video.processingDetails?.processingStatus ?? null,
         processingProgress: video.processingDetails?.processingProgress ?? null,
@@ -86,6 +90,9 @@ export async function getYouTubeVideoStatus(auth, videoId) {
     }
 }
 export async function uploadYouTubeVideo(auth, input) {
+    if (!input.expectedChannelId)
+        throw new Error('expectedChannelId is required before uploading.');
+    const channel = await verifyYouTubeChannel(auth, input.expectedChannelId);
     const privacyStatus = input.privacyStatus ?? 'private';
     assertVisibilityConfirmed(privacyStatus, input.confirmVisible);
     const file = assertUploadFile(input.filePath);
@@ -131,6 +138,7 @@ export async function uploadYouTubeVideo(auth, input) {
             throw new Error('YouTube 업로드 응답에 videoId가 없습니다.');
         return {
             ...safeStatus(response.data),
+            authenticatedChannel: channel,
             requestedPrivacyStatus: privacyStatus,
             file: { path: input.filePath, size: file.size, ...facts },
             validationWarnings: validation.issues,

package/dist/youtube/comments.d.ts

@@ -0,0 +1,156 @@
+import type { OAuth2Client } from 'google-auth-library';
+export interface YouTubeCommentsPageInput {
+    expectedChannelId?: string;
+    videoId?: string;
+    maxResults?: number;
+    pageToken?: string;
+}
+/** One bounded page of top-level comments; embedded replies are deliberately not treated as complete. */
+export declare function listYouTubeComments(auth: OAuth2Client, input: YouTubeCommentsPageInput): Promise<{
+    channel: {
+        id: string;
+        title: string;
+    };
+    videoId: string | null;
+    threads: {
+        threadId: string | null;
+        videoId: string | null;
+        topLevelComment: {
+            id: string | null;
+            text: string | null;
+            authorDisplayName: string | null;
+            authorChannelId: string | null;
+            publishedAt: string | null;
+            updatedAt: string | null;
+            likeCount: number | null;
+        };
+        canReply: boolean | null;
+        totalReplyCount: number | null;
+        repliesIncluded: boolean;
+        repliesComplete: boolean;
+    }[];
+    nextPageToken: string | null;
+}>;
+interface ParentTarget {
+    expectedChannelId: string;
+    videoId: string;
+    threadId: string;
+    parentCommentId: string;
+}
+export interface YouTubeCommentRepliesInput extends ParentTarget {
+    maxResults?: number;
+    pageToken?: string;
+}
+export declare function listYouTubeCommentReplies(auth: OAuth2Client, input: YouTubeCommentRepliesInput): Promise<{
+    replies: {
+        id: string | null;
+        text: string | null;
+        authorDisplayName: string | null;
+        authorChannelId: string | null;
+        publishedAt: string | null;
+        updatedAt: string | null;
+        likeCount: number | null;
+    }[];
+    nextPageToken: string | null;
+    repliesComplete: boolean;
+    channel: {
+        id: string;
+        title: string;
+    };
+    video: {
+        id: string | null | undefined;
+        title: string | null;
+    };
+    parentComment: {
+        id: string | null;
+        text: string | null;
+        authorDisplayName: string | null;
+        authorChannelId: string | null;
+        publishedAt: string | null;
+        updatedAt: string | null;
+        likeCount: number | null;
+    };
+    canReply: boolean | null;
+    totalReplyCount: number | null;
+}>;
+export interface YouTubeReplyInput extends ParentTarget {
+    text: string;
+    confirm?: boolean;
+}
+export declare function replyToYouTubeComment(auth: OAuth2Client, input: YouTubeReplyInput): Promise<{
+    text: string;
+    public: boolean;
+    channel: {
+        id: string;
+        title: string;
+    };
+    video: {
+        id: string | null | undefined;
+        title: string | null;
+    };
+    parentComment: {
+        id: string | null;
+        text: string | null;
+        authorDisplayName: string | null;
+        authorChannelId: string | null;
+        publishedAt: string | null;
+        updatedAt: string | null;
+        likeCount: number | null;
+    };
+    canReply: boolean | null;
+    totalReplyCount: number | null;
+    status: "preview";
+} | {
+    note: string;
+    text: string;
+    public: boolean;
+    channel: {
+        id: string;
+        title: string;
+    };
+    video: {
+        id: string | null | undefined;
+        title: string | null;
+    };
+    parentComment: {
+        id: string | null;
+        text: string | null;
+        authorDisplayName: string | null;
+        authorChannelId: string | null;
+        publishedAt: string | null;
+        updatedAt: string | null;
+        likeCount: number | null;
+    };
+    canReply: boolean | null;
+    totalReplyCount: number | null;
+    status: "unknown";
+} | {
+    reply: {
+        id: string;
+        text: string;
+        publishedAt: string | null;
+    };
+    text: string;
+    public: boolean;
+    channel: {
+        id: string;
+        title: string;
+    };
+    video: {
+        id: string | null | undefined;
+        title: string | null;
+    };
+    parentComment: {
+        id: string | null;
+        text: string | null;
+        authorDisplayName: string | null;
+        authorChannelId: string | null;
+        publishedAt: string | null;
+        updatedAt: string | null;
+        likeCount: number | null;
+    };
+    canReply: boolean | null;
+    totalReplyCount: number | null;
+    status: "posted";
+}>;
+export {};

package/dist/youtube/comments.js

@@ -0,0 +1,158 @@
+import { google } from '../lib/googleapis-lite.js';
+import { friendlyGoogleError, googleErrorDetail } from '../lib/google-errors.js';
+import { verifyYouTubeChannel } from '../auth/youtube-channel.js';
+function apiError(error) {
+    const friendly = friendlyGoogleError(error);
+    const detail = googleErrorDetail(error);
+    return detail && !friendly.message.includes(detail)
+        ? new Error(`${friendly.message}\nGoogle API: ${detail}`, { cause: error }) : friendly;
+}
+function pageSize(value) {
+    const size = value ?? 20;
+    if (!Number.isInteger(size) || size < 1 || size > 100)
+        throw new Error('maxResults must be 1–100.');
+    return size;
+}
+function commentSummary(comment) {
+    return {
+        id: comment?.id ?? null,
+        text: comment?.snippet?.textDisplay ?? comment?.snippet?.textOriginal ?? null,
+        authorDisplayName: comment?.snippet?.authorDisplayName ?? null,
+        authorChannelId: comment?.snippet?.authorChannelId?.value ?? null,
+        publishedAt: comment?.snippet?.publishedAt ?? null,
+        updatedAt: comment?.snippet?.updatedAt ?? null,
+        likeCount: comment?.snippet?.likeCount ?? null,
+    };
+}
+async function assertOwnedVideo(auth, channelId, videoId) {
+    try {
+        const result = await google.youtube({ version: 'v3', auth }).videos.list({
+            part: ['snippet'], id: [videoId],
+        });
+        const video = result.data.items?.[0];
+        if (video?.id !== videoId || video.snippet?.channelId !== channelId) {
+            throw new Error('Video is missing or does not belong to the authenticated YouTube channel.');
+        }
+        return video;
+    }
+    catch (error) {
+        throw apiError(error);
+    }
+}
+/** One bounded page of top-level comments; embedded replies are deliberately not treated as complete. */
+export async function listYouTubeComments(auth, input) {
+    const channel = await verifyYouTubeChannel(auth, input.expectedChannelId);
+    if (input.videoId)
+        await assertOwnedVideo(auth, channel.id, input.videoId);
+    try {
+        const result = await google.youtube({ version: 'v3', auth }).commentThreads.list({
+            part: ['snippet'], textFormat: 'plainText', order: 'time',
+            ...(input.videoId ? { videoId: input.videoId } : { allThreadsRelatedToChannelId: channel.id }),
+            maxResults: pageSize(input.maxResults),
+            ...(input.pageToken ? { pageToken: input.pageToken } : {}),
+        });
+        const threads = (result.data.items ?? []).map((thread) => {
+            if (thread.snippet?.channelId !== channel.id ||
+                (input.videoId && thread.snippet?.videoId !== input.videoId)) {
+                throw new Error('YouTube returned a comment thread outside the selected channel/video.');
+            }
+            const totalReplyCount = thread.snippet.totalReplyCount ?? null;
+            return {
+                threadId: thread.id ?? null,
+                videoId: thread.snippet.videoId ?? null,
+                topLevelComment: commentSummary(thread.snippet.topLevelComment),
+                canReply: thread.snippet.canReply ?? null,
+                totalReplyCount,
+                repliesIncluded: false,
+                repliesComplete: totalReplyCount === 0,
+            };
+        });
+        return { channel, videoId: input.videoId ?? null, threads,
+            nextPageToken: result.data.nextPageToken ?? null };
+    }
+    catch (error) {
+        throw apiError(error);
+    }
+}
+async function verifiedParent(auth, input) {
+    if (!input.expectedChannelId || !input.videoId || !input.threadId || !input.parentCommentId) {
+        throw new Error('expectedChannelId, videoId, threadId, and parentCommentId are required.');
+    }
+    const channel = await verifyYouTubeChannel(auth, input.expectedChannelId);
+    const video = await assertOwnedVideo(auth, channel.id, input.videoId);
+    try {
+        const youtube = google.youtube({ version: 'v3', auth });
+        const commentResponse = await youtube.comments.list({
+            part: ['snippet'], id: [input.parentCommentId], textFormat: 'plainText',
+        });
+        const comment = commentResponse.data.items?.[0];
+        if (comment?.id !== input.parentCommentId)
+            throw new Error('Parent comment was not found.');
+        if (comment.snippet?.parentId)
+            throw new Error('Replies to replies are not supported; choose a top-level comment.');
+        // Comment.authorChannelId identifies the commenter, not the video's owner.
+        if (comment.snippet?.channelId !== channel.id)
+            throw new Error('Parent comment is not associated with the selected channel.');
+        const threadResponse = await youtube.commentThreads.list({
+            part: ['snippet'], id: [input.threadId], textFormat: 'plainText',
+        });
+        const thread = threadResponse.data.items?.[0];
+        if (thread?.id !== input.threadId || thread.snippet?.topLevelComment?.id !== input.parentCommentId ||
+            thread.snippet.videoId !== input.videoId || thread.snippet.channelId !== channel.id) {
+            throw new Error('Parent comment could not be verified on the selected video.');
+        }
+        return { channel, video: { id: video.id, title: video.snippet?.title ?? null },
+            parentComment: commentSummary(comment), canReply: thread.snippet.canReply ?? null,
+            totalReplyCount: thread.snippet.totalReplyCount ?? null };
+    }
+    catch (error) {
+        throw apiError(error);
+    }
+}
+export async function listYouTubeCommentReplies(auth, input) {
+    const target = await verifiedParent(auth, input);
+    try {
+        const result = await google.youtube({ version: 'v3', auth }).comments.list({
+            part: ['snippet'], parentId: input.parentCommentId, textFormat: 'plainText',
+            maxResults: pageSize(input.maxResults),
+            ...(input.pageToken ? { pageToken: input.pageToken } : {}),
+        });
+        const replies = (result.data.items ?? []).map((comment) => {
+            if (comment.snippet?.parentId !== input.parentCommentId)
+                throw new Error('YouTube returned a reply for a different parent comment.');
+            return commentSummary(comment);
+        });
+        return { ...target, replies, nextPageToken: result.data.nextPageToken ?? null,
+            repliesComplete: !result.data.nextPageToken && !input.pageToken &&
+                target.totalReplyCount !== null && replies.length >= target.totalReplyCount };
+    }
+    catch (error) {
+        throw apiError(error);
+    }
+}
+export async function replyToYouTubeComment(auth, input) {
+    if (!input.text?.trim() || input.text.length > 10_000)
+        throw new Error('Reply text must be nonempty and at most 10000 characters.');
+    const target = await verifiedParent(auth, input);
+    const preview = { ...target, text: input.text, public: true };
+    if (input.confirm !== true)
+        return { status: 'preview', ...preview };
+    if (target.canReply === false)
+        throw new Error('YouTube says this thread cannot accept replies.');
+    try {
+        const result = await google.youtube({ version: 'v3', auth }).comments.insert({
+            part: ['snippet'], requestBody: { snippet: {
+                    parentId: input.parentCommentId, textOriginal: input.text,
+                } },
+        }, { retry: false });
+        if (!result.data.id)
+            return { status: 'unknown', ...preview,
+                note: 'YouTube returned no reply ID. Call youtube_list_comment_replies and check for the text before retrying.' };
+        return { status: 'posted', ...preview,
+            reply: { id: result.data.id, text: result.data.snippet?.textDisplay ?? result.data.snippet?.textOriginal ?? input.text,
+                publishedAt: result.data.snippet?.publishedAt ?? null } };
+    }
+    catch (error) {
+        throw new Error(`${apiError(error).message}\nThe reply may have posted. Call youtube_list_comment_replies and check for the text before retrying.`, { cause: error });
+    }
+}

package/dist/youtube/insights.d.ts

@@ -0,0 +1,82 @@
+import type { OAuth2Client } from 'google-auth-library';
+export interface YouTubeContentInsightsInput {
+    expectedChannelId: string;
+    startDate: string;
+    endDate: string;
+    maxVideos?: number;
+    minViews?: number;
+}
+export declare function comparisonPeriods(startDate: string, endDate: string): {
+    current: {
+        startDate: string;
+        endDate: string;
+        inclusiveDays: number;
+    };
+    previous: {
+        startDate: string;
+        endDate: string;
+        inclusiveDays: number;
+    };
+};
+export declare function getYouTubeContentInsights(auth: OAuth2Client, input: YouTubeContentInsightsInput): Promise<{
+    status: string;
+    channel: {
+        id: string;
+        title: string;
+    };
+    periods: {
+        current: {
+            startDate: string;
+            endDate: string;
+            inclusiveDays: number;
+        };
+        previous: {
+            startDate: string;
+            endDate: string;
+            inclusiveDays: number;
+        };
+    };
+    sources: {
+        channelTotals: string;
+        sampledVideos: string;
+        videoMetadata: string;
+    };
+    channelMetrics: Record<"views" | "estimatedMinutesWatched" | "averageViewDuration" | "subscribersGained", {
+        current: number | null;
+        previous: number | null;
+        absolute: number | null;
+        percent: number | null;
+    }>;
+    sample: {
+        requestedMaxVideos: number;
+        returnedVideos: number;
+        minViewsForEligibility: number;
+        sampledVideos: {
+            metadata: {
+                title: string | null;
+                publishedAt: string | null;
+                duration: string | null;
+            } | null;
+            descriptivePer1000Views: {
+                estimatedMinutesWatched: number | null;
+                subscribersGained: number | null;
+            };
+            views: number;
+            estimatedMinutesWatched: number;
+            averageViewDuration: number;
+            subscribersGained: number;
+            videoId: string;
+        }[];
+        eligibleVideos: {
+            rankByPeriodViews: number;
+            videoId: string;
+            views: number;
+        }[];
+    };
+    limitations: string[];
+    planningHandoff: {
+        instruction: string;
+        productionRoute: string;
+        generatedStoryboard: boolean;
+    };
+}>;

package/dist/youtube/insights.js

@@ -0,0 +1,155 @@
+import { google } from '../lib/googleapis-lite.js';
+import { friendlyGoogleError, googleErrorDetail } from '../lib/google-errors.js';
+import { getYouTubeAnalyticsReport } from './tools.js';
+const DAY_MS = 86_400_000;
+const METRICS = ['views', 'estimatedMinutesWatched', 'averageViewDuration', 'subscribersGained'];
+function apiError(error) {
+    const friendly = friendlyGoogleError(error);
+    const detail = googleErrorDetail(error);
+    return detail && !friendly.message.includes(detail)
+        ? new Error(`${friendly.message}\nGoogle API: ${detail}`, { cause: error }) : friendly;
+}
+function parseDate(value, label) {
+    const date = /^\d{4}-\d{2}-\d{2}$/.test(value) ? new Date(`${value}T00:00:00Z`) : null;
+    if (!date || !Number.isFinite(date.getTime()) || date.toISOString().slice(0, 10) !== value) {
+        throw new Error(`${label} must be a valid YYYY-MM-DD date.`);
+    }
+    return date.getTime();
+}
+function utcDate(ms) { return new Date(ms).toISOString().slice(0, 10); }
+export function comparisonPeriods(startDate, endDate) {
+    const start = parseDate(startDate, 'startDate');
+    const end = parseDate(endDate, 'endDate');
+    if (start > end)
+        throw new Error('startDate must be on or before endDate.');
+    const days = (end - start) / DAY_MS + 1;
+    if (days > 366)
+        throw new Error('Date range must be at most 366 days.');
+    return {
+        current: { startDate, endDate, inclusiveDays: days },
+        previous: { startDate: utcDate(start - days * DAY_MS), endDate: utcDate(start - DAY_MS), inclusiveDays: days },
+    };
+}
+function columnIndex(report, name) {
+    const index = report.columnHeaders.findIndex((header) => header.name === name);
+    if (index < 0)
+        throw new Error(`YouTube Analytics response is missing column ${name}.`);
+    return index;
+}
+function numberCell(row, index, name) {
+    const raw = row[index];
+    const valid = typeof raw === 'number' || (typeof raw === 'string' && /^\d+(?:\.\d+)?$/.test(raw));
+    const value = valid ? Number(raw) : Number.NaN;
+    if (!Number.isFinite(value) || value < 0 || ((name === 'views' || name === 'subscribersGained') && !Number.isInteger(value))) {
+        throw new Error(`YouTube Analytics response has invalid ${name} value.`);
+    }
+    return value;
+}
+function rowMetrics(report, row) {
+    return Object.fromEntries(METRICS.map((name) => [name, numberCell(row, columnIndex(report, name), name)]));
+}
+function totalMetrics(report) {
+    if (report.rows.length === 0)
+        return null;
+    if (report.rows.length !== 1)
+        throw new Error('YouTube Analytics total report returned multiple rows.');
+    return rowMetrics(report, report.rows[0]);
+}
+function metricDelta(current, previous) {
+    const absolute = current === null || previous === null ? null : current - previous;
+    return { current, previous, absolute,
+        percent: absolute === null || previous === null || previous === 0 ? null : (absolute / previous) * 100 };
+}
+function channelComparison(current, previous) {
+    return Object.fromEntries(METRICS.map((name) => [name, metricDelta(current?.[name] ?? null, previous?.[name] ?? null)]));
+}
+export async function getYouTubeContentInsights(auth, input) {
+    if (!input.expectedChannelId)
+        throw new Error('expectedChannelId is required for content insights.');
+    const periods = comparisonPeriods(input.startDate, input.endDate);
+    const maxVideos = input.maxVideos ?? 10;
+    const minViews = input.minViews ?? 100;
+    if (!Number.isInteger(maxVideos) || maxVideos < 1 || maxVideos > 50)
+        throw new Error('maxVideos must be 1–50.');
+    if (!Number.isInteger(minViews) || minViews < 0 || minViews > 1_000_000_000_000) {
+        throw new Error('minViews must be an integer from 0 to 1,000,000,000,000.');
+    }
+    const base = { expectedChannelId: input.expectedChannelId };
+    const current = await getYouTubeAnalyticsReport(auth, { ...base, ...periods.current, dimension: 'total' });
+    const previous = await getYouTubeAnalyticsReport(auth, { ...base, ...periods.previous, dimension: 'total' });
+    const top = await getYouTubeAnalyticsReport(auth, { ...base, ...periods.current,
+        dimension: 'video', maxResults: maxVideos });
+    if (current.channel.id !== input.expectedChannelId || previous.channel.id !== input.expectedChannelId ||
+        top.channel.id !== input.expectedChannelId)
+        throw new Error('YouTube Analytics channel identity changed during report collection.');
+    const currentTotals = totalMetrics(current);
+    const previousTotals = totalMetrics(previous);
+    const sample = top.rows.map((row) => {
+        const cells = row;
+        const id = cells[columnIndex(top, 'video')];
+        if (typeof id !== 'string' || !id.trim())
+            throw new Error('YouTube Analytics response has an invalid video ID.');
+        return { videoId: id, ...rowMetrics(top, cells) };
+    });
+    if (new Set(sample.map((video) => video.videoId)).size !== sample.length) {
+        throw new Error('YouTube Analytics response contains duplicate video IDs.');
+    }
+    let metadata = new Map();
+    if (sample.length) {
+        try {
+            const result = await google.youtube({ version: 'v3', auth }).videos.list({
+                part: ['snippet', 'contentDetails'], id: sample.map((video) => video.videoId), maxResults: 50,
+            });
+            metadata = new Map((result.data.items ?? []).filter((video) => !!video.id).map((video) => {
+                if (video.snippet?.channelId !== input.expectedChannelId) {
+                    throw new Error('Sampled video metadata does not belong to the authenticated channel.');
+                }
+                return [video.id, { title: video.snippet.title ?? null,
+                        publishedAt: video.snippet.publishedAt ?? null, duration: video.contentDetails?.duration ?? null }];
+            }));
+        }
+        catch (error) {
+            throw apiError(error);
+        }
+    }
+    const sampledVideos = sample.map((video) => ({
+        ...video,
+        metadata: metadata.get(video.videoId) ?? null,
+        descriptivePer1000Views: {
+            estimatedMinutesWatched: video.views > 0 ? video.estimatedMinutesWatched / video.views * 1000 : null,
+            subscribersGained: video.views > 0 ? video.subscribersGained / video.views * 1000 : null,
+        },
+    }));
+    const eligibleVideos = currentTotals === null || currentTotals.views === 0 ? [] : sampledVideos
+        .filter((video) => video.metadata !== null && video.views > 0 && video.views >= minViews)
+        .sort((a, b) => b.views - a.views)
+        .map((video, index) => ({ rankByPeriodViews: index + 1, videoId: video.videoId, views: video.views }));
+    const status = currentTotals === null || currentTotals.views === 0 || sample.length === 0 ? 'insufficient_data'
+        : previousTotals === null || eligibleVideos.length === 0 ? 'partial_data' : 'ready';
+    return {
+        status, channel: current.channel, periods,
+        sources: { channelTotals: 'YouTube Analytics API v2 (dimension=total)',
+            sampledVideos: 'YouTube Analytics API v2 (dimension=video, sort=-views)',
+            videoMetadata: 'YouTube Data API v3 videos.list' },
+        channelMetrics: channelComparison(currentTotals, previousTotals),
+        sample: { requestedMaxVideos: maxVideos, returnedVideos: sampledVideos.length,
+            minViewsForEligibility: minViews, sampledVideos, eligibleVideos },
+        limitations: [
+            'Top-video rows are a bounded sample ranked by views, not all channel videos or all recent uploads.',
+            'YouTube Analytics may omit recent days until requested metrics are available; periods are requested dates, not guaranteed complete coverage.',
+            'Video ages differ; period views do not make publishing strategies causally comparable.',
+            'Per-video subscribersGained counts gains on that video watch page; do not sum sampled values as the channel total.',
+            'Average view duration is seconds, not retention or CTR. No CTR or retention claim is inferred.',
+            'Rates per 1,000 views are descriptive ratios only. Missing or zero denominators produce null, not zero.',
+            ...(previousTotals === null ? ['Previous-period totals were unavailable; comparison deltas are null.'] : []),
+            ...(metadata.size < sample.length ? ['Some sampled video metadata was unavailable; those videos are excluded from eligibility.'] : []),
+        ],
+        planningHandoff: {
+            instruction: status === 'insufficient_data'
+                ? 'Gather more complete Analytics data before choosing a direction; do not declare a winning format.'
+                : 'Choose one testable next-video experiment citing the video IDs and observed metrics, then save an agent-authored plan with video_save_plan. Do not claim the observed metrics caused performance.',
+            productionRoute: 'Runway web is the primary generation route; Grok web subscription is the fallback. Avoid API spend unless separately authorized.',
+            generatedStoryboard: false,
+        },
+    };
+}