@zapier/zapier-sdk 0.94.0 → 0.95.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @zapier/zapier-sdk
 
+## 0.95.0
+
+### Minor Changes
+
+- 80dc74a: Auto-mode approvals that are escalated to a human reviewer now open the approval URL in the browser automatically and continue polling until the reviewer decides.
+- 6e5189c: Added a `manual` option (experimental) to `publishWorkflowVersion`, exposed in the CLI as `--manual` on `publish-workflow-version`. Pass `manual: true` to publish an on-demand, triggerless workflow version explicitly; pass `trigger` for a triggered one. The two are mutually exclusive — sending both is rejected with a 400.
+
+## 0.94.1
+
+### Patch Changes
+
+- 59a8180: `fetch()` now populates`ZapierRelayError.retryable` (boolean) and `ZapierRelayError.errors` (structured error code array) when the proxy provides machine-readable error metadata.
+
 ## 0.94.0
 
 ### Minor Changes

package/README.md

@@ -2019,11 +2019,12 @@ Publish a new version of a durable workflow. Enables the workflow by default.
 | ​ ↳ `ignoreOpenDrafts`     | `boolean` | ❌       | —       | —               | Publish even though the workflow has open draft(s). Without this, the API rejects a direct publish with a 409 while any draft is open, since publishing the draft later would ship its stale content over this version. |
 | ​ ↳ `connections`          | `object`  | ❌       | —       | —               | Map of connection aliases to Zapier connections used by the workflow. Pass `null` to clear an existing binding.                                                                                                         |
 | ​ ↳ `appVersions`          | `object`  | ❌       | —       | —               | Map of app keys to pinned app implementation/version used by the workflow. Pass `null` to clear an existing binding.                                                                                                    |
-| ​ ↳ `trigger`              | `object`  | ❌       | —       | —               | Trigger configuration. When provided, the workflow subscribes to a Zapier trigger; omit for webhook-only workflows.                                                                                                     |
+| ​ ↳ `trigger`              | `object`  | ❌       | —       | —               | Trigger configuration. When provided, the workflow subscribes to a Zapier trigger; for an on-demand, triggerless workflow, omit this and pass `manual: true` instead.                                                   |
 | ​   ↳ `selectedApi`        | `string`  | ❌       | —       | —               | Zapier app/API identifier (e.g. 'GoogleSheetsAPI'). Required when a trigger is configured.                                                                                                                              |
 | ​   ↳ `action`             | `string`  | ✅       | —       | —               | Trigger action key (e.g. 'new_row')                                                                                                                                                                                     |
 | ​   ↳ `authenticationId`   | `string`  | ❌       | —       | —               | Connection ID for the trigger source. Omit or pass null for no-auth triggers (e.g. Schedule by Zapier).                                                                                                                 |
 | ​   ↳ `params`             | `object`  | ❌       | —       | —               | Trigger parameters as a JSON object                                                                                                                                                                                     |
+| ​ ↳ `manual`               | `boolean` | ❌       | —       | —               | Declare this an on-demand, triggerless workflow version. Pass `manual: true` only when omitting `trigger`; passing both is a contradiction the API rejects with a 400.                                                  |
 
 **Returns:** `Promise<WorkflowVersionItem>`
 

package/dist/{chunk-XUVZWY2D.mjs → chunk-JZDH3POI.mjs}

