@zapier/zapier-sdk 0.8.3 → 0.10.0

package/src/plugins/manifest/index.ts

@@ -1,30 +1,41 @@
-import { readFileSync } from "fs";
-import { resolve } from "path";
+import { readFile, writeFile, resolve } from "../../utils/file-utils";
 import type {
-  GetImplementation,
-  GetManifestEntry,
   GetVersionedImplementationId,
   Manifest,
+  ManifestEntry,
   ManifestPluginOptionsSchema,
+  ResolveAppKeys,
 } from "./schemas";
-import { ManifestSchema } from "./schemas";
-import type { GetSdkType, Plugin } from "../../types/plugin";
+import { ManifestSchema, DEFAULT_CONFIG_PATH } from "./schemas";
+import type { Plugin } from "../../types/plugin";
 import type { z } from "zod";
 import type { ApiClient } from "../../api";
-import type { ListAppsPluginProvides } from "../listApps";
-import type { ImplementationsResponse } from "../../api/types";
+import type { ImplementationsMetaResponse } from "../../api/types";
 import {
-  normalizeImplementationToAppItem,
+  normalizeImplementationMetaToAppItem,
   splitVersionedKey,
+  isSnakeCasedSlug,
+  dashifySnakeCasedSlug,
+  toAppLocator,
+  type ResolvedAppLocator,
+  isResolvedAppLocator,
 } from "../../utils/domain-utils";
+import type { AppItem } from "../../types/domain";
+import { extractCursor } from "../../utils/function-utils";
+import { paginate } from "../../utils/pagination-utils";
+import { toArrayFromAsync } from "../../utils/array-utils";
 
 export type ManifestPluginOptions = z.infer<typeof ManifestPluginOptionsSchema>;
 
 export interface ManifestPluginProvides {
   context: {
     getVersionedImplementationId: GetVersionedImplementationId;
-    getManifestEntry: GetManifestEntry;
-    getImplementation: GetImplementation;
+    resolveAppKeys: ResolveAppKeys;
+    updateManifestEntry: (
+      appKey: string,
+      entry: ManifestEntry,
+      configPath?: string,
+    ) => Promise<[string, ManifestEntry]>;
   };
 }
 
@@ -54,127 +65,372 @@ function parseManifestContent(
 }
 
 /**
- * Load manifest from a file path synchronously
- * Supports local files (Node.js only)
+ * Read manifest from a file path asynchronously
+ * Supports local files (Node.js) and browser environments (fallback to global filesystem)
  */
