@zapier/zapier-sdk 0.42.1 → 0.44.0

package/dist/api/client.js

@@ -11,8 +11,21 @@ import { resolveAuthToken, invalidateCredentialsToken, isCliLoginAvailable, } fr
 import { getZapierBaseUrl } from "../utils/url-utils";
 import { sleep, calculateExponentialBackoffMs } from "../utils/retry-utils";
 import { isPlainObject } from "../utils/type-guard-utils";
-import { ZapierApiError, ZapierAuthenticationError, ZapierValidationError, ZapierNotFoundError, ZapierRateLimitError, } from "../types/errors";
-import { ZAPIER_MAX_NETWORK_RETRIES, ZAPIER_MAX_NETWORK_RETRY_DELAY_MS, } from "../constants";
+import { ZapierApiError, ZapierApprovalError, ZapierAuthenticationError, ZapierTimeoutError, ZapierValidationError, ZapierNotFoundError, ZapierRateLimitError, } from "../types/errors";
+import { ZAPIER_MAX_NETWORK_RETRIES, ZAPIER_MAX_NETWORK_RETRY_DELAY_MS, getZapierIsInteractive, getZapierApprovalMode, DEFAULT_APPROVAL_TIMEOUT_MS, DEFAULT_MAX_APPROVAL_RETRIES, } from "../constants";
+import { openApproval } from "../utils/open-approval";
+import { z } from "zod";
+const ApprovalStatusSchema = z.enum(["pending_approval", "approved", "denied"]);
+const CreateApprovalResponseSchema = z.object({
+    status: ApprovalStatusSchema,
+    approval_id: z.string(),
+    approval_url: z.string().url(),
+    poll_url: z.string().url(),
+});
+const PollApprovalResponseSchema = z.object({
+    status: ApprovalStatusSchema,
+    approval_id: z.string(),
+});
 /**
  * Parse rate limit information from response headers
  */
