typedmailer 1.0.0

package/dist/providers/smtp.js

@@ -0,0 +1,71 @@
+import nodemailer from 'nodemailer';
+import { Buffer } from 'node:buffer';
+import { MailError, normalizeProviderError } from '../errors.js';
+function toNodemailerAddress(address) {
+    if (typeof address === 'string')
+        return address;
+    return { address: address.email, ...(address.name !== undefined ? { name: address.name } : {}) };
+}
+export function createSmtpProvider(options) {
+    const transport = nodemailer.createTransport({
+        host: options.host,
+        port: options.port,
+        secure: options.secure,
+        ...(options.port === 587 && !options.secure ? { requireTLS: true } : {}),
+        connectionTimeout: options.connectionTimeout,
+        greetingTimeout: options.greetingTimeout,
+        socketTimeout: options.socketTimeout,
+        ...(options.user && options.password ? { auth: { user: options.user, pass: options.password } } : {}),
+    });
+    return {
+        async send(input) {
+            try {
+                if (input.idempotencyKey || input.metadata) {
+                    throw new MailError('SMTP does not support idempotency keys or provider metadata.', 'unsupported', 'smtp', false);
+                }
+                const result = await transport.sendMail({
+                    from: toNodemailerAddress(input.from),
+                    to: input.to.map(toNodemailerAddress),
+                    subject: input.subject,
+                    ...(input.messageId ? { messageId: input.messageId } : {}),
+                    ...(input.text !== undefined ? { text: input.text } : {}),
+                    ...(input.html !== undefined ? { html: input.html } : {}),
+                    ...(input.replyTo ? { replyTo: toNodemailerAddress(input.replyTo) } : {}),
+                    ...(input.cc ? { cc: input.cc.map(toNodemailerAddress) } : {}),
+                    ...(input.bcc ? { bcc: input.bcc.map(toNodemailerAddress) } : {}),
+                    ...(input.headers ? { headers: input.headers } : {}),
+                    ...(input.attachments
+                        ? {
+                            attachments: input.attachments.map((attachment) => ({
+                                filename: attachment.filename,
+                                content: typeof attachment.content === 'string' ? attachment.content : Buffer.from(attachment.content),
+                                ...(attachment.contentType ? { contentType: attachment.contentType } : {}),
+                                ...(attachment.contentId ? { cid: attachment.contentId } : {}),
+                            })),
+                        }
+                        : {}),
+                });
+                if (!result.messageId) {
+                    throw new MailError('SMTP returned no message identifier.', 'provider', 'smtp', false, {
+                        deliveryUnknown: true,
+                    });
+                }
+                return { messageId: result.messageId };
+            }
+            catch (error) {
+                throw normalizeProviderError(error, 'smtp');
+            }
+        },
+        async verifyConnection() {
+            try {
+                await transport.verify();
+            }
+            catch (error) {
+                throw normalizeProviderError(error, 'smtp');
+            }
+        },
+        async close() {
+            transport.close();
+        },
+    };
+}

package/dist/testing.d.ts

@@ -0,0 +1,12 @@
+import type { Mailer, SendMailInput } from './types.js';
+export interface CapturedMail extends SendMailInput {
+    readonly from: NonNullable<SendMailInput['from']>;
+}
+export interface TestMailer extends Mailer {
+    readonly sent: CapturedMail[];
+    clear(): void;
+}
+/** In-memory mailer for application tests and local flows. It never sends network requests. */
+export declare function createTestMailer(options: {
+    from: NonNullable<SendMailInput['from']>;
+}): TestMailer;

package/dist/testing.js

