@zapier/zapier-sdk 0.70.3 → 0.71.0

package/dist/index.mjs

@@ -1058,6 +1058,11 @@ function getZapierApprovalMode() {
     return value;
   return void 0;
 }
+function getZapierOpenAutoModeApprovalsInBrowser() {
+  const value = globalThis.process?.env?.ZAPIER_OPEN_AUTO_MODE_APPROVALS_IN_BROWSER;
+  if (value === void 0) return void 0;
+  return value === "true";
+}
 function getZapierDefaultApprovalMode() {
   const isInteractive = !!globalThis.process?.stdin?.isTTY && !!globalThis.process?.stdout?.isTTY;
   return isInteractive ? "poll" : "throw";
@@ -1281,6 +1286,8 @@ var ZapierApprovalError = class extends ZapierError {
     this.approvalStatus = options.status;
     this.approvalUrl = options.approvalUrl;
     this.pollUrl = options.pollUrl;
+    this.streamUrl = options.streamUrl;
+    this.reason = options.reason;
   }
 };
 var ZapierRelayError = class extends ZapierError {
@@ -6777,9 +6784,101 @@ function createSseParserStream() {
     }
   });
 }
+var ApprovalReviewChunkSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("text-delta"),
+    delta: z.string()
+  }).passthrough(),
+  z.object({
+    type: z.literal("tool-input-available"),
+    toolCallId: z.string(),
+    toolName: z.string()
+  }).passthrough(),
+  z.object({
+    type: z.literal("tool-output-available"),
+    toolCallId: z.string(),
+    output: z.unknown()
+  }).passthrough()
+]);
+var ReportDecisionOutputSchema = z.object({
+  success: z.boolean().optional(),
+  decision: z.enum(["approved", "denied"]),
+  reason: z.string().optional()
+}).passthrough();
+async function consumeApprovalReviewStream({
+  approvalId,
+  streamUrl,
+  signal,
+  stream,
+  emitEvent
+}) {
+  try {
+    const toolNames = /* @__PURE__ */ new Map();
+    for await (const frame of stream(streamUrl, {
+      method: "GET",
+      headers: {
+        "Accept-Encoding": "identity"
+      },
+      signal
+    })) {
+      if (!frame.parsed) continue;
+      const payload = parseApprovalReviewStreamPayload(frame.data, toolNames);
+      if (!payload) continue;
+      if (payload.kind === "message") {
+        emitEvent("approval:review_message", {
+          approvalId,
+          streamUrl,
+          data: payload.data,
+          message: payload.message
+        });
+        continue;
+      }
+      emitEvent("approval:review_decision", {
+        approvalId,
+        streamUrl,
+        data: payload.data,
+        decision: payload.decision,
+        ...payload.reason ? { reason: payload.reason } : {}
+      });
+    }
+  } catch (err) {
+    if (isAbortError(err) || signal.aborted) return;
+    emitEvent("approval:review_stream_error", {
+      approvalId,
+      streamUrl,
+      message: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function parseApprovalReviewStreamPayload(parsed, toolNames) {
+  const chunk = ApprovalReviewChunkSchema.safeParse(parsed);
+  if (!chunk.success) return void 0;
+  switch (chunk.data.type) {
+    case "text-delta": {
+      const message = chunk.data.delta.trim();
+      return message.length > 0 ? { kind: "message", data: parsed, message } : void 0;
+    }
+    case "tool-input-available":
+      toolNames.set(chunk.data.toolCallId, chunk.data.toolName);
+      return void 0;
+    case "tool-output-available": {
+      if (toolNames.get(chunk.data.toolCallId) !== "report_decision") {
+        return void 0;
+      }
+      const decision = ReportDecisionOutputSchema.safeParse(chunk.data.output);
+      if (!decision.success) return void 0;
+      return {
+        kind: "decision",
+        data: parsed,
+        decision: decision.data.decision,
+        ...decision.data.reason ? { reason: decision.data.reason } : {}
+      };
+    }
+  }
+}
 
 // src/sdk-version.ts
-var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.70.3" : void 0) || "unknown";
+var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.71.0" : void 0) || "unknown";
 
 // src/utils/open-url.ts
 var nodePrefix = "node:";
@@ -6831,6 +6930,9 @@ var openUrl = async (url) => {
   } else if (platform === "win32") {
     command = "rundll32";
     args = ["url.dll,FileProtocolHandler", target];
+  } else if (platform === "linux") {
+    command = "xdg-open";
+    args = [target];
   } else {
     throw new Error(`Unsupported platform: ${platform}`);
   }
@@ -6853,16 +6955,39 @@ async function openApproval(url) {
   } catch {
   }
 }
-var ApprovalStatusSchema = z.enum(["pending_approval", "approved", "denied"]);
+var ApprovalStatusSchema = z.enum([
+  "pending_approval",
+  "approved",
+  "denied",
+  "failed"
+]);
+var ApprovalModeSchema = z.enum(["manual", "auto"]);
 var CreateApprovalResponseSchema = z.object({
+  id: z.string().optional(),
   status: ApprovalStatusSchema,
-  approval_id: z.string(),
+  approval_id: z.string().optional(),
+  mode: ApprovalModeSchema,
   approval_url: z.string().url(),
-  poll_url: z.string().url()
+  poll_url: z.string().url(),
+  stream_url: z.string().url().optional(),
+  reason: z.string().optional()
+}).transform((approval, ctx) => {
+  const id = approval.id ?? approval.approval_id;
+  if (!id) {
+    ctx.addIssue({
+      code: "custom",
+      message: "Approval response must include id"
+    });
+    return z.NEVER;
+  }
+  return { ...approval, id };
 });
 var PollApprovalResponseSchema = z.object({
+  id: z.string().optional(),
   status: ApprovalStatusSchema,
-  approval_id: z.string()
+  approval_id: z.string().optional(),
+  mode: ApprovalModeSchema.optional(),
+  reason: z.string().optional()
 });
 var APPROVAL_MAX_POLLING_INTERVAL_MS = 5e3;
 function parseRateLimitHeaders(response) {
@@ -7135,7 +7260,11 @@ var ZapierApiClient = class {
             { statusCode: 403 }
           );
         }
-        await this.runOneApprovalRound(init.approvalContext, mode);
+        await this.runOneApprovalRound(
+          init.approvalContext,
+          mode,
+          init.signal ?? void 0
+        );
       }
       throw new ZapierApprovalError(
         `Exceeded maximum approval retries (${maxRetries}) for ${path}`,
@@ -7163,6 +7292,7 @@ var ZapierApiClient = class {
      * any frame), so transport / auth failures surface as usual.
      */
     this.fetchJsonStream = (path, init) => jsonFrames(this.fetchStream(path, init));
+    this.streamTrustedJsonUrl = (url, init) => jsonFrames(this.streamTrustedSseUrl(url, init));
     this.get = async (path, options = {}) => {
       return this.fetchJson("GET", path, void 0, options);
     };
@@ -7502,7 +7632,7 @@ var ZapierApiClient = class {
   // bound `fetchStream` arrow above for parity with the other client methods.
   async *streamSse(path, init) {
     const { onOpen, headers: initHeaders, ...fetchInit } = init ?? {};
-    const signal = fetchInit.signal;
+    const signal = fetchInit.signal ?? void 0;
     if (signal?.aborted) return;
     const wasMissingAuthToken = fetchInit.authRequired === true && await this.getAuthToken({
       requiredScopes: fetchInit.requiredScopes
@@ -7520,13 +7650,62 @@ var ZapierApiClient = class {
       if (signal?.aborted || isAbortError(err)) return;
       throw err;
     }
+    yield* this.readSseResponse({
+      response,
+      signal,
+      onOpen,
+      wasMissingAuthToken,
+      requiredScopes: fetchInit.requiredScopes
+    });
+  }
+  // Approval `stream_url` is server-supplied and origin-pinned before use, like
+  // `poll_url`; keep absolute-URL streaming private rather than widening the
+  // public path-based `fetchStream` API.
+  async *streamTrustedSseUrl(url, init) {
+    const { onOpen, headers: initHeaders, ...fetchInit } = init ?? {};
+    const signal = fetchInit.signal ?? void 0;
+    if (signal?.aborted) return;
+    const wasMissingAuthToken = fetchInit.authRequired === true && await this.getAuthToken({
+      requiredScopes: fetchInit.requiredScopes
+    }) == null;
+    const headers = new Headers(initHeaders);
+    if (!headers.has("Accept")) headers.set("Accept", "text/event-stream");
+    let response;
+    try {
+      response = await this.withSemaphore(
+        { url, method: fetchInit.method ?? "GET", signal },
+        () => this.rawFetchUrl(url, {
+          ...fetchInit,
+          method: fetchInit.method ?? "GET",
+          headers
+        })
+      );
+    } catch (err) {
+      if (signal?.aborted || isAbortError(err)) return;
+      throw err;
+    }
+    yield* this.readSseResponse({
+      response,
+      signal,
+      onOpen,
+      wasMissingAuthToken,
+      requiredScopes: fetchInit.requiredScopes
+    });
+  }
+  async *readSseResponse({
+    response,
+    signal,
+    onOpen,
+    wasMissingAuthToken,
+    requiredScopes
+  }) {
     if (!response.ok) {
       const { data } = await this.parseResult(response);
       await this.throwForErrorResponse({
         response,
         responseData: data,
         wasMissingAuthToken,
-        requiredScopes: fetchInit.requiredScopes
+        requiredScopes
       });
     }
     if (!response.body) return;
@@ -7552,12 +7731,12 @@ var ZapierApiClient = class {
   /**
    * Run a single approval round: create the approval, open the URL (poll mode)
    * or throw (throw mode), poll until resolved, and emit events. Throws on
-   * denied/timeout/unexpected status. Returns on approved.
+   * denied/failed/timeout/unexpected status. Returns on approved.
    *
    * Caller is responsible for passing a non-"disabled" mode; this method
    * unconditionally creates an approval.
    */
-  async runOneApprovalRound(buildContext, mode) {
+  async runOneApprovalRound(buildContext, mode, signal) {
     const context = buildContext();
     let approvalResponse;
     try {
@@ -7567,9 +7746,11 @@ var ZapierApiClient = class {
           "Content-Type": "application/json",
           Accept: "application/json"
         },
-        body: JSON.stringify({ context })
+        body: JSON.stringify({ context }),
+        signal
       });
     } catch (err) {
+      if (isAbortError(err)) throw err;
       throw new ZapierApiError("Failed to create approval request", {
         statusCode: 0,
         cause: err
@@ -7622,6 +7803,9 @@ var ZapierApiClient = class {
     };
     if (!isLocalhostBaseUrl(this.options.baseUrl)) {
       assertApprovalOrigin(approval.poll_url, sdkapiOrigin, "poll_url");
+      if (approval.stream_url) {
+        assertApprovalOrigin(approval.stream_url, sdkapiOrigin, "stream_url");
+      }
       assertApprovalOrigin(
         approval.approval_url,
         browserOrigin,
@@ -7629,19 +7813,79 @@ var ZapierApiClient = class {
       );
     }
     this.emitEvent("approval:required", {
-      approvalId: approval.approval_id,
-      approvalUrl: approval.approval_url
+      approvalId: approval.id,
+      approvalUrl: approval.approval_url,
+      mode: approval.mode,
+      ...approval.stream_url ? { streamUrl: approval.stream_url } : {}
     });
-    if (mode === "throw") {
-      throw new ZapierApprovalError("This request requires approval.", {
-        approvalId: approval.approval_id,
-        approvalUrl: approval.approval_url,
-        pollUrl: approval.poll_url,
-        status: "pending"
-      });
+    const shouldOpenAutoModeApproval = this.options.openAutoModeApprovalsInBrowser ?? getZapierOpenAutoModeApprovalsInBrowser() ?? false;
+    if (approval.mode === "auto") {
+      if (shouldOpenAutoModeApproval) {
+        await openApproval(approval.approval_url);
+      }
+      if (approval.status === "approved") {
+        this.emitEvent("approval:approved", {
+          approvalId: approval.id
+        });
+        return;
+      }
+      if (approval.status === "denied") {
+        this.emitEvent("approval:denied", {
+          approvalId: approval.id,
+          ...approval.reason ? { reason: approval.reason } : {}
+        });
+        throw new ZapierApprovalError(
+          approval.reason ? `Request denied: ${approval.reason}` : "Request denied by user",
+          {
+            approvalId: approval.id,
+            status: "denied",
+            reason: approval.reason
+          }
+        );
+      }
+      if (approval.status === "failed") {
+        this.throwApprovalFailed({
+          approvalId: approval.id,
+          approvalUrl: approval.approval_url,
+          pollUrl: approval.poll_url,
+          streamUrl: approval.stream_url,
+          reason: approval.reason
+        });
+      }
+    } else {
+      if (mode === "throw") {
+        throw new ZapierApprovalError("This request requires approval.", {
+          approvalId: approval.id,
+          approvalUrl: approval.approval_url,
+          pollUrl: approval.poll_url,
+          streamUrl: approval.stream_url,
+          status: "pending"
+        });
+      }
+      await openApproval(approval.approval_url);
     }
-    await openApproval(approval.approval_url);
     const timeoutMs = this.options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+    let streamAbortController;
+    let streamPromise;
+    let removeStreamAbortListener;
+    if (approval.mode === "auto" && approval.stream_url) {
+      const streamUrl = approval.stream_url;
+      streamAbortController = new AbortController();
+      const abortStream = () => streamAbortController?.abort();
+      if (signal?.aborted) {
+        abortStream();
+      } else if (signal) {
+        signal.addEventListener("abort", abortStream, { once: true });
+        removeStreamAbortListener = () => signal.removeEventListener("abort", abortStream);
+      }
+      streamPromise = consumeApprovalReviewStream({
+        approvalId: approval.id,
+        streamUrl,
+        signal: streamAbortController.signal,
+        stream: (url, streamInit) => this.streamTrustedJsonUrl(url, streamInit),
+        emitEvent: (type, payload) => this.emitEvent(type, payload)
+      });
+    }
     let rawPollResult;
     try {
       rawPollResult = await pollUntilComplete({
@@ -7652,14 +7896,16 @@ var ZapierApiClient = class {
         // 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" },
+          { url: approval.poll_url, method: "GET", signal },
           () => this.rawFetchUrl(approval.poll_url, {
             method: "GET",
-            headers: { Accept: "application/json" }
+            headers: { Accept: "application/json" },
+            signal
           })
         ),
         timeoutMs,
         maxPollingIntervalMs: APPROVAL_MAX_POLLING_INTERVAL_MS,
+        signal,
         isPending: (body2) => {
           const parsed = PollApprovalResponseSchema.safeParse(body2);
           return parsed.success && parsed.data.status === "pending_approval";
@@ -7667,25 +7913,38 @@ var ZapierApiClient = class {
       });
     } catch (err) {
       if (!(err instanceof ZapierTimeoutError)) {
+        this.emitEvent("approval:error", {
+          approvalId: approval.id,
+          message: err instanceof Error ? err.message : String(err)
+        });
         throw err;
       }
       this.emitEvent("approval:timeout", {
-        approvalId: approval.approval_id
+        approvalId: approval.id
       });
       throw new ZapierApprovalError(
         `Approval timed out after ${timeoutMs / 1e3} seconds`,
         {
-          approvalId: approval.approval_id,
+          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", {
+        approvalId: approval.id,
+        message: `Failed to parse approval poll response: ${bodyPreview}`
+      });
       throw new ZapierApiError(
         `Failed to parse approval poll response: ${bodyPreview}`,
         {
@@ -7698,21 +7957,62 @@ var ZapierApiClient = class {
     const pollResult = pollParse.data;
     if (pollResult.status === "denied") {
       this.emitEvent("approval:denied", {
-        approvalId: approval.approval_id
+        approvalId: approval.id,
+        ...pollResult.reason ? { reason: pollResult.reason } : {}
       });
-      throw new ZapierApprovalError("Request denied by user", {
-        approvalId: approval.approval_id,
-        status: "denied"
+      throw new ZapierApprovalError(
+        pollResult.reason ? `Request denied: ${pollResult.reason}` : "Request denied by user",
+        {
+          approvalId: approval.id,
+          status: "denied",
+          reason: pollResult.reason
+        }
+      );
+    }
+    if (pollResult.status === "failed") {
+      this.throwApprovalFailed({
+        approvalId: approval.id,
+        approvalUrl: approval.approval_url,
+        pollUrl: approval.poll_url,
+        streamUrl: approval.stream_url,
+        reason: pollResult.reason
       });
     }
     if (pollResult.status !== "approved") {
+      this.emitEvent("approval:error", {
+        approvalId: approval.id,
+        message: `Unexpected approval status received: ${pollResult.status}`
+      });
       throw new ZapierApiError(
         `Unexpected approval status received: ${pollResult.status}`
       );
     }
     this.emitEvent("approval:approved", {
-      approvalId: approval.approval_id
+      approvalId: approval.id
+    });
+  }
+  throwApprovalFailed({
+    approvalId,
+    approvalUrl,
+    pollUrl,
+    streamUrl,
+    reason
+  }) {
+    this.emitEvent("approval:failed", {
+      approvalId,
+      ...reason ? { reason } : {}
     });
+    throw new ZapierApprovalError(
+      reason ? `Approval failed: ${reason}` : "Approval failed",
+      {
+        approvalId,
+        approvalUrl,
+        pollUrl,
+        streamUrl,
+        status: "failed",
+        reason
+      }
+    );
   }
 };
 var createZapierApi = (options) => {
@@ -7774,6 +8074,7 @@ var apiPlugin = definePlugin(
       approvalTimeoutMs,
       maxApprovalRetries,
       approvalMode,
+      openAutoModeApprovalsInBrowser,
       callerPackage
     } = sdk.context.options;
     const api = createZapierApi({
@@ -7789,6 +8090,7 @@ var apiPlugin = definePlugin(
       approvalTimeoutMs,
       maxApprovalRetries,
       approvalMode,
+      openAutoModeApprovalsInBrowser,
       callerPackage
     });
     return {
@@ -8781,6 +9083,260 @@ var zapierCorePlugin = createCorePlugin({
 function createZapierCoreStack() {
   return createPluginStack().use(zapierCorePlugin);
 }
+var GetConnectionStartUrlSchema = z.object({
+  app: AppPropertySchema
+}).describe(
+  "Mint a short-lived URL that begins an SDK-initiated connection flow. The URL is signed by zapier.com and bound to the current user/account \u2014 opening it in a different browser session will fail the binding check. Returns the URL as data so the caller decides what to do with it.\n\nUse this directly (rather than the higher-level `create-connection`) when you want either of: (a) hand off the URL and *not* block waiting for completion \u2014 call this alone, skip `wait-for-new-connection` entirely, or (b) do something custom between minting the URL and waiting for the connection \u2014 call this, then email or DM the URL, render it as a QR code for mobile sign-in, etc., then call `wait-for-new-connection`. For the common case where you'd just print and poll back-to-back, `create-connection` is one call.\n\nPair with `wait-for-new-connection` to detect completion: pass the `startedAt` returned here straight through (it's the server's mint time, so polling isn't affected by client clock skew). Example (JS):\n\n```ts\nconst { data: { url, app, startedAt } } = await zapier.getConnectionStartUrl({ app: 'slack' });\n// hand `url` off \u2014 print it, DM it, email it, render a button, whatever\nconst { data: conn } = await zapier.waitForNewConnection({ app, startedAt });\n```"
+);
+var GetConnectionStartUrlItemSchema = z.object({
+  url: z.string().describe(
+    "URL the user should open in their browser to complete the auth flow. Single-use, time-limited."
+  ),
+  expiresAt: z.number().describe(
+    "Unix timestamp (seconds) after which the URL's signature is rejected by zapier.com."
+  ),
+  startedAt: z.number().describe(
+    "Unix timestamp (seconds) when the server minted the URL. Use it as the `startedAt` for `wait-for-new-connection` so polling is anchored to server time rather than a possibly-skewed client clock."
+  ),
+  app: z.string().describe(
+    "Versionless app key the URL was minted for (e.g., 'SlackCLIAPI'). Useful for downstream filtering."
+  )
+}).describe(
+  "The signed start-URL plus metadata needed to poll for completion."
+);
+
+// src/plugins/getConnectionStartUrl/index.ts
+var START_PATH = "/zapier/api/authentications/v1/sdk/connections/start";
+var getConnectionStartUrlPlugin = definePlugin(
+  (sdk) => createPluginMethod(sdk, {
+    name: "getConnectionStartUrl",
+    categories: ["connection"],
+    type: "create",
+    itemType: "ConnectionStartUrl",
+    inputSchema: GetConnectionStartUrlSchema,
+    outputSchema: GetConnectionStartUrlItemSchema,
+    resolvers: { app: appKeyResolver },
+    handler: async ({
+      sdk: inner,
+      options
+    }) => {
+      const versionedKey = await inner.context.getVersionedImplementationId(
+        options.app
+      );
+      const selectedApi = versionedKey ? versionedKey.split("@")[0] : options.app;
+      setMethodMetadata({ selectedApi });
+      const response = await inner.context.api.post(
+        START_PATH,
+        { selected_api: selectedApi },
+        { authRequired: true }
+      );
+      return {
+        data: GetConnectionStartUrlItemSchema.parse({
+          url: response.url,
+          expiresAt: response.expires_at,
+          startedAt: response.started_at,
+          app: selectedApi
+        })
+      };
+    }
+  })
+);
+var WaitForNewConnectionSchema = z.object({
+  app: AppPropertySchema,
+  startedAt: z.number().int().nonnegative().describe(
+    "Unix timestamp (seconds). Only connections whose `date` is at or after this value count as 'new'. Prefer the `startedAt` returned by `get-connection-start-url` \u2014 it's server-stamped, so the comparison isn't thrown off by client clock skew. If you mint the timestamp yourself, capture it *before* showing the start URL so a fast OAuth completion isn't missed."
+  ),
+  timeoutMs: z.number().int().positive().optional().describe(
+    "How long to wait before giving up. Default 5 minutes (300_000)."
+  ),
+  pollIntervalMs: z.number().int().positive().optional().describe(
+    "Delay before the first poll request, in ms. Default 3 seconds (3_000). Subsequent polling cadence is managed by the SDK's polling primitive (backoff with sane defaults)."
+  )
+}).describe(
+  "Wait for a new connection to appear for the given app. Polls `/api/v0/connections` with server-side `ordering=-date` until the most recent matching row's `date` is at or after the started-at timestamp, then returns it. Pair with `get-connection-start-url` \u2014 that mints the URL the user opens, this waits for the resulting connection to land. Errors with a timeout after the configured timeout (default 5 min). Example (JS):\n\n```ts\nconst { data: { url, app, startedAt } } = await zapier.getConnectionStartUrl({ app: 'slack' });\n// show `url` to the user via the channel they're reading from\nconst { data: conn } = await zapier.waitForNewConnection({ app, startedAt });\n```"
+);
+var WaitForNewConnectionItemSchema = z.object({
+  id: z.string().describe(
+    "The new connection's ID. Public UUID when available, falling back to the numeric ID."
+  ),
+  app: z.string().describe(
+    "Versionless app key the connection was created for (e.g., 'SlackCLIAPI')."
+  ),
+  title: z.string().nullable().optional().describe(
+    "Human-readable connection title set by the auth flow, when available."
+  )
+}).describe("The new connection that was detected.");
+
+// src/plugins/waitForNewConnection/index.ts
+var CONNECTIONS_PATH = "/api/v0/connections";
+var waitForNewConnectionPlugin = definePlugin(
+  (sdk) => createPluginMethod(sdk, {
+    name: "waitForNewConnection",
+    categories: ["connection"],
+    type: "item",
+    itemType: "Connection",
+    inputSchema: WaitForNewConnectionSchema,
+    outputSchema: WaitForNewConnectionItemSchema,
+    resolvers: { app: appKeyResolver },
+    handler: async ({
+      sdk: inner,
+      options
+    }) => {
+      const versionedKey = await inner.context.getVersionedImplementationId(
+        options.app
+      );
+      const appKey = versionedKey ? versionedKey.split("@")[0] : options.app;
+      setMethodMetadata({ selectedApi: appKey });
+      try {
+        const top = await inner.context.api.poll(
+          CONNECTIONS_PATH,
+          {
+            searchParams: {
+              app_key: appKey,
+              // Scope to the current user's own connections. The connection
+              // we're waiting on is by definition owned by the caller; without
+              // this the one-row head-check could match a teammate's freshly
+              // created connection for the same app.
+              owner: "me",
+              is_expired: "false",
+              ordering: "-date",
+              page_size: "1"
+            },
+            authRequired: true,
+            timeoutMs: options.timeoutMs ?? 3e5,
+            initialDelay: options.pollIntervalMs ?? 3e3,
+            isPending: (body) => {
+              const rows = body.data ?? [];
+              const head = rows[0];
+              if (!head?.date) return true;
+              const created = Math.floor(new Date(head.date).getTime() / 1e3);
+              return !Number.isFinite(created) || created < options.startedAt;
+            },
+            resultExtractor: (body) => (
+              // `isPending` guaranteed a fresh row at index 0 before this fires.
+              body.data[0]
+            )
+          }
+        );
+        return {
+          data: WaitForNewConnectionItemSchema.parse({
+            id: String(top.public_id ?? top.id),
+            app: appKey,
+            title: top.title ?? null
+          })
+        };
+      } catch (err) {
+        if (err instanceof ZapierTimeoutError) {
+          throw new ZapierTimeoutError(
+            `Timed out waiting for a new "${appKey}" connection. If the user completed the auth flow, retrieve the connection via sdk.getConnection({ id }) with the ID shown on the completion page.`
+          );
+        }
+        throw err;
+      }
+    }
+  })
+);
+
+// src/utils/should-open-browser.ts
+function shouldOpenBrowser() {
+  if (isCiEnv()) return false;
+  const env = globalThis.process?.env;
+  if (env?.SSH_TTY || env?.SSH_CONNECTION) return false;
+  if (globalThis.process?.platform === "linux" && !env?.DISPLAY && !env?.WAYLAND_DISPLAY) {
+    return false;
+  }
+  return true;
+}
+function isCiEnv() {
+  const env = globalThis.process?.env;
+  return !!(env?.CI || env?.CONTINUOUS_INTEGRATION || env?.GITHUB_ACTIONS || env?.JENKINS_URL || env?.GITLAB_CI || env?.CIRCLECI || env?.TRAVIS || env?.BUILDKITE || env?.DRONE || env?.BITBUCKET_PIPELINES_UUID);
+}
+var CreateConnectionSchema = z.object({
+  app: AppPropertySchema,
+  browser: z.enum(["auto", "always", "never"]).default("auto").describe(
+    "When to auto-open the URL in a browser. `auto` (default) opens in local sessions and skips opening in CI / SSH / headless-Linux. `always` forces the open attempt. `never` skips it. The URL is always printed to stderr regardless \u2014 a failed or skipped open degrades gracefully to copy-paste."
+  ),
+  timeoutMs: z.number().int().positive().optional().describe(
+    "How long to wait for the user to complete the connection flow before giving up. Default 5 minutes (300_000)."
+  ),
+  pollIntervalMs: z.number().int().positive().optional().describe(
+    "Delay before the first poll request, in ms. Default 3 seconds (3_000). Subsequent polling cadence is managed by the SDK's polling primitive (backoff with sane defaults)."
+  )
+}).describe(
+  "Create a new app connection, end-to-end. Mints the start URL via `get-connection-start-url`, prints it to stderr, opportunistically opens it in a browser when it looks safe to do so (skipping CI / SSH / headless-Linux by default \u2014 pass `--browser always` to force, `--browser never` to suppress), then polls via `wait-for-new-connection` until the user completes OAuth and the new connection appears. Returns the connection.\n\nThis is the right command for most callers. Reach for the lower-level building blocks when you want either of: (a) hand off the URL and *not* block on completion \u2014 call `get-connection-start-url` alone, no `wait-for-new-connection` needed, or (b) do something custom between minting the URL and waiting \u2014 call `get-connection-start-url`, do your work (email or DM the URL, render a QR code, etc.), then `wait-for-new-connection`."
+);
+var CreateConnectionItemSchema = z.object({
+  id: z.string().describe(
+    "The new connection's ID. Public UUID when available, falling back to the numeric ID."
+  ),
+  app: z.string().describe(
+    "Versionless app key the connection was created for (e.g., 'SlackCLIAPI')."
+  ),
+  title: z.string().nullable().optional().describe(
+    "Human-readable connection title set by the auth flow, when available."
+  )
+}).describe("The newly created connection.");
+
+// src/plugins/createConnection/index.ts
+var createConnectionPlugin = definePlugin(
+  (sdk) => createPluginMethod(sdk, {
+    name: "createConnection",
+    categories: ["connection"],
+    type: "create",
+    itemType: "Connection",
+    inputSchema: CreateConnectionSchema,
+    outputSchema: CreateConnectionItemSchema,
+    resolvers: { app: appKeyResolver },
+    formatter: {
+      format: (item) => ({
+        title: `Connection created: ${item.title || item.id}`,
+        id: item.id,
+        details: [
+          { text: `App: ${item.app}`, style: "normal" },
+          { text: `ID:  ${item.id}`, style: "accent" }
+        ]
+      })
+    },
+    handler: async ({
+      sdk: inner,
+      options
+    }) => {
+      const { data: start } = await inner.getConnectionStartUrl({
+        app: options.app
+      });
+      setMethodMetadata({ selectedApi: start.app });
+      console.error(
+        `
+Open this URL to complete the connection:
+  ${start.url}
+`
+      );
+      const shouldOpen = options.browser === "always" || options.browser === "auto" && shouldOpenBrowser();
+      if (shouldOpen) {
+        try {
+          await open_url_default(start.url);
+        } catch {
+        }
+      }
+      const { data: fresh } = await inner.waitForNewConnection({
+        app: start.app,
+        // Server-stamped mint time: measured on the same clock as a
+        // connection's `date`, so the freshness check is immune to
+        // client/server clock skew.
+        startedAt: start.startedAt,
+        timeoutMs: options.timeoutMs,
+        pollIntervalMs: options.pollIntervalMs
+      });
+      return {
+        data: CreateConnectionItemSchema.parse({
+          id: fresh.id,
+          app: start.app,
+          title: fresh.title ?? null
+        })
+      };
+    }
+  })
+);
 
 // src/plugins/deprecated/authentications.ts
 var listAuthenticationsPlugin = definePlugin(
@@ -9636,7 +10192,7 @@ function createZapierSdkWithoutRegistry(options = {}) {
   return createZapierSdk(options);
 }
 function createZapierSdkStack(options = {}) {
-  return createZapierCoreStack().use(createOptionsPlugin(options)).use(eventEmissionPlugin).use(apiPlugin).use(manifestPlugin).use(capabilitiesPlugin).use(connectionsPlugin).use(listAppsPlugin).use(getAppPlugin).use(listConnectionsPlugin).use(getConnectionPlugin).use(findFirstConnectionPlugin).use(findUniqueConnectionPlugin).use(listActionsPlugin).use(getActionPlugin).use(listActionInputFieldsPlugin).use(getActionInputFieldsSchemaPlugin).use(listActionInputFieldChoicesPlugin).use(listInputFieldsDeprecatedPlugin).use(getInputFieldsSchemaDeprecatedPlugin).use(listInputFieldChoicesDeprecatedPlugin).use(runActionPlugin).use(listAuthenticationsPlugin).use(getAuthenticationPlugin).use(findFirstAuthenticationPlugin).use(findUniqueAuthenticationPlugin).use(listClientCredentialsPlugin).use(createClientCredentialsPlugin).use(deleteClientCredentialsPlugin).use(fetchPlugin).use(requestPlugin).use(listTablesPlugin).use(getTablePlugin).use(deleteTablePlugin).use(createTablePlugin).use(listTableFieldsPlugin).use(createTableFieldsPlugin).use(deleteTableFieldsPlugin).use(listTableRecordsPlugin).use(getTableRecordPlugin).use(createTableRecordsPlugin).use(deleteTableRecordsPlugin).use(updateTableRecordsPlugin).use(appsPlugin).use(getProfilePlugin);
+  return createZapierCoreStack().use(createOptionsPlugin(options)).use(eventEmissionPlugin).use(apiPlugin).use(manifestPlugin).use(capabilitiesPlugin).use(connectionsPlugin).use(listAppsPlugin).use(getAppPlugin).use(listConnectionsPlugin).use(getConnectionPlugin).use(findFirstConnectionPlugin).use(findUniqueConnectionPlugin).use(getConnectionStartUrlPlugin).use(waitForNewConnectionPlugin).use(createConnectionPlugin).use(listActionsPlugin).use(getActionPlugin).use(listActionInputFieldsPlugin).use(getActionInputFieldsSchemaPlugin).use(listActionInputFieldChoicesPlugin).use(listInputFieldsDeprecatedPlugin).use(getInputFieldsSchemaDeprecatedPlugin).use(listInputFieldChoicesDeprecatedPlugin).use(runActionPlugin).use(listAuthenticationsPlugin).use(getAuthenticationPlugin).use(findFirstAuthenticationPlugin).use(findUniqueAuthenticationPlugin).use(listClientCredentialsPlugin).use(createClientCredentialsPlugin).use(deleteClientCredentialsPlugin).use(fetchPlugin).use(requestPlugin).use(listTablesPlugin).use(getTablePlugin).use(deleteTablePlugin).use(createTablePlugin).use(listTableFieldsPlugin).use(createTableFieldsPlugin).use(deleteTableFieldsPlugin).use(listTableRecordsPlugin).use(getTableRecordPlugin).use(createTableRecordsPlugin).use(deleteTableRecordsPlugin).use(updateTableRecordsPlugin).use(appsPlugin).use(getProfilePlugin);
 }
 function createZapierSdk(options = {}) {
   return withDeprecatedAddPlugin(createZapierSdkStack(options).toSdk());
@@ -9682,7 +10238,10 @@ var BaseSdkOptionsSchema = z.object({
     "Maximum number of sequential approval rounds per request (one per gating policy) before giving up. Default: 2."
   ),
   approvalMode: z.enum(["disabled", "poll", "throw"]).optional().describe(
-    'Approval flow behavior. "poll" creates the approval, opens it in a browser, polls until resolved, and retries the original request. "throw" creates the approval and throws a ZapierApprovalError with the approval URL so the caller can surface it. "disabled" throws a ZapierApprovalError on approval-required responses without creating an approval. Resolution order is: explicit option, then ZAPIER_APPROVAL_MODE, then the default behavior (poll for interactive TTY, throw otherwise).'
+    'Approval flow behavior for manual approvals. "poll" creates the approval, opens it in a browser, polls until resolved, and retries the original request. "throw" creates the manual approval and throws a ZapierApprovalError with the approval URL so the caller can surface it. Server-created auto-mode approvals always poll until they reach a terminal status and retry the original request on approval, even when this option is "throw". "disabled" throws a ZapierApprovalError on approval-required responses without creating an approval. Resolution order is: explicit option, then ZAPIER_APPROVAL_MODE, then the default behavior (poll for interactive TTY, throw otherwise).'
+  ),
+  openAutoModeApprovalsInBrowser: z.boolean().optional().describe(
+    "By default, auto-mode approvals do not open in a browser. Enable this option to open the approval URL and watch the approval process. Resolution order is: explicit option, then ZAPIER_OPEN_AUTO_MODE_APPROVALS_IN_BROWSER, then false."
   ),
   // Internal
   manifestPath: z.string().optional().describe("Path to a .zapierrc manifest file for app version locking.").meta({ internal: true }),
@@ -9708,4 +10267,4 @@ var registryPlugin = definePlugin((_sdk) => {
   return {};
 });
 
-export { ActionKeyPropertySchema, ActionPropertySchema, ActionTimeoutMsPropertySchema, ActionTypePropertySchema, AppKeyPropertySchema, AppPropertySchema, AppsPropertySchema, AuthenticationIdPropertySchema, BaseSdkOptionsSchema, CONTEXT_CACHE_MAX_SIZE, CONTEXT_CACHE_TTL_MS, CORE_ERROR_SYMBOL, ClientCredentialsObjectSchema, ConnectionEntrySchema, ConnectionIdPropertySchema, ConnectionPropertySchema, ConnectionsMapSchema, ConnectionsPropertySchema, CoreErrorCode, 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, LeaseLimitPropertySchema, LeasePropertySchema, LeaseSecondsPropertySchema, LimitPropertySchema, MAX_CONCURRENCY_LIMIT, MAX_PAGE_LIMIT, OffsetPropertySchema, OutputPropertySchema, ParamsPropertySchema, PkceCredentialsObjectSchema, RecordPropertySchema, RecordsPropertySchema, RelayFetchSchema, RelayRequestSchema, ResolvedCredentialsSchema, TablePropertySchema, TablesPropertySchema, TriggerInboxNamePropertySchema, TriggerInboxPropertySchema, ZAPIER_BASE_URL, ZAPIER_MAX_CONCURRENT_REQUESTS, ZAPIER_MAX_NETWORK_RETRIES, ZAPIER_MAX_NETWORK_RETRY_DELAY_MS, ZapierAbortDrainSignal, ZapierActionError, ZapierApiError, ZapierAppNotFoundError, ZapierApprovalError, ZapierAuthenticationError, ZapierBundleError, ZapierConfigurationError, ZapierConflictError, ZapierError, ZapierNotFoundError, ZapierRateLimitError, ZapierRelayError, ZapierReleaseTriggerMessageSignal, ZapierResourceNotFoundError, ZapierSignal, ZapierTimeoutError, ZapierUnknownError, ZapierValidationError, actionKeyResolver, actionTypeResolver, addPlugin, apiPlugin, appKeyResolver, appsPlugin, connectionIdGenericResolver as authenticationIdGenericResolver, connectionIdResolver as authenticationIdResolver, batch, buildApplicationLifecycleEvent, buildCapabilityMessage, buildErrorEvent, buildErrorEventWithContext, buildMethodCalledEvent, cleanupEventListeners, clearTokenCache, clientCredentialsNameResolver, clientIdResolver, composePlugins, connectionIdGenericResolver, connectionIdResolver, connectionsPlugin, createBaseEvent, createClientCredentialsPlugin, createCorePlugin, createFunction, createMemoryCache, createOptionsPlugin, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createSdk, createTableFieldsPlugin, createTablePlugin, createTableRecordsPlugin, createZapierApi, createZapierCoreStack, createZapierSdk, createZapierSdkStack, createZapierSdkWithoutRegistry, definePlugin, deleteClientCredentialsPlugin, deleteTableFieldsPlugin, deleteTablePlugin, deleteTableRecordsPlugin, durableRunIdResolver, eventEmissionPlugin, fetchPlugin, findFirstConnectionPlugin, findManifestEntry, findUniqueConnectionPlugin, formatErrorMessage, generateEventId, getActionInputFieldsSchemaPlugin, getActionPlugin, getAgent, getAppPlugin, getBaseUrlFromCredentials, getCiPlatform, getClientIdFromCredentials, getConnectionPlugin, getCoreErrorCause, getCoreErrorCode, getCpuTime, getCurrentTimestamp, getMemoryUsage, getOrCreateApiClient, getOsInfo, getPlatformVersions, getPreferredManifestEntryKey, getProfilePlugin, getReleaseId, getTablePlugin, getTableRecordPlugin, getTokenFromCliLogin, getTtyContext, getZapierApprovalMode, getZapierDefaultApprovalMode, getZapierSdkService, injectCliLogin, inputFieldKeyResolver, inputsAllOptionalResolver, inputsResolver, invalidateCachedToken, invalidateCredentialsToken, isCi, isCliLoginAvailable, isClientCredentials, isCoreError, isCredentialsFunction, isCredentialsObject, isPermanentHttpError, isPkceCredentials, isPositional, listActionInputFieldChoicesPlugin, listActionInputFieldsPlugin, listActionsPlugin, listAppsPlugin, listClientCredentialsPlugin, listConnectionsPlugin, listTableFieldsPlugin, listTableRecordsPlugin, listTablesPlugin, logDeprecation2 as logDeprecation, manifestPlugin, parseConcurrencyEnvVar, readManifestFromFile, registryPlugin, requestPlugin, resetDeprecationWarnings2 as resetDeprecationWarnings, resolveAuthToken, resolveCredentials, resolveCredentialsFromEnv, runActionPlugin, runInMethodScope, runWithTelemetryContext, tableFieldIdsResolver, tableFieldsResolver, tableFiltersResolver, tableIdResolver, tableNameResolver, tableRecordIdResolver, tableRecordIdsResolver, tableRecordsResolver, tableSortResolver, tableUpdateRecordsResolver, toSnakeCase, toTitleCase, triggerInboxResolver, triggerMessagesResolver, updateTableRecordsPlugin, workflowIdResolver, workflowRunIdResolver, workflowVersionIdResolver, zapierAdaptError };
+export { ActionKeyPropertySchema, ActionPropertySchema, ActionTimeoutMsPropertySchema, ActionTypePropertySchema, AppKeyPropertySchema, AppPropertySchema, AppsPropertySchema, AuthenticationIdPropertySchema, BaseSdkOptionsSchema, CONTEXT_CACHE_MAX_SIZE, CONTEXT_CACHE_TTL_MS, CORE_ERROR_SYMBOL, ClientCredentialsObjectSchema, ConnectionEntrySchema, ConnectionIdPropertySchema, ConnectionPropertySchema, ConnectionsMapSchema, ConnectionsPropertySchema, CoreErrorCode, 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, LeaseLimitPropertySchema, LeasePropertySchema, LeaseSecondsPropertySchema, LimitPropertySchema, MAX_CONCURRENCY_LIMIT, MAX_PAGE_LIMIT, OffsetPropertySchema, OutputPropertySchema, ParamsPropertySchema, PkceCredentialsObjectSchema, RecordPropertySchema, RecordsPropertySchema, RelayFetchSchema, RelayRequestSchema, ResolvedCredentialsSchema, TablePropertySchema, TablesPropertySchema, TriggerInboxNamePropertySchema, TriggerInboxPropertySchema, ZAPIER_BASE_URL, ZAPIER_MAX_CONCURRENT_REQUESTS, ZAPIER_MAX_NETWORK_RETRIES, ZAPIER_MAX_NETWORK_RETRY_DELAY_MS, ZapierAbortDrainSignal, ZapierActionError, ZapierApiError, ZapierAppNotFoundError, ZapierApprovalError, ZapierAuthenticationError, ZapierBundleError, ZapierConfigurationError, ZapierConflictError, ZapierError, ZapierNotFoundError, ZapierRateLimitError, ZapierRelayError, ZapierReleaseTriggerMessageSignal, ZapierResourceNotFoundError, ZapierSignal, ZapierTimeoutError, ZapierUnknownError, ZapierValidationError, actionKeyResolver, actionTypeResolver, addPlugin, apiPlugin, appKeyResolver, appsPlugin, connectionIdGenericResolver as authenticationIdGenericResolver, connectionIdResolver as authenticationIdResolver, batch, buildApplicationLifecycleEvent, buildCapabilityMessage, buildErrorEvent, buildErrorEventWithContext, buildMethodCalledEvent, cleanupEventListeners, clearTokenCache, clientCredentialsNameResolver, clientIdResolver, composePlugins, connectionIdGenericResolver, connectionIdResolver, connectionsPlugin, createBaseEvent, createClientCredentialsPlugin, createCorePlugin, createFunction, createMemoryCache, createOptionsPlugin, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createSdk, createTableFieldsPlugin, createTablePlugin, createTableRecordsPlugin, createZapierApi, createZapierCoreStack, createZapierSdk, createZapierSdkStack, createZapierSdkWithoutRegistry, definePlugin, deleteClientCredentialsPlugin, deleteTableFieldsPlugin, deleteTablePlugin, deleteTableRecordsPlugin, durableRunIdResolver, eventEmissionPlugin, fetchPlugin, findFirstConnectionPlugin, findManifestEntry, findUniqueConnectionPlugin, formatErrorMessage, generateEventId, getActionInputFieldsSchemaPlugin, getActionPlugin, getAgent, getAppPlugin, getBaseUrlFromCredentials, getCiPlatform, getClientIdFromCredentials, getConnectionPlugin, getCoreErrorCause, getCoreErrorCode, getCpuTime, getCurrentTimestamp, getMemoryUsage, getOrCreateApiClient, getOsInfo, getPlatformVersions, getPreferredManifestEntryKey, getProfilePlugin, getReleaseId, getTablePlugin, getTableRecordPlugin, getTokenFromCliLogin, getTtyContext, getZapierApprovalMode, getZapierDefaultApprovalMode, getZapierOpenAutoModeApprovalsInBrowser, getZapierSdkService, injectCliLogin, inputFieldKeyResolver, inputsAllOptionalResolver, inputsResolver, invalidateCachedToken, invalidateCredentialsToken, isCi, isCliLoginAvailable, isClientCredentials, isCoreError, isCredentialsFunction, isCredentialsObject, isPermanentHttpError, isPkceCredentials, isPositional, listActionInputFieldChoicesPlugin, listActionInputFieldsPlugin, listActionsPlugin, listAppsPlugin, listClientCredentialsPlugin, listConnectionsPlugin, listTableFieldsPlugin, listTableRecordsPlugin, listTablesPlugin, logDeprecation2 as logDeprecation, manifestPlugin, parseConcurrencyEnvVar, readManifestFromFile, registryPlugin, requestPlugin, resetDeprecationWarnings2 as resetDeprecationWarnings, resolveAuthToken, resolveCredentials, resolveCredentialsFromEnv, runActionPlugin, runInMethodScope, runWithTelemetryContext, tableFieldIdsResolver, tableFieldsResolver, tableFiltersResolver, tableIdResolver, tableNameResolver, tableRecordIdResolver, tableRecordIdsResolver, tableRecordsResolver, tableSortResolver, tableUpdateRecordsResolver, toSnakeCase, toTitleCase, triggerInboxResolver, triggerMessagesResolver, updateTableRecordsPlugin, workflowIdResolver, workflowRunIdResolver, workflowVersionIdResolver, zapierAdaptError };