@@ -85,14 +98,23 @@ const pathConfig = {
 class ZapierApiClient {
     constructor(options) {
         this.options = options;
-        this.fetch = async (path, init) => {
-            if (!path.startsWith("/")) {
-                throw new ZapierValidationError(`fetch expects a path starting with '/', got: ${path}`);
-            }
+        /**
+         * Perform a request against an already-resolved URL.
+         *
+         * Does auth, header merging, and 429 retry — all the cross-cutting
+         * concerns that every Zapier-bound HTTP call needs. Callers that have a
+         * path (e.g. `/relay/...`) should use `rawFetch` instead, which does
+         * path → URL resolution and delegates here.
+         *
+         * Exposed as a separate helper so call sites with a server-supplied
+         * absolute URL (e.g. an approval poll URL) can still share the same
+         * auth/retry pipeline instead of reaching for `this.options.fetch`
+         * directly and drifting.
+         */
+        this.rawFetchUrl = async (url, init, pathConfig) => {
             if (init?.body && (isPlainObject(init.body) || Array.isArray(init.body))) {
                 init.body = JSON.stringify(init.body);
             }
-            const { url, pathConfig } = this.buildUrl(path, init?.searchParams);
             const builtHeaders = await this.buildHeaders(init, pathConfig);
             const inputHeaders = new Headers(init?.headers ?? {});
             const mergedHeaders = new Headers();
@@ -102,44 +124,147 @@ class ZapierApiClient {
             inputHeaders.forEach((value, key) => {
                 mergedHeaders.set(key, value);
             });
-            // Retry loop for rate limiting (429)
             let retries = 0;
+            // Retry loop for rate limiting (429)
             while (true) {
                 const response = await this.options.fetch(url, {
                     ...init,
                     headers: mergedHeaders,
                 });
-                // Handle rate limiting (429) with retries
-                if (response.status === 429) {
-                    const rateLimitInfo = parseRateLimitHeaders(response);
-                    // Calculate delay: prefer Retry-After/X-RateLimit-Reset, fall back to exponential backoff
-                    const delayMs = rateLimitInfo.retryAfterMs ??
-                        calculateExponentialBackoffMs(retries + 1);
-                    // If delay exceeds maxNetworkRetryDelayMs or retries exhausted, throw immediately
-                    if (delayMs > this.maxNetworkRetryDelayMs ||
-                        retries >= this.maxNetworkRetries) {
-                        throw new ZapierRateLimitError("Rate limited", {
-                            statusCode: 429,
-                            rateLimit: rateLimitInfo,
-                            retries,
-                        });
-                    }
-                    retries++;
-                    // Emit retry event
-                    this.emitEvent("api:rate_limit_retry", {
-                        retry: retries,
-                        maxNetworkRetries: this.maxNetworkRetries,
-                        delayMs,
-                        path,
-                        method: init?.method ?? "GET",
+                if (response.status !== 429) {
+                    return response;
+                }
+                // Calculate delay: prefer Retry-After/X-RateLimit-Reset, fall back to exponential backoff
+                const rateLimitInfo = parseRateLimitHeaders(response);
+                const delayMs = rateLimitInfo.retryAfterMs ??
+                    calculateExponentialBackoffMs(retries + 1);
+                // If delay exceeds maxNetworkRetryDelayMs or retries exhausted, throw immediately
+                if (delayMs > this.maxNetworkRetryDelayMs ||
+                    retries >= this.maxNetworkRetries) {
+                    throw new ZapierRateLimitError("Rate limited", {
+                        statusCode: 429,
                         rateLimit: rateLimitInfo,
+                        retries,
                     });
-                    // Wait before retrying
-                    await sleep(delayMs);
-                    continue;
                 }
-                return response;
+                retries++;
+                // Emit retry event
+                this.emitEvent("api:rate_limit_retry", {
+                    retry: retries,
+                    maxNetworkRetries: this.maxNetworkRetries,
+                    delayMs,
+                    path: url,
+                    method: init?.method ?? "GET",
+                    rateLimit: rateLimitInfo,
+                });
+                await sleep(delayMs);
+            }
+        };
+        /**
+         * Perform a request with auth, header merging, and rate-limit (429) retries.
+         * Does NOT handle 403 approval_required — that's routed by `fetch`.
+         */
+        this.rawFetch = async (path, init) => {
+            if (!path.startsWith("/")) {
+                throw new ZapierValidationError(`fetch expects a path starting with '/', got: ${path}`);
             }
+            const { url, pathConfig } = this.buildUrl(path, init?.searchParams);
+            return this.rawFetchUrl(url, init, pathConfig);
+        };
+        /**
+         * Approval-aware HTTP fetch.
+         *
+         * Wraps `rawFetch` with the backend's just-in-time approval protocol. The
+         * backend signals approval state via a 403 response with an
+         * `x-zapier-error-type` header:
+         *
+         *   - `request_denied_by_policy`  → a policy rule permanently blocks the
+         *                                   request; no human can approve it. Throw.
+         *   - `approval_required`         → the request needs human approval; the
+         *                                   SDK creates an approval, opens the URL
+         *                                   (poll mode), waits for resolution, and
+         *                                   retries the original request.
+         *   - anything else               → not our concern, pass through.
+         *
+         * The retry loop exists because a single user action can legitimately
+         * require multiple sequential approvals (e.g. policies that approve one
+         * step at a time). Each iteration is either a first attempt or a post-
+         * approval retry; `maxApprovalRetries` bounds the loop as a runaway-loop
+         * safeguard.
+         *
+         * Loop accounting: `attempt` counts rawFetch calls, not approval rounds.
+         * With `maxRetries = N` we perform up to `N + 1` rawFetch calls and at
+         * most `N` approval rounds. The `attempt === maxRetries` guard ensures we
+         * don't run an (N+1)th approval round we'll never consume — if the final
+         * retry still returns `approval_required`, we break out and throw
+         * `max_retries_exceeded` instead.
+         */
+        this.fetch = async (path, init) => {
+            const maxRetries = this.options.maxApprovalRetries ?? DEFAULT_MAX_APPROVAL_RETRIES;
+            // `<= maxRetries` gives us one initial attempt plus `maxRetries` post-
+            // approval retries. See "Loop accounting" in the jsdoc above.
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                const response = await this.rawFetch(path, init);
+                // Happy path and non-403 errors: hand the response back untouched. Any
+                // other error handling (e.g. 4xx envelope parsing) lives downstream.
+                if (response.status !== 403)
+                    return response;
+                // All approval-related responses are 403 + a typed header. Classify the
+                // kind of 403 we got exactly once, here — no other call site should be
+                // reading `x-zapier-error-type`.
+                const errorType = response.headers.get("x-zapier-error-type");
+                // Terminal policy denial: a rule blocked the request and no approval
+                // can unblock it. Bubble the server-provided detail message so callers
+                // surface the actual reason ("Spend over $X requires finance approval",
+                // etc.) rather than a generic one.
+                if (errorType === "request_denied_by_policy") {
+                    const { data } = await this.parseResult(response);
+                    const { message, errors } = this.parseErrorResponse({
+                        status: response.status,
+                        statusText: response.statusText,
+                        data,
+                    });
+                    throw new ZapierApprovalError(message || "Request explicitly denied by policy", {
+                        status: "policy_denied",
+                        statusCode: response.status,
+                        errors,
+                    });
+                }
+                // 403 with no `approval_required` header isn't part of the approval
+                // protocol — could be auth scope, per-endpoint perms, etc. Pass it
+                // through so the caller's normal error handling sees it.
+                if (errorType !== "approval_required")
+                    return response;
+                // We got `approval_required`. If this was our last scheduled attempt,
+                // don't start an approval round we can't retry — fall out of the loop
+                // and throw `max_retries_exceeded` below.
+                if (attempt === maxRetries)
+                    break;
+                // Approval requires opening a URL in a browser. If the caller's session
+                // can't do that (CI, server, headless container), surface a distinct
+                // status so callers can branch on "retry interactively or use
+                // approvalMode: 'fail'" vs. a real policy denial.
+                const isInteractive = this.options.isInteractive ?? getZapierIsInteractive();
+                if (!isInteractive) {
+                    throw new ZapierApprovalError("Approval required but session is not interactive", { status: "approval_required" });
+                }
+                // `approvalContext` is a builder, not a value, because the SDK may
+                // retry the same request across multiple approval rounds and each POST
+                // to /approvals needs a freshly-built context (timestamps, etc.).
+                // Missing context is a programmer error — this code path is only
+                // reachable for callers that opted into approval-capable requests.
+                if (!init?.approvalContext) {
+                    throw new ZapierApiError(`Received 403 approval_required for ${path}, but the caller did not provide an approvalContext builder. Every approval-capable request must pass approvalContext so the SDK can create the approval with the correct policy context.`, { statusCode: 403 });
+                }
+                // Create the approval, open the URL (poll mode) or throw with the URL
+                // attached (fail mode), and wait for terminal resolution. Returns only
+                // on "approved" — every other outcome throws from inside the helper.
+                // On return, loop back to retry the original request.
+                await this.runOneApprovalRound(init.approvalContext);
+            }
+            // Only reachable when the final attempt returned `approval_required`
+            // (see the `break` above). Every other terminal outcome throws inline.
+            throw new ZapierApprovalError(`Exceeded maximum approval retries (${maxRetries}) for ${path}`, { status: "max_retries_exceeded" });
         };
         this.get = async (path, options = {}) => {
             return this.fetchJson("GET", path, undefined, options);
@@ -480,6 +605,155 @@ class ZapierApiClient {
         }
         return result;
     }
+    /**
+     * Run a single approval round: create the approval, open the URL (poll mode)
+     * or throw (fail mode), poll until resolved, and emit events. Throws on
+     * denied/timeout/unexpected status. Returns on approved.
+     */
+    async runOneApprovalRound(buildContext) {
+        const context = buildContext();
+        // Route through rawFetch so the approval POST shares auth + 429 retry.
+        let approvalResponse;
+        try {
+            approvalResponse = await this.rawFetch("/api/v0/approvals", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify({ context }),
+            });
+        }
+        catch (err) {
+            throw new ZapierApiError("Failed to create approval request", {
+                statusCode: 0,
+                cause: err,
+            });
+        }
+        if (!approvalResponse.ok) {
+            const body = await approvalResponse.text().catch(() => undefined);
+            throw new ZapierApiError(`Failed to create approval request: ${approvalResponse.status}`, { statusCode: approvalResponse.status, response: body });
+        }
+        let body;
+        try {
+            body = await approvalResponse.text();
+        }
+        catch (err) {
+            throw new ZapierApiError("Failed to read approval response body", {
+                statusCode: approvalResponse.status,
+                cause: err,
+            });
+        }
+        let approval;
+        try {
+            approval = CreateApprovalResponseSchema.parse(JSON.parse(body));
+        }
+        catch (err) {
+            throw new ZapierApiError(`Failed to parse approval response: ${body}`, {
+                statusCode: approvalResponse.status,
+                cause: err,
+                response: body,
+            });
+        }
+        // Origin-pin server-supplied URLs before we attach the bearer token
+        // (poll_url) or open them in the user's browser (approval_url). Without
+        // this, a compromised or buggy sdkapi response could redirect the SDK to
+        // an attacker-controlled host and leak the auth token.
+        const sdkapiOrigin = new URL(this.buildUrl("/api/v0/approvals").url).origin;
+        const browserOrigin = getZapierBaseUrl(this.options.baseUrl) ?? sdkapiOrigin;
+        const assertApprovalOrigin = (url, expectedOrigin, label) => {
+            let parsed;
+            try {
+                parsed = new URL(url);
+            }
+            catch {
+                throw new ZapierApiError(`Invalid approval ${label}: ${url}`, {
+                    statusCode: approvalResponse.status,
+                    response: body,
+                });
+            }
+            if (parsed.origin !== expectedOrigin) {
+                throw new ZapierApiError(`Approval ${label} origin ${parsed.origin} does not match expected ${expectedOrigin}`, { statusCode: approvalResponse.status, response: body });
+            }
+        };
+        assertApprovalOrigin(approval.poll_url, sdkapiOrigin, "poll_url");
+        assertApprovalOrigin(approval.approval_url, browserOrigin, "approval_url");
+        this.emitEvent("approval:required", {
+            approvalId: approval.approval_id,
+            approvalUrl: approval.approval_url,
+        });
+        const approvalMode = this.options.approvalMode ?? getZapierApprovalMode();
+        if (approvalMode === "fail") {
+            throw new ZapierApprovalError("This request requires approval.", {
+                approvalId: approval.approval_id,
+                approvalUrl: approval.approval_url,
+                pollUrl: approval.poll_url,
+                status: "pending",
+            });
+        }
+        // approvalMode: "poll" (default) — open browser and poll
+        await openApproval(approval.approval_url);
+        const timeoutMs = this.options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+        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.
+                fetchPoll: () => this.rawFetchUrl(approval.poll_url, {
+                    method: "GET",
+                    headers: { Accept: "application/json" },
+                }),
+                timeoutMs,
+                isPending: (body) => {
+                    const parsed = PollApprovalResponseSchema.safeParse(body);
+                    return parsed.success && parsed.data.status === "pending_approval";
+                },
+            });
+        }
+        catch (err) {
+            if (!(err instanceof ZapierTimeoutError)) {
+                throw err;
+            }
+            this.emitEvent("approval:timeout", {
+                approvalId: approval.approval_id,
+            });
+            throw new ZapierApprovalError(`Approval timed out after ${timeoutMs / 1000} seconds`, {
+                approvalId: approval.approval_id,
+                approvalUrl: approval.approval_url,
+                pollUrl: approval.poll_url,
+                status: "timeout",
+                cause: err,
+            });
+        }
+        const pollParse = PollApprovalResponseSchema.safeParse(rawPollResult);
+        if (!pollParse.success) {
+            const bodyPreview = typeof rawPollResult === "string"
+                ? rawPollResult
+                : JSON.stringify(rawPollResult);
+            throw new ZapierApiError(`Failed to parse approval poll response: ${bodyPreview}`, {
+                statusCode: 0,
+                cause: pollParse.error,
+                response: rawPollResult,
+            });
+        }
+        const pollResult = pollParse.data;
+        if (pollResult.status === "denied") {
+            this.emitEvent("approval:denied", {
+                approvalId: approval.approval_id,
+            });
+            throw new ZapierApprovalError("Request denied by user", {
+                approvalId: approval.approval_id,
+                status: "denied",
+            });
+        }
+        if (pollResult.status !== "approved") {
+            throw new ZapierApiError(`Unexpected approval status received: ${pollResult.status}`);
+        }
+        this.emitEvent("approval:approved", {
+            approvalId: approval.approval_id,
+        });
+    }
 }
 export const createZapierApi = (options) => {
     const { debug = false, fetch: originalFetch = globalThis.fetch } = options;

package/dist/api/types.d.ts

@@ -12,6 +12,7 @@ import type { ConnectionSchema, ConnectionsResponseSchema } from "@zapier/zapier
 import type { ImplementationMetaSchema, ImplementationsMetaResponseSchema } from "@zapier/zapier-sdk-core/v0/schemas/implementations";
 import type { SdkEvent } from "../types/events";
 import type { Credentials } from "../types/credentials";
+import type { RequestContext } from "@zapier/policy-context";
 import type { z } from "zod";
 import type { NeedChoicesSchema, NeedSchema, ActionLinksSchema, ActionPermissionsSchema, ActionSchema, ChoiceSchema, FieldSchema, ActionExecutionResultSchema, ActionFieldChoiceSchema, ActionFieldSchema, UserProfileSchema, AppSchema, NeedsRequestSchema, NeedsResponseSchema, ImplementationSchema, ImplementationsResponseSchema, ServiceSchema, ServicesResponseSchema, NeedChoicesRequestSchema, NeedChoicesResponseSchema, NeedChoicesResponseMetaSchema, NeedChoicesResponseLinksSchema } from "./schemas";
 export interface ApiClientOptions {
@@ -38,6 +39,27 @@ export interface ApiClientOptions {
      * Default is 60000 (60 seconds).
      */
     maxNetworkRetryDelayMs?: number;
+    /**
+     * Whether this session is interactive (user can visit approval URLs).
+     */
+    isInteractive?: boolean;
+    /**
+     * Controls how the approval flow is handled.
+     * - "poll": (default) Opens the approval URL in a browser and polls until resolved.
+     * - "fail": Creates the approval and throws a ZapierApprovalError immediately with the approval URL.
+     */
+    approvalMode?: "poll" | "fail";
+    /**
+     * Timeout in ms for approval polling. Default: 600000 (10 minutes).
+     */
+    approvalTimeoutMs?: number;
+    /**
+     * Maximum number of sequential approval rounds for a single request before
+     * giving up. A single request can legitimately require multiple approvals
+     * (one per gating policy); this cap prevents a runaway loop if the server
+     * keeps returning approval_required. Default: 2.
+     */
+    maxApprovalRetries?: number;
 }
 export interface ApiClient {
     get: <T = unknown>(path: string, options?: RequestOptions) => Promise<T>;
@@ -49,6 +71,7 @@ export interface ApiClient {
     fetch: (path: string, init?: RequestInit & {
         searchParams?: Record<string, string>;
         authRequired?: boolean;
+        approvalContext?: () => RequestContext;
     }) => Promise<Response>;
 }
 export interface RequestOptions {
@@ -66,6 +89,12 @@ export interface RequestOptions {
         statusText: string;
         data: unknown;
     }) => Error | undefined;
+    /**
+     * Builds the policy context for this request if it triggers the approval
+     * flow. Callers that may receive a 403 `approval_required` response MUST
+     * provide this so the SDK can create an approval with the correct context.
+     */
+    approvalContext?: () => RequestContext;
 }
 export interface PollOptions extends RequestOptions {
     initialDelay?: number;

package/dist/api/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -24,4 +24,29 @@ export declare const DEFAULT_ACTION_TIMEOUT_MS = 180000;
  */
 export declare const ZAPIER_MAX_NETWORK_RETRIES: number;
 export declare const ZAPIER_MAX_NETWORK_RETRY_DELAY_MS: number;
+/**
+ * Whether this session is interactive (user can visit approval URLs).
+ *
+ * Read lazily so tests can set the env var after module import.
+ */
+export declare function getZapierIsInteractive(): boolean;
+/**
+ * Approval flow behavior from environment variable.
+ * - "poll": (default) Opens the approval URL in a browser and polls until resolved.
+ * - "fail": Creates the approval and throws immediately with the approval URL.
+ *
+ * Read lazily so tests can set the env var after module import.
+ */
+export declare function getZapierApprovalMode(): "poll" | "fail" | undefined;
+/**
+ * Default timeout for approval polling (10 minutes)
+ */
+export declare const DEFAULT_APPROVAL_TIMEOUT_MS: number;
+/**
+ * Default cap on chained approval retries for a single request. Multiple
+ * sequential approvals can occur when more than one policy gates the same
+ * action; this cap prevents a runaway loop if the server keeps returning
+ * approval_required after a successful approval.
+ */
+export declare const DEFAULT_MAX_APPROVAL_RETRIES = 2;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe,QACsC,CAAC;AAEnE;;GAEG;AACH,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAejD;;GAEG;AACH,eAAO,MAAM,0BAA0B,QACY,CAAC;AACpD,eAAO,MAAM,iCAAiC,QACiB,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe,QACsC,CAAC;AAEnE;;GAEG;AACH,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAejD;;GAEG;AACH,eAAO,MAAM,0BAA0B,QACY,CAAC;AACpD,eAAO,MAAM,iCAAiC,QACiB,CAAC;AAEhE;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,MAAM,GAAG,SAAS,CAInE;AAED;;GAEG;AACH,eAAO,MAAM,2BAA2B,QAAiB,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,IAAI,CAAC"}

package/dist/constants.js

@@ -35,3 +35,35 @@ function parseIntEnvVar(name) {
  */
 export const ZAPIER_MAX_NETWORK_RETRIES = parseIntEnvVar("ZAPIER_MAX_NETWORK_RETRIES") ?? 3;
 export const ZAPIER_MAX_NETWORK_RETRY_DELAY_MS = parseIntEnvVar("ZAPIER_MAX_NETWORK_RETRY_DELAY_MS") ?? 60000;
+/**
+ * Whether this session is interactive (user can visit approval URLs).
+ *
+ * Read lazily so tests can set the env var after module import.
+ */
+export function getZapierIsInteractive() {
+    return globalThis.process?.env?.ZAPIER_IS_INTERACTIVE === "true";
+}
+/**
+ * Approval flow behavior from environment variable.
+ * - "poll": (default) Opens the approval URL in a browser and polls until resolved.
+ * - "fail": Creates the approval and throws immediately with the approval URL.
+ *
+ * Read lazily so tests can set the env var after module import.
+ */
+export function getZapierApprovalMode() {
+    const value = globalThis.process?.env?.ZAPIER_APPROVAL_MODE;
+    if (value === "poll" || value === "fail")
+        return value;
+    return undefined;
+}
+/**
+ * Default timeout for approval polling (10 minutes)
+ */
+export const DEFAULT_APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * Default cap on chained approval retries for a single request. Multiple
+ * sequential approvals can occur when more than one policy gates the same
+ * action; this cap prevents a runaway loop if the server keeps returning
+ * approval_required after a successful approval.
+ */
+export const DEFAULT_MAX_APPROVAL_RETRIES = 2;