@zapier/zapier-sdk 0.12.1 → 0.13.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @zapier/zapier-sdk
 
+## 0.13.1
+
+### Patch Changes
+
+- a607e3a: Fixes a bug where listApps would return all apps if no appKeys were resolved to app locators. This in turn fixes the `add` command hanging when using only invalid app keys (since it would try to add all apps), and it fixes getApp which returned the first app of all apps for an invalid slug, since it just calls to listApps.
+
+## 0.13.0
+
+### Minor Changes
+
+- 53ad336: Tweak list-apps output. Hint at slug for appKey parameters. Fix type gen for new field format. Fix action normalization.
+
 ## 0.12.1
 
 ### Patch Changes

package/README.md

@@ -30,9 +30,14 @@
 ## Installation
 
 ```bash
-npm install @zapier/zapier-sdk
-npm install -D @types/node typescript
+# If starting a new project:
+cd your-project-dir
+npm init -y
 npx tsc --init
+# Also, set `"type": "module"` in your package.json for the code examples below.
+
+npm install @zapier/zapier-sdk
+npm install -D @zapier/zapier-sdk-cli @types/node typescript
 ```
 
 ## Quick Start
@@ -41,15 +46,15 @@ npx tsc --init
 # Authenticates through your browser, automatically handling token management
 npx zapier-sdk login
 
-# Generate TypeScript types for the request/response signatures of apps.
-# By default, the types will be generated inside of your `src` folder, if you have one, or the root folder.
-# To use these types, ensure they are added to your `tsconfig.json` file.
+# Generate TypeScript types for actions and fields of any apps you want to use.
+npx zapier-sdk add slack github trello
 
-# Single app
-npx zapier-sdk add slack --types-output ./types/slack.ts
+# By default, types will be generated inside your `src` or `lib` folder if you
+# have one or otherwise the root folder. Make sure your `tsconfig.json` file
+# includes the generated type files.
 
-# Multiple apps
-npx zapier-sdk add slack github trello
+# Alternatively, you can specify a custom output directory.
+npx zapier-sdk add slack github trello --types-output ./types
 ```
 
 ```typescript
@@ -65,22 +70,78 @@ const zapier = createZapierSdk();
 // });
 
 // ######## Access Apps ########
-const apps = await zapier.listApps();
-const singleApp = await zapier.getApp({ appKey: "SlackCLIAPI" });
+// List methods return a promise for a page with {data, nextCursor}.
+const { data: firstPageApps, nextCursor } = await zapier.listApps();
+// Use the cursor to get the next page:
+const { data: secondPageApps } = await zapier.listApps({ cursor: nextCursor });
+
+console.log({
+  firstPageApps,
+  secondPageApps,
+});
+
+// List methods also return an iterator for all pages.
+// Be careful with lots of pages, note the `search` to filter.
+for await (const page of zapier.listApps({ search: "slack" })) {
+  const { data: apps } = page;
+  console.log({
+    apps,
+  });
+}
+
+// Use `.items()` to iterate over all items of all pages:
+// Again, be careful with lots of items. Note the `maxItems` to limit the total items.
+for await (const app of zapier.listApps({ maxItems: 100 }).items()) {
+  console.log({
+    app,
+  });
+}
+
+// You can collect all results, but this could take a while for long lists!
+const allApps = await Array.fromAsync(
+  zapier.listApps({ maxItems: 100 }).items(),
+);
+
+console.log({
+  allApps,
+});
+
+// The item methods return a promise for a single item, wrapped with {data}.
+// This is just to give us room to add metadata in the future.
+const { data: app } = await zapier.getApp({ appKey: "slack" });
+
+console.log({
+  app,
+});
 
 // ######## Authentication Usage ########
