typedmailer 1.2.0 → 1.3.0

package/README.md

@@ -176,6 +176,32 @@ Provider capabilities differ. Unsupported fields return a `MailError` with code
 | Amazon SES | No                 | No               | Yes      | Yes                | Unsupported          |
 | SMTP       | Yes                | No               | No       | Yes                | Yes                  |
 
+### Custom providers
+
+Use `ProviderAdapter` when your provider is not built in or you need to wrap an existing mail SDK. The adapter receives normalized addresses and the configured default sender; its `send` method must resolve with the provider message ID. Implement `verifyConnection` only when the provider offers a safe connection check, and use `close` to release resources such as pooled clients.
+
+```ts
+import { createMailer, type ProviderAdapter } from 'typedmailer';
+
+const adapter: ProviderAdapter<'acme'> = {
+  name: 'acme',
+  async send(message) {
+    const response = await acmeClient.sendEmail(message);
+    return { messageId: response.id };
+  },
+  async close() {
+    await acmeClient.close();
+  },
+};
+
+const mailer = createMailer({ provider: adapter, from: 'noreply@example.com' });
+const result = await mailer.send({ to: 'person@example.com', subject: 'Hello', text: 'Hi' });
+// result.provider is typed as "acme".
+await mailer.close();
+```
+
+The custom adapter owns provider SDK setup, field support, and error handling. Throwing an error still passes through TypedMailer error normalization. Connection verification is reported as `unsupported` when the adapter does not implement it.
+
 ```ts
 await mailer.send({
   to: [{ email: 'person@example.com', name: 'Sam' }],

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { MailAddress } from './types.js';
 export declare const mailInputSchema: z.ZodObject<{
     from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
         email: z.ZodString;
@@ -44,14 +45,8 @@ export declare const mailInputSchema: z.ZodObject<{
     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;
-}): {
+export declare function emailOf(address: MailAddress): string;
+export declare function addressWithName(address: MailAddress): {
     email: string;
     name?: string;
 };

package/dist/config.js

@@ -53,8 +53,9 @@ export function emailOf(address) {
     return namedAddress?.[2] ?? address;
 }
 export function addressWithName(address) {
-    if (typeof address !== 'string')
-        return address;
+    if (typeof address !== 'string') {
+        return { email: address.email, ...(address.name !== undefined ? { name: address.name } : {}) };
+    }
     const namedAddress = address.match(/^(.+) <([^<>\s]+@[^<>\s]+)>$/);
     return namedAddress ? { email: namedAddress[2], name: namedAddress[1] } : { email: address };
 }

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import { type MailerOptions } from './providers/registry.js';
-import type { Mailer } from './types.js';
-export type { MailerOptions };
-export declare function createMailer(input: MailerOptions): Mailer;
+import { type MailerOptions as BuiltInMailerOptions } from './providers/registry.js';
+import type { CustomMailerOptions, Mailer, ProviderName } from './types.js';
+export type MailerOptions = BuiltInMailerOptions | CustomMailerOptions;
+export declare function createMailer<const TProvider extends string>(input: CustomMailerOptions<TProvider>): Mailer<TProvider>;
+export declare function createMailer(input: BuiltInMailerOptions): Mailer<ProviderName | 'test'>;
+export declare function createMailer(input: MailerOptions): Mailer<string>;
 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';
+export type { CustomMailerOptions, MailAddress, MailAttachment, Mailer, NormalizedMailInput, ProviderAdapter, ProviderName, ProviderSendResult, SendMailInput, SendMailResult, } from './types.js';

package/dist/index.js

@@ -1,21 +1,59 @@
 import { Buffer } from 'node:buffer';
+import { z } from 'zod';
 import { MailError, normalizeProviderError } from './errors.js';
 import { mailInputSchema, normalizeAddresses } from './config.js';
-import { loadProvider, mailerOptionsSchema } from './providers/registry.js';
+import { loadProvider, mailerBaseOptionsSchema, mailerOptionsSchema, } from './providers/registry.js';
+function isProviderAdapter(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const adapter = value;
+    return (typeof adapter.name === 'string' &&
+        adapter.name.length > 0 &&
+        adapter.name.trim() === adapter.name &&
+        typeof adapter.send === 'function' &&
+        (adapter.verifyConnection === undefined || typeof adapter.verifyConnection === 'function') &&
+        (adapter.close === undefined || typeof adapter.close === 'function'));
+}
+const customMailerOptionsSchema = mailerBaseOptionsSchema
+    .extend({ provider: z.custom(isProviderAdapter, 'Invalid custom provider adapter.') })
+    .strict();
+function isCustomOptions(input) {
+    return typeof input.provider !== 'string';
+}
+function createCustomProvider(adapter) {
+    return {
+        send: (input) => adapter.send(input),
+        async verifyConnection() {
+            if (!adapter.verifyConnection) {
+                throw new MailError(`Connection verification is not supported by the custom provider "${adapter.name}".`, 'unsupported', adapter.name, false);
+            }
+            await adapter.verifyConnection();
+        },
+        async close() {
+            await adapter.close?.();
+        },
+    };
+}
 export function createMailer(input) {
     let providerPromise;
     let closed = false;
     let closePromise;
     let activeOperations = 0;
     let resolveOperationsIdle;
-    const parsedOptions = mailerOptionsSchema.parse(input);
+    const parsedOptions = isCustomOptions(input)
+        ? customMailerOptionsSchema.parse(input)
+        : mailerOptionsSchema.parse(input);
+    const providerName = typeof parsedOptions.provider === 'string' ? parsedOptions.provider : parsedOptions.provider.name;
     const assertOpen = () => {
         if (closed)
-            throw new MailError('Mailer has been closed.', 'configuration', parsedOptions.provider, false);
+            throw new MailError('Mailer has been closed.', 'configuration', providerName, false);
     };
     const getProvider = () => {
         assertOpen();
-        providerPromise ??= loadProvider(parsedOptions);
+        providerPromise ??=
+            typeof parsedOptions.provider === 'string'
+                ? loadProvider(parsedOptions)
+                : Promise.resolve(createCustomProvider(parsedOptions.provider));
         return providerPromise;
     };
     const runWithProvider = async (operation) => {
@@ -41,11 +79,13 @@ export function createMailer(input) {
                     ? Buffer.byteLength(attachment.content)
                     : attachment.content.byteLength), 0) ?? 0;
             if (parsedOptions.maxAttachmentBytes !== undefined && attachmentBytes > parsedOptions.maxAttachmentBytes) {
-                throw new MailError(`Attachment content exceeds the configured limit of ${parsedOptions.maxAttachmentBytes} bytes.`, 'configuration', parsedOptions.provider, false);
+                throw new MailError(`Attachment content exceeds the configured limit of ${parsedOptions.maxAttachmentBytes} bytes.`, 'configuration', providerName, false);
             }
+            const cc = normalizeAddresses(parsed.cc);
+            const bcc = normalizeAddresses(parsed.bcc);
             const normalized = {
-                from: (parsed.from ?? parsedOptions.from),
-                to: (normalizeAddresses(parsed.to) ?? []),
+                from: parsed.from ?? parsedOptions.from,
+                to: normalizeAddresses(parsed.to) ?? [],
                 subject: parsed.subject,
                 ...(parsed.messageId ? { messageId: parsed.messageId } : {}),
                 ...(parsed.text !== undefined ? { text: parsed.text } : {}),
@@ -63,24 +103,20 @@ export function createMailer(input) {
                     : {}),
                 ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
                 ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
-                ...(normalizeAddresses(parsed.cc)
-                    ? { cc: normalizeAddresses(parsed.cc) }
-                    : {}),
-                ...(normalizeAddresses(parsed.bcc)
-                    ? { bcc: normalizeAddresses(parsed.bcc) }
-                    : {}),
+                ...(cc ? { cc } : {}),
+                ...(bcc ? { bcc } : {}),
                 ...(parsed.replyTo ? { replyTo: parsed.replyTo } : {}),
             };
             try {
                 const result = await runWithProvider((provider) => provider.send(normalized));
                 return {
-                    provider: parsedOptions.provider,
+                    provider: providerName,
                     messageId: result.messageId,
                     acceptedAt: new Date(),
                 };
             }
             catch (error) {
-                throw normalizeProviderError(error, parsedOptions.provider, 'send');
+                throw normalizeProviderError(error, providerName, 'send');
             }
         },
         async verifyConnection() {
@@ -88,7 +124,7 @@ export function createMailer(input) {
                 await runWithProvider((provider) => provider.verifyConnection());
             }
             catch (error) {
-                throw normalizeProviderError(error, parsedOptions.provider);
+                throw normalizeProviderError(error, providerName);
             }
         },
         async close() {

package/dist/providers/registry.d.ts

@@ -1,5 +1,12 @@
 import { z } from 'zod';
 import type { MailProvider } from '../types.js';
+export declare const mailerBaseOptionsSchema: z.ZodObject<{
+    from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>;
+    maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 export declare const providerOptions: {
     readonly resend: z.ZodObject<{
         from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{

package/dist/providers/registry.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { MailError } from '../errors.js';
-const baseOptions = z.object({
+export const mailerBaseOptionsSchema = z.object({
     from: z.union([
         z.string().email(),
         z.string().regex(/^.+ <[^<>\s]+@[^<>\s]+>$/, 'Use a valid email address or "Name <email@example.com>".'),
@@ -10,18 +10,18 @@ const baseOptions = z.object({
     maxAttachmentBytes: z.number().int().positive().optional(),
 });
 export const providerOptions = {
-    resend: baseOptions.extend({ provider: z.literal('resend'), apiKey: z.string().min(1) }),
-    brevo: baseOptions.extend({ provider: z.literal('brevo'), apiKey: z.string().min(1) }),
-    postmark: baseOptions.extend({ provider: z.literal('postmark'), apiKey: z.string().min(1) }),
-    sendgrid: baseOptions.extend({ provider: z.literal('sendgrid'), apiKey: z.string().min(1) }),
-    mailgun: baseOptions.extend({
+    resend: mailerBaseOptionsSchema.extend({ provider: z.literal('resend'), apiKey: z.string().min(1) }),
+    brevo: mailerBaseOptionsSchema.extend({ provider: z.literal('brevo'), apiKey: z.string().min(1) }),
+    postmark: mailerBaseOptionsSchema.extend({ provider: z.literal('postmark'), apiKey: z.string().min(1) }),
+    sendgrid: mailerBaseOptionsSchema.extend({ provider: z.literal('sendgrid'), apiKey: z.string().min(1) }),
+    mailgun: mailerBaseOptionsSchema.extend({
         provider: z.literal('mailgun'),
         apiKey: z.string().min(1),
         domain: z.string().min(1),
         region: z.enum(['us', 'eu']).default('us'),
     }),
-    ses: baseOptions.extend({ provider: z.literal('ses'), region: z.string().min(1) }),
-    smtp: baseOptions
+    ses: mailerBaseOptionsSchema.extend({ provider: z.literal('ses'), region: z.string().min(1) }),
+    smtp: mailerBaseOptionsSchema
         .extend({
         provider: z.literal('smtp'),
         host: z.string().min(1),

package/dist/testing.d.ts

@@ -2,7 +2,7 @@ import type { Mailer, SendMailInput } from './types.js';
 export interface CapturedMail extends SendMailInput {
     readonly from: NonNullable<SendMailInput['from']>;
 }
-export interface TestMailer extends Mailer {
+export interface TestMailer extends Mailer<'test'> {
     readonly sent: CapturedMail[];
     clear(): void;
 }

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 export type MailAddress = string | {
     readonly email: string;
-    readonly name?: string;
+    readonly name?: string | undefined;
 };
 export interface MailAttachment {
     readonly filename: string;
@@ -24,18 +24,29 @@ export interface SendMailInput {
     readonly metadata?: Readonly<Record<string, string>>;
 }
 export type ProviderName = 'resend' | 'brevo' | 'smtp' | 'postmark' | 'sendgrid' | 'mailgun' | 'ses';
-export interface SendMailResult {
-    readonly provider: ProviderName | 'test';
+export interface SendMailResult<TProvider extends string = ProviderName | 'test'> {
+    readonly provider: TProvider;
     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>;
+export interface Mailer<TProvider extends string = ProviderName | 'test'> {
+    send(input: SendMailInput): Promise<SendMailResult<TProvider>>;
     verifyConnection(): Promise<void>;
     /** Rejects new operations, waits for active operations, and closes the provider at most once. */
     close(): Promise<void>;
 }
+export interface ProviderAdapter<TProvider extends string = string> {
+    readonly name: TProvider;
+    send(input: NormalizedMailInput): Promise<ProviderSendResult>;
+    verifyConnection?(): Promise<void>;
+    close?(): Promise<void> | void;
+}
+export interface CustomMailerOptions<TProvider extends string = string> {
+    readonly provider: ProviderAdapter<TProvider>;
+    readonly from: MailAddress;
+    readonly maxAttachmentBytes?: number;
+}
 export interface NormalizedMailInput extends Omit<SendMailInput, 'from' | 'to' | 'cc' | 'bcc' | 'replyTo'> {
     readonly from: MailAddress;
     readonly to: readonly MailAddress[];

package/dist/webhooks/types.d.ts

@@ -15,6 +15,7 @@ export type WebhookHeaders = Readonly<Record<string, string | readonly string[]
 interface RawWebhookInput {
     readonly rawBody: string | Uint8Array;
     readonly headers: WebhookHeaders;
+    readonly maxBodyBytes?: number;
     readonly now?: Date;
     readonly toleranceSeconds?: number;
 }

package/dist/webhooks.js

@@ -4,6 +4,11 @@ import { normalizeMailgun, normalizeProviderEvents, normalizeResend, normalizeSe
 export { WebhookVerificationError } from './webhooks/types.js';
 /** Authenticates a provider webhook before returning normalized, typed email events. */
 export async function verifyWebhook(input) {
+    const rawBodyByteLength = typeof input.rawBody === 'string' ? Buffer.byteLength(input.rawBody) : input.rawBody.byteLength;
+    if (input.maxBodyBytes !== undefined &&
+        (!Number.isSafeInteger(input.maxBodyBytes) || input.maxBodyBytes < 1 || rawBodyByteLength > input.maxBodyBytes)) {
+        throw new WebhookVerificationError('invalid_payload');
+    }
     const rawBody = Buffer.from(input.rawBody);
     let payload;
     try {

package/docs/provider-contracts.md

@@ -1,6 +1,6 @@
 # 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.
+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; built-in adapter contract tests are organized by provider under `tests/providers/`.
 
 ## Shared guarantees
 
@@ -28,3 +28,7 @@ Attachments are buffered for provider SDK requests. Configure `maxAttachmentByte
 ## Updating a provider adapter
 
 When changing an adapter, add its configuration schema and lazy loader in `src/providers/registry.ts`, keep its implementation in `src/providers/<provider>.ts`, and 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. CI derives the minimum-version install list from each peer range's explicit lower bound so the support metadata and compatibility check stay aligned.
