Skip to content

YoutubeService

katanakit-js / YoutubeService

Defined in: core/services/youtube.service.ts:46

YoutubeService — Singleton facade over the YouTube Data API v3 and the keyless channel RSS feed.

Applies the Singleton pattern (one shared instance via YoutubeService.getInstance, so the registered API config and the default channel are shared process-wide) and the Facade pattern: each public method hides registry keys, HTTP calls, schema validation and video normalization behind one call returning a Safe Result.

Every public method uses the use* prefix per CONTRIBUTING.md; the module level use* functions below are thin wrappers kept for call-site ergonomics.

import { useGetChannelVideos, useInitYoutube } from "katanakit-js";
useInitYoutube({ apiKey: process.env.YOUTUBE_API_KEY!, channelId: "UC…" });
const page = await useGetChannelVideos({ maxResults: 6 });
useBuildYoutubeRssUrl(channelId): string;

Defined in: core/services/youtube.service.ts:177

Builds the public channel RSS feed URL. Needs no API key and costs zero quota — ideal for “latest videos” widgets.

Parameter Type Description
channelId string Channel id (UC…).

string

Feed URL.


useGetChannelVideos(params?): Promise<FetchResult<{
nextPageToken?: string;
prevPageToken?: string;
totalResults?: number;
videos: {
channelTitle?: string;
description: string;
durationSeconds?: number;
embedUrl: string;
id: string;
publishedAt: string;
thumbnail: string;
thumbnails: {
default: string;
high: string;
medium: string;
};
title: string;
url: string;
viewCount?: number;
}[];
}>>;

Defined in: core/services/youtube.service.ts:280

Lists channel videos via the quota-cheap path (channels → playlistItems, never search.list which costs 100 units). Call server/build-time and cache the response (1h) to share quota across every repo using the same GCP project.

Parameter Type Description
params? { channelId?: string; maxResults?: number; pageToken?: string; playlistId?: string; } Channel/playlist, page size (1–50) and page token.
params.channelId? string Channel id (defaults to the one from useInitYoutube).
params.maxResults? number Items per page (1–50, defaults to 12).
params.pageToken? string Opaque page token from a previous response.
params.playlistId? string Skip the channels lookup when the uploads playlist id is known.

Promise<FetchResult<{ nextPageToken?: string; prevPageToken?: string; totalResults?: number; videos: { channelTitle?: string; description: string; durationSeconds?: number; embedUrl: string; id: string; publishedAt: string; thumbnail: string; thumbnails: { default: string; high: string; medium: string; }; title: string; url: string; viewCount?: number; }[]; }>>

Safe Result with normalized videos + pagination.


useGetChannelVideosRss(channelId?): Promise<FetchResult<{
channelTitle?: string;
description: string;
durationSeconds?: number;
embedUrl: string;
id: string;
publishedAt: string;
thumbnail: string;
thumbnails: {
default: string;
high: string;
medium: string;
};
title: string;
url: string;
viewCount?: number;
}[]>>;

Defined in: core/services/youtube.service.ts:458

Fetches the keyless channel RSS feed and parses it. Zero quota, limited to the latest ~15 videos with basic metadata.

Parameter Type Description
channelId? string Channel id (defaults to the configured one).

Promise<FetchResult<{ channelTitle?: string; description: string; durationSeconds?: number; embedUrl: string; id: string; publishedAt: string; thumbnail: string; thumbnails: { default: string; high: string; medium: string; }; title: string; url: string; viewCount?: number; }[]>>

Safe Result with normalized videos.


useGetUploadsPlaylistId(channelId?): Promise<FetchResult<string>>;

Defined in: core/services/youtube.service.ts:224

Resolves a channel id to its uploads playlist id (quota cost: 1 unit). Prefer passing playlistId to useGetChannelVideos to skip this call.

Parameter Type Description
channelId? string Channel id (defaults to the configured one).

Promise<FetchResult<string>>

Safe Result with the uploads playlist id.


useGetVideoDetails(ids): Promise<FetchResult<{
channelTitle?: string;
description: string;
durationSeconds?: number;
embedUrl: string;
id: string;
publishedAt: string;
thumbnail: string;
thumbnails: {
default: string;
high: string;
medium: string;
};
title: string;
url: string;
viewCount?: number;
}[]>>;

Defined in: core/services/youtube.service.ts:366

Enriches videos with duration and view count (videos.list, 1 unit).

Parameter Type Description
ids string[] Up to 50 video ids.

Promise<FetchResult<{ channelTitle?: string; description: string; durationSeconds?: number; embedUrl: string; id: string; publishedAt: string; thumbnail: string; thumbnails: { default: string; high: string; medium: string; }; title: string; url: string; viewCount?: number; }[]>>

Safe Result with enriched videos.


useGetYoutubeConfig(): {
apiKey: string;
channelId: string;
};

Defined in: core/services/youtube.service.ts:166

Returns a shallow copy of the YouTube config (safe to mutate locally).

The current { apiKey, channelId }.

apiKey: string;

YouTube Data API v3 key (server/build-time only, never public).

channelId: string;

Default channel id (UC…). Per-call params can override it.


useInitYoutube(config): void;

Defined in: core/services/youtube.service.ts:138

Registers the YouTube APIs (youtube + keyless youtubeFeed) and stores the default channel. Call once per app, server/build-time — the API key must never ship to the browser.

Parameter Type Description
config { apiKey: string; channelId: string; } API key + default channel id.
config.apiKey? string YouTube Data API v3 key (server/build-time only, never public).
config.channelId? string Default channel id (UC…). Per-call params can override it.

void

useInitYoutube({ apiKey: process.env.YOUTUBE_API_KEY!, channelId: "UC…" });
const page = await useGetChannelVideos({ maxResults: 6 });

useParseIso8601Duration(input): number;

Defined in: core/services/youtube.service.ts:190

Parses an ISO 8601 duration (PT1H2M3S) into seconds. Pure and SSR-safe.

Parameter Type Description
input string Duration string from contentDetails.duration.

number

Total seconds (0 for invalid input).


useParseYoutubeRss(xml): {
channelTitle?: string;
description: string;
durationSeconds?: number;
embedUrl: string;
id: string;
publishedAt: string;
thumbnail: string;
thumbnails: {
default: string;
high: string;
medium: string;
};
title: string;
url: string;
viewCount?: number;
}[];

Defined in: core/services/youtube.service.ts:426

Parses a YouTube channel RSS feed (feeds/videos.xml) into normalized videos. Pure and SSR-safe — no network, no DOM parser.

Parameter Type Description
xml string Raw feed XML.

{ channelTitle?: string; description: string; durationSeconds?: number; embedUrl: string; id: string; publishedAt: string; thumbnail: string; thumbnails: { default: string; high: string; medium: string; }; title: string; url: string; viewCount?: number; }[]

Normalized videos (newest first, as served by the feed).


static getInstance(): YoutubeService;

Defined in: core/services/youtube.service.ts:56

Returns the shared instance (Singleton).

YoutubeService