@contract-kit/mail

Shared mail types for contract-kit mail providers. This package provides framework-agnostic interfaces that can be implemented by different mail backends (SMTP, Resend, SendGrid, etc.).

Installation

npm install @contract-kit/mail
# or
bun add @contract-kit/mail

TypeScript Requirements

This package requires TypeScript 5.0 or higher for proper type inference.

Overview

This package contains only TypeScript types and interfaces - no runtime code. It defines the MailerPort interface that all mail provider implementations must follow.

Types

MailerPort<Client>

The main interface that all mail providers implement:

interface MailerPort<Client = unknown> {
  sendText(to: string, subject: string, text: string): Promise<void>;
  sendHtml(to: string, subject: string, html: string): Promise<void>;
  send(options: SendTextOptions | SendHtmlOptions): Promise<void>;
  client: Client;
}

The Client generic parameter allows providers to expose their underlying client (e.g., nodemailer.Transporter, Resend).

SendTextOptions

Options for sending plain text emails:

interface SendTextOptions {
  to: string;
  subject: string;
  text: string;
  from?: string;
}

SendHtmlOptions

Options for sending HTML emails:

interface SendHtmlOptions {
  to: string;
  subject: string;
  html: string;
  from?: string;
}

Available Providers

• @contract-kit/provider-mail-smtp - SMTP/nodemailer implementation
• @contract-kit/provider-mail-resend - Resend implementation

Usage

This package is primarily for mail provider implementors. If you're building your own mail provider:

import { MailerPort, SendTextOptions, SendHtmlOptions } from "@contract-kit/mail";
import { createProvider } from "@contract-kit/ports";

// Define your client type
type MyMailClient = {
  // ... your mail client
};

export const myMailProvider = createProvider({
  name: "my-mail",
  async register({ ports, config }) {
    const client = new MyMailClient(config);
    
    const mailer: MailerPort<MyMailClient> = {
      async sendText(to, subject, text) {
        await client.send({ to, subject, text });
      },
      async sendHtml(to, subject, html) {
        await client.send({ to, subject, html });
      },
      async send(options) {
        await client.send(options);
      },
      client,
    };
    
    ports.extend("mailer", mailer);
  },
});

License

MIT