zapier-platform-cli 18.2.3 → 18.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zapier-platform-cli",
-  "version": "18.2.3",
+  "version": "18.3.0",
   "description": "The CLI for managing integrations in Zapier Developer Platform.",
   "repository": "zapier/zapier-platform",
   "homepage": "https://platform.zapier.com/",

package/src/generators/templates/README.template.md

@@ -31,4 +31,4 @@ zapier scaffold trigger contact
 zapier scaffold create contact
 ``` 
 
-Find out more on the latest docs: https://github.com/zapier/zapier-platform/blob/main/packages/cli/README.md.
+Find out more on the latest docs: https://docs.zapier.com/platform

package/src/generators/templates/dynamic-dropdown/README.md

@@ -1,5 +1,107 @@
-# The "dynamic-dropdown" Template
+# dynamic-dropdown
 
-This example integration uses the [Star Wars API](https://swapi.info/) to provide a dynamic listing of choices for an `inputField` in a trigger.
+This example integration demonstrates how to create **dynamic dropdowns** (also known as dynamic choices) in Zapier integrations.
 
-![](https://cdn.zappy.app/d985065c5098089795d9b60c77791e12.png)
+## Dynamic Dropdown Patterns
+
+There are two ways to implement dynamic dropdowns:
+
+### 1. Trigger-based (Legacy Pattern)
+
+Uses a separate trigger to fetch choices. Reference it with the `dynamic` property:
+
+```javascript
+{
+  key: 'species_id',
+  type: 'integer',
+  label: 'Species',
+  dynamic: 'species.id.name',  // Format: "triggerKey.idField.labelField"
+}
+```
+
+The trigger (`species`) fetches data, and Zapier uses `id` for the value and `name` for the display label.
+
+### 2. Perform-based (New Pattern)
+
+Uses a function to fetch choices directly. Define it with `choices.perform`:
+
+```javascript
+{
+  key: 'planet_id',
+  type: 'integer',
+  label: 'Home Planet',
+  resource: 'planet', // Explicit resource linking (see below)
+  choices: {
+    perform: getPlanetChoices,
+  },
+}
+```
+
+#### Resource Linking
+
+The `resource` property explicitly links an input field to a resource. This is particularly important for perform-based dropdowns since they don't have a `dynamic` property to derive the resource from.
+
+```javascript
+{
+  key: 'spreadsheet_id',
+  resource: 'spreadsheet',
+  choices: { perform: getSpreadsheets },
+}
+```
+
+The perform function must return:
+
+```javascript
+{
+  results: [
+    { id: '1', label: 'Tatooine' },
+    { id: '2', label: 'Alderaan' },
+  ],
+  paging_token: 'https://api.example.com/planets?page=2',  // or null if no more pages
+}
+```
+
+#### Pagination Support
+
+The perform function receives `bundle.meta.paging_token` for subsequent page requests:
+
+```javascript
+const getPlanetChoices = async (z, bundle) => {
+  // First request: paging_token is undefined
+  // Subsequent requests: paging_token is the value you returned previously
+  const url = bundle.meta.paging_token || 'https://api.example.com/planets';
+
+  const response = await z.request({ url });
+
+  return {
+    results: response.data.results.map((item) => ({
+      id: item.id,
+      label: item.name,
+    })),
+    // Return null when there are no more pages
+    paging_token: response.data.next,
+  };
+};
+```
+
+## This Example
+
+This integration uses the [Star Wars API](https://swapi.dev/) to demonstrate:
+
+- **Species dropdown** - Trigger-based pattern using the `species` trigger
+- **Planet dropdown** - Perform-based pattern with pagination and explicit `resource` linking
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+zapier test
+
+# Push to Zapier
+zapier push
+```
+
+Find out more on the latest docs: https://docs.zapier.com/platform

package/src/generators/templates/dynamic-dropdown/triggers/people.js

@@ -1,5 +1,33 @@
 const { extractID } = require('../utils');
 
+/**
+ * PERFORM-BASED choices WITH PAGINATION (NEW pattern)
+ * Fetches planets from the Star Wars API with pagination support.
+ *
+ * - bundle.meta.paging_token is a full URL from the previous response
+ * - Return paging_token as the API's next page URL (or null if no more pages)
+ *
+ * MUST return: { results: [...], paging_token: string|null }
+ */
+const getPlanetChoices = async (z, bundle) => {
+  // paging_token is a full URL to the next page (from SWAPI's "next" field)
+  // First page: paging_token is undefined/null, use default URL
+  const url = bundle.meta.paging_token || 'https://swapi.dev/api/planets/';
+
+  const response = await z.request({ url });
+  const data = response.data;
+
+  // SWAPI returns: { results: [...], next: "url" or null }
+  return {
+    results: data.results.map((planet) => ({
+      id: extractID(planet.url),
+      label: planet.name,
+    })),
+    // Return SWAPI's next URL as our paging_token
+    paging_token: data.next,
+  };
+};
+
 // Fetches a list of records from the endpoint
 const perform = async (z, bundle) => {
   // Ideally, we should poll through all the pages of results, but in this
@@ -23,6 +51,16 @@ const perform = async (z, bundle) => {
     });
   }
 
