Merge main into update-readme: resolve conflicts in README.md

Author: narekhovhannisyan

README.md

@@ -280,7 +280,7 @@ General API:
 
 - Suppressions (find & delete) – [`sending/suppressions.ts`](examples/sending/suppressions.ts)
 
-- Billing info – (no example yet) ← add in future
+- Billing info – [`general/billing.ts`](examples/general/billing.ts)
 
 - Accounts info – [`general/accounts.ts`](examples/general/accounts.ts)
 

examples/general/billing.ts

@@ -0,0 +1,20 @@
+import { MailtrapClient } from "mailtrap"
+
+const TOKEN = "<YOUR-TOKEN-HERE>";
+const TEST_INBOX_ID = "<YOUR-TEST-INBOX-ID-HERE>"
+const ACCOUNT_ID = "<YOUR-ACCOUNT-ID-HERE>"
+
+const client = new MailtrapClient({ token: TOKEN, testInboxId: TEST_INBOX_ID, accountId: ACCOUNT_ID });
+
+const billingClient = client.general.billing
+
+const testBillingCycleUsage = async () => {
+  try {
+    const result = await billingClient.getCurrentBillingCycleUsage()
+    console.log("Billing cycle usage:", JSON.stringify(result, null, 2))
+  } catch (error) {
+    console.error(error)
+  }
+}
+
+testBillingCycleUsage()

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

@@ -13,11 +13,13 @@ describe("lib/api/General: ", () => {
         expect(generalAPI).toHaveProperty("accountAccesses");
         expect(generalAPI).toHaveProperty("accounts");
         expect(generalAPI).toHaveProperty("permissions");
+        expect(generalAPI).toHaveProperty("billing");
       });
 
       it("lazily instantiates account-specific APIs via getters when accountId is provided.", () => {
         expect(generalAPI.accountAccesses).toBeDefined();
         expect(generalAPI.permissions).toBeDefined();
+        expect(generalAPI.billing).toBeDefined();
         expect(generalAPI.accounts).toBeDefined();
       });
     });
@@ -56,6 +58,15 @@ describe("lib/api/General: ", () => {
           "Account ID is required for this operation. Please provide accountId when creating GeneralAPI instance."
         );
       });
+
+      it("throws error when accessing billing without accountId.", () => {
+        expect(() => {
+          // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+          generalAPI.billing;
+        }).toThrow(
+          "Account ID is required for this operation. Please provide accountId when creating GeneralAPI instance."
+        );
+      });
     });
 
     describe("account discovery functionality: ", () => {
@@ -78,10 +89,14 @@ describe("lib/api/General: ", () => {
       it("maintains existing API surface for account-specific operations.", () => {
         expect(generalAPI.accountAccesses).toBeDefined();
         expect(generalAPI.permissions).toBeDefined();
+        expect(generalAPI.billing).toBeDefined();
         expect(typeof generalAPI.accountAccesses.listAccountAccesses).toBe(
           "function"
         );
         expect(typeof generalAPI.permissions.getResources).toBe("function");
+        expect(typeof generalAPI.billing.getCurrentBillingCycleUsage).toBe(
+          "function"
+        );
       });
     });
 
@@ -109,10 +124,14 @@ describe("lib/api/General: ", () => {
         expect(generalAPI.accounts).toBeDefined();
         expect(generalAPI.accountAccesses).toBeDefined();
         expect(generalAPI.permissions).toBeDefined();
+        expect(generalAPI.billing).toBeDefined();
         expect(typeof generalAPI.accountAccesses.listAccountAccesses).toBe(
           "function"
         );
         expect(typeof generalAPI.permissions.getResources).toBe("function");
+        expect(typeof generalAPI.billing.getCurrentBillingCycleUsage).toBe(
+          "function"
+        );
       });
     });
   });

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

