@zapier/zapier-sdk 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @zapier/zapier-sdk
 
+## 0.37.0
+
+### Minor Changes
+
+- 307aa98: Add named connections support. A new `connection` parameter on `runAction`, the apps proxy, and `fetch` resolves a connection alias (string) from a connections map, or accepts a numeric `connectionId` directly. The map is provided via the `connections` field in `.zapierrc` (or the inline `manifest` option on `createZapierSdk()`).
+
+## 0.36.0
+
+### Minor Changes
+
+- 3a447d3: Add support for pagination in Run Action
+
 ## 0.35.0
 
 ### Minor Changes

package/CLAUDE.md

@@ -237,6 +237,56 @@ Run `add` again when:
 - An app has been updated and you want the latest fields
 - You've deleted your generated types
 
+## Named Connections
+
+Named connections let you decouple workflow code from specific connection IDs. An external system (like an execution engine) provides the mapping via `.zapierrc`, and the workflow code references connections by name.
+
+### Providing the Mapping
+
+Connections are configured in `.zapierrc` alongside app version pins, or inline via the `manifest` option:
+
+```typescript
+const zapier = createZapierSdk({
+  manifest: {
+    apps: { slack: { implementationName: "SlackCLIAPI", version: "1.21.1" } },
+    connections: {
+      slack_work: { connectionId: 12345 },
+      google_sheets: { connectionId: 67890 },
+    },
+  },
+});
+```
+
+### Using Named Connections
+
+```typescript
+// Per-call with alias
+await zapier.apps.slack.read.channels({ connection: "slack_work" });
+
+// Factory binding
+const slack = zapier.apps.slack({ connection: "slack_work" });
+await slack.read.channels({});
+
+// Lower-level API
+await zapier.runAction({
+  appKey: "slack",
+  actionType: "read",
+  actionKey: "channels",
+  connection: "slack_work",
+});
+
+// Direct connectionId also works
+await zapier.apps.slack.read.channels({ connection: 12345 });
+```
+
+### Resolution Precedence
+
+For `connectionId`: explicit `connectionId` > `connection` alias lookup (strings) or direct use (numbers) > factory binding > deprecated `authenticationId`.
+
+App version is always resolved from the `.zapierrc` manifest, not from connections.
+
+`connectionId` and `connection` are mutually exclusive in the same call.
+
 ## Error Handling
 
 ### Debugging

package/README.md

@@ -329,6 +329,61 @@ The `createZapierSdk(...)` factory function is the main entry point for the SDK.
 | `maxNetworkRetries`      | `number`                   | ❌       | —       | —               | Max retries for rate-limited requests (default: 3).                                                                                                                                           |
 | `maxNetworkRetryDelayMs` | `number`                   | ❌       | —       | —               | Max delay in ms to wait for retry (default: 60000).                                                                                                                                           |
 
+## Named Connections
+
+Named connections let you decouple workflow code from specific connection IDs. Instead of hardcoding a `connectionId`, you reference a connection by name and the SDK resolves it from a mapping.
+
+This is useful when an execution engine or deployment system manages which connections a workflow should use.
+
+### Providing the mapping
+
+Connections are configured in `.zapierrc` alongside app version pins, or inline via the `manifest` option:
+
+```typescript
+const zapier = createZapierSdk({
+  manifest: {
+    apps: { slack: { implementationName: "SlackCLIAPI", version: "1.21.1" } },
+    connections: {
+      slack_work: { connectionId: 12345 },
+      google_sheets: { connectionId: 67890 },
+    },
+  },
+});
+```
+
+Each connection entry maps a name to a `connectionId`. App version resolution is handled separately via the `apps` section of `.zapierrc`.
+
+### Using named connections
+
+Reference connections by alias using the `connection` parameter. String values are resolved from the connections map; numeric values are used directly as a `connectionId`.
+
+```typescript
+// Per-call with alias
+await zapier.apps.slack.read.channels({ connection: "slack_work" });
+
+// Factory binding
+const slack = zapier.apps.slack({ connection: "slack_work" });
+await slack.read.channels({});
+
+// Lower-level runAction
+await zapier.runAction({
+  appKey: "slack",
+  actionType: "read",
+  actionKey: "channels",
+  connection: "slack_work",
+});
+
+// Authenticated fetch
+await zapier.fetch("https://slack.com/api/auth.test", {
+  connection: "slack_work",
+});
+
+// Direct connectionId also works
+await zapier.apps.slack.read.channels({ connection: 12345 });
+```
+
+`connection` and `connectionId` are mutually exclusive in the same call. You can still use `connectionId` directly if you prefer.
+
 ## Available Functions
 
 ### Accounts
@@ -561,18 +616,19 @@ Execute an action with the given inputs
 
 **Parameters:**
 
