@zapier/zapier-sdk 0.8.2 → 0.9.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/sdk.ts

@@ -32,7 +32,6 @@ import { listInputFieldsPlugin } from "./plugins/listInputFields";
 import { listInputFieldChoicesPlugin } from "./plugins/listInputFieldChoices";
 import { requestPlugin } from "./plugins/request";
 import { manifestPlugin } from "./plugins/manifest";
-import { lockVersionPlugin } from "./plugins/lockVersion";
 
 // Full SDK interface with plugins applied
 // Note: ZapierSdk is now defined as ReturnType<typeof createZapierSdk> at the bottom of this file
@@ -125,10 +124,10 @@ export function createZapierSdkWithoutRegistry(options: ZapierSdkOptions = {}) {
       .addPlugin(apiPlugin)
 
       // Manifest plugin (provides version locking context)
+      .addPlugin(manifestPlugin)
 
       // Apps/actions/fields
       .addPlugin(listAppsPlugin)
-      .addPlugin(manifestPlugin)
       .addPlugin(getAppPlugin)
       .addPlugin(listActionsPlugin)
       .addPlugin(getActionPlugin)
@@ -138,9 +137,6 @@ export function createZapierSdkWithoutRegistry(options: ZapierSdkOptions = {}) {
       // Run action
       .addPlugin(runActionPlugin)
 
-      // Version locking
-      .addPlugin(lockVersionPlugin)
-
       // Authentications
       .addPlugin(listAuthenticationsPlugin)
       .addPlugin(getAuthenticationPlugin)

package/src/types/plugin.ts

@@ -41,6 +41,9 @@ export type GetSdkType<TPluginProvides extends PluginProvides> =
     getContext(): NonNullable<ExtractContextProperties<TPluginProvides>>;
   };
 
+export type GetContextType<TPluginProvides extends PluginProvides> =
+  NonNullable<ExtractContextProperties<TPluginProvides>>;
+
 // Helper type for standard plugin options with SDK dependency and meta context
 export type PluginOptions<TSdk = {}, TContext = {}> = {
   sdk: TSdk;

package/src/types/sdk.ts

@@ -29,12 +29,12 @@ import type { GetAuthenticationSdkFunction } from "../plugins/getAuthentication/
 import type { FindFirstAuthenticationSdkFunction } from "../plugins/findFirstAuthentication/schemas";
 import type { FindUniqueAuthenticationSdkFunction } from "../plugins/findUniqueAuthentication/schemas";
 import type { RelayRequestSdkFunction } from "../plugins/request/schemas";
-import type { LockVersionPluginProvides } from "../plugins/lockVersion";
 
 import type { z } from "zod";
 import type { RegistryPluginProvides } from "../plugins/registry";
 import type { GetProfilePluginProvides } from "../plugins/getProfile";
-import type { AppsPluginProvides } from "../plugins/apps";
+import type { AppsPluginProvides, ZapierSdkApps } from "../plugins/apps";
+import type { ActionProxy } from "../plugins/apps/types";
 import type { FetchPluginProvides } from "../plugins/fetch";
 import type { ListAppsPluginProvides } from "../plugins/listApps";
 import type { GetAppPluginProvides } from "../plugins/getApp";
@@ -46,6 +46,7 @@ import type { GetAuthenticationPluginProvides } from "../plugins/getAuthenticati
 import type { FindFirstAuthenticationPluginProvides } from "../plugins/findFirstAuthentication";
 import type { FindUniqueAuthenticationPluginProvides } from "../plugins/findUniqueAuthentication";
 import type { ListInputFieldsPluginProvides } from "../plugins/listInputFields";
+import type { ListInputFieldChoicesPluginProvides } from "../plugins/listInputFieldChoices";
 import type { RequestPluginProvides } from "../plugins/request";
 import type { GetSdkType } from "./plugin";
 import type { ManifestPluginProvides } from "../plugins/manifest";
@@ -78,22 +79,26 @@ export interface ZapierSdkFunctions
 // Note: ZapierSdk type removed - use ReturnType<typeof createZapierSdk> instead
 // This ensures the type matches exactly what the builder produces
 
-export type ZapierSdk = GetSdkType<
-  RegistryPluginProvides &
-    FetchPluginProvides &
-    AppsPluginProvides &
-    ListAppsPluginProvides &
-    ManifestPluginProvides &
-    GetAppPluginProvides &
-    ListActionsPluginProvides &
-    GetActionPluginProvides &
-    RunActionPluginProvides &
-    LockVersionPluginProvides &
-    ListAuthenticationsPluginProvides &
-    GetAuthenticationPluginProvides &
-    FindFirstAuthenticationPluginProvides &
-    FindUniqueAuthenticationPluginProvides &
-    ListInputFieldsPluginProvides &
-    RequestPluginProvides &
-    GetProfilePluginProvides
->;
+export interface ZapierSdk
+  extends GetSdkType<
+    RegistryPluginProvides &
+      FetchPluginProvides &
+      AppsPluginProvides &
+      ListAppsPluginProvides &
+      ManifestPluginProvides &
+      GetAppPluginProvides &
+      ListActionsPluginProvides &
+      GetActionPluginProvides &
+      RunActionPluginProvides &
+      ListAuthenticationsPluginProvides &
+      GetAuthenticationPluginProvides &
+      FindFirstAuthenticationPluginProvides &
+      FindUniqueAuthenticationPluginProvides &
+      ListInputFieldsPluginProvides &
+      ListInputFieldChoicesPluginProvides &
+      RequestPluginProvides &
+      GetProfilePluginProvides
+  > {
+  // Override apps property to intersect ActionProxy with our typed apps
+  apps: ActionProxy & ZapierSdkApps;
+}