@zapier/youtube-connector 0.0.0 → 0.0.1

package/index.ts

@@ -0,0 +1,79 @@
+import { defineConnector, toFunctions } from "@zapier/connectors-sdk";
+
+import { connectionResolvers } from "./connections.ts";
+import addVideoToPlaylistDefinition from "./scripts/addVideoToPlaylist.ts";
+import createPlaylistDefinition from "./scripts/createPlaylist.ts";
+import deletePlaylistDefinition from "./scripts/deletePlaylist.ts";
+import deleteVideoDefinition from "./scripts/deleteVideo.ts";
+import downloadCaptionDefinition from "./scripts/downloadCaption.ts";
+import getChannelDefinition from "./scripts/getChannel.ts";
+import getVideoDefinition from "./scripts/getVideo.ts";
+import listCaptionsDefinition from "./scripts/listCaptions.ts";
+import listCommentsDefinition from "./scripts/listComments.ts";
+import listPlaylistItemsDefinition from "./scripts/listPlaylistItems.ts";
+import listPlaylistsDefinition from "./scripts/listPlaylists.ts";
+import listSubscriptionsDefinition from "./scripts/listSubscriptions.ts";
+import listVideoCategoriesDefinition from "./scripts/listVideoCategories.ts";
+import postCommentDefinition from "./scripts/postComment.ts";
+import rateVideoDefinition from "./scripts/rateVideo.ts";
+import removeVideoFromPlaylistDefinition from "./scripts/removeVideoFromPlaylist.ts";
+import replyToCommentDefinition from "./scripts/replyToComment.ts";
+import searchVideosDefinition from "./scripts/searchVideos.ts";
+import subscribeToChannelDefinition from "./scripts/subscribeToChannel.ts";
+import unsubscribeFromChannelDefinition from "./scripts/unsubscribeFromChannel.ts";
+import updatePlaylistDefinition from "./scripts/updatePlaylist.ts";
+import updateVideoDefinition from "./scripts/updateVideo.ts";
+
+const connector = defineConnector({
+  scripts: {
+    addVideoToPlaylist: addVideoToPlaylistDefinition,
+    createPlaylist: createPlaylistDefinition,
+    deletePlaylist: deletePlaylistDefinition,
+    deleteVideo: deleteVideoDefinition,
+    downloadCaption: downloadCaptionDefinition,
+    getChannel: getChannelDefinition,
+    getVideo: getVideoDefinition,
+    listCaptions: listCaptionsDefinition,
+    listComments: listCommentsDefinition,
+    listPlaylistItems: listPlaylistItemsDefinition,
+    listPlaylists: listPlaylistsDefinition,
+    listSubscriptions: listSubscriptionsDefinition,
+    listVideoCategories: listVideoCategoriesDefinition,
+    postComment: postCommentDefinition,
+    rateVideo: rateVideoDefinition,
+    removeVideoFromPlaylist: removeVideoFromPlaylistDefinition,
+    replyToComment: replyToCommentDefinition,
+    searchVideos: searchVideosDefinition,
+    subscribeToChannel: subscribeToChannelDefinition,
+    unsubscribeFromChannel: unsubscribeFromChannelDefinition,
+    updatePlaylist: updatePlaylistDefinition,
+    updateVideo: updateVideoDefinition,
+  },
+  connectionResolvers,
+});
+
+export default connector;
+export const {
+  addVideoToPlaylist,
+  createPlaylist,
+  deletePlaylist,
+  deleteVideo,
+  downloadCaption,
+  getChannel,
+  getVideo,
+  listCaptions,
+  listComments,
+  listPlaylistItems,
+  listPlaylists,
+  listSubscriptions,
+  listVideoCategories,
+  postComment,
+  rateVideo,
+  removeVideoFromPlaylist,
+  replyToComment,
+  searchVideos,
+  subscribeToChannel,
+  unsubscribeFromChannel,
+  updatePlaylist,
+  updateVideo,
+} = toFunctions(connector);

