Merge branch 'main' into contact-exports-api

Author: narekhovhannisyan

README.md

@@ -30,13 +30,14 @@ Currently, with this SDK you can:
   - Inbox management
   - Project management
 - Contact management
-  - Contacts CRUD
-  - Lists CRUD
-  - Contact Fields CRUD
+  - Contacts
   - Contact Exports
+  - Contact Fields
+  - Contact Imports
+  - Contact Lists
 - General
-  - Templates CRUD
-  - Suppressions management (find and delete)
+  - Templates
+  - Suppressions management
   - Account access management
   - Permissions management
   - List accounts you have access to
@@ -130,6 +131,9 @@ Refer to the [`examples`](examples) folder for the source code of this and other
 ### Contact Exports API
 
 - [Contact Exports](examples/contact-exports/everything.ts)
+### Contact Imports API
+
+- [Contact Imports](examples/contact-imports/everything.ts)
 
 ### Sending API
 

examples/contact-imports/everything.ts

@@ -0,0 +1,36 @@
+import { MailtrapClient } from "mailtrap";
+
+const TOKEN = "<YOUR-TOKEN-HERE>";
+const ACCOUNT_ID = "<YOUR-ACCOUNT-ID-HERE>";
+
+const client = new MailtrapClient({
+  token: TOKEN,
+  accountId: ACCOUNT_ID
+});
+
+async function runContactImportsFlow() {
+  const importData = {
+    contacts: [
+      {
+        email: "customer1@example.com"
+      },
+      {
+        email: "customer2@example.com"
+      }
+    ]
+  };
+
+  try {
+    // Create import
+    const response = await client.contactImports.create(importData);
+    console.log("Import created:", response);
+
+    // Get import by ID
+    const importDetails = await client.contactImports.get(response.id);
+    console.log("Import details:", importDetails);
+  } catch (error: any) {
+    console.error("Error:", error);
+  }
+}
+
+runContactImportsFlow();

package.json

@@ -7,6 +7,7 @@
     "axios": ">=0.27"
   },
   "devDependencies": {
+    "rimraf": "^5.0.5",
     "@babel/core": "^7.20.5",
     "@babel/preset-env": "^7.20.2",
     "@babel/preset-typescript": "^7.18.6",
@@ -39,6 +40,13 @@
   ],
   "license": "MIT",
   "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
   "peerDependencies": {
     "@types/nodemailer": "^6.4.9",
     "nodemailer": "^7.0.7"
@@ -53,10 +61,12 @@
   },
   "repository": "https://github.com/railsware/mailtrap-nodejs",
   "scripts": {
+    "build": "rimraf dist && tsc --project tsconfig.build.json",
     "lint": "yarn lint:eslint && yarn lint:tsc",
     "lint:eslint": "yarn run eslint . --ext .js,.ts",
     "lint:tsc": "tsc -p . --noEmit --incremental false",
-    "prepublish": "rm -rf dist && tsc --project tsconfig.build.json",
+    "prepare": "yarn build",
+    "prepublishOnly": "yarn build",
     "test": "jest --verbose",
     "coverage": "jest --coverage"
   },

src/__tests__/lib/api/ContactImports.test.ts

@@ -0,0 +1,17 @@
+import axios from "axios";
+
+import ContactImports from "../../../lib/api/ContactImports";
+
+describe("lib/api/ContactImports: ", () => {
+  const accountId = 100;
+  const contactImportsAPI = new ContactImports(axios, accountId);
+
+  describe("class ContactImports(): ", () => {
+    describe("init: ", () => {
+      it("initializes with all necessary params.", () => {
+        expect(contactImportsAPI).toHaveProperty("create");
+        expect(contactImportsAPI).toHaveProperty("get");
+      });
+    });
+  });
+});

src/__tests__/lib/api/resources/ContactImports.test.ts

