zapier-platform-core 17.7.1 → 17.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zapier-platform-core",
-  "version": "17.7.1",
+  "version": "17.7.2",
   "description": "The core SDK for CLI apps in the Zapier Developer Platform.",
   "repository": "zapier/zapier-platform",
   "homepage": "https://platform.zapier.com/",
@@ -63,7 +63,7 @@
     "node-fetch": "2.7.0",
     "oauth-sign": "0.9.0",
     "semver": "7.7.1",
-    "zapier-platform-schema": "17.7.1"
+    "zapier-platform-schema": "17.7.2"
   },
   "devDependencies": {
     "@types/node-fetch": "^2.6.11",

package/types/custom.d.ts

@@ -112,6 +112,14 @@ export interface Bundle<
       };
     };
 
+    /**
+     * A token, such as a pagination cursor, that means this run should
+     * continue pulling results. Currently only used for search
+     * pagination. Set by previous invocations by returning `{results:
+     * […], paging_token: '…'}`
+     */
+    paging_token?: string;
+
     /**
      * Contains metadata about the input fields, optionally provided
      * by the inputField.meta property. Useful for storing extra data
@@ -142,7 +150,11 @@ export interface Bundle<
 
 // Error class types that match the runtime structure from src/errors.js
 type ErrorConstructor = new (message?: string) => Error;
-type AppErrorConstructor = new (message: string, code?: string, status?: number) => Error;
+type AppErrorConstructor = new (
+  message: string,
+  code?: string,
+  status?: number,
+) => Error;
 type ThrottledErrorConstructor = new (message: string, delay?: number) => Error;
 type ResponseErrorConstructor = new (response: HttpResponse) => Error;
 
@@ -163,7 +175,6 @@ interface ErrorsModule {
   handleError: (...args: any[]) => never;
 }
 
-
 // copied http stuff from external typings
 export interface HttpRequestOptions {
   agent?: Agent;

package/types/functions.d.ts

@@ -1,7 +1,20 @@
 import type { Bundle, ZObject } from './custom';
+import type { InferInputData, InputField } from './inputs';
 
 type DefaultInputData = Record<string, unknown>;
 
+/**
+ * Automatically infer the type of the bundle based on if a raw
+ * inputData object shape is given, or an array of input fields that
+ * should be automatically inferred into an inputData object.
+ */
+type AutoBundle<$InputDataOrFields extends DefaultInputData | InputField[]> =
+  $InputDataOrFields extends InputField[]
+    ? Bundle<InferInputData<$InputDataOrFields>>
+    : $InputDataOrFields extends DefaultInputData
+      ? Bundle<$InputDataOrFields>
+      : never;
+
 /**
  * Wraps a `perform` function that is used to poll for data from an API.
  * By default must return an array of objects with an `id` field, but
@@ -10,9 +23,12 @@ type DefaultInputData = Record<string, unknown>;
  * those keys.
  */
 export type PollingTriggerPerform<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = { id: string },
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return[] | Promise<$Return[]>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return[] | Promise<$Return[]>;
 
 /**
  * Process the data of a webhook sent to Zapier.
@@ -21,62 +37,83 @@ export type PollingTriggerPerform<
  * in `bundle.cleanedRequest` (and `bundle.rawRequest`).
  */
 export type WebhookTriggerPerform<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return[] | Promise<$Return[]>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return[] | Promise<$Return[]>;
 
 /**
  * Pull sample data from the webhook trigger. Try to make these resemble
  * to data of the hooks as closely as possible.
  */
 export type WebhookTriggerPerformList<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return[] | Promise<$Return[]>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return[] | Promise<$Return[]>;
 
 /**
  * Return must be an object of subscription data. It will be passed as
  * `bundle.subscribeData` in the performUnsubscribe function.
  */
 export type WebhookTriggerPerformSubscribe<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return | Promise<$Return>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return | Promise<$Return>;
 
 /**
  * Unsubscribe from the webhook.
  * Data from the subscribe function is provided in `bundle.subscribeData`.
  */
 export type WebhookTriggerPerformUnsubscribe<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return | Promise<$Return>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return | Promise<$Return>;
 
 /**
  * Pull data from the API service, same as a polling trigger.
  */
 export type HookToPollTriggerPerformList<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return[] | Promise<$Return[]>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return[] | Promise<$Return[]>;
 
 /**
  * Return must be an object of subscription data. It will be passed as
  * `bundle.subscribeData` in the performUnsubscribe function.
  */
 export type HookToPollTriggerPerformSubscribe<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return | Promise<$Return>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return | Promise<$Return>;
 
 /**
  * Unsubscribe from the HookToPoll.
  * Data from the subscribe function is provided in `bundle.subscribeData`.
  */
 export type HookToPollTriggerPerformUnsubscribe<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return | Promise<$Return>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return | Promise<$Return>;
 
 /**
  * Create an item on a partner API.
@@ -85,9 +122,12 @@ export type HookToPollTriggerPerformUnsubscribe<
  * to populate more data.
  */
 export type CreatePerform<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return | Promise<$Return>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return | Promise<$Return>;
 
 /**
  * A `perform` function can setup a partner API to call back to this
@@ -104,18 +144,24 @@ export type CreatePerform<
  * - bundle.outputData: The output data from the original `perform`.
  */
 export type CreatePerformResume<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   // TODO: Type cleanedRequest & outputData on Bundle interface
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return | Promise<$Return>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return | Promise<$Return>;
 
 /**
  * Look up an object to populate it after creation?
  */
 export type CreatePerformGet<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return | Promise<$Return>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return | Promise<$Return>;
 
 /**
  * Helper type for search results that can optionally include pagination.
@@ -125,7 +171,7 @@ export type CreatePerformGet<
  *
  * When `canPaginate` is true for the search, the object shape is required.
  */
