@zapier/zapier-sdk 0.9.0 → 0.11.0

package/src/schemas/Run.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { withFormatter, type FormattedItem } from "../utils/schema-utils";
+
+// Type guard to safely access object properties
+function getStringProperty(obj: unknown, key: string): string | undefined {
+  if (typeof obj === "object" && obj !== null && key in obj) {
+    const value = (obj as Record<string, unknown>)[key];
+    return typeof value === "string" ? value : undefined;
+  }
+  return undefined;
+}
+
+// Formatter for action results - handles any data structure
+function formatActionResult(item: unknown): FormattedItem {
+  // Try to extract common fields for structured display
+  const obj = typeof item === "object" && item !== null ? item : {};
+
+  // Try common title fields
+  const title =
+    getStringProperty(obj, "title") ||
+    getStringProperty(obj, "name") ||
+    getStringProperty(obj, "label") ||
+    getStringProperty(obj, "subject") ||
+    "Action Result";
+
+  return {
+    title,
+    id: getStringProperty(obj, "id"),
+    key: getStringProperty(obj, "key"),
+    description: getStringProperty(obj, "description"),
+    data: item, // Let formatJsonOutput handle the JSON rendering
+    details: [], // Not used when data is provided
+  };
+}
+
+// Flexible schema for action results - can be any object
+export const ActionResultItemSchema = withFormatter(
+  z.unknown().describe("Action execution result"),
+  { format: formatActionResult },
+);

package/src/schemas/UserProfile.ts

@@ -15,21 +15,38 @@ export const UserProfileItemSchema = withFormatter(
   {
     format: (item) => {
       const details = [];
-      details.push({ text: item.email, style: "dim" as const });
-      if (item.timezone) {
+      if (
+        item == null ||
+        typeof item !== "object" ||
+        !("full_name" in item) ||
+        !("username" in item)
+      ) {
+        return {
+          title: "User Profile",
+          subtitle: "Malformatted result item",
+          details: [],
+        };
+      }
+
+      if ("email" in item) {
+        details.push({ text: item.email, style: "dim" as const });
+      }
+      if ("timezone" in item && item.timezone) {
         details.push({
           text: `Timezone: ${item.timezone}`,
           style: "accent" as const,
         });
       }
-      details.push({
-        text: `Member since: ${item.since_signup}`,
-        style: "dim" as const,
-      });
+      if ("since_signup" in item && item.since_signup) {
+        details.push({
+          text: `Member since: ${item.since_signup}`,
+          style: "dim" as const,
+        });
+      }
 
       return {
         title: item.full_name,
-        subtitle: `@${item.username}`,
+        id: item.id.toString(),
         details,
       };
     },

package/src/sdk.ts

@@ -9,6 +9,7 @@ import type {
   Sdk,
   Plugin,
   ExtractContextProperties,
+  ExtractSdkProperties,
   PluginProvides,
   PluginMeta,
 } from "./types/plugin";
@@ -41,12 +42,14 @@ export interface ZapierSdkOptions extends BaseSdkOptions {}
 // Create SDK that supports flat plugins - returns an SDK, not a builder
 export function createSdk<
   TCurrentSdk = {},
-  TCurrentContext = { meta: Record<string, PluginMeta> },
+  TCurrentContext extends { meta: Record<string, PluginMeta> } = {
+    meta: Record<string, PluginMeta>;
+  },
 >(
   options: ZapierSdkOptions = {},
   initialSdk: TCurrentSdk = {} as TCurrentSdk,
   initialContext: TCurrentContext = { meta: {} } as TCurrentContext,
-): Sdk<TCurrentSdk, TCurrentContext> {
+) {
   return {
     ...initialSdk,
     getContext: () => initialContext,
@@ -56,8 +59,11 @@ export function createSdk<
         TRequiresContext,
         TProvides
       >,
-      addPluginOptions: any = {},
-    ) {
+      addPluginOptions: Record<string, unknown> = {},
+    ): Sdk<
+      TCurrentSdk & ExtractSdkProperties<TProvides>,
+      TCurrentContext & NonNullable<ExtractContextProperties<TProvides>>
+    > {
       // Create SDK with getContext method for plugins to use
       const currentSdkWithContext = {
         ...initialSdk,
@@ -71,7 +77,7 @@ export function createSdk<
           ...initialContext,
           // Add the options that createSdk was called with to context
           options,
-        },
+        } as TCurrentContext & { options: ZapierSdkOptions } & TRequiresContext,
         ...addPluginOptions,
       });
 
@@ -86,7 +92,8 @@ export function createSdk<
       let newContext = {
         ...initialContext,
         ...addPluginOptions,
-        meta: (initialContext as any).meta || {},
+        meta:
+          (initialContext as { meta?: Record<string, PluginMeta> }).meta || {},
       } as TCurrentContext & NonNullable<ExtractContextProperties<TProvides>>;
 
       if (pluginContext) {
@@ -112,7 +119,10 @@ export function createSdk<
       }
 
       // Recursively create new SDK with updated properties
-      return createSdk(options, newSdk, newContext) as any;
+      return createSdk(options, newSdk, newContext) as Sdk<
+        TCurrentSdk & ExtractSdkProperties<TProvides>,
+        TCurrentContext & NonNullable<ExtractContextProperties<TProvides>>
+      >;
     },
   };
 }

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/types/plugin.ts

