ts-mailkit 0.1.0 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@ Works seamlessly in **Node.js**, **Cloudflare Workers** (`workerd`), **Bun**, **
 
 - **Type-Safe DTOs**: Strongly-typed Data Transfer Objects for transactional emails (verification, password reset, 2FA, magic links, newsletters).
 - **Pluggable Transports (`IEmailSender`)**: Decoupled transport adapter interface with built-in senders:
-  - `ZeptoMailSender` (Zoho Mail transactional API via native `fetch`).
+  - `ZeptoMailHttpSender` (Zoho Mail transactional API via native `fetch`).
   - `MemoryEmailSender` (In-memory mock transport for unit and integration testing).
   - `ConsoleEmailSender` (Formatted terminal logger for local development).
 - **Zero Runtime Dependencies**: Core uses standard web APIs (global `fetch`), ensuring zero heavy dependencies and complete edge compatibility.
@@ -18,7 +18,11 @@ Works seamlessly in **Node.js**, **Cloudflare Workers** (`workerd`), **Bun**, **
   1. DTO schema and validation.
   2. Template building and responsive HTML rendering.
   3. Dispatch via the chosen transport adapter.
-- **Multitenant & Dynamic Branding**: Configure global branding or pass a dynamic brand name resolver for multi-tenant applications.
+- **Multitenant & Dynamic Branding**: Configure global branding, top-center logos, or pass a dynamic brand name resolver for multi-tenant applications.
+- **Top-Center Brand Logo**: Display your brand or company logo top-center with automatic HTTP(S) URL validation.
+- **Auto Plain-Text Fallbacks**: When sending custom or raw HTML, accessible plain-text equivalents are cleanly generated automatically if not explicitly provided.
+- **RFC 5322 Address Parser**: Optional utility to safely parse `"Display Name <email@example.com>"` strings into structured address objects.
+- **Template Preview**: Inspect [`demo-newsletter.html`](demo-newsletter.html) directly in the root folder to view the responsive default email template before installing.
 - **Dual ESM & CommonJS**: Full support for `import` and `require` with first-class TypeScript declaration maps.
 
 ---
@@ -48,10 +52,10 @@ bun add ts-mailkit
 ### 1. Initialize Transport & Client
 
 ```ts
-import { createMailKit, ZeptoMailSender, EmailTemplateFactory } from 'ts-mailkit';
+import { createMailKit, ZeptoMailHttpSender, EmailTemplateFactory } from 'ts-mailkit';
 
 // Configure the Zoho ZeptoMail HTTP transport
-const transport = new ZeptoMailSender({
+const transport = new ZeptoMailHttpSender({
   apiToken: process.env.ZEPTO_MAIL_TOKEN!,
   apiHost: 'api.zeptomail.com', // or 'api.zeptomail.eu', 'api.zeptomail.in'
   from: { address: 'noreply@yourdomain.com', name: 'Acme App' },
@@ -137,6 +141,7 @@ You can instantiate `EmailTemplateFactory` with brand-level defaults:
 ```ts
 const tenantFactory = new EmailTemplateFactory({
   brandName: 'St. Patrick High School',
+  logoUrl: 'https://school.edu/assets/logo.png',
   securityMessage: 'If you did not make this request, contact our school IT administration immediately.',
   footer: (brand) => `© ${new Date().getFullYear()} ${brand}. Authorized educational portal.`,
 });
