@zapier/zapier-sdk-cli 0.4.0 → 0.4.2

package/src/commands/generate-types/cli.ts

@@ -0,0 +1,110 @@
+import { Command } from "commander";
+import { createZapierSdk } from "@zapier/zapier-sdk";
+import { GenerateTypesSchema } from "./schemas";
+import { generateTypes } from "./index";
+import chalk from "chalk";
+import { SchemaParameterResolver } from "../../utils/parameter-resolver";
+import {
+  analyzeZodSchema,
+  convertCliArgsToSdkParams,
+} from "../../utils/cli-generator-utils";
+
+export function createGenerateTypesCommand(): Command {
+  const parameters = analyzeZodSchema(GenerateTypesSchema);
+  const description =
+    GenerateTypesSchema.description ||
+    "Generate TypeScript SDK types for a specific app";
+
+  const command = new Command("generate-types").description(description);
+
+  // Add parameters to command using same logic as CLI generator
+  parameters.forEach((param) => {
+    // Convert camelCase to kebab-case for CLI display
+    const kebabName = param.name.replace(/([A-Z])/g, "-$1").toLowerCase();
+
+    if (param.hasResolver && param.required) {
+      // Required parameters with resolvers become optional positional arguments (resolver handles prompting)
+      command.argument(
+        `[${kebabName}]`,
+        param.description || `${kebabName} parameter`,
+      );
+    } else if (param.required) {
+      // Required parameters without resolvers become required positional arguments
+      command.argument(
+        `<${kebabName}>`,
+        param.description || `${kebabName} parameter`,
+      );
+    } else if (param.isPositional) {
+      // Optional parameters marked as positional become optional positional arguments
+      command.argument(
+        `[${kebabName}]`,
+        param.description || `${kebabName} parameter`,
+      );
+    } else {
+      // Optional parameters become flags (whether they have resolvers or not)
+      const flags = [`--${kebabName}`];
+
+      if (param.type === "boolean") {
+        command.option(flags.join(", "), param.description);
+      } else {
+        const flagSignature = flags.join(", ") + ` <${param.type}>`;
+        command.option(flagSignature, param.description, param.default);
+      }
+    }
+  });
+
+  // Add formatting options like other commands
+  command.option("--json", "Output raw JSON instead of formatted results");
+
+  command.action(async (...args: any[]) => {
+    try {
+      // The last argument is always the command object with parsed options
+      const commandObj = args[args.length - 1];
+      const options = commandObj.opts();
+
+      // Convert CLI args to SDK method parameters
+      const rawParams = convertCliArgsToSdkParams(
+        parameters,
+        args.slice(0, -1),
+        options,
+      );
+
+      // Create SDK instance
+      const sdk = createZapierSdk();
+
+      // Resolve missing parameters interactively using schema metadata
+      const resolver = new SchemaParameterResolver();
+      const resolvedParams = await resolver.resolveParameters(
+        GenerateTypesSchema,
+        rawParams,
+        sdk,
+      );
+
+      console.log(
+        chalk.blue(
+          `🔧 Generating TypeScript types for ${resolvedParams.appKey}...`,
+        ),
+      );
+
+      // Call our implementation
+      const result = await generateTypes({ ...resolvedParams, sdk });
+
+      if (options.json) {
+        console.log(JSON.stringify({ result }, null, 2));
+      } else {
+        const output =
+          resolvedParams.output || `./types/${resolvedParams.appKey}.d.ts`;
+        console.log(chalk.green("✅ TypeScript types generated successfully!"));
+        console.log(chalk.gray(`Output written to: ${output}`));
+      }
+    } catch (error) {
+      console.error(
+        chalk.red("Error:"),
+        error instanceof Error ? error.message : "Unknown error",
+      );
+      process.exit(1);
+    }
+  });
+
+  return command;
+}

package/src/commands/generate-types/index.ts

