@zapier/connectors-sdk 0.1.0-experimental.5 → 0.1.0-experimental.7

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,70 @@ 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 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;
 }
@@ -921,7 +973,8 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   if (helpRequested) {
     io.stdout.write(
       buildHelpText(wrappedScript, connectionResolvers, {
-        invocation: io.invocation
+        invocation: io.invocation,
+        env: io.env
       })
     );
     return;
@@ -969,7 +1022,8 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
   }
   const connectionsBlock = formatHelpForConnections(
     definition,
-    connectionResolvers
+    connectionResolvers,
+    opts.env
   );
   if (connectionsBlock.length > 0) {
     lines.push(...connectionsBlock);

package/dist/index.d.cts

@@ -50,6 +50,12 @@ type EnvFromKey<K extends string> = Uppercase<Replace<K, "-", "_">>;
 interface SingleConnectionResolver<TName extends string = string> {
     readonly name: TName;
     readonly keySuffixes?: undefined;
+    /**
+     * npm package names that must be installed for this resolver to function
+     * at runtime. Declared here so `--help` can check availability and tell
+     * the agent which packages to install before using this resolver.
+     */
+    readonly optionalPackages?: readonly string[];
     resolve: (credential: string) => typeof globalThis.fetch | Promise<typeof globalThis.fetch>;
 }
 /**
@@ -68,6 +74,12 @@ interface SingleConnectionResolver<TName extends string = string> {
 interface MultiConnectionResolver<TName extends string = string, TSuffixes extends readonly string[] = readonly string[]> {
     readonly name: TName;
     readonly keySuffixes: TSuffixes;
+    /**
+     * npm package names that must be installed for this resolver to function
+     * at runtime. Declared here so `--help` can check availability and tell
+     * the agent which packages to install before using this resolver.
+     */
+    readonly optionalPackages?: readonly string[];
     resolve: (credentials: Record<TSuffixes[number], string>) => typeof globalThis.fetch | Promise<typeof globalThis.fetch>;
 }
 /** Either resolver shape. */
