YouTube channel

This pack gives an agent video and Shorts uploads, comments, search, trends, statistics, playlist management and scheduled publishing through the YouTube Data API using googleapis. Code that holds the service can also read the status of a batch of videos (below).

Installation

npm install @framers/agentos-ext-channel-youtube

Peer dependency: @framers/agentos >=0.10.40.

Usage

import { AgentOS } from '@framers/agentos';

const agentos = await AgentOS.create({
  extensionManifest: {
    packs: [
      {
        package: '@framers/agentos-ext-channel-youtube',
        options: { apiKey: process.env.YOUTUBE_API_KEY },
      },
    ],
  },
});

Configuration

The API key resolves from options, then options.secrets, then environment variables. The first environment lookup uses apiKeyEnv, which defaults to YOUTUBE_API_KEY. An explicit oauth object overrides OAuth secret and environment resolution. Otherwise each OAuth field resolves from secrets before its environment variable, and OAuth is enabled only when all fields resolve. The oauth interface requires all fields when the object is supplied.

Tools

youtubeUpload

youtubeShort

youtubeComment

youtubeSearch

youtubeTrending

youtubeAnalytics

youtubePlaylist

youtubeSchedule

Channel adapter

The adapter registers platform youtube. Activation initializes the API service, and connection status follows its running state. A video block triggers an upload from its HTTPS URL; metadata comes from platformOptions.title, platformOptions.tags, platformOptions.categoryId and platformOptions.privacyStatus. The title falls back to the video caption, then Untitled; a text block supplies the description before the caption fallback.

Without a video block, sending posts a comment using conversationId as the video ID and replyToMessageId as the optional parent comment ID. Empty video IDs or comment text throw. The adapter stores event handlers but emits no inbound events. Typing indicators do nothing.

Reading the status of videos

YouTubeService.getVideosStatus(videoIds) reads the status of many videos at once and needs the API key alone. It calls videos.list with the parts snippet, status and contentDetails once for each fifty ids, and each call costs one quota unit, so 120 ids cost three units.

It returns one row for each video the API returned, in the order of the ids asked for. An id asked twice is read once and has one row. An id the API returns nothing for, such as a removed or private video, has no row. A row holds the video's id and these fields, each value as the API gave it, so a caller checks a value's type itself:

A field the API left out is absent from the row. An empty list makes no call. A failed call, a refused quota among them, rejects with the API's own error, and no rows are returned. The method stores nothing and logs nothing.

import { YouTubeService, type VideoStatusRow } from '@framers/agentos-ext-channel-youtube';

const youtube = new YouTubeService({ apiKey: process.env.YOUTUBE_API_KEY! });
await youtube.initialize();
const rows: VideoStatusRow[] = await youtube.getVideosStatus(['video-id-1', 'video-id-2']);

Notes

Creating the pack throws if no API key resolves. Uploads, comments, playlist creation, playlist additions and playlist deletion require OAuth credentials and change content on the account. Listing the account's own playlists also requires OAuth. Channel analytics require channelId when OAuth is absent.

Upload tools fetch HTTP or HTTPS video URLs and stream responses to the API. They set no download timeout, check no HTTP response status and implement no redirect handling. The service defaults uploads to public, video/mp4 and the People & Blogs category, and sets selfDeclaredMadeForKids to false.

Shorts uploads add Shorts to tags and append #Shorts to the description. The code does not validate duration or orientation. Scheduling rejects invalid or past dates, then uploads with private privacy and publishAt; it uses no local publishing timer.

Search, trending and playlist listing requests are capped at 50 results. Playlist lists default to 25 results. Tool failures return success: false and an error message. Action-specific playlist fields and video analytics IDs are checked during execution despite being optional in their schemas.

Releases

New versions are published from framerslab/agentos-extensions by GitHub Actions through npm trusted publishing, with a provenance statement.

License

Apache-2.0