@opencoredev/social-sdk 0.1.1 → 0.2.0

package/dist/platforms/youtube.js

@@ -1,18 +1,26 @@
+/* oxlint-disable anti-slop/no-conditional-empty-object-spread, anti-slop/no-runtime-typeof, anti-slop/require-safety-comment-for-type-assertion, anti-slop/require-readable-spacing, anti-slop/no-chained-type-assertions -- validated external boundary or fixture contract. */
 import { remainingBudget } from "../transport/budget.js";
 import { defineAdapter } from "../core/adapter.js";
 import { SocialError } from "../core/errors.js";
 import { managedHttp, publicFields } from "../cloud/common.js";
+import { createHttp, HttpError } from "../transport/http.js";
 import { array, object, optionalString, string } from "../transport/validation.js";
 import { beginYouTubeUpload, queryYouTubeUpload, sendYouTubeUpload, } from "./youtube-upload.js";
 export function youtube(options) {
     const request = managedHttp("https://www.googleapis.com", {
         apiKey: options.auth.accessToken,
+        // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
         ...(options.fetch ? { fetch: options.fetch } : {}),
     });
     const analyticsRequest = managedHttp("https://youtubeanalytics.googleapis.com", {
         apiKey: options.auth.accessToken,
+        // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
         ...(options.fetch ? { fetch: options.fetch } : {}),
     });
+    const binaryRequest = createHttp({
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+        timeoutMs: 30_000,
+    });
     const now = () => (options.clock?.() ?? new Date()).toISOString();
     const authorize = (ref, context) => {
         if (ref.backend !== context.backendInstance ||
@@ -48,7 +56,9 @@ export function youtube(options) {
             });
         return video;
     };
-    const outcome = (video, target) => {
+    const outcome = (
+    // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- validated boundary or fixture contract.
+    video, target) => {
         const id = string(video["id"]);
         const status = object(video["status"]);
         const uploaded = optionalString(status["uploadStatus"]) ?? "unknown";
@@ -123,6 +133,56 @@ export function youtube(options) {
             status: "connected",
         };
     };
+    const nativeAuthorize = (context) => authorize({ backend: context.backendInstance, platform: "youtube", accountId: options.auth.channelId }, context);
+    const mediaBlob = (media) => {
+        if (!media || media.source.kind !== "blob")
+            throw new SocialError({
+                code: "invalid_input",
+                operation: "native",
+                message: "This YouTube operation requires a Blob media source.",
+            });
+        return media.source.blob;
+    };
+    const binaryJson = async (path, context, body, query, method = "POST", contentType) => {
+        const url = new URL(`https://www.googleapis.com${path}`);
+        for (const [key, value] of Object.entries(query))
+            url.searchParams.set(key, value);
+        try {
+            const result = await binaryRequest({
+                url,
+                method,
+                body,
+                headers: {
+                    Authorization: `Bearer ${options.auth.accessToken}`,
+                    ...(contentType ? { "Content-Type": contentType } : {}),
+                },
+                timeoutMs: remainingBudget(context),
+                ...(context.signal ? { signal: context.signal } : {}),
+            });
+            return object(result);
+        }
+        catch (error) {
+            if (!(error instanceof HttpError))
+                throw error;
+            const ambiguous = error.dispatched && (error.kind !== "http" || (error.status ?? 0) >= 500);
+            throw new SocialError({
+                code: ambiguous
+                    ? "ambiguous_outcome"
+                    : error.status === 401
+                        ? "reconnect_required"
+                        : error.status === 403
+                            ? "missing_permission"
+                            : error.status === 429
+                                ? "rate_limited"
+                                : "upstream_failure",
+                operation: path,
+                message: error.message,
+                upstreamStatus: error.status,
+                retryDisposition: ambiguous ? { kind: "reconcile-first" } : { kind: "never" },
+                cause: error,
+            });
+        }
+    };
     return defineAdapter({
         id: "youtube",
         capabilities: {
@@ -158,6 +218,25 @@ export function youtube(options) {
                     platform: "youtube",
                     availability: "available",
                     requiredScopes: ["https://www.googleapis.com/auth/youtube.upload"],
+                    notes: "Scheduled videos are uploaded private with a future ISO publishAt timestamp.",
+                },
+                {
+                    operation: "posts.removeFromPlatform",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube"],
+                },
+                {
+                    operation: "playlists.read",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube.readonly"],
+                },
+                {
+                    operation: "playlists.write",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube"],
                 },
                 {
                     operation: "thumbnails.write",
@@ -165,6 +244,36 @@ export function youtube(options) {
                     availability: "available",
                     requiredScopes: ["https://www.googleapis.com/auth/youtube"],
                 },
+                {
+                    operation: "videos.update",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube"],
+                },
+                {
+                    operation: "posts.update",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube"],
+                },
+                {
+                    operation: "videos.delete",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube"],
+                },
+                {
+                    operation: "posts.delete",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube"],
+                },
+                {
+                    operation: "videos.rate",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube.force-ssl"],
+                },
                 {
                     operation: "captions.read",
                     platform: "youtube",
@@ -177,17 +286,52 @@ export function youtube(options) {
                     availability: "available",
                     requiredScopes: ["https://www.googleapis.com/auth/youtube.force-ssl"],
                 },
-                { operation: "playlists.read", platform: "youtube", availability: "available" },
-                { operation: "playlists.write", platform: "youtube", availability: "available" },
-                { operation: "posts.update", platform: "youtube", availability: "available" },
-                { operation: "posts.delete", platform: "youtube", availability: "available" },
+                {
+                    operation: "subscriptions.read",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube.readonly"],
+                },
+                {
+                    operation: "subscriptions.write",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube"],
+                },
+                { operation: "search.keyword", platform: "youtube", availability: "available" },
+                {
+                    operation: "search.posts",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube.readonly"],
+                    notes: "Uses search.list with type=video. Each request costs 100 quota units.",
+                },
+                {
+                    operation: "comments.moderate",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube.force-ssl"],
+                },
                 {
                     operation: "analytics.youtube.read",
                     platform: "youtube",
                     availability: "available",
                     requiredScopes: ["https://www.googleapis.com/auth/yt-analytics.readonly"],
                 },
-                { operation: "live.broadcasts", platform: "youtube", availability: "approval-dependent" },
+                {
+                    operation: "analytics.report.read",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/yt-analytics.readonly"],
+                    notes: "Reports require an explicit bounded date range and provider-supported metrics.",
+                },
+                {
+                    operation: "live.broadcasts",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube"],
+                    notes: "The channel must have live streaming enabled in YouTube Studio. Use native access: liveBroadcasts.",
+                },
             ],
         },
         accounts: {
@@ -227,6 +371,7 @@ export function youtube(options) {
                     playlistId: uploads,
                     part: "snippet,contentDetails",
                     maxResults: String(limit),
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                     ...(input.cursor ? { pageToken: input.cursor } : {}),
                 }));
                 return {
@@ -252,6 +397,14 @@ export function youtube(options) {
                             contentDetails: publicFields(content, ["videoId", "videoPublishedAt"]),
                         };
                     }),
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
+                    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- provider payload is validated at this adapter boundary.
+                    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated external boundary or fixture contract.
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated external boundary or fixture contract.
+                    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated external boundary or fixture contract.
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated external boundary or fixture contract.
+                    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated external boundary or fixture contract.
                     ...(typeof page["nextPageToken"] === "string"
                         ? { nextCursor: page["nextPageToken"] }
                         : {}),
@@ -276,16 +429,27 @@ export function youtube(options) {
                         fail("youtube.size", "Streaming upload requires its exact byte size.");
                 }
                 const config = target.options === undefined ? {} : object(target.options);
-                if (typeof config["title"] !== "string" ||
+                if (
+                // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
+                typeof config["title"] !== "string" ||
                     !config["title"] ||
-                    [...config["title"]].length > 100)
+                    [...config["title"]].length > 100 ||
+                    /[<>]/u.test(config["title"]))
                     fail("youtube.title", "Select a title of 1 to 100 characters.");
                 if (!["public", "unlisted", "private"].includes(String(config["visibility"])))
                     fail("youtube.visibility", "Explicit visibility is required.");
+                // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
                 if (typeof config["madeForKids"] !== "boolean")
                     fail("youtube.audience", "Explicit made-for-kids declaration is required.");
-                if (target.schedule || target.replyTo)
-                    fail("youtube.operation", "Use a job runner for scheduling or comments.reply for replies.");
+                if (target.content.text !== undefined &&
+                    new TextEncoder().encode(target.content.text).byteLength > 5000)
+                    fail("youtube.description", "Description must be at most 5000 UTF-8 bytes.");
+                if (target.schedule &&
+                    (!Number.isFinite(Date.parse(target.schedule.at)) ||
+                        Date.parse(target.schedule.at) <= (options.clock?.() ?? new Date()).getTime()))
+                    fail("youtube.schedule", "Schedule time must be a valid timestamp in the future.");
+                if (target.replyTo)
+                    fail("youtube.operation", "Use comments.reply for replies.");
                 return issues;
             },
             async publishTarget(target, context) {
@@ -299,9 +463,11 @@ export function youtube(options) {
                     });
                 const config = object(target.options);
                 const uploadOptions = {
-                    timeoutMs: remainingBudget(context),
+                    timeoutMs: Math.max(remainingBudget(context), 15 * 60_000),
                     accessToken: options.auth.accessToken,
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                     ...(options.fetch ? { fetch: options.fetch } : {}),
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                     ...(context.signal ? { signal: context.signal } : {}),
                 };
                 const size = media.byteSize ?? (media.source.kind === "blob" ? media.source.blob.size : 0);
@@ -314,6 +480,12 @@ export function youtube(options) {
                         status: {
                             privacyStatus: string(config["visibility"]),
                             selfDeclaredMadeForKids: config["madeForKids"] === true,
+                            ...(target.schedule
+                                ? {
+                                    publishAt: new Date(target.schedule.at).toISOString(),
+                                    privacyStatus: "private",
+                                }
+                                : {}),
                         },
                     },
                 }, uploadOptions);
