@opencoredev/social-sdk 0.3.0 → 0.4.0

package/dist/platforms/youtube.js

@@ -1,24 +1,28 @@
-/* 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 { managedHttp, optionsObject, publicFields } from "../cloud/common.js";
+import { definedFields } from "../core/fields.js";
+import { verifyYouTubeWebhook } from "../server/webhooks.js";
+import { directWebhooks, webhookCapability } from "./webhook-adapter.js";
 import { createHttp, HttpError } from "../transport/http.js";
-import { array, object, optionalString, string } from "../transport/validation.js";
+import { array, isBoolean, isFiniteNumber, isJsonObject, isString, object, optionalArray, optionalObject, optionalString, string, } from "../transport/validation.js";
 import { beginYouTubeUpload, queryYouTubeUpload, sendYouTubeUpload, } from "./youtube-upload.js";
+/** Drop empty strings so optional query parameters are omitted rather than sent blank. */
+function nonEmpty(value) {
+    return value || undefined;
+}
 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 } : {}),
+        ...definedFields({ 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 } : {}),
+        ...definedFields({ fetch: options.fetch }),
     });
     const binaryRequest = createHttp({
-        ...(options.fetch ? { fetch: options.fetch } : {}),
+        ...definedFields({ fetch: options.fetch }),
         timeoutMs: 30_000,
     });
     const now = () => (options.clock?.() ?? new Date()).toISOString();
@@ -56,9 +60,17 @@ export function youtube(options) {
             });
         return video;
     };
