zapier-platform-schema 11.0.0 → 11.2.0

package/LICENSE

@@ -1,4 +1,3 @@
 Copyright (c) Zapier, Inc.
 
-This repository is part of Zapier Platform, of which license terms can be found at
-https://zapier.com/platform/tos.
+This repository is part of Zapier Platform.  By downloading, installing, accessing, or using any part of the Zapier Platform, including this repository, you agree to the Zapier Platform Agreement, which can be found at: https://zapier.com/platform/tos.  If you do not agree to the Zapier Platform Agreement, you may not download, install, access, or use any part of the Zapier Platform, including this repository.

package/exported-schema.json

@@ -1,5 +1,5 @@
 {
-  "version": "11.0.0",
+  "version": "11.2.0",
   "schemas": {
     "AppSchema": {
       "id": "/AppSchema",
@@ -115,7 +115,7 @@
       "id": "/RefResourceSchema",
       "description": "Reference a resource by key and the data it returns. In the format of: `{resource_key}.{foreign_key}(.{human_label_key})`.",
       "type": "string",
-      "pattern": "^[a-zA-Z0-9_]+\\.[a-zA-Z0-9_]+(\\.[a-zA-Z0-9_]+(,[a-zA-Z0-9_]+)*)?$"
+      "pattern": "^[a-zA-Z0-9_]+\\.[a-zA-Z0-9_\\s\\[\\]]+(\\.[a-zA-Z0-9_\\s\\[\\]]+(,[a-zA-Z0-9_\\s\\[\\]]+)*)?$"
     },
     "FieldChoicesSchema": {
       "id": "/FieldChoicesSchema",
@@ -164,7 +164,7 @@
           "maxLength": 1000
         },
         "type": {
-          "description": "The type of this value.",
+          "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.",
           "type": "string",
           "enum": [
             "string",
@@ -175,7 +175,8 @@
             "datetime",
             "file",
             "password",
-            "copy"
+            "copy",
+            "code"
           ]
         },
         "required": {
@@ -732,6 +733,10 @@
             }
           }
         },
+        "canPaginate": {
+          "description": "Does this endpoint support pagination via temporary cursor storage?",
+          "type": "boolean"
+        },
         "performSubscribe": {
           "description": "Takes a URL and any necessary data from the user and subscribes. Note: this is required for public apps to ensure the best UX for the end-user. For private apps, you can ignore warnings about this property with the `--without-style` flag during `zapier push`.",
           "oneOf": [
@@ -816,7 +821,7 @@
           ]
         },
         "canPaginate": {
-          "description": "Does this endpoint support a page offset?",
+          "description": "Does this endpoint support pagination via temporary cursor storage?",
           "type": "boolean"
         },
         "inputFields": {
@@ -1059,6 +1064,83 @@
       },
       "additionalProperties": false
     },
+    "BasicHookToPollOperationSchema": {
+      "id": "/BasicHookToPollOperationSchema",
+      "description": "Represents the inbound mechanics of hook to poll style triggers. Defers to list for fields.",
+      "type": "object",
+      "required": ["performList", "performSubscribe", "performUnsubscribe"],
+      "properties": {
+        "type": {
+          "description": "Must be explicitly set to `\"hook_to_poll\"`.",
+          "type": "string",
+          "enum": ["hook_to_poll"],
+          "required": {
+            "type": "replace",
+            "value": "**yes** (with exceptions, see description)"
+          }
+        },
+        "performList": {
+          "description": "Similar a polling trigger, but checks for new data when a webhook is received, instead of every few minutes",
+          "oneOf": [
+            {
+              "$ref": "/RequestSchema"
+            },
+            {
+              "$ref": "/FunctionSchema"
+            }
+          ]
+        },
+        "canPaginate": {
+          "description": "Does this endpoint support pagination via temporary cursor storage?",
+          "type": "boolean"
+        },
+        "performSubscribe": {
+          "description": "Takes a URL and any necessary data from the user and subscribes. ",
+          "oneOf": [
+            {
+              "$ref": "/RequestSchema"
+            },
+            {
+              "$ref": "/FunctionSchema"
+            }
+          ]
+        },
+        "performUnsubscribe": {
+          "description": "Takes a URL and data from a previous subscribe call and unsubscribes. ",
+          "oneOf": [
+            {
+              "$ref": "/RequestSchema"
+            },
+            {
+              "$ref": "/FunctionSchema"
+            }
+          ]
+        },
+        "inputFields": {
+          "description": "What should the form a user sees and configures look like?",
+          "$ref": "/DynamicFieldsSchema"
+        },
+        "outputFields": {
+          "description": "What fields of data will this return? Will use resource outputFields if missing, will also use sample if available.",
+          "$ref": "/DynamicFieldsSchema"
+        },
+        "sample": {
+          "description": "What does a sample of data look like? Will use resource sample if missing. Requirement waived if `display.hidden` is true or if this belongs to a resource that has a top-level sample",
+          "type": "object",
+          "minProperties": 1,
+          "docAnnotation": {
+            "required": {
+              "type": "replace",
+              "value": "**yes** (with exceptions, see description)"
+            }
+          }
+        }
+      },
+      "additionalProperties": false,
+      "docAnnotation": {
+        "hide": true
+      }
+    },
     "TriggerSchema": {
       "id": "/TriggerSchema",
       "description": "How will Zapier get notified of new objects?",
@@ -1087,6 +1169,9 @@
             },
             {
               "$ref": "/BasicHookOperationSchema"
+            },
+            {
+              "$ref": "/BasicHookToPollOperationSchema"
             }
           ]
         }

