@zapier/connectors-sdk 0.1.0-experimental.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/README.internal.md

@@ -0,0 +1,397 @@
+# @zapier/connectors-sdk
+
+The workspace package every connector script imports from at the top of its module.
+
+### Package entry (`index.ts`)
+
+```ts
+import {
+  defineConnector,
+  defineConnectionResolver,
+  defineBearerTokenResolver,
+  defineTool,
+  handleIfScriptMain,
+  runDispatchCli,
+  toFunctions,
+  zapierConnectionResolver,
+  type AnyToolDefinition,
+  type ConnectorDefinition,
+  type RunOptions,
+} from "@zapier/connectors-sdk";
+```
+
+| Export                                                  | Lives in                                    | Purpose                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`defineTool(config)`**                                | `./define-tool.ts`                          | Authoring helper. Returns a `ToolDefinition` (none / single / multi connection). The author's `run` is `(input, ctx)` for connection-bearing scripts; `(input)` for credential-free ones.                                                                                                                                             |
+| **`defineConnector({ scripts, connectionResolvers })`** | `./define-connector.ts`                     | Connector `index.ts` helper. Wraps each script's `run` so consumers call `script.run(input, opts: RunOptions)`; the connector's resolvers translate `RunOptions` into the per-slot authed `fetch` the author's `run` receives via `ctx`.                                                                                              |
+| **`defineConnectionResolver(resolver)`**                | `./connection-resolvers.ts`                 | Typed-identity helper for hand-rolled resolvers; preserves the literal `name` and `keySuffixes` so `RunOptions.connection` narrows on the consumer side.                                                                                                                                                                              |
+| **`zapierConnectionResolver`**                          | `./connection-resolvers.ts`                 | SDK-shipped resolver (`name: "zapier-connection-id"`). Operators set `<KEY>_ZAPIER_CONNECTION_ID`; the resolver routes through Zapier Relay (lazy `import("@zapier/zapier-sdk")`).                                                                                                                                                    |
+| **`defineBearerTokenResolver(opts?)`**                  | `./connection-resolvers.ts`                 | SDK-shipped resolver factory (default `name: "token"`, `scheme: "Bearer"`). Composes to `<KEY>_TOKEN` — matching the dominant ecosystem convention (`NOTION_TOKEN`, `GITHUB_TOKEN`).                                                                                                                                                  |
+| **`toFunctions(connector)`**                            | `./surfaces/to-functions.ts`                | Maps each script in a connector to its wrapped `.run` for package named exports.                                                                                                                                                                                                                                                      |
+| **`handleIfScriptMain(meta, definition, opts?)`**       | `./surfaces/handle-if-script-main.ts`       | Per-script execution surface. When `import.meta.main`, parses argv/stdin, builds `RunOptions` from env via the supplied resolvers, calls the wrapped run.                                                                                                                                                                             |
+| **`runDispatchCli(meta, connector)`**                   | `./surfaces/run-dispatch-cli.ts`            | Bundled-CLI surface. Routes `<bin> run <script> [args...]` to per-script CLI orchestration; `<bin> mcp` boots a local MCP stdio server exposing every script.                                                                                                                                                                         |
+| **Types**                                               | `./tool-types.ts` / `./define-connector.ts` | `AnyToolDefinition`, `ConnectorDefinition`, `RunOptions`. Narrower types (`SingleConnectionResolver<TName>`, `MultiConnectionResolver<TName, TSuffixes>`, `Context*`, `RunOptions*`, …) are inferred via `defineTool` / `defineConnectionResolver` and aren't part of the public surface — polymorphic walks use `AnyToolDefinition`. |
+
+### On the connector object (`defineConnector` return value)
+
+| Member                                    | Lives in                                | Purpose                                                                                                                                                                                                                   |
+| ----------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`connector.scripts`**                   | —                                       | Wrapped scripts: each `script.run(input, opts: RunOptions)` translates the caller-provided `ConnectionValue` into an authed `fetch` per slot via the connector's resolvers.                                               |
+| **`connector.connectionResolvers`**       | —                                       | The resolver map this connector was constructed with. X-app connectors will import resolver values from app connectors and re-register them under different connection keys.                                              |
+| **`toMcpTool(script)`**                   | `./surfaces/to-mcp-tool.ts`             | Wire-format MCP `Tool` descriptor (JSON Schema'd `inputSchema`). For deprecated `Server` + `setRequestHandler` flows.                                                                                                     |
+| **`toMcpServerTool(script)`**             | `./surfaces/to-mcp-server-tool.ts`      | `McpServer.registerTool(name, config, cb)` config object (Zod schemas pass-through). For the modern API.                                                                                                                  |
+| **`toChatCompletionTool(script)`**        | `./surfaces/to-chat-completion-tool.ts` | Chat Completions registration shape.                                                                                                                                                                                      |
+| **`toResponsesTool(script)`**             | `./surfaces/to-responses-tool.ts`       | Responses API registration shape.                                                                                                                                                                                         |
+| **`buildRunOptionsFromEnv(script, env)`** | `./normalize-connections.ts`            | Bound to the connector's resolvers. Build `RunOptions` for a wrapped script from a process-env bag — useful for long-running consumers that resolve credentials once and reuse the same opts for the life of the process. |
+
+### Surfaces
+
+A **surface** is how a `ToolDefinition` is exposed to a consumer. **Registration surfaces** publish tool metadata; **execution surfaces** run a tool.
+
+| Surface                       | Kind         | Helper                         | Surface shape / behavior                                                                     |
+| ----------------------------- | ------------ | ------------------------------ | -------------------------------------------------------------------------------------------- |
+| MCP `tools/list` (descriptor) | registration | `toMcpTool`                    | Wire-format `Tool` (JSON Schema'd `inputSchema`, optional `_meta`)                           |
+| MCP `McpServer.registerTool`  | registration | `toMcpServerTool`              | `registerTool` config (Zod schemas pass-through, optional `_meta`)                           |
+| OpenAI Chat Completions       | registration | `toChatCompletionTool`         | `{ type: "function", function: { name, description, parameters } }`                          |
+| OpenAI Responses              | registration | `toResponsesTool`              | `{ type: "function", name, description, parameters }`                                        |
+| Per-script CLI                | execution    | `handleIfScriptMain`           | argv/stdin JSON in → wrapped `script.run` → JSON stdout                                      |
+| Connector bin                 | execution    | `runDispatchCli`               | `<bin> run <script> [args…]` → per-script CLI; `<bin> mcp` → local MCP server                |
+| Local MCP server              | execution    | `runDispatchCli` (`<bin> mcp`) | Stdio MCP server registering every script as a native MCP tool (`tools/list` + `tools/call`) |
+| In-process run                | execution    | `script.run` / named export    | Typed input + `RunOptions` → output                                                          |
+
+## Authoring a script — `defineTool`
+
+A script declares **whether it needs credentials** through a single string knob:
+
+| Author writes                                         | Means                                                                                                             |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `connection: "notion"`                                | One slot bound to connection key `notion`. The author's `run(input, ctx)` receives `ctx.fetch`.                   |
+| `connections: { source: "notion", target: "notion" }` | Multiple slots, each bound to a connection key. The author's `run(input, ctx)` receives `ctx.connections.<slot>`. |
+| (no `connection` / `connections` field)               | Credential-free. The author's `run(input)` takes only the parsed input.                                           |
+
+The connection key is a string identifier — connectors register a resolver (or array of resolvers) for each key on the `connectionResolvers` map at `defineConnector` time. Authors don't see env-var names, programmatic-bag keys, slot prefixes, or Relay app slugs in their script body — the wrapper composes those from the resolver's `name` (and `keySuffixes` for multi-credential resolvers).
+
+### Authoring example — single connection
+
+```ts
+import { z } from "zod";
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+
+import { connectionResolvers } from "../connections.ts";
+
+const definition = defineTool({
+  name: "search",
+  title: "Search Notion",
+  description: "Search Notion pages and databases by query string.",
+  inputSchema: z.object({ query: z.string() }),
+  outputSchema: z.object({ results: z.array(z.unknown()) }),
+  annotations: { readOnlyHint: true },
+  connection: "notion",
+  run: async (input, ctx) => {
+    const res = await ctx.fetch("https://api.notion.com/v1/search", {
+      method: "POST",
+      headers: {
+        "Notion-Version": "2022-06-28",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(input),
+    });
+    if (!res.ok)
+      throw new Error(`Notion search ${res.status}: ${await res.text()}`);
+    return res.json() as Promise<{ results: unknown[] }>;
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });
+```
+
+### Authoring example — multi-connection
+
+A script that copies a page from one Notion workspace to another declares two slots (`source` + `target`) — same script body, two independently authed fetches. Both slots share the connection key `notion`; the wrapper distinguishes them by env-var prefix at run-time.
+
+```ts
+const definition = defineTool({
+  name: "copy_page",
+  description: "Copy a Notion page between two workspaces.",
+  inputSchema: z.object({
+    sourcePageId: z.string(),
+    targetParentPageId: z.string(),
+  }),
+  outputSchema: z.object({ id: z.string(), url: z.string() }),
+  connections: { source: "notion", target: "notion" },
+  run: async (input, ctx) => {
+    const page = await (
+      await ctx.connections.source(
+        `https://api.notion.com/v1/pages/${input.sourcePageId}`,
+      )
+    ).json();
+    const created = await (
+      await ctx.connections.target("https://api.notion.com/v1/pages", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          parent: { page_id: input.targetParentPageId },
+          properties: (page as { properties: unknown }).properties,
+        }),
+      })
+    ).json();
+    return created as { id: string; url: string };
+  },
+});
+```
+
+## Resolvers — bridging credentials and `fetch`
+
+A **connection resolver** is a small data object the connector exports for one connection key. It declares:
+
+- a `name` (e.g. `"token"`, `"zapier-connection-id"`, `"hmac"`),
+- optional `keySuffixes` (for multi-credential shapes like HMAC `KEY` / `SECRET`),
+- a `resolve(credential)` function that returns an authed `fetch`.
+
+Resolvers don't know about env vars, slot names, or connection keys — the wrapper composes those at the boundary.
+
+Every connector follows the same uniform shape: `connections.ts` exports a single keyed map named **`connectionResolvers`** (one entry per connection key the connector serves); `index.ts` and each script consume it as-is. No wrapping or re-keying is needed — the connector's connection keys are baked into the map.
+
+```ts
+// apps/notion/connections.ts
+import {
+  defineBearerTokenResolver,
+  zapierConnectionResolver,
+} from "@zapier/connectors-sdk";
+
+export const connectionResolvers = {
+  notion: [zapierConnectionResolver, defineBearerTokenResolver()],
+} as const;
+```
+
+```ts
+// apps/notion/index.ts
+import { defineConnector, toFunctions } from "@zapier/connectors-sdk";
+
+import { connectionResolvers } from "./connections.ts";
+import searchDefinition from "./scripts/search.ts";
+// ...
+
+const connector = defineConnector({
+  scripts: { search: searchDefinition /* ... */ },
+  connectionResolvers,
+});
+
+export default connector;
+export const { search /* ... */ } = toFunctions(connector);
+```
+
+Multi-slot scripts (e.g. `connections: { source: "notion", target: "notion" }`) share a single `notion` entry — the wrapper routes each slot via its env-var prefix (`SOURCE_NOTION_*` vs `TARGET_NOTION_*`).
+
+A downstream cross-app connector reaches the resolver list through `connector.connectionResolvers.<connectionKey>` and can re-register it under a different key:
+
+```ts
+import notion from "@zapier/notion-connector";
+
+const notionResolvers = notion.connectionResolvers.notion;
+
+defineConnector({
+  scripts: {
+    /* ... */
+  },
+  connectionResolvers: {
+    "notion-prod": notionResolvers,
+    "notion-staging": notionResolvers,
+  },
+});
+```
+
+The order of resolvers in the array is also the **dispatch order**: at runtime, the wrapper picks the **first** resolver whose required env vars (or programmatic-bag keys) are all set. So putting `zapierConnectionResolver` before the bearer-token resolver means a connection ID wins when both are configured — useful for migration paths.
+
+### SDK-shipped resolvers
+
+| Helper                            | Shape                                                                                                           | Composition (single-slot, key `notion`)                                                                                  |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| **`zapierConnectionResolver`**    | Single-credential value (no parameters). `name: "zapier-connection-id"`.                                        | env: `NOTION_ZAPIER_CONNECTION_ID` · programmatic: `{ ZAPIER_CONNECTION_ID: string }`                                    |
+| **`defineBearerTokenResolver()`** | Single-credential factory. Default `name: "token"`, `scheme: "Bearer"`. Override either via `{ name, scheme }`. | env: `NOTION_TOKEN` · programmatic: `{ TOKEN: string }`. Override `name: "bearer-token"` for `<KEY>_BEARER_TOKEN` style. |
+
+### Hand-rolled resolvers — `defineConnectionResolver`
+
+Use the typed-identity helper to preserve the literal `name` (and `keySuffixes`) so consumer-side type narrowing on `RunOptions.connection` works:
+
+```ts
+// Single-credential.
+export const apiKeyResolver = defineConnectionResolver({
+  name: "api-key",
+  resolve:
+    (key) =>
+    (input, init = {}) =>
+      globalThis.fetch(input, {
+        ...init,
+        headers: { ...(init.headers ?? {}), "X-API-Key": key },
+      }),
+});
+
+// Multi-credential — `keySuffixes` declares which credentials the resolver needs.
+// `resolve` receives a suffix-keyed bag (NOT name-prefixed); the wrapper strips
+// the `<NAME>_` prefix for you.
+export const hmacResolver = defineConnectionResolver({
+  name: "hmac",
+  keySuffixes: ["KEY", "SECRET"] as const,
+  resolve: ({ KEY, SECRET }) =>
+    /* ... build authed fetch ... */ globalThis.fetch,
+});
+```
+
+## Env-only credentials
+
+**The CLI never accepts secrets via argv.** Per-script (`handleIfScriptMain`) and connector-bin (`runDispatchCli`) entries take only the input JSON (positional arg or stdin) plus `--help`. Credentials come from environment variables.
+
+### Env-var composition rules
+
+The wrapper composes env-var names from `[<SLOT>_]<CONNECTION_KEY>_<RESOLVER_NAME>[_<SUFFIX>]`:
+
+| Slot prefix            | Connection key | Resolver name          | Suffix           | Composed env var                             |
+| ---------------------- | -------------- | ---------------------- | ---------------- | -------------------------------------------- |
+| (none — single-slot)   | `notion`       | `zapier-connection-id` | (none)           | `NOTION_ZAPIER_CONNECTION_ID`                |
+| (none — single-slot)   | `notion`       | `token`                | (none)           | `NOTION_TOKEN`                               |
+| `SOURCE_` (multi-slot) | `notion`       | `token`                | (none)           | `SOURCE_NOTION_TOKEN`                        |
+| `TARGET_` (multi-slot) | `notion`       | `zapier-connection-id` | (none)           | `TARGET_NOTION_ZAPIER_CONNECTION_ID`         |
+| (none — single-slot)   | `some-api`     | `hmac`                 | `KEY` / `SECRET` | `SOME_API_HMAC_KEY` + `SOME_API_HMAC_SECRET` |
+
+Run a per-script CLI with `--help` to print the exact env vars each registered resolver demands for that script.
+
+### CLI examples
+
+```bash
+# Single-conn — natural ecosystem-shape envs:
+echo '{"query":"Q4 planning"}' \
+  | NOTION_TOKEN=secret_xxx node apps/notion/scripts/search.ts
+
+# Single-conn — Zapier-relayed (the first resolver in `[zapier, bearer]` wins
+# because `NOTION_ZAPIER_CONNECTION_ID` is the env var that turned up):
+NOTION_ZAPIER_CONNECTION_ID=conn_xxx node apps/notion/scripts/search.ts \
+  '{"query":"Q4 planning"}'
+
+# Multi-conn — per-slot env prefixes route each credential to the right slot:
+SOURCE_NOTION_TOKEN=src_xxx \
+TARGET_NOTION_TOKEN=tgt_xxx \
+node apps/notion/scripts/copy-page.ts \
+  '{"sourcePageId":"...","targetParentPageId":"..."}'
+
+# Per-script help — lists positional input shape + every resolver's env vars:
+node apps/notion/scripts/search.ts --help
+
+# Connector bin help — lists scripts; `<bin> <script> --help` for per-script env:
+npx @zapier/notion-connector --help
+npx @zapier/notion-connector search --help
+```
+
+## In-process consumption — `script.run(input, opts)`
+
+`ToolDefinition` carries the wrapped `.run`; consumers always pass an explicit `RunOptions`.
+
+```ts
+import notion, { search } from "@zapier/notion-connector";
+
+// Bundle path:
+await notion.scripts.search.run(
+  { query: "Q4 planning" },
+  { connection: { TOKEN: "secret_xxx" } },
+);
+
+// Named export (each export is the wrapped `.run`):
+await search({ query: "Q4 planning" }, { connection: { TOKEN: "secret_xxx" } });
+
+// Long-running consumers — build opts once, pass on every call:
+const runOpts = notion.buildRunOptionsFromEnv(
+  notion.scripts.search,
+  process.env,
+);
+await notion.scripts.search.run({ query: "a" }, runOpts);
+```
+
+### `RunOptions.connection` shapes
+
+A slot's `connection` (or per-slot entry under `connections`) accepts one of three shapes:
+
+| Shape                        | Resolution                                                                                                                                                                            |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`function`** (a `Fetch`)   | Used as-is — no resolver consulted. Mocked-Fetch test paths use this.                                                                                                                 |
+| **`string`** (shorthand)     | Forwarded to the **first** `SingleConnectionResolver` in the slot's array. Throws when there isn't one (e.g. all resolvers in the array are multi-credential).                        |
+| **`Record<string, string>`** | The keys are name-prefixed (`<NAME>` for single-credential, `<NAME>_<SUFFIX>` for multi). The wrapper picks the resolver whose `bagKeysFor` set matches `Object.keys(value)` exactly. |
+
+The record bag is the canonical programmatic shape. `string` shorthand is a convenience when the slot has exactly one viable resolver and you don't want to spell its name out. Errors include the script name, slot label, and the available resolvers' shapes so multi-conn misconfig points the operator at the right credential.
+
+### `RunOptions.connection` type narrowing
+
+The wrapped `.run` narrows `RunOptions.connection` against the resolver entry registered for the slot's connection key. For Notion (`[zapierConnectionResolver, defineBearerTokenResolver()]`):
+
+```ts
+// All four are statically valid for `connection: "notion"`:
+await notion.scripts.search.run(input, { connection: globalThis.fetch }); // (1) Fetch
+await notion.scripts.search.run(input, { connection: "conn_xxx" }); // (2) string → first single-cred (zapier)
+await notion.scripts.search.run(input, {
+  connection: { ZAPIER_CONNECTION_ID: "conn_xxx" },
+}); // (3) zapier-prefixed bag
+await notion.scripts.search.run(input, { connection: { TOKEN: "secret_xxx" } }); // (3) bearer-prefixed bag
+```
+
+A multi-credential resolver `{ name: "hmac", keySuffixes: ["KEY", "SECRET"] }` would contribute the bag shape `{ HMAC_KEY: string; HMAC_SECRET: string }` — the resolver's `name` always heads each bag key.
+
+## `Context` — the author surface
+
+| Slot cardinality               | Author writes          | `ctx` shape                                                       |
+| ------------------------------ | ---------------------- | ----------------------------------------------------------------- |
+| Credential-free                | `run: (input) =>`      | (no `ctx`)                                                        |
+| Single (`connection: ...`)     | `run: (input, ctx) =>` | `ctx.fetch` — the resolved authed `fetch` for the slot.           |
+| Multi (`connections: { ... }`) | `run: (input, ctx) =>` | `ctx.connections.<slot>` per declared slot. No `ctx.fetch` sugar. |
+
+The author never sees `process.env`, never threads a `Fetch` through their script body, never re-implements auth logic.
+
+## `inputDependencies` — out-of-band dependent-field metadata
+
+Some scripts have input fields whose accepted shape depends on another input field — e.g. Notion's `create_database_item` takes a `databaseId` and a `properties` map whose schema is determined by which database was chosen. JSON Schema can't express that conditional shape, but adapters that drive option-loading or schema-resolution chains need to know about it.
+
+`defineTool` publishes the metadata in two places:
+
+1. `definition.inputDependencies` — programmatic readers reach for it directly on the script's default export.
+2. MCP registration shape — `_meta["zapier:inputDependencies"]` via either `toMcpTool` (wire-format) or `toMcpServerTool` (`McpServer.registerTool` config).
+
+Shape constraints:
+
+- Dependencies are keyed by the dependent input field's name (`databaseId`, `properties`).
+- Each entry names another tool by **string** (`fromTool: "list-databases"`), not by function reference — so the chain stays serializable.
+- Args passed to the resolver tool use `$<fieldName>` syntax to reference other input fields (`fromArgs: { databaseId: "$databaseId" }`). The adapter reads and evaluates these references; the script body does not.
+
+```ts
+inputDependencies: {
+  databaseId: { kind: "options", fromTool: "list-databases", fromArgs: {} },
+  properties: {
+    kind: "schema",
+    fromTool: "get-database-schema",
+    fromArgs: { databaseId: "$databaseId" },
+  },
+} as const,
+```
+
+## `<bin> mcp` — local-MCP-server execution surface
+
+Reached through the bundled CLI as `npx @zapier/<x>-connector mcp` — no per-app glue. The dispatcher reserves the primary command `mcp` and delegates to the internal `serveMcpStdio` helper:
+
+1. Builds an in-memory registry keyed by `script.name`, with each entry holding the script and `RunOptions` resolved once via `buildRunOptionsFromEnv` against the connector's resolvers.
+2. Resolves server identity (`name` / `version`) from the `package.json` adjacent to the connector's `cli.ts` (via `meta.url`).
+3. For each script, calls `server.registerTool(script.name, toMcpServerTool(script), cb)` — `McpServer` handles `tools/list` and runs the Zod input parse before dispatching to `script.run(input, runOpts)`. The callback returns the result as both `structuredContent` and a JSON-stringified text part.
+4. Connects via `StdioServerTransport` and writes a one-line ready banner to stderr.
+
+```bash
+NOTION_TOKEN=secret_xxx npx @zapier/notion-connector mcp
+```
+
+For consumers who want to register connector scripts inside their **own** MCP server, there are two lower-level helpers depending on the SDK API used:
+
+- Modern `McpServer.registerTool`: `toMcpServerTool(script)` + `connector.buildRunOptionsFromEnv` — see [`examples/mcp-server-tool/`](../../examples/mcp-server-tool/).
+- Deprecated `Server.setRequestHandler`: `toMcpTool(script)` + `connector.buildRunOptionsFromEnv` — see [`examples/mcp-tool/`](../../examples/mcp-tool/).
+
+## Why is the package surface this small?
+
+`defineTool` + `defineConnector` + `handleIfScriptMain` + `runDispatchCli` + `toFunctions` is the authoring + execution contract every script and connector entry imports. SDK-shipped resolvers (`zapierConnectionResolver`, `defineBearerTokenResolver`) and the typed-identity `defineConnectionResolver` cover the most common auth paths; everything else flows through the same `ConnectionResolver` shape. Registration surface helpers and env partitioning live on the connector object, not the package entry, so MCP/OpenAI/CLI consumers depend on the connector bundle — not duplicate SDK exports.
+
+The Zapier-Relay path (`zapierConnectionResolver`) lazy-imports `@zapier/zapier-sdk` only when it actually wins resolution — connectors that don't expose Zapier auth don't pull the SDK into their dependency closure.

package/README.md

@@ -0,0 +1,6 @@
+# @zapier/connectors-sdk
+
+> [!WARNING]
+> **EXPERIMENTAL** — APIs may change between minor versions without a major bump.
+> Not recommended for production outside Zapier-internal projects.
+> Licensed under the [Elastic License 2.0](./LICENSE).

package/dist/build-zapier-fetch-DWCYBAF4.js

@@ -0,0 +1,52 @@
+// src/build-zapier-fetch.ts
+async function buildZapierFetch(connectionId) {
+  if (!connectionId) {
+    throw new Error(
+      "buildZapierFetch: connectionId is required (the Zapier connection UUID)."
+    );
+  }
+  let sdkModule;
+  try {
+    sdkModule = await import("@zapier/zapier-sdk");
+  } catch (err) {
+    throw new Error(
+      "buildZapierFetch: `@zapier/zapier-sdk` is not installed. Zapier mode requires the SDK as a peer dependency \u2014 list it alongside `@zapier/connectors-sdk` in the connector's `package.json`, and run `zapier-sdk login` (or set `ZAPIER_TOKEN`) on the host before invoking the script.",
+      { cause: err }
+    );
+  }
+  const sdk = sdkModule.createZapierSdk();
+  return (async (input, init = {}) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    const method = init.method ?? "GET";
+    const headers = normaliseHeaders(init.headers);
+    const body = init.body;
+    if (body != null && typeof body !== "string") {
+      throw new Error(
+        "buildZapierFetch: Zapier-mode `fetch` only accepts `body: string | undefined`. Serialize the body (e.g. `JSON.stringify(...)`) before calling. Streaming bodies, `FormData`, `Blob`, and `ArrayBuffer` are not supported in Zapier mode."
+      );
+    }
+    const response = await sdk.fetch(url, {
+      method,
+      authenticationId: connectionId,
+      headers,
+      body: body ?? void 0
+    });
+    return response;
+  });
+}
+function normaliseHeaders(h) {
+  if (!h) return void 0;
+  if (h instanceof Headers) return Object.fromEntries(h.entries());
+  if (Array.isArray(h)) {
+    return Object.fromEntries(h.map(([k, v]) => [k, flattenValue(v)]));
+  }
+  return Object.fromEntries(
+    Object.entries(h).map(([k, v]) => [k, flattenValue(v)])
+  );
+}
+function flattenValue(v) {
+  return Array.isArray(v) ? v.join(", ") : v;
+}
+export {
+  buildZapierFetch
+};