-| Name             | Type             | Required | Default | Possible Values                                                                                | Description                                                                                                                            |
-| ---------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `options`        | `object`         | ✅       | —       | —                                                                                              |                                                                                                                                        |
-| ↳ `appKey`       | `string`         | ✅       | —       | —                                                                                              | App key (e.g., 'SlackCLIAPI' or slug like 'github')                                                                                    |
-| ↳ `actionType`   | `string`         | ✅       | —       | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Action type that matches the action's defined type                                                                                     |
-| ↳ `actionKey`    | `string`         | ✅       | —       | —                                                                                              | Action key to execute                                                                                                                  |
-| ↳ `connectionId` | `string, number` | ❌       | —       | —                                                                                              | Connection ID to use when running the action. Required if the action needs a connection to authenticate and interact with the service. |
-| ↳ `inputs`       | `object`         | ❌       | —       | —                                                                                              | Input parameters for the action                                                                                                        |
-| ↳ `timeoutMs`    | `number`         | ❌       | —       | —                                                                                              | Maximum time to wait for action completion in milliseconds (default: 180000)                                                           |
-| ↳ `pageSize`     | `number`         | ❌       | —       | —                                                                                              | Number of results per page                                                                                                             |
-| ↳ `maxItems`     | `number`         | ❌       | —       | —                                                                                              | Maximum total items to return across all pages                                                                                         |
-| ↳ `cursor`       | `string`         | ❌       | —       | —                                                                                              | Cursor to start from                                                                                                                   |
+| Name             | Type             | Required | Default | Possible Values                                                                                | Description                                                                                                                                                        |
+| ---------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `options`        | `object`         | ✅       | —       | —                                                                                              |                                                                                                                                                                    |
+| ↳ `appKey`       | `string`         | ✅       | —       | —                                                                                              | App key (e.g., 'SlackCLIAPI' or slug like 'github')                                                                                                                |
+| ↳ `actionType`   | `string`         | ✅       | —       | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Action type that matches the action's defined type                                                                                                                 |
+| ↳ `actionKey`    | `string`         | ✅       | —       | —                                                                                              | Action key to execute                                                                                                                                              |
+| ↳ `connectionId` | `string, number` | ❌       | —       | —                                                                                              | Connection ID to use when running the action. Required if the action needs a connection to authenticate and interact with the service.                             |
+| ↳ `connection`   | `string, number` | ❌       | —       | —                                                                                              | Connection alias (string) or numeric connectionId. Strings are resolved from the connections map; numbers are used directly. Mutually exclusive with connectionId. |
+| ↳ `inputs`       | `object`         | ❌       | —       | —                                                                                              | Input parameters for the action                                                                                                                                    |
+| ↳ `timeoutMs`    | `number`         | ❌       | —       | —                                                                                              | Maximum time to wait for action completion in milliseconds (default: 180000)                                                                                       |
+| ↳ `pageSize`     | `number`         | ❌       | —       | —                                                                                              | Number of results per page                                                                                                                                         |
+| ↳ `maxItems`     | `number`         | ❌       | —       | —                                                                                              | Maximum total items to return across all pages                                                                                                                     |
+| ↳ `cursor`       | `string`         | ❌       | —       | —                                                                                              | Cursor to start from                                                                                                                                               |
 
 **Returns:** `Promise<PaginatedResult<ActionResultItem>>`
 