@@ -0,0 +1,30 @@
+import { MailError } from './errors.js';
+import { mailInputSchema } from './config.js';
+/** In-memory mailer for application tests and local flows. It never sends network requests. */
+export function createTestMailer(options) {
+    const sent = [];
+    let closed = false;
+    const assertOpen = () => {
+        if (closed)
+            throw new MailError('Mailer has been closed.', 'configuration', 'test', false);
+    };
+    return {
+        sent,
+        clear() {
+            sent.length = 0;
+        },
+        async send(input) {
+            assertOpen();
+            const message = { ...input, from: input.from ?? options.from };
+            mailInputSchema.parse(message);
+            sent.push(message);
+            return { provider: 'test', messageId: `test-${sent.length}`, acceptedAt: new Date() };
+        },
+        async verifyConnection() {
+            assertOpen();
+        },
+        async close() {
+            closed = true;
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+export type MailAddress = string | {
+    readonly email: string;
+    readonly name?: string;
+};
+export interface MailAttachment {
+    readonly filename: string;
+    readonly content: string | Uint8Array;
+    readonly contentType?: string;
+    readonly contentId?: string;
+}
+export interface SendMailInput {
+    readonly from?: MailAddress;
+    readonly to: MailAddress | readonly MailAddress[];
+    readonly subject: string;
+    readonly messageId?: string;
+    readonly text?: string;
+    readonly html?: string;
+    readonly replyTo?: MailAddress;
+    readonly cc?: MailAddress | readonly MailAddress[];
+    readonly bcc?: MailAddress | readonly MailAddress[];
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly attachments?: readonly MailAttachment[];
+    readonly idempotencyKey?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+export type ProviderName = 'resend' | 'brevo' | 'smtp' | 'postmark' | 'sendgrid' | 'mailgun' | 'ses';
+export interface SendMailResult {
+    readonly provider: ProviderName | 'test';
+    readonly messageId: string;
+    /** Time when the provider accepted the request. This does not confirm inbox delivery. */
+    readonly acceptedAt: Date;
+}
+export interface Mailer {
+    send(input: SendMailInput): Promise<SendMailResult>;
+    verifyConnection(): Promise<void>;
+    /** Rejects new operations, waits for active operations, and closes the provider at most once. */
+    close(): Promise<void>;
+}
+export interface NormalizedMailInput extends Omit<SendMailInput, 'from' | 'to' | 'cc' | 'bcc' | 'replyTo'> {
+    readonly from: MailAddress;
+    readonly to: readonly MailAddress[];
+    readonly cc?: readonly MailAddress[];
+    readonly bcc?: readonly MailAddress[];
+    readonly replyTo?: MailAddress;
+}
+export interface ProviderSendResult {
+    readonly messageId: string;
+}
+export interface MailProvider {
+    send(input: NormalizedMailInput): Promise<ProviderSendResult>;
+    verifyConnection(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/integration-testing.md

@@ -0,0 +1,12 @@
+# Integration smoke workflow
+
+The `Provider integration smoke` workflow runs weekly or manually. It is intentionally separate from pull request CI. It always sends one message to an isolated Mailpit service; this does not contact a real mailbox.
+
+The workflow can also send controlled live messages through Resend or Amazon SES. To enable one, set the repository variable `TYPEDMAILER_INTEGRATION_PROVIDERS` to a comma-separated list such as `mailpit,resend` or `mailpit,ses`, then configure the following values:
+
+| Provider   | Repository variables                                                                                   | Repository secrets                                                                              |
+| ---------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| Resend     | `TYPEDMAILER_SMOKE_FROM`, `TYPEDMAILER_SMOKE_TO`                                                       | `TYPEDMAILER_RESEND_API_KEY`                                                                    |
+| Amazon SES | `TYPEDMAILER_SMOKE_FROM`, `TYPEDMAILER_SMOKE_TO`, `TYPEDMAILER_AWS_REGION`, `TYPEDMAILER_AWS_ROLE_ARN` | No long-lived AWS access key; configure the GitHub OIDC provider and a narrowly scoped IAM role |
+
+For SES, the repository already has a `provider-smoke` GitHub environment limited to the `main` branch. Configure the AWS GitHub OIDC provider and a role with trust subject `repo:erolsenol/typedmailer:environment:provider-smoke`, then set `TYPEDMAILER_AWS_ROLE_ARN` to that role's ARN. Grant it only `ses:SendEmail` for the test identity. Use a verified sender and a mailbox reserved for automated tests. Enabling a provider sends a real email whenever the workflow runs. Remove that provider from the variable to stop live sends. The workflow never enables live providers implicitly.

package/docs/provider-contracts.md

@@ -0,0 +1,30 @@
+# Provider behavior contracts
+
+The adapters provide one `createMailer(...).send(...)` interface, while provider APIs differ. This page records the behavior callers may rely on. The capability table in the README is the quick reference; adapter contract tests in `tests/provider-adapters.test.ts` are the executable mapping checks.
+
+## Shared guarantees
+
+- Provider SDKs are optional peers. Only the selected adapter is loaded, and a missing selected SDK becomes a `MailError` with code `configuration`.
+- `send()` resolves when the provider reports that it accepted the request. It does not prove inbox delivery.
+- A successful result includes the selected provider, provider message ID, and local acceptance timestamp. If the provider gives no ID, `messageId` is an empty string.
+- TypedMailer does not retry automatically. `retryable` and `deliveryUnknown` are diagnostic signals, not a safe retry instruction. A timeout or ambiguous provider response can mean the provider accepted the message.
+- Unsupported fields or operations fail with `MailError` code `unsupported`; adapters must not silently discard caller data.
+- `close()` is safe to call repeatedly, stops new work, waits for in-flight operations, and closes the underlying transport at most once.
+
+## Capability map
+
+| Provider   | Custom message ID | Idempotency key | Metadata | Inline attachments | Connection verification |
+| ---------- | ----------------- | --------------- | -------- | ------------------ | ----------------------- |
+| Resend     | No                | Yes             | Yes      | Yes                | Unsupported             |
+| Brevo      | No                | No              | Yes      | No                 | Unsupported             |
+| Postmark   | No                | No              | Yes      | Yes                | Unsupported             |
+| SendGrid   | No                | No              | Yes      | Yes                | Unsupported             |
+| Mailgun    | No                | No              | Yes      | Yes                | Unsupported             |
+| Amazon SES | No                | No              | Yes      | Yes                | Unsupported             |
+| SMTP       | Yes               | No              | No       | Yes                | SMTP connection check   |
+
+Attachments are buffered for provider SDK requests. Large-file streaming belongs in the application. `contentId` is supported by the providers listed as supporting inline attachments. `verifyConnection()` is only available for SMTP because the API providers do not offer a side-effect-free check through this interface.
+
+## Updating a provider adapter
+
+When changing an adapter, update the README capability table and this contract if caller-visible behavior changes. Add or adjust adapter tests for the provider payload, unsupported fields, returned message ID, and error normalization. Keep provider SDK versions within the declared peer range and verify both the locked SDK and minimum supported SDK set.

package/package.json

@@ -0,0 +1,147 @@
+{
+  "name": "typedmailer",
+  "version": "1.0.0",
+  "description": "A type-safe Node.js email library with one API for Resend, Brevo, Postmark, SendGrid, Mailgun, Amazon SES, or SMTP.",
+  "author": "Erol Senol",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "assets/typedmailer-mark.svg",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "SUPPORT.md",
+    "docs/provider-contracts.md",
+    "docs/integration-testing.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "lint": "eslint .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "release:check": "node scripts/release-preflight.mjs",
+    "examples:check": "node --check examples/resend.mjs && node --check examples/ses.mjs && node --check examples/smtp-mailpit.mjs",
+    "security:audit": "npm audit --audit-level=high",
+    "package:smoke": "node scripts/package-smoke.mjs",
+    "integration:smoke": "node scripts/live-provider-smoke.mjs",
+    "pack:check": "npm pack --dry-run --ignore-scripts && npm run package:smoke",
+    "check": "npm run lint && npm run format:check && npm run test && npm run typecheck && npm run examples:check && npm run build && npm run pack:check",
+    "prepare": "npm run build && husky"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint",
+      "prettier --check"
+    ],
+    "*.{json,md,yml,yaml,js,mjs,cjs}": [
+      "prettier --check"
+    ]
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-sesv2": ">=3.0.0 <4",
+    "@getbrevo/brevo": ">=6.0.1 <7",
+    "@sendgrid/mail": ">=8.0.0 <9",
+    "form-data": ">=4.0.0 <5",
+    "mailgun.js": ">=14.0.0 <15",
+    "nodemailer": ">=7.0.0 <11",
+    "postmark": ">=5.0.0 <6",
+    "resend": ">=6.0.0 <7"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-sesv2": {
+      "optional": true
+    },
+    "@getbrevo/brevo": {
+      "optional": true
+    },
+    "@sendgrid/mail": {
+      "optional": true
+    },
+    "form-data": {
+      "optional": true
+    },
+    "mailgun.js": {
+      "optional": true
+    },
+    "nodemailer": {
+      "optional": true
+    },
+    "postmark": {
+      "optional": true
+    },
+    "resend": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-sesv2": ">=3.0.0 <4",
+    "@getbrevo/brevo": ">=6.0.1 <7",
+    "@sendgrid/mail": ">=8.0.0 <9",
+    "@types/node": "^24.5.2",
+    "@types/nodemailer": "^7.0.1",
+    "eslint": "^10.11.0",
+    "form-data": ">=4.0.0 <5",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.6.0",
+    "mailgun.js": ">=14.0.0 <15",
+    "nodemailer": ">=7.0.0 <11",
+    "postmark": ">=5.0.0 <6",
+    "prettier": "^3.9.9",
+    "resend": ">=6.0.0 <7",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.70.1",
+    "vitest": "^5.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/erolsenol/typedmailer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/erolsenol/typedmailer/issues"
+  },
+  "homepage": "https://github.com/erolsenol/typedmailer#readme",
+  "keywords": [
+    "email",
+    "email-client",
+    "email-library",
+    "email-provider",
+    "email-sending",
+    "amazon-ses",
+    "mailer",
+    "mail",
+    "node",
+    "mailgun",
+    "ses",
+    "typescript",
+    "type-safe",
+    "transactional-email",
+    "smtp",
+    "resend",
+    "brevo",
+    "postmark",
+    "sendgrid",
+    "nodemailer"
+  ]
+}