@zapier/zapier-sdk-cli 0.13.5 → 0.13.6

package/src/plugins/buildManifest/index.ts

@@ -0,0 +1,128 @@
+import type {
+  Plugin,
+  GetSdkType,
+  GetContextType,
+  ListAppsPluginProvides,
+  ManifestPluginProvides,
+  AppItem,
+  Manifest,
+} from "@zapier/zapier-sdk";
+import { createFunction } from "@zapier/zapier-sdk";
+import {
+  BuildManifestSchema,
+  type BuildManifestOptions,
+  type BuildManifestResult,
+} from "./schemas";
+import { createManifestEntry } from "../../utils/manifest-helpers";
+
+export interface BuildManifestPluginProvides {
+  buildManifest: (
+    options: BuildManifestOptions,
+  ) => Promise<BuildManifestResult>;
+  context: {
+    meta: {
+      buildManifest: {
+        inputSchema: typeof BuildManifestSchema;
+      };
+    };
+  };
+}
+
+export const buildManifestPlugin: Plugin<
+  GetSdkType<ListAppsPluginProvides>,
+  GetContextType<ManifestPluginProvides>,
+  BuildManifestPluginProvides
+> = ({ sdk, context }) => {
+  const buildManifest = createFunction(async function buildManifest(
+    options: BuildManifestOptions,
+  ): Promise<BuildManifestResult> {
+    const { appKeys, skipWrite = false, configPath, onProgress } = options;
+
+    const result: BuildManifestResult = {
+      errors: [],
+    };
+
+    // Get apps using listApps (which respects existing manifest for version locking)
+    onProgress?.({ type: "apps_lookup_start", count: appKeys.length });
+    const appsIterator = sdk.listApps({ appKeys }).items();
+    const apps: AppItem[] = [];
+    for await (const app of appsIterator) {
+      apps.push(app);
+      onProgress?.({ type: "app_found", app });
+    }
+    onProgress?.({ type: "apps_lookup_complete", count: apps.length });
+
+    if (apps.length === 0) {
+      return result;
+    }
+
+    let updatedManifest: Manifest | undefined;
+
+    // Process each app
+    for (const app of apps) {
+      onProgress?.({
+        type: "app_processing_start",
+        appKey: app.key,
+        slug: app.slug,
+      });
+
+      try {
+        const manifestEntry = createManifestEntry(app);
+
+        onProgress?.({
+          type: "manifest_entry_built",
+          appKey: app.key,
+          manifestKey: manifestEntry.implementationName,
+          version: manifestEntry.version,
+        });
+
+        const [updatedManifestKey, , manifest] =
+          await context.updateManifestEntry({
+            appKey: app.key,
+            entry: manifestEntry,
+            configPath,
+            skipWrite,
+            manifest: updatedManifest,
+          });
+
+        updatedManifest = manifest;
+
+        onProgress?.({
+          type: "manifest_updated",
+          appKey: app.key,
+          manifestKey: updatedManifestKey,
+          version: manifestEntry.version,
+        });
+
+        onProgress?.({ type: "app_processing_complete", appKey: app.key });
+      } catch (error) {
+        const errorMessage = `Failed to process app: ${error}`;
+        result.errors.push({
+          appKey: app.key,
+          error: errorMessage,
+        });
+        onProgress?.({
+          type: "app_processing_error",
+          appKey: app.key,
+          error: errorMessage,
+        });
+      }
+    }
+
+    result.manifest = updatedManifest;
+
+    return result;
+  }, BuildManifestSchema);
+
+  return {
+    buildManifest,
+    context: {
+      meta: {
+        buildManifest: {
+          categories: ["utility"],
+          inputSchema: BuildManifestSchema,
+        },
+      },
+    },
+  };
+};

