@deenruv/email-plugin 1.0.0

package/lib/src/plugin.js

@@ -0,0 +1,428 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var EmailPlugin_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailPlugin = exports.ReactComponentEmailGenerator = exports.ReactComponentLoader = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const core_2 = require("@deenruv/core");
+const common_2 = require("./common");
+const constants_1 = require("./constants");
+const dev_mailbox_1 = require("./dev-mailbox");
+const email_processor_1 = require("./email-processor");
+const file_based_template_loader_1 = require("./template-loader/file-based-template-loader");
+var react_email_template_loader_1 = require("./template-loader/react-email-template-loader");
+Object.defineProperty(exports, "ReactComponentLoader", { enumerable: true, get: function () { return react_email_template_loader_1.ReactComponentLoader; } });
+var react_email_generator_1 = require("./generator/react-email-generator");
+Object.defineProperty(exports, "ReactComponentEmailGenerator", { enumerable: true, get: function () { return react_email_generator_1.ReactComponentEmailGenerator; } });
+/**
+ * @description
+ * The EmailPlugin creates and sends transactional emails based on Deenruv events. By default, it uses an [MJML](https://mjml.io/)-based
+ * email generator to generate the email body and [Nodemailer](https://nodemailer.com/about/) to send the emails.
+ *
+ * ## High-level description
+ * Deenruv has an internal events system (see {@link EventBus}) that allows plugins to subscribe to events. The EmailPlugin is configured with {@link EmailEventHandler}s
+ * that listen for a specific event and when it is published, the handler defines which template to use to generate the resulting email.
+ *
+ * The plugin comes with a set of default handler for the following events:
+ * - Order confirmation
+ * - New customer email address verification
+ * - Password reset request
+ * - Email address change request
+ *
+ * You can also create your own handler and register them with the plugin - see the {@link EmailEventHandler} docs for more details.
+ *
+ * ## Installation
+ *
+ * `yarn add \@deenruv/email-plugin`
+ *
+ * or
+ *
+ * `npm install \@deenruv/email-plugin`
+ *
+ * @example
+ * ```ts
+ * import { defaultEmailHandlers, EmailPlugin } from '\@deenruv/email-plugin';
+ *
+ * const config: DeenruvConfig = {
+ *   // Add an instance of the plugin to the plugins array
+ *   plugins: [
+ *     EmailPlugin.init({
+ *       handler: defaultEmailHandlers,
+ *       templatePath: path.join(__dirname, 'static/email/templates'),
+ *       transport: {
+ *         type: 'smtp',
+ *         host: 'smtp.example.com',
+ *         port: 587,
+ *         auth: {
+ *           user: 'username',
+ *           pass: 'password',
+ *         }
+ *       },
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * ## Email templates
+ *
+ * In the example above, the plugin has been configured to look in `<app-root>/static/email/templates`
+ * for the email template files. If you used `\@deenruv/create` to create your application, the templates will have
+ * been copied to that location during setup.
+ *
+ * If you are installing the EmailPlugin separately, then you'll need to copy the templates manually from
+ * `node_modules/\@deenruv/email-plugin/templates` to a location of your choice, and then point the `templatePath` config
+ * property at that directory.
+ *
+ * * ### Dynamic Email Templates
+ * Instead of passing a static value to `templatePath`, use `templateLoader` to define a template path.
+ * ```ts
+ *   EmailPlugin.init({
+ *    ...,
+ *    templateLoader: new FileBasedTemplateLoader(my/order-confirmation/templates)
+ *   })
+ * ```
+ * ## Customizing templates
+ *
+ * Emails are generated from templates which use [MJML](https://mjml.io/) syntax. MJML is an open-source HTML-like markup
+ * language which makes the task of creating responsive email markup simple. By default, the templates are installed to
+ * `<project root>/deenruv/email/templates` and can be freely edited.
+ *
+ * Dynamic data such as the recipient's name or order items are specified using [Handlebars syntax](https://handlebarsjs.com/):
+ *
+ * ```html
+ * <p>Dear {{ order.customer.firstName }} {{ order.customer.lastName }},</p>
+ *
+ * <p>Thank you for your order!</p>
+ *
+ * <mj-table cellpadding="6px">
+ *   {{#each order.lines }}
+ *     <tr class="order-row">
+ *       <td>{{ quantity }} x {{ productVariant.name }}</td>
+ *       <td>{{ productVariant.quantity }}</td>
+ *       <td>{{ formatMoney totalPrice }}</td>
+ *     </tr>
+ *   {{/each}}
+ * </mj-table>
+ * ```
+ *
+ * ### Setting global variables using `globalTemplateVars`
+ *
+ * `globalTemplateVars` is an object that can be passed to the configuration of the Email Plugin with static object variables.
+ * You can also pass an async function that will be called with the `RequestContext` and the `Injector` so you can access services
+ * and e.g. load channel specific theme configurations.
+ *
+ * @example
+ * ```ts
+ * EmailPlugin.init({
+ *    globalTemplateVars: {
+ *      primaryColor: '#FF0000',
+ *      fromAddress: 'no-reply@ourstore.com'
+ *    }
+ * })
+ * ```
+ * or
+ * ```ts
+ * EmailPlugin.init({
+ *    globalTemplateVars: async (ctx, injector) => {
+ *      const myAsyncService = injector.get(MyAsyncService);
+ *      const asyncValue = await myAsyncService.get(ctx);
+ *      const channel = ctx.channel;
+ *      const { primaryColor } = channel.customFields.theme;
+ *      const theme = {
+ *         primaryColor,
+ *         asyncValue,
+ *      };
+ *      return theme;
+ *    }
+ * })
+ * ```
+ *
+ * ### Handlebars helpers
+ *
+ * The following helper functions are available for use in email templates:
+ *
+ * * `formatMoney`: Formats an amount of money (which are always stored as integers in Deenruv) as a decimal, e.g. `123` => `1.23`
+ * * `formatDate`: Formats a Date value with the [dateformat](https://www.npmjs.com/package/dateformat) package.
+ *
+ * ## Extending the default email handler
+ *
+ * The `defaultEmailHandlers` array defines the default handler such as for handling new account registration, order confirmation, password reset
+ * etc. These defaults can be extended by adding custom templates for languages other than the default, or even completely new types of emails
+ * which respond to any of the available [DeenruvEvents](/reference/typescript-api/events/).
+ *
+ * A good way to learn how to create your own email handler is to take a look at the
+ * [source code of the default handler](https://github.com/deenruv-ecommerce/deenruv/blob/master/packages/email-plugin/src/handler/default-email-handlers.ts).
+ * New handler are defined in exactly the same way.
+ *
+ * It is also possible to modify the default handler:
+ *
+ * ```ts
+ * // Rather than importing `defaultEmailHandlers`, you can
+ * // import the handler individually
+ * import {
+ *   orderConfirmationHandler,
+ *   emailVerificationHandler,
+ *   passwordResetHandler,
+ *   emailAddressChangeHandler,
+ * } from '\@deenruv/email-plugin';
+ * import { CustomerService } from '\@deenruv/core';
+ *
+ * // This allows you to then customize each handler to your needs.
+ * // For example, let's set a new subject line to the order confirmation:
+ * const myOrderConfirmationHandler = orderConfirmationHandler
+ *   .setSubject(`We received your order!`);
+ *
+ * // Another example: loading additional data and setting new
+ * // template variables.
+ * const myPasswordResetHandler = passwordResetHandler
+ *   .loadData(async ({ event, injector }) => {
+ *     const customerService = injector.get(CustomerService);
+ *     const customer = await customerService.findOneByUserId(event.ctx, event.user.id);
+ *     return { customer };
+ *   })
+ *   .setTemplateVars(event => ({
+ *     passwordResetToken: event.user.getNativeAuthenticationMethod().passwordResetToken,
+ *     customer: event.data.customer,
+ *   }));
+ *
+ * // Then you pass the handler to the EmailPlugin init method
+ * // individually
+ * EmailPlugin.init({
+ *   handler: [
+ *     myOrderConfirmationHandler,
+ *     myPasswordResetHandler,
+ *     emailVerificationHandler,
+ *     emailAddressChangeHandler,
+ *   ],
+ *   // ...
+ * }),
+ * ```
+ *
+ * For all available methods of extending a handler, see the {@link EmailEventHandler} documentation.
+ *
+ * ## Dynamic SMTP settings
+ *
+ * Instead of defining static transport settings, you can also provide a function that dynamically resolves
+ * channel aware transport settings.
+ *
+ * @example
+ * ```ts
+ * import { defaultEmailHandlers, EmailPlugin } from '\@deenruv/email-plugin';
+ * import { MyTransportService } from './transport.services.ts';
+ * const config: DeenruvConfig = {
+ *   plugins: [
+ *     EmailPlugin.init({
+ *       handler: defaultEmailHandlers,
+ *       templatePath: path.join(__dirname, 'static/email/templates'),
+ *       transport: (injector, ctx) => {
+ *         if (ctx) {
+ *           return injector.get(MyTransportService).getSettings(ctx);
+ *         } else {
+ *           return {
+ *             type: 'smtp',
+ *             host: 'smtp.example.com',
+ *             // ... etc.
+ *           }
+ *         }
+ *       }
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * ## Dev mode
+ *
+ * For development, the `transport` option can be replaced by `devMode: true`. Doing so configures Deenruv to use the
+ * file transport (See {@link FileTransportOptions}) and outputs emails as rendered HTML files in the directory specified by the
+ * `outputPath` property.
+ *
+ * ```ts
+ * EmailPlugin.init({
+ *   devMode: true,
+ *   route: 'mailbox',
+ *   handler: defaultEmailHandlers,
+ *   templatePath: path.join(__dirname, 'deenruv/email/templates'),
+ *   outputPath: path.join(__dirname, 'test-emails'),
+ * })
+ * ```
+ *
+ * ### Dev mailbox
+ *
+ * In dev mode, a webmail-like interface available at the `/mailbox` path, e.g.
+ * http://localhost:3000/mailbox. This is a simple way to view the output of all emails generated by the EmailPlugin while in dev mode.
+ *
+ * ## Troubleshooting SMTP Connections
+ *
+ * If you are having trouble sending email over and SMTP connection, set the `logging` and `debug` options to `true`. This will
+ * send detailed information from the SMTP transporter to the configured logger (defaults to console). For maximum detail combine
+ * this with a detail log level in the configured DeenruvLogger:
+ *
+ * ```ts
+ * const config: DeenruvConfig = {
+ *   logger: new DefaultLogger({ level: LogLevel.Debug })
+ *   // ...
+ *   plugins: [
+ *     EmailPlugin.init({
+ *       // ...
+ *       transport: {
+ *         type: 'smtp',
+ *         host: 'smtp.example.com',
+ *         port: 587,
+ *         auth: {
+ *           user: 'username',
+ *           pass: 'password',
+ *         },
+ *         logging: true,
+ *         debug: true,
+ *       },
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * @docsCategory core plugins/EmailPlugin
+ */
+let EmailPlugin = EmailPlugin_1 = class EmailPlugin {
+    /** @internal */
+    constructor(eventBus, moduleRef, emailProcessor, jobQueueService, processContext, options) {
+        this.eventBus = eventBus;
+        this.moduleRef = moduleRef;
+        this.emailProcessor = emailProcessor;
+        this.jobQueueService = jobQueueService;
+        this.processContext = processContext;
+        this.options = options;
+    }
+    /**
+     * Set the plugin options.
+     */
+    static init(options) {
+        if (options.templateLoader) {
+            core_2.Logger.info(`Using custom template loader '${options.templateLoader.constructor.name}'`);
+        }
+        else if (!options.templateLoader && options.templatePath) {
+            // TODO: this else-if can be removed when deprecated templatePath is removed,
+            // because we will either have a custom template loader, or the default loader with a default path
+            options.templateLoader = new file_based_template_loader_1.FileBasedTemplateLoader(options.templatePath);
+        }
+        else {
+            throw new Error("You must either supply a templatePath or provide a custom templateLoader");
+        }
+        this.options = options;
+        return EmailPlugin_1;
+    }
+    /** @internal */
+    async onApplicationBootstrap() {
+        await this.initInjectableStrategies();
+        await this.setupEventSubscribers();
+        const transport = await (0, common_2.resolveTransportSettings)(this.options, new core_2.Injector(this.moduleRef));
+        if (!(0, common_2.isDevModeOptions)(this.options) && transport.type === "testing") {
+            // When running tests, we don't want to go through the JobQueue system,
+            // so we just call the email sending logic directly.
+            this.testingProcessor = new email_processor_1.EmailProcessor(this.options, this.moduleRef, this.eventBus);
+            await this.testingProcessor.init();
+        }
+        else {
+            await this.emailProcessor.init();
+            this.jobQueue = await this.jobQueueService.createQueue({
+                name: "send-email",
+                process: (job) => {
+                    return this.emailProcessor.process(job.data);
+                },
+            });
+        }
+    }
+    async onApplicationShutdown() {
+        await this.destroyInjectableStrategies();
+    }
+    configure(consumer) {
+        if ((0, common_2.isDevModeOptions)(this.options) && this.processContext.isServer) {
+            core_2.Logger.info("Creating dev mailbox middleware", constants_1.loggerCtx);
+            this.devMailbox = new dev_mailbox_1.DevMailbox();
+            consumer
+                .apply(this.devMailbox.serve(this.options))
+                .forRoutes(this.options.route);
+            this.devMailbox.handleMockEvent((handler, event) => this.handleEvent(handler, event));
+            (0, core_2.registerPluginStartupMessage)("Dev mailbox", this.options.route);
+        }
+    }
+    async initInjectableStrategies() {
+        var _a, _b;
+        const injector = new core_2.Injector(this.moduleRef);
+        if (typeof ((_a = this.options.emailGenerator) === null || _a === void 0 ? void 0 : _a.init) === "function") {
+            await this.options.emailGenerator.init(injector);
+        }
+        if (typeof ((_b = this.options.emailSender) === null || _b === void 0 ? void 0 : _b.init) === "function") {
+            await this.options.emailSender.init(injector);
+        }
+    }
+    async destroyInjectableStrategies() {
+        var _a, _b;
+        if (typeof ((_a = this.options.emailGenerator) === null || _a === void 0 ? void 0 : _a.destroy) === "function") {
+            await this.options.emailGenerator.destroy();
+        }
+        if (typeof ((_b = this.options.emailSender) === null || _b === void 0 ? void 0 : _b.destroy) === "function") {
+            await this.options.emailSender.destroy();
+        }
+    }
+    async setupEventSubscribers() {
+        for (const handler of EmailPlugin_1.options.handlers) {
+            this.eventBus.ofType(handler.event).subscribe((event) => {
+                return this.handleEvent(handler, event);
+            });
+        }
+    }
+    async handleEvent(handler, event) {
+        core_2.Logger.debug(`Handling event "${handler.type}"`, constants_1.loggerCtx);
+        const { type } = handler;
+        try {
+            const injector = new core_2.Injector(this.moduleRef);
+            let globalTemplateVars = this.options.globalTemplateVars;
+            if (typeof globalTemplateVars === "function") {
+                globalTemplateVars = await globalTemplateVars(event.ctx, injector);
+            }
+            const result = await handler.handle(event, globalTemplateVars, injector);
+            if (!result) {
+                return;
+            }
+            if (this.jobQueue) {
+                await this.jobQueue.add(result, { retries: 5 });
+            }
+            else if (this.testingProcessor) {
+                await this.testingProcessor.process(result);
+            }
+        }
+        catch (e) {
+            core_2.Logger.error(e.message, constants_1.loggerCtx, e.stack);
+        }
+    }
+};
+exports.EmailPlugin = EmailPlugin;
+exports.EmailPlugin = EmailPlugin = EmailPlugin_1 = __decorate([
+    (0, core_2.DeenruvPlugin)({
+        imports: [core_2.PluginCommonModule],
+        providers: [
+            { provide: constants_1.EMAIL_PLUGIN_OPTIONS, useFactory: () => EmailPlugin.options },
+            email_processor_1.EmailProcessor,
+        ],
+        compatibility: "^0.0.0",
+    }),
+    __param(5, (0, common_1.Inject)(constants_1.EMAIL_PLUGIN_OPTIONS)),
+    __metadata("design:paramtypes", [core_2.EventBus,
+        core_1.ModuleRef,
+        email_processor_1.EmailProcessor,
+        core_2.JobQueueService,
+        core_2.ProcessContext, Object])
+], EmailPlugin);
+//# sourceMappingURL=plugin.js.map