@@ -4511,6 +4511,7 @@ var ZapierRelayError = class extends ZapierError {
     super(message, options);
     this.name = "ZapierRelayError";
     this.code = "ZAPIER_RELAY_ERROR";
+    if (options.retryable !== void 0) this.retryable = options.retryable;
   }
 };
 function hasZapierErrorCode(value, code) {
@@ -6191,7 +6192,7 @@ function parseDeprecationDate(value) {
 }
 
 // src/sdk-version.ts
-var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.94.0" : void 0) || "unknown";
+var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.95.0" : void 0) || "unknown";
 
 // src/utils/open-url.ts
 var nodePrefix = "node:";
@@ -6300,7 +6301,11 @@ var PollApprovalResponseSchema = z.object({
   status: ApprovalStatusSchema,
   approval_id: z.string().optional(),
   mode: ApprovalModeSchema.optional(),
-  reason: z.string().optional()
+  reason: z.string().optional(),
+  // Present when an auto-mode agent escalated the approval to a human reviewer.
+  // The SDK uses review_status to detect escalation and approval_url to open the browser.
+  review_status: z.enum(["in_review", "escalated"]).optional(),
+  approval_url: z.string().optional()
 });
 var APPROVAL_MAX_POLLING_INTERVAL_MILLISECONDS = 5e3;
 function validateSdkPath(path) {
@@ -7310,6 +7315,7 @@ var ZapierApiClient = class {
       await openApproval(approval.approval_url);
     }
     const timeoutMs = this.options.approvalTimeoutMilliseconds ?? this.options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MILLISECONDS;
+    const approvalDeadline = Date.now() + timeoutMs;
     let streamAbortController;
     let streamPromise;
     let removeStreamAbortListener;
@@ -7331,75 +7337,87 @@ var ZapierApiClient = class {
         emitEvent: (type, payload) => this.emitEvent(type, payload)
       });
     }