-    const outcome = (
-    // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- validated boundary or fixture contract.
-    video, target) => {
+    /** Returns the publishAt time only while the video is private and still waiting to publish. */
+    const scheduledAt = (status) => {
+        const publishAt = optionalString(status["publishAt"]);
+        if (status["privacyStatus"] !== "private" || publishAt === undefined)
+            return undefined;
+        const time = Date.parse(publishAt);
+        return Number.isFinite(time) && time > (options.clock?.() ?? new Date()).getTime()
+            ? publishAt
+            : undefined;
+    };
+    const outcome = (video, target) => {
         const id = string(video["id"]);
         const status = object(video["status"]);
         const uploaded = optionalString(status["uploadStatus"]) ?? "unknown";
@@ -75,6 +87,28 @@ export function youtube(options) {
                 deliveryId: id,
             },
         };
+        if (uploaded === "failed" || uploaded === "rejected")
+            return {
+                ...base,
+                state: "failed",
+                code: "media_error",
+                message: "YouTube rejected or failed to process the video. Inspect channel eligibility and upload requirements.",
+                retryDisposition: { kind: "never" },
+            };
+        // A private video with a future publishAt is waiting for YouTube to publish it.
+        if (scheduledAt(status) !== undefined)
+            return {
+                ...base,
+                state: "scheduled",
+                job: {
+                    kind: "scheduled-job",
+                    version: 1,
+                    backend: target.account.backend,
+                    platform: "youtube",
+                    accountId: target.account.accountId,
+                    jobId: id,
+                },
+            };
         if (uploaded === "processed")
             return {
                 ...base,
@@ -91,14 +125,6 @@ export function youtube(options) {
             };
         if (uploaded === "uploaded")
             return { ...base, state: "processing" };
-        if (uploaded === "failed" || uploaded === "rejected")
-            return {
-                ...base,
-                state: "failed",
-                code: "media_error",
-                message: "YouTube rejected or failed to process the video. Inspect channel eligibility and upload requirements.",
-                retryDisposition: { kind: "never" },
-            };
         return {
             ...base,
             state: "unknown",
@@ -154,10 +180,10 @@ export function youtube(options) {
                 body,
                 headers: {
                     Authorization: `Bearer ${options.auth.accessToken}`,
-                    ...(contentType ? { "Content-Type": contentType } : {}),
+                    ...definedFields({ "Content-Type": nonEmpty(contentType) }),
                 },
                 timeoutMs: remainingBudget(context),
-                ...(context.signal ? { signal: context.signal } : {}),
+                ...definedFields({ signal: context.signal }),
             });
             return object(result);
         }
@@ -191,6 +217,7 @@ export function youtube(options) {
             apiRevision: "YouTube Data API v3",
             runtime: ["node22", "node24", "bun"],
             capabilities: [
+                webhookCapability("youtube", "Verifies the PubSubHubbub X-Hub-Signature for subscriptions created with hub.secret and decodes the Atom feed. Answer the GET verification with answerYouTubeWebhookChallenge."),
                 ...[
                     "accounts.read",
                     "posts.read",
@@ -220,12 +247,25 @@ export function youtube(options) {
                     requiredScopes: ["https://www.googleapis.com/auth/youtube.upload"],
                     notes: "Scheduled videos are uploaded private with a future ISO publishAt timestamp.",
                 },
+                {
+                    operation: "posts.cancelScheduled",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube"],
+                    notes: "Clears status.publishAt with videos.update and keeps the video private. The video is not deleted. Costs 51 quota units (videos.list + videos.update).",
+                },
                 {
                     operation: "posts.removeFromPlatform",
                     platform: "youtube",
                     availability: "available",
                     requiredScopes: ["https://www.googleapis.com/auth/youtube"],
                 },
+                {
+                    operation: "notifications.read",
+                    platform: "youtube",
+                    availability: "unsupported-by-platform",
+                    notes: "The YouTube Data API has no notifications resource. activities.list reports actions a channel took, not notifications it received.",
+                },
                 {
                     operation: "playlists.read",
                     platform: "youtube",
@@ -256,6 +296,13 @@ export function youtube(options) {
                     availability: "available",
                     requiredScopes: ["https://www.googleapis.com/auth/youtube"],
                 },
+                {
+                    operation: "profile.update",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube"],
+                    notes: "Native access: updateProfile. Writes brandingSettings.channel or localizations through channels.update. Each call reads the channel (1 quota unit) and then writes it (50 units).",
+                },
                 {
                     operation: "videos.delete",
                     platform: "youtube",
@@ -312,6 +359,13 @@ export function youtube(options) {
                     availability: "available",
                     requiredScopes: ["https://www.googleapis.com/auth/youtube.force-ssl"],
                 },
+                {
+                    operation: "comments.delete",
+                    platform: "youtube",
+                    availability: "available",
+                    requiredScopes: ["https://www.googleapis.com/auth/youtube.force-ssl"],
+                    notes: "comments.delete costs 50 quota units. Delete a thread through its top-level comment ID. Google does not document which comments a channel may delete; insufficient permissions return 403 forbidden.",
+                },
                 {
                     operation: "analytics.youtube.read",
                     platform: "youtube",
@@ -334,6 +388,7 @@ export function youtube(options) {
                 },
             ],
         },
+        webhooks: directWebhooks("youtube", (input) => verifyYouTubeWebhook({ ...input, secret: options.webhookSecret ?? "" }), now),
         accounts: {
             async list(_input, context) {
                 return { items: [await accountInfo(context)] };
@@ -371,8 +426,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 } : {}),
+                    ...definedFields({ pageToken: nonEmpty(input.cursor) }),
                 }));
                 return {
                     items: array(page["items"]).map((value) => {
@@ -397,17 +451,7 @@ 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"] }
-                        : {}),
+                    ...definedFields({ nextCursor: optionalString(page["nextPageToken"]) }),
                 };
             },
             prepareTarget(target) {
@@ -428,18 +472,13 @@ export function youtube(options) {
                     if (item.source.kind !== "blob" && !item.byteSize)
                         fail("youtube.size", "Streaming upload requires its exact byte size.");
                 }
-                const config = target.options === undefined ? {} : object(target.options);
-                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 ||
-                    /[<>]/u.test(config["title"]))
+                const config = optionsObject(target);
+                const title = config["title"];
+                if (!isString(title) || !title || [...title].length > 100 || /[<>]/u.test(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")
+                if (!isBoolean(config["madeForKids"]))
                     fail("youtube.audience", "Explicit made-for-kids declaration is required.");
                 if (target.content.text !== undefined &&
                     new TextEncoder().encode(target.content.text).byteLength > 5000)
@@ -461,32 +500,32 @@ export function youtube(options) {
                         operation: "posts.publish",
                         message: "Video required.",
                     });
-                const config = object(target.options);
+                const config = optionsObject(target);
                 const uploadOptions = {
                     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 } : {}),
+                    ...definedFields({ fetch: options.fetch, signal: context.signal }),
                 };
                 const size = media.byteSize ?? (media.source.kind === "blob" ? media.source.blob.size : 0);
+                const mimeType = string(media.mimeType);
+                const title = string(config["title"]);
+                const visibility = string(config["visibility"]);
+                const selfDeclaredMadeForKids = config["madeForKids"] === true;
+                // A schedule forces private visibility until YouTube publishes at `publishAt`.
+                const status = target.schedule === undefined
+                    ? { privacyStatus: visibility, selfDeclaredMadeForKids }
+                    : {
+                        privacyStatus: "private",
+                        selfDeclaredMadeForKids,
+                        publishAt: new Date(target.schedule.at).toISOString(),
+                    };
                 const session = await beginYouTubeUpload({
                     channelId: options.auth.channelId,
                     size,
-                    mimeType: string(media.mimeType),
+                    mimeType,
                     metadata: {
-                        snippet: { title: string(config["title"]), description: target.content.text ?? "" },
-                        status: {
-                            privacyStatus: string(config["visibility"]),
-                            selfDeclaredMadeForKids: config["madeForKids"] === true,
-                            ...(target.schedule
-                                ? {
-                                    publishAt: new Date(target.schedule.at).toISOString(),
-                                    privacyStatus: "private",
-                                }
-                                : {}),
-                        },
+                        snippet: { title, description: target.content.text ?? "" },
+                        status,
                     },
                 }, uploadOptions);
                 if (options.saveUploadSession)
@@ -531,6 +570,81 @@ export function youtube(options) {
                 const video = await get({ ...account, kind: "platform-post", postId: ref.deliveryId }, context);
                 return outcome(video, { account, targetIndex: 0 });
             },
+            async cancelScheduled(ref, context) {
+                authorize(ref, context);
+                if (!ref.jobId)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "posts.cancelScheduled",
+                        message: "jobId must be the scheduled video's ID.",
+                    });
+                const video = await get({
+                    kind: "platform-post",
+                    version: 1,
+                    backend: ref.backend,
+                    platform: "youtube",
+                    accountId: ref.accountId,
+                    postId: ref.jobId,
+                }, context);
+                const status = object(video["status"]);
+                if (scheduledAt(status) === undefined)
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "posts.cancelScheduled",
+                        message: "Only a private video with a future publishAt can be cancelled. Reconcile a due or published video.",
+                    });
+                // videos.update replaces the whole status part: an omitted field is reset. Resend every
+                // writable field read above, set privacyStatus to private, and omit publishAt to clear it.
+                const flag = (key) => {
+                    const value = status[key];
+                    if (value === undefined || value === true || value === false)
+                        return value;
+                    throw new SocialError({
+                        code: "upstream_failure",
+                        operation: "posts.cancelScheduled",
+                        message: `YouTube returned an invalid status.${key} value.`,
+                    });
+                };
+                const selfDeclaredMadeForKids = flag("selfDeclaredMadeForKids");
+                if (selfDeclaredMadeForKids === undefined)
+                    throw new SocialError({
+                        code: "upstream_failure",
+                        operation: "posts.cancelScheduled",
+                        message: "YouTube did not return the made-for-kids declaration, so the update could not preserve it. Nothing was changed.",
+                    });
+                const license = optionalString(status["license"]);
+                const embeddable = flag("embeddable");
+                const publicStatsViewable = flag("publicStatsViewable");
+                const containsSyntheticMedia = flag("containsSyntheticMedia");
+                const next = (() => {
+                    const result = {};
+                    result["privacyStatus"] = "private";
+                    result["selfDeclaredMadeForKids"] = selfDeclaredMadeForKids;
+                    if (license !== undefined)
+                        result["license"] = license;
+                    if (embeddable !== undefined)
+                        result["embeddable"] = embeddable;
+                    if (publicStatsViewable !== undefined)
+                        result["publicStatsViewable"] = publicStatsViewable;
+                    if (containsSyntheticMedia !== undefined)
+                        result["containsSyntheticMedia"] = containsSyntheticMedia;
+                    return result;
+                })();
+                const result = object(await request("/youtube/v3/videos", context, { id: ref.jobId, status: next }, { part: "status" }, "PUT"));
+                const written = result["status"] === undefined ? undefined : object(result["status"]);
+                if (result["id"] !== ref.jobId ||
+                    written?.["privacyStatus"] !== "private" ||
+                    (written?.["publishAt"] !== undefined && written?.["publishAt"] !== null))
+                    throw new SocialError({
+                        code: "ambiguous_outcome",
+                        operation: "posts.cancelScheduled",
+                        backend: context.backendInstance,
+                        correlationId: context.correlationId,
+                        message: "YouTube did not confirm that the schedule was cleared. Read the video before retrying.",
+                        retryDisposition: { kind: "reconcile-first" },
+                    });
+                return { state: "cancelled", backendRecord: "retained" };
+            },
             async removeFromPlatform(ref, context) {
                 authorize(ref, context);
                 if (!ref.postId)
@@ -563,14 +677,15 @@ export function youtube(options) {
                     q: input.query,
                     type: "video",
                     maxResults: String(limit),
-                    ...(input.cursor ? { pageToken: input.cursor } : {}),
-                    ...(input.startTime ? { publishedAfter: input.startTime } : {}),
-                    ...(input.endTime ? { publishedBefore: input.endTime } : {}),
+                    ...definedFields({
+                        pageToken: nonEmpty(input.cursor),
+                        publishedAfter: nonEmpty(input.startTime),
+                        publishedBefore: nonEmpty(input.endTime),
+                    }),
                 }));
