@deenruv/email-plugin 1.0.0

package/lib/src/handler/mock-events.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockEmailAddressChangeEvent = exports.mockPasswordResetEvent = exports.mockAccountRegistrationEvent = exports.mockOrderStateTransitionEvent = void 0;
+const generated_shop_types_1 = require("@deenruv/common/lib/generated-shop-types");
+const core_1 = require("@deenruv/core");
+exports.mockOrderStateTransitionEvent = new core_1.OrderStateTransitionEvent("ArrangingPayment", "PaymentSettled", {}, new core_1.Order({
+    id: "6",
+    currencyCode: core_1.CurrencyCode.USD,
+    createdAt: "2018-10-31T11:18:29.261Z",
+    updatedAt: "2018-10-31T15:24:17.000Z",
+    orderPlacedAt: "2018-10-31T13:54:17.000Z",
+    code: "T3EPGJKTVZPBD6Z9",
+    state: "ArrangingPayment",
+    active: true,
+    customer: new core_1.Customer({
+        id: "3",
+        firstName: "Test",
+        lastName: "Customer",
+        emailAddress: "test@test.com",
+    }),
+    lines: [
+        new core_1.OrderLine({
+            id: "5",
+            featuredAsset: {
+                preview: "/mailbox/placeholder-image",
+            },
+            productVariant: new core_1.ProductVariant({
+                id: "2",
+                name: "Curvy Monitor 24 inch",
+                sku: "C24F390",
+            }),
+            quantity: 1,
+            listPrice: 14374,
+            listPriceIncludesTax: true,
+            adjustments: [
+                {
+                    adjustmentSource: "Promotion:1",
+                    type: generated_shop_types_1.AdjustmentType.PROMOTION,
+                    amount: -1000,
+                    description: "$10 off computer equipment",
+                },
+            ],
+            taxLines: [],
+        }),
+        new core_1.OrderLine({
+            id: "6",
+            featuredAsset: {
+                preview: "/mailbox/placeholder-image",
+            },
+            productVariant: new core_1.ProductVariant({
+                id: "4",
+                name: "Hard Drive 1TB",
+                sku: "IHD455T1",
+            }),
+            quantity: 1,
+            listPrice: 3799,
+            listPriceIncludesTax: true,
+            adjustments: [],
+            taxLines: [],
+        }),
+    ],
+    subTotal: 15144,
+    subTotalWithTax: 18173,
+    shipping: 1000,
+    shippingLines: [
+        new core_1.ShippingLine({
+            listPrice: 1000,
+            listPriceIncludesTax: true,
+            taxLines: [{ taxRate: 20, description: "shipping tax" }],
+            shippingMethod: {
+                code: "express-flat-rate",
+                name: "Express Shipping",
+                description: "Express Shipping",
+                id: "2",
+            },
+        }),
+    ],
+    surcharges: [],
+    shippingAddress: {
+        fullName: "Test Customer",
+        company: "",
+        streetLine1: "6000 Pagac Land",
+        streetLine2: "",
+        city: "Port Kirsten",
+        province: "Avon",
+        postalCode: "ZU32 9CP",
+        country: "Cabo Verde",
+        phoneNumber: "",
+    },
+    payments: [],
+}));
+exports.mockAccountRegistrationEvent = new core_1.AccountRegistrationEvent({}, new core_1.User({
+    verified: false,
+    authenticationMethods: [
+        new core_1.NativeAuthenticationMethod({
+            identifier: "test@test.com",
+            verificationToken: "MjAxOC0xMS0xM1QxNToxNToxNC42ODda_US2U6UK1WZC7NDAX",
+        }),
+    ],
+    identifier: "test@test.com",
+}));
+exports.mockPasswordResetEvent = new core_1.PasswordResetEvent({}, new core_1.User({
+    identifier: "test@test.com",
+    authenticationMethods: [
+        new core_1.NativeAuthenticationMethod({
+            passwordResetToken: "MjAxOS0wNC0xNVQxMzozMDozOC43MjFa_MA2FR6HRZBW7JWD6",
+        }),
+    ],
+}));
+exports.mockEmailAddressChangeEvent = new core_1.IdentifierChangeRequestEvent({}, new core_1.User({
+    identifier: "old-address@test.com",
+    authenticationMethods: [
+        new core_1.NativeAuthenticationMethod({
+            pendingIdentifier: "new-address@test.com",
+            identifierChangeToken: "MjAxOS0wNC0xNVQxMzozMDozOC43MjFa_MA2FR6HRZBW7JWD6",
+        }),
+    ],
+}));
+//# sourceMappingURL=mock-events.js.map