@@ -611,14 +667,15 @@ for await (const actionResult of zapier
 
 #### `apps.{appKey}`
 
-Bind a connection ID to an app
+Bind a connection alias or numeric connectionId to an app
 
 **Parameters:**
 
-| Name             | Type             | Required | Default | Possible Values | Description                          |
-| ---------------- | ---------------- | -------- | ------- | --------------- | ------------------------------------ |
-| `options`        | `object`         | ✅       | —       | —               |                                      |
-| ↳ `connectionId` | `string, number` | ❌       | —       | —               | Connection ID to use for this action |
+| Name             | Type             | Required | Default | Possible Values | Description                                                                                                                  |
+| ---------------- | ---------------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `options`        | `object`         | ✅       | —       | —               |                                                                                                                              |
+| ↳ `connectionId` | `string, number` | ❌       | —       | —               | Connection ID to use for this action                                                                                         |
+| ↳ `connection`   | `string, number` | ❌       | —       | —               | Connection alias (string) or numeric connectionId. Strings are resolved from the connections map; numbers are used directly. |
 
 **Returns:** `Promise<AppProxy>`
 
@@ -634,12 +691,13 @@ Execute an action with the given inputs for the bound app, as an alternative to
 
 **Parameters:**
 
-| Name             | Type             | Required | Default | Possible Values | Description                                                                  |
-| ---------------- | ---------------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------- |
-| `options`        | `object`         | ✅       | —       | —               |                                                                              |
-| ↳ `inputs`       | `object`         | ❌       | —       | —               |                                                                              |
-| ↳ `connectionId` | `string, number` | ❌       | —       | —               | Connection ID to use for this action                                         |
-| ↳ `timeoutMs`    | `number`         | ❌       | —       | —               | Maximum time to wait for action completion in milliseconds (default: 180000) |
+| Name             | Type             | Required | Default | Possible Values | Description                                                                                                                  |
+| ---------------- | ---------------- | -------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `options`        | `object`         | ✅       | —       | —               |                                                                                                                              |
+| ↳ `inputs`       | `object`         | ❌       | —       | —               |                                                                                                                              |
+| ↳ `connectionId` | `string, number` | ❌       | —       | —               | Connection ID to use for this action                                                                                         |
+| ↳ `connection`   | `string, number` | ❌       | —       | —               | Connection alias (string) or numeric connectionId. Strings are resolved from the connections map; numbers are used directly. |
+| ↳ `timeoutMs`    | `number`         | ❌       | —       | —               | Maximum time to wait for action completion in milliseconds (default: 180000)                                                 |
 
 **Returns:** `Promise<PaginatedResult<ActionResultItem>>`
 
@@ -912,15 +970,16 @@ Make authenticated HTTP requests to any API through Zapier. Pass a connectionId
 
 **Parameters:**
 
-| Name             | Type                     | Required | Default | Possible Values                                            | Description                                                                                         |
-| ---------------- | ------------------------ | -------- | ------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `url`            | `string, custom`         | ✅       | —       | —                                                          | The full URL of the API endpoint to call (proxied through Zapier's Relay service)                   |
-| `init`           | `object`                 | ❌       | —       | —                                                          | Request options including method, headers, body, and authentication                                 |
-| ↳ `method`       | `string`                 | ❌       | —       | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS` | HTTP method for the request (defaults to GET)                                                       |
-| ↳ `headers`      | `object`                 | ❌       | —       | —                                                          | HTTP headers to include in the request                                                              |
-| ↳ `body`         | `string, custom, record` | ❌       | —       | —                                                          | Request body — plain objects and JSON strings are auto-detected and Content-Type is set accordingly |
-| ↳ `connectionId` | `string, number`         | ❌       | —       | —                                                          | Connection ID to use for this action                                                                |
-| ↳ `callbackUrl`  | `string`                 | ❌       | —       | —                                                          | URL to send async response to (makes request async)                                                 |
+| Name             | Type                     | Required | Default | Possible Values                                            | Description                                                                                                                  |
+| ---------------- | ------------------------ | -------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `url`            | `string, custom`         | ✅       | —       | —                                                          | The full URL of the API endpoint to call (proxied through Zapier's Relay service)                                            |
+| `init`           | `object`                 | ❌       | —       | —                                                          | Request options including method, headers, body, and authentication                                                          |
+| ↳ `method`       | `string`                 | ❌       | —       | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS` | HTTP method for the request (defaults to GET)                                                                                |
+| ↳ `headers`      | `object`                 | ❌       | —       | —                                                          | HTTP headers to include in the request                                                                                       |
+| ↳ `body`         | `string, custom, record` | ❌       | —       | —                                                          | Request body — plain objects and JSON strings are auto-detected and Content-Type is set accordingly                          |
+| ↳ `connectionId` | `string, number`         | ❌       | —       | —                                                          | Connection ID to use for this action                                                                                         |
+| ↳ `connection`   | `string, number`         | ❌       | —       | —                                                          | Connection alias (string) or numeric connectionId. Strings are resolved from the connections map; numbers are used directly. |
+| ↳ `callbackUrl`  | `string`                 | ❌       | —       | —                                                          | URL to send async response to (makes request async)                                                                          |
 
 **Returns:** `Promise<Response>`
 

package/dist/constants.d.ts

@@ -11,6 +11,10 @@ export declare const ZAPIER_BASE_URL: string;
  * Maximum number of items that can be requested per page across all paginated functions
  */
 export declare const MAX_PAGE_LIMIT = 10000;
+/**
+ * Default number of items per page for paginated functions
+ */
+export declare const DEFAULT_PAGE_SIZE = 100;
 /**
  * Default timeout for action execution (in milliseconds)
  */

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe,QACyB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAejD;;GAEG;AACH,eAAO,MAAM,0BAA0B,QACY,CAAC;AACpD,eAAO,MAAM,iCAAiC,QACiB,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe,QACyB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAejD;;GAEG;AACH,eAAO,MAAM,0BAA0B,QACY,CAAC;AACpD,eAAO,MAAM,iCAAiC,QACiB,CAAC"}

package/dist/constants.js

@@ -11,6 +11,10 @@ export const ZAPIER_BASE_URL = process.env.ZAPIER_BASE_URL || "https://zapier.co
  * Maximum number of items that can be requested per page across all paginated functions
  */
 export const MAX_PAGE_LIMIT = 10000;
+/**
+ * Default number of items per page for paginated functions
+ */
+export const DEFAULT_PAGE_SIZE = 100;
 /**
  * Default timeout for action execution (in milliseconds)
  */