@zapier/zapier-sdk-cli 0.8.3 → 0.9.0

package/src/plugins/add/ast-generator.ts

@@ -0,0 +1,777 @@
+import * as ts from "typescript";
+import type {
+  Action,
+  ActionField,
+  GetSdkType,
+  ListActionsPluginProvides,
+  ListInputFieldsPluginProvides,
+  ManifestPluginProvides,
+} from "@zapier/zapier-sdk";
+
+interface ActionWithActionFields extends Omit<Action, "inputFields" | "type"> {
+  inputFields: ActionField[];
+  app_key: string;
+  action_type: Action["type"];
+  title: string;
+  type: "action";
+}
+
+interface GenerateTypesOptions {
+  appKey: string;
+  authenticationId?: number;
+}
+
+/**
+ * AST-based TypeScript type generator using the TypeScript Compiler API
+ */
+export class AstTypeGenerator {
+  private readonly factory = ts.factory;
+  private readonly printer = ts.createPrinter({
+    newLine: ts.NewLineKind.LineFeed,
+    removeComments: false,
+    omitTrailingSemicolon: false,
+  });
+
+  /**
+   * Generate TypeScript types using AST for a specific app
+   */
+  async generateTypes(
+    options: GenerateTypesOptions & {
+      sdk: GetSdkType<
+        ListActionsPluginProvides &
+          ListInputFieldsPluginProvides &
+          ManifestPluginProvides
+      >;
+    },
+  ): Promise<string> {
+    const { appKey, authenticationId, sdk } = options;
+
+    // Parse app identifier (support app@version format)
+    const { app, version } = this.parseAppIdentifier(appKey);
+
+    // Fetch all actions for the app
+    const actionsResult = await sdk.listActions({
+      appKey: app,
+    });
+
+    const actions = actionsResult.data;
+
+    if (actions.length === 0) {
+      return this.generateEmptyTypesFile(app, version);
+    }
+
+    // Fetch input fields for each action
+    const actionsWithFields: ActionWithActionFields[] = [];
+
+    if (authenticationId) {
+      for (const action of actions) {
+        try {
+          const fieldsResult = await sdk.listInputFields({
+            appKey: appKey,
+            actionKey: action.key,
+            actionType: action.action_type,
+            authenticationId: authenticationId,
+          });
+
+          const fields = fieldsResult.data.map(
+            (field: unknown): ActionField => {
+              const fieldObj = field as {
+                is_required?: boolean;
+                required?: boolean;
+                [key: string]: unknown;
+              };
+              return {
+                ...fieldObj,
+                required: fieldObj.is_required || fieldObj.required || false,
+              } as ActionField;
+            },
+          );
+          actionsWithFields.push({
+            ...action,
+            inputFields: fields,
+            name: action.title || action.key,
+          });
+        } catch {
+          // If we can't get fields for an action, include it without fields
+          actionsWithFields.push({
+            ...action,
+            inputFields: [],
+            name: action.title || action.key,
+          });
+        }
+      }
+    } else {
+      // Convert actions to have empty input fields (will generate generic types)
+      actions.forEach(
+        (action: {
+          key: string;
+          title?: string;
+          app_key?: string;
+          action_type?: string;
+          description?: string;
+        }) => {
+          actionsWithFields.push({
+            ...action,
+            inputFields: [],
+            name: action.title || action.key,
+            app_key: action.app_key || appKey,
+            action_type: (action.action_type as Action["type"]) || "write",
+            title: action.title || action.key,
+            type: "action" as const,
+            description: action.description || "",
+          });
+        },
+      );
+    }
+
+    // Generate TypeScript AST nodes
+    const sourceFile = this.createSourceFile(app, actionsWithFields, version);
+
+    // Print the AST to string
+    return this.printer.printFile(sourceFile);
+  }
+
+  private parseAppIdentifier(identifier: string): {
+    app: string;
+    version?: string;
+  } {
+    const parts = identifier.split("@");
+    return {
+      app: parts[0],
+      version: parts[1],
+    };
+  }
+
+  private createSourceFile(
+    appKey: string,
+    actions: ActionWithActionFields[],
+    version?: string,
+  ): ts.SourceFile {
+    const appName = this.capitalize(appKey);
+    const versionComment = version
+      ? ` * Generated for ${appKey}@${version}`
+      : ` * Generated for ${appKey}`;
+
+    // Create header comment
+    const headerComment = `Auto-generated TypeScript types for Zapier ${appKey} actions
+${versionComment.slice(3)}
+Generated on: ${new Date().toISOString()}
+
+This file automatically augments the base SDK types when present.
+No manual imports or type casting required.
+
+Usage:
+  import { createZapierSdk } from "@zapier/zapier-sdk";
+  
+  const zapier = createZapierSdk();
+  // Types are automatically available:
+  await zapier.apps.${appKey}.search.user_by_email({ authenticationId: 123, inputs: { email } })
+  
+  // Factory usage (pinned auth):
+  const my${appName} = zapier.apps.${appKey}({ authenticationId: 123 })
+  await my${appName}.search.user_by_email({ inputs: { email } })`;
+
+    const statements: ts.Statement[] = [
+      // Import the SDK to activate module augmentation
+      this.createImportStatement(["@zapier/zapier-sdk"]),
+
+      // Import types we'll use
+      this.createTypeImportStatement(
+        [
+          "ActionExecutionOptions",
+          "ActionExecutionResult",
+          "ZapierFetchInitOptions",
+        ],
+        "@zapier/zapier-sdk",
+      ),
+    ];
+
+    // Group actions by type
+    const actionsByType = this.groupActionsByType(actions);
+
+    // Generate input interfaces for each action
+    actions.forEach((action) => {
+      if (action.inputFields.length > 0) {
+        const inputInterface = this.createInputInterface(appName, action);
+        statements.push(inputInterface);
+      }
+    });
+
+    // Generate action type interfaces
+    Object.entries(actionsByType).forEach(([actionType, typeActions]) => {
+      const actionInterface = this.createActionInterface(
+        appName,
+        actionType,
+        typeActions,
+      );
+      statements.push(actionInterface);
+    });
+
+    // Generate app proxy interface
+    const appProxyInterface = this.createAppProxyInterface(
+      appName,
+      actionsByType,
+    );
+    statements.push(appProxyInterface);
+
+    // Generate app factory interface
+    const appFactoryInterface = this.createAppFactoryInterface(appName);
+    statements.push(appFactoryInterface);
+
+    // Generate combined app type
+    const appWithFactoryType = this.createAppWithFactoryType(appName);
+    statements.push(appWithFactoryType);
+
+    // Generate module augmentation for automatic type integration
+    const moduleAugmentation = this.createModuleAugmentation(appKey, appName);
+    statements.push(moduleAugmentation);
+
+    // Add empty export to make this a module
+    statements.push(
+      this.factory.createExportDeclaration(
+        undefined,
+        false,
+        this.factory.createNamedExports([]),
+      ),
+    );
+
+    // Create source file
+    const sourceFile = ts.createSourceFile(
+      "generated.d.ts",
+      "",
+      ts.ScriptTarget.Latest,
+      false,
+      ts.ScriptKind.TS,
+    );
+
+    // Add the header comment and ESLint disable as leading trivia to the first statement
+    if (statements.length > 0) {
+      // Add ESLint disable comment
+      ts.addSyntheticLeadingComment(
+        statements[0],
+        ts.SyntaxKind.MultiLineCommentTrivia,
+        " eslint-disable @typescript-eslint/naming-convention, @typescript-eslint/no-explicit-any ",
+        true,
+      );
+      // Add header comment
+      ts.addSyntheticLeadingComment(
+        statements[0],
+        ts.SyntaxKind.MultiLineCommentTrivia,
+        headerComment,
+        true,
+      );
+    }
+
+    return this.factory.updateSourceFile(sourceFile, statements);
+  }
+
+  private createImportStatement(
+    imports: string[],
+    from?: string,
+  ): ts.ImportDeclaration {
+    // Handle side-effect only import (no imports, just the module path)
+    if (imports.length === 1 && !from && imports[0].startsWith("@")) {
+      return this.factory.createImportDeclaration(
+        undefined,
+        undefined,
+        this.factory.createStringLiteral(imports[0]),
+        undefined,
+      );
+    }
+
+    const fromModule = from || imports[0];
+    const importNames = from ? imports : [];
+
+    return this.factory.createImportDeclaration(
+      undefined,
+      importNames.length > 0
+        ? this.factory.createImportClause(
+            false,
+            undefined,
+            this.factory.createNamedImports(
+              importNames.map((name) =>
+                this.factory.createImportSpecifier(
+                  false,
+                  undefined,
+                  this.factory.createIdentifier(name),
+                ),
+              ),
+            ),
+          )
+        : undefined,
+      this.factory.createStringLiteral(fromModule),
+      undefined,
+    );
+  }
+
+  private createTypeImportStatement(
+    imports: string[],
+    from: string,
+  ): ts.ImportDeclaration {
+    return this.factory.createImportDeclaration(
+      undefined,
+      this.factory.createImportClause(
+        true, // typeOnly: true
+        undefined,
+        this.factory.createNamedImports(
+          imports.map((name) =>
+            this.factory.createImportSpecifier(
+              false,
+              undefined,
+              this.factory.createIdentifier(name),
+            ),
+          ),
+        ),
+      ),
+      this.factory.createStringLiteral(from),
+      undefined,
+    );
+  }
+
+  private groupActionsByType(
+    actions: ActionWithActionFields[],
+  ): Record<string, ActionWithActionFields[]> {
+    return 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[]>,
+    );
+  }
+
+  private createInputInterface(
+    appName: string,
+    action: ActionWithActionFields,
+  ): ts.InterfaceDeclaration {
+    const inputTypeName = `${appName}${this.capitalize(action.action_type)}${this.capitalize(
+      this.sanitizeActionName(action.key),
+    )}Inputs`;
+
+    const properties = action.inputFields.map((field) => {
+      const fieldType = this.mapFieldTypeToTypeNode(field);
+      const isOptional = !field.required;
+
+      let property = this.factory.createPropertySignature(
+        undefined,
+        this.sanitizeFieldName(field.key),
+        isOptional
+          ? this.factory.createToken(ts.SyntaxKind.QuestionToken)
+          : undefined,
+        fieldType,
+      );
+
+      // Add JSDoc comment if helpText exists
+      if (field.helpText) {
+        property = ts.addSyntheticLeadingComment(
+          property,
+          ts.SyntaxKind.MultiLineCommentTrivia,
+          `* ${this.escapeComment(field.helpText)} `,
+          true,
+        );
+      }
+
+      return property;
+    });
+
+    return this.factory.createInterfaceDeclaration(
+      undefined,
+      inputTypeName,
+      undefined,
+      undefined,
+      properties,
+    );
+  }
+
+  private createActionInterface(
+    appName: string,
+    actionType: string,
+    typeActions: ActionWithActionFields[],
+  ): ts.InterfaceDeclaration {
+    const typeName = `${appName}${this.capitalize(actionType)}Actions`;
+
+    const methods = typeActions.map((action) => {
+      const actionName = this.sanitizeActionName(action.key);
+
+      let methodSignature: ts.MethodSignature;
+
+      if (action.inputFields.length > 0) {
+        // Generate type-safe action method signature
+        const inputTypeName = `${appName}${this.capitalize(action.action_type)}${this.capitalize(
+          this.sanitizeActionName(action.key),
+        )}Inputs`;
+
+        const inputsType = this.factory.createTypeLiteralNode([
+          this.factory.createPropertySignature(
+            undefined,
+            "inputs",
+            undefined,
+            this.factory.createTypeReferenceNode(inputTypeName),
+          ),
+        ]);
+
+        const omitType = this.factory.createTypeReferenceNode("Omit", [
+          this.factory.createTypeReferenceNode("ActionExecutionOptions"),
+          this.factory.createLiteralTypeNode(
+            this.factory.createStringLiteral("inputs"),
+          ),
+        ]);
+
+        const optionsType = this.factory.createIntersectionTypeNode([
+          inputsType,
+          omitType,
+        ]);
+
+        methodSignature = this.factory.createMethodSignature(
+          undefined,
+          actionName,
+          undefined,
+          undefined,
+          [
+            this.factory.createParameterDeclaration(
+              undefined,
+              undefined,
+              "options",
+              undefined,
+              optionsType,
+            ),
+          ],
+          this.factory.createTypeReferenceNode("Promise", [
+            this.factory.createTypeReferenceNode("ActionExecutionResult"),
+          ]),
+        );
+      } else {
+        // No specific input fields available - use generic Record<string, any> for inputs
+        const genericInputsType = this.factory.createTypeLiteralNode([
+          this.factory.createPropertySignature(
+            undefined,
+            "inputs",
+            this.factory.createToken(ts.SyntaxKind.QuestionToken),
+            this.factory.createTypeReferenceNode("Record", [
+              this.factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+              this.factory.createKeywordTypeNode(ts.SyntaxKind.AnyKeyword),
+            ]),
+          ),
+        ]);
+
+        const intersectionType = this.factory.createIntersectionTypeNode([
+          genericInputsType,
+          this.factory.createTypeReferenceNode("ActionExecutionOptions"),
+        ]);
+
+        methodSignature = this.factory.createMethodSignature(
+          undefined,
+          actionName,
+          undefined,
+          undefined,
+          [
+            this.factory.createParameterDeclaration(
+              undefined,
+              undefined,
+              "options",
+              this.factory.createToken(ts.SyntaxKind.QuestionToken),
+              intersectionType,
+            ),
+          ],
+          this.factory.createTypeReferenceNode("Promise", [
+            this.factory.createTypeReferenceNode("ActionExecutionResult"),
+          ]),
+        );
+      }
+
+      // Add JSDoc comment if description exists
+      if (action.description) {
+        methodSignature = ts.addSyntheticLeadingComment(
+          methodSignature,
+          ts.SyntaxKind.MultiLineCommentTrivia,
+          `* ${this.escapeComment(action.description)} `,
+          true,
+        );
+      }
+
+      return methodSignature;
+    });
+
+    return this.factory.createInterfaceDeclaration(
+      undefined,
+      typeName,
+      undefined,
+      undefined,
+      methods,
+    );
+  }
+
+  private createAppProxyInterface(
+    appName: string,
+    actionsByType: Record<string, ActionWithActionFields[]>,
+  ): ts.InterfaceDeclaration {
+    const properties = [
+      ...Object.keys(actionsByType).map((actionType) =>
+        this.factory.createPropertySignature(
+          undefined,
+          actionType,
+          undefined,
+          this.factory.createTypeReferenceNode(
+            `${appName}${this.capitalize(actionType)}Actions`,
+          ),
+        ),
+      ),
+      // Always include fetch method for authenticated HTTP requests
+      this.createFetchMethodProperty(),
+    ];
+
+    return this.factory.createInterfaceDeclaration(
+      undefined,
+      `${appName}AppProxy`,
+      undefined,
+      undefined,
+      properties,
+    );
+  }
+
+  private createFetchMethodProperty(): ts.PropertySignature {
+    let property = this.factory.createPropertySignature(
+      undefined,
+      "fetch",
+      undefined,
+      this.factory.createFunctionTypeNode(
+        undefined,
+        [
+          this.factory.createParameterDeclaration(
+            undefined,
+            undefined,
+            "url",
+            undefined,
+            this.factory.createUnionTypeNode([
+              this.factory.createTypeReferenceNode("string"),
+              this.factory.createTypeReferenceNode("URL"),
+            ]),
+          ),
+          this.factory.createParameterDeclaration(
+            undefined,
+            undefined,
+            "init",
+            this.factory.createToken(ts.SyntaxKind.QuestionToken),
+            this.factory.createTypeReferenceNode("ZapierFetchInitOptions"),
+          ),
+        ],
+        this.factory.createTypeReferenceNode("Promise", [
+          this.factory.createTypeReferenceNode("Response"),
+        ]),
+      ),
+    );
+
+    // Add JSDoc comment
+    property = ts.addSyntheticLeadingComment(
+      property,
+      ts.SyntaxKind.MultiLineCommentTrivia,
+      "* Make authenticated HTTP requests through Zapier's Relay service ",
+      true,
+    );
+
+    return property;
+  }
+
+  private createAppFactoryInterface(appName: string): ts.InterfaceDeclaration {
+    const callSignature = this.factory.createCallSignature(
+      undefined,
+      [
+        this.factory.createParameterDeclaration(
+          undefined,
+          undefined,
+          "options",
+          undefined,
+          this.factory.createTypeLiteralNode([
+            this.factory.createPropertySignature(
+              undefined,
+              "authenticationId",
+              undefined,
+              this.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword),
+            ),
+          ]),
+        ),
+      ],
+      this.factory.createTypeReferenceNode(`${appName}AppProxy`),
+    );
+
+    return this.factory.createInterfaceDeclaration(
+      undefined,
+      `${appName}AppFactory`,
+      undefined,
+      undefined,
+      [callSignature],
+    );
+  }
+
+  private createAppWithFactoryType(appName: string): ts.TypeAliasDeclaration {
+    return this.factory.createTypeAliasDeclaration(
+      undefined,
+      `${appName}AppWithFactory`,
+      undefined,
+      this.factory.createIntersectionTypeNode([
+        this.factory.createTypeReferenceNode(`${appName}AppFactory`),
+        this.factory.createTypeReferenceNode(`${appName}AppProxy`),
+      ]),
+    );
+  }
+
+  private createModuleAugmentation(
+    appKey: string,
+    appName: string,
+  ): ts.ModuleDeclaration {
+    // Create: declare module "@zapier/zapier-sdk" { interface ZapierSdkApps { [appKey]: AppWithFactory } }
+    // This creates a new interface that we can merge with ZapierSdk
+    return this.factory.createModuleDeclaration(
+      [this.factory.createToken(ts.SyntaxKind.DeclareKeyword)],
+      this.factory.createStringLiteral("@zapier/zapier-sdk"),
+      this.factory.createModuleBlock([
+        this.factory.createInterfaceDeclaration(
+          undefined,
+          "ZapierSdkApps",
+          undefined,
+          undefined,
+          [
+            this.factory.createPropertySignature(
+              undefined,
+              appKey,
+              undefined,
+              this.factory.createTypeReferenceNode(`${appName}AppWithFactory`),
+            ),
+          ],
+        ),
+      ]),
+    );
+  }
+
+  private mapFieldTypeToTypeNode(field: ActionField): ts.TypeNode {
+    // 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"
+            ? this.factory.createLiteralTypeNode(
+                this.factory.createStringLiteral(choice.value),
+              )
+            : this.factory.createLiteralTypeNode(
+                this.factory.createNumericLiteral(String(choice.value)),
+              ),
+        );
+
+      if (choiceValues.length > 0) {
+        return this.factory.createUnionTypeNode(choiceValues);
+      }
+    }
+
+    // Map Zapier field types to TypeScript types
+    switch (field.type?.toLowerCase()) {
+      case "string":
+      case "text":
+      case "email":
+      case "url":
+      case "password":
+      case "datetime":
+      case "date":
+      case "file":
+        return this.factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword);
+      case "integer":
+      case "number":
+        return this.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword);
+      case "boolean":
+        return this.factory.createKeywordTypeNode(ts.SyntaxKind.BooleanKeyword);
+      case "array":
+        return this.factory.createArrayTypeNode(
+          this.factory.createKeywordTypeNode(ts.SyntaxKind.AnyKeyword),
+        );
+      case "object":
+        return this.factory.createTypeReferenceNode("Record", [
+          this.factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+          this.factory.createKeywordTypeNode(ts.SyntaxKind.AnyKeyword),
+        ]);
+      default:
+        // Default to string | number | boolean for unknown types
+        return this.factory.createUnionTypeNode([
+          this.factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+          this.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword),
+          this.factory.createKeywordTypeNode(ts.SyntaxKind.BooleanKeyword),
+        ]);
+    }
+  }
+
+  private generateEmptyTypesFile(appKey: string, version?: string): string {
+    const appName = this.capitalize(appKey);
+    const versionComment = version
+      ? ` * Generated for ${appKey}@${version}`
+      : ` * Generated for ${appKey}`;
+
+    return `/* eslint-disable @typescript-eslint/naming-convention, @typescript-eslint/no-explicit-any */
+/**
+ * Auto-generated TypeScript types for Zapier ${appKey} actions
+${versionComment}
+ * Generated on: ${new Date().toISOString()}
+ * 
+ * No actions found for this app.
+ */
+
+import type { ActionExecutionOptions, ActionExecutionResult, ZapierFetchInitOptions } from '@zapier/zapier-sdk'
+
+interface ${appName}AppProxy {
+  /** Make authenticated HTTP requests through Zapier's Relay service */
+  fetch: (url: string | URL, init?: ZapierFetchInitOptions) => Promise<Response>
+}
+
+interface ${appName}AppFactory {
+  (options: { authenticationId: number }): ${appName}AppProxy
+}
+
+type ${appName}AppWithFactory = ${appName}AppFactory & ${appName}AppProxy
+
+declare module "@zapier/zapier-sdk" {
+  interface ZapierSdkApps {
+    ${appKey}: ${appName}AppWithFactory
+  }
+}
+`;
+  }
+
+  private capitalize(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1).replace(/[-_]/g, "");
+  }
+
+  private 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;
+  }
+
+  private 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;
+  }
+
+  private escapeComment(comment: string): string {
+    // Escape comment text to prevent breaking the JSDoc comment
+    return comment.replace(/\*\//g, "*\\/").replace(/\r?\n/g, " ");
+  }
+}