@travetto/email 4.0.0-rc.0 → 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,6 +1,7 @@
 export * from './src/service';
 export * from './src/types';
 export * from './src/config';
+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": "4.0.0-rc.0",
+  "version": "4.0.0-rc.1",
   "description": "Email transmission module.",
   "keywords": [
     "email",
@@ -23,9 +23,9 @@
     "directory": "module/email"
   },
   "dependencies": {
-    "@travetto/base": "^4.0.0-rc.0",
-    "@travetto/config": "^4.0.0-rc.0",
-    "@travetto/di": "^4.0.0-rc.0",
+    "@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

@@ -0,0 +1,19 @@
+import { AppError, Env, FileLoader } from '@travetto/base';
+import { RuntimeIndex } from '@travetto/manifest';
+
+/** 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

@@ -90,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/types.ts

@@ -1,3 +1,4 @@
+import { FileLoader } from '@travetto/base';
 import { Readable } from 'node:stream';
 import { Url } from 'node:url';
 
@@ -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[] | readonly 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 { RuntimeContext } from '@travetto/manifest';
 
-import { EmailAttachment } from './types';
+import { EmailAttachment, EmailIdentity, EmailIdentityList, EmailOptions } from './types';
+import { Util } from '@travetto/base';
 
 /**
  * Utilities for email
@@ -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]}>`;
+  }
 }