@zapier/zapier-sdk 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @zapier/zapier-sdk
 
+## 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

@@ -31,7 +31,7 @@
 
 ```bash
 npm install @zapier/zapier-sdk
-npm install -D @types/node typescript
+npm install -D @zapier/zapier-sdk-cli @types/node typescript
 npx tsc --init
 ```
 
@@ -65,22 +65,74 @@ 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: 1000 }).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",
 });
 
 // ######## 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 +143,28 @@ 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,
+const { data: users } = await zapier.apps.slack.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,
 });
 ```
 
@@ -143,12 +198,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 +223,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 +268,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 +277,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 +326,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 +374,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 +482,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 +510,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 +539,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 +562,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 +606,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>>`