@zapier/zapier-sdk 0.10.0 → 0.11.0

package/src/plugins/listInputFields/index.ts

@@ -1,7 +1,12 @@
 import type { Plugin, GetSdkType } from "../../types/plugin";
 import type { ApiClient } from "../../api";
 import type { NeedsRequest, NeedsResponse, Need } from "../../api/types";
-import type { InputFieldItem } from "../../types/domain";
+import type {
+  InputFieldItem,
+  InfoFieldItem,
+  FieldsetItem,
+  RootFieldItem,
+} from "../../types/domain";
 import {
   ListInputFieldsSchema,
   type ListInputFieldsOptions,
@@ -18,7 +23,8 @@ import {
   authenticationIdResolver,
   inputsAllOptionalResolver,
 } from "../../resolvers";
-import { InputFieldItemSchema } from "../../schemas/Field";
+import { RootFieldItemSchema } from "../../schemas/Field";
+import { toTitleCase } from "../../utils/string-utils";
 
 // Enums for input field transformation
 enum InputFieldType {
@@ -101,7 +107,7 @@ function transformNeedToInputFieldItem(need: Need): InputFieldItem {
   const itemsType = getItemsTypeFromNeed(need);
 
   return {
-    // Only the final computed/mapped fields that are in InputFieldItemSchema
+    type: "input_field",
     key: need.key,
     default_value: need.default || "",
     depends_on: need.depends_on || [],
@@ -116,12 +122,68 @@ function transformNeedToInputFieldItem(need: Need): InputFieldItem {
   };
 }
 
+// Transform Need to InfoFieldItem (for copy fields)
+function transformNeedToInfoFieldItem(need: Need): InfoFieldItem {
+  return {
+    type: "info_field",
+    key: need.key,
+    description: need.help_text || "",
+    title: need.label,
+  };
+}
+
+// Transform needs to fields (similar to partnerapi compute_root_fieldset_from_needs)
+function transformNeedsToFields(needs: Need[]): RootFieldItem[] {
+  const rootFields: (InputFieldItem | InfoFieldItem | FieldsetItem)[] = [];
+  const fieldsetMap = new Map<string, FieldsetItem>();
+
+  for (const need of needs) {
+    if (need.computed) {
+      // Computed needs (i.e zap_id for CodeAPI steps) are not shown by the
+      // editor, hide them here too.
+      continue;
+    }
+
+    // If parent_key is set, we need to ensure that a corresponding
+    // fieldset exists, since we'll be adding this need to that fieldset
+    if (need.parent_key) {
+      let fieldset = fieldsetMap.get(need.parent_key);
+      if (!fieldset) {
+        fieldset = {
+          type: "fieldset",
+          key: need.parent_key,
+          title: toTitleCase(need.parent_key),
+          fields: [],
+        };
+        fieldsetMap.set(need.parent_key, fieldset);
+        rootFields.push(fieldset);
+      }
+
+      // Add field to fieldset
+      if (need.type === "copy" && need.help_text) {
+        fieldset.fields.push(transformNeedToInfoFieldItem(need));
+      } else {
+        fieldset.fields.push(transformNeedToInputFieldItem(need));
+      }
+    } else {
+      // Add field to root
+      if (need.type === "copy" && need.help_text) {
+        rootFields.push(transformNeedToInfoFieldItem(need));
+      } else {
+        rootFields.push(transformNeedToInputFieldItem(need));
+      }
+    }
+  }
+
+  return rootFields;
+}
+
 export interface ListInputFieldsPluginProvides {
   listInputFields: (options?: ListInputFieldsOptions) => Promise<{
-    data: InputFieldItem[];
+    data: RootFieldItem[];
   }> &
-    AsyncIterable<{ data: InputFieldItem[]; nextCursor?: string }> & {
-      items(): AsyncIterable<InputFieldItem>;
+    AsyncIterable<{ data: RootFieldItem[]; nextCursor?: string }> & {
+      items(): AsyncIterable<InputFieldItem | InfoFieldItem | FieldsetItem>;
     };
   context: {
     meta: {
@@ -189,13 +251,11 @@ export const listInputFieldsPlugin: Plugin<
         );
       }
 
-      // Transform Need objects to InputFieldItem objects
-      const inputFields: InputFieldItem[] = (needsData.needs || []).map(
-        transformNeedToInputFieldItem,
-      );
+      // Transform Need objects to Root Fieldset with proper nesting
+      const rootFieldset = transformNeedsToFields(needsData.needs || []);
 
       return {
-        data: inputFields,
+        data: rootFieldset,
         nextCursor: undefined, // No pagination needed since we return all input fields
       };
     },
@@ -209,9 +269,9 @@ export const listInputFieldsPlugin: Plugin<
         listInputFields: {
           categories: ["action"],
           type: "list",
-          itemType: "InputField",
+          itemType: "RootFieldItem",
           inputSchema: ListInputFieldsSchema,
-          outputSchema: InputFieldItemSchema,
+          outputSchema: RootFieldItemSchema,
           resolvers: {
             appKey: appKeyResolver,
             actionType: actionTypeResolver,

package/src/plugins/listInputFields/schemas.ts

@@ -6,7 +6,7 @@ import {
   AuthenticationIdPropertySchema,
   InputsPropertySchema,
 } from "../../types/properties";
-import type { InputFieldItem } from "../../types/domain";
+import type { RootFieldItem } from "../../types/domain";
 import type { PaginatedSdkFunction } from "../../types/functions";
 import type {
   ZapierConfigurationError,
@@ -54,11 +54,14 @@ export type ListInputFieldsError =
 
 // Page result structure
 export interface ListInputFieldsPage {
-  data: InputFieldItem[];
+  data: RootFieldItem[];
   nextCursor?: string;
 }
 
 // SDK function interface
 export interface ListInputFieldsSdkFunction {
-  listInputFields: PaginatedSdkFunction<ListInputFieldsOptions, InputFieldItem>;
+  listInputFields: PaginatedSdkFunction<
+    ListInputFieldsOptions,
+    RootFieldItem[]
+  >;
 }

package/src/resolvers/inputFieldKey.ts

@@ -1,6 +1,37 @@
 import type { DynamicResolver } from "../utils/schema-utils";
 import type { InputFieldItem } from "../schemas/Field";
 import type { ActionTypeProperty } from "../types/properties";
+import type {
+  RootFieldItem,
+  InfoFieldItem,
+  FieldsetItem,
+} from "../types/domain";
+
+/**
+ * Helper function to flatten fieldsets into a flat array of input fields.
+ * Used to extract all input fields from nested fieldset structure for field selection.
+ */
+function flattenRootFieldset(rootFieldset: RootFieldItem[]): InputFieldItem[] {
+  const result: InputFieldItem[] = [];
+
+  function processItem(item: InputFieldItem | InfoFieldItem | FieldsetItem) {
+    if (item.type === "input_field") {
+      result.push(item);
+    } else if (item.type === "fieldset") {
+      // Recursively process fields in the fieldset
+      for (const field of item.fields) {
+        processItem(field);
+      }
+    }
+    // Skip info fields as they're not input fields
+  }
+
+  for (const item of rootFieldset) {
+    processItem(item);
+  }
+
+  return result;
+}
 
 export const inputFieldKeyResolver: DynamicResolver<
   InputFieldItem,
@@ -22,7 +53,8 @@ export const inputFieldKeyResolver: DynamicResolver<
       authenticationId: resolvedParams.authenticationId,
       inputs: resolvedParams.inputs, // Pass along currently resolved inputs
     });
-    return fieldsResponse.data;
+    // Flatten the fieldset structure for field selection
+    return flattenRootFieldset(fieldsResponse.data);
   },
   prompt: (fields) => ({
     type: "list",

package/src/resolvers/inputs.ts

@@ -1,13 +1,41 @@
-import type { FieldsResolver } from "../utils/schema-utils";
 import type { ActionTypeProperty } from "../types/properties";
+import type { RootFieldItem } from "../types/domain";
 
-type InputsResolver = FieldsResolver<{
-  appKey: string;
-  actionKey: string;
-  actionType: ActionTypeProperty;
-  authenticationId: number;
-  inputs?: Record<string, unknown>;
-}>;
+// Helper function to recursively make all input fields optional while preserving structure
+function makeFieldsOptional(fields: RootFieldItem[]): RootFieldItem[] {
+  return fields.map((field) => {
+    if (field.type === "input_field") {
+      return {
+        ...field,
+        is_required: false,
+      };
+    } else if (field.type === "fieldset") {
+      return {
+        ...field,
+        fields: makeFieldsOptional(field.fields),
+      };
+    } else {
+      // Info fields remain unchanged
+      return field;
+    }
+  });
+}
+
+// Custom resolver type for fieldsets - returns the nested structure
+type InputsResolver = {
+  type: "fields";
+  depends: readonly string[];
+  fetch: (
+    sdk: any,
+    resolvedParams: {
+      appKey: string;
+      actionKey: string;
+      actionType: ActionTypeProperty;
+      authenticationId: number;
+      inputs?: Record<string, unknown>;
+    },
+  ) => Promise<RootFieldItem[]>;
+};
 
 export const inputsResolver: InputsResolver = {
   type: "fields",
@@ -35,9 +63,7 @@ export const inputsAllOptionalResolver: InputsResolver = {
       authenticationId: resolvedParams.authenticationId,
       inputs: resolvedParams.inputs, // Pass along currently resolved inputs
     });
-    return fieldsResponse.data.map((field) => ({
-      ...field,
-      is_required: false,
-    }));
+    // Return nested structure with all fields marked as optional.
+    return makeFieldsOptional(fieldsResponse.data);
   },
 };

package/src/schemas/Field.ts

@@ -1,13 +1,22 @@
 import { z } from "zod";
 import { withFormatter } from "../utils/schema-utils";
 
+// ============================================================================
+// Base Field Schema
+// ============================================================================
+
+export const BaseFieldItemSchema = z.object({
+  type: z.string(), // "input_field", "info_field", or "fieldset"
+  key: z.string(), // From need.key
+});
+
 // ============================================================================
 // Input Field Item Schema (extends API Need schema with computed fields and formatting)
 // ============================================================================
 
 export const InputFieldItemSchema = withFormatter(
-  z.object({
-    key: z.string(), // From need.key
+  BaseFieldItemSchema.extend({
+    type: z.literal("input_field"),
     default_value: z.string(), // Mapped from 'default' with fallback to ""
     depends_on: z.array(z.string()), // Mapped from 'depends_on' with fallback to []
     description: z.string(), // Mapped from 'help_text' with fallback to ""
@@ -89,11 +98,72 @@ export const InputFieldItemSchema = withFormatter(
   },
 );
 
+// ============================================================================
+// Info Field Item Schema (for help text and copy fields)
+// ============================================================================
+
+export const InfoFieldItemSchema = withFormatter(
+  BaseFieldItemSchema.extend({
+    type: z.literal("info_field"),
+    description: z.string(), // From need.help_text
+    title: z.string().optional(), // Optional title
+  }),
+  {
+    format: (item) => ({
+      title: item.title || "Info",
+      key: item.key,
+      description: item.description,
+      details: [{ text: item.description, style: "normal" as const }],
+    }),
+  },
+);
+
+// ============================================================================
+// Fieldset Schema (for grouping fields)
+// ============================================================================
+
+// Forward reference for recursive type
+type FieldsetItemType =
+  | z.infer<typeof InputFieldItemSchema>
+  | z.infer<typeof InfoFieldItemSchema>
+  | FieldsetItem;
+
+export interface FieldsetItem {
+  type: "fieldset";
+  key: string;
+  title: string;
+  fields: FieldsetItemType[];
+}
+
+export const FieldsetItemSchema: z.ZodType<FieldsetItem> =
+  BaseFieldItemSchema.extend({
+    type: z.literal("fieldset"),
+    title: z.string(),
+    fields: z.lazy(() =>
+      z.array(
+        z.union([
+          InputFieldItemSchema,
+          InfoFieldItemSchema,
+          FieldsetItemSchema,
+        ]),
+      ),
+    ),
+  });
+
+// ============================================================================
+// Root Field Item Schema (union of all possible field types)
+// ============================================================================
+
+export const RootFieldItemSchema = z.union([
+  InputFieldItemSchema,
+  InfoFieldItemSchema,
+  FieldsetItemSchema,
+]);
+
 // ============================================================================
 // Type Exports
 // ============================================================================
 
 export type InputFieldItem = z.infer<typeof InputFieldItemSchema>;
-
-// Legacy alias for backward compatibility
-export type FieldItem = InputFieldItem;
+export type InfoFieldItem = z.infer<typeof InfoFieldItemSchema>;
+export type RootFieldItem = z.infer<typeof RootFieldItemSchema>;

package/src/types/domain.ts

@@ -9,8 +9,13 @@ import type { z } from "zod";
 import type { AppItemSchema } from "../schemas/App";
 import type { AuthenticationItemSchema } from "../schemas/Auth";
 import type { ActionItemSchema } from "../schemas/Action";
-import type { InputFieldItemSchema } from "../schemas/Field";
+import type {
+  InputFieldItemSchema,
+  InfoFieldItemSchema,
+  RootFieldItemSchema,
+} from "../schemas/Field";
 import type { UserProfileItemSchema } from "../schemas/UserProfile";
+import type { FieldsetItem } from "../schemas/Field";
 
 /**
  * Represents an app item returned by getApp and listApps functions
@@ -36,6 +41,24 @@ export type ActionItem = z.infer<typeof ActionItemSchema>;
  */
 export type InputFieldItem = z.infer<typeof InputFieldItemSchema>;
 
+/**
+ * Represents an info field item (help text/copy) returned by listInputFields functions
+ * Inferred from InfoFieldItemSchema
+ */
+export type InfoFieldItem = z.infer<typeof InfoFieldItemSchema>;
+
+/**
+ * Represents a fieldset (group of fields) returned by listInputFields functions
+ * This is defined as an interface rather than inferred due to recursive nature
+ */
+export type { FieldsetItem };
+
+/**
+ * Represents a root field item (any field/fieldset type) returned by listInputFields
+ * Inferred from RootFieldItemSchema - use as RootFieldItem[]
+ */
+export type RootFieldItem = z.infer<typeof RootFieldItemSchema>;
+
 /**
  * Represents a user profile item returned by getProfile function
  * Inferred from UserProfileItemSchema which extends the base UserProfile API schema

package/src/utils/string-utils.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { toTitleCase } from "./string-utils";
+
+describe("toTitleCase", () => {
+  it("converts snake_case to title case", () => {
+    expect(toTitleCase("first_name")).toBe("First Name");
+    expect(toTitleCase("sender_settings")).toBe("Sender Settings");
+    expect(toTitleCase("api_key_config")).toBe("Api Key Config");
+  });
+
+  it("converts camelCase to title case", () => {
+    expect(toTitleCase("firstName")).toBe("First Name");
+    expect(toTitleCase("senderSettings")).toBe("Sender Settings");
+    expect(toTitleCase("apiKeyConfig")).toBe("Api Key Config");
+  });
+
+  it("converts kebab-case to title case", () => {
+    expect(toTitleCase("first-name")).toBe("First Name");
+    expect(toTitleCase("sender-settings")).toBe("Sender Settings");
+    expect(toTitleCase("api-key-config")).toBe("Api Key Config");
+  });
+
+  it("handles mixed formats", () => {
+    expect(toTitleCase("first_name-value")).toBe("First Name Value");
+    expect(toTitleCase("sender_settings-config")).toBe(
+      "Sender Settings Config",
+    );
+  });
+
+  it("handles single words", () => {
+    expect(toTitleCase("name")).toBe("Name");
+    expect(toTitleCase("settings")).toBe("Settings");
+  });
+
+  it("handles multiple spaces and trims", () => {
+    expect(toTitleCase("  first   name  ")).toBe("First Name");
+    expect(toTitleCase("sender__settings")).toBe("Sender Settings");
+  });
+
+  it("handles empty and edge cases", () => {
+    expect(toTitleCase("")).toBe("");
+    expect(toTitleCase("a")).toBe("A");
+    expect(toTitleCase("_")).toBe("");
+  });
+});

package/src/utils/string-utils.ts

@@ -0,0 +1,26 @@
+/**
+ * String utility functions for the Zapier SDK
+ */
+
+/**
+ * Converts a string to title case, handling various input formats:
+ * - camelCase: "firstName" → "First Name"
+ * - snake_case: "first_name" → "First Name"
+ * - kebab-case: "first-name" → "First Name"
+ * - mixed formats: "first_name-value" → "First Name Value"
+ */
+export function toTitleCase(input: string): string {
+  return (
+    input
+      // insert a space before capital letters (handles camelCase)
+      .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+      // replace delimiters (underscore, dash, multiple spaces) with single space
+      .replace(/[_\-]+/g, " ")
+      .replace(/\s+/g, " ")
+      .trim()
+      // split and capitalize each word
+      .split(" ")
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join(" ")
+  );
+}