zapier-platform-core 17.6.0 → 17.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zapier-platform-core",
-  "version": "17.6.0",
+  "version": "17.7.0",
   "description": "The core SDK for CLI apps in the Zapier Developer Platform.",
   "repository": "zapier/zapier-platform",
   "homepage": "https://platform.zapier.com/",
@@ -63,7 +63,7 @@
     "node-fetch": "2.7.0",
     "oauth-sign": "0.9.0",
     "semver": "7.7.1",
-    "zapier-platform-schema": "17.6.0"
+    "zapier-platform-schema": "17.7.0"
   },
   "devDependencies": {
     "@types/node-fetch": "^2.6.11",

package/src/checks/index.js

@@ -1,7 +1,7 @@
 module.exports = {
   createIsObject: require('./create-is-object'),
 
-  searchIsArray: require('./search-is-array'),
+  searchIsArrayOrEnvelope: require('./search-is-array-or-envelope'),
 
   triggerIsArray: require('./trigger-is-array'),
   triggerIsObject: require('./trigger-is-object'),

package/src/checks/search-is-array-or-envelope.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const _ = require('lodash');
+const { simpleTruncate } = require('../tools/data');
+
+const isSearch = require('./is-search');
+
+const hasCanPaginate = (searchKey, compiledApp) => {
+  const canPaginate =
+    compiledApp?.searches?.[searchKey]?.operation?.canPaginate;
+  return canPaginate;
+};
+
+/*
+  Searches should return an array of objects,
+  or a response envelope like { results: [...], paging_token: '...' } 
+  when canPaginate is true.
+*/
+const searchIsArrayOrEnvelope = {
+  name: 'searchIsArrayOrEnvelope',
+  shouldRun: isSearch,
+  run: (method, results, compiledApp) => {
+    const searchKey = method.split('.', 2)[1];
+    const truncatedResults = simpleTruncate(JSON.stringify(results), 50);
+
+    if (hasCanPaginate(searchKey, compiledApp)) {
+      // if paging is supported and results is an object (indicating pagination), it must have results and paging_token
+      if (_.isPlainObject(results)) {
+        if (!_.has(results, 'results') || !_.has(results, 'paging_token')) {
+          return [
+            `Paginated search results must be an object containing results and paging_token, got: ${truncatedResults}`,
+          ];
+        }
+        if (
+          !_.isString(results.paging_token) &&
+          !_.isNull(results.paging_token)
+        ) {
+          return [
+            `"paging_token" must be a string or null, got: ${typeof results.paging_token}`,
+          ];
+        }
+        // pass to array check below
+        results = results.results;
+      } else {
+        return [
+          `Paginated search results must be an object, got: ${typeof results}, (${truncatedResults})`,
+        ];
+      }
+    }
+
+    if (!_.isArray(results)) {
+      return [
+        `Search results must be an array, got: ${typeof results}, (${truncatedResults})`,
+      ];
+    }
+    return [];
+  },
+};
+
+module.exports = searchIsArrayOrEnvelope;

package/types/functions.d.ts

@@ -118,9 +118,17 @@ export type CreatePerformGet<
 > = (z: ZObject, bundle: Bundle<$InputData>) => $Return | Promise<$Return>;
 
 /**
- * Search for objects on a partner API.
+ * Helper type for search results that can optionally include pagination.
+ * Returns either:
+ * - an array of objects, matching the search query.
+ * - an object with a `results` array of objects and a `paging_token` string.
  *
- * Returns an 1-item array of objects, matching the search query.
+ * When `canPaginate` is true for the search, the object shape is required.
+ */
+type SearchResult<T> = T[] | { results: T[], paging_token: string };
+
+/**
+ * Search for objects on a partner API.
  *
  * @remarks
  * This type requires a one-item array. Multiple items *can* be
@@ -130,7 +138,7 @@ export type CreatePerformGet<
 export type SearchPerform<
   $InputData extends DefaultInputData = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return[] | Promise<$Return[]>;
+> = (z: ZObject, bundle: Bundle<$InputData>) => SearchResult<$Return> | Promise<SearchResult<$Return>>;
 
 /**
  * Follow up a search's perform with additional data.

package/types/schemas.generated.d.ts

@@ -4,7 +4,7 @@
  * files, and/or the schema-to-ts tool and run its CLI to regenerate
  * these typings.
  *
- * zapier-platform-schema version: 17.5.0
+ * zapier-platform-schema version: 17.6.0
  *  schema-to-ts compiler version: 0.1.0
  */
 import type {
@@ -1193,6 +1193,9 @@ export interface BasicSearchOperation<
    */
   performGet?: Request | SearchPerformGet<InferInputData<$InputFields>>;
 
+  /** Does this search support pagination? */
+  canPaginate?: boolean;
+
   /** What should the form a user sees and configures look like? */
   inputFields?: $InputFields;
 

package/src/checks/search-is-array.js

@@ -1,23 +0,0 @@
-'use strict';
-
-const _ = require('lodash');
-const { simpleTruncate } = require('../tools/data');
-
-const isSearch = require('./is-search');
-
-/*
-  Searches should always return an array of objects.
-*/
-const searchIsArray = {
-  name: 'triggerIsArray',
-  shouldRun: isSearch,
-  run: (method, results) => {
-    if (!_.isArray(results)) {
-      const repr = simpleTruncate(JSON.stringify(results), 50);
-      return [`Results must be an array, got: ${typeof results}, (${repr})`];
-    }
-    return [];
-  },
-};
-
-module.exports = searchIsArray;