package/package.json

@@ -1,7 +1,62 @@
 {
   "name": "@zapier/youtube-connector",
-  "version": "0.0.0",
-  "description": "Placeholder published to enable OIDC Trusted Publisher setup. The real package is published via GitLab CI.",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Agent-callable YouTube tools — search and read videos, upload and update videos, manage playlists and playlist items, read and post comments, rate videos, manage subscriptions, and read channel and caption metadata. Use when the user mentions YouTube or wants to find, upload, comment on, or organize YouTube videos and playlists, even if they don't name YouTube explicitly.",
   "license": "Elastic-2.0",
-  "private": false
-}
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./index.ts"
+    }
+  },
+  "bin": {
+    "@zapier/youtube-connector": "./cli.js"
+  },
+  "files": [
+    "dist/",
+    "cli.js",
+    "*.ts",
+    "scripts/",
+    "preflight.sh",
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+    "references/",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@zapier/connectors-sdk": "^0.1.0",
+    "zod": "^4.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@zapier/zapier-sdk": ">=0.59.0 <1.0.0"
+  },
+  "keywords": [
+    "youtube",
+    "zapier",
+    "connector",
+    "tools",
+    "skills",
+    "mcp",
+    "agent",
+    "ai",
+    "automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zapier/connectors.git",
+    "directory": "apps/youtube"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}

