@travetto/email 3.1.13 → 3.1.15

package/README.md

@@ -13,7 +13,7 @@ npm install @travetto/email
 yarn add @travetto/email
 ```
 
-A standard API for sending and rendering emails. The mail transport must be defined to allow for mail to be sent properly.  Out of the box, the only transport available by default is the [NullTransport](https://github.com/travetto/travetto/tree/main/module/email/src/transport.ts#L15) which will just drop emails. The structure of the API is derived from  [nodemailer](https://nodemailer.com/about/), but is compatible with any library that can handle the [MessageOptions](https://github.com/travetto/travetto/tree/main/module/email/src/types.ts#L37) input. 
+A standard API for sending and rendering emails. The mail transport must be defined to allow for mail to be sent properly.  Out of the box, the only transport available by default is the [NullTransport](https://github.com/travetto/travetto/tree/main/module/email/src/transport.ts#L15) which will just drop emails. The structure of the API is derived from  [nodemailer](https://nodemailer.com/about/), but is compatible with any library that can handle the [EmailOptions](https://github.com/travetto/travetto/tree/main/module/email/src/types.ts#L39) input. 
 
 To expose the necessary email transport, the following pattern is commonly used:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/email",
-  "version": "3.1.13",
+  "version": "3.1.15",
   "description": "Email transmission module.",
   "keywords": [
     "email",
@@ -23,9 +23,9 @@
     "directory": "module/email"
   },
   "dependencies": {
-    "@travetto/base": "^3.1.3",
-    "@travetto/config": "^3.1.7",
-    "@travetto/di": "^3.1.4",
+    "@travetto/base": "^3.1.4",
+    "@travetto/config": "^3.1.9",
+    "@travetto/di": "^3.1.5",
     "@types/mustache": "^4.2.2",
     "mustache": "^4.2.0"
   },

package/src/internal/types.ts

@@ -1,2 +1,2 @@
-export class MailTemplateEngineTarget { }
+export class MailInterpolatorTarget { }
 export class MailTransportTarget { }

package/src/service.ts

@@ -1,13 +1,13 @@
 import { GlobalEnv } from '@travetto/base';
 import { Injectable } from '@travetto/di';
 
-import { MessageCompiled, MessageOptions, SentMessage } from './types';
+import { EmailCompiled, EmailOptions, SentEmail } from './types';
 import { MailTransport } from './transport';
-import { MailTemplateEngine } from './template';
+import { MailInterpolator } from './template';
 import { MailUtil } from './util';
 import { EmailResource } from './resource';
 
-type MessageWithoutBody = Omit<MessageOptions, keyof MessageCompiled>;
+type MessageWithoutBody = Omit<EmailOptions, keyof EmailCompiled>;
 
 /**
  * Email service for sending and templating emails
@@ -15,17 +15,17 @@ type MessageWithoutBody = Omit<MessageOptions, keyof MessageCompiled>;
 @Injectable()
 export class MailService {
 
-  #compiled = new Map<string, MessageCompiled>();
+  #compiled = new Map<string, EmailCompiled>();
   #transport: MailTransport;
-  #tplEngine: MailTemplateEngine;
+  #interpolator: MailInterpolator;
   #resources: EmailResource;
 
   constructor(
     transport: MailTransport,
-    tplEngine: MailTemplateEngine,
+    interpolator: MailInterpolator,
     resources: EmailResource
   ) {
-    this.#tplEngine = tplEngine;
+    this.#interpolator = interpolator;
     this.#transport = transport;
     this.#resources = resources;
   }
@@ -33,13 +33,13 @@ export class MailService {
   /**
    * Get compiled content by key
    */
-  async getCompiled(key: string): Promise<MessageCompiled> {
+  async getCompiled(key: string): Promise<EmailCompiled> {
     if (GlobalEnv.dynamic || !this.#compiled.has(key)) {
       const [html, text, subject] = await Promise.all([
         this.#resources.read(`${key}.compiled.html`),
         this.#resources.read(`${key}.compiled.text`),
         this.#resources.read(`${key}.compiled.subject`)
-      ]);
+      ].map(x => x.then(MailUtil.purgeBrand)));
 
       this.#compiled.set(key, { html, text, subject });
     }
@@ -52,13 +52,13 @@ export class MailService {
    * @param ctx
    * @returns
    */
-  async templateMessage(keyOrMessage: string | MessageCompiled, ctx: Record<string, unknown>): Promise<MessageCompiled> {
+  async renderMessage(keyOrMessage: string | EmailCompiled, ctx: Record<string, unknown>): Promise<EmailCompiled> {
     const tpl = (typeof keyOrMessage === 'string' ? await this.getCompiled(keyOrMessage) : keyOrMessage);
 
     const [html, text, subject] = await Promise.all([
-      this.#tplEngine!.template(tpl.html, ctx),
-      this.#tplEngine!.template(tpl.text, ctx),
-      this.#tplEngine!.template(tpl.subject, ctx)
+      this.#interpolator.render(tpl.html, ctx),
+      this.#interpolator.render(tpl.text ?? '', ctx),
+      this.#interpolator.render(tpl.subject, ctx)
     ]);
 
     return { html, text, subject };
@@ -67,15 +67,15 @@ export class MailService {
   /**
    * Send a single message
    */
-  async send<S extends SentMessage = SentMessage>(
-    message: Pick<MessageOptions, 'to' | 'from' | 'replyTo'>,
+  async send<S extends SentEmail = SentEmail>(
+    message: Pick<EmailOptions, 'to' | 'from' | 'replyTo'>,
     key: string,
     ctx?: Record<string, unknown>,
     base?: MessageWithoutBody
   ): Promise<S>;
-  async send<S extends SentMessage = SentMessage>(message: MessageOptions): Promise<S>;
-  async send<S extends SentMessage = SentMessage>(
-    message: MessageOptions | Pick<MessageOptions, 'to' | 'from' | 'replyTo'>,
+  async send<S extends SentEmail = SentEmail>(message: EmailOptions): Promise<S>;
+  async send<S extends SentEmail = SentEmail>(
+    message: EmailOptions | Pick<EmailOptions, 'to' | 'from' | 'replyTo'>,
     key?: string,
     ctx?: Record<string, unknown>,
     base?: MessageWithoutBody
@@ -83,7 +83,7 @@ export class MailService {
     const keyOrMessage = key ?? ('html' in message ? message : '') ?? '';
     const context = ctx ?? (('context' in message) ? message.context : {}) ?? {};
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    const compiled = await this.templateMessage(keyOrMessage as MessageCompiled, context);
+    const compiled = await this.renderMessage(keyOrMessage as EmailCompiled, context);
 
     const final = { ...base, ...message, ...compiled, context };
 
@@ -100,7 +100,7 @@ export class MailService {
   /**
    * Send multiple messages.
    */
-  async sendAll<S extends SentMessage = SentMessage>(messages: MessageOptions[], base: Partial<MessageOptions> = {}): Promise<S[]> {
+  async sendAll<S extends SentEmail = SentEmail>(messages: EmailOptions[], base: Partial<EmailOptions> = {}): Promise<S[]> {
     return Promise.all(messages.map(msg => this.send<S>({
       ...base,
       ...msg,

package/src/template.ts

@@ -5,24 +5,24 @@ import { Injectable } from '@travetto/di';
 import { EmailResource } from './resource';
 
 /**
- * Mail templating engine
+ * Mail interpolation engine
  *
- * @concrete ./internal/types:MailTemplateEngineTarget
+ * @concrete ./internal/types:MailInterpolatorTarget
  */
-export interface MailTemplateEngine {
+export interface MailInterpolator {
   /**
   * Resolved nested templates
   */
   resolveNested(template: string): Promise<string>;
 
   /**
-   * Interpolate a string with a given context, useful for simple messages
+   * Interpolate a string with a given context
    */
-  template(text: string, ctx: Record<string, unknown>): Promise<string> | string;
+  render(text: string, ctx: Record<string, unknown>): Promise<string> | string;
 }
 
 @Injectable()
-export class MustacheTemplateEngine implements MailTemplateEngine {
+export class MustacheInterpolator implements MailInterpolator {
 
   resources = new EmailResource();
 
@@ -45,7 +45,7 @@ export class MustacheTemplateEngine implements MailTemplateEngine {
   /**
    * Interpolate text with data
    */
-  template(text: string, data: Record<string, unknown>): string {
+  render(text: string, data: Record<string, unknown>): string {
     return mustache.render(text, data);
   }
 }

package/src/transport.ts

@@ -1,4 +1,4 @@
-import { MessageOptions, SentMessage } from './types';
+import { EmailOptions, SentEmail } from './types';
 
 /**
  * Default mail transport
@@ -6,14 +6,14 @@ import { MessageOptions, SentMessage } from './types';
  * @concrete ./internal/types:MailTransportTarget
  */
 export interface MailTransport {
-  send<S extends SentMessage = SentMessage>(mail: MessageOptions): Promise<S>;
+  send<S extends SentEmail = SentEmail>(mail: EmailOptions): Promise<S>;
 }
 
 /**
  * Transport that consumes messages without sending
  */
 export class NullTransport implements MailTransport {
-  async send<S extends SentMessage = SentMessage>(mail: MessageOptions): Promise<S> {
+  async send<S extends SentEmail = SentEmail>(mail: EmailOptions): Promise<S> {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
     return {} as S;
   }

package/src/types.ts

@@ -4,7 +4,7 @@ import { Url } from 'url';
 /**
  * An address
  */
-export interface Address {
+export interface EmailAddress {
   name: string;
   address: string;
 }
@@ -20,7 +20,7 @@ interface AttachmentLike {
 /**
  * A full attachment
  */
-export interface Attachment extends AttachmentLike {
+export interface EmailAttachment extends AttachmentLike {
   filename?: string | false;
   cid?: string;
   encoding?: string;
@@ -31,53 +31,54 @@ export interface Attachment extends AttachmentLike {
   raw?: string | Buffer | Readable | AttachmentLike;
 }
 
+type EmailContentType = 'html' | 'text' | 'subject';
+
 /**
  * Full message options
  */
-export interface MessageOptions {
+export interface EmailOptions {
   html: string;
   text?: string;
-  subject?: string;
+  subject: string;
   context?: Record<string, unknown>; // For templating
 
-  from?: string | Address;
-  sender?: string | Address;
-  to?: string | Address | (string | Address)[];
-  cc?: string | Address | (string | Address)[];
-  bcc?: string | Address | (string | Address)[];
-  replyTo?: string | Address;
-  inReplyTo?: string | Address;
+  from?: string | EmailAddress;
+  sender?: string | EmailAddress;
+  to?: string | EmailAddress | (string | EmailAddress)[];
+  cc?: string | EmailAddress | (string | EmailAddress)[];
+  bcc?: string | EmailAddress | (string | EmailAddress)[];
+  replyTo?: string | EmailAddress;
+  inReplyTo?: string | EmailAddress;
   references?: string | string[];
   headers?: Record<string, string | string[]>;
-  attachments?: Attachment[];
-  alternatives?: Attachment[];
+  attachments?: EmailAttachment[];
+  alternatives?: EmailAttachment[];
   messageId?: string;
   date?: Date | string;
   encoding?: string;
 }
 
-export type SentMessage = {
+export type SentEmail = {
   messageId?: string;
 };
 
-export type MessageCompiled = { html: string, text: string, subject: string };
+export type EmailCompiled = Record<EmailContentType, string>;
 
-export type MessageCompilationStyles = {
+// Compilation support, defined here to allow for templates to not have a direct dependency on the compiler
+type BaseTemplateConfig = {
   search?: string[];
-  global?: string;
   inline?: boolean;
 };
 
-export type MessageCompilationImages = {
-  search?: string[];
-  inline?: boolean;
+export type EmailTemplateStyleConfig = BaseTemplateConfig & { global?: string };
+export type EmailTemplateImageConfig = BaseTemplateConfig & {};
+
+export type EmailTemplateConfig = {
+  styles?: EmailTemplateStyleConfig;
+  images?: EmailTemplateImageConfig;
 };
 
-export type MessageCompilationSource = {
-  file?: string;
-  styles?: MessageCompilationStyles;
-  images?: MessageCompilationImages;
-  html: () => Promise<string> | string;
-  text: () => Promise<string> | string;
-  subject: () => Promise<string> | string;
-};
+export type EmailTemplateLocation = { file: string, module: string };
+export type EmailRenderer = (ctx: EmailTemplateLocation & EmailTemplateConfig) => Promise<string> | string;
+export type EmailCompileSource = EmailTemplateConfig & Record<EmailContentType, EmailRenderer>;
+export type EmailCompileContext = EmailTemplateLocation & EmailCompileSource;

package/src/util.ts

@@ -1,17 +1,34 @@
-import { Attachment } from './types';
+import { RootIndex } from '@travetto/manifest';
+
+import { EmailAttachment } from './types';
 
 /**
  * Utilities for email
  */
 export class MailUtil {
+  /** Remove brand from text */
+  static purgeBrand(text: string): string {
+    return text.replace(/<!-- WARNING:[^\n]*\n/m, '');
+  }
+
+  /** Add brand to text */
+  static buildBrand(file: string, content: string, compile?: string): string {
+    const out = [
+      'WARNING: Do not modify.',
+      `File is generated from "${file.replace(RootIndex.manifest.workspacePath, '.')}"`,
+      compile ? `Run \`${compile.replaceAll('\n', ' ')}\` to regenerate` : ''
+    ];
+    return `<!-- ${out.join(' ').trim()}   -->\n${content}`;
+  }
+
   /**
    * Extract images from html as attachments
    *
    * @param html
    */
-  static async extractImageAttachments(html: string): Promise<{ html: string, attachments: Attachment[] }> {
+  static async extractImageAttachments(html: string): Promise<{ html: string, attachments: EmailAttachment[] }> {
     let idx = 0;
-    const attachments: Attachment[] = [];
+    const attachments: EmailAttachment[] = [];
     const contentMap = new Map<string, string>();
 
     html = html.replace(/data:(image\/[^;]+);base64,([^"']+)/g, (__, contentType, content) => {