typedmailer 1.0.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,20 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We are committed to making participation in this project a welcoming and respectful experience for everyone, regardless of background or identity.
+
+## Expected behavior
+
+- Be respectful and constructive.
+- Focus feedback on the work and its impact.
+- Accept responsibility and correct mistakes when they occur.
+- Respect differing viewpoints and experiences.
+
+## Unacceptable behavior
+
+Harassment, insults, discriminatory language, intimidation, unwelcome sexual attention, and publishing another person's private information are not acceptable.
+
+## Enforcement
+
+Report conduct concerns privately through GitHub's contact/reporting tools for the repository owner. Reports will be reviewed and handled as fairly and promptly as possible. Maintainers may remove content or restrict participation for behavior that violates this code.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erol Senol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+<p align="center">
+  <img src="assets/typedmailer-mark.svg" alt="TypedMailer" width="72" height="72" />
+</p>
+
+<h1 align="center">TypedMailer: TypeScript Email Sending for Node.js</h1>
+
+<p align="center"><strong>One typed API for sending Node.js email with seven providers.</strong></p>
+
+<p align="center">
+  <a href="https://github.com/erolsenol/typedmailer/actions/workflows/ci.yml"><img src="https://github.com/erolsenol/typedmailer/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
+  <a href="https://www.npmjs.com/package/typedmailer"><img src="https://img.shields.io/npm/v/typedmailer" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/typedmailer"><img src="https://img.shields.io/npm/dm/typedmailer" alt="monthly npm downloads" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" /></a>
+</p>
+
+TypedMailer is a type-safe email library for Node.js and TypeScript applications. It gives server-side code one API for sending transactional email with Resend, Brevo, Postmark, SendGrid, Mailgun, Amazon SES, or SMTP. Your application keeps ownership of templates, queues, retries, and business rules.
+
+Use TypedMailer when you want to switch email providers without coupling application code to a provider SDK. Provider SDKs are optional peer dependencies, and only the selected adapter is loaded.
+
+## Install
+
+Install the `typedmailer` npm package with the provider SDK you plan to use:
+
+```sh
+npm install typedmailer resend
+# or
+npm install typedmailer @getbrevo/brevo
+# or
+npm install typedmailer nodemailer
+# or
+npm install typedmailer postmark
+# or
+npm install typedmailer @sendgrid/mail
+# or
+npm install typedmailer mailgun.js form-data
+# or
+npm install typedmailer @aws-sdk/client-sesv2
+```
+
+Requires Node.js 22 or newer. Provider SDKs are optional peers and are loaded only when their adapter is selected.
+
+Supported runtime and release guarantees are documented in [`SUPPORT.md`](SUPPORT.md). Provider behavior guarantees and their test coverage are described in [`docs/provider-contracts.md`](docs/provider-contracts.md). The scheduled and manual provider smoke workflow is documented in [`docs/integration-testing.md`](docs/integration-testing.md).
+
+TypedMailer is for trusted server-side Node.js runtimes. It is not intended for browser or mobile client bundles.
+
+## Quick start
+
+```ts
+import { createMailer } from 'typedmailer';
+
+const mailer = createMailer({
+  provider: 'resend',
+  apiKey: process.env.RESEND_API_KEY!,
+  from: 'Example App <noreply@example.com>',
+});
+
+const result = await mailer.send({
+  to: 'person@example.com',
+  subject: 'Welcome',
+  text: 'Your account is ready.',
+  html: '<p>Your account is ready.</p>',
+});
+
+console.log(result.messageId);
+await mailer.close();
+```
+
+## Providers
+
+TypedMailer supports these email providers through the same `createMailer` and `send` API:
+
+- **Resend** for API-based email delivery.
+- **Brevo** for API-based email delivery.
+- **Postmark** for API-based email delivery.
+- **SendGrid** for API-based email delivery.
+- **Mailgun** for API-based email delivery in US or EU regions.
+- **Amazon SES** for API-based email delivery using AWS credentials.
+- **SMTP** for compatible SMTP services and local development servers such as Mailpit.
+
+### Brevo
+
+```ts
+const mailer = createMailer({
+  provider: 'brevo',
+  apiKey: process.env.BREVO_API_KEY!,
+  from: { email: 'hello@example.com', name: 'Example App' },
+});
+```
+
+### Postmark
+
+Use your Postmark server token as `apiKey`:
+
+```ts
+const mailer = createMailer({
+  provider: 'postmark',
+  apiKey: process.env.POSTMARK_SERVER_TOKEN!,
+  from: 'Example App <noreply@example.com>',
+});
+```
+
+### SendGrid
+
+```ts
+const mailer = createMailer({
+  provider: 'sendgrid',
+  apiKey: process.env.SENDGRID_API_KEY!,
+  from: 'Example App <noreply@example.com>',
+});
+```
+
+### Mailgun
+
+Mailgun requires a sending domain and API key. Set `region` to `'eu'` for an EU account; it defaults to `'us'`.
+
+```ts
+const mailer = createMailer({
+  provider: 'mailgun',
+  apiKey: process.env.MAILGUN_API_KEY!,
+  domain: process.env.MAILGUN_DOMAIN!,
+  region: 'eu',
+  from: 'Example App <noreply@example.com>',
+});
+```
+
+### Amazon SES
+
+SES requires a region and uses the AWS SDK credential provider chain, such as environment credentials, a shared profile, or an IAM role.
+
+```ts
+const mailer = createMailer({
+  provider: 'ses',
+  region: process.env.AWS_REGION!,
+  from: 'Example App <noreply@example.com>',
+});
+```
+
+### SMTP
+
+```ts
+const mailer = createMailer({
+  provider: 'smtp',
+  host: process.env.SMTP_HOST ?? '127.0.0.1',
+  port: Number(process.env.SMTP_PORT ?? 1025),
+  secure: process.env.SMTP_SECURE === 'true',
+  ...(process.env.SMTP_USER ? { user: process.env.SMTP_USER } : {}),
+  ...(process.env.SMTP_PASSWORD ? { password: process.env.SMTP_PASSWORD } : {}),
+  from: 'Local App <local@example.test>',
+});
+```
+
+For local development, start Mailpit with `docker run --rm -p 1025:1025 -p 8025:8025 axllent/mailpit`. Messages appear at `http://127.0.0.1:8025`.
+
+## Message options
+
+`to` accepts an email string, a `{ email, name }` object, or an array. Provide `text` or `html` (or both). Optional fields include `from`, `replyTo`, `cc`, `bcc`, `headers`, `attachments`, `metadata`, and `idempotencyKey`; `messageId` is SMTP-only. Attachments may include `contentId` for inline images with Resend, Postmark, SendGrid, Mailgun, Amazon SES, and SMTP. Attachment content accepts strings or `Uint8Array`; the provider adapters buffer it for SDK requests, so use an application-managed upload or streaming workflow for large files.
+
+Subjects and attachment filenames cannot be blank. Supplied content types and inline content IDs must be non-empty. The library does not impose a fixed attachment-size limit.
+
+Provider capabilities differ. Unsupported fields return a `MailError` with code `unsupported` instead of being silently ignored.
+
+| Provider   | Custom `messageId` | `idempotencyKey` | Metadata | Inline attachments | `verifyConnection()` |
+| ---------- | ------------------ | ---------------- | -------- | ------------------ | -------------------- |
+| 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                | Yes                  |
+
+```ts
+await mailer.send({
+  to: [{ email: 'person@example.com', name: 'Sam' }],
+  subject: 'Your receipt',
+  text: 'Receipt attached.',
+  attachments: [{ filename: 'receipt.txt', content: 'Receipt 123' }],
+  idempotencyKey: 'receipt/order-123',
+});
+```
+
+TypedMailer does not retry sends automatically: after a network timeout the provider may already have accepted the message. Apply retries only when you understand the provider's idempotency guarantees.
+
+## Test your application flow
+
+Use the in-memory adapter to exercise mail flows without contacting a provider:
+
+```ts
+import { createTestMailer } from 'typedmailer/testing';
+
+const mailer = createTestMailer({ from: 'Test <test@example.test>' });
+await mailer.send({ to: 'person@example.test', subject: 'Hello', text: 'Hi' });
+console.log(mailer.sent[0]);
+```
+
+Messages captured by `createTestMailer` return `provider: 'test'` so test results are not mistaken for SMTP deliveries.
+
+## Runnable examples
+
+The repository includes complete Resend, Amazon SES, and local SMTP/Mailpit examples in [`examples/`](examples/). From a clone, copy `examples/.env.example` to `.env`, replace the example sender and recipient with addresses valid for your account, then install the SDK for the chosen provider:
+
+```sh
+npm install typedmailer resend
+node --env-file=.env examples/resend.mjs
+```
+
+For Amazon SES, run `npm install typedmailer @aws-sdk/client-sesv2 && node --env-file=.env examples/ses.mjs`; credentials come from the standard AWS SDK credential provider chain. For local SMTP, start Mailpit with `docker run --rm -p 1025:1025 -p 8025:8025 axllent/mailpit`, then run `npm install typedmailer nodemailer && node --env-file=.env examples/smtp-mailpit.mjs`. View captured messages at `http://127.0.0.1:8025`.
+
+## Errors and delivery
+
+Provider and transport failures are normalized as `MailError`, with `code`, `provider`, `retryable`, `deliveryUnknown`, and the original error in `cause`. Codes mean:
+
+| Code             | Meaning                                                               |
+| ---------------- | --------------------------------------------------------------------- |
+| `configuration`  | Invalid setup, missing optional SDK, or use after close.              |
+| `authentication` | The provider rejected credentials or access.                          |
+| `rate_limit`     | The provider throttled the request.                                   |
+| `network`        | A recognized connection or timeout failure occurred.                  |
+| `provider`       | The provider returned another failure or an invalid response.         |
+| `unsupported`    | The selected adapter cannot represent a requested field or operation. |
+
+`retryable` is guidance from the normalized failure: recognized network failures and rate limits are retryable; API provider 5xx failures are retryable; authentication, configuration, unsupported, and SMTP 5xx failures are not. `deliveryUnknown` is separate: it is true when a send timeout/socket interruption, a provider 5xx, or an accepted response without a message ID means the provider may have accepted the message without returning a clear result. It stays false for verification failures, DNS lookup failures, authentication errors, rate limits, and SMTP response errors. This does not guarantee that retrying is safe. Use provider-supported idempotency where available and apply retry policy in your application. `cause` retains the original SDK error for diagnostics and can contain provider details; avoid logging it without reviewing your data handling policy.
+
+A successful `send()` means the provider accepted the request; it does not confirm inbox delivery. Delivery, bounce, and complaint events require provider webhooks and are outside this package's current scope.
+
+`verifyConnection()` currently supports SMTP. API provider adapters report `unsupported` because they do not expose a side-effect-free credential check through this API; verify credentials with a controlled provider test message.
+
+`close()` is idempotent. It rejects new sends and verification calls, waits for operations already in progress, and closes the provider transport at most once. Reuse requires creating a new mailer.
+
+## Security
+
+- Use TypedMailer only in trusted server-side Node.js code. Never expose provider keys in browser or mobile bundles.
+- Keep secrets in environment variables or secret managers, not source control.
+- TypedMailer does not log message content or credentials.
+- See [SECURITY.md](SECURITY.md) to report a vulnerability.
+
+## Contributing
+
+Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for development and contribution guidelines.
+
+After cloning, run `npm ci` to install dependencies and enable the local Git hooks. Commits run staged-file lint and format checks plus unit tests. Pushes run the full `npm run check` quality gate, including an isolated npm tarball consumer smoke test; GitHub Actions runs it on Node.js 22 and 24 and audits dependencies before merge and publish.
+
+## Türkçe kısa başlangıç
+
+TypedMailer, Node.js sunucu uygulamalarında Resend, Brevo, Postmark, SendGrid, Mailgun, Amazon SES veya SMTP ile e-posta göndermek için ortak ve tip güvenli bir API sunar. Şablonlar, kuyruk ve tekrar deneme politikaları uygulamanızda kalır. Seçtiğiniz sağlayıcının SDK'sını TypedMailer ile birlikte yükleyin. API anahtarlarını yalnızca sunucu ortamında tutun.
+
+## License
+
+MIT © 2026 Erol Senol