@@ -0,0 +1,265 @@
+import axios from "axios";
+import AxiosMockAdapter from "axios-mock-adapter";
+
+import ContactImportsApi from "../../../../lib/api/resources/ContactImports";
+import handleSendingError from "../../../../lib/axios-logger";
+import MailtrapError from "../../../../lib/MailtrapError";
+import {
+  ContactImportResponse,
+  ImportContactsRequest,
+} from "../../../../types/api/contact-imports";
+
+import CONFIG from "../../../../config";
+
+const { CLIENT_SETTINGS } = CONFIG;
+const { GENERAL_ENDPOINT } = CLIENT_SETTINGS;
+
+describe("lib/api/resources/ContactImports: ", () => {
+  let mock: AxiosMockAdapter;
+  const accountId = 100;
+  const contactImportsAPI = new ContactImportsApi(axios, accountId);
+
+  const createImportRequest: ImportContactsRequest = {
+    contacts: [
+      {
+        email: "customer1@example.com",
+        fields: {
+          first_name: "John",
+          last_name: "Doe",
+        },
+        list_ids_included: [1, 2],
+      },
+      {
+        email: "customer2@example.com",
+        fields: {
+          first_name: "Jane",
+          zip_code: 12345,
+        },
+        list_ids_excluded: [3],
+      },
+    ],
+  };
+
+  const createImportResponse: ContactImportResponse = {
+    id: 1,
+    status: "created",
+    created_contacts_count: 2,
+    updated_contacts_count: 0,
+    contacts_over_limit_count: 0,
+  };
+
+  const getImportResponse: ContactImportResponse = {
+    id: 1,
+    status: "finished",
+    created_contacts_count: 2,
+    updated_contacts_count: 0,
+    contacts_over_limit_count: 0,
+  };
+
+  describe("class ContactImportsApi(): ", () => {
+    describe("init: ", () => {
+      it("initializes with all necessary params.", () => {
+        expect(contactImportsAPI).toHaveProperty("create");
+        expect(contactImportsAPI).toHaveProperty("get");
+      });
+    });
+  });
+
+  beforeAll(() => {
+    axios.interceptors.response.use(
+      (response) => response.data,
+      handleSendingError
+    );
+    mock = new AxiosMockAdapter(axios);
+  });
+
+  afterEach(() => {
+    mock.reset();
+  });
+
+  describe("create(): ", () => {
+    it("successfully creates a contact import.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/contacts/imports`;
+      const expectedResponseData = createImportResponse;
+
+      expect.assertions(2);
+
+      mock
+        .onPost(endpoint, createImportRequest)
+        .reply(200, expectedResponseData);
+      const result = await contactImportsAPI.create(createImportRequest);
+
+      expect(mock.history.post[0].url).toEqual(endpoint);
+      expect(result).toEqual(expectedResponseData);
+    });
+
+    it("successfully creates a contact import with minimal data.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/contacts/imports`;
+      const minimalRequest: ImportContactsRequest = {
+        contacts: [
+          {
+            email: "customer@example.com",
+          },
+        ],
+      };
+      const expectedResponseData: ContactImportResponse = {
+        id: 2,
+        status: "created",
+      };
+
+      expect.assertions(2);
+
+      mock.onPost(endpoint, minimalRequest).reply(200, expectedResponseData);
+      const result = await contactImportsAPI.create(minimalRequest);
+
+      expect(mock.history.post[0].url).toEqual(endpoint);
+      expect(result).toEqual(expectedResponseData);
+    });
+
+    it("fails with error.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/contacts/imports`;
+      const expectedErrorMessage = "Request failed with status code 400";
+
+      expect.assertions(2);
+
+      mock.onPost(endpoint).reply(400, { error: expectedErrorMessage });
+
+      try {
+        await contactImportsAPI.create(createImportRequest);
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual(expectedErrorMessage);
+        }
+      }
+    });
+
+    it("fails with validation error.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/contacts/imports`;
+      const invalidRequest: ImportContactsRequest = {
+        contacts: [
+          {
+            email: "invalid-email",
+          },
+        ],
+      };
+      const expectedErrorMessage = "Invalid email format";
+
+      expect.assertions(2);
+
+      mock.onPost(endpoint).reply(422, { error: expectedErrorMessage });
+
+      try {
+        await contactImportsAPI.create(invalidRequest);
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual(expectedErrorMessage);
+        }
+      }
+    });
+
+    it("fails with array of validation errors.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/contacts/imports`;
+      const invalidRequest: ImportContactsRequest = {
+        contacts: [
+          {
+            email: "invalid-email-1",
+          },
+          {
+            email: "invalid-email-2",
+          },
+        ],
+      };
+
+      expect.assertions(2);
+
+      // API returns errors as an array of objects (confirmed by actual API response)
+      // Each object contains the email and nested errors object with field-specific messages
+      mock.onPost(endpoint).reply(422, {
+        errors: [
+          {
+            email: "invalid-email-1",
+            errors: {
+              email: ["is invalid", "is required"],
+            },
+          },
+          {
+            email: "invalid-email-2",
+            errors: {
+              base: ["Contact limit exceeded"],
+            },
+          },
+        ],
+      });
+
+      try {
+        await contactImportsAPI.create(invalidRequest);
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+        if (error instanceof MailtrapError) {
+          // Note: Current axios-logger doesn't properly handle array of objects format,
+          // so it falls back to stringifying the array, resulting in [object Object],[object Object]
+          // This test documents the current behavior. Updating axios-logger to properly
+          // parse this format will be a separate task.
+          expect(error.message).toBe("[object Object],[object Object]");
+        }
+      }
+    });
+  });
+
+  describe("get(): ", () => {
+    it("successfully gets a contact import by ID.", async () => {
+      const importId = 1;
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/contacts/imports/${importId}`;
+      const expectedResponseData = getImportResponse;
+
+      expect.assertions(2);
+
+      mock.onGet(endpoint).reply(200, expectedResponseData);
+      const result = await contactImportsAPI.get(importId);
+
+      expect(mock.history.get[0].url).toEqual(endpoint);
+      expect(result).toEqual(expectedResponseData);
+    });
+
+    it("successfully gets a contact import with all status fields.", async () => {
+      const importId = 2;
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/contacts/imports/${importId}`;
+      const expectedResponseData: ContactImportResponse = {
+        id: importId,
+        status: "failed",
+        created_contacts_count: 5,
+        updated_contacts_count: 3,
+        contacts_over_limit_count: 2,
+      };
+
+      expect.assertions(2);
+
+      mock.onGet(endpoint).reply(200, expectedResponseData);
+      const result = await contactImportsAPI.get(importId);
+
+      expect(mock.history.get[0].url).toEqual(endpoint);
+      expect(result).toEqual(expectedResponseData);
+    });
+
+    it("fails with error when getting a contact import.", async () => {
+      const importId = 999;
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/contacts/imports/${importId}`;
+      const expectedErrorMessage = "Contact import not found";
+
+      expect.assertions(2);
+
+      mock.onGet(endpoint).reply(404, { error: expectedErrorMessage });
+
+      try {
+        await contactImportsAPI.get(importId);
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual(expectedErrorMessage);
+        }
+      }
+    });
+  });
+});