@codepunter-labs/mock-mail

Mock SDK for email APIs. Provides fully-typed mock implementations for testing email sending, templates, status tracking, and webhooks without making real API calls.

Installation

npm install @codepunter-labs/mock-mail

Features

• Send Email: Send direct emails and template-based emails
• Email Status: Track email delivery status
• Templates: Create and manage email templates
• Webhooks: Verify webhook signatures and parse events
• Type-safe: Full TypeScript support with accurate API types
• Test Framework Agnostic: Works with Jest, Vitest, and other spy-based frameworks

Repository

• GitHub: https://github.com/DERRICK-TORKORNOO/mock-sdks/tree/main/packages/mock-mail
• Source Code: src/
• Tests: tests/

Usage

Basic Setup

import { vi } from 'vitest';
import { createMockMail } from '@codepunter-labs/mock-mail';

const mail = createMockMail({ spy: vi.fn });

Using with Jest

import { createMockMail } from '@codepunter-labs/mock-mail';

const mail = createMockMail({ spy: jest.fn });

Example: Send Email

// Default behavior - returns realistic mock data
const result = await mail.sendEmail({
  to: '[email protected]',
  from: '[email protected]',
  subject: 'Test Email',
  html: '<p>Hello World</p>'
});

Example: Send Template Email

const result = await mail.sendTemplateEmail({
  templateId: 'tpl_123',
  to: '[email protected]',
  variables: { name: 'John' }
});

Example: Get Email Status

const result = await mail.getEmailStatus('msg_123');

Example: Override Mock Response

import { makeSendEmailResponse } from '@codepunter-labs/mock-mail';

mail.sendEmail.mockResolvedValue({
  success: true,
  message: 'Email sent successfully',
  data: makeSendEmailResponse({ status: 'sent' })
});

Example: Error Simulation

import { MailErrors } from '@codepunter-labs/mock-mail';

mail.sendEmail.mockRejectedValue(
  MailErrors.invalidEmail()
);

Example: Webhook Verification

const isValid = mail.verifyWebhookSignature(
  payload,
  signature,
  'webhook-secret'
);

const event = mail.parseWebhookEvent(payload);

API Reference

MockMail

| Method | Description | Source | |--------|-------------|--------| | sendEmail(request) | Send email | mock-mail.ts | | sendTemplateEmail(request) | Send template email | mock-mail.ts | | getEmailStatus(messageId) | Get email status | mock-mail.ts | | listEmailStatuses(options?) | List email statuses | mock-mail.ts | | createTemplate(request) | Create email template | mock-mail.ts | | getTemplate(templateId) | Get template details | mock-mail.ts | | listTemplates() | List all templates | mock-mail.ts | | verifyWebhookSignature(payload, signature, secret) | Verify webhook signature | mock-mail.ts | | parseWebhookEvent(payload) | Parse webhook event | mock-mail.ts |

Fixture Factories

| Factory | Description | Source | |---------|-------------|--------| | makeSendEmailResponse(options?) | Create send email response | fixtures.ts | | makeEmailStatus(options?) | Create email status | fixtures.ts | | makeEmailTemplate(options?) | Create email template | fixtures.ts | | makeWebhookEvent(options?) | Create webhook event | fixtures.ts |

Error Factories

| Error | Description | Source | |-------|-------------|--------| | MailErrors.unauthorized() | Unauthorized error | errors.ts | | MailErrors.invalidEmail() | Invalid email error | errors.ts | | MailErrors.sendFailed() | Send failed error | errors.ts | | MailErrors.serverError() | Server error | errors.ts |

Testing Patterns

Test Success Path

test('should send email successfully', async () => {
  const mail = createMockMail({ spy: vi.fn });
  
  const result = await mail.sendEmail(request);
  
  expect(result.success).toBe(true);
  expect(result.data.messageId).toBeDefined();
});

Test Error Handling

test('should handle invalid email address error', async () => {
  const mail = createMockMail({ spy: vi.fn });
  
  mail.sendEmail.mockRejectedValue(
    MailErrors.invalidEmail()
  );
  
  await expect(mail.sendEmail(request)).rejects.toMatchObject({ message: /Invalid email/ });
});

Test with Custom Data

test('should use custom email status', async () => {
  const mail = createMockMail({ spy: vi.fn });
  
  mail.sendEmail.mockResolvedValue({
    success: true,
    message: 'Email sent successfully',
    data: makeSendEmailResponse({ status: 'delivered' })
  });
  
  const result = await mail.sendEmail(request);
  expect(result.data.status).toBe('delivered');
});

Test Webhook

test('should verify webhook signature', () => {
  const mail = createMockMail({ spy: vi.fn });
  
  const isValid = mail.verifyWebhookSignature(
    '{"event":"delivered"}',
    'signature',
    'secret'
  );
  
  expect(isValid).toBe(true);
});

License

MIT