@zapier/zapier-sdk 0.13.8 → 0.14.0

package/dist/utils/retry-utils.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Retry and Backoff Utilities
+ *
+ * Shared utilities for implementing resilient retry logic with exponential backoff
+ * and jitter. Used by both polling and batch operations.
+ */
+/**
+ * Maximum number of consecutive errors before giving up
+ * Prevents infinite retry loops when the API is consistently failing
+ */
+export declare const MAX_CONSECUTIVE_ERRORS = 3;
+/**
+ * Base delay for error backoff in milliseconds
+ * Each error adds this amount (with scaling) to the wait time
+ */
+export declare const BASE_ERROR_BACKOFF_MS = 1000;
+/**
+ * Jitter factor (0.0 to 1.0) for randomizing wait times
+ * Prevents thundering herd problem when many clients retry simultaneously
+ * A factor of 0.5 means we add 0-50% random variance to the base interval
+ */
+export declare const JITTER_FACTOR = 0.5;
+/**
+ * Calculate wait time with jitter and error backoff
+ *
+ * This implements two key reliability patterns:
+ * 1. Jitter - Adds randomness to prevent synchronized retries across clients
+ * 2. Error backoff - Increases wait time when errors occur, giving the API time to recover
+ *
+ * @param baseInterval - The base wait time in milliseconds
+ * @param errorCount - Number of consecutive errors (0 if no errors)
+ * @returns Wait time in milliseconds with jitter and error backoff applied
+ *
+ * @example
+ * // No errors: returns 1000-1500ms (1000 + 0-500ms jitter)
+ * calculateWaitTime(1000, 0);
+ *
+ * // 2 errors: returns 1000-1500ms base + up to 1000ms error backoff = 1000-2500ms
+ * calculateWaitTime(1000, 2);
+ *
+ * // 6 errors: returns 1000-1500ms base + 2000ms capped backoff = 3000-3500ms
+ * calculateWaitTime(1000, 6);
+ */
+export declare function calculateWaitTime(baseInterval: number, errorCount: number): number;
+//# sourceMappingURL=retry-utils.d.ts.map

package/dist/utils/retry-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-utils.d.ts","sourceRoot":"","sources":["../../src/utils/retry-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,MAAM,CAYR"}

package/dist/utils/retry-utils.js

@@ -0,0 +1,51 @@
+/**
+ * Retry and Backoff Utilities
+ *
+ * Shared utilities for implementing resilient retry logic with exponential backoff
+ * and jitter. Used by both polling and batch operations.
+ */
+/**
+ * Maximum number of consecutive errors before giving up
+ * Prevents infinite retry loops when the API is consistently failing
+ */
+export const MAX_CONSECUTIVE_ERRORS = 3;
+/**
+ * Base delay for error backoff in milliseconds
+ * Each error adds this amount (with scaling) to the wait time
+ */
+export const BASE_ERROR_BACKOFF_MS = 1000;
+/**
+ * Jitter factor (0.0 to 1.0) for randomizing wait times
+ * Prevents thundering herd problem when many clients retry simultaneously
+ * A factor of 0.5 means we add 0-50% random variance to the base interval
+ */
+export const JITTER_FACTOR = 0.5;
+/**
+ * Calculate wait time with jitter and error backoff
+ *
+ * This implements two key reliability patterns:
+ * 1. Jitter - Adds randomness to prevent synchronized retries across clients
+ * 2. Error backoff - Increases wait time when errors occur, giving the API time to recover
+ *
+ * @param baseInterval - The base wait time in milliseconds
+ * @param errorCount - Number of consecutive errors (0 if no errors)
+ * @returns Wait time in milliseconds with jitter and error backoff applied
+ *
+ * @example
+ * // No errors: returns 1000-1500ms (1000 + 0-500ms jitter)
+ * calculateWaitTime(1000, 0);
+ *
+ * // 2 errors: returns 1000-1500ms base + up to 1000ms error backoff = 1000-2500ms
+ * calculateWaitTime(1000, 2);
+ *
+ * // 6 errors: returns 1000-1500ms base + 2000ms capped backoff = 3000-3500ms
+ * calculateWaitTime(1000, 6);
+ */
+export function calculateWaitTime(baseInterval, errorCount) {
+    // Jitter to avoid thundering herd (multiple clients retrying at exact same time)
+    const jitter = Math.random() * JITTER_FACTOR * baseInterval;
+    // Exponential backoff scaled by error count, but capped at 2x base interval
+    // This prevents wait times from growing unboundedly
+    const errorBackoff = Math.min(BASE_ERROR_BACKOFF_MS * (errorCount / 2), baseInterval * 2);
+    return Math.floor(baseInterval + jitter + errorBackoff);
+}

