@zerobounce/zero-bounce-sdk 1.2.0 → 1.2.1

package/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/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": {

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

package/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,9 +40,11 @@ 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;
@@ -50,11 +52,28 @@ export class ZeroBounceSDK {
       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 });
   }
 

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

package/dist/zeroBounceSDK.js

@@ -1 +0,0 @@
-!function(e,i){"object"==typeof exports&&"object"==typeof module?module.exports=i():"function"==typeof define&&define.amd?define([],i):"object"==typeof exports?exports.ZeroBounceSDK=i():e.ZeroBounceSDK=i()}(this,(()=>(()=>{"use strict";var e={d:(i,t)=>{for(var a in t)e.o(t,a)&&!e.o(i,a)&&Object.defineProperty(i,a,{enumerable:!0,get:t[a]})},o:(e,i)=>Object.prototype.hasOwnProperty.call(e,i)},i={};e.d(i,{default:()=>s});const t={Accept:"*/*","Accept-Encoding":"gzip, deflate, br",Connection:"keep-alive"};async function a({requestType:e,body:i=null,params:a=null,path:r,batch:n=!1,returnText:s=!1,scoring:l=!1}){const o=`${n?"https://bulkapi.zerobounce.net/v2":"https://api.zerobounce.net/v2"}${r}?${new URLSearchParams(a)}`;try{const a=await fetch(o,{method:e,headers:t,body:i});if(s){const e=await a.text();return e.includes('"success":"False"')?JSON.parse(e):function(e,i){if(!window.navigator.msSaveOrOpenBlob){const t=document.createElement("a");document.body.appendChild(t);const a=window.URL.createObjectURL(e);return t.href=a,t.download=i,t.click(),setTimeout((()=>{window.URL.revokeObjectURL(a),document.body.removeChild(t)}),0),i}window.navigator.msSaveOrOpenBlob(e,i)}(new Blob([e],{type:"application/json"}),`result${l?"-scoring":""}.csv`)}if(403===a.status)throw new Error("[Error]: api_key is invalid");return await a.json()}catch(e){throw new Error(e)}}function r(){console.error("ZeroBounce: Call init function first with a valid api key.")}function n(e,i=""){console.error(`ZeroBounce: ${e} parameter is missing. ${i}`)}const s=class{constructor(){this._initialized=!1,this._api_key=null}init(e){e?(this._api_key=e,this._initialized=!0):n("Api key","Please provide a valid API key.")}getCredits(){if(this._initialized)return a({requestType:"GET",params:{api_key:this._api_key},path:"/getcredits"});r()}validateEmail(e,i=null){if(this._initialized){if(e)return a({requestType:"GET",params:{api_key:this._api_key,email:e,ip_address:i},path:"/validate"});n("Email")}else r()}getApiUsage(e,i){if(this._initialized)if(e){if(i)return a({requestType:"GET",params:{api_key:this._api_key,start_date:e,end_date:i},path:"/getapiusage"});n("End date","Format: YYYY-MM-DD")}else n("Start date","Format: YYYY-MM-DD");else r()}validateBatch(e){if(!this._initialized)return void r();if(!e)return void n("Email list");const i={api_key:this._api_key,email_batch:e};return a({requestType:"POST",path:"/validatebatch",body:JSON.stringify(i),batch:!0})}getEmailActivity(e){if(this._initialized){if(e)return a({requestType:"GET",params:{api_key:this._api_key,email:e},path:"/activity"});n("Email")}else r()}sendFile({file:e,email_address_column:i,first_name_column:t=!1,return_url:s=!1,last_name_column:l=!1,gender_column:o=!1,ip_address_column:d=!1,has_header_row:p=!1,remove_duplicate:u=!1}){if(!this._initialized)return void r();if(!e)return void n("file");if(!i)return void n("email_address_column");const _=new FormData;return s&&_.append("return_url",s),t&&_.append("first_name_column",t),l&&_.append("last_name_column",l),o&&_.append("gender_column",o),d&&_.append("ip_address_column",d),_.append("email_address_column",i),_.append("file",e),_.append("has_header_row",p),_.append("remove_duplicate",u),_.append("api_key",this._api_key),a({requestType:"POST",path:"/sendfile",body:_,batch:!0})}sendScoringFile({file:e,email_address_column:i,return_url:t=!1,has_header_row:s=!1,remove_duplicate:l=!1}){if(!this._initialized)return void r();if(!e)return void n("file: File");if(!i)return void n("email_address_column: number");const o=new FormData;return t&&o.append("return_url",t),o.append("file",e),o.append("email_address_column",i),o.append("has_header_row",s),o.append("api_key",this._api_key),o.append("remove_duplicate",l),a({requestType:"POST",path:"/scoring/sendfile",body:o,batch:!0})}_getStatusUtil(e,i){if(this._initialized){if(e)return a({requestType:"GET",params:{api_key:this._api_key,file_id:e},path:i,batch:!0});n("File id")}else r()}getFileStatus(e){return this._getStatusUtil(e,"/filestatus")}getScoringFileStatus(e){return this._getStatusUtil(e,"/scoring/filestatus")}_getFileUtil(e,i,t=!1){if(this._initialized){if(e)return a({requestType:"GET",params:{api_key:this._api_key,file_id:e},path:i,batch:!0,returnText:!0,scoring:t});n("File id")}else r()}getFile(e){return this._getFileUtil(e,"/getfile")}getScoringFile(e){return this._getFileUtil(e,"/scoring/getfile",!0)}_deleteFileUtil(e,i,t=!1){if(this._initialized){if(e)return a({requestType:"GET",params:{api_key:this._api_key,file_id:e},path:i,batch:!0,scoring:t});n("File id")}else r()}deleteFile(e){return this._deleteFileUtil(e,"/deletefile")}deleteScoringFile(e){return this._deleteFileUtil(e,"/scoring/deletefile",!0)}guessFormat({domain:e,first_name:i=null,middle_name:t=null,last_name:s=null}){if(this._initialized){if(e)return a({requestType:"GET",params:{api_key:this._api_key,domain:e,first_name:i,middle_name:t,last_name:s},path:"/guessformat"});n("domain")}else r()}};return i.default})()));