@zapier/zapier-sdk 0.42.1 → 0.44.0

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { buildHttpRequestContext, buildActionRunContext } from '@zapier/policy-context';
 import { ListAppsQuerySchema, AppItemSchema as AppItemSchema$1 } from '@zapier/zapier-sdk-core/v0/schemas/apps';
 import { ListConnectionsQuerySchema as ListConnectionsQuerySchema$1, ConnectionItemSchema as ConnectionItemSchema$1 } from '@zapier/zapier-sdk-core/v0/schemas/connections';
 import { ListClientCredentialsQuerySchema as ListClientCredentialsQuerySchema$1, CreateClientCredentialsRequestSchema, ClientCredentialsItemSchema as ClientCredentialsItemSchema$1, ClientCredentialsCreatedItemSchema as ClientCredentialsCreatedItemSchema$1 } from '@zapier/zapier-sdk-core/v0/schemas/client-credentials';
@@ -56,6 +57,16 @@ function parseIntEnvVar(name) {
 }
 var ZAPIER_MAX_NETWORK_RETRIES = parseIntEnvVar("ZAPIER_MAX_NETWORK_RETRIES") ?? 3;
 var ZAPIER_MAX_NETWORK_RETRY_DELAY_MS = parseIntEnvVar("ZAPIER_MAX_NETWORK_RETRY_DELAY_MS") ?? 6e4;
+function getZapierIsInteractive() {
+  return globalThis.process?.env?.ZAPIER_IS_INTERACTIVE === "true";
+}
+function getZapierApprovalMode() {
+  const value = globalThis.process?.env?.ZAPIER_APPROVAL_MODE;
+  if (value === "poll" || value === "fail") return value;
+  return void 0;
+}
+var DEFAULT_APPROVAL_TIMEOUT_MS = 10 * 60 * 1e3;
+var DEFAULT_MAX_APPROVAL_RETRIES = 2;
 
 // src/types/properties.ts
 var AppKeyPropertySchema = withPositional(
@@ -88,7 +99,7 @@ var AuthenticationIdPropertySchema = ConnectionIdPropertySchema.meta({
   deprecated: true
 });
 var ConnectionPropertySchema = z.union([z.string(), z.number().int().positive()]).describe(
-  "Connection alias (string) or numeric connectionId. Strings are resolved from the connections map; numbers are used directly."
+  "Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly."
 );
 var InputsPropertySchema = z.record(z.string(), z.unknown()).describe("Input parameters for the action");
 var LimitPropertySchema = z.number().int().min(1).max(MAX_PAGE_LIMIT).default(50).describe("Maximum number of items to return");
@@ -224,6 +235,17 @@ var ZapierRateLimitError = class extends ZapierError {
     this.retries = options.retries ?? 0;
   }
 };