package/SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest published version is currently supported.
+
+## Reporting a vulnerability
+
+Please do not report security vulnerabilities in public issues. Use GitHub's private vulnerability reporting for this repository. Include the affected version, impact, and a minimal reproduction. Do not include real credentials, recipient data, or message contents.

package/SUPPORT.md

@@ -0,0 +1,21 @@
+# Support policy
+
+## Runtime support
+
+TypedMailer requires Node.js 22 or newer. CI tests Node.js 22 and 24. We support the latest patch release of each Node.js major that is still in its official maintenance or active LTS period; end-of-life Node.js releases are unsupported even when they satisfy the package engine range.
+
+Install the provider SDK required by your selected adapter. Provider SDKs are optional peer dependencies; see the [provider contracts](docs/provider-contracts.md) and README compatibility table.
+
+## Versioning
+
+TypedMailer follows Semantic Versioning for its public TypeScript API and documented runtime behavior:
+
+- Patch: backward-compatible bug and security fixes.
+- Minor: backward-compatible features and provider support.
+- Major: breaking API, runtime requirement, or documented behavior changes.
+
+A documented provider capability is part of the public contract. Changes to these guarantees require compatibility review, tests, and a changelog entry.
+
+## Security and support
+
+Report vulnerabilities through GitHub's private vulnerability reporting. For usage questions and reproducible bugs, use the repository's GitHub Issues. Include the TypedMailer version, Node.js version, provider and SDK version, and sanitized error fields. Never include credentials, recipient addresses, message content, or unreviewed provider error causes.

