zapier-platform-core 18.2.3 → 18.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zapier-platform-core",
-  "version": "18.2.3",
+  "version": "18.4.0",
   "description": "The core SDK for CLI apps in the Zapier Developer Platform.",
   "repository": "zapier/zapier-platform",
   "homepage": "https://platform.zapier.com/",
@@ -35,13 +35,14 @@
     "dotenv": "17.2.1",
     "fernet": "^0.3.3",
     "form-data": "4.0.5",
+    "json-schema-to-ts": "3.1.1",
     "lodash": "4.17.23",
     "mime-types": "3.0.1",
     "node-abort-controller": "3.1.1",
     "node-fetch": "2.7.0",
     "oauth-sign": "0.9.0",
     "semver": "7.7.2",
-    "zapier-platform-schema": "18.2.3"
+    "zapier-platform-schema": "18.4.0"
   },
   "devDependencies": {
     "@types/node-fetch": "^2.6.11",

package/types/inputs.d.ts

@@ -3,6 +3,7 @@ import type {
   PlainInputField,
 } from './schemas.generated';
 import type { ZObject, Bundle } from './custom';
+import type { FromSchema, JSONSchema } from 'json-schema-to-ts';
 
 // #region UTILITIES
 
@@ -103,6 +104,26 @@ type Merge<T extends object[]> = T extends [infer F, ...infer R]
 // MAIN BITS
 // =========
 
+/**
+ * Any value that is valid in JSON, including primitives. Used for
+ * nested values inside a json field's object or array.
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * The root-level type of a `json` input field. Per the platform's
+ * functional constraint, a json field's root schema.type must be
+ * "object" or "array" — bare primitives are not allowed at the top
+ * level. Nested values inside can be any JsonValue.
+ */
+export type JsonFieldValue = JsonValue[] | { [key: string]: JsonValue };
+
 type InputDataConstraint = Record<string, unknown>;
 type InputDataDefault = Record<string, undefined>;
 
@@ -130,7 +151,9 @@ type FieldResultTypes = {
       ? number
       : $FieldType extends 'boolean'
         ? boolean
-        : never; // Ignore `copy` and any other non-value types
+        : $FieldType extends 'json'
+          ? JsonFieldValue
+          : never; // Ignore `copy` and any other non-value types
 };
 
 /**
@@ -156,7 +179,11 @@ type PrimitiveFieldResultType<$Field extends PlainInputField> = $Field extends {
   type: infer $T extends PlainInputField['type'];
 }
   ? $T extends string
-    ? FieldResultTypes[$T]
+    ? $T extends 'json'
+      ? $Field extends { schema: infer $S extends JSONSchema }
+        ? FromSchema<$S>
+        : JsonFieldValue
+      : FieldResultTypes[$T]
     : string
   : string;
 

package/types/inputs.plainfields.test-d.ts

@@ -1,6 +1,6 @@
 import { expectAssignable, expectType } from 'tsd';
 
-import type { PlainFieldContribution } from './inputs';
+import type { PlainFieldContribution, JsonFieldValue } from './inputs';
 
 //
 // Parent fields (where `children` is set)
@@ -636,3 +636,139 @@ expectAssignable<optionalStringArrayChoicesAutoCompleteUnions>({
   optional_string_array_choices_auto_complete_unions: 'alpha',
 });
 expectAssignable<optionalStringArrayChoicesAutoCompleteUnions>({});
+
+//
+// JSON fields (where `type: 'json'` is set)
+//
+
+// Required json primitive field.
+type primitiveRequiredJsonResult = PlainFieldContribution<{
+  key: 'primitive_required_json';
+  type: 'json';
+  required: true;
+}>;
+expectType<primitiveRequiredJsonResult>(
+  {} as { primitive_required_json: JsonFieldValue },
+);
+expectAssignable<primitiveRequiredJsonResult>({
+  primitive_required_json: { name: 'test' },
+});
+expectAssignable<primitiveRequiredJsonResult>({
+  primitive_required_json: ['a', 'b'],
+});
+
+// Optional json primitive field.
+type primitiveOptionalJsonResult = PlainFieldContribution<{
+  key: 'primitive_optional_json';
+  type: 'json';
+}>;
+expectAssignable<primitiveOptionalJsonResult>({
+  primitive_optional_json: { nested: { deep: true } },
+});
+expectAssignable<primitiveOptionalJsonResult>({
+  primitive_optional_json: [1, 2, 3],
+});
+expectAssignable<primitiveOptionalJsonResult>({
+  primitive_optional_json: undefined,
+});
+expectAssignable<primitiveOptionalJsonResult>({});
+
+// Required json list field.
+type jsonListRequiredResult = PlainFieldContribution<{
+  key: 'list_required_json';
+  type: 'json';
+  required: true;
+  list: true;
+}>;
+expectType<jsonListRequiredResult>(
+  {} as { list_required_json: JsonFieldValue[] },
+);
+expectAssignable<jsonListRequiredResult>({
+  list_required_json: [{ a: 1 }, { b: 2 }],
+});
+
+// Json field with schema — infers specific type from schema.
+type jsonWithSchemaResult = PlainFieldContribution<{
+  key: 'payload';
+  type: 'json';
+  required: true;
+  schema: {
+    type: 'object';
+    properties: {
+      name: { type: 'string' };
+      age: { type: 'number' };
+    };
+    required: ['name'];
+    additionalProperties: false;
+  };
+}>;
+expectType<jsonWithSchemaResult>(
+  {} as { payload: { name: string; age?: number } },
+);
+
+// Json field with schema, optional.
+type jsonWithSchemaOptionalResult = PlainFieldContribution<{
+  key: 'data';
+  type: 'json';
+  schema: {
+    type: 'object';
+    properties: {
+      items: { type: 'array'; items: { type: 'string' } };
+    };
+  };
+}>;
+expectAssignable<jsonWithSchemaOptionalResult>({
+  data: { items: ['a', 'b'] },
+});
+expectAssignable<jsonWithSchemaOptionalResult>({});
+
+// Json field with schema + list.
+type jsonWithSchemaListResult = PlainFieldContribution<{
+  key: 'payloads';
+  type: 'json';
+  required: true;
+  list: true;
+  schema: {
+    type: 'object';
+    properties: {
+      id: { type: 'number' };
+    };
+    additionalProperties: false;
+  };
+}>;
+expectType<jsonWithSchemaListResult>(
+  {} as { payloads: { id?: number }[] },
+);
+
+// Json field WITHOUT schema still falls back to JsonFieldValue.
+type jsonNoSchemaResult = PlainFieldContribution<{
+  key: 'raw';
+  type: 'json';
+  required: true;
+}>;
+expectType<jsonNoSchemaResult>(
+  {} as { raw: JsonFieldValue },
+);
+
+// Json field as a child of a parent field.
+type jsonChildResult = PlainFieldContribution<{
+  key: 'parent_with_json';
+  children: [
+    { key: 'json_child'; type: 'json'; required: true },
+    { key: 'string_child'; type: 'string'; required: true },
+  ];
+}>;
+expectAssignable<jsonChildResult>({
+  json_child: { key: 'value' },
+  string_child: 'hello',
+});
+expectType<jsonChildResult>(
+  {} as {
+    json_child: JsonFieldValue;
+    string_child: string;
+    parent_with_json?: {
+      json_child: JsonFieldValue;
+      string_child: string;
+    }[];
+  },
+);

package/types/inputs.test-d.ts

@@ -9,6 +9,7 @@
 import type {
   InferInputData,
   InputFieldFunctionWithInputs,
+  JsonFieldValue,
   StringHints,
 } from './inputs';
 import { defineInputFields } from '.';
@@ -58,6 +59,7 @@ const typeComboInputs = defineInputFields([
   { key: 'boolean_type', type: 'boolean', required: true },
   { key: 'datetime_type', type: 'datetime', required: true },
   { key: 'file_type', type: 'file', required: true },
+  { key: 'json_type', type: 'json', required: true },
 ]);
 const typeComboResult: InferInputData<typeof typeComboInputs> = {
   string_type: 'a',
@@ -69,6 +71,7 @@ const typeComboResult: InferInputData<typeof typeComboInputs> = {
   boolean_type: true,
   datetime_type: 'datetime',
   file_type: 'file',
+  json_type: { key: 'value' },
 };
 expectType<{
   string_type: string;
@@ -80,8 +83,37 @@ expectType<{
   boolean_type: boolean;
   datetime_type: string;
   file_type: string;
+  json_type: JsonFieldValue;
 }>(typeComboResult);
 
+//
+// Test json field with schema infers specific type via InferInputData.
+const jsonSchemaInputs = defineInputFields([
+  {
+    key: 'typed_json',
+    type: 'json',
+    required: true,
+    schema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        count: { type: 'number' },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+  },
+  { key: 'plain_json', type: 'json', required: true },
+]);
+const jsonSchemaResult: InferInputData<typeof jsonSchemaInputs> = {
+  typed_json: { name: 'hello' },
+  plain_json: { key: 'value' },
+};
+expectType<{
+  typed_json: { name: string; count?: number };
+  plain_json: JsonFieldValue;
+}>(jsonSchemaResult);
+
 //
 // Test that copy fields are never appear in the bundle.
 const copyComboInputs = defineInputFields([

package/types/schemas.generated.d.ts

@@ -4,7 +4,7 @@
  * files, and/or the schema-to-ts tool and run its CLI to regenerate
  * these typings.
  *
- * zapier-platform-schema version: 18.2.2
+ * zapier-platform-schema version: 18.4.0
  *  schema-to-ts compiler version: 0.1.0
  */
 import type {
@@ -289,7 +289,11 @@ export interface AppFlags {
    * via middleware), [Shorthand
    * requests](https://github.com/zapier/zapier-platform/blob/main/packages/cli/README.md#shorthand-http-requests)
    * _always_ call `throwForStatus()`. `z.request()` calls can also
-   * ignore this flag if they set `skipThrowForStatus` directly
+   * ignore this flag if they set `skipThrowForStatus` directly. It is
+   * important to note that for oauth2 or session auths with
+   * `authRefresh:true`, `401` status codes will throw a
+   * `RefreshAuthError` regardless of `skipThrowForStatus`, and will
+   * need to be handled manually if intervention is required.
    */
   skipThrowForStatus?: boolean;
 
@@ -1703,7 +1707,8 @@ export interface PlainInputField {
     | 'file'
     | 'password'
     | 'copy'
-    | 'code';
+    | 'code'
+    | 'json';
 
   /** If this value is required or not. */
   required?: boolean;
@@ -1744,10 +1749,25 @@ export interface PlainInputField {
   dynamic?: RefResource;
 
   /**
-   * An object of machine keys and human values to populate a static
-   * dropdown.
+   * Specifies which other input fields this field depends on. These
+   * must be filled before this one becomes enabled, and when their
+   * values change, this field's value should be cleared.
    */
-  choices?: FieldChoices;
+  dependsOn?: string[];
+
+  /**
+   * Explicitly links this input field to a resource. Use the resource
+   * key (e.g., "spreadsheet") or dot notation for resource fields
+   * (e.g., "spreadsheet.url"). If not set for dynamic dropdowns, the
+   * resource is derived implicitly from the `dynamic` property.
+   */
+  resource?: string;
+
+  /**
+   * Describes how to populate this dropdown. Can be a static list or
+   * a dynamic object with pagination and search support.
+   */
+  choices?: FieldChoices | FieldDynamicChoices;
 
   /** An example value that is not saved. */
   placeholder?: string;
@@ -1783,6 +1803,12 @@ export interface PlainInputField {
    * organize this field with others.
    */
   group?: Key;
+
+  /**
+   * A JSON Schema object that describes the expected structure of the
+   * JSON value. Only valid when `type` is `json`.
+   */
+  schema?: JsonSchema;
 }
 
 /** Object for visual grouping of input fields. */
@@ -1803,5 +1829,25 @@ export interface InputFieldGroup {
  */
 export type RefResource = string;
 
+/**
+ * Describes dynamic dropdowns powered by a perform function or
+ * request.
+ */
+export interface FieldDynamicChoices {
+  /**
+   * A function or request that returns choices for this dynamic
+   * dropdown.
+   */
+  perform: Function | Request;
+}
+
 /** Allows for additional metadata to be stored on the field. */
 export type FieldMeta = Record<string, string | number | boolean>;
+
+/**
+ * A JSON Schema object that describes the expected structure of a
+ * JSON value. Validated against JSON Schema Draft 4, 6, or 7
+ * meta-schema (based on the `$schema` field, defaulting to Draft 7)
+ * via the validateJsonFieldSchema functional constraint.
+ */
+export type JsonSchema = Record<string, unknown>;