feat: implement MailGun webhook service for logging email events

Implemented a production-ready TypeScript/Express.js service to receive
and log MailGun webhook events (delivered, failed, opened, clicked, etc.).

Key features:
- Webhook endpoint (POST /webhook) with comprehensive event logging
- Full TypeScript type definitions for all MailGun event types
- Prometheus metrics integration for monitoring
- Health check endpoint (GET /ping)
- Comprehensive Jest test suite with 87.76% coverage
- Docker containerization with build scripts

Removed template/example code:
- All SQL/MSSQL dependencies and related code
- Example auth router and middleware
- PRTG metrics support (simplified to Prometheus only)
- Unused middleware (CORS, IP whitelist, request parsing/validation)
- Template documentation (kept only MailGun webhook API spec)

The service is clean, minimal, and focused solely on receiving and
logging MailGun webhook events to the console.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

mailgun-webhook/tests/__mocks__/crypto.ts

@@ -0,0 +1 @@
+export const randomUUID = () => 'mock-uuid-created-by-crypto';

mailgun-webhook/tests/__mocks__/logger.ts

@@ -0,0 +1,18 @@
+/**
+ * Mock implementation of the logger module for testing
+ */
+
+export const logServer = jest.fn();
+export const logHealthCheck = jest.fn();
+export const logError = jest.fn();
+export const logWarn = jest.fn();
+export const logInfo = jest.fn();
+
+// Helper function to reset all mocks
+export const resetAllLoggerMocks = () => {
+    logServer.mockClear();
+    logHealthCheck.mockClear();
+    logError.mockClear();
+    logWarn.mockClear();
+    logInfo.mockClear();
+};

mailgun-webhook/tests/__mocks__/prom-client.ts

@@ -0,0 +1,29 @@
+import { LabelValues } from "prom-client";
+
+export class Counter {
+    public inc() {
+
+    }
+}
+
+export class Histogram<T extends string> {
+    startTimer(labels?: LabelValues<T>): (labels?: LabelValues<T>) => void {
+        return((labels?: LabelValues<T>) => { });
+    }
+}
+
+class Register {
+    public setDefaultLabels(labels: Object) {
+
+    }
+
+    public metrics(): Promise<string> {
+        return(Promise.resolve(""));
+    }
+
+    public get contentType() {
+        return("");
+    }
+}
+
+export const register = new Register();

mailgun-webhook/tests/helpers/mockHttpContext.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview
+ * This file is a part of an "auth" example router, which was taken from an existing integration.
+ * It is to be used only as a reference for how an API router for a web service should be structured.
+ * In a real-live implementation all files related to `/auth` route example should be removed
+ * by new set of files implementing the new API.
+ */
+import { Request, Response, NextFunction } from 'express';
+import { AppLocals } from "../../src/types/AppLocals";
+
+interface IMockHttpParams {
+  sessionID?: number
+  sessionGUID?: string
+  table_id?: string
+  clientIp?: string
+  free_play: 0 | 1
+}
+
+interface IMockHttpContext {
+  clientIpAddress?:string
+  reqPath?:string
+  headersSent?:boolean
+  writableEnded?:boolean
+  method?:string
+  params?: IMockHttpParams
+}
+
+export const defaultMockParams:IMockHttpParams = {
+  sessionID: 123,
+  sessionGUID: '016e6812-b915-4e5e-94fe-193582239b96',
+  table_id: 'mock-table-id',
+  clientIp: '192.168.1.10',
+  free_play: 0
+}
+
+export const mockHttpContext = ({reqPath="/", headersSent=false, writableEnded=false, method="GET", params=defaultMockParams}:IMockHttpContext|undefined = {}) => {
+    const req = {
+      path:reqPath,
+      method,
+      url:`https://localhost${reqPath}`,
+      params,
+    } as unknown as Request;
+  
+    const res = {
+      end: jest.fn(),
+      status: jest.fn(),
+      setHeader: jest.fn(),
+      params,
+      locals: {
+        stopPrometheusTimer: jest.fn(),
+      } as unknown as AppLocals,
+      headersSent,
+      writableEnded,
+    } as unknown as Response;
+
+    const next:NextFunction = jest.fn();
+  
+    return({req,res,next})
+  }

mailgun-webhook/tests/helpers/mockWebhookEvent.ts