package/assets/typedmailer-mark.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" fill="none">
+  <rect width="96" height="96" rx="24" fill="#111827" />
+  <path d="M22 34.5 48 53l26-18.5" stroke="#F8F7F4" stroke-width="6" stroke-linecap="round" stroke-linejoin="round" />
+  <path d="M24 32h48a5 5 0 0 1 5 5v24a5 5 0 0 1-5 5H24a5 5 0 0 1-5-5V37a5 5 0 0 1 5-5Z" stroke="#F8F7F4" stroke-width="5" />
+  <path d="M62 66h11a4 4 0 0 0 4-4v-1" stroke="#34D399" stroke-width="5" stroke-linecap="round" />
+  <circle cx="78" cy="56" r="5" fill="#34D399" />
+</svg>

package/dist/config.d.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+export declare const mailInputSchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>;
+    to: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>]>;
+    subject: z.ZodString;
+    messageId: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    html: z.ZodOptional<z.ZodString>;
+    replyTo: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>;
+    cc: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>]>>;
+    bcc: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>]>>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        filename: z.ZodString;
+        content: z.ZodUnion<readonly [z.ZodString, z.ZodInstanceOf<Uint8Array<ArrayBuffer>>]>;
+        contentType: z.ZodOptional<z.ZodString>;
+        contentId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export declare function normalizeAddresses<T>(value: T | readonly T[] | undefined): readonly T[] | undefined;
+export declare function emailOf(address: string | {
+    email: string;
+    name?: string;
+}): string;
+export declare function addressWithName(address: string | {
+    email: string;
+    name?: string;
+}): {
+    email: string;
+    name?: string;
+};