package/src/plugins/buildManifest/schemas.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import type { AppItem, ManifestEntry, Manifest } from "@zapier/zapier-sdk";
+
+export const BuildManifestSchema = z
+  .object({
+    appKeys: z
+      .array(z.string().min(1, "App key cannot be empty"))
+      .min(1, "At least one app key is required")
+      .describe(
+        "One or more app keys to build manifest entries for (e.g., 'slack', 'github', 'trello')",
+      ),
+    skipWrite: z
+      .boolean()
+      .optional()
+      .describe(
+        "If true, returns manifest entries without writing to disk. If false or omitted, writes to the manifest file.",
+      ),
+    configPath: z
+      .string()
+      .optional()
+      .describe(
+        "Path to the manifest file. Only used when skipWrite is false or omitted.",
+      ),
+  })
+  .describe(
+    "Build manifest entries for apps - can optionally write to disk or just return JSON",
+  );
+
+export type BuildManifestOptions = z.infer<typeof BuildManifestSchema> & {
+  onProgress?: (event: ManifestBuildProgressEvent) => void;
+};
+
+export type ManifestBuildProgressEvent =
+  | { type: "apps_lookup_start"; count: number }
+  | { type: "app_found"; app: AppItem }
+  | { type: "apps_lookup_complete"; count: number }
+  | { type: "app_processing_start"; appKey: string; slug?: string }
+  | {
+      type: "manifest_entry_built";
+      appKey: string;
+      manifestKey: string;
+      version: string;
+    }
+  | {
+      type: "manifest_updated";
+      appKey: string;
+      manifestKey: string;
+      version: string;
+    }
+  | { type: "app_processing_complete"; appKey: string }
+  | { type: "app_processing_error"; appKey: string; error: string };
+
+export interface BuildManifestResult {
+  manifest?: Manifest; // The updated manifest, included when skipWrite is false
+  errors: Array<{
+    appKey: string;
+    error: string;
+  }>;
+}
+
+export type { ManifestEntry };

package/src/plugins/generateAppTypes/index.ts

