@zapier/zapier-sdk-cli 0.70.0 → 0.71.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @zapier/zapier-sdk-cli
 
+## 0.71.1
+
+### Patch Changes
+
+- 0f54b24: CLI commands with an object-typed parameter (e.g. `run-durable`'s `<source-files>`, or an array-of-object parameter like its `notifications`) now reject invalid input with a clear error naming the parameter, instead of silently passing it through to a confusing downstream validation error like `expected record, received string`:
+  - A string that isn't valid JSON reports the parse failure. A value that looks like a file path (contains a slash or ends in `.ts`/`.js`/`.tsx`/`.jsx`/`.json`) gets an additional hint that a JSON value was expected, not a path on disk.
+  - A string that parses as valid JSON but isn't an object (e.g. `42`, `true`, `null`) is also rejected, since it can never satisfy an object-shaped parameter.
+
+- Updated dependencies [59a8180]
+  - @zapier/zapier-sdk@0.94.1
+  - @zapier/zapier-sdk-mcp@0.19.1
+
+## 0.71.0
+
+### Minor Changes
+
+- d700196: Added `createActionRun` and `getActionRun`, the two halves of `runAction` as separately callable methods:
+  - `createActionRun({ app, actionType, action, connection?, inputs?, page?, callbackUrl? })` — starts an action run and returns `{ id, implementation_id }` right away, without waiting for it to finish. `implementation_id` is the versioned implementation the run was started against, matching `implementation_id` on an app from `getApp` / `listApps`.
+  - `getActionRun({ run })` — returns that run's state: `{ id, status, results, errors, next_page? }`. It is a point-in-time read that answers immediately, so a run that is still executing comes back with `status: "waiting"` and it is up to the caller to check again. Unlike `runAction`, a failed run is reported as `status: "error"` with the details in `errors` rather than thrown.
+
+  To page a bulk read, pass the `next_page` from `getActionRun` back as the `page` for the next `createActionRun`. The pair uses the same page terminology in both directions, and `next_page` is always a string so it can be handed straight back. `runAction` is a paginated list method, so it keeps the SDK's usual `cursor` / `nextCursor` pair.
+
+  Pass `callbackUrl` to `createActionRun` to skip polling altogether: Zapier posts the finished run to that URL. It must use HTTPS and resolve to a public host. The delivered body matches what `getActionRun` returns, and carries a `Zapier-Callback-Signature` header holding an RS256 JWT you can verify against `https://zapier.com/.well-known/jwks.json`. Delivery is retried, so the same run can arrive more than once.
+
+  `runAction` is unchanged and is still the right call for most cases — it starts a run and waits for the result in one step. Reach for the pair when you don't want to block on the result: fan out many runs and collect them later, hand a run ID to another process, or pick a run back up after a restart. Run results are retained for seven days.
+
+### Patch Changes
+
+- Updated dependencies [d700196]
+  - @zapier/zapier-sdk@0.94.0
+  - @zapier/zapier-sdk-mcp@0.19.0
+
 ## 0.70.0
 
 ### Minor Changes

package/README.md

@@ -13,8 +13,10 @@
   - [`logout`](#logout)
   - [`signup`](#signup)
 - [Actions](#actions)
+  - [`create-action-run`](#create-action-run)
   - [`get-action`](#get-action)
   - [`get-action-input-fields-schema`](#get-action-input-fields-schema)
+  - [`get-action-run`](#get-action-run)
   - [`list-action-input-field-choices`](#list-action-input-field-choices)
   - [`list-action-input-fields`](#list-action-input-fields)
   - [`list-actions`](#list-actions)
@@ -264,6 +266,28 @@ npx zapier-sdk signup [--timeout] [--use-approvals] [--non-interactive] [--headl
 
 ### Actions
 
+#### `create-action-run`
+
+Start an action run and return its ID without waiting for the result. Running an action is asynchronous: this hands back a run ID immediately, and `getActionRun` fetches the outcome. Reach for this pair when you want to start work and collect it later (fan out many runs, hand the ID to another process, survive a restart). `runAction` is the one-call form that starts a run and waits for its result.
+
+**Options:**
+
+| Option           | Type             | Required | Default | Possible Values                                                                                | Description                                                                                                                                                                                                                                                                                              |
+| ---------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<app>`          | `string`         | ✅       | —       | —                                                                                              | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3')                                                                                                                                                                                             |
+| `<action-type>`  | `string`         | ✅       | —       | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Action type that matches the action's defined type                                                                                                                                                                                                                                                       |
+| `<action>`       | `string`         | ✅       | —       | —                                                                                              | Action key (e.g., 'send_message' or 'find_row')                                                                                                                                                                                                                                                          |
+| `--connection`   | `string, number` | ❌       | —       | —                                                                                              | Connection alias or connection ID (UUID or positive integer). Required if the action needs a connection to authenticate and interact with the service. Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly.                 |
+| `--inputs`       | `object`         | ❌       | —       | —                                                                                              | Input parameters for the action                                                                                                                                                                                                                                                                          |
+| `--page`         | `string`         | ❌       | —       | —                                                                                              | Page to fetch for bulk read actions. Pass the `next_page` a previous run returned to fetch the following page.                                                                                                                                                                                           |
+| `--callback-url` | `string`         | ❌       | —       | —                                                                                              | URL Zapier posts the finished run to, so you do not have to poll for it. Must use HTTPS and resolve to a public host, so a local receiver needs a tunnel. The body matches what `getActionRun` returns. Verify the `Zapier-Callback-Signature` header, and expect the same run to arrive more than once. |
+
+**Usage:**
+
+```bash
+npx zapier-sdk create-action-run <app> <action-type> <action> [--connection] [--inputs] [--page] [--callback-url]
+```
+
 #### `get-action`
 
 Get detailed information about a specific action
@@ -302,6 +326,22 @@ Get the JSON Schema representation of input fields for an action. Returns a JSON
 npx zapier-sdk get-action-input-fields-schema <app> <action-type> <action> [--connection] [--inputs]
 ```
 
+#### `get-action-run`
+
+Fetch the current state of an action run started by `createActionRun`. This is a point-in-time read that returns immediately: a run Zapier has not finished executing comes back with status `waiting`, so call again to check for a result. `runAction` starts a run and waits for its result in one call. Results are stored for seven days after the run was created.
+
+**Options:**
+
+| Option  | Type     | Required | Default | Possible Values | Description                                 |
+| ------- | -------- | -------- | ------- | --------------- | ------------------------------------------- |
+| `<run>` | `string` | ✅       | —       | —               | Action run ID returned by `createActionRun` |
+
+**Usage:**
+
+```bash
+npx zapier-sdk get-action-run <run>
+```
+
 #### `list-action-input-field-choices`
 
 Get the available choices for a dynamic dropdown input field

package/dist/cli.cjs

@@ -602,7 +602,7 @@ var SHARED_COMMAND_CLI_OPTIONS = [
 
 // package.json
 var package_default = {
-  version: "0.70.0"};
+  version: "0.71.1"};
 var PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
 var LOCKFILES = [
   ["pnpm-lock.yaml", "pnpm"],
@@ -1982,7 +1982,8 @@ function convertCliArgsToSdkParams(parameters, positionalArgs, options) {
       sdkParams[param.name] = convertValue(
         positionalValue,
         param.type,
-        param.elementType
+        param.elementType,
+        param.name
       );
     }
   });
@@ -2005,7 +2006,12 @@ function convertCliArgsToSdkParams(parameters, positionalArgs, options) {
       if (param.type === "array" && Array.isArray(value) && value.length === 0) {
         return;
       }
-      sdkParams[camelKey] = convertValue(value, param.type, param.elementType);
+      sdkParams[camelKey] = convertValue(
+        value,
+        param.type,
+        param.elementType,
+        param.name
+      );
     }
   });
   return sdkParams;
@@ -2020,7 +2026,28 @@ function parseCliBoolean(value) {
     `Expected a boolean (true or false), received "${value}".`
   );
 }
-function convertValue(value, type, elementType) {
+function looksLikeFilePath(value) {
+  return /[/\\]/.test(value) || /\.(ts|js|tsx|jsx|json)$/i.test(value);
+}
+function parseJsonParameter(value, paramName) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    const parseErrorMessage = error instanceof Error ? error.message : String(error);
+    const pathHint = looksLikeFilePath(value) ? ` "${value}" looks like a file path \u2014 this parameter expects a JSON value (e.g. an object), not a path on disk.` : "";
+    throw new commander.InvalidArgumentError(
+      `Parameter "${paramName}" expects JSON, but the value could not be parsed: ${parseErrorMessage}.${pathHint}`
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new commander.InvalidArgumentError(
+      `Parameter "${paramName}" expects a JSON object, but got: ${value}.`
+    );
+  }
+  return parsed;
+}
+function convertValue(value, type, elementType, paramName) {
   if (value === void 0) {
     return void 0;
   }
@@ -2033,12 +2060,8 @@ function convertValue(value, type, elementType) {
       const arr = Array.isArray(value) ? value : [value];
       if (elementType !== "object") return arr;
       return arr.flatMap((item) => {
-        if (typeof item === "string" && (item.startsWith("{") || item.startsWith("["))) {
-          try {
-            return JSON.parse(item);
-          } catch {
-            return item;
-          }
+        if (typeof item === "string") {
+          return parseJsonParameter(item, paramName ?? "value");
         }
         return item;
       });
@@ -2047,11 +2070,7 @@ function convertValue(value, type, elementType) {
       return value;
     case "object":
       if (typeof value === "string") {
-        try {
-          return JSON.parse(value);
-        } catch {
-          return value;
-        }
+        return parseJsonParameter(value, paramName ?? "value");
       }
       return value;
     default:
@@ -8341,7 +8360,7 @@ function buildBoxLines(message) {
 // package.json with { type: 'json' }
 var package_default2 = {
   name: "@zapier/zapier-sdk-cli",
-  version: "0.70.0"};
+  version: "0.71.1"};
 
 // src/sdk.ts
 var warnedDeprecatedMethods = /* @__PURE__ */ new Set();

package/dist/cli.mjs

@@ -558,7 +558,7 @@ var SHARED_COMMAND_CLI_OPTIONS = [
 
 // package.json
 var package_default = {
-  version: "0.70.0"};
+  version: "0.71.1"};
 var PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
 var LOCKFILES = [
   ["pnpm-lock.yaml", "pnpm"],
@@ -1938,7 +1938,8 @@ function convertCliArgsToSdkParams(parameters, positionalArgs, options) {
       sdkParams[param.name] = convertValue(
         positionalValue,
         param.type,
-        param.elementType
+        param.elementType,
+        param.name
       );
     }
   });
@@ -1961,7 +1962,12 @@ function convertCliArgsToSdkParams(parameters, positionalArgs, options) {
       if (param.type === "array" && Array.isArray(value) && value.length === 0) {
         return;
       }
-      sdkParams[camelKey] = convertValue(value, param.type, param.elementType);
+      sdkParams[camelKey] = convertValue(
+        value,
+        param.type,
+        param.elementType,
+        param.name
+      );
     }
   });
   return sdkParams;
@@ -1976,7 +1982,28 @@ function parseCliBoolean(value) {
     `Expected a boolean (true or false), received "${value}".`
   );
 }
-function convertValue(value, type, elementType) {
+function looksLikeFilePath(value) {
+  return /[/\\]/.test(value) || /\.(ts|js|tsx|jsx|json)$/i.test(value);
+}
+function parseJsonParameter(value, paramName) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    const parseErrorMessage = error instanceof Error ? error.message : String(error);
+    const pathHint = looksLikeFilePath(value) ? ` "${value}" looks like a file path \u2014 this parameter expects a JSON value (e.g. an object), not a path on disk.` : "";
+    throw new InvalidArgumentError(
+      `Parameter "${paramName}" expects JSON, but the value could not be parsed: ${parseErrorMessage}.${pathHint}`
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new InvalidArgumentError(
+      `Parameter "${paramName}" expects a JSON object, but got: ${value}.`
+    );
+  }
+  return parsed;
+}
+function convertValue(value, type, elementType, paramName) {
   if (value === void 0) {
     return void 0;
   }
@@ -1989,12 +2016,8 @@ function convertValue(value, type, elementType) {
       const arr = Array.isArray(value) ? value : [value];
       if (elementType !== "object") return arr;
       return arr.flatMap((item) => {
-        if (typeof item === "string" && (item.startsWith("{") || item.startsWith("["))) {
-          try {
-            return JSON.parse(item);
-          } catch {
-            return item;
-          }
+        if (typeof item === "string") {
+          return parseJsonParameter(item, paramName ?? "value");
         }
         return item;
       });
@@ -2003,11 +2026,7 @@ function convertValue(value, type, elementType) {
       return value;
     case "object":
       if (typeof value === "string") {
-        try {
-          return JSON.parse(value);
-        } catch {
-          return value;
-        }
+        return parseJsonParameter(value, paramName ?? "value");
       }
       return value;
     default:
@@ -8297,7 +8316,7 @@ function buildBoxLines(message) {
 // package.json with { type: 'json' }
 var package_default2 = {
   name: "@zapier/zapier-sdk-cli",
-  version: "0.70.0"};
+  version: "0.71.1"};
 
 // src/sdk.ts
 var warnedDeprecatedMethods = /* @__PURE__ */ new Set();

package/dist/experimental.cjs

@@ -6861,7 +6861,7 @@ function collectDeprecationNoticeAndForward(event, onEvent) {
 // package.json with { type: 'json' }
 var package_default = {
   name: "@zapier/zapier-sdk-cli",
-  version: "0.70.0"};
+  version: "0.71.1"};
 
 // src/sdk.ts
 var warnedDeprecatedMethods = /* @__PURE__ */ new Set();

package/dist/experimental.mjs

@@ -6820,7 +6820,7 @@ function collectDeprecationNoticeAndForward(event, onEvent) {
 // package.json with { type: 'json' }
 var package_default = {
   name: "@zapier/zapier-sdk-cli",
-  version: "0.70.0"};
+  version: "0.71.1"};
 
 // src/sdk.ts
 var warnedDeprecatedMethods = /* @__PURE__ */ new Set();

package/dist/index.cjs

@@ -6862,7 +6862,7 @@ function collectDeprecationNoticeAndForward(event, onEvent) {
 // package.json with { type: 'json' }
 var package_default = {
   name: "@zapier/zapier-sdk-cli",
-  version: "0.70.0"};
+  version: "0.71.1"};
 
 // src/sdk.ts
 var warnedDeprecatedMethods = /* @__PURE__ */ new Set();
@@ -6946,7 +6946,7 @@ function createZapierCliSdk(options = {}) {
 
 // package.json
 var package_default2 = {
-  version: "0.70.0"};
+  version: "0.71.1"};
 
 // src/telemetry/builders.ts
 function createCliBaseEvent(context = {}) {

package/dist/index.mjs

@@ -6821,7 +6821,7 @@ function collectDeprecationNoticeAndForward(event, onEvent) {
 // package.json with { type: 'json' }
 var package_default = {
   name: "@zapier/zapier-sdk-cli",
-  version: "0.70.0"};
+  version: "0.71.1"};
 
 // src/sdk.ts
 var warnedDeprecatedMethods = /* @__PURE__ */ new Set();
@@ -6905,7 +6905,7 @@ function createZapierCliSdk(options = {}) {
 
 // package.json
 var package_default2 = {
-  version: "0.70.0"};
+  version: "0.71.1"};
 
 // src/telemetry/builders.ts
 function createCliBaseEvent(context = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/zapier-sdk-cli",
-  "version": "0.70.0",
+  "version": "0.71.1",
   "description": "Command line interface for Zapier SDK",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -95,8 +95,8 @@
     "typescript": "^5.8.3",
     "wrap-ansi": "^10.0.0",
     "zod": "4.3.6",
-    "@zapier/zapier-sdk": "0.93.0",
-    "@zapier/zapier-sdk-mcp": "0.18.23"
+    "@zapier/zapier-sdk": "0.94.1",
+    "@zapier/zapier-sdk-mcp": "0.19.1"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",