@@ -0,0 +1,115 @@
+/**
+ * Helper for creating mock MailGun webhook events for testing
+ */
+
+import {
+  MailgunWebhookEvent,
+  MailgunDeliveredEvent,
+  MailgunFailedEvent,
+  MailgunOpenedEvent,
+  MailgunClickedEvent,
+  MailgunBouncedEvent,
+  MailgunComplainedEvent,
+  MailgunUnsubscribedEvent
+} from '../../src/types/MailgunWebhookEvent';
+
+/**
+ * Base event data common to all webhook events
+ */
+const baseEventData = {
+  timestamp: '1234567890',
+  token: 'mock-token-123',
+  signature: 'mock-signature-abc123',
+  recipient: 'user@example.com',
+  domain: 'mail.example.com',
+  'message-id': '<20240101120000.1.ABC123@mail.example.com>',
+  'Message-Id': '<20240101120000.1.ABC123@mail.example.com>'
+};
+
+/**
+ * Creates a mock 'delivered' event
+ */
+export const createMockDeliveredEvent = (): MailgunDeliveredEvent => ({
+  ...baseEventData,
+  event: 'delivered',
+  'message-headers': JSON.stringify([
+    ['Subject', 'Test Email'],
+    ['From', 'sender@example.com']
+  ])
+});
+
+/**
+ * Creates a mock 'failed' event
+ */
+export const createMockFailedEvent = (): MailgunFailedEvent => ({
+  ...baseEventData,
+  event: 'failed',
+  severity: 'permanent',
+  reason: 'bounce',
+  notification: 'User inbox is full'
+});
+
+/**
+ * Creates a mock 'opened' event
+ */
+export const createMockOpenedEvent = (): MailgunOpenedEvent => ({
+  ...baseEventData,
+  event: 'opened',
+  city: 'San Francisco',
+  country: 'US',
+  'device-type': 'desktop',
+  'client-os': 'macOS',
+  'client-name': 'Apple Mail',
+  ip: '192.168.1.100'
+});
+
+/**
+ * Creates a mock 'clicked' event
+ */
+export const createMockClickedEvent = (): MailgunClickedEvent => ({
+  ...baseEventData,
+  event: 'clicked',
+  url: 'https://example.com/link',
+  city: 'New York',
+  country: 'US',
+  'device-type': 'mobile',
+  'client-os': 'iOS',
+  'client-name': 'Gmail',
+  ip: '192.168.1.101'
+});
+
+/**
+ * Creates a mock 'bounced' event
+ */
+export const createMockBouncedEvent = (): MailgunBouncedEvent => ({
+  ...baseEventData,
+  event: 'bounced',
+  code: '550',
+  error: 'User not found',
+  notification: 'The email account that you tried to reach does not exist'
+});
+
+/**
+ * Creates a mock 'complained' event
+ */
+export const createMockComplainedEvent = (): MailgunComplainedEvent => ({
+  ...baseEventData,
+  event: 'complained'
+});
+
+/**
+ * Creates a mock 'unsubscribed' event
+ */
+export const createMockUnsubscribedEvent = (): MailgunUnsubscribedEvent => ({
+  ...baseEventData,
+  event: 'unsubscribed'
+});
+
+/**
+ * Creates an invalid event missing required fields
+ */
+export const createInvalidEvent = () => ({
+  timestamp: '1234567890',
+  token: 'mock-token-123'
+  // Missing 'event' and 'recipient' fields
+});

mailgun-webhook/tests/routers/errorRouter.spec.ts

