@travetto/email 3.4.4 → 4.0.0-rc.1

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 [EmailOptions](https://github.com/travetto/travetto/tree/main/module/email/src/types.ts#L39) 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#L43) input. 
 
 To expose the necessary email transport, the following pattern is commonly used:
 

package/__index__.ts

@@ -1,7 +1,7 @@
 export * from './src/service';
 export * from './src/types';
 export * from './src/config';
-export * from './src/transport';
 export * from './src/resource';
+export * from './src/transport';
 export * from './src/util';
 export * from './src/template';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/email",
-  "version": "3.4.4",
+  "version": "4.0.0-rc.1",
   "description": "Email transmission module.",
   "keywords": [
     "email",
@@ -23,9 +23,9 @@
     "directory": "module/email"
   },
   "dependencies": {
-    "@travetto/base": "^3.4.2",
-    "@travetto/config": "^3.4.4",
-    "@travetto/di": "^3.4.2",
+    "@travetto/base": "^4.0.0-rc.1",
+    "@travetto/config": "^4.0.0-rc.1",
+    "@travetto/di": "^4.0.0-rc.1",
     "@types/mustache": "^4.2.5",
     "mustache": "^4.2.0"
   },

package/src/resource.ts

@@ -1,10 +1,19 @@
-import { ResourceLoader } from '@travetto/base';
-import { InjectableFactory } from '@travetto/di';
+import { AppError, Env, FileLoader } from '@travetto/base';
+import { RuntimeIndex } from '@travetto/manifest';
 
-export class EmailResource extends ResourceLoader {
-
-  @InjectableFactory()
-  static getResources(): EmailResource {
-    return new EmailResource();
+/** Build a resource loader that looks into a module and it's dependencies */
+export class EmailResourceLoader extends FileLoader {
+  constructor(module: string, globalResources?: string[]) {
+    const mod = RuntimeIndex.getModule(module);
+    if (!mod) {
+      throw new AppError(`Unknown module - ${module}`, 'notfound', { module });
+    }
+    super([
+      ...Env.TRV_RESOURCES.list ?? [],
+      `${module}#resources`,
+      ...RuntimeIndex.getDependentModules(mod, 'children').map(x => `${x.name}#resources`),
+      '@@#resources',
+      ...globalResources ?? []
+    ]);
   }
 }

package/src/service.ts

@@ -1,11 +1,10 @@
-import { GlobalEnv } from '@travetto/base';
+import { Env, RuntimeResources } from '@travetto/base';
 import { Injectable } from '@travetto/di';
 
 import { EmailCompiled, EmailOptions, SentEmail } from './types';
 import { MailTransport } from './transport';
 import { MailInterpolator } from './template';
 import { MailUtil } from './util';
-import { EmailResource } from './resource';
 
 type MessageWithoutBody = Omit<EmailOptions, keyof EmailCompiled>;
 
@@ -18,27 +17,24 @@ export class MailService {
   #compiled = new Map<string, EmailCompiled>();
   #transport: MailTransport;
   #interpolator: MailInterpolator;
-  #resources: EmailResource;
 
   constructor(
     transport: MailTransport,
     interpolator: MailInterpolator,
-    resources: EmailResource
   ) {
     this.#interpolator = interpolator;
     this.#transport = transport;
-    this.#resources = resources;
   }
 
   /**
    * Get compiled content by key
    */
   async getCompiled(key: string): Promise<EmailCompiled> {
-    if (GlobalEnv.dynamic || !this.#compiled.has(key)) {
+    if (Env.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`)
+        RuntimeResources.read(`${key}.compiled.html`),
+        RuntimeResources.read(`${key}.compiled.text`),
+        RuntimeResources.read(`${key}.compiled.subject`)
       ].map(x => x.then(MailUtil.purgeBrand)));
 
       this.#compiled.set(key, { html, text, subject });
@@ -94,6 +90,17 @@ export class MailService {
       final.attachments = [...attachments, ...(final.attachments ?? [])];
     }
 
+    // Disable threading if desired, provide a unique message id and a unique reply-to
+    if ('disableThreading' in message && message.disableThreading) {
+      const id = MailUtil.buildUniqueMessageId(message);
+      final.headers = {
+        'In-Reply-To': id,
+        References: id,
+        'X-Message-Id': id,
+        ...final.headers
+      };
+    }
+
     return this.#transport.send<S>(final);
   }
 

package/src/template.ts

@@ -1,13 +1,12 @@
 import mustache from 'mustache';
 
-import { Inject, Injectable } from '@travetto/di';
-
-import { EmailResource } from './resource';
+import { Injectable } from '@travetto/di';
+import { RuntimeResources } from '@travetto/base';
 
 /**
  * Mail interpolation engine
  *
- * @concrete ./internal/types:MailInterpolatorTarget
+ * @concrete ./internal/types#MailInterpolatorTarget
  */
 export interface MailInterpolator {
   /**
@@ -24,9 +23,6 @@ export interface MailInterpolator {
 @Injectable()
 export class MustacheInterpolator implements MailInterpolator {
 
-  @Inject()
-  resources: EmailResource;
-
   /**
    * Resolved nested templates
    */
@@ -34,7 +30,7 @@ export class MustacheInterpolator implements MailInterpolator {
     const promises: Promise<string>[] = [];
     template = template.replace(/[{]{2,3}>\s+(\S+)([.]html)?\s*[}]{2,3}/g, (all: string, name: string) => {
       promises.push(
-        this.resources.read(`${name}.html`) // Ensure html file
+        RuntimeResources.read(`${name}.html`) // Ensure html file
           .then(contents => this.resolveNested(contents))
       );
       return `$%${promises.length - 1}%$`;

package/src/transport.ts

@@ -3,7 +3,7 @@ import { EmailOptions, SentEmail } from './types';
 /**
  * Default mail transport
  *
- * @concrete ./internal/types:MailTransportTarget
+ * @concrete ./internal/types#MailTransportTarget
  */
 export interface MailTransport {
   send<S extends SentEmail = SentEmail>(mail: EmailOptions): Promise<S>;

package/src/types.ts

@@ -1,5 +1,6 @@
-import { Readable } from 'stream';
-import { Url } from 'url';
+import { FileLoader } from '@travetto/base';
+import { Readable } from 'node:stream';
+import { Url } from 'node:url';
 
 /**
  * An address
@@ -33,6 +34,9 @@ export interface EmailAttachment extends AttachmentLike {
 
 type EmailContentType = 'html' | 'text' | 'subject';
 
+export type EmailIdentity = string | EmailAddress;
+export type EmailIdentityList = EmailIdentity | EmailIdentity[];
+
 /**
  * Full message options
  */
@@ -42,13 +46,15 @@ export interface EmailOptions {
   subject: string;
   context?: Record<string, unknown>; // For templating
 
-  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;
+  disableThreading?: boolean;
+
+  from?: EmailIdentity;
+  sender?: EmailIdentity;
+  to?: EmailIdentityList;
+  cc?: EmailIdentityList;
+  bcc?: EmailIdentityList;
+  replyTo?: EmailIdentity;
+  inReplyTo?: EmailIdentity;
   references?: string | string[];
   headers?: Record<string, string | string[]>;
   attachments?: EmailAttachment[];
@@ -65,20 +71,15 @@ export type SentEmail = {
 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 EmailTemplateResource = {
+  loader: FileLoader;
+  inlineStyle?: boolean;
+  inlineImages?: boolean;
+  globalStyles?: string;
 };
 
-export type EmailTemplateStyleConfig = BaseTemplateConfig & { global?: string };
-export type EmailTemplateImageConfig = BaseTemplateConfig & {};
-
-export type EmailTemplateConfig = {
-  styles?: EmailTemplateStyleConfig;
-  images?: EmailTemplateImageConfig;
-};
+type EmailTemplateContent = Record<EmailContentType, () => (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;
+export type EmailTemplateModule = EmailTemplateResource & EmailTemplateContent;
+export type EmailTemplateImport = { prepare(loc: EmailTemplateLocation): Promise<EmailTemplateModule> };

package/src/util.ts

@@ -1,6 +1,7 @@
-import { RootIndex } from '@travetto/manifest';
+import { RuntimeContext } from '@travetto/manifest';
 
-import { EmailAttachment } from './types';
+import { EmailAttachment, EmailIdentity, EmailIdentityList, EmailOptions } from './types';
+import { Util } from '@travetto/base';
 
 /**
  * Utilities for email
@@ -15,7 +16,7 @@ export class MailUtil {
   static buildBrand(file: string, content: string, compile?: string): string {
     const out = [
       'WARNING: Do not modify.',
-      `File is generated from "${file.replace(RootIndex.manifest.workspacePath, '.')}"`,
+      `File is generated from "${file.replace(RuntimeContext.workspace.path, '.')}"`,
       compile ? `Run \`${compile.replaceAll('\n', ' ')}\` to regenerate` : ''
     ];
     return `<!-- ${out.join(' ').trim()}   -->\n${content}`;
@@ -57,4 +58,27 @@ export class MailUtil {
       html, attachments
     };
   }
+
+  /**
+   * Get the primary email, if set from an email identity or identity list
+   */
+  static getPrimaryEmail(src?: EmailIdentity | EmailIdentityList): string | undefined {
+    if (!src) {
+      return;
+    }
+    if (Array.isArray(src)) {
+      src = src[0];
+    }
+    return (typeof src === 'string') ? src : src.address;
+  }
+
+  /**
+   * Build a unique message id
+   */
+  static buildUniqueMessageId(message: EmailOptions): string {
+    const from = this.getPrimaryEmail(message.from)!;
+    const to = this.getPrimaryEmail(message.to)!;
+    const uid = Util.shortHash(`${to}${from}${message.subject}${Date.now()}`).substring(0, 12);
+    return `<${uid}@${from.split('@')[1]}>`;
+  }
 }