@@ -0,0 +1,155 @@
+import axios from "axios";
+import AxiosMockAdapter from "axios-mock-adapter";
+
+import Billing from "../../../../lib/api/resources/Billing";
+import handleSendingError from "../../../../lib/axios-logger";
+import MailtrapError from "../../../../lib/MailtrapError";
+
+import CONFIG from "../../../../config";
+
+const { CLIENT_SETTINGS } = CONFIG;
+const { GENERAL_ENDPOINT } = CLIENT_SETTINGS;
+
+describe("lib/api/resources/Billing: ", () => {
+  let mock: AxiosMockAdapter;
+  const accountId = 100;
+  const billingAPI = new Billing(axios, accountId);
+  const responseData = {
+    billing: {
+      cycle_start: "2024-01-01T00:00:00Z",
+      cycle_end: "2024-01-31T23:59:59Z",
+    },
+    sending: {
+      plan: {
+        name: "Pro",
+      },
+      usage: {
+        sent_messages_count: {
+          current: 1000,
+          limit: 10000,
+        },
+      },
+    },
+    testing: {
+      plan: {
+        name: "Pro",
+      },
+      usage: {
+        sent_messages_count: {
+          current: 500,
+          limit: 5000,
+        },
+        forwarded_messages_count: {
+          current: 200,
+          limit: 2000,
+        },
+      },
+    },
+  };
+
+  describe("class Billing(): ", () => {
+    describe("init: ", () => {
+      it("initializes with all necessary params.", () => {
+        expect(billingAPI).toHaveProperty("getCurrentBillingCycleUsage");
+      });
+    });
+  });
+
+  beforeAll(() => {
+    /**
+     * Init Axios interceptors for handling response.data, errors.
+     */
+    axios.interceptors.response.use(
+      (response) => response.data,
+      handleSendingError
+    );
+    mock = new AxiosMockAdapter(axios);
+  });
+
+  afterEach(() => {
+    mock.reset();
+  });
+
+  describe("getCurrentBillingCycleUsage(): ", () => {
+    it("successfully gets billing cycle usage.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/billing/usage`;
+
+      expect.assertions(2);
+
+      mock.onGet(endpoint).reply(200, responseData);
+      const result = await billingAPI.getCurrentBillingCycleUsage();
+
+      expect(mock.history.get[0].url).toEqual(endpoint);
+      expect(result).toEqual(responseData);
+    });
+
+    it("fails with error when accountId is invalid.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/billing/usage`;
+      const expectedErrorMessage = "Account not found";
+      const statusCode = 404;
+
+      expect.assertions(3);
+
+      mock.onGet(endpoint).reply(statusCode, { error: expectedErrorMessage });
+
+      try {
+        await billingAPI.getCurrentBillingCycleUsage();
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual(expectedErrorMessage);
+          // Verify status code is accessible via cause property
+          // @ts-expect-error ES5 types don't know about cause property
+          expect(error.cause?.response?.status).toEqual(statusCode);
+        }
+      }
+    });
+
+    it("fails with error when billing endpoint returns 403 Forbidden.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/billing/usage`;
+      const expectedErrorMessage = "Access denied";
+      const statusCode = 403;
+
+      expect.assertions(3);
+
+      mock.onGet(endpoint).reply(statusCode, { error: expectedErrorMessage });
+
+      try {
+        await billingAPI.getCurrentBillingCycleUsage();
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual(expectedErrorMessage);
+          // Verify status code is accessible via cause property
+          // @ts-expect-error ES5 types don't know about cause property
+          expect(error.cause?.response?.status).toEqual(statusCode);
+        }
+      }
+    });
+
+    it("fails with error when no error body is provided.", async () => {
+      const endpoint = `${GENERAL_ENDPOINT}/api/accounts/${accountId}/billing/usage`;
+      const expectedErrorMessage = "Request failed with status code 500";
+      const statusCode = 500;
+
+      expect.assertions(3);
+
+      mock.onGet(endpoint).reply(statusCode);
+
+      try {
+        await billingAPI.getCurrentBillingCycleUsage();
+      } catch (error) {
+        expect(error).toBeInstanceOf(MailtrapError);
+
+        if (error instanceof MailtrapError) {
+          expect(error.message).toEqual(expectedErrorMessage);
+          // Verify status code is accessible via cause property
+          // @ts-expect-error ES5 types don't know about cause property
+          expect(error.cause?.response?.status).toEqual(statusCode);
+        }
+      }
+    });
+  });
+});

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

@@ -111,8 +111,8 @@ describe("lib/api/resources/ContactExports: ", () => {
       } catch (error) {
         expect(error).toBeInstanceOf(MailtrapError);
         if (error instanceof MailtrapError) {
-          // axios logger returns "[object Object]" for error objects, so we check for that
-          expect(error.message).toBe("[object Object]");
+          // When errors object doesn't match recognized pattern, falls back to default Axios error message
+          expect(error.message).toBe("Request failed with status code 422");
         }
       }
     });

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

@@ -198,11 +198,9 @@ describe("lib/api/resources/ContactImports: ", () => {
       } 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]");
+          expect(error.message).toBe(
+            "invalid-email-1: email: is invalid, is required | invalid-email-2: Contact limit exceeded"
+          );
         }
       }
     });