package/lib/functional-constraints/uniqueInputFieldKeys.js

@@ -15,6 +15,11 @@ const uniqueInputFieldKeys = (definition) => {
       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(

package/lib/schemas/BasicHookOperationSchema.js

@@ -51,6 +51,11 @@ BasicHookOperationSchema.properties = {
       },
     },
   },
+  canPaginate: {
+    description:
+      'Does this endpoint support pagination via temporary cursor storage?',
+    type: 'boolean',
+  },
   performSubscribe: {
     description:
       'Takes a URL and any necessary data from the user and subscribes. ' +

package/lib/schemas/BasicHookToPollOperationSchema.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+const { SKIP_KEY } = require('../constants');
+
+const BasicOperationSchema = require('./BasicOperationSchema');
+const FunctionSchema = require('./FunctionSchema');
+const RequestSchema = require('./RequestSchema');
+
+// TODO: would be nice to deep merge these instead
+// or maybe use allOf which is built into json-schema
+const BasicHookToPollOperationSchema = JSON.parse(
+  JSON.stringify(BasicOperationSchema.schema)
+);
+
+BasicHookToPollOperationSchema.id = '/BasicHookToPollOperationSchema';
+
+BasicHookToPollOperationSchema.description =
+  'Represents the inbound mechanics of hook to poll style triggers. Defers to list for fields.';
+
+BasicHookToPollOperationSchema.docAnnotation = {
+  hide: true,
+};
+
+BasicHookToPollOperationSchema.required = [
+  'performList',
+  'performSubscribe',
+  'performUnsubscribe',
+];
+
+BasicHookToPollOperationSchema.properties = {
+  type: {
+    description: 'Must be explicitly set to `"hook_to_poll"`.',
+    type: 'string',
+    enum: ['hook_to_poll'],
+    required: {
+      type: 'replace',
+      value: '**yes** (with exceptions, see description)',
+    },
+  },
+  performList: {
+    description:
+      'Similar a polling trigger, but checks for new data when a webhook is received, instead of every few minutes',
+    oneOf: [{ $ref: RequestSchema.id }, { $ref: FunctionSchema.id }],
+  },
+  canPaginate: {
+    description:
+      'Does this endpoint support pagination via temporary cursor storage?',
+    type: 'boolean',
+  },
+  performSubscribe: {
+    description:
+      'Takes a URL and any necessary data from the user and subscribes. ',
+    oneOf: [{ $ref: RequestSchema.id }, { $ref: FunctionSchema.id }],
+  },
+  performUnsubscribe: {
+    description:
+      'Takes a URL and data from a previous subscribe call and unsubscribes. ',
+    oneOf: [{ $ref: RequestSchema.id }, { $ref: FunctionSchema.id }],
+  },
+  inputFields: BasicHookToPollOperationSchema.properties.inputFields,
+  outputFields: BasicHookToPollOperationSchema.properties.outputFields,
+  sample: BasicHookToPollOperationSchema.properties.sample,
+};
+
+BasicHookToPollOperationSchema.examples = [
+  {
+    type: 'hook_to_poll',
+    performList: { require: 'some/path/to/file2.js' },
+    performSubscribe: { require: 'some/path/to/file3.js' },
+    performUnsubscribe: { require: 'some/path/to/file4.js' },
+    sample: { id: 42, name: 'Hooli' },
+  },
+];
+
+BasicHookToPollOperationSchema.antiExamples = [
+  {
+    [SKIP_KEY]: true, // Cannot validate that sample is only required if display isn't true
+    example: {
+      type: 'hook_to_poll',
+      performList: { require: 'some/path/to/file2.js' },
+      performSubscribe: { require: 'some/path/to/file3.js' },
+      performUnsubscribe: { require: 'some/path/to/file4.js' },
+    },
+    reason:
+      'Missing required key: sample. Note - This is only invalid if `display` is not explicitly set to true',
+  },
+];
+
+module.exports = makeSchema(
+  BasicHookToPollOperationSchema,
+  BasicOperationSchema.dependencies
+);

package/lib/schemas/BasicPollingOperationSchema.js

@@ -26,7 +26,8 @@ BasicPollingOperationSchema.properties = {
   resource: BasicPollingOperationSchema.properties.resource,
   perform: BasicPollingOperationSchema.properties.perform,
   canPaginate: {
-    description: 'Does this endpoint support a page offset?',
+    description:
+      'Does this endpoint support pagination via temporary cursor storage?',
     type: 'boolean',
   },
   inputFields: BasicPollingOperationSchema.properties.inputFields,

package/lib/schemas/FieldSchema.js

@@ -14,9 +14,8 @@ const { INCOMPATIBLE_FIELD_SCHEMA_KEYS } = require('../constants');
 // ... etc
 const wrapInBackticks = (s) => `\`${s}\``;
 const formatBullet = (f) => `* ${f.map(wrapInBackticks).join(' & ')}`;
-const incompatibleFieldsList = INCOMPATIBLE_FIELD_SCHEMA_KEYS.map(
-  formatBullet
-).join('\n');
+const incompatibleFieldsList =
+  INCOMPATIBLE_FIELD_SCHEMA_KEYS.map(formatBullet).join('\n');
 
 module.exports = makeSchema(
   {
@@ -45,7 +44,8 @@ module.exports = makeSchema(
         maxLength: 1000,
       },
       type: {
-        description: 'The type of this value.',
+        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.',
         type: 'string',
         // string == unicode
         // text == a long textarea string
@@ -61,6 +61,7 @@ module.exports = makeSchema(
           'file',
           'password',
           'copy',
+          'code',
         ],
       },
       required: {

package/lib/schemas/RefResourceSchema.js

@@ -7,18 +7,29 @@ module.exports = makeSchema({
   description:
     'Reference a resource by key and the data it returns. In the format of: `{resource_key}.{foreign_key}(.{human_label_key})`.',
   type: 'string',
+  // the human_label_key should match the broad `string` type that FieldSchema.key can be, with commas!
   pattern:
-    '^[a-zA-Z0-9_]+\\.[a-zA-Z0-9_]+(\\.[a-zA-Z0-9_]+(,[a-zA-Z0-9_]+)*)?$',
+    '^[a-zA-Z0-9_]+\\.[a-zA-Z0-9_\\s\\[\\]]+(\\.[a-zA-Z0-9_\\s\\[\\]]+(,[a-zA-Z0-9_\\s\\[\\]]+)*)?$',
   examples: [
     'contact.id',
     'contact.id.name',
     'contact.id.firstName,lastName',
     'contact.id.first_name,last_name,email',
+    'contact.Contact Id.Full Name',
+    'contact.data[]id.data[]First Name,data[]Last Name',
   ],
   antiExamples: [
+    {
+      example: 'Contact List',
+      reason: 'Does not match resource_key pattern',
+    },
+    {
+      example: 'Contact.list,find.id',
+      reason: 'Does not match foreign_key pattern',
+    },
     {
       example: 'Contact.list.id.full_name',
-      reason: 'Does not match pattern',
+      reason: 'Does not match human_label_key pattern',
     },
   ],
 });

package/lib/schemas/TriggerSchema.js

@@ -4,6 +4,7 @@ const makeSchema = require('../utils/makeSchema');
 
 const BasicDisplaySchema = require('./BasicDisplaySchema');
 const BasicHookOperationSchema = require('./BasicHookOperationSchema');
+const BasicHookToPollOperationSchema = require('./BasicHookToPollOperationSchema');
 const BasicPollingOperationSchema = require('./BasicPollingOperationSchema');
 const KeySchema = require('./KeySchema');
 
@@ -34,6 +35,7 @@ module.exports = makeSchema(
         anyOf: [
           { $ref: BasicPollingOperationSchema.id },
           { $ref: BasicHookOperationSchema.id },
+          { $ref: BasicHookToPollOperationSchema.id },
         ],
       },
     },
@@ -89,5 +91,6 @@ module.exports = makeSchema(
     BasicDisplaySchema,
     BasicPollingOperationSchema,
     BasicHookOperationSchema,
+    BasicHookToPollOperationSchema,
   ]
 );

package/lib/utils/buildDocs.js

@@ -11,6 +11,7 @@ const links = require('./links');
 const NO_DESCRIPTION = '_No description given._';
 const COMBOS = ['anyOf', 'allOf', 'oneOf'];
 const { SKIP_KEY } = require('../constants');
+const hiddenRefs = [];
 
 const walkSchemas = (InitSchema, callback) => {
   const recurse = (Schema, parents) => {
@@ -27,7 +28,11 @@ const walkSchemas = (InitSchema, callback) => {
 const collectSchemas = (InitSchema) => {
   const schemas = {};
   walkSchemas(InitSchema, (Schema) => {
-    schemas[Schema.id] = Schema;
+    if (!_.get(Schema, 'schema.docAnnotation.hide')) {
+      schemas[Schema.id] = Schema;
+    } else {
+      hiddenRefs.push(Schema.id);
+    }
   });
   return schemas;
 };
@@ -64,12 +69,18 @@ const typeOrLink = (schema) => {
     return `${quoteOrNa(schema.type)}[${typeOrLink(schema.items)}]`;
   }
   if (schema.$ref) {
-    return `[${schema.$ref}](${links.anchor(schema.$ref)})`;
+    if (!hiddenRefs.includes(schema.$ref)) {
+      return `[${schema.$ref}](${links.anchor(schema.$ref)})`;
+    }
+    return;
   }
   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(', ')})`;
+      return `${key}(${schema[key]
+        .map(typeOrLink)
+        .filter(Boolean)
+        .join(', ')})`;
     }
   }
   if (schema.enum && schema.enum.length) {

package/package.json

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