zapier-platform-schema 12.1.0 → 12.2.1

package/exported-schema.json

@@ -1,5 +1,5 @@
 {
-  "version": "12.1.0",
+  "version": "12.2.1",
   "schemas": {
     "AppSchema": {
       "id": "/AppSchema",
@@ -67,6 +67,10 @@
           "description": "All the search-or-create combos for your app. You can create your own here, or Zapier will automatically register any from resources that define a search, a create, and a get (or define a searchOrCreate directly). Register non-resource search-or-creates here as well.",
           "$ref": "/SearchOrCreatesSchema"
         },
+        "searchAndCreates": {
+          "description": "An alias for \"searchOrCreates\".",
+          "$ref": "/SearchAndCreatesSchema"
+        },
         "flags": {
           "description": "Top-level app options",
           "$ref": "/AppFlagsSchema"
@@ -164,7 +168,7 @@
           "maxLength": 1000
         },
         "type": {
-          "description": "The type of this value. Use `string` for basic text input, `text` for a large, `<textarea>` style box, and `code` for a `<textarea>` with a fixed-width font.",
+          "description": "The type of this value. Use `string` for basic text input, `text` for a large, `<textarea>` style box, and `code` for a `<textarea>` with a fixed-width font. Field type of `file` will accept either a file object or a string. If a URL is provided in the string, Zapier will automatically make a GET for that file. Otherwise, a .txt file will be generated.",
           "type": "string",
           "enum": [
             "string",
@@ -1319,10 +1323,33 @@
         "create": {
           "description": "The key of the create that powers this search-or-create",
           "$ref": "/KeySchema"
+        },
+        "update": {
+          "description": "EXPERIMENTAL: The key of the update action (in `creates`) that will be used if a search succeeds.",
+          "$ref": "/KeySchema"
+        },
+        "updateInputFromSearchOutput": {
+          "description": "EXPERIMENTAL: A mapping where the key represents the input field for the update action, and the value represents the field from the search action's output that should be mapped to the update action's input field.",
+          "$ref": "/FlatObjectSchema"
+        },
+        "searchUniqueInputToOutputConstraint": {
+          "description": "EXPERIMENTAL: A mapping where the key represents an input field for the search action, and the value represents how that field's value will be used to filter down the search output for an exact match.",
+          "type": "object"
         }
       },
       "additionalProperties": false
     },
+    "SearchOrCreatesSchema": {
+      "id": "/SearchOrCreatesSchema",
+      "description": "Enumerates the search-or-creates your app has available for users.",
+      "type": "object",
+      "patternProperties": {
+        "^[a-zA-Z]+[a-zA-Z0-9_]*$": {
+          "description": "Any unique key can be used and its values will be validated against the SearchOrCreateSchema.",
+          "$ref": "/SearchOrCreateSchema"
+        }
+      }
+    },
     "AuthenticationSchema": {
       "id": "/AuthenticationSchema",
       "description": "Represents authentication schemes.",
@@ -1442,9 +1469,9 @@
         }
       }
     },