-export function loadManifestFromFile(filePath: string): Manifest | null {
+export async function readManifestFromFile(
+  filePath: string,
+): Promise<Manifest | null> {
   try {
     // Resolve relative paths relative to current working directory
-    const resolvedPath = resolve(filePath);
-    const content = readFileSync(resolvedPath, "utf8");
+    const resolvedPath = await resolve(filePath);
+    const content = await readFile(resolvedPath);
     return parseManifestContent(content, resolvedPath);
   } catch {
-    console.warn(`⚠️ Failed to load manifest from ${filePath}`);
+    console.warn(`⚠️ Failed to read manifest from ${filePath}`);
     return null;
   }
 }
 
-const emitWarning = (appKey: string) => {
-  console.warn(
-    `\n${"⚠️".padEnd(3)} ${"WARNING".padEnd(8)} No manifest version found for '${appKey}'`,
-  );
-  console.warn(
-    `   ${"↳".padEnd(3)} Using a manifest ensures version locking and prevents unexpected behavior due to version changes.`,
+/**
+ * Write manifest to a file path asynchronously
+ * Supports local files (Node.js) and browser environments (fallback to global filesystem)
+ */
+async function writeManifestToFile(
+  manifest: Manifest,
+  filePath: string,
+): Promise<void> {
+  const resolvedPath = await resolve(filePath);
+  await writeFile(resolvedPath, JSON.stringify(manifest, null, 2));
+}
+
+/**
+ * Get the preferred key for storing an app in the manifest
+ * Extracted from plugin to make it easier to test
+ */
+export async function getPreferredManifestEntryKey({
+  appKey,
+  api,
+}: {
+  appKey: string;
+  api: ApiClient;
+}): Promise<string> {
+  const locator = toAppLocator(appKey);
+
+  // If we have a slug, prefer it
+  if (locator.slug) {
+    return locator.slug;
+  }
+
+  // If we have implementation name, look up the latest to get the slug
+  if (locator.implementationName) {
+    try {
+      // API call to get app metadata by implementation name using selected_apis parameter
+      const implementationsEnvelope: ImplementationsMetaResponse =
+        await api.get(`/api/v4/implementations-meta/lookup/`, {
+          searchParams: {
+            selected_apis: locator.implementationName,
+          },
+        });
+
+      if (
+        implementationsEnvelope.results.length > 0 &&
+        implementationsEnvelope.results[0].slug
+      ) {
+        return implementationsEnvelope.results[0].slug;
+      }
+    } catch {
+      // Fall back to implementation name if lookup fails
+    }
+
+    return locator.implementationName;
+  }
+
+  // Fall back to original key if we can't determine anything better
+  return locator.lookupAppKey;
+}
+
+async function listAppsForSlugsPage({
+  slugs,
+  cursor,
+  api,
+}: {
+  slugs: string[];
+  cursor?: string;
+  api: ApiClient;
+}) {
+  const searchParams: Record<string, string> = {};
+
+  if (slugs.length > 0) {
+    searchParams.slugs = slugs.join(",");
+  }
+
+  if (cursor) {
+    searchParams.offset = cursor;
+  }
+
+  const implementationsEnvelope: ImplementationsMetaResponse = await api.get(
+    "/api/v4/implementations-meta/lookup/",
+    {
+      searchParams,
+    },
   );
-  console.warn(
-    `   ${"↳".padEnd(3)} Generate/update the manifest with: \`zapier-sdk lock-version ${appKey}\`\n`,
+
+  return {
+    data: implementationsEnvelope.results.map(
+      normalizeImplementationMetaToAppItem,
+    ),
+    nextCursor: extractCursor(implementationsEnvelope),
+  };
+}
+
+/**
+ * Find a manifest entry by any app key (implementation name, slug, etc.).
+ */
+export function findManifestEntry({
+  appKey,
+  manifest,
+}: {
+  appKey: string;
+  manifest: Manifest;
+}): [string, ManifestEntry] | null {
+  const [appKeyWithoutVersion] = splitVersionedKey(appKey);
+
+  // Direct match by key
+  if (manifest.apps[appKeyWithoutVersion]) {
+    return [appKeyWithoutVersion, manifest.apps[appKeyWithoutVersion]];
+  }
+
+  // Handle snake-cased slugs (convert to dashed)
+  if (isSnakeCasedSlug(appKey)) {
+    const slug = dashifySnakeCasedSlug(appKey);
+    if (manifest.apps[slug]) {
+      return [slug, manifest.apps[slug]];
+    }
+  }
+
+  // Search by implementation name in manifest values
+  for (const [key, entry] of Object.entries(manifest.apps)) {
+    if (entry.implementationName === appKeyWithoutVersion) {
+      return [key, entry];
+    }
+  }
+
+  // No match found
+  return null;
+}
+
+/**
+ * Turn any app keys (slugs, implementation names, etc.) into app locators, which are objects that will be guaranteed to
+ * have implementation names. Note that this function will not actually guarantee that implementation names are valid!
+ * It will attempt to find the app key in the manifest, or if it's a slug, actually do an API call, or otherwise just
+ * assume it's an implementation name that will be used for an API call.
+ */
+async function resolveAppKeys({
+  appKeys,
+  api,
+  manifest,
+}: {
+  appKeys: string[];
+  api: ApiClient;
+  manifest: Manifest;
+}): Promise<ResolvedAppLocator[]> {
+  // Step 1: Convert all app keys to locators
+  const locators = appKeys.map(toAppLocator);
+
+  // Step 2: Map to resolved/unresolved via manifest
+  const locatorsWithManifest = locators.map((locator) => {
+    const manifestEntryResult = findManifestEntry({
+      appKey: locator.lookupAppKey,
+      manifest,
+    });
+
+    if (manifestEntryResult) {
+      const [, manifestEntry] = manifestEntryResult;
+      // Use manifest entry to resolve implementation name
+      const resolvedVersion = locator.version || manifestEntry.version;
+
+      const resolvedLocator: ResolvedAppLocator = {
+        ...locator,
+        implementationName: manifestEntry.implementationName,
+        version: resolvedVersion,
+      };
+
+      return resolvedLocator;
+    }
+
+    // If these have an implementationName, they're already resolved.
+    return locator;
+  });
+
+  // Step 3: Separate resolved from unresolved
+  const unresolvedLocators = locatorsWithManifest.filter(
+    (locator) => !isResolvedAppLocator(locator),
   );
-};
+
+  // Step 4: Resolve slugs via API
+  const slugsToResolve = unresolvedLocators
+    .map((locator) => locator.slug)
+    .filter((slug): slug is string => !!slug)
+    .filter((slug, index, array) => array.indexOf(slug) === index); // dedupe
+
+  if (slugsToResolve.length === 0) {
+    return locatorsWithManifest.filter(isResolvedAppLocator);
+  }
+
+  const iterator = paginate(listAppsForSlugsPage, {
+    slugs: slugsToResolve,
+    api,
+  });
+
+  const pages = await toArrayFromAsync(iterator);
+  const apps = pages.flatMap((page) => page.data);
+
+  const slugToAppData = new Map<string, AppItem>();
+  for (const app of apps) {
+    if (app.slug) {
+      slugToAppData.set(app.slug, app);
+    }
+  }
+
+  const slugResolvedLocators = locatorsWithManifest.map((locator) => {
+    if (isResolvedAppLocator(locator)) {
+      return locator;
+    }
+    if (locator.slug) {
+      const appData = slugToAppData.get(locator.slug);
+      if (appData) {
+        // After resolving from API, check if we have a manifest entry for this implementation name
+        const manifestEntryByImplementationName = findManifestEntry({
+          appKey: appData.key, // appData.key is the implementation name
+          manifest,
+        });
+
+        let version = locator.version;
+        if (!version) {
+          // Prefer manifest version if available, otherwise use API version
+          version = manifestEntryByImplementationName
+            ? manifestEntryByImplementationName[1].version || appData.version
+            : appData.version;
+        }
+
+        return {
+          ...locator,
+          implementationName: appData.key,
+          version,
+        };
+      }
+    }
+    return locator;
+  });
+
+  // Return all resolved locators.
+  return slugResolvedLocators.filter(isResolvedAppLocator);
+}
+
+export { DEFAULT_CONFIG_PATH } from "./schemas";
 
 export const manifestPlugin: Plugin<
-  GetSdkType<ListAppsPluginProvides>,
+  {}, // no SDK dependencies
   { api: ApiClient },
   ManifestPluginProvides
 > = (params) => {
-  const { sdk, context } = params;
+  const { context } = params;
   const { api, options } = context;
-  const { manifestPath = ".zapierrc", manifest } = options || {};
+  const { manifestPath = DEFAULT_CONFIG_PATH, manifest } = options || {};
 
   let resolvedManifest: Manifest | undefined | null;
 
-  function resolveManifest() {
+  async function resolveManifest(): Promise<Manifest | null> {
     // If manifest is provided directly, use it
     if (manifest) {
       return manifest;
     }
     // If manifestPath is provided, load from file
     if (manifestPath) {
-      return loadManifestFromFile(manifestPath);
+      return await readManifestFromFile(manifestPath);
     }
     return null;
   }
 
-  const getResolvedManifest = () => {
+  const getResolvedManifest = async (): Promise<Manifest | null> => {
     if (typeof resolvedManifest === "undefined") {
-      resolvedManifest = resolveManifest() ?? null;
+      resolvedManifest = (await resolveManifest()) ?? null;
     }
 
     return resolvedManifest;
   };
 
-  const getManifestEntry = (appKey: string) => {
-    return getResolvedManifest()?.apps?.[appKey] || null;
+  const getVersionedImplementationId = async (appKey: string) => {
+    const resolvedApps = await resolveAppKeys({
+      appKeys: [appKey],
+      api,
+      manifest: (await getResolvedManifest()) ?? { apps: {} },
+    });
+
+    const resolvedApp = resolvedApps[0];
+    if (!resolvedApp) return null;
+
+    return `${resolvedApp.implementationName}@${resolvedApp.version || "latest"}`;
   };
 
-  const getImplementation = async (appKey: string) => {
-    let selectedApi = null;
-    const manifestImplementation = getResolvedManifest()?.apps?.[appKey];
-    const [versionlessAppKey, version] = splitVersionedKey(appKey);
-
-    // Use versioned app key if provided
-    if (version) {
-      selectedApi = `${versionlessAppKey}@${version}`;
-      // Otherwise, use manifest entry if available
-    } else if (manifestImplementation) {
-      selectedApi = `${manifestImplementation.implementationName}@${manifestImplementation.version || "latest"}`;
-    }
+  const updateManifestEntry = async (
+    appKey: string,
+    entry: ManifestEntry,
+    configPath: string = DEFAULT_CONFIG_PATH,
+  ): Promise<[string, ManifestEntry]> => {
+    const manifest = (await readManifestFromFile(configPath)) || { apps: {} };
 
-    if (selectedApi) {
-      const searchParams = {
-        selected_apis: selectedApi,
-      };
-      const implementationData: ImplementationsResponse = await api.get(
-        "/api/v4/implementations/",
-        {
-          searchParams,
-        },
-      );
-      const implementationResults = implementationData.results[0];
-      if (!implementationResults) return null;
-      return normalizeImplementationToAppItem(implementationResults);
-    }
-    emitWarning(appKey);
+    // Try to find existing entry by direct key first
+    let existingEntry = findManifestEntry({
+      appKey,
+      manifest,
+    });
 
-    const appsIterator = sdk.listApps({ appKeys: [appKey] }).items();
+    // If not found directly, try to resolve the app key and search by implementation name
+    if (!existingEntry) {
+      try {
+        const resolvedApps = await resolveAppKeys({
+          appKeys: [appKey],
+          api,
+          manifest,
+        });
 
-    const apps = [];
-    for await (const app of appsIterator) {
-      apps.push(app);
-      break; // Only need the first result
+        if (resolvedApps.length > 0) {
+          const resolvedImplementationName = resolvedApps[0].implementationName;
+          // Try to find entry using the resolved implementation name
+          existingEntry = findManifestEntry({
+            appKey: resolvedImplementationName,
+            manifest,
+          });
+        }
+      } catch {
+        // If resolution fails, continue with original logic
+      }
     }
 
-    if (apps.length === 0) {
-      return null;
-    }
-    const app = apps[0];
-    return app;
-  };
+    let manifestKey: string;
 
-  const getVersionedImplementationId = async (appKey: string) => {
-    const manifestEntry = getManifestEntry(appKey);
-    if (manifestEntry) {
-      return `${manifestEntry.implementationName}@${manifestEntry.version || "latest"}`;
+    if (existingEntry) {
+      // Use existing key to maintain consistency with types files
+      manifestKey = existingEntry[0];
+    } else {
+      // Get preferred key for new entries
+      manifestKey = await getPreferredManifestEntryKey({
+        appKey,
+        api,
+      });
     }
-    const implementation = await getImplementation(appKey);
-    if (!implementation) return null;
-    return implementation.current_implementation_id;
+
+    manifest.apps[manifestKey] = entry;
+    await writeManifestToFile(manifest, configPath);
+
+    // Clear the cached manifest so it gets reloaded with the new data
+    resolvedManifest = undefined;
+
+    return [manifestKey, entry];
   };
 
   return {
     context: {
       getVersionedImplementationId,
-      getManifestEntry,
-      getImplementation,
+      resolveAppKeys: async ({ appKeys }: { appKeys: string[] }) =>
+        resolveAppKeys({
+          appKeys,
+          api,
+          manifest: (await getResolvedManifest()) ?? { apps: {} },
+        }),
+      updateManifestEntry,
     },
   };
 };

package/src/plugins/manifest/schemas.ts

@@ -1,13 +1,14 @@
 import { z } from "zod";
+import type { ResolvedAppLocator } from "../../utils/domain-utils";
 import type { AppItem } from "../../types/domain";
 
+export const DEFAULT_CONFIG_PATH = ".zapierrc" as const;
+
 export type ManifestEntry = {
   implementationName: string;
   version?: string;
 };
 
-export type GetManifestEntry = (appKey: string) => ManifestEntry | null;
-
 export type GetVersionedImplementationId = (
   appKey: string,
 ) => Promise<string | null>;
@@ -18,6 +19,12 @@ export type Manifest = {
   apps: Record<string, ManifestEntry>;
 };
 
+export type ResolveAppKeys = ({
+  appKeys,
+}: {
+  appKeys: string[];
+}) => Promise<ResolvedAppLocator[]>;
+
 /**
  * Manifest schema for version locking
  * Maps app keys to their locked version information

package/src/plugins/registry/index.ts

@@ -55,10 +55,16 @@ export const registryPlugin: Plugin<
   const functions = metaKeys
     .filter((key) => typeof sdk[key as keyof typeof sdk] === "function")
     .map((key) => {
+      const meta = context.meta[key];
       return {
-        ...context.meta[key],
-        categories: context.meta[key].categories || [],
         name: key,
+        type: meta.type,
+        itemType: meta.itemType,
+        returnType: meta.returnType,
+        inputSchema: meta.inputSchema,
+        outputSchema: meta.outputSchema,
+        categories: meta.categories || [],
+        resolvers: meta.resolvers,
       };
     })
     .sort((a, b) => a.name.localeCompare(b.name));

package/src/plugins/request/index.ts

@@ -96,6 +96,7 @@ export const requestPlugin: Plugin<
       meta: {
         request: {
           categories: ["http"],
+          returnType: "Response",
           inputSchema: RelayRequestSchema,
         },
       },

package/src/plugins/runAction/index.ts

@@ -5,6 +5,7 @@ import {
   type RunActionOptions,
   type RunActionPage,
 } from "./schemas";
+import { ActionResultItemSchema } from "../../schemas/Run";
 import {
   ZapierValidationError,
   ZapierConfigurationError,
@@ -13,6 +14,13 @@ import {
 import { createPaginatedFunction } from "../../utils/function-utils";
 import type { GetActionPluginProvides } from "../getAction";
 import type { GetAppPluginProvides } from "../getApp";
+import {
+  appKeyResolver,
+  actionTypeResolver,
+  actionKeyResolver,
+  authenticationIdResolver,
+  inputsResolver,
+} from "../../resolvers";
 import type { GetVersionedImplementationId } from "../manifest/schemas";
 
 export interface RunActionPluginProvides {
@@ -177,7 +185,17 @@ export const runActionPlugin: Plugin<
       meta: {
         runAction: {
           categories: ["action"],
+          type: "list",
+          itemType: "ActionResult",
           inputSchema: RunActionSchema,
+          outputSchema: ActionResultItemSchema,
+          resolvers: {
+            appKey: appKeyResolver,
+            actionType: actionTypeResolver,
+            actionKey: actionKeyResolver,
+            authenticationId: authenticationIdResolver,
+            inputs: inputsResolver,
+          },
         },
       },
     },

package/src/resolvers/actionKey.ts

@@ -1,27 +1,29 @@
-import type { ZapierSdk } from "../types/sdk";
+import type { DynamicResolver } from "../utils/schema-utils";
+import type { ActionTypeProperty } from "../types/properties";
 
-export interface ActionKeyResolver {
-  type: "dynamic";
-  depends: readonly string[];
-  fetch: (
-    sdk: ZapierSdk,
-    resolvedParams: Record<string, any>,
-  ) => Promise<any[]>;
-  prompt: (items: any[], params: Record<string, any>) => any;
+interface ActionItem {
+  key: string;
+  title?: string;
+  name?: string;
+  description?: string;
+  action_type: string;
 }
 
-export const actionKeyResolver: ActionKeyResolver = {
+export const actionKeyResolver: DynamicResolver<
+  ActionItem,
+  { appKey: string; actionType: ActionTypeProperty }
+> = {
   type: "dynamic",
   depends: ["appKey", "actionType"] as const,
-  fetch: async (sdk: ZapierSdk, resolvedParams: Record<string, any>) => {
+  fetch: async (sdk, resolvedParams) => {
     const actionsResponse = await sdk.listActions({
       appKey: resolvedParams.appKey,
     });
     return actionsResponse.data.filter(
-      (action: any) => action.action_type === resolvedParams.actionType,
+      (action: ActionItem) => action.action_type === resolvedParams.actionType,
     );
   },
-  prompt: (actions: any[]) => ({
+  prompt: (actions) => ({
     type: "list",
     name: "actionKey",
     message: "Select action:",

package/src/resolvers/actionType.ts

@@ -1,19 +1,17 @@
-import type { ZapierSdk } from "../types/sdk";
+import type { DynamicResolver } from "../utils/schema-utils";
 
-export interface ActionTypeResolver {
-  type: "dynamic";
-  depends: readonly string[];
-  fetch: (
-    sdk: ZapierSdk,
-    resolvedParams: Record<string, any>,
-  ) => Promise<any[]>;
-  prompt: (items: any[], params: Record<string, any>) => any;
+interface ActionTypeItem {
+  key: string;
+  name: string;
 }
 
-export const actionTypeResolver: ActionTypeResolver = {
+export const actionTypeResolver: DynamicResolver<
+  ActionTypeItem,
+  { appKey: string }
+> = {
   type: "dynamic",
   depends: ["appKey"] as const,
-  fetch: async (sdk: ZapierSdk, resolvedParams: Record<string, any>) => {
+  fetch: async (sdk, resolvedParams) => {
     const actionsResponse = await sdk.listActions({
       appKey: resolvedParams.appKey,
     });
@@ -23,7 +21,7 @@ export const actionTypeResolver: ActionTypeResolver = {
     ];
     return types.map((type) => ({ key: type, name: type }));
   },
-  prompt: (types: any[]) => ({
+  prompt: (types) => ({
     type: "list",
     name: "actionType",
     message: "Select action type:",

package/src/resolvers/appKey.ts

@@ -1,10 +1,6 @@
-export interface AppKeyResolver {
-  type: "static";
-  inputType?: "text" | "password" | "email";
-  placeholder?: string;
-}
+import type { StaticResolver } from "../utils/schema-utils";
 
-export const appKeyResolver: AppKeyResolver = {
+export const appKeyResolver: StaticResolver = {
   type: "static",
   inputType: "text",
   placeholder: "Enter app key (e.g., 'SlackCLIAPI' or slug like 'github')",