package/lib/src/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/plugin.ts"],"names":[],"mappings":"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"}

package/lib/src/sender/email-sender.d.ts

@@ -0,0 +1,45 @@
+import { InjectableStrategy } from "@deenruv/core";
+import { EmailDetails, EmailTransportOptions } from "../types";
+/**
+ * @description
+ * An EmailSender is responsible for sending the email, e.g. via an SMTP connection
+ * or using some other mail-sending API. By default, the EmailPlugin uses the
+ * {@link NodemailerEmailSender}, but it is also possible to supply a custom implementation:
+ *
+ * @example
+ * ```ts
+ * const sgMail = require('\@sendgrid/mail');
+ *
+ * sgMail.setApiKey(process.env.SENDGRID_API_KEY);
+ *
+ * class SendgridEmailSender implements EmailSender {
+ *   async send(email: EmailDetails) {
+ *     await sgMail.send({
+ *       to: email.recipient,
+ *       from: email.from,
+ *       subject: email.subject,
+ *       html: email.body,
+ *     });
+ *   }
+ * }
+ *
+ * const config: DeenruvConfig = {
+ *   logger: new DefaultLogger({ level: LogLevel.Debug })
+ *   // ...
+ *   plugins: [
+ *     EmailPlugin.init({
+ *        // ... template, handler config omitted
+ *       transport: { type: 'none' },
+ *        emailSender: new SendgridEmailSender(),
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * @docsCategory core plugins/EmailPlugin
+ * @docsPage EmailSender
+ * @docsWeight 0
+ */
+export interface EmailSender extends InjectableStrategy {
+    send: (email: EmailDetails, options: EmailTransportOptions) => void | Promise<void>;
+}

