@travetto/email 3.1.12 → 3.1.14

package/README.md

@@ -37,4 +37,4 @@ By design, sending an email requires the sender to specify the html, text option
    *  `resources/<key>.compiled.html`
    *  `resources/<key>.compiled.text`
    *  `resources/<key>.compiled.subject`
-With `.html` being the only required field.  The [Email Templating](https://github.com/travetto/travetto/tree/main/module/email-template#readme "Email templating module") module supports this format, and will generate files accordingly. Also, note that `<key>` can include slashes, allowing for nesting folders.
+With `.html` being the only required field.  The [Email Compilation Support](https://github.com/travetto/travetto/tree/main/module/email-compiler#readme "Email compiling module") module supports this format, and will generate files accordingly. Also, note that `<key>` can include slashes, allowing for nesting folders.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/email",
-  "version": "3.1.12",
+  "version": "3.1.14",
   "description": "Email transmission module.",
   "keywords": [
     "email",
@@ -23,9 +23,9 @@
     "directory": "module/email"
   },
   "dependencies": {
-    "@travetto/base": "^3.1.2",
-    "@travetto/config": "^3.1.6",
-    "@travetto/di": "^3.1.3",
+    "@travetto/base": "^3.1.3",
+    "@travetto/config": "^3.1.8",
+    "@travetto/di": "^3.1.4",
     "@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,46 +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>;
+
+// Compilation support, defined here to allow for templates to not have a direct dependency on the compiler
+type BaseTemplateConfig = {
+  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?: {
-    search: string[];
-    global?: string;
-  };
-  inlineImages?: boolean;
-  inlineStyles?: boolean;
-  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) => {