-    let rawPollResult;
-    try {
-      rawPollResult = await pollUntilComplete({
-        // poll_url is an absolute URL supplied by the server, so we use
-        // rawFetchUrl directly (skipping path resolution) but still share
-        // auth + interactive-header + 429-retry with the rest of the SDK.
-        // Each individual poll request goes through the concurrency
-        // semaphore — but we deliberately do not hold a slot across the
-        // sleep between polls or across the human-approval wait.
-        fetchPoll: () => this.withSemaphore(
-          { url: approval.poll_url, method: "GET", signal },
-          () => this.rawFetchUrl(approval.poll_url, {
-            method: "GET",
-            headers: { Accept: "application/json" },
-            signal
-          })
-        ),
-        timeoutMs,
-        maxPollingIntervalMs: APPROVAL_MAX_POLLING_INTERVAL_MILLISECONDS,
-        signal,
-        isPending: (body2) => {
-          const parsed = PollApprovalResponseSchema.safeParse(body2);
-          return parsed.success && parsed.data.status === "pending_approval";
-        }
-      });
-    } catch (err) {
-      if (!isZapierTimeoutError(err)) {
-        this.emitEvent("approval:error", {
-          approvalId: approval.id,
-          message: err instanceof Error ? err.message : String(err)
+    const fetchApprovalPoll = () => this.withSemaphore(
+      { url: approval.poll_url, method: "GET", signal },
+      () => this.rawFetchUrl(approval.poll_url, {
+        method: "GET",
+        headers: { Accept: "application/json" },
+        signal
+      })
+    );
+    const pollApprovalUntilComplete = async (isPending, deadlineMs = approvalDeadline) => {
+      try {
+        return await pollUntilComplete({
+          fetchPoll: fetchApprovalPoll,
+          timeoutMs: Math.max(1, deadlineMs - Date.now()),
+          maxPollingIntervalMs: APPROVAL_MAX_POLLING_INTERVAL_MILLISECONDS,
+          signal,
+          isPending
         });
-        throw err;
+      } catch (err) {
+        if (!isZapierTimeoutError(err)) {
+          this.emitEvent("approval:error", {
+            approvalId: approval.id,
+            message: err instanceof Error ? err.message : String(err)
+          });
+          throw err;
+        }
+        this.emitEvent("approval:timeout", { approvalId: approval.id });
+        throw new ZapierApprovalError(
+          `Approval timed out after ${timeoutMs / 1e3} seconds`,
+          {
+            approvalId: approval.id,
+            approvalUrl: approval.approval_url,
+            pollUrl: approval.poll_url,
+            streamUrl: approval.stream_url,
+            status: "timeout",
+            cause: err
+          }
+        );
       }
-      this.emitEvent("approval:timeout", {
-        approvalId: approval.id
+    };
+    let rawPollResult;
+    try {
+      rawPollResult = await pollApprovalUntilComplete((body2) => {
+        const parsed = PollApprovalResponseSchema.safeParse(body2);
+        if (!parsed.success) return false;
+        if (parsed.data.review_status === "escalated") return false;
+        return parsed.data.status === "pending_approval";
       });
-      throw new ZapierApprovalError(
-        `Approval timed out after ${timeoutMs / 1e3} seconds`,
-        {
-          approvalId: approval.id,
-          approvalUrl: approval.approval_url,
-          pollUrl: approval.poll_url,
-          streamUrl: approval.stream_url,
-          status: "timeout",
-          cause: err
-        }
-      );
     } finally {
       removeStreamAbortListener?.();
       streamAbortController?.abort();
       await streamPromise;
     }
-    const pollParse = PollApprovalResponseSchema.safeParse(rawPollResult);
-    if (!pollParse.success) {
-      const bodyPreview = typeof rawPollResult === "string" ? rawPollResult : JSON.stringify(rawPollResult);
-      this.emitEvent("approval:error", {
+    const parsePollResult = (raw) => {
+      const parsed = PollApprovalResponseSchema.safeParse(raw);
+      if (!parsed.success) {
+        const bodyPreview = typeof raw === "string" ? raw : JSON.stringify(raw);
+        this.emitEvent("approval:error", {
+          approvalId: approval.id,
+          message: `Failed to parse approval poll response: ${bodyPreview}`
+        });
+        throw new ZapierApiError(
+          `Failed to parse approval poll response: ${bodyPreview}`,
+          { statusCode: 0, cause: parsed.error, response: raw }
+        );
+      }
+      return parsed.data;
+    };
+    const pollResult = parsePollResult(rawPollResult);
+    if (pollResult.review_status === "escalated") {
+      const escalationUrl = pollResult.approval_url ?? approval.approval_url;
+      this.emitEvent("approval:escalated", {
         approvalId: approval.id,
-        message: `Failed to parse approval poll response: ${bodyPreview}`
+        approvalUrl: escalationUrl
       });
-      throw new ZapierApiError(
-        `Failed to parse approval poll response: ${bodyPreview}`,
-        {
-          statusCode: 0,
-          cause: pollParse.error,
-          response: rawPollResult
-        }
-      );
+      await openApproval(escalationUrl);
+      const humanRaw = await pollApprovalUntilComplete((body2) => {
+        const parsed = PollApprovalResponseSchema.safeParse(body2);
+        return parsed.success && parsed.data.status === "pending_approval";
+      });
+      Object.assign(pollResult, parsePollResult(humanRaw));
     }
-    const pollResult = pollParse.data;
     if (pollResult.status === "denied") {
       this.emitEvent("approval:denied", {
         approvalId: approval.id,
@@ -8459,8 +8477,20 @@ var fetchPlugin = defineMethod({
       });
       const relayError = result.headers.get("x-relay-error");
       if (relayError) {
+        const relayErrorCode = result.headers.get("x-relay-error-code");
+        const retryableHeader = result.headers.get("x-relay-error-retryable");
+        const retryable = retryableHeader === "true" ? true : retryableHeader === "false" ? false : void 0;
         throw new ZapierRelayError(relayError, {
-          statusCode: result.status
+          statusCode: result.status,
+          retryable,
+          errors: relayErrorCode ? [
+            {
+              status: result.status,
+              code: relayErrorCode,
+              title: "API Proxy Error",
+              detail: relayError
+            }
+          ] : void 0
         });
       }
       return result;

package/dist/{chunk-TQT6EGZU.cjs → chunk-Z7BGM75G.cjs}

@@ -4513,6 +4513,7 @@ var ZapierRelayError = class extends ZapierError {
     super(message, options);
     this.name = "ZapierRelayError";
     this.code = "ZAPIER_RELAY_ERROR";
+    if (options.retryable !== void 0) this.retryable = options.retryable;
   }
 };
 function hasZapierErrorCode(value, code) {
@@ -6193,7 +6194,7 @@ function parseDeprecationDate(value) {
 }
 
 // src/sdk-version.ts
-var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.94.0" : void 0) || "unknown";
+var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.95.0" : void 0) || "unknown";
 
 // src/utils/open-url.ts
 var nodePrefix = "node:";
@@ -6302,7 +6303,11 @@ var PollApprovalResponseSchema = zod.z.object({
   status: ApprovalStatusSchema,
   approval_id: zod.z.string().optional(),
   mode: ApprovalModeSchema.optional(),
-  reason: zod.z.string().optional()
+  reason: zod.z.string().optional(),
+  // Present when an auto-mode agent escalated the approval to a human reviewer.
+  // The SDK uses review_status to detect escalation and approval_url to open the browser.
+  review_status: zod.z.enum(["in_review", "escalated"]).optional(),
+  approval_url: zod.z.string().optional()
 });
 var APPROVAL_MAX_POLLING_INTERVAL_MILLISECONDS = 5e3;
 function validateSdkPath(path) {
@@ -7312,6 +7317,7 @@ var ZapierApiClient = class {
       await openApproval(approval.approval_url);
     }
     const timeoutMs = this.options.approvalTimeoutMilliseconds ?? this.options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MILLISECONDS;
+    const approvalDeadline = Date.now() + timeoutMs;
     let streamAbortController;
     let streamPromise;
     let removeStreamAbortListener;
@@ -7333,75 +7339,87 @@ var ZapierApiClient = class {
         emitEvent: (type, payload) => this.emitEvent(type, payload)
       });
     }
-    let rawPollResult;
-    try {
-      rawPollResult = await pollUntilComplete({
-        // poll_url is an absolute URL supplied by the server, so we use
-        // rawFetchUrl directly (skipping path resolution) but still share
-        // auth + interactive-header + 429-retry with the rest of the SDK.
-        // Each individual poll request goes through the concurrency
-        // semaphore — but we deliberately do not hold a slot across the
-        // sleep between polls or across the human-approval wait.
-        fetchPoll: () => this.withSemaphore(
-          { url: approval.poll_url, method: "GET", signal },
-          () => this.rawFetchUrl(approval.poll_url, {
-            method: "GET",
-            headers: { Accept: "application/json" },
-            signal
-          })
-        ),
-        timeoutMs,
-        maxPollingIntervalMs: APPROVAL_MAX_POLLING_INTERVAL_MILLISECONDS,
-        signal,
-        isPending: (body2) => {
-          const parsed = PollApprovalResponseSchema.safeParse(body2);
-          return parsed.success && parsed.data.status === "pending_approval";
-        }
-      });
-    } catch (err) {
-      if (!isZapierTimeoutError(err)) {
-        this.emitEvent("approval:error", {
-          approvalId: approval.id,
-          message: err instanceof Error ? err.message : String(err)
+    const fetchApprovalPoll = () => this.withSemaphore(
+      { url: approval.poll_url, method: "GET", signal },
+      () => this.rawFetchUrl(approval.poll_url, {
+        method: "GET",
+        headers: { Accept: "application/json" },
+        signal
+      })
+    );
+    const pollApprovalUntilComplete = async (isPending, deadlineMs = approvalDeadline) => {
+      try {
+        return await pollUntilComplete({
+          fetchPoll: fetchApprovalPoll,
+          timeoutMs: Math.max(1, deadlineMs - Date.now()),
+          maxPollingIntervalMs: APPROVAL_MAX_POLLING_INTERVAL_MILLISECONDS,
+          signal,
+          isPending
         });
-        throw err;
+      } catch (err) {
+        if (!isZapierTimeoutError(err)) {
+          this.emitEvent("approval:error", {
+            approvalId: approval.id,
+            message: err instanceof Error ? err.message : String(err)
+          });
+          throw err;
+        }
+        this.emitEvent("approval:timeout", { approvalId: approval.id });
+        throw new ZapierApprovalError(
+          `Approval timed out after ${timeoutMs / 1e3} seconds`,
+          {
+            approvalId: approval.id,
+            approvalUrl: approval.approval_url,
+            pollUrl: approval.poll_url,
+            streamUrl: approval.stream_url,
+            status: "timeout",
+            cause: err
+          }
+        );
       }
-      this.emitEvent("approval:timeout", {
-        approvalId: approval.id
+    };
+    let rawPollResult;
+    try {
+      rawPollResult = await pollApprovalUntilComplete((body2) => {
+        const parsed = PollApprovalResponseSchema.safeParse(body2);
+        if (!parsed.success) return false;
+        if (parsed.data.review_status === "escalated") return false;
+        return parsed.data.status === "pending_approval";
       });
-      throw new ZapierApprovalError(
-        `Approval timed out after ${timeoutMs / 1e3} seconds`,
-        {
-          approvalId: approval.id,
-          approvalUrl: approval.approval_url,
-          pollUrl: approval.poll_url,
-          streamUrl: approval.stream_url,
-          status: "timeout",
-          cause: err
-        }
-      );
     } finally {
       removeStreamAbortListener?.();
       streamAbortController?.abort();
       await streamPromise;
     }
-    const pollParse = PollApprovalResponseSchema.safeParse(rawPollResult);
-    if (!pollParse.success) {
-      const bodyPreview = typeof rawPollResult === "string" ? rawPollResult : JSON.stringify(rawPollResult);
-      this.emitEvent("approval:error", {
+    const parsePollResult = (raw) => {
+      const parsed = PollApprovalResponseSchema.safeParse(raw);
+      if (!parsed.success) {
+        const bodyPreview = typeof raw === "string" ? raw : JSON.stringify(raw);
+        this.emitEvent("approval:error", {
+          approvalId: approval.id,
+          message: `Failed to parse approval poll response: ${bodyPreview}`
+        });
+        throw new ZapierApiError(
+          `Failed to parse approval poll response: ${bodyPreview}`,
+          { statusCode: 0, cause: parsed.error, response: raw }
+        );
+      }
+      return parsed.data;
+    };
+    const pollResult = parsePollResult(rawPollResult);
+    if (pollResult.review_status === "escalated") {
+      const escalationUrl = pollResult.approval_url ?? approval.approval_url;
+      this.emitEvent("approval:escalated", {
         approvalId: approval.id,
-        message: `Failed to parse approval poll response: ${bodyPreview}`
+        approvalUrl: escalationUrl
       });
-      throw new ZapierApiError(
-        `Failed to parse approval poll response: ${bodyPreview}`,
-        {
-          statusCode: 0,
-          cause: pollParse.error,
-          response: rawPollResult
-        }
-      );
+      await openApproval(escalationUrl);
+      const humanRaw = await pollApprovalUntilComplete((body2) => {
+        const parsed = PollApprovalResponseSchema.safeParse(body2);
+        return parsed.success && parsed.data.status === "pending_approval";
+      });
+      Object.assign(pollResult, parsePollResult(humanRaw));
     }
-    const pollResult = pollParse.data;
     if (pollResult.status === "denied") {
       this.emitEvent("approval:denied", {
         approvalId: approval.id,
@@ -8461,8 +8479,20 @@ var fetchPlugin = defineMethod({
       });
       const relayError = result.headers.get("x-relay-error");
       if (relayError) {
+        const relayErrorCode = result.headers.get("x-relay-error-code");
+        const retryableHeader = result.headers.get("x-relay-error-retryable");
+        const retryable = retryableHeader === "true" ? true : retryableHeader === "false" ? false : void 0;
         throw new ZapierRelayError(relayError, {
-          statusCode: result.status
+          statusCode: result.status,
+          retryable,
+          errors: relayErrorCode ? [
+            {
+              status: result.status,
+              code: relayErrorCode,
+              title: "API Proxy Error",
+              detail: relayError
+            }
+          ] : void 0
         });
       }
       return result;