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

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. */

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. */

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.6",
   "description": "SDK for building Zapier connectors. Provides the authoring primitives and execution surfaces for connector scripts.",
   "license": "Elastic-2.0",
   "type": "module",