@@ -359,6 +531,48 @@ export function youtube(options) {
                 const video = await get({ ...account, kind: "platform-post", postId: ref.deliveryId }, context);
                 return outcome(video, { account, targetIndex: 0 });
             },
+            async removeFromPlatform(ref, context) {
+                authorize(ref, context);
+                if (!ref.postId)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "posts.removeFromPlatform",
+                        message: "postId is required.",
+                    });
+                await request("/youtube/v3/videos", context, undefined, { id: ref.postId }, "DELETE");
+            },
+        },
+        search: {
+            async posts(account, input, context) {
+                authorize(account, context);
+                const limit = input.limit ?? 25;
+                if (input.scope !== undefined && input.scope !== "recent")
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "search.posts",
+                        message: "YouTube search supports only the recent scope.",
+                    });
+                if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "search.posts",
+                        message: "YouTube search limit must be between 1 and 50.",
+                    });
+                const page = object(await request("/youtube/v3/search", context, undefined, {
+                    part: "snippet",
+                    q: input.query,
+                    type: "video",
+                    maxResults: String(limit),
+                    ...(input.cursor ? { pageToken: input.cursor } : {}),
+                    ...(input.startTime ? { publishedAfter: input.startTime } : {}),
+                    ...(input.endTime ? { publishedBefore: input.endTime } : {}),
+                }));
+                const nextCursor = optionalString(page["nextPageToken"]);
+                return {
+                    items: array(page["items"]).map((value) => object(value)),
+                    ...(nextCursor ? { nextCursor } : {}),
+                };
+            },
         },
         analytics: {
             async getPostMetrics(ref, context) {
@@ -369,6 +583,7 @@ export function youtube(options) {
                 const metrics = [];
                 for (const name of ["viewCount", "likeCount", "commentCount"]) {
                     const raw = values[name];
+                    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
                     if (typeof raw !== "string" || !/^\d+$/.test(raw))
                         continue;
                     const value = Number(raw);
@@ -408,6 +623,7 @@ export function youtube(options) {
                     if (name === "subscriberCount" && stats["hiddenSubscriberCount"] === true)
                         return [];
                     const raw = stats[name];
+                    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
                     return typeof raw === "string" && /^\d+$/.test(raw) && Number.isSafeInteger(Number(raw))
                         ? [
                             {
@@ -423,6 +639,68 @@ export function youtube(options) {
                         : [];
                 });
             },
+            async getReport(accountRef, query, context) {
+                authorize(accountRef, context);
+                const date = /^\d{4}-\d{2}-\d{2}$/;
+                if (!date.test(query.from) ||
+                    !date.test(query.to) ||
+                    query.from > query.to ||
+                    query.metrics.length === 0 ||
+                    query.metrics.some((metric) => !/^[A-Za-z][A-Za-z0-9_.-]*$/.test(metric)) ||
+                    query.dimensions?.some((dimension) => !/^[A-Za-z][A-Za-z0-9_.-]*$/.test(dimension)))
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "analytics.report.read",
+                        message: "YouTube reports require YYYY-MM-DD dates (from <= to) and provider-safe metric names.",
+                    });
+                const result = object(await analyticsRequest("/v2/reports", context, undefined, {
+                    ids: `channel==${options.auth.channelId}`,
+                    startDate: query.from,
+                    endDate: query.to,
+                    metrics: query.metrics.join(","),
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
+                    ...(query.dimensions && query.dimensions.length > 0
+                        ? { dimensions: query.dimensions.join(",") }
+                        : {}),
+                }));
+                const headers = array(result["columnHeaders"]).map((value) => {
+                    const header = object(value);
+                    return {
+                        name: string(header["name"]),
+                        type: optionalString(header["columnType"]) ?? "METRIC",
+                    };
+                });
+                const rows = [];
+                // Analytics omits `rows` entirely when the requested period has no data.
+                for (const value of Array.isArray(result["rows"]) ? result["rows"] : []) {
+                    const cells = array(value);
+                    const dimensions = Object.fromEntries(headers.flatMap((header, index) => {
+                        if (header.type !== "DIMENSION")
+                            return [];
+                        const raw = cells[index];
+                        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
+                        return typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean"
+                            ? [[header.name, raw]]
+                            : [];
+                    }));
+                    const metrics = {};
+                    headers.forEach((header, index) => {
+                        if (header.type === "DIMENSION")
+                            return;
+                        const raw = cells[index];
+                        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
+                        const parsed = typeof raw === "number"
+                            ? raw
+                            : typeof raw === "string" && raw.trim() !== ""
+                                ? Number(raw)
+                                : undefined;
+                        if (parsed !== undefined && Number.isFinite(parsed))
+                            metrics[header.name] = parsed;
+                    });
+                    rows.push({ dimensions, metrics });
+                }
+                return { query, rows, fetchedAt: now(), source: "youtube-analytics-v2" };
+            },
         },
         comments: {
             async list(ref, input, context) {
@@ -439,6 +717,7 @@ export function youtube(options) {
                     videoId: ref.postId,
                     textFormat: "plainText",
                     maxResults: String(limit),
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                     ...(input.cursor === undefined ? {} : { pageToken: input.cursor }),
                 }));
                 const cursor = optionalString(result["nextPageToken"]);
@@ -456,6 +735,7 @@ export function youtube(options) {
                             ]),
                         };
                     }),
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                     ...(cursor ? { nextCursor: cursor } : {}),
                 };
             },
