edge-mailer 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # edge-mailer
 
+## 0.6.1
+
+- Add JSR module documentation for public entrypoints.
+- Add JSDoc for exported symbols to improve generated API documentation.
+
 ## 0.6.0
 
 - Start public prerelease versioning at `v0.6.0`.

package/CLIENT-INTEGRATION.md

@@ -1,8 +1,7 @@
 # Client Integration
 
 Edge Mailer exposes one SMTP client API with runtime-specific entrypoints.
-Cloudflare Workers and Deno are both first-class edge runtimes. Cloudflare
-Workers was implemented first; it is not a priority tier over Deno.
+Cloudflare Workers and Deno are both first-class edge runtimes.
 
 ## Runtime Imports
 
@@ -24,6 +23,10 @@ The default package entrypoint remains Cloudflare-compatible:
 import { EdgeMailer } from 'edge-mailer'
 ```
 
+The default npm entrypoint imports `cloudflare:sockets`, so it is not intended
+to load directly in plain Node.js. Use a runtime-specific subpath for non-
+Cloudflare environments.
+
 ## Minimal Send
 
 ```ts

package/README.md

@@ -4,9 +4,7 @@ Edge Mailer is a serverless SMTP submission toolkit for applications that need
 to send through existing SMTP infrastructure from modern edge runtimes.
 
 The current implementation supports Cloudflare Workers and Deno as first-class
-edge runtimes. Cloudflare Workers was the first runtime implemented, but it is
-not a priority tier over Deno. The public API is versioned as a `0.x`
-prerelease surface.
+edge runtimes. The public API is versioned as a `0.x` prerelease surface.
 
 Install from npm for Cloudflare Workers and Node-compatible build pipelines:
 
@@ -62,6 +60,9 @@ Use the default import or Cloudflare subpath for Cloudflare Workers:
 import { EdgeMailer } from 'edge-mailer/cloudflare'
 ```
 
+The default npm entrypoint is Cloudflare-compatible and imports
+`cloudflare:sockets`; it is not intended to load directly in plain Node.js.
+
 Use the Deno subpath for Deno:
 
 ```ts
@@ -94,10 +95,9 @@ Runnable samples and deploy quickstarts live in [sample](sample):
 
 ## Roadmap
 
-Cloudflare Workers and Deno are both first-class edge runtimes. Cloudflare
-Workers was implemented first; future work should keep both runtimes aligned
-unless a runtime-specific platform limit is documented. The next useful work is
-grouped by product risk:
+Cloudflare Workers and Deno are both first-class edge runtimes. Future work
+should keep both runtimes aligned unless a runtime-specific platform limit is
+documented. The next useful work is grouped by product risk:
 
 - Stabilization: publish a v0 package surface, keep runtime subpaths stable,
   expand live smokes across at least two SMTP providers, and keep package

package/dist/cloudflare.d.mts

@@ -1,2 +1,2 @@
-export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, B as BatchSendOptions, c as BatchSendResult, C as Credentials, D as DkimConfig, d as DsnOptions, E as EdgeMailerOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, i as EmailOptions, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, n as SmtpConnectionPool, o as SmtpMailer, p as SmtpPoolOptions, q as SmtpRejectedRecipient, r as SmtpSendReceipt, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-CcxclJQJ.mjs';
+export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, B as BatchSendOptions, c as BatchSendResult, C as Credentials, D as DkimConfig, d as DsnOptions, E as EdgeMailerOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, i as EmailOptions, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, n as SmtpConnectionPool, o as SmtpMailer, p as SmtpPoolOptions, q as SmtpRejectedRecipient, r as SmtpSendReceipt, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-Db8Z1fqb.mjs';
 export { EdgeMailer, cloudflareSocketConnector } from './index.mjs';

package/dist/cloudflare.d.ts

@@ -1,2 +1,2 @@
-export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, B as BatchSendOptions, c as BatchSendResult, C as Credentials, D as DkimConfig, d as DsnOptions, E as EdgeMailerOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, i as EmailOptions, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, n as SmtpConnectionPool, o as SmtpMailer, p as SmtpPoolOptions, q as SmtpRejectedRecipient, r as SmtpSendReceipt, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-CcxclJQJ.js';
+export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, B as BatchSendOptions, c as BatchSendResult, C as Credentials, D as DkimConfig, d as DsnOptions, E as EdgeMailerOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, i as EmailOptions, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, n as SmtpConnectionPool, o as SmtpMailer, p as SmtpPoolOptions, q as SmtpRejectedRecipient, r as SmtpSendReceipt, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-Db8Z1fqb.js';
 export { EdgeMailer, cloudflareSocketConnector } from './index.js';

