@igniter-js/mail 0.1.0 → 0.1.1

package/dist/index.mjs

@@ -4,7 +4,7 @@ import nodemailer from 'nodemailer';
 import React from 'react';
 import { render } from '@react-email/components';
 
-// src/errors/igniter-mail.error.ts
+// src/errors/mail.error.ts
 var IgniterMailError = class _IgniterMailError extends IgniterError {
   constructor(payload) {
     super({
@@ -27,560 +27,375 @@ var IgniterMailError = class _IgniterMailError extends IgniterError {
 };
 
 // src/adapters/postmark.adapter.ts
-var PostmarkMailAdapterBuilder = class _PostmarkMailAdapterBuilder {
-  /** Creates a new builder instance. */
-  static create() {
-    return new _PostmarkMailAdapterBuilder();
-  }
-  /** Sets the Postmark Server Token. */
-  withSecret(secret) {
-    this.secret = secret;
-    return this;
+var PostmarkMailAdapter = class _PostmarkMailAdapter {
+  /**
+   * Creates a new adapter instance.
+   *
+   * @param credentials - Provider credentials (secret/from).
+   * @throws {IgniterMailError} Does not throw on creation; errors surface on send.
+   */
+  constructor(credentials = {}) {
+    this.credentials = credentials;
   }
-  /** Sets the default FROM address used when sending emails via Postmark. */
-  withFrom(from) {
-    this.from = from;
-    return this;
+  /**
+   * Creates a new adapter instance.
+   *
+   * @param credentials - Provider credentials (secret/from).
+   * @returns A Postmark adapter instance.
+   * @throws {IgniterMailError} Does not throw on creation; errors surface on send.
+   * @example
+   * ```ts
+   * const adapter = PostmarkMailAdapter.create({ secret: 'token', from: 'no-reply@acme.com' })
+   * ```
+   */
+  static create(credentials) {
+    return new _PostmarkMailAdapter(credentials);
   }
-  /** Builds the adapter instance. */
-  build() {
-    if (!this.secret) {
+  /**
+   * Sends an email using Postmark (HTTP API).
+   *
+   * @param params - Normalized email parameters.
+   * @returns A promise that resolves when the email is accepted.
+   * @throws {IgniterMailError} When configuration is invalid or Postmark rejects the request.
+   * @example
+   * ```ts
+   * await adapter.send({ to: 'user@example.com', subject: 'Hello', html: '<p>Hi</p>', text: 'Hi' })
+   * ```
+   */
+  async send(params) {
+    if (!this.credentials.secret) {
       throw new IgniterMailError({
         code: "MAIL_ADAPTER_CONFIGURATION_INVALID",
         message: "Postmark adapter secret is required"
       });
     }
-    if (!this.from) {
+    if (!this.credentials.from) {
       throw new IgniterMailError({
         code: "MAIL_ADAPTER_CONFIGURATION_INVALID",
         message: "Postmark adapter from is required"
       });
     }
-    const token = this.secret;
-    const from = this.from;
-    return {
-      /** Sends an email using Postmark (HTTP API). */
-      send: async ({ to, subject, html, text }) => {
-        const response = await fetch("https://api.postmarkapp.com/email", {
-          method: "POST",
-          headers: {
-            Accept: "application/json",
-            "Content-Type": "application/json",
-            "X-Postmark-Server-Token": token
-          },
-          body: JSON.stringify({
-            From: from,
-            To: to,
-            Subject: subject,
-            HtmlBody: html,
-            TextBody: text
-          })
-        });
-        if (!response.ok) {
-          const body = await response.text().catch(() => "");
-          throw new IgniterMailError({
-            code: "MAIL_PROVIDER_SEND_FAILED",
-            message: "Postmark send failed",
-            metadata: {
-              status: response.status,
-              body
-            }
-          });
+    const token = this.credentials.secret;
+    const from = this.credentials.from;
+    const response = await fetch("https://api.postmarkapp.com/email", {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "X-Postmark-Server-Token": token
+      },
+      body: JSON.stringify({
+        From: from,
+        To: params.to,
+        Subject: params.subject,
+        HtmlBody: params.html,
+        TextBody: params.text
+      })
+    });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new IgniterMailError({
+        code: "MAIL_PROVIDER_SEND_FAILED",
+        message: "Postmark send failed",
+        metadata: {
+          status: response.status,
+          body
         }
-      }
-    };
+      });
+    }
   }
 };
-var postmarkAdapter = (options) => PostmarkMailAdapterBuilder.create().withSecret(options.secret).withFrom(options.from).build();
-var ResendMailAdapterBuilder = class _ResendMailAdapterBuilder {
-  /** Creates a new builder instance. */
-  static create() {
-    return new _ResendMailAdapterBuilder();
-  }
-  /** Sets the Resend API key. */
-  withSecret(secret) {
-    this.secret = secret;
-    return this;
+var ResendMailAdapter = class _ResendMailAdapter {
+  /**
+   * Creates an adapter with credentials.
+   *
+   * @param credentials - Adapter credentials including API secret and default from.
+   * @throws {IgniterMailError} Does not throw on creation; errors surface on send.
+   */
+  constructor(credentials = {}) {
+    this.credentials = credentials;
   }
-  /** Sets the default FROM address used when sending emails via Resend. */
-  withFrom(from) {
-    this.from = from;
-    return this;
+  /**
+   * Creates a new adapter instance.
+   *
+   * @param credentials - Adapter credentials including API secret and default from.
+   * @returns A configured Resend adapter.
+   * @throws {IgniterMailError} Does not throw on creation; errors surface on send.
+   * @example
+   * ```ts
+   * const adapter = ResendMailAdapter.create({ secret: 'token', from: 'no-reply@acme.com' })
+   * ```
+   */
+  static create(credentials) {
+    return new _ResendMailAdapter(credentials);
   }
-  /** Builds the adapter instance. */
-  build() {
-    if (!this.secret) {
+  /**
+   * Sends an email using Resend.
+   *
+   * @param params - Email payload to send.
+   * @returns Resolves when the email is accepted by Resend.
+   * @throws {IgniterMailError} When credentials are missing or Resend rejects the request.
+   *
+   * @example
+   * ```ts
+   * await adapter.send({ to: 'user@example.com', subject: 'Welcome', html: '<p>Hi</p>', text: 'Hi' })
+   * ```
+   */
+  async send(params) {
+    if (!this.credentials.secret) {
       throw new IgniterMailError({
         code: "MAIL_ADAPTER_CONFIGURATION_INVALID",
         message: "Resend adapter secret is required"
       });
     }
-    if (!this.from) {
+    if (!this.credentials.from) {
       throw new IgniterMailError({
         code: "MAIL_ADAPTER_CONFIGURATION_INVALID",
         message: "Resend adapter from is required"
       });
     }
-    const resend = new Resend(this.secret);
-    const from = this.from;
-    return {
-      /**
-       * Sends an email using Resend.
-       *
-       * Note: Resend accepts `scheduledAt` as an ISO string.
-       */
-      send: async ({ to, subject, html, text, scheduledAt }) => {
-        await resend.emails.create({
-          to,
-          from,
-          subject,
-          html,
-          text,
-          scheduledAt: scheduledAt?.toISOString()
-        });
-      }
-    };
+    const resend = new Resend(this.credentials.secret);
+    const from = this.credentials.from;
+    await resend.emails.create({
+      to: params.to,
+      from,
+      subject: params.subject,
+      html: params.html,
+      text: params.text,
+      scheduledAt: params.scheduledAt?.toISOString()
+    });
   }
 };
-var resendAdapter = (options) => ResendMailAdapterBuilder.create().withSecret(options.secret).withFrom(options.from).build();
 
 // src/adapters/sendgrid.adapter.ts
-var SendGridMailAdapterBuilder = class _SendGridMailAdapterBuilder {
-  /** Creates a new builder instance. */
-  static create() {
-    return new _SendGridMailAdapterBuilder();
-  }
-  /** Sets the SendGrid API key. */
-  withSecret(secret) {
-    this.secret = secret;
-    return this;
+var SendGridMailAdapter = class _SendGridMailAdapter {
+  /**
+   * Creates an adapter with credentials.
+   *
+   * @param credentials - Adapter credentials including API secret and default from.
+   * @throws {IgniterMailError} Does not throw on creation; errors surface on send.
+   */
+  constructor(credentials = {}) {
+    this.credentials = credentials;
   }
-  /** Sets the default FROM address used when sending emails via SendGrid. */
-  withFrom(from) {
-    this.from = from;
-    return this;
+  /**
+   * Creates a new adapter instance.
+   *
+   * @param credentials - Adapter credentials including API secret and default from.
+   * @returns A configured SendGrid adapter.
+   * @throws {IgniterMailError} Does not throw on creation; errors surface on send.
+   * @example
+   * ```ts
+   * const adapter = SendGridMailAdapter.create({ secret: 'token', from: 'no-reply@acme.com' })
+   * ```
+   */
+  static create(credentials) {
+    return new _SendGridMailAdapter(credentials);
   }
-  /** Builds the adapter instance. */
-  build() {
-    if (!this.secret) {
+  /**
+   * Sends an email using SendGrid (HTTP API).
+   *
+   * @param params - Email payload to send.
+   * @returns Resolves when the email is accepted by SendGrid.
+   * @throws {IgniterMailError} When credentials are missing or the API fails.
+   *
+   * @example
+   * ```ts
+   * await adapter.send({ to: 'user@example.com', subject: 'Hi', html: '<p>Hi</p>', text: 'Hi' })
+   * ```
+   */
+  async send(params) {
+    if (!this.credentials.secret) {
       throw new IgniterMailError({
         code: "MAIL_ADAPTER_CONFIGURATION_INVALID",
         message: "SendGrid adapter secret is required"
       });
     }
-    if (!this.from) {
+    if (!this.credentials.from) {
       throw new IgniterMailError({
         code: "MAIL_ADAPTER_CONFIGURATION_INVALID",
         message: "SendGrid adapter from is required"
       });
     }
-    const apiKey = this.secret;
-    const from = this.from;
-    return {
-      /** Sends an email using SendGrid (HTTP API). */
-      send: async ({ to, subject, html, text }) => {
-        const response = await fetch("https://api.sendgrid.com/v3/mail/send", {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json"
-          },
-          body: JSON.stringify({
-            personalizations: [{
-              to: [{ email: to }]
-            }],
-            from: { email: from },
-            subject,
-            content: [
-              { type: "text/plain", value: text },
-              { type: "text/html", value: html }
-            ]
-          })
-        });
-        if (!response.ok) {
-          const body = await response.text().catch(() => "");
-          throw new IgniterMailError({
-            code: "MAIL_PROVIDER_SEND_FAILED",
-            message: "SendGrid send failed",
-            metadata: {
-              status: response.status,
-              body
-            }
-          });
+    const apiKey = this.credentials.secret;
+    const from = this.credentials.from;
+    const response = await fetch("https://api.sendgrid.com/v3/mail/send", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        personalizations: [
+          {
+            to: [{ email: params.to }]
+          }
+        ],
+        from: { email: from },
+        subject: params.subject,
+        content: [
+          { type: "text/plain", value: params.text },
+          { type: "text/html", value: params.html }
+        ]
+      })
+    });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new IgniterMailError({
+        code: "MAIL_PROVIDER_SEND_FAILED",
+        message: "SendGrid send failed",
+        metadata: {
+          status: response.status,
+          body
         }
-      }
-    };
+      });
+    }
   }
 };
-var sendgridAdapter = (options) => SendGridMailAdapterBuilder.create().withSecret(options.secret).withFrom(options.from).build();
-var SmtpMailAdapterBuilder = class _SmtpMailAdapterBuilder {
-  /** Creates a new builder instance. */
-  static create() {
-    return new _SmtpMailAdapterBuilder();
-  }
-  /** Sets the SMTP connection URL (e.g. `smtps://user:pass@host:port`). */
-  withSecret(secret) {
-    this.secret = secret;
-    return this;
+var SmtpMailAdapter = class _SmtpMailAdapter {
+  /**
+   * Creates an adapter with credentials.
+   *
+   * @param credentials - Adapter credentials including SMTP URL and default from.
+   * @throws {IgniterMailError} Does not throw on creation; errors surface on send.
+   */
+  constructor(credentials = {}) {
+    this.credentials = credentials;
   }
-  /** Sets the default FROM address used when sending emails via SMTP. */
-  withFrom(from) {
-    this.from = from;
-    return this;
+  /**
+   * Creates a new adapter instance.
+   *
+   * @param credentials - Adapter credentials including SMTP URL and default from.
+   * @returns A configured SMTP adapter.
+   * @throws {IgniterMailError} Does not throw on creation; errors surface on send.
+   * @example
+   * ```ts
+   * const adapter = SmtpMailAdapter.create({ secret: 'smtps://user:pass@host:465', from: 'no-reply@acme.com' })
+   * ```
+   */
+  static create(credentials) {
+    return new _SmtpMailAdapter(credentials);
   }
-  /** Builds the adapter instance. */
-  build() {
-    if (!this.secret) {
+  /**
+   * Sends an email using Nodemailer over SMTP.
+   *
+   * @param params - Email payload to send.
+   * @returns Resolves when the email is sent.
+   * @throws {IgniterMailError} When credentials are missing or the SMTP send fails.
+   *
+   * @example
+   * ```ts
+   * await adapter.send({ to: 'user@example.com', subject: 'Hi', html: '<p>Hi</p>', text: 'Hi' })
+   * ```
+   */
+  async send(params) {
+    if (!this.credentials.secret) {
       throw new IgniterMailError({
         code: "MAIL_ADAPTER_CONFIGURATION_INVALID",
         message: "SMTP adapter secret is required"
       });
     }
-    if (!this.from) {
+    if (!this.credentials.from) {
       throw new IgniterMailError({
         code: "MAIL_ADAPTER_CONFIGURATION_INVALID",
         message: "SMTP adapter from is required"
       });
     }
-    const smtpUrl = this.secret;
-    const from = this.from;
-    const createTransporter = () => {
-      return nodemailer.createTransport(smtpUrl, {
-        tls: {
-          rejectUnauthorized: false
-        },
-        connectionTimeout: 1e4,
-        greetingTimeout: 5e3,
-        socketTimeout: 1e4
-      });
-    };
-    return {
-      /** Sends an email using Nodemailer over SMTP. */
-      send: async ({ to, subject, html, text }) => {
-        const transport = createTransporter();
-        const mailOptions = {
-          from,
-          to,
-          subject,
-          html,
-          text
-        };
-        try {
-          await transport.sendMail(mailOptions);
-          transport.close();
-        } catch (error) {
-          transport.close();
-          throw error;
-        }
+    const smtpUrl = this.credentials.secret;
+    const from = this.credentials.from;
+    const transport = nodemailer.createTransport(smtpUrl, {
+      connectionTimeout: 1e4,
+      greetingTimeout: 5e3,
+      socketTimeout: 1e4,
+      tls: {
+        rejectUnauthorized: false
       }
-    };
-  }
-};
-var smtpAdapter = (options) => SmtpMailAdapterBuilder.create().withSecret(options.secret).withFrom(options.from).build();
-
-// src/adapters/test.adapter.ts
-function createTestMailAdapter(options = {}) {
-  const sent = [];
-  const logger = options.logger ?? console;
-  const silent = options.silent ?? false;
-  return {
-    sent,
-    reset: () => {
-      sent.length = 0;
-    },
-    last: () => sent.at(-1),
-    send: async (params) => {
-      sent.push({ ...params, at: /* @__PURE__ */ new Date() });
-      if (!silent) {
-        logger.info(
-          `[TestMailAdapter] to=${params.to} subject=${params.subject} html=${params.html.length}B text=${params.text.length}B`
-        );
-      }
-    }
-  };
-}
-
-// src/adapters/webhook.adapter.ts
-var WebhookMailAdapterBuilder = class _WebhookMailAdapterBuilder {
-  /** Creates a new builder instance. */
-  static create() {
-    return new _WebhookMailAdapterBuilder();
-  }
-  /**
-   * Sets the webhook URL.
-   *
-   * Note: when using `IgniterMailBuilder.withAdapter('webhook', secret)`, the `secret`
-   * is treated as the webhook URL.
-   */
-  withUrl(url) {
-    this.url = url;
-    return this;
-  }
-  /** Sets the default FROM address. */
-  withFrom(from) {
-    this.from = from;
-    return this;
-  }
-  /** Builds the adapter instance. */
-  build() {
-    if (!this.url) {
-      throw new IgniterMailError({
-        code: "MAIL_ADAPTER_CONFIGURATION_INVALID",
-        message: "Webhook adapter url is required"
+    });
+    try {
+      await transport.sendMail({
+        from,
+        to: params.to,
+        subject: params.subject,
+        html: params.html,
+        text: params.text
       });
-    }
-    if (!this.from) {
+    } catch (error) {
       throw new IgniterMailError({
-        code: "MAIL_ADAPTER_CONFIGURATION_INVALID",
-        message: "Webhook adapter from is required"
+        code: "MAIL_PROVIDER_SEND_FAILED",
+        message: "SMTP send failed",
+        metadata: {
+          originalError: error
+        }
       });
+    } finally {
+      transport.close();
     }
-    const url = this.url;
-    const from = this.from;
-    return {
-      /** Sends an email by POST-ing to the configured webhook URL. */
-      send: async ({ to, subject, html, text, scheduledAt }) => {
-        const response = await fetch(url, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json"
-          },
-          body: JSON.stringify({
-            to,
-            from,
-            subject,
-            html,
-            text,
-            scheduledAt: scheduledAt?.toISOString()
-          })
-        });
-        if (!response.ok) {
-          const body = await response.text().catch(() => "");
-          throw new IgniterMailError({
-            code: "MAIL_PROVIDER_SEND_FAILED",
-            message: "Webhook send failed",
-            metadata: {
-              status: response.status,
-              body
-            }
-          });
-        }
-      }
-    };
   }
 };
-var webhookAdapter = (options) => WebhookMailAdapterBuilder.create().withUrl(options.secret).withFrom(options.from).build();
 
-// src/builders/igniter-mail.builder.ts
-var IgniterMailBuilder = class _IgniterMailBuilder {
-  constructor(factory) {
-    this.templates = {};
-    this.factory = factory;
-  }
-  /**
-   * Creates a new builder.
-   */
-  static create(factory) {
-    return new _IgniterMailBuilder(factory);
-  }
-  /** Sets the default FROM address. */
-  withFrom(from) {
-    this.from = from;
-    return this;
-  }
-  /** Attaches a logger instance. */
-  withLogger(logger) {
-    this.logger = logger;
-    return this;
-  }
+// src/types/telemetry.ts
+var IGNITER_MAIL_TELEMETRY_EVENTS = {
+  /** Emitted when mail send operation starts */
+  SEND_STARTED: "igniter.mail.send.started",
+  /** Emitted when mail send operation succeeds */
+  SEND_SUCCESS: "igniter.mail.send.success",
+  /** Emitted when mail send operation fails */
+  SEND_ERROR: "igniter.mail.send.error",
+  /** Emitted when mail schedule operation starts */
+  SCHEDULE_STARTED: "igniter.mail.schedule.started",
+  /** Emitted when mail schedule operation succeeds */
+  SCHEDULE_SUCCESS: "igniter.mail.schedule.success",
+  /** Emitted when mail schedule operation fails */
+  SCHEDULE_ERROR: "igniter.mail.schedule.error"
+};
+
+// src/utils/schema.ts
+var IgniterMailSchema = class {
   /**
-   * Enables queue delivery.
+   * Validates an unknown input using `StandardSchemaV1` when the schema provides `~standard.validate`.
    *
-   * If configured, `IgniterMail.schedule()` will enqueue jobs instead of using `setTimeout`.
-   */
-  withQueue(adapter, options) {
-    this.queue = { adapter, options };
-    return this;
-  }
-  withAdapter(adapterOrProvider, secret) {
-    if (typeof adapterOrProvider === "string") {
-      if (!secret) {
-        throw new IgniterMailError({
-          code: "MAIL_PROVIDER_ADAPTER_SECRET_REQUIRED",
-          message: "MAIL_PROVIDER_ADAPTER_SECRET_REQUIRED",
-          logger: this.logger
-        });
-      }
-      this.adapter = {
-        kind: "provider",
-        provider: adapterOrProvider,
-        secret
-      };
-      return this;
-    }
-    this.adapter = {
-      kind: "adapter",
-      adapter: adapterOrProvider
-    };
-    return this;
-  }
-  /**
-   * Registers a template.
-   */
-  addTemplate(key, template) {
-    this.templates[key] = template;
-    return this;
-  }
-  /** Hook invoked before sending. */
-  withOnSendStarted(onSendStarted) {
-    this.onSendStarted = onSendStarted;
-    return this;
-  }
-  /** Hook invoked on error. */
-  withOnSendError(onSendError) {
-    this.onSendError = onSendError;
-    return this;
-  }
-  /** Hook invoked on success. */
-  withOnSendSuccess(onSendSuccess) {
-    this.onSendSuccess = onSendSuccess;
-    return this;
-  }
-  /**
-   * Builds the {@link IgniterMail} instance.
+   * If the schema does not provide a validator, this method returns the input as-is.
    */
-  build() {
-    if (!this.from) {
-      throw new IgniterMailError({
-        code: "MAIL_PROVIDER_FROM_REQUIRED",
-        message: "MAIL_PROVIDER_FROM_REQUIRED",
-        logger: this.logger
-      });
+  static async validateInput(schema, input) {
+    const standard = schema?.["~standard"];
+    if (!standard?.validate) {
+      return input;
     }
-    if (!this.adapter) {
+    const result = await standard.validate(input);
+    if (result?.issues?.length) {
       throw new IgniterMailError({
-        code: "MAIL_PROVIDER_ADAPTER_REQUIRED",
-        message: "MAIL_PROVIDER_ADAPTER_REQUIRED",
-        logger: this.logger
+        code: "MAIL_PROVIDER_TEMPLATE_DATA_INVALID",
+        message: "Invalid mail template payload",
+        statusCode: 400,
+        details: result.issues
       });
     }
-    const resolvedAdapter = this.adapter.kind === "adapter" ? this.adapter.adapter : (() => {
-      switch (this.adapter.provider) {
-        case "resend":
-          return ResendMailAdapterBuilder.create().withSecret(this.adapter.secret).withFrom(this.from).build();
-        case "smtp":
-          return SmtpMailAdapterBuilder.create().withSecret(this.adapter.secret).withFrom(this.from).build();
-        case "postmark":
-          return PostmarkMailAdapterBuilder.create().withSecret(this.adapter.secret).withFrom(this.from).build();
-        case "sendgrid":
-          return SendGridMailAdapterBuilder.create().withSecret(this.adapter.secret).withFrom(this.from).build();
-        case "webhook":
-          return WebhookMailAdapterBuilder.create().withUrl(this.adapter.secret).withFrom(this.from).build();
-        default:
-          throw new IgniterMailError({
-            code: "MAIL_PROVIDER_ADAPTER_NOT_FOUND",
-            message: `MAIL_PROVIDER_ADAPTER_NOT_FOUND: ${this.adapter.provider}`,
-            logger: this.logger,
-            metadata: {
-              provider: this.adapter.provider
-            }
-          });
-      }
-    })();
-    return this.factory({
-      from: this.from,
-      adapter: resolvedAdapter,
-      templates: this.templates,
-      onSendStarted: this.onSendStarted,
-      onSendError: this.onSendError,
-      onSendSuccess: this.onSendSuccess,
-      logger: this.logger,
-      queue: this.queue ? {
-        adapter: this.queue.adapter,
-        id: `${this.queue.options?.namespace ?? "mail"}.${this.queue.options?.task ?? "send"}`,
-        options: this.queue.options
-      } : void 0
-    });
+    return result?.value ?? input;
   }
-};
-
-// src/builders/mail-template.builder.ts
-var MailTemplateBuilder = class _MailTemplateBuilder {
-  /** Creates a new builder instance. */
-  static create() {
-    return new _MailTemplateBuilder();
-  }
-  /** Sets the default subject for the template. */
-  withSubject(subject) {
-    this.subject = subject;
-    return this;
-  }
-  /** Attaches the schema used to validate and infer payload types. */
-  withSchema(schema) {
-    this.schema = schema;
-    return this;
-  }
-  /** Sets the React Email render function for the template. */
-  withRender(render2) {
-    this.render = render2;
-    return this;
-  }
-  /** Builds the template definition. */
-  build() {
-    if (!this.subject) {
-      throw new IgniterMailError({
-        code: "MAIL_TEMPLATE_CONFIGURATION_INVALID",
-        message: "Mail template subject is required"
-      });
-    }
-    if (!this.schema) {
-      throw new IgniterMailError({
-        code: "MAIL_TEMPLATE_CONFIGURATION_INVALID",
-        message: "Mail template schema is required"
-      });
-    }
-    if (!this.render) {
-      throw new IgniterMailError({
-        code: "MAIL_TEMPLATE_CONFIGURATION_INVALID",
-        message: "Mail template render is required"
-      });
-    }
+  /**
+   * Creates a passthrough StandardSchema validator.
+   */
+  static createPassthroughSchema() {
     return {
-      subject: this.subject,
-      schema: this.schema,
-      render: this.render
+      "~standard": {
+        vendor: "@igniter-js/mail",
+        version: 1,
+        validate: async (value) => ({ value })
+      }
     };
   }
 };
 
-// src/utils/validate-standard-schema-input.ts
-async function validateStandardSchemaInput(schema, input) {
-  const standard = schema?.["~standard"];
-  if (!standard?.validate) {
-    return input;
-  }
-  const result = await standard.validate(input);
-  if (result?.issues?.length) {
-    throw new IgniterMailError({
-      code: "MAIL_PROVIDER_TEMPLATE_DATA_INVALID",
-      message: "Invalid mail template payload",
-      statusCode: 400,
-      details: result.issues
-    });
-  }
-  return result?.value ?? input;
-}
-
-// src/core/igniter-mail.tsx
-var _IgniterMail = class _IgniterMail {
+// src/core/manager.tsx
+var IgniterMailManagerCore = class {
   constructor(options) {
     this.queueJobRegistered = false;
     /**
      * Type inference helper.
      * Access via `typeof mail.$Infer` (type-level only).
      */
-    this.$Infer = void 0;
-    const { adapter, templates, logger, queue, ...rest } = options;
+    this.$Infer = {};
+    const { adapter, templates, logger, telemetry, queue, ...rest } = options;
     if (!adapter) {
       throw new IgniterMailError({
         code: "MAIL_PROVIDER_ADAPTER_REQUIRED",
@@ -598,6 +413,7 @@ var _IgniterMail = class _IgniterMail {
     this.adapter = adapter;
     this.templates = templates;
     this.logger = logger;
+    this.telemetry = telemetry;
     this.queue = queue;
     this.options = rest;
   }
@@ -611,30 +427,20 @@ var _IgniterMail = class _IgniterMail {
     }
     this.queueJobRegistering = (async () => {
       const queueOptions = queue.options;
-      const name = queueOptions?.name ?? "send";
-      const passthroughSchema = {
-        "~standard": {
-          vendor: "@igniter-js/mail",
-          version: 1,
-          validate: async (value) => ({ value })
-        }
-      };
-      const definition = queue.adapter.register({
-        name,
+      const passthroughSchema = IgniterMailSchema.createPassthroughSchema();
+      queue.adapter.register({
+        name: queueOptions?.job ?? "send",
         input: passthroughSchema,
-        handler: async ({ input }) => {
-          await this.send(input);
-        },
-        queue: queueOptions?.queue,
         attempts: queueOptions?.attempts,
         priority: queueOptions?.priority,
         removeOnComplete: queueOptions?.removeOnComplete,
         removeOnFail: queueOptions?.removeOnFail,
         metadata: queueOptions?.metadata,
-        limiter: queueOptions?.limiter
-      });
-      await queue.adapter.bulkRegister({
-        [queue.id]: definition
+        limiter: queueOptions?.limiter,
+        queue: { name: queueOptions?.queue ?? "mail" },
+        handler: async ({ input }) => {
+          await this.send(input);
+        }
       });
       this.queueJobRegistered = true;
     })();
@@ -646,7 +452,7 @@ var _IgniterMail = class _IgniterMail {
   }
   async validateTemplateData(template, data) {
     try {
-      return await validateStandardSchemaInput(
+      return await IgniterMailSchema.validateInput(
         template.schema,
         data
       );
@@ -665,11 +471,20 @@ var _IgniterMail = class _IgniterMail {
    * Sends an email immediately.
    */
   async send(params) {
+    const startTime = Date.now();
     try {
       this.logger?.debug("IgniterMail.send started", {
         to: params.to,
         template: String(params.template)
       });
+      this.telemetry?.emit(IGNITER_MAIL_TELEMETRY_EVENTS.SEND_STARTED, {
+        level: "debug",
+        attributes: {
+          "mail.to": params.to,
+          "mail.template": String(params.template),
+          "mail.subject": params.subject
+        }
+      });
       await this.onSendStarted(params);
       const template = this.templates[params.template];
       if (!template) {
@@ -698,9 +513,20 @@ var _IgniterMail = class _IgniterMail {
         text
       });
       await this.onSendSuccess(params);
+      const durationMs = Date.now() - startTime;
+      this.telemetry?.emit(IGNITER_MAIL_TELEMETRY_EVENTS.SEND_SUCCESS, {
+        level: "info",
+        attributes: {
+          "mail.to": params.to,
+          "mail.template": String(params.template),
+          "mail.subject": params.subject || template.subject,
+          "mail.duration_ms": durationMs
+        }
+      });
       this.logger?.info("IgniterMail.send success", {
         to: params.to,
-        template: String(params.template)
+        template: String(params.template),
+        durationMs
       });
     } catch (error) {
       const normalizedError = IgniterMailError.is(error) ? error : new IgniterMailError({
@@ -713,6 +539,18 @@ var _IgniterMail = class _IgniterMail {
           template: String(params.template)
         }
       });
+      const durationMs = Date.now() - startTime;
+      this.telemetry?.emit(IGNITER_MAIL_TELEMETRY_EVENTS.SEND_ERROR, {
+        level: "error",
+        attributes: {
+          "mail.to": params.to,
+          "mail.template": String(params.template),
+          "mail.subject": params.subject,
+          "mail.error.code": normalizedError.code,
+          "mail.error.message": normalizedError.message,
+          "mail.duration_ms": durationMs
+        }
+      });
       this.logger?.error("IgniterMail.send failed", normalizedError);
       await this.onSendError(params, normalizedError);
       throw normalizedError;
@@ -721,10 +559,10 @@ var _IgniterMail = class _IgniterMail {
   /**
    * Schedules an email for a future date.
    *
-   * If a queue is configured, this method enqueues a job.
-   * Otherwise, it uses a best-effort `setTimeout`.
+   * Requires a queue adapter; otherwise it throws.
    */
   async schedule(params, date) {
+    const startTime = Date.now();
     if (date.getTime() <= Date.now()) {
       throw new IgniterMailError({
         code: "MAIL_PROVIDER_SCHEDULE_DATE_INVALID",
@@ -732,24 +570,60 @@ var _IgniterMail = class _IgniterMail {
         logger: this.logger
       });
     }
-    if (this.queue) {
-      try {
-        await this.ensureQueueJobRegistered();
-        const delay = Math.max(0, date.getTime() - Date.now());
-        this.logger?.info("IgniterMail.schedule enqueued", {
-          id: this.queue.id,
-          to: params.to,
-          template: String(params.template),
-          delay
-        });
-        await this.queue.adapter.invoke({
-          id: this.queue.id,
-          input: params,
-          delay
-        });
-        return;
-      } catch (error) {
-        const normalizedError = IgniterMailError.is(error) ? error : new IgniterMailError({
+    const delay = Math.max(0, date.getTime() - Date.now());
+    this.logger?.debug("IgniterMail.schedule started", {
+      to: params.to,
+      template: String(params.template),
+      scheduledAt: date.toISOString(),
+      delayMs: delay
+    });
+    this.telemetry?.emit(IGNITER_MAIL_TELEMETRY_EVENTS.SCHEDULE_STARTED, {
+      level: "debug",
+      attributes: {
+        "mail.to": params.to,
+        "mail.template": String(params.template),
+        "mail.scheduled_at": date.toISOString(),
+        "mail.delay_ms": delay
+      }
+    });
+    if (!this.queue) {
+      throw new IgniterMailError({
+        code: "MAIL_PROVIDER_SCHEDULE_QUEUE_NOT_CONFIGURED",
+        message: "MAIL_PROVIDER_SCHEDULE_QUEUE_NOT_CONFIGURED",
+        logger: this.logger
+      });
+    }
+    try {
+      await this.ensureQueueJobRegistered();
+      const queue = this.queue.options?.queue ?? "mail";
+      const job = this.queue.options?.job ?? "send";
+      const id = `${queue}.${job}`;
+      this.logger?.info("IgniterMail.schedule enqueued", {
+        to: params.to,
+        template: String(params.template),
+        delay,
+        durationMs: Date.now() - startTime
+      });
+      await this.queue.adapter.invoke({
+        id,
+        input: params,
+        delay
+      });
+      this.telemetry?.emit(IGNITER_MAIL_TELEMETRY_EVENTS.SCHEDULE_SUCCESS, {
+        level: "info",
+        attributes: {
+          "mail.to": params.to,
+          "mail.template": String(params.template),
+          "mail.scheduled_at": date.toISOString(),
+          "mail.delay_ms": delay,
+          "mail.queue_id": this.queue.options?.queue ?? "mail"
+        }
+      });
+      return;
+    } catch (error) {
+      let normalizedError = error;
+      if (!IgniterMailError.is(error)) {
+        normalizedError = new IgniterMailError({
           code: "MAIL_PROVIDER_SCHEDULE_FAILED",
           message: "MAIL_PROVIDER_SCHEDULE_FAILED",
           cause: error,
@@ -757,19 +631,23 @@ var _IgniterMail = class _IgniterMail {
           metadata: {
             to: params.to,
             template: String(params.template),
-            date: date.toISOString()
+            scheduledAt: date.toISOString()
           }
         });
-        this.logger?.error("IgniterMail.schedule failed", normalizedError);
-        throw normalizedError;
       }
-    }
-    const timeout = date.getTime() - Date.now();
-    setTimeout(() => {
-      this.send(params).catch((error) => {
-        console.error("Failed to send scheduled email:", error);
+      this.telemetry?.emit(IGNITER_MAIL_TELEMETRY_EVENTS.SCHEDULE_ERROR, {
+        level: "error",
+        attributes: {
+          "mail.to": params.to,
+          "mail.template": String(params.template),
+          "mail.scheduled_at": date.toISOString(),
+          "mail.error.code": normalizedError.code,
+          "mail.error.message": normalizedError.message
+        }
       });
-    }, timeout);
+      this.logger?.error("IgniterMail.schedule failed", normalizedError);
+      throw normalizedError;
+    }
   }
   async onSendStarted(params) {
     await this.options.onSendStarted?.(params);
@@ -781,76 +659,227 @@ var _IgniterMail = class _IgniterMail {
     await this.options.onSendSuccess?.(params);
   }
 };
-/** Helper to declare adapter factories. */
-_IgniterMail.adapter = (adapter) => adapter;
-/** Helper to declare templates with inferred payload types. */
-_IgniterMail.template = (template) => template;
-/**
- * Creates a new builder instance.
- */
-_IgniterMail.create = () => IgniterMailBuilder.create((options) => new _IgniterMail(options));
-/**
- * Initializes (singleton) instance.
- *
- * Prefer using {@link IgniterMail.create} for new code.
- */
-_IgniterMail.initialize = (options) => {
-  if (_IgniterMail.instance) {
-    return _IgniterMail.instance;
-  }
-  const adapter = options.adapter;
-  if (typeof adapter === "function") {
-    const legacyOptions = options;
-    _IgniterMail.instance = new _IgniterMail({
-      from: legacyOptions.from,
-      templates: legacyOptions.templates,
-      adapter: legacyOptions.adapter(legacyOptions),
-      onSendStarted: legacyOptions.onSendStarted,
-      onSendError: legacyOptions.onSendError,
-      onSendSuccess: legacyOptions.onSendSuccess
+
+// src/builders/main.builder.ts
+var IgniterMailBuilder = class _IgniterMailBuilder {
+  constructor(options) {
+    this.templates = {};
+    this.from = options.from;
+    this.adapter = options.adapter;
+    this.templates = options.templates;
+    this.logger = options.logger;
+    this.telemetry = options.telemetry;
+    this.onSendStartedHandler = options.onSendStarted;
+    this.onSendErrorHandler = options.onSendError;
+    this.onSendSuccessHandler = options.onSendSuccess;
+    if (options.queue) {
+      this.queue = {
+        adapter: options.queue.adapter,
+        options: options.queue.options
+      };
+    }
+  }
+  /**
+   * Creates a new builder.
+   */
+  static create() {
+    return new _IgniterMailBuilder({ from: "", adapter: {}, templates: {} });
+  }
+  /** Sets the default FROM address. */
+  withFrom(from) {
+    this.from = from;
+    return this;
+  }
+  /** Attaches a logger instance. */
+  withLogger(logger) {
+    this.logger = logger;
+    return this;
+  }
+  /** Attaches a telemetry instance for observability. */
+  withTelemetry(telemetry) {
+    this.telemetry = telemetry;
+    return this;
+  }
+  /**
+   * Enables queue delivery.
+   *
+   * When configured, `IgniterMail.schedule()` will enqueue jobs using the queue adapter.
+   */
+  withQueue(adapter, options) {
+    this.queue = { adapter, options };
+    return this;
+  }
+  withAdapter(adapterOrProvider, secret) {
+    if (typeof adapterOrProvider === "string") {
+      if (!secret) {
+        throw new IgniterMailError({
+          code: "MAIL_PROVIDER_ADAPTER_SECRET_REQUIRED",
+          message: "MAIL_PROVIDER_ADAPTER_SECRET_REQUIRED",
+          logger: this.logger
+        });
+      }
+      switch (adapterOrProvider) {
+        case "resend":
+          this.adapter = ResendMailAdapter.create({
+            secret,
+            from: this.from
+          });
+          return this;
+        case "smtp":
+          this.adapter = SmtpMailAdapter.create({
+            secret,
+            from: this.from
+          });
+          return this;
+        case "postmark":
+          this.adapter = PostmarkMailAdapter.create({
+            secret,
+            from: this.from
+          });
+          return this;
+        case "sendgrid":
+          this.adapter = SendGridMailAdapter.create({
+            secret,
+            from: this.from
+          });
+          return this;
+        default:
+          throw new IgniterMailError({
+            code: "MAIL_PROVIDER_ADAPTER_NOT_FOUND",
+            message: `MAIL_PROVIDER_ADAPTER_NOT_FOUND: ${adapterOrProvider}`,
+            logger: this.logger,
+            metadata: {
+              provider: adapterOrProvider
+            }
+          });
+      }
+    }
+    this.adapter = adapterOrProvider;
+    return this;
+  }
+  /**
+   * Registers a template.
+   */
+  addTemplate(key, template) {
+    return new _IgniterMailBuilder({
+      from: this.from,
+      adapter: this.adapter,
+      templates: {
+        ...this.templates,
+        [key]: template
+      },
+      logger: this.logger,
+      telemetry: this.telemetry,
+      onSendStarted: this.onSendStartedHandler,
+      onSendError: this.onSendErrorHandler,
+      onSendSuccess: this.onSendSuccessHandler,
+      queue: this.queue ? {
+        adapter: this.queue.adapter,
+        options: this.queue.options
+      } : void 0
+    });
+  }
+  /** Hook invoked before sending. */
+  onSendStarted(handler) {
+    this.onSendStartedHandler = handler;
+    return this;
+  }
+  /** Hook invoked on error. */
+  onSendError(handler) {
+    this.onSendErrorHandler = handler;
+    return this;
+  }
+  /** Hook invoked on success. */
+  onSendSuccess(handler) {
+    this.onSendSuccessHandler = handler;
+    return this;
+  }
+  /**
+   * Builds the {@link IgniterMail} instance.
+   */
+  build() {
+    if (!this.from) {
+      throw new IgniterMailError({
+        code: "MAIL_PROVIDER_FROM_REQUIRED",
+        message: "MAIL_PROVIDER_FROM_REQUIRED",
+        logger: this.logger
+      });
+    }
+    if (!this.adapter) {
+      throw new IgniterMailError({
+        code: "MAIL_PROVIDER_ADAPTER_REQUIRED",
+        message: "MAIL_PROVIDER_ADAPTER_REQUIRED",
+        logger: this.logger
+      });
+    }
+    return new IgniterMailManagerCore({
+      from: this.from,
+      adapter: this.adapter,
+      templates: this.templates,
+      onSendStarted: this.onSendStartedHandler,
+      onSendError: this.onSendErrorHandler,
+      onSendSuccess: this.onSendSuccessHandler,
+      telemetry: this.telemetry,
+      logger: this.logger,
+      queue: this.queue ? {
+        adapter: this.queue.adapter,
+        options: this.queue.options
+      } : void 0
     });
-    return _IgniterMail.instance;
   }
-  _IgniterMail.instance = new _IgniterMail(
-    options
-  );
-  return _IgniterMail.instance;
 };
-var IgniterMail = _IgniterMail;
+var IgniterMail = IgniterMailBuilder;
 
-// src/types/provider.ts
-function createPassthroughSchema() {
-  return {
-    "~standard": {
-      vendor: "@igniter-js/mail",
-      version: 1,
-      validate: async (value) => ({ value })
+// src/builders/template.builder.ts
+var IgniterMailTemplateBuilder = class _IgniterMailTemplateBuilder {
+  /** Creates a new builder instance. */
+  static create() {
+    return new _IgniterMailTemplateBuilder();
+  }
+  /** Sets the default subject for the template. */
+  withSubject(subject) {
+    this.subject = subject;
+    return this;
+  }
+  /** Attaches the schema used to validate and infer payload types. */
+  withSchema(schema) {
+    this.schema = schema;
+    return this;
+  }
+  /** Sets the React Email render function for the template. */
+  withRender(render2) {
+    this.render = render2;
+    return this;
+  }
+  /** Builds the template definition. */
+  build() {
+    if (!this.subject) {
+      throw new IgniterMailError({
+        code: "MAIL_TEMPLATE_CONFIGURATION_INVALID",
+        message: "Mail template subject is required"
+      });
     }
-  };
-}
-
-// src/utils/get-adapter.ts
-var getAdapter = (adapter) => {
-  switch (adapter) {
-    case "resend":
-      return resendAdapter;
-    case "smtp":
-      return smtpAdapter;
-    case "postmark":
-      return postmarkAdapter;
-    case "sendgrid":
-      return sendgridAdapter;
-    case "webhook":
-      return webhookAdapter;
-    default:
+    if (!this.schema) {
       throw new IgniterMailError({
-        code: "MAIL_PROVIDER_ADAPTER_NOT_FOUND",
-        message: `MAIL_PROVIDER_ADAPTER_NOT_FOUND: ${adapter}`,
-        metadata: { adapter }
+        code: "MAIL_TEMPLATE_CONFIGURATION_INVALID",
+        message: "Mail template schema is required"
       });
+    }
+    if (!this.render) {
+      throw new IgniterMailError({
+        code: "MAIL_TEMPLATE_CONFIGURATION_INVALID",
+        message: "Mail template render is required"
+      });
+    }
+    return {
+      subject: this.subject,
+      schema: this.schema,
+      render: this.render
+    };
   }
 };
+var IgniterMailTemplate = IgniterMailTemplateBuilder;
 
-export { IgniterMail, IgniterMailBuilder, IgniterMailError, MailTemplateBuilder, PostmarkMailAdapterBuilder, ResendMailAdapterBuilder, SendGridMailAdapterBuilder, SmtpMailAdapterBuilder, WebhookMailAdapterBuilder, createPassthroughSchema, createTestMailAdapter, getAdapter, postmarkAdapter, resendAdapter, sendgridAdapter, smtpAdapter, validateStandardSchemaInput, webhookAdapter };
+export { IgniterMail, IgniterMailBuilder, IgniterMailError, IgniterMailManagerCore, IgniterMailSchema, IgniterMailTemplate, IgniterMailTemplateBuilder };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map