@zapier/connectors-sdk 0.1.0-experimental.1 → 0.1.0-experimental.11

package/README.internal.md

@@ -346,32 +346,6 @@ A multi-credential resolver `{ name: "hmac", keySuffixes: ["KEY", "SECRET"] }` w
 
 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:

package/dist/index.cjs

@@ -109,6 +109,7 @@ function defineConnectionResolver(resolver) {
 }
 var zapierConnectionResolver = defineConnectionResolver({
   name: "zapier-connection-id",
+  optionalPackages: ["@zapier/zapier-sdk"],
   resolve: async (connectionId) => {
     const { buildZapierFetch: buildZapierFetch2 } = await Promise.resolve().then(() => (init_build_zapier_fetch(), build_zapier_fetch_exports));
     return buildZapierFetch2(connectionId);
@@ -128,12 +129,16 @@ function defineBearerTokenResolver(opts = {}) {
   });
 }
 
+// src/normalize-connections.ts
+var import_node_module = require("module");
+
 // src/connection-key.ts
 function envFromKey(name) {
   return name.toUpperCase().replace(/-/g, "_");
 }
 
 // src/normalize-connections.ts
+var import_meta = {};
 function* walkConnections(definition) {
   if (typeof definition.connection === "string") {
     yield { slotName: void 0, connectionKey: definition.connection };
@@ -267,23 +272,103 @@ function buildRunOptionsFromEnv(definition, env, connectionResolvers) {
   }
   return { connections: wrapped };
 }
-function formatHelpForConnections(definition, connectionResolvers) {
+function isPackageInstalled(name) {
+  try {
+    (0, import_node_module.createRequire)(import_meta.url).resolve(name);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function buildMissingConnectionError(scriptName, missingSlots) {
+  const lines = [];
+  if (missingSlots.length === 1 && missingSlots[0].slotName === void 0) {
+    const { connectionKey, resolvers } = missingSlots[0];
+    lines.push(
+      `"${scriptName}" requires the "${connectionKey}" connection but no credentials were found in the environment.`
+    );
+    lines.push("");
+    lines.push(
+      "Set one of the following environment variables before running:"
+    );
+    lines.push("");
+    for (const resolver of resolvers) {
+      const vars = envVarsFor(void 0, connectionKey, resolver);
+      lines.push(`  ${vars.join("  ")}  (${resolver.name})`);
+    }
+  } else {
+    lines.push(
+      `"${scriptName}" is missing credentials for connection slot(s):`
+    );
+    for (const { slotName, connectionKey, resolvers } of missingSlots) {
+      lines.push("");
+      lines.push(`  ${slotName} (${connectionKey}):`);
+      for (const resolver of resolvers) {
+        const vars = envVarsFor(slotName, connectionKey, resolver);
+        lines.push(`    ${vars.join("  ")}  (${resolver.name})`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push("Run with --help for the full auth guide.");
+  return new Error(lines.join("\n"));
+}
+function formatHelpForConnections(definition, connectionResolvers, env) {
   const slots = [...walkConnections(definition)];
   if (slots.length === 0) return [];
   const lines = [];
   lines.push(
-    "Connections (set as environment variables; do NOT pass via CLI argument):"
+    "Auth (set as environment variables; do NOT pass via CLI argument):"
   );
+  const notReadySlots = [];
   for (const { slotName, connectionKey } of slots) {
     const resolvers = resolversForKey(connectionResolvers, connectionKey);
-    const heading = slotName ? `  ${slotName} (${connectionKey}):` : `  ${connectionKey}:`;
-    lines.push(heading);
+    if (slotName !== void 0) {
+      lines.push(`  ${slotName} (${connectionKey}):`);
+    }
+    const resolverIndent = slotName !== void 0 ? "    " : "  ";
+    const varIndent = slotName !== void 0 ? "      " : "    ";
+    let slotHasReady = false;
     for (const resolver of resolvers) {
-      lines.push(`    ${resolver.name}:`);
-      for (const envVar of envVarsFor(slotName, connectionKey, resolver)) {
-        lines.push(`      ${envVar}`);
+      const vars = envVarsFor(slotName, connectionKey, resolver);
+      let isReady = false;
+      let missingPkgs = [];
+      if (env !== void 0) {
+        const envVarsOk = vars.every(
+          (k) => typeof env[k] === "string" && env[k] !== ""
+        );
+        if (envVarsOk) isReady = true;
+        missingPkgs = (resolver.optionalPackages ?? []).filter(
+          (pkg) => !isPackageInstalled(pkg)
+        );
+      }
+      const markReady = isReady && !slotHasReady;
+      if (markReady) slotHasReady = true;
+      const resolverSuffix = env !== void 0 && markReady ? "  [READY \u2014 use this]" : "";
+      lines.push(`${resolverIndent}${resolver.name}:${resolverSuffix}`);
+      for (const envVar of vars) {
+        const varSuffix = env !== void 0 ? env[envVar] !== void 0 && env[envVar] !== "" ? "  [set]" : "  [not set]" : "";
+        lines.push(`${varIndent}${envVar}${varSuffix}`);
+      }
+      if (env !== void 0) {
+        for (const pkg of resolver.optionalPackages ?? []) {
+          if (missingPkgs.includes(pkg)) {
+            lines.push(
+              `${varIndent}${pkg}  [not installed \u2014 run \`npm install ${pkg}\` first]`
+            );
+          } else {
+            lines.push(`${varIndent}${pkg}  [installed]`);
+          }
+        }
       }
     }
+    if (env !== void 0 && !slotHasReady) {
+      notReadySlots.push(slotName ?? connectionKey);
+    }
+  }
+  if (env !== void 0 && notReadySlots.length > 0) {
+    const label = notReadySlots.length === slots.length ? "No option is ready" : `No option is ready for slot${notReadySlots.length > 1 ? "s" : ""} ${notReadySlots.join(", ")}`;
+    lines.push(`${label} \u2014 set one of the env vars above.`);
   }
   return lines;
 }
@@ -368,8 +453,8 @@ function ensureConnectionValue(scriptName, slotName, connectionKey, value) {
   return value;
 }
 async function buildContext(definition, opts, connectionResolvers) {
-  const hasConnection = "connection" in opts && opts.connection !== void 0;
-  const hasConnections = "connections" in opts && opts.connections !== void 0;
+  const hasConnection = opts !== void 0 && "connection" in opts && opts.connection !== void 0;
+  const hasConnections = opts !== void 0 && "connections" in opts && opts.connections !== void 0;
   if (definition.connection === void 0 && definition.connections === void 0) {
     if (hasConnection || hasConnections) {
       throw new Error(
@@ -378,6 +463,11 @@ async function buildContext(definition, opts, connectionResolvers) {
     }
     return {};
   }
+  if (opts === void 0) {
+    throw new Error(
+      `ToolDefinition "${definition.name}": \`RunOptions\` is required \u2014 pass \`{ connection: ... }\` or \`{ connections: ... }\`.`
+    );
+  }
   if (hasConnection && hasConnections) {
     throw new Error(
       `ToolDefinition "${definition.name}": \`RunOptions\` sets both \`connection\` and \`connections\`. Use one or the other.`
@@ -395,7 +485,7 @@ async function buildContext(definition, opts, connectionResolvers) {
       definition.name,
       void 0,
       connectionKey,
-      opts.connection
+      "connection" in opts ? opts.connection : void 0
     );
     const fetch = await resolveSlotFetch(
       definition.name,
@@ -412,12 +502,12 @@ async function buildContext(definition, opts, connectionResolvers) {
       `ToolDefinition "${definition.name}" is multi-connection (slots: ${declaredSlots.join(", ")}) \u2014 call with \`{ connections: { ... } }\`, not \`{ connection: ... }\`.`
     );
   }
-  if (!hasConnections) {
+  const provided = opts.connections;
+  if (provided === void 0) {
     throw new Error(
       `ToolDefinition "${definition.name}" is multi-connection \u2014 \`RunOptions.connections\` is required.`
     );
   }
-  const provided = opts.connections;
   const unknown = Object.keys(provided).filter(
     (s) => !declaredSlots.includes(s)
   );
@@ -471,28 +561,18 @@ function toChatCompletionTool(definition) {
 
 // src/surfaces/to-mcp-server-tool.ts
 function toMcpServerTool(definition) {
-  const config = {
+  return {
     title: definition.title,
     description: definition.description,
     inputSchema: definition.inputSchema,
     outputSchema: definition.outputSchema,
     annotations: definition.annotations
   };
-  if (definition.inputDependencies) {
-    config._meta = {
-      "zapier:inputDependencies": definition.inputDependencies
-    };
-  }
-  return config;
 }
 
 // src/surfaces/to-mcp-tool.ts
 var import_zod2 = require("zod");
 function toMcpTool(definition) {
-  const meta = {};
-  if (definition.inputDependencies) {
-    meta["zapier:inputDependencies"] = definition.inputDependencies;
-  }
   return {
     name: definition.name,
     title: definition.title,
@@ -501,8 +581,7 @@ function toMcpTool(definition) {
     outputSchema: import_zod2.z.toJSONSchema(
       definition.outputSchema
     ),
-    annotations: definition.annotations,
-    ...Object.keys(meta).length > 0 ? { _meta: meta } : {}
+    annotations: definition.annotations
   };
 }
 
@@ -516,24 +595,9 @@ function toResponsesTool(definition) {
 
 // src/define-connector.ts
 function wrapScriptWithResolvers(definition, connectionResolvers) {
-  const authorRun = definition.run;
   const wrappedRun = async (input, opts) => {
-    const validated = definition.inputSchema.parse(input);
-    if (definition.connection === void 0 && definition.connections === void 0) {
-      if (opts !== void 0 && (opts.connection !== void 0 || opts.connections !== void 0)) {
-        throw new Error(
-          `ToolDefinition "${definition.name}" is credential-free \u2014 \`RunOptions\` must not include \`connection\` or \`connections\`.`
-        );
-      }
-      return authorRun(validated);
-    }
-    if (opts === void 0) {
-      throw new Error(
-        `ToolDefinition "${definition.name}": \`RunOptions\` is required \u2014 pass \`{ connection: ... }\` or \`{ connections: ... }\`.`
-      );
-    }
     const ctx = await buildContext(definition, opts, connectionResolvers);
-    return authorRun(validated, ctx);
+    return definition.run(input, ctx);
   };
   return { ...definition, run: wrappedRun };
 }
@@ -543,6 +607,11 @@ function defineConnector(config) {
   validateConnectionResolvers(scriptsAsAny, connectionResolvers);
   const wrapped = {};
   for (const [key, definition] of Object.entries(scriptsAsAny)) {
+    if (key !== definition.name) {
+      throw new Error(
+        `defineConnector: script key "${key}" must match its tool name \u2014 got name "${definition.name}". Rename the key to "${definition.name}" or update the tool's name field.`
+      );
+    }
     wrapped[key] = wrapScriptWithResolvers(definition, connectionResolvers);
   }
   return {
@@ -612,6 +681,12 @@ function defineTool(config) {
       validateConnectionKey(config.name, value);
     }
   }
+  const authorRun = config.run;
+  const wrappedRun = async (input, ctx) => {
+    const validated = config.inputSchema.parse(input);
+    const result = await authorRun(validated, ctx);
+    return config.outputSchema.parse(result);
+  };
   const base = {
     kind: "tool",
     name: config.name,
@@ -620,9 +695,7 @@ function defineTool(config) {
     inputSchema: config.inputSchema,
     outputSchema: config.outputSchema,
     annotations: config.annotations,
-    statements: config.statements,
-    inputDependencies: config.inputDependencies,
-    run: config.run
+    run: wrappedRun
   };
   if (hasSingular) base.connection = config.connection;
   if (hasPlural) base.connections = config.connections;
@@ -766,10 +839,73 @@ async function runDispatchCliBody(connector, opts) {
     });
     return;
   }
+  if (first === "skill") {
+    if (!opts.meta) {
+      throw new Error(
+        "runDispatchCliBody: `skill` requires `meta` in options (the connector's `import.meta` from `cli.ts`)."
+      );
+    }
+    const cliPath = (0, import_node_url2.fileURLToPath)(opts.meta.url);
+    const connectorDir = path2.dirname(cliPath);
+    const skillPath = path2.join(connectorDir, "SKILL.md");
+    let content;
+    try {
+      content = await fs2.readFile(skillPath, "utf8");
+    } catch {
+      throw new Error(
+        `SKILL.md not found at ${skillPath}. Ensure the connector ships a SKILL.md.`
+      );
+    }
+    opts.stdout.write(resolveRelativeLinks(content, connectorDir));
+    return;
+  }
+  if (first === "reference") {
+    if (!opts.meta) {
+      throw new Error(
+        "runDispatchCliBody: `reference` requires `meta` in options (the connector's `import.meta` from `cli.ts`)."
+      );
+    }
+    const cliPath = (0, import_node_url2.fileURLToPath)(opts.meta.url);
+    const connectorDir = path2.dirname(cliPath);
+    const refsDir = path2.join(connectorDir, "references");
+    const name = args[1];
+    if (!name) {
+      let entries;
+      try {
+        const files = await fs2.readdir(refsDir);
+        entries = files.filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -".md".length));
+      } catch {
+        entries = [];
+      }
+      if (entries.length === 0) {
+        opts.stdout.write(`Available references: <none>
+`);
+      } else {
+        opts.stdout.write(`Available references:
+`);
+        for (const entry of entries) {
+          opts.stdout.write(`  ${entry}
+`);
+        }
+      }
+      return;
+    }
+    const refPath = path2.join(refsDir, `${name}.md`);
+    let content;
+    try {
+      content = await fs2.readFile(refPath, "utf8");
+    } catch {
+      throw new Error(
+        `Reference file not found at ${refPath}. Ensure the connector ships \`references/${name}.md\`.`
+      );
+    }
+    opts.stdout.write(resolveRelativeLinks(content, refsDir));
+    return;
+  }
   if (first !== "run") {
     printUsage(scripts, errOut, packageName);
     throw new Error(
-      `Unknown command "${first}". Use \`run <script>\` to dispatch a script (available: ${Object.keys(scripts).join(", ") || "<none>"}), or \`mcp\` to boot a local MCP server.`
+      `Unknown command "${first}". Use \`run <script>\` to dispatch a script (available: ${Object.keys(scripts).join(", ") || "<none>"}), \`mcp\` to boot a local MCP server, \`skill\` to print SKILL.md, or \`reference [<name>]\` to print or list reference docs.`
     );
   }
   const scriptName = args[1];
@@ -796,6 +932,17 @@ async function runDispatchCliBody(connector, opts) {
     invocation
   });
 }
+function resolveRelativeLinks(content, baseDir) {
+  return content.replace(
+    /(!?\[([^\]]*)\])\(([^)]+)\)/g,
+    (match, prefix, _alt, url) => {
+      if (url.startsWith("http://") || url.startsWith("https://") || url.startsWith("file:") || url.startsWith("#") || url.startsWith("/")) {
+        return match;
+      }
+      return `${prefix}(${path2.resolve(baseDir, url)})`;
+    }
+  );
+}
 async function resolvePackageName(meta) {
   if (!meta?.url) return void 0;
   try {
@@ -814,6 +961,8 @@ function printUsage(scripts, out, packageName) {
     `Usage: <bin> run <script> [<json-input>]
        <bin> run <script> --help    (per-script input + required env vars)
        <bin> mcp                    (run as a local MCP server over stdio)
+       <bin> skill                  (print SKILL.md to stdout)
+       <bin> reference [<name>]     (print references/<name>.md, or list all)
 
 `
   );
@@ -926,12 +1075,13 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   if (helpRequested) {
     io.stdout.write(
       buildHelpText(wrappedScript, connectionResolvers, {
-        invocation: io.invocation
+        invocation: io.invocation,
+        env: io.env
       })
     );
     return;
   }
-  const raw = positional ?? await new Response(io.stdin).text();
+  const raw = positional ?? await readStdinInput(io.stdin, wrappedScript.name);
   if (raw.trim().length === 0) {
     throw new Error(
       `Missing JSON input for "${wrappedScript.name}". Pass it as a positional argument or via stdin.`
@@ -940,9 +1090,33 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   const input = wrappedScript.inputSchema.parse(JSON.parse(raw));
   const hasConnections = [...walkConnections(wrappedScript)].length > 0;
   const runOpts = hasConnections ? buildRunOptionsFromEnv(wrappedScript, io.env, connectionResolvers) : void 0;
+  if (runOpts !== void 0) {
+    const missing = [];
+    for (const { slotName, connectionKey } of walkConnections(wrappedScript)) {
+      const value = slotName === void 0 ? "connection" in runOpts ? runOpts.connection : void 0 : "connections" in runOpts ? runOpts.connections[slotName] : void 0;
+      if (value === void 0) {
+        missing.push({
+          slotName,
+          connectionKey,
+          resolvers: resolversForKey(connectionResolvers, connectionKey)
+        });
+      }
+    }
+    if (missing.length > 0) {
+      throw buildMissingConnectionError(wrappedScript.name, missing);
+    }
+  }
   const result = await wrappedScript.run(input, runOpts);
   io.stdout.write(JSON.stringify(result, null, 2) + "\n");
 }
+async function readStdinInput(stdin, scriptName) {
+  if (stdin.isTTY) {
+    throw new Error(
+      `Missing JSON input for "${scriptName}". Pass it as a positional argument or pipe it via stdin.`
+    );
+  }
+  return new Response(stdin).text();
+}
 function buildHelpText(definition, connectionResolvers, opts = {}) {
   const lines = [];
   const description = definition.description.split("\n")[0]?.trim() ?? "";
@@ -966,7 +1140,8 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
   }
   const connectionsBlock = formatHelpForConnections(
     definition,
-    connectionResolvers
+    connectionResolvers,
+    opts.env
   );
   if (connectionsBlock.length > 0) {
     lines.push(...connectionsBlock);