@zapier/connectors-sdk 0.1.0-experimental.12 → 0.1.0-experimental.13

package/dist/index.cjs

@@ -1050,8 +1050,8 @@ async function resolvePackageName(meta) {
 function printUsage(scripts, out, packageName) {
   const names = Object.keys(scripts);
   out.write(
-    `Usage: <bin> run <script> [<json-input>]
-       <bin> run <script> --help    (per-script input + required env vars)
+    `Usage: <bin> run <script> [<json-input>] [--filter <jq>]
+       <bin> run <script> --help    (per-script input/output schema, env vars, --filter)
        <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)
@@ -1080,7 +1080,7 @@ function printUsage(scripts, out, packageName) {
   }
   out.write(
     `
-Credentials are environment-variable only \u2014 run \`<bin> run <script> --help\` to list each script's required env vars.
+Run \`<bin> run <script> --help\` for a script's input/output schema, its required env vars (credentials are environment-variable only), and the \`--filter <jq>\` flag for trimming output.
 `
   );
 }
@@ -1156,12 +1156,31 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   const args = io.argv.slice(2);
   let positional;
   let helpRequested = false;
-  for (const arg of args) {
+  let filter;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     if (arg === "--help" || arg === "-h") {
       helpRequested = true;
+    } else if (arg === "--filter") {
+      const value = args[i + 1];
+      if (value === void 0 || value.length === 0) {
+        throw new Error(
+          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
+        );
+      }
+      filter = value;
+      i++;
+    } else if (arg.startsWith("--filter=")) {
+      const value = arg.slice("--filter=".length);
+      if (value.length === 0) {
+        throw new Error(
+          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
+        );
+      }
+      filter = value;
     } else if (arg.startsWith("--")) {
       throw new Error(
-        `Unknown flag "${arg}". The per-script CLI accepts only \`--help\` and a positional JSON-encoded input. Credentials are env-only \u2014 set the resolver's required env vars (run with \`--help\` to list them).`
+        `Unknown flag "${arg}". The per-script CLI accepts \`--help\`, \`--filter <jq>\`, and a positional JSON-encoded input. Credentials are env-only \u2014 set the resolver's required env vars (run with \`--help\` to list them).`
       );
     } else if (positional === void 0) {
       positional = arg;
@@ -1206,7 +1225,12 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
     }
   }
   const result = await wrappedScript.run(input, runOpts);
-  io.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  const output = filter === void 0 ? result : await applyJqFilter(result, filter);
+  io.stdout.write(JSON.stringify(output, null, 2) + "\n");
+}
+async function applyJqFilter(value, filter) {
+  const { json: runJq } = await import("jq-wasm");
+  return runJq(value, filter);
 }
 async function readStdinInput(stdin, scriptName) {
   if (stdin.isTTY) {
@@ -1225,11 +1249,19 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
   lines.push("");
   lines.push("Usage:");
   if (opts.invocation) {
-    lines.push(`  <bin> run ${opts.invocation.scriptName} '<json-input>'`);
+    lines.push(
+      `  <bin> run ${opts.invocation.scriptName} '<json-input>' [--filter <jq>]`
+    );
   } else {
-    lines.push(`  <bin> '<json-input>'`);
+    lines.push(`  <bin> '<json-input>' [--filter <jq>]`);
   }
   lines.push("");
+  lines.push(
+    "  --filter <jq>  Transform the JSON output through a jq expression."
+  );
+  lines.push("                 Useful for trimming large outputs, e.g.");
+  lines.push("                 --filter '.results | length'.");
+  lines.push("");
   if (opts.invocation) {
     lines.push("Example:");
     lines.push(
@@ -1254,6 +1286,11 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
     lines.push(...inputBlock);
     lines.push("");
   }
+  const outputBlock = formatHelpForOutput(definition);
+  if (outputBlock.length > 0) {
+    lines.push(...outputBlock);
+    lines.push("");
+  }
   return lines.join("\n");
 }
 function formatExampleCommand(definition, connectionResolvers, invocation) {
@@ -1290,6 +1327,20 @@ function formatHelpForInput(definition) {
   }
   return lines;
 }
+function formatHelpForOutput(definition) {
+  let schema;
+  try {
+    schema = import_zod3.z.toJSONSchema(definition.outputSchema);
+  } catch {
+    return [];
+  }
+  const lines = ["Output (JSON Schema):"];
+  const json = JSON.stringify(schema, null, 2);
+  for (const line of json.split("\n")) {
+    lines.push(`  ${line}`);
+  }
+  return lines;
+}
 
 // src/surfaces/to-functions.ts
 function toFunctions(connector) {

package/dist/index.d.cts

@@ -463,8 +463,9 @@ declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends
  * 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
+ * **Credentials are env-only by design.** The CLI takes positional
+ * JSON (the script's `inputSchema`), `--help`, and `--filter <jq>` (a jq
+ * expression that post-processes the JSON output). Passing secrets via
  * argv would leak them through shell history, `ps`, audit logs, and CI
  * runner echo.
  *

package/dist/index.d.ts

@@ -463,8 +463,9 @@ declare function defineTool<TIn extends z.ZodObject<z.ZodRawShape>, TOut extends
  * 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
+ * **Credentials are env-only by design.** The CLI takes positional
+ * JSON (the script's `inputSchema`), `--help`, and `--filter <jq>` (a jq
+ * expression that post-processes the JSON output). Passing secrets via
  * argv would leak them through shell history, `ps`, audit logs, and CI
  * runner echo.
  *

package/dist/index.js

@@ -944,8 +944,8 @@ async function resolvePackageName(meta) {
 function printUsage(scripts, out, packageName) {
   const names = Object.keys(scripts);
   out.write(
-    `Usage: <bin> run <script> [<json-input>]
-       <bin> run <script> --help    (per-script input + required env vars)
+    `Usage: <bin> run <script> [<json-input>] [--filter <jq>]
+       <bin> run <script> --help    (per-script input/output schema, env vars, --filter)
        <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)
@@ -974,7 +974,7 @@ function printUsage(scripts, out, packageName) {
   }
   out.write(
     `
-Credentials are environment-variable only \u2014 run \`<bin> run <script> --help\` to list each script's required env vars.
+Run \`<bin> run <script> --help\` for a script's input/output schema, its required env vars (credentials are environment-variable only), and the \`--filter <jq>\` flag for trimming output.
 `
   );
 }
@@ -1050,12 +1050,31 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
   const args = io.argv.slice(2);
   let positional;
   let helpRequested = false;
-  for (const arg of args) {
+  let filter;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     if (arg === "--help" || arg === "-h") {
       helpRequested = true;
+    } else if (arg === "--filter") {
+      const value = args[i + 1];
+      if (value === void 0 || value.length === 0) {
+        throw new Error(
+          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
+        );
+      }
+      filter = value;
+      i++;
+    } else if (arg.startsWith("--filter=")) {
+      const value = arg.slice("--filter=".length);
+      if (value.length === 0) {
+        throw new Error(
+          `\`--filter\` requires a jq expression, e.g. \`--filter '.results | length'\`.`
+        );
+      }
+      filter = value;
     } else if (arg.startsWith("--")) {
       throw new Error(
-        `Unknown flag "${arg}". The per-script CLI accepts only \`--help\` and a positional JSON-encoded input. Credentials are env-only \u2014 set the resolver's required env vars (run with \`--help\` to list them).`
+        `Unknown flag "${arg}". The per-script CLI accepts \`--help\`, \`--filter <jq>\`, and a positional JSON-encoded input. Credentials are env-only \u2014 set the resolver's required env vars (run with \`--help\` to list them).`
       );
     } else if (positional === void 0) {
       positional = arg;
@@ -1100,7 +1119,12 @@ async function handleIfScriptMainBody(wrappedScript, connectionResolvers, io) {
     }
   }
   const result = await wrappedScript.run(input, runOpts);
-  io.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  const output = filter === void 0 ? result : await applyJqFilter(result, filter);
+  io.stdout.write(JSON.stringify(output, null, 2) + "\n");
+}
+async function applyJqFilter(value, filter) {
+  const { json: runJq } = await import("jq-wasm");
+  return runJq(value, filter);
 }
 async function readStdinInput(stdin, scriptName) {
   if (stdin.isTTY) {
@@ -1119,11 +1143,19 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
   lines.push("");
   lines.push("Usage:");
   if (opts.invocation) {
-    lines.push(`  <bin> run ${opts.invocation.scriptName} '<json-input>'`);
+    lines.push(
+      `  <bin> run ${opts.invocation.scriptName} '<json-input>' [--filter <jq>]`
+    );
   } else {
-    lines.push(`  <bin> '<json-input>'`);
+    lines.push(`  <bin> '<json-input>' [--filter <jq>]`);
   }
   lines.push("");
+  lines.push(
+    "  --filter <jq>  Transform the JSON output through a jq expression."
+  );
+  lines.push("                 Useful for trimming large outputs, e.g.");
+  lines.push("                 --filter '.results | length'.");
+  lines.push("");
   if (opts.invocation) {
     lines.push("Example:");
     lines.push(
@@ -1148,6 +1180,11 @@ function buildHelpText(definition, connectionResolvers, opts = {}) {
     lines.push(...inputBlock);
     lines.push("");
   }
+  const outputBlock = formatHelpForOutput(definition);
+  if (outputBlock.length > 0) {
+    lines.push(...outputBlock);
+    lines.push("");
+  }
   return lines.join("\n");
 }
 function formatExampleCommand(definition, connectionResolvers, invocation) {
@@ -1184,6 +1221,20 @@ function formatHelpForInput(definition) {
   }
   return lines;
 }
+function formatHelpForOutput(definition) {
+  let schema;
+  try {
+    schema = z3.toJSONSchema(definition.outputSchema);
+  } catch {
+    return [];
+  }
+  const lines = ["Output (JSON Schema):"];
+  const json = JSON.stringify(schema, null, 2);
+  for (const line of json.split("\n")) {
+    lines.push(`  ${line}`);
+  }
+  return lines;
+}
 
 // src/surfaces/to-functions.ts
 function toFunctions(connector) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/connectors-sdk",
-  "version": "0.1.0-experimental.12",
+  "version": "0.1.0-experimental.13",
   "description": "SDK for building Zapier connectors. Provides the authoring primitives and execution surfaces for connector scripts.",
   "license": "Elastic-2.0",
   "type": "module",
@@ -24,6 +24,9 @@
     "README.md",
     "LICENSE"
   ],
+  "dependencies": {
+    "jq-wasm": "1.1.0-jq-1.8.1"
+  },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@zapier/zapier-sdk": "^0.59.0",