@@ -0,0 +1,235 @@
+import type {
+  Plugin,
+  GetSdkType,
+  ListActionsPluginProvides,
+  ListAppsPluginProvides,
+  ListInputFieldsPluginProvides,
+  ListAuthenticationsPluginProvides,
+  ManifestPluginProvides,
+  AppItem,
+} from "@zapier/zapier-sdk";
+import { createFunction } from "@zapier/zapier-sdk";
+import {
+  GenerateAppTypesSchema,
+  type GenerateAppTypesOptions,
+  type GenerateAppTypesResult,
+} from "./schemas";
+import { AstTypeGenerator } from "../../generators/ast-generator";
+import { getManifestKey } from "../../utils/manifest-helpers";
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+
+export interface GenerateAppTypesPluginProvides {
+  generateAppTypes: (
+    options: GenerateAppTypesOptions,
+  ) => Promise<GenerateAppTypesResult>;
+  context: {
+    meta: {
+      generateAppTypes: {
+        inputSchema: typeof GenerateAppTypesSchema;
+      };
+    };
+  };
+}
+
+export const generateAppTypesPlugin: Plugin<
+  GetSdkType<
+    ListAppsPluginProvides &
+      ListActionsPluginProvides &
+      ListInputFieldsPluginProvides &
+      ListAuthenticationsPluginProvides &
+      ManifestPluginProvides
+  >,
+  {},
+  GenerateAppTypesPluginProvides
+> = ({ sdk }) => {
+  const generateAppTypes = createFunction(async function generateAppTypes(
+    options: GenerateAppTypesOptions,
+  ): Promise<GenerateAppTypesResult> {
+    const {
+      appKeys,
+      authenticationIds,
+      skipWrite = false,
+      typesOutputDirectory,
+      onProgress,
+    } = options;
+
+    // Validate that typesOutputDirectory is provided when skipWrite is false
+    if (!skipWrite && !typesOutputDirectory) {
+      throw new Error(
+        "typesOutputDirectory is required when skipWrite is false",
+      );
+    }
+
+    const result: GenerateAppTypesResult = {
+      typeDefinitions: {},
+      errors: [],
+    };
+
+    // Get apps using listApps (which respects existing manifest for version locking)
+    onProgress?.({ type: "apps_lookup_start", count: appKeys.length });
+    const appsIterator = sdk.listApps({ appKeys }).items();
+    const apps: AppItem[] = [];
+    for await (const app of appsIterator) {
+      apps.push(app);
+      onProgress?.({ type: "app_found", app });
+    }
+    onProgress?.({ type: "apps_lookup_complete", count: apps.length });
+
+    if (apps.length === 0) {
+      return result;
+    }
+
+    // Fetch authentications if provided
+    const authentications = [];
+    if (authenticationIds && authenticationIds.length > 0) {
+      onProgress?.({
+        type: "authentications_lookup_start",
+        count: authenticationIds.length,
+      });
+      const authsIterator = sdk
+        .listAuthentications({ authenticationIds })
+        .items();
+      for await (const auth of authsIterator) {
+        authentications.push(auth);
+      }
+      onProgress?.({
+        type: "authentications_lookup_complete",
+        count: authentications.length,
+      });
+    }
+
+    // Ensure output directory exists if we're writing files
+    if (!skipWrite && typesOutputDirectory) {
+      await mkdir(typesOutputDirectory, { recursive: true });
+    }
+
+    // Initialize writtenFiles if we're writing to disk
+    if (!skipWrite) {
+      result.writtenFiles = {};
+    }
+
+    // Process each app
+    for (const app of apps) {
+      onProgress?.({
+        type: "app_processing_start",
+        appKey: app.key,
+        slug: app.slug,
+      });
+
+      try {
+        if (!app.version) {
+          const error = `Invalid implementation ID format: ${app.implementation_id}. Expected format: <implementationName>@<version>`;
+          result.errors.push({
+            appKey: app.key,
+            error,
+          });
+          onProgress?.({
+            type: "app_processing_error",
+            appKey: app.key,
+            error,
+          });
+          continue;
+        }
+
+        // Find matching authentication for this app if authentications were provided
+        let authenticationId: number | undefined;
+        if (authentications.length > 0) {
+          const matchingAuth = authentications.find((auth) => {
+            return auth.app_key === app.key;
+          });
+
+          if (matchingAuth) {
+            authenticationId = matchingAuth.id;
+            onProgress?.({
+              type: "authentication_matched",
+              appKey: app.key,
+              authenticationId: matchingAuth.id,
+              authenticationTitle: matchingAuth.title || "",
+            });
+          } else {
+            onProgress?.({
+              type: "authentication_not_matched",
+              appKey: app.key,
+            });
+          }
+        }
+
+        const manifestKey = getManifestKey(app);
+
+        // Generate type definitions
+        try {
+          const generator = new AstTypeGenerator();
+          const typeDefinitionString = await generator.generateTypes({
+            app,
+            authenticationId,
+            sdk,
+          });
+
+          result.typeDefinitions[manifestKey] = typeDefinitionString;
+
+          onProgress?.({
+            type: "type_generated",
+            manifestKey,
+            sizeBytes: typeDefinitionString.length,
+          });
+
+          // Write to file if skipWrite is false
+          if (!skipWrite && typesOutputDirectory && result.writtenFiles) {
+            const filePath = join(typesOutputDirectory, `${manifestKey}.d.ts`);
+            await writeFile(filePath, typeDefinitionString, "utf8");
+
+            result.writtenFiles[manifestKey] = filePath;
+
+            onProgress?.({
+              type: "file_written",
+              manifestKey,
+              filePath,
+            });
+          }
+
+          onProgress?.({
+            type: "app_processing_complete",
+            appKey: app.key,
+          });
+        } catch (error) {
+          const errorMessage = `Failed to generate types: ${error}`;
+          result.errors.push({
+            appKey: app.key,
+            error: errorMessage,
+          });
+          onProgress?.({
+            type: "app_processing_error",
+            appKey: app.key,
+            error: errorMessage,
+          });
+        }
+      } catch (error) {
+        const errorMessage = `Failed to process app: ${error}`;
+        result.errors.push({
+          appKey: app.key,
+          error: errorMessage,
+        });
+        onProgress?.({
+          type: "app_processing_error",
+          appKey: app.key,
+          error: errorMessage,
+        });
+      }
+    }
+
+    return result;
+  }, GenerateAppTypesSchema);
+
+  return {
+    generateAppTypes,
+    context: {
+      meta: {
+        generateAppTypes: {
+          categories: ["utility"],
+          inputSchema: GenerateAppTypesSchema,
+        },
+      },
+    },
+  };
+};

package/src/plugins/generateAppTypes/schemas.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import type { AppItem } from "@zapier/zapier-sdk";
+
+export const GenerateAppTypesSchema = z
+  .object({
+    appKeys: z
+      .array(z.string().min(1, "App key cannot be empty"))
+      .min(1, "At least one app key is required")
+      .describe(
+        "One or more app keys to generate types for (e.g., 'slack', 'github', 'trello')",
+      ),
+    authenticationIds: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Authentication IDs to use for type generation (e.g., ['123', '456'])",
+      ),
+    skipWrite: z
+      .boolean()
+      .optional()
+      .describe(
+        "If true, returns type definitions without writing to disk. If false or omitted, writes type files.",
+      ),
+    typesOutputDirectory: z
+      .string()
+      .optional()
+      .describe(
+        "Directory for TypeScript type files. Required when skipWrite is false or omitted.",
+      ),
+  })
+  .describe(
+    "Generate TypeScript type definitions for apps - can optionally write to disk or just return type strings",
+  );
+
+export type GenerateAppTypesOptions = z.infer<typeof GenerateAppTypesSchema> & {
+  onProgress?: (event: AppTypesProgressEvent) => void;
+};
+
+export type AppTypesProgressEvent =
+  | { type: "apps_lookup_start"; count: number }
+  | { type: "app_found"; app: AppItem }
+  | { type: "apps_lookup_complete"; count: number }
+  | { type: "authentications_lookup_start"; count: number }
+  | { type: "authentications_lookup_complete"; count: number }
+  | { type: "app_processing_start"; appKey: string; slug?: string }
+  | {
+      type: "authentication_matched";
+      appKey: string;
+      authenticationId: number;
+      authenticationTitle: string;
+    }
+  | { type: "authentication_not_matched"; appKey: string }
+  | { type: "type_generated"; manifestKey: string; sizeBytes: number }
+  | { type: "file_written"; manifestKey: string; filePath: string }
+  | { type: "app_processing_complete"; appKey: string }
+  | { type: "app_processing_error"; appKey: string; error: string };
+
+export interface GenerateAppTypesResult {
+  typeDefinitions: Record<string, string>; // manifestKey -> type definition string
+  writtenFiles?: Record<string, string>; // manifestKey -> file path (only when skipWrite is false)
+  errors: Array<{
+    appKey: string;
+    error: string;
+  }>;
+}

package/src/plugins/index.ts

@@ -4,3 +4,5 @@ export { mcpPlugin } from "./mcp";
 export { bundleCodePlugin } from "./bundleCode";
 export { getLoginConfigPathPlugin } from "./getLoginConfigPath";
 export { addPlugin } from "./add";
+export { generateAppTypesPlugin } from "./generateAppTypes";
+export { buildManifestPlugin } from "./buildManifest";

package/src/sdk.ts

