zapier-platform-schema 11.1.1

package/lib/constants.js

@@ -0,0 +1,21 @@
+module.exports = {
+  ROOT_GITHUB: 'https://github.com/zapier/zapier-platform',
+  DOCS_PATH: 'docs/build/schema.md',
+  DOC_URL_TEMPLATE:
+    'https://platform.zapier.com/cli_docs/schema<%= anchor %>@<%= version %>',
+  SKIP_KEY: '_skipTest',
+  // the following pairs of keys can't be used together in FieldSchema
+  // they're stored here because they're used in a few places
+  INCOMPATIBLE_FIELD_SCHEMA_KEYS: [
+    ['children', 'list'], // This is actually a Feature Request (https://github.com/zapier/zapier-platform-cli/issues/115)
+    ['children', 'dict'], // dict is ignored
+    ['children', 'type'], // type is ignored
+    ['children', 'placeholder'], // placeholder is ignored
+    ['children', 'helpText'], // helpText is ignored
+    ['children', 'default'], // default is ignored
+    ['dict', 'list'], // Use only one or the other
+    ['dynamic', 'dict'], // dict is ignored
+    ['dynamic', 'choices'], // choices are ignored
+  ],
+  FIELD_SCHEMA_BOOLEANS: new Set(['dict', 'list']),
+};

package/lib/functional-constraints/deepNestedFields.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const _ = require('lodash');
+const jsonschema = require('jsonschema');
+
+const collectErrors = (inputFields, path) => {
+  const errors = [];
+
+  _.each(inputFields, (inputField, index) => {
+    if (inputField.children) {
+      if (inputField.children.length === 0) {
+        errors.push(
+          new jsonschema.ValidationError(
+            'must not be empty.',
+            inputField,
+            '/FieldSchema',
+            `instance.${path}.inputFields[${index}].children`,
+            'empty',
+            'inputFields'
+          )
+        );
+      } else {
+        const hasDeeplyNestedChildren = _.some(
+          inputField.children,
+          (child) => child.children
+        );
+
+        if (hasDeeplyNestedChildren) {
+          errors.push(
+            new jsonschema.ValidationError(
+              'must not contain deeply nested child fields. One level max.',
+              inputField,
+              '/FieldSchema',
+              `instance.${path}.inputFields[${index}]`,
+              'deepNesting',
+              'inputFields'
+            )
+          );
+        }
+      }
+    }
+  });
+
+  return errors;
+};
+
+const validateFieldNesting = (definition) => {
+  let errors = [];
+
+  _.each(['triggers', 'searches', 'creates'], (typeOf) => {
+    if (definition[typeOf]) {
+      _.each(definition[typeOf], (actionDef) => {
+        if (actionDef.operation && actionDef.operation.inputFields) {
+          errors = errors.concat(
+            collectErrors(
+              actionDef.operation.inputFields,
+              `${typeOf}.${actionDef.key}`
+            )
+          );
+        }
+      });
+    }
+  });
+
+  return errors;
+};
+
+module.exports = validateFieldNesting;

package/lib/functional-constraints/index.js

@@ -0,0 +1,35 @@
+'use strict';
+
+/* 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
+ *     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'
+ *     argument // optional
+ *   );
+ */
+const checks = [
+  require('./searchOrCreateKeys'),
+  require('./deepNestedFields'),
+  require('./mutuallyExclusiveFields'),
+  require('./requiredSamples'),
+  require('./matchingKeys'),
+  require('./labelWhenVisible'),
+  require('./uniqueInputFieldKeys'),
+];
+
+const runFunctionalConstraints = (definition, mainSchema) => {
+  return checks.reduce((errors, checkFunc) => {
+    const errorsForCheck = checkFunc(definition, mainSchema);
+    if (errorsForCheck) {
+      errors = errors.concat(errorsForCheck);
+    }
+    return errors;
+  }, []);
+};
+
+module.exports = {
+  run: runFunctionalConstraints,
+};

package/lib/functional-constraints/labelWhenVisible.js

@@ -0,0 +1,31 @@
+const _ = require('lodash');
+const jsonschema = require('jsonschema');
+
+const actionTypes = ['triggers', 'searches', 'creates'];
+
+const labelWhenVisible = (definition) => {
+  const errors = [];
+
+  for (const actionType of actionTypes) {
+    const group = definition[actionType] || {};
+    _.each(group, (action, key) => {
+      const { display } = action;
+      if (!display.hidden && !(display.label && display.description)) {
+        errors.push(
+          new jsonschema.ValidationError(
+            `visible actions must have a label and description`,
+            action,
+            `/BasicDisplaySchema`,
+            `instance.${actionType}.${key}.display`,
+            'invalid',
+            'key'
+          )
+        );
+      }
+    });
+  }
+
+  return errors;
+};
+
+module.exports = labelWhenVisible;

package/lib/functional-constraints/matchingKeys.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const _ = require('lodash');
+const jsonschema = require('jsonschema');
+
+const actionTypes = ['triggers', 'searches', 'creates'];
+
+const matchingKeys = (definition) => {
+  const errors = [];
+
+  // verifies that x.key === x
+  // otherwise, we double results in the compiled app via core's compileApp
+
+  for (const actionType of actionTypes) {
+    const group = definition[actionType] || {};
+    _.each(group, (action, key) => {
+      if (action.key !== key) {
+        errors.push(
+          new jsonschema.ValidationError(
+            `must have a matching top-level key (found "${key}" and "${action.key}")`,
+            action,
+            `/${_.capitalize(actionType)}Schema`,
+            `instance.${key}.key`,
+            'invalid',
+            'key'
+          )
+        );
+      }
+    });
+  }
+
+  return errors;
+};
+
+module.exports = matchingKeys;

package/lib/functional-constraints/mutuallyExclusiveFields.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const _ = require('lodash');
+const jsonschema = require('jsonschema');
+
+// NOTE: While it would be possible to accomplish this with a solution like
+//   https://stackoverflow.com/questions/28162509/mutually-exclusive-property-groups#28172831
+//   it was harder to read and understand.
+
+const {
+  INCOMPATIBLE_FIELD_SCHEMA_KEYS,
+  FIELD_SCHEMA_BOOLEANS,
+} = require('../constants');
+
+const verifyIncompatibilities = (inputFields, path) => {
+  const errors = [];
+
+  _.each(inputFields, (inputField, index) => {
+    _.each(INCOMPATIBLE_FIELD_SCHEMA_KEYS, ([firstField, secondField]) => {
+      if (_.has(inputField, firstField) && _.has(inputField, secondField)) {
+        // this could be ok if it's a boolean field and is falsy
+        // i'm reasonably sure that the editor handles this fine, but if it also checks
+        // for the existence of the property (not the truthiness), then there could be an issue
+        if (
+          (FIELD_SCHEMA_BOOLEANS.has(firstField) && !inputField[firstField]) ||
+          (FIELD_SCHEMA_BOOLEANS.has(secondField) && !inputField[secondField])
+        ) {
+          return;
+        }
+
+        errors.push(
+          new jsonschema.ValidationError(
+            `must not contain ${firstField} and ${secondField}, as they're mutually exclusive.`,
+            inputField,
+            '/FieldSchema',
+            `instance.${path}.inputFields[${index}]`,
+            'invalid',
+            'inputFields'
+          )
+        );
+      }
+    });
+  });
+
+  return errors;
+};
+
+const mutuallyExclusiveFields = (definition) => {
+  let errors = [];
+
+  _.each(['triggers', 'searches', 'creates'], (typeOf) => {
+    if (definition[typeOf]) {
+      _.each(definition[typeOf], (actionDef) => {
+        if (actionDef.operation && actionDef.operation.inputFields) {
+          errors = [
+            ...errors,
+            ...verifyIncompatibilities(
+              actionDef.operation.inputFields,
+              `${typeOf}.${actionDef.key}`
+            ),
+          ];
+        }
+      });
+    }
+  });
+
+  return errors;
+};
+
+module.exports = mutuallyExclusiveFields;

package/lib/functional-constraints/requiredSamples.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const _ = require('lodash');
+const jsonschema = require('jsonschema');
+
+// todo: deal with circular dep.
+const RESOURCE_ID = '/ResourceSchema';
+const RESOURCE_METHODS = ['get', 'hook', 'list', 'search', 'create'];
+
+const check = (definition) => {
+  if (!definition.operation || _.get(definition, 'display.hidden')) {
+    return null;
+  }
+
+  const samples = _.get(definition, 'operation.sample', {});
+  return !_.isEmpty(samples)
+    ? null
+    : new jsonschema.ValidationError(
+        'requires "sample", because it\'s not hidden',
+        definition,
+        definition.id
+      );
+};
+
+module.exports = (definition, mainSchema) => {
+  let definitions = [];
+
+  if (mainSchema.id === RESOURCE_ID) {
+    definitions = RESOURCE_METHODS.map((method) => definition[method]).filter(
+      Boolean
+    );
+
+    // allow method definitions to inherit the sample
+    if (definition.sample) {
+      definitions.forEach((methodDefinition) => {
+        if (methodDefinition.operation && !methodDefinition.operation.sample) {
+          methodDefinition.operation.sample = definition.sample;
+        }
+      });
+    }
+
+    if (!definitions.length) {
+      return [
+        new jsonschema.ValidationError(
+          'expected at least one resource operation',
+          definition,
+          definition.id
+        ),
+      ];
+    }
+  } else {
+    definitions = [definition];
+  }
+
+  return definitions.map(check).filter(Boolean);
+};

package/lib/functional-constraints/searchOrCreateKeys.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const _ = require('lodash');
+const jsonschema = require('jsonschema');
+
+const validateSearchOrCreateKeys = (definition) => {
+  if (!definition.searchOrCreates) {
+    return [];
+  }
+
+  const errors = [];
+
+  const searchKeys = _.keys(definition.searches);
+  const createKeys = _.keys(definition.creates);
+
+  _.each(definition.searchOrCreates, (searchOrCreateDef, key) => {
+    const searchOrCreateKey = searchOrCreateDef.key;
+    const searchKey = searchOrCreateDef.search;
+    const createKey = searchOrCreateDef.create;
+
+    // Confirm searchOrCreate.key matches a searches.key (current Zapier editor limitation)
+    if (!definition.searches[searchOrCreateKey]) {
+      errors.push(
+        new jsonschema.ValidationError(
+          `must match a "key" from a search (options: ${searchKeys})`,
+          searchOrCreateDef,
+          '/SearchOrCreateSchema',
+          `instance.searchOrCreates.${key}.key`,
+          'invalidKey',
+          'key'
+        )
+      );
+    }
+
+    // Confirm searchOrCreate.search matches a searches.key
+    if (!definition.searches[searchKey]) {
+      errors.push(
+        new jsonschema.ValidationError(
+          `must match a "key" from a search (options: ${searchKeys})`,
+          searchOrCreateDef,
+          '/SearchOrCreateSchema',
+          `instance.searchOrCreates.${key}.search`,
+          'invalidKey',
+          'search'
+        )
+      );
+    }
+
+    // Confirm searchOrCreate.create matches a creates.key
+    if (!definition.creates[createKey]) {
+      errors.push(
+        new jsonschema.ValidationError(
+          `must match a "key" from a create (options: ${createKeys})`,
+          searchOrCreateDef,
+          '/SearchOrCreateSchema',
+          `instance.searchOrCreates.${key}.create`,
+          'invalidKey',
+          'create'
+        )
+      );
+    }
+  });
+
+  return errors;
+};
+
+module.exports = validateSearchOrCreateKeys;

package/lib/functional-constraints/uniqueInputFieldKeys.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const _ = require('lodash');
+const jsonschema = require('jsonschema');
+
+const actionTypes = ['triggers', 'searches', 'creates'];
+
+const uniqueInputFieldKeys = (definition) => {
+  const errors = [];
+  for (const actionType of actionTypes) {
+    const group = definition[actionType] || {};
+    _.each(group, (action, key) => {
+      const inputFields = _.get(action, ['operation', 'inputFields'], []);
+
+      const existingKeys = {}; // map of key to where it already lives
+
+      inputFields.forEach((inputField, index) => {
+        // could be a string or a non-field object (`source` or `require` function obj)
+        if (!inputField.key) {
+          return;
+        }
+
+        if (existingKeys[inputField.key]) {
+          errors.push(
+            new jsonschema.ValidationError(
+              `inputField keys must be unique for each action. The key "${
+                inputField.key
+              }" is already in use at ${actionType}.${key}.operation.${
+                existingKeys[inputField.key]
+              }.key`,
+              inputField.key,
+              `/BasicOperationSchema`,
+              `instance.${actionType}.${key}.operation.inputFields[${index}].key`
+            )
+          );
+        } else {
+          existingKeys[inputField.key] = `inputFields[${index}]`;
+        }
+
+        (inputField.children || []).forEach((subField, subFieldIndex) => {
+          if (existingKeys[subField.key]) {
+            errors.push(
+              new jsonschema.ValidationError(
+                `inputField keys must be unique for each action, even if they're children. The key "${
+                  subField.key
+                }" is already in use at ${actionType}.${key}.operation.${
+                  existingKeys[subField.key]
+                }.key`,
+                subField.key,
+                `/BasicOperationSchema`,
+                `instance.${actionType}.${key}.operation.inputFields[${index}].children[${subFieldIndex}].key`
+              )
+            );
+          } else {
+            existingKeys[
+              subField.key
+            ] = `inputFields[${index}].children[${subFieldIndex}]`;
+          }
+        });
+      });
+    });
+  }
+
+  return errors;
+};
+
+module.exports = uniqueInputFieldKeys;

package/lib/schemas/AppFlagsSchema.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+module.exports = makeSchema({
+  id: '/AppFlagsSchema',
+  description: 'Codifies high-level options for your app.',
+  type: 'object',
+  properties: {
+    skipHttpPatch: {
+      description:
+        "By default, Zapier patches the core `http` module so that all requests (including those from 3rd-party SDKs) can be logged. Set this to true if you're seeing issues using an SDK (such as AWS).",
+      type: 'boolean',
+    },
+  },
+  additionalProperties: false,
+  examples: [{ skipHttpPatch: true }, { skipHttpPatch: false }, {}],
+  antiExamples: [
+    { example: { foo: true }, reason: 'Invalid key.' },
+    { example: { skipHttpPatch: 'yes' }, reason: 'Invalid value.' },
+  ],
+});

package/lib/schemas/AppSchema.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+const AuthenticationSchema = require('./AuthenticationSchema');
+const FlatObjectSchema = require('./FlatObjectSchema');
+const ResourcesSchema = require('./ResourcesSchema');
+const TriggersSchema = require('./TriggersSchema');
+const ReadBulksSchema = require('./BulkReadsSchema');
+const SearchesSchema = require('./SearchesSchema');
+const CreatesSchema = require('./CreatesSchema');
+const SearchOrCreatesSchema = require('./SearchOrCreatesSchema');
+const RequestSchema = require('./RequestSchema');
+const VersionSchema = require('./VersionSchema');
+const MiddlewaresSchema = require('./MiddlewaresSchema');
+const HydratorsSchema = require('./HydratorsSchema');
+const AppFlagsSchema = require('./AppFlagsSchema');
+
+module.exports = makeSchema(
+  {
+    id: '/AppSchema',
+    description: 'Represents a full app.',
+    type: 'object',
+    required: ['version', 'platformVersion'],
+    properties: {
+      version: {
+        description: 'A version identifier for your code.',
+        $ref: VersionSchema.id,
+      },
+      platformVersion: {
+        description:
+          'A version identifier for the Zapier execution environment.',
+        $ref: VersionSchema.id,
+      },
+      beforeApp: {
+        description:
+          'EXPERIMENTAL: Before the perform method is called on your app, you can modify the execution context.',
+        $ref: MiddlewaresSchema.id,
+      },
+      afterApp: {
+        description:
+          'EXPERIMENTAL: After the perform method is called on your app, you can modify the response.',
+        $ref: MiddlewaresSchema.id,
+      },
+      authentication: {
+        description: 'Choose what scheme your API uses for authentication.',
+        $ref: AuthenticationSchema.id,
+      },
+      requestTemplate: {
+        description:
+          'Define a request mixin, great for setting custom headers, content-types, etc.',
+        $ref: RequestSchema.id,
+      },
+      beforeRequest: {
+        description:
+          'Before an HTTP request is sent via our `z.request()` client, you can modify it.',
+        $ref: MiddlewaresSchema.id,
+      },
+      afterResponse: {
+        description:
+          'After an HTTP response is recieved via our `z.request()` client, you can modify it.',
+        $ref: MiddlewaresSchema.id,
+      },
+      hydrators: {
+        description:
+          "An optional bank of named functions that you can use in `z.hydrate('someName')` to lazily load data.",
+        $ref: HydratorsSchema.id,
+      },
+      resources: {
+        description:
+          'All the resources for your app. Zapier will take these and generate the relevent triggers/searches/creates automatically.',
+        $ref: ResourcesSchema.id,
+      },
+      triggers: {
+        description:
+          'All the triggers for your app. You can add your own here, or Zapier will automatically register any from the list/hook methods on your resources.',
+        $ref: TriggersSchema.id,
+      },
+      bulkReads: {
+        description:
+          'All of the read bulks (GETs) your app exposes to retrieve resources in batches.',
+        $ref: ReadBulksSchema.id,
+      },
+      searches: {
+        description:
+          'All the searches for your app. You can add your own here, or Zapier will automatically register any from the search method on your resources.',
+        $ref: SearchesSchema.id,
+      },
+      creates: {
+        description:
+          'All the creates for your app. You can add your own here, or Zapier will automatically register any from the create method on your resources.',
+        $ref: CreatesSchema.id,
+      },
+      searchOrCreates: {
+        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.id,
+      },
+      flags: {
+        description: 'Top-level app options',
+        $ref: AppFlagsSchema.id,
+      },
+      legacy: {
+        description:
+          '**INTERNAL USE ONLY**. Zapier uses this to hold properties from a legacy Web Builder app.',
+        type: 'object',
+        docAnnotation: {
+          hide: true,
+        },
+      },
+      firehoseWebhooks: {
+        description:
+          '**INTERNAL USE ONLY**. Zapier uses this for internal webhook app configurations.',
+        type: 'object',
+        docAnnotation: {
+          hide: true,
+        },
+      },
+    },
+    additionalProperties: false,
+    examples: [{ version: '1.0.0', platformVersion: '10.1.2' }],
+    antiExamples: [
+      {
+        example: { version: 'v1.0.0', platformVersion: '10.1.2' },
+        reason: 'Invalid value for version.',
+      },
+      {
+        example: { version: '1.0.0', platformVersion: 'v10.1.2' },
+        reason: 'Invalid value for platformVersion.',
+      },
+    ],
+  },
+  [
+    AuthenticationSchema,
+    FlatObjectSchema,
+    ResourcesSchema,
+    ReadBulksSchema,
+    TriggersSchema,
+    SearchesSchema,
+    CreatesSchema,
+    SearchOrCreatesSchema,
+    RequestSchema,
+    VersionSchema,
+    MiddlewaresSchema,
+    HydratorsSchema,
+    AppFlagsSchema,
+  ]
+);

package/lib/schemas/AuthenticationBasicConfigSchema.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+module.exports = makeSchema({
+  id: '/AuthenticationBasicConfigSchema',
+  description:
+    'Config for Basic Authentication. No extra properties are required to setup Basic Auth, so you can leave this empty if your app uses Basic Auth.',
+  type: 'object',
+  properties: {},
+  additionalProperties: false,
+  examples: [{}],
+  antiExamples: [{ example: { foo: true }, reason: 'Invalid key.' }],
+});

package/lib/schemas/AuthenticationCustomConfigSchema.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+module.exports = makeSchema({
+  id: '/AuthenticationCustomConfigSchema',
+  description:
+    'Config for custom authentication (like API keys). No extra properties are required to setup this auth type, so you can leave this empty if your app uses a custom auth method.',
+  type: 'object',
+  properties: {},
+  additionalProperties: false,
+  examples: [{}],
+  antiExamples: [{ example: { foo: true }, reason: 'Invalid key.' }],
+});

package/lib/schemas/AuthenticationDigestConfigSchema.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+module.exports = makeSchema({
+  id: '/AuthenticationDigestConfigSchema',
+  description:
+    'Config for Digest Authentication. No extra properties are required to setup Digest Auth, so you can leave this empty if your app uses Digets Auth.',
+  type: 'object',
+  properties: {},
+  additionalProperties: false,
+  examples: [{}],
+  antiExamples: [{ example: { foo: true }, reason: 'Invalid key.' }],
+});