package/dist/config.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+const addressSchema = z.union([
+    z.string().email(),
+    z.object({ email: z.string().email(), name: z.string().optional() }).strict(),
+]);
+const senderSchema = z.union([
+    z.string().email(),
+    z.string().regex(/^.+ <[^<>\s]+@[^<>\s]+>$/, 'Use a valid email address or "Name <email@example.com>".'),
+    z.object({ email: z.string().email(), name: z.string().optional() }).strict(),
+]);
+export const mailInputSchema = z
+    .object({
+    from: senderSchema.optional(),
+    to: z.union([addressSchema, z.array(addressSchema).min(1)]),
+    subject: z
+        .string()
+        .min(1)
+        .refine((value) => value.trim().length > 0, 'Subject cannot be blank.'),
+    messageId: z.string().min(1).optional(),
+    text: z.string().optional(),
+    html: z.string().optional(),
+    replyTo: addressSchema.optional(),
+    cc: z.union([addressSchema, z.array(addressSchema)]).optional(),
+    bcc: z.union([addressSchema, z.array(addressSchema)]).optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    attachments: z
+        .array(z.object({
+        filename: z
+            .string()
+            .min(1)
+            .refine((value) => value.trim().length > 0, 'Attachment filename cannot be blank.'),
+        content: z.union([z.string(), z.instanceof(Uint8Array)]),
+        contentType: z.string().min(1).optional(),
+        contentId: z.string().min(1).optional(),
+    }))
+        .optional(),
+    idempotencyKey: z.string().min(1).optional(),
+    metadata: z.record(z.string(), z.string()).optional(),
+})
+    .strict()
+    .refine((input) => input.text !== undefined || input.html !== undefined, {
+    message: 'Provide at least one of text or html.',
+});
+export function normalizeAddresses(value) {
+    if (value === undefined)
+        return undefined;
+    return Array.isArray(value) ? value : [value];
+}
+export function emailOf(address) {
+    if (typeof address !== 'string')
+        return address.email;
+    const namedAddress = address.match(/^(.+) <([^<>\s]+@[^<>\s]+)>$/);
+    return namedAddress?.[2] ?? address;
+}
+export function addressWithName(address) {
+    if (typeof address !== 'string')
+        return address;
+    const namedAddress = address.match(/^(.+) <([^<>\s]+@[^<>\s]+)>$/);
+    return namedAddress ? { email: namedAddress[2], name: namedAddress[1] } : { email: address };
+}

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+export type MailErrorCode = 'configuration' | 'authentication' | 'rate_limit' | 'network' | 'provider' | 'unsupported';
+export interface MailErrorOptions extends ErrorOptions {
+    readonly deliveryUnknown?: boolean;
+}
+export declare class MailError extends Error {
+    readonly code: MailErrorCode;
+    readonly provider: string;
+    readonly retryable: boolean;
+    readonly deliveryUnknown: boolean;
+    constructor(message: string, code: MailErrorCode, provider: string, retryable: boolean, options?: MailErrorOptions);
+}
+export type MailErrorOperation = 'send' | 'verify';
+export declare function normalizeProviderError(error: unknown, provider: string, operation?: MailErrorOperation): MailError;