package/preflight.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env sh
+# Connector pre-flight readiness check.
+#
+# Managed by @zapier/connectors-dev — do not edit; synced byte-for-byte
+# across every connector.
+#
+# Runs inside whatever agent harness installed the connector (Cursor, Claude
+# Code, Codex, Gemini CLI, Goose, ...) — often a minimal container — and answers
+# ONE question: how do I run the TypeScript scripts here? It picks a runtime —
+# Node 22.18+ when it can already resolve the connector's deps, else an explicit
+# install step (`npm install`, or `bun install` when only Bun is present) — and
+# tells the agent the exact command to run (see EXIT CODES). When deps are
+# missing it disambiguates the two sandbox failures that block an install: a
+# read-only connector dir (must run unsandboxed / be granted write) vs. a
+# blocked home dir (point the package cache inside this dir). Both surface as a
+# misleading `EPERM`, so the recommendation names the actual fix.
+#
+# NEEDS_ACTION is a single self-verifying step (install a runtime / deps), not a
+# loop: do it, then run a script. The action confirms its own success and the
+# first `--help` run is the authoritative check, so re-running this pre-flight to
+# reconfirm is optional, not required.
+#
+# THE AGENT CONTRACT IS THE STDOUT, NOT THIS HEADER. Agents don't read this file;
+# they run it and parse the `PREFLIGHT_*` lines — each value starts with a stable
+# token (parse as `KEY: (\w+)`), with an optional human gloss in parens, and
+# `PREFLIGHT_RECOMMENDATION` is the one-line next step. SKILL.md "Step 0" is the
+# agent-facing spec; this header is for maintainers of the canonical script.
+#
+# WHY POSIX sh (not bash)
+#   Minimal sandboxes often ship only BusyBox `sh` with no bash. This script runs
+#   unchanged under BusyBox sh, dash, and bash, and never hard-requires
+#   node/bun/npm — a missing runtime degrades to a NEEDS_ACTION instruction.
+#
+# EXIT CODES (the verdict; also emitted on PREFLIGHT_STATUS)
+#   0  READY         a runtime + deps are in place; run the scripts
+#   1  NEEDS_ACTION  perform the printed action (install runtime / deps), then
+#                    run a script — re-running this check is optional
+
+set -u
+
+EXIT_READY=0
+EXIT_NEEDS_ACTION=1
+
+# Directory this script lives in — deps + scripts are resolved relative to it,
+# not the caller's cwd, so `./preflight.sh` works from anywhere.
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+
+has() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+# Node >= 22.18 is the connector baseline (native .ts stripping). Anything older
+# is treated as "no Node" so we fall back to Bun.
+node_ge_2218() {
+  has node || return 1
+  v=$(node -v 2>/dev/null) || return 1
+  v=${v#v}
+  major=${v%%.*}
+  rest=${v#*.}
+  minor=${rest%%.*}
+  case "$major" in '' | *[!0-9]*) return 1 ;; esac
+  case "$minor" in '' | *[!0-9]*) minor=0 ;; esac
+  [ "$major" -gt 22 ] && return 0
+  [ "$major" -eq 22 ] && [ "$minor" -ge 18 ] && return 0
+  return 1
+}
+
+# Are the connector's declared deps installed where Node would find them? Node
+# won't fetch — they must be on disk (this dir's node_modules or an ancestor's).
+# Reads the connector's own package.json, so this stays connector-agnostic. A
+# bare `[ -d node_modules ]` is the wrong test: under pnpm/monorepo layouts the
+# deps can live in an ancestor (or be hoisted), and a local node_modules can
+# exist without the package being present. We check each dep's package.json
+# exists in one of Node's resolution paths rather than `require.resolve(name)`,
+# because resolving the package ENTRY can fail for ESM-only / `exports`-map
+# packages even when they're fully installed and importable.
+node_resolves() {
+  ( CDPATH= cd -- "$SCRIPT_DIR" && node -e 'const fs=require("fs"),path=require("path");const d=require("./package.json").dependencies||{};for(const k of Object.keys(d)){const ps=require.resolve.paths(k)||[];if(!ps.some(b=>fs.existsSync(path.join(b,k,"package.json"))))process.exit(1);}' ) >/dev/null 2>&1
+}
+
+# Can we actually WRITE into this directory right now? Any dep install must land
+# `node_modules/` here, so if the harness mounts the connector read-only (common
+# when skills live under ~/.<agent>/skills, outside the agent's writable
+# workspace) no install can succeed in place — the only fixes are to run it
+# unsandboxed or grant write access. Two deliberate choices:
+#   - Probe with a real create+remove, not `[ -w ]`: a sandbox denies the write
+#     at the syscall while the permission bits still look writable.
+#   - Probe by creating a DIRECTORY (`mkdir`), not a file: that's the install's
+#     very first on-disk action (node_modules/ and the cache dirs), and at least
+#     one sandbox (Claude Code) permits creating a file here while denying
+#     `mkdir` — a file-based probe reports writable and the install then EPERMs.
+dir_writable() {
+  _t="$SCRIPT_DIR/.preflight-write-test.$$"
+  mkdir "$_t" 2>/dev/null || return 1
+  rmdir "$_t" 2>/dev/null
+  return 0
+}
+
+# ---- 1) Pick a runtime -----------------------------------------------------
+# Node 22.18+ (native TS strip) is the baseline and the preferred runner whenever
+# it's present — it runs the .ts scripts directly. Bun is the fallback runner
+# only when there's no usable Node. We DON'T lean on Bun's implicit auto-install:
+# it's silently suppressed by any ancestor node_modules (monorepo layouts) and
+# fails the same way Node's `npm install` does under a sandbox that blocks Bun's
+# home cache — so missing deps are always an explicit, cache-local install step.
+nresolves=false
+node_ge_2218 && node_resolves && nresolves=true
+
+if [ "$nresolves" = true ]; then
+  runner=node
+  ready=true
+elif node_ge_2218; then
+  runner=node # present but deps unresolved — install step below
+  ready=false
+elif has bun; then
+  runner=bun # no usable Node — Bun runs the scripts; install step below
+  ready=false
+else
+  echo "PREFLIGHT_STATUS: NEEDS_ACTION"
+  echo "PREFLIGHT_RECOMMENDATION: no Node 22.18+ or Bun found — install Node 22.18+ (ships npm) or Bun, then run \`<runner> ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  exit "$EXIT_NEEDS_ACTION"
+fi
+
+# ---- 2) Install deps if the chosen runtime can't run as-is -----------------
+# Two distinct sandbox failures to disambiguate, because their fixes differ:
+#   a) This directory is READ-ONLY (skills installed outside the agent's
+#      writable workspace). No install can place node_modules here — the agent
+#      must run it unsandboxed or be granted write access. A cache flag can't
+#      help.
+#   b) The directory is writable but the HOME dir is sandboxed, so the default
+#      ~/.npm / ~/.bun cache write is what EPERMs mid-install. Pointing the cache
+#      INSIDE this directory sidesteps that without disabling the sandbox (and is
+#      harmless otherwise — just an unused cache dir).
+# So probe writability first and recommend accordingly.
+if [ "$ready" != true ]; then
+  echo "PREFLIGHT_STATUS: NEEDS_ACTION"
+  [ "$runner" = bun ] && install_cmd="bun install" || install_cmd="npm install"
+  if ! dir_writable; then
+    echo "PREFLIGHT_RECOMMENDATION: dependencies are not installed and ${SCRIPT_DIR} is read-only in the current sandbox (a test write there failed) — \`${install_cmd}\` can't place node_modules here. Run the install with the sandbox disabled, or grant the agent write access to ${SCRIPT_DIR} (a cache flag won't help — node_modules must land in this directory); then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  elif [ "$runner" = bun ]; then
+    echo "PREFLIGHT_RECOMMENDATION: dependencies are not installed — run \`BUN_INSTALL_CACHE_DIR=\"${SCRIPT_DIR}/.bun-cache\" bun install\` in ${SCRIPT_DIR} (the workspace-local cache survives a sandbox that blocks ~/.bun; plain \`bun install\` works otherwise), then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  elif has npm; then
+    echo "PREFLIGHT_RECOMMENDATION: dependencies are not installed — run \`npm install --cache \"${SCRIPT_DIR}/.npm-cache\"\` in ${SCRIPT_DIR} (the workspace-local --cache survives a sandbox that blocks ~/.npm; plain \`npm install\` works otherwise), then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  else
+    # node >= 22.18 ships npm, so a missing npm means it was removed from the
+    # Node install. Restore it, then install with a workspace-local cache.
+    echo "PREFLIGHT_RECOMMENDATION: npm is missing (it ships with Node 22.18+) — reinstall/repair Node 22.18+, run \`npm install --cache \"${SCRIPT_DIR}/.npm-cache\"\` in ${SCRIPT_DIR}, then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  fi
+  exit "$EXIT_NEEDS_ACTION"
+fi
+
+# ---- 3) Ready --------------------------------------------------------------
+# Runtime + deps are in place — the scripts run.
+echo "PREFLIGHT_STATUS: READY"
+echo "PREFLIGHT_RUNNER: ${runner}"
+echo "PREFLIGHT_RECOMMENDATION: run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials, then run the script with the required env vars set."
+exit "$EXIT_READY"

