@zapier/youtube-connector 0.0.0 → 0.0.1

package/scripts/createPlaylist.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { PlaylistSchema, throwForYouTube } from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    snippet: z
+      .object({
+        title: z.string().describe("Playlist title (required)."),
+        description: z.string().describe("Playlist description.").optional(),
+        defaultLanguage: z
+          .string()
+          .describe(
+            "BCP-47 language code of the title/description text, e.g. en.",
+          )
+          .optional(),
+      })
+      .strict(),
+    status: z
+      .object({
+        privacyStatus: z
+          .enum(["public", "unlisted", "private"])
+          .describe("Playlist visibility. Defaults to private if omitted.")
+          .optional(),
+      })
+      .strict()
+      .optional(),
+    part: z
+      .string()
+      .describe("Resource parts being written. Leave as the default.")
+      .default("snippet,status"),
+  })
+  .strict();
+const outputSchema = PlaylistSchema;
+
+const definition = defineTool({
+  name: "createPlaylist",
+  title: "Create Playlist",
+  description:
+    "Create a new playlist on the authenticated user's channel. Returns the new playlist id for addVideoToPlaylist.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "youtube",
+  run: async (input, ctx) => {
+    const url = new URL(`https://www.googleapis.com/youtube/v3/playlists`);
+    if (input.part !== undefined) {
+      url.searchParams.set("part", String(input.part));
+    }
+    const body: Record<string, unknown> = {};
+    if (input.snippet !== undefined) body["snippet"] = input.snippet;
+    if (input.status !== undefined) body["status"] = input.status;
+    const res = await ctx.fetch(url.toString(), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    await throwForYouTube(res, "createPlaylist");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/deletePlaylist.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { SuccessResultSchema, throwForYouTube } from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    id: z
+      .string()
+      .describe("The id of the playlist to delete (from listPlaylists)."),
+  })
+  .strict();
+const outputSchema = SuccessResultSchema;
+
+const definition = defineTool({
+  name: "deletePlaylist",
+  title: "Delete Playlist",
+  description:
+    "Permanently delete a playlist owned by the authenticated user. Irreversible.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "youtube",
+  run: async (input, ctx) => {
+    const url = new URL(`https://www.googleapis.com/youtube/v3/playlists`);
+    if (input.id !== undefined) {
+      url.searchParams.set("id", String(input.id));
+    }
+    const res = await ctx.fetch(url.toString(), {
+      method: "DELETE",
+    });
+    await throwForYouTube(res, "deletePlaylist");
+    return { success: true as const };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/deleteVideo.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { SuccessResultSchema, throwForYouTube } from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({ id: z.string().describe("The id of the video to delete.") })
+  .strict();
+const outputSchema = SuccessResultSchema;
+
+const definition = defineTool({
+  name: "deleteVideo",
+  title: "Delete Video",
+  description:
+    "Permanently delete a video from the authenticated user's channel. Irreversible. The caller must own the video.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "youtube",
+  run: async (input, ctx) => {
+    const url = new URL(`https://www.googleapis.com/youtube/v3/videos`);
+    if (input.id !== undefined) {
+      url.searchParams.set("id", String(input.id));
+    }
+    const res = await ctx.fetch(url.toString(), {
+      method: "DELETE",
+    });
+    await throwForYouTube(res, "deleteVideo");
+    return { success: true as const };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/downloadCaption.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// captions.download returns a raw caption FILE body (srt/vtt/sbv/scc/ttml text),
+// not a JSON resource — so the response is read as text and wrapped here rather
+// than parsed as JSON.
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { throwForYouTube } from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    id: z
+      .string()
+      .describe("The caption track id to download (from listCaptions)."),
+    tfmt: z
+      .enum(["srt", "vtt", "sbv", "scc", "ttml"])
+      .describe("Output caption format. Defaults to srt.")
+      .default("srt"),
+    tlang: z
+      .string()
+      .describe(
+        "Optional BCP-47 language code (e.g. es) to request a machine translation of the track.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = z.object({
+  caption_text: z
+    .string()
+    .describe("The caption track text in the requested format."),
+  format: z.string().describe("The format the text was returned in."),
+});
+
+const definition = defineTool({
+  name: "downloadCaption",
+  title: "Download Caption",
+  description:
+    "Download a caption track's text in a chosen format (srt, vtt, sbv, scc, or ttml). Resolve the track id via listCaptions. Requires permission to edit the video (the owner or an editor) and the youtube.force-ssl scope.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "youtube",
+  run: async (input, ctx) => {
+    const url = new URL(
+      `https://www.googleapis.com/youtube/v3/captions/${encodeURIComponent(input.id)}`,
+    );
+    url.searchParams.set("tfmt", input.tfmt);
+    if (input.tlang !== undefined) url.searchParams.set("tlang", input.tlang);
+
+    const res = await ctx.fetch(url.toString(), { method: "GET" });
+    await throwForYouTube(res, "downloadCaption");
+    const caption_text = await res.text();
+    return { caption_text, format: input.tfmt };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/getChannel.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { ChannelSchema, throwForYouTube } from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    part: z
+      .string()
+      .describe("Resource parts to return. Leave as the default.")
+      .default("snippet,contentDetails,statistics,brandingSettings"),
+    mine: z
+      .boolean()
+      .describe(
+        "Return the authenticated user's own channel(s). Use this to discover the caller's channel id and uploads playlist.",
+      )
+      .optional(),
+    id: z
+      .string()
+      .describe("Look up channel(s) by id (UC..., comma-separated, max 50).")
+      .optional(),
+    forHandle: z
+      .string()
+      .describe(
+        "Look up a channel by its @handle, e.g. @MrBeast (with or without the leading @). Mutually exclusive with mine and id.",
+      )
+      .optional(),
+  })
+  .strict()
+  // Exactly one selector — the API silently ignores conflicting selectors, so make
+  // the at-most-one rule explicit. (x-mutually-exclusive: [[mine, id, forHandle]])
+  .refine(
+    (v) =>
+      [v.mine, v.id, v.forHandle].filter((x) => x !== undefined).length <= 1,
+    {
+      message:
+        "Provide only one of mine, id, or forHandle (they are mutually exclusive).",
+    },
+  );
+const outputSchema = z.object({
+  items: z.array(ChannelSchema).describe("The requested channels."),
+});
+
+const definition = defineTool({
+  name: "getChannel",
+  title: "Get Channel",
+  description:
+    "Get a channel's profile, statistics, and uploads-playlist id. Pass mine=true for the authenticated user's channel, or a channel id / handle to look up another. The resolver for channelId and for a channel's uploads playlist.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "youtube",
+  run: async (input, ctx) => {
+    const url = new URL(`https://www.googleapis.com/youtube/v3/channels`);
+    if (input.part !== undefined) {
+      url.searchParams.set("part", String(input.part));
+    }
+    if (input.mine !== undefined) {
+      url.searchParams.set("mine", String(input.mine));
+    }
+    if (input.id !== undefined) {
+      url.searchParams.set("id", String(input.id));
+    }
+    if (input.forHandle !== undefined) {
+      url.searchParams.set("forHandle", String(input.forHandle));
+    }
+    const res = await ctx.fetch(url.toString(), {
+      method: "GET",
+    });
+    await throwForYouTube(res, "getChannel");
+    const payload = (await res.json()) as { items?: unknown };
+    return { items: payload.items ?? [] };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/getVideo.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { NextPageToken, throwForYouTube, VideoSchema } from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    part: z
+      .string()
+      .describe("Resource parts to return. Leave as the default.")
+      .default("snippet,contentDetails,statistics,status"),
+    id: z
+      .string()
+      .describe(
+        "One video id or a comma-separated list (max 50), e.g. dQw4w9WgXcQ. The 11-char id from a watch URL or searchVideos.",
+      ),
+    maxResults: z
+      .number()
+      .int()
+      .gte(1)
+      .lte(50)
+      .describe(
+        "Max results per page when listing many ids. Defaults to 10 when omitted; pass a value when you need a specific number of results.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = z.object({
+  items: z.array(VideoSchema).describe("The requested videos."),
+  next_page_token: NextPageToken,
+});
+
+const definition = defineTool({
+  name: "getVideo",
+  title: "Get Video",
+  description:
+    "Get full details of one or more videos by id — snippet (title, description, tags, category), statistics (view/like/comment counts), contentDetails (ISO-8601 duration), and status (privacy, upload state). Counts come back as strings; like/comment counts are absent when the owner hides them. Resolve ids via searchVideos or a watch URL.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "youtube",
+  run: async (input, ctx) => {
+    const url = new URL(`https://www.googleapis.com/youtube/v3/videos`);
+    url.searchParams.set("part", input.part);
+    url.searchParams.set("id", input.id);
+    url.searchParams.set("maxResults", String(input.maxResults ?? 10));
+
+    const res = await ctx.fetch(url.toString(), { method: "GET" });
+    await throwForYouTube(res, "getVideo");
+    const payload = (await res.json()) as {
+      items?: unknown;
+      nextPageToken?: string;
+    };
+    return {
+      items: payload.items ?? [],
+      next_page_token: payload.nextPageToken,
+    };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/listCaptions.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { CaptionSchema, throwForYouTube } from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    part: z
+      .string()
+      .describe("Resource parts to return. Leave as the default.")
+      .default("snippet"),
+    videoId: z.string().describe("The video id whose caption tracks to list."),
+  })
+  .strict();
+const outputSchema = z.object({
+  items: z.array(CaptionSchema).describe("The caption tracks for the video."),
+});
+
+const definition = defineTool({
+  name: "listCaptions",
+  title: "List Captions",
+  description:
+    "List the caption tracks available for a video (id, language, name, type, status). Use the track id with downloadCaption to fetch the text. Requires the youtube.force-ssl scope.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "youtube",
+  run: async (input, ctx) => {
+    const url = new URL(`https://www.googleapis.com/youtube/v3/captions`);
+    if (input.part !== undefined) {
+      url.searchParams.set("part", String(input.part));
+    }
+    if (input.videoId !== undefined) {
+      url.searchParams.set("videoId", String(input.videoId));
+    }
+    const res = await ctx.fetch(url.toString(), {
+      method: "GET",
+    });
+    await throwForYouTube(res, "listCaptions");
+    const payload = (await res.json()) as { items?: unknown };
+    return { items: payload.items ?? [] };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/listComments.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  CommentThreadSchema,
+  NextPageToken,
+  throwForYouTube,
+} from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    part: z
+      .string()
+      .describe("Resource parts to return. Leave as the default.")
+      .default("snippet,replies"),
+    videoId: z.string().describe("The video id whose comment threads to list."),
+    order: z
+      .enum(["time", "relevance"])
+      .describe("time = newest first; relevance = YouTube's relevance ranking.")
+      .default("time"),
+    searchTerms: z
+      .string()
+      .describe("Only return comment threads matching this text.")
+      .optional(),
+    maxResults: z
+      .number()
+      .int()
+      .gte(1)
+      .lte(100)
+      .describe(
+        "Max threads per page (1-100). Defaults to 20 when omitted; pass a value when you need a specific number of results.",
+      )
+      .optional(),
+    pageToken: z
+      .string()
+      .describe(
+        "Page cursor from a previous response's next_page_token. Omit for the first page.",
+      )
+      .optional(),
+  })
+  .strict();
+const outputSchema = z.object({
+  items: z.array(CommentThreadSchema).describe("The comment threads."),
+  next_page_token: NextPageToken,
+});
+
+const definition = defineTool({
+  name: "listComments",
+  title: "List Comments",
+  description:
+    "List top-level comment threads on a video (each with its first replies). Use to read what viewers commented. Resolve videoId via searchVideos/getVideo.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "youtube",
+  run: async (input, ctx) => {
+    const url = new URL(`https://www.googleapis.com/youtube/v3/commentThreads`);
+    if (input.part !== undefined) {
+      url.searchParams.set("part", String(input.part));
+    }
+    if (input.videoId !== undefined) {
+      url.searchParams.set("videoId", String(input.videoId));
+    }
+    if (input.order !== undefined) {
+      url.searchParams.set("order", String(input.order));
+    }
+    if (input.searchTerms !== undefined) {
+      url.searchParams.set("searchTerms", String(input.searchTerms));
+    }
+    url.searchParams.set("maxResults", String(input.maxResults ?? 20));
+    if (input.pageToken !== undefined) {
+      url.searchParams.set("pageToken", String(input.pageToken));
+    }
+    const res = await ctx.fetch(url.toString(), {
+      method: "GET",
+    });
+    await throwForYouTube(res, "listComments");
+    const payload = (await res.json()) as {
+      items?: unknown;
+      nextPageToken?: string;
+    };
+    return {
+      items: payload.items ?? [],
+      next_page_token: payload.nextPageToken,
+    };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/listPlaylistItems.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  NextPageToken,
+  PlaylistItemSchema,
+  throwForYouTube,
+} from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    part: z
+      .string()
+      .describe("Resource parts to return. Leave as the default.")
+      .default("snippet,contentDetails,status"),
+    playlistId: z
+      .string()
+      .describe(
+        "The playlist id whose items to list (from listPlaylists). For a channel's uploads, use the uploads playlist id from getChannel.",
+      ),
+    maxResults: z
+      .number()
+      .int()
+      .gte(1)
+      .lte(50)
+      .describe(
+        "Max items per page (1-50). Defaults to 20 when omitted; pass a value when you need a specific number of results.",
+      )
+      .optional(),
+    pageToken: z
+      .string()
+      .describe(
+        "Page cursor from a previous response's next_page_token. Omit for the first page.",
+      )
+      .optional(),
+  })
+  .strict();
+const outputSchema = z.object({
+  items: z
+    .array(PlaylistItemSchema)
+    .describe("The videos in the playlist, in order."),
+  next_page_token: NextPageToken,
+});
+
+const definition = defineTool({
+  name: "listPlaylistItems",
+  title: "List Playlist Items",
+  description:
+    "List the videos in a playlist, in playlist order. Each item carries its own playlistItem id (needed by removeVideoFromPlaylist) plus the video id and snippet.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "youtube",
+  run: async (input, ctx) => {
+    const url = new URL(`https://www.googleapis.com/youtube/v3/playlistItems`);
+    if (input.part !== undefined) {
+      url.searchParams.set("part", String(input.part));
+    }
+    if (input.playlistId !== undefined) {
+      url.searchParams.set("playlistId", String(input.playlistId));
+    }
+    url.searchParams.set("maxResults", String(input.maxResults ?? 20));
+    if (input.pageToken !== undefined) {
+      url.searchParams.set("pageToken", String(input.pageToken));
+    }
+    const res = await ctx.fetch(url.toString(), {
+      method: "GET",
+    });
+    await throwForYouTube(res, "listPlaylistItems");
+    const payload = (await res.json()) as {
+      items?: unknown;
+      nextPageToken?: string;
+    };
+    return {
+      items: payload.items ?? [],
+      next_page_token: payload.nextPageToken,
+    };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });