zapier-platform-schema 11.1.1

package/lib/schemas/SearchSchema.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+const BasicDisplaySchema = require('./BasicDisplaySchema');
+const BasicActionOperationSchema = require('./BasicActionOperationSchema');
+const KeySchema = require('./KeySchema');
+
+module.exports = makeSchema(
+  {
+    id: '/SearchSchema',
+    description: 'How will Zapier search for existing objects?',
+    type: 'object',
+    required: ['key', 'noun', 'display', 'operation'],
+    properties: {
+      key: {
+        description: 'A key to uniquely identify this search.',
+        $ref: KeySchema.id,
+      },
+      noun: {
+        description:
+          'A noun for this search that completes the sentence "finds a specific XXX".',
+        type: 'string',
+        minLength: 2,
+        maxLength: 255,
+      },
+      display: {
+        description: 'Configures the UI for this search.',
+        $ref: BasicDisplaySchema.id,
+      },
+      operation: {
+        description: 'Powers the functionality for this search.',
+        $ref: BasicActionOperationSchema.id,
+      },
+    },
+    additionalProperties: false,
+    examples: [
+      {
+        key: 'recipe',
+        noun: 'Recipe',
+        display: {
+          label: 'Find a Recipe',
+          description: 'Search for recipe by cuisine style.',
+        },
+        operation: {
+          perform: '$func$2$f$',
+          sample: { id: 1 },
+        },
+      },
+      {
+        key: 'recipe',
+        noun: 'Recipe',
+        display: {
+          label: 'Find a Recipe',
+          description: 'Search for recipe by cuisine style.',
+          hidden: true,
+        },
+        operation: { perform: '$func$2$f$' },
+      },
+    ],
+    antiExamples: [
+      {
+        example: 'abc',
+        reason: 'Must be an object',
+      },
+      {
+        example: {
+          key: 'recipe',
+          noun: 'Recipe',
+          display: {
+            label: 'Find a Recipe',
+            description: 'Search for recipe by cuisine style.',
+          },
+          operation: {
+            perform: '$func$2$f$',
+          },
+        },
+        reason:
+          'Missing required key in operation: sample. Note - this is valid if the associated resource has defined a sample.',
+      },
+    ],
+  },
+  [BasicDisplaySchema, BasicActionOperationSchema, KeySchema]
+);

package/lib/schemas/SearchesSchema.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+const { SKIP_KEY } = require('../constants');
+
+const SearchSchema = require('./SearchSchema');
+
+module.exports = makeSchema(
+  {
+    id: '/SearchesSchema',
+    description: 'Enumerates the searches 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 SearchSchema.',
+        $ref: SearchSchema.id,
+      },
+    },
+    examples: [
+      {
+        recipe: {
+          key: 'recipe',
+          noun: 'Recipe',
+          display: {
+            label: 'Find a Recipe',
+            description: 'Search for recipe by cuisine style.',
+            hidden: true,
+          },
+          operation: { perform: '$func$2$f$' },
+        },
+      },
+    ],
+    antiExamples: [
+      {
+        [SKIP_KEY]: true, // Cannot validate that keys match
+        example: {
+          searchRecipe: {
+            key: 'recipe',
+            noun: 'Recipe',
+            display: {
+              label: 'Find a Recipe',
+              description: 'Search for recipe by cuisine style.',
+              hidden: true,
+            },
+            operation: { perform: '$func$2$f$' },
+          },
+        },
+        reason: 'Key must match the key of the associated /SearchSchema',
+      },
+    ],
+  },
+  [SearchSchema]
+);

package/lib/schemas/TriggerSchema.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+const BasicDisplaySchema = require('./BasicDisplaySchema');
+const BasicHookOperationSchema = require('./BasicHookOperationSchema');
+const BasicPollingOperationSchema = require('./BasicPollingOperationSchema');
+const KeySchema = require('./KeySchema');
+
+module.exports = makeSchema(
+  {
+    id: '/TriggerSchema',
+    description: 'How will Zapier get notified of new objects?',
+    type: 'object',
+    required: ['key', 'noun', 'display', 'operation'],
+    properties: {
+      key: {
+        description: 'A key to uniquely identify this trigger.',
+        $ref: KeySchema.id,
+      },
+      noun: {
+        description:
+          'A noun for this trigger that completes the sentence "triggers on a new XXX".',
+        type: 'string',
+        minLength: 2,
+        maxLength: 255,
+      },
+      display: {
+        description: 'Configures the UI for this trigger.',
+        $ref: BasicDisplaySchema.id,
+      },
+      operation: {
+        description: 'Powers the functionality for this trigger.',
+        anyOf: [
+          { $ref: BasicPollingOperationSchema.id },
+          { $ref: BasicHookOperationSchema.id },
+        ],
+      },
+    },
+    additionalProperties: false,
+    examples: [
+      {
+        key: 'new_recipe',
+        noun: 'Recipe',
+        display: {
+          label: 'New Recipe',
+          description: 'Triggers when a new recipe is added.',
+        },
+        operation: {
+          type: 'polling',
+          perform: '$func$0$f$',
+          sample: { id: 1 },
+        },
+      },
+      {
+        key: 'new_recipe',
+        noun: 'Recipe',
+        display: {
+          label: 'New Recipe',
+          description: 'Triggers when a new recipe is added.',
+          hidden: true,
+        },
+        operation: {
+          type: 'polling',
+          perform: '$func$0$f$',
+        },
+      },
+    ],
+    antiExamples: [
+      {
+        example: {
+          key: 'new_recipe',
+          noun: 'Recipe',
+          display: {
+            label: 'New Recipe',
+            description: 'Triggers when a new recipe is added.',
+          },
+          operation: {
+            perform: '$func$0$f$',
+          },
+        },
+        reason:
+          'Missing required key from operation: sample. Note - this is valid if the Recipe resource has defined a sample.',
+      },
+    ],
+  },
+  [
+    KeySchema,
+    BasicDisplaySchema,
+    BasicPollingOperationSchema,
+    BasicHookOperationSchema,
+  ]
+);

package/lib/schemas/TriggersSchema.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+const { SKIP_KEY } = require('../constants');
+
+const TriggerSchema = require('./TriggerSchema');
+
+module.exports = makeSchema(
+  {
+    id: '/TriggersSchema',
+    description: 'Enumerates the triggers 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 TriggerSchema.',
+        $ref: TriggerSchema.id,
+      },
+    },
+    additionalProperties: false,
+    examples: [
+      {
+        newRecipe: {
+          key: 'newRecipe',
+          noun: 'Recipe',
+          display: {
+            label: 'New Recipe',
+            description: 'Triggers when a new recipe is added.',
+          },
+          operation: {
+            type: 'polling',
+            perform: '$func$0$f$',
+            sample: { id: 1 },
+          },
+        },
+      },
+    ],
+    antiExamples: [
+      {
+        example: {
+          [SKIP_KEY]: true, // Cannot validate that keys don't match
+          newRecipe: {
+            key: 'new_recipe',
+            noun: 'Recipe',
+            display: {
+              label: 'New Recipe',
+              description: 'Triggers when a new recipe is added.',
+            },
+            operation: {
+              type: 'polling',
+              perform: '$func$0$f$',
+              sample: { id: 1 },
+            },
+          },
+        },
+        reason: 'Key must match the key on the associated /TriggerSchema',
+      },
+    ],
+  },
+  [TriggerSchema]
+);

package/lib/schemas/VersionSchema.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+module.exports = makeSchema({
+  id: '/VersionSchema',
+  description:
+    'Represents a simplified semver string, from `0.0.0` to `999.999.999`.',
+  type: 'string',
+  pattern: '^[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}$',
+  examples: ['1.0.0', '2.11.3', '999.999.999'],
+  antiExamples: [
+    { example: '1.0.0.0', reason: 'Must have only 2 periods' },
+    { example: '1000.0.0', reason: 'Each number can be a maximum of 3 digits' },
+    { example: 'v1.0.0', reason: 'No letters allowed' },
+    { example: '1.0.0-beta', reson: 'No letters allowed' },
+  ],
+});

package/lib/utils/buildDocs.js

@@ -0,0 +1,213 @@
+'use strict';
+
+const util = require('util');
+
+const _ = require('lodash');
+const toc = require('markdown-toc');
+
+const packageJson = require('../../package.json');
+const links = require('./links');
+
+const NO_DESCRIPTION = '_No description given._';
+const COMBOS = ['anyOf', 'allOf', 'oneOf'];
+const { SKIP_KEY } = require('../constants');
+
+const walkSchemas = (InitSchema, callback) => {
+  const recurse = (Schema, parents) => {
+    parents = parents || [];
+    callback(Schema, parents);
+    Schema.dependencies.forEach((childSchema) => {
+      const newParents = parents.concat([InitSchema]);
+      recurse(childSchema, newParents);
+    });
+  };
+  recurse(InitSchema);
+};
+
+const collectSchemas = (InitSchema) => {
+  const schemas = {};
+  walkSchemas(InitSchema, (Schema) => {
+    schemas[Schema.id] = Schema;
+  });
+  return schemas;
+};
+
+const BREAK_LENGTH = 96;
+const prepQuote = (val) => val.replace('`', '');
+const quote = (val, triple, indent = '') =>
+  // either ``` with optional indentation or `
+  triple && val.length > BREAK_LENGTH
+    ? '```\n' +
+      val
+        .match(/[^\r\n]+/g)
+        .map((line) => indent + line)
+        .join('\n') +
+      '\n' +
+      indent +
+      '```'
+    : `\`${prepQuote(val)}\``;
+const quoteOrNa = (val, triple = false, indent = '') =>
+  val ? quote(val, triple, indent) : '_n/a_';
+
+const formatExample = (example) => {
+  const ex = _.isPlainObject(example) ? _.omit(example, SKIP_KEY) : example;
+  return `* ${quoteOrNa(
+    util.inspect(ex, { depth: null, breakLength: BREAK_LENGTH }),
+    true,
+    '  '
+  )}`.replace(/\s+\n/gm, '\n');
+};
+
+// Generate a display of the type (or link to a $ref).
+const typeOrLink = (schema) => {
+  if (schema.type === 'array' && schema.items) {
+    return `${quoteOrNa(schema.type)}[${typeOrLink(schema.items)}]`;
+  }
+  if (schema.$ref) {
+    return `[${schema.$ref}](${links.anchor(schema.$ref)})`;
+  }
+  for (let i = 0; i < COMBOS.length; i++) {
+    const key = COMBOS[i];
+    if (schema[key] && schema[key].length) {
+      return `${key}(${schema[key].map(typeOrLink).join(', ')})`;
+    }
+  }
+  if (schema.enum && schema.enum.length) {
+    return `${quoteOrNa(schema.type)} in (${schema.enum
+      .map(util.inspect)
+      .map(quoteOrNa)
+      .join(', ')})`;
+  }
+  return quoteOrNa(schema.type);
+};
+
+// Properly quote and display examples.
+const makeExampleSection = (Schema) => {
+  const examples = Schema.schema.examples || [];
+  if (!examples.length) {
+    return '';
+  }
+  return `\
+#### Examples
+
+${examples.map(formatExample).join('\n')}
+`;
+};
+
+// Properly quote and display anti-examples.
+const makeAntiExampleSection = (Schema) => {
+  const antiExamples = Schema.schema.antiExamples || [];
+  if (!antiExamples.length) {
+    return '';
+  }
+  return `\
+#### Anti-Examples
+
+${antiExamples
+  .map(({ example, reason }) => {
+    const formattedAntiExample = formatExample(example);
+    // If block quote, newline and indent the reason.
+    // Otherwise, show the reason inline w/ the anti-example and separated by a dash.
+    return formattedAntiExample.endsWith('```')
+      ? `${formattedAntiExample}\n  _${reason}_`
+      : `${formattedAntiExample} - _${reason}_`;
+  })
+  .join('\n')}
+`;
+};
+
+const processProperty = (key, property, propIsRequired) => {
+  let isRequired = propIsRequired ? '**yes**' : 'no';
+  if (_.get(property, 'docAnnotation.hide')) {
+    return '';
+  } else if (_.get(property, 'docAnnotation.required')) {
+    // can also support keys besides "required"
+    const annotation = property.docAnnotation.required;
+    if (annotation.type === 'replace') {
+      isRequired = annotation.value;
+    } else if (annotation.type === 'append') {
+      isRequired += annotation.value;
+    } else {
+      throw new Error(`unrecognized docAnnotation type: ${annotation.type}`);
+    }
+  }
+  return `${quoteOrNa(key)} | ${isRequired} | ${typeOrLink(property)} | ${
+    property.description || NO_DESCRIPTION
+  }`;
+};
+
+// Enumerate the properties as a table.
+const makePropertiesSection = (Schema) => {
+  const properties =
+    Schema.schema.properties || Schema.schema.patternProperties || {};
+  if (!Object.keys(properties).length) {
+    return '';
+  }
+  const required = Schema.schema.required || [];
+  return `\
+#### Properties
+
+Key | Required | Type | Description
+--- | -------- | ---- | -----------
+${Object.keys(properties)
+  .map((key) => {
+    const property = properties[key];
+    return processProperty(key, property, required.includes(key));
+  })
+  .join('\n')}
+`;
+};
+
+// Given a "root" schema, create some markdown.
+const makeMarkdownSection = (Schema) => {
+  return `\
+## ${Schema.id}
+
+${Schema.schema.description || NO_DESCRIPTION}
+
+#### Details
+
+* **Type** - ${typeOrLink(Schema.schema)}${
+    Schema.schema.pattern
+      ? `
+* **Pattern** - ${quoteOrNa(Schema.schema.pattern)}`
+      : ''
+  }
+* [**Source Code**](${links.makeCodeLink(Schema.id)})
+
+${makePropertiesSection(Schema)}
+${makeExampleSection(Schema)}
+${makeAntiExampleSection(Schema)}
+`.trim();
+};
+
+// Generate the final markdown.
+const buildDocs = (InitSchema) => {
+  const schemas = collectSchemas(InitSchema);
+  const markdownSections = _.chain(schemas)
+    .values()
+    .sortBy('id')
+    .map(makeMarkdownSection)
+    .join('\n\n-----\n\n');
+  const docs = `\
+<!-- {% raw %} -->
+# \`zapier-platform-schema\` Generated Documentation
+
+This is automatically generated by the \`npm run docs\` command in \`zapier-platform-schema\` version ${quoteOrNa(
+    packageJson.version
+  )}.
+
+-----
+
+## Index
+<!-- toc -->
+
+-----
+
+${markdownSections}
+<!-- {% endraw %} -->
+`.trim();
+  return toc.insert(docs, { maxdepth: 2, bullets: '*' });
+};
+
+module.exports = buildDocs;