@@ -198,14 +203,14 @@ describe('User Registration Email', () => {
 
 ### 4. Sending Raw Emails (No Template DTO)
 
-For custom HTML or plain-text messages:
+For custom HTML or plain-text messages. When `text` is omitted, an accessible plain-text fallback is automatically extracted from the `html`:
 
 ```ts
 await mailer.sendRaw({
   to: [{ address: 'support@example.com', name: 'Support Team' }],
   subject: 'Urgent System Alert',
   html: '<h1>System Alert</h1><p>Database failover completed successfully.</p>',
-  text: 'System Alert: Database failover completed successfully.',
+  // text is optional — auto-converted from html if omitted
   attachments: [
     {
       filename: 'report.txt',
@@ -216,7 +221,21 @@ await mailer.sendRaw({
 });
 ```
 
-### 5. Pluggable Transports (`IEmailSender`)
+### 5. Parsing RFC 5322 Email Addresses
+
+If your application receives combined address strings like `"Jane Doe <jane@example.com>"`, use the standalone, tree-shakeable `parseEmailAddress` helper:
+
+```ts
+import { parseEmailAddress } from 'ts-mailkit';
+
+const recipient = parseEmailAddress('Jane Doe <jane@example.com>');
+// => { address: 'jane@example.com', name: 'Jane Doe' }
+
+const simple = parseEmailAddress('jane@example.com');
+// => { address: 'jane@example.com' }
+```
+
+### 6. Pluggable Transports (`IEmailSender`)
 
 You can implement custom transports (e.g. SMTP, Resend, SendGrid, Postmark) by satisfying the `IEmailSender` interface:
 
@@ -238,6 +257,14 @@ export class CustomSmtpSender implements IEmailSender {
 
 ---
 
+## Template Preview
+
+You can inspect what the default responsive email template looks like without writing code or installing the library:
+
+- 📄 **[demo-newsletter.html](demo-newsletter.html)** &mdash; Standalone, fully pre-rendered HTML newsletter showcasing top-center brand logo, hero banner, typography, call-to-action button, and footer. Generated automatically during the test suite.
+
+---
+
 ## Development & Testing
 
 ```bash
@@ -259,6 +286,23 @@ pnpm run prepublishOnly
 
 ---
 
+## Deprecated API (Scheduled for Removal in v1.0.0)
+
+The following legacy migration bridges and aliases are marked `@deprecated` and scheduled for removal in `v1.0.0`:
+
+| Deprecated | Replacement | Notes |
+| :--- | :--- | :--- |
+| `ZeptoMailSender` | `ZeptoMailHttpSender` | Renamed to explicitly signify HTTP transport adapter. |
+| `ZeptoMailConfig` | `ZeptoMailHttpConfig` | Configuration interface rename. |
+| `sender.sendEmail(...)` | `sender.send({ to, subject, html, text, ... })` | Standardized on `SendMailOptions`. |
+| `mailer.send(to, template, toName)` | `mailer.send({ to, template, ... })` | Use the type-safe options object. |
+| `mailer.sendSimpleMessage(...)` | `mailer.sendRaw({ to, subject, text, html })` | Direct raw email dispatch. |
+| `mailer.buildPlainTextMessage(template)` | `mailer.render(template)` or `buildPlainText(dto)` | Standalone or client renderer methods. |
+| `EmailService` | `MailKit` | Main client class. |
+| `BaseEmailDto` | `EmailTemplateDto` | Core DTO interface. |
+
+---
+
 ## License
 
 [MIT](LICENSE)

package/dist/core/client.d.ts

@@ -1,6 +1,6 @@
 import type { IEmailSender } from '../transports/sender.interface.js';
 import type { IEmailRenderer, RenderedEmail } from '../renderers/renderer.interface.js';
-import type { BaseEmailDto } from '../templates/dto/index.js';
+import type { EmailTemplateDto } from '../templates/dto/index.js';
 import { type Recipient, type SendMailOptions, type SendResult } from './types.js';
 export interface SendTemplateOptions {
     /**
@@ -10,7 +10,7 @@ export interface SendTemplateOptions {
     /**
      * Templated email DTO to render and send.
      */
-    template: BaseEmailDto;
+    template: EmailTemplateDto;
     /**
      * Optional recipient display name (used when `to` is a plain string).
      */
@@ -54,7 +54,7 @@ export interface SendTemplateOptions {
 }
 export interface MailKitOptions {
     /**
-     * The transport adapter used to dispatch emails (e.g. ZeptoMailSender, MemoryEmailSender).
+     * The transport adapter used to dispatch emails (e.g. ZeptoMailHttpSender, MemoryEmailSender).
      */
     transport: IEmailSender;
     /**
@@ -92,37 +92,50 @@ export declare class MailKit {
     /**
      * Renders an email DTO to HTML and plain text without dispatching.
      */
-    render(template: BaseEmailDto): Promise<RenderedEmail>;
+    render(template: EmailTemplateDto): Promise<RenderedEmail>;
     /**
-     * Returns the plain-text fallback for an email DTO without sending.
+     * Legacy positional send signature for backwards compatibility with 0.1.x:
+     * `send(to: string, template: EmailTemplateDto, toName?: string): Promise<SendResult>`
+     *
+     * @deprecated Use `send({ to, template, ... })` instead. This overload will be removed in v1.0.0.
      */
-    buildPlainTextMessage(template: BaseEmailDto): string;
+    send(to: string, template: EmailTemplateDto, toName?: string): Promise<SendResult>;
     /**
      * Sends an email using a strongly-typed template DTO.
-     * Supports both modern options object:
-     *   `mailer.send({ to: 'user@example.com', template: myDto })`
-     * and legacy positional arguments for seamless migration:
-     *   `mailer.send('user@example.com', myDto, 'User Name')`
+     *
+     * Example:
+     * ```ts
+     * await mailer.send({
+     *   to: 'user@example.com',
+     *   template: myDto,
+     * });
+     * ```
      */
     send(options: SendTemplateOptions): Promise<SendResult>;
-    send(to: string, template: BaseEmailDto, toName?: string): Promise<SendResult>;
     /**
      * Dispatches a raw, pre-rendered email directly through the transport.
+     * If `options.text` is omitted, plain text is automatically derived from `options.html`.
      */
     sendRaw(options: SendMailOptions): Promise<SendResult>;
     /**
-     * Sends a raw plain-text email with basic HTML pre-formatting.
-     * Useful for plain notifications, alerts, or simple text messages.
+     * Helper method matching legacy 0.1.x `sendSimpleMessage(to, subject, text, fromName?)`.
+     * @deprecated Use `sendRaw({ to, subject, text, ... })` instead. This method will be removed in v1.0.0.
      */
-    sendSimpleMessage(to: string, subject: string, text: string, toName?: string): Promise<SendResult>;
+    sendSimpleMessage(to: string, subject: string, text: string, fromName?: string): Promise<SendResult>;
+    /**
+     * Legacy helper method to construct plain text from a template.
+     * @deprecated Use `render(template)` or `buildPlainText(dto)` instead. This method will be removed in v1.0.0.
+     */
+    buildPlainTextMessage(template: EmailTemplateDto): string;
 }
-/**
- * Drop-in alias for MailKit to maintain compatibility with existing EmailService code.
- */
-export declare const EmailService: typeof MailKit;
-export type EmailService = MailKit;
 /**
  * Convenience factory to create a MailKit client instance.
  */
 export declare function createMailKit(options: MailKitOptions): MailKit;
+/**
+ * Backward-compatibility alias for `MailKit`.
+ * @deprecated Use `MailKit` instead. This alias will be removed in v1.0.0.
+ */
+export declare const EmailService: typeof MailKit;
+export type EmailService = MailKit;
 //# sourceMappingURL=client.d.ts.map

package/dist/core/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAExF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,EAAE,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC5B;;OAEG;IACH,QAAQ,EAAE,YAAY,CAAC;IACvB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC7B;;OAEG;IACH,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC9B;;OAEG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAClC;;OAEG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC,aAAa,CAAC,CAAC;IAC7C;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,SAAS,EAAE,YAAY,CAAC;IACxB;;OAEG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;CACpD;AAED;;GAEG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAY;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAiC;gBAExD,OAAO,EAAE,cAAc;IAWnC;;OAEG;IACH,YAAY,IAAI,YAAY;IAI5B;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAI5D;;OAEG;IACH,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM;IAIrD;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;IACvD,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAoEpF;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAQ5D;;;OAGG;IACG,iBAAiB,CACrB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,MAAW,GAClB,OAAO,CAAC,UAAU,CAAC;CASvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,gBAAU,CAAC;AACpC,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC;AAEnC;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAE9D"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"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"}

package/dist/core/types.d.ts

@@ -14,6 +14,14 @@ export type Recipient = string | EmailAddress | {
     email: string;
     name?: string;
 };
+/**
+ * Parses an RFC 5322 formatted address string into an EmailAddress.
+ * Supports formats such as:
+ * - "user@example.com" -> { address: "user@example.com" }
+ * - "Sender Name <sender@example.com>" -> { name: "Sender Name", address: "sender@example.com" }
+ * - "\"Sender Name\" <sender@example.com>" -> { name: "Sender Name", address: "sender@example.com" }
+ */
+export declare function parseEmailAddress(input: string): EmailAddress;
 /**
  * Normalizes a Recipient value into a standardized EmailAddress.
  */

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,YAAY,GACZ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,YAAY,CAcrE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,GACnC,YAAY,EAAE,CAIhB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC7B,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAClC,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,YAAY,GACZ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAa7D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,YAAY,CAcrE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,GACnC,YAAY,EAAE,CAIhB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC7B,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAClC,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/index.cjs

@@ -30,18 +30,35 @@ __export(index_exports, {
   MemoryEmailSender: () => MemoryEmailSender,
   TemplateError: () => TemplateError,
   TransportError: () => TransportError,
+  ZeptoMailHttpSender: () => ZeptoMailHttpSender,
   ZeptoMailSender: () => ZeptoMailSender,
   buildHtml: () => buildHtml,
   buildPlainText: () => buildPlainText,
   createMailKit: () => createMailKit,
   decodeHtmlEntities: () => decodeHtmlEntities,
   htmlToPlainText: () => htmlToPlainText,
+  isValidHttpUrl: () => isValidHttpUrl,
   normalizeRecipient: () => normalizeRecipient,
-  normalizeRecipients: () => normalizeRecipients
+  normalizeRecipients: () => normalizeRecipients,
+  parseEmailAddress: () => parseEmailAddress
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/core/types.ts
+function parseEmailAddress(input) {
+  if (!input || typeof input !== "string") {
+    return { address: "" };
+  }
+  const trimmed = input.trim();
+  const match = trimmed.match(/^(?:["']?([^"']+)["']?\s+)?<?([^\s<>@]+@[^\s<>@]+)>?$/);
+  if (!match) {
+    return { address: trimmed };
+  }
+  return {
+    address: match[2].trim(),
+    name: match[1]?.trim() || void 0
+  };
+}
 function normalizeRecipient(recipient) {
   if (typeof recipient === "string") {
     return { address: recipient.trim() };
@@ -113,6 +130,15 @@ function htmlToPlainText(html) {
 }
 
 // src/renderers/default/default-renderer.ts
+function isValidHttpUrl(urlString) {
+  if (!urlString || typeof urlString !== "string") return false;
+  try {
+    const url = new URL(urlString.trim());
+    return (url.protocol === "http:" || url.protocol === "https:") && url.hostname.length > 0;
+  } catch {
+    return false;
+  }
+}
 function buildPlainText(dto) {
   if (dto.noHtmlMessage) {
     return dto.noHtmlMessage;
@@ -155,6 +181,15 @@ function buildHtml(dto, options = {}) {
     `<body style="margin:0;padding:24px 16px;background-color:#f9fafb;font-family:${fontFamily};color:#1f2937;line-height:1.6;">`,
     `<div style="max-width:${maxWidth};margin:0 auto;background-color:#ffffff;padding:32px 28px;border-radius:8px;box-shadow:0 1px 3px rgba(0,0,0,0.1);border:1px solid #f3f4f6;">`
   ];
+  const logoCandidate = dto.logoUrl ?? options.logoUrl;
+  if (logoCandidate && isValidHttpUrl(logoCandidate)) {
+    const validLogo = logoCandidate.trim();
+    parts.push(
+      `<div style="margin-bottom:24px;text-align:center;">`,
+      `  <img src="${validLogo}" alt="${dto.fromName || "Logo"}" style="max-height:48px;max-width:200px;height:auto;width:auto;display:inline-block;border:0;outline:none;text-decoration:none;" />`,
+      `</div>`
+    );
+  }
   if (dto.imageUrl) {
     parts.push(
       `<div style="margin-bottom:24px;text-align:center;">`,
@@ -239,29 +274,15 @@ var MailKit = class {
   async render(template) {
     return await this.renderer.render(template);
   }
-  /**
-   * Returns the plain-text fallback for an email DTO without sending.
-   */
-  buildPlainTextMessage(template) {
-    return template.noHtmlMessage ?? buildPlainText(template);
-  }
-  async send(optionsOrTo, maybeTemplate, maybeToName) {
-    let opts;
-    if (typeof optionsOrTo === "string") {
-      if (!maybeTemplate) {
-        throw new ConfigurationError("MailKit.send: Missing required template DTO argument.");
-      }
-      opts = {
-        to: optionsOrTo,
-        template: maybeTemplate,
-        toName: maybeToName
-      };
-    } else {
-      opts = optionsOrTo;
-    }
-    const template = opts.template;
-    const recipientName = opts.toName ?? template.userName;
-    let resolvedFromName = opts.fromName ?? template.fromName;
+  async send(toOrOptions, maybeTemplate, maybeToName) {
+    const options = typeof toOrOptions === "string" ? {
+      to: toOrOptions,
+      template: maybeTemplate,
+      toName: maybeToName
+    } : toOrOptions;
+    const template = options.template;
+    const recipientName = options.toName ?? template.userName;
+    let resolvedFromName = options.fromName ?? template.fromName;
     if (!resolvedFromName && this.brandNameResolver) {
       resolvedFromName = await this.brandNameResolver();
     }
@@ -271,12 +292,12 @@ var MailKit = class {
     const rendered = await this.renderer.render(template);
     const plaintextBody = template.noHtmlMessage ?? rendered.text;
     let toRecipients;
-    if (typeof opts.to === "string" && recipientName) {
-      toRecipients = { address: opts.to, name: recipientName };
+    if (typeof options.to === "string" && recipientName) {
+      toRecipients = { address: options.to, name: recipientName };
     } else {
-      toRecipients = opts.to;
+      toRecipients = options.to;
     }
-    let from = opts.from ?? this.defaultFrom;
+    let from = options.from ?? this.defaultFrom;
     if (resolvedFromName && from) {
       const normalizedFrom = normalizeRecipient(from);
       from = { address: normalizedFrom.address, name: resolvedFromName };
@@ -287,46 +308,56 @@ var MailKit = class {
       subject: template.subject,
       html: rendered.html,
       text: plaintextBody,
-      cc: opts.cc,
-      bcc: opts.bcc,
-      replyTo: opts.replyTo,
-      attachments: opts.attachments,
-      headers: opts.headers,
-      tags: opts.tags,
-      metadata: opts.metadata
+      cc: options.cc,
+      bcc: options.bcc,
+      replyTo: options.replyTo,
+      attachments: options.attachments,
+      headers: options.headers,
+      tags: options.tags,
+      metadata: options.metadata
     });
   }
   /**
    * Dispatches a raw, pre-rendered email directly through the transport.
+   * If `options.text` is omitted, plain text is automatically derived from `options.html`.
    */
   async sendRaw(options) {
     const from = options.from ?? this.defaultFrom;
+    const text = options.text ?? (options.html ? htmlToPlainText(options.html) : void 0);
     return await this.transport.send({
       ...options,
-      from
+      from,
+      text
     });
   }
   /**
-   * Sends a raw plain-text email with basic HTML pre-formatting.
-   * Useful for plain notifications, alerts, or simple text messages.
+   * Helper method matching legacy 0.1.x `sendSimpleMessage(to, subject, text, fromName?)`.
+   * @deprecated Use `sendRaw({ to, subject, text, ... })` instead. This method will be removed in v1.0.0.
    */
-  async sendSimpleMessage(to, subject, text, toName = "") {
-    const html = `<pre style="font-family:monospace;white-space:pre-wrap;">${text}</pre>`;
+  async sendSimpleMessage(to, subject, text, fromName) {
     return await this.sendRaw({
-      to: { address: to, name: toName },
+      to,
       subject,
-      html,
-      text
+      text,
+      html: `<pre style="font-family:monospace;white-space:pre-wrap;">${text}</pre>`,
+      from: fromName && this.defaultFrom ? { address: normalizeRecipient(this.defaultFrom).address, name: fromName } : this.defaultFrom
     });
   }
+  /**
+   * Legacy helper method to construct plain text from a template.
+   * @deprecated Use `render(template)` or `buildPlainText(dto)` instead. This method will be removed in v1.0.0.
+   */
+  buildPlainTextMessage(template) {
+    return template.noHtmlMessage ?? buildPlainText(template);
+  }
 };
-var EmailService = MailKit;
 function createMailKit(options) {
   return new MailKit(options);
 }
+var EmailService = MailKit;
 
 // src/transports/zeptomail/zeptomail-sender.ts
-var ZeptoMailSender = class {
+var ZeptoMailHttpSender = class {
   name = "zeptomail";
   apiUrl;
   authHeader;
@@ -334,10 +365,10 @@ var ZeptoMailSender = class {
   fetchImpl;
   constructor(config) {
     if (!config.apiToken || typeof config.apiToken !== "string") {
-      throw new ConfigurationError("ZeptoMailSender: Missing or invalid apiToken.");
+      throw new ConfigurationError("ZeptoMailHttpSender: Missing or invalid apiToken.");
     }
     if (!config.from) {
-      throw new ConfigurationError("ZeptoMailSender: Missing required default from address.");
+      throw new ConfigurationError("ZeptoMailHttpSender: Missing required default from address.");
     }
     const host = (config.apiHost || "api.zeptomail.com").replace(/^https?:\/\//, "").replace(/\/+$/, "");
     this.apiUrl = `https://${host}/v1.1/email`;
@@ -345,12 +376,12 @@ var ZeptoMailSender = class {
     this.authHeader = token.startsWith("Zoho-") ? token : `Zoho-enczapikey ${token}`;
     this.defaultFrom = normalizeRecipient(config.from);
     if (!this.defaultFrom.address) {
-      throw new ConfigurationError("ZeptoMailSender: Configured from address must not be empty.");
+      throw new ConfigurationError("ZeptoMailHttpSender: Configured from address must not be empty.");
     }
     this.fetchImpl = config.fetch ?? globalThis.fetch;
     if (typeof this.fetchImpl !== "function") {
       throw new ConfigurationError(
-        "ZeptoMailSender: No global fetch implementation found. Pass a custom fetch to ZeptoMailConfig if running on Node < 18."
+        "ZeptoMailHttpSender: No global fetch implementation found. Pass a custom fetch to ZeptoMailHttpConfig if running on Node < 18."
       );
     }
   }
@@ -360,7 +391,7 @@ var ZeptoMailSender = class {
   async send(options) {
     const toRecipients = normalizeRecipients(options.to);
     if (toRecipients.length === 0) {
-      throw new TransportError("ZeptoMailSender: At least one recipient (to) must be specified.", {
+      throw new TransportError("ZeptoMailHttpSender: At least one recipient (to) must be specified.", {
         transportName: this.name
       });
     }
@@ -442,7 +473,7 @@ var ZeptoMailSender = class {
         body: JSON.stringify(payload)
       });
     } catch (err) {
-      throw new TransportError(`ZeptoMailSender: Network request failed: ${err instanceof Error ? err.message : String(err)}`, {
+      throw new TransportError(`ZeptoMailHttpSender: Network request failed: ${err instanceof Error ? err.message : String(err)}`, {
         transportName: this.name,
         cause: err
       });
@@ -456,7 +487,7 @@ var ZeptoMailSender = class {
     }
     if (!response.ok) {
       const errorMessage = responseData?.error?.message || responseData?.message || `HTTP ${response.status}: ${responseText || response.statusText}`;
-      throw new TransportError(`ZeptoMailSender: Failed to send email - ${errorMessage}`, {
+      throw new TransportError(`ZeptoMailHttpSender: Failed to send email - ${errorMessage}`, {
         transportName: this.name,
         statusCode: response.status,
         responseBody: responseText
@@ -472,6 +503,7 @@ var ZeptoMailSender = class {
   /**
    * Backward-compatible helper method matching legacy signature:
    * `sendEmail(to, htmlBody, subject, toName?, plaintextBody?, fromName?)`
+   * @deprecated Use `send({ to, subject, html, text, ... })` instead. This method will be removed in v1.0.0.
    */
   async sendEmail(to, htmlBody, subject, toName = "", plaintextBody, fromName) {
     await this.send({
@@ -483,6 +515,7 @@ var ZeptoMailSender = class {
     });
   }
 };
+var ZeptoMailSender = ZeptoMailHttpSender;
 
 // src/transports/memory/memory-sender.ts
 var MemoryEmailSender = class {
@@ -581,9 +614,11 @@ var EmailTemplateFactory = class _EmailTemplateFactory {
   defaultBrandName;
   defaultSecurityMessage;
   footerResolver;
+  defaultLogoUrl;
   constructor(config = {}) {
     this.defaultBrandName = config.brandName || "Application";
     this.defaultSecurityMessage = config.securityMessage || DEFAULT_SECURITY_MESSAGE;
+    this.defaultLogoUrl = config.logoUrl;
     if (typeof config.footer === "function") {
       this.footerResolver = config.footer;
     } else if (typeof config.footer === "string") {
@@ -609,6 +644,7 @@ var EmailTemplateFactory = class _EmailTemplateFactory {
       subject: "Verify Your Email Address",
       header: `Welcome to ${brand}!`,
       body,
+      logoUrl: this.defaultLogoUrl,
       otpCode: otp,
       actionUrl: verificationUrl,
       actionText: "Verify Email",
@@ -637,6 +673,7 @@ Your OTP code is: ${otp}` : "";
       subject: "Password Reset Request",
       header: "Reset Your Password",
       body,
+      logoUrl: this.defaultLogoUrl,
       otpCode: otp || void 0,
       actionUrl: resetUrl,
       actionText: "Reset Password",
@@ -659,6 +696,7 @@ ${resetUrl}`
       subject,
       header,
       body,
+      logoUrl: this.defaultLogoUrl,
       footer: this.buildFooter(brand),
       fromName: brand,
       noHtmlMessage: htmlToPlainText(body)
@@ -667,7 +705,7 @@ ${resetUrl}`
   /**
    * Newsletter / announcement email with an optional hero image and CTA button.
    */
-  createNewsLetter(subject, header, body, imageUrl, actionUrl, actionText, brandName) {
+  createNewsLetter(subject, header, body, imageUrl, actionUrl, actionText, brandName, logoUrl) {
     const brand = this.resolveBrand(brandName);
     let noHtmlMessage = htmlToPlainText(body);
     if (actionUrl) {
@@ -679,6 +717,7 @@ ${actionText || "Learn more"}: ${actionUrl}`;
       subject,
       header,
       body,
+      logoUrl: logoUrl || this.defaultLogoUrl,
       imageUrl,
       actionUrl,
       actionText,
@@ -701,6 +740,7 @@ ${magicLink}` : "";
       subject: "Your Login Verification Code",
       header: "Two-Factor Authentication",
       body,
+      logoUrl: this.defaultLogoUrl,
       otpCode: otp,
       actionUrl: magicLink || void 0,
       actionText: magicLink ? "Verify Login" : void 0,
@@ -723,6 +763,7 @@ Your verification code is: ${otp}` + plainLink
       subject: "Your Magic Link",
       header: `Sign In to ${brand}`,
       body,
+      logoUrl: this.defaultLogoUrl,
       actionUrl: magicLink,
       actionText: "Sign In",
       extraMessage: this.defaultSecurityMessage,
@@ -752,7 +793,7 @@ ${magicLink}`
   static createSimpleMessage(subject, header, body, brandName) {
     return this.defaultInstance.createSimpleMessage(subject, header, body, brandName);
   }
-  static createNewsLetter(subject, header, body, imageUrl, actionUrl, actionText, brandName) {
+  static createNewsLetter(subject, header, body, imageUrl, actionUrl, actionText, brandName, logoUrl) {
     return this.defaultInstance.createNewsLetter(
       subject,
       header,
@@ -760,7 +801,8 @@ ${magicLink}`
       imageUrl,
       actionUrl,
       actionText,
-      brandName
+      brandName,
+      logoUrl
     );
   }
   static create2FAEmail(username, otp, magicLink, brandName) {
@@ -782,13 +824,16 @@ ${magicLink}`
   MemoryEmailSender,
   TemplateError,
   TransportError,
+  ZeptoMailHttpSender,
   ZeptoMailSender,
   buildHtml,
   buildPlainText,
   createMailKit,
   decodeHtmlEntities,
   htmlToPlainText,
+  isValidHttpUrl,
   normalizeRecipient,
-  normalizeRecipients
+  normalizeRecipients,
+  parseEmailAddress
 });
 //# sourceMappingURL=index.cjs.map