-    "SearchOrCreatesSchema": {
-      "id": "/SearchOrCreatesSchema",
-      "description": "Enumerates the search-or-creates your app has available for users.",
+    "SearchAndCreatesSchema": {
+      "id": "/SearchAndCreatesSchema",
+      "description": "Alias for /SearchOrCreatesSchema",
       "type": "object",
       "patternProperties": {
         "^[a-zA-Z]+[a-zA-Z0-9_]*$": {

package/lib/functional-constraints/index.js

@@ -3,7 +3,7 @@
 /* Each check below is expected to return a list of ValidationSchema errors. An error is defined by:
  *   new jsonschema.ValidationError(
  *     message, // string that explains the problem, like 'must not have a URL that points to AWS'
- *     instance, // the snippet of the app defintion that is invalid
+ *     instance, // the snippet of the app definition that is invalid
  *     schema, // name of the schema that failed, like '/TriggerSchema'
  *     propertyPath, // stringified path to problematic snippet, like 'instance.triggers.find_contact'
  *     name, // optional, the validation type that failed. Can make something up like 'invalidUrl'
@@ -18,6 +18,7 @@ const checks = [
   require('./matchingKeys'),
   require('./labelWhenVisible'),
   require('./uniqueInputFieldKeys'),
+  require('./searchAndCreatesAlias'),
 ];
 
 const runFunctionalConstraints = (definition, mainSchema) => {

package/lib/functional-constraints/searchAndCreatesAlias.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const jsonschema = require('jsonschema');
+
+const searchAndCreatesAliasConstraint = (definition) => {
+  // Ensure that 'searchOrCreates' and 'searchAndCreates' don't appear together, since one is an alias of the other
+  const errors = [];
+  if (definition.searchOrCreates && definition.searchAndCreates) {
+    errors.push(
+      new jsonschema.ValidationError(
+        `should not be used at the same time as its alias, searchAndCreates`,
+        definition,
+        `/AppSchema`,
+        `instance.searchOrCreates`,
+        'invalid',
+        'key'
+      )
+    );
+  }
+
+  return errors;
+};
+
+module.exports = searchAndCreatesAliasConstraint;

package/lib/functional-constraints/searchOrCreateKeys.js

@@ -3,20 +3,78 @@
 const _ = require('lodash');
 const jsonschema = require('jsonschema');
 
+const getFieldKeys = (definition, path) => {
+  const fields = _.get(definition, path, []);
+  // Filter out any `undefined` values using .filter(), which may happen due to incoming inputFields
+  // containing functions instead of plain Objects.
+  return fields.map((field) => field.key).filter((key) => key);
+};
+
+// This method differs from 'getFieldKeys' since here we obtain the actual object keys with Object.keys()
+const getSearchOutputSampleKeys = (definition, searchKey) => {
+  const searchOutputSampleFields = _.get(
+    definition.searches,
+    `${searchKey}.operation.sample`,
+    {}
+  );
+
+  return Object.keys(searchOutputSampleFields);
+};
+
 const validateSearchOrCreateKeys = (definition) => {
-  if (!definition.searchOrCreates) {
+  // searchAndCreates is an alias for searchOrCreates. Another functional constraint makes sure only one of them is defined.
+  const searchCreatesKey = definition.searchAndCreates
+    ? 'searchAndCreates'
+    : 'searchOrCreates';
+  const searchCreates = definition[searchCreatesKey];
+
+  if (!searchCreates) {
     return [];
   }
 
   const errors = [];
 
-  const searchKeys = _.keys(definition.searches);
-  const createKeys = _.keys(definition.creates);
+  const searchKeys = Object.keys(definition.searches);
+  const createKeys = Object.keys(definition.creates);
 
-  _.each(definition.searchOrCreates, (searchOrCreateDef, key) => {
+  _.each(searchCreates, (searchOrCreateDef, key) => {
     const searchOrCreateKey = searchOrCreateDef.key;
     const searchKey = searchOrCreateDef.search;
     const createKey = searchOrCreateDef.create;
+    const updateKey = searchOrCreateDef.update;
+
+    const updateInputKeys = getFieldKeys(
+      definition.creates,
+      `${updateKey}.operation.inputFields`
+    );
+    const searchInputKeys = getFieldKeys(
+      definition.searches,
+      `${searchKey}.operation.inputFields`
+    );
+    const searchOutputKeys = getFieldKeys(
+      definition.searches,
+      `${searchKey}.operation.outputFields`
+    );
+    const searchOutputSampleKeys = getSearchOutputSampleKeys(
+      definition,
+      searchKey
+    );
+
+    // There are constraints where we check for keys in either outputFields or sample, so combining them is a shortcut
+    const allSearchOutputKeys = new Set([
+      ...searchOutputKeys,
+      ...searchOutputSampleKeys,
+    ]);
+
+    // For some constraints, there is a difference between not "having" a key defined versus having one but with empty values
+    const hasSearchOutputFields = _.has(
+      definition.searches,
+      `${searchKey}.operation.outputFields`
+    );
+    const hasSearchOutputSample = _.has(
+      definition.searches,
+      `${searchKey}.operation.sample`
+    );
 
     // Confirm searchOrCreate.key matches a searches.key (current Zapier editor limitation)
     if (!definition.searches[searchOrCreateKey]) {
@@ -25,7 +83,7 @@ const validateSearchOrCreateKeys = (definition) => {
           `must match a "key" from a search (options: ${searchKeys})`,
           searchOrCreateDef,
           '/SearchOrCreateSchema',
-          `instance.searchOrCreates.${key}.key`,
+          `instance.${searchCreatesKey}.${key}.key`,
           'invalidKey',
           'key'
         )
@@ -39,7 +97,7 @@ const validateSearchOrCreateKeys = (definition) => {
           `must match a "key" from a search (options: ${searchKeys})`,
           searchOrCreateDef,
           '/SearchOrCreateSchema',
-          `instance.searchOrCreates.${key}.search`,
+          `instance.${searchCreatesKey}.${key}.search`,
           'invalidKey',
           'search'
         )
@@ -53,12 +111,144 @@ const validateSearchOrCreateKeys = (definition) => {
           `must match a "key" from a create (options: ${createKeys})`,
           searchOrCreateDef,
           '/SearchOrCreateSchema',
-          `instance.searchOrCreates.${key}.create`,
+          `instance.${searchCreatesKey}.${key}.create`,
           'invalidKey',
           'create'
         )
       );
     }
+
+    // Confirm searchOrCreate.update matches a creates.key, if it is defined
+    if (updateKey && !definition.creates[updateKey]) {
+      errors.push(
+        new jsonschema.ValidationError(
+          `must match a "key" from a create (options: ${createKeys})`,
+          searchOrCreateDef,
+          '/SearchOrCreateSchema',
+          `instance.${searchCreatesKey}.${key}.update`,
+          'invalidKey'
+        )
+      );
+    }
+
+    // Confirm searchOrCreate.updateInputFromSearchOutput existing implies searchOrCreate.update is defined
+    if (searchOrCreateDef.updateInputFromSearchOutput && !updateKey) {
+      errors.push(
+        new jsonschema.ValidationError(
+          `requires searchOrCreates.${key}.update to be defined`,
+          searchOrCreateDef,
+          '/SearchOrCreateSchema',
+          `instance.${searchCreatesKey}.${key}.updateInputFromSearchOutput`,
+          'invalid'
+        )
+      );
+    }
+
+    // Confirm searchOrCreate.searchUniqueInputToOutputConstraint existing implies searchOrCreate.update is defined
+    if (searchOrCreateDef.searchUniqueInputToOutputConstraint && !updateKey) {
+      errors.push(
+        new jsonschema.ValidationError(
+          `requires searchOrCreates.${key}.update to be defined`,
+          searchOrCreateDef,
+          '/SearchOrCreateSchema',
+          `instance.${searchCreatesKey}.${key}.searchUniqueInputToOutputConstraint`,
+          'invalid'
+        )
+      );
+    }
+
+    // Confirm searchOrCreate.updateInputFromSearchOutput contains objects with:
+    // keys existing in creates[update].operation.inputFields.key
+    // values existing in searches[search].operation.(outputFields.key|sample keys), if they are defined
+    if (
+      updateKey &&
+      _.isPlainObject(searchOrCreateDef.updateInputFromSearchOutput)
+    ) {
+      const updateInputOptionHint = _.isEmpty(updateInputKeys)
+        ? '(no "key" found in inputFields)'
+        : `(options: ${updateInputKeys})`;
+
+      const searchOutputOptionHint = `(options: ${[...allSearchOutputKeys]})`;
+
+      for (const [updateInputField, searchOutputField] of Object.entries(
+        searchOrCreateDef.updateInputFromSearchOutput
+      )) {
+        if (!updateInputKeys.includes(updateInputField)) {
+          errors.push(
+            new jsonschema.ValidationError(
+              `object key must match a "key" from a creates.${updateKey}.operation.inputFields ${updateInputOptionHint}`,
+              searchOrCreateDef,
+              '/SearchOrCreateSchema',
+              `instance.${searchCreatesKey}.${key}.updateInputFromSearchOutput`,
+              'invalidKey'
+            )
+          );
+        }
+
+        if (
+          (hasSearchOutputFields || hasSearchOutputSample) &&
+          !allSearchOutputKeys.has(searchOutputField)
+        ) {
+          errors.push(
+            new jsonschema.ValidationError(
+              `object value must match a "key" from searches.${searchKey}.operation.(outputFields|sample) ${searchOutputOptionHint}`,
+              searchOrCreateDef,
+              '/SearchOrCreateSchema',
+              `instance.${searchCreatesKey}.${key}.updateInputFromSearchOutput`,
+              'invalidKey'
+            )
+          );
+        }
+      }
+    }
+
+    // Confirm searchOrCreate.searchUniqueInputToOutputConstraint contains objects with:
+    // keys existing in searches[search].operation.inputFields.key
+    // values existing in searches[search].operation.(outputFields.key|sample keys), if they are defined
+    if (
+      updateKey &&
+      _.isPlainObject(searchOrCreateDef.searchUniqueInputToOutputConstraint)
+    ) {
+      const searchInputOptionHint = _.isEmpty(searchInputKeys)
+        ? '(no "key" found in inputFields)'
+        : `(options: ${searchInputKeys})`;
+
+      const searchOutputOptionHint = `(options: ${[...allSearchOutputKeys]})`;
+
+      for (const [searchInputField, searchOutputField] of Object.entries(
+        searchOrCreateDef.searchUniqueInputToOutputConstraint
+      )) {
+        if (!searchInputKeys.includes(searchInputField)) {
+          errors.push(
+            new jsonschema.ValidationError(
+              `object key must match a "key" from a searches.${searchKey}.operation.inputFields ${searchInputOptionHint}`,
+              searchOrCreateDef,
+              '/SearchOrCreateSchema',
+              `instance.${searchCreatesKey}.${key}.searchUniqueInputToOutputConstraint`,
+              'invalidKey'
+            )
+          );
+        }
+
+        if (
+          (hasSearchOutputFields || hasSearchOutputSample) &&
+          typeof searchOutputField === 'string' &&
+          !allSearchOutputKeys.has(searchOutputField)
+        ) {
+          errors.push(
+            new jsonschema.ValidationError(
+              `object value must match a "key" from searches.${searchKey}.operation.(outputFields|sample) ${searchOutputOptionHint}`,
+              searchOrCreateDef,
+              '/SearchOrCreateSchema',
+              `instance.${searchCreatesKey}.${key}.searchUniqueInputToOutputConstraint`,
+              'invalidKey'
+            )
+          );
+        }
+      }
+    }
+
+    return errors;
   });
 
   return errors;

package/lib/schemas/AppSchema.js

@@ -10,6 +10,7 @@ const ReadBulksSchema = require('./BulkReadsSchema');
 const SearchesSchema = require('./SearchesSchema');
 const CreatesSchema = require('./CreatesSchema');
 const SearchOrCreatesSchema = require('./SearchOrCreatesSchema');
+const SearchAndCreatesSchema = require('./SearchAndCreatesSchema');
 const RequestSchema = require('./RequestSchema');
 const VersionSchema = require('./VersionSchema');
 const MiddlewaresSchema = require('./MiddlewaresSchema');
@@ -96,6 +97,10 @@ module.exports = makeSchema(
           'All the search-or-create combos for your app. You can create your own here, or Zapier will automatically register any from resources that define a search, a create, and a get (or define a searchOrCreate directly). Register non-resource search-or-creates here as well.',
         $ref: SearchOrCreatesSchema.id,
       },
+      searchAndCreates: {
+        description: 'An alias for "searchOrCreates".',
+        $ref: SearchAndCreatesSchema.id,
+      },
       flags: {
         description: 'Top-level app options',
         $ref: AppFlagsSchema.id,
@@ -139,6 +144,7 @@ module.exports = makeSchema(
     SearchesSchema,
     CreatesSchema,
     SearchOrCreatesSchema,
+    SearchAndCreatesSchema,
     RequestSchema,
     VersionSchema,
     MiddlewaresSchema,

package/lib/schemas/FieldSchema.js

@@ -45,7 +45,7 @@ module.exports = makeSchema(
       },
       type: {
         description:
-          'The type of this value. Use `string` for basic text input, `text` for a large, `<textarea>` style box, and `code` for a `<textarea>` with a fixed-width font.',
+          'The type of this value. Use `string` for basic text input, `text` for a large, `<textarea>` style box, and `code` for a `<textarea>` with a fixed-width font. Field type of `file` will accept either a file object or a string. If a URL is provided in the string, Zapier will automatically make a GET for that file. Otherwise, a .txt file will be generated.',
         type: 'string',
         // string == unicode
         // text == a long textarea string

package/lib/schemas/SearchAndCreatesSchema.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+const SearchOrCreatesSchema = require('./SearchOrCreatesSchema');
+
+module.exports = makeSchema(
+  {
+    ...SearchOrCreatesSchema.schema,
+    id: '/SearchAndCreatesSchema',
+    description: 'Alias for /SearchOrCreatesSchema',
+  },
+  [SearchOrCreatesSchema]
+);

package/lib/schemas/SearchOrCreateSchema.js

@@ -1,8 +1,10 @@
 'use strict';
 
+const { SKIP_KEY } = require('../constants');
 const makeSchema = require('../utils/makeSchema');
 
 const BasicDisplaySchema = require('./BasicDisplaySchema');
+const FlatObjectSchema = require('./FlatObjectSchema');
 const KeySchema = require('./KeySchema');
 
 module.exports = makeSchema(
@@ -30,6 +32,21 @@ module.exports = makeSchema(
         description: 'The key of the create that powers this search-or-create',
         $ref: KeySchema.id,
       },
+      update: {
+        description:
+          'EXPERIMENTAL: The key of the update action (in `creates`) that will be used if a search succeeds.',
+        $ref: KeySchema.id,
+      },
+      updateInputFromSearchOutput: {
+        description:
+          "EXPERIMENTAL: A mapping where the key represents the input field for the update action, and the value represents the field from the search action's output that should be mapped to the update action's input field.",
+        $ref: FlatObjectSchema.id,
+      },
+      searchUniqueInputToOutputConstraint: {
+        description:
+          "EXPERIMENTAL: A mapping where the key represents an input field for the search action, and the value represents how that field's value will be used to filter down the search output for an exact match.",
+        type: 'object',
+      },
     },
     additionalProperties: false,
     examples: [
@@ -45,6 +62,25 @@ module.exports = makeSchema(
         search: 'searchWidgets',
         create: 'createWidget',
       },
+      {
+        key: 'upsertWidgets',
+        display: {
+          label: 'Upsert Widgets',
+          description:
+            'Searches for a widget matching the provided query and updates it if found, or creates one if it does not exist.',
+          important: true,
+          hidden: false,
+        },
+        search: 'searchWidgets',
+        create: 'createWidget',
+        update: 'updateExistingWidget',
+        updateInputFromSearchOutput: {
+          widget_id: 'id',
+        },
+        searchUniqueInputToOutputConstraint: {
+          widget_name: 'name',
+        },
+      },
     ],
     antiExamples: [
       {
@@ -78,7 +114,30 @@ module.exports = makeSchema(
         reason:
           'Invalid values for keys: search and create (must be a string that matches the key of a registered search or create)',
       },
+      {
+        [SKIP_KEY]: true, // Cannot validate field dependency between updateInputFromSearchOutput / searchUniqueInputToOutputConstraint and update
+        example: {
+          key: 'upsertWidgets',
+          display: {
+            label: 'Upsert Widgets',
+            description:
+              'Searches for a widget matching the provided query and updates it if found, or creates one if it does not exist.',
+            important: true,
+            hidden: false,
+          },
+          search: 'searchWidgets',
+          create: 'createWidget',
+          updateInputFromSearchOutput: {
+            widget_id: 'id',
+          },
+          searchUniqueInputToOutputConstraint: {
+            widget_name: 'name',
+          },
+        },
+        reason:
+          'If either the updateInputFromSearchOutput or searchUniqueInputToOutputConstraint keys are present, then the update key must be present as well.',
+      },
     ],
   },
-  [BasicDisplaySchema, KeySchema]
+  [BasicDisplaySchema, KeySchema, FlatObjectSchema]
 );

package/lib/schemas/SearchOrCreatesSchema.js

@@ -33,6 +33,21 @@ module.exports = makeSchema(
           create: 'createWidget',
         },
       },
+      {
+        searchAndCreateWidgets: {
+          key: 'searchAndCreateWidgets',
+          display: {
+            label: 'Search and Create Widgets',
+            description:
+              'Searches for a widget matching the provided query, creates one if it does not exist or updates existing one if found.',
+            important: true,
+            hidden: false,
+          },
+          search: 'searchWidgets',
+          create: 'createWidget',
+          update: 'updateWidget',
+        },
+      },
     ],
     antiExamples: [
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zapier-platform-schema",
-  "version": "12.1.0",
+  "version": "12.2.1",
   "description": "Schema definition for CLI apps in the Zapier Developer Platform.",
   "repository": "zapier/zapier-platform",
   "homepage": "https://platform.zapier.com/",