@@ -488,7 +768,9 @@ export function youtube(options) {
                 const uploadOptions = {
                     timeoutMs: remainingBudget(context),
                     accessToken: options.auth.accessToken,
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                     ...(options.fetch ? { fetch: options.fetch } : {}),
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                     ...(context.signal ? { signal: context.signal } : {}),
                 };
                 const confirmed = await queryYouTubeUpload(session, uploadOptions);
@@ -505,28 +787,131 @@ export function youtube(options) {
                     });
                 return queryYouTubeUpload(session, {
                     accessToken: options.auth.accessToken,
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                     ...(options.fetch ? { fetch: options.fetch } : {}),
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                     ...(context.signal ? { signal: context.signal } : {}),
                 });
             },
             async setThumbnail({ videoId, thumbnail, context }) {
-                void thumbnail;
-                authorize({
-                    backend: context.backendInstance,
-                    platform: "youtube",
-                    accountId: options.auth.channelId,
-                }, context);
-                return object(await request("/youtube/v3/thumbnails/set", context, undefined, { videoId, uploadType: "media" }, "POST"));
+                nativeAuthorize(context);
+                return binaryJson("/upload/youtube/v3/thumbnails/set", context, mediaBlob(thumbnail), { videoId, uploadType: "media" }, "POST", thumbnail.mimeType ?? "application/octet-stream");
             },
