diff --git a/packages/core/types/zapier.custom.d.ts b/packages/core/types/zapier.custom.d.ts index 1bb92230b..1d8faa322 100644 --- a/packages/core/types/zapier.custom.d.ts +++ b/packages/core/types/zapier.custom.d.ts @@ -102,6 +102,13 @@ export interface Bundle { timezone: string; }; }; + + /** + * Contains metadata about the input fields, optionally provided + * by the inputField.meta property. Useful for storing extra data + * in dynamically created input fields. + */ + inputFields: { [fieldKey: string]: { [metaKey: string]: string | number | boolean } }; }; rawRequest?: Partial<{ method: HttpMethod; diff --git a/packages/core/types/zapier.generated.d.ts b/packages/core/types/zapier.generated.d.ts index 2bd6c4885..ebdf1fd3c 100644 --- a/packages/core/types/zapier.generated.d.ts +++ b/packages/core/types/zapier.generated.d.ts @@ -187,6 +187,22 @@ export type FieldChoices = | { [k: string]: unknown } | (string | FieldChoiceWithLabel)[]; +/** + * Allows for additional metadata to be stored on the field. + * + * [Docs: FieldMetaSchema](https://github.com/zapier/zapier-platform/blob/main/packages/schema/docs/build/schema.md#FieldMetaSchema) + */ +export interface FieldMeta { + /** + * Only string, integer or boolean values are allowed. + * + * This interface was referenced by `FieldMetaSchema`'s JSON-Schema + * definition + * via the `patternProperty` "[^\s]+". + */ + [k: string]: string | number | boolean; +} + /** * Defines a field an app either needs as input, or gives as output. * In addition to the requirements below, the following keys are @@ -323,6 +339,12 @@ export interface Field { * "https://{{input}}.yourdomain.com"). */ inputFormat?: string; + + /** + * Allows for additional metadata to be stored on the field. + * Supports simple key-values only (no sub-objects or arrays). + */ + meta?: FieldMeta; } /** diff --git a/packages/schema/docs/build/schema.md b/packages/schema/docs/build/schema.md index 691baa56c..297115092 100644 --- a/packages/schema/docs/build/schema.md +++ b/packages/schema/docs/build/schema.md @@ -32,6 +32,7 @@ This is automatically generated by the `npm run docs` command in `zapier-platfor * [/DynamicFieldsSchema](#dynamicfieldsschema) * [/FieldChoiceWithLabelSchema](#fieldchoicewithlabelschema) * [/FieldChoicesSchema](#fieldchoicesschema) +* [/FieldMetaSchema](#fieldmetaschema) * [/FieldOrFunctionSchema](#fieldorfunctionschema) * [/FieldSchema](#fieldschema) * [/FieldsSchema](#fieldsschema) @@ -931,6 +932,33 @@ Yes | Yes | Array of [FieldChoiceWithLabel](#fieldchoicewithlabelschema) ----- +## /FieldMetaSchema + +Allows for additional metadata to be stored on the field. + +#### Details + +* **Type** - `object` +* [**Source Code**](https://github.com/zapier/zapier-platform/blob/zapier-platform-schema@15.18.1/packages/schema/lib/schemas/FieldMetaSchema.js) + +#### Properties + +Key | Required | Type | Description +--- | -------- | ---- | ----------- +`[^\s]+` | no | anyOf(`string`, `integer`, `boolean`) | Only string, integer or boolean values are allowed. + +#### Examples + +* `{ shouldCapitalize: true }` +* `{ shouldCapitalize: true, internalType: 'datetime' }` + +#### Anti-Examples + +* `{ databank: { primaryContact: 'abc' } }` - _No complex values allowed_ +* `{ needsProcessing: null }` - _No null values allowed_ + +----- + ## /FieldOrFunctionSchema Represents an array of fields or functions. @@ -997,6 +1025,7 @@ Key | Required | Type | Description `altersDynamicFields` | no | `boolean` | Does the value of this field affect the definitions of other fields in the set? `steadyState` | no | `boolean` | Prevents triggering on new output until all values for fields with this property remain unchanged for 2 polls. It can be used to, e.g., not trigger on a new contact until the contact has completed typing their name. NOTE that this only applies to the `outputFields` of polling triggers. `inputFormat` | no | `string` | Useful when you expect the input to be part of a longer string. Put "{{input}}" in place of the user's input (IE: "https://{{input}}.yourdomain.com"). +`meta` | no | [/FieldMetaSchema](#fieldmetaschema) | Allows for additional metadata to be stored on the field. Supports simple key-values only (no sub-objects or arrays). #### Examples @@ -1006,6 +1035,13 @@ Key | Required | Type | Description * `{ key: 'abc', choices: [ { label: 'Red', sample: '#f00', value: '#f00' } ] }` * `{ key: 'abc', children: [ { key: 'abc' } ] }` * `{ key: 'abc', type: 'integer', helpText: 'neat' }` +* ``` + { + key: 'abc', + type: 'integer', + meta: { internalType: 'numeric', should_call_api: true, display_order: 1 } + } + ``` #### Anti-Examples diff --git a/packages/schema/exported-schema.json b/packages/schema/exported-schema.json index 8aab038cd..298e708c1 100644 --- a/packages/schema/exported-schema.json +++ b/packages/schema/exported-schema.json @@ -149,6 +149,27 @@ } ] }, + "FieldMetaSchema": { + "id": "/FieldMetaSchema", + "type": "object", + "description": "Allows for additional metadata to be stored on the field.", + "patternProperties": { + "[^\\s]+": { + "description": "Only string, integer or boolean values are allowed.", + "anyOf": [ + { + "type": "string" + }, + { + "type": "integer" + }, + { + "type": "boolean" + } + ] + } + } + }, "FieldSchema": { "id": "/FieldSchema", "description": "Defines a field an app either needs as input, or gives as output. In addition to the requirements below, the following keys are mutually exclusive:\n\n* `children` & `list`\n* `children` & `dict`\n* `children` & `type`\n* `children` & `placeholder`\n* `children` & `helpText`\n* `children` & `default`\n* `dict` & `list`\n* `dynamic` & `dict`\n* `dynamic` & `choices`", @@ -249,6 +270,10 @@ "description": "Useful when you expect the input to be part of a longer string. Put \"{{input}}\" in place of the user's input (IE: \"https://{{input}}.yourdomain.com\").", "type": "string", "pattern": "^.*{{input}}.*$" + }, + "meta": { + "description": "Allows for additional metadata to be stored on the field. Supports simple key-values only (no sub-objects or arrays).", + "$ref": "/FieldMetaSchema" } }, "additionalProperties": false diff --git a/packages/schema/lib/schemas/FieldMetaSchema.js b/packages/schema/lib/schemas/FieldMetaSchema.js new file mode 100644 index 000000000..233382c43 --- /dev/null +++ b/packages/schema/lib/schemas/FieldMetaSchema.js @@ -0,0 +1,29 @@ +'use strict'; + +const makeSchema = require('../utils/makeSchema'); + +module.exports = makeSchema({ + id: '/FieldMetaSchema', + type: 'object', + description: 'Allows for additional metadata to be stored on the field.', + patternProperties: { + '[^\\s]+': { + description: 'Only string, integer or boolean values are allowed.', + anyOf: [{ type: 'string' }, { type: 'integer' }, { type: 'boolean' }], + }, + }, + examples: [ + { shouldCapitalize: true }, + { shouldCapitalize: true, internalType: 'datetime' }, + ], + antiExamples: [ + { + example: { databank: { primaryContact: 'abc' } }, + reason: 'No complex values allowed', + }, + { + example: { needsProcessing: null }, + reason: 'No null values allowed', + }, + ], +}); diff --git a/packages/schema/lib/schemas/FieldSchema.js b/packages/schema/lib/schemas/FieldSchema.js index b3421df8a..ec76f62d3 100644 --- a/packages/schema/lib/schemas/FieldSchema.js +++ b/packages/schema/lib/schemas/FieldSchema.js @@ -6,6 +6,8 @@ const RefResourceSchema = require('./RefResourceSchema'); const FieldChoicesSchema = require('./FieldChoicesSchema'); +const FieldMetaSchema = require('./FieldMetaSchema'); + const { INCOMPATIBLE_FIELD_SCHEMA_KEYS } = require('../constants'); // the following takes an array of string arrays (string[][]) and returns the follwing string: @@ -137,6 +139,11 @@ module.exports = makeSchema( // TODO: Check if it contains one and ONLY ONE '{{input}}' pattern: '^.*{{input}}.*$', }, + meta: { + description: + 'Allows for additional metadata to be stored on the field. Supports simple key-values only (no sub-objects or arrays).', + $ref: FieldMetaSchema.id, + }, }, examples: [ { key: 'abc' }, @@ -148,6 +155,15 @@ module.exports = makeSchema( }, { key: 'abc', children: [{ key: 'abc' }] }, { key: 'abc', type: 'integer', helpText: 'neat' }, + { + key: 'abc', + type: 'integer', + meta: { + internalType: 'numeric', + should_call_api: true, + display_order: 1, + }, + }, ], antiExamples: [ { @@ -190,5 +206,5 @@ module.exports = makeSchema( ], additionalProperties: false, }, - [RefResourceSchema, FieldChoicesSchema] + [RefResourceSchema, FieldChoicesSchema, FieldMetaSchema] ); diff --git a/packages/schema/test/index.js b/packages/schema/test/index.js index dbd469ba9..9e09f9bab 100644 --- a/packages/schema/test/index.js +++ b/packages/schema/test/index.js @@ -9,7 +9,7 @@ const appDefinition = require('../examples/definition.json'); const copy = (o) => JSON.parse(JSON.stringify(o)); -const NUM_SCHEMAS = 56; // changes regularly as we expand +const NUM_SCHEMAS = 57; // changes regularly as we expand describe('app', () => { describe('validation', () => {