@@ -1,7 +1,6 @@
 import {
   createZapierSdkWithoutRegistry,
   registryPlugin,
-  type ZapierSdk,
 } from "@zapier/zapier-sdk";
 import {
   loginPlugin,
@@ -10,7 +9,10 @@ import {
   bundleCodePlugin,
   getLoginConfigPathPlugin,
   addPlugin,
+  generateAppTypesPlugin,
+  buildManifestPlugin,
 } from "./plugins/index";
+import type { ZapierSdkCli } from "./types/sdk";
 
 export interface ZapierCliSdkOptions {
   debug?: boolean;
@@ -30,23 +32,24 @@ export interface ZapierCliSdkOptions {
  */
 export function createZapierCliSdk(
   options: ZapierCliSdkOptions = {},
-): ZapierSdk {
-  // Create SDK instance without registry
-  let sdk = createZapierSdkWithoutRegistry({
-    debug: options.debug,
-    eventEmission: options.eventEmission,
-  });
-
-  // Add CLI-specific plugins before registry
-  sdk = sdk.addPlugin(bundleCodePlugin);
-  sdk = sdk.addPlugin(getLoginConfigPathPlugin);
-  sdk = sdk.addPlugin(addPlugin);
-  sdk = sdk.addPlugin(mcpPlugin);
-  sdk = sdk.addPlugin(loginPlugin);
-  sdk = sdk.addPlugin(logoutPlugin);
-
-  // Add registry plugin to finalize SDK
-  const finalSdk = sdk.addPlugin(registryPlugin);
-
-  return finalSdk;
+): ZapierSdkCli {
+  // Create SDK instance and chain all plugins
+  // Chaining prevents type widening that occurs with let reassignment
+  return (
+    createZapierSdkWithoutRegistry({
+      debug: options.debug,
+      eventEmission: options.eventEmission,
+    })
+      // Add CLI-specific plugins before registry
+      .addPlugin(generateAppTypesPlugin)
+      .addPlugin(buildManifestPlugin)
+      .addPlugin(bundleCodePlugin)
+      .addPlugin(getLoginConfigPathPlugin)
+      .addPlugin(addPlugin)
+      .addPlugin(mcpPlugin)
+      .addPlugin(loginPlugin)
+      .addPlugin(logoutPlugin)
+      // Add registry plugin to finalize SDK
+      .addPlugin(registryPlugin)
+  );
 }

package/src/types/sdk.ts

@@ -0,0 +1,8 @@
+import type { GetSdkType, ZapierSdk } from "@zapier/zapier-sdk";
+import type { BuildManifestPluginProvides } from "../plugins/buildManifest";
+import type { GenerateAppTypesPluginProvides } from "../plugins/generateAppTypes";
+
+export interface ZapierSdkCli
+  extends GetSdkType<
+    ZapierSdk & BuildManifestPluginProvides & GenerateAppTypesPluginProvides
+  > {}

package/src/utils/directory-detection.ts

@@ -0,0 +1,23 @@
+import { access } from "fs/promises";
+import { join } from "path";
+
+/**
+ * Detect the best default directory for TypeScript types
+ * Looks for src or lib directories, falls back to current directory
+ */
+export async function detectTypesOutputDirectory(): Promise<string> {
+  // Check for common source directories in priority order
+  const candidates = ["src", "lib"];
+
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return join(candidate, "zapier", "apps");
+    } catch {
+      // Directory doesn't exist, continue to next candidate
+    }
+  }
+
+  // Fall back to current directory
+  return "./zapier/apps/";
+}

package/src/utils/manifest-helpers.ts

@@ -0,0 +1,28 @@
+import type { AppItem } from "@zapier/zapier-sdk";
+
+/**
+ * Get the preferred key for a manifest entry
+ * Prefers slug over implementation name
+ */
+export function getManifestKey(app: AppItem): string {
+  return app.slug || app.key;
+}
+
+/**
+ * Create a manifest entry from an app
+ */
+export function createManifestEntry(app: AppItem): {
+  implementationName: string;
+  version: string;
+} {
+  if (!app.version) {
+    throw new Error(
+      `App ${app.key} does not have a version. Implementation ID: ${app.implementation_id}`,
+    );
+  }
+
+  return {
+    implementationName: app.key,
+    version: app.version,
+  };
+}