@zapier/zapier-sdk 0.70.4 → 0.71.1

package/dist/index.cjs

@@ -1060,6 +1060,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";
@@ -1283,6 +1288,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 {
@@ -6779,9 +6786,101 @@ function createSseParserStream() {
     }
   });
 }
+var ApprovalReviewChunkSchema = zod.z.discriminatedUnion("type", [
+  zod.z.object({
+    type: zod.z.literal("text-delta"),
+    delta: zod.z.string()
+  }).passthrough(),
+  zod.z.object({
+    type: zod.z.literal("tool-input-available"),
+    toolCallId: zod.z.string(),
+    toolName: zod.z.string()
+  }).passthrough(),
+  zod.z.object({
+    type: zod.z.literal("tool-output-available"),
+    toolCallId: zod.z.string(),
+    output: zod.z.unknown()
+  }).passthrough()
+]);
+var ReportDecisionOutputSchema = zod.z.object({
+  success: zod.z.boolean().optional(),
+  decision: zod.z.enum(["approved", "denied"]),
+  reason: zod.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.4" : void 0) || "unknown";
+var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.71.1" : void 0) || "unknown";
 
 // src/utils/open-url.ts
 var nodePrefix = "node:";
@@ -6833,6 +6932,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}`);
   }
@@ -6855,16 +6957,39 @@ async function openApproval(url) {
   } catch {
   }
 }
-var ApprovalStatusSchema = zod.z.enum(["pending_approval", "approved", "denied"]);
+var ApprovalStatusSchema = zod.z.enum([
+  "pending_approval",
+  "approved",
+  "denied",
+  "failed"
+]);
+var ApprovalModeSchema = zod.z.enum(["manual", "auto"]);
 var CreateApprovalResponseSchema = zod.z.object({
+  id: zod.z.string().optional(),
   status: ApprovalStatusSchema,
-  approval_id: zod.z.string(),
+  approval_id: zod.z.string().optional(),
+  mode: ApprovalModeSchema,
   approval_url: zod.z.string().url(),
-  poll_url: zod.z.string().url()
+  poll_url: zod.z.string().url(),
+  stream_url: zod.z.string().url().optional(),
+  reason: zod.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 zod.z.NEVER;
+  }
+  return { ...approval, id };
 });
 var PollApprovalResponseSchema = zod.z.object({
+  id: zod.z.string().optional(),
   status: ApprovalStatusSchema,
-  approval_id: zod.z.string()
+  approval_id: zod.z.string().optional(),
+  mode: ApprovalModeSchema.optional(),
+  reason: zod.z.string().optional()
 });
 var APPROVAL_MAX_POLLING_INTERVAL_MS = 5e3;
 function parseRateLimitHeaders(response) {
@@ -7137,7 +7262,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}`,
@@ -7165,6 +7294,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);
     };
@@ -7504,7 +7634,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
@@ -7522,13 +7652,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;
@@ -7554,12 +7733,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 {
@@ -7569,9 +7748,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
@@ -7624,6 +7805,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,
@@ -7631,19 +7815,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({
@@ -7654,14 +7898,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";
@@ -7669,25 +7915,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}`,
         {
@@ -7700,21 +7959,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) => {
@@ -7776,6 +8076,7 @@ var apiPlugin = definePlugin(
       approvalTimeoutMs,
       maxApprovalRetries,
       approvalMode,
+      openAutoModeApprovalsInBrowser,
       callerPackage
     } = sdk.context.options;
     const api = createZapierApi({
@@ -7791,6 +8092,7 @@ var apiPlugin = definePlugin(
       approvalTimeoutMs,
       maxApprovalRetries,
       approvalMode,
+      openAutoModeApprovalsInBrowser,
       callerPackage
     });
     return {
@@ -8783,6 +9085,260 @@ var zapierCorePlugin = createCorePlugin({
 function createZapierCoreStack() {
   return createPluginStack().use(zapierCorePlugin);
 }
+var GetConnectionStartUrlSchema = zod.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 = zod.z.object({
+  url: zod.z.string().describe(
+    "URL the user should open in their browser to complete the auth flow. Single-use, time-limited."
+  ),
+  expiresAt: zod.z.number().describe(
+    "Unix timestamp (seconds) after which the URL's signature is rejected by zapier.com."
+  ),
+  startedAt: zod.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: zod.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 = zod.z.object({
+  app: AppPropertySchema,
+  startedAt: zod.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: zod.z.number().int().positive().optional().describe(
+    "How long to wait before giving up. Default 5 minutes (300_000)."
+  ),
+  pollIntervalMs: zod.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 = zod.z.object({
+  id: zod.z.string().describe(
+    "The new connection's ID. Public UUID when available, falling back to the numeric ID."
+  ),
+  app: zod.z.string().describe(
+    "Versionless app key the connection was created for (e.g., 'SlackCLIAPI')."
+  ),
+  title: zod.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 = zod.z.object({
+  app: AppPropertySchema,
+  browser: zod.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: zod.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: zod.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 = zod.z.object({
+  id: zod.z.string().describe(
+    "The new connection's ID. Public UUID when available, falling back to the numeric ID."
+  ),
+  app: zod.z.string().describe(
+    "Versionless app key the connection was created for (e.g., 'SlackCLIAPI')."
+  ),
+  title: zod.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(
@@ -9638,7 +10194,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());
@@ -9684,7 +10240,10 @@ var BaseSdkOptionsSchema = zod.z.object({
     "Maximum number of sequential approval rounds per request (one per gating policy) before giving up. Default: 2."
   ),
   approvalMode: zod.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: zod.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: zod.z.string().optional().describe("Path to a .zapierrc manifest file for app version locking.").meta({ internal: true }),
@@ -9861,6 +10420,7 @@ exports.getTokenFromCliLogin = getTokenFromCliLogin;
 exports.getTtyContext = getTtyContext;
 exports.getZapierApprovalMode = getZapierApprovalMode;
 exports.getZapierDefaultApprovalMode = getZapierDefaultApprovalMode;
+exports.getZapierOpenAutoModeApprovalsInBrowser = getZapierOpenAutoModeApprovalsInBrowser;
 exports.getZapierSdkService = getZapierSdkService;
 exports.injectCliLogin = injectCliLogin;
 exports.inputFieldKeyResolver = inputFieldKeyResolver;