package/dist/utils/retry-utils.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=retry-utils.test.d.ts.map

package/dist/utils/retry-utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-utils.test.d.ts","sourceRoot":"","sources":["../../src/utils/retry-utils.test.ts"],"names":[],"mappings":""}

package/dist/utils/retry-utils.test.js

@@ -0,0 +1,90 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { calculateWaitTime, MAX_CONSECUTIVE_ERRORS, BASE_ERROR_BACKOFF_MS, JITTER_FACTOR, } from "./retry-utils";
+describe("retry-utils", () => {
+    describe("calculateWaitTime", () => {
+        beforeEach(() => {
+            // Seed random for consistent testing
+            vi.spyOn(Math, "random");
+        });
+        afterEach(() => {
+            vi.restoreAllMocks();
+        });
+        it("should return base interval with jitter when no errors", () => {
+            vi.spyOn(Math, "random").mockReturnValue(0.5); // Middle of jitter range
+            const baseInterval = 1000;
+            const waitTime = calculateWaitTime(baseInterval, 0);
+            // With 0.5 random and JITTER_FACTOR 0.5:
+            // jitter = 0.5 * 0.5 * 1000 = 250ms
+            // errorBackoff = 0 (no errors)
+            // total = 1000 + 250 + 0 = 1250ms
+            expect(waitTime).toBe(1250);
+        });
+        it("should add error backoff for consecutive errors", () => {
+            vi.spyOn(Math, "random").mockReturnValue(0); // No jitter for simpler math
+            const baseInterval = 1000;
+            const errorCount = 2;
+            const waitTime = calculateWaitTime(baseInterval, errorCount);
+            // jitter = 0 (random is 0)
+            // errorBackoff = BASE_ERROR_BACKOFF_MS * (errorCount / 2) = 1000 * (2/2) = 1000ms
+            // total = 1000 + 0 + 1000 = 2000ms
+            expect(waitTime).toBe(2000);
+        });
+        it("should cap error backoff at 2x base interval", () => {
+            vi.spyOn(Math, "random").mockReturnValue(0); // No jitter
+            const baseInterval = 1000;
+            const errorCount = 10; // Large error count
+            const waitTime = calculateWaitTime(baseInterval, errorCount);
+            // errorBackoff would be 1000 * (10/2) = 5000ms
+            // but it's capped at 2x base = 2000ms
+            // total = 1000 + 0 + 2000 = 3000ms
+            expect(waitTime).toBe(3000);
+        });
+        it("should add random jitter to prevent thundering herd", () => {
+            const baseInterval = 1000;
+            const results = new Set();
+            // Run multiple times with real random to ensure jitter varies
+            vi.spyOn(Math, "random").mockRestore(); // Use real random
+            for (let i = 0; i < 10; i++) {
+                const waitTime = calculateWaitTime(baseInterval, 0);
+                results.add(waitTime);
+            }
+            // Should have multiple different values due to jitter
+            expect(results.size).toBeGreaterThan(1);
+            // All values should be in expected range
+            // baseInterval (1000) + jitter (0 to JITTER_FACTOR * baseInterval)
+            // = 1000 to 1500ms
+            for (const result of results) {
+                expect(result).toBeGreaterThanOrEqual(1000);
+                expect(result).toBeLessThanOrEqual(1500);
+            }
+        });
+        it("should combine jitter and error backoff", () => {
+            vi.spyOn(Math, "random").mockReturnValue(0.5);
+            const baseInterval = 1000;
+            const errorCount = 2;
+            const waitTime = calculateWaitTime(baseInterval, errorCount);
+            // jitter = 0.5 * 0.5 * 1000 = 250ms
+            // errorBackoff = 1000 * (2/2) = 1000ms
+            // total = 1000 + 250 + 1000 = 2250ms
+            expect(waitTime).toBe(2250);
+        });
+        it("should return integer wait time", () => {
+            vi.spyOn(Math, "random").mockReturnValue(0.333);
+            const baseInterval = 1000;
+            const waitTime = calculateWaitTime(baseInterval, 1);
+            // Result should be floored integer
+            expect(Number.isInteger(waitTime)).toBe(true);
+        });
+    });
+    describe("constants", () => {
+        it("should export MAX_CONSECUTIVE_ERRORS", () => {
+            expect(MAX_CONSECUTIVE_ERRORS).toBe(3);
+        });
+        it("should export BASE_ERROR_BACKOFF_MS", () => {
+            expect(BASE_ERROR_BACKOFF_MS).toBe(1000);
+        });
+        it("should export JITTER_FACTOR", () => {
+            expect(JITTER_FACTOR).toBe(0.5);
+        });
+    });
+});

package/package.json

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