-                const nextCursor = optionalString(page["nextPageToken"]);
                 return {
-                    items: array(page["items"]).map((value) => object(value)),
-                    ...(nextCursor ? { nextCursor } : {}),
+                    items: array(page["items"]).map(object),
+                    ...definedFields({ nextCursor: nonEmpty(optionalString(page["nextPageToken"])) }),
                 };
             },
         },
@@ -583,8 +698,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))
+                    if (!isString(raw) || !/^\d+$/.test(raw))
                         continue;
                     const value = Number(raw);
                     if (!Number.isSafeInteger(value))
@@ -623,8 +737,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))
+                    return isString(raw) && /^\d+$/.test(raw) && Number.isSafeInteger(Number(raw))
                         ? [
                             {
                                 name,
@@ -658,10 +771,11 @@ export function youtube(options) {
                     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(",") }
-                        : {}),
+                    ...definedFields({
+                        dimensions: query.dimensions && query.dimensions.length > 0
+                            ? query.dimensions.join(",")
+                            : undefined,
+                    }),
                 }));
                 const headers = array(result["columnHeaders"]).map((value) => {
                     const header = object(value);
@@ -672,14 +786,14 @@ export function youtube(options) {
                 });
                 const rows = [];
                 // Analytics omits `rows` entirely when the requested period has no data.
-                for (const value of Array.isArray(result["rows"]) ? result["rows"] : []) {
+                for (const value of optionalArray(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"
+                        // JSON numbers are always finite, so isFiniteNumber accepts every numeric cell.
+                        return isString(raw) || isFiniteNumber(raw) || isBoolean(raw)
                             ? [[header.name, raw]]
                             : [];
                     }));
@@ -688,10 +802,9 @@ export function youtube(options) {
                         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"
+                        const parsed = isFiniteNumber(raw)
                             ? raw
-                            : typeof raw === "string" && raw.trim() !== ""
+                            : isString(raw) && raw.trim() !== ""
                                 ? Number(raw)
                                 : undefined;
                         if (parsed !== undefined && Number.isFinite(parsed))
@@ -717,8 +830,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 }),
+                    ...definedFields({ pageToken: input.cursor }),
                 }));
                 const cursor = optionalString(result["nextPageToken"]);
                 return {
@@ -735,8 +847,7 @@ export function youtube(options) {
                             ]),
                         };
                     }),