package/dist/deno.d.mts

@@ -1,5 +1,5 @@
-import { o as SmtpMailer, E as EdgeMailerOptions, i as EmailOptions, r as SmtpSendReceipt, B as BatchSendOptions, c as BatchSendResult, n as SmtpConnectionPool, e as EdgeSocketConnector } from './pool-CcxclJQJ.mjs';
-export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, C as Credentials, D as DkimConfig, d as DsnOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, p as SmtpPoolOptions, q as SmtpRejectedRecipient, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-CcxclJQJ.mjs';
+import { o as SmtpMailer, E as EdgeMailerOptions, i as EmailOptions, r as SmtpSendReceipt, B as BatchSendOptions, c as BatchSendResult, n as SmtpConnectionPool, e as EdgeSocketConnector } from './pool-Db8Z1fqb.mjs';
+export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, C as Credentials, D as DkimConfig, d as DsnOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, p as SmtpPoolOptions, q as SmtpRejectedRecipient, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-Db8Z1fqb.mjs';
 
 type DenoConn = {
     readable: ReadableStream<Uint8Array>;
@@ -7,6 +7,7 @@ type DenoConn = {
     closed?: Promise<void>;
     close(): void;
 };
+/** Subset of Deno socket APIs required by the Deno connector. */
 type DenoSocketRuntime = {
     connect(options: {
         hostname: string;
@@ -22,12 +23,18 @@ type DenoSocketRuntime = {
         hostname?: string;
     }): Promise<DenoConn>;
 };
+/** Creates an SMTP socket connector for Deno runtimes. */
 declare function createDenoSocketConnector(deno?: DenoSocketRuntime): EdgeSocketConnector;
+/** Deno mailer using Deno TCP, TLS, and STARTTLS socket APIs. */
 declare class DenoMailer extends SmtpMailer {
     private constructor();
+    /** Opens and initializes an SMTP session in Deno. */
     static connect(options: EdgeMailerOptions): Promise<DenoMailer>;
+    /** Sends one message and closes the SMTP session afterward. */
     static send(options: EdgeMailerOptions, email: EmailOptions): Promise<SmtpSendReceipt>;
+    /** Sends messages sequentially over one SMTP session. */
     static sendBatch(options: EdgeMailerOptions, emails: EmailOptions[], batchOptions?: BatchSendOptions): Promise<BatchSendResult>;
+    /** Creates a bounded pool of Deno SMTP sessions. */
     static createPool(options: EdgeMailerOptions): SmtpConnectionPool<DenoMailer>;
 }
 

package/dist/deno.d.ts

@@ -1,5 +1,5 @@
-import { o as SmtpMailer, E as EdgeMailerOptions, i as EmailOptions, r as SmtpSendReceipt, B as BatchSendOptions, c as BatchSendResult, n as SmtpConnectionPool, e as EdgeSocketConnector } from './pool-CcxclJQJ.js';
-export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, C as Credentials, D as DkimConfig, d as DsnOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, p as SmtpPoolOptions, q as SmtpRejectedRecipient, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-CcxclJQJ.js';
+import { o as SmtpMailer, E as EdgeMailerOptions, i as EmailOptions, r as SmtpSendReceipt, B as BatchSendOptions, c as BatchSendResult, n as SmtpConnectionPool, e as EdgeSocketConnector } from './pool-Db8Z1fqb.js';
+export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, C as Credentials, D as DkimConfig, d as DsnOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, p as SmtpPoolOptions, q as SmtpRejectedRecipient, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-Db8Z1fqb.js';
 
 type DenoConn = {
     readable: ReadableStream<Uint8Array>;
@@ -7,6 +7,7 @@ type DenoConn = {
     closed?: Promise<void>;
     close(): void;
 };
+/** Subset of Deno socket APIs required by the Deno connector. */
 type DenoSocketRuntime = {
     connect(options: {
         hostname: string;
@@ -22,12 +23,18 @@ type DenoSocketRuntime = {
         hostname?: string;
     }): Promise<DenoConn>;
 };
+/** Creates an SMTP socket connector for Deno runtimes. */
 declare function createDenoSocketConnector(deno?: DenoSocketRuntime): EdgeSocketConnector;
+/** Deno mailer using Deno TCP, TLS, and STARTTLS socket APIs. */
 declare class DenoMailer extends SmtpMailer {
     private constructor();
+    /** Opens and initializes an SMTP session in Deno. */
     static connect(options: EdgeMailerOptions): Promise<DenoMailer>;
+    /** Sends one message and closes the SMTP session afterward. */
     static send(options: EdgeMailerOptions, email: EmailOptions): Promise<SmtpSendReceipt>;
+    /** Sends messages sequentially over one SMTP session. */
     static sendBatch(options: EdgeMailerOptions, emails: EmailOptions[], batchOptions?: BatchSendOptions): Promise<BatchSendResult>;
+    /** Creates a bounded pool of Deno SMTP sessions. */
     static createPool(options: EdgeMailerOptions): SmtpConnectionPool<DenoMailer>;
 }
 

package/dist/index.d.mts

@@ -1,12 +1,18 @@
-import { o as SmtpMailer, E as EdgeMailerOptions, i as EmailOptions, r as SmtpSendReceipt, B as BatchSendOptions, c as BatchSendResult, n as SmtpConnectionPool, e as EdgeSocketConnector } from './pool-CcxclJQJ.mjs';
-export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, C as Credentials, D as DkimConfig, d as DsnOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, p as SmtpPoolOptions, q as SmtpRejectedRecipient, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-CcxclJQJ.mjs';
+import { o as SmtpMailer, E as EdgeMailerOptions, i as EmailOptions, r as SmtpSendReceipt, B as BatchSendOptions, c as BatchSendResult, n as SmtpConnectionPool, e as EdgeSocketConnector } from './pool-Db8Z1fqb.mjs';
+export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, C as Credentials, D as DkimConfig, d as DsnOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, p as SmtpPoolOptions, q as SmtpRejectedRecipient, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-Db8Z1fqb.mjs';
 
+/** Cloudflare Workers socket connector backed by `cloudflare:sockets`. */
 declare const cloudflareSocketConnector: EdgeSocketConnector;
+/** Cloudflare Workers mailer using outbound TCP sockets. */
 declare class EdgeMailer extends SmtpMailer {
     private constructor();
+    /** Opens and initializes an SMTP session in a Cloudflare Worker. */
     static connect(options: EdgeMailerOptions): Promise<EdgeMailer>;
+    /** Sends one message and closes the SMTP session afterward. */
     static send(options: EdgeMailerOptions, email: EmailOptions): Promise<SmtpSendReceipt>;
+    /** Sends messages sequentially over one SMTP session. */
     static sendBatch(options: EdgeMailerOptions, emails: EmailOptions[], batchOptions?: BatchSendOptions): Promise<BatchSendResult>;
+    /** Creates a bounded pool of Cloudflare SMTP sessions. */
     static createPool(options: EdgeMailerOptions): SmtpConnectionPool<EdgeMailer>;
 }
 

package/dist/index.d.ts

@@ -1,12 +1,18 @@
-import { o as SmtpMailer, E as EdgeMailerOptions, i as EmailOptions, r as SmtpSendReceipt, B as BatchSendOptions, c as BatchSendResult, n as SmtpConnectionPool, e as EdgeSocketConnector } from './pool-CcxclJQJ.js';
-export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, C as Credentials, D as DkimConfig, d as DsnOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, p as SmtpPoolOptions, q as SmtpRejectedRecipient, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-CcxclJQJ.js';
+import { o as SmtpMailer, E as EdgeMailerOptions, i as EmailOptions, r as SmtpSendReceipt, B as BatchSendOptions, c as BatchSendResult, n as SmtpConnectionPool, e as EdgeSocketConnector } from './pool-Db8Z1fqb.js';
+export { A as AttachmentDisposition, a as AttachmentEncoding, b as AuthType, C as Credentials, D as DkimConfig, d as DsnOptions, f as Email, g as EmailAttachment, h as EmailAttachmentContent, L as LogLevel, M as MailBodyType, j as MailEnvelopeOptions, P as PipeliningMode, S as SMTPError, k as SMTPErrorOptions, l as SMTPStage, m as SmtpBodyType, p as SmtpPoolOptions, q as SmtpRejectedRecipient, U as User, s as encodeHeader, t as signDkimMessage, v as validateDkimConfig } from './pool-Db8Z1fqb.js';
 
+/** Cloudflare Workers socket connector backed by `cloudflare:sockets`. */
 declare const cloudflareSocketConnector: EdgeSocketConnector;
+/** Cloudflare Workers mailer using outbound TCP sockets. */
 declare class EdgeMailer extends SmtpMailer {
     private constructor();
+    /** Opens and initializes an SMTP session in a Cloudflare Worker. */
     static connect(options: EdgeMailerOptions): Promise<EdgeMailer>;
+    /** Sends one message and closes the SMTP session afterward. */
     static send(options: EdgeMailerOptions, email: EmailOptions): Promise<SmtpSendReceipt>;
+    /** Sends messages sequentially over one SMTP session. */
     static sendBatch(options: EdgeMailerOptions, emails: EmailOptions[], batchOptions?: BatchSendOptions): Promise<BatchSendResult>;
+    /** Creates a bounded pool of Cloudflare SMTP sessions. */
     static createPool(options: EdgeMailerOptions): SmtpConnectionPool<EdgeMailer>;
 }
 

package/dist/{pool-CcxclJQJ.d.mts → pool-Db8Z1fqb.d.mts}

@@ -1,8 +1,11 @@
+/** Encodes non-ASCII header text using RFC 2047 quoted-printable words. */
 declare function encodeHeader(text: string): string;
+/** Email address with an optional display name. */
 type User = {
     name?: string;
     email: string;
 };
+/** SMTP delivery status notification options. */
 type DsnOptions = {
     envelopeId?: string;
     RET?: {
@@ -17,7 +20,9 @@ type DsnOptions = {
     };
     ORCPT?: string;
 };
+/** SMTP MAIL FROM BODY parameter value. */
 type MailBodyType = '7BIT' | '8BITMIME';
+/** SMTP envelope overrides used for MAIL FROM and RCPT TO commands. */
 type MailEnvelopeOptions = {
     from?: string;
     to?: string | string[];
@@ -26,9 +31,13 @@ type MailEnvelopeOptions = {
     smtpUtf8?: boolean;
     requireTls?: boolean;
 };
+/** MIME content-transfer-encoding for an attachment body. */
 type AttachmentEncoding = 'base64' | 'quoted-printable' | '7bit';
+/** MIME content disposition for attachment parts. */
 type AttachmentDisposition = 'attachment' | 'inline';
+/** Supported attachment content inputs. */
 type EmailAttachmentContent = string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob;
+/** File or inline part to include in the generated MIME message. */
 type EmailAttachment = {
     filename: string;
     content: EmailAttachmentContent;
@@ -38,6 +47,7 @@ type EmailAttachment = {
     contentId?: string;
     disposition?: AttachmentDisposition;
 };
+/** High-level email message options accepted by mailer send methods. */
 type EmailOptions = {
     from: string | User;
     to: string | string[] | User | User[];
@@ -52,28 +62,47 @@ type EmailOptions = {
     envelope?: MailEnvelopeOptions;
     dsnOverride?: DsnOptions;
 };
+/** Builds MIME email messages and SMTP DATA payloads from {@link EmailOptions}. */
 declare class Email {
+    /** Sender address used for MIME From and default envelope sender. */
     readonly from: User;
+    /** Primary recipients emitted in the MIME To header. */
     readonly to: User[];
+    /** Reply-To address. */
     readonly reply?: User;
+    /** Carbon-copy recipients emitted in the MIME Cc header. */
     readonly cc?: User[];
+    /** Blind-copy recipients used for envelope delivery only. */
     readonly bcc?: User[];
+    /** MIME Subject header value. */
     readonly subject: string;
+    /** Plain text body. */
     readonly text?: string;
+    /** HTML body. */
     readonly html?: string;
+    /** SMTP envelope overrides. */
     readonly envelope?: Omit<MailEnvelopeOptions, 'to'> & {
         to?: string[];
     };
+    /** Per-message DSN overrides. */
     readonly dsnOverride?: DsnOptions;
+    /** Attachments and inline content parts. */
     readonly attachments?: EmailAttachment[];
+    /** Custom MIME headers. */
     readonly headers: Record<string, string>;
+    /** Marks this email as sent for callers tracking queued send state. */
     setSent: () => void;
+    /** Marks this email as failed for callers tracking queued send state. */
     setSentError: (e: unknown) => void;
+    /** Resolves when the email has been sent by a mailer. */
     sent: Promise<void>;
+    /** Creates a MIME message builder from high-level email options. */
     constructor(options: EmailOptions);
     private static toUsers;
     private static toEnvelopeRecipients;
+    /** Returns MIME message data without SMTP dot-stuffing. */
     getMessageData(): string;
+    /** Returns MIME message data, resolving Blob attachment content first. */
     getMessageDataAsync(): Promise<string>;
     private buildMessageData;
     private resolveAttachments;
@@ -87,8 +116,11 @@ declare class Email {
     private bytesToWrappedBase64;
     private bytesToBase64;
     private wrapBase64;
+    /** Returns SMTP DATA payload with dot-stuffing and final terminator. */
     getEmailData(): string;
+    /** Returns SMTP DATA payload after resolving async attachment content. */
     getEmailDataAsync(): Promise<string>;
+    /** Dot-stuffs MIME data and appends the SMTP DATA terminator. */
     static toSmtpData(data: string): string;
     private static applyDotStuffing;
     private generateSafeBoundary;
@@ -101,15 +133,19 @@ declare class Email {
     private resolveCC;
 }
 
+/** DKIM signing options for RSA-SHA256 signatures. */
 type DkimConfig = {
     domainName: string;
     keySelector: string;
     privateKey: string;
     headerFieldNames?: string[];
 };
+/** Validates DKIM configuration before message signing. */
 declare function validateDkimConfig(dkim: DkimConfig | undefined): void;
+/** Returns a MIME message prefixed with a DKIM-Signature header. */
 declare function signDkimMessage(message: string, dkim: DkimConfig): Promise<string>;
 
+/** Verbosity levels for SMTP client logging. */
 declare enum LogLevel {
     DEBUG = 0,
     INFO = 1,
@@ -118,7 +154,9 @@ declare enum LogLevel {
     NONE = 4
 }
 
+/** TLS mode requested from a runtime socket adapter. */
 type SocketTlsMode = 'off' | 'on' | 'starttls';
+/** Minimal readable/writable socket contract used by the SMTP core. */
 type EdgeSocket = {
     readable: ReadableStream<Uint8Array>;
     writable: WritableStream<Uint8Array>;
@@ -127,24 +165,30 @@ type EdgeSocket = {
     close(reason?: unknown): Promise<void> | void;
     startTls?(): EdgeSocket | Promise<EdgeSocket>;
 };
+/** Runtime socket connection request. */
 type EdgeSocketConnectOptions = {
     hostname: string;
     port: number;
     tls: SocketTlsMode;
     signal?: AbortSignal;
 };
+/** Runtime adapter that opens SMTP TCP/TLS sockets. */
 type EdgeSocketConnector = {
     connect(options: EdgeSocketConnectOptions): EdgeSocket | Promise<EdgeSocket>;
 };
 
+/** SMTP authentication mechanisms supported by the shared SMTP client. */
 type AuthType = 'plain' | 'login' | 'cram-md5';
+/** Username and password used for SMTP AUTH. */
 type Credentials = {
     username: string;
     password: string;
 };
+/** Controls ordered batch behavior when one message fails. */
 type BatchSendOptions = {
     continueOnError?: boolean;
 };
+/** Recipient rejected by the SMTP server during the envelope phase. */
 type SmtpRejectedRecipient = {
     recipient: string;
     response: string;
@@ -152,6 +196,7 @@ type SmtpRejectedRecipient = {
     enhancedStatusCode?: string;
     transient: boolean;
 };
+/** Structured receipt returned after an SMTP DATA transaction completes. */
 type SmtpSendReceipt = {
     messageId: string;
     envelope: {
@@ -165,26 +210,40 @@ type SmtpSendReceipt = {
     enhancedStatusCode?: string;
     size: number;
 };
+/** Ordered result list returned by `sendBatch()` and `sendMany()`. */
 type BatchSendResult = PromiseSettledResult<SmtpSendReceipt>[];
+/** SMTP PIPELINING behavior. */
 type PipeliningMode = 'auto' | false;
+/** SMTP message body encoding advertised in MAIL FROM. */
 type SmtpBodyType = '7BIT' | '8BITMIME';
+/** Protocol stage attached to structured SMTP errors. */
 type SMTPStage = 'connect' | 'greet' | 'ehlo' | 'helo' | 'starttls' | 'auth' | 'mail' | 'rcpt' | 'data' | 'body' | 'rset' | 'quit' | 'send' | 'read';
+/** Constructor details for {@link SMTPError}. */
 type SMTPErrorOptions = {
     stage: SMTPStage;
     command?: string;
     response?: string;
     cause?: unknown;
 };
+/** Error thrown when an SMTP command or socket stage fails. */
 declare class SMTPError extends Error {
+    /** SMTP stage where the failure happened. */
     readonly stage: SMTPStage;
+    /** SMTP command active when the failure happened, when available. */
     readonly command?: string;
+    /** Raw SMTP response line associated with the failure. */
     readonly response?: string;
+    /** Three-digit SMTP response code parsed from {@link response}. */
     readonly responseCode?: number;
+    /** Enhanced status code parsed from {@link response}. */
     readonly enhancedStatusCode?: string;
+    /** Whether the response code is a transient 4xx failure. */
     readonly transient: boolean;
     readonly cause?: unknown;
+    /** Creates a structured SMTP error. */
     constructor(message: string, options: SMTPErrorOptions);
 }
+/** SMTP client configuration shared by Cloudflare and Deno runtimes. */
 type EdgeMailerOptions = {
     host: string;
     port: number;
@@ -200,11 +259,13 @@ type EdgeMailerOptions = {
     socketTimeoutMs?: number;
     responseTimeoutMs?: number;
 };
+/** Connection-pool limits for repeated SMTP sends. */
 type SmtpPoolOptions = {
     maxConnections?: number;
     maxMessagesPerConnection?: number;
     idleTimeoutMs?: number;
 };
+/** Runtime-neutral SMTP session implementation used by runtime mailers. */
 declare class SmtpMailer {
     private readonly connector;
     private readonly host;
@@ -240,9 +301,13 @@ declare class SmtpMailer {
     private supportsStartTls;
     private supportsPipelining;
     protected constructor(options: EdgeMailerOptions, connector: EdgeSocketConnector, runtimeName?: string);
+    /** Sends one message over the active SMTP session. */
     send(options: EmailOptions): Promise<SmtpSendReceipt>;
+    /** Sends messages sequentially over the active SMTP session. */
     sendMany(emails: EmailOptions[], options?: BatchSendOptions): Promise<BatchSendResult>;
+    /** Closes the SMTP socket and rejects any queued sends. */
     close(error?: Error): Promise<void>;
+    /** Returns whether the SMTP session is open and usable. */
     isActive(): boolean;
     protected initializeSmtpSession(): Promise<void>;
     private sendEmail;
@@ -291,6 +356,7 @@ declare class SmtpMailer {
     private getSocket;
 }
 
+/** Bounded SMTP connection pool for reusing runtime mailer sessions. */
 declare class SmtpConnectionPool<TMailer extends SmtpMailer> {
     private readonly options;
     private readonly connectMailer;
@@ -305,8 +371,11 @@ declare class SmtpConnectionPool<TMailer extends SmtpMailer> {
     private totalConnections;
     private closed;
     constructor(options: EdgeMailerOptions, connectMailer: (options: EdgeMailerOptions) => Promise<TMailer>);
+    /** Sends one message through an acquired SMTP session. */
     send(email: Parameters<TMailer['send']>[0]): Promise<SmtpSendReceipt>;
+    /** Sends messages sequentially through the pool. */
     sendMany(emails: Parameters<TMailer['send']>[0][], options?: BatchSendOptions): Promise<BatchSendResult>;
+    /** Closes all pooled SMTP sessions and rejects queued sends. */
     close(): Promise<void>;
     private acquire;
     private release;

package/dist/{pool-CcxclJQJ.d.ts → pool-Db8Z1fqb.d.ts}

@@ -1,8 +1,11 @@
+/** Encodes non-ASCII header text using RFC 2047 quoted-printable words. */
 declare function encodeHeader(text: string): string;
+/** Email address with an optional display name. */
 type User = {
     name?: string;
     email: string;
 };
+/** SMTP delivery status notification options. */
 type DsnOptions = {
     envelopeId?: string;
     RET?: {
@@ -17,7 +20,9 @@ type DsnOptions = {
     };
     ORCPT?: string;
 };
+/** SMTP MAIL FROM BODY parameter value. */
 type MailBodyType = '7BIT' | '8BITMIME';
+/** SMTP envelope overrides used for MAIL FROM and RCPT TO commands. */
 type MailEnvelopeOptions = {
     from?: string;
     to?: string | string[];
@@ -26,9 +31,13 @@ type MailEnvelopeOptions = {
     smtpUtf8?: boolean;
     requireTls?: boolean;
 };
+/** MIME content-transfer-encoding for an attachment body. */
 type AttachmentEncoding = 'base64' | 'quoted-printable' | '7bit';
+/** MIME content disposition for attachment parts. */
 type AttachmentDisposition = 'attachment' | 'inline';
+/** Supported attachment content inputs. */
 type EmailAttachmentContent = string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob;
+/** File or inline part to include in the generated MIME message. */
 type EmailAttachment = {
     filename: string;
     content: EmailAttachmentContent;
@@ -38,6 +47,7 @@ type EmailAttachment = {
     contentId?: string;
     disposition?: AttachmentDisposition;
 };
+/** High-level email message options accepted by mailer send methods. */
 type EmailOptions = {
     from: string | User;
     to: string | string[] | User | User[];
@@ -52,28 +62,47 @@ type EmailOptions = {
     envelope?: MailEnvelopeOptions;
     dsnOverride?: DsnOptions;
 };
+/** Builds MIME email messages and SMTP DATA payloads from {@link EmailOptions}. */
 declare class Email {
+    /** Sender address used for MIME From and default envelope sender. */
     readonly from: User;
+    /** Primary recipients emitted in the MIME To header. */
     readonly to: User[];
+    /** Reply-To address. */
     readonly reply?: User;
+    /** Carbon-copy recipients emitted in the MIME Cc header. */
     readonly cc?: User[];
+    /** Blind-copy recipients used for envelope delivery only. */
     readonly bcc?: User[];
+    /** MIME Subject header value. */
     readonly subject: string;
+    /** Plain text body. */
     readonly text?: string;
+    /** HTML body. */
     readonly html?: string;
+    /** SMTP envelope overrides. */
     readonly envelope?: Omit<MailEnvelopeOptions, 'to'> & {
         to?: string[];
     };
+    /** Per-message DSN overrides. */
     readonly dsnOverride?: DsnOptions;
+    /** Attachments and inline content parts. */
     readonly attachments?: EmailAttachment[];
+    /** Custom MIME headers. */
     readonly headers: Record<string, string>;
+    /** Marks this email as sent for callers tracking queued send state. */
     setSent: () => void;
+    /** Marks this email as failed for callers tracking queued send state. */
     setSentError: (e: unknown) => void;
+    /** Resolves when the email has been sent by a mailer. */
     sent: Promise<void>;
+    /** Creates a MIME message builder from high-level email options. */
     constructor(options: EmailOptions);
     private static toUsers;
     private static toEnvelopeRecipients;
+    /** Returns MIME message data without SMTP dot-stuffing. */
     getMessageData(): string;
+    /** Returns MIME message data, resolving Blob attachment content first. */
     getMessageDataAsync(): Promise<string>;
     private buildMessageData;
     private resolveAttachments;
@@ -87,8 +116,11 @@ declare class Email {
     private bytesToWrappedBase64;
     private bytesToBase64;
     private wrapBase64;
+    /** Returns SMTP DATA payload with dot-stuffing and final terminator. */
     getEmailData(): string;
+    /** Returns SMTP DATA payload after resolving async attachment content. */
     getEmailDataAsync(): Promise<string>;
+    /** Dot-stuffs MIME data and appends the SMTP DATA terminator. */
     static toSmtpData(data: string): string;
     private static applyDotStuffing;
     private generateSafeBoundary;
@@ -101,15 +133,19 @@ declare class Email {
     private resolveCC;
 }
 
+/** DKIM signing options for RSA-SHA256 signatures. */
 type DkimConfig = {
     domainName: string;
     keySelector: string;
     privateKey: string;
     headerFieldNames?: string[];
 };
+/** Validates DKIM configuration before message signing. */
 declare function validateDkimConfig(dkim: DkimConfig | undefined): void;
+/** Returns a MIME message prefixed with a DKIM-Signature header. */
 declare function signDkimMessage(message: string, dkim: DkimConfig): Promise<string>;
 
+/** Verbosity levels for SMTP client logging. */
 declare enum LogLevel {
     DEBUG = 0,
     INFO = 1,
@@ -118,7 +154,9 @@ declare enum LogLevel {
     NONE = 4
 }
 
+/** TLS mode requested from a runtime socket adapter. */
 type SocketTlsMode = 'off' | 'on' | 'starttls';
+/** Minimal readable/writable socket contract used by the SMTP core. */
 type EdgeSocket = {
     readable: ReadableStream<Uint8Array>;
     writable: WritableStream<Uint8Array>;
@@ -127,24 +165,30 @@ type EdgeSocket = {
     close(reason?: unknown): Promise<void> | void;
     startTls?(): EdgeSocket | Promise<EdgeSocket>;
 };
+/** Runtime socket connection request. */
 type EdgeSocketConnectOptions = {
     hostname: string;
     port: number;
     tls: SocketTlsMode;
     signal?: AbortSignal;
 };
+/** Runtime adapter that opens SMTP TCP/TLS sockets. */
 type EdgeSocketConnector = {
     connect(options: EdgeSocketConnectOptions): EdgeSocket | Promise<EdgeSocket>;
 };
 
+/** SMTP authentication mechanisms supported by the shared SMTP client. */
 type AuthType = 'plain' | 'login' | 'cram-md5';
+/** Username and password used for SMTP AUTH. */
 type Credentials = {
     username: string;
     password: string;
 };
+/** Controls ordered batch behavior when one message fails. */
 type BatchSendOptions = {
     continueOnError?: boolean;
 };
+/** Recipient rejected by the SMTP server during the envelope phase. */
 type SmtpRejectedRecipient = {
     recipient: string;
     response: string;
@@ -152,6 +196,7 @@ type SmtpRejectedRecipient = {
     enhancedStatusCode?: string;
     transient: boolean;
 };
+/** Structured receipt returned after an SMTP DATA transaction completes. */
 type SmtpSendReceipt = {
     messageId: string;
     envelope: {
@@ -165,26 +210,40 @@ type SmtpSendReceipt = {
     enhancedStatusCode?: string;
     size: number;
 };
+/** Ordered result list returned by `sendBatch()` and `sendMany()`. */
 type BatchSendResult = PromiseSettledResult<SmtpSendReceipt>[];
+/** SMTP PIPELINING behavior. */
 type PipeliningMode = 'auto' | false;
+/** SMTP message body encoding advertised in MAIL FROM. */
 type SmtpBodyType = '7BIT' | '8BITMIME';
+/** Protocol stage attached to structured SMTP errors. */
 type SMTPStage = 'connect' | 'greet' | 'ehlo' | 'helo' | 'starttls' | 'auth' | 'mail' | 'rcpt' | 'data' | 'body' | 'rset' | 'quit' | 'send' | 'read';
+/** Constructor details for {@link SMTPError}. */
 type SMTPErrorOptions = {
     stage: SMTPStage;
     command?: string;
     response?: string;
     cause?: unknown;
 };
+/** Error thrown when an SMTP command or socket stage fails. */
 declare class SMTPError extends Error {
+    /** SMTP stage where the failure happened. */
     readonly stage: SMTPStage;
+    /** SMTP command active when the failure happened, when available. */
     readonly command?: string;
+    /** Raw SMTP response line associated with the failure. */
     readonly response?: string;
+    /** Three-digit SMTP response code parsed from {@link response}. */
     readonly responseCode?: number;
+    /** Enhanced status code parsed from {@link response}. */
     readonly enhancedStatusCode?: string;
+    /** Whether the response code is a transient 4xx failure. */
     readonly transient: boolean;
     readonly cause?: unknown;
+    /** Creates a structured SMTP error. */
     constructor(message: string, options: SMTPErrorOptions);
 }
+/** SMTP client configuration shared by Cloudflare and Deno runtimes. */
 type EdgeMailerOptions = {
     host: string;
     port: number;
@@ -200,11 +259,13 @@ type EdgeMailerOptions = {
     socketTimeoutMs?: number;
     responseTimeoutMs?: number;
 };
+/** Connection-pool limits for repeated SMTP sends. */
 type SmtpPoolOptions = {
     maxConnections?: number;
     maxMessagesPerConnection?: number;
     idleTimeoutMs?: number;
 };
+/** Runtime-neutral SMTP session implementation used by runtime mailers. */
 declare class SmtpMailer {
     private readonly connector;
     private readonly host;
@@ -240,9 +301,13 @@ declare class SmtpMailer {
     private supportsStartTls;
     private supportsPipelining;
     protected constructor(options: EdgeMailerOptions, connector: EdgeSocketConnector, runtimeName?: string);
+    /** Sends one message over the active SMTP session. */
     send(options: EmailOptions): Promise<SmtpSendReceipt>;
+    /** Sends messages sequentially over the active SMTP session. */
     sendMany(emails: EmailOptions[], options?: BatchSendOptions): Promise<BatchSendResult>;
+    /** Closes the SMTP socket and rejects any queued sends. */
     close(error?: Error): Promise<void>;
+    /** Returns whether the SMTP session is open and usable. */
     isActive(): boolean;
     protected initializeSmtpSession(): Promise<void>;
     private sendEmail;
@@ -291,6 +356,7 @@ declare class SmtpMailer {
     private getSocket;
 }
 
+/** Bounded SMTP connection pool for reusing runtime mailer sessions. */
 declare class SmtpConnectionPool<TMailer extends SmtpMailer> {
     private readonly options;
     private readonly connectMailer;
@@ -305,8 +371,11 @@ declare class SmtpConnectionPool<TMailer extends SmtpMailer> {
     private totalConnections;
     private closed;
     constructor(options: EdgeMailerOptions, connectMailer: (options: EdgeMailerOptions) => Promise<TMailer>);
+    /** Sends one message through an acquired SMTP session. */
     send(email: Parameters<TMailer['send']>[0]): Promise<SmtpSendReceipt>;
+    /** Sends messages sequentially through the pool. */
     sendMany(emails: Parameters<TMailer['send']>[0][], options?: BatchSendOptions): Promise<BatchSendResult>;
+    /** Closes all pooled SMTP sessions and rejects queued sends. */
     close(): Promise<void>;
     private acquire;
     private release;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edge-mailer",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "SMTP submission toolkit for edge and serverless runtimes.",
   "license": "MIT",
   "author": "sparticle9 <201596840+sparticle9@users.noreply.github.com>",