@zapier/zapier-sdk 0.70.3 → 0.71.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +248 -95
  3. package/dist/api/approval-review-stream.d.ts +25 -0
  4. package/dist/api/approval-review-stream.d.ts.map +1 -0
  5. package/dist/api/approval-review-stream.js +104 -0
  6. package/dist/api/client.d.ts.map +1 -1
  7. package/dist/api/client.js +215 -27
  8. package/dist/api/types.d.ts +13 -3
  9. package/dist/api/types.d.ts.map +1 -1
  10. package/dist/constants.d.ts +1 -0
  11. package/dist/constants.d.ts.map +1 -1
  12. package/dist/constants.js +6 -0
  13. package/dist/experimental.cjs +702 -67
  14. package/dist/experimental.d.mts +242 -2
  15. package/dist/experimental.d.ts +240 -0
  16. package/dist/experimental.d.ts.map +1 -1
  17. package/dist/experimental.js +10 -0
  18. package/dist/experimental.mjs +702 -68
  19. package/dist/{index-rIzBEINC.d.mts → index-B43uST61.d.mts} +248 -10
  20. package/dist/{index-rIzBEINC.d.ts → index-B43uST61.d.ts} +248 -10
  21. package/dist/index.cjs +592 -32
  22. package/dist/index.d.mts +1 -1
  23. package/dist/index.mjs +592 -33
  24. package/dist/plugins/api/index.d.ts.map +1 -1
  25. package/dist/plugins/api/index.js +2 -1
  26. package/dist/plugins/codeSubstrate/deleteWorkflow/index.d.ts +9 -0
  27. package/dist/plugins/codeSubstrate/deleteWorkflow/index.d.ts.map +1 -1
  28. package/dist/plugins/codeSubstrate/disableWorkflow/index.d.ts +9 -0
  29. package/dist/plugins/codeSubstrate/disableWorkflow/index.d.ts.map +1 -1
  30. package/dist/plugins/codeSubstrate/enableWorkflow/index.d.ts +9 -0
  31. package/dist/plugins/codeSubstrate/enableWorkflow/index.d.ts.map +1 -1
  32. package/dist/plugins/codeSubstrate/getDurableRun/schemas.d.ts +5 -5
  33. package/dist/plugins/codeSubstrate/getTriggerRun/schemas.d.ts +1 -1
  34. package/dist/plugins/codeSubstrate/getWorkflow/index.d.ts +31 -0
  35. package/dist/plugins/codeSubstrate/getWorkflow/index.d.ts.map +1 -1
  36. package/dist/plugins/codeSubstrate/getWorkflow/schemas.d.ts +42 -0
  37. package/dist/plugins/codeSubstrate/getWorkflow/schemas.d.ts.map +1 -1
  38. package/dist/plugins/codeSubstrate/getWorkflow/schemas.js +20 -0
  39. package/dist/plugins/codeSubstrate/getWorkflowRun/index.d.ts +9 -0
  40. package/dist/plugins/codeSubstrate/getWorkflowRun/index.d.ts.map +1 -1
  41. package/dist/plugins/codeSubstrate/getWorkflowRun/schemas.d.ts +1 -1
  42. package/dist/plugins/codeSubstrate/getWorkflowVersion/index.d.ts +35 -0
  43. package/dist/plugins/codeSubstrate/getWorkflowVersion/index.d.ts.map +1 -1
  44. package/dist/plugins/codeSubstrate/getWorkflowVersion/schemas.d.ts +13 -0
  45. package/dist/plugins/codeSubstrate/getWorkflowVersion/schemas.d.ts.map +1 -1
  46. package/dist/plugins/codeSubstrate/getWorkflowVersion/schemas.js +10 -0
  47. package/dist/plugins/codeSubstrate/listDurableRuns/schemas.d.ts +3 -3
  48. package/dist/plugins/codeSubstrate/listWorkflowRuns/index.d.ts +9 -0
  49. package/dist/plugins/codeSubstrate/listWorkflowRuns/index.d.ts.map +1 -1
  50. package/dist/plugins/codeSubstrate/listWorkflowRuns/schemas.d.ts +3 -3
  51. package/dist/plugins/codeSubstrate/listWorkflowVersions/index.d.ts +22 -0
  52. package/dist/plugins/codeSubstrate/listWorkflowVersions/index.d.ts.map +1 -1
  53. package/dist/plugins/codeSubstrate/listWorkflowVersions/schemas.d.ts +26 -0
  54. package/dist/plugins/codeSubstrate/listWorkflowVersions/schemas.d.ts.map +1 -1
  55. package/dist/plugins/codeSubstrate/listWorkflowVersions/schemas.js +10 -0
  56. package/dist/plugins/codeSubstrate/listWorkflows/index.d.ts +9 -0
  57. package/dist/plugins/codeSubstrate/listWorkflows/index.d.ts.map +1 -1
  58. package/dist/plugins/codeSubstrate/listWorkflows/schemas.d.ts +32 -0
  59. package/dist/plugins/codeSubstrate/listWorkflows/schemas.d.ts.map +1 -1
  60. package/dist/plugins/codeSubstrate/listWorkflows/schemas.js +11 -0
  61. package/dist/plugins/codeSubstrate/publishWorkflowVersion/index.d.ts +22 -0
  62. package/dist/plugins/codeSubstrate/publishWorkflowVersion/index.d.ts.map +1 -1
  63. package/dist/plugins/codeSubstrate/publishWorkflowVersion/schemas.d.ts +14 -1
  64. package/dist/plugins/codeSubstrate/publishWorkflowVersion/schemas.d.ts.map +1 -1
  65. package/dist/plugins/codeSubstrate/publishWorkflowVersion/schemas.js +11 -44
  66. package/dist/plugins/codeSubstrate/runDurable/index.d.ts +6 -0
  67. package/dist/plugins/codeSubstrate/runDurable/index.d.ts.map +1 -1
  68. package/dist/plugins/codeSubstrate/runDurable/index.js +3 -0
  69. package/dist/plugins/codeSubstrate/runDurable/schemas.d.ts +12 -0
  70. package/dist/plugins/codeSubstrate/runDurable/schemas.d.ts.map +1 -1
  71. package/dist/plugins/codeSubstrate/runDurable/schemas.js +33 -0
  72. package/dist/plugins/codeSubstrate/shared-schemas.d.ts +37 -0
  73. package/dist/plugins/codeSubstrate/shared-schemas.d.ts.map +1 -0
  74. package/dist/plugins/codeSubstrate/shared-schemas.js +69 -0
  75. package/dist/plugins/codeSubstrate/triggerWorkflow/index.d.ts +9 -0
  76. package/dist/plugins/codeSubstrate/triggerWorkflow/index.d.ts.map +1 -1
  77. package/dist/plugins/codeSubstrate/updateWorkflow/index.d.ts +11 -0
  78. package/dist/plugins/codeSubstrate/updateWorkflow/index.d.ts.map +1 -1
  79. package/dist/plugins/codeSubstrate/updateWorkflow/schemas.d.ts +2 -0
  80. package/dist/plugins/codeSubstrate/updateWorkflow/schemas.d.ts.map +1 -1
  81. package/dist/plugins/codeSubstrate/updateWorkflow/schemas.js +7 -0
  82. package/dist/plugins/createConnection/index.d.ts +189 -0
  83. package/dist/plugins/createConnection/index.d.ts.map +1 -0
  84. package/dist/plugins/createConnection/index.js +71 -0
  85. package/dist/plugins/createConnection/schemas.d.ts +21 -0
  86. package/dist/plugins/createConnection/schemas.d.ts.map +1 -0
  87. package/dist/plugins/createConnection/schemas.js +38 -0
  88. package/dist/plugins/getConnectionStartUrl/index.d.ts +206 -0
  89. package/dist/plugins/getConnectionStartUrl/index.d.ts.map +1 -0
  90. package/dist/plugins/getConnectionStartUrl/index.js +39 -0
  91. package/dist/plugins/getConnectionStartUrl/schemas.d.ts +15 -0
  92. package/dist/plugins/getConnectionStartUrl/schemas.d.ts.map +1 -0
  93. package/dist/plugins/getConnectionStartUrl/schemas.js +23 -0
  94. package/dist/plugins/waitForNewConnection/index.d.ts +209 -0
  95. package/dist/plugins/waitForNewConnection/index.d.ts.map +1 -0
  96. package/dist/plugins/waitForNewConnection/index.js +75 -0
  97. package/dist/plugins/waitForNewConnection/schemas.d.ts +17 -0
  98. package/dist/plugins/waitForNewConnection/schemas.d.ts.map +1 -0
  99. package/dist/plugins/waitForNewConnection/schemas.js +39 -0
  100. package/dist/sdk.d.ts +126 -0
  101. package/dist/sdk.d.ts.map +1 -1
  102. package/dist/sdk.js +8 -0
  103. package/dist/types/errors.d.ts +13 -4
  104. package/dist/types/errors.d.ts.map +1 -1
  105. package/dist/types/errors.js +2 -0
  106. package/dist/types/sdk.d.ts +1 -0
  107. package/dist/types/sdk.d.ts.map +1 -1
  108. package/dist/types/sdk.js +5 -1
  109. package/dist/utils/open-url.d.ts.map +1 -1
  110. package/dist/utils/open-url.js +7 -0
  111. package/dist/utils/should-open-browser.d.ts +24 -0
  112. package/dist/utils/should-open-browser.d.ts.map +1 -0
  113. package/dist/utils/should-open-browser.js +55 -0
  114. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,40 @@
