@zapier/zapier-sdk-cli 0.44.0 → 0.45.0

package/dist/src/utils/cli-generator.js

@@ -224,6 +224,17 @@ function analyzeZodField(name, schema, functionInfo) {
             break;
         }
     }
+    // Some schema kinds aren't expressible as CLI flags and would
+    // otherwise fall through to a bogus `--name <string>` flag:
+    //   - z.function() — onMessage / onError-style callbacks
+    //   - z.custom<AbortSignal>() and other custom predicates — passed
+    //     programmatically by callers, or filled in by a CLI-side
+    //     decorator plugin (closure-capture + override).
+    // Skip them so the auto-generated CLI surface stays clean.
+    const baseSchemaDef = baseSchema._zod?.def;
+    if (baseSchema instanceof z.ZodFunction || baseSchemaDef?.type === "custom") {
+        return null;
+    }
     // Determine parameter type
     let paramType = "string";
     let elementType;
@@ -448,9 +459,15 @@ function createCommandConfig(cliCommandName, functionInfo, sdk) {
             }
         }
     }
-    const description = functionInfo.description ||
+    const baseDescription = functionInfo.description ||
         schema?.description ||
         `${cliCommandName} command`;
+    // Mark experimental commands clearly in --help so users know what they're
+    // touching. The command only reaches here at all when the experimental SDK
+    // factory is loaded, so we don't need to gate help visibility separately.
+    const description = functionInfo.experimental
+        ? `${baseDescription} (experimental)`
+        : baseDescription;
     const handler = async (...args) => {
         const startTime = Date.now();
         let success = true;

package/dist/src/utils/cli-renderer.d.ts

@@ -25,6 +25,18 @@ export interface CliRenderer {
     renderError(error: unknown): never;
 }
 export declare function buildJsonErrors(error: unknown): JsonErrorEntry[];
+/**
+ * Replacer for JSON.stringify that coerces Error instances to a plain
+ * object with `{ name, message, stack }`. Without this, `JSON.stringify`
+ * renders an Error as `{}` (its useful properties are non-enumerable),
+ * which surfaces in any command that returns Error-like values — most
+ * notably `drainTriggerInbox` whose `errors[].reason` is typed `unknown`
+ * and is usually an Error.
+ *
+ * Walks recursively because the replacer is invoked for every nested
+ * key/value pair, not just the top-level value.
+ */
+export declare function jsonReplacer(_key: string, value: unknown): unknown;
 export declare function createJsonRenderer(): CliRenderer;
 export declare function createInteractiveRenderer(): CliRenderer;
 export {};

package/dist/src/utils/cli-renderer.js

@@ -50,8 +50,29 @@ async function unwrapHttpResponse(response) {
 // ============================================================================
 // JSON renderer
 // ============================================================================
+/**
+ * Replacer for JSON.stringify that coerces Error instances to a plain
+ * object with `{ name, message, stack }`. Without this, `JSON.stringify`
+ * renders an Error as `{}` (its useful properties are non-enumerable),
+ * which surfaces in any command that returns Error-like values — most
+ * notably `drainTriggerInbox` whose `errors[].reason` is typed `unknown`
+ * and is usually an Error.
+ *
+ * Walks recursively because the replacer is invoked for every nested
+ * key/value pair, not just the top-level value.
+ */
+export function jsonReplacer(_key, value) {
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: value.message,
+            ...(value.stack ? { stack: value.stack } : {}),
+        };
+    }
+    return value;
+}
 function outputJson(envelope) {
-    console.log(JSON.stringify(envelope, null, 2));
+    console.log(JSON.stringify(envelope, jsonReplacer, 2));
 }
 export function createJsonRenderer() {
     return {

package/dist/src/utils/parameter-resolver.d.ts

@@ -64,4 +64,5 @@ export declare class SchemaParameterResolver {
     private hasResolver;
     private getResolver;
     private getLocalResolvers;
+    private getResolverConstants;
 }

package/dist/src/utils/parameter-resolver.js

@@ -24,7 +24,7 @@ function formatZodError(error) {
  */
 function getLocalResolutionOrder(paramName, resolvers, resolved = new Set()) {
     const resolver = resolvers[paramName];
-    if (!resolver || resolver.type === "static") {
+    if (!resolver || resolver.type === "static" || resolver.type === "constant") {
         return [paramName];
     }
     const order = [];
@@ -119,7 +119,16 @@ export class SchemaParameterResolver {
                 return parseResult.data;
             }
             // 2. Resolve required parameters
-            const resolvedParams = { ...providedParams };
+            // Seed resolvedParams with constant resolvers — entries in `resolvers`
+            // typed `{ type: "constant", value }` for parameters not in the schema.
+            // Used when a dependent resolver needs a value the user never sets
+            // (e.g., trigger plugins pin actionType="read" so actionKeyResolver
+            // and inputsResolver work without actionType being a real input).
+            const resolverConstants = this.getResolverConstants(sdk, functionName);
+            const resolvedParams = {
+                ...resolverConstants,
+                ...providedParams,
+            };
             const context = {
                 sdk,
                 currentParams: providedParams,
@@ -263,11 +272,17 @@ export class SchemaParameterResolver {
         const missingParams = [];
         for (const param of params) {
             const resolver = this.getResolver(param.name, context.sdk, functionName);
-            const autoResolution = resolver?.type === "dynamic"
-                ? await this.tryAutoResolve(resolver, context)
-                : null;
-            if (autoResolution != null) {
-                this.setNestedValue(resolvedParams, param.path, autoResolution.resolvedValue);
+            let autoResolved = null;
+            if (resolver?.type === "constant") {
+                autoResolved = {
+                    resolvedValue: resolver.value,
+                };
+            }
+            else if (resolver?.type === "dynamic") {
+                autoResolved = await this.tryAutoResolve(resolver, context);
+            }
+            if (autoResolved != null) {
+                this.setNestedValue(resolvedParams, param.path, autoResolved.resolvedValue);
                 context.resolvedParams = resolvedParams;
             }
             else {
@@ -299,7 +314,12 @@ export class SchemaParameterResolver {
             : param.name;
         const promptName = inArrayContext ? "value" : param.name;
         this.debugLog(`Resolving ${promptLabel}${isOptional ? " (optional)" : ""}`);
-        if (resolver.type === "static") {
+        if (resolver.type === "constant") {
+            const constantResolver = resolver;
+            this.stopSpinner();
+            return constantResolver.value;
+        }
+        else if (resolver.type === "static") {
             const staticResolver = resolver;
             const promptConfig = {
                 type: staticResolver.inputType === "password" ? "password" : "input",
@@ -370,6 +390,15 @@ export class SchemaParameterResolver {
             while (true) {
                 const promptConfig = dynamicResolver.prompt(items, context.resolvedParams);
                 promptConfig.name = promptName;
+                // Friendlier than inquirer's default "No selectable choices. All
+                // choices are disabled." when the resolver returns no items (or
+                // filters everything out in `prompt`). Use ZapierCliValidationError
+                // so the message renders to the user; ZapierCliExitError exits
+                // silently and would be confusing here.
+                const hasSelectableChoice = promptConfig.choices?.some((c) => !c.disabled);
+                if (!hasSelectableChoice && !hasMore) {
+                    throw new ZapierCliValidationError(`No ${promptLabel} available to select.`);
+                }
                 if (isOptional && promptConfig.choices) {
                     promptConfig.choices.unshift({
                         name: chalk.dim("(Skip)"),
@@ -711,7 +740,7 @@ export class SchemaParameterResolver {
                 ? `Fetching more choices for ${fieldMeta.title}`
                 : `Fetching choices for ${fieldMeta.title}`);
             this.startSpinner();
-            const page = await context.sdk.listInputFieldChoices({
+            const page = await context.sdk.listActionInputFieldChoices({
                 app: context.resolvedParams.app,
                 action: context.resolvedParams.action,
                 actionType: context.resolvedParams.actionType,
@@ -956,4 +985,21 @@ export class SchemaParameterResolver {
         const functionInfo = registry.functions.find((f) => f.name === functionName);
         return functionInfo?.resolvers || {};
     }
+    getResolverConstants(sdk, functionName) {
+        if (!functionName || typeof sdk.getRegistry !== "function") {
+            return {};
+        }
+        const registry = sdk.getRegistry();
+        const functionInfo = registry.functions.find((f) => f.name === functionName);
+        const resolvers = functionInfo?.resolvers ?? {};
+        const constants = {};
+        for (const [key, resolver] of Object.entries(resolvers)) {
+            if (resolver &&
+                typeof resolver === "object" &&
+                resolver.type === "constant") {
+                constants[key] = resolver.value;
+            }
+        }
+        return constants;
+    }
 }

package/dist/src/utils/triggerDrain.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Shared CLI helpers for the `drain-trigger-inbox` and
+ * `watch-trigger-inbox` commands. Both wrap the eager SDK callback API
+ * and dispatch on the same flag set: interactive default (TTY),
+ * `--exec` (binary + argv, no shell), `--exec-shell` (shell handler),
+ * `--json` (drain: collect-and-print; watch: NDJSON streaming).
+ */
+import { type LeasedTriggerMessageItem } from "@zapier/zapier-sdk";
+export type Callback = (message: LeasedTriggerMessageItem) => Promise<void>;
+/**
+ * Marker error thrown by `createInteractiveCallback` when the user
+ * picks "Skip (let lease expire)". The SDK treats it like any other
+ * Error subclass — leave-leased per default `releaseOnError: false`
+ * — so the lease-timeout recovery path is preserved. The CLI uses
+ * the marker type to distinguish a deliberate skip from an unhandled
+ * exception when counting summary lines. Not a `ZapierSignal`: the
+ * SDK's signal-handling auto-releases the message, which is exactly
+ * what skip-expire does *not* want.
+ */
+export declare class CliSkipLeaseExpireError extends Error {
+    readonly name = "CliSkipLeaseExpireError";
+    constructor();
+}
+/**
+ * Prompts the user per message. Choices:
+ *
+ * - **Ack**: returns normally so the SDK acks the message.
+ * - **Skip (release after draining)**: throws
+ *   `ZapierReleaseTriggerMessageSignal`. The SDK marks the message for
+ *   release; the actual release call is deferred until the drain
+ *   finishes so the same drain doesn't immediately re-lease it. After
+ *   drain ends, the message returns to `available` for a future drain
+ *   run or another consumer.
+ * - **Skip (let lease expire)**: throws `CliSkipLeaseExpireError` so
+ *   the SDK leaves the message leased (it's not a `ZapierSignal`,
+ *   so the SDK's catch-all "leave on error" path applies); the lease
+ *   timeout (~5 min default) is the recovery path. Use this when you
+ *   want backpressure on reprocessing. The CLI catches the marker
+ *   to count it as a skip in the drain summary.
+ * - **Quit**: throws `ZapierAbortDrainSignal` so the SDK stops draining
+ *   after the current batch finishes (in-flight callbacks complete;
+ *   not-yet-started messages in the batch are released).
+ *
+ * Ctrl-C during the prompt is translated to `ZapierAbortDrainSignal`
+ * (same as Quit) — inquirer raises `ExitPromptError`, which we catch
+ * and re-throw as the abort signal.
+ */
+export declare function createInteractiveCallback(): Callback;
+/**
+ * Writes one JSON object per line to stdout (NDJSON) for piping. Acks
+ * each message after the write resolves; if stdout is closed mid-drain
+ * (broken pipe), the write throws and the message stays unacked.
+ *
+ * The write callback alone provides backpressure: it doesn't fire until
+ * the chunk is fully committed to the underlying resource, so awaiting
+ * it pauses the drain when stdout is busy. No separate `drain` listener
+ * needed — and adding one would race with the callback (drain fires at
+ * highWaterMark, callback fires after full commit; if drain wins, the
+ * later callback's error gets dropped on the floor).
+ */
+export declare function createNdjsonCallback(): Callback;
+export declare function runShellCommand(command: string, message: LeasedTriggerMessageItem, signal?: AbortSignal): Promise<void>;
+/**
+ * Run a binary per message with no shell interpretation. `argv[0]` is
+ * the executable; the rest are passed literally as argv to the child.
+ * Otherwise identical to `runShellCommand`: stdin = message JSON, exit
+ * code 0 acks, non-zero rejects, abort signal kills the child.
+ */
+export declare function runExecCommand(argv: string[], message: LeasedTriggerMessageItem, signal?: AbortSignal): Promise<void>;
+/**
+ * Print a single per-message error to stderr. Used as the live
+ * `onError` body so failures surface as they happen (vs accumulated
+ * and dumped at the end, which is broken for `watch-trigger-inbox`
+ * where "the end" is Ctrl-C).
+ */
+export declare function printDrainError(reason: unknown, message: LeasedTriggerMessageItem): void;
+/**
+ * One-line summary printed when the CLI finished a drain in a mode
+ * where the data array is uninformative (interactive, exec, exec-shell).
+ * Both the bounded and forever variants use the same format.
+ *
+ * `skipped` is the interactive-mode count of user-driven Skip choices
+ * (release-after-draining + let-lease-expire). Omitted when zero so the
+ * subprocess modes — which have no skip semantics — keep their original
+ * two-part summary.
+ */
+export declare function printDrainSummary(counts: {
+    fulfilled: number;
+    rejected: number;
+    skipped?: number;
+}): void;
+/**
+ * Warn on stderr that interactive mode is overriding an explicit
+ * `continueOnError: false`. Only fires when the caller (programmatic
+ * SDK consumer or future flag form that takes `=false`) opted into
+ * fail-fast — bare `--continue-on-error` flag absence leaves it
+ * `undefined` and doesn't trigger this. Interactive mode mechanically
+ * requires continue-on-error: the "Skip (let lease expire)" choice
+ * throws a plain Error to leave the message leased, and a fail-fast
+ * drain would tear down on the first skip.
+ */
+export declare function warnInteractiveContinueOnErrorOverride(): void;
+/**
+ * Throw a CliValidationError if the current process isn't attached to
+ * a real terminal on both stdin and stdout. Used by the interactive
+ * default to fail fast with a useful message instead of letting
+ * inquirer fall over later.
+ */
+export declare function requireInteractiveTty(commandName: string): void;
+/**
+ * Reject more than one of `--exec`, `--exec-shell`, and `--json`.
+ * Each is a non-interactive output path and choosing implicitly is
+ * ambiguous.
+ */
+export declare function rejectExecJsonMutex(opts: {
+    exec?: unknown;
+    execShell?: unknown;
+    json?: unknown;
+}): void;
+/**
+ * Pull argv tokens after the first `--` separator out of `process.argv`.
+ * Returns `[]` when there's no `--`. Used by drain/watch to append
+ * post-`--` args to the `--exec` binary, mirroring `xargs`, `gh`, and
+ * `npm run -- ...` semantics.
+ *
+ * Read from `process.argv` rather than threading via cli-generator
+ * because Commander already consumes `--` at parse time and there's
+ * no per-command API for "the args after `--`" exposed through the
+ * SDK options object.
+ */
+export declare function getPostDashArgs(argv?: string[]): string[];
+/**
+ * Combine an optional user signal with an internal one (typically the
+ * SIGINT controller) into a single AbortSignal that fires when either
+ * source aborts. Returns a `dispose` to detach the listeners; safe to
+ * call regardless of whether the combined signal fired.
+ *
+ * Plain shape rather than the SDK's `combineAbortSignals`, which works
+ * over `DisposableAbortSignal` handles and returns a different shape.
+ */
+export declare function combineSignals(a: AbortSignal | undefined, b: AbortSignal): {
+    signal: AbortSignal;
+    dispose: () => void;
+};