@igniter-js/mail 0.1.13 → 0.1.14

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { StandardSchemaV1, JobLimiter, IgniterLogger, IgniterJobQueueAdapter, IgniterError } from '@igniter-js/core';
+import { StandardSchemaV1, IgniterLogger, IgniterError } from '@igniter-js/common';
+import { JobLimiter, IgniterJobQueueAdapter } from '@igniter-js/core';
 import { I as IgniterMailAdapter } from './index-CbiH0sth.js';
 export { b as IgniterMailAdapterCredentials, a as IgniterMailAdapterSendParams, M as MockMailAdapter, P as PostmarkMailAdapter, R as ResendMailAdapter, S as SendGridMailAdapter, c as SmtpMailAdapter } from './index-CbiH0sth.js';
 import { ReactElement } from 'react';
@@ -10,11 +11,44 @@ import { IgniterTelemetryManager } from '@igniter-js/telemetry';
 interface IgniterMailTemplateBuilt<TSchema extends StandardSchemaV1> {
     /** Default subject for the template (can be overridden per-send). */
     subject: string;
+    /** Optional display name for Studio and tooling. */
+    name?: string;
+    /** Optional description for Studio and tooling. */
+    description?: string;
+    /** Optional path hint for Studio and tooling. */
+    path?: string;
+    /** Optional created timestamp (ISO string). */
+    createdAt?: string;
+    /** Optional updated timestamp (ISO string). */
+    updatedAt?: string;
+    /** Optional list of variable names for Studio and tooling. */
+    variables?: string[];
     /** Schema used to validate and infer template payload. */
     schema: TSchema;
     /** React Email component renderer. */
     render: (data: StandardSchemaV1.InferInput<TSchema>) => ReactElement;
 }
+/**
+ * Template metadata exposed by {@link IIgniterMail}.
+ */
+interface IgniterMailTemplateMeta {
+    /** Template identifier (registry key). */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Description for UI listings. */
+    description: string;
+    /** Path hint for routing. */
+    path: string;
+    /** Subject line for the template. */
+    subject: string;
+    /** Creation timestamp (ISO string). */
+    createdAt: string;
+    /** Last update timestamp (ISO string). */
+    updatedAt: string;
+    /** Optional list of variables for the template. */
+    variables?: string[];
+}
 /**
  * Extracts the valid template keys from a template map.
  */
@@ -107,6 +141,31 @@ interface IgniterMailHooks<TTemplates extends object> {
     /** Invoked after a successful send. */
     onSendSuccess?: (params: IgniterMailSendParams<TTemplates, any>) => Promise<void>;
 }
+/**
+ * Template registry API exposed by {@link IIgniterMail}.
+ */
+interface IgniterMailTemplatesAPI<TTemplates extends object> {
+    /**
+     * Lists all registered templates with metadata.
+     */
+    list: () => Promise<IgniterMailTemplateMeta[]>;
+    /**
+     * Resolves a template metadata entry by id.
+     *
+     * @param id - Template key.
+     */
+    get: <TSelectedTemplate extends IgniterMailTemplateKey<TTemplates>>(id: TSelectedTemplate) => Promise<IgniterMailTemplateMeta | null>;
+    /**
+     * Renders a template to HTML + text.
+     *
+     * @param id - Template key.
+     * @param variables - Template input payload.
+     */
+    render: <TSelectedTemplate extends IgniterMailTemplateKey<TTemplates>>(id: TSelectedTemplate, variables?: IgniterMailTemplatePayload<TTemplates[TSelectedTemplate]>) => Promise<{
+        html: string;
+        text: string;
+    }>;
+}
 /**
  * Options used to initialize {@link IgniterMail}.
  */
