Dynamic user agent

src/__tests__/lib/get-agent.test.ts

@@ -0,0 +1,256 @@
+import CONFIG from "../../config";
+
+// Mock the config
+jest.mock("../../config", () => ({
+  CLIENT_SETTINGS: {
+    USER_AGENT:
+      "mailtrap-nodejs (https://github.com/railsware/mailtrap-nodejs)",
+    MCP_USER_AGENT: "mailtrap-mcp (https://github.com/railsware/mailtrap-mcp)",
+  },
+}));
+
+describe("get-agent", () => {
+  let originalCwd: string;
+  let originalError: typeof Error;
+
+  beforeEach(() => {
+    // Store original values
+    originalCwd = process.cwd();
+    originalError = global.Error;
+  });
+
+  afterEach(() => {
+    // Restore original values
+    process.cwd = jest.fn().mockReturnValue(originalCwd);
+    global.Error = originalError;
+    jest.clearAllMocks();
+  });
+
+  describe("getDynamicUserAgent", () => {
+    it("should return USER_AGENT by default", () => {
+      // Import after mocking to get fresh module
+      const { default: getDynamicUserAgent } = jest.requireActual(
+        "../../lib/get-agent"
+      );
+
+      const result = getDynamicUserAgent();
+      expect(result).toBe(CONFIG.CLIENT_SETTINGS.USER_AGENT);
+    });
+
+    it("should return MCP_USER_AGENT when cwd contains 'mailtrap-mcp' and not in node_modules", () => {
+      process.cwd = jest.fn().mockReturnValue("/path/to/mailtrap-mcp");
+
+      // Clear module cache and re-import to get fresh module
+      jest.resetModules();
+      const { default: getDynamicUserAgent } = jest.requireActual(
+        "../../lib/get-agent"
+      );
+
+      const result = getDynamicUserAgent();
+      expect(result).toBe(CONFIG.CLIENT_SETTINGS.MCP_USER_AGENT);
+    });
+
+    it("should return USER_AGENT when cwd contains 'mailtrap-mcp' but is in node_modules", () => {
+      process.cwd = jest
+        .fn()
+        .mockReturnValue("/path/to/node_modules/mailtrap-mcp");
+
+      jest.resetModules();
+      const { default: getDynamicUserAgent } = jest.requireActual(
+        "../../lib/get-agent"
+      );
+
+      const result = getDynamicUserAgent();
+      expect(result).toBe(CONFIG.CLIENT_SETTINGS.USER_AGENT);
+    });
+
+    it("should return USER_AGENT when process.cwd() throws an error", () => {
+      process.cwd = jest.fn().mockImplementation(() => {
+        throw new Error("Permission denied");
+      });
+
+      jest.resetModules();
+      const { default: getDynamicUserAgent } = jest.requireActual(
+        "../../lib/get-agent"
+      );
+
+      const result = getDynamicUserAgent();
+      expect(result).toBe(CONFIG.CLIENT_SETTINGS.USER_AGENT);
+    });
+
+    it("should return MCP_USER_AGENT when call stack contains 'mailtrap-mcp' and not from node_modules/mailtrap", () => {
+      global.Error = jest.fn().mockImplementation(() => ({
+        stack: `
+Error: Test error
+    at Object.<anonymous> (/path/to/mailtrap-mcp/index.js:10:1)
+    at Module._compile (internal/modules/cjs/loader.js:1063:30)
+        `,
+      })) as any;
+
+      process.cwd = jest.fn().mockReturnValue("/path/to/regular-app");
+
+      jest.resetModules();
+      const { default: getDynamicUserAgent } = jest.requireActual(
+        "../../lib/get-agent"
+      );
+
+      const result = getDynamicUserAgent();
+      expect(result).toBe(CONFIG.CLIENT_SETTINGS.MCP_USER_AGENT);
+    });
+
+    it("should return USER_AGENT when call stack contains 'mailtrap-mcp' but is from node_modules/mailtrap", () => {
+      global.Error = jest.fn().mockImplementation(() => ({
+        stack: `
+Error: Test error
+    at Object.<anonymous> (/path/to/node_modules/mailtrap/index.js:10:1)
+    at Module._compile (internal/modules/cjs/loader.js:1063:30)
+        `,
+      })) as any;
+
+      process.cwd = jest.fn().mockReturnValue("/path/to/regular-app");
+
+      jest.resetModules();
+      const { default: getDynamicUserAgent } = jest.requireActual(
+        "../../lib/get-agent"
+      );
+
+      const result = getDynamicUserAgent();
+      expect(result).toBe(CONFIG.CLIENT_SETTINGS.USER_AGENT);
+    });
+
+    it("should return USER_AGENT when call stack does not contain 'mailtrap-mcp'", () => {
+      global.Error = jest.fn().mockImplementation(() => ({
+        stack: `
+Error: Test error
+    at Object.<anonymous> (/path/to/regular-app/index.js:10:1)
+    at Module._compile (internal/modules/cjs/loader.js:1063:30)
+        `,
+      })) as any;
+
+      process.cwd = jest.fn().mockReturnValue("/path/to/regular-app");
+
+      jest.resetModules();
+      const { default: getDynamicUserAgent } = jest.requireActual(
+        "../../lib/get-agent"
+      );
+
+      const result = getDynamicUserAgent();
+      expect(result).toBe(CONFIG.CLIENT_SETTINGS.USER_AGENT);
+    });
+
+    it("should return USER_AGENT when call stack is undefined", () => {
+      global.Error = jest.fn().mockImplementation(() => ({
+        stack: undefined,
+      })) as any;
+
+      process.cwd = jest.fn().mockReturnValue("/path/to/regular-app");
+
+      jest.resetModules();
+      const { default: getDynamicUserAgent } = jest.requireActual(
+        "../../lib/get-agent"
+      );
+
+      const result = getDynamicUserAgent();
+      expect(result).toBe(CONFIG.CLIENT_SETTINGS.USER_AGENT);
+    });
+
+    it("should handle edge cases gracefully", () => {
+      // All undefined/null cases
+      process.cwd = jest.fn().mockImplementation(() => {
+        throw new Error("Permission denied");
+      });
+      global.Error = jest.fn().mockImplementation(() => ({
+        stack: undefined,
+      })) as any;
+
+      jest.resetModules();
+      const { default: getDynamicUserAgent } = jest.requireActual(
+        "../../lib/get-agent"
+      );
+
+      const result = getDynamicUserAgent();
+      expect(result).toBe(CONFIG.CLIENT_SETTINGS.USER_AGENT);
+    });
+  });
+
+  describe("real-world scenarios", () => {
+    it("should detect MCP context when running from MCP working directory", () => {
+      process.cwd = jest
+        .fn()
+        .mockReturnValue("/Users/user/projects/mailtrap-mcp");
+
+      jest.resetModules();
+      const { default: getDynamicUserAgent } = jest.requireActual(
+        "../../lib/get-agent"
+      );
+
+      const result = getDynamicUserAgent();
+      expect(result).toBe(CONFIG.CLIENT_SETTINGS.MCP_USER_AGENT);
+    });
+
+    it("should not detect MCP context when used as a regular npm package", () => {
+      process.cwd = jest.fn().mockReturnValue("/Users/user/projects/my-app");
+
+      jest.resetModules();
+      const { default: getDynamicUserAgent } = jest.requireActual(
+        "../../lib/get-agent"
+      );
+
+      const result = getDynamicUserAgent();
+      expect(result).toBe(CONFIG.CLIENT_SETTINGS.USER_AGENT);
+    });
+  });
+
+  describe("integration with MailtrapClient", () => {
+    it("should be used by MailtrapClient for User-Agent header", () => {
+      // Mock the full config for MailtrapClient
+      jest.doMock("../../config", () => ({
+        CLIENT_SETTINGS: {
+          SENDING_ENDPOINT: "https://send.api.mailtrap.io",
+          BULK_ENDPOINT: "https://bulk.api.mailtrap.io",
+          TESTING_ENDPOINT: "https://sandbox.api.mailtrap.io",
+          GENERAL_ENDPOINT: "https://mailtrap.io",
+          USER_AGENT:
+            "mailtrap-nodejs (https://github.com/railsware/mailtrap-nodejs)",
+          MCP_USER_AGENT:
+            "mailtrap-mcp (https://github.com/railsware/mailtrap-mcp)",
+          MAX_REDIRECTS: 0,
+          TIMEOUT: 10000,
+        },
+        ERRORS: {
+          FILENAME_REQUIRED: "Filename is required.",
+          CONTENT_REQUIRED: "Content is required.",
+          SUBJECT_REQUIRED: "Subject is required.",
+          FROM_REQUIRED: "From is required.",
+          SENDING_FAILED: "Sending failed.",
+          NO_DATA_ERROR: "No Data.",
+          TEST_INBOX_ID_MISSING:
+            "testInboxId is missing, testing API will not work.",
+          ACCOUNT_ID_MISSING:
+            "accountId is missing, some features of testing API may not work properly.",
+          BULK_SANDBOX_INCOMPATIBLE:
+            "Bulk mode is not applicable for sandbox API.",
+        },
+        TRANSPORT_SETTINGS: {
+          NAME: "MailtrapTransport",
+        },
+      }));
+
+      // Clear module cache and re-import
+      jest.resetModules();
+      const { default: MailtrapClient } = jest.requireActual(
+        "../../lib/MailtrapClient"
+      );
+
+      // Create a client instance
+      const client = new MailtrapClient({
+        token: "test-token",
+      });
+
+      // The User-Agent should be set in the axios instance
+      // We can't easily test the internal axios instance, but we can verify
+      // that the function is called during client creation
+      expect(client).toBeDefined();
+    });
+  });
+});