package/dist/errors.js

@@ -0,0 +1,109 @@
+export class MailError extends Error {
+    code;
+    provider;
+    retryable;
+    deliveryUnknown;
+    constructor(message, code, provider, retryable, options) {
+        super(message, options);
+        this.code = code;
+        this.provider = provider;
+        this.retryable = retryable;
+        this.name = 'MailError';
+        this.deliveryUnknown = options?.deliveryUnknown ?? false;
+    }
+}
+const networkErrorCodes = new Set([
+    'ETIMEDOUT',
+    'ECONNECTION',
+    'ENOTFOUND',
+    'ECONNRESET',
+    'EPIPE',
+    'ECONNREFUSED',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ESOCKET',
+]);
+const ambiguousNetworkErrorCodes = new Set(['ETIMEDOUT', 'ECONNECTION', 'ECONNRESET', 'EPIPE', 'ESOCKET']);
+function mayHaveBeenAccepted(error, provider) {
+    const candidate = error;
+    const status = typeof candidate?.statusCode === 'number'
+        ? candidate.statusCode
+        : typeof candidate?.status === 'number'
+            ? candidate.status
+            : typeof candidate?.code === 'number'
+                ? candidate.code
+                : typeof error?.responseCode === 'number'
+                    ? error.responseCode
+                    : typeof error?.$metadata?.httpStatusCode ===
+                        'number'
+                        ? error.$metadata.httpStatusCode
+                        : undefined;
+    const code = typeof candidate?.code === 'string' ? candidate.code : candidate?.name;
+    if (provider === 'smtp' && status !== undefined)
+        return false;
+    if (status === 429 || status === 401 || status === 403 || (status !== undefined && status >= 400 && status < 500)) {
+        return false;
+    }
+    if (status !== undefined)
+        return status >= 500 && status < 600;
+    return typeof code === 'string' && ambiguousNetworkErrorCodes.has(code);
+}
+export function normalizeProviderError(error, provider, operation = 'verify') {
+    if (error instanceof MailError) {
+        const deliveryUnknown = operation === 'send' && (error.deliveryUnknown || mayHaveBeenAccepted(error.cause, provider));
+        if (error.deliveryUnknown === deliveryUnknown)
+            return error;
+        return new MailError(error.message, error.code, error.provider, error.retryable, {
+            ...(error.cause !== undefined ? { cause: error.cause } : {}),
+            deliveryUnknown,
+        });
+    }
+    const candidate = error;
+    const status = typeof candidate?.statusCode === 'number'
+        ? candidate.statusCode
+        : typeof candidate?.status === 'number'
+            ? candidate.status
+            : typeof candidate?.code === 'number'
+                ? candidate.code
+                : typeof error?.responseCode === 'number'
+                    ? error.responseCode
+                    : typeof error?.$metadata?.httpStatusCode ===
+                        'number'
+                        ? error.$metadata.httpStatusCode
+                        : undefined;
+    const code = typeof candidate?.code === 'string'
+        ? candidate.code
+        : typeof candidate?.name === 'string'
+            ? candidate.name
+            : undefined;
+    const authenticationFailure = status === 401 ||
+        status === 403 ||
+        code === 'EAUTH' ||
+        code === 'AccessDeniedException' ||
+        code === 'UnrecognizedClientException' ||
+        code === 'InvalidClientTokenId';
+    const rateLimitFailure = status === 429 || code === 'ThrottlingException' || code === 'TooManyRequestsException';
+    const safeMessage = authenticationFailure
+        ? 'The email provider rejected the configured credentials.'
+        : rateLimitFailure
+            ? 'The email provider rate limit was reached.'
+            : status !== undefined
+                ? `The email provider request failed with status ${status}.`
+                : typeof code === 'string' && networkErrorCodes.has(code)
+                    ? 'Could not connect to the email provider.'
+                    : 'The email provider could not accept the message.';
+    const errorCode = authenticationFailure
+        ? 'authentication'
+        : rateLimitFailure
+            ? 'rate_limit'
+            : typeof code === 'string' && networkErrorCodes.has(code)
+                ? 'network'
+                : 'provider';
+    const retryable = errorCode === 'network' ||
+        errorCode === 'rate_limit' ||
+        (provider !== 'smtp' && status !== undefined && status >= 500 && status < 600);
+    return new MailError(safeMessage, errorCode, provider, retryable, {
+        cause: error,
+        deliveryUnknown: operation === 'send' && mayHaveBeenAccepted(error, provider),
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import type { Mailer } from './types.js';
+declare const providerOptions: {
+    readonly resend: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        provider: z.ZodLiteral<"resend">;
+        apiKey: z.ZodString;
+    }, z.core.$strip>;
+    readonly brevo: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        provider: z.ZodLiteral<"brevo">;
+        apiKey: z.ZodString;
+    }, z.core.$strip>;
+    readonly postmark: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        provider: z.ZodLiteral<"postmark">;
+        apiKey: z.ZodString;
+    }, z.core.$strip>;
+    readonly sendgrid: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        provider: z.ZodLiteral<"sendgrid">;
+        apiKey: z.ZodString;
+    }, z.core.$strip>;
+    readonly mailgun: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        provider: z.ZodLiteral<"mailgun">;
+        apiKey: z.ZodString;
+        domain: z.ZodString;
+        region: z.ZodDefault<z.ZodEnum<{
+            us: "us";
+            eu: "eu";
+        }>>;
+    }, z.core.$strip>;
+    readonly ses: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        provider: z.ZodLiteral<"ses">;
+        region: z.ZodString;
+    }, z.core.$strip>;
+    readonly smtp: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        provider: z.ZodLiteral<"smtp">;
+        host: z.ZodString;
+        port: z.ZodNumber;
+        secure: z.ZodBoolean;
+        user: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+        connectionTimeout: z.ZodDefault<z.ZodNumber>;
+        greetingTimeout: z.ZodDefault<z.ZodNumber>;
+        socketTimeout: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+};
+export type MailerOptions = z.input<typeof providerOptions.resend> | z.input<typeof providerOptions.brevo> | z.input<typeof providerOptions.postmark> | z.input<typeof providerOptions.sendgrid> | z.input<typeof providerOptions.mailgun> | z.input<typeof providerOptions.ses> | z.input<typeof providerOptions.smtp>;
+export declare function createMailer(input: MailerOptions): Mailer;
+export { MailError } from './errors.js';
+export type { MailErrorCode, MailErrorOperation, MailErrorOptions } from './errors.js';
+export type { MailAddress, MailAttachment, Mailer, NormalizedMailInput, ProviderName, SendMailInput, SendMailResult, } from './types.js';