@@ -0,0 +1,365 @@
+import type {
+  Action,
+  ActionField,
+  ActionItem,
+  createZapierSdk,
+} from "@zapier/zapier-sdk";
+import type { GenerateTypesOptions } from "./schemas";
+import * as fs from "fs";
+import * as path from "path";
+
+interface ActionWithActionFields extends Omit<Action, "inputFields" | "type"> {
+  inputFields: ActionField[];
+  app_key: string;
+  action_type: Action["type"];
+  title: string;
+  type: "action";
+}
+
+/**
+ * Generate the fetch method signature for app proxies
+ */
+function generateFetchMethodSignature(): string {
+  return `  /** Make authenticated HTTP requests through Zapier's Relay service */
+  fetch: (options: Omit<z.infer<typeof RelayFetchSchema>, 'authenticationId'>) => Promise<Response>`;
+}
+
+/**
+ * Generate TypeScript types for a specific app (CLI version)
+ */
+export async function generateTypes(
+  options: GenerateTypesOptions & { sdk: ReturnType<typeof createZapierSdk> },
+): Promise<string> {
+  const {
+    appKey,
+    authenticationId,
+    output = `./types/${appKey}.d.ts`,
+    sdk,
+  } = options;
+
+  // Parse app identifier (support app@version format)
+  const { app, version } = parseAppIdentifier(appKey);
+
+  // Fetch all actions for the app
+  const actionsResult = await sdk.listActions({
+    appKey: app,
+  });
+
+  const actions = actionsResult.data;
+
+  if (actions.length === 0) {
+    const typeDefinitions = generateEmptyTypesFile(app, version);
+
+    if (output) {
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.writeFileSync(output, typeDefinitions, "utf8");
+    }
+
+    return typeDefinitions;
+  }
+
+  // Fetch input fields for each action
+  const actionsWithFields: ActionWithActionFields[] = [];
+
+  if (authenticationId) {
+    for (const action of actions) {
+      try {
+        const fieldsResult = await sdk.listInputFields({
+          appKey: action.app_key,
+          actionKey: action.key,
+          actionType: action.action_type as any,
+          authenticationId: authenticationId,
+        });
+
+        const fields = fieldsResult.data; // Direct array result
+        actionsWithFields.push({ ...action, inputFields: fields } as any);
+      } catch {
+        // If we can't get fields for an action, include it without fields
+        actionsWithFields.push({ ...action, inputFields: [] } as any);
+      }
+    }
+  } else {
+    // Convert actions to have empty input fields (will generate generic types)
+    actions.forEach((action: ActionItem) => {
+      actionsWithFields.push({ ...action, inputFields: [] } as any);
+    });
+  }
+
+  // Generate TypeScript types
+  const typeDefinitions = generateTypeDefinitions(
+    app,
+    actionsWithFields,
+    version,
+  );
+
+  // Write to file if output path specified
+  if (output) {
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    fs.writeFileSync(output, typeDefinitions, "utf8");
+  }
+
+  return typeDefinitions;
+}
+
+function parseAppIdentifier(identifier: string): {
+  app: string;
+  version?: string;
+} {
+  const parts = identifier.split("@");
+  return {
+    app: parts[0],
+    version: parts[1],
+  };
+}
+
+function generateTypeDefinitions(
+  appKey: string,
+  actions: ActionWithActionFields[],
+  version?: string,
+): string {
+  // Handle empty actions
+  if (actions.length === 0) {
+    return generateEmptyTypesFile(appKey, version);
+  }
+
+  // Group actions by type
+  const actionsByType = actions.reduce(
+    (acc, action) => {
+      if (!acc[action.action_type]) {
+        acc[action.action_type] = [];
+      }
+      acc[action.action_type].push(action);
+      return acc;
+    },
+    {} as Record<string, ActionWithActionFields[]>,
+  );
+
+  const appName = capitalize(appKey);
+  const versionComment = version
+    ? ` * Generated for ${appKey}@${version}`
+    : ` * Generated for ${appKey}`;
+
+  let output = `/* eslint-disable @typescript-eslint/naming-convention */
+/**
+ * Auto-generated TypeScript types for Zapier ${appKey} actions
+${versionComment}
+ * Generated on: ${new Date().toISOString()}
+ * 
+ * Usage:
+ *   import type { ${appName}Sdk } from './path/to/this/file'
+ *   const sdk = createZapierSdk() as unknown as ${appName}Sdk
+ *   
+ *   // Direct usage (per-call auth):
+ *   await sdk.apps.${appKey}.search.user_by_email({ authenticationId: 123, inputs: { email } })
+ *   
+ *   // Factory usage (pinned auth):
+ *   const my${appName} = sdk.apps.${appKey}({ authenticationId: 123 })
+ *   await my${appName}.search.user_by_email({ inputs: { email } })
+ */
+
+import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapier-sdk'
+import { z } from 'zod'
+import { RelayFetchSchema } from '@zapier/zapier-sdk'
+
+`;
+
+  // Generate input types for each action
+  actions.forEach((action) => {
+    if (action.inputFields.length > 0) {
+      const inputTypeName = `${appName}${capitalize(action.action_type)}${capitalize(
+        sanitizeActionName(action.key),
+      )}Inputs`;
+
+      output += `interface ${inputTypeName} {\n`;
+
+      action.inputFields.forEach((field) => {
+        const isOptional = !field.required;
+        const fieldType = mapFieldTypeToTypeScript(field);
+        const description = field.helpText
+          ? `  /** ${escapeComment(field.helpText)} */\n`
+          : "";
+
+        output += `${description}  ${sanitizeFieldName(field.key)}${
+          isOptional ? "?" : ""
+        }: ${fieldType}\n`;
+      });
+
+      output += `}\n\n`;
+    }
+  });
+
+  // Generate action type interfaces for each action type
+  Object.entries(actionsByType).forEach(([actionType, typeActions]) => {
+    const typeName = `${appName}${capitalize(actionType)}Actions`;
+
+    output += `interface ${typeName} {\n`;
+
+    typeActions.forEach((action: ActionWithActionFields) => {
+      const actionName = sanitizeActionName(action.key);
+      const description = action.description
+        ? `  /** ${escapeComment(action.description)} */\n`
+        : "";
+
+      // Generate type-safe action method signature
+      if (action.inputFields.length > 0) {
+        const inputTypeName = `${appName}${capitalize(action.action_type)}${capitalize(
+          sanitizeActionName(action.key),
+        )}Inputs`;
+        output += `${description}  ${actionName}: (options: { inputs: ${inputTypeName} } & Omit<ActionExecutionOptions, 'inputs'>) => Promise<ActionExecutionResult>\n`;
+      } else {
+        // No specific input fields available - use generic Record<string, any> for inputs
+        output += `${description}  ${actionName}: (options?: { inputs?: Record<string, any> } & ActionExecutionOptions) => Promise<ActionExecutionResult>\n`;
+      }
+    });
+
+    output += `}\n\n`;
+  });
+
+  // Generate the main app SDK interface with factory pattern support
+
+  // Generate the app proxy interface (actions grouped by type)
+  output += `interface ${appName}AppProxy {\n`;
+  Object.keys(actionsByType).forEach((actionType) => {
+    const typeName = `${appName}${capitalize(actionType)}Actions`;
+    output += `  ${actionType}: ${typeName}\n`;
+  });
+  // Always include fetch method for authenticated HTTP requests
+  output += generateFetchMethodSignature() + "\n";
+  output += `}\n\n`;
+
+  // Generate the factory function interface
+  output += `interface ${appName}AppFactory {\n`;
+  output += `  (options: { authenticationId: number }): ${appName}AppProxy\n`;
+  output += `}\n\n`;
+
+  // Combine factory and direct access
+  output += `type ${appName}AppWithFactory = ${appName}AppFactory & ${appName}AppProxy\n\n`;
+
+  // Generate the main SDK interface
+  output += `export interface ${appName}Sdk {\n`;
+  output += `  apps: {\n`;
+  output += `    ${appKey}: ${appName}AppWithFactory\n`;
+  output += `  }\n`;
+  output += `}\n`;
+
+  return output;
+}
+
+function generateEmptyTypesFile(appKey: string, version?: string): string {
+  const appName = capitalize(appKey);
+  const versionComment = version
+    ? ` * Generated for ${appKey}@${version}`
+    : ` * Generated for ${appKey}`;
+
+  return `/* eslint-disable @typescript-eslint/naming-convention */
+/**
+ * Auto-generated TypeScript types for Zapier ${appKey} actions
+${versionComment}
+ * Generated on: ${new Date().toISOString()}
+ * 
+ * No actions found for this app.
+ */
+
+import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapier-sdk'
+import { z } from 'zod'
+import { RelayFetchSchema } from '@zapier/zapier-sdk'
+
+interface ${appName}AppProxy {
+  // No actions available
+${generateFetchMethodSignature()}
+}
+
+interface ${appName}AppFactory {
+  (options: { authenticationId: number }): ${appName}AppProxy
+}
+
+type ${appName}AppWithFactory = ${appName}AppFactory & ${appName}AppProxy
+
+export interface ${appName}Sdk {
+  apps: {
+    ${appKey}: ${appName}AppWithFactory
+  }
+}
+`;
+}
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1).replace(/[-_]/g, "");
+}
+
+function sanitizeActionName(actionKey: string): string {
+  // Ensure the action name is a valid TypeScript identifier
+  let sanitized = actionKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+
+  // If it starts with a number, prepend an underscore
+  if (/^[0-9]/.test(sanitized)) {
+    sanitized = "_" + sanitized;
+  }
+
+  return sanitized;
+}
+
+function sanitizeFieldName(fieldKey: string): string {
+  // Ensure the field name is a valid TypeScript identifier
+  let sanitized = fieldKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+
+  // If it starts with a number, prepend an underscore
+  if (/^[0-9]/.test(sanitized)) {
+    sanitized = "_" + sanitized;
+  }
+
+  return sanitized;
+}
+
+function escapeComment(comment: string): string {
+  // Escape comment text to prevent breaking the JSDoc comment
+  return comment.replace(/\*\//g, "*\\/").replace(/\r?\n/g, " ");
+}
+
+function mapFieldTypeToTypeScript(field: ActionField): string {
+  // Handle choices (enum-like fields)
+  if (field.choices && field.choices.length > 0) {
+    const choiceValues = field.choices
+      .filter(
+        (choice) =>
+          choice.value !== undefined &&
+          choice.value !== null &&
+          choice.value !== "",
+      )
+      .map((choice) =>
+        typeof choice.value === "string" ? `"${choice.value}"` : choice.value,
+      );
+
+    if (choiceValues.length > 0) {
+      return choiceValues.join(" | ");
+    }
+    // If all choices were filtered out, fall through to default type handling
+  }
+
+  // Map Zapier field types to TypeScript types
+  switch (field.type?.toLowerCase()) {
+    case "string":
+    case "text":
+    case "email":
+    case "url":
+    case "password":
+      return "string";
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "datetime":
+    case "date":
+      return "string"; // ISO date strings
+    case "file":
+      return "string"; // File URL or content
+    case "array":
+      return "any[]";
+    case "object":
+      return "Record<string, any>";
+    default:
+      // Default to string for unknown types, with union for common cases
+      return "string | number | boolean";
+  }
+}

package/src/commands/generate-types/schemas.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import {
+  AppKeyPropertySchema,
+  AuthenticationIdPropertySchema,
+  OutputPropertySchema,
+  DebugPropertySchema,
+} from "@zapier/zapier-sdk";
+
+// Generate types schema - mirrors the original from SDK but for CLI use
+export const GenerateTypesSchema = z
+  .object({
+    appKey: AppKeyPropertySchema.describe("App key to generate SDK code for"),
+    authenticationId: AuthenticationIdPropertySchema.optional(),
+    output: OutputPropertySchema.optional().describe(
+      "Output file path (defaults to generated/<appKey>.ts)",
+    ),
+    debug: DebugPropertySchema.describe(
+      "Enable debug logging during generation",
+    ),
+  })
+  .describe("Generate TypeScript SDK code for a specific app");
+
+export type GenerateTypesOptions = z.infer<typeof GenerateTypesSchema>;

package/src/commands/index.ts

@@ -1,4 +1,6 @@
 export { createLoginCommand } from "./login";
 export { createLogoutCommand } from "./logout";
-export { createWhoamiCommand } from "./whoami";
 export { createConfigPathCommand } from "./configPath";
+export { createGenerateTypesCommand } from "./generate-types/cli";
+export { createBundleCodeCommand } from "./bundle-code/cli";
+export { createMcpCommand } from "./mcp";

package/src/commands/mcp.ts

@@ -0,0 +1,14 @@
+import { Command } from "commander";
+import { startMcpServerAsProcess } from "@zapier/zapier-sdk-mcp";
+
+export function createMcpCommand(): Command {
+  const command = new Command("mcp");
+
+  command
+    .description("Start MCP server for Zapier SDK")
+    .option("--debug", "Enable debug logging")
+    .option("--port <port>", "Port to listen on (for future HTTP transport)")
+    .action(startMcpServerAsProcess);
+
+  return command;
+}

package/src/utils/cli-generator-utils.ts

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { hasResolver, isPositional } from "@zapier/zapier-sdk";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CliParameter {
+  name: string;
+  type: "string" | "number" | "boolean" | "array";
+  required: boolean;
+  description?: string;
+  default?: any;
+  choices?: string[];
+  hasResolver?: boolean;
+  isPositional?: boolean;
+}
+
+// ============================================================================
+// Schema Analysis
+// ============================================================================
+
+export function analyzeZodSchema(schema: z.ZodSchema): CliParameter[] {
+  const parameters: CliParameter[] = [];
+
+  if (schema instanceof z.ZodObject) {
+    const shape = schema.shape;
+
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+      const param = analyzeZodField(key, fieldSchema as z.ZodSchema);
+      if (param) {
+        parameters.push(param);
+      }
+    }
+  }
+
+  return parameters;
+}
+
+function analyzeZodField(
+  name: string,
+  schema: z.ZodSchema,
+): CliParameter | null {
+  let baseSchema = schema;
+  let required = true;
+  let defaultValue: any = undefined;
+
+  // Unwrap optional and default wrappers
+  if (baseSchema instanceof z.ZodOptional) {
+    required = false;
+    baseSchema = baseSchema._def.innerType;
+  }
+
+  if (baseSchema instanceof z.ZodDefault) {
+    required = false;
+    defaultValue = baseSchema._def.defaultValue();
+    baseSchema = baseSchema._def.innerType;
+  }
+
+  // Determine parameter type
+  let paramType: CliParameter["type"] = "string";
+  let choices: string[] | undefined;
+
+  if (baseSchema instanceof z.ZodString) {
+    paramType = "string";
+  } else if (baseSchema instanceof z.ZodNumber) {
+    paramType = "number";
+  } else if (baseSchema instanceof z.ZodBoolean) {
+    paramType = "boolean";
+  } else if (baseSchema instanceof z.ZodArray) {
+    paramType = "array";
+  } else if (baseSchema instanceof z.ZodEnum) {
+    paramType = "string";
+    choices = baseSchema._def.values;
+  } else if (baseSchema instanceof z.ZodRecord) {
+    // Handle Record<string, any> as JSON string input
+    paramType = "string";
+  }
+
+  // Extract resolver metadata
+  return {
+    name,
+    type: paramType,
+    required,
+    description: schema.description,
+    default: defaultValue,
+    choices,
+    hasResolver: hasResolver(name),
+    isPositional: isPositional(schema),
+  };
+}
+
+// ============================================================================
+// Parameter Conversion
+// ============================================================================
+
+export function convertCliArgsToSdkParams(
+  parameters: CliParameter[],
+  positionalArgs: any[],
+  options: Record<string, any>,
+): Record<string, any> {
+  const sdkParams: Record<string, any> = {};
+
+  // Handle positional arguments (required parameters or optional positional parameters)
+  let argIndex = 0;
+  parameters.forEach((param) => {
+    if (
+      (param.required || param.isPositional) &&
+      argIndex < positionalArgs.length
+    ) {
+      // Use the original camelCase parameter name for the SDK
+      sdkParams[param.name] = convertValue(
+        positionalArgs[argIndex],
+        param.type,
+      );
+      argIndex++;
+    }
+  });
+
+  // Handle option flags
+  Object.entries(options).forEach(([key, value]) => {
+    // Convert kebab-case back to camelCase
+    const camelKey = key.replace(/-([a-z])/g, (g) => g[1].toUpperCase());
+    const param = parameters.find((p) => p.name === camelKey);
+
+    if (param && value !== undefined) {
+      sdkParams[camelKey] = convertValue(value, param.type);
+    }
+  });
+
+  return sdkParams;
+}
+
+function convertValue(value: any, type: CliParameter["type"]): any {
+  switch (type) {
+    case "number":
+      return Number(value);
+    case "boolean":
+      return Boolean(value);
+    case "array":
+      return Array.isArray(value) ? value : [value];
+    case "string":
+    default:
+      // Handle JSON string for objects
+      if (
+        typeof value === "string" &&
+        (value.startsWith("{") || value.startsWith("["))
+      ) {
+        try {
+          return JSON.parse(value);
+        } catch {
+          return value;
+        }
+      }
+      return value;
+  }
+}