feat: add timeout option for email validation

documentation.md

@@ -57,13 +57,19 @@ try {
 
 ```javascript
 const email = "<EMAIL_ADDRESS>"; // The email address you want to validate
-const ip_address = "127.0.0.1"; // The IP Address the email signed up from (Optional)
 
+// Using options object (recommended)
 try {
-  const response = await zeroBounce.validateEmail(email, ip_address);
+  const response = await zeroBounce.validateEmail(email, {
+    ip_address: "127.0.0.1", // The IP Address the email signed up from (Optional)
+    timeout: 10, // Validation timeout in seconds, 3-60 (Optional)
+  });
 } catch (error) {
   console.error(error);
 }
+
+// Legacy syntax (still supported for backwards compatibility)
+// const response = await zeroBounce.validateEmail(email, "127.0.0.1");
 ```
 
 - ####### Get api usage from a start date to an end date

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerobounce/zero-bounce-sdk",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "This SDK contains methods for interacting easily with ZeroBounce API. More information about ZeroBounce you can find in the official documentation.",
   "main": "dist/zeroBounceSDK.js",
   "scripts": {

src/utils.js

@@ -74,3 +74,9 @@ export function parameterIsMissing(parameter, aditionalInfo = "") {
     `ZeroBounce: ${parameter} parameter is missing. ${aditionalInfo}`
   );
 }
+
+export function parameterIsInvalid(parameter, aditionalInfo = "") {
+  console.error(
+    `ZeroBounce: ${parameter} parameter is invalid. ${aditionalInfo}`
+  );
+}

src/zero-bounce.js

@@ -1,4 +1,4 @@
-import { createRequest, notInitialized, parameterIsMissing } from "./utils.js";
+import { createRequest, notInitialized, parameterIsMissing, parameterIsInvalid } from "./utils.js";
 
 export class ZeroBounceSDK {
   static ApiURL = Object.freeze({
@@ -40,21 +40,40 @@ export class ZeroBounceSDK {
 
   /**
    * @param email - email to be validated
-   * @param ip_address
+   * @param options - options object or ip_address string for backwards compatibility
+   * @param options.ip_address - IP address (optional)
+   * @param options.timeout - validation timeout in seconds, 3-60 (optional). If met, the API will return unknown/greylisted.
    * */
-  validateEmail(email, ip_address = null) {
+  validateEmail(email, options = null) {
     if (!this._initialized) {
       notInitialized();
       return;
     } else if (!email) {
       parameterIsMissing("Email");
       return;
     }
+
+    let ip_address;
+    let timeout;
+    if (typeof options === "string") {
+      ip_address = options;
+    } else if (options && typeof options === "object") {
+      ip_address = options.ip_address;
+      timeout = options.timeout;
+    }
+
+    if (timeout != null && (timeout < 3 || timeout > 60)) {
+      parameterIsInvalid("timeout", "Must be between 3 and 60 seconds.");
+      return;
+    }
+
     const params = {
       api_key: this._api_key,
-      email: email,
-      ip_address,
+      email,
     };
+    if (ip_address != null) params.ip_address = ip_address;
+    if (timeout != null) params.timeout = timeout;
+
     return createRequest({ requestType: "GET", params, path: "/validate", apiBaseURL: this._api_base_url });
   }
 

tests/zero-bounce.test.js

@@ -199,6 +199,84 @@ describe("ZeroBounceSDK", () => {
       const response = await zeroBounceSDK.validateEmail(email, ip_address);
       expect(response).toEqual(expectedResponse);
     });
+
+    it("should pass options object to the API", async () => {
+      const expectedResponse = {
+        "address": "valid@example.com",
+        "status": "valid",
+        "sub_status": "",
+        "free_email": false,
+        "did_you_mean": null,
+        "account": null,
+        "domain": null,
+        "domain_age_days": "9692",
+        "smtp_provider": "example",
+        "mx_found": "true",
+        "mx_record": "mx.example.com",
+        "firstname": "zero",
+        "lastname": "bounce",
+        "gender": "male",
+        "country": null,
+        "region": null,
+        "city": null,
+        "zipcode": null,
+        "processed_at": "2023-04-27 13:47:23.980"
+      }
+
+      const fetchSpy = jest.spyOn(global, "fetch").mockImplementationOnce(() => Promise.resolve({
+        json: () => Promise.resolve(expectedResponse),
+        text: () => Promise.resolve(JSON.stringify(expectedResponse)),
+      }));
+
+      zeroBounceSDK.init("valid-api-key", ZeroBounceSDK.ApiURL.DEFAULT_API_URL);
+      await zeroBounceSDK.validateEmail(email, { ip_address: ip_address, timeout: 10 });
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining("ip_address=127.0.0.1"),
+        expect.any(Object)
+      );
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining("timeout=10"),
+        expect.any(Object)
+      );
+    });
+
+    it("should pass timeout only via options object", async () => {
+      const expectedResponse = {
+        "address": "valid@example.com",
+        "status": "valid",
+        "sub_status": "",
+      }
+
+      const fetchSpy = jest.spyOn(global, "fetch").mockImplementationOnce(() => Promise.resolve({
+        json: () => Promise.resolve(expectedResponse),
+        text: () => Promise.resolve(JSON.stringify(expectedResponse)),
+      }));
+
+      zeroBounceSDK.init("valid-api-key", ZeroBounceSDK.ApiURL.DEFAULT_API_URL);
+      await zeroBounceSDK.validateEmail(email, { timeout: 30 });
+
+      expect(fetchSpy).toHaveBeenCalledWith(
+        expect.stringContaining("timeout=30"),
+        expect.any(Object)
+      );
+    });
+
+    it("should throw an error if timeout is less than 3", async () => {
+      zeroBounceSDK.init("valid-api-key", ZeroBounceSDK.ApiURL.DEFAULT_API_URL);
+      await zeroBounceSDK.validateEmail(email, { timeout: 2 });
+      expect(console.error).toHaveBeenCalledWith(
+        expect.stringContaining("timeout parameter is invalid")
+      );
+    });
+
+    it("should throw an error if timeout is greater than 60", async () => {
+      zeroBounceSDK.init("valid-api-key", ZeroBounceSDK.ApiURL.DEFAULT_API_URL);
+      await zeroBounceSDK.validateEmail(email, { timeout: 61 });
+      expect(console.error).toHaveBeenCalledWith(
+        expect.stringContaining("timeout parameter is invalid")
+      );
+    });
   });