@brilab-mailer/contracts

Overview

@brilab-mailer/contracts defines the foundational interfaces, types, and tokens used across the Brilab Mailer ecosystem.
It ensures strong typing, loose coupling, and clear architectural boundaries between the core mailer module, providers, and template engines.

Architecture

Key Design Principles

• Dependency inversion — providers implement interfaces defined here.
• Strict typing — all providers must satisfy MailerProvider.
• Pluggable system — any provider or template engine can be dynamically injected.
• Stable contract layer — safe for cross-package communication.

Key Interfaces

MailerProvider

export interface MailerProvider {
  send(options: MailerSendOptions): Promise<void>;
}

MailerSendOptions

export interface MailerSendOptions {
  to: string;
  subject: string;
  html?: string;
  text?: string;
}

Injection Tokens

export const MAILER_PROVIDER = Symbol('MAILER_PROVIDER');
export const MAILER_TEMPLATE_ENGINE = Symbol('MAILER_TEMPLATE_ENGINE');

How Other Packages Use Contracts

Core

The core mailer module injects:

@Inject(MAILER_PROVIDER)
provider: MailerProvider

Providers

Each provider implements:

export class MailtrapApiProvider implements MailerProvider { ... }

Templates

Template engines implement:

export class HandlebarsTemplateEngine implements MailerTemplateEngine { ... }

Best Practices

• Providers must never return provider-specific result structures.
• Template engines must not depend on the Nest context.
• Contracts must not import from Core or Providers → no circular deps.

Versioning Strategy

Contracts follow semver-major discipline:

• minor updates allowed for additions
• major bump required for breaking interface changes