-type SearchResult<T> = T[] | { results: T[], paging_token: string };
+type SearchResult<T> = T[] | { results: T[]; paging_token: string };
 
 /**
  * Search for objects on a partner API.
@@ -136,9 +182,12 @@ type SearchResult<T> = T[] | { results: T[], paging_token: string };
  * revisit this?
  */
 export type SearchPerform<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => SearchResult<$Return> | Promise<SearchResult<$Return>>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => SearchResult<$Return> | Promise<SearchResult<$Return>>;
 
 /**
  * Follow up a search's perform with additional data.
@@ -148,17 +197,23 @@ export type SearchPerform<
  * -> PROBABLY: Just the result of searchPerform, no inputFields.
  */
 export type SearchPerformGet<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return | Promise<$Return>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return | Promise<$Return>;
 
 /**
  *
  */
 export type SearchPerformResume<
-  $InputData extends DefaultInputData = DefaultInputData,
+  $InputDataOrFields extends DefaultInputData | InputField[] = DefaultInputData,
   $Return extends {} = {},
-> = (z: ZObject, bundle: Bundle<$InputData>) => $Return | Promise<$Return>;
+> = (
+  z: ZObject,
+  bundle: AutoBundle<$InputDataOrFields>,
+) => $Return | Promise<$Return>;
 
 /**
  * Produce the URL to send the user to authorise with the OAuth2 provider.

package/types/functions.test-d.ts

@@ -1,5 +1,8 @@
-import { expectAssignable } from 'tsd';
+import { expectAssignable, expectType } from 'tsd';
 import type { PollingTriggerPerform } from './functions';
+import { Bundle, ZObject } from './custom';
+import { InferInputData } from './inputs';
+import { defineInputFields } from './typeHelpers';
 
 const simplePerform = (async (z, bundle) => {
   return [{ id: '1', name: 'test' }];
@@ -16,3 +19,46 @@ const primaryKeyOverridePerform = (async (z, bundle) => {
 expectAssignable<PollingTriggerPerform<{}, { itemId: number; name: string }>>(
   primaryKeyOverridePerform,
 );
+
+//
+// Automatic inputData inference
+//
+// Pass shape directly
+const simplePerformWithInputFields = (async (z, bundle) => {
+  return [{ id: '1', name: 'test' }];
+}) satisfies PollingTriggerPerform<{ key: 'string' }>;
+expectType<
+  (
+    z: ZObject,
+    bundle: Bundle<{ key: 'string' }>,
+  ) => Promise<{ id: string; name: string }[]>
+>(simplePerformWithInputFields);
+
+// Use InputFields and manually infer inputData
+const inputFields = defineInputFields([
+  { key: 'key1', type: 'string', required: true },
+  { key: 'key2', type: 'number', required: false },
+]);
+const simplePerformWithInputFieldsAndManualInference = (async (z, bundle) => {
+  return [{ id: '1', name: 'test' }];
+}) satisfies PollingTriggerPerform<InferInputData<typeof inputFields>>;
+expectType<
+  (
+    z: ZObject,
+    bundle: Bundle<{ key1: string; key2?: number | undefined }>,
+  ) => Promise<{ id: string; name: string }[]>
+>(simplePerformWithInputFieldsAndManualInference);
+
+// Use inputFields and automatically infer inputData
+const simplePerformWithInputFieldsAndAutomaticInference = (async (
+  z,
+  bundle,
+) => {
+  return [{ id: '1', name: 'test' }];
+}) satisfies PollingTriggerPerform<typeof inputFields>;
+expectType<
+  (
+    z: ZObject,
+    bundle: Bundle<{ key1: string; key2?: number | undefined }>,
+  ) => Promise<{ id: string; name: string }[]>
+>(simplePerformWithInputFieldsAndAutomaticInference);

package/types/inputs.d.ts

@@ -1,4 +1,7 @@
-import type { PlainInputField } from './schemas.generated';
+import type {
+  FieldChoiceWithLabel,
+  PlainInputField,
+} from './schemas.generated';
 import type { ZObject, Bundle } from './custom';
 
 // #region UTILITIES
@@ -132,9 +135,24 @@ type FieldResultTypes = {
 
 /**
  * Get the TypeScript type that corresponds to the zapier field type. If
- * `type` is not set, the field defaults to `string`.
+ * `type` is not set, the field defaults to `string`. Does not pay
+ * attention to `list` `, `dict`, or `required` statuses. Does not work
+ * for fields with `children` subfields either.
+ *
+ * @example
+ * type result = PrimitiveFieldResultType<{ }>;
+ * // string (string is default when `type` is not set)
+ *
+ * type result = PrimitiveFieldResultType<{ type: 'string' }>;
+ * // string
+ *
+ * type result = PrimitiveFieldResultType<{ type: 'number' }>;
+ * // number
+ *
+ * type result = PrimitiveFieldResultType<{ type: 'boolean' }>;
+ * // boolean
  */
