@zapier/zapier-sdk 0.70.4 → 0.71.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @zapier/zapier-sdk
 
+## 0.71.1
+
+### Patch Changes
+
+- 2521624: Rename `createWorkflow`'s `is_private` input to `private` to match `runDurable`, keeping `is_private` as a deprecated alias; the wire field stays `is_private`. Clarify the `run-durable` connections param description to show the required object shape.
+
+## 0.71.0
+
+### Minor Changes
+
+- 3474ff3: Add `createConnection` and two lower-level building blocks for connecting an app from code, end to end:
+  - `createConnection({ app, browser?, timeoutMs?, pollIntervalMs? })` — high-level: mints a connection URL, prints it (and opens it in a browser when it's safe to do so), waits for the user to finish, and returns the new connection. `browser` is `"auto"` (default — opens locally, skips CI / SSH / headless Linux), `"always"`, or `"never"`. The URL is always printed, so a skipped or failed open falls back to copy/paste.
+  - `getConnectionStartUrl({ app })` — low-level: mints a short-lived, signed start URL bound to the current user/account. Returns `{ url, startedAt, expiresAt, app }`.
+  - `waitForNewConnection({ app, startedAt, timeoutMs?, pollIntervalMs? })` — low-level: polls until a connection for the app created at or after `startedAt` appears, then returns `{ id, app, title? }`. Throws `ZapierTimeoutError` after `timeoutMs` (default 5 minutes).
+
+  `createConnection` is the right call for most cases. Reach for the two low-level methods when you want to hand off the URL without blocking (call `getConnectionStartUrl` alone), or do something custom between minting the URL and waiting — email it, post it to Slack, render a QR code — then call `waitForNewConnection`.
+
+### Patch Changes
+
+- 5ca445d: Add private-beta support for streaming auto-mode approval review messages and handling terminal failed approvals through the SDK and CLI. Auto mode is only enabled service-side for approved beta users.
+
 ## 0.70.4
 
 ### Patch Changes

package/README.md

@@ -46,10 +46,13 @@
   - [`triggerWorkflow`](#triggerworkflow--experimental)
   - [`updateWorkflow`](#updateworkflow--experimental)
 - [Connections](#connections)
+  - [`createConnection`](#createconnection)
   - [`findFirstConnection`](#findfirstconnection)
   - [`findUniqueConnection`](#finduniqueconnection)
   - [`getConnection`](#getconnection)
+  - [`getConnectionStartUrl`](#getconnectionstarturl)
   - [`listConnections`](#listconnections)
+  - [`waitForNewConnection`](#waitfornewconnection)
 - [HTTP Requests](#http-requests)
   - [`fetch`](#fetch)
 - [Tables](#tables)
@@ -349,21 +352,22 @@ console.log(emojiData.emoji);
 
 The `createZapierSdk(...)` factory function is the main entry point for the SDK. It provides methods for managing connections, listing apps, running actions, and more.
 
-| Name                          | Type                       | Required | Default | Possible Values             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ----------------------------- | -------------------------- | -------- | ------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `credentials`                 | `string, object, function` | ❌       | —       | —                           | Authentication credentials. Can be a string (token or API key), a client credentials object ({ clientId, clientSecret }), a PKCE object ({ clientId }), or a function returning any of those.                                                                                                                                                                                                                                                                                                      |
-| `debug`                       | `boolean`                  | ❌       | —       | —                           | Enable debug logging.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `baseUrl`                     | `string`                   | ❌       | —       | —                           | Base URL for Zapier API endpoints.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `trackingBaseUrl`             | `string`                   | ❌       | —       | —                           | Base URL for Zapier tracking endpoints.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `maxNetworkRetries`           | `number`                   | ❌       | —       | —                           | Max retries for rate-limited requests (default: 3).                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `maxNetworkRetryDelayMs`      | `number`                   | ❌       | —       | —                           | Max delay in ms to wait for retry (default: 60000).                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `maxConcurrentRequests`       | `number, literal`          | ❌       | —       | —                           | Max concurrent in-flight HTTP requests (default: 200, max: 10000).                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `approvalTimeoutMs`           | `number`                   | ❌       | —       | —                           | Timeout in ms for approval polling. Default: 600000 (10 min).                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `maxApprovalRetries`          | `number`                   | ❌       | —       | —                           | Maximum number of sequential approval rounds per request (one per gating policy) before giving up. Default: 2.                                                                                                                                                                                                                                                                                                                                                                                     |
-| `approvalMode`                | `string`                   | ❌       | —       | `disabled`, `poll`, `throw` | 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). |
-| `canIncludeSharedConnections` | `boolean`                  | ❌       | —       | —                           | Allow listing shared connections.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `canIncludeSharedTables`      | `boolean`                  | ❌       | —       | —                           | Allow listing shared tables.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `canDeleteTables`             | `boolean`                  | ❌       | —       | —                           | Allow deleting tables.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Name                             | Type                       | Required | Default | Possible Values             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| -------------------------------- | -------------------------- | -------- | ------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `credentials`                    | `string, object, function` | ❌       | —       | —                           | Authentication credentials. Can be a string (token or API key), a client credentials object ({ clientId, clientSecret }), a PKCE object ({ clientId }), or a function returning any of those.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `debug`                          | `boolean`                  | ❌       | —       | —                           | Enable debug logging.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `baseUrl`                        | `string`                   | ❌       | —       | —                           | Base URL for Zapier API endpoints.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `trackingBaseUrl`                | `string`                   | ❌       | —       | —                           | Base URL for Zapier tracking endpoints.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `maxNetworkRetries`              | `number`                   | ❌       | —       | —                           | Max retries for rate-limited requests (default: 3).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `maxNetworkRetryDelayMs`         | `number`                   | ❌       | —       | —                           | Max delay in ms to wait for retry (default: 60000).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `maxConcurrentRequests`          | `number, literal`          | ❌       | —       | —                           | Max concurrent in-flight HTTP requests (default: 200, max: 10000).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `approvalTimeoutMs`              | `number`                   | ❌       | —       | —                           | Timeout in ms for approval polling. Default: 600000 (10 min).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `maxApprovalRetries`             | `number`                   | ❌       | —       | —                           | Maximum number of sequential approval rounds per request (one per gating policy) before giving up. Default: 2.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `approvalMode`                   | `string`                   | ❌       | —       | `disabled`, `poll`, `throw` | 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` | `boolean`                  | ❌       | —       | —                           | 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `canIncludeSharedConnections`    | `boolean`                  | ❌       | —       | —                           | Allow listing shared connections.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `canIncludeSharedTables`         | `boolean`                  | ❌       | —       | —                           | Allow listing shared tables.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `canDeleteTables`                | `boolean`                  | ❌       | —       | —                           | Allow deleting tables.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 ## Named Connections
 
@@ -1141,7 +1145,7 @@ Create a durable workflow container. Starts disabled with no version; publish a
 | `options`         | `object`  | ✅       | —       | —               |                                                                                                       |
 | ​ ↳ `name`        | `string`  | ✅       | —       | —               | Workflow name                                                                                         |
 | ​ ↳ `description` | `string`  | ❌       | —       | —               | Optional description for the workflow                                                                 |
-| ​ ↳ `is_private`  | `boolean` | ❌       | —       | —               | If true, only the creating user can see or manage this workflow. Defaults to false (account-visible). |
+| ​ ↳ `private`     | `boolean` | ❌       | —       | —               | If true, only the creating user can see or manage this workflow. Defaults to false (account-visible). |
 
 **Returns:** `Promise<WorkflowItem>`
 
@@ -1701,21 +1705,21 @@ Run a workflow source file as a run-once durable run on sdkdurableapi (no deploy
 
 **Parameters:**
 
-| Name                         | Type       | Required | Default | Possible Values | Description                                                                                                     |
-| ---------------------------- | ---------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
-| `options`                    | `object`   | ✅       | —       | —               |                                                                                                                 |
-| ​ ↳ `source_files`           | `object`   | ✅       | —       | —               | Source files keyed by filename → contents                                                                       |
-| ​ ↳ `input`                  | `unknown`  | ❌       | —       | —               | Input data passed to the run                                                                                    |
-| ​ ↳ `dependencies`           | `object`   | ❌       | —       | —               | Optional npm package dependencies                                                                               |
-| ​ ↳ `zapier_durable_version` | `string`   | ❌       | —       | —               | Exact semver of @zapier/zapier-durable to use (e.g. "1.2.3"). Defaults to server-configured version if omitted. |
-| ​ ↳ `connections`            | `object`   | ❌       | —       | —               | Named connection aliases. Maps alias names to Zapier connection IDs.                                            |
-| ​ ↳ `app_versions`           | `object`   | ❌       | —       | —               | Pinned app versions. Maps app keys (slugs) to implementation names and versions.                                |
-| ​ ↳ `private`                | `boolean`  | ❌       | —       | —               | Only the creating user can see the run (default false)                                                          |
-| ​ ↳ `notifications[]`        | `object[]` | ❌       | —       | —               | Webhook subscribers for run lifecycle events. Each entry specifies a URL and the events it subscribes to.       |
-| ​   ↳ `type`                 | `string`   | ❌       | —       | `webhook`       | Notification transport. Webhook is the only supported type.                                                     |
-| ​   ↳ `url`                  | `string`   | ✅       | —       | —               | URL to POST event notifications to. Payload is `{run_id, event}`.                                               |
-| ​   ↳ `max_retries`          | `number`   | ❌       | —       | —               | Max delivery attempts with exponential backoff. Defaults to 3 server-side.                                      |
-| ​   ↳ `events`               | `array`    | ✅       | —       | —               | One or more lifecycle events to subscribe this URL to.                                                          |
+| Name                         | Type       | Required | Default | Possible Values | Description                                                                                                                              |
+| ---------------------------- | ---------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`                    | `object`   | ✅       | —       | —               |                                                                                                                                          |
+| ​ ↳ `source_files`           | `object`   | ✅       | —       | —               | Source files keyed by filename → contents                                                                                                |
+| ​ ↳ `input`                  | `unknown`  | ❌       | —       | —               | Input data passed to the run                                                                                                             |
+| ​ ↳ `dependencies`           | `object`   | ❌       | —       | —               | Optional npm package dependencies                                                                                                        |
+| ​ ↳ `zapier_durable_version` | `string`   | ❌       | —       | —               | Exact semver of @zapier/zapier-durable to use (e.g. "1.2.3"). Defaults to server-configured version if omitted.                          |
+| ​ ↳ `connections`            | `object`   | ❌       | —       | —               | Named connection aliases. Maps each alias to an object holding its Zapier connection ID, e.g. `{ "slack": { "connection_id": "123" } }`. |
+| ​ ↳ `app_versions`           | `object`   | ❌       | —       | —               | Pinned app versions. Maps app keys (slugs) to implementation names and versions.                                                         |
+| ​ ↳ `private`                | `boolean`  | ❌       | —       | —               | Only the creating user can see the run (default false)                                                                                   |
+| ​ ↳ `notifications[]`        | `object[]` | ❌       | —       | —               | Webhook subscribers for run lifecycle events. Each entry specifies a URL and the events it subscribes to.                                |
+| ​   ↳ `type`                 | `string`   | ❌       | —       | `webhook`       | Notification transport. Webhook is the only supported type.                                                                              |
+| ​   ↳ `url`                  | `string`   | ✅       | —       | —               | URL to POST event notifications to. Payload is `{run_id, event}`.                                                                        |
+| ​   ↳ `max_retries`          | `number`   | ❌       | —       | —               | Max delivery attempts with exponential backoff. Defaults to 3 server-side.                                                               |
+| ​   ↳ `events`               | `array`    | ✅       | —       | —               | One or more lifecycle events to subscribe this URL to.                                                                                   |
 
 **Returns:** `Promise<DurableRunItem>`
 
@@ -1802,6 +1806,39 @@ const result = await zapier.updateWorkflow({
 
 ### Connections
 
+#### `createConnection`
+
+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 — 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.
+
+This 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 — call `get-connection-start-url` alone, no `wait-for-new-connection` needed, or (b) do something custom between minting the URL and waiting — call `get-connection-start-url`, do your work (email or DM the URL, render a QR code, etc.), then `wait-for-new-connection`.
+
+**Parameters:**
+
+| Name                 | Type     | Required | Default  | Possible Values           | Description                                                                                                                                                                                                                                                                                       |
+| -------------------- | -------- | -------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`            | `object` | ✅       | —        | —                         |                                                                                                                                                                                                                                                                                                   |
+| ​ ↳ `app`            | `string` | ✅       | —        | —                         | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3')                                                                                                                                                                                      |
+| ​ ↳ `browser`        | `string` | ❌       | `"auto"` | `auto`, `always`, `never` | 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 — a failed or skipped open degrades gracefully to copy-paste. |
+| ​ ↳ `timeoutMs`      | `number` | ❌       | —        | —                         | How long to wait for the user to complete the connection flow before giving up. Default 5 minutes (300_000).                                                                                                                                                                                      |
+| ​ ↳ `pollIntervalMs` | `number` | ❌       | —        | —                         | 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).                                                                                                                         |
+
+**Returns:** `Promise<ConnectionItem>`
+
+| Name        | Type     | Required | Possible Values | Description                                                                          |
+| ----------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
+| `data`      | `object` | ✅       | —               |                                                                                      |
+| ​ ↳ `id`    | `string` | ✅       | —               | The new connection's ID. Public UUID when available, falling back to the numeric ID. |
+| ​ ↳ `app`   | `string` | ✅       | —               | Versionless app key the connection was created for (e.g., 'SlackCLIAPI').            |
+| ​ ↳ `title` | `string` | ❌       | —               | Human-readable connection title set by the auth flow, when available.                |
+
+**Example:**
+
+```typescript
+const result = await zapier.createConnection({
+  app: "example-app",
+});
+```
+
 #### `findFirstConnection`
 
 Find the first connection matching the criteria
@@ -1964,6 +2001,47 @@ Execute getConnection
 const { data: connection } = await zapier.getConnection();
 ```
 
+#### `getConnectionStartUrl`
+
+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 — 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.
+
+Use 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 — call this alone, skip `wait-for-new-connection` entirely, or (b) do something custom between minting the URL and waiting for the connection — 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.
+
+Pair 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):
+
+```ts
+const {
+  data: { url, app, startedAt },
+} = await zapier.getConnectionStartUrl({ app: "slack" });
+// hand `url` off — print it, DM it, email it, render a button, whatever
+const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
+```
+
+**Parameters:**
+
+| Name      | Type     | Required | Default | Possible Values | Description                                                                                                  |
+| --------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
+| `options` | `object` | ✅       | —       | —               |                                                                                                              |
+| ​ ↳ `app` | `string` | ✅       | —       | —               | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
+
+**Returns:** `Promise<ConnectionStartUrlItem>`
+
+| Name            | Type     | Required | Possible Values | Description                                                                                                                                                                                        |
+| --------------- | -------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`          | `object` | ✅       | —               |                                                                                                                                                                                                    |
+| ​ ↳ `url`       | `string` | ✅       | —               | URL the user should open in their browser to complete the auth flow. Single-use, time-limited.                                                                                                     |
+| ​ ↳ `expiresAt` | `number` | ✅       | —               | Unix timestamp (seconds) after which the URL's signature is rejected by zapier.com.                                                                                                                |
+| ​ ↳ `startedAt` | `number` | ✅       | —               | 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`       | `string` | ✅       | —               | Versionless app key the URL was minted for (e.g., 'SlackCLIAPI'). Useful for downstream filtering.                                                                                                 |
+
+**Example:**
+
+```typescript
+const result = await zapier.getConnectionStartUrl({
+  app: "example-app",
+});
+```
+
 #### `listConnections`
 
 List available connections with optional filtering
@@ -2036,6 +2114,46 @@ for await (const connection of zapier.listConnections().items()) {
 }
 ```
 
+#### `waitForNewConnection`
+
+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` — 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):
+
+```ts
+const {
+  data: { url, app, startedAt },
+} = await zapier.getConnectionStartUrl({ app: "slack" });
+// show `url` to the user via the channel they're reading from
+const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
+```
+
+**Parameters:**
+
+| Name                 | Type     | Required | Default | Possible Values | Description                                                                                                                                                                                                                                                                                                                                                            |
+| -------------------- | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`            | `object` | ✅       | —       | —               |                                                                                                                                                                                                                                                                                                                                                                        |
+| ​ ↳ `app`            | `string` | ✅       | —       | —               | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3')                                                                                                                                                                                                                                                           |
+| ​ ↳ `startedAt`      | `number` | ✅       | —       | —               | 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` — 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`      | `number` | ❌       | —       | —               | How long to wait before giving up. Default 5 minutes (300_000).                                                                                                                                                                                                                                                                                                        |
+| ​ ↳ `pollIntervalMs` | `number` | ❌       | —       | —               | 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).                                                                                                                                                                                              |
+
+**Returns:** `Promise<ConnectionItem>`
+
+| Name        | Type     | Required | Possible Values | Description                                                                          |
+| ----------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
+| `data`      | `object` | ✅       | —               |                                                                                      |
+| ​ ↳ `id`    | `string` | ✅       | —               | The new connection's ID. Public UUID when available, falling back to the numeric ID. |
+| ​ ↳ `app`   | `string` | ✅       | —               | Versionless app key the connection was created for (e.g., 'SlackCLIAPI').            |
+| ​ ↳ `title` | `string` | ❌       | —               | Human-readable connection title set by the auth flow, when available.                |
+
+**Example:**
+
+```typescript
+const { data: connection } = await zapier.waitForNewConnection({
+  app: "example-app",
+  startedAt: 100,
+});
+```
+
 ### HTTP Requests
 
 #### `fetch`

package/dist/api/approval-review-stream.d.ts

@@ -0,0 +1,25 @@
+import type { FetchStreamInit } from "./types";
+import type { JsonSseMessage } from "./sse-parser";
+interface ApprovalReviewMessagePayload {
+    kind: "message";
+    message: string;
+    data: unknown;
+}
+interface ApprovalReviewDecisionPayload {
+    kind: "decision";
+    decision: "approved" | "denied";
+    reason?: string;
+    data: unknown;
+}
+export type ApprovalReviewStreamPayload = ApprovalReviewMessagePayload | ApprovalReviewDecisionPayload;
+interface ConsumeApprovalReviewStreamOptions {
+    approvalId: string;
+    streamUrl: string;
+    signal: AbortSignal;
+    stream: (url: string, init?: FetchStreamInit) => AsyncGenerator<JsonSseMessage>;
+    emitEvent: (type: string, payload: Record<string, unknown>) => void;
+}
+export declare function consumeApprovalReviewStream({ approvalId, streamUrl, signal, stream, emitEvent, }: ConsumeApprovalReviewStreamOptions): Promise<void>;
+export declare function parseApprovalReviewStreamPayload(parsed: unknown, toolNames: Map<string, string>): ApprovalReviewStreamPayload | undefined;
+export {};
+//# sourceMappingURL=approval-review-stream.d.ts.map

package/dist/api/approval-review-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-review-stream.d.ts","sourceRoot":"","sources":["../../src/api/approval-review-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAmCnD,UAAU,4BAA4B;IACpC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,UAAU,6BAA6B;IACrC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,UAAU,GAAG,QAAQ,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,2BAA2B,GACnC,4BAA4B,GAC5B,6BAA6B,CAAC;AAElC,UAAU,kCAAkC;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,CACN,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,eAAe,KACnB,cAAc,CAAC,cAAc,CAAC,CAAC;IACpC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACrE;AAED,wBAAsB,2BAA2B,CAAC,EAChD,UAAU,EACV,SAAS,EACT,MAAM,EACN,MAAM,EACN,SAAS,GACV,EAAE,kCAAkC,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CpD;AAED,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,2BAA2B,GAAG,SAAS,CA8BzC"}

package/dist/api/approval-review-stream.js

@@ -0,0 +1,104 @@
+import { isAbortError } from "../utils/abort-utils";
+import { z } from "zod";
+const 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(),
+]);
+const ReportDecisionOutputSchema = z
+    .object({
+    success: z.boolean().optional(),
+    decision: z.enum(["approved", "denied"]),
+    reason: z.string().optional(),
+})
+    .passthrough();
+export async function consumeApprovalReviewStream({ approvalId, streamUrl, signal, stream, emitEvent, }) {
+    try {
+        const toolNames = 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),
+        });
+    }
+}
+export function parseApprovalReviewStreamPayload(parsed, toolNames) {
+    const chunk = ApprovalReviewChunkSchema.safeParse(parsed);
+    if (!chunk.success)
+        return undefined;
+    switch (chunk.data.type) {
+        case "text-delta": {
+            const message = chunk.data.delta.trim();
+            return message.length > 0
+                ? { kind: "message", data: parsed, message }
+                : undefined;
+        }
+        case "tool-input-available":
+            toolNames.set(chunk.data.toolCallId, chunk.data.toolName);
+            return undefined;
+        case "tool-output-available": {
+            if (toolNames.get(chunk.data.toolCallId) !== "report_decision") {
+                return undefined;
+            }
+            const decision = ReportDecisionOutputSchema.safeParse(chunk.data.output);
+            if (!decision.success)
+                return undefined;
+            return {
+                kind: "decision",
+                data: parsed,
+                decision: decision.data.decision,
+                ...(decision.data.reason ? { reason: decision.data.reason } : {}),
+            };
+        }
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAIjB,MAAM,SAAS,CAAC;AAk0CjB,eAAO,MAAM,eAAe,GAAI,SAAS,gBAAgB,KAAG,SAW3D,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAIjB,MAAM,SAAS,CAAC;AA2jDjB,eAAO,MAAM,eAAe,GAAI,SAAS,gBAAgB,KAAG,SAW3D,CAAC"}