+var ZapierApprovalError = class extends ZapierError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "ZapierApprovalError";
+    this.code = "ZAPIER_APPROVAL_ERROR";
+    this.approvalId = options.approvalId;
+    this.approvalStatus = options.status;
+    this.approvalUrl = options.approvalUrl;
+    this.pollUrl = options.pollUrl;
+  }
+};
 var ZapierRelayError = class extends ZapierError {
   constructor(message, options = {}) {
     super(message, options);
@@ -268,6 +290,10 @@ ${context.join(", ")}`;
   if (error instanceof ZapierBundleError && error.buildErrors && error.buildErrors.length > 0) {
     message += "\n\nBuild errors:\n" + error.buildErrors.map((err) => `  \u2022 ${err}`).join("\n");
   }
+  if (error instanceof ZapierApprovalError && error.approvalUrl) {
+    message += `
+Approval URL: ${error.approvalUrl}`;
+  }
   if (error instanceof ZapierRateLimitError) {
     const { limit, remaining, retryAfterMs } = error.rateLimit;
     const parts = [];
@@ -975,18 +1001,27 @@ var fetchPlugin = (sdk) => {
           if (maxTime !== void 0) {
             headers["X-Zapier-Sdk-Max-Time"] = String(maxTime);
           }
+          const upstreamUrl = new URL(url).toString();
+          const method = (fetchInit.method ?? "GET").toUpperCase();
           const abortHandle = buildAbortHandle({
             maxTimeSeconds: maxTime,
             callerSignal: fetchInit.signal
           });
           try {
             const result = await api.fetch(relayPath, {
-              method: fetchInit.method ?? "GET",
+              method,
               body: fetchInit.body,
               headers,
               redirect: fetchInit.redirect,
               signal: abortHandle?.signal,
-              authRequired: true
+              authRequired: true,
+              approvalContext: () => buildHttpRequestContext({
+                method,
+                url: upstreamUrl,
+                headers,
+                body: typeof fetchInit.body === "string" ? fetchInit.body : void 0,
+                connection_id: resolvedConnectionId ? String(resolvedConnectionId) : void 0
+              })
             });
             const relayError = result.headers.get("x-relay-error");
             if (relayError) {
@@ -2976,7 +3011,7 @@ var listActionsPlugin = (sdk) => {
 var ListInputFieldsDescription = "Get the input fields required for a specific action";
 var ListInputFieldsBaseSchema = z.object({
   connection: ConnectionPropertySchema.optional().describe(
-    "Connection alias (string) or numeric connectionId. Strings are resolved from the connections map; numbers are used directly. Mutually exclusive with connectionId."
+    "Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. Mutually exclusive with connectionId."
   ),
   connectionId: ConnectionIdPropertySchema.nullable().optional().describe(
     "Connection ID to use when listing input fields. Required if the action needs a connection to determine available fields."
@@ -3672,7 +3707,9 @@ var listClientCredentialsPlugin = (sdk) => {
   };
 };
 var CreateClientCredentialsSchema = CreateClientCredentialsRequestSchema.omit({ allowed_scopes: true }).extend({
-  allowedScopes: z.array(z.enum(["credentials", "external"])).default(["external"]).describe("Scopes to allow for these credentials")
+  allowedScopes: z.array(z.enum(["credentials", "external"])).default(["external"]).describe("Scopes to allow for these credentials"),
+  // Temporarily hidden while we finalise work to make approvals/policies customer-facing.
+  policy: z.record(z.string(), z.unknown()).optional().describe("Policy document (JSON) to attach to the credentials").meta({ deprecated: true })
 }).describe("Create new client credentials for the authenticated user");
 
 // src/plugins/createClientCredentials/index.ts
@@ -3683,7 +3720,8 @@ var createClientCredentialsPlugin = (sdk) => {
       "/api/v0/client-credentials",
       {
         name: options.name,
-        allowed_scopes: options.allowedScopes
+        allowed_scopes: options.allowedScopes,
+        ...options.policy && { policy: options.policy }
       },
       {
         customErrorHandler: ({ status }) => {
@@ -4073,7 +4111,7 @@ var findUniqueConnectionPlugin = (sdk) => {
 var RunActionDescription = "Execute an action with the given inputs";
 var RunActionBaseSchema = z.object({
   connection: ConnectionPropertySchema.optional().describe(
-    "Connection alias (string) or numeric connectionId. Strings are resolved from the connections map; numbers are used directly. Mutually exclusive with connectionId."
+    "Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. Mutually exclusive with connectionId."
   ),
   connectionId: ConnectionIdPropertySchema.nullable().optional().describe(
     "Connection ID to use when running the action. Required if the action needs a connection to authenticate and interact with the service."
@@ -4106,8 +4144,6 @@ var RunActionSchemaDeprecated = z.object({
   actionKey: ActionKeyPropertySchema
 }).merge(RunActionBaseSchema);
 var RunActionInputSchema = z.union([RunActionSchema, RunActionSchemaDeprecated]).describe(RunActionDescription);
-
-// src/plugins/runAction/index.ts
 async function executeAction(actionOptions) {
   const {
     api,
@@ -4138,7 +4174,18 @@ async function executeAction(actionOptions) {
   };
   const runData = await api.post(
     "/zapier/api/actions/v1/runs",
-    runRequest
+    runRequest,
+    {
+      approvalContext: () => buildActionRunContext({
+        selected_api: selectedApi,
+        action_type: actionType,
+        action_key: actionKey,
+        connection_id: connectionId != null ? String(connectionId) : void 0,
+        // Cast: inputs is Record<string, unknown> at the SDK surface, but
+        // buildActionRunContext coerces to JsonValue at runtime via zod.
+        inputs: executionOptions.inputs ?? {}
+      })
+    }
   );
   const runId = runData.data.id;
   return await api.poll(`/zapier/api/actions/v1/runs/${runId}`, {
@@ -4443,8 +4490,12 @@ async function readFile(filePath) {
   }
   throw new Error(`File not found: ${filePath}`);
 }
+var POSITIVE_INTEGER_OR_UUID = /^([1-9][0-9]*|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/;
 var ConnectionEntrySchema = z.object({
-  connectionId: z.number().int().positive().describe("Zapier connection ID for the third-party service.")
+  connectionId: z.union([
+    z.string().regex(POSITIVE_INTEGER_OR_UUID),
+    z.number().int().positive()
+  ]).describe("Zapier connection ID for the third-party service.")
 });
 var ConnectionsMapSchema = z.record(z.string(), ConnectionEntrySchema);
 
@@ -5687,7 +5738,89 @@ async function invalidateCredentialsToken(options) {
   }
 }
 
-// src/api/client.ts
+// src/utils/open-url.ts
+var nodePrefix = "node:";
+async function loadChildProcess() {
+  return import(`${nodePrefix}child_process`);
+}
+async function loadProcess() {
+  return import(`${nodePrefix}process`);
+}
+var openUrl = async (url) => {
+  if (typeof url !== "string") {
+    throw new TypeError("Expected `url` to be a string");
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`Refusing to open non-http(s) URL: ${parsed.protocol}`);
+  }
+  const target = parsed.toString();
+  if (typeof globalThis.window !== "undefined" && typeof globalThis.window.open === "function") {
+    globalThis.window.open(target, "_blank", "noopener");
+    return;
+  }
+  let spawn;
+  let platform;
+  try {
+    const [cp, proc] = await Promise.all([loadChildProcess(), loadProcess()]);
+    spawn = cp.spawn;
+    platform = proc.platform;
+  } catch {
+    throw new Error(
+      "openUrl: no supported runtime. window.open is unavailable and node:child_process could not be loaded."
+    );
+  }
+  if (typeof spawn !== "function") {
+    throw new Error(
+      "openUrl: child_process.spawn is not available in this runtime"
+    );
+  }
+  let command;
+  let args;
+  if (platform === "darwin") {
+    command = "open";
+    args = [target];
+  } else if (platform === "win32") {
+    command = "rundll32";
+    args = ["url.dll,FileProtocolHandler", target];
+  } else {
+    throw new Error(`Unsupported platform: ${platform}`);
+  }
+  const child = spawn(command, args, {
+    stdio: "ignore",
+    detached: true,
+    windowsHide: true
+  });
+  child.once("error", () => {
+  });
+  child.unref();
+};
+var open_url_default = openUrl;
+
+// src/utils/open-approval.ts
+async function openApproval(url) {
+  console.error(`Approval required. Opening browser: ${url}`);
+  try {
+    await open_url_default(url);
+  } catch {
+  }
+}
+var ApprovalStatusSchema = z.enum(["pending_approval", "approved", "denied"]);
+var CreateApprovalResponseSchema = z.object({
+  status: ApprovalStatusSchema,
+  approval_id: z.string(),
+  approval_url: z.string().url(),
+  poll_url: z.string().url()
+});
+var PollApprovalResponseSchema = z.object({
+  status: ApprovalStatusSchema,
+  approval_id: z.string()
+});
 function parseRateLimitHeaders(response) {
   const info = {};
   const retryAfter = response.headers.get("retry-after");
@@ -5748,16 +5881,23 @@ var pathConfig = {
 var ZapierApiClient = class {
   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, pathConfig2) => {
       if (init?.body && (isPlainObject(init.body) || Array.isArray(init.body))) {
         init.body = JSON.stringify(init.body);
       }
-      const { url, pathConfig: pathConfig2 } = this.buildUrl(path, init?.searchParams);
       const builtHeaders = await this.buildHeaders(
         init,
         pathConfig2
@@ -5776,30 +5916,114 @@ var ZapierApiClient = class {
           ...init,
           headers: mergedHeaders
         });
-        if (response.status === 429) {
-          const rateLimitInfo = parseRateLimitHeaders(response);
-          const delayMs = rateLimitInfo.retryAfterMs ?? calculateExponentialBackoffMs(retries + 1);
-          if (delayMs > this.maxNetworkRetryDelayMs || retries >= this.maxNetworkRetries) {
-            throw new ZapierRateLimitError("Rate limited", {
-              statusCode: 429,
-              rateLimit: rateLimitInfo,
-              retries
-            });
-          }
-          retries++;
-          this.emitEvent("api:rate_limit_retry", {
-            retry: retries,
-            maxNetworkRetries: this.maxNetworkRetries,
-            delayMs,
-            path,
-            method: init?.method ?? "GET",
-            rateLimit: rateLimitInfo
+        if (response.status !== 429) {
+          return response;
+        }
+        const rateLimitInfo = parseRateLimitHeaders(response);
+        const delayMs = rateLimitInfo.retryAfterMs ?? calculateExponentialBackoffMs(retries + 1);
+        if (delayMs > this.maxNetworkRetryDelayMs || retries >= this.maxNetworkRetries) {
+          throw new ZapierRateLimitError("Rate limited", {
+            statusCode: 429,
+            rateLimit: rateLimitInfo,
+            retries
+          });
+        }
+        retries++;
+        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: pathConfig2 } = this.buildUrl(path, init?.searchParams);
+      return this.rawFetchUrl(url, init, pathConfig2);
+    };
+    /**
+     * 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;
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const response = await this.rawFetch(path, init);
+        if (response.status !== 403) return response;
+        const errorType = response.headers.get("x-zapier-error-type");
+        if (errorType === "request_denied_by_policy") {
+          const { data } = await this.parseResult(response);
+          const { message, errors } = this.parseErrorResponse({
+            status: response.status,
+            statusText: response.statusText,
+            data
           });
-          await sleep(delayMs);
-          continue;
+          throw new ZapierApprovalError(
+            message || "Request explicitly denied by policy",
+            {
+              status: "policy_denied",
+              statusCode: response.status,
+              errors
+            }
+          );
+        }
+        if (errorType !== "approval_required") return response;
+        if (attempt === maxRetries) break;
+        const isInteractive = this.options.isInteractive ?? getZapierIsInteractive();
+        if (!isInteractive) {
+          throw new ZapierApprovalError(
+            "Approval required but session is not interactive",
+            { status: "approval_required" }
+          );
+        }
+        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 }
+          );
         }
-        return response;
+        await this.runOneApprovalRound(init.approvalContext);
       }
+      throw new ZapierApprovalError(
+        `Exceeded maximum approval retries (${maxRetries}) for ${path}`,
+        { status: "max_retries_exceeded" }
+      );
     };
     this.get = async (path, options = {}) => {
       return this.fetchJson("GET", path, void 0, options);
@@ -6084,6 +6308,156 @@ var ZapierApiClient = class {
     }
     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();
+    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 body2 = await approvalResponse.text().catch(() => void 0);
+      throw new ZapierApiError(
+        `Failed to create approval request: ${approvalResponse.status}`,
+        { statusCode: approvalResponse.status, response: body2 }
+      );
+    }
+    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
+      });
+    }
+    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"
+      });
+    }
+    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: (body2) => {
+          const parsed = PollApprovalResponseSchema.safeParse(body2);
+          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 / 1e3} 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
+    });
+  }
 };
 var createZapierApi = (options) => {
   const { debug = false, fetch: originalFetch = globalThis.fetch } = options;
@@ -6106,7 +6480,11 @@ var apiPlugin = (sdk) => {
     onEvent,
     debug = false,
     maxNetworkRetries = ZAPIER_MAX_NETWORK_RETRIES,
-    maxNetworkRetryDelayMs = ZAPIER_MAX_NETWORK_RETRY_DELAY_MS
+    maxNetworkRetryDelayMs = ZAPIER_MAX_NETWORK_RETRY_DELAY_MS,
+    isInteractive,
+    approvalTimeoutMs,
+    maxApprovalRetries,
+    approvalMode
   } = sdk.context.options;
   const api = createZapierApi({
     baseUrl,
@@ -6116,7 +6494,11 @@ var apiPlugin = (sdk) => {
     fetch: customFetch,
     onEvent,
     maxNetworkRetries,
-    maxNetworkRetryDelayMs
+    maxNetworkRetryDelayMs,
+    isInteractive,
+    approvalTimeoutMs,
+    maxApprovalRetries,
+    approvalMode
   });
   return {
     context: {
@@ -7671,7 +8053,7 @@ var findUniqueAuthenticationPlugin = (sdk) => ({
 var GetInputFieldsSchemaDescription = "Get the JSON Schema representation of input fields for an action. Returns a JSON Schema object describing the structure, types, and validation rules for the action's input parameters.";
 var GetInputFieldsSchemaBaseSchema = z.object({
   connection: ConnectionPropertySchema.optional().describe(
-    "Connection alias (string) or numeric connectionId. Strings are resolved from the connections map; numbers are used directly. Mutually exclusive with connectionId."
+    "Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. Mutually exclusive with connectionId."
   ),
   connectionId: ConnectionIdPropertySchema.nullable().optional().describe(
     "Connection ID to use when fetching the schema. Required if the action needs a connection to determine available fields."
@@ -7809,7 +8191,7 @@ var InputFieldChoiceItemSchema = withFormatter(NeedChoicesSchema, {
 var ListInputFieldChoicesDescription = "Get the available choices for a dynamic dropdown input field";
 var ListInputFieldChoicesBaseSchema = z.object({
   connection: ConnectionPropertySchema.optional().describe(
-    "Connection alias (string) or numeric connectionId. Strings are resolved from the connections map; numbers are used directly. Mutually exclusive with connectionId."
+    "Connection alias or connection ID (UUID or positive integer). Strings that match a key in the connections map are resolved against it; otherwise the value is used as a connection ID directly. Mutually exclusive with connectionId."
   ),
   connectionId: ConnectionIdPropertySchema.nullable().optional().describe(
     "Connection ID to use when listing available field choices. Required if the action needs a connection to populate dynamic dropdown options."
@@ -8668,6 +9050,16 @@ var BaseSdkOptionsSchema = z.object({
    * Default is 60000 (60 seconds).
    */
   maxNetworkRetryDelayMs: z.number().optional().describe("Max delay in ms to wait for retry (default: 60000).").meta({ valueHint: "ms" }),
+  isInteractive: z.boolean().optional().describe(
+    "Whether this session is interactive (user can visit approval URLs). Defaults to ZAPIER_IS_INTERACTIVE env var."
+  ).meta({ internal: true }),
+  approvalTimeoutMs: z.number().optional().describe("Timeout in ms for approval polling. Default: 600000 (10 min).").meta({ valueHint: "ms", internal: true }),
+  maxApprovalRetries: z.number().optional().describe(
+    "Maximum number of sequential approval rounds per request (one per gating policy) before giving up. Default: 2."
+  ).meta({ internal: true }),
+  approvalMode: z.enum(["poll", "fail"]).optional().describe(
+    'Approval flow behavior. "poll" opens browser and polls (default). "fail" creates the approval and throws immediately with the approval URL.'
+  ).meta({ internal: true }),
   // Internal
   manifestPath: z.string().optional().describe("Path to a .zapierrc manifest file for app version locking.").meta({ internal: true }),
   manifest: z.custom().optional().describe("Manifest for app version locking.").meta({ internal: true }),
@@ -8682,4 +9074,4 @@ var BaseSdkOptionsSchema = z.object({
   // Use credentials instead
 });
 
-export { ActionKeyPropertySchema, ActionPropertySchema, ActionTimeoutMsPropertySchema, ActionTypePropertySchema, AppKeyPropertySchema, AppPropertySchema, AppsPropertySchema, AuthenticationIdPropertySchema, BaseSdkOptionsSchema, CONTEXT_CACHE_MAX_SIZE, CONTEXT_CACHE_TTL_MS, ClientCredentialsObjectSchema, ConnectionEntrySchema, ConnectionIdPropertySchema, ConnectionPropertySchema, ConnectionsMapSchema, ConnectionsPropertySchema, CredentialsFunctionSchema, CredentialsObjectSchema, CredentialsSchema, DEFAULT_ACTION_TIMEOUT_MS, DEFAULT_CONFIG_PATH, DEFAULT_PAGE_SIZE, DebugPropertySchema, FieldsPropertySchema, InputFieldPropertySchema, InputsPropertySchema, LimitPropertySchema, MAX_PAGE_LIMIT, OffsetPropertySchema, OutputPropertySchema, ParamsPropertySchema, PkceCredentialsObjectSchema, RecordPropertySchema, RecordsPropertySchema, RelayFetchSchema, RelayRequestSchema, ResolvedCredentialsSchema, TablePropertySchema, TablesPropertySchema, ZAPIER_BASE_URL, ZAPIER_MAX_NETWORK_RETRIES, ZAPIER_MAX_NETWORK_RETRY_DELAY_MS, ZapierActionError, ZapierApiError, ZapierAppNotFoundError, ZapierAuthenticationError, ZapierBundleError, ZapierConfigurationError, ZapierError, ZapierNotFoundError, ZapierRateLimitError, ZapierRelayError, ZapierResourceNotFoundError, ZapierTimeoutError, ZapierUnknownError, ZapierValidationError, actionKeyResolver, actionTypeResolver, apiPlugin, appKeyResolver, appsPlugin, connectionIdGenericResolver as authenticationIdGenericResolver, connectionIdResolver as authenticationIdResolver, batch, buildApplicationLifecycleEvent, buildCapabilityMessage, buildErrorEvent, buildErrorEventWithContext, buildMethodCalledEvent, clearTokenCache, clientCredentialsNameResolver, clientIdResolver, connectionIdGenericResolver, connectionIdResolver, connectionsPlugin, createBaseEvent, createClientCredentialsPlugin, createFunction, createOptionsPlugin, createSdk, createTableFieldsPlugin, createTablePlugin, createTableRecordsPlugin, createZapierSdk, createZapierSdkWithoutRegistry, deleteClientCredentialsPlugin, deleteTableFieldsPlugin, deleteTablePlugin, deleteTableRecordsPlugin, fetchPlugin, findFirstConnectionPlugin, findManifestEntry, findUniqueConnectionPlugin, formatErrorMessage, generateEventId, getActionPlugin, getAppPlugin, getBaseUrlFromCredentials, getCiPlatform, getClientIdFromCredentials, getConnectionPlugin, getCpuTime, getCurrentTimestamp, getMemoryUsage, getOsInfo, getPlatformVersions, getPreferredManifestEntryKey, getProfilePlugin, getReleaseId, getTablePlugin, getTableRecordPlugin, getTokenFromCliLogin, injectCliLogin, inputFieldKeyResolver, inputsAllOptionalResolver, inputsResolver, invalidateCachedToken, invalidateCredentialsToken, isCi, isCliLoginAvailable, isClientCredentials, isCredentialsFunction, isCredentialsObject, isPkceCredentials, isPositional, listActionsPlugin, listAppsPlugin, listClientCredentialsPlugin, listConnectionsPlugin, listInputFieldsPlugin, listTableFieldsPlugin, listTableRecordsPlugin, listTablesPlugin, logDeprecation, manifestPlugin, readManifestFromFile, registryPlugin, requestPlugin, resetDeprecationWarnings, resolveAuthToken, resolveCredentials, resolveCredentialsFromEnv, runActionPlugin, runWithTelemetryContext, tableFieldIdsResolver, tableFieldsResolver, tableFiltersResolver, tableIdResolver, tableNameResolver, tableRecordIdResolver, tableRecordIdsResolver, tableRecordsResolver, tableSortResolver, tableUpdateRecordsResolver, toSnakeCase, toTitleCase, updateTableRecordsPlugin };
+export { ActionKeyPropertySchema, ActionPropertySchema, ActionTimeoutMsPropertySchema, ActionTypePropertySchema, AppKeyPropertySchema, AppPropertySchema, AppsPropertySchema, AuthenticationIdPropertySchema, BaseSdkOptionsSchema, CONTEXT_CACHE_MAX_SIZE, CONTEXT_CACHE_TTL_MS, ClientCredentialsObjectSchema, ConnectionEntrySchema, ConnectionIdPropertySchema, ConnectionPropertySchema, ConnectionsMapSchema, ConnectionsPropertySchema, CredentialsFunctionSchema, CredentialsObjectSchema, CredentialsSchema, DEFAULT_ACTION_TIMEOUT_MS, DEFAULT_APPROVAL_TIMEOUT_MS, DEFAULT_CONFIG_PATH, DEFAULT_MAX_APPROVAL_RETRIES, DEFAULT_PAGE_SIZE, DebugPropertySchema, FieldsPropertySchema, InputFieldPropertySchema, InputsPropertySchema, LimitPropertySchema, MAX_PAGE_LIMIT, OffsetPropertySchema, OutputPropertySchema, ParamsPropertySchema, PkceCredentialsObjectSchema, RecordPropertySchema, RecordsPropertySchema, RelayFetchSchema, RelayRequestSchema, ResolvedCredentialsSchema, TablePropertySchema, TablesPropertySchema, ZAPIER_BASE_URL, ZAPIER_MAX_NETWORK_RETRIES, ZAPIER_MAX_NETWORK_RETRY_DELAY_MS, ZapierActionError, ZapierApiError, ZapierAppNotFoundError, ZapierApprovalError, ZapierAuthenticationError, ZapierBundleError, ZapierConfigurationError, ZapierError, ZapierNotFoundError, ZapierRateLimitError, ZapierRelayError, ZapierResourceNotFoundError, ZapierTimeoutError, ZapierUnknownError, ZapierValidationError, actionKeyResolver, actionTypeResolver, apiPlugin, appKeyResolver, appsPlugin, connectionIdGenericResolver as authenticationIdGenericResolver, connectionIdResolver as authenticationIdResolver, batch, buildApplicationLifecycleEvent, buildCapabilityMessage, buildErrorEvent, buildErrorEventWithContext, buildMethodCalledEvent, clearTokenCache, clientCredentialsNameResolver, clientIdResolver, connectionIdGenericResolver, connectionIdResolver, connectionsPlugin, createBaseEvent, createClientCredentialsPlugin, createFunction, createOptionsPlugin, createSdk, createTableFieldsPlugin, createTablePlugin, createTableRecordsPlugin, createZapierSdk, createZapierSdkWithoutRegistry, deleteClientCredentialsPlugin, deleteTableFieldsPlugin, deleteTablePlugin, deleteTableRecordsPlugin, fetchPlugin, findFirstConnectionPlugin, findManifestEntry, findUniqueConnectionPlugin, formatErrorMessage, generateEventId, getActionPlugin, getAppPlugin, getBaseUrlFromCredentials, getCiPlatform, getClientIdFromCredentials, getConnectionPlugin, getCpuTime, getCurrentTimestamp, getMemoryUsage, getOsInfo, getPlatformVersions, getPreferredManifestEntryKey, getProfilePlugin, getReleaseId, getTablePlugin, getTableRecordPlugin, getTokenFromCliLogin, getZapierApprovalMode, getZapierIsInteractive, injectCliLogin, inputFieldKeyResolver, inputsAllOptionalResolver, inputsResolver, invalidateCachedToken, invalidateCredentialsToken, isCi, isCliLoginAvailable, isClientCredentials, isCredentialsFunction, isCredentialsObject, isPkceCredentials, isPositional, listActionsPlugin, listAppsPlugin, listClientCredentialsPlugin, listConnectionsPlugin, listInputFieldsPlugin, listTableFieldsPlugin, listTableRecordsPlugin, listTablesPlugin, logDeprecation, manifestPlugin, readManifestFromFile, registryPlugin, requestPlugin, resetDeprecationWarnings, resolveAuthToken, resolveCredentials, resolveCredentialsFromEnv, runActionPlugin, runWithTelemetryContext, tableFieldIdsResolver, tableFieldsResolver, tableFiltersResolver, tableIdResolver, tableNameResolver, tableRecordIdResolver, tableRecordIdsResolver, tableRecordsResolver, tableSortResolver, tableUpdateRecordsResolver, toSnakeCase, toTitleCase, updateTableRecordsPlugin };

package/dist/plugins/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/api/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAQnE,MAAM,WAAW,gBAAiB,SAAQ,cAAc;CAAG;AAG3D,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE;QACP,GAAG,EAAE,SAAS,CAAC;QACf,kBAAkB,EAAE,MAAM,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC;KACpE,CAAC;CACH;AAED,eAAO,MAAM,SAAS,EAAE,MAAM,CAC5B;IAAE,OAAO,EAAE;QAAE,OAAO,EAAE,cAAc,CAAA;KAAE,CAAA;CAAE,EACxC,iBAAiB,CAsClB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/api/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAQnE,MAAM,WAAW,gBAAiB,SAAQ,cAAc;CAAG;AAG3D,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE;QACP,GAAG,EAAE,SAAS,CAAC;QACf,kBAAkB,EAAE,MAAM,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC;KACpE,CAAC;CACH;AAED,eAAO,MAAM,SAAS,EAAE,MAAM,CAC5B;IAAE,OAAO,EAAE;QAAE,OAAO,EAAE,cAAc,CAAA;KAAE,CAAA;CAAE,EACxC,iBAAiB,CA8ClB,CAAC"}