@@ -160,7 +172,7 @@ interface ContextMulti<TSlots extends string = string> {
 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> {
+interface DefineToolConfigBase<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
     name: TName;
     title: string;
     description: string;
@@ -169,22 +181,22 @@ interface DefineToolConfigBase<TIn extends z.ZodType, TOut extends z.ZodType, TI
     annotations: _modelcontextprotocol_sdk_types_js.Tool["annotations"];
     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> {
+interface DefineToolConfigNone<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> extends DefineToolConfigBase<TIn, TOut, TInputDependencies, TName> {
     connection?: never;
     connections?: never;
     run: (input: z.infer<TIn>, ctx?: ContextNone) => Promise<unknown>;
 }
-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> {
+interface DefineToolConfigSingle<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, 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<unknown>;
 }
-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> {
+interface DefineToolConfigMulti<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, 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<unknown>;
 }
-interface ToolDefinitionBase<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
+interface ToolDefinitionBase<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
     readonly kind: "tool";
     readonly name: TName;
     readonly title: string;
@@ -194,25 +206,25 @@ interface ToolDefinitionBase<TIn extends z.ZodType, TOut extends z.ZodType, TInp
     readonly annotations: _modelcontextprotocol_sdk_types_js.Tool["annotations"];
     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> {
+interface ToolDefinitionNone<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string> extends ToolDefinitionBase<TIn, TOut, TInputDependencies, TName> {
     readonly connection?: undefined;
     readonly connections?: undefined;
     run: (input: z.infer<TIn>, ctx?: ContextNone) => 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> {
+interface ToolDefinitionSingle<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, 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> {
+interface ToolDefinitionMulti<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, 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>;
+type ToolDefinition<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, 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"> & {
+type AnyToolDefinition = Omit<ToolDefinitionBase<z.ZodObject<z.ZodRawShape>, z.ZodObject<z.ZodRawShape>, any, string>, "run" | "inputDependencies"> & {
     inputDependencies: AnyInputDependencies$1 | undefined;
     run: AnyToolDefinitionRun;
     readonly connection?: string | undefined;
@@ -445,9 +457,9 @@ declare function defineConnector<TScripts extends Record<string, AnyDef>, const
  */
 
 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>;
+declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, 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.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, 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.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, 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

package/dist/index.d.ts

@@ -50,6 +50,12 @@ type EnvFromKey<K extends string> = Uppercase<Replace<K, "-", "_">>;
 interface SingleConnectionResolver<TName extends string = string> {
     readonly name: TName;
     readonly keySuffixes?: undefined;
+    /**
+     * npm package names that must be installed for this resolver to function
+     * at runtime. Declared here so `--help` can check availability and tell
+     * the agent which packages to install before using this resolver.
+     */
+    readonly optionalPackages?: readonly string[];
     resolve: (credential: string) => typeof globalThis.fetch | Promise<typeof globalThis.fetch>;
 }
 /**
@@ -68,6 +74,12 @@ interface SingleConnectionResolver<TName extends string = string> {
 interface MultiConnectionResolver<TName extends string = string, TSuffixes extends readonly string[] = readonly string[]> {
     readonly name: TName;
     readonly keySuffixes: TSuffixes;
+    /**
+     * npm package names that must be installed for this resolver to function
+     * at runtime. Declared here so `--help` can check availability and tell
+     * the agent which packages to install before using this resolver.
+     */
+    readonly optionalPackages?: readonly string[];
     resolve: (credentials: Record<TSuffixes[number], string>) => typeof globalThis.fetch | Promise<typeof globalThis.fetch>;
 }
 /** Either resolver shape. */
@@ -160,7 +172,7 @@ interface ContextMulti<TSlots extends string = string> {
 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> {
+interface DefineToolConfigBase<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
     name: TName;
     title: string;
     description: string;
@@ -169,22 +181,22 @@ interface DefineToolConfigBase<TIn extends z.ZodType, TOut extends z.ZodType, TI
     annotations: _modelcontextprotocol_sdk_types_js.Tool["annotations"];
     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> {
+interface DefineToolConfigNone<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> extends DefineToolConfigBase<TIn, TOut, TInputDependencies, TName> {
     connection?: never;
     connections?: never;
     run: (input: z.infer<TIn>, ctx?: ContextNone) => Promise<unknown>;
 }
-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> {
+interface DefineToolConfigSingle<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, 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<unknown>;
 }
-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> {
+interface DefineToolConfigMulti<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, 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<unknown>;
 }
-interface ToolDefinitionBase<TIn extends z.ZodType, TOut extends z.ZodType, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
+interface ToolDefinitionBase<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, TInputDependencies extends AnyInputDependencies$1 | undefined, TName extends string> {
     readonly kind: "tool";
     readonly name: TName;
     readonly title: string;
@@ -194,25 +206,25 @@ interface ToolDefinitionBase<TIn extends z.ZodType, TOut extends z.ZodType, TInp
     readonly annotations: _modelcontextprotocol_sdk_types_js.Tool["annotations"];
     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> {
+interface ToolDefinitionNone<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TInputDependencies extends AnyInputDependencies$1 | undefined = undefined, TName extends string = string> extends ToolDefinitionBase<TIn, TOut, TInputDependencies, TName> {
     readonly connection?: undefined;
     readonly connections?: undefined;
     run: (input: z.infer<TIn>, ctx?: ContextNone) => 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> {
+interface ToolDefinitionSingle<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, 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> {
+interface ToolDefinitionMulti<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, 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>;
+type ToolDefinition<TIn extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, 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"> & {
+type AnyToolDefinition = Omit<ToolDefinitionBase<z.ZodObject<z.ZodRawShape>, z.ZodObject<z.ZodRawShape>, any, string>, "run" | "inputDependencies"> & {
     inputDependencies: AnyInputDependencies$1 | undefined;
     run: AnyToolDefinitionRun;
     readonly connection?: string | undefined;
@@ -445,9 +457,9 @@ declare function defineConnector<TScripts extends Record<string, AnyDef>, const
  */
 
 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>;
+declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, 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.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, 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.ZodObject<z.ZodRawShape>, TOut extends z.ZodObject<z.ZodRawShape>, 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

package/dist/index.js

@@ -4,6 +4,7 @@ function defineConnectionResolver(resolver) {
 }
 var zapierConnectionResolver = defineConnectionResolver({
   name: "zapier-connection-id",
+  optionalPackages: ["@zapier/zapier-sdk"],
   resolve: async (connectionId) => {
     const { buildZapierFetch } = await import("./build-zapier-fetch-DWCYBAF4.js");
     return buildZapierFetch(connectionId);
@@ -23,6 +24,9 @@ function defineBearerTokenResolver(opts = {}) {
   });
 }
 
+// src/normalize-connections.ts
+import { createRequire } from "module";
+
 // src/connection-key.ts
 function envFromKey(name) {
   return name.toUpperCase().replace(/-/g, "_");
@@ -162,23 +166,70 @@ function buildRunOptionsFromEnv(definition, env, connectionResolvers) {
   }
   return { connections: wrapped };
 }
-function formatHelpForConnections(definition, connectionResolvers) {
+function isPackageInstalled(name) {
+  try {
+    createRequire(import.meta.url).resolve(name);
+    return true;
+  } catch {
+    return false;
+  }
+}
+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;
 }
@@ -816,7 +867,8 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   if (helpRequested) {
     io.stdout.write(
       buildHelpText(wrappedScript, connectionResolvers, {
-        invocation: io.invocation
+        invocation: io.invocation,
+        env: io.env
       })
     );
     return;
@@ -864,7 +916,8 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
   }
   const connectionsBlock = formatHelpForConnections(
     definition,
-    connectionResolvers
+    connectionResolvers,
+    opts.env
   );
   if (connectionsBlock.length > 0) {
     lines.push(...connectionsBlock);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/connectors-sdk",
-  "version": "0.1.0-experimental.5",
+  "version": "0.1.0-experimental.7",
   "description": "SDK for building Zapier connectors. Provides the authoring primitives and execution surfaces for connector scripts.",
   "license": "Elastic-2.0",
   "type": "module",