@zapier/zapier-sdk 0.9.0 → 0.10.0

package/src/schemas/Field.ts

@@ -1,28 +1,22 @@
 import { z } from "zod";
 import { withFormatter } from "../utils/schema-utils";
-import { NeedSchema } from "../api/schemas";
 
 // ============================================================================
 // Input Field Item Schema (extends API Need schema with computed fields and formatting)
 // ============================================================================
 
 export const InputFieldItemSchema = withFormatter(
-  NeedSchema.omit({
-    depends_on: true,
-    placeholder: true,
-    required: true,
-    format: true,
-  }).extend({
-    id: z.string(), // Mapped from 'key'
+  z.object({
+    key: z.string(), // From need.key
     default_value: z.string(), // Mapped from 'default' with fallback to ""
-    depends_on: z.array(z.string()), // Override: mapped from 'depends_on' 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 ""
     invalidates_input_fields: z.boolean(), // Mapped from 'alters_custom_fields' with fallback to false
-    is_required: z.boolean(), // Override: mapped from 'required' with fallback to false
-    placeholder: z.string(), // Override: mapped from 'placeholder' with fallback to ""
+    is_required: z.boolean(), // Mapped from 'required' with fallback to false
+    placeholder: z.string(), // Mapped from 'placeholder' with fallback to ""
     title: z.string(), // Mapped from 'label' with fallback to ""
     value_type: z.string(), // Computed from InputFieldType enum
-    format: z.string().optional(), // Override: computed from InputFieldFormat enum (optional)
+    format: z.string().optional(), // Computed from InputFieldFormat enum (optional)
     items: z.object({ type: z.string() }).optional(), // Computed from ItemsType enum (optional, only for arrays)
   }),
   {
@@ -31,8 +25,8 @@ export const InputFieldItemSchema = withFormatter(
 
       // Type and required status
       const typeInfo = [
-        item.type && `Type: ${item.type}`,
-        `Required: ${item.required ? "Yes" : "No"}`,
+        item.value_type && `Type: ${item.value_type}`,
+        `Required: ${item.is_required ? "Yes" : "No"}`,
       ]
         .filter(Boolean)
         .join(" | ");
@@ -40,15 +34,18 @@ export const InputFieldItemSchema = withFormatter(
         details.push({ text: typeInfo, style: "dim" as const });
       }
 
-      // Help text
-      if (item.helpText) {
-        details.push({ text: item.helpText, style: "normal" as const });
+      // Description
+      if (item.description) {
+        details.push({
+          text: item.description,
+          style: "normal" as const,
+        });
       }
 
       // Default value
-      if (item.default !== undefined) {
+      if (item.default_value) {
         details.push({
-          text: `Default: ${item.default}`,
+          text: `Default: ${item.default_value}`,
           style: "accent" as const,
         });
       }
@@ -61,25 +58,10 @@ export const InputFieldItemSchema = withFormatter(
         });
       }
 
-      // Choices
-      if (item.choices && item.choices.length > 0) {
-        const choiceText =
-          item.choices.length <= 3
-            ? `Choices: ${item.choices.map((c: { label?: string; value: string | number }) => c.label || c.value).join(", ")}`
-            : `Choices: ${item.choices
-                .slice(0, 3)
-                .map(
-                  (c: { label?: string; value: string | number }) =>
-                    c.label || c.value,
-                )
-                .join(", ")} (+${item.choices.length - 3} more)`;
-        details.push({ text: choiceText, style: "accent" as const });
-      }
-
       // Dependencies
-      if (item.dependsOn && item.dependsOn.length > 0) {
+      if (item.depends_on && item.depends_on.length > 0) {
         details.push({
-          text: `Depends on: ${item.dependsOn.join(", ")}`,
+          text: `Depends on: ${item.depends_on.join(", ")}`,
           style: "warning" as const,
         });
       }
@@ -89,33 +71,18 @@ export const InputFieldItemSchema = withFormatter(
         details.push({ text: `Format: ${item.format}`, style: "dim" as const });
       }
 
-      // Input format
-      if (item.inputFormat && item.inputFormat.length > 0) {
+      // Items type for arrays
+      if (item.items) {
         details.push({
-          text: `Input formats: ${item.inputFormat.join(", ")}`,
+          text: `Items type: ${item.items.type}`,
           style: "dim" as const,
         });
       }
 
-      // Special field flags
-      const flags = [];
-      if (item.computed) flags.push("computed");
-      if (item.customField) flags.push("custom");
-      if (flags.length > 0) {
-        details.push({
-          text: `Flags: ${flags.join(", ")}`,
-          style: "success" as const,
-        });
-      }
-
-      // Backwards compatibility: show description if no helpText
-      if (item.description && !item.helpText) {
-        details.push({ text: item.description, style: "normal" as const });
-      }
-
       return {
-        title: item.label || item.name || item.key,
-        subtitle: `(${item.key})`,
+        title: item.title || item.key,
+        key: item.key,
+        description: item.description,
         details,
       };
     },

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/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;
   }