-                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
-                    ...(cursor ? { nextCursor: cursor } : {}),
+                    ...definedFields({ nextCursor: nonEmpty(cursor) }),
                 };
             },
             async reply(ref, content, context) {
@@ -768,10 +879,7 @@ 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 } : {}),
+                    ...definedFields({ fetch: options.fetch, signal: context.signal }),
                 };
                 const confirmed = await queryYouTubeUpload(session, uploadOptions);
                 if (confirmed.state === "complete")
@@ -787,10 +895,7 @@ 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 } : {}),
+                    ...definedFields({ fetch: options.fetch, signal: context.signal }),
                 });
             },
             async setThumbnail({ videoId, thumbnail, context }) {
@@ -811,7 +916,7 @@ export function youtube(options) {
                     const response = await (options.fetch ?? globalThis.fetch)(url, {
                         headers: { Authorization: `Bearer ${options.auth.accessToken}` },
                         redirect: "error",
-                        ...(context.signal ? { signal: context.signal } : {}),
+                        ...definedFields({ signal: context.signal }),
                     });
                     if (!response.ok)
                         throw new SocialError({
@@ -840,7 +945,7 @@ export function youtube(options) {
                     const metadata = action === "update"
                         ? { ...body, id: captionId ?? body["id"] ?? null }
                         : { ...body, snippet: { ...snippet, videoId: videoId ?? null } };
-                    if (action === "update" && typeof metadata["id"] !== "string")
+                    if (action === "update" && !isString(metadata["id"]))
                         throw new SocialError({
                             code: "invalid_input",
                             operation: "captions.update",
@@ -892,22 +997,20 @@ export function youtube(options) {
                         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) } : {}),
+                    ...definedFields({
+                        id: nonEmpty(playlistId),
+                        channelId: nonEmpty(channelId),
+                        // Listing with no playlist or channel filter defaults to the caller's playlists.
+                        mine: (action === "list" && !playlistId && !channelId) || mine ? "true" : undefined,
+                        pageToken: nonEmpty(pageToken),
+                        maxResults: maxResults ? String(maxResults) : undefined,
+                    }),
                 }, method));
             },
             async playlistItems({ action, playlistId, playlistItemId, body, pageToken, context }) {
@@ -931,9 +1034,11 @@ export function youtube(options) {
                 }
                 return object(await request("/youtube/v3/playlistItems", context, body, {
                     part: "snippet,contentDetails",
-                    ...(playlistId ? { playlistId } : {}),
-                    ...(playlistItemId ? { id: playlistItemId } : {}),
-                    ...(pageToken ? { pageToken } : {}),
+                    ...definedFields({
+                        playlistId: nonEmpty(playlistId),
+                        id: nonEmpty(playlistItemId),
+                        pageToken: nonEmpty(pageToken),
+                    }),
                 }, method));
             },
             async updateVideo({ videoId, body, context }) {
@@ -961,6 +1066,52 @@ export function youtube(options) {
                 };
                 return object(await request("/youtube/v3/videos", context, merged, { part: "snippet,status" }, "PUT"));
             },
+            async updateProfile({ part, value, context }) {
+                nativeAuthorize(context);
+                const operation = "profile.update";
+                const invalid = (message) => new SocialError({ code: "invalid_input", operation, message });
+                if (part !== "brandingSettings" && part !== "localizations")
+                    throw invalid("part must be brandingSettings or localizations.");
+                if (!isJsonObject(value) || Object.keys(value).length === 0)
+                    throw invalid("value must be a non-empty object.");
+                const channelPatch = value["channel"];
+                if (part === "brandingSettings" &&
+                    (Object.keys(value).some((key) => key !== "channel") || !isJsonObject(channelPatch)))
+                    throw invalid("brandingSettings updates accept only a channel object.");
+                if (part === "localizations" &&
+                    Object.entries(value).some(([key, entry]) => key.trim() === "" || (entry !== null && !isJsonObject(entry))))
+                    throw invalid("Each localization must be an object keyed by language, or null to remove it.");
+                // channels.update deletes omitted mutable properties, so merge into the current part.
+                const merge = (current, patch) => Object.fromEntries(Object.entries({ ...optionalObject(current), ...patch }).filter(([, entry]) => entry !== null));
+                const channel = array(object(await request("/youtube/v3/channels", context, undefined, {
+                    id: options.auth.channelId,
+                    part,
+                }))["items"])
+                    .map(object)
+                    .find((item) => item["id"] === options.auth.channelId);
+                if (!channel)
+                    throw new SocialError({
+                        code: "unauthorized",
+                        operation,
+                        message: "Configured channel is absent or inaccessible to this authorization.",
+                    });
+                const branding = optionalObject(channel["brandingSettings"]) ?? {};
+                // Resend only documented writable branding: the merged channel object and the current
+                // banner URL, which channels.update would otherwise delete. Deprecated watch, hints, and
+                // image fields are dropped; YouTube rejects some of them on write.
+                const bannerExternalUrl = optionalString(optionalObject(branding["image"])?.["bannerExternalUrl"]);
+                const brandingNext = (patch) => {
+                    const result = {};
+                    result["channel"] = merge(branding["channel"], patch);
+                    if (bannerExternalUrl !== undefined && bannerExternalUrl !== "")
+                        result["image"] = { bannerExternalUrl };
+                    return result;
+                };
+                const next = part === "brandingSettings" && isJsonObject(channelPatch)
+                    ? brandingNext(channelPatch)
+                    : merge(channel["localizations"], value);
+                return object(await request("/youtube/v3/channels", context, { id: options.auth.channelId, [part]: next }, { part }, "PUT"));
+            },
             async deleteVideo({ videoId, context }) {
                 nativeAuthorize(context);
                 if (!videoId)
@@ -991,9 +1142,7 @@ export function youtube(options) {
                         message: "subscriptionId is required.",
                     });
                 const insertBody = channelId
-                    ? {
-                        snippet: { resourceId: { kind: "youtube#channel", channelId } },
-                    }
+                    ? { snippet: { resourceId: { kind: "youtube#channel", channelId } } }
                     : undefined;
                 if (action === "delete") {
                     await request("/youtube/v3/subscriptions", context, undefined, { id: subscriptionId ?? "" }, method);
@@ -1001,14 +1150,13 @@ export function youtube(options) {
                 }
                 return object(await request("/youtube/v3/subscriptions", context, insertBody, {
                     part: "snippet,contentDetails",
-                    ...(subscriptionId
-                        ? { id: subscriptionId }
-                        : channelId
-                            ? { channelId }
-                            : action === "list"
-                                ? { mine: "true" }
-                                : {}),
-                    ...(pageToken ? { pageToken } : {}),
+                    // Filter by subscription, else by channel, else list the caller's own subscriptions.
+                    ...definedFields({
+                        id: nonEmpty(subscriptionId),
+                        channelId: subscriptionId ? undefined : nonEmpty(channelId),
+                        mine: subscriptionId || channelId || action !== "list" ? undefined : "true",
+                        pageToken: nonEmpty(pageToken),
+                    }),
                 }, method));
             },
             async search({ q, type, channelId, order, publishedAfter, publishedBefore, pageToken, maxResults, context, }) {
@@ -1016,13 +1164,15 @@ export function youtube(options) {
                 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) } : {}),
+                    ...definedFields({
+                        type: nonEmpty(type),
+                        channelId: nonEmpty(channelId),
+                        order: nonEmpty(order),
+                        publishedAfter: nonEmpty(publishedAfter),
+                        publishedBefore: nonEmpty(publishedBefore),
+                        pageToken: nonEmpty(pageToken),
+                        maxResults: maxResults ? String(maxResults) : undefined,
+                    }),
                 }));
             },
             async commentsModeration({ action, commentId, moderationStatus, banAuthor, body, context }) {
@@ -1044,7 +1194,7 @@ export function youtube(options) {
                                     message: "moderationStatus is required.",
                                 });
                             })(),
-                        ...(banAuthor ? { banAuthor: "true" } : {}),
+                        ...definedFields({ banAuthor: banAuthor ? "true" : undefined }),
                     }, "POST");
                     return;
                 }
@@ -1060,26 +1210,36 @@ export function youtube(options) {
                     });
                 return object(await request("/youtube/v3/comments", context, { ...body, id: commentId }, { part: "snippet" }, "PUT"));
             },
+            async deleteComment({ account, commentId, context }) {
+                // Source: https://developers.google.com/youtube/v3/docs/comments/delete (accessed 2026-09-24).
+                authorize(account, context);
+                if (!commentId.trim())
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "comments.delete",
+                        message: "commentId is required.",
+                    });
+                await request("/youtube/v3/comments", context, undefined, { id: commentId }, "DELETE");
+            },
             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) } : {}),
+                    ...definedFields({
+                        pageToken: nonEmpty(pageToken),
+                        maxResults: maxResults ? String(maxResults) : undefined,
+                    }),
                 }));
             },
             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, 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",
-                        // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
                         ...(id ? { id } : { mine: "true" }),
                     }));
                 if (action === "transition") {
@@ -1089,10 +1249,8 @@ export function youtube(options) {
                             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"));
             },
         },