@@ -0,0 +1,120 @@
+import { errorRouter } from '../../src/routes/errorRouter';
+import createError from "http-errors";
+import { mockHttpContext } from "../helpers/mockHttpContext";
+import { logWarn, resetAllLoggerMocks } from '../__mocks__/logger';
+
+// Mock the logger module
+jest.mock('../../src/lib/logger', () => require('../__mocks__/logger'));
+
+describe("errorRouter", () => {
+
+    beforeEach(() => {
+      resetAllLoggerMocks();
+    });
+
+    test("should return string message 'page not found' in case of 404 error", async () => {
+        const err = createError(404)
+        const {req,res,next} = mockHttpContext();
+  
+        await errorRouter(err, req, res, next);
+  
+        expect(res.status).toHaveBeenCalledWith(404);
+        expect(res.setHeader).toHaveBeenCalledWith('Content-Type', "text/html");
+        expect(res.end).toHaveBeenCalledWith("page not found");
+      });
+
+      test("should log page not found warning in case of 404 error", async () => {
+        const err = createError(404)
+        const reqPath = "/some-path/";
+        const {req,res,next} = mockHttpContext({ reqPath });
+  
+        await errorRouter(err, req, res, next);
+  
+        expect(logWarn).toHaveBeenCalledWith(`page not found GET ${reqPath}`);
+        expect(logWarn).toHaveBeenCalledWith(`${err.name}:page ${reqPath} not found`);
+      });
+
+      test("should not send headers again if they are already sent", async () => {
+        const err = createError(404)
+        const {req,res,next} = mockHttpContext({ headersSent:true, writableEnded:true });
+  
+        await errorRouter(err, req, res, next);
+  
+        expect(res.status).not.toHaveBeenCalled();
+        expect(res.setHeader).not.toHaveBeenCalled();
+        expect(res.end).not.toHaveBeenCalled();
+      });
+
+      test("should call [end] method if it has NOT been called yet", async () => {
+        const err = createError(404)
+        const {req,res,next} = mockHttpContext({ headersSent:true, writableEnded:false });
+  
+        await errorRouter(err, req, res, next);
+  
+        expect(res.status).not.toHaveBeenCalled();
+        expect(res.setHeader).not.toHaveBeenCalled();
+        expect(res.end).toHaveBeenCalled();
+      });
+  
+      test("should stop Prometheus Timer", async () => {
+        const err = createError(404)
+        const {req,res,next} = mockHttpContext({ headersSent:true, writableEnded:false });
+  
+        await errorRouter(err, req, res, next);
+  
+        expect(res.locals.stopPrometheusTimer).toHaveBeenCalled();
+      });
+
+      test("should return string message 'internal server error' in case of 500 error", async () => {
+        const err = createError(500)
+        const {req,res,next} = mockHttpContext();
+  
+        await errorRouter(err, req, res, next);
+  
+        expect(res.status).toHaveBeenCalledWith(500);
+        expect(res.setHeader).toHaveBeenCalledWith('Content-Type', "text/html");
+        expect(res.end).toHaveBeenCalledWith("internal server error");
+      });
+
+      test("should return string message 'bad request' and log error in case of 400 error", async () => {
+        const errorMessage = "mock error text 1";
+        const err = createError(400, errorMessage);
+        const {req,res,next} = mockHttpContext();
+  
+        await errorRouter(err, req, res, next);
+  
+        expect(res.status).toHaveBeenCalledWith(400);
+        expect(res.setHeader).toHaveBeenCalledWith('Content-Type', "text/html");
+        expect(res.end).toHaveBeenCalledWith("bad request");
+
+        expect(logWarn).toHaveBeenCalledWith(`${err.name}:${errorMessage}`);
+      });
+
+      test("should return string message 'unauthorized' and log error in case of 401 error", async () => {
+        const errorMessage = "mock error text 2";
+        const err = createError(401, errorMessage)
+        const {req,res,next} = mockHttpContext();
+  
+        await errorRouter(err, req, res, next);
+  
+        expect(res.status).toHaveBeenCalledWith(401);
+        expect(res.setHeader).toHaveBeenCalledWith('Content-Type', "text/html");
+        expect(res.end).toHaveBeenCalledWith("unauthorized");
+
+        expect(logWarn).toHaveBeenCalledWith(`${err.name}:${errorMessage}`);
+      });
+
+      test("should return string message 'forbidden' and log error in case of 403 error", async () => {
+        const errorMessage = "mock error text 3";
+        const err = createError(403, errorMessage);
+        const {req,res,next} = mockHttpContext();
+  
+        await errorRouter(err, req, res, next);
+  
+        expect(res.status).toHaveBeenCalledWith(403);
+        expect(res.setHeader).toHaveBeenCalledWith('Content-Type', "text/html");
+        expect(res.end).toHaveBeenCalledWith("forbidden");
+
+        expect(logWarn).toHaveBeenCalledWith(`${err.name}:${errorMessage}`);
+      });
+});

mailgun-webhook/tests/routers/webhookRouter.spec.ts