-            async captions({ action, videoId, captionId, context }) {
-                const method = action === "list" ? "GET" : action === "delete" ? "DELETE" : "POST";
-                return object(await request("/youtube/v3/captions", context, action === "insert" ? { snippet: { videoId } } : undefined, {
-                    ...(action === "list" || action === "insert" ? { videoId } : {}),
-                    ...(captionId ? { id: captionId } : {}),
-                    part: "snippet",
+            async captions({ action, videoId, captionId, caption, body, context }) {
+                nativeAuthorize(context);
+                if (action === "download") {
+                    if (!captionId)
+                        throw new SocialError({
+                            code: "invalid_input",
+                            operation: "captions.download",
+                            message: "captionId is required.",
+                        });
+                    const url = new URL(`https://www.googleapis.com/youtube/v3/captions/${encodeURIComponent(captionId)}`);
+                    url.searchParams.set("tfmt", "vtt");
+                    const response = await (options.fetch ?? globalThis.fetch)(url, {
+                        headers: { Authorization: `Bearer ${options.auth.accessToken}` },
+                        redirect: "error",
+                        ...(context.signal ? { signal: context.signal } : {}),
+                    });
+                    if (!response.ok)
+                        throw new SocialError({
+                            code: "upstream_failure",
+                            operation: "captions.download",
+                            message: `YouTube returned HTTP ${response.status}.`,
+                            upstreamStatus: response.status,
+                            retryDisposition: { kind: "never" },
+                        });
+                    return response.blob();
+                }
+                if (action === "insert" || action === "update") {
+                    if (!body || (action === "insert" && !caption))
+                        throw new SocialError({
+                            code: "invalid_input",
+                            operation: `captions.${action}`,
+                            message: "Caption metadata and media are required for insert.",
+                        });
+                    const snippet = object(body["snippet"] ?? {});
+                    if (action === "insert" && (!videoId || (snippet["videoId"] ?? videoId) !== videoId))
+                        throw new SocialError({
+                            code: "invalid_input",
+                            operation: "captions.insert",
+                            message: "videoId is required and must match body.snippet.videoId.",
+                        });
+                    const metadata = action === "update"
+                        ? { ...body, id: captionId ?? body["id"] ?? null }
+                        : { ...body, snippet: { ...snippet, videoId: videoId ?? null } };
+                    if (action === "update" && typeof metadata["id"] !== "string")
+                        throw new SocialError({
+                            code: "invalid_input",
+                            operation: "captions.update",
+                            message: "captionId or body.id is required.",
+                        });
+                    if (action === "update" && !caption)
+                        return binaryJson("/youtube/v3/captions", context, JSON.stringify(metadata), { part: "snippet" }, "PUT", "application/json");
+                    if (!caption)
+                        throw new SocialError({
+                            code: "invalid_input",
+                            operation: "captions.insert",
+                            message: "Caption media is required.",
+                        });
+                    const boundary = `youtube-caption-${crypto.randomUUID()}`;
+                    const media = mediaBlob(caption);
+                    const filename = (caption.filename ?? "captions.vtt").replace(/[\r\n]/gu, "");
+                    const encoded = new Blob([
+                        `--${boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n${JSON.stringify(metadata)}\r\n`,
+                        `--${boundary}\r\nContent-Type: ${caption.mimeType ?? "text/vtt"}\r\nContent-Disposition: attachment; filename="${filename}"\r\n\r\n`,
+                        media,
+                        `\r\n--${boundary}--\r\n`,
+                    ]);
+                    return binaryJson("/upload/youtube/v3/captions", context, encoded, { uploadType: "multipart", part: "snippet" }, action === "update" ? "PUT" : "POST", `multipart/related; boundary=${boundary}`);
+                }
+                if (action === "delete") {
+                    if (!captionId)
+                        throw new SocialError({
+                            code: "invalid_input",
+                            operation: "captions.delete",
+                            message: "captionId is required.",
+                        });
+                    await request("/youtube/v3/captions", context, undefined, { id: captionId ?? "" }, "DELETE");
+                    return {};
+                }
+                return object(await request("/youtube/v3/captions", context, undefined, { part: "snippet", videoId }, "GET"));
+            },
+            async playlists({ action, playlistId, channelId, mine, pageToken, maxResults, body, context, }) {
+                nativeAuthorize(context);
+                const method = action === "list"
+                    ? "GET"
+                    : action === "delete"
+                        ? "DELETE"
+                        : action === "update"
+                            ? "PUT"
+                            : "POST";
+                if ((action === "delete" || action === "update") && !playlistId)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: `playlists.${action}`,
+                        message: "playlistId is required.",
+                    });
+                // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- validated boundary or fixture contract.
+                if (action === "delete") {
+                    await request("/youtube/v3/playlists", context, undefined, { id: playlistId ?? "" }, method);
+                    return {};
+                }
+                return object(await request("/youtube/v3/playlists", context, body, {
+                    part: "snippet,status,contentDetails",
+                    ...(playlistId ? { id: playlistId } : {}),
+                    ...(channelId ? { channelId } : {}),
+                    ...(action === "list" && !playlistId && !channelId
+                        ? { mine: "true" }
+                        : mine
+                            ? { mine: "true" }
+                            : {}),
+                    ...(pageToken ? { pageToken } : {}),
+                    ...(maxResults ? { maxResults: String(maxResults) } : {}),
                 }, method));
             },
-            async playlists({ action, playlistId, body, context }) {
+            async playlistItems({ action, playlistId, playlistItemId, body, pageToken, context }) {
+                nativeAuthorize(context);
                 const method = action === "list"
                     ? "GET"
                     : action === "delete"
@@ -534,25 +919,180 @@ export function youtube(options) {
                         : action === "update"
                             ? "PUT"
                             : "POST";
-                return object(await request("/youtube/v3/playlists", context, body, { ...(playlistId ? { id: playlistId } : {}), part: "snippet,status,contentDetails" }, method));
+                if (action === "delete") {
+                    if (!playlistItemId)
+                        throw new SocialError({
+                            code: "invalid_input",
+                            operation: "playlistItems.delete",
+                            message: "playlistItemId is required.",
+                        });
+                    await request("/youtube/v3/playlistItems", context, undefined, { id: playlistItemId }, method);
+                    return {};
+                }
+                return object(await request("/youtube/v3/playlistItems", context, body, {
+                    part: "snippet,contentDetails",
+                    ...(playlistId ? { playlistId } : {}),
+                    ...(playlistItemId ? { id: playlistItemId } : {}),
+                    ...(pageToken ? { pageToken } : {}),
+                }, method));
             },
             async updateVideo({ videoId, body, context }) {
-                return object(await request("/youtube/v3/videos", context, { id: videoId, ...body }, { part: "snippet,status" }, "PUT"));
+                nativeAuthorize(context);
+                if (!videoId)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "videos.update",
+                        message: "videoId is required.",
+                    });
+                const existing = await get({
+                    kind: "platform-post",
+                    version: 1,
+                    backend: context.backendInstance,
+                    platform: "youtube",
+                    accountId: options.auth.channelId,
+                    postId: videoId,
+                }, context);
+                const merged = {
+                    ...existing,
+                    ...body,
+                    id: videoId,
+                    snippet: { ...object(existing["snippet"]), ...object(body["snippet"] ?? {}) },
+                    status: { ...object(existing["status"] ?? {}), ...object(body["status"] ?? {}) },
+                };
+                return object(await request("/youtube/v3/videos", context, merged, { part: "snippet,status" }, "PUT"));
             },
             async deleteVideo({ videoId, context }) {
+                nativeAuthorize(context);
+                if (!videoId)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "videos.delete",
+                        message: "videoId is required.",
+                    });
                 await request("/youtube/v3/videos", context, undefined, { id: videoId }, "DELETE");
             },