package/lib/src/handler/mock-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-events.js","sourceRoot":"","sources":["../../../src/handler/mock-events.ts"],"names":[],"mappings":";;;AAAA,mFAA0E;AAC1E,wCAauB;AAEV,QAAA,6BAA6B,GAAG,IAAI,gCAAyB,CACxE,kBAAkB,EAClB,gBAAgB,EAChB,EAAS,EACT,IAAI,YAAK,CAAC;IACR,EAAE,EAAE,GAAG;IACP,YAAY,EAAE,mBAAY,CAAC,GAAG;IAC9B,SAAS,EAAE,0BAA0B;IACrC,SAAS,EAAE,0BAA0B;IACrC,aAAa,EAAE,0BAA0B;IACzC,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,kBAAkB;IACzB,MAAM,EAAE,IAAI;IACZ,QAAQ,EAAE,IAAI,eAAQ,CAAC;QACrB,EAAE,EAAE,GAAG;QACP,SAAS,EAAE,MAAM;QACjB,QAAQ,EAAE,UAAU;QACpB,YAAY,EAAE,eAAe;KAC9B,CAAC;IACF,KAAK,EAAE;QACL,IAAI,gBAAS,CAAC;YACZ,EAAE,EAAE,GAAG;YACP,aAAa,EAAE;gBACb,OAAO,EAAE,4BAA4B;aACtC;YACD,cAAc,EAAE,IAAI,qBAAc,CAAC;gBACjC,EAAE,EAAE,GAAG;gBACP,IAAI,EAAE,uBAAuB;gBAC7B,GAAG,EAAE,SAAS;aACf,CAAC;YACF,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,KAAK;YAChB,oBAAoB,EAAE,IAAI;YAC1B,WAAW,EAAE;gBACX;oBACE,gBAAgB,EAAE,aAAa;oBAC/B,IAAI,EAAE,qCAAc,CAAC,SAAS;oBAC9B,MAAM,EAAE,CAAC,IAAW;oBACpB,WAAW,EAAE,4BAA4B;iBAC1C;aACF;YACD,QAAQ,EAAE,EAAE;SACb,CAAC;QACF,IAAI,gBAAS,CAAC;YACZ,EAAE,EAAE,GAAG;YACP,aAAa,EAAE;gBACb,OAAO,EAAE,4BAA4B;aACtC;YACD,cAAc,EAAE,IAAI,qBAAc,CAAC;gBACjC,EAAE,EAAE,GAAG;gBACP,IAAI,EAAE,gBAAgB;gBACtB,GAAG,EAAE,UAAU;aAChB,CAAC;YACF,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,IAAI;YACf,oBAAoB,EAAE,IAAI;YAC1B,WAAW,EAAE,EAAE;YACf,QAAQ,EAAE,EAAE;SACb,CAAC;KACH;IACD,QAAQ,EAAE,KAAK;IACf,eAAe,EAAE,KAAK;IACtB,QAAQ,EAAE,IAAI;IACd,aAAa,EAAE;QACb,IAAI,mBAAY,CAAC;YACf,SAAS,EAAE,IAAI;YACf,oBAAoB,EAAE,IAAI;YAC1B,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC;YACxD,cAAc,EAAE;gBACd,IAAI,EAAE,mBAAmB;gBACzB,IAAI,EAAE,kBAAkB;gBACxB,WAAW,EAAE,kBAAkB;gBAC/B,EAAE,EAAE,GAAG;aACR;SACF,CAAC;KACH;IACD,UAAU,EAAE,EAAE;IACd,eAAe,EAAE;QACf,QAAQ,EAAE,eAAe;QACzB,OAAO,EAAE,EAAE;QACX,WAAW,EAAE,iBAAiB;QAC9B,WAAW,EAAE,EAAE;QACf,IAAI,EAAE,cAAc;QACpB,QAAQ,EAAE,MAAM;QAChB,UAAU,EAAE,UAAU;QACtB,OAAO,EAAE,YAAY;QACrB,WAAW,EAAE,EAAE;KAChB;IACD,QAAQ,EAAE,EAAE;CACb,CAAC,CACH,CAAC;AAEW,QAAA,4BAA4B,GAAG,IAAI,+BAAwB,CACtE,EAAS,EACT,IAAI,WAAI,CAAC;IACP,QAAQ,EAAE,KAAK;IACf,qBAAqB,EAAE;QACrB,IAAI,iCAA0B,CAAC;YAC7B,UAAU,EAAE,eAAe;YAC3B,iBAAiB,EAAE,mDAAmD;SACvE,CAAC;KACH;IACD,UAAU,EAAE,eAAe;CAC5B,CAAC,CACH,CAAC;AAEW,QAAA,sBAAsB,GAAG,IAAI,yBAAkB,CAC1D,EAAS,EACT,IAAI,WAAI,CAAC;IACP,UAAU,EAAE,eAAe;IAC3B,qBAAqB,EAAE;QACrB,IAAI,iCAA0B,CAAC;YAC7B,kBAAkB,EAAE,mDAAmD;SACxE,CAAC;KACH;CACF,CAAC,CACH,CAAC;AAEW,QAAA,2BAA2B,GAAG,IAAI,mCAA4B,CACzE,EAAS,EACT,IAAI,WAAI,CAAC;IACP,UAAU,EAAE,sBAAsB;IAClC,qBAAqB,EAAE;QACrB,IAAI,iCAA0B,CAAC;YAC7B,iBAAiB,EAAE,sBAAsB;YACzC,qBAAqB,EACnB,mDAAmD;SACtD,CAAC;KACH;CACF,CAAC,CACH,CAAC"}

package/lib/src/plugin.d.ts

@@ -0,0 +1,301 @@
+import { MiddlewareConsumer, NestModule, OnApplicationBootstrap, OnApplicationShutdown } from "@nestjs/common";
+import { ModuleRef } from "@nestjs/core";
+import { EventBus, JobQueueService, ProcessContext, Type } from "@deenruv/core";
+import { EmailProcessor } from "./email-processor";
+export { ReactComponentLoader } from "./template-loader/react-email-template-loader";
+export { ReactComponentEmailGenerator } from "./generator/react-email-generator";
+import { EmailPluginDevModeOptions, EmailPluginOptions, InitializedEmailPluginOptions } from "./types";
+/**
+ * @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
+ */
+export declare class EmailPlugin implements OnApplicationBootstrap, OnApplicationShutdown, NestModule {
+    private eventBus;
+    private moduleRef;
+    private emailProcessor;
+    private jobQueueService;
+    private processContext;
+    private options;
+    private static options;
+    private devMailbox;
+    private jobQueue;
+    private testingProcessor;
+    /** @internal */
+    constructor(eventBus: EventBus, moduleRef: ModuleRef, emailProcessor: EmailProcessor, jobQueueService: JobQueueService, processContext: ProcessContext, options: InitializedEmailPluginOptions);
+    /**
+     * Set the plugin options.
+     */
+    static init(options: EmailPluginOptions | EmailPluginDevModeOptions): Type<EmailPlugin>;
+    /** @internal */
+    onApplicationBootstrap(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    configure(consumer: MiddlewareConsumer): void;
+    private initInjectableStrategies;
+    private destroyInjectableStrategies;
+    private setupEventSubscribers;
+    private handleEvent;
+}