package/lib/utils/exportSchema.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const _ = require('lodash');
+const packageJson = require('../../package.json');
+
+const exportSchema = (InitSchema) => {
+  const exportedSchema = {
+    version: packageJson.version,
+    schemas: {},
+  };
+  const addAndRecurse = (Schema) => {
+    exportedSchema.schemas[Schema.id.replace('/', '')] = _.omit(
+      Schema.schema,
+      'examples',
+      'antiExamples'
+    );
+    Schema.dependencies.map(addAndRecurse);
+  };
+  addAndRecurse(InitSchema);
+  return exportedSchema;
+};
+
+module.exports = exportSchema;

package/lib/utils/links.js

@@ -0,0 +1,27 @@
+const _ = require('lodash');
+
+const packageJson = require('../../package.json');
+const constants = require('../constants.js');
+
+// From '</SomeSchema>' to 'SomeSchema'.
+const filename = (val) => _.trim(String(val), '/<>');
+
+// From '/SomeSchema' to '#someschema'.
+const anchor = (val) => '#' + filename(val.toLowerCase());
+
+const makeCodeLink = (id) =>
+  `${constants.ROOT_GITHUB}/blob/zapier-platform-schema@${
+    packageJson.version
+  }/packages/schema/lib/schemas/${filename(id)}.js`;
+const makeDocLink = (id) =>
+  _.template(constants.DOC_URL_TEMPLATE)({
+    version: packageJson.version,
+    anchor: anchor(id),
+  });
+
+module.exports = {
+  filename: filename,
+  anchor: anchor,
+  makeCodeLink: makeCodeLink,
+  makeDocLink: makeDocLink,
+};

package/lib/utils/makeSchema.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const _ = require('lodash');
+
+const makeValidator = require('./makeValidator');
+
+const getRawSchema = (schema) => schema.schema;
+
+const getDependencies = (schema) => schema.dependencies;
+
+const flattenDependencies = (schemas) => {
+  schemas = schemas || [];
+  return _.flatten(schemas.map(getDependencies).concat(schemas));
+};
+
+const makeSchema = (schemaDefinition, schemaDependencies) => {
+  const dependencies = flattenDependencies(schemaDependencies);
+  const validatorDependencies = dependencies.map(getRawSchema);
+  return {
+    dependencies,
+    id: schemaDefinition.id,
+    schema: schemaDefinition,
+    validate: makeValidator(schemaDefinition, validatorDependencies).validate,
+  };
+};
+
+module.exports = makeSchema;