src/config/index.ts

@@ -18,6 +18,7 @@ export default {
     GENERAL_ENDPOINT: "https://mailtrap.io",
     USER_AGENT:
       "mailtrap-nodejs (https://github.com/railsware/mailtrap-nodejs)",
+    MCP_USER_AGENT: "mailtrap-mcp (https://github.com/railsware/mailtrap-mcp)",
     MAX_REDIRECTS: 0,
     TIMEOUT: 10000,
   },

src/lib/MailtrapClient.ts

@@ -6,12 +6,14 @@ import axios, { AxiosInstance } from "axios";
 import encodeMailBuffers from "./mail-buffer-encoder";
 import handleSendingError from "./axios-logger";
 import MailtrapError from "./MailtrapError";
+import getDynamicUserAgent from "./get-agent";
 
 import GeneralAPI from "./api/General";
 import TestingAPI from "./api/Testing";
 import ContactsBaseAPI from "./api/Contacts";
 import ContactListsBaseAPI from "./api/ContactLists";
 import TemplatesBaseAPI from "./api/Templates";
+import SuppressionsBaseAPI from "./api/Suppressions";
 
 import CONFIG from "../config";
 
@@ -22,13 +24,11 @@ import {
   BatchSendResponse,
   BatchSendRequest,
 } from "../types/mailtrap";
