@zapier/connectors-sdk 0.1.0-experimental.1

package/dist/index.d.ts

@@ -0,0 +1,575 @@
+import * as _modelcontextprotocol_sdk_types_js from '@modelcontextprotocol/sdk/types.js';
+import { ToolAnnotations, Tool } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+
+/**
+ * `connection-key.ts` — runtime + type pair that names this codebase's
+ * single transform between identifier strings (kebab/lowercase) and the
+ * `SCREAMING_SNAKE_CASE` segments used to compose env-var names and
+ * programmatic-bag keys.
+ *
+ * Internal only. Not re-exported from the public SDK index — resolver
+ * authors don't compose env vars themselves; the wrappers do.
+ */
+/**
+ * Recursive template-literal helper. Replaces every occurrence of `From`
+ * with `To` in `S`. Used only by `EnvFromKey`; not generally useful on
+ * its own (no built-in TS string-replace primitive).
+ */
+type Replace<S extends string, From extends string, To extends string> = S extends `${infer Head}${From}${infer Tail}` ? Replace<`${Head}${To}${Tail}`, From, To> : S;
+/**
+ * Type-level mirror of the `envFromKey` runtime function. Used by
+ * `define-connector.ts` to compose programmatic-bag key types from each
+ * resolver's literal `name` (and suffixes).
+ *
+ * Examples:
+ *   EnvFromKey<"notion">              -> "NOTION"
+ *   EnvFromKey<"google-drive">        -> "GOOGLE_DRIVE"
+ *   EnvFromKey<"zapier-connection-id"> -> "ZAPIER_CONNECTION_ID"
+ *   EnvFromKey<"token">               -> "TOKEN"
+ */
+type EnvFromKey<K extends string> = Uppercase<Replace<K, "-", "_">>;
+
+/**
+ * A Zapier policy statement. Carried on the `ToolDefinition` for in-process
+ * governance consumers (policy engines that wrap `script.run` before HTTP).
+ * Not propagated to MCP `_meta` — only `inputDependencies` is published over
+ * the wire (`_meta["zapier:inputDependencies"]`) by `toMcpTool` /
+ * `toMcpServerTool`.
+ */
+interface Statement {
+    effect: "allow" | "ask" | "deny";
+    permissions: ReadonlyArray<string>;
+    resources: ReadonlyArray<string>;
+    conditions?: ReadonlyArray<{
+        path: ReadonlyArray<string>;
+        operator: string;
+        value: unknown;
+    }>;
+    label?: string;
+}
+/**
+ * Single-credential resolver: the resolver's `name` IS the credential
+ * descriptor. `resolve` receives the credential as a plain `string` —
+ * matching the `string` shorthand arm of `ConnectionValue`. Resolvers do
+ * NOT see env-var names or programmatic-bag keys; the wrapper does the
+ * key composition.
+ *
+ * Composition (single-slot, connection key "notion"):
+ *
+ *   { name: "token", resolve: (token) => ... }
+ *     -> env var:           NOTION_TOKEN
+ *     -> programmatic key:  TOKEN
+ *
+ *   { name: "zapier-connection-id", resolve: (id) => ... }
+ *     -> env var:           NOTION_ZAPIER_CONNECTION_ID
+ *     -> programmatic key:  ZAPIER_CONNECTION_ID
+ */
+interface SingleConnectionResolver<TName extends string = string> {
+    readonly name: TName;
+    readonly keySuffixes?: undefined;
+    resolve: (credential: string) => typeof globalThis.fetch | Promise<typeof globalThis.fetch>;
+}
+/**
+ * Multi-credential resolver: requires N>1 distinct credentials. `resolve`
+ * receives a suffix-keyed bag (NOT name-prefixed) — the wrapper strips the
+ * `<NAME>_` prefix before calling.
+ *
+ * Composition (single-slot, connection key "some-api"):
+ *
+ *   { name: "hmac", keySuffixes: ["KEY", "SECRET"] as const,
+ *     resolve: ({ KEY, SECRET }) => ... }
+ *     -> env vars:         SOME_API_HMAC_KEY, SOME_API_HMAC_SECRET
+ *     -> programmatic bag: { HMAC_KEY: string; HMAC_SECRET: string }
+ *     -> resolve receives: { KEY: string;     SECRET: string }
+ */
+interface MultiConnectionResolver<TName extends string = string, TSuffixes extends readonly string[] = readonly string[]> {
+    readonly name: TName;
+    readonly keySuffixes: TSuffixes;
+    resolve: (credentials: Record<TSuffixes[number], string>) => typeof globalThis.fetch | Promise<typeof globalThis.fetch>;
+}
+/** Either resolver shape. */
+type ConnectionResolver = SingleConnectionResolver | MultiConnectionResolver;
+/**
+ * Per-key resolver entry: a single resolver, or an ordered list. The
+ * wrapper walks the list in order — first resolver whose required env
+ * vars are all set wins (or, for programmatic input, the resolver whose
+ * bag-key set matches `Object.keys(value)` exactly).
+ */
+type ConnectionResolverEntry = ConnectionResolver | readonly ConnectionResolver[];
+/**
+ * Map from connection-key string -> resolver entry. The keys must cover
+ * every connection key referenced by every script's `connection` /
+ * `connections` declaration.
+ */
+type ConnectionResolversMap = Readonly<Record<string, ConnectionResolverEntry>>;
+/**
+ * The four input shapes a slot's caller-provided handle accepts.
+ *
+ *   1. function          → pre-authed `fetch`, used as-is.
+ *   2. string            → shorthand; forwarded to the FIRST single-
+ *                          credential resolver in the array.
+ *   3. Record<string,…>  → name-prefixed bag (`<NAME>` for single,
+ *                          `<NAME>_<SUFFIX>` for multi). Disambiguates
+ *                          between same-shape resolvers in one array.
+ */
+type ConnectionValue = typeof globalThis.fetch | string | Record<string, string>;
+type AnyResolverArray = readonly ConnectionResolver[];
+/**
+ * Programmatic record-bag shape for a single resolver. Single-credential
+ * resolvers contribute `{ [EnvFromKey<TName>]: string }`; multi-credential
+ * resolvers contribute `{ [\`${EnvFromKey<TName>}_${TSuffixes[number]}\`]:
+ * string }`.
+ */
+type BagOf<R> = R extends SingleConnectionResolver<infer TName> ? {
+    readonly [K in EnvFromKey<TName>]: string;
+} : R extends MultiConnectionResolver<infer TName, infer TSuffixes> ? {
+    readonly [K in `${EnvFromKey<TName>}_${TSuffixes[number]}`]: string;
+} : never;
+/**
+ * `ConnectionValue` narrowed to a specific resolver entry. Single-resolver
+ * forms also accept the resolver's bag shape; resolver arrays additionally
+ * union the per-resolver bag shapes; the `string` shorthand arm appears
+ * iff the entry contains at least one single-credential resolver.
+ */
+type ConnectionValueFor<R extends ConnectionResolverEntry> = R extends ConnectionResolver ? typeof globalThis.fetch | (R extends SingleConnectionResolver ? string : never) | BagOf<R> : R extends AnyResolverArray ? typeof globalThis.fetch | (Extract<R[number], SingleConnectionResolver> extends never ? never : string) | BagOf<R[number]> : never;
+type AnyResolversMap = Record<string, ConnectionResolverEntry>;
+/**
+ * Per-slot narrowing: given the connector's resolvers map and the
+ * connection key the slot references, return the slot's
+ * `ConnectionValueFor` shape (or `ConnectionValue` if the key is unknown
+ * to the type system — we still validate at runtime).
+ */
+type ConnectionValueForKey<TResolvers extends AnyResolversMap, TKey extends string> = TKey extends keyof TResolvers ? ConnectionValueFor<TResolvers[TKey]> : ConnectionValue;
+/**
+ * Caller-provided run options. Three shapes (mirrors `ToolDefinition`):
+ *   - none:   `RunOptionsNone`     — no `connection` / `connections`.
+ *   - single: `RunOptionsSingle`   — `connection` only.
+ *   - multi:  `RunOptionsMulti`    — `connections` only.
+ */
+interface RunOptionsNone {
+    connection?: never;
+    connections?: never;
+}
+interface RunOptionsSingle<TValue = ConnectionValue> {
+    connection: TValue;
+    connections?: never;
+}
+interface RunOptionsMulti<TSlots extends string = string, TPerSlot extends Record<TSlots, ConnectionValue> = Record<TSlots, ConnectionValue>> {
+    connection?: never;
+    connections: TPerSlot;
+}
+type RunOptions<TSlots extends string = string, TValue = ConnectionValue, TPerSlot extends Record<TSlots, ConnectionValue> = Record<TSlots, ConnectionValue>> = RunOptionsNone | RunOptionsSingle<TValue> | RunOptionsMulti<TSlots, TPerSlot>;
+/** Author-facing context for a single-connection script. */
+interface ContextSingle {
+    fetch: typeof globalThis.fetch;
+}
+/** Author-facing context for a multi-connection script. */
+interface ContextMulti<TSlots extends string = string> {
+    connections: Record<TSlots, typeof globalThis.fetch>;
+}
+type AnyInputDependencies$1 = Readonly<Record<string, unknown>>;
+/** When authoring omits `inputDependencies`, the definition value is `undefined`. */
+type InputDependenciesValue<T> = [T] extends [undefined] ? undefined : T;
+interface DefineToolConfigBase<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
+    name: TName;
+    title: string;
+    description: string;
+    inputSchema: TIn;
+    outputSchema: TOut;
+    annotations: _modelcontextprotocol_sdk_types_js.Tool["annotations"];
+    statements?: ReadonlyArray<Statement>;
+    inputDependencies?: TInputDependencies;
+}
+interface DefineToolConfigNone<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> extends DefineToolConfigBase<TIn, TOut, TInputDependencies, TName> {
+    connection?: never;
+    connections?: never;
+    run: (input: z.infer<TIn>) => Promise<z.infer<TOut>>;
+}
+interface DefineToolConfigSingle<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string, TKey extends string> extends DefineToolConfigBase<TIn, TOut, TInputDependencies, TName> {
+    connection: TKey;
+    connections?: never;
+    run: (input: z.infer<TIn>, ctx: ContextSingle) => Promise<z.infer<TOut>>;
+}
+interface DefineToolConfigMulti<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string, TSlots extends string, TKey extends string> extends DefineToolConfigBase<TIn, TOut, TInputDependencies, TName> {
+    connection?: never;
+    connections: Record<TSlots, TKey>;
+    run: (input: z.infer<TIn>, ctx: ContextMulti<TSlots>) => Promise<z.infer<TOut>>;
+}
+interface ToolDefinitionBase<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
+    readonly kind: "tool";
+    readonly name: TName;
+    readonly title: string;
+    readonly description: string;
+    inputSchema: TIn;
+    outputSchema: TOut;
+    readonly annotations: _modelcontextprotocol_sdk_types_js.Tool["annotations"];
+    readonly statements: ReadonlyArray<Statement> | undefined;
+    inputDependencies: InputDependenciesValue<TInputDependencies>;
+}
+interface ToolDefinitionNone<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string> extends ToolDefinitionBase<TIn, TOut, TInputDependencies, TName> {
+    readonly connection?: undefined;
+    readonly connections?: undefined;
+    /** Author's run; the wrapper passes `input` directly. */
+    run: (input: z.infer<TIn>) => Promise<z.infer<TOut>>;
+}
+interface ToolDefinitionSingle<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string, TKey extends string = string> extends ToolDefinitionBase<TIn, TOut, TInputDependencies, TName> {
+    readonly connection: TKey;
+    readonly connections?: undefined;
+    run: (input: z.infer<TIn>, ctx: ContextSingle) => Promise<z.infer<TOut>>;
+}
+interface ToolDefinitionMulti<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string, TSlots extends string = string, TKey extends string = string> extends ToolDefinitionBase<TIn, TOut, TInputDependencies, TName> {
+    readonly connection?: undefined;
+    readonly connections: Record<TSlots, TKey>;
+    run: (input: z.infer<TIn>, ctx: ContextMulti<TSlots>) => Promise<z.infer<TOut>>;
+}
+type ToolDefinition<TIn extends z.ZodType = z.ZodType, TOut extends z.ZodType = z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string, TSlots extends string = string, TKey extends string = string> = ToolDefinitionNone<TIn, TOut, TInputDependencies, TName> | ToolDefinitionSingle<TIn, TOut, TInputDependencies, TName, TKey> | ToolDefinitionMulti<TIn, TOut, TInputDependencies, TName, TSlots, TKey>;
+/** Wide author-side `run` signature for polymorphic walks. */
+type AnyToolDefinitionRun = (input: any, ctx?: any) => Promise<any>;
+type AnyToolDefinition = Omit<ToolDefinitionBase<z.ZodType, z.ZodType, any, string>, "run" | "inputDependencies"> & {
+    inputDependencies: AnyInputDependencies$1 | undefined;
+    run: AnyToolDefinitionRun;
+    readonly connection?: string | undefined;
+    readonly connections?: Record<string, string> | undefined;
+};
+
+/**
+ * SDK-shipped resolvers and the `defineConnectionResolver` typed-identity
+ * helper.
+ *
+ * Resolvers are plain data objects matching one of two shapes
+ * (`SingleConnectionResolver` / `MultiConnectionResolver`). They never
+ * see env-var names, programmatic-bag keys, slot names, or connection
+ * keys — the surface wrappers (`defineConnector`, `handleIfScriptMain`)
+ * compose those from the resolver's `name` and (optional) `keySuffixes`.
+ */
+
+/**
+ * Typed identity helper for hand-rolled resolvers. Preserves the literal
+ * `name` (and `keySuffixes` for multi-credential resolvers) on the value's
+ * type so `defineConnector` can compose programmatic-bag key types via
+ * `EnvFromKey<TName>` template literals.
+ *
+ * Examples:
+ *
+ *   const myToken = defineConnectionResolver({
+ *     name: "api-key",
+ *     resolve: (key) => ...,
+ *   });  // -> SingleConnectionResolver<"api-key">
+ *
+ *   const myHmac = defineConnectionResolver({
+ *     name: "hmac",
+ *     keySuffixes: ["KEY", "SECRET"] as const,
+ *     resolve: ({ KEY, SECRET }) => ...,
+ *   });  // -> MultiConnectionResolver<"hmac", readonly ["KEY", "SECRET"]>
+ */
+declare function defineConnectionResolver<T extends ConnectionResolver>(resolver: T): T;
+/**
+ * Zapier-relayed resolver. Single-credential — operators set
+ * `<SLOT>_<CONNECTION_KEY>_ZAPIER_CONNECTION_ID` in env, and Relay derives
+ * the app from the connection itself (no app arg needed).
+ *
+ * Composition (single-slot):
+ *
+ *   notion        -> env: NOTION_ZAPIER_CONNECTION_ID         programmatic: { ZAPIER_CONNECTION_ID }
+ *   github        -> env: GITHUB_ZAPIER_CONNECTION_ID         programmatic: { ZAPIER_CONNECTION_ID }
+ *   google-drive  -> env: GOOGLE_DRIVE_ZAPIER_CONNECTION_ID   programmatic: { ZAPIER_CONNECTION_ID }
+ *
+ * Composition (multi-slot):
+ *
+ *   { source: "notion" } -> env: SOURCE_NOTION_ZAPIER_CONNECTION_ID
+ *
+ * Exported as a value (no parameters):
+ * `connectionResolvers: { notion: zapierConnectionResolver }`. The
+ * `@zapier/zapier-sdk` import stays lazy — it only loads when this
+ * resolver actually wins resolution at run time.
+ */
+declare const zapierConnectionResolver: SingleConnectionResolver<"zapier-connection-id">;
+/**
+ * Bearer-token resolver: `Authorization: <scheme> <token>`.
+ * Single-credential.
+ *
+ * Default `name: "token"` so a single-resolver setup composes to
+ * `<SLOT>_<CONNECTION_KEY>_TOKEN` (env) and `{ TOKEN }` (programmatic),
+ * matching the dominant ecosystem convention (`NOTION_TOKEN`,
+ * `GITHUB_TOKEN`, `STRIPE_SECRET_KEY` patterns). Authors who prefer
+ * `<SLOT>_<KEY>_BEARER_TOKEN` (Twitter/X-style) override:
+ * `defineBearerTokenResolver({ name: "bearer-token" })`.
+ *
+ * The `name` literal flows through the generic so `RunOptions.connection`
+ * narrows to `{ [EnvFromKey<TName>]: string }`.
+ *
+ * `scheme` defaults to `"Bearer"`; pass `"token"` for GitHub-style PATs.
+ */
+declare function defineBearerTokenResolver<TName extends string = "token">(opts?: {
+    scheme?: string;
+    name?: TName;
+}): SingleConnectionResolver<TName>;
+
+/** Chat Completions registration surface shape (`chat.completions.create({ tools })`). */
+interface ChatCompletionFunctionTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** Build the Chat Completions registration surface shape from a `ToolDefinition`. */
+declare function toChatCompletionTool(definition: AnyToolDefinition): ChatCompletionFunctionTool;
+
+/**
+ * Config object passable to `McpServer.registerTool(name, config, cb)`.
+ *
+ * Mirrors the inline shape declared by `@modelcontextprotocol/sdk`'s
+ * `McpServer.registerTool` signature: Zod schemas (not JSON Schema) for
+ * `inputSchema` / `outputSchema`, `annotations`, and an optional `_meta`
+ * passthrough. `name` is omitted — `registerTool` takes it as the first
+ * positional argument, distinct from the config object.
+ */
+interface McpRegisterToolConfig {
+    title?: string;
+    description?: string;
+    inputSchema?: z.ZodType;
+    outputSchema?: z.ZodType;
+    annotations?: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Build the `McpServer.registerTool` config for a `ToolDefinition`.
+ *
+ * Use this with the modern high-level API:
+ *
+ * ```ts
+ * server.registerTool(script.name, notion.toMcpServerTool(script), cb);
+ * ```
+ *
+ * For the deprecated `Server.setRequestHandler(ListToolsRequestSchema, ...)`
+ * flow (or any consumer that wants a self-contained JSON-Schema'd descriptor),
+ * use `toMcpTool` instead.
+ */
+declare function toMcpServerTool(definition: AnyToolDefinition): McpRegisterToolConfig;
+
+/**
+ * Build the wire-format MCP `Tool` descriptor for a `ToolDefinition`.
+ *
+ * Produces a JSON-Schema'd `Tool` suitable for the deprecated
+ * `Server.setRequestHandler(ListToolsRequestSchema, ...)` flow, plus any
+ * non-`McpServer` consumer that wants a self-contained tool descriptor
+ * (catalog APIs, OpenAPI bridges, `tools/list` proxies).
+ *
+ * For the modern `McpServer.registerTool(name, config, cb)` path, use
+ * `toMcpServerTool` instead — that helper keeps `inputSchema` / `outputSchema`
+ * as Zod and matches the inline config shape `registerTool` expects.
+ */
+declare function toMcpTool(definition: AnyToolDefinition): Tool;
+
+/** Responses API registration surface shape (`responses.create({ tools })`). */
+interface ResponsesFunctionTool {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/** Build the Responses API registration surface shape from a `ToolDefinition`. */
+declare function toResponsesTool(definition: AnyToolDefinition): ResponsesFunctionTool;
+
+/**
+ * `defineConnector({ scripts, connectionResolvers })` — connector
+ * `index.ts` helper.
+ *
+ * Validates that every connection key referenced by any script's
+ * `connection` / `connections` fields exists in the supplied
+ * `connectionResolvers` map, and that every resolver name within each
+ * key's array is unique. Wraps each script's author-side `.run(input,
+ * ctx)` into a consumer-facing `.run(input, opts: RunOptions) =>
+ * Promise<output>`. The wrapped form is what consumers invoke; the
+ * registration helpers (`toMcpTool`, `toMcpServerTool`, etc.) and
+ * registration surfaces (per-script CLI, dispatcher, MCP stdio) all
+ * consume the wrapped scripts unchanged.
+ */
+
+type AnyDef = ToolDefinition<any, any, any, string, string, string>;
+/**
+ * Map a script's `ToolDefinition` to its consumer-facing wrapped form,
+ * narrowed against the connector's `connectionResolvers` map. The wrapped
+ * `run` takes `(input, opts: RunOptions)`; `RunOptions.connection` /
+ * `RunOptions.connections.<slot>` is narrowed per the slot's resolver
+ * array via `ConnectionValueFor`.
+ */
+type WrappedScript<D extends AnyDef, TResolvers extends ConnectionResolversMap> = D extends ToolDefinitionNone<infer TIn, infer TOut, infer _TInputDependencies, infer _TName> ? Omit<D, "run"> & {
+    run: (input: z.infer<TIn>, opts?: RunOptionsNone) => Promise<z.infer<TOut>>;
+} : D extends ToolDefinitionSingle<infer TIn, infer TOut, infer _TInputDependencies, infer _TName, infer TKey> ? Omit<D, "run"> & {
+    run: (input: z.infer<TIn>, opts: RunOptionsSingle<ConnectionValueForKey<TResolvers, TKey>>) => Promise<z.infer<TOut>>;
+} : D extends ToolDefinitionMulti<infer TIn, infer TOut, infer _TInputDependencies, infer _TName, infer TSlots, infer TKey> ? Omit<D, "run"> & {
+    run: (input: z.infer<TIn>, opts: {
+        connection?: never;
+        connections: {
+            [S in TSlots]: ConnectionValueForKey<TResolvers, TKey>;
+        };
+    }) => Promise<z.infer<TOut>>;
+} : never;
+type WrappedScripts<TScripts extends Record<string, AnyDef>, TResolvers extends ConnectionResolversMap> = {
+    [K in keyof TScripts]: WrappedScript<TScripts[K], TResolvers>;
+};
+interface ConnectorDefinition<TScripts extends Record<string, AnyDef>, TResolvers extends ConnectionResolversMap> {
+    scripts: WrappedScripts<TScripts, TResolvers>;
+    /** The `connectionResolvers` map this connector was constructed with. */
+    connectionResolvers: TResolvers;
+    toMcpTool: typeof toMcpTool;
+    toMcpServerTool: typeof toMcpServerTool;
+    toChatCompletionTool: typeof toChatCompletionTool;
+    toResponsesTool: typeof toResponsesTool;
+    /**
+     * Build `RunOptions` for a wrapped script from a process-env bag.
+     * Convenience for long-running consumers that resolve credentials once
+     * and reuse the same opts for the life of the process.
+     */
+    buildRunOptionsFromEnv: (script: AnyToolDefinition, env: Record<string, string | undefined>) => RunOptions;
+}
+interface DefineConnectorConfig<TScripts extends Record<string, AnyDef>, TResolvers extends ConnectionResolversMap> {
+    scripts: TScripts;
+    connectionResolvers?: TResolvers;
+}
+/**
+ * Wrap every script in the bundle with the connector's resolvers, then
+ * attach the SDK helpers consumers reach for through the connector
+ * default export.
+ */
+declare function defineConnector<TScripts extends Record<string, AnyDef>, const TResolvers extends ConnectionResolversMap = ConnectionResolversMap>(config: DefineConnectorConfig<TScripts, TResolvers>): ConnectorDefinition<TScripts, TResolvers>;
+
+/**
+ * `defineTool({...})` — the *authoring* surface of `@zapier/connectors-sdk`.
+ *
+ * A script's single `export default defineTool({...})` produces a
+ * `ToolDefinition` value: metadata (`kind: "tool"`, schemas, optional
+ * `connection` / `connections` string keys, …) plus an author-side `run`
+ * — `(input)` for credential-free scripts, `(input, ctx)` for those that
+ * declare connections.
+ *
+ * `defineTool` is intentionally light: it does NOT translate
+ * `RunOptions` to `Context`, does NOT read `process.env`, and does NOT
+ * compose env-var names. All of that lives on the surface wrappers
+ * (`defineConnector`, `handleIfScriptMain`) where the connector's
+ * `connectionResolvers` are attached.
+ *
+ * Three overloads (none / single / multi) only differ in the
+ * `connection` / `connections` field shape and the `ctx` shape passed
+ * to `run`. The returned definition mirrors the input one-to-one.
+ */
+
+type AnyInputDependencies = Readonly<Record<string, unknown>>;
+declare function defineTool<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies | undefined = undefined, const TName extends string = string>(config: DefineToolConfigNone<TIn, TOut, TInputDependencies, TName>): ToolDefinitionNone<TIn, TOut, TInputDependencies, TName>;
+declare function defineTool<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies | undefined = undefined, const TName extends string = string, const TKey extends string = string>(config: DefineToolConfigSingle<TIn, TOut, TInputDependencies, TName, TKey>): ToolDefinitionSingle<TIn, TOut, TInputDependencies, TName, TKey>;
+declare function defineTool<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies | undefined = undefined, const TName extends string = string, const TSlots extends string = string, const TKey extends string = string>(config: DefineToolConfigMulti<TIn, TOut, TInputDependencies, TName, TSlots, TKey>): ToolDefinitionMulti<TIn, TOut, TInputDependencies, TName, TSlots, TKey>;
+
+/**
+ * `handleIfScriptMain(meta, definition, opts?)` — per-script CLI execution
+ * surface (not the connector bin).
+ *
+ * Each `apps/<app>/scripts/<name>.ts` ends with
+ * `await handleIfScriptMain(import.meta, definition, { connectionResolvers })`.
+ * When `import.meta.main` is true: parses argv/stdin, builds `RunOptions`
+ * from `process.env` via `buildRunOptionsFromEnv`, calls the wrapped
+ * script, writes JSON.
+ *
+ * **Credentials are env-only by design.** The CLI takes only positional
+ * JSON (the script's `inputSchema`) and `--help`. Passing secrets via
+ * argv would leak them through shell history, `ps`, audit logs, and CI
+ * runner echo.
+ *
+ * **Error handling.** The public entry catches any thrown error, writes
+ * it to stderr, and calls `process.exit(1)`. This mirrors the explicit
+ * catch+exit in `runDispatchCli`; see that function's header for the
+ * rationale (top-level-await rejection alone can be silently swallowed
+ * in practice, e.g. when a script's `run` chain triggers a lazy dynamic
+ * `import()` inside a dependency).
+ *
+ * `handleIfScriptMainBody` rethrows so it composes cleanly: the
+ * connector bin's `runDispatchCliBody` delegates to it after argv
+ * shifting, and the dispatcher's own public entry is responsible for
+ * the single `process.exit`. Advanced programmatic consumers that
+ * embed this surface get the raw error and decide what to do.
+ */
+
+interface HandleIfScriptMainOptions {
+    /**
+     * Required when the script declares any connection (`connection` /
+     * `connections`); omit for credential-free scripts. Same shape as
+     * `defineConnector`'s `connectionResolvers` — single resolver or
+     * ordered array per connection key.
+     */
+    connectionResolvers?: ConnectionResolversMap;
+}
+declare function handleIfScriptMain<D extends AnyToolDefinition>(meta: ImportMeta, definition: D, opts?: HandleIfScriptMainOptions): Promise<void>;
+
+/**
+ * `runDispatchCli(meta, connector)` — connector-bin execution surface.
+ *
+ * Each app's `apps/<app>/cli.ts` ends with `await runDispatchCli(import.meta,
+ * connector)` (where `connector` is the `defineConnector` result), which:
+ *
+ *   1. Returns early when imported as a module (`import.meta.main` is false).
+ *   2. Parses argv:
+ *      - `<bin> run <script> [args...]`        — dispatch to a script.
+ *      - `<bin> mcp`                           — boot a local MCP stdio
+ *                                                server exposing every
+ *                                                script.
+ *      - `<bin>`, `<bin> --help`, `<bin> -h`   — usage to stdout.
+ *      - `<bin> run <script> --help`           — per-script help (input
+ *                                                schema + required env
+ *                                                vars per slot/resolver).
+ *      - `<bin> mcp --help`, `<bin> mcp -h`    — `mcp` primary-command
+ *                                                help (what the server
+ *                                                exposes + how to set
+ *                                                env vars).
+ *   3. Delegates to `handleIfScriptMainBody` with shifted argv, so per-script
+ *      semantics (positional JSON input, stdin fallback, `--help`) are
+ *      identical to the per-script `node apps/<app>/scripts/<x>.ts`
+ *      invocation.
+ *
+ * `run` is required to dispatch a script — there is no shorthand
+ * `<bin> <script>` form. This was deliberately removed (originally
+ * supported, reverted in favor of one canonical grammar) because the
+ * shorthand collided with primary commands (`mcp`), forced a
+ * reserved-name carve-out for script authors, and added a second shape
+ * for agents/humans to remember without paying for itself in keystrokes.
+ *
+ * Credentials are env-only: there are no credential CLI flags. Operators
+ * set the env vars listed by `--help`.
+ *
+ * **Error handling.** The public entry catches any thrown error from the
+ * dispatch body, writes it to stderr, and calls `process.exit(1)`.
+ * Relying on Node's top-level-await unhandled-rejection diagnostic is not
+ * enough in practice: when a script's `run` triggers a lazy dynamic
+ * `import()` deep in a dependency (e.g. `@zapier/zapier-sdk`'s lazy
+ * `@zapier/zapier-sdk-cli/login` probe) the rejection raced against
+ * pending microtasks can resolve to a silent `exit 0` with no output.
+ * The explicit `try`/`catch` + `process.exit` makes the error surface
+ * deterministic across Node versions and dependency-loading topologies.
+ *
+ * `process.exit` only happens at this single boundary. The lower-level
+ * `runDispatchCliBody` rethrows so its two real consumers — the public
+ * entry above and advanced programmatic consumers (cron wrappers,
+ * custom IO, the per-script `handleIfScriptMainBody` callee chain) —
+ * can format the error their own way before exiting (or not exiting at
+ * all, for embedded use).
+ */
+
+type AnyConnector = ConnectorDefinition<any, any>;
+/** Public: thin guard + delegate. App `cli.ts` files call this. */
+declare function runDispatchCli(meta: ImportMeta, connector: AnyConnector): Promise<void>;
+
+type AnyScripts = Record<string, any>;
+type NamedFunctions<TScripts extends AnyScripts> = {
+    [K in keyof TScripts]: TScripts[K]["run"];
+};
+/**
+ * Map each wrapped script in a connector definition to its `.run`
+ * function, so a connector's package can `export const { search,
+ * createDatabaseItem } = toFunctions(connector)`. Each export is the
+ * consumer-facing `(input, opts: RunOptions) => Promise<output>`.
+ */
+declare function toFunctions<TScripts extends AnyScripts, TResolvers extends ConnectionResolversMap>(connector: ConnectorDefinition<TScripts, TResolvers>): NamedFunctions<ConnectorDefinition<TScripts, TResolvers>["scripts"]>;
+
+export { type AnyToolDefinition, type ConnectorDefinition, type RunOptions, defineBearerTokenResolver, defineConnectionResolver, defineConnector, defineTool, handleIfScriptMain, runDispatchCli, toFunctions, zapierConnectionResolver };