@zapier/youtube-connector 0.0.0 → 0.0.1

package/scripts/listPlaylists.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  NextPageToken,
+  PlaylistSchema,
+  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"),
+    mine: z
+      .boolean()
+      .describe(
+        "List the authenticated user's own playlists. The default when no channelId or id is given.",
+      )
+      .optional(),
+    channelId: z
+      .string()
+      .describe(
+        "List playlists owned by this channel id (UC...). Mutually exclusive with mine and id.",
+      )
+      .optional(),
+    id: z
+      .string()
+      .describe(
+        "Fetch specific playlists by id (comma-separated, max 50). Mutually exclusive with mine and channelId.",
+      )
+      .optional(),
+    maxResults: z
+      .number()
+      .int()
+      .gte(1)
+      .lte(50)
+      .describe(
+        "Max playlists 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(PlaylistSchema).describe("The playlists."),
+  next_page_token: NextPageToken,
+});
+
+const definition = defineTool({
+  name: "listPlaylists",
+  title: "List Playlists",
+  description:
+    "List playlists owned by the authenticated user (default) or by a channel, or fetch specific playlists by id. The resolver for any playlistId input.",
+  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/playlists`);
+    if (input.part !== undefined) {
+      url.searchParams.set("part", String(input.part));
+    }
+    if (input.mine !== undefined) {
+      url.searchParams.set("mine", String(input.mine));
+    }
+    if (input.channelId !== undefined) {
+      url.searchParams.set("channelId", String(input.channelId));
+    }
+    if (input.id !== undefined) {
+      url.searchParams.set("id", String(input.id));
+    }
+    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, "listPlaylists");
+    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/listSubscriptions.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  NextPageToken,
+  SubscriptionSchema,
+  throwForYouTube,
+} from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    part: z
+      .string()
+      .describe("Resource parts to return. Leave as the default.")
+      .default("snippet,contentDetails"),
+    mine: z
+      .boolean()
+      .describe("List the authenticated user's subscriptions. The default.")
+      .default(true),
+    forChannelId: z
+      .string()
+      .describe(
+        "Restrict to a subscription to this specific channel id — returns one item if subscribed, none otherwise. Use to check subscription state.",
+      )
+      .optional(),
+    order: z
+      .enum(["alphabetical", "relevance", "unread"])
+      .describe("Sort order.")
+      .default("relevance"),
+    maxResults: z
+      .number()
+      .int()
+      .gte(1)
+      .lte(50)
+      .describe(
+        "Max subscriptions 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(SubscriptionSchema).describe("The subscriptions."),
+  next_page_token: NextPageToken,
+});
+
+const definition = defineTool({
+  name: "listSubscriptions",
+  title: "List Subscriptions",
+  description:
+    "List the channels the authenticated user is subscribed to (default), or check whether the user subscribes to a specific channel via forChannelId.",
+  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/subscriptions`);
+    if (input.part !== undefined) {
+      url.searchParams.set("part", String(input.part));
+    }
+    if (input.mine !== undefined) {
+      url.searchParams.set("mine", String(input.mine));
+    }
+    if (input.forChannelId !== undefined) {
+      url.searchParams.set("forChannelId", String(input.forChannelId));
+    }
+    if (input.order !== undefined) {
+      url.searchParams.set("order", String(input.order));
+    }
+    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, "listSubscriptions");
+    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/listVideoCategories.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { throwForYouTube, VideoCategorySchema } from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    part: z
+      .string()
+      .describe("Resource parts to return. Leave as the default.")
+      .default("snippet"),
+    regionCode: z
+      .string()
+      .describe(
+        "ISO 3166-1 alpha-2 country code whose category set to return (e.g. US, GB). Categories vary by region.",
+      )
+      .default("US"),
+  })
+  .strict();
+const outputSchema = z.object({
+  items: z
+    .array(VideoCategorySchema)
+    .describe("The categories for the region."),
+});
+
+const definition = defineTool({
+  name: "listVideoCategories",
+  title: "List Video Categories",
+  description:
+    "List the assignable video categories for a region (the id/title pairs that categoryId accepts on a video). Resolver for the category an upload or update should use.",
+  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/videoCategories`,
+    );
+    if (input.part !== undefined) {
+      url.searchParams.set("part", String(input.part));
+    }
+    if (input.regionCode !== undefined) {
+      url.searchParams.set("regionCode", String(input.regionCode));
+    }
+    const res = await ctx.fetch(url.toString(), {
+      method: "GET",
+    });
+    await throwForYouTube(res, "listVideoCategories");
+    const payload = (await res.json()) as { items?: unknown };
+    return { items: payload.items ?? [] };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/postComment.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { CommentThreadSchema, throwForYouTube } from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    snippet: z
+      .object({
+        videoId: z.string().describe("The video to comment on."),
+        topLevelComment: z
+          .object({
+            snippet: z
+              .object({
+                textOriginal: z.string().describe("The comment text to post."),
+              })
+              .strict(),
+          })
+          .strict(),
+      })
+      .strict(),
+    part: z
+      .string()
+      .describe("Resource parts being written. Leave as the default.")
+      .default("snippet"),
+  })
+  .strict();
+const outputSchema = CommentThreadSchema;
+
+const definition = defineTool({
+  name: "postComment",
+  title: "Post Comment",
+  description:
+    "Post a new top-level comment on a video. For a reply to an existing comment, use replyToComment instead. Requires the youtube.force-ssl scope.",
+  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/commentThreads`);
+    if (input.part !== undefined) {
+      url.searchParams.set("part", String(input.part));
+    }
+    const body: Record<string, unknown> = {};
+    if (input.snippet !== undefined) body["snippet"] = input.snippet;
+    const res = await ctx.fetch(url.toString(), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    await throwForYouTube(res, "postComment");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/rateVideo.ts

@@ -0,0 +1,50 @@
+#!/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 rate."),
+    rating: z
+      .enum(["like", "dislike", "none"])
+      .describe(
+        "like or dislike to set the rating; none to remove an existing rating.",
+      ),
+  })
+  .strict();
+
+const outputSchema = SuccessResultSchema;
+
+const definition = defineTool({
+  name: "rateVideo",
+  title: "Rate Video",
+  description:
+    "Like, dislike, or clear the authenticated user's rating on a video (the thumbs up/down action). Use rating=none to remove an existing rating. The API returns no body; the connector synthesizes a success flag.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    // Setting the same rating twice leaves the same state.
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "youtube",
+  run: async (input, ctx) => {
+    const url = new URL(`https://www.googleapis.com/youtube/v3/videos/rate`);
+    url.searchParams.set("id", input.id);
+    url.searchParams.set("rating", input.rating);
+
+    // videos.rate returns 204 No Content on success — synthesize the success flag.
+    const res = await ctx.fetch(url.toString(), { method: "POST" });
+    await throwForYouTube(res, "rateVideo");
+    return { success: true as const };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/removeVideoFromPlaylist.ts

@@ -0,0 +1,49 @@
+#!/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 playlistItem id to remove (the item's own id from listPlaylistItems, not the video id).",
+      ),
+  })
+  .strict();
+const outputSchema = SuccessResultSchema;
+
+const definition = defineTool({
+  name: "removeVideoFromPlaylist",
+  title: "Remove Video From Playlist",
+  description:
+    "Remove an item from a playlist. The id is the playlistItem id (NOT the video id) — get it from listPlaylistItems.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    // Reversible — the video can be re-added with addVideoToPlaylist.
+    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.id !== undefined) {
+      url.searchParams.set("id", String(input.id));
+    }
+    const res = await ctx.fetch(url.toString(), {
+      method: "DELETE",
+    });
+    await throwForYouTube(res, "removeVideoFromPlaylist");
+    return { success: true as const };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/replyToComment.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import {
+  ConnectorHttpError,
+  defineTool,
+  handleIfScriptMain,
+} from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  CommentSchema,
+  hasYouTubeReason,
+  throwForYouTube,
+} from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    snippet: z
+      .object({
+        parentId: z
+          .string()
+          .describe(
+            "The TOP-LEVEL comment thread id to reply to (from listComments) — not a reply id. Replies are single-level: you cannot reply to a reply.",
+          ),
+        textOriginal: z.string().describe("The reply text to post."),
+      })
+      .strict(),
+    part: z
+      .string()
+      .describe("Resource parts being written. Leave as the default.")
+      .default("snippet"),
+  })
+  .strict();
+const outputSchema = CommentSchema;
+
+const definition = defineTool({
+  name: "replyToComment",
+  title: "Reply To Comment",
+  description:
+    "Reply to an existing top-level comment thread. The parentId must be a top-level comment thread id from listComments — replies are single-level, so you cannot reply to a reply (YouTube rejects it with operationNotSupported). Requires the youtube.force-ssl scope.",
+  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/comments`);
+    if (input.part !== undefined) {
+      url.searchParams.set("part", String(input.part));
+    }
+    const body: Record<string, unknown> = {};
+    if (input.snippet !== undefined) body["snippet"] = input.snippet;
+    const res = await ctx.fetch(url.toString(), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (res.ok) return res.json();
+
+    // Replies are single-level: passing a reply's id as parentId (instead of a
+    // top-level thread id) is rejected with operationNotSupported. Translate it
+    // into actionable guidance rather than surfacing the raw upstream reason.
+    if (res.status === 400) {
+      const errBody = (await res.json().catch(() => null)) as unknown;
+      if (hasYouTubeReason(errBody, "operationNotSupported")) {
+        throw ConnectorHttpError.fromResponseBody(res, errBody, {
+          message:
+            "YouTube replyToComment 400: operationNotSupported — parentId must be a top-level comment thread id (from listComments), not a reply. YouTube does not support nested replies.",
+        });
+      }
+      throw ConnectorHttpError.fromResponseBody(res, errBody, {
+        message: `YouTube replyToComment 400: ${
+          (errBody as { error?: { message?: string } })?.error?.message ??
+          "bad request"
+        }`,
+      });
+    }
+
+    await throwForYouTube(res, "replyToComment");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/searchVideos.ts

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  NextPageToken,
+  SearchResultSchema,
+  throwForYouTube,
+} from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    part: z
+      .string()
+      .describe("Resource parts to return. Leave as the default.")
+      .default("snippet"),
+    type: z
+      .string()
+      .describe(
+        "Resource type to search. Leave as the default to search videos.",
+      )
+      .default("video"),
+    q: z
+      .string()
+      .describe(
+        'Free-text search query. Supports the NOT (-) and OR (|) operators, e.g. "boating|sailing -fishing".',
+      )
+      .optional(),
+    channelId: z
+      .string()
+      .describe(
+        "Restrict results to videos uploaded by this channel id (UC...). Resolve via getChannel.",
+      )
+      .optional(),
+    forMine: z
+      .boolean()
+      .describe(
+        "Restrict results to the authenticated user's own videos. Requires type=video. Cannot be combined with channelId.",
+      )
+      .optional(),
+    order: z
+      .enum(["date", "rating", "relevance", "title", "videoCount", "viewCount"])
+      .describe("Sort order for results.")
+      .default("relevance"),
+    publishedAfter: z
+      .string()
+      .datetime({ offset: true })
+      .describe(
+        "Only return videos published at or after this RFC3339 datetime, e.g. 2026-01-01T00:00:00Z.",
+      )
+      .optional(),
+    publishedBefore: z
+      .string()
+      .datetime({ offset: true })
+      .describe("Only return videos published before this RFC3339 datetime.")
+      .optional(),
+    videoDuration: z
+      .enum(["any", "long", "medium", "short"])
+      .describe(
+        "Filter by length. short = <4 min, medium = 4-20 min, long = >20 min.",
+      )
+      .optional(),
+    regionCode: z
+      .string()
+      .describe(
+        "ISO 3166-1 alpha-2 country code (e.g. US, GB) to return results for.",
+      )
+      .optional(),
+    relevanceLanguage: z
+      .string()
+      .describe("ISO 639-1 language code (e.g. en, es) to bias results toward.")
+      .optional(),
+    maxResults: z
+      .number()
+      .int()
+      .gte(1)
+      .lte(50)
+      .describe(
+        "Max results per page (1-50). Defaults to 10 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(SearchResultSchema).describe("The search hits."),
+  next_page_token: NextPageToken,
+});
+
+const definition = defineTool({
+  name: "searchVideos",
+  title: "Search Videos",
+  description:
+    "Search YouTube for videos by keyword, channel, date, or duration. Returns lightweight results (id + snippet); call getVideo for statistics and contentDetails. Metered against a separate Search Queries quota bucket, independent of the main 10,000-unit pool.",
+  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/search`);
+    if (input.part !== undefined) {
+      url.searchParams.set("part", String(input.part));
+    }
+    if (input.type !== undefined) {
+      url.searchParams.set("type", String(input.type));
+    }
+    if (input.q !== undefined) {
+      url.searchParams.set("q", String(input.q));
+    }
+    if (input.channelId !== undefined) {
+      url.searchParams.set("channelId", String(input.channelId));
+    }
+    if (input.forMine !== undefined) {
+      url.searchParams.set("forMine", String(input.forMine));
+    }
+    if (input.order !== undefined) {
+      url.searchParams.set("order", String(input.order));
+    }
+    if (input.publishedAfter !== undefined) {
+      url.searchParams.set("publishedAfter", String(input.publishedAfter));
+    }
+    if (input.publishedBefore !== undefined) {
+      url.searchParams.set("publishedBefore", String(input.publishedBefore));
+    }
+    if (input.videoDuration !== undefined) {
+      url.searchParams.set("videoDuration", String(input.videoDuration));
+    }
+    if (input.regionCode !== undefined) {
+      url.searchParams.set("regionCode", String(input.regionCode));
+    }
+    if (input.relevanceLanguage !== undefined) {
+      url.searchParams.set(
+        "relevanceLanguage",
+        String(input.relevanceLanguage),
+      );
+    }
+    url.searchParams.set("maxResults", String(input.maxResults ?? 10));
+    if (input.pageToken !== undefined) {
+      url.searchParams.set("pageToken", String(input.pageToken));
+    }
+    const res = await ctx.fetch(url.toString(), {
+      method: "GET",
+    });
+    await throwForYouTube(res, "searchVideos");
+    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 });