stophy 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -6,9 +6,9 @@ type ErrorResponse = {
      */
     success: false;
     /**
-     * Machine-readable error code.
+     * Machine-readable error code. `UPSTREAM_UNAVAILABLE` indicates the upstream YouTube/Innertube endpoint could not be reached or is currently blocked.
      */
-    code?: "UNAUTHORIZED" | "INSUFFICIENT_CREDITS" | "BAD_REQUEST" | "INVALID_INPUT" | "NOT_FOUND" | "CONCURRENCY_LIMITED" | "INTERNAL_ERROR";
+    code?: "UNAUTHORIZED" | "INSUFFICIENT_CREDITS" | "BAD_REQUEST" | "INVALID_INPUT" | "NOT_FOUND" | "CONCURRENCY_LIMITED" | "UPSTREAM_UNAVAILABLE" | "INTERNAL_ERROR";
     /**
      * Human-readable error message.
      */
@@ -23,344 +23,478 @@ type Thumbnail = {
     width: number;
     height: number;
 };
-type EmptyState = {
-    code: string;
-    message: string;
-};
-type TranscriptLanguage = {
-    code: string | null;
-    name: string | null;
-    isAutoGenerated: boolean;
+/**
+ * An MCP tool exposed by the Stophy MCP server.
+ */
+type McpTool = {
+    name?: "stophy_search_videos" | "stophy_get_video" | "stophy_get_channel" | "stophy_get_playlist" | "stophy_get_suggestions" | "stophy_music" | "stophy_kids" | "stophy_get_credits";
+    description?: string;
+    inputSchema?: {
+        [key: string]: unknown;
+    };
 };
-type TranscriptSegment = {
-    start: number;
-    duration: number;
-    text: string;
+type VideoRequestVideoOp = {
+    type: "details" | "transcript" | "comments" | "livechat";
+    videoUrl: string;
+    /**
+     * Comment sort order: any (YouTube's default ordering), top, or latest. Only applies when type is 'comments'. Defaults to any.
+     */
+    sortBy?: "any" | "top" | "latest";
+    chatType?: "top" | "live";
+    /**
+     * Preferred transcript language code. Only applies when type is transcript.
+     */
+    lang?: string;
+    continuationToken?: string;
 };
-type TranscriptResult = {
-    language: TranscriptLanguage;
-    segments: Array<TranscriptSegment>;
-    text: string;
-    empty?: EmptyState;
+type VideoRequestReplies = {
+    type: "replies";
+    continuationToken: string;
 };
-type VideoDetails = {
+type VideoDetail = {
+    /**
+     * Item type discriminator. Always `video` for this schema.
+     */
+    type: "video";
     id: string;
-    type?: "video";
+    /**
+     * Canonical URL alias for the item.
+     */
+    url: string;
     videoUrl: string;
-    title: string | null;
-    author?: string | null;
-    authorId?: string | null;
-    category?: string | null;
-    description?: string | null;
-    durationSec?: number | null;
-    durationText?: string | null;
-    isLive?: boolean;
-    likeCount?: number | null;
-    likeCountText?: string | null;
-    publishedAt?: string | null;
-    tags?: Array<string>;
-    viewCount?: number | null;
-    viewCountText?: string | null;
+    title: string;
+    author: string | null;
+    authorId: string | null;
+    description: string | null;
+    viewCount: number | null;
+    viewCountText: string | null;
+    likeCount: number | null;
+    likeCountText: string | null;
+    durationSec: number | null;
+    durationText: string | null;
+    publishedAt: string | null;
+    tags: Array<string>;
+    chapters: Array<{
+        title: string;
+        startMs: number;
+        startSec: number;
+    }>;
+    isLive: boolean;
+    category: string | null;
     thumbnails: Array<Thumbnail>;
 };
 type RelatedVideo = {
+    /**
+     * Item type discriminator. Always `video` for this schema.
+     */
+    type: "video";
     id: string;
-    type?: "video";
+    /**
+     * Canonical URL alias for the item.
+     */
+    url: string;
     videoUrl: string;
-    title?: string | null;
-    author?: string | null;
-    authorId?: string | null;
-    durationSec?: number | null;
-    durationText?: string | null;
-    publishedAt?: string | null;
-    publishedAtText?: string | null;
-    viewCount?: number | null;
-    viewCountText?: string | null;
+    title: string | null;
+    author: string | null;
+    authorId: string | null;
+    viewCount: number | null;
+    viewCountText: string | null;
+    durationSec: number | null;
+    durationText: string | null;
+    publishedAt: string | null;
+    publishedAtText: string | null;
     thumbnails: Array<Thumbnail>;
 };
-type VideoDetailsData = {
-    video: VideoDetails;
-    related: Array<RelatedVideo>;
-};
 type Comment = {
-    id: string | null;
-    text: string | null;
+    id: string;
+    text: string;
     author: string | null;
     authorId: string | null;
-    authorThumbnail?: string | null;
+    /**
+     * URL of the commenter’s channel avatar. Plain string URL, not an object.
+     */
+    authorThumbnail: string | null;
     hasChannelOwnerReplied: boolean;
     isChannelOwner: boolean;
     isHearted: boolean;
     isPinned: boolean;
     isVerified: boolean;
-    publishedAt?: string | null;
-    publishedAtText?: string | null;
-    likeCount?: number | null;
-    likeCountText?: string | null;
-    replyCount?: number | null;
-    replyCountText?: string | null;
-    repliesToken?: string | null;
-};
-type CommentsData = {
+    publishedAt: string | null;
+    publishedAtText: string | null;
+    likeCount: number | null;
+    likeCountText: string | null;
+    replyCount: number | null;
+    replyCountText: string | null;
+    /**
+     * Token to fetch replies via type=replies.
+     */
+    repliesToken: string | null;
+};
+/**
+ * Returned when type is 'details'.
+ */
+type VideoResponseDetails = {
+    videoId: string;
+    video: VideoDetail;
+    related: Array<RelatedVideo>;
+};
+/**
+ * Returned when type is 'transcript'.
+ */
+type VideoResponseTranscript = {
+    videoId: string;
+    language: {
+        code: string | null;
+        name: string | null;
+        isAutoGenerated: boolean;
+    };
+    isTranslated: boolean;
+    availableTracks: Array<{
+        languageCode: string;
+        languageName: string;
+        isAutoGenerated: boolean;
+    }>;
+    segments: Array<{
+        text: string;
+        /**
+         * Start time in seconds.
+         */
+        start: number;
+        /**
+         * Duration in seconds.
+         */
+        duration: number;
+    }>;
+    /**
+     * Concatenated transcript text.
+     */
+    text: string;
+};
+/**
+ * Returned when type is 'comments'.
+ */
+type VideoResponseComments = {
+    videoId: string;
+    sortBy: "any" | "top" | "latest";
     items: Array<Comment>;
     continuationToken: string | null;
-    empty?: EmptyState;
+    hasMore: boolean;
 };
-type LiveChatMessage = {
-    id: string;
-    text: string;
-    author?: string | null;
-    authorId?: string | null;
-    timestampUsec?: string | null;
-    isOwner: boolean;
-    isModerator: boolean;
-    isVerified: boolean;
-    superChatAmount?: string | null;
-    superChatCurrency?: string | null;
+/**
+ * Returned when type is 'replies'. Note: no videoId/sortBy; the parent video is implied. Reply items have no replyCount/replyCountText/repliesToken since replies cannot be threaded.
+ */
+type VideoResponseReplies = {
+    items: Array<Reply>;
+    continuationToken: string | null;
+    hasMore: boolean;
 };
-type LiveChatData = {
-    status: string;
+/**
+ * Returned when type is 'livechat'.
+ */
+type VideoResponseLivechat = {
+    /**
+     * The YouTube video ID this live chat belongs to. Mirrors the `videoUrl` from the request.
+     */
+    videoId: string;
+    status: "live" | "upcoming" | "replay" | "chat_disabled" | "not_live";
     isLive: boolean;
-    concurrentViewers?: number | null;
-    pollIntervalMs?: number | null;
-    messages: Array<LiveChatMessage>;
+    concurrentViewers: number | null;
+    /**
+     * Suggested delay before next poll.
+     */
+    pollIntervalMs: number | null;
+    messages: Array<{
+        id: string;
+        text: string;
+        author: string | null;
+        authorId: string | null;
+        /**
+         * Message timestamp in microseconds.
+         */
+        timestampUsec: string | null;
+        isOwner: boolean;
+        isModerator: boolean;
+        isVerified: boolean;
+        superChatAmount: string | null;
+        superChatCurrency: string | null;
+    }>;
     continuationToken: string | null;
+    hasMore: boolean;
+};
+type EmptyState = {
+    code: string;
+    message: string;
+};
+type MusicArtistRef = {
+    id: string | null;
+    name: string;
+};
+type MusicAlbumRef = {
+    id: string | null;
+    name: string;
 };
 /**
- * Shape depends on the request `type`: details, transcript, comments/replies, or livechat.
+ * YouTube Music result item. URL fields are populated only when YouTube returns the matching identifier for that item type.
  */
-type VideoData = VideoDetailsData | TranscriptResult | CommentsData | LiveChatData;
-type SearchVideo = {
-    type: "video";
-    id: string;
-    videoUrl: string;
+type MusicItem = {
+    type: "song" | "video" | "album" | "artist" | "playlist" | "podcast" | "episode" | "profile";
+    id: string | null;
+    url: string | null;
+    videoUrl?: string | null;
+    playlistUrl?: string | null;
+    channelUrl?: string | null;
+    albumUrl?: string | null;
+    artistUrl?: string | null;
     title: string;
-    author?: string | null;
-    authorId?: string | null;
-    description?: string | null;
-    duration?: string | null;
-    durationSec?: number | null;
-    durationText?: string | null;
-    isLive?: boolean;
-    isUpcoming?: boolean;
-    isVerified?: boolean;
-    viewCount?: number | null;
-    viewCountText?: string | null;
-    publishedAt?: string | null;
-    publishedAtText?: string | null;
+    author: string | null;
+    authorId: string | null;
+    album: MusicAlbumRef | null;
+    artists: Array<MusicArtistRef>;
+    duration: string | null;
+    durationSec: number | null;
+    durationText: string | null;
+    isExplicit: boolean;
+    plays: string | null;
     thumbnails: Array<Thumbnail>;
 };
-type SearchShort = {
-    type: "short";
+type MusicSong = {
     id: string;
-    shortUrl: string;
+    url: string;
+    videoUrl: string;
     title: string;
-    author?: string | null;
-    authorId?: string | null;
-    description?: string | null;
-    duration?: string | null;
-    durationSec?: number | null;
-    durationText?: string | null;
-    viewCount?: number | null;
-    viewCountText?: string | null;
-    publishedAt?: string | null;
-    publishedAtText?: string | null;
+    author: string | null;
+    authorId: string | null;
+    album: MusicAlbumRef | null;
+    artists: Array<MusicArtistRef>;
+    duration: string | null;
+    durationSec: number | null;
+    durationText: string | null;
+    isExplicit: boolean;
+    lyricsBrowseId: string | null;
+    relatedBrowseId: string | null;
     thumbnails: Array<Thumbnail>;
 };
-type SearchPlaylist = {
-    type: "playlist";
-    id: string;
-    playlistUrl: string;
-    title: string;
-    author?: string | null;
-    authorId?: string | null;
-    videoCount?: number | null;
-    videoCountText?: string | null;
-    thumbnails: Array<Thumbnail>;
+type MusicSearchData = {
+    items: Array<MusicItem>;
+    continuationToken: string | null;
+    hasMore: boolean;
+    /**
+     * Present only when the operation yields no results.
+     */
+    empty?: EmptyState | null;
 };
-type SearchChannel = {
-    type: "channel";
-    id: string;
-    channelUrl: string;
-    name: string;
-    handle?: string | null;
-    description?: string | null;
-    subscriberCount?: number | null;
-    subscriberCountText?: string | null;
-    isVerified?: boolean;
-    thumbnails: Array<Thumbnail>;
+type MusicSuggestData = {
+    q: string;
+    suggestions: Array<string>;
 };
-type SearchItem = ({
-    type?: "video";
-} & SearchVideo) | ({
-    type?: "short";
-} & SearchShort) | ({
-    type?: "playlist";
-} & SearchPlaylist) | ({
-    type?: "channel";
-} & SearchChannel);
-type SearchData = {
-    items: Array<SearchItem>;
-    continuationToken: string | null;
-    estimatedResults?: number;
-    empty?: EmptyState;
+type MusicSongData = {
+    song: MusicSong;
+} | {
+    empty: EmptyState;
 };
-type ChannelLink = {
-    title: string;
-    url: string;
+type MusicLyricsData = {
+    videoId: string;
+    videoUrl: string;
+    lyrics: string | null;
+    source: string | null;
+    hasTimedLyrics: boolean;
+    /**
+     * Present only when the operation yields no results.
+     */
+    empty?: EmptyState | null;
 };
-type ChannelProfile = {
-    id: string | null;
-    name: string | null;
-    handle: string | null;
-    channelUrl: string | null;
-    description?: string | null;
-    subscriberCount?: number | null;
-    subscriberCountText?: string | null;
-    videoCount?: number | null;
-    videoCountText?: string | null;
-    viewCount?: number | null;
-    viewCountText?: string | null;
-    isVerified: boolean;
-    country?: string | null;
-    joinedDate?: string | null;
-    thumbnails: Array<Thumbnail>;
-    banners: Array<Thumbnail>;
-    links?: Array<ChannelLink> | null;
+type MusicAlbumData = {
+    album: {
+        id: string;
+        url: string | null;
+        albumUrl: string | null;
+        title: string;
+        artists: Array<MusicArtistRef>;
+        year: string | null;
+        trackCountText: string | null;
+        durationText: string | null;
+        thumbnails: Array<Thumbnail>;
+    };
+    items: Array<MusicItem>;
+    /**
+     * Present only when the operation yields no results.
+     */
+    empty?: EmptyState | null;
 };
-type ContentItem = {
-    id: string;
-    type?: string;
-    title?: string | null;
-    videoUrl?: string;
-    shortUrl?: string;
-    playlistUrl?: string;
-    author?: string | null;
-    authorId?: string | null;
-    durationSec?: number | null;
-    durationText?: string | null;
-    viewCount?: number | null;
-    viewCountText?: string | null;
-    publishedAt?: string | null;
-    publishedAtText?: string | null;
-    thumbnails: Array<Thumbnail>;
+type MusicArtistData = {
+    artist: {
+        id: string | null;
+        url: string | null;
+        channelUrl: string | null;
+        name: string;
+        description: string | null;
+        subscriberText: string | null;
+        thumbnails: Array<Thumbnail>;
+    };
+    sections: Array<{
+        title: string;
+        items: Array<{
+            id: string | null;
+            url: string | null;
+            videoUrl?: string;
+            channelUrl?: string;
+            kind: "watch" | "browse";
+            title: string;
+            subtitle: string | null;
+            thumbnails: Array<Thumbnail>;
+        }>;
+    }>;
+    /**
+     * Present only when the operation yields no results.
+     */
+    empty?: EmptyState | null;
 };
-type ChannelData = {
-    channel: ChannelProfile | null;
-    tab?: string | null;
-    items?: Array<ContentItem>;
-    continuationToken?: string | null;
-    empty?: EmptyState;
+type MusicPlaylistData = {
+    playlist: {
+        id: string | null;
+        url: string | null;
+        playlistUrl: string | null;
+        title: string;
+        subtitle: string | null;
+        trackCountText: string | null;
+        durationText: string | null;
+        thumbnails: Array<Thumbnail>;
+    };
+    items: Array<MusicItem>;
+    continuationToken: string | null;
+    hasMore: boolean;
+    /**
+     * Present only when the operation yields no results.
+     */
+    empty?: EmptyState | null;
 };
-type PlaylistMeta = {
+/**
+ * Response payload varies by request `type`.
+ */
+type MusicResponseData = MusicSearchData | MusicSuggestData | MusicSongData | MusicLyricsData | MusicAlbumData | MusicArtistData | MusicPlaylistData;
+type KidsVideoItem = {
+    type: "video";
     id: string;
-    type?: "playlist";
-    playlistUrl: string;
-    title?: string | null;
-    author?: string | null;
-    authorId?: string | null;
-    description?: string | null;
-    videoCount?: string | null;
+    url: string;
+    videoUrl: string;
+    kidsUrl: string;
+    title: string;
+    author: string | null;
+    authorId: string | null;
+    authorUrl: string | null;
+    duration: string | null;
+    durationSec: number | null;
+    durationText: string | null;
+    publishedAt: string | null;
+    publishedAtText: string | null;
+    viewCount: number | null;
+    viewCountText: string | null;
     thumbnails: Array<Thumbnail>;
 };
-type PlaylistItem = {
+type KidsVideoDetails = {
+    type: "video";
     id: string;
-    type?: "video";
+    url: string;
     videoUrl: string;
-    title?: string | null;
-    author?: string | null;
-    authorId?: string | null;
-    durationSec?: number | null;
-    durationText?: string | null;
-    index?: number | null;
-    isLive?: boolean;
-    isPlayable?: boolean;
-    isUpcoming?: boolean;
-    upcomingAt?: string | null;
-    viewCount?: number | null;
-    viewCountText?: string | null;
-    publishedAt?: string | null;
-    publishedAtText?: string | null;
+    kidsUrl: string;
+    title: string;
+    author: string | null;
+    authorId: string | null;
+    authorUrl: string | null;
+    description: string | null;
+    duration: string | null;
+    durationSec: number | null;
+    durationText: string | null;
+    isLive: boolean;
+    isLiveContent: boolean;
+    keywords: Array<string>;
+    viewCount: number | null;
+    viewCountText: string | null;
     thumbnails: Array<Thumbnail>;
 };
-type PlaylistData = {
-    playlist: PlaylistMeta | null;
-    items: Array<PlaylistItem>;
+type KidsSearchData = {
+    items: Array<KidsVideoItem>;
     continuationToken: string | null;
-    empty?: EmptyState;
-};
-type SuggestData = {
-    q: string;
-    hl: string;
-    gl: string;
-    suggestions: Array<string>;
+    hasMore: boolean;
+    /**
+     * Present only when the operation yields no results.
+     */
+    empty?: EmptyState | null;
 };
-type CreditsData = {
-    credits: number;
+type KidsVideoData = {
+    video: KidsVideoDetails;
+    related: Array<KidsVideoItem>;
+} | {
+    empty: EmptyState;
 };
-type LogEntry = {
+/**
+ * Response payload varies by request `type`.
+ */
+type KidsResponseData = KidsSearchData | KidsVideoData;
+/**
+ * A reply to a comment. Replies cannot be threaded, so there are no reply-count or repliesToken fields.
+ */
+type Reply = {
     id: string;
-    userId?: string;
-    apiKeyId?: string | null;
-    apiKeyName?: string | null;
-    endpoint: string;
-    method: string;
-    status: number;
-    credits: number;
-    durationMs?: number | null;
-    response?: string | null;
-    createdAt: string;
-};
-type LogsData = {
-    logs: Array<LogEntry>;
-    total: number;
-    page: number;
-    pageSize: number;
-    totalPages: number;
-    endpoints: Array<string>;
-};
-type UsageItem = {
-    date: string;
-    credits: number;
-    requests: number;
-};
-type UsageData = {
-    items: Array<UsageItem>;
+    text: string;
+    author: string | null;
+    authorId: string | null;
+    /**
+     * URL of the commenter’s channel avatar. Plain string URL, not an object.
+     */
+    authorThumbnail: string | null;
+    hasChannelOwnerReplied: boolean;
+    isChannelOwner: boolean;
+    isHearted: boolean;
+    isPinned: boolean;
+    isVerified: boolean;
+    publishedAt: string | null;
+    publishedAtText: string | null;
+    likeCount: number | null;
+    likeCountText: string | null;
 };
-type GetVideoData = {
+type SearchVideosData = {
     body: {
         /**
-         * The type of data to retrieve.
+         * Search query.
          */
-        type: "details" | "transcript" | "comments" | "replies" | "livechat";
+        q: string;
         /**
-         * Full YouTube video URL. Not required when type is replies.
+         * Filter by content type.
          */
-        videoUrl: string;
+        type?: "video" | "short" | "channel" | "playlist" | "movie";
         /**
-         * Comment sort order. Only applies when type is comments.
+         * Sort order. Defaults to relevance.
          */
-        sortBy?: "latest" | "top";
+        sortBy?: "relevance" | "popularity" | "date" | "rating";
         /**
-         * Live chat mode. Only applies when type is livechat: 'top' = Top chat (moderated, default), 'live' = all messages. Applied on the first call; later polls keep the chosen mode.
+         * Filter by upload date.
          */
-        chatType?: "top" | "live";
+        uploadDate?: "today" | "week" | "month" | "year";
+        /**
+         * Duration filter. Not applicable when type is short.
+         */
+        duration?: "short" | "medium" | "long";
         /**
-         * Pagination token. Required when type is replies (use the repliesToken from a comment item); for livechat, pass the continuationToken from a previous livechat response to poll for new messages.
+         * Filter by video features.
+         */
+        features?: Array<"live" | "4k" | "hd" | "subtitles" | "creativeCommons" | "360" | "vr180" | "3d" | "hdr" | "location" | "purchased">;
+        /**
+         * Token from a previous response to fetch the next page.
          */
         continuationToken?: string;
     };
     path?: never;
     query?: never;
-    url: "/v1/video";
+    url: "/v1/search";
 };
-type GetVideoErrors = {
+type SearchVideosErrors = {
     /**
      * Validation error
      */
     400: ErrorResponse;
     /**
-     * Invalid or missing API key
+     * Unauthorized
      */
     401: ErrorResponse;
     /**
@@ -368,71 +502,162 @@ type GetVideoErrors = {
      */
     402: ErrorResponse;
     /**
-     * Rate limited
+     * Concurrency limited. Too many requests in flight for your plan; retry once an in-flight request finishes.
      */
     429: ErrorResponse;
     /**
      * Internal error
      */
     500: ErrorResponse;
+    /**
+     * Transient upstream failure (UPSTREAM_UNAVAILABLE). YouTube was unreachable or bot-checked; the credit is refunded. Retry the request.
+     */
+    503: ErrorResponse;
 };
-type GetVideoError = GetVideoErrors[keyof GetVideoErrors];
-type GetVideoResponses = {
+type SearchVideosError = SearchVideosErrors[keyof SearchVideosErrors];
+type SearchVideosResponses = {
     /**
-     * Successful response
+     * Search results
      */
     200: {
-        success: true;
-        requestId: string;
-        data: VideoData;
-        cacheState: "hit" | "miss";
-        creditsUsed: number;
-        creditsRemaining: number;
+        success?: true;
+        requestId?: string;
+        cacheState?: "hit" | "miss";
+        creditsUsed?: number;
+        creditsRemaining?: number;
+        /**
+         * When no results match, the response includes `data.empty = { code: 'EMPTY_SEARCH_RESULTS', message }`.
+         */
+        data?: {
+            /**
+             * Search results. The shape of each item depends on the `type` filter (or on the item's intrinsic type if `type` was not specified).
+             */
+            items: Array<{
+                type: "video";
+                id: string;
+                /**
+                 * Canonical URL alias for the item.
+                 */
+                url: string;
+                videoUrl: string;
+                title: string;
+                author: string | null;
+                authorId: string | null;
+                description: string | null;
+                duration: string | null;
+                durationSec: number | null;
+                durationText: string | null;
+                isLive: boolean;
+                isUpcoming: boolean;
+                isVerified: boolean;
+                viewCount: number | null;
+                viewCountText: string | null;
+                publishedAt: string | null;
+                publishedAtText: string | null;
+                thumbnails: Array<Thumbnail>;
+            } | {
+                type: "short";
+                id: string;
+                /**
+                 * Canonical URL alias for the item.
+                 */
+                url: string;
+                shortUrl: string;
+                title: string;
+                viewCount: number | null;
+                viewCountText: string | null;
+                thumbnails: Array<Thumbnail>;
+            } | {
+                type: "channel";
+                id: string;
+                /**
+                 * Canonical URL alias for the item.
+                 */
+                url: string;
+                channelUrl: string;
+                name: string;
+                handle: string | null;
+                description: string | null;
+                subscriberCount: number | null;
+                subscriberCountText: string | null;
+                isVerified: boolean;
+                thumbnails: Array<Thumbnail>;
+            } | {
+                type: "playlist";
+                id: string;
+                /**
+                 * Canonical URL alias for the item.
+                 */
+                url: string;
+                playlistUrl: string;
+                title: string;
+                thumbnails: Array<Thumbnail>;
+                author: string | null;
+                authorId: string | null;
+                videoCount: number | null;
+                videoCountText: string | null;
+            }>;
+            continuationToken: string | null;
+            hasMore: boolean;
+            /**
+             * Estimated total from YouTube on the first page; null when YouTube omits it or for continuation pages.
+             */
+            estimatedResults: number | null;
+            /**
+             * Present only when the operation yields no results.
+             */
+            empty?: {
+                code?: string;
+                message?: string;
+            } | null;
+        };
     };
 };
-type GetVideoResponse = GetVideoResponses[keyof GetVideoResponses];
-type SearchVideosData = {
+type SearchVideosResponse = SearchVideosResponses[keyof SearchVideosResponses];
+type GetVideoData = {
     body: {
         /**
-         * Search query.
+         * The type of data to retrieve.
          */
-        q: string;
+        type: "details" | "transcript" | "comments" | "livechat";
         /**
-         * Filter by content type.
+         * Full YouTube video URL (e.g. https://www.youtube.com/watch?v=...).
          */
-        type?: "video" | "short" | "channel" | "playlist" | "movie";
+        videoUrl: string;
         /**
-         * Sort order. Defaults to relevance.
+         * Comment sort order: any (YouTube's default ordering), top, or latest. Only applies when type is 'comments'. Defaults to any.
          */
-        sortBy?: "relevance" | "popularity" | "date" | "rating";
+        sortBy?: "any" | "top" | "latest";
         /**
-         * Filter by upload date.
+         * Live chat mode. Only applies when type is 'livechat'. 'top' = Top chat (moderated, default), 'live' = all messages. Applied on the first call; later polls keep the chosen mode.
          */
-        uploadDate?: "today" | "week" | "month" | "year";
+        chatType?: "top" | "live";
         /**
-         * Duration filter. Not applicable when type is short.
+         * Preferred transcript language code. Only applies when type is 'transcript'.
          */
-        duration?: "short" | "medium" | "long";
+        lang?: string;
         /**
-         * Filter by video features.
+         * Pagination token. For 'livechat', pass the continuationToken from a previous livechat response to poll for new messages.
          */
-        features?: Array<"live" | "4k" | "hd" | "subtitles" | "creativeCommons" | "360" | "vr180" | "3d" | "hdr" | "location" | "purchased">;
+        continuationToken?: string;
+    } | {
+        type: "replies";
         /**
-         * Token from a previous response to fetch the next page.
+         * The repliesToken from a previous comments response.
          */
-        continuationToken?: string;
+        continuationToken: string;
     };
     path?: never;
     query?: never;
-    url: "/v1/search";
+    url: "/v1/video";
 };
-type SearchVideosErrors = {
+type GetVideoErrors = {
     /**
      * Validation error
      */
     400: ErrorResponse;
     /**
-     * Unauthorized
+     * Invalid or missing API key
      */
     401: ErrorResponse;
     /**
@@ -440,29 +665,46 @@ type SearchVideosErrors = {
      */
     402: ErrorResponse;
     /**
-     * Rate limited
+     * Concurrency limited. Too many requests in flight for your plan; retry once an in-flight request finishes.
      */
     429: ErrorResponse;
     /**
      * Internal error
      */
     500: ErrorResponse;
+    /**
+     * Transient upstream failure (UPSTREAM_UNAVAILABLE). YouTube was unreachable or bot-checked; the credit is refunded. Retry the request.
+     */
+    503: ErrorResponse;
 };
-type SearchVideosError = SearchVideosErrors[keyof SearchVideosErrors];
-type SearchVideosResponses = {
+type GetVideoError = GetVideoErrors[keyof GetVideoErrors];
+type GetVideoResponses = {
     /**
-     * Search results
+     * Successful response
      */
     200: {
-        success: true;
-        requestId: string;
-        data: SearchData;
-        cacheState: "hit" | "miss";
-        creditsUsed: number;
-        creditsRemaining: number;
+        success?: true;
+        requestId?: string;
+        cacheState?: "hit" | "miss";
+        creditsUsed?: number;
+        creditsRemaining?: number;
+        /**
+         * Per-type response payload. See oneOf branches. If the operation yields no results, the response may include a `data.empty` object instead of the expected payload: `{ code: string, message: string }`. Codes: `EMPTY_TRANSCRIPT_SEGMENTS`, `EMPTY_COMMENTS`, `EMPTY_COMMENT_REPLIES`.
+         */
+        data?: ({
+            _kind?: "details";
+        } & VideoResponseDetails) | ({
+            _kind?: "transcript";
+        } & VideoResponseTranscript) | ({
+            _kind?: "comments";
+        } & VideoResponseComments) | ({
+            _kind?: "replies";
+        } & VideoResponseReplies) | ({
+            _kind?: "livechat";
+        } & VideoResponseLivechat);
     };
 };
-type SearchVideosResponse = SearchVideosResponses[keyof SearchVideosResponses];
+type GetVideoResponse = GetVideoResponses[keyof GetVideoResponses];
 type GetChannelData = {
     body: {
         /**
@@ -472,7 +714,11 @@ type GetChannelData = {
         /**
          * Content tab to fetch. Defaults to video.
          */
-        tab?: "video" | "short" | "playlist" | "about";
+        tab?: "video" | "short" | "live" | "playlist" | "post" | "community" | "course" | "about";
+        /**
+         * Search query within the channel. When supplied, tab is ignored.
+         */
+        query?: string;
         /**
          * Token from a previous response to fetch the next page.
          */
@@ -500,13 +746,17 @@ type GetChannelErrors = {
      */
     402: ErrorResponse;
     /**
-     * Rate limited
+     * Concurrency limited. Too many requests in flight for your plan; retry once an in-flight request finishes.
      */
     429: ErrorResponse;
     /**
      * Internal error
      */
     500: ErrorResponse;
+    /**
+     * Transient upstream failure (UPSTREAM_UNAVAILABLE). YouTube was unreachable or bot-checked; the credit is refunded. Retry the request.
+     */
+    503: ErrorResponse;
 };
 type GetChannelError = GetChannelErrors[keyof GetChannelErrors];
 type GetChannelResponses = {
@@ -514,12 +764,183 @@ type GetChannelResponses = {
      * Channel data
      */
     200: {
-        success: true;
-        requestId: string;
-        data: ChannelData;
-        cacheState: "hit" | "miss";
-        creditsUsed: number;
-        creditsRemaining: number;
+        success?: true;
+        requestId?: string;
+        cacheState?: "hit" | "miss";
+        creditsUsed?: number;
+        creditsRemaining?: number;
+        /**
+         * All tabs return the same top-level fields. For `tab: "about"`, `items` is empty, `continuationToken` is null, and `hasMore` is false. When a content tab has no items, the response also includes `data.empty`.
+         */
+        data?: {
+            /**
+             * The channel profile. Always returned for the 'about' tab; may be null on continuation requests for other tabs.
+             */
+            channel: {
+                type: "channel";
+                /**
+                 * YouTube channel ID (UC...).
+                 */
+                id: string | null;
+                /**
+                 * Canonical URL alias for the channel.
+                 */
+                url: string | null;
+                /**
+                 * Canonical URL of the channel.
+                 */
+                channelUrl: string | null;
+                /**
+                 * Display name of the channel.
+                 */
+                name: string | null;
+                /**
+                 * Channel handle without the @ symbol (e.g. 'mkbhd').
+                 */
+                handle: string | null;
+                /**
+                 * Channel description / about text.
+                 */
+                description: string | null;
+                /**
+                 * Parsed subscriber count as a number.
+                 */
+                subscriberCount: number | null;
+                /**
+                 * Formatted subscriber count string as displayed on YouTube (e.g. '21M subscribers').
+                 */
+                subscriberCountText: string | null;
+                /**
+                 * Parsed total video count as a number.
+                 */
+                videoCount: number | null;
+                /**
+                 * Formatted video count string (e.g. '1.2K videos').
+                 */
+                videoCountText: string | null;
+                /**
+                 * Whether the channel has a verification badge.
+                 */
+                isVerified: boolean;
+                /**
+                 * Channel avatar thumbnails.
+                 */
+                thumbnails: Array<Thumbnail>;
+                /**
+                 * Channel banner images.
+                 */
+                banners: Array<Thumbnail>;
+                /**
+                 * Channel country from the About tab; null when unavailable or on other tabs.
+                 */
+                country: string | null;
+                /**
+                 * Date the channel was created; null when unavailable or on other tabs.
+                 */
+                joinedDate: string | null;
+                /**
+                 * Total channel view count from the About tab; null when unavailable or on other tabs.
+                 */
+                viewCount: number | null;
+                /**
+                 * Formatted total view count from the About tab; null when unavailable or on other tabs.
+                 */
+                viewCountText: string | null;
+                /**
+                 * External links from the About tab; null when unavailable or on other tabs.
+                 */
+                links: Array<{
+                    title: string;
+                    url: string;
+                }> | null;
+            } | null;
+            tab: string;
+            /**
+             * Tab-specific items. Shape varies by `tab`; empty for `tab: "about"`.
+             */
+            items: Array<{
+                type: "video";
+                id: string;
+                /**
+                 * Canonical URL alias for the item.
+                 */
+                url: string;
+                videoUrl: string;
+                title: string | null;
+                author: string | null;
+                authorId: string | null;
+                viewCount: number | null;
+                viewCountText: string | null;
+                duration: string | null;
+                durationSec: number | null;
+                durationText: string | null;
+                isLive: boolean;
+                isUpcoming: boolean;
+                upcomingAt: string | null;
+                publishedAt: string | null;
+                publishedAtText: string | null;
+                thumbnails: Array<Thumbnail>;
+            } | {
+                type: "short";
+                id: string;
+                /**
+                 * Canonical URL alias for the item.
+                 */
+                url: string;
+                shortUrl: string;
+                title: string | null;
+                author: string | null;
+                authorId: string | null;
+                viewCount: number | null;
+                viewCountText: string | null;
+                thumbnails: Array<Thumbnail>;
+            } | {
+                type: "playlist";
+                id: string;
+                /**
+                 * Canonical URL alias for the item.
+                 */
+                url: string;
+                playlistUrl: string;
+                title: string | null;
+                author: string | null;
+                authorId: string | null;
+                /**
+                 * Parsed playlist video count.
+                 */
+                videoCount: number | null;
+                /**
+                 * Raw formatted playlist video count string from YouTube.
+                 */
+                videoCountText: string | null;
+                thumbnails: Array<Thumbnail>;
+            } | {
+                type: "post";
+                id: string;
+                url: string;
+                content: string | null;
+                publishedTimeText: string | null;
+                likeCountText: string | null;
+                commentCountText: string | null;
+                images: Array<{
+                    thumbnails: Array<Thumbnail>;
+                }>;
+                video: {
+                    id: string;
+                    title: string | null;
+                    url: string;
+                } | null;
+            }>;
+            continuationToken: string | null;
+            hasMore: boolean;
+            /**
+             * Present only when the operation yields no results.
+             */
+            empty?: {
+                code?: string;
+                message?: string;
+            } | null;
+        };
     };
 };
 type GetChannelResponse = GetChannelResponses[keyof GetChannelResponses];
@@ -552,13 +973,17 @@ type GetPlaylistErrors = {
      */
     402: ErrorResponse;
     /**
-     * Rate limited
+     * Concurrency limited. Too many requests in flight for your plan; retry once an in-flight request finishes.
      */
     429: ErrorResponse;
     /**
      * Internal error
      */
     500: ErrorResponse;
+    /**
+     * Transient upstream failure (UPSTREAM_UNAVAILABLE). YouTube was unreachable or bot-checked; the credit is refunded. Retry the request.
+     */
+    503: ErrorResponse;
 };
 type GetPlaylistError = GetPlaylistErrors[keyof GetPlaylistErrors];
 type GetPlaylistResponses = {
@@ -566,19 +991,83 @@ type GetPlaylistResponses = {
      * Playlist items
      */
     200: {
-        success: true;
-        requestId: string;
-        data: PlaylistData;
-        cacheState: "hit" | "miss";
-        creditsUsed: number;
-        creditsRemaining: number;
+        success?: true;
+        requestId?: string;
+        cacheState?: "hit" | "miss";
+        creditsUsed?: number;
+        creditsRemaining?: number;
+        /**
+         * When the playlist has no videos, the response includes `data.empty = { code: 'EMPTY_PLAYLIST_VIDEOS', message }`.
+         */
+        data?: {
+            playlist: {
+                type: "playlist";
+                id: string;
+                /**
+                 * Canonical URL alias for the item.
+                 */
+                url: string;
+                playlistUrl: string;
+                title: string;
+                author: string | null;
+                authorId: string | null;
+                description: string | null;
+                /**
+                 * Parsed video count, e.g. 52.
+                 */
+                videoCount: number | null;
+                thumbnails: Array<Thumbnail>;
+                /**
+                 * Raw formatted string from YouTube, e.g. "52 videos".
+                 */
+                videoCountText: string | null;
+            } | null;
+            /**
+             * Playlist video items. Supports both legacy playlistVideoRenderer and new lockupViewModel layout.
+             */
+            items: Array<{
+                type: "video";
+                id: string;
+                /**
+                 * Canonical URL alias for the item.
+                 */
+                url: string;
+                videoUrl: string;
+                title: string;
+                author: string | null;
+                authorId: string | null;
+                duration: string | null;
+                durationSec: number | null;
+                durationText: string | null;
+                /**
+                 * 1-based playlist index; null for lockup items.
+                 */
+                index: number | null;
+                isLive: boolean;
+                isPlayable: boolean;
+                isUpcoming: boolean;
+                upcomingAt: string | null;
+                viewCount: number | null;
+                viewCountText: string | null;
+                publishedAt: string | null;
+                publishedAtText: string | null;
+                thumbnails: Array<Thumbnail>;
+            }>;
+            continuationToken: string | null;
+            hasMore: boolean;
+            /**
+             * Present only when the operation yields no results.
+             */
+            empty?: {
+                code?: string;
+                message?: string;
+            } | null;
+        };
     };
 };
 type GetPlaylistResponse = GetPlaylistResponses[keyof GetPlaylistResponses];
 type GetSuggestionsData = {
-    body?: never;
-    path?: never;
-    query: {
+    body: {
         /**
          * Search query.
          */
@@ -592,6 +1081,8 @@ type GetSuggestionsData = {
          */
         gl?: string;
     };
+    path?: never;
+    query?: never;
     url: "/v1/suggest";
 };
 type GetSuggestionsErrors = {
@@ -604,13 +1095,21 @@ type GetSuggestionsErrors = {
      */
     401: ErrorResponse;
     /**
-     * Rate limited
+     * Insufficient credits
+     */
+    402: ErrorResponse;
+    /**
+     * Concurrency limited. Too many requests in flight for your plan; retry once an in-flight request finishes.
      */
     429: ErrorResponse;
     /**
      * Internal error
      */
     500: ErrorResponse;
+    /**
+     * Transient upstream failure (UPSTREAM_UNAVAILABLE). YouTube was unreachable or bot-checked; the credit is refunded. Retry the request.
+     */
+    503: ErrorResponse;
 };
 type GetSuggestionsError = GetSuggestionsErrors[keyof GetSuggestionsErrors];
 type GetSuggestionsResponses = {
@@ -618,15 +1117,161 @@ type GetSuggestionsResponses = {
      * Autocomplete suggestions
      */
     200: {
-        success: true;
-        requestId: string;
-        data: SuggestData;
-        cacheState: "hit" | "miss";
-        creditsUsed: number;
-        creditsRemaining: number;
+        success?: true;
+        requestId?: string;
+        cacheState?: "hit" | "miss";
+        creditsUsed?: number;
+        creditsRemaining?: number;
+        data?: {
+            suggestions: Array<string>;
+        };
     };
 };
 type GetSuggestionsResponse = GetSuggestionsResponses[keyof GetSuggestionsResponses];
+type YoutubeMusicData = {
+    body: {
+        /**
+         * Music resource to fetch.
+         */
+        type: "search" | "suggest" | "song" | "lyrics" | "album" | "artist" | "playlist";
+        /**
+         * Search or suggestion query. Required for type search and suggest.
+         */
+        q?: string;
+        /**
+         * Music search result type. Used only when type is search.
+         */
+        searchType?: "song" | "video" | "album" | "artist" | "playlist" | "podcast" | "episode" | "profile";
+        /**
+         * YouTube / YouTube Music video URL or bare video ID. Required for type song and lyrics.
+         */
+        videoUrl?: string;
+        /**
+         * YouTube Music album URL or bare MPRE/OLAK album ID. Required for type album.
+         */
+        albumUrl?: string;
+        /**
+         * YouTube Music artist URL or bare UC/MPAD artist ID. Required for type artist.
+         */
+        artistUrl?: string;
+        /**
+         * YouTube / YouTube Music playlist URL or bare playlist ID. Required for type playlist.
+         */
+        playlistUrl?: string;
+        /**
+         * Token from a previous music search or playlist response.
+         */
+        continuationToken?: string;
+    };
+    path?: never;
+    query?: never;
+    url: "/v1/music";
+};
+type YoutubeMusicErrors = {
+    /**
+     * Validation error
+     */
+    400: ErrorResponse;
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+    /**
+     * Insufficient credits
+     */
+    402: ErrorResponse;
+    /**
+     * Concurrency limited. Too many requests in flight for your plan; retry once an in-flight request finishes.
+     */
+    429: ErrorResponse;
+    /**
+     * Internal error
+     */
+    500: ErrorResponse;
+    /**
+     * Transient upstream failure (UPSTREAM_UNAVAILABLE). YouTube was unreachable or bot-checked; the credit is refunded. Retry the request.
+     */
+    503: ErrorResponse;
+};
+type YoutubeMusicError = YoutubeMusicErrors[keyof YoutubeMusicErrors];
+type YoutubeMusicResponses = {
+    /**
+     * Success
+     */
+    200: {
+        success?: true;
+        requestId?: string;
+        cacheState?: "hit" | "miss";
+        creditsUsed?: number;
+        creditsRemaining?: number;
+        data?: MusicResponseData;
+    };
+};
+type YoutubeMusicResponse = YoutubeMusicResponses[keyof YoutubeMusicResponses];
+type YoutubeKidsData = {
+    body: {
+        /**
+         * Kids resource to fetch.
+         */
+        type: "search" | "video";
+        /**
+         * YouTube Kids search query. Required for type search.
+         */
+        q?: string;
+        /**
+         * YouTube Kids / YouTube video URL or bare video ID. Required for type video.
+         */
+        videoUrl?: string;
+        /**
+         * Token from a previous YouTube Kids search response.
+         */
+        continuationToken?: string;
+    };
+    path?: never;
+    query?: never;
+    url: "/v1/kids";
+};
+type YoutubeKidsErrors = {
+    /**
+     * Validation error
+     */
+    400: ErrorResponse;
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+    /**
+     * Insufficient credits
+     */
+    402: ErrorResponse;
+    /**
+     * Concurrency limited. Too many requests in flight for your plan; retry once an in-flight request finishes.
+     */
+    429: ErrorResponse;
+    /**
+     * Internal error
+     */
+    500: ErrorResponse;
+    /**
+     * Transient upstream failure (UPSTREAM_UNAVAILABLE). YouTube was unreachable or bot-checked; the credit is refunded. Retry the request.
+     */
+    503: ErrorResponse;
+};
+type YoutubeKidsError = YoutubeKidsErrors[keyof YoutubeKidsErrors];
+type YoutubeKidsResponses = {
+    /**
+     * Success
+     */
+    200: {
+        success?: true;
+        requestId?: string;
+        cacheState?: "hit" | "miss";
+        creditsUsed?: number;
+        creditsRemaining?: number;
+        data?: KidsResponseData;
+    };
+};
+type YoutubeKidsResponse = YoutubeKidsResponses[keyof YoutubeKidsResponses];
 type GetCreditsData = {
     body?: never;
     path?: never;
@@ -645,12 +1290,59 @@ type GetCreditsResponses = {
      * Credit balance
      */
     200: {
-        success: true;
-        requestId: string;
-        data: CreditsData;
+        success?: true;
+        requestId?: string;
+        data?: {
+            /**
+             * Current credit balance.
+             */
+            credits?: number;
+        };
     };
 };
 type GetCreditsResponse = GetCreditsResponses[keyof GetCreditsResponses];
+type GetUsageData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Time window: 'today', the last 7 days, or the last 30 days.
+         */
+        days?: "today" | "7" | "30";
+        /**
+         * Timezone offset in minutes used to bucket activity into days. Defaults to UTC.
+         */
+        tz?: string;
+    };
+    url: "/v1/usage";
+};
+type GetUsageErrors = {
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+};
+type GetUsageError = GetUsageErrors[keyof GetUsageErrors];
+type GetUsageResponses = {
+    /**
+     * Daily usage
+     */
+    200: {
+        success?: true;
+        requestId?: string;
+        data?: {
+            items?: Array<{
+                /**
+                 * e.g. 2026-05-28
+                 */
+                date?: string;
+                credits?: number;
+                requests?: number;
+            }>;
+        };
+    };
+};
+type GetUsageResponse = GetUsageResponses[keyof GetUsageResponses];
 type GetLogsData = {
     body?: never;
     path?: never;
@@ -682,66 +1374,252 @@ type GetLogsResponses = {
      * Request logs
      */
     200: {
-        success: true;
-        requestId: string;
-        data: LogsData;
+        success?: true;
+        requestId?: string;
+        data?: {
+            logs?: Array<{
+                id?: string;
+                userId?: string;
+                apiKeyId?: string | null;
+                apiKeyName?: string | null;
+                /**
+                 * e.g. /video
+                 */
+                endpoint?: string;
+                /**
+                 * e.g. POST
+                 */
+                method?: string;
+                status?: number;
+                credits?: number;
+                durationMs?: number | null;
+                /**
+                 * Serialized response body.
+                 */
+                response?: string | null;
+                createdAt?: string;
+            }>;
+            /**
+             * Total number of matching log entries.
+             */
+            total?: number;
+            /**
+             * Zero-based page index that was returned.
+             */
+            page?: number;
+            /**
+             * Fixed page size (50).
+             */
+            pageSize?: number;
+            totalPages?: number;
+            /**
+             * Distinct endpoints seen for this account, useful for building filters.
+             */
+            endpoints?: Array<string>;
+        };
     };
 };
 type GetLogsResponse = GetLogsResponses[keyof GetLogsResponses];
-type GetUsageData = {
-    body?: never;
+type McpTransportHeaderData = {
+    /**
+     * JSON-RPC 2.0 request envelope with jsonrpc, id, method, and params fields.
+     */
+    body: {
+        jsonrpc: "2.0";
+        /**
+         * Request identifier echoed in the response.
+         */
+        id: unknown;
+        /**
+         * JSON-RPC method, e.g. initialize, tools/list, tools/call.
+         */
+        method: string;
+        params?: {
+            [key: string]: unknown;
+        };
+        [key: string]: unknown | "2.0" | string | {
+            [key: string]: unknown;
+        } | undefined;
+    };
     path?: never;
-    query?: {
+    query?: never;
+    url: "/v1/mcp";
+};
+type McpTransportHeaderErrors = {
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+    /**
+     * Method not allowed. Use POST.
+     */
+    405: ErrorResponse;
+};
+type McpTransportHeaderError = McpTransportHeaderErrors[keyof McpTransportHeaderErrors];
+type McpTransportHeaderResponses = {
+    /**
+     * MCP response
+     */
+    200: {
+        [key: string]: unknown;
+    };
+};
+type McpTransportHeaderResponse = McpTransportHeaderResponses[keyof McpTransportHeaderResponses];
+type McpTransportPathData = {
+    /**
+     * JSON-RPC 2.0 request envelope with jsonrpc, id, method, and params fields.
+     */
+    body: {
+        jsonrpc: "2.0";
         /**
-         * Time window: 'today', the last 7 days, or the last 30 days.
+         * Request identifier echoed in the response.
          */
-        days?: "today" | "7" | "30";
+        id: unknown;
         /**
-         * Timezone offset in minutes used to bucket activity into days. Defaults to UTC.
+         * JSON-RPC method, e.g. initialize, tools/list, tools/call.
          */
-        tz?: string;
+        method: string;
+        params?: {
+            [key: string]: unknown;
+        };
+        [key: string]: unknown | "2.0" | string | {
+            [key: string]: unknown;
+        } | undefined;
     };
-    url: "/v1/usage";
+    path: {
+        /**
+         * Your Stophy API key in the format st_<key>
+         */
+        apiKey: string;
+    };
+    query?: never;
+    url: "/v1/mcp/{apiKey}";
 };
-type GetUsageErrors = {
+type McpTransportPathErrors = {
     /**
      * Unauthorized
      */
     401: ErrorResponse;
+    /**
+     * Method not allowed. Use POST.
+     */
+    405: ErrorResponse;
 };
-type GetUsageError = GetUsageErrors[keyof GetUsageErrors];
-type GetUsageResponses = {
+type McpTransportPathError = McpTransportPathErrors[keyof McpTransportPathErrors];
+type McpTransportPathResponses = {
     /**
-     * Daily usage
+     * MCP response
      */
     200: {
-        success: true;
-        requestId: string;
-        data: UsageData;
+        [key: string]: unknown;
     };
 };
-type GetUsageResponse = GetUsageResponses[keyof GetUsageResponses];
+type McpTransportPathResponse = McpTransportPathResponses[keyof McpTransportPathResponses];
 type ClientOptions = {
     baseUrl: "https://api.stophy.dev" | (string & {});
 };
 
+interface MeteredResponse<T> {
+    success: true;
+    requestId: string;
+    cacheState: "hit" | "miss";
+    creditsUsed: number;
+    creditsRemaining: number;
+    warning?: string;
+    data: T;
+}
+interface AccountResponse<T> {
+    success: true;
+    requestId: string;
+    data: T;
+}
+
+type CreditsResponse = AccountResponse<NonNullable<GetCreditsResponse["data"]>>;
+type LogsResponse = AccountResponse<NonNullable<GetLogsResponse["data"]>>;
+type UsageResponse = AccountResponse<NonNullable<GetUsageResponse["data"]>>;
+
 type ChannelBody = GetChannelData["body"];
 type ChannelOptions = Omit<ChannelBody, "channelUrl">;
+type GeneratedChannelData = NonNullable<GetChannelResponse["data"]>;
+type GeneratedChannelItem = GeneratedChannelData["items"][number];
+interface ChannelCourseItem {
+    type: "course";
+    id: string;
+    url: string;
+    courseUrl: string;
+    playlistUrl: string;
+    title: string | null;
+    author: string | null;
+    authorId: string | null;
+    videoCount: number | null;
+    videoCountText: string | null;
+    thumbnails: Array<{
+        url: string;
+        width: number;
+        height: number;
+    }>;
+}
+type ChannelData = Omit<GeneratedChannelData, "items" | "tab"> & {
+    items: Array<GeneratedChannelItem | ChannelCourseItem>;
+    tab: ChannelBody["tab"] | "community" | "course";
+};
+type ChannelResponse = MeteredResponse<ChannelData>;
+
+type KidsInput = {
+    type: "search";
+    q: string;
+    continuationToken?: string;
+} | {
+    type: "video";
+    videoUrl: string;
+};
+type KidsDataFor<T extends KidsInput["type"]> = T extends "search" ? KidsSearchData : KidsVideoData;
+
+type GeneratedMusicBody = YoutubeMusicData["body"];
+type SearchType = NonNullable<GeneratedMusicBody["searchType"]>;
+type MusicInput = {
+    type: "search";
+    q: string;
+    searchType?: SearchType;
+    continuationToken?: string;
+} | {
+    type: "suggest";
+    q: string;
+} | {
+    type: "song" | "lyrics";
+    videoUrl: string;
+} | {
+    type: "album";
+    albumUrl: string;
+} | {
+    type: "artist";
+    artistUrl: string;
+} | {
+    type: "playlist";
+    playlistUrl: string;
+    continuationToken?: string;
+};
+type MusicDataFor<T extends MusicInput["type"]> = T extends "search" ? MusicSearchData : T extends "suggest" ? MusicSuggestData : T extends "song" ? MusicSongData : T extends "lyrics" ? MusicLyricsData : T extends "album" ? MusicAlbumData : T extends "artist" ? MusicArtistData : MusicPlaylistData;
 
 type PlaylistBody = GetPlaylistData["body"];
 type PlaylistOptions = Omit<PlaylistBody, "playlistUrl">;
+type PlaylistResponse = MeteredResponse<NonNullable<GetPlaylistResponse["data"]>>;
 
 type SearchBody = SearchVideosData["body"];
 type SearchOptions = Omit<SearchBody, "q">;
+type SearchResponse = MeteredResponse<NonNullable<SearchVideosResponse["data"]>>;
 
-type SuggestQuery = GetSuggestionsData["query"];
-type SuggestOptions = Omit<SuggestQuery, "q">;
+type SuggestBody = GetSuggestionsData["body"];
+type SuggestOptions = Omit<SuggestBody, "q">;
+type SuggestResponse = MeteredResponse<NonNullable<GetSuggestionsResponse["data"]>>;
 
-type VideoResponseFor<T> = Omit<GetVideoResponse, "data"> & {
-    data: T;
-};
-type CommentsOptions = Pick<GetVideoData["body"], "sortBy" | "continuationToken">;
-type LiveChatOptions = Pick<GetVideoData["body"], "chatType" | "continuationToken">;
+type VideoResponseFor<T> = MeteredResponse<T>;
+type VideoUrlBody = Extract<GetVideoData["body"], {
+    videoUrl: string;
+}>;
+type CommentsOptions = Pick<VideoUrlBody, "sortBy" | "continuationToken">;
+type TranscriptOptions = Pick<VideoUrlBody, "lang">;
+type LiveChatOptions = Pick<VideoUrlBody, "chatType" | "continuationToken">;
 
 interface StophyOptions {
     /** Defaults to `STOPHY_API_KEY`. */
@@ -760,33 +1638,38 @@ declare class Stophy {
     constructor(input?: StophyClientInput);
     video(body: GetVideoData["body"] & {
         type: "details";
-    }): Promise<VideoResponseFor<VideoDetailsData>>;
+    }): Promise<VideoResponseFor<VideoResponseDetails>>;
     video(body: GetVideoData["body"] & {
         type: "transcript";
-    }): Promise<VideoResponseFor<TranscriptResult>>;
+    }): Promise<VideoResponseFor<VideoResponseTranscript>>;
+    video(body: GetVideoData["body"] & {
+        type: "comments";
+    }): Promise<VideoResponseFor<VideoResponseComments>>;
     video(body: GetVideoData["body"] & {
-        type: "comments" | "replies";
-    }): Promise<VideoResponseFor<CommentsData>>;
+        type: "replies";
+    }): Promise<VideoResponseFor<VideoResponseReplies>>;
     video(body: GetVideoData["body"] & {
         type: "livechat";
-    }): Promise<VideoResponseFor<LiveChatData>>;
+    }): Promise<VideoResponseFor<VideoResponseLivechat>>;
     video(body: GetVideoData["body"]): Promise<GetVideoResponse>;
-    videoDetails(videoUrl: string): Promise<VideoResponseFor<VideoDetailsData>>;
-    transcript(videoUrl: string): Promise<VideoResponseFor<TranscriptResult>>;
-    comments(videoUrl: string, options?: CommentsOptions): Promise<VideoResponseFor<CommentsData>>;
-    replies(continuationToken: string): Promise<VideoResponseFor<CommentsData>>;
-    liveChat(videoUrl: string, options?: LiveChatOptions): Promise<VideoResponseFor<LiveChatData>>;
-    search(body: SearchVideosData["body"]): Promise<SearchVideosResponse>;
-    search(query: string, options?: SearchOptions): Promise<SearchVideosResponse>;
-    channel(body: GetChannelData["body"]): Promise<GetChannelResponse>;
-    channel(channelUrl: string, options?: ChannelOptions): Promise<GetChannelResponse>;
-    playlist(body: GetPlaylistData["body"]): Promise<GetPlaylistResponse>;
-    playlist(playlistUrl: string, options?: PlaylistOptions): Promise<GetPlaylistResponse>;
-    suggest(query: GetSuggestionsData["query"]): Promise<GetSuggestionsResponse>;
-    suggest(query: string, options?: SuggestOptions): Promise<GetSuggestionsResponse>;
-    credits(): Promise<GetCreditsResponse>;
-    logs(query?: GetLogsData["query"]): Promise<GetLogsResponse>;
-    usage(query?: GetUsageData["query"]): Promise<GetUsageResponse>;
+    videoDetails(videoUrl: string): Promise<VideoResponseFor<VideoResponseDetails>>;
+    transcript(videoUrl: string, options?: TranscriptOptions): Promise<VideoResponseFor<VideoResponseTranscript>>;
+    comments(videoUrl: string, options?: CommentsOptions): Promise<VideoResponseFor<VideoResponseComments>>;
+    replies(continuationToken: string): Promise<VideoResponseFor<VideoResponseReplies>>;
+    liveChat(videoUrl: string, options?: LiveChatOptions): Promise<VideoResponseFor<VideoResponseLivechat>>;
+    search(body: SearchVideosData["body"]): Promise<SearchResponse>;
+    search(query: string, options?: SearchOptions): Promise<SearchResponse>;
+    channel(body: GetChannelData["body"]): Promise<ChannelResponse>;
+    channel(channelUrl: string, options?: ChannelOptions): Promise<ChannelResponse>;
+    playlist(body: GetPlaylistData["body"]): Promise<PlaylistResponse>;
+    playlist(playlistUrl: string, options?: PlaylistOptions): Promise<PlaylistResponse>;
+    suggest(query: GetSuggestionsData["body"]): Promise<SuggestResponse>;
+    suggest(query: string, options?: SuggestOptions): Promise<SuggestResponse>;
+    music<T extends MusicInput>(body: T): Promise<MeteredResponse<MusicDataFor<T["type"]>>>;
+    kids<T extends KidsInput>(body: T): Promise<MeteredResponse<KidsDataFor<T["type"]>>>;
+    credits(): Promise<CreditsResponse>;
+    logs(query?: GetLogsData["query"]): Promise<LogsResponse>;
+    usage(query?: GetUsageData["query"]): Promise<UsageResponse>;
 }
 
 /** Thrown when the Stophy API responds with a non-success status. */
@@ -803,4 +1686,4 @@ declare class StophyError extends Error {
     });
 }
 
-export { type ChannelData, type ChannelLink, type ChannelOptions, type ChannelProfile, type ClientOptions, type Comment, type CommentsData, type CommentsOptions, type ContentItem, type CreditsData, type EmptyState, type ErrorResponse, type GetChannelData, type GetChannelError, type GetChannelErrors, type GetChannelResponse, type GetChannelResponses, type GetCreditsData, type GetCreditsError, type GetCreditsErrors, type GetCreditsResponse, type GetCreditsResponses, type GetLogsData, type GetLogsError, type GetLogsErrors, type GetLogsResponse, type GetLogsResponses, type GetPlaylistData, type GetPlaylistError, type GetPlaylistErrors, type GetPlaylistResponse, type GetPlaylistResponses, type GetSuggestionsData, type GetSuggestionsError, type GetSuggestionsErrors, type GetSuggestionsResponse, type GetSuggestionsResponses, type GetUsageData, type GetUsageError, type GetUsageErrors, type GetUsageResponse, type GetUsageResponses, type GetVideoData, type GetVideoError, type GetVideoErrors, type GetVideoResponse, type GetVideoResponses, type LiveChatData, type LiveChatMessage, type LiveChatOptions, type LogEntry, type LogsData, type PlaylistData, type PlaylistItem, type PlaylistMeta, type PlaylistOptions, type RelatedVideo, type SearchChannel, type SearchData, type SearchItem, type SearchOptions, type SearchPlaylist, type SearchShort, type SearchVideo, type SearchVideosData, type SearchVideosError, type SearchVideosErrors, type SearchVideosResponse, type SearchVideosResponses, Stophy, type StophyClientInput, StophyError, type StophyOptions, type SuggestData, type SuggestOptions, type Thumbnail, type TranscriptLanguage, type TranscriptResult, type TranscriptSegment, type UsageData, type UsageItem, type VideoData, type VideoDetails, type VideoDetailsData, Stophy as default };
+export { type AccountResponse, type ChannelOptions, type ChannelResponse, type ClientOptions, type Comment, type CommentsOptions, type CreditsResponse, type EmptyState, type ErrorResponse, type GetChannelData, type GetChannelError, type GetChannelErrors, type GetChannelResponse, type GetChannelResponses, type GetCreditsData, type GetCreditsError, type GetCreditsErrors, type GetCreditsResponse, type GetCreditsResponses, type GetLogsData, type GetLogsError, type GetLogsErrors, type GetLogsResponse, type GetLogsResponses, type GetPlaylistData, type GetPlaylistError, type GetPlaylistErrors, type GetPlaylistResponse, type GetPlaylistResponses, type GetSuggestionsData, type GetSuggestionsError, type GetSuggestionsErrors, type GetSuggestionsResponse, type GetSuggestionsResponses, type GetUsageData, type GetUsageError, type GetUsageErrors, type GetUsageResponse, type GetUsageResponses, type GetVideoData, type GetVideoError, type GetVideoErrors, type GetVideoResponse, type GetVideoResponses, type KidsDataFor, type KidsInput, type KidsResponseData, type KidsSearchData, type KidsVideoData, type KidsVideoDetails, type KidsVideoItem, type LiveChatOptions, type LogsResponse, type McpTool, type McpTransportHeaderData, type McpTransportHeaderError, type McpTransportHeaderErrors, type McpTransportHeaderResponse, type McpTransportHeaderResponses, type McpTransportPathData, type McpTransportPathError, type McpTransportPathErrors, type McpTransportPathResponse, type McpTransportPathResponses, type MeteredResponse, type MusicAlbumData, type MusicAlbumRef, type MusicArtistData, type MusicArtistRef, type MusicDataFor, type MusicInput, type MusicItem, type MusicLyricsData, type MusicPlaylistData, type MusicResponseData, type MusicSearchData, type MusicSong, type MusicSongData, type MusicSuggestData, type PlaylistOptions, type PlaylistResponse, type RelatedVideo, type Reply, type SearchOptions, type SearchResponse, type SearchVideosData, type SearchVideosError, type SearchVideosErrors, type SearchVideosResponse, type SearchVideosResponses, Stophy, type StophyClientInput, StophyError, type StophyOptions, type SuggestOptions, type SuggestResponse, type Thumbnail, type UsageResponse, type VideoDetail, type VideoRequestReplies, type VideoRequestVideoOp, type VideoResponseComments, type VideoResponseDetails, type VideoResponseLivechat, type VideoResponseReplies, type VideoResponseTranscript, type YoutubeKidsData, type YoutubeKidsError, type YoutubeKidsErrors, type YoutubeKidsResponse, type YoutubeKidsResponses, type YoutubeMusicData, type YoutubeMusicError, type YoutubeMusicErrors, type YoutubeMusicResponse, type YoutubeMusicResponses, Stophy as default };