-type FieldResultType<F extends PlainInputField> = F extends {
+type PrimitiveFieldResultType<$Field extends PlainInputField> = $Field extends {
   type: infer $T extends PlainInputField['type'];
 }
   ? $T extends string
@@ -142,6 +160,29 @@ type FieldResultType<F extends PlainInputField> = F extends {
     : string
   : string;
 
+/**
+ * Capture a union of string literals while also allowing the string
+ * type. This allows the available choices to show in autocomplete,
+ * while also allowing arbitrary strings to still be valid.
+ *
+ * @example
+ * type result = StringHints<'a' | 'b'>;
+ * const A: result = 'a'; // Ok and autocomplete shows 'a' and 'b'.
+ * const C: result = 'c'; // Any string still ok.
+ */
+export type StringHints<S> = S | (string & {});
+
+type PrimitiveFieldResultTypesWithChoiceHints<$Field extends PlainInputField> =
+  $Field extends { choices: infer $Choices }
+    ? $Choices extends Record<string, string>
+      ? StringHints<keyof $Choices>
+      : $Choices extends FieldChoiceWithLabel[]
+        ? StringHints<$Choices[number]['value']>
+        : $Choices extends string[]
+          ? StringHints<$Choices[number]>
+          : PrimitiveFieldResultType<$Field>
+    : PrimitiveFieldResultType<$Field>;
+
 /**
  * A function that returns a list of plain fields, sync or async.
  * Can be used as a member of an array of input fields itself.
@@ -179,15 +220,93 @@ export type InputFields = InputField[];
  * type result3 = PlainFieldContribution<{ key: "c"; type: "boolean" }>;
  * // { c?: boolean | undefined }
  */
-type PlainFieldContribution<$Field extends PlainInputField> = $Field extends {
-  required: true;
-}
-  ? FieldResultType<$Field> extends never
-    ? {}
-    : Record<$Field['key'], FieldResultType<$Field>>
-  : FieldResultType<$Field> extends never
+export type PlainFieldContribution<$Field extends PlainInputField> =
+  $Field extends { children: PlainInputField[] }
+    ? ParentFieldContribution<$Field>
+    : $Field extends { dict: true }
+      ? DictFieldContribution<$Field>
+      : $Field extends { list: true }
+        ? ListFieldContribution<$Field>
+        : PrimitiveFieldContribution<$Field>;
+
+/**
+ * Extract the contribution of a parent field to the input data. A parent
+ * Field has a `children` field array. The parent's own `key` will be
+ * ignored, and the children's contributions will be merged into the top
+ * level inputData object.
+ *
+ * @example
+ * type result = ParentFieldContribution<{ key: "a"; children: [{ key: "b"; required: true }] }>;
+ * // { b: string }
+ */
+type ParentFieldContribution<
+  $Field extends PlainInputField & { children: PlainInputField[] },
+> = PlainFieldArrayContribution<$Field['children']>;
+
+/**
+ * Extract the contribution of a dictionary field to the input data. A
+ * dictionary field has a `dict:true` field. The type for this `key`
+ * field in the inputData object will therefore be a record of the key.
+ * Currently, the value type is always `string`, but this may change in
+ * the future.
+ *
+ * @see https://zapier.atlassian.net/browse/PDE-6547 for when non-string
+ * values will be supported.
+ *
+ * @example
+ * type result = DictFieldContribution<{ key: "a"; dict: true, required: true }>;
+ * // { a: Record<string, string> }
+ */
+type DictFieldContribution<$Field extends PlainInputField & { dict: true }> =
+  $Field extends { required: true }
+    ? Record<$Field['key'], Record<string, string>>
+    : Partial<Record<$Field['key'], Record<string, string>>>;
+
+/**
+ * Extract the contribution of a list field to the input data. A list
+ * field has a `list:true` field. The type for this `key` field in the
+ * inputData object will therefore be an array of the value type.
+ *
+ * @example
+ * type result1 = ListFieldContribution<{ key: "a"; list: true, required: true }>;
+ * // { a: string[] }
+ *
+ * type result2 = ListFieldContribution<{ key: "a"; list: true; type: "integer" }>;
+ * // { a?: number[] | undefined }
+ */
+type ListFieldContribution<$Field extends PlainInputField & { list: true }> =
+  $Field extends { required: true }
+    ? Record<$Field['key'], PrimitiveFieldResultTypesWithChoiceHints<$Field>[]>
+    : Partial<
+        Record<
+          $Field['key'],
+          PrimitiveFieldResultTypesWithChoiceHints<$Field>[]
+        >
+      >;
+
+/**
+ * Extract the contribution of a primitive field to the input data. A
+ * primitive field is a PlainInputField that is not a parent, dict, or
+ * list field. The `type` field MAY be set, but will default to `string`.
+ *
+ * @example
+ * type result1 = PrimitiveFieldContribution<{ key: "a" }>;
+ * // { a?: string | undefined }
+ *
+ * type result2 = PrimitiveFieldContribution<{ key: "a"; type: "integer", required: true }>;
+ * // { a: number }
+ */
+type PrimitiveFieldContribution<$Field extends PlainInputField> =
+  PrimitiveFieldResultTypesWithChoiceHints<$Field> extends never
     ? {}
-    : Partial<Record<$Field['key'], FieldResultType<$Field>>>;
+    : $Field extends { required: true }
+      ? Record<$Field['key'], PrimitiveFieldResultTypesWithChoiceHints<$Field>>
+      : Partial<
+          Record<
+            $Field['key'],
+            PrimitiveFieldResultTypesWithChoiceHints<$Field>
+          >
+        >;
 
 /**
  * Extract the contribution of multiple plain fields defined in an
@@ -297,6 +416,18 @@ type FieldFunctionContribution<$F> = $F extends (
 // the fields that a plain field or field function will contribute to
 // the bundle, but the more straightforward term "InputData" is
 // exposed to for the public API.
+//
+// TERMINOLOGY
+// -----------
+// InputField: A PlainInputField or a FieldFunction.
+// FieldFunction: A function that returns an array of InputFields.
+// KnownFieldFunction: A FieldFunction that returns explicitly named InputFields.
+// UnknownFieldFunction: A FieldFunction that returns an array of InputFields that are not explicitly named.
+// PlainInputField: From the schema. Object with a key, and possibly `children`, `dict`, `list`, `type`, `required`, fields.
+// ParentInputField: A PlainInputField with a `children` field array.
+// DictInputField: A PlainInputField with a `dict:true` field.
+// ListInputField: A PlainInputField with a `list:true` field.
+// PrimitiveInputField: A PlainInputField with a `type` field that is not a parent, dict, or list field.
 
 /**
  * Get the bundle contribution of a single field. This is either a plain

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

@@ -0,0 +1,484 @@
+import { expectAssignable, expectType } from 'tsd';
+
+import type { PlainFieldContribution } from './inputs';
+
+//
+// Parent fields (where `children` is set)
+//
+
+// Simplest `children: [{...}]` case.
+const singleRequiredChild = {
+  string_required: 'some_string',
+};
+type singleRequiredChildren = PlainFieldContribution<{
+  key: 'parent_input';
+  children: [{ key: 'string_required'; type: 'string'; required: true }];
+}>;
+expectType<singleRequiredChildren>(singleRequiredChild);
+
+// Complete `children: [{...}]` case.
+const multipleRequiredChild = {
+  string_required: 'some_string',
+  number_required: 1,
+  boolean_required: true,
+  datetime_required: '2021-01-01T00:00:00Z',
+  file_required: 'some_file',
+  password_required: 'some_password',
+  code_required: 'some_code',
+};
+type multipleRequiredChildren = PlainFieldContribution<{
+  key: 'parent_input';
+  children: [
+    { key: 'string_required'; type: 'string'; required: true },
+    { key: 'number_required'; type: 'number'; required: true },
+    { key: 'boolean_required'; type: 'boolean'; required: true },
+    { key: 'datetime_required'; type: 'datetime'; required: true },
+    { key: 'file_required'; type: 'file'; required: true },
+    { key: 'password_required'; type: 'password'; required: true },
+    { key: 'code_required'; type: 'code'; required: true },
+  ];
+}>;
+expectType<multipleRequiredChildren>(multipleRequiredChild);
+
+// Complete `children: [{...}]` case where all children are optional.
+const multipleOptionalChild = {
+  string_optional: 'some_string',
+  number_optional: 1,
+  boolean_optional: true,
+  datetime_optional: '2021-01-01T00:00:00Z',
+  file_optional: 'some_file',
+  password_optional: 'some_password',
+  code_optional: 'some_code',
+};
+type multipleOptionalChildren = PlainFieldContribution<{
+  key: 'parent_input';
+  children: [
+    { key: 'string_optional'; type: 'string'; required: false },
+    { key: 'number_optional'; type: 'number'; required: false },
+    { key: 'boolean_optional'; type: 'boolean'; required: false },
+    { key: 'datetime_optional'; type: 'datetime'; required: false },
+    { key: 'file_optional'; type: 'file'; required: false },
+    { key: 'password_optional'; type: 'password'; required: false },
+    { key: 'code_optional'; type: 'code'; required: false },
+  ];
+}>;
+expectAssignable<multipleOptionalChildren>(multipleOptionalChild);
+expectAssignable<multipleOptionalChildren>({});
+
+// Complete `children: [{...}]` case with complete mixture of required
+// and optional fields.
+const mixedOptionalChildren = {
+  string_required: 'some_string',
+  string_optional: 'some_string',
+  number_required: 1,
+  number_optional: 1,
+  boolean_required: true,
+  boolean_optional: true,
+  datetime_required: '2021-01-01T00:00:00Z',
+  datetime_optional: '2021-01-01T00:00:00Z',
+  file_required: 'some_file',
+  file_optional: 'some_file',
+  password_required: 'some_password',
+  password_optional: 'some_password',
+  code_optional: 'some_code',
+};
+type mixedOptionalChildren = PlainFieldContribution<{
+  key: 'parent_input';
+  children: [
+    { key: 'string_required'; type: 'string'; required: true },
+    { key: 'string_optional'; type: 'string'; required: false },
+  ];
+}>;
+expectAssignable<mixedOptionalChildren>(multipleRequiredChild);
+expectAssignable<mixedOptionalChildren>({
+  ...multipleRequiredChild,
+  ...multipleOptionalChild,
+});
+
+//
+// Dictionary fields (where `dict:true` is set)
+//
+// Required dictionary fields.
+const expectedDictRequired = {
+  dict_required: {
+    some_string_1: 'some_string_1',
+  } as Record<string, string>,
+};
+type dictRequiredResult = PlainFieldContribution<{
+  key: 'dict_required';
+  type: 'string';
+  required: true;
+  dict: true;
+}>;
+expectType<dictRequiredResult>(expectedDictRequired);
+
+// Optional dictionary fields.
+type dictOptionalResult = PlainFieldContribution<{
+  key: 'dict_optional';
+  type: 'string';
+  dict: true;
+}>;
+expectAssignable<dictOptionalResult>({
+  dict_optional: { a: 'aaa' },
+});
+expectAssignable<dictOptionalResult>({
+  dict_optional: {} as Record<string, string>,
+});
+expectAssignable<dictOptionalResult>({
+  dict_optional: {},
+});
+expectAssignable<dictOptionalResult>({ dict_optional: undefined });
+expectAssignable<dictOptionalResult>({});
+
+//
+// List fields (where `list:true` is set)
+//
+// Required string list fields.
+const expectedStringListRequired = {
+  list_required_string: ['some_string_1', 'some_string_2'],
+};
+type stringListRequiredResult = PlainFieldContribution<{
+  key: 'list_required_string';
+  type: 'string';
+  required: true;
+  list: true;
+}>;
+expectType<stringListRequiredResult>(expectedStringListRequired);
+
+// Optional string list fields.
+type stringListOptionalResult = PlainFieldContribution<{
+  key: 'list_optional_string';
+  type: 'string';
+  list: true;
+}>;
+expectAssignable<stringListOptionalResult>({
+  list_optional_string: ['some_string_1', 'some_string_2'],
+});
+expectAssignable<stringListOptionalResult>({
+  list_optional_string: [],
+});
+expectAssignable<stringListOptionalResult>({
+  list_optional_string: undefined,
+});
+expectAssignable<stringListOptionalResult>({});
+
+// Optional omitted type (string) list fields.
+type omittedTypeListOptionalResult = PlainFieldContribution<{
+  key: 'list_optional_omitted_type';
+  // No `type` set.
+  list: true;
+}>;
+expectAssignable<omittedTypeListOptionalResult>({
+  list_optional_omitted_type: ['some_string_1', 'some_string_2'],
+});
+expectAssignable<omittedTypeListOptionalResult>({
+  list_optional_omitted_type: [],
+});
+expectAssignable<omittedTypeListOptionalResult>({
+  list_optional_omitted_type: undefined,
+});
+expectAssignable<omittedTypeListOptionalResult>({});
+
+// Required integer list fields.
+const expectedIntegerListRequired = {
+  list_required_integer: [1, 2],
+};
+type integerListRequiredResult = PlainFieldContribution<{
+  key: 'list_required_integer';
+  type: 'integer';
+  required: true;
+  list: true;
+}>;
+expectType<integerListRequiredResult>(expectedIntegerListRequired);
+
+// Optional integer list fields.
+type integerListOptionalResult = PlainFieldContribution<{
+  key: 'list_required';
+  type: 'integer';
+  list: true;
+}>;
+expectAssignable<integerListOptionalResult>({
+  list_required: [1, 2],
+});
+expectAssignable<integerListOptionalResult>({
+  list_required: [],
+});
+expectAssignable<integerListOptionalResult>({
+  list_required: undefined,
+});
+expectAssignable<integerListOptionalResult>({});
+
+//
+// Primitive fields (no parent, dict, or list. Single input field.)
+//
+// Required primitive string field.
+const expectedPrimitiveRequired = {
+  primitive_required_string: 'some_string',
+};
+type primitiveRequiredStringResult = PlainFieldContribution<{
+  key: 'primitive_required_string';
+  type: 'string';
+  required: true;
+}>;
+expectType<primitiveRequiredStringResult>(expectedPrimitiveRequired);
+
+// Optional primitive string field.
+type primitiveOptionalStringResult = PlainFieldContribution<{
+  key: 'primitive_optional_string';
+  type: 'string';
+}>;
+expectAssignable<primitiveOptionalStringResult>({
+  primitive_optional_string: 'some_string',
+});
+expectAssignable<primitiveOptionalStringResult>({
+  primitive_optional_string: undefined,
+});
+expectAssignable<primitiveOptionalStringResult>({});
+
+// Required primitive integer field.
+const expectedPrimitiveRequiredInteger = {
+  primitive_required_integer: 1,
+};
+type primitiveRequiredIntegerResult = PlainFieldContribution<{
+  key: 'primitive_required_integer';
+  type: 'integer';
+  required: true;
+}>;
+expectType<primitiveRequiredIntegerResult>(expectedPrimitiveRequiredInteger);
+
+// Optional primitive integer field.
+type primitiveOptionalIntegerResult = PlainFieldContribution<{
+  key: 'primitive_optional_integer';
+  type: 'integer';
+}>;
+expectAssignable<primitiveOptionalIntegerResult>({
+  primitive_optional_integer: 1,
+});
+expectAssignable<primitiveOptionalIntegerResult>({
+  primitive_optional_integer: undefined,
+});
+expectAssignable<primitiveOptionalIntegerResult>({});
+
+// Required primitive number field.
+const expectedPrimitiveRequiredNumber = {
+  primitive_required_number: 1.1,
+};
+type primitiveRequiredNumberResult = PlainFieldContribution<{
+  key: 'primitive_required_number';
+  type: 'number';
+  required: true;
+}>;
+expectType<primitiveRequiredNumberResult>(expectedPrimitiveRequiredNumber);
+
+// Optional primitive number field.
+type primitiveOptionalNumberResult = PlainFieldContribution<{
+  key: 'primitive_optional_number';
+  type: 'number';
+}>;
+expectAssignable<primitiveOptionalNumberResult>({
+  primitive_optional_number: 1.1,
+});
+expectAssignable<primitiveOptionalNumberResult>({
+  primitive_optional_number: undefined,
+});
+expectAssignable<primitiveOptionalNumberResult>({});
+
+// Required primitive boolean field.
+const expectedPrimitiveRequiredBoolean = {
+  primitive_required_boolean: true,
+};
+type primitiveRequiredBooleanResult = PlainFieldContribution<{
+  key: 'primitive_required_boolean';
+  type: 'boolean';
+  required: true;
+}>;
+expectType<primitiveRequiredBooleanResult>(expectedPrimitiveRequiredBoolean);
+
+// Optional primitive boolean field.
+type primitiveOptionalBooleanResult = PlainFieldContribution<{
+  key: 'primitive_optional_boolean';
+  type: 'boolean';
+}>;
+expectAssignable<primitiveOptionalBooleanResult>({
+  primitive_optional_boolean: true,
+});
+expectAssignable<primitiveOptionalBooleanResult>({
+  primitive_optional_boolean: undefined,
+});
+expectAssignable<primitiveOptionalBooleanResult>({});
+
+// Required primitive datetime field.
+const expectedPrimitiveRequiredDatetime = {
+  primitive_required_datetime: '2021-01-01T00:00:00Z',
+};
+
+type primitiveRequiredDatetimeResult = PlainFieldContribution<{
+  key: 'primitive_required_datetime';
+  type: 'datetime';
+  required: true;
+}>;
+expectType<primitiveRequiredDatetimeResult>(expectedPrimitiveRequiredDatetime);
+
+// Optional primitive datetime field.
+type primitiveOptionalDatetimeResult = PlainFieldContribution<{
+  key: 'primitive_optional_datetime';
+  type: 'datetime';
+}>;
+expectAssignable<primitiveOptionalDatetimeResult>({
+  primitive_optional_datetime: '2021-01-01T00:00:00Z',
+});
+expectAssignable<primitiveOptionalDatetimeResult>({
+  primitive_optional_datetime: undefined,
+});
+expectAssignable<primitiveOptionalDatetimeResult>({});
+
+// Optional primitive copy field.
+type primitiveOptionalCopyResult = PlainFieldContribution<{
+  key: 'primitive_optional_copy';
+  type: 'copy';
+}>;
+expectAssignable<primitiveOptionalCopyResult>({
+  primitive_optional_copy: undefined,
+});
+expectAssignable<primitiveOptionalCopyResult>({});
+
+//
+// Choices auto-complete unions.
+//
+// Required object choices auto-complete unions.
+type requiredObjectChoicesAutoCompleteUnions = PlainFieldContribution<{
+  key: 'required_object_choices_auto_complete_unions';
+  type: 'string';
+  required: true;
+  choices: {
+    alpha: 'Alpha';
+    beta: 'Beta';
+  };
+}>;
+expectType<requiredObjectChoicesAutoCompleteUnions>(
+  {} as {
+    required_object_choices_auto_complete_unions:
+      | 'alpha'
+      | 'beta'
+      | (string & {});
+  },
+);
+expectAssignable<requiredObjectChoicesAutoCompleteUnions>({
+  required_object_choices_auto_complete_unions: 'alpha',
+});
+
+// Optional object choices auto-complete unions.
+type optionalObjectChoicesAutoCompleteUnions = PlainFieldContribution<{
+  key: 'optional_object_choices_auto_complete_unions';
+  type: 'string';
+  required: false;
+  choices: {
+    alpha: 'Alpha';
+    beta: 'Beta';
+  };
+}>;
+expectType<optionalObjectChoicesAutoCompleteUnions>(
+  {} as {
+    optional_object_choices_auto_complete_unions?:
+      | 'alpha'
+      | 'beta'
+      | (string & {});
+  },
+);
+expectAssignable<optionalObjectChoicesAutoCompleteUnions>({
+  optional_object_choices_auto_complete_unions: 'alpha',
+});
+expectAssignable<optionalObjectChoicesAutoCompleteUnions>({
+  optional_object_choices_auto_complete_unions: undefined,
+});
+expectAssignable<optionalObjectChoicesAutoCompleteUnions>({});
+
+// Required array choices auto-complete unions.
+type requiredFieldArrayChoicesAutoCompleteUnions = PlainFieldContribution<{
+  key: 'required_field_array_choices_auto_complete_unions';
+  type: 'string';
+  required: true;
+  choices: [
+    { label: 'Alpha'; value: 'alpha'; sample: 'alpha' },
+    { label: 'Beta'; value: 'beta'; sample: 'beta' },
+  ];
+}>;
+expectType<requiredFieldArrayChoicesAutoCompleteUnions>(
+  {} as {
+    required_field_array_choices_auto_complete_unions:
+      | 'alpha'
+      | 'beta'
+      | (string & {});
+  },
+);
+expectAssignable<requiredFieldArrayChoicesAutoCompleteUnions>({
+  required_field_array_choices_auto_complete_unions: 'alpha',
+});
+expectAssignable<requiredFieldArrayChoicesAutoCompleteUnions>({
+  required_field_array_choices_auto_complete_unions: 'something_else',
+});
+
+// Optional array choices auto-complete unions.
+type optionalFieldArrayChoicesAutoCompleteUnions = PlainFieldContribution<{
+  key: 'optional_field_array_choices_auto_complete_unions';
+  type: 'string';
+  required: false;
+  choices: [
+    { label: 'Alpha'; value: 'alpha'; sample: 'alpha' },
+    { label: 'Beta'; value: 'beta'; sample: 'beta' },
+  ];
+}>;
+expectType<optionalFieldArrayChoicesAutoCompleteUnions>(
+  {} as {
+    optional_field_array_choices_auto_complete_unions?:
+      | 'alpha'
+      | 'beta'
+      | (string & {});
+  },
+);
+expectAssignable<optionalFieldArrayChoicesAutoCompleteUnions>({
+  optional_field_array_choices_auto_complete_unions: 'alpha',
+});
+expectAssignable<optionalFieldArrayChoicesAutoCompleteUnions>({});
+
+//
+// Required string array choices auto-complete unions.
+type requiredStringArrayChoicesAutoCompleteUnions = PlainFieldContribution<{
+  key: 'required_string_array_choices_auto_complete_unions';
+  type: 'string';
+  required: true;
+  choices: ['alpha', 'beta'];
+}>;
+expectType<requiredStringArrayChoicesAutoCompleteUnions>(
+  {} as {
+    required_string_array_choices_auto_complete_unions:
+      | 'alpha'
+      | 'beta'
+      | (string & {});
+  },
+);
+expectAssignable<requiredStringArrayChoicesAutoCompleteUnions>({
+  required_string_array_choices_auto_complete_unions: 'alpha',
+});
+expectAssignable<requiredStringArrayChoicesAutoCompleteUnions>({
+  required_string_array_choices_auto_complete_unions: 'something_else',
+});
+
+type optionalStringArrayChoicesAutoCompleteUnions = PlainFieldContribution<{
+  key: 'optional_string_array_choices_auto_complete_unions';
+  type: 'string';
+  required: false;
+  choices: ['alpha', 'beta'];
+}>;
+expectType<optionalStringArrayChoicesAutoCompleteUnions>(
+  {} as {
+    optional_string_array_choices_auto_complete_unions?:
+      | 'alpha'
+      | 'beta'
+      | (string & {});
+  },
+);
+expectAssignable<optionalStringArrayChoicesAutoCompleteUnions>({
+  optional_string_array_choices_auto_complete_unions: 'alpha',
+});
+expectAssignable<optionalStringArrayChoicesAutoCompleteUnions>({});

package/types/inputs.test-d.ts

@@ -9,7 +9,7 @@
 import type {
   InferInputData,
   InputFieldFunctionWithInputs,
-  InputFields,
+  StringHints,
 } from './inputs';
 import { defineInputFields } from '.';
 import type { PlainInputField } from './schemas.generated';
@@ -18,9 +18,7 @@ import { expectAssignable, expectType } from 'tsd';
 
 //
 // Test for when `type` is not set, the field defaults to `string`.
-const defaultStringInputs = [
-  { key: 'default_string' },
-] as const satisfies InputFields;
+const defaultStringInputs = defineInputFields([{ key: 'default_string' }]);
 const defaultStringResult1: InferInputData<typeof defaultStringInputs> = {
   default_string: 'a',
 };
@@ -32,11 +30,11 @@ expectAssignable<{ default_string?: string }>(defaultStringResult2);
 
 //
 // Tests for `required` combinations.
-const requiredComboInputs = [
+const requiredComboInputs = defineInputFields([
   { key: 'required_true', required: true },
   { key: 'required_false', required: false },
   { key: 'required_omitted' }, // Will also be optional.
-] as const satisfies InputFields;
+]);
 
 const requiredComboResult1: InferInputData<typeof requiredComboInputs> = {
   required_true: 'a',
@@ -50,7 +48,7 @@ expectAssignable<{
 
 //
 // Test available types.
-const typeComboInputs = [
+const typeComboInputs = defineInputFields([
   { key: 'string_type', type: 'string', required: true },
   { key: 'text_type', type: 'text', required: true },
   { key: 'password_type', type: 'password', required: true },
@@ -60,7 +58,7 @@ const typeComboInputs = [
   { key: 'boolean_type', type: 'boolean', required: true },
   { key: 'datetime_type', type: 'datetime', required: true },
   { key: 'file_type', type: 'file', required: true },
-] as const satisfies InputFields;
+]);
 const typeComboResult: InferInputData<typeof typeComboInputs> = {
   string_type: 'a',
   text_type: 'b',
@@ -86,11 +84,11 @@ expectType<{
 
 //
 // Test that copy fields are never appear in the bundle.
-const copyComboInputs = [
+const copyComboInputs = defineInputFields([
   { key: 'copy_type', type: 'copy' },
   { key: 'copy_type_required', type: 'copy', required: true },
   { key: 'copy_type_not_required', type: 'copy', required: false },
-] as const satisfies InputFields;
+]);
 const copyComboResult: InferInputData<typeof copyComboInputs> = {};
 expectType<{}>(copyComboResult);
 
@@ -100,14 +98,14 @@ expectType<{}>(copyComboResult);
 //   the return type is a constant array.
 // - Even if the possible result fields are known, they will all be
 //   considered optional.
-const knownFieldFunctionInputs = [
+const knownFieldFunctionInputs = defineInputFields([
   () =>
-    [
+    defineInputFields([
       { key: 'ff_required', type: 'string', required: true },
       { key: 'ff_optional', type: 'string', required: false },
       { key: 'ff_omitted', type: 'string' },
-    ] as const satisfies InputFields,
-] as const satisfies InputFields;
+    ]),
+]);
 const fieldFunctionResult: InferInputData<typeof knownFieldFunctionInputs> = {
   ff_required: 'a',
   ff_optional: 'b',
@@ -121,14 +119,14 @@ expectType<{
 
 //
 // Same but Async.
-const knownFieldFunctionAsyncInputs = [
+const knownFieldFunctionAsyncInputs = defineInputFields([
   async () =>
-    [
+    defineInputFields([
       { key: 'ff_required', type: 'string', required: true },
       { key: 'ff_optional', type: 'string', required: false },
       { key: 'ff_omitted', type: 'string' },
-    ] as const satisfies InputFields,
-] as const satisfies InputFields;
+    ]),
+]);
 const knownFieldFunctionAsyncResult: InferInputData<
   typeof knownFieldFunctionAsyncInputs
 > = {
@@ -145,18 +143,18 @@ expectType<{
 //
 // Test that all possible inputs a field function could return are
 // combined into a flat object as optional fields.
-const unionOfFunctionResultInputs = [
+const unionOfFunctionResultInputs = defineInputFields([
   () => {
     if (Math.random() > 0.5) {
-      return [
+      return defineInputFields([
         { key: 'ff_a', type: 'string', required: true },
-      ] as const satisfies InputFields;
+      ]);
     }
-    return [
+    return defineInputFields([
       { key: 'ff_b', type: 'string', required: false },
-    ] as const satisfies InputFields;
+    ]);
   },
-] as const satisfies InputFields;
+]);
 const unionOfFunctionResultInputsResult: InferInputData<
   typeof unionOfFunctionResultInputs
 > = {
@@ -170,18 +168,18 @@ expectType<{
 
 //
 // Same but Async.
-const unionOfFunctionResultAsyncInputs = [
+const unionOfFunctionResultAsyncInputs = defineInputFields([
   async (z, bundle) => {
     if (Math.random() > 0.5) {
-      return [
+      return defineInputFields([
         { key: 'ff_a', type: 'string', required: true },
-      ] as const satisfies InputFields;
+      ]);
     }
-    return [
+    return defineInputFields([
       { key: 'ff_b', type: 'string', required: false },
-    ] as const satisfies InputFields;
+    ]);
   },
-] as const satisfies InputFields;
+]);
 const unionOfFunctionResultAsyncResult: InferInputData<
   typeof unionOfFunctionResultAsyncInputs
 > = {
@@ -196,12 +194,12 @@ expectType<{
 //
 // Test that inputFieldFunctions with unknown fields results produce
 // Record<string, unknown>.
-const unknownFieldFunctionInputs = [
+const unknownFieldFunctionInputs = defineInputFields([
   () => {
     // E.g. Fetch fields from an API
-    return [] as PlainInputField[];
+    return [];
   },
-] as const satisfies InputFields;
+]);
 const unknownFieldFunctionResult: InferInputData<
   typeof unknownFieldFunctionInputs
 > = {};
@@ -209,12 +207,12 @@ expectType<Record<string, unknown>>(unknownFieldFunctionResult);
 
 //
 // Same but Async.
-const unknownFieldFunctionAsyncInputs = [
+const unknownFieldFunctionAsyncInputs = defineInputFields([
   async () => {
     // E.g. Fetch fields from an API
     return [] as PlainInputField[];
   },
-] as const satisfies InputFields;
+]);
 const unknownFieldFunctionAsyncResult: InferInputData<
   typeof unknownFieldFunctionAsyncInputs
 > = {};
@@ -225,13 +223,13 @@ expectType<Record<string, unknown>>(unknownFieldFunctionAsyncResult);
 // function inputs, and then testing the result of all of the inputs
 // combined.
 
-const basicFields = [
+const basicFields = defineInputFields([
   { key: 'string_field', type: 'string', required: true },
   { key: 'number_field', type: 'number', required: true },
   { key: 'boolean_field', type: 'boolean', required: true },
   { key: 'optional_field', type: 'string', required: false },
   { key: 'omitted_field', type: 'string' },
-] as const satisfies InputFields;
+]);
 
 const dynamicField = ((z, bundle) => {
   expectType<{
@@ -241,9 +239,9 @@ const dynamicField = ((z, bundle) => {
     optional_field?: string;
     omitted_field?: string;
   }>(bundle.inputData);
-  return [
+  return defineInputFields([
     { key: 'dynamic_field', type: 'string', required: true },
-  ] as const satisfies InputFields;
+  ]);
 }) satisfies InputFieldFunctionWithInputs<typeof basicFields>;
 
 const allFields = defineInputFields([...basicFields, dynamicField]);
@@ -264,3 +262,69 @@ expectType<{
   omitted_field?: string;
   dynamic_field?: string; // Becomes optional.
 }>(allFieldsResult);
+
+// Choices
+const choicesInputs = defineInputFields([
+  {
+    key: 'choices_string_array',
+    type: 'string',
+    required: true,
+    choices: ['c1', 'c2'],
+  },
+  {
+    key: 'choices_object',
+    type: 'string',
+    required: true,
+    choices: { c3: 'C3', c4: 'C4' },
+  },
+  {
+    key: 'choices_field_array',
+    type: 'string',
+    required: true,
+    choices: [
+      { label: 'C5', value: 'c5', sample: 'c5' },
+      { label: 'C6', value: 'c6', sample: 'c6' },
+    ],
+  },
+  {
+    key: 'choices_list',
+    type: 'string',
+    required: true,
+    list: true,
+    choices: ['c7', 'c8'],
+  },
+  {
+    key: 'ignored_parent',
+    children: [
+      {
+        key: 'child_choice',
+        type: 'string',
+        required: true,
+        choices: { c9: 'C9', c10: 'C10' },
+      },
+      {
+        key: 'child_choice_list',
+        type: 'string',
+        required: true,
+        list: true,
+        choices: ['c11', 'c12'],
+      },
+    ],
+  },
+]);
+const choicesResult: InferInputData<typeof choicesInputs> = {
+  choices_string_array: 'c1',
+  choices_object: 'c3',
+  choices_field_array: 'c5',
+  choices_list: ['c7'],
+  child_choice: 'c9',
+  child_choice_list: ['c11'],
+};
+expectType<{
+  choices_string_array: StringHints<'c1' | 'c2'>;
+  choices_object: StringHints<'c3' | 'c4'>;
+  choices_field_array: StringHints<'c5' | 'c6'>;
+  choices_list: StringHints<'c7' | 'c8'>[];
+  child_choice: StringHints<'c9' | 'c10'>;
+  child_choice_list: StringHints<'c11' | 'c12'>[];
+}>(choicesResult);

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: 17.7.1
+ * zapier-platform-schema version: 17.7.2
  *  schema-to-ts compiler version: 0.1.0
  */
 import type {