@zapier/youtube-connector 0.0.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/NOTICE

@@ -0,0 +1,8 @@
+Independent, unofficial connector for YouTube.
+
+Zapier licenses only the connector code in this package, under the Elastic
+License 2.0. Zapier grants no rights in YouTube's API, services, data,
+schemas, documentation, or other materials, which remain the property of
+YouTube. YouTube and its logos are trademarks of their owner, used only to
+identify the service this connector works with. Not affiliated with, endorsed
+by, or sponsored by YouTube.

package/README.md

@@ -1,4 +1,119 @@
 # @zapier/youtube-connector
 
-> **Placeholder** — published to bootstrap OIDC Trusted Publisher configuration.
-> The real package is published via GitLab CI once trust is established.
+_Independent, unofficial connector for YouTube. Not affiliated with, endorsed by, or sponsored by YouTube. "YouTube" is a trademark of its owner, used only to identify the service this connector works with._
+
+Agent-callable YouTube tools — search and read videos, update and delete 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, comment on, or organize YouTube videos and playlists, even if they don't name YouTube explicitly.
+
+This connector wraps the [YouTube Data API v3](https://developers.google.com/youtube/v3) (`https://www.googleapis.com/youtube/v3/`) behind 22 agent-callable tools spanning video discovery and detail, video update / delete, playlist and playlist-item management, comment reading and posting, subscriptions, and the channel / category / caption read surfaces an agent needs to resolve ids. Auth is Google OAuth 2.0 — a single access token whose capabilities are gated by OAuth scope and by resource ownership.
+
+This connector is the same artifact across four shapes: MCP server, CLI bin, importable Node module, and an [Agent Skill](https://agentskills.io/) anchored by [`SKILL.md`](SKILL.md). Pick the shape that matches how your agent runs.
+
+## Install
+
+```bash
+# Run a tool with zero install — npx fetches the package on first use
+YOUTUBE_ACCESS_TOKEN=xxx npx @zapier/youtube-connector run <toolName> '{ ... }' --connection env:YOUTUBE_ACCESS_TOKEN
+
+# Install as a dependency to import the tools in your own code
+npm install @zapier/youtube-connector
+
+# Or install as an Agent Skill (https://agentskills.io)
+npx skills zapier/connectors --skill youtube
+```
+
+Auth is one `[<resolver>:]<value>` connection string passed with `--connection`. The value is a _selector_, not the secret: `--connection zapier:<connection-id>` routes through Zapier-managed auth (recommended; no third-party secret enters the agent's environment — store the id in `YOUTUBE_ZAPIER_CONNECTION_ID` and pass `--connection "zapier:$YOUTUBE_ZAPIER_CONNECTION_ID"` if you like), and `--connection env:YOUTUBE_ACCESS_TOKEN` reads a direct token from `$YOUTUBE_ACCESS_TOKEN` (the token stays in `env`, never on argv; Google access tokens expire ~1h and are not refreshed in direct mode). The `<resolver>:` prefix is optional — a bare value is claimed by the first matching resolver. See [`SKILL.md`](SKILL.md#auth) for the scope matrix and how to find a connection ID.
+
+## Tools
+
+| Tool                      | Description                                                                                 |
+| ------------------------- | ------------------------------------------------------------------------------------------- |
+| `searchVideos`            | Search videos by keyword, channel, date, or duration (id + snippet only; quota-heavy).      |
+| `getVideo`                | Get full details of one or more videos by id — snippet, statistics, contentDetails, status. |
+| `updateVideo`             | Update a video's metadata (read-modify-write — only the fields you pass change).            |
+| `deleteVideo`             | Permanently delete a video you own.                                                         |
+| `rateVideo`               | Like, dislike, or clear your rating on a video.                                             |
+| `listPlaylists`           | List playlists owned by the user or a channel, or fetch playlists by id.                    |
+| `createPlaylist`          | Create a new playlist on the user's channel.                                                |
+| `updatePlaylist`          | Update a playlist's title, description, or privacy (replaces, doesn't merge).               |
+| `deletePlaylist`          | Permanently delete a playlist you own.                                                      |
+| `listPlaylistItems`       | List the videos in a playlist, in order (each item carries its playlistItem id).            |
+| `addVideoToPlaylist`      | Add a video to a playlist you own.                                                          |
+| `removeVideoFromPlaylist` | Remove an item from a playlist (by playlistItem id, not video id).                          |
+| `listComments`            | List top-level comment threads on a video, each with its first replies.                     |
+| `postComment`             | Post a new top-level comment on a video (needs the comment scope).                          |
+| `replyToComment`          | Reply to an existing top-level comment thread (needs the comment scope).                    |
+| `getChannel`              | Get a channel's profile, statistics, and uploads-playlist id (by mine / id / @handle).      |
+| `listVideoCategories`     | List the assignable video categories for a region.                                          |
+| `listSubscriptions`       | List the user's subscriptions, or check a subscription to one channel.                      |
+| `subscribeToChannel`      | Subscribe the user to a channel.                                                            |
+| `unsubscribeFromChannel`  | Unsubscribe the user from a channel (by subscription id, not channel id).                   |
+| `listCaptions`            | List the caption tracks available for a video (needs the comment/caption scope).            |
+| `downloadCaption`         | Download a caption track's text in a chosen format (srt/vtt/sbv/scc/ttml).                  |
+
+Run `npx @zapier/youtube-connector run <toolName> --help` to see any tool's exact input contract + the available resolvers.
+
+## Usage
+
+```ts
+import { getVideo } from "@zapier/youtube-connector";
+
+// Each named export is the consumer-facing (input, opts) => Promise<{ data, meta }>.
+const { data } = await getVideo(
+  { id: "dQw4w9WgXcQ" },
+  { connection: "env:YOUTUBE_ACCESS_TOKEN" },
+);
+// data.items[0].statistics.viewCount — counts are returned as strings, not numbers.
+```
+
+`data` is the tool's output (its `outputSchema`); `meta.outputDataValidation` reports what validation did. Pass `{ skipOutputDataValidation: true }` in the run options for the raw, unvalidated output. See [`SKILL.md`](SKILL.md#output-format) for the full envelope contract.
+
+## MCP Server
+
+Add one stanza to any MCP-aware client (Claude Desktop, Cursor, Claude Code, …) to auto-discover the tools over stdio:
+
+<!-- prettier-ignore -->
+```jsonc
+// e.g. claude_desktop_config.json or .cursor/mcp.json
+{
+  "mcpServers": {
+    "youtube": {
+      "command": "npx",
+      "args": ["@zapier/youtube-connector", "mcp", "--connection", "zapier:<connection-id>"],
+    }
+  }
+}
+```
+
+No Zapier account? Use the `env:` resolver — point `--connection` at an env-var name and keep the token in `env`: `"args": ["@zapier/youtube-connector", "mcp", "--connection", "env:YOUTUBE_ACCESS_TOKEN"]` with `"env": { "YOUTUBE_ACCESS_TOKEN": "xxx" }`.
+
+## When to use this
+
+- An agent needs to read YouTube data — find videos, pull a video's full statistics and details, enumerate a playlist or a channel's uploads, or read comment threads.
+- An agent needs to manage a creator's own content — update videos, organize playlists, post or reply to comments, or manage subscriptions.
+- You want a single, scope-gated OAuth surface over the YouTube Data API that resolves ids (channels → uploads playlist, categories, caption tracks) the way an agent reasons about them.
+
+## When NOT to use this
+
+- **Analytics / reporting** (views-over-time, watch-time, revenue, demographics) — not covered; that's the YouTube Analytics API.
+- **Video upload, custom thumbnails, live streaming, comment moderation, caption upload, or channel administration** — out of scope for v1 (video upload and thumbnails require binary media uploads the connection transport doesn't support; captions are read-only here).
+- **Bulk discovery via search** — `search.list` costs 100 quota units and is eventually consistent; to enumerate a known channel's videos, prefer `getChannel` → `listPlaylistItems` on the uploads playlist.
+
+## Links
+
+- [`SKILL.md`](SKILL.md) — runtime guidance for agents
+- [YouTube Data API v3 reference](https://developers.google.com/youtube/v3)
+- [Source](https://github.com/zapier/connectors/tree/main/apps/youtube)
+
+## Legal
+
+**Scope of license.** Zapier licenses only the connector code in this package. Zapier grants no rights in YouTube's API, services, data, schemas, documentation, or other materials, which remain the property of YouTube. Your use of YouTube's API is governed by your own agreement with YouTube.
+
+**Trademarks and affiliation.** YouTube and its logos are trademarks of their owner, used here only to identify the service this connector works with. This connector is not affiliated with, endorsed by, or sponsored by YouTube.
+
+**Your responsibility.** This connector calls YouTube's API using credentials you supply. You are responsible for holding a valid YouTube account, for complying with YouTube's API terms, developer policies, and acceptable use rules, and for the data you send and receive through it.
+
+**No warranty.** This connector is provided "as is," without warranty of any kind, and is not an official YouTube product. Zapier is not responsible for changes YouTube makes to its API or for any consequence of your use of YouTube's API. See the repository LICENSE for the full disclaimer.
+
+**Forks.** You may fork and modify this connector under the Elastic License 2.0. You may state that your fork is "based on" Zapier's connector, but you may not use the "Zapier" name or logo as the name or branding of your fork, or in any way that suggests Zapier produces, endorses, or supports it.
+
+Licensed under the Elastic License 2.0. See the repository LICENSE and NOTICE.

package/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: youtube
+description: Agent-callable YouTube tools — search and read videos, update and delete 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, comment on, or organize YouTube videos and playlists, even if they don't name YouTube explicitly.
+license: Elastic-2.0
+compatibility: Requires Node.js 22.18+ or Bun 1.x; run `npm install` in this directory first.
+metadata:
+  title: YouTube
+  source: https://github.com/zapier/connectors/blob/main/apps/youtube/SKILL.md
+  zapier-app-key: YouTubeV2CLIAPI
+  api-docs: https://developers.google.com/youtube/v3
+---
+
+# YouTube
+
+_Independent, unofficial connector for YouTube. Not affiliated with, endorsed by, or sponsored by YouTube. "YouTube" is a trademark of its owner, used only to identify the service this connector works with._
+
+Tools for working with YouTube against the [YouTube Data API v3](https://developers.google.com/youtube/v3) (`https://www.googleapis.com/youtube/v3/`): search and read videos, update or delete videos, like or dislike videos, create and manage playlists and their items, read and post comments, manage subscriptions, and read channel, category, and caption metadata. 22 tools across video discovery, video and playlist management, community engagement, and the read surfaces an agent needs to resolve ids.
+
+## When to use this connector
+
+- An agent needs to **find or read** video data — search for videos, get a video's full statistics and details, list the videos in a playlist, or read a channel's profile and uploads.
+- An agent needs to **manage videos** — update an existing video's metadata without wiping the fields it didn't touch, like/dislike, or delete a video it owns.
+- An agent needs to **organize playlists** — create, update, or delete playlists, and add or remove videos.
+- An agent needs to **engage with the community** — read comment threads, post a comment, reply to a thread, or subscribe / unsubscribe to channels.
+
+## Scripts
+
+One file per tool in [`scripts/`](scripts/); each tool's `inputSchema` / `outputSchema` (Zod) in the script file is the source of truth for its contract. All tools use the single connection `youtube`.
+
+| Script                                                                     | Tool name                 | Connections | Description                                                                                      |
+| -------------------------------------------------------------------------- | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------ |
+| [`scripts/searchVideos.ts`](scripts/searchVideos.ts)                       | `searchVideos`            | `youtube`   | Search videos by keyword, channel, date, or duration (id + snippet only; separate quota bucket). |
+| [`scripts/getVideo.ts`](scripts/getVideo.ts)                               | `getVideo`                | `youtube`   | Get full details of one or more videos by id — snippet, statistics, contentDetails, status.      |
+| [`scripts/updateVideo.ts`](scripts/updateVideo.ts)                         | `updateVideo`             | `youtube`   | Update a video's metadata (read-modify-write — only the fields you pass change).                 |
+| [`scripts/deleteVideo.ts`](scripts/deleteVideo.ts)                         | `deleteVideo`             | `youtube`   | Permanently delete a video you own.                                                              |
+| [`scripts/rateVideo.ts`](scripts/rateVideo.ts)                             | `rateVideo`               | `youtube`   | Like, dislike, or clear your rating on a video.                                                  |
+| [`scripts/listPlaylists.ts`](scripts/listPlaylists.ts)                     | `listPlaylists`           | `youtube`   | List playlists owned by the user or a channel, or fetch playlists by id.                         |
+| [`scripts/createPlaylist.ts`](scripts/createPlaylist.ts)                   | `createPlaylist`          | `youtube`   | Create a new playlist on the user's channel.                                                     |
+| [`scripts/updatePlaylist.ts`](scripts/updatePlaylist.ts)                   | `updatePlaylist`          | `youtube`   | Update a playlist's title, description, or privacy (replaces, doesn't merge).                    |
+| [`scripts/deletePlaylist.ts`](scripts/deletePlaylist.ts)                   | `deletePlaylist`          | `youtube`   | Permanently delete a playlist you own.                                                           |
+| [`scripts/listPlaylistItems.ts`](scripts/listPlaylistItems.ts)             | `listPlaylistItems`       | `youtube`   | List the videos in a playlist, in order (each item carries its playlistItem id).                 |
+| [`scripts/addVideoToPlaylist.ts`](scripts/addVideoToPlaylist.ts)           | `addVideoToPlaylist`      | `youtube`   | Add a video to a playlist you own.                                                               |
+| [`scripts/removeVideoFromPlaylist.ts`](scripts/removeVideoFromPlaylist.ts) | `removeVideoFromPlaylist` | `youtube`   | Remove an item from a playlist (by playlistItem id, not video id).                               |
+| [`scripts/listComments.ts`](scripts/listComments.ts)                       | `listComments`            | `youtube`   | List top-level comment threads on a video, each with its first replies.                          |
+| [`scripts/postComment.ts`](scripts/postComment.ts)                         | `postComment`             | `youtube`   | Post a new top-level comment on a video (needs the comment scope).                               |
+| [`scripts/replyToComment.ts`](scripts/replyToComment.ts)                   | `replyToComment`          | `youtube`   | Reply to an existing top-level comment thread (needs the comment scope).                         |
+| [`scripts/getChannel.ts`](scripts/getChannel.ts)                           | `getChannel`              | `youtube`   | Get a channel's profile, statistics, and uploads-playlist id (by mine / id / @handle).           |
+| [`scripts/listVideoCategories.ts`](scripts/listVideoCategories.ts)         | `listVideoCategories`     | `youtube`   | List the assignable video categories for a region.                                               |
+| [`scripts/listSubscriptions.ts`](scripts/listSubscriptions.ts)             | `listSubscriptions`       | `youtube`   | List the user's subscriptions, or check a subscription to one channel.                           |
+| [`scripts/subscribeToChannel.ts`](scripts/subscribeToChannel.ts)           | `subscribeToChannel`      | `youtube`   | Subscribe the user to a channel.                                                                 |
+| [`scripts/unsubscribeFromChannel.ts`](scripts/unsubscribeFromChannel.ts)   | `unsubscribeFromChannel`  | `youtube`   | Unsubscribe the user from a channel (by subscription id, not channel id).                        |
+| [`scripts/listCaptions.ts`](scripts/listCaptions.ts)                       | `listCaptions`            | `youtube`   | List the caption tracks available for a video (needs the comment/caption scope).                 |
+| [`scripts/downloadCaption.ts`](scripts/downloadCaption.ts)                 | `downloadCaption`         | `youtube`   | Download a caption track's text in a chosen format (srt/vtt/sbv/scc/ttml).                       |
+
+**Always learn a script's input contract before calling it — never guess field names, casing, or types.** Run `--help` on either entrypoint — `./scripts/<script>.ts --help` or `npx @zapier/youtube-connector run <script> --help` — which renders `inputSchema` as JSON Schema and lists the connection flag(s) and available resolvers.
+
+## Output format
+
+Every script returns a `{ data, meta }` envelope (same shape across the CLI's JSON output, the imported SDK return value, and the MCP tool's `structuredContent`):
+
+- **`data`** — the script's result (the shape declared by its `outputSchema`).
+- **`meta.outputDataValidation`** — what validating `data` did:
+  - `{ skipped: false, droppedPaths: null }` — validated, nothing removed.
+  - `{ skipped: false, droppedPaths: [...], instruction }` — validated, but those paths (fields the API returned that the `outputSchema` doesn't declare) were stripped from `data`. If you need them, re-run with output validation skipped.
+  - `{ skipped: true }` — validation was bypassed; `data` is the raw, unchecked API output.
+
+**Reading dropped fields / `skipOutputDataValidation`.** To receive the raw, unvalidated result, set the single token `skipOutputDataValidation` — CLI: append `--skipOutputDataValidation`; MCP: pass `meta: { skipOutputDataValidation: true }` as a tool argument; SDK: pass `{ skipOutputDataValidation: true }` in the run options. Input validation is never skipped.
+
+**Trimming the result / `filterOutputData`.** To shrink a large result down to the fields you need, pass a jq expression that post-processes `data` — CLI: append `--filterOutputData '<jq>'`; MCP: pass `meta: { filterOutputData: "<jq>" }` as a tool argument. The jq runs against `data` only, NOT the `{ data, meta }` envelope, so write it rooted at `data` (see this script's output schema). The transformed value replaces `data`, `meta` is preserved, and the result is NOT re-validated against the output schema. The imported SDK has no `filterOutputData` option — reshape the returned `data` in code instead.
+
+## Disambiguation & refusals
+
+**Disambiguation before a write.** Before writing against a video, playlist, or channel you looked up by name (e.g. a video from `searchVideos`, a playlist from `listPlaylists`, a channel from `getChannel`/`searchVideos`), count the **exact case-insensitive title matches**:
+
+- **Exactly one match** — act on it. Don't over-ask; a single unambiguous match is the answer.
+- **Two or more that tie** — stop. List the tied candidates with a distinguishing field (channel title, publish date, view count, or the id) and ask the user which one they mean. Titles are not unique on YouTube — many videos and channels share a name — so never pick arbitrarily and never write to all of them.
+
+**Mind the id traps.** `removeVideoFromPlaylist` takes the **playlistItem** id from `listPlaylistItems`, not the video id. `unsubscribeFromChannel` takes the **subscription** id from `listSubscriptions`, not the channel id. Passing the wrong id is the most common failure; resolve via the listed tool first.
+
+**Unsupported operations — say so and stop; don't fake it with another tool.** This catalog deliberately does not:
+
+- **Report analytics** (views-over-time, watch-time, revenue, demographics). There is no analytics tool. Don't substitute a video's lifetime `statistics` counts and present them as an analytics report.
+- **Moderate comments** (edit, delete, hide, mark as spam, or set moderation status) — only reading, posting, and replying are supported. Replies are single-level: you cannot reply to a reply.
+- **Live-stream** (create or manage broadcasts/streams) or **upload/replace captions** — captions are read-only here (list + download).
+- **Upload videos or set custom thumbnails** — there is no `uploadVideo` or `setVideoThumbnail` tool. These require binary media uploads, which the connection transport does not support.
+- **Administer a channel** (edit channel branding, sections, or settings).
+
+If asked for any of these, tell the user it's unsupported and stop — don't reach for an unrelated tool to approximate it.
+
+## Auth
+
+YouTube uses **Google OAuth 2.0** with a single access token, resolved into the one `youtube` connection slot. Every tool uses the same credential; what a token can do is gated by **OAuth scope** (granted at connect) and by **resource ownership** (you can only modify videos, playlists, and subscriptions you own), not by token type. Pass auth as one connection string with `--connection [<resolver>:]<value>` (CLI / MCP) or `{ connection: "[<resolver>:]<value>" }` (imported). The value is a _selector_, not the secret. Two resolvers — the Zapier-managed one is recommended:
+
+- **`zapier:<connection-id>`** _(recommended)_ — Zapier-managed auth. Route through a Zapier YouTube connection; the Zapier auth, retries, and governance layer injects the token and **handles refresh for you**. **Prerequisite: a Zapier account** (free signup at <https://zapier.com>). Find the ID with the Zapier SDK CLI: `npx @zapier/zapier-sdk-cli list-connections YouTubeV2CLIAPI` (run `login` first if unauthenticated; add `--json` for machine output).
+- **`env:<ENV_VAR>`** — direct mode, for bring-your-own-token or local testing. Read a Google OAuth access token from the named environment variable (conventionally `env:YOUTUBE_ACCESS_TOKEN`, with the token exported in `YOUTUBE_ACCESS_TOKEN`). The token must carry the scopes for the tools you call. Google access tokens expire ~1 hour after issue and are **not** refreshed in direct mode, so this suits short-lived / testing use.
+
+**Scopes.** The connection should be granted the access the tools you use need:
+
+- `youtube.readonly` — all read / list tools (search, videos, playlists, playlist items, channels, categories, subscriptions, comment threads).
+- `youtube` — manage tools: playlist create/update/delete, playlist-item add/remove, subscribe/unsubscribe, video update/delete, **and rateVideo** (rating does _not_ need the comment scope).
+- `youtube.force-ssl` — **required** for all comment writes (`postComment`, `replyToComment`) and for **all caption** operations (`listCaptions`, `downloadCaption`).
+
+A request made with an insufficient scope returns **403**; reconnect YouTube with the broader access. A 403 because you don't **own** the resource is a different problem — reconnecting won't help.
+
+If no connection is passed the script fails with an actionable error telling you to `Pass --connection [<resolver>:]<value>` and lists the resolvers in match order.
+
+## Using this skill
+
+### 0. Pre-flight and auth
+
+Run the bundled pre-flight check **once** at the start of a session to learn how to run the scripts in the current harness, then run scripts directly — reuse the result for the rest of the session. It detects a usable runtime (Node 22.18+ or Bun) and that dependencies are installed; it does **not** probe the network or auth (the scripts own that). Read `PREFLIGHT_STATUS` first — the single verdict token; `PREFLIGHT_RUNNER` names the runtime.
+
+```bash
+./preflight.sh
+```
+
+Exit `0` **READY**: follow `PREFLIGHT_RECOMMENDATION` — it gives the exact `--help` command to run next. The `--help` output renders `inputSchema` as JSON Schema, lists the connection flag(s) the script reads and every resolver each accepts, and tells you exactly what to provide. Use the runner from `PREFLIGHT_RUNNER` against the local script path — never `npx` (a sandbox that blocked the dep install may also block registry fetches). If a script call later fails with a network error, egress is blocked — recommend the user set up Zapier's remote MCP at `https://mcp.zapier.com`.
+
+Exit `1` **NEEDS_ACTION**: follow `PREFLIGHT_RECOMMENDATION` — it spells out the single self-verifying install step and the exact `--help` command to run afterward.
+
+The three invocation paths below all assume the pre-flight reported `READY`.
+
+### 1. Execute scripts directly
+
+When the agent has shell access to the installed directory, run a script file straight from `scripts/`. Each script is `chmod +x` with a Node-targeted shebang. **Run `--help` first** to read the input contract and confirm an auth resolver is ready — `--help` is the one path for both "learn the input contract" and "check auth":
+
+```bash
+# Inspect the contract + resolvers first
+./scripts/getVideo.ts --help
+
+# Then invoke (direct token — token stays in env)
+YOUTUBE_ACCESS_TOKEN=ya29.xxx ./scripts/getVideo.ts '{"id":"dQw4w9WgXcQ"}' --connection env:YOUTUBE_ACCESS_TOKEN
+
+# Or route through a Zapier connection
+./scripts/searchVideos.ts '{"q":"lo-fi beats"}' --connection zapier:conn_xxx
+```
+
+Prerequisites: Node.js 22.18+ (or Bun 1.x) on `PATH`, plus `npm install` once in this directory. Pin the runtime explicitly with `node scripts/<name>.ts …` or `bun scripts/<name>.ts …` when needed — all forms run the same script body.
+
+### 2. Use the package's CLI
+
+```bash
+YOUTUBE_ACCESS_TOKEN=ya29.xxx npx @zapier/youtube-connector run getVideo '{"id":"dQw4w9WgXcQ"}' --connection env:YOUTUBE_ACCESS_TOKEN
+npx @zapier/youtube-connector --help                  # all scripts
+npx @zapier/youtube-connector run getVideo --help     # per-script schema + resolvers
+```
+
+Same scripts, different entry point. Use `bunx` when `PREFLIGHT_RUNNER` is `bun`. Some harnesses block `npx`/`bunx` — fall back to (1).
+
+### 3. Use as a recipe
+
+When no shipped script matches, read this `SKILL.md`, the [`references/`](references/) files, and the `scripts/` files as a recipe to generate custom code. Each script is one `export default defineTool({...})` from `@zapier/connectors-sdk` referencing the connection key `"youtube"`; imitate that shape (Zod input/output schemas, `(input, ctx) => …` run body, the direct-mode auth being a Bearer token in the `Authorization` header). If you persist generated code, add a comment pointing back to this skill's source:
+
+```ts
+// Source: https://github.com/zapier/connectors/blob/main/apps/youtube/SKILL.md
+```
+
+## API quirks worth knowing
+
+| Reference                                                                | Load when                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`references/youtube-api-gotchas.md`](references/youtube-api-gotchas.md) | Before relying on counts, quotas, scopes, pagination, IDs, or any non-obvious response field — covers the `part` model, the per-bucket quota system, the error envelope and `reason`→recovery mapping, OAuth scope requirements (`youtube`, `youtube.force-ssl`), counts-as-strings, and per-resource quirks for videos, search, playlists, comments, captions, channels, and subscriptions. |

package/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Connector CLI entry point.
+ *
+ * When dist/cli.js is present (npm install route, or after a local build):
+ *   → delegates to the compiled CLI, works on any Node version.
+ *
+ * When dist/ is absent (git-clone route, no build step):
+ *   → handles the `build` subcommand directly (any Node version, no TS needed),
+ *     then falls through to cli.ts for all other subcommands (requires Node 22.18+
+ *     or Bun for TypeScript stripping outside node_modules).
+ *
+ * `build` subcommand: compiles the connector so that
+ *   `import { search } from "@zapier/notion-connector"` works on any Node version
+ *   even when the connector was installed from a git/file source. Invoked
+ *   automatically by the `prepare` lifecycle hook on git-clone installs.
+ *   Tries `npx tsup`, falls back to `bunx tsup`, exits 0 regardless so that
+ *   `npm install` / `pnpm install` never fails in restricted environments.
+ *
+ * Managed by @zapier/connectors-dev — do not edit; synced byte-for-byte
+ * across every connector.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const dir = dirname(fileURLToPath(import.meta.url));
+
+if (process.argv[2] === "build") {
+  if (!existsSync(join(dir, "dist", "cli.js"))) {
+    // Try the locally-installed tsup binary first so module resolution for
+    // typescript (a required tsup peer) works from the connector's own
+    // node_modules. Fall back to npx/bunx for environments without a local
+    // install (e.g. fresh git-clone before npm install).
+    const localTsup = join(dir, "node_modules", ".bin", "tsup");
+    const candidates = existsSync(localTsup)
+      ? [
+          [process.execPath, [localTsup]],
+          ["npx", ["tsup"]],
+          ["bunx", ["tsup"]],
+        ]
+      : [
+          ["npx", ["tsup"]],
+          ["bunx", ["tsup"]],
+        ];
+    for (const [cmd, args] of candidates) {
+      const { status } = spawnSync(cmd, args, {
+        stdio: "inherit",
+        shell: true,
+        cwd: dir,
+      });
+      if (status === 0) break;
+    }
+  }
+  process.exit(0);
+}
+
+// Spawn the target as a subprocess so it runs as the entry point.
+// Dynamic import() would set import.meta.main = false, causing
+// runDispatchCli to return early without executing anything.
+const target = existsSync(join(dir, "dist", "cli.js"))
+  ? join(dir, "dist", "cli.js")
+  : join(dir, "cli.ts");
+
+const { status } = spawnSync(
+  process.execPath,
+  [target, ...process.argv.slice(2)],
+  { stdio: "inherit" },
+);
+process.exit(status ?? 1);

package/cli.ts

@@ -0,0 +1,5 @@
+import { runDispatchCli } from "@zapier/connectors-sdk";
+
+import connector from "./index.ts";
+
+await runDispatchCli(import.meta, connector);

package/connections.ts

@@ -0,0 +1,8 @@
+import {
+  defineEnvTokenResolver,
+  zapierConnectionResolver,
+} from "@zapier/connectors-sdk";
+
+export const connectionResolvers = {
+  youtube: [zapierConnectionResolver, defineEnvTokenResolver()],
+} as const;

package/dist/cli.js

@@ -0,0 +1,4 @@
+// cli.ts
+import { runDispatchCli } from "@zapier/connectors-sdk";
+import connector from "./index.js";
+await runDispatchCli(import.meta, connector);