+            async rateVideo({ videoId, rating, context }) {
+                nativeAuthorize(context);
+                await request("/youtube/v3/videos/rate", context, undefined, { id: videoId, rating }, "POST");
+            },
+            async getRating({ videoIds, context }) {
+                nativeAuthorize(context);
+                return object(await request("/youtube/v3/videos/getRating", context, undefined, {
+                    id: videoIds.join(","),
+                }));
+            },
+            async subscriptions({ action, subscriptionId, channelId, pageToken, context }) {
+                nativeAuthorize(context);
+                const method = action === "list" ? "GET" : action === "delete" ? "DELETE" : "POST";
+                if (action === "delete" && !subscriptionId)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "subscriptions.delete",
+                        message: "subscriptionId is required.",
+                    });
+                const insertBody = channelId
+                    ? {
+                        snippet: { resourceId: { kind: "youtube#channel", channelId } },
+                    }
+                    : undefined;
+                if (action === "delete") {
+                    await request("/youtube/v3/subscriptions", context, undefined, { id: subscriptionId ?? "" }, method);
+                    return {};
+                }
+                return object(await request("/youtube/v3/subscriptions", context, insertBody, {
+                    part: "snippet,contentDetails",
+                    ...(subscriptionId
+                        ? { id: subscriptionId }
+                        : channelId
+                            ? { channelId }
+                            : action === "list"
+                                ? { mine: "true" }
+                                : {}),
+                    ...(pageToken ? { pageToken } : {}),
+                }, method));
+            },
+            async search({ q, type, channelId, order, publishedAfter, publishedBefore, pageToken, maxResults, context, }) {
+                nativeAuthorize(context);
+                return object(await request("/youtube/v3/search", context, undefined, {
+                    part: "snippet",
+                    q,
+                    ...(type ? { type } : {}),
+                    ...(channelId ? { channelId } : {}),
+                    ...(order ? { order } : {}),
+                    ...(publishedAfter ? { publishedAfter } : {}),
+                    ...(publishedBefore ? { publishedBefore } : {}),
+                    ...(pageToken ? { pageToken } : {}),
+                    ...(maxResults ? { maxResults: String(maxResults) } : {}),
+                }));
+            },
+            async commentsModeration({ action, commentId, moderationStatus, banAuthor, body, context }) {
+                nativeAuthorize(context);
+                if (!commentId)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "comments.moderate",
+                        message: "commentId is required.",
+                    });
+                if (action === "setModerationStatus") {
+                    await request("/youtube/v3/comments/setModerationStatus", context, undefined, {
+                        id: commentId,
+                        moderationStatus: moderationStatus ??
+                            (() => {
+                                throw new SocialError({
+                                    code: "invalid_input",
+                                    operation: "comments.moderate",
+                                    message: "moderationStatus is required.",
+                                });
+                            })(),
+                        ...(banAuthor ? { banAuthor: "true" } : {}),
+                    }, "POST");
+                    return;
+                }
+                if (action === "delete") {
+                    await request("/youtube/v3/comments", context, undefined, { id: commentId }, "DELETE");
+                    return;
+                }
+                if (!body || (body["id"] ?? commentId) !== commentId)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "comments.update",
+                        message: "Provide a comment body whose id, if present, matches commentId.",
+                    });
+                return object(await request("/youtube/v3/comments", context, { ...body, id: commentId }, { part: "snippet" }, "PUT"));
+            },
+            async heldComments({ pageToken, maxResults, context }) {
+                nativeAuthorize(context);
+                return object(await request("/youtube/v3/commentThreads", context, undefined, {
+                    part: "snippet",
+                    moderationStatus: "heldForReview",
+                    allThreadsRelatedToChannelId: options.auth.channelId,
+                    ...(pageToken ? { pageToken } : {}),
+                    ...(maxResults ? { maxResults: String(maxResults) } : {}),
+                }));
+            },
             async analytics({ query, context }) {
+                // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- validated boundary or fixture contract.
                 return object(await analyticsRequest("/v2/reports", context, undefined, query));
             },
-            async liveBroadcasts({ action, body, id, context }) {
+            async liveBroadcasts({ action, body, id, broadcastStatus, context }) {
                 if (action === "list")
+                    // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- validated boundary or fixture contract.
                     return object(await request("/youtube/v3/liveBroadcasts", context, undefined, {
                         part: "snippet,status",
-                        ...(id ? { id } : {}),
+                        // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
+                        ...(id ? { id } : { mine: "true" }),
                     }));
-                if (action === "transition")
-                    return object(await request("/youtube/v3/liveBroadcasts/transition", context, body, { part: "snippet,status", id: id ?? "" }, "POST"));
+                if (action === "transition") {
+                    if (!id || !broadcastStatus)
+                        throw new SocialError({
+                            code: "invalid_input",
+                            operation: "live.broadcasts",
+                            message: "id and broadcastStatus are required.",
+                        });
+                    // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- validated boundary or fixture contract.
+                    return object(await request("/youtube/v3/liveBroadcasts/transition", context, undefined, { part: "snippet,status", id, broadcastStatus }, "POST"));
+                }
+                // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- validated boundary or fixture contract.
                 return object(await request("/youtube/v3/liveBroadcasts", context, body, { part: "snippet,status" }, "POST"));
             },
         },