@zapier/zapier-sdk 0.8.2 → 0.9.0

package/src/api/polling.ts

@@ -5,69 +5,249 @@
  * with configurable retry logic and exponential backoff.
  */
 
-import { ZapierTimeoutError, ZapierApiError } from "../types/errors";
+import {
+  ZapierTimeoutError,
+  ZapierApiError,
+  ZapierValidationError,
+} from "../types/errors";
+import { setTimeout } from "timers/promises";
 
-export async function pollUntilComplete(options: {
+// Constants
+const DEFAULT_TIMEOUT_MS = 180_000;
+const DEFAULT_SUCCESS_STATUS = 200;
+const DEFAULT_PENDING_STATUS = 202;
+const DEFAULT_INITIAL_DELAY_MS = 50;
+const DEFAULT_MAX_POLLING_INTERVAL_MS = 10_000;
+const MAX_CONSECUTIVE_ERRORS = 3;
+const MAX_TIMEOUT_BUFFER_MS = 10_000;
+const BASE_ERROR_BACKOFF_MS = 1_000;
+const JITTER_FACTOR = 0.5;
+
+// Polling stages: [threshold_ms, interval_ms]
+// Note: These are default stages, actual hard timeout is enforced separately below
+const DEFAULT_POLLING_STAGES = [
+  [125, 125], // Up to 125ms: poll every 125ms
+  [375, 250], // Up to 375ms: poll every 250ms
+  [875, 500], // Up to 875ms: poll every 500ms
+  [10_000, 1_000], // Up to 10s: poll every 1s
+  [30_000, 2_500], // Up to 30s: poll every 2.5s
+  [60_000, 5_000], // Up to 60s: poll every 5s
+] as const satisfies Array<[number, number]>;
+
+/**
+ * Options for the polling function
+ */
+export interface PollOptions<TResult = unknown> {
+  /** Function that performs the HTTP request */
   fetchPoll: () => Promise<Response>;
-  maxAttempts?: number;
-  initialDelay?: number;
-  maxDelay?: number;
+  /** Maximum time to wait for completion (in milliseconds) */
+  timeoutMs?: number;
+  /** HTTP status code indicating successful completion */
   successStatus?: number;
+  /** HTTP status code indicating the operation is still pending */
   pendingStatus?: number;
-  resultExtractor?: (response: any) => any;
-}): Promise<any> {
+  /** Function to extract the result from the response */
+  resultExtractor?: (response: unknown) => TResult;
+  /** Initial delay before the first poll attempt (in milliseconds) */
+  initialDelay?: number;
+}
+
+const enum PollStatus {
+  Success = "success",
+  Continue = "continue",
+}
+
+/**
+ * Result of a poll operation
+ */
+export type PollResult<TResult = unknown> = {
+  result?: TResult;
+  status: PollStatus;
+  errorCount: number;
+};
+
+// Helper to calculate wait time with jitter and error backoff
+const calculateWaitTime = (
+  baseInterval: number,
+  errorCount: number,
+): number => {
+  // Jitter to avoid thundering herd
+  const jitter = Math.random() * JITTER_FACTOR * baseInterval;
+  // More backoff added if errors are seen
+  const errorBackoff = Math.min(
+    BASE_ERROR_BACKOFF_MS * (errorCount / 2),
+    baseInterval * 2, // Cap error backoff at 2x the base interval
+  );
+  return Math.floor(baseInterval + jitter + errorBackoff);
+};
+
+const processResponse = async <TResult = unknown>(
+  response: Response,
+  successStatus: number,
+  pendingStatus: number,
+  resultExtractor: (response: unknown) => TResult,
+  errorCount: number,
+): Promise<PollResult<TResult>> => {
+  // Handle other error responses
+  if (!response.ok) {
+    return {
+      status: PollStatus.Continue,
+      // If for some reason the status is pending, we don't want to increment the error count
+      errorCount:
+        response.status === pendingStatus ? errorCount : errorCount + 1,
+    };
+  }
+
+  // Check for successful completion
+  if (response.status === successStatus) {
+    try {
+      const resultJson = await response.json();
+      return {
+        result: resultExtractor(resultJson),
+        status: PollStatus.Success,
+        errorCount: 0,
+      };
+    } catch (error) {
+      throw new ZapierApiError(
+        "Result extractor failed to parse successful response as JSON",
+        {
+          statusCode: response.status,
+          cause: error,
+        },
+      );
+    }
+  }
+
+  // If it's not pending, it's unexpected
+  if (response.status !== pendingStatus) {
+    throw new ZapierApiError(
+      `Unexpected response status during polling: ${response.status}`,
+      {
+        statusCode: response.status,
+      },
+    );
+  }
+
+  // It's still pending, so we continue polling
+  return {
+    status: PollStatus.Continue,
+    errorCount: 0,
+  };
+};
+
+/**
+ * Polls an endpoint until completion, timeout, or error
+ * @param options Configuration options for polling
+ * @returns The extracted result from the successful response
+ * @throws {ZapierValidationError} When the input parameters are invalid
+ * @throws {ZapierTimeoutError} When the operation times out
+ * @throws {ZapierApiError} When the API returns consecutive errors
+ */
+export async function pollUntilComplete<TResult = unknown>(
+  options: PollOptions<TResult>,
+): Promise<TResult> {
   const {
     fetchPoll,
-    maxAttempts = 30,
-    initialDelay = 50,
-    maxDelay = 1000,
-    successStatus = 200,
-    pendingStatus = 202,
-    resultExtractor = (response) => response,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    initialDelay = DEFAULT_INITIAL_DELAY_MS,
+    successStatus = DEFAULT_SUCCESS_STATUS,
+    pendingStatus = DEFAULT_PENDING_STATUS,
+    resultExtractor = (response) => response as TResult,
   } = options;
 
-  let delay = initialDelay;
+  // Validate input parameters
+  if (timeoutMs <= 0) {
+    throw new ZapierValidationError("Timeout must be greater than 0", {
+      details: { timeoutMs },
+    });
+  }
+
+  if (initialDelay < 0) {
+    throw new ZapierValidationError("Initial delay must be non-negative", {
+      details: { initialDelay },
+    });
+  }
+
+  const startTime = Date.now();
+  let attempts = 0;
   let errorCount = 0;
 
-  for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    const response = await fetchPoll();
-
-    if (response.status === successStatus) {
-      // Success - reset error count and return results
-      errorCount = 0;
-      const result = await response.json();
-      return resultExtractor(result);
-    } else if (response.status === pendingStatus) {
-      // Still processing - reset error count and wait and retry
-      errorCount = 0;
-      if (attempt < maxAttempts - 1) {
-        await new Promise((resolve) => setTimeout(resolve, delay));
-        delay = Math.min(delay * 2, maxDelay); // Exponential backoff
-        continue;
+  // Build polling stages with the actual timeout appended
+  const pollingStages = [
+    ...DEFAULT_POLLING_STAGES,
+    [timeoutMs + MAX_TIMEOUT_BUFFER_MS, DEFAULT_MAX_POLLING_INTERVAL_MS], // Up to timeout + 10s: poll every 10s
+  ] as const satisfies Array<[number, number]>;
+
+  // Apply initial delay if specified
+  if (initialDelay > 0) {
+    await setTimeout(initialDelay);
+  }
+
+  while (true) {
+    attempts++;
+    const elapsedTime = Date.now() - startTime;
+
+    // Find the current polling stage
+    const pollingInterval = pollingStages.find(
+      ([maxTimeForStage, _interval]) => {
+        return elapsedTime < maxTimeForStage;
+      },
+    );
+
+    // If there isn't a current stage, throw timeout error
+    if (!pollingInterval) {
+      throw new ZapierTimeoutError(
+        `Operation timed out after ${Math.floor(elapsedTime / 1000)}s (${attempts} attempts)`,
+        {
+          attempts,
+        },
+      );
+    }
+
+    // Wait before polling (except on first attempt)
+    if (attempts > 1) {
+      const waitTime = calculateWaitTime(pollingInterval[1], errorCount);
+      await setTimeout(waitTime);
+    }
+
+    // Perform the poll request
+    try {
+      const response = await fetchPoll();
+      const {
+        result,
+        errorCount: newErrorCount,
+        status,
+      } = await processResponse<TResult>(
+        response,
+        successStatus,
+        pendingStatus,
+        resultExtractor,
+        errorCount,
+      );
+      errorCount = newErrorCount;
+
+      if (status === PollStatus.Success) {
+        return result as TResult;
       }
-    } else {
-      // Error occurred - increment error count
-      errorCount++;
 
-      if (errorCount >= 3) {
+      if (errorCount >= MAX_CONSECUTIVE_ERRORS) {
         // Too many consecutive errors, fail
         throw new ZapierApiError(
           `Poll request failed: ${response.status} ${response.statusText}`,
           { statusCode: response.status },
         );
       }
-
-      // Treat as pending for up to 3 errors - wait and retry
-      if (attempt < maxAttempts - 1) {
-        await new Promise((resolve) => setTimeout(resolve, delay));
-        delay = Math.min(delay * 2, maxDelay); // Exponential backoff
-        continue;
+    } catch (error) {
+      errorCount++;
+      if (errorCount >= MAX_CONSECUTIVE_ERRORS) {
+        throw new ZapierApiError(
+          `Failed to poll after ${errorCount} consecutive errors: ${error instanceof Error ? error.message : String(error)}`,
+          {
+            cause: error,
+          },
+        );
       }
     }
+    // Continue polling if status is pending
   }
-
-  throw new ZapierTimeoutError(
-    `Operation timed out after ${maxAttempts} attempts`,
-    { attempts: maxAttempts, maxAttempts: maxAttempts },
-  );
 }

package/src/api/types.ts

@@ -88,9 +88,8 @@ export interface RequestOptions {
 }
 
 export interface PollOptions extends RequestOptions {
-  maxAttempts?: number;
   initialDelay?: number;
-  maxDelay?: number;
+  timeoutMs?: number;
   successStatus?: number;
   pendingStatus?: number;
   resultExtractor?: (response: unknown) => unknown;

package/src/index.ts

@@ -17,7 +17,6 @@ export * from "./plugins/findUniqueAuthentication";
 export * from "./plugins/runAction";
 export * from "./plugins/request";
 export * from "./plugins/manifest";
-export * from "./plugins/lockVersion";
 export * from "./plugins/getProfile";
 export * from "./plugins/api";
 
@@ -74,6 +73,7 @@ export type {
   PluginDependencies,
   PluginOptions,
   GetSdkType,
+  GetContextType,
   Sdk,
 } from "./types/plugin";
 

package/src/plugins/apps/index.ts

@@ -1,5 +1,4 @@
-import type { ActionExecutionOptions } from "./types";
-import type { ActionProxy } from "./types";
+import type { ActionExecutionOptions, ActionProxy } from "./types";
 import { ZapierValidationError } from "../../types/errors";
 import type { Plugin, GetSdkType } from "../../types/plugin";
 import type { FetchPluginProvides } from "../fetch/index";
@@ -173,3 +172,11 @@ export const appsPlugin: Plugin<
     apps: createAppsProxy({ sdk }),
   };
 };
+
+// Export types for use in generated code
+export type { ActionExecutionOptions } from "./types";
+export type { ActionExecutionResult } from "../../api/types";
+
+// Interface for generated apps - will be augmented by generated .d.ts files
+// This interface will contain only the specifically typed apps
+export interface ZapierSdkApps {}

package/src/plugins/getApp/index.test.ts

@@ -12,8 +12,8 @@ import { manifestPlugin } from "../manifest";
 function createTestSdk() {
   return createSdk()
     .addPlugin(apiPlugin, { fetch: global.fetch })
-    .addPlugin(listAppsPlugin)
     .addPlugin(manifestPlugin)
+    .addPlugin(listAppsPlugin)
     .addPlugin(getAppPlugin);
 }
 

package/src/plugins/getApp/index.ts

@@ -5,8 +5,7 @@ import type { GetAppOptions } from "./schemas";
 import type { AppItem } from "../../types/domain";
 import { ZapierAppNotFoundError } from "../../types/errors";
 import type { GetSdkType } from "../../types/plugin";
-import type { GetImplementation } from "../manifest/schemas";
-import type { ManifestPluginProvides } from "../manifest";
+import type { ListAppsPluginProvides } from "../listApps";
 
 // GetApp plugin provides interface - getApp goes directly to SDK root
 export interface GetAppPluginProvides {
@@ -22,21 +21,20 @@ export interface GetAppPluginProvides {
 
 // GetApp plugin depends on listApps SDK function
 export const getAppPlugin: Plugin<
-  GetSdkType<ManifestPluginProvides>, // depends on manifest plugin with getImplementation in context
-  { getImplementation: GetImplementation }, //
+  GetSdkType<ListAppsPluginProvides>,
+  {},
   GetAppPluginProvides
-> = ({ context }) => {
+> = ({ sdk }) => {
   const getApp = createFunction(async function getApp(options: GetAppOptions) {
-    const app = await context.getImplementation(options.appKey);
-    if (!app) {
-      throw new ZapierAppNotFoundError("App not found", {
-        appKey: options.appKey,
-      });
+    const appsIterator = sdk.listApps({ appKeys: [options.appKey] }).items();
+    for await (const app of appsIterator) {
+      return {
+        data: app,
+      };
     }
-
-    return {
-      data: app,
-    };
+    throw new ZapierAppNotFoundError("App not found", {
+      appKey: options.appKey,
+    });
   }, GetAppSchema);
 
   // Return flat structure - getApp goes directly to SDK

package/src/plugins/getAuthentication/index.test.ts

@@ -45,8 +45,8 @@ describe("getAuthentication plugin", () => {
   function createTestSdk() {
     return createSdk()
       .addPlugin(apiPlugin)
-      .addPlugin(listAppsPlugin)
       .addPlugin(manifestPlugin)
+      .addPlugin(listAppsPlugin)
       .addPlugin(getAuthenticationPlugin);
   }
 

package/src/plugins/listActions/index.test.ts

@@ -68,6 +68,8 @@ describe("listActions plugin", () => {
       .mockResolvedValue("SlackCLIAPI@1.21.1");
   });
 
+  const mockResolveAppKeys = vi.fn().mockResolvedValue([]);
+
   function createTestSdk() {
     // Create a proper plugin chain with context dependencies
 
@@ -76,18 +78,17 @@ describe("listActions plugin", () => {
       .addPlugin(() => ({
         context: {
           api: mockApiClient,
-          getVersionedImplementationId: mockGetVersionedImplementationId,
         },
       }))
-      .addPlugin(listAppsPlugin)
       .addPlugin(() => ({
         context: {
           manifest: null,
-          getManifestEntry: () => null,
           getVersionedImplementationId: mockGetVersionedImplementationId,
-          getImplementation: () => Promise.resolve(null),
+          resolveAppKeys: mockResolveAppKeys,
+          updateManifestEntry: vi.fn().mockResolvedValue(["test-key", {}]),
         },
       }))
+      .addPlugin(listAppsPlugin)
       .addPlugin(listActionsPlugin);
   }
 
@@ -166,7 +167,7 @@ describe("listActions plugin", () => {
 
       expect(result.data).toHaveLength(2); // Only write actions
       expect(
-        result.data.every((action) => action.action_type === "write"),
+        result.data.every((action: any) => action.action_type === "write"),
       ).toBe(true);
     });
   });
@@ -309,9 +310,9 @@ describe("listActions plugin", () => {
 
       expect(result.data).toHaveLength(2);
       expect(
-        result.data.every((action) => action.action_type === "write"),
+        result.data.every((action: any) => action.action_type === "write"),
       ).toBe(true);
-      expect(result.data.map((action) => action.key)).toEqual([
+      expect(result.data.map((action: any) => action.key)).toEqual([
         "send_message",
         "create_channel",
       ]);

package/src/plugins/listActions/index.ts

@@ -32,11 +32,11 @@ export interface ListActionsPluginProvides {
 }
 
 export const listActionsPlugin: Plugin<
-  GetSdkType<ManifestPluginProvides>, // requires getApp in SDK
+  GetSdkType<ManifestPluginProvides>,
   {
     api: ApiClient;
     getVersionedImplementationId: GetVersionedImplementationId;
-  }, // requires api and getVersionedImplementationId in context
+  },
   ListActionsPluginProvides
 > = ({ context }) => {
   const listActions = createPaginatedFunction(async function listActionsPage(
@@ -44,7 +44,7 @@ export const listActionsPlugin: Plugin<
   ): Promise<ListActionsPage> {
     const { api, getVersionedImplementationId } = context;
 
-    // Use the getApp function from the SDK (dependency injection)
+    // Use getVersionedImplementationId (optimized to check manifest first)
     const selectedApi = await getVersionedImplementationId(options.appKey);
 
     if (!selectedApi) {

package/src/plugins/listApps/index.test.ts

@@ -28,9 +28,26 @@ const mockAppsResponse = {
   },
 };
 
+const mockResolveAppKeys = vi
+  .fn()
+  .mockImplementation(async ({ appKeys }: { appKeys: string[] }) => {
+    // Mock implementation that returns resolved locators for the app keys
+    return appKeys.map((appKey) => ({
+      lookupAppKey: appKey,
+      implementationName: appKey, // For testing, use appKey as implementationName
+      slug: appKey.toLowerCase(),
+      version: undefined,
+    }));
+  });
+
 function createTestSdk() {
   return createSdk()
     .addPlugin(apiPlugin, { fetch: global.fetch })
+    .addPlugin(() => ({
+      context: {
+        resolveAppKeys: mockResolveAppKeys,
+      },
+    }))
     .addPlugin(listAppsPlugin as any);
 }
 
@@ -100,7 +117,11 @@ describe("listApps plugin", () => {
       expect((context.api as any).get).toHaveBeenCalledWith(
         "/api/v4/implementations-meta/lookup/",
         {
-          searchParams: { latest_only: "true", limit: "100" },
+          searchParams: {
+            latest_only: "true",
+            limit: "100",
+            selected_apis: "",
+          },
         },
       );
     });
@@ -338,7 +359,7 @@ describe("listApps plugin", () => {
         expect.stringContaining("implementations-meta"),
         expect.objectContaining({
           searchParams: expect.objectContaining({
-            selected_apis: "SlackCLIAPI,GitHubCLIAPI",
+            selected_apis: "SlackCLIAPI@latest,GitHubCLIAPI@latest",
           }),
         }),
       );

package/src/plugins/listApps/index.ts

@@ -1,16 +1,19 @@
-import type { Plugin } from "../../types/plugin";
-import type { ApiClient } from "../../api/types";
+import type { GetContextType, Plugin } from "../../types/plugin";
 import { createPaginatedFunction } from "../../utils/function-utils";
 import { ListAppsSchema } from "./schemas";
 import type { ListAppsOptions, ListAppsPage } from "./schemas";
 import type { AppItem } from "../../types/domain";
+import type { ResolvedAppLocator } from "../../utils/domain-utils";
 import {
-  groupAppKeysByType,
   normalizeImplementationMetaToAppItem,
   splitVersionedKey,
+  toAppLocator,
+  toImplementationId,
 } from "../../utils/domain-utils";
 import { extractCursor } from "../../utils/function-utils";
 import type { ImplementationsMetaResponse } from "../../api/types";
+import type { ManifestPluginProvides } from "../manifest";
+import type { ApiPluginProvides } from "../api";
 // ListApps plugin provides interface - listApps goes directly to SDK root
 export interface ListAppsPluginProvides {
   listApps: (options?: ListAppsOptions) => Promise<{ data: AppItem[] }> &
@@ -26,10 +29,9 @@ export interface ListAppsPluginProvides {
   };
 }
 
-// Direct plugin function - takes options + sdk + context in one object
 export const listAppsPlugin: Plugin<
-  {}, // no SDK dependencies
-  { api: ApiClient }, // requires api in context
+  {},
+  GetContextType<ApiPluginProvides & ManifestPluginProvides>,
   ListAppsPluginProvides
 > = ({ context }) => {
   const listApps = createPaginatedFunction(async function listAppsPage(
@@ -38,9 +40,28 @@ export const listAppsPlugin: Plugin<
     const api = context.api;
     const opts = options;
 
-    const appKeys = [...(opts.appKeys ?? [])].map(
-      (key) => splitVersionedKey(key)[0],
-    );
+    const appLocators = await context.resolveAppKeys({
+      appKeys: [...(opts.appKeys ?? [])],
+    });
+    const implementationNameToLocator: Record<string, ResolvedAppLocator[]> =
+      {};
+    for (const locator of appLocators) {
+      implementationNameToLocator[locator.implementationName] = [
+        ...(implementationNameToLocator[locator.implementationName] ?? []),
+        locator,
+      ];
+    }
+    const duplicatedLookupAppKeys = Object.keys(implementationNameToLocator)
+      .filter((key) => implementationNameToLocator[key].length > 1)
+      .map((key) => implementationNameToLocator[key])
+      .flat()
+      .map((locator) => locator.lookupAppKey);
+
+    if (duplicatedLookupAppKeys.length > 0) {
+      throw new Error(
+        `Duplicate lookup app keys found: ${duplicatedLookupAppKeys.join(", ")}`,
+      );
+    }
 
     if (opts.search) {
       const searchParams: Record<string, string> = {};
@@ -58,12 +79,18 @@ export const listAppsPlugin: Plugin<
         normalizeImplementationMetaToAppItem,
       );
 
-      const appKeysSet = new Set(appKeys);
+      const implementationNameSet = new Set<string>(
+        appLocators.map((locator) => locator.implementationName),
+      );
 
       for (const implementation of implementations) {
-        if (!appKeysSet.has(implementation.key)) {
-          appKeysSet.add(implementation.key);
-          appKeys.push(implementation.key);
+        const [implementationName] = splitVersionedKey(implementation.key);
+        if (!implementationNameSet.has(implementationName)) {
+          implementationNameSet.add(implementationName);
+          appLocators.push({
+            ...toAppLocator(implementation.key),
+            implementationName,
+          });
         }
       }
     }
@@ -74,23 +101,17 @@ export const listAppsPlugin: Plugin<
       searchParams.limit = opts.pageSize.toString();
     }
 
-    searchParams.latest_only = "true";
+    if (appLocators.length === 0) {
+      searchParams.latest_only = "true";
+    }
 
     if (opts.cursor) {
       searchParams.offset = opts.cursor;
     }
 
-    if (appKeys.length > 0) {
-      const groupedAppKeys = groupAppKeysByType(appKeys);
-
-      if (groupedAppKeys.selectedApi.length > 0) {
-        searchParams.selected_apis = groupedAppKeys.selectedApi.join(",");
-      }
-
-      if (groupedAppKeys.slug.length > 0) {
-        searchParams.slugs = groupedAppKeys.slug.join(",");
-      }
-    }
+    searchParams.selected_apis = appLocators
+      .map((locator) => toImplementationId(locator))
+      .join(",");
 
     const implementationsEnvelope: ImplementationsMetaResponse = await api.get(
       "/api/v4/implementations-meta/lookup/",