zapier-platform-schema 15.14.0 → 15.14.2

package/exported-schema.json

@@ -1,5 +1,5 @@
 {
-  "version": "15.14.0",
+  "version": "15.14.2",
   "schemas": {
     "AppSchema": {
       "id": "/AppSchema",
@@ -1360,18 +1360,35 @@
       },
       "additionalProperties": false
     },
+    "BufferConfigSchema": {
+      "id": "/BufferConfigSchema",
+      "description": "Currently an **internal-only** feature. Zapier uses this configuration for creating objects in bulk.",
+      "type": "object",
+      "required": ["groupedBy", "limit"],
+      "properties": {
+        "groupedBy": {
+          "description": "The list of keys of input fields to group bulk-create with. The actual user data provided for the fields will be used during execution. Note that a required input field should be referenced to get user data always.",
+          "type": "array",
+          "minItems": 1
+        },
+        "limit": {
+          "description": "The maximum number of items to call `performBuffer` with. **Note** that it is capped by the platform to prevent exceeding the [AWS Lambda's request/response payload size quota of 6 MB](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html#function-configuration-deployment-and-execution). Also, the execution is time-bound; we recommend reducing it upon consistent timeout.",
+          "type": "integer"
+        }
+      },
+      "additionalProperties": false
+    },
     "BasicCreateActionOperationSchema": {
       "id": "/BasicCreateActionOperationSchema",
       "description": "Represents the fundamental mechanics of a create.",
       "type": "object",
-      "required": ["perform"],
       "properties": {
         "resource": {
           "description": "Optionally reference and extends a resource. Allows Zapier to automatically tie together samples, lists and hooks, greatly improving the UX. EG: if you had another trigger reusing a resource but filtering the results.",
           "$ref": "/KeySchema"
         },
         "perform": {
-          "description": "How will Zapier get the data? This can be a function like `(z) => [{id: 123}]` or a request like `{url: 'http...'}`.",
+          "description": "How will Zapier get the data? This can be a function like `(z) => [{id: 123}]` or a request like `{url: 'http...'}`. Exactly one of `perform` or `performBuffer` must be defined. If you choose to define `buffer` and `performBuffer`, you must omit `perform`.",
           "oneOf": [
             {
               "$ref": "/RequestSchema"
@@ -1379,7 +1396,13 @@
             {
               "$ref": "/FunctionSchema"
             }
-          ]
+          ],
+          "docAnnotation": {
+            "required": {
+              "type": "replace",
+              "value": "no (with exceptions, see description)"
+            }
+          }
         },
         "performResume": {
           "description": "A function that parses data from a perform (which uses z.generateCallbackUrl()) and callback request to resume this action.",
@@ -1426,6 +1449,26 @@
         "shouldLock": {
           "description": "Should this action be performed one at a time (avoid concurrency)?",
           "type": "boolean"
+        },
+        "buffer": {
+          "description": "Currently an **internal-only** feature. Zapier uses this configuration for creating objects in bulk with `performBuffer`.",
+          "$ref": "/BufferConfigSchema",
+          "docAnnotation": {
+            "required": {
+              "type": "replace",
+              "value": "no (with exceptions, see description)"
+            }
+          }
+        },
+        "performBuffer": {
+          "description": "Currently an **internal-only** feature. A function to create objects in bulk with. `buffer` and `performBuffer` must either both be defined or neither. Additionally, only one of `perform` or `performBuffer` can be defined. If you choose to define `perform`, you must omit `buffer` and `performBuffer`.",
+          "$ref": "/FunctionSchema",
+          "docAnnotation": {
+            "required": {
+              "type": "replace",
+              "value": "no (with exceptions, see description)"
+            }
+          }
         }
       },
       "additionalProperties": false

package/lib/functional-constraints/bufferedCreateConstraints.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const _ = require('lodash');
+const jsonschema = require('jsonschema');
+
+const bufferedCreateConstraints = (definition) => {
+  const errors = [];
+  const actionType = 'creates';
+
+  if (definition[actionType]) {
+    _.each(definition[actionType], (actionDef) => {
+      if (actionDef.operation && actionDef.operation.buffer) {
+        if (!actionDef.operation.performBuffer) {
+          errors.push(
+            new jsonschema.ValidationError(
+              'must contain property "performBuffer" because property "buffer" is present.',
+              actionDef.operation,
+              '/BasicCreateActionOperationSchema',
+              `instance.${actionType}.${actionDef.key}.operation`,
+              'missing',
+              'performBuffer'
+            )
+          );
+        }
+
+        if (actionDef.operation.perform) {
+          errors.push(
+            new jsonschema.ValidationError(
+              'must not contain property "perform" because it is mutually exclusive with property "buffer".',
+              actionDef.operation,
+              '/BasicCreateActionOperationSchema',
+              `instance.${actionType}.${actionDef.key}.operation`,
+              'invalid',
+              'perform'
+            )
+          );
+        }
+
+        if (actionDef.operation.buffer.groupedBy) {
+          const requiredInputFields = [];
+          const inputFields = _.get(
+            actionDef,
+            ['operation', 'inputFields'],
+            []
+          );
+          inputFields.forEach((inputField) => {
+            if (inputField.required) {
+              requiredInputFields.push(inputField.key);
+            }
+          });
+
+          actionDef.operation.buffer.groupedBy.forEach((field, index) => {
+            if (!requiredInputFields.includes(field)) {
+              errors.push(
+                new jsonschema.ValidationError(
+                  `cannot use optional or non-existent inputField "${field}".`,
+                  actionDef.operation.buffer,
+                  '/BufferConfigSchema',
+                  `instance.${actionType}.${actionDef.key}.operation.buffer.groupedBy[${index}]`,
+                  'invalid',
+                  'groupedBy'
+                )
+              );
+            }
+          });
+        }
+      }
+
+      if (actionDef.operation && actionDef.operation.performBuffer) {
+        if (!actionDef.operation.buffer) {
+          errors.push(
+            new jsonschema.ValidationError(
+              'must contain property "buffer" because property "performBuffer" is present.',
+              actionDef.operation,
+              '/BasicCreateActionOperationSchema',
+              `instance.${actionType}.${actionDef.key}.operation`,
+              'missing',
+              'buffer'
+            )
+          );
+        }
+
+        if (actionDef.operation.perform) {
+          errors.push(
+            new jsonschema.ValidationError(
+              'must not contain property "perform" because it is mutually exclusive with property "performBuffer".',
+              actionDef.operation,
+              '/BasicCreateActionOperationSchema',
+              `instance.${actionType}.${actionDef.key}.operation`,
+              'invalid',
+              'perform'
+            )
+          );
+        }
+      }
+    });
+  }
+
+  return errors;
+};
+
+module.exports = bufferedCreateConstraints;

package/lib/functional-constraints/index.js

@@ -18,6 +18,8 @@ const checks = [
   require('./matchingKeys'),
   require('./labelWhenVisible'),
   require('./uniqueInputFieldKeys'),
+  require('./bufferedCreateConstraints'),
+  require('./requirePerformConditionally'),
   require('./pollingThrottle'),
 ];
 

package/lib/functional-constraints/requirePerformConditionally.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const _ = require('lodash');
+const jsonschema = require('jsonschema');
+
+const requirePerformConditionally = (definition) => {
+  const errors = [];
+  const actionType = 'creates';
+
+  if (definition[actionType]) {
+    _.each(definition[actionType], (actionDef) => {
+      if (
+        actionDef.operation &&
+        !actionDef.operation.buffer &&
+        !actionDef.operation.performBuffer &&
+        !actionDef.operation.perform
+      ) {
+        errors.push(
+          new jsonschema.ValidationError(
+            'requires property "perform".',
+            actionDef.operation,
+            '/BasicCreateActionOperationSchema',
+            `instance.${actionType}.${actionDef.key}.operation`,
+            'required',
+            'perform'
+          )
+        );
+      }
+    });
+  }
+
+  return errors;
+};
+
+module.exports = requirePerformConditionally;

package/lib/schemas/BasicCreateActionOperationSchema.js

@@ -3,6 +3,9 @@
 const makeSchema = require('../utils/makeSchema');
 
 const BasicActionOperationSchema = require('./BasicActionOperationSchema');
+const BufferConfigSchema = require('./BufferConfigSchema');
+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
@@ -20,7 +23,45 @@ BasicCreateActionOperationSchema.properties.shouldLock = {
   type: 'boolean',
 };
 
+BasicCreateActionOperationSchema.properties.perform = {
+  description:
+    "How will Zapier get the data? This can be a function like `(z) => [{id: 123}]` or a request like `{url: 'http...'}`. Exactly one of `perform` or `performBuffer` must be defined. If you choose to define `buffer` and `performBuffer`, you must omit `perform`.",
+  oneOf: [{ $ref: RequestSchema.id }, { $ref: FunctionSchema.id }],
+  docAnnotation: {
+    required: {
+      type: 'replace', // replace or append
+      value: 'no (with exceptions, see description)',
+    },
+  },
+};
+
+BasicCreateActionOperationSchema.properties.buffer = {
+  description:
+    'Currently an **internal-only** feature. Zapier uses this configuration for creating objects in bulk with `performBuffer`.',
+  $ref: BufferConfigSchema.id,
+  docAnnotation: {
+    required: {
+      type: 'replace', // replace or append
+      value: 'no (with exceptions, see description)',
+    },
+  },
+};
+
+BasicCreateActionOperationSchema.properties.performBuffer = {
+  description:
+    'Currently an **internal-only** feature. A function to create objects in bulk with. `buffer` and `performBuffer` must either both be defined or neither. Additionally, only one of `perform` or `performBuffer` can be defined. If you choose to define `perform`, you must omit `buffer` and `performBuffer`.',
+  $ref: FunctionSchema.id,
+  docAnnotation: {
+    required: {
+      type: 'replace', // replace or append
+      value: 'no (with exceptions, see description)',
+    },
+  },
+};
+
+delete BasicCreateActionOperationSchema.required;
+
 module.exports = makeSchema(
   BasicCreateActionOperationSchema,
-  BasicActionOperationSchema.dependencies
+  BasicActionOperationSchema.dependencies.concat(BufferConfigSchema)
 );

package/lib/schemas/BufferConfigSchema.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const makeSchema = require('../utils/makeSchema');
+
+module.exports = makeSchema({
+  id: '/BufferConfigSchema',
+  description:
+    'Currently an **internal-only** feature. Zapier uses this configuration for creating objects in bulk.',
+  type: 'object',
+  required: ['groupedBy', 'limit'],
+  properties: {
+    groupedBy: {
+      description:
+        'The list of keys of input fields to group bulk-create with. The actual user data provided for the fields will be used during execution. Note that a required input field should be referenced to get user data always.',
+      type: 'array',
+      minItems: 1,
+    },
+    limit: {
+      description:
+        "The maximum number of items to call `performBuffer` with. **Note** that it is capped by the platform to prevent exceeding the [AWS Lambda's request/response payload size quota of 6 MB](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html#function-configuration-deployment-and-execution). Also, the execution is time-bound; we recommend reducing it upon consistent timeout.",
+      type: 'integer',
+    },
+  },
+  examples: [
+    {
+      groupedBy: ['workspace', 'sheet'],
+      limit: 100,
+    },
+  ],
+  antiExamples: [
+    {
+      example: {
+        groupedBy: [],
+        limit: 100,
+      },
+      reason: 'Empty groupedBy list provided: `[]`.',
+    },
+    {
+      example: { groupedBy: ['workspace'] },
+      reason: 'Missing required key: `limit`.',
+    },
+    {
+      example: { limit: 1 },
+      reason: 'Missing required key: `groupedBy`.',
+    },
+  ],
+  additionalProperties: false,
+});

package/package.json

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