+  if (bundle.inputData.planet_id) {
+    // The Zap's setup has requested a specific home planet. Filter people by
+    // homeworld (SWAPI people have a homeworld URL).
+    peopleArray = peopleArray.filter((person) => {
+      if (!person.homeworld) return false;
+      const homeworldID = extractID(person.homeworld);
+      return homeworldID === bundle.inputData.planet_id;
+    });
+  }
+
   return peopleArray.map((person) => {
     person.id = extractID(person.url);
     return person;
@@ -39,13 +77,30 @@ module.exports = {
 
   operation: {
     inputFields: [
+      // TRIGGER-BASED dynamic dropdown (legacy pattern)
+      // Uses a separate trigger to fetch choices
       {
         key: 'species_id',
         type: 'integer',
-        helpText: 'Species of person',
+        label: 'Species (trigger-based)',
+        helpText:
+          'Filter by species. Uses trigger-based dynamic dropdown (dynamic: "species.id.name").',
         dynamic: 'species.id.name',
         altersDynamicFields: true,
       },
+      // PERFORM-BASED dynamic dropdown WITH PAGINATION (new pattern)
+      // Uses a function to fetch choices directly
+      {
+        key: 'planet_id',
+        type: 'integer',
+        label: 'Home Planet (perform-based)',
+        helpText:
+          'Filter by home planet. Uses perform-based dynamic dropdown with pagination support.',
+        resource: 'planet', // Explicit resource linking for perform-based dropdowns
+        choices: {
+          perform: getPlanetChoices,
+        },
+      },
     ],
     perform,
     sample: {

package/src/oclif/commands/invoke/prompts.js

@@ -1,7 +1,10 @@
 const _ = require('lodash');
 
 const { listAuthentications } = require('../../../utils/api');
+const { startSpinner, endSpinner } = require('../../../utils/display');
 const { fetchChoices } = require('./remote');
+const { localAppCommandWithRelayErrorHandler } = require('./relay');
+const { customLogger } = require('./logger');
 
 /**
  * Formats a field definition for display in prompts.
@@ -121,6 +124,96 @@ const getDynamicDropdownChoices = async (
   }
 };
 
+/**
+ * Checks whether a field uses perform-based dynamic choices (choices: { perform }).
+ * @param {Object} field - The field definition
+ * @returns {boolean} True if the field has perform-based choices
+ */
+const isPerformBasedChoices = (field) =>
+  field.choices &&
+  typeof field.choices === 'object' &&
+  !Array.isArray(field.choices) &&
+  field.choices.perform !== undefined;
+
+/**
+ * Fetches choices for a perform-based dynamic dropdown field.
+ * @param {import('../../ZapierBaseCommand')} command - The command instance
+ * @param {Object} context - The execution context
+ * @param {Object} field - The field definition with choices.perform
+ * @returns {Promise<{choices: Array<Object>, nextPagingToken: string|null}>}
+ */
+const getPerformBasedChoices = async (command, context, field) => {
+  if (context.remote) {
+    const choices = (await fetchChoices(context, field.key)).map((c) => ({
+      name: `${c.label} (${c.value})`,
+      value: c.value,
+    }));
+    return { choices, nextPagingToken: null };
+  }
+
+  // Find the field's index in the action's inputFields array
+  const action =
+    context.appDefinition[context.actionTypePlural][context.actionKey];
+  const allInputFields = action.operation.inputFields || [];
+  const fieldIndex = allInputFields.findIndex(
+    (f) => f.key === field.key && f.choices && f.choices.perform,
+  );
+  if (fieldIndex === -1) {
+    throw new Error(
+      `Cannot find perform-based choices for field "${field.key}" in ` +
+        `${context.actionTypePlural}.${context.actionKey}.operation.inputFields.`,
+    );
+  }
+
+  const methodName = `${context.actionTypePlural}.${context.actionKey}.operation.inputFields.${fieldIndex}.choices.perform`;
+  const displayName = `${context.actionTypePlural}.${context.actionKey}.operation.inputFields[${fieldIndex}].choices.perform`;
+  const adverb = context.remote
+    ? 'remotely'
+    : context.authId
+      ? 'locally with relay'
+      : 'locally';
+  startSpinner(`Invoking ${displayName} ${adverb}`);
+  const result = await localAppCommandWithRelayErrorHandler({
+    command: 'execute',
+    method: methodName,
+    bundle: {
+      inputData: context.inputData,
+      inputDataRaw: context.inputData,
+      authData: context.authData,
+      meta: {
+        ...context.meta,
+        isFillingDynamicDropdown: true,
+      },
+    },
+    zcacheTestObj: context.zcacheTestObj,
+    cursorTestObj: context.cursorTestObj,
+    customLogger,
+    calledFromCliInvoke: true,
+    appId: context.appId,
+    deployKey: context.deployKey,
+    relayAuthenticationId: context.authId,
+  });
+  endSpinner();
+
+  // The perform function returns { results: [{ id, label }, ...], paging_token }
+  // or a plain array of { id, label } objects
+  let results, nextPagingToken;
+  if (Array.isArray(result)) {
+    results = result;
+    nextPagingToken = null;
+  } else {
+    results = result.results || [];
+    nextPagingToken = result.paging_token || null;
+  }
+
+  const choices = results.map((c) => ({
+    name: `${c.label || c.id} (${c.id})`,
+    value: String(c.id),
+  }));
+
+  return { choices, nextPagingToken };
+};
+
 /**
  * Normalizes static choices into an array of { name, value } objects for
  * prompting.
@@ -150,18 +243,22 @@ const getStaticChoices = (choices) => {
 };
 
 /**
- * Gets choices for a dropdown field, handling both static and dynamic cases.
+ * Gets choices for a dropdown field, handling static, trigger-based dynamic,
+ * and perform-based dynamic cases.
  * @param {import('../../ZapierBaseCommand')} command - The command instance for prompting
  * @param {Object} context - The execution context
  * @param {Object} field - The field definition
- * @param {Function} invokeAction - Function to invoke actions (used for dynamic dropdowns)
- * @returns {Promise<Array<Object>>} Array of choices formatted as { name, value } objects
+ * @param {Function} invokeAction - Function to invoke actions (used for trigger-based dynamic dropdowns)
+ * @param {Object} [pagingState] - Pagination state for perform-based choices
+ * @param {boolean} [pagingState.hasPreviousPage] - Whether there is a previous page
+ * @returns {Promise<{choices: Array<Object>, nextPagingToken: string|null}>}
  */
 const getStaticOrDynamicDropdownChoices = async (
   command,
   context,
   field,
   invokeAction,
+  pagingState,
 ) => {
   if (field.dynamic) {
     const choices = await getDynamicDropdownChoices(
@@ -181,9 +278,28 @@ const getStaticOrDynamicDropdownChoices = async (
       name: `>>> NEXT PAGE <<<`,
       value: '__next_page__',
     });
-    return choices;
+    return { choices, nextPagingToken: null };
+  } else if (isPerformBasedChoices(field)) {
+    const { choices, nextPagingToken } = await getPerformBasedChoices(
+      command,
+      context,
+      field,
+    );
+    if (pagingState && pagingState.hasPreviousPage) {
+      choices.unshift({
+        name: `>>> PREVIOUS PAGE <<<`,
+        value: '__prev_page__',
+      });
+    }
+    if (nextPagingToken) {
+      choices.push({
+        name: `>>> NEXT PAGE <<<`,
+        value: '__next_page__',
+      });
+    }
+    return { choices, nextPagingToken };
   } else {
-    return getStaticChoices(field.choices);
+    return { choices: getStaticChoices(field.choices), nextPagingToken: null };
   }
 };
 
@@ -199,35 +315,64 @@ const getStaticOrDynamicDropdownChoices = async (
 const promptForField = async (command, context, field, invokeAction) => {
   const message = formatFieldDisplay(field) + ':';
   if (field.dynamic || field.choices) {
+    const performBased = isPerformBasedChoices(field);
     let answer;
+
+    // Paging state for perform-based choices (token-based pagination)
+    const pagingTokenStack = [];
+    let currentPagingToken = null;
+    let nextPagingToken = null;
+
     while (
       !answer ||
       answer === '__next_page__' ||
       answer === '__prev_page__'
     ) {
-      let page = 0;
-      switch (answer) {
-        case '__next_page__':
-          page = (context.meta.page || 0) + 1;
-          break;
-        case '__prev_page__':
-          page = Math.max((context.meta.page || 0) - 1, 0);
-          break;
+      if (performBased) {
+        switch (answer) {
+          case '__next_page__':
+            pagingTokenStack.push(currentPagingToken);
+            currentPagingToken = nextPagingToken;
+            break;
+          case '__prev_page__':
+            currentPagingToken = pagingTokenStack.pop() || null;
+            break;
+        }
+        context = {
+          ...context,
+          meta: {
+            ...context.meta,
+            paging_token: currentPagingToken,
+          },
+        };
+      } else {
+        let page = 0;
+        switch (answer) {
+          case '__next_page__':
+            page = (context.meta.page || 0) + 1;
+            break;
+          case '__prev_page__':
+            page = Math.max((context.meta.page || 0) - 1, 0);
+            break;
+        }
+        context = {
+          ...context,
+          meta: {
+            ...context.meta,
+            page,
+          },
+        };
       }
-      context = {
-        ...context,
-        meta: {
-          ...context.meta,
-          page,
-        },
-      };
-      const choices = await getStaticOrDynamicDropdownChoices(
+
+      const result = await getStaticOrDynamicDropdownChoices(
         command,
         context,
         field,
         invokeAction,
+        { hasPreviousPage: pagingTokenStack.length > 0 },
       );
-      answer = await command.promptWithList(message, choices, {
+      nextPagingToken = result.nextPagingToken;
+      answer = await command.promptWithList(message, result.choices, {
         useStderr: true,
       });
     }