@@ -0,0 +1,196 @@
+/**
+ * Tests for MailGun webhook router
+ */
+
+import request from 'supertest';
+import app from '../../src/app';
+import {
+  createMockDeliveredEvent,
+  createMockFailedEvent,
+  createMockOpenedEvent,
+  createMockClickedEvent,
+  createMockBouncedEvent,
+  createMockComplainedEvent,
+  createMockUnsubscribedEvent,
+  createInvalidEvent
+} from '../helpers/mockWebhookEvent';
+
+describe('MailGun Webhook Router', () => {
+  // Mock console.log to avoid cluttering test output
+  let consoleLogSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    consoleLogSpy = jest.spyOn(console, 'log').mockImplementation();
+  });
+
+  afterEach(() => {
+    consoleLogSpy.mockRestore();
+  });
+
+  describe('POST /webhook', () => {
+    it('should handle delivered event successfully', async () => {
+      const event = createMockDeliveredEvent();
+
+      const response = await request(app)
+        .post('/webhook')
+        .send(event)
+        .expect(200);
+
+      expect(response.body).toEqual({
+        status: 'received',
+        message: 'Webhook event logged successfully'
+      });
+
+      // Verify console.log was called with event data
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const logOutput = consoleLogSpy.mock.calls.join('\n');
+      expect(logOutput).toContain('MailGun Webhook Event Received');
+      expect(logOutput).toContain('Event Type: delivered');
+      expect(logOutput).toContain('Recipient: user@example.com');
+    });
+
+    it('should handle failed event successfully', async () => {
+      const event = createMockFailedEvent();
+
+      const response = await request(app)
+        .post('/webhook')
+        .send(event)
+        .expect(200);
+
+      expect(response.body).toEqual({
+        status: 'received',
+        message: 'Webhook event logged successfully'
+      });
+
+      const logOutput = consoleLogSpy.mock.calls.join('\n');
+      expect(logOutput).toContain('Event Type: failed');
+      expect(logOutput).toContain('Severity: permanent');
+      expect(logOutput).toContain('Reason: bounce');
+    });
+
+    it('should handle opened event successfully', async () => {
+      const event = createMockOpenedEvent();
+
+      const response = await request(app)
+        .post('/webhook')
+        .send(event)
+        .expect(200);
+
+      expect(response.body.status).toBe('received');
+
+      const logOutput = consoleLogSpy.mock.calls.join('\n');
+      expect(logOutput).toContain('Event Type: opened');
+      expect(logOutput).toContain('City: San Francisco');
+      expect(logOutput).toContain('Device Type: desktop');
+    });
+
+    it('should handle clicked event successfully', async () => {
+      const event = createMockClickedEvent();
+
+      const response = await request(app)
+        .post('/webhook')
+        .send(event)
+        .expect(200);
+
+      expect(response.body.status).toBe('received');
+
+      const logOutput = consoleLogSpy.mock.calls.join('\n');
+      expect(logOutput).toContain('Event Type: clicked');
+      expect(logOutput).toContain('URL Clicked: https://example.com/link');
+    });
+
+    it('should handle bounced event successfully', async () => {
+      const event = createMockBouncedEvent();
+
+      const response = await request(app)
+        .post('/webhook')
+        .send(event)
+        .expect(200);
+
+      expect(response.body.status).toBe('received');
+
+      const logOutput = consoleLogSpy.mock.calls.join('\n');
+      expect(logOutput).toContain('Event Type: bounced');
+      expect(logOutput).toContain('SMTP Code: 550');
+    });
+
+    it('should handle complained event successfully', async () => {
+      const event = createMockComplainedEvent();
+
+      const response = await request(app)
+        .post('/webhook')
+        .send(event)
+        .expect(200);
+
+      expect(response.body.status).toBe('received');
+
+      const logOutput = consoleLogSpy.mock.calls.join('\n');
+      expect(logOutput).toContain('Event Type: complained');
+    });
+
+    it('should handle unsubscribed event successfully', async () => {
+      const event = createMockUnsubscribedEvent();
+
+      const response = await request(app)
+        .post('/webhook')
+        .send(event)
+        .expect(200);
+
+      expect(response.body.status).toBe('received');
+
+      const logOutput = consoleLogSpy.mock.calls.join('\n');
+      expect(logOutput).toContain('Event Type: unsubscribed');
+    });
+
+    it('should return 400 for invalid event missing required fields', async () => {
+      const event = createInvalidEvent();
+
+      const response = await request(app)
+        .post('/webhook')
+        .send(event)
+        .expect(400);
+
+      // Error router returns plain text, not JSON
+      expect(response.text).toBe('bad request');
+    });
+
+    it('should handle URL-encoded form data (MailGun default format)', async () => {
+      const event = createMockDeliveredEvent();
+
+      const response = await request(app)
+        .post('/webhook')
+        .type('form')
+        .send(event)
+        .expect(200);
+
+      expect(response.body.status).toBe('received');
+    });
+
+    it('should log timestamp in human-readable format', async () => {
+      const event = createMockDeliveredEvent();
+
+      await request(app)
+        .post('/webhook')
+        .send(event)
+        .expect(200);
+
+      const logOutput = consoleLogSpy.mock.calls.join('\n');
+      expect(logOutput).toContain('Timestamp: 1234567890');
+      // Check that ISO format date is logged
+      expect(logOutput).toMatch(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+    });
+
+    it('should log full event data as JSON', async () => {
+      const event = createMockDeliveredEvent();
+
+      await request(app)
+        .post('/webhook')
+        .send(event)
+        .expect(200);
+
+      const logOutput = consoleLogSpy.mock.calls.join('\n');
+      expect(logOutput).toContain('Full Event Data (JSON)');
+      expect(logOutput).toContain('"event": "delivered"');
+    });
+  });
+});