-import SuppressionsBaseAPI from "./api/Suppressions";
 
 const { CLIENT_SETTINGS, ERRORS } = CONFIG;
 const {
   SENDING_ENDPOINT,
   MAX_REDIRECTS,
-  USER_AGENT,
   TIMEOUT,
   TESTING_ENDPOINT,
   BULK_ENDPOINT,
@@ -66,7 +66,7 @@ export default class MailtrapClient {
       headers: {
         Authorization: `Bearer ${token}`,
         Connection: "keep-alive",
-        "User-Agent": USER_AGENT,
+        "User-Agent": getDynamicUserAgent(),
       },
       maxRedirects: MAX_REDIRECTS,
       timeout: TIMEOUT,
@@ -182,12 +182,12 @@ export default class MailtrapClient {
    */
   public async send(mail: Mail): Promise<SendResponse> {
     const host = this.determineHost();
-
     this.validateTestInboxIdPresence();
 
     const url = `${host}/api/send${
       this.sandbox && this.testInboxId ? `/${this.testInboxId}` : ""
     }`;
+
     const preparedMail = encodeMailBuffers(mail);
 
     return this.axios.post<SendResponse, SendResponse>(url, preparedMail);

src/lib/get-agent.ts

@@ -0,0 +1,75 @@
+import CONFIG from "../config";
+
+const { USER_AGENT, MCP_USER_AGENT } = CONFIG.CLIENT_SETTINGS;
+
+/**
+ * Checks if the main module filename indicates MCP context.
+ * @returns true if main module contains "mailtrap-mcp" and is not in node_modules
+ */
+function isMainModuleMCP(): boolean {
+  const mainFile = require?.main?.filename;
+
+  return !!(
+    mainFile &&
+    mainFile.includes("mailtrap-mcp") &&
+    !mainFile.includes("node_modules")
+  );
+}
+
+/**
+ * Checks if running in MCP runtime context (Claude Desktop).
+ * @returns true if main module is from MCP runtime
+ */
+function isMCPRuntimeContext(): boolean {
+  const mainFile = require?.main?.filename;
+
+  return !!(
+    mainFile &&
+    (mainFile.includes("mcp-runtime") ||
+      mainFile.includes("nodeHost.js") ||
+      mainFile.includes("Claude.app"))
+  );
+}
+
+/**
+ * Checks if the current working directory indicates MCP context.
+ * @returns true if cwd contains "mailtrap-mcp" and is not in node_modules
+ */
+function isWorkingDirectoryMCP(): boolean {
+  try {
+    const cwd = process.cwd();
+    return cwd.includes("mailtrap-mcp") && !cwd.includes("node_modules");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Checks if the call stack indicates MCP context.
+ * @returns true if stack contains "mailtrap-mcp" and is not from node_modules/mailtrap
+ */
+function isCallStackMCP(): boolean {
+  const { stack } = new Error();
+
+  return !!(
+    stack &&
+    stack.includes("mailtrap-mcp") &&
+    !stack.includes("node_modules/mailtrap")
+  );
+}
+
+/**
+ * Gets the appropriate User-Agent string based on the current context.
+ * @returns The User-Agent string for the current context
+ */
+function getDynamicUserAgent(): string {
+  const isMailtrapMCPContext =
+    isMainModuleMCP() ||
+    isWorkingDirectoryMCP() ||
+    isCallStackMCP() ||
+    isMCPRuntimeContext();
+
+  return isMailtrapMCPContext ? MCP_USER_AGENT : USER_AGENT;
+}
+
+export default getDynamicUserAgent;