-const myAuths = await zapier.listAuthentications({
-  appKey: "SlackCLIAPI",
+const { data: myAuths } = await zapier.listAuthentications({
+  appKey: "slack",
   owner: "me",
 });
 
+console.log({
+  myAuths,
+});
+
 // ######## Find Actions ########
 // Option 1: List actions
-const actions = await zapier.listActions({ appKey: "SlackCLIAPI" });
+// Remember, this is just the first page which may not include them all!
+// See `.items()` usage above, which can be used to make sure you get all actions.
+const { data: actions } = await zapier.listActions({ appKey: "slack" });
+
+console.log({
+  actions,
+});
+
 const singleAction = await zapier.getAction({
-  appKey: "SlackCLIAPI",
-  actionType: actions.data[0].action_type,
-  actionKey: actions.data[0].key,
+  appKey: "slack",
+  actionType: actions[0].action_type,
+  actionKey: actions[0].key,
+});
+
+console.log({
+  singleAction,
 });
 
 // Option 2: Access actions via the `apps` proxy
@@ -91,25 +152,46 @@ const singleAction = await zapier.getAction({
 
 // ######## Run Actions ########
 // Option 1:
-const allChannels = await zapier.runAction({
-  appKey: "SlackCLIAPI",
+const { data: channels } = await zapier.runAction({
+  appKey: "slack",
   actionType: "read",
   actionKey: "channels",
-  authenticationId: myAuths.data[0].id,
+  authenticationId: myAuths[0].id,
+});
+
+console.log({
+  channels,
 });
 
+const { data: profile } = await zapier.getProfile();
+
 // Option 2:
-const allChannelsResult = await zapier.apps.slack.read.channels({
-  authenticationId: myAuths.data[0].id,
+// Create an app binding to your authentication.
+const mySlack = zapier.apps.slack({
+  authenticationId: myAuths[0].id,
+});
+
+// Use your app binding to run the action.
+const { data: users } = await mySlack.search.user_by_email({
+  inputs: {
+    email: profile.email,
+  },
 });
 
 console.log({
-  apps: apps.data[0],
-  singleApp,
-  actions: actions.data[0],
-  singleAction,
-  allChannels: allChannels.data[0],
-  allChannelsResult,
+  users,
+});
+
+// You can also skip the app binding and pass the auth into the action.
+const { data: sameUsers } = await zapier.apps.slack.search.user_by_email({
+  inputs: {
+    email: profile.email,
+  },
+  authenticationId: myAuths[0].id,
+});
+
+console.log({
+  sameUsers,
 });
 ```
 
@@ -143,12 +225,12 @@ Get detailed information about a specific action
 
 **Parameters:**
 
-| Name           | Type     | Required | Default | Possible Values                                                                                | Description                                        |
-| -------------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| `options`      | `object` | ✅       | —       | —                                                                                              |                                                    |
-| ↳ `appKey`     | `string` | ✅       | —       | —                                                                                              | App key (e.g., 'SlackCLIAPI')                      |
-| ↳ `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                              |
+| 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                               |
 
 **Returns:** `Promise<ActionItem>`
 
@@ -168,13 +250,14 @@ List all actions for a specific app
 
 **Parameters:**
 
-| Name           | Type     | Required | Default | Possible Values                                                                                | Description                                      |
-| -------------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| `options`      | `object` | ✅       | —       | —                                                                                              |                                                  |
-| ↳ `appKey`     | `string` | ✅       | —       | —                                                                                              | App key of actions to list (e.g., 'SlackCLIAPI') |
-| ↳ `actionType` | `string` | ❌       | —       | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Filter actions by type                           |
-| ↳ `pageSize`   | `number` | ❌       | —       | —                                                                                              | Number of actions per page                       |
-| ↳ `maxItems`   | `number` | ❌       | —       | —                                                                                              | Maximum total items to return across all pages   |
+| Name           | Type     | Required | Default | Possible Values                                                                                | Description                                                            |
+| -------------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `options`      | `object` | ✅       | —       | —                                                                                              |                                                                        |
+| ↳ `appKey`     | `string` | ✅       | —       | —                                                                                              | App key of actions to list (e.g., 'SlackCLIAPI' or slug like 'github') |
+| ↳ `actionType` | `string` | ❌       | —       | `read`, `read_bulk`, `write`, `run`, `search`, `search_or_write`, `search_and_write`, `filter` | Filter actions by type                                                 |
+| ↳ `pageSize`   | `number` | ❌       | —       | —                                                                                              | Number of actions per page                                             |
+| ↳ `maxItems`   | `number` | ❌       | —       | —                                                                                              | Maximum total items to return across all pages                         |
+| ↳ `cursor`     | `string` | ❌       | —       | —                                                                                              | Cursor to start from                                                   |
 
 **Returns:** `Promise<PaginatedResult<ActionItem>>`
 
@@ -212,7 +295,7 @@ Get the available choices for a dynamic dropdown input field
 | Name                 | Type     | Required | Default | Possible Values                                                                                | Description                                            |
 | -------------------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
 | `options`            | `object` | ✅       | —       | —                                                                                              |                                                        |
-| ↳ `appKey`           | `string` | ✅       | —       | —                                                                                              | App key (e.g., 'SlackCLIAPI')                          |
+| ↳ `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                                  |
 | ↳ `inputFieldKey`    | `string` | ✅       | —       | —                                                                                              | Input field key to get choices for.                    |
@@ -221,6 +304,7 @@ Get the available choices for a dynamic dropdown input field
 | ↳ `page`             | `number` | ❌       | —       | —                                                                                              | Page number for paginated results                      |
 | ↳ `pageSize`         | `number` | ❌       | —       | —                                                                                              | Number of choices per page                             |
 | ↳ `maxItems`         | `number` | ❌       | —       | —                                                                                              | Maximum total items to return across all pages         |
+| ↳ `cursor`           | `string` | ❌       | —       | —                                                                                              | Cursor to start from                                   |
 
 **Returns:** `Promise<PaginatedResult<InputFieldChoiceItem>>`
 
@@ -269,13 +353,14 @@ Get the input fields required for a specific action
 | Name                 | Type     | Required | Default | Possible Values                                                                                | Description                                           |
 | -------------------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
 | `options`            | `object` | ✅       | —       | —                                                                                              |                                                       |
-| ↳ `appKey`           | `string` | ✅       | —       | —                                                                                              | App key (e.g., 'SlackCLIAPI')                         |
+| ↳ `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                                 |
 | ↳ `authenticationId` | `string` | ❌       | —       | —                                                                                              | Authentication ID to use for this action              |
 | ↳ `inputs`           | `object` | ❌       | —       | —                                                                                              | Current input values that may affect available fields |
 | ↳ `pageSize`         | `number` | ❌       | —       | —                                                                                              | Number of input fields per page                       |
 | ↳ `maxItems`         | `number` | ❌       | —       | —                                                                                              | Maximum total items to return across all pages        |
+| ↳ `cursor`           | `string` | ❌       | —       | —                                                                                              | Cursor to start from                                  |
 
 **Returns:** `Promise<PaginatedResult<RootFieldItemItem>>`
 
@@ -316,16 +401,17 @@ Execute an action with the given inputs
 
 **Parameters:**
 
-| Name                 | Type     | Required | Default | Possible Values                                                                                | Description                                        |
-| -------------------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| `options`            | `object` | ✅       | —       | —                                                                                              |                                                    |
-| ↳ `appKey`           | `string` | ✅       | —       | —                                                                                              | App key (e.g., 'SlackCLIAPI')                      |
-| ↳ `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                              |
-| ↳ `authenticationId` | `string` | ❌       | —       | —                                                                                              | Authentication ID to use for this action           |
-| ↳ `inputs`           | `object` | ❌       | —       | —                                                                                              | Input parameters for the action                    |
-| ↳ `pageSize`         | `number` | ❌       | —       | —                                                                                              | Number of results per page                         |
-| ↳ `maxItems`         | `number` | ❌       | —       | —                                                                                              | Maximum total items to return across all pages     |
+| 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                               |
+| ↳ `authenticationId` | `string` | ❌       | —       | —                                                                                              | Authentication ID to use for this action            |
+| ↳ `inputs`           | `object` | ❌       | —       | —                                                                                              | Input parameters for the action                     |
+| ↳ `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>>`
 
@@ -423,10 +509,10 @@ Get detailed information about a specific app
 
 **Parameters:**
 
-| Name       | Type     | Required | Default | Possible Values | Description                                   |
-| ---------- | -------- | -------- | ------- | --------------- | --------------------------------------------- |
-| `options`  | `object` | ✅       | —       | —               |                                               |
-| ↳ `appKey` | `string` | ✅       | —       | —               | App key of app to fetch (e.g., 'SlackCLIAPI') |
+| Name       | Type     | Required | Default | Possible Values | Description                                                         |
+| ---------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------------------- |
+| `options`  | `object` | ✅       | —       | —               |                                                                     |
+| ↳ `appKey` | `string` | ✅       | —       | —               | App key of app to fetch (e.g., 'SlackCLIAPI' or slug like 'github') |
 
 **Returns:** `Promise<AppItem>`
 
@@ -451,6 +537,7 @@ List all available apps with optional filtering
 | ↳ `search`   | `string` | ❌       | —       | —               | Search for apps by name                                             |
 | ↳ `pageSize` | `number` | ❌       | —       | —               | Number of apps per page                                             |
 | ↳ `maxItems` | `number` | ❌       | —       | —               | Maximum total items to return across all pages                      |
+| ↳ `cursor`   | `string` | ❌       | —       | —               | Cursor to start from                                                |
 
 **Returns:** `Promise<PaginatedResult<AppItem>>`
 
@@ -479,14 +566,14 @@ Find the first authentication matching the criteria
 
 **Parameters:**
 
-| Name          | Type     | Required | Default | Possible Values | Description                                             |
-| ------------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------- |
-| `options`     | `object` | ✅       | —       | —               |                                                         |
-| ↳ `appKey`    | `string` | ❌       | —       | —               | App key of authentication to find (e.g., 'SlackCLIAPI') |
-| ↳ `search`    | `string` | ❌       | —       | —               | Search term to filter authentications by title          |
-| ↳ `title`     | `string` | ❌       | —       | —               | Filter authentications by exact title match             |
-| ↳ `accountId` | `string` | ❌       | —       | —               | Filter by account ID                                    |
-| ↳ `owner`     | `string` | ❌       | —       | —               | Filter by owner                                         |
+| Name          | Type     | Required | Default | Possible Values | Description                                                                   |
+| ------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------- |
+| `options`     | `object` | ✅       | —       | —               |                                                                               |
+| ↳ `appKey`    | `string` | ❌       | —       | —               | App key of authentication to find (e.g., 'SlackCLIAPI' or slug like 'github') |
+| ↳ `search`    | `string` | ❌       | —       | —               | Search term to filter authentications by title                                |
+| ↳ `title`     | `string` | ❌       | —       | —               | Filter authentications by exact title match                                   |
+| ↳ `accountId` | `string` | ❌       | —       | —               | Filter by account ID                                                          |
+| ↳ `owner`     | `string` | ❌       | —       | —               | Filter by owner                                                               |
 
 **Returns:** `Promise<AuthenticationItem>`
 
@@ -502,14 +589,14 @@ Find a unique authentication matching the criteria
 
 **Parameters:**
 
-| Name          | Type     | Required | Default | Possible Values | Description                                             |
-| ------------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------- |
-| `options`     | `object` | ✅       | —       | —               |                                                         |
-| ↳ `appKey`    | `string` | ❌       | —       | —               | App key of authentication to find (e.g., 'SlackCLIAPI') |
-| ↳ `search`    | `string` | ❌       | —       | —               | Search term to filter authentications by title          |
-| ↳ `title`     | `string` | ❌       | —       | —               | Filter authentications by exact title match             |
-| ↳ `accountId` | `string` | ❌       | —       | —               | Filter by account ID                                    |
-| ↳ `owner`     | `string` | ❌       | —       | —               | Filter by owner                                         |
+| Name          | Type     | Required | Default | Possible Values | Description                                                                   |
+| ------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------- |
+| `options`     | `object` | ✅       | —       | —               |                                                                               |
+| ↳ `appKey`    | `string` | ❌       | —       | —               | App key of authentication to find (e.g., 'SlackCLIAPI' or slug like 'github') |
+| ↳ `search`    | `string` | ❌       | —       | —               | Search term to filter authentications by title                                |
+| ↳ `title`     | `string` | ❌       | —       | —               | Filter authentications by exact title match                                   |
+| ↳ `accountId` | `string` | ❌       | —       | —               | Filter by account ID                                                          |
+| ↳ `owner`     | `string` | ❌       | —       | —               | Filter by owner                                                               |
 
 **Returns:** `Promise<AuthenticationItem>`
 
@@ -546,17 +633,18 @@ List available authentications with optional filtering
 
 **Parameters:**
 
-| Name                  | Type     | Required | Default | Possible Values | Description                                                              |
-| --------------------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------------------------ |
-| `options`             | `object` | ✅       | —       | —               |                                                                          |
-| ↳ `appKey`            | `string` | ❌       | —       | —               | App key of authentications to list (e.g., 'SlackCLIAPI')                 |
-| ↳ `authenticationIds` | `array`  | ❌       | —       | —               | List of authentication IDs to filter by                                  |
-| ↳ `search`            | `string` | ❌       | —       | —               | Search term to filter authentications by title                           |
-| ↳ `title`             | `string` | ❌       | —       | —               | Filter authentications by exact title match                              |
-| ↳ `accountId`         | `string` | ❌       | —       | —               | Filter by account ID                                                     |
-| ↳ `owner`             | `string` | ❌       | —       | —               | Filter by owner, 'me' for your own authentications or a specific user ID |
-| ↳ `pageSize`          | `number` | ❌       | —       | —               | Number of authentications per page                                       |
-| ↳ `maxItems`          | `number` | ❌       | —       | —               | Maximum total items to return across all pages                           |
+| Name                  | Type     | Required | Default | Possible Values | Description                                                                    |
+| --------------------- | -------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------ |
+| `options`             | `object` | ✅       | —       | —               |                                                                                |
+| ↳ `appKey`            | `string` | ❌       | —       | —               | App key of authentications to list (e.g., 'SlackCLIAPI' or slug like 'github') |
+| ↳ `authenticationIds` | `array`  | ❌       | —       | —               | List of authentication IDs to filter by                                        |
+| ↳ `search`            | `string` | ❌       | —       | —               | Search term to filter authentications by title                                 |
+| ↳ `title`             | `string` | ❌       | —       | —               | Filter authentications by exact title match                                    |
+| ↳ `accountId`         | `string` | ❌       | —       | —               | Filter by account ID                                                           |
+| ↳ `owner`             | `string` | ❌       | —       | —               | Filter by owner, 'me' for your own authentications or a specific user ID       |
+| ↳ `pageSize`          | `number` | ❌       | —       | —               | Number of authentications per page                                             |
+| ↳ `maxItems`          | `number` | ❌       | —       | —               | Maximum total items to return across all pages                                 |
+| ↳ `cursor`            | `string` | ❌       | —       | —               | Cursor to start from                                                           |
 
 **Returns:** `Promise<PaginatedResult<AuthenticationItem>>`