1
1
  # @zapier/zapier-sdk
2
2
 
3
+ ## 0.71.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 3474ff3: Add `createConnection` and two lower-level building blocks for connecting an app from code, end to end:
8
+ - `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.
9
+ - `getConnectionStartUrl({ app })` — low-level: mints a short-lived, signed start URL bound to the current user/account. Returns `{ url, startedAt, expiresAt, app }`.
10
+ - `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).
11
+
12
+ `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`.
13
+
14
+ ### Patch Changes
15
+
16
+ - 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.
17
+
18
+ ## 0.70.4
19
+
20
+ ### Patch Changes
21
+
22
+ - a790695: Response-field parity audit for the experimental code-substrate
23
+ plugins. Restores fields the backend returns that were silently
24
+ stripped by the SDK's Zod schemas after the port from
25
+ `@zapier/zapier-sdk-code-substrate`.
26
+ - `updateWorkflow`, `getWorkflow`, `listWorkflows` responses now
27
+ include `is_private`, `created_by_user_id`, and (where applicable)
28
+ `triggers` with live claim status.
29
+ - `publishWorkflowVersion`, `getWorkflowVersion`, `listWorkflowVersions`
30
+ responses now include `trigger`, `connections`, and `app_versions`.
31
+ - `runDurable` input accepts `notifications` (webhook subscribers for
32
+ run lifecycle events).
33
+
34
+ Shared schemas (`ConnectionBindingSchema`, `AppVersionBindingSchema`,
35
+ `WorkflowVersionTriggerConfigSchema`, `WorkflowTriggerSchema`) live in
36
+ a new `shared-schemas.ts` for reuse across the workflow plugins.
37
+
3
38
  ## 0.70.3
