feat: add inline images to draft uploads

Author: ksambhi

email/mailmerge-cli/src/commands/upload-drafts.ts

@@ -34,6 +34,11 @@ export default class UploadDrafts extends Command {
             char: "n",
             description: "Only send this many emails (i.e. the first X emails)",
         }),
+        inlineImages: Flags.string({
+            char: "i",
+            description:
+                "Path to a JSON file containing informationa about inline images - see InlineImagesSpec type for format",
+        }),
     };
 
     public async run(): Promise<void> {
@@ -49,6 +54,7 @@ export default class UploadDrafts extends Command {
         await uploadDrafts(storageBackend, ENGINES_MAP, flags.yes, {
             sleepBetween: flags.sleepBetween,
             onlySend: flags.only,
+            inlineImages: flags.inlineImages,
         });
     }
 }

email/mailmerge/src/engines/index.ts

@@ -13,7 +13,7 @@
  * For example, the {@link NunjucksMarkdownEngine} will return a markdown preview and an HTML preview,
  * and will allow the user to edit the markdown preview and then rerender the HTML preview.
  * 
- * ### Example simpl usage:
+ * ### Example simple usage:
  * ```typescript
  * import { NunjucksMarkdownEngine } from '@docsoc/mailmerge';
  * 

email/mailmerge/src/engines/react/index.ts

@@ -5,12 +5,14 @@ import React from "react";
 import { MappedRecord } from "../../util/types.js";
 import { TemplateEngine, TemplateEngineOptions, TemplatePreviews } from "../types.js";
 
+/** Valid types we can pass through as props to rendered templates */
 export enum PropTypes {
     String = "string",
     Number = "number",
     Boolean = "boolean",
+    /** Supported when using JSON as a data source */
     Array = "array",
-    /** An arbitrary object */
+    /** An arbitrary object (supported when using JSON as a data source) */
     Object = "object",
 }
 
@@ -31,7 +33,7 @@ export interface ReactEmailEngineExports<
      */
     parameters: () => Record<string, PropTypes>;
     /**
-     * Return the template engine itself - essentially a function that takes a T and return a React component./
+     * Return the template engine itself as the default export - essentially a function that takes a T and return a React component./
      */
     default: React.FC<T>;
 }
@@ -45,12 +47,16 @@ export interface ReactEmailEngineOptions {
     [key: string]: string;
 }
 
+/** Sidecar metadata to store in sidecar files mailmerge generates so we can reload templates later */
 export interface ReactEmailSidecarMetadata {
     type: "react";
+    /** Store the path to the original JSX file we loaded, so we can rerun the render method */
     templatePath: string;
+    // Needed or TS complains
     [key: string]: unknown;
 }
 
+// TS hack to get type inference on the arbitrary option object mailmerge gives us
 function assertIsReactEmailTemplateOptions(
     options: Record<string, unknown>,
 ): asserts options is ReactEmailEngineOptions {
@@ -64,7 +70,9 @@ function assertIsReactEmailTemplateOptions(
  *
  * The email engine here returns one preview, which contains the HTML to send.
  *
- * On rerender, it will re-render the React component and return the new HTML.
+ * On rerender, it will re-render the React component (by reloading the original template that is stores) and return the new HTML.
+ * Through this, unlike nunjucks, we can update our template and run re-render to update the outputs
+ * (in nunjucks you can only edit the generated markdown files and rerender to generate the output HTML)
  */
 export default class ReactEmailEngine extends TemplateEngine {
     private loadedTemplate?: ReactEmailEngineExports;
@@ -119,13 +127,13 @@ export default class ReactEmailEngine extends TemplateEngine {
         ];
     }
     /**
-     * Re-rendering in react really m
+     * Re-rendering by reloading the template and regenerateing HTML
      */
     public override async rerenderPreviews(
         loadedPreviews: TemplatePreviews,
         associatedRecord: MappedRecord,
     ): Promise<TemplatePreviews> {
-        // 1: do we have at least one preview?
+        // 1: do we have at least one preview? (we only generate one preview, see renderPreview)
         if (loadedPreviews.length === 0) {
             throw new Error("No previews to re-render");
         }
@@ -156,7 +164,7 @@ export default class ReactEmailEngine extends TemplateEngine {
         ];
     }
 
-    /** Return the first preview */
+    /** Return the first preview as we only generate one that being the HTML to send */
     public override async getHTMLToSend(loadedPreviews: TemplatePreviews): Promise<string> {
         return loadedPreviews[0].content;
     }

email/mailmerge/src/graph/uploadDrafts.ts

@@ -84,8 +84,9 @@ export class EmailUploader {
      * Upload attachments to a created message
      * @param path Path to attachment to upload
      * @param messageID ID of the message to upload the attachment to
+     * @param cid Optional ContentID to upload under for use in IMG tags.
      */
-    private async uploadFile(path: string, messageID: string) {
+    private async uploadFile(path: string, messageID: string, cid?: string) {
         this.logger.info(`Uploading file ${path}...`);
         if (!this.client) {
             throw new Error("Client not authenticated");
@@ -108,6 +109,7 @@ export class EmailUploader {
                         attachmentType: "file",
                         name: filename,
                         size: fileStats.size,
+                        contentId: cid,
                     },
                 });
             const { uploadUrl } = uploadSession;
@@ -187,15 +189,15 @@ export class EmailUploader {
      * @param to List of email addresses to send to
      * @param subject Subject of the email
      * @param html HTML content of the email
-     * @param attachmentPaths List of paths to attachments to upload
+     * @param attachmentPaths List of paths to attachments to upload, with their CIDs if needed
      * @param additionalInfo Additional info for the email (cc, bcc)
      * @param options Options for the uploader (e.g. enabling hacks to get around Outlook limitations)
      */
     public async uploadEmail(
         to: string[],
         subject: string,
         html: string,
-        attachmentPaths: string[] = [],
+        attachmentPaths: (string | { path: string; cid: string })[] = [],
         additionalInfo: { cc: EmailString[]; bcc: EmailString[] } = { cc: [], bcc: [] },
         options: {
             /**
@@ -246,7 +248,11 @@ export class EmailUploader {
             if (attachmentPaths.length > 0) {
                 this.logger.info("Uploading attachments...");
                 for (const path of attachmentPaths) {
-                    await this.uploadFile(path, response.id);
+                    if (typeof path === "string") {
+                        await this.uploadFile(path, response.id);
+                    } else {
+                        await this.uploadFile(path.path, response.id, path.cid);
+                    }
                 }
             }
         } catch (error) {

email/mailmerge/src/pipelines/send.ts

@@ -2,35 +2,23 @@ import { createLogger } from "@docsoc/util";
 import chalk from "chalk";
 // Load dotenv
 import "dotenv/config";
-import { promises as fs } from "fs";
 import readlineSync from "readline-sync";
 
 import { ENGINES_MAP } from "../engines/index.js";
 import { TemplateEngineConstructor } from "../engines/types.js";
 import Mailer from "../mailer/mailer.js";
+import { InlineImagesSpec, loadInlineImageJSON } from "../util/inline-images.js";
 import { EmailString, FromEmail } from "../util/types.js";
 import { StorageBackend, MergeResultWithMetadata, PostSendActionMode } from "./storage/types.js";
 
-/** See https://www.nodemailer.com/message/embedded-images/ */
-export interface InlineImage {
-    /** Filename to attach to email as */
-    filename: string;
-    /** Path to file relative to CWD */
-    path: string;
-    /** Content ID to use in the email */
-    cid: string;
-}
-
-export type InlineImagesSpec = InlineImage[];
-
 interface SendEmailsOptions {
     /** Time to sleep between sending emails to prevent hitting rate limits */
     sleepBetween?: number;
     /** Only send this many emails (i.e. the first X emails) */
     onlySend?: number;
     /** Send the top {@link onlySend} emails to this email as a test */
     testSendTo?: EmailString;
-    /** Path to JSON file conforming to {@link InlineImagesSpec} with attachments */
+    /** Path to JSON file conforming to a {@link InlineImagesSpec} with files to attach for use as inline images. */
     inlineImages?: string;
 }
 
@@ -46,7 +34,7 @@ const DEFAULT_SLEEP_BETWEEN = 0;
  * @param enginesMap Map of engine names to engine constructors, as we need to ask the engine what the HTML is to send from the result
  * @param disablePrompt If true, will not prompt the user before sending emails. Defaults to false (will prompt)
  * @param logger Logger to use for logging
- * @param options
+ * @param options Other options
  */
 export async function sendEmails(
     storageBackend: StorageBackend,
@@ -70,31 +58,7 @@ export async function sendEmails(
     let inlineImages: InlineImagesSpec = [];
     if (options.inlineImages) {
         logger.info("Loading inline images...");
-        inlineImages = JSON.parse(await fs.readFile(options.inlineImages, "utf-8"));
-        // Validate the inline images
-        if (!Array.isArray(inlineImages)) {
-            logger.error(
-                "Invalid inline images - must be an array of InlineImage objects. See https://www.nodemailer.com/message/embedded-images/ for format.",
-            );
-            throw new Error("Invalid inline images - must be an array of InlineImage objects.");
-        }
-        logger.info(`Loaded ${inlineImages.length} inline images.`);
-        // Check all the paths are valid (accessble) & have a cid & filename proprty
-        for (const image of inlineImages) {
-            if (
-                typeof image.filename !== "string" ||
-                typeof image.path !== "string" ||
-                typeof image.cid !== "string"
-            ) {
-                logger.error(
-                    "Invalid inline image - must have a filename, path, and cid property. Got ",
-                    image,
-                );
-                throw new Error(
-                    `Invalid inline image - must have a filename, path, and cid property. Got ${image}`,
-                );
-            }
-        }
+        inlineImages = await loadInlineImageJSON(options.inlineImages, logger);
     }
 
     // 1: Load data

email/mailmerge/src/pipelines/uploadDrafts.ts

@@ -7,13 +7,16 @@ import readlineSync from "readline-sync";
 import { TemplateEngineConstructor, ENGINES_MAP } from "../engines/index.js";
 import { EmailUploader } from "../graph/index.js";
 import { EmailString } from "../util/index.js";
+import { InlineImagesSpec, loadInlineImageJSON } from "../util/inline-images.js";
 import { StorageBackend, MergeResultWithMetadata, PostSendActionMode } from "./storage/index.js";
 
 interface UploadDraftsOptions {
     /** Time to sleep between sending emails to prevent hitting rate limits */
     sleepBetween?: number;
-    /** Only send this many emails (i.e. the first X emails) */
+    /** Only upload this many emails (i.e. the first X emails) */
     onlySend?: number;
+    /** Path to JSON file conforming to a {@link InlineImagesSpec} with files to attach for use as inline images. */
+    inlineImages?: string;
 }
 
 /**
@@ -55,6 +58,12 @@ export async function uploadDrafts(
     logger.info("Loading merge results...");
     const results = storageBackend.loadMergeResults();
 
+    let inlineImages: InlineImagesSpec = [];
+    if (options.inlineImages) {
+        logger.info("Loading inline images...");
+        inlineImages = await loadInlineImageJSON(options.inlineImages, logger);
+    }
+
     // For each sidecar, send the previews
     const pendingEmails: {
         to: EmailString[];
@@ -143,7 +152,7 @@ export async function uploadDrafts(
             to,
             subject,
             html,
-            attachments,
+            [...attachments, ...inlineImages],
             {
                 cc,
                 bcc,

email/mailmerge/src/util/inline-images.ts

@@ -0,0 +1,55 @@
+/** See https://www.nodemailer.com/message/embedded-images/ */
+
+/** How to specify a image we should attach as inline for sending */
+import { createLogger } from "@docsoc/util";
+import fs from "fs/promises";
+
+export interface InlineImage {
+    /** Filename to attach to email as */
+    filename: string;
+    /** Path to file relative to CWD */
+    path: string;
+    /** Content ID to use in the email - use <img src="cid:id123.png" /> if cid is id123.png, say */
+    cid: string;
+}
+
+export type InlineImagesSpec = InlineImage[];
+
+/**
+ * Load & Validate a JSON containing {@link InlineImagesSpec} for use for inline imags.
+ * @param path Path to inline images JSON
+ * @param logger Loggr to use
+ */
+export async function loadInlineImageJSON(
+    path: string,
+    logger = createLogger("docsoc"),
+): Promise<InlineImagesSpec> {
+    logger.info("Loading inline images...");
+    const inlineImages = JSON.parse(await fs.readFile(path, "utf-8"));
+    // Validate the inline images
+    if (!Array.isArray(inlineImages)) {
+        logger.error(
+            "Invalid inline images - must be an array of InlineImage objects. See https://www.nodemailer.com/message/embedded-images/ for format.",
+        );
+        throw new Error("Invalid inline images - must be an array of InlineImage objects.");
+    }
+    logger.info(`Loaded ${inlineImages.length} inline images.`);
+    // Check all the paths are valid (accessble) & have a cid & filename proprty
+    for (const image of inlineImages) {
+        if (
+            typeof image.filename !== "string" ||
+            typeof image.path !== "string" ||
+            typeof image.cid !== "string"
+        ) {
+            logger.error(
+                "Invalid inline image - must have a filename, path, and cid property. Got ",
+                image,
+            );
+            throw new Error(
+                `Invalid inline image - must have a filename, path, and cid property. Got ${image}`,
+            );
+        }
+    }
+
+    return inlineImages;
+}

email/mailmerge/src/util/types.ts

@@ -3,4 +3,3 @@ export type FromEmail = `"${string}" <${EmailString}>`;
 
 export type RawRecord = Record<string, unknown>;
 export type MappedRecord = Record<string, unknown>;
-