package/references/youtube-api-gotchas.md

@@ -0,0 +1,252 @@
+# YouTube Data API — gotchas
+
+Non-obvious behaviors of the YouTube Data API v3 that affect how tools should be
+called and how their responses should be interpreted. Every non-trivial claim links
+to the public source it was taken from.
+
+## Parts & fields
+
+- Every resource is partitioned into named **parts** (e.g. `snippet`,
+  `contentDetails`, `statistics`, `status`). The `part` parameter "is a required
+  parameter for any API request that retrieves or returns a resource" and identifies
+  which parts the response will include — request a part or its fields will be
+  absent. ([overview](https://developers.google.com/youtube/v3/getting-started),
+  [videos.list](https://developers.google.com/youtube/v3/docs/videos/list))
+- On a **write**, `part` does double duty: it "identifies the properties that the
+  write operation will set as well as the properties that the API response will
+  include." ([playlists.insert](https://developers.google.com/youtube/v3/docs/playlists/insert))
+
+## Quota & rate limits
+
+- Default allocation is "10,000 units per day combined for all other endpoints,"
+  plus separate per-call allowances for the bucketed methods below.
+  ([overview](https://developers.google.com/youtube/v3/getting-started),
+  [quota guide](https://developers.google.com/youtube/v3/guides/quota_and_compliance_audits))
+- Cost per call (verbatim "quota cost" from each method's reference page):
+  - read / list (videos, channels, playlistItems, commentThreads, videoCategories,
+    subscriptions): **1 unit**.
+    ([videos.list](https://developers.google.com/youtube/v3/docs/videos/list),
+    [playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list),
+    [commentThreads.list](https://developers.google.com/youtube/v3/docs/commentThreads/list),
+    [subscriptions.list](https://developers.google.com/youtube/v3/docs/subscriptions/list))
+  - write (videos.update, playlists.insert, subscriptions.insert,
+    commentThreads.insert, comments.insert, videos.rate, videos.delete): **50 units**.
+    ([videos.update](https://developers.google.com/youtube/v3/docs/videos/update),
+    [playlists.insert](https://developers.google.com/youtube/v3/docs/playlists/insert),
+    [subscriptions.insert](https://developers.google.com/youtube/v3/docs/subscriptions/insert),
+    [commentThreads.insert](https://developers.google.com/youtube/v3/docs/commentThreads/insert),
+    [comments.insert](https://developers.google.com/youtube/v3/docs/comments/insert),
+    [videos.rate](https://developers.google.com/youtube/v3/docs/videos/rate))
+  - `captions.list`: **50 units**; `captions.download`: **200 units** (the
+    most expensive read in this catalog).
+    ([captions.list](https://developers.google.com/youtube/v3/docs/captions/list),
+    [captions.download](https://developers.google.com/youtube/v3/docs/captions/download))
+  - `search.list` is **no longer charged against the 10,000-unit pool**. As of June 1,
+    2026 the API "is transitioning to a granular quota system … starting with
+    `videos.insert` and `search.list`," which "will be charged to their own respective
+    quota buckets." The current per-method page states `search.list` "has a quota cost
+    of 1 unit in the Search Queries quota bucket" — older guidance citing 100 units
+    against the main pool is stale.
+    ([revision history](https://developers.google.com/youtube/v3/revision_history),
+    [search.list](https://developers.google.com/youtube/v3/docs/search/list))
+- When the daily quota is exhausted the API returns `quotaExceeded` (403). The error
+  docs describe no `Retry-After` header; treat quota exhaustion as non-retryable until
+  the daily reset rather than backing off in a loop.
+  ([errors](https://developers.google.com/youtube/v3/docs/errors))
+
+## Errors & recovery
+
+- All errors share Google's standard envelope:
+  ```json
+  {
+    "error": {
+      "errors": [{ "domain": "...", "reason": "...", "message": "..." }],
+      "code": 400,
+      "message": "..."
+    }
+  }
+  ```
+  The actionable signal is `error.errors[0].reason`.
+  ([error format](https://developers.google.com/youtube/v3/docs/core_errors))
+- `quotaExceeded` (403): "The request cannot be completed because you have exceeded
+  your quota." → stop; do not retry until quota resets.
+  ([errors](https://developers.google.com/youtube/v3/docs/errors))
+- `insufficientPermissions` (403): "The OAuth 2.0 token provided for the request
+  specifies scopes that are insufficient for accessing the requested data." →
+  reconnect with the scope the operation needs.
+  ([errors](https://developers.google.com/youtube/v3/docs/errors))
+- `forbidden` (403): "Access forbidden. The request may not be properly authorized."
+  → either a missing scope or you do not own the resource (reconnecting won't fix
+  ownership). ([errors](https://developers.google.com/youtube/v3/docs/errors))
+- `notFound` (404): the identified resource "cannot be found" → verify the id.
+  ([errors](https://developers.google.com/youtube/v3/docs/errors))
+- `authorizationRequired` (401): e.g. "The request uses the `mine` parameter but is
+  not properly authorized." → reconnect.
+  ([errors](https://developers.google.com/youtube/v3/docs/errors))
+- `subscriptionDuplicate` (400): "The subscription that you are trying to create
+  already exists." This is a post-condition-satisfied state, not a hard failure — the
+  user is already subscribed.
+  ([subscriptions.insert](https://developers.google.com/youtube/v3/docs/subscriptions/insert))
+
+## OAuth scopes & ownership
+
+Scope descriptions (from the consent screen):
+
+- `youtube.readonly` — "View your YouTube account."
+- `youtube` — "Manage your YouTube account."
+- `youtube.force-ssl` — "See, edit, and permanently delete your YouTube videos,
+  ratings, comments and captions."
+  ([scopes](https://developers.google.com/youtube/v3/guides/auth/installed-apps))
+
+- **Comment and caption writes require `youtube.force-ssl`.** `commentThreads.insert`,
+  `comments.insert`, `captions.list`, and `captions.download` all list
+  `youtube.force-ssl` among their accepted scopes.
+  ([commentThreads.insert](https://developers.google.com/youtube/v3/docs/commentThreads/insert),
+  [comments.insert](https://developers.google.com/youtube/v3/docs/comments/insert),
+  [captions.list](https://developers.google.com/youtube/v3/docs/captions/list),
+  [captions.download](https://developers.google.com/youtube/v3/docs/captions/download))
+- **Ownership:** downloading a caption track "requires the user to have permission to
+  edit the video" (the video's owner or an editor), not merely read access.
+  ([captions.download](https://developers.google.com/youtube/v3/docs/captions/download))
+  `textOriginal` for a comment "is only returned to the authenticated user if they are
+  the comment's author."
+  ([comments resource](https://developers.google.com/youtube/v3/docs/comments))
+
+## Pagination
+
+- List methods return `nextPageToken` which "identifies the next page of the result
+  that can be retrieved"; pass it back as `pageToken`. When it is absent, there are no
+  more pages. ([commentThreads.list](https://developers.google.com/youtube/v3/docs/commentThreads/list))
+- `maxResults` caps differ by resource:
+  - search, playlistItems, subscriptions: 0–50, default 5.
+    ([search.list](https://developers.google.com/youtube/v3/docs/search/list),
+    [playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list),
+    [subscriptions.list](https://developers.google.com/youtube/v3/docs/subscriptions/list))
+  - commentThreads: 1–100, default 20.
+    ([commentThreads.list](https://developers.google.com/youtube/v3/docs/commentThreads/list))
+
+## IDs
+
+- A `playlistItem` id is distinct from the video id it points to — use the
+  playlistItem id to remove an item.
+- A `subscription` id is distinct from the channel id — use the subscription id to
+  unsubscribe.
+- `channels.list` `id` "specifies a comma-separated list of the YouTube channel ID(s)."
+  ([channels.list](https://developers.google.com/youtube/v3/docs/channels/list))
+
+## Statistics (counts as strings)
+
+- Count fields are typed `unsigned long` and come back as JSON **strings**, not
+  numbers: `viewCount`, `likeCount`, `commentCount` (videos), and `viewCount`,
+  `subscriberCount`, `videoCount` (channels). Do not coerce blindly.
+  ([videos resource](https://developers.google.com/youtube/v3/docs/videos),
+  [channels resource](https://developers.google.com/youtube/v3/docs/channels))
+- `channels` `subscriberCount` "is rounded down to three significant figures," and
+  `hiddenSubscriberCount` "Indicates whether the channel's subscriber count is publicly
+  visible" — when hidden, treat `subscriberCount` as unavailable.
+  ([channels resource](https://developers.google.com/youtube/v3/docs/channels))
+- `channels` `videoCount` "reflects the count of the channel's public videos only,
+  even to owners." ([channels resource](https://developers.google.com/youtube/v3/docs/channels))
+
+## Per-resource notes
+
+### Videos
+
+- `contentDetails.duration` is an ISO 8601 duration, e.g. `PT15M33S` for 15 min 33 s.
+  ([videos resource](https://developers.google.com/youtube/v3/docs/videos))
+- `contentDetails.caption` is the **string** `"true"` or `"false"`, not a boolean.
+  ([videos resource](https://developers.google.com/youtube/v3/docs/videos))
+- `status.uploadStatus` ∈ {`deleted`, `failed`, `processed`, `rejected`, `uploaded`};
+  `status.privacyStatus` ∈ {`private`, `public`, `unlisted`}.
+  ([videos resource](https://developers.google.com/youtube/v3/docs/videos))
+- `status.publishAt` (scheduled publish) "can be set only if the privacy status of the
+  video is private." ([videos resource](https://developers.google.com/youtube/v3/docs/videos))
+- COPPA: `selfDeclaredMadeForKids` lets the channel owner "designate the video as being
+  child-directed" on insert/update; `madeForKids` is the resulting status.
+  ([videos resource](https://developers.google.com/youtube/v3/docs/videos))
+- **`videos.update` replaces, it does not merge.** "this method will override the
+  existing values for all of the mutable properties that are contained in any parts
+  that the parameter value specifies," and "if your request does not specify a value
+  for a property that already has a value, the property's existing value will be
+  deleted." Read the current resource, modify, then write back the whole part.
+  ([videos.update](https://developers.google.com/youtube/v3/docs/videos/update))
+- `videos.update` with a `snippet` part requires `snippet.title` and
+  `snippet.categoryId`.
+  ([videos.update](https://developers.google.com/youtube/v3/docs/videos/update))
+- `videos.insert` `notifySubscribers` default "is True."
+  ([videos.insert](https://developers.google.com/youtube/v3/docs/videos/insert))
+- A video title "has a character limit of 100 characters and cannot include invalid
+  characters." ([title limits, Help Center](https://support.google.com/youtube/answer/57404))
+- `videos.rate` returns "an HTTP `204` response code (`No Content`)" — empty body on
+  success; `rating` ∈ {`like`, `dislike`, `none`}.
+  ([videos.rate](https://developers.google.com/youtube/v3/docs/videos/rate))
+
+### Search
+
+- A `search.list` result resource contains only `kind`, `etag`, `id`, and `snippet` —
+  no `statistics` or `contentDetails`. The `snippet` "contains basic details about a
+  search result, such as its title or description"; call `getVideo` (videos.list) when
+  you need view counts, duration, or other full-resource fields.
+  ([searchResult resource](https://developers.google.com/youtube/v3/docs/search))
+- `order` ∈ {`date`, `rating`, `relevance` (default), `title`, `videoCount`,
+  `viewCount`}; `publishedAfter`/`publishedBefore` take RFC 3339 date-times;
+  `relevanceLanguage` is an ISO 639-1 two-letter code.
+  ([search.list](https://developers.google.com/youtube/v3/docs/search/list))
+
+### Playlists
+
+- `status.privacyStatus` ∈ {`private`, `public`, `unlisted`}; no default is documented
+  in the API reference.
+  ([playlists resource](https://developers.google.com/youtube/v3/docs/playlists))
+- `playlistItems.list` `maxResults` is 0–50 (default 5).
+  ([playlistItems.list](https://developers.google.com/youtube/v3/docs/playlistItems/list))
+
+### Comments
+
+- `textDisplay` "can be retrieved in either plain text or HTML" and "may differ from
+  the original comment text. For example, it may replace video links with video
+  titles." `textOriginal` is "the original, raw text." Control format via
+  `commentThreads.list`'s `textFormat` (`html` default, or `plainText`).
+  ([comments resource](https://developers.google.com/youtube/v3/docs/comments),
+  [commentThreads.list](https://developers.google.com/youtube/v3/docs/commentThreads/list))
+- To create a top-level comment use `commentThreads.insert`; `comments.insert` "handles
+  replies to existing comments, requiring the `snippet.parentId` property."
+  ([comments.insert](https://developers.google.com/youtube/v3/docs/comments/insert))
+
+### Captions
+
+- `snippet.trackKind` ∈ {`standard` (a regular caption track, the default), `ASR`
+  (generated by automatic speech recognition), `forced`}; `snippet.status` ∈
+  {`serving`, `syncing`, `failed`}; `snippet.language` is a BCP-47 tag.
+  ([captions resource](https://developers.google.com/youtube/v3/docs/captions))
+- `captions.download` `tfmt` ∈ {`sbv`, `scc`, `srt`, `ttml`, `vtt`}; `tlang` requests a
+  machine translation (ISO 639-1 code). Returns a raw caption file body, not JSON.
+  ([captions.download](https://developers.google.com/youtube/v3/docs/captions/download))
+- Insufficient permission to download a track returns 403: "The permissions associated
+  with the request are not sufficient to download the caption track."
+  ([captions.download](https://developers.google.com/youtube/v3/docs/captions/download))
+
+### Channels
+
+- Resolve the authenticated user's channel with `mine=true`; look up others with `id`
+  (comma-separated) or `forHandle` ("a YouTube handle … can be prepended with an `@`
+  symbol"). ([channels.list](https://developers.google.com/youtube/v3/docs/channels/list))
+- A channel's uploads playlist is `contentDetails.relatedPlaylists.uploads` — "The ID
+  of the playlist that contains the channel's uploaded videos." Pass it to
+  `playlistItems.list` to enumerate a channel's videos.
+  ([channels resource](https://developers.google.com/youtube/v3/docs/channels))
+
+### Subscriptions
+
+- `subscriptions.list` `forChannelId` "specifies a comma-separated list of channel
+  IDs" to filter by; combine with `mine=true` to check whether the user is subscribed
+  to a specific channel.
+  ([subscriptions.list](https://developers.google.com/youtube/v3/docs/subscriptions/list))
+
+### Video categories
+
+- Only categories whose `snippet.assignable` is true can be set on a video —
+  `assignable` "Indicates whether videos can be associated with the category."
+  ([videoCategories resource](https://developers.google.com/youtube/v3/docs/videoCategories))
+- Categories are region-specific; `videoCategories.list` is queried by `regionCode`.
+  ([videoCategories.list](https://developers.google.com/youtube/v3/docs/videoCategories/list))

package/scripts/addVideoToPlaylist.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { PlaylistItemSchema, throwForYouTube } from "../lib/youtube.ts";
+
+const inputSchema = z
+  .object({
+    snippet: z
+      .object({
+        playlistId: z
+          .string()
+          .describe(
+            "The id of the playlist to add the video to (from listPlaylists; you must own it).",
+          ),
+        resourceId: z
+          .object({
+            kind: z
+              .string()
+              .describe("Always youtube#video for adding a video.")
+              .default("youtube#video"),
+            videoId: z.string().describe("The 11-char id of the video to add."),
+          })
+          .strict()
+          .describe(
+            "The video to add. Set kind to youtube#video and videoId to the 11-char video id.",
+          ),
+        position: z
+          .number()
+          .int()
+          .describe("0-based insert position. Omit to append at the end.")
+          .optional(),
+      })
+      .strict(),
+    part: z
+      .string()
+      .describe("Resource parts being written. Leave as the default.")
+      .default("snippet"),
+  })
+  .strict();
+
+const outputSchema = PlaylistItemSchema;
+
+const definition = defineTool({
+  name: "addVideoToPlaylist",
+  title: "Add Video To Playlist",
+  description:
+    "Add a video to a playlist owned by the authenticated user. Resolve the playlist id via listPlaylists. Returns the new playlistItem id (distinct from the video id — use it with removeVideoFromPlaylist).",
+  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/playlistItems`);
+    url.searchParams.set("part", input.part);
+
+    const res = await ctx.fetch(url.toString(), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ snippet: input.snippet }),
+    });
+    await throwForYouTube(res, "addVideoToPlaylist");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });