@travetto/email 2.1.7 → 2.2.0

package/README.md

@@ -8,7 +8,7 @@
 npm install @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#L36) 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 [MessageOptions](https://github.com/travetto/travetto/tree/main/module/email/src/types.ts#L37) input.
 
 To expose the necessary email transport, the following pattern is commonly used:
 
@@ -35,7 +35,7 @@ By design, sending an email requires the sender to specify the html, text option
    *  `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.
 
-## Nodmailer - Extension
+## Nodemailer - Extension
 
 Given the integration with [nodemailer](https://nodemailer.com/about/), all extensions should be usable out of the box. The primary [nodemailer](https://nodemailer.com/about/) modules are provided (assuming dependencies are installed):
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@travetto/email",
   "displayName": "Email",
-  "version": "2.1.7",
+  "version": "2.2.0",
   "description": "Email transmission module.",
   "keywords": [
     "email",
@@ -24,8 +24,8 @@
     "directory": "module/email"
   },
   "dependencies": {
-    "@travetto/config": "^2.1.5",
-    "@travetto/di": "^2.1.5",
+    "@travetto/config": "^2.2.0",
+    "@travetto/di": "^2.2.0",
     "@types/mustache": "^4.1.3",
     "mustache": "^4.2.0"
   },

package/src/extension/nodemailer.ts

@@ -20,8 +20,9 @@ export class NodemailerTransport implements MailTransport {
     this.#transport = nodemailer.createTransport(transportFactory);
   }
 
-  async send(mail: MessageOptions): Promise<SentMessage> {
-    const res = await this.#transport.sendMail(mail as nodemailer.SendMailOptions) as {
+  async send<S extends SentMessage = SentMessage>(mail: MessageOptions): Promise<S> {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const res = await this.#transport.sendMail(mail) as {
       messageId?: string;
       envelope?: Record<string, string>;
       accepted?: string[];
@@ -34,6 +35,7 @@ export class NodemailerTransport implements MailTransport {
       console.error('Unable to send emails', { recipientCount: res.rejected?.length });
     }
 
-    return res;
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return res as S;
   }
 }

package/src/service.ts

@@ -2,7 +2,7 @@ import { ResourceManager } from '@travetto/base';
 import { Injectable } from '@travetto/di';
 import { EnvUtil } from '@travetto/boot';
 
-import { MessageOptions } from './types';
+import { MessageOptions, SentMessage } from './types';
 import { MailTransport } from './transport';
 import { MailTemplateEngine } from './template';
 import { MailUtil } from './util';
@@ -28,8 +28,8 @@ export class MailService {
   /**
    * Send multiple messages.
    */
-  async sendAll(messages: MessageOptions[], base: Partial<MessageOptions> = {}) {
-    return Promise.all(messages.map(msg => this.send({
+  async sendAll<S extends SentMessage = SentMessage>(messages: MessageOptions[], base: Partial<MessageOptions> = {}): Promise<S[]> {
+    return Promise.all(messages.map(msg => this.send<S>({
       ...base,
       ...msg,
       ...(msg.context || base.context ? {
@@ -44,7 +44,7 @@ export class MailService {
   /**
    * Send a pre compiled email that has a relevant html, subject and optional text file associated
    */
-  async sendCompiled(key: string, msg: Omit<MessageOptions, 'html' | 'text' | 'subject'>): Promise<unknown> {
+  async sendCompiled<S extends SentMessage = SentMessage>(key: string, msg: Omit<MessageOptions, 'html' | 'text' | 'subject'>): Promise<S> {
     // Bypass cache if in dynamic mode
     if (EnvUtil.isDynamic() || !this.#compiled.has(key)) {
       const [html, text, subject] = await Promise.all([
@@ -55,13 +55,13 @@ export class MailService {
 
       this.#compiled.set(key, { html, text, subject });
     }
-    return this.send({ ...msg, ...this.#compiled.get(key)! });
+    return this.send<S>({ ...msg, ...this.#compiled.get(key)! });
   }
 
   /**
    * Send a single message
    */
-  async send(msg: MessageOptions): Promise<unknown> {
+  async send<S extends SentMessage>(msg: MessageOptions): Promise<S> {
     // Template if context is provided
     if (msg.context) {
       const [html, text, subject] = await Promise.all([
@@ -92,6 +92,6 @@ export class MailService {
       delete msg.html; // This is a hack to fix nodemailer
     }
 
-    return this.#transport.send(msg);
+    return this.#transport.send<S>(msg);
   }
 }

package/src/template.ts

@@ -42,7 +42,7 @@ export class MustacheTemplateEngine implements MailTemplateEngine {
   /**
    * Interpolate text with data
    */
-  template(text: string, data: Record<string, unknown>) {
+  template(text: string, data: Record<string, unknown>): string {
     return Mustache.render(text, data);
   }
 }

package/src/transport.ts

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

package/src/types.ts

@@ -1,3 +1,4 @@
+import { Readable } from 'stream';
 import { Url } from 'url';
 
 /**
@@ -12,7 +13,7 @@ export interface Address {
  * An attachment for the email
  */
 interface AttachmentLike {
-  content?: string | Buffer | NodeJS.ReadableStream;
+  content?: string | Buffer | Readable;
   path?: string | Url;
 }
 
@@ -24,10 +25,10 @@ export interface Attachment extends AttachmentLike {
   cid?: string;
   encoding?: string;
   contentType?: string;
-  contentTransferEncoding?: string;
-  contentDisposition?: string;
+  contentTransferEncoding?: false | '7bit' | 'base64' | 'quoted-printable';
+  contentDisposition?: 'attachment' | 'inline';
   headers?: Record<string, string | string[]>;
-  raw?: string | Buffer | NodeJS.ReadableStream | AttachmentLike;
+  raw?: string | Buffer | Readable | AttachmentLike;
 }
 
 /**

package/src/util.ts

@@ -9,7 +9,7 @@ export class MailUtil {
    *
    * @param html
    */
-  static async extractImageAttachments(html: string) {
+  static async extractImageAttachments(html: string): Promise<{ html: string, attachments: Attachment[] }> {
     let idx = 0;
     const attachments: Attachment[] = [];
     const contentMap = new Map<string, string>();