package/lib/src/sender/email-sender.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=email-sender.js.map

package/lib/src/sender/email-sender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-sender.js","sourceRoot":"","sources":["../../../src/sender/email-sender.ts"],"names":[],"mappings":""}

package/lib/src/sender/nodemailer-email-sender.d.ts

@@ -0,0 +1,37 @@
+/// <reference types="node" />
+import { Stream } from "stream";
+import { EmailDetails, EmailTransportOptions } from "../types";
+import { EmailSender } from "./email-sender";
+export type StreamTransportInfo = {
+    envelope: {
+        from: string;
+        to: string[];
+    };
+    messageId: string;
+    message: Stream;
+};
+/**
+ * @description
+ * Uses the configured transport to send the generated email.
+ *
+ * @docsCategory core plugins/EmailPlugin
+ * @docsPage EmailSender
+ */
+export declare class NodemailerEmailSender implements EmailSender {
+    private _smtpTransport;
+    private _sendMailTransport;
+    private _sesTransport;
+    send(email: EmailDetails, options: EmailTransportOptions): Promise<undefined>;
+    private getSmtpTransport;
+    private getSesTransport;
+    private getSendMailTransport;
+    private sendMail;
+    private sendFileJson;
+    private sendFileRaw;
+    private writeStreamToFile;
+    /**
+     * Adapts the DeenruvLogger to work with the bunyan-compatible logger format
+     * used by Nodemailer.
+     */
+    private createLogger;
+}

