@zapier/zapier-sdk 0.8.1 → 0.8.3

package/src/api/polling.test.ts

@@ -0,0 +1,405 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { pollUntilComplete } from "./polling";
+import {
+  ZapierTimeoutError,
+  ZapierApiError,
+  ZapierValidationError,
+} from "../types/errors";
+
+// Mock the timers/promises module
+vi.mock("timers/promises", () => ({
+  setTimeout: vi.fn(() => Promise.resolve()),
+}));
+
+describe("pollUntilComplete", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("successful polling", () => {
+    it("should return immediately on first successful response", async () => {
+      const mockResponse = {
+        ok: true,
+        status: 200,
+        json: vi.fn().mockResolvedValue({ data: "success" }),
+      } as unknown as Response;
+
+      const fetchPoll = vi.fn().mockResolvedValue(mockResponse);
+
+      const result = await pollUntilComplete({ fetchPoll });
+      expect(result).toEqual({ data: "success" });
+      expect(fetchPoll).toHaveBeenCalledTimes(1);
+    });
+
+    it("should poll until success status is received", async () => {
+      const pendingResponse = {
+        ok: true,
+        status: 202,
+      } as Response;
+
+      const successResponse = {
+        ok: true,
+        status: 200,
+        json: vi.fn().mockResolvedValue({ data: "complete" }),
+      } as unknown as Response;
+
+      const fetchPoll = vi
+        .fn()
+        .mockResolvedValueOnce(pendingResponse)
+        .mockResolvedValueOnce(pendingResponse)
+        .mockResolvedValueOnce(successResponse);
+
+      const result = await pollUntilComplete({ fetchPoll });
+      expect(result).toEqual({ data: "complete" });
+      expect(fetchPoll).toHaveBeenCalledTimes(3);
+    });
+
+    it("should use custom success and pending status codes", async () => {
+      const pendingResponse = {
+        ok: true,
+        status: 301,
+      } as Response;
+
+      const successResponse = {
+        ok: true,
+        status: 204,
+        json: vi.fn().mockResolvedValue({ done: true }),
+      } as unknown as Response;
+
+      const fetchPoll = vi
+        .fn()
+        .mockResolvedValueOnce(pendingResponse)
+        .mockResolvedValueOnce(successResponse);
+
+      const result = await pollUntilComplete({
+        fetchPoll,
+        successStatus: 204,
+        pendingStatus: 301,
+      });
+      expect(result).toEqual({ done: true });
+      expect(fetchPoll).toHaveBeenCalledTimes(2);
+    });
+
+    it("should apply result extractor function", async () => {
+      const mockResponse = {
+        ok: true,
+        status: 200,
+        json: vi.fn().mockResolvedValue({
+          nested: { data: { value: "extracted" } },
+        }),
+      } as unknown as Response;
+
+      const fetchPoll = vi.fn().mockResolvedValue(mockResponse);
+      const resultExtractor = (response: any) => response.nested.data.value;
+
+      const result = await pollUntilComplete({
+        fetchPoll,
+        resultExtractor,
+      });
+      expect(result).toBe("extracted");
+    });
+  });
+
+  describe("initial delay", () => {
+    it("should wait for initial delay before first poll", async () => {
+      const mockResponse = {
+        ok: true,
+        status: 200,
+        json: vi.fn().mockResolvedValue({ data: "success" }),
+      } as unknown as Response;
+
+      const fetchPoll = vi.fn().mockResolvedValue(mockResponse);
+      const { setTimeout: mockSetTimeout } = await import("timers/promises");
+
+      const result = await pollUntilComplete({
+        fetchPoll,
+        initialDelay: 500,
+      });
+
+      expect(result).toEqual({ data: "success" });
+      expect(fetchPoll).toHaveBeenCalledTimes(1);
+      // Verify setTimeout was called with the initial delay
+      expect(mockSetTimeout).toHaveBeenCalledWith(500);
+    });
+  });
+
+  describe("error handling", () => {
+    it("should retry on transient network errors", async () => {
+      const successResponse = {
+        ok: true,
+        status: 200,
+        json: vi.fn().mockResolvedValue({ data: "recovered" }),
+      } as unknown as Response;
+
+      const fetchPoll = vi
+        .fn()
+        .mockRejectedValueOnce(new Error("Network error"))
+        .mockRejectedValueOnce(new Error("Network error"))
+        .mockResolvedValueOnce(successResponse);
+
+      const result = await pollUntilComplete({ fetchPoll });
+      expect(result).toEqual({ data: "recovered" });
+      expect(fetchPoll).toHaveBeenCalledTimes(3);
+    });
+
+    it("should fail after MAX_CONSECUTIVE_ERRORS network failures", async () => {
+      const fetchPoll = vi
+        .fn()
+        .mockRejectedValue(new Error("Persistent network error"));
+
+      await expect(pollUntilComplete({ fetchPoll })).rejects.toThrow(
+        ZapierApiError,
+      );
+      expect(fetchPoll).toHaveBeenCalledTimes(3);
+    });
+
+    it("should retry on HTTP error responses", async () => {
+      const errorResponse = {
+        ok: false,
+        status: 500,
+        statusText: "Internal Server Error",
+      } as Response;
+
+      const successResponse = {
+        ok: true,
+        status: 200,
+        json: vi.fn().mockResolvedValue({ data: "recovered" }),
+      } as unknown as Response;
+
+      const fetchPoll = vi
+        .fn()
+        .mockResolvedValueOnce(errorResponse)
+        .mockResolvedValueOnce(errorResponse)
+        .mockResolvedValueOnce(successResponse);
+
+      const result = await pollUntilComplete({ fetchPoll });
+      expect(result).toEqual({ data: "recovered" });
+      expect(fetchPoll).toHaveBeenCalledTimes(3);
+    });
+
+    it("should fail after MAX_CONSECUTIVE_ERRORS HTTP failures", async () => {
+      const errorResponse = {
+        ok: false,
+        status: 503,
+        statusText: "Service Unavailable",
+      } as Response;
+
+      const fetchPoll = vi.fn().mockResolvedValue(errorResponse);
+
+      await expect(pollUntilComplete({ fetchPoll })).rejects.toThrow(
+        ZapierApiError,
+      );
+      expect(fetchPoll).toHaveBeenCalledTimes(3);
+    });
+
+    it("should throw error for unexpected response status", async () => {
+      const unexpectedResponse = {
+        ok: true,
+        status: 301, // Not success (200) or pending (202)
+      } as Response;
+
+      const fetchPoll = vi.fn().mockResolvedValue(unexpectedResponse);
+
+      await expect(pollUntilComplete({ fetchPoll })).rejects.toThrow(
+        "Unexpected response status",
+      );
+      // Will retry 3 times before failing
+      expect(fetchPoll).toHaveBeenCalledTimes(3);
+    });
+
+    it("should throw error if successful response is not valid JSON", async () => {
+      const mockResponse = {
+        ok: true,
+        status: 200,
+        json: vi.fn().mockRejectedValue(new Error("Invalid JSON")),
+      } as unknown as Response;
+
+      const fetchPoll = vi.fn().mockResolvedValue(mockResponse);
+
+      await expect(pollUntilComplete({ fetchPoll })).rejects.toThrow(
+        "Failed to poll after 3 consecutive errors",
+      );
+      // Will retry 3 times before failing
+      expect(fetchPoll).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("timeout behavior", () => {
+    it("should timeout after specified duration", async () => {
+      // Mock Date.now to simulate time passing
+      const originalDateNow = Date.now;
+      let currentTime = 1000;
+      Date.now = vi.fn(() => currentTime);
+
+      const pendingResponse = {
+        ok: true,
+        status: 202,
+      } as Response;
+
+      const fetchPoll = vi.fn().mockImplementation(() => {
+        // Simulate time passing with each poll
+        currentTime += 500;
+        return Promise.resolve(pendingResponse);
+      });
+
+      try {
+        await expect(
+          pollUntilComplete({
+            fetchPoll,
+            timeoutMs: 1000,
+            initialDelay: 0,
+          }),
+        ).rejects.toThrow(ZapierTimeoutError);
+      } finally {
+        Date.now = originalDateNow;
+      }
+    });
+
+    it("should use default timeout when not specified", async () => {
+      // Mock Date.now to simulate time passing beyond default timeout
+      const originalDateNow = Date.now;
+      let currentTime = 1000;
+      Date.now = vi.fn(() => currentTime);
+
+      const pendingResponse = {
+        ok: true,
+        status: 202,
+      } as Response;
+
+      const fetchPoll = vi.fn().mockImplementation(() => {
+        // Simulate time passing beyond default timeout (180 seconds + buffer)
+        currentTime += 50000;
+        return Promise.resolve(pendingResponse);
+      });
+
+      try {
+        await expect(
+          pollUntilComplete({
+            fetchPoll,
+            initialDelay: 0,
+          }),
+        ).rejects.toThrow(ZapierTimeoutError);
+      } finally {
+        Date.now = originalDateNow;
+      }
+    });
+  });
+
+  describe("input validation", () => {
+    it("should throw error for invalid timeout", async () => {
+      const fetchPoll = vi.fn();
+
+      await expect(
+        pollUntilComplete({
+          fetchPoll,
+          timeoutMs: 0,
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+
+      await expect(
+        pollUntilComplete({
+          fetchPoll,
+          timeoutMs: -1000,
+        }),
+      ).rejects.toThrow(/Timeout must be greater than 0/);
+    });
+
+    it("should throw error for negative initial delay", async () => {
+      const fetchPoll = vi.fn();
+
+      await expect(
+        pollUntilComplete({
+          fetchPoll,
+          initialDelay: -100,
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+
+      await expect(
+        pollUntilComplete({
+          fetchPoll,
+          initialDelay: -1,
+        }),
+      ).rejects.toThrow(/Initial delay must be non-negative/);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle rapid status changes", async () => {
+      const responses = [
+        { ok: true, status: 202 } as Response,
+        { ok: false, status: 500 } as Response,
+        { ok: true, status: 202 } as Response,
+        {
+          ok: true,
+          status: 200,
+          json: vi.fn().mockResolvedValue({ data: "success" }),
+        } as unknown as Response,
+      ];
+
+      let index = 0;
+      const fetchPoll = vi.fn().mockImplementation(() => {
+        const response = responses[index];
+        index++;
+        return Promise.resolve(response);
+      });
+
+      const result = await pollUntilComplete({ fetchPoll });
+      expect(result).toEqual({ data: "success" });
+      expect(fetchPoll).toHaveBeenCalledTimes(4);
+    });
+
+    it("should handle immediate success with no initial delay", async () => {
+      const mockResponse = {
+        ok: true,
+        status: 200,
+        json: vi.fn().mockResolvedValue({ instant: true }),
+      } as unknown as Response;
+
+      const fetchPoll = vi.fn().mockResolvedValue(mockResponse);
+
+      const result = await pollUntilComplete({
+        fetchPoll,
+        initialDelay: 0,
+      });
+
+      expect(result).toEqual({ instant: true });
+      expect(fetchPoll).toHaveBeenCalledTimes(1);
+    });
+
+    it("should handle very short timeout", async () => {
+      // Mock Date.now to simulate time passing
+      const originalDateNow = Date.now;
+      let currentTime = 1000;
+      Date.now = vi.fn(() => currentTime);
+
+      const pendingResponse = {
+        ok: true,
+        status: 202,
+      } as Response;
+
+      const fetchPoll = vi.fn().mockImplementation(() => {
+        // Simulate time passing beyond the short timeout
+        currentTime += 200;
+        return Promise.resolve(pendingResponse);
+      });
+
+      try {
+        await expect(
+          pollUntilComplete({
+            fetchPoll,
+            timeoutMs: 100,
+            initialDelay: 0,
+          }),
+        ).rejects.toThrow(ZapierTimeoutError);
+        // Should have made at least 1 attempt before timing out
+        expect(fetchPoll.mock.calls.length).toBeGreaterThanOrEqual(1);
+      } finally {
+        Date.now = originalDateNow;
+      }
+    });
+  });
+});

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 },
-  );
 }