+
+## Custom adapters
+
+Applications can provide a `ProviderAdapter<TName>` directly to `createMailer()` without adding a built-in provider. Its `send()` method receives `NormalizedMailInput`: `from` is always set, and `to`, `cc`, and `bcc` are arrays when present. Resolve with `{ messageId }` after the SDK accepts the message. `verifyConnection()` and `close()` are optional; verification rejects with `unsupported` when omitted, while close is a no-op. TypedMailer normalizes thrown errors and tags results with the adapter's name. The generic adapter name is preserved in `SendMailResult<TName>` for TypeScript callers. Custom adapters are responsible for documenting and enforcing unsupported message fields.

package/docs/webhooks.md

@@ -4,7 +4,7 @@ TypedMailer exposes `verifyWebhook()` from `typedmailer/webhooks`. It authentica
 
 ## Raw request bodies
 
-Pass the exact bytes received by your HTTP framework. Parsing JSON and serializing it again changes the signed input and causes verification to fail. `rawBody` accepts a string or `Uint8Array`; `headers` is a case-insensitive record of request header names and values. If the framework parses request bodies automatically, configure a raw-body capture before its JSON parser.
+Pass the exact bytes received by your HTTP framework. Parsing JSON and serializing it again changes the signed input and causes verification to fail. `rawBody` accepts a string or `Uint8Array`; `headers` is a case-insensitive record of request header names and values. If the framework parses request bodies automatically, configure a raw-body capture before its JSON parser. Apply an HTTP request-body size limit before buffering the body. You can also set `maxBodyBytes` on `verifyWebhook()` to reject an oversized payload before JSON parsing; it has no default because provider event batches vary in size.
 
 ## Authentication configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typedmailer",
-  "version": "1.2.0",
+  "version": "1.3.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",