package/lib/src/sender/nodemailer-email-sender.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodemailerEmailSender = void 0;
+const normalize_string_1 = require("@deenruv/common/lib/normalize-string");
+const shared_utils_1 = require("@deenruv/common/lib/shared-utils");
+const core_1 = require("@deenruv/core");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const nodemailer_1 = require("nodemailer");
+const path_1 = __importDefault(require("path"));
+const util_1 = require("util");
+const constants_1 = require("../constants");
+/**
+ * @description
+ * Uses the configured transport to send the generated email.
+ *
+ * @docsCategory core plugins/EmailPlugin
+ * @docsPage EmailSender
+ */
+class NodemailerEmailSender {
+    async send(email, options) {
+        switch (options.type) {
+            case "none":
+                return;
+                break;
+            case "file":
+                const fileName = (0, normalize_string_1.normalizeString)(`${new Date().toISOString()} ${email.recipient} ${email.subject}`, "_");
+                const filePath = path_1.default.join(options.outputPath, fileName);
+                if (options.raw) {
+                    await this.sendFileRaw(email, filePath);
+                }
+                else {
+                    await this.sendFileJson(email, filePath);
+                }
+                break;
+            case "sendmail":
+                await this.sendMail(email, this.getSendMailTransport(options));
+                break;
+            case "ses":
+                await this.sendMail(email, this.getSesTransport(options));
+                break;
+            case "smtp":
+                await this.sendMail(email, this.getSmtpTransport(options));
+                break;
+            case "testing":
+                options.onSend(email);
+                break;
+            default:
+                return (0, shared_utils_1.assertNever)(options);
+        }
+    }
+    getSmtpTransport(options) {
+        if (!this._smtpTransport) {
+            options.logger = options.logging ? this.createLogger() : false;
+            this._smtpTransport = (0, nodemailer_1.createTransport)(options);
+        }
+        return this._smtpTransport;
+    }
+    getSesTransport(options) {
+        if (!this._sesTransport) {
+            this._sesTransport = (0, nodemailer_1.createTransport)(options);
+        }
+        return this._sesTransport;
+    }
+    getSendMailTransport(options) {
+        if (!this._sendMailTransport) {
+            this._sendMailTransport = (0, nodemailer_1.createTransport)(Object.assign({ sendmail: true }, options));
+        }
+        return this._sendMailTransport;
+    }
+    async sendMail(email, transporter) {
+        return transporter.sendMail({
+            from: email.from,
+            to: email.recipient,
+            subject: email.subject,
+            html: email.body,
+            attachments: email.attachments,
+            cc: email.cc,
+            bcc: email.bcc,
+            replyTo: email.replyTo,
+        });
+    }
+    async sendFileJson(email, pathWithoutExt) {
+        const output = {
+            date: new Date().toLocaleString(),
+            from: email.from,
+            recipient: email.recipient,
+            subject: email.subject,
+            body: email.body,
+            cc: email.cc,
+            bcc: email.bcc,
+            replyTo: email.replyTo,
+        };
+        await fs_extra_1.default.writeFile(pathWithoutExt + ".json", JSON.stringify(output, null, 2));
+    }
+    async sendFileRaw(email, pathWithoutExt) {
+        const transporter = (0, nodemailer_1.createTransport)({
+            streamTransport: true,
+            buffer: true,
+        });
+        const result = await this.sendMail(email, transporter);
+        await this.writeStreamToFile(pathWithoutExt + ".txt", result);
+    }
+    async writeStreamToFile(filePath, info) {
+        const writeStream = fs_extra_1.default.createWriteStream(filePath);
+        return new Promise((resolve, reject) => {
+            writeStream.on("open", () => {
+                info.message.pipe(writeStream);
+                writeStream.on("close", () => resolve(filePath));
+                writeStream.on("error", reject);
+            });
+        });
+    }
+    /**
+     * Adapts the DeenruvLogger to work with the bunyan-compatible logger format
+     * used by Nodemailer.
+     */
+    createLogger() {
+        function formatError(args) {
+            const [ctx, message, ...params] = args;
+            return (0, util_1.format)(message, ...params);
+        }
+        return {
+            level(level) {
+                /* noop */
+            },
+            trace(...params) {
+                core_1.Logger.debug(formatError(params), constants_1.loggerCtx);
+            },
+            debug(...params) {
+                core_1.Logger.verbose(formatError(params), constants_1.loggerCtx);
+            },
+            info(...params) {
+                core_1.Logger.info(formatError(params), constants_1.loggerCtx);
+            },
+            warn(...params) {
+                core_1.Logger.warn(formatError(params), constants_1.loggerCtx);
+            },
+            error(...params) {
+                core_1.Logger.error(formatError(params), constants_1.loggerCtx);
+            },
+            fatal(...params) {
+                core_1.Logger.error(formatError(params), constants_1.loggerCtx);
+            },
+        };
+    }
+}
+exports.NodemailerEmailSender = NodemailerEmailSender;
+//# sourceMappingURL=nodemailer-email-sender.js.map