@zapier/zapier-sdk 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/zapier-sdk",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Complete Zapier SDK - combines all Zapier SDK packages",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",

package/src/api/client.ts

@@ -437,19 +437,20 @@ class ZapierApiClient implements ApiClient {
     path: string,
     options: PollOptions = {},
   ): Promise<TOutput> => {
-    return pollUntilComplete({
+    return pollUntilComplete<TOutput>({
       fetchPoll: () =>
         this.plainFetch(path, {
           method: "GET",
           searchParams: options.searchParams,
           authRequired: options.authRequired,
         }),
-      maxAttempts: options.maxAttempts,
       initialDelay: options.initialDelay,
-      maxDelay: options.maxDelay,
+      timeoutMs: options.timeoutMs,
       successStatus: options.successStatus,
       pendingStatus: options.pendingStatus,
-      resultExtractor: options.resultExtractor,
+      resultExtractor: options.resultExtractor as
+        | ((response: unknown) => TOutput)
+        | undefined,
     });
   };
 }

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