4
39
 
5
40
  ### Patch Changes
package/README.md CHANGED
@@ -46,10 +46,13 @@
46
46
  - [`triggerWorkflow`](#triggerworkflow--experimental)
47
47
  - [`updateWorkflow`](#updateworkflow--experimental)
48
48
  - [Connections](#connections)
49
+ - [`createConnection`](#createconnection)
49
50
  - [`findFirstConnection`](#findfirstconnection)
50
51
  - [`findUniqueConnection`](#finduniqueconnection)
51
52
  - [`getConnection`](#getconnection)
53
+ - [`getConnectionStartUrl`](#getconnectionstarturl)
52
54
  - [`listConnections`](#listconnections)
55
+ - [`waitForNewConnection`](#waitfornewconnection)
53
56
  - [HTTP Requests](#http-requests)
54
57
  - [`fetch`](#fetch)
55
58
  - [Tables](#tables)
@@ -349,21 +352,22 @@ console.log(emojiData.emoji);
349
352
 
350
353
  The `createZapierSdk(...)` factory function is the main entry point for the SDK. It provides methods for managing connections, listing apps, running actions, and more.
351
354
 
352
- | Name | Type | Required | Default | Possible Values | Description |
353
- | ----------------------------- | -------------------------- | -------- | ------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
354
- | `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. |
355
- | `debug` | `boolean` | ❌ | — | — | Enable debug logging. |
356
- | `baseUrl` | `string` | ❌ | — | — | Base URL for Zapier API endpoints. |
357
- | `trackingBaseUrl` | `string` | ❌ | — | — | Base URL for Zapier tracking endpoints. |
358
- | `maxNetworkRetries` | `number` | ❌ | — | — | Max retries for rate-limited requests (default: 3). |
359
- | `maxNetworkRetryDelayMs` | `number` | ❌ | — | — | Max delay in ms to wait for retry (default: 60000). |
360
- | `maxConcurrentRequests` | `number, literal` | ❌ | — | — | Max concurrent in-flight HTTP requests (default: 200, max: 10000). |
361
- | `approvalTimeoutMs` | `number` | ❌ | — | — | Timeout in ms for approval polling. Default: 600000 (10 min). |
362
- | `maxApprovalRetries` | `number` | ❌ | — | — | Maximum number of sequential approval rounds per request (one per gating policy) before giving up. Default: 2. |
363
- | `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). |
364
- | `canIncludeSharedConnections` | `boolean` | ❌ | — | — | Allow listing shared connections. |
365
- | `canIncludeSharedTables` | `boolean` | ❌ | — | — | Allow listing shared tables. |
366
- | `canDeleteTables` | `boolean` | ❌ | — | — | Allow deleting tables. |
355
+ | Name | Type | Required | Default | Possible Values | Description |
356
+ | -------------------------------- | -------------------------- | -------- | ------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
357
+ | `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. |
358
+ | `debug` | `boolean` | ❌ | — | — | Enable debug logging. |
359
+ | `baseUrl` | `string` | ❌ | — | — | Base URL for Zapier API endpoints. |
360
+ | `trackingBaseUrl` | `string` | ❌ | — | — | Base URL for Zapier tracking endpoints. |
361
+ | `maxNetworkRetries` | `number` | ❌ | — | — | Max retries for rate-limited requests (default: 3). |
362
+ | `maxNetworkRetryDelayMs` | `number` | ❌ | — | — | Max delay in ms to wait for retry (default: 60000). |
363
+ | `maxConcurrentRequests` | `number, literal` | ❌ | — | — | Max concurrent in-flight HTTP requests (default: 200, max: 10000). |
364
+ | `approvalTimeoutMs` | `number` | ❌ | — | — | Timeout in ms for approval polling. Default: 600000 (10 min). |
365
+ | `maxApprovalRetries` | `number` | ❌ | — | — | Maximum number of sequential approval rounds per request (one per gating policy) before giving up. Default: 2. |
366
+ | `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). |
367
+ | `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. |
368
+ | `canIncludeSharedConnections` | `boolean` | ❌ | — | — | Allow listing shared connections. |
369
+ | `canIncludeSharedTables` | `boolean` | ❌ | — | — | Allow listing shared tables. |
370
+ | `canDeleteTables` | `boolean` | ❌ | — | — | Allow deleting tables. |
367
371
 
368
372
  ## Named Connections
369
373
 
@@ -1326,24 +1330,35 @@ Get a durable workflow with its current version details and trigger claim status
1326
1330
 
1327
1331
  **Returns:** `Promise<WorkflowItem>`
1328
1332
 
1329
- | Name | Type | Required | Possible Values | Description |
1330
- | ------------------------------ | --------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
1331
- | `data` | `object` | ✅ | — | |
1332
- | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1333
- | ​ ↳ `name` | `string` | ✅ | — | Workflow name |
1334
- | ​ ↳ `description` | `string` | ✅ | — | Optional workflow description (null if unset) |
1335
- | ​ ↳ `trigger_url` | `string` | ✅ | — | Public webhook URL that fires this workflow when POSTed to. Embeds a secret trigger token in the path — treat as sensitive. |
1336
- | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
1337
- | ​ ↳ `current_version` | `object` | ❌ | — | The currently published version, if any. Absent for workflows with no version published yet. |
1338
- | ​   ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
1339
- | ​   ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID |
1340
- | ​   ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1341
- | ​   ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
1342
- | ​   ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
1343
- | ​   ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
1344
- | ​   ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
1345
- | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
1346
- | ​ ↳ `updated_at` | `string` | ✅ | — | When the workflow was last modified (ISO-8601) |
1333
+ | Name | Type | Required | Possible Values | Description |
1334
+ | ------------------------------ | ---------- | -------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
1335
+ | `data` | `object` | ✅ | — | |
1336
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1337
+ | ​ ↳ `name` | `string` | ✅ | — | Workflow name |
1338
+ | ​ ↳ `description` | `string` | ✅ | — | Optional workflow description (null if unset) |
1339
+ | ​ ↳ `trigger_url` | `string` | ✅ | — | Public webhook URL that fires this workflow when POSTed to. Embeds a secret trigger token in the path — treat as sensitive. |
1340
+ | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
1341
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
1342
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | User ID of the workflow creator (null in legacy data) |
1343
+ | ​ ↳ `current_version` | `object` | ❌ | — | The currently published version, if any. Absent for workflows with no version published yet. |
1344
+ | ​   ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
1345
+ | ​   ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID |
1346
+ | ​   ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1347
+ | ​   ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
1348
+ | ​   ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
1349
+ | ​   ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
1350
+ | ​   ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
1351
+ | ​   ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
1352
+ | ​   ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
1353
+ | ​   ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
1354
+ | ​ ↳ `triggers[]` | `object[]` | ✅ | — | Trigger configurations from the current version, with live claim status. Empty array when the workflow has no triggers. |
1355
+ | ​   ↳ `selected_api` | `string` | ✅ | — | Zapier app/API identifier (e.g. 'GoogleSheetsAPI') |
1356
+ | ​   ↳ `action` | `string` | ✅ | — | Trigger action key (e.g. 'new_row') |
1357
+ | ​   ↳ `authentication_id` | `string` | ❌ | — | Connection ID for the trigger source. Null for no-auth triggers. |
1358
+ | ​   ↳ `params` | `object` | ❌ | — | Trigger parameters as a JSON object |
1359
+ | ​   ↳ `status` | `string` | ✅ | `unclaimed`, `pending`, `active`, `releasing`, `released`, `failed` | Live trigger claim status — whether the trigger is currently subscribed to its source. |
1360
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
1361
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When the workflow was last modified (ISO-8601) |
1347
1362
 
1348
1363
  **Example:**
1349
1364
 
@@ -1403,16 +1418,19 @@ Get full details of a workflow version including source files
1403
1418
 
1404
1419
  **Returns:** `Promise<WorkflowVersionItem>`
1405
1420
 
1406
- | Name | Type | Required | Possible Values | Description |
1407
- | ---------------------------- | -------- | -------- | --------------- | ------------------------------------------------------------------- |
1408
- | `data` | `object` | ✅ | — | |
1409
- | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
1410
- | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
1411
- | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1412
- | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
1413
- | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
1414
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
1415
- | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
1421
+ | Name | Type | Required | Possible Values | Description |
1422
+ | ---------------------------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
1423
+ | `data` | `object` | ✅ | — | |
1424
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
1425
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
1426
+ | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1427
+ | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
1428
+ | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
1429
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
1430
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
1431
+ | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
1432
+ | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
1433
+ | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
1416
1434
 
1417
1435
  **Example:**
1418
1436
 
@@ -1541,16 +1559,19 @@ List published versions for a workflow, newest first
1541
1559
 
1542
1560
  **Returns:** `Promise<PaginatedResult<WorkflowVersionItem>>`
1543
1561
 
1544
- | Name | Type | Required | Possible Values | Description |
1545
- | ---------------------------- | ---------- | -------- | --------------- | ------------------------------------------------------------------- |
1546
- | `data[]` | `object[]` | ✅ | — | |
1547
- | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
1548
- | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
1549
- | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
1550
- | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
1551
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
1552
- | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
1553
- | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
1562
+ | Name | Type | Required | Possible Values | Description |
1563
+ | ---------------------------- | ---------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
1564
+ | `data[]` | `object[]` | ✅ | — | |
1565
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
1566
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
1567
+ | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
1568
+ | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
1569
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
1570
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
1571
+ | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
1572
+ | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
1573
+ | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
1574
+ | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
1554
1575
 
1555
1576
  **Example:**
1556
1577
 
@@ -1593,18 +1614,26 @@ List all active durable workflows for the authenticated account
1593
1614
 
1594
1615
  **Returns:** `Promise<PaginatedResult<WorkflowItem>>`
1595
1616
 
1596
- | Name | Type | Required | Possible Values | Description |
1597
- | ------------------------ | ---------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
1598
- | `data[]` | `object[]` | ✅ | — | |
1599
- | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1600
- | ​ ↳ `name` | `string` | ✅ | — | Workflow name |
1601
- | ​ ↳ `description` | `string` | ✅ | — | Optional workflow description (null if unset) |
1602
- | ​ ↳ `trigger_url` | `string` | ✅ | — | Public webhook URL that fires this workflow when POSTed to. Embeds a secret trigger token in the path — treat as sensitive. |
1603
- | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
1604
- | ​ ↳ `current_version_id` | `string` | ✅ | — | ID of the workflow version that runs handle. Null until a version is published. |
1605
- | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
1606
- | ​ ↳ `updated_at` | `string` | ✅ | — | When the workflow was last modified (ISO-8601) |
1607
- | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
1617
+ | Name | Type | Required | Possible Values | Description |
1618
+ | ------------------------- | ---------- | -------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
1619
+ | `data[]` | `object[]` | ✅ | — | |
1620
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1621
+ | ​ ↳ `name` | `string` | ✅ | — | Workflow name |
1622
+ | ​ ↳ `description` | `string` | ✅ | — | Optional workflow description (null if unset) |
1623
+ | ​ ↳ `trigger_url` | `string` | ✅ | — | Public webhook URL that fires this workflow when POSTed to. Embeds a secret trigger token in the path — treat as sensitive. |
1624
+ | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
1625
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
1626
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | User ID of the workflow creator (null in legacy data) |
1627
+ | ​ ↳ `current_version_id` | `string` | ✅ | — | ID of the workflow version that runs handle. Null until a version is published. |
1628
+ | ​ ↳ `triggers[]` | `object[]` | ✅ | — | Trigger configurations from the current version, with live claim status. Empty array when the workflow has no triggers. |
1629
+ | ​   ↳ `selected_api` | `string` | ✅ | — | Zapier app/API identifier (e.g. 'GoogleSheetsAPI') |
1630
+ | ​   ↳ `action` | `string` | ✅ | — | Trigger action key (e.g. 'new_row') |
1631
+ | ​   ↳ `authentication_id` | `string` | ❌ | — | Connection ID for the trigger source. Null for no-auth triggers. |
1632
+ | ​   ↳ `params` | `object` | ❌ | — | Trigger parameters as a JSON object |
1633
+ | ​   ↳ `status` | `string` | ✅ | `unclaimed`, `pending`, `active`, `releasing`, `released`, `failed` | Live trigger claim status — whether the trigger is currently subscribed to its source. |
1634
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
1635
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When the workflow was last modified (ISO-8601) |
1636
+ | `nextCursor` | `string` | ❌ | — | Cursor for the next page; omitted when there are no more pages |
1608
1637
 
1609
1638
  **Example:**
1610
1639
 
@@ -1647,16 +1676,19 @@ Publish a new version of a durable workflow. Enables the workflow by default.
1647
1676
 
1648
1677
  **Returns:** `Promise<WorkflowVersionItem>`
1649
1678
 
1650
- | Name | Type | Required | Possible Values | Description |
1651
- | ---------------------------- | -------- | -------- | --------------- | ------------------------------------------------------------------- |
1652
- | `data` | `object` | ✅ | — | |
1653
- | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
1654
- | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
1655
- | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1656
- | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
1657
- | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
1658
- | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
1659
- | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
1679
+ | Name | Type | Required | Possible Values | Description |
1680
+ | ---------------------------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
1681
+ | `data` | `object` | ✅ | — | |
1682
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow version ID (UUID) |
1683
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | Parent workflow ID (UUID) |
1684
+ | ​ ↳ `source_files` | `object` | ✅ | — | Source files keyed by filename → contents |
1685
+ | ​ ↳ `zapier_durable_version` | `string` | ✅ | — | Pinned semver of @zapier/zapier-durable used by this version's runs |
1686
+ | ​ ↳ `dependencies` | `object` | ✅ | — | Additional npm dependencies pinned for this version (or null) |
1687
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | ID of the user who published this version |
1688
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the version was published (ISO-8601) |
1689
+ | ​ ↳ `trigger` | `object` | ✅ | — | Trigger configuration persisted on this version, or null for webhook-only workflows. |
1690
+ | ​ ↳ `connections` | `object` | ✅ | — | Connection aliases bound on this version (or null). |
1691
+ | ​ ↳ `app_versions` | `object` | ✅ | — | App-version pins bound on this version (or null). |
1660
1692
 
1661
1693
  **Example:**
1662
1694
 
@@ -1673,16 +1705,21 @@ Run a workflow source file as a run-once durable run on sdkdurableapi (no deploy
1673
1705
 
1674
1706
  **Parameters:**
1675
1707
 
1676
- | Name | Type | Required | Default | Possible Values | Description |
1677
- | ---------------------------- | --------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
1678
- | `options` | `object` | ✅ | — | — | |
1679
- | ​ ↳ `source_files` | `object` | ✅ | — | — | Source files keyed by filename → contents |
1680
- | ​ ↳ `input` | `unknown` | ❌ | — | — | Input data passed to the run |
1681
- | ​ ↳ `dependencies` | `object` | ❌ | — | — | Optional npm package dependencies |
1682
- | ​ ↳ `zapier_durable_version` | `string` | ❌ | — | — | Exact semver of @zapier/zapier-durable to use (e.g. "1.2.3"). Defaults to server-configured version if omitted. |
1683
- | ​ ↳ `connections` | `object` | ❌ | — | — | Named connection aliases. Maps alias names to Zapier connection IDs. |
1684
- | ​ ↳ `app_versions` | `object` | ❌ | — | — | Pinned app versions. Maps app keys (slugs) to implementation names and versions. |
1685
- | ​ ↳ `private` | `boolean` | ❌ | — | — | Only the creating user can see the run (default false) |
1708
+ | Name | Type | Required | Default | Possible Values | Description |
1709
+ | ---------------------------- | ---------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
1710
+ | `options` | `object` | ✅ | — | — | |
1711
+ | ​ ↳ `source_files` | `object` | ✅ | — | — | Source files keyed by filename → contents |
1712
+ | ​ ↳ `input` | `unknown` | ❌ | — | — | Input data passed to the run |
1713
+ | ​ ↳ `dependencies` | `object` | ❌ | — | — | Optional npm package dependencies |
1714
+ | ​ ↳ `zapier_durable_version` | `string` | ❌ | — | — | Exact semver of @zapier/zapier-durable to use (e.g. "1.2.3"). Defaults to server-configured version if omitted. |
1715
+ | ​ ↳ `connections` | `object` | ❌ | — | — | Named connection aliases. Maps alias names to Zapier connection IDs. |
1716
+ | ​ ↳ `app_versions` | `object` | ❌ | — | — | Pinned app versions. Maps app keys (slugs) to implementation names and versions. |
1717
+ | ​ ↳ `private` | `boolean` | ❌ | — | — | Only the creating user can see the run (default false) |
1718
+ | ​ ↳ `notifications[]` | `object[]` | ❌ | — | — | Webhook subscribers for run lifecycle events. Each entry specifies a URL and the events it subscribes to. |
1719
+ | ​   ↳ `type` | `string` | ❌ | — | `webhook` | Notification transport. Webhook is the only supported type. |
1720
+ | ​   ↳ `url` | `string` | ✅ | — | — | URL to POST event notifications to. Payload is `{run_id, event}`. |
1721
+ | ​   ↳ `max_retries` | `number` | ❌ | — | — | Max delivery attempts with exponential backoff. Defaults to 3 server-side. |
1722
+ | ​   ↳ `events` | `array` | ✅ | — | — | One or more lifecycle events to subscribe this URL to. |
1686
1723
 
1687
1724
  **Returns:** `Promise<DurableRunItem>`
1688
1725
 
@@ -1746,16 +1783,18 @@ Update a durable workflow's name and/or description
1746
1783
 
1747
1784
  **Returns:** `Promise<WorkflowItem>`
1748
1785
 
1749
- | Name | Type | Required | Possible Values | Description |
1750
- | ----------------- | --------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
1751
- | `data` | `object` | ✅ | — | |
1752
- | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1753
- | ​ ↳ `name` | `string` | ✅ | — | Workflow name (post-update) |
1754
- | ​ ↳ `description` | `string` | ✅ | — | Workflow description, post-update (null if unset) |
1755
- | ​ ↳ `trigger_url` | `string` | ✅ | — | Public webhook URL that fires this workflow when POSTed to. Embeds a secret trigger token in the path — treat as sensitive. |
1756
- | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
1757
- | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
1758
- | ​ ↳ `updated_at` | `string` | ✅ | — | When this update was applied (ISO-8601) |
1786
+ | Name | Type | Required | Possible Values | Description |
1787
+ | ------------------------ | --------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
1788
+ | `data` | `object` | ✅ | — | |
1789
+ | ​ ↳ `id` | `string` | ✅ | — | Workflow ID (UUID) |
1790
+ | ​ ↳ `name` | `string` | ✅ | — | Workflow name (post-update) |
1791
+ | ​ ↳ `description` | `string` | ✅ | — | Workflow description, post-update (null if unset) |
1792
+ | ​ ↳ `trigger_url` | `string` | ✅ | — | Public webhook URL that fires this workflow when POSTed to. Embeds a secret trigger token in the path — treat as sensitive. |
1793
+ | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether the workflow currently accepts triggers |
1794
+ | ​ ↳ `is_private` | `boolean` | ✅ | — | Whether the workflow is private to the creating user. False means account-visible. |
1795
+ | ​ ↳ `created_by_user_id` | `string` | ✅ | — | User ID of the workflow creator (null in legacy data) |
1796
+ | ​ ↳ `created_at` | `string` | ✅ | — | When the workflow was created (ISO-8601) |
1797
+ | ​ ↳ `updated_at` | `string` | ✅ | — | When this update was applied (ISO-8601) |
1759
1798
 
1760
1799
  **Example:**
1761
1800
 
@@ -1767,6 +1806,39 @@ const result = await zapier.updateWorkflow({
1767
1806
 
1768
1807
  ### Connections
1769
1808
 
1809
+ #### `createConnection`
1810
+
1811
+ 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.
1812
+
1813
+ 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`.
1814
+
1815
+ **Parameters:**
1816
+
1817
+ | Name | Type | Required | Default | Possible Values | Description |
1818
+ | -------------------- | -------- | -------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1819
+ | `options` | `object` | ✅ | — | — | |
1820
+ | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
1821
+ | ​ ↳ `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. |
1822
+ | ​ ↳ `timeoutMs` | `number` | ❌ | — | — | How long to wait for the user to complete the connection flow before giving up. Default 5 minutes (300_000). |
1823
+ | ​ ↳ `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). |
1824
+
1825
+ **Returns:** `Promise<ConnectionItem>`
1826
+
1827
+ | Name | Type | Required | Possible Values | Description |
1828
+ | ----------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
1829
+ | `data` | `object` | ✅ | — | |
1830
+ | ​ ↳ `id` | `string` | ✅ | — | The new connection's ID. Public UUID when available, falling back to the numeric ID. |
1831
+ | ​ ↳ `app` | `string` | ✅ | — | Versionless app key the connection was created for (e.g., 'SlackCLIAPI'). |
1832
+ | ​ ↳ `title` | `string` | ❌ | — | Human-readable connection title set by the auth flow, when available. |
1833
+
1834
+ **Example:**
1835
+
1836
+ ```typescript
1837
+ const result = await zapier.createConnection({
1838
+ app: "example-app",
1839
+ });
1840
+ ```
1841
+
1770
1842
  #### `findFirstConnection`
1771
1843
 
1772
1844
  Find the first connection matching the criteria
@@ -1929,6 +2001,47 @@ Execute getConnection
1929
2001
  const { data: connection } = await zapier.getConnection();
1930
2002
  ```
1931
2003
 
2004
+ #### `getConnectionStartUrl`
2005
+
2006
+ 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.
2007
+
2008
+ 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.
2009
+
2010
+ 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):
2011
+
2012
+ ```ts
2013
+ const {
2014
+ data: { url, app, startedAt },
2015
+ } = await zapier.getConnectionStartUrl({ app: "slack" });
2016
+ // hand `url` off — print it, DM it, email it, render a button, whatever
2017
+ const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
2018
+ ```
2019
+
2020
+ **Parameters:**
2021
+
2022
+ | Name | Type | Required | Default | Possible Values | Description |
2023
+ | --------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
2024
+ | `options` | `object` | ✅ | — | — | |
2025
+ | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
2026
+
2027
+ **Returns:** `Promise<ConnectionStartUrlItem>`
2028
+
2029
+ | Name | Type | Required | Possible Values | Description |
2030
+ | --------------- | -------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2031
+ | `data` | `object` | ✅ | — | |
2032
+ | ​ ↳ `url` | `string` | ✅ | — | URL the user should open in their browser to complete the auth flow. Single-use, time-limited. |
2033
+ | ​ ↳ `expiresAt` | `number` | ✅ | — | Unix timestamp (seconds) after which the URL's signature is rejected by zapier.com. |
2034
+ | ​ ↳ `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. |
2035
+ | ​ ↳ `app` | `string` | ✅ | — | Versionless app key the URL was minted for (e.g., 'SlackCLIAPI'). Useful for downstream filtering. |
2036
+
2037
+ **Example:**
2038
+
2039
+ ```typescript
2040
+ const result = await zapier.getConnectionStartUrl({
2041
+ app: "example-app",
2042
+ });
2043
+ ```
2044
+
1932
2045
  #### `listConnections`
1933
2046
 
1934
2047
  List available connections with optional filtering
@@ -2001,6 +2114,46 @@ for await (const connection of zapier.listConnections().items()) {
2001
2114
  }
2002
2115
  ```
2003
2116
 
2117
+ #### `waitForNewConnection`
2118
+
2119
+ 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):
2120
+
2121
+ ```ts
2122
+ const {
2123
+ data: { url, app, startedAt },
2124
+ } = await zapier.getConnectionStartUrl({ app: "slack" });
2125
+ // show `url` to the user via the channel they're reading from
2126
+ const { data: conn } = await zapier.waitForNewConnection({ app, startedAt });
2127
+ ```
2128
+
2129
+ **Parameters:**
2130
+
2131
+ | Name | Type | Required | Default | Possible Values | Description |
2132
+ | -------------------- | -------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2133
+ | `options` | `object` | ✅ | — | — | |
2134
+ | ​ ↳ `app` | `string` | ✅ | — | — | App slug (e.g., 'github'), implementation name (e.g., 'SlackCLIAPI'), or versioned ID (e.g., 'github@1.2.3') |
2135
+ | ​ ↳ `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. |
2136
+ | ​ ↳ `timeoutMs` | `number` | ❌ | — | — | How long to wait before giving up. Default 5 minutes (300_000). |
2137
+ | ​ ↳ `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). |
2138
+
2139
+ **Returns:** `Promise<ConnectionItem>`
2140
+
2141
+ | Name | Type | Required | Possible Values | Description |
2142
+ | ----------- | -------- | -------- | --------------- | ------------------------------------------------------------------------------------ |
2143
+ | `data` | `object` | ✅ | — | |
2144
+ | ​ ↳ `id` | `string` | ✅ | — | The new connection's ID. Public UUID when available, falling back to the numeric ID. |
2145
+ | ​ ↳ `app` | `string` | ✅ | — | Versionless app key the connection was created for (e.g., 'SlackCLIAPI'). |
2146
+ | ​ ↳ `title` | `string` | ❌ | — | Human-readable connection title set by the auth flow, when available. |
2147
+
2148
+ **Example:**
2149
+
2150
+ ```typescript
2151
+ const { data: connection } = await zapier.waitForNewConnection({
2152
+ app: "example-app",
2153
+ startedAt: 100,
2154
+ });
2155
+ ```
2156
+
2004
2157
  ### HTTP Requests
2005
2158
 
2006
2159
  #### `fetch`
package/dist/api/approval-review-stream.d.ts ADDED
@@ -0,0 +1,25 @@
1
+ import type { FetchStreamInit } from "./types";
2
+ import type { JsonSseMessage } from "./sse-parser";
3
+ interface ApprovalReviewMessagePayload {
4
+ kind: "message";
5
+ message: string;
6
+ data: unknown;
7
+ }
8
+ interface ApprovalReviewDecisionPayload {
9
+ kind: "decision";
10
+ decision: "approved" | "denied";
11
+ reason?: string;
12
+ data: unknown;
13
+ }
14
+ export type ApprovalReviewStreamPayload = ApprovalReviewMessagePayload | ApprovalReviewDecisionPayload;
15
+ interface ConsumeApprovalReviewStreamOptions {
16
+ approvalId: string;
17
+ streamUrl: string;
18
+ signal: AbortSignal;
19
+ stream: (url: string, init?: FetchStreamInit) => AsyncGenerator<JsonSseMessage>;
20
+ emitEvent: (type: string, payload: Record<string, unknown>) => void;
21
+ }
22
+ export declare function consumeApprovalReviewStream({ approvalId, streamUrl, signal, stream, emitEvent, }: ConsumeApprovalReviewStreamOptions): Promise<void>;
23
+ export declare function parseApprovalReviewStreamPayload(parsed: unknown, toolNames: Map<string, string>): ApprovalReviewStreamPayload | undefined;
24
+ export {};
25
+ //# sourceMappingURL=approval-review-stream.d.ts.map
package/dist/api/approval-review-stream.d.ts.map ADDED
@@ -0,0 +1 @@
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"}