@@ -133,6 +192,10 @@ interface IIgniterMail<TTemplates extends object> {
      * Access via `typeof mail.$Infer` (type-level only).
      */
     readonly $Infer: IgniterMailInfer<TTemplates>;
+    /**
+     * Template registry helpers.
+     */
+    readonly templates: IgniterMailTemplatesAPI<TTemplates>;
     /** Sends an email immediately. */
     send: <TSelectedTemplate extends IgniterMailTemplateKey<TTemplates>>(params: IgniterMailSendParams<TTemplates, TSelectedTemplate>) => Promise<void>;
     /** Schedules an email for a future date (requires queue adapter). */
@@ -223,7 +286,7 @@ declare const IgniterMailTemplate: typeof IgniterMailTemplateBuilder;
  */
 declare class IgniterMailManagerCore<TTemplates extends object> implements IIgniterMail<TTemplates> {
     private readonly adapter;
-    private readonly templates;
+    private readonly templateRegistry;
     private readonly logger?;
     private readonly telemetry?;
     private readonly queue?;
@@ -235,7 +298,15 @@ declare class IgniterMailManagerCore<TTemplates extends object> implements IIgni
      * Access via `typeof mail.$Infer` (type-level only).
      */
     readonly $Infer: IgniterMailInfer<TTemplates>;
+    /**
+     * Template registry helpers.
+     */
+    readonly templates: IgniterMailTemplatesAPI<TTemplates>;
     constructor(options: IgniterMailOptions<TTemplates>);
+    private buildTemplateMeta;
+    private listTemplates;
+    private getTemplate;
+    private renderTemplate;
     private ensureQueueJobRegistered;
     private validateTemplateData;
     /**
@@ -256,7 +327,7 @@ declare class IgniterMailManagerCore<TTemplates extends object> implements IIgni
 /**
  * Known error codes thrown by `@igniter-js/mail` runtime.
  */
-type IgniterMailErrorCode = 'MAIL_PROVIDER_FROM_REQUIRED' | 'MAIL_PROVIDER_ADAPTER_REQUIRED' | 'MAIL_PROVIDER_ADAPTER_SECRET_REQUIRED' | 'MAIL_PROVIDER_ADAPTER_NOT_FOUND' | 'MAIL_PROVIDER_TEMPLATES_REQUIRED' | 'MAIL_PROVIDER_TEMPLATE_NOT_FOUND' | 'MAIL_PROVIDER_TEMPLATE_DATA_INVALID' | 'MAIL_PROVIDER_SCHEDULE_DATE_INVALID' | 'MAIL_PROVIDER_SEND_FAILED' | 'MAIL_PROVIDER_SCHEDULE_FAILED' | 'MAIL_ADAPTER_CONFIGURATION_INVALID' | 'MAIL_TEMPLATE_CONFIGURATION_INVALID' | 'MAIL_PROVIDER_SCHEDULE_QUEUE_NOT_CONFIGURED';
+type IgniterMailErrorCode = 'MAIL_PROVIDER_FROM_REQUIRED' | 'MAIL_PROVIDER_ADAPTER_REQUIRED' | 'MAIL_PROVIDER_ADAPTER_SECRET_REQUIRED' | 'MAIL_PROVIDER_ADAPTER_NOT_FOUND' | 'MAIL_PROVIDER_TEMPLATES_REQUIRED' | 'MAIL_PROVIDER_TEMPLATE_NOT_FOUND' | 'MAIL_PROVIDER_TEMPLATE_DATA_INVALID' | 'MAIL_PROVIDER_TEMPLATE_LIST_FAILED' | 'MAIL_PROVIDER_TEMPLATE_GET_FAILED' | 'MAIL_PROVIDER_TEMPLATE_RENDER_FAILED' | 'MAIL_PROVIDER_SCHEDULE_DATE_INVALID' | 'MAIL_PROVIDER_SEND_FAILED' | 'MAIL_PROVIDER_SCHEDULE_FAILED' | 'MAIL_ADAPTER_CONFIGURATION_INVALID' | 'MAIL_TEMPLATE_CONFIGURATION_INVALID' | 'MAIL_PROVIDER_SCHEDULE_QUEUE_NOT_CONFIGURED';
 /**
  * Payload used to create an {@link IgniterMailError}.
  */
@@ -306,4 +377,4 @@ declare class IgniterMailSchema {
     static createPassthroughSchema(): StandardSchemaV1;
 }
 
-export { type IIgniterMail, IgniterMail, IgniterMailAdapter, IgniterMailBuilder, IgniterMailError, type IgniterMailErrorCode, type IgniterMailErrorPayload, type IgniterMailHooks, type IgniterMailInfer, IgniterMailManagerCore, type IgniterMailOptions, type IgniterMailQueueConfig, type IgniterMailQueueOptions, IgniterMailSchema, type IgniterMailSendParams, IgniterMailTemplate, IgniterMailTemplateBuilder, type IgniterMailTemplateBuilt, type IgniterMailTemplateKey, type IgniterMailTemplatePayload };
+export { type IIgniterMail, IgniterMail, IgniterMailAdapter, IgniterMailBuilder, IgniterMailError, type IgniterMailErrorCode, type IgniterMailErrorPayload, type IgniterMailHooks, type IgniterMailInfer, IgniterMailManagerCore, type IgniterMailOptions, type IgniterMailQueueConfig, type IgniterMailQueueOptions, IgniterMailSchema, type IgniterMailSendParams, IgniterMailTemplate, IgniterMailTemplateBuilder, type IgniterMailTemplateBuilt, type IgniterMailTemplateKey, type IgniterMailTemplateMeta, type IgniterMailTemplatePayload, type IgniterMailTemplatesAPI };

package/dist/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var core = require('@igniter-js/core');
+var common = require('@igniter-js/common');
 var resend = require('resend');
 var nodemailer = require('nodemailer');
 var React = require('react');
@@ -12,7 +12,7 @@ var nodemailer__default = /*#__PURE__*/_interopDefault(nodemailer);
 var React__default = /*#__PURE__*/_interopDefault(React);
 
 // src/errors/mail.error.ts
-var IgniterMailError = class _IgniterMailError extends core.IgniterError {
+var IgniterMailError = class _IgniterMailError extends common.IgniterError {
   constructor(payload) {
     super({
       code: payload.code,
@@ -402,11 +402,193 @@ var IgniterMailManagerCore = class {
       });
     }
     this.adapter = adapter;
-    this.templates = templates;
+    this.templateRegistry = templates;
     this.logger = logger;
     this.telemetry = telemetry;
     this.queue = queue;
     this.options = rest;
+    this.templates = {
+      list: async () => this.listTemplates(),
+      get: async (id) => this.getTemplate(id),
+      render: async (id, variables) => this.renderTemplate(id, variables)
+    };
+  }
+  buildTemplateMeta(key, template) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      id: key,
+      name: template.name ?? key,
+      description: template.description ?? `Template ${key}`,
+      path: template.path ?? `mail/${key}`,
+      subject: template.subject,
+      createdAt: template.createdAt ?? now,
+      updatedAt: template.updatedAt ?? now,
+      variables: template.variables
+    };
+  }
+  async listTemplates() {
+    const startTime = Date.now();
+    this.logger?.debug("IgniterMail.templates.list started");
+    this.telemetry?.emit("igniter.mail.templates.list.started", {
+      level: "debug",
+      attributes: {}
+    });
+    try {
+      const results = Object.entries(this.templateRegistry).map(
+        ([key, template]) => this.buildTemplateMeta(
+          key,
+          template
+        )
+      );
+      this.telemetry?.emit("igniter.mail.templates.list.success", {
+        level: "info",
+        attributes: {
+          "ctx.mail.template.count": results.length,
+          "ctx.mail.duration_ms": Date.now() - startTime
+        }
+      });
+      this.logger?.info("IgniterMail.templates.list success", {
+        count: results.length,
+        durationMs: Date.now() - startTime
+      });
+      return results;
+    } catch (error) {
+      const normalizedError = IgniterMailError.is(error) ? error : new IgniterMailError({
+        code: "MAIL_PROVIDER_TEMPLATE_LIST_FAILED",
+        message: "MAIL_PROVIDER_TEMPLATE_LIST_FAILED",
+        cause: error,
+        logger: this.logger
+      });
+      this.telemetry?.emit("igniter.mail.templates.list.error", {
+        level: "error",
+        attributes: {
+          "ctx.mail.error.code": normalizedError.code,
+          "ctx.mail.error.message": normalizedError.message,
+          "ctx.mail.duration_ms": Date.now() - startTime
+        }
+      });
+      this.logger?.error("IgniterMail.templates.list failed", normalizedError);
+      throw normalizedError;
+    }
+  }
+  async getTemplate(id) {
+    const startTime = Date.now();
+    this.logger?.debug("IgniterMail.templates.get started", {
+      template: String(id)
+    });
+    this.telemetry?.emit("igniter.mail.templates.get.started", {
+      level: "debug",
+      attributes: {
+        "ctx.mail.template_id": String(id)
+      }
+    });
+    try {
+      const template = this.templateRegistry[id];
+      if (!template) {
+        this.telemetry?.emit("igniter.mail.templates.get.success", {
+          level: "info",
+          attributes: {
+            "ctx.mail.template_id": String(id),
+            "ctx.mail.duration_ms": Date.now() - startTime
+          }
+        });
+        return null;
+      }
+      const result = this.buildTemplateMeta(String(id), template);
+      this.telemetry?.emit("igniter.mail.templates.get.success", {
+        level: "info",
+        attributes: {
+          "ctx.mail.template_id": String(id),
+          "ctx.mail.duration_ms": Date.now() - startTime
+        }
+      });
+      return result;
+    } catch (error) {
+      const normalizedError = IgniterMailError.is(error) ? error : new IgniterMailError({
+        code: "MAIL_PROVIDER_TEMPLATE_GET_FAILED",
+        message: "MAIL_PROVIDER_TEMPLATE_GET_FAILED",
+        cause: error,
+        logger: this.logger,
+        metadata: { template: String(id) }
+      });
+      this.telemetry?.emit("igniter.mail.templates.get.error", {
+        level: "error",
+        attributes: {
+          "ctx.mail.template_id": String(id),
+          "ctx.mail.error.code": normalizedError.code,
+          "ctx.mail.error.message": normalizedError.message,
+          "ctx.mail.duration_ms": Date.now() - startTime
+        }
+      });
+      this.logger?.error("IgniterMail.templates.get failed", normalizedError);
+      throw normalizedError;
+    }
+  }
+  async renderTemplate(id, variables) {
+    const startTime = Date.now();
+    this.logger?.debug("IgniterMail.templates.render started", {
+      template: String(id)
+    });
+    this.telemetry?.emit("igniter.mail.templates.render.started", {
+      level: "debug",
+      attributes: {
+        "ctx.mail.template_id": String(id)
+      }
+    });
+    try {
+      const template = this.templateRegistry[id];
+      if (!template) {
+        throw new IgniterMailError({
+          code: "MAIL_PROVIDER_TEMPLATE_NOT_FOUND",
+          message: "MAIL_PROVIDER_TEMPLATE_NOT_FOUND",
+          logger: this.logger,
+          metadata: { template: String(id) }
+        });
+      }
+      const validatedData = await this.validateTemplateData(
+        template,
+        variables ?? {}
+      );
+      const MailTemplate = template.render;
+      const html = await components.render(
+        /* @__PURE__ */ React__default.default.createElement(MailTemplate, { ...validatedData })
+      );
+      const text = await components.render(
+        /* @__PURE__ */ React__default.default.createElement(MailTemplate, { ...validatedData }),
+        { plainText: true }
+      );
+      this.telemetry?.emit("igniter.mail.templates.render.success", {
+        level: "info",
+        attributes: {
+          "ctx.mail.template_id": String(id),
+          "ctx.mail.duration_ms": Date.now() - startTime
+        }
+      });
+      this.logger?.info("IgniterMail.templates.render success", {
+        template: String(id),
+        durationMs: Date.now() - startTime
+      });
+      return { html, text };
+    } catch (error) {
+      const normalizedError = IgniterMailError.is(error) ? error : new IgniterMailError({
+        code: "MAIL_PROVIDER_TEMPLATE_RENDER_FAILED",
+        message: "MAIL_PROVIDER_TEMPLATE_RENDER_FAILED",
+        cause: error,
+        logger: this.logger,
+        metadata: { template: String(id) }
+      });
+      this.telemetry?.emit("igniter.mail.templates.render.error", {
+        level: "error",
+        attributes: {
+          "ctx.mail.template_id": String(id),
+          "ctx.mail.error.code": normalizedError.code,
+          "ctx.mail.error.message": normalizedError.message,
+          "ctx.mail.duration_ms": Date.now() - startTime
+        }
+      });
+      this.logger?.error("IgniterMail.templates.render failed", normalizedError);
+      throw normalizedError;
+    }
   }
   async ensureQueueJobRegistered() {
     const queue = this.queue;
@@ -477,7 +659,7 @@ var IgniterMailManagerCore = class {
         }
       });
       await this.onSendStarted(params);
-      const template = this.templates[params.template];
+      const template = this.templateRegistry[params.template];
       if (!template) {
         throw new IgniterMailError({
           code: "MAIL_PROVIDER_TEMPLATE_NOT_FOUND",