@@ -22,7 +22,12 @@ export interface PluginProvides extends Record<string, any> {
 
 export interface PluginMeta {
   categories: string[];
+  type?: "list" | "item";
+  itemType?: string;
+  returnType?: string;
   inputSchema: z.ZodSchema;
+  outputSchema?: z.ZodSchema;
+  resolvers?: Record<string, any>;
   [key: string]: any;
 }
 

package/src/types/sdk.ts

@@ -57,8 +57,13 @@ import type { ManifestPluginProvides } from "../plugins/manifest";
 // Registry entry interface with proper types
 export interface FunctionRegistryEntry {
   name: string;
+  type?: "list" | "item";
+  itemType?: string;
+  returnType?: string;
   inputSchema: z.ZodSchema;
+  outputSchema?: z.ZodSchema;
   categories: string[];
+  resolvers?: Record<string, any>;
 }
 
 // Compose SDK functions from individual function interfaces

package/src/utils/domain-utils.ts

@@ -2,14 +2,7 @@
  * Domain utility functions for working with app identifiers and data normalization
  */
 
-import type {
-  Action,
-  App,
-  Authentication,
-  Implementation,
-  ImplementationMeta,
-  Service,
-} from "../api/types";
+import type { Action, Authentication, ImplementationMeta } from "../api/types";
 import type { ActionItem, AppItem, AuthenticationItem } from "../types/domain";
 
 /**
@@ -34,48 +27,6 @@ export function splitVersionedKey(
   return [versionedKey, undefined];
 }
 
-/**
- * Converts an API App to an AppItem with normalized field names
- *
- * @param app - Raw App from API
- * @returns Normalized AppItem
- */
-export function normalizeAppItem(app: App): AppItem {
-  // Extract API name and version from current_implementation_id
-  const [apiName, appVersion] = app.current_implementation_id
-    ? splitVersionedKey(app.current_implementation_id)
-    : [app.current_implementation_id || "", undefined];
-
-  return {
-    title: app.name,
-    key: app.slug || apiName,
-    current_implementation_id: app.current_implementation_id || "",
-    version: appVersion, // Extract version separately
-  };
-}
-
-/**
- * Converts an Implementation to an AppItem with normalized field names
- *
- * @param implementation - Raw Implementation from API
- * @returns Normalized AppItem
- */
-export function normalizeImplementationToAppItem(
-  implementation: Implementation,
-): AppItem {
-  // Extract API name and version from selected_api
-  const [selectedApi, appVersion] = implementation.selected_api
-    ? splitVersionedKey(implementation.selected_api)
-    : [implementation.selected_api || "", undefined];
-
-  return {
-    title: implementation.name || selectedApi,
-    key: selectedApi,
-    current_implementation_id: implementation.selected_api || "",
-    version: appVersion, // Extract version separately
-  };
-}
-
 /**
  * Converts a lightweight ImplementationMeta to a slimmed AppItem
  *
@@ -88,26 +39,17 @@ export function normalizeImplementationMetaToAppItem(
   // Extract API name and version from the implementation ID
   const [selectedApi, appVersion] = splitVersionedKey(implementationMeta.id);
 
-  return {
-    title: implementationMeta.name,
-    key: selectedApi,
-    current_implementation_id: implementationMeta.id, // Keep the full versioned ID
-    version: appVersion, // Extract version separately
-    slug: implementationMeta.slug,
-  };
-}
-
-export function normalizeServiceToAppItem(service: Service): AppItem {
-  const [selectedApi, appVersion] = service.current_implementation_id
-    ? splitVersionedKey(service.current_implementation_id)
-    : ["", undefined];
+  // Destructure to exclude id and name before spreading
+  const { id, name, ...restOfImplementationMeta } = implementationMeta;
 
   return {
-    title: service.name,
+    // Pass through all ImplementationMeta fields except id and name
+    ...restOfImplementationMeta,
+    // Transform key fields
+    title: name,
     key: selectedApi,
-    current_implementation_id: service.current_implementation_id,
-    version: appVersion,
-    description: service.description,
+    implementation_id: id, // Keep the full versioned ID
+    version: appVersion, // Extract version separately
   };
 }
 

package/src/utils/schema-utils.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import type { ZapierSdk } from "../types/sdk";
+import type { InputFieldItem } from "../schemas/Field";
 
 // ============================================================================
 // Format Metadata Types
@@ -6,92 +8,121 @@ import { z } from "zod";
 
 export interface FormattedItem {
   title: string;
-  subtitle?: string;
+  id?: string;
+  key?: string;
+  description?: string;
+  data?: unknown; // Optional: if provided, CLI will use formatJsonOutput instead of details
   details: Array<{
     text: string;
     style: "normal" | "dim" | "accent" | "warning" | "success";
   }>;
 }
 
-export interface FormatMetadata {
-  format: (item: any) => FormattedItem;
+export interface FormatMetadata<TItem = unknown> {
+  format: (item: TItem) => FormattedItem;
 }
 
 // Helper function to add format metadata to schemas
 export function withFormatter<T extends z.ZodType>(
   schema: T,
-  formatMeta: FormatMetadata,
+  formatMeta: FormatMetadata<z.infer<T>>,
 ): T {
   // Store format metadata on the schema definition
-  (schema._def as any).formatMeta = formatMeta;
-  return schema;
+  Object.assign(schema._def, {
+    formatMeta: formatMeta,
+  });
+  return schema as T & {
+    _def: T["_def"] & { formatMeta: FormatMetadata<z.infer<T>> };
+  };
 }
 
-// Helper function to get format metadata from a schema
-export function getFormatMetadata(
-  schema: z.ZodType,
-): FormatMetadata | undefined {
-  return (schema._def as any).formatMeta;
+// Helper function to get output schema from an input schema
+export function getOutputSchema(inputSchema: z.ZodType): z.ZodType | undefined {
+  return (inputSchema._def as { outputSchema?: z.ZodType }).outputSchema;
 }
 
 // Helper function to link input schemas to output schemas
 export function withOutputSchema<T extends z.ZodType>(
   inputSchema: T,
   outputSchema: z.ZodType,
-): T {
+): T & {
+  _def: T["_def"] & { outputSchema: z.ZodType };
+} {
   // Store output schema reference on the input schema
-  (inputSchema._def as any).outputSchema = outputSchema;
-  return inputSchema;
-}
-
-// Helper function to get output schema from an input schema
-export function getOutputSchema(inputSchema: z.ZodType): z.ZodType | undefined {
-  return (inputSchema._def as any).outputSchema;
+  Object.assign(inputSchema._def, {
+    outputSchema,
+  });
+  return inputSchema as T & {
+    _def: T["_def"] & { outputSchema: z.ZodType };
+  };
 }
 
 // ============================================================================
 // Resolution Metadata Types
 // ============================================================================
 
-export interface StaticResolver {
+export interface PromptConfig {
+  type: "list";
+  name: string;
+  message: string;
+  choices: Array<{
+    name: string;
+    value: unknown;
+  }>;
+}
+
+export interface Resolver {
+  type: string;
+  depends?: readonly string[] | string[]; // Parameters this resolver depends on
+}
+
+export interface StaticResolver extends Resolver {
   type: "static";
   inputType?: "text" | "password" | "email";
   placeholder?: string;
 }
 
-export interface DynamicResolver {
+export interface DynamicResolver<
+  TItem = unknown,
+  TParams = Record<string, unknown>,
+> extends Resolver {
   type: "dynamic";
-  fetch: (sdk: any, resolvedParams: any) => Promise<any[]>; // Function to fetch data using SDK
-  prompt: (items: any[], params: any) => any;
-  depends?: string[]; // Parameters this resolver depends on
+  fetch: (sdk: ZapierSdk, resolvedParams: TParams) => Promise<TItem[]>; // Function to fetch data using SDK
+  prompt: (items: TItem[], params: TParams) => PromptConfig;
 }
 
-export interface FieldsResolver {
+export interface FieldsResolver<TParams = Record<string, unknown>>
+  extends Resolver {
   type: "fields";
-  fetch: (sdk: any, resolvedParams: any) => Promise<any[]>; // Function to fetch fields using SDK
-  depends?: string[]; // Parameters this resolver depends on
+  fetch: (sdk: ZapierSdk, resolvedParams: TParams) => Promise<InputFieldItem[]>; // Function to fetch fields using SDK
 }
 
-export type ResolverMetadata =
-  | StaticResolver
-  | DynamicResolver
-  | FieldsResolver;
+export type ResolverMetadata<
+  TItem = unknown,
+  TParams = Record<string, unknown>,
+> = StaticResolver | DynamicResolver<TItem, TParams> | FieldsResolver<TParams>;
 
 // Wrapper interface for resolver metadata to allow future extensibility
-export interface ResolverConfig {
-  resolver: ResolverMetadata;
+export interface ResolverConfig<
+  TItem = unknown,
+  TParams = Record<string, unknown>,
+> {
+  resolver: ResolverMetadata<TItem, TParams>;
   // Future metadata types can be added here:
   // validation?: ValidationMetadata;
   // display?: DisplayMetadata;
 }
 
 // Helper function to add resolver metadata to schemas
-export function withResolver<T extends z.ZodType>(
-  schema: T,
-  config: ResolverConfig,
-): T {
+export function withResolver<
+  T extends z.ZodType,
+  TItem = unknown,
+  TParams = Record<string, unknown>,
+>(schema: T, config: ResolverConfig<TItem, TParams>): T {
   // Store resolver metadata on the schema definition
-  (schema._def as any).resolverMeta = config;
+  (
+    schema._def as { resolverMeta?: ResolverConfig<TItem, TParams> }
+  ).resolverMeta = config;
   return schema;
 }
 
@@ -104,7 +135,7 @@ export function getSchemaDescription(schema: z.ZodSchema): string | undefined {
 }
 
 export function getFieldDescriptions(
-  schema: z.ZodObject<any>,
+  schema: z.ZodObject<z.ZodRawShape>,
 ): Record<string, string> {
   const descriptions: Record<string, string> = {};
   const shape = schema.shape;
@@ -123,20 +154,41 @@ export function getFieldDescriptions(
 // ============================================================================
 
 export interface PositionalMetadata {
-  positional: true;
+  positionalMeta: {
+    positional: true;
+  };
 }
 
 // Helper function to mark a parameter as positional for CLI
-export function withPositional<T extends z.ZodType>(schema: T): T {
+export function withPositional<T extends z.ZodType>(
+  schema: T,
+): T & {
+  _def: T["_def"] & PositionalMetadata;
+} {
   // Store positional metadata on the schema definition
-  (schema._def as any).positionalMeta = { positional: true };
-  return schema;
+  Object.assign(schema._def, {
+    positionalMeta: { positional: true },
+  } satisfies PositionalMetadata);
+  return schema as T & {
+    _def: T["_def"] & PositionalMetadata;
+  };
+}
+
+function schemaHasPositionalMeta<T extends z.ZodType>(
+  schema: T,
+): schema is T & {
+  _def: T["_def"] & PositionalMetadata;
+} {
+  return "positionalMeta" in schema._def;
 }
 
 // Helper function to check if a parameter should be positional
 export function isPositional(schema: z.ZodType): boolean {
   // Check the current schema first
-  if ((schema._def as any).positionalMeta?.positional) {
+  if (
+    schemaHasPositionalMeta(schema) &&
+    schema._def.positionalMeta?.positional
+  ) {
     return true;
   }
 

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(" ")
+  );
+}