@vendure/email-plugin 2.0.0-next.9 → 2.0.1

package/lib/src/types.d.ts

@@ -1,7 +1,11 @@
 import { LanguageCode } from '@vendure/common/lib/generated-types';
 import { Omit } from '@vendure/common/lib/omit';
-import { Injector, RequestContext, VendureEvent } from '@vendure/core';
+import { Injector, RequestContext, SerializedRequestContext, VendureEvent } from '@vendure/core';
 import { Attachment } from 'nodemailer/lib/mailer';
+import SESTransport from 'nodemailer/lib/ses-transport';
+import SMTPTransport from 'nodemailer/lib/smtp-transport';
+import { EmailGenerator } from './email-generator';
+import { EmailSender } from './email-sender';
 import { EmailEventHandler } from './event-handler';
 /**
  * @description
@@ -9,10 +13,10 @@ import { EmailEventHandler } from './event-handler';
  * {@link RequestContext}, which is used to determine the channel and language
  * to use when generating the email.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Email Plugin Types
  */
-export declare type EventWithContext = VendureEvent & {
+export type EventWithContext = VendureEvent & {
     ctx: RequestContext;
 };
 /**
@@ -20,17 +24,17 @@ export declare type EventWithContext = VendureEvent & {
  * A VendureEvent with a {@link RequestContext} and a `data` property which contains the
  * value resolved from the {@link EmailEventHandler}`.loadData()` callback.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Email Plugin Types
  */
-export declare type EventWithAsyncData<Event extends EventWithContext, R> = Event & {
+export type EventWithAsyncData<Event extends EventWithContext, R> = Event & {
     data: R;
 };
 /**
  * @description
  * Configuration for the EmailPlugin.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage EmailPluginOptions
  * */
 export interface EmailPluginOptions {
@@ -38,13 +42,23 @@ export interface EmailPluginOptions {
      * @description
      * The path to the location of the email templates. In a default Vendure installation,
      * the templates are installed to `<project root>/vendure/email/templates`.
+     *
+     * @deprecated Use `templateLoader` to define a template path: `templateLoader: new FileBasedTemplateLoader('../your-path/templates')`
+     */
+    templatePath?: string;
+    /**
+     * @description
+     * An optional TemplateLoader which can be used to load templates from a custom location or async service.
+     * The default uses the FileBasedTemplateLoader which loads templates from `<project root>/vendure/email/templates`
+     *
+     * @since 2.0.0
      */
-    templatePath: string;
+    templateLoader?: TemplateLoader;
     /**
      * @description
      * Configures how the emails are sent.
      */
-    transport: EmailTransportOptions;
+    transport: EmailTransportOptions | ((injector?: Injector, ctx?: RequestContext) => EmailTransportOptions | Promise<EmailTransportOptions>);
     /**
      * @description
      * An array of {@link EmailEventHandler}s which define which Vendure events will trigger
@@ -77,11 +91,17 @@ export interface EmailPluginOptions {
      */
     emailGenerator?: EmailGenerator;
 }
+/**
+ * EmailPLuginOptions type after initialization, where templateLoader is no longer optional
+ */
+export type InitializedEmailPluginOptions = EmailPluginOptions & {
+    templateLoader: TemplateLoader;
+};
 /**
  * @description
  * Configuration for running the EmailPlugin in development mode.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage EmailPluginOptions
  */
 export interface EmailPluginDevModeOptions extends Omit<EmailPluginOptions, 'transport'> {
@@ -97,81 +117,23 @@ export interface EmailPluginDevModeOptions extends Omit<EmailPluginOptions, 'tra
      */
     route: string;
 }
-/**
- * @description
- * The credentials used for sending email via SMTP
- *
- * @docsCategory EmailPlugin
- * @docsPage Email Plugin Types
- */
-export interface SMTPCredentials {
-    /** @description The username */
-    user: string;
-    /** @description The password */
-    pass: string;
-}
 /**
  * @description
  * A union of all the possible transport options for sending emails.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Transport Options
  */
-export declare type EmailTransportOptions = SMTPTransportOptions | SendmailTransportOptions | FileTransportOptions | NoopTransportOptions | TestingTransportOptions;
+export type EmailTransportOptions = SMTPTransportOptions | SendmailTransportOptions | FileTransportOptions | NoopTransportOptions | SESTransportOptions | TestingTransportOptions;
 /**
  * @description
- * A subset of the SMTP transport options of [Nodemailer](https://nodemailer.com/smtp/)
+ * The SMTP transport options of [Nodemailer](https://nodemailer.com/smtp/)
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Transport Options
  */
-export interface SMTPTransportOptions {
+export interface SMTPTransportOptions extends SMTPTransport.Options {
     type: 'smtp';
-    /**
-     * @description
-     * the hostname or IP address to connect to (defaults to ‘localhost’)
-     */
-    host: string;
-    /**
-     * @description
-     * The port to connect to (defaults to 25 or 465)
-     */
-    port: number;
-    /**
-     * @description
-     * Defines authentication data
-     */
-    auth: SMTPCredentials;
-    /**
-     * @description
-     * Defines if the connection should use SSL (if true) or not (if false)
-     */
-    secure?: boolean;
-    /**
-     * @description
-     * Turns off STARTTLS support if true
-     */
-    ignoreTLS?: boolean;
-    /**
-     * @description
-     * Forces the client to use STARTTLS. Returns an error if upgrading the connection is not possible or fails.
-     */
-    requireTLS?: boolean;
-    /**
-     * @description
-     * Optional hostname of the client, used for identifying to the server
-     */
-    name?: string;
-    /**
-     * @description
-     * The local interface to bind to for network connections
-     */
-    localAddress?: string;
-    /**
-     * @description
-     * Defines preferred authentication method, e.g. ‘PLAIN’
-     */
-    authMethod?: string;
     /**
      * @description
      * If true, uses the configured {@link VendureLogger} to log messages from Nodemailer as it interacts with
@@ -180,26 +142,52 @@ export interface SMTPTransportOptions {
      * @default false
      */
     logging?: boolean;
-    /**
-     * @description
-     * If set to true, then logs SMTP traffic without message content.
-     *
-     * @default false
-     */
-    transactionLog?: boolean;
-    /**
-     * @description
-     * If set to true, then logs SMTP traffic and message content, otherwise logs only transaction events.
-     *
-     * @default false
-     */
-    debug?: boolean;
+}
+/**
+ * @description
+ * The SES transport options of [Nodemailer](https://nodemailer.com/transports/ses//)
+ *
+ * See [Nodemailers's SES docs](https://nodemailer.com/transports/ses/) for more details
+ *
+ * @example
+ * ```TypeScript
+ *  import { SES, SendRawEmailCommand } from '\@aws-sdk/client-ses'
+ *
+ *  const ses = new SES({
+ *     apiVersion: '2010-12-01',
+ *     region: 'eu-central-1',
+ *     credentials: {
+ *         accessKeyId: process.env.SES_ACCESS_KEY || '',
+ *         secretAccessKey: process.env.SES_SECRET_KEY || '',
+ *     },
+ *  })
+ *
+ *  const config: VendureConfig = {
+ *   // Add an instance of the plugin to the plugins array
+ *   plugins: [
+ *     EmailPlugin.init({
+ *       handlers: defaultEmailHandlers,
+ *       templatePath: path.join(__dirname, 'static/email/templates'),
+ *       transport: {
+ *         type: 'ses',
+ *         SES: { ses, aws: { SendRawEmailCommand } },
+ *         sendingRate: 10, // optional messages per second sending rate
+ *       },
+ *     }),
+ *   ],
+ * };
+ *  ```
+ * @docsCategory core plugins/EmailPlugin
+ * @docsPage Transport Options
+ */
+export interface SESTransportOptions extends SESTransport.Options {
+    type: 'ses';
 }
 /**
  * @description
  * Uses the local Sendmail program to send the email.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Transport Options
  */
 export interface SendmailTransportOptions {
@@ -213,7 +201,7 @@ export interface SendmailTransportOptions {
  * @description
  * Outputs the email as an HTML file for development purposes.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Transport Options
  */
 export interface FileTransportOptions {
@@ -228,7 +216,7 @@ export interface FileTransportOptions {
  * Does nothing with the generated email. Intended for use in testing where we don't care about the email transport,
  * or when using a custom {@link EmailSender} which does not require transport options.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Transport Options
  */
 export interface NoopTransportOptions {
@@ -238,7 +226,7 @@ export interface NoopTransportOptions {
  * @description
  * The final, generated email details to be sent.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Email Plugin Types
  */
 export interface EmailDetails<Type extends 'serialized' | 'unserialized' = 'unserialized'> {
@@ -255,7 +243,7 @@ export interface EmailDetails<Type extends 'serialized' | 'unserialized' = 'unse
  * @description
  * Forwards the raw GeneratedEmailContext object to a provided callback, for use in testing.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Transport Options
  */
 export interface TestingTransportOptions {
@@ -266,84 +254,18 @@ export interface TestingTransportOptions {
      */
     onSend: (details: EmailDetails) => void;
 }
-/**
- * @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
- * ```TypeScript
- * 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: VendureConfig = {
- *   logger: new DefaultLogger({ level: LogLevel.Debug })
- *   // ...
- *   plugins: [
- *     EmailPlugin.init({
- *        // ... template, handlers config omitted
- *       transport: { type: 'none' },
- *        emailSender: new SendgridEmailSender(),
- *     }),
- *   ],
- * };
- * ```
- *
- * @docsCategory EmailPlugin
- * @docsPage EmailSender
- * @docsWeight 0
- */
-export interface EmailSender {
-    send: (email: EmailDetails, options: EmailTransportOptions) => void | Promise<void>;
-}
-/**
- * @description
- * An EmailGenerator generates the subject and body details of an email.
- *
- * @docsCategory EmailPlugin
- * @docsPage EmailGenerator
- * @docsWeight 0
- */
-export interface EmailGenerator<T extends string = any, E extends VendureEvent = any> {
-    /**
-     * @description
-     * Any necessary setup can be performed here.
-     */
-    onInit?(options: EmailPluginOptions): void | Promise<void>;
-    /**
-     * @description
-     * Given a subject and body from an email template, this method generates the final
-     * interpolated email text.
-     */
-    generate(from: string, subject: string, body: string, templateVars: {
-        [key: string]: any;
-    }): Pick<EmailDetails, 'from' | 'subject' | 'body'>;
-}
 /**
  * @description
  * A function used to load async data for use by an {@link EmailEventHandler}.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Email Plugin Types
  */
-export declare type LoadDataFn<Event extends EventWithContext, R> = (context: {
+export type LoadDataFn<Event extends EventWithContext, R> = (context: {
     event: Event;
     injector: Injector;
 }) => Promise<R>;
-export declare type OptionalToNullable<O> = {
+export type OptionalToNullable<O> = {
     [K in keyof O]-?: undefined extends O[K] ? NonNullable<O[K]> | null : O[K];
 };
 /**
@@ -353,16 +275,17 @@ export declare type OptionalToNullable<O> = {
  * only uses the `path` property to define a filesystem path or a URL pointing to
  * the attachment file.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Email Plugin Types
  */
-export declare type EmailAttachment = Omit<Attachment, 'raw'> & {
+export type EmailAttachment = Omit<Attachment, 'raw'> & {
     path?: string;
 };
-export declare type SerializedAttachment = OptionalToNullable<Omit<EmailAttachment, 'content'> & {
+export type SerializedAttachment = OptionalToNullable<Omit<EmailAttachment, 'content'> & {
     content: string | null;
 }>;
-export declare type IntermediateEmailDetails = {
+export type IntermediateEmailDetails = {
+    ctx: SerializedRequestContext;
     type: string;
     from: string;
     recipient: string;
@@ -379,8 +302,7 @@ export declare type IntermediateEmailDetails = {
  * Configures the {@link EmailEventHandler} to handle a particular channel & languageCode
  * combination.
  *
- * @docsCategory EmailPlugin
- * @docsPage Email Plugin Types
+ * @deprecated Use a custom {@link TemplateLoader} instead.
  */
 export interface EmailTemplateConfig {
     /**
@@ -407,15 +329,60 @@ export interface EmailTemplateConfig {
      */
     subject: string;
 }
+export interface LoadTemplateInput {
+    type: string;
+    templateName: string;
+}
+export interface Partial {
+    name: string;
+    content: string;
+}
+/**
+ * @description
+ * Load an email template based on the given request context, type and template name
+ * and return the template as a string.
+ *
+ * @example
+ * ```TypeScript
+ * import { EmailPlugin, TemplateLoader } from '@vendure/email-plugin';
+ *
+ * class MyTemplateLoader implements TemplateLoader {
+ *      loadTemplate(injector, ctx, { type, templateName }){
+ *          return myCustomTemplateFunction(ctx);
+ *      }
+ * }
+ *
+ * // In vendure-config.ts:
+ * ...
+ * EmailPlugin.init({
+ *     templateLoader: new MyTemplateLoader()
+ *     ...
+ * })
+ * ```
+ *
+ * @docsCategory core plugins/EmailPlugin
+ * @docsPage Custom Template Loader
+ */
+export interface TemplateLoader {
+    /**
+     * Load template and return it's content as a string
+     */
+    loadTemplate(injector: Injector, ctx: RequestContext, input: LoadTemplateInput): Promise<string>;
+    /**
+     * Load partials and return their contents.
+     * This method is only called during initalization, i.e. during server startup.
+     */
+    loadPartials?(): Promise<Partial[]>;
+}
 /**
  * @description
  * A function used to define template variables available to email templates.
  * See {@link EmailEventHandler}.setTemplateVars().
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Email Plugin Types
  */
-export declare type SetTemplateVarsFn<Event> = (event: Event, globals: {
+export type SetTemplateVarsFn<Event> = (event: Event, globals: {
     [key: string]: any;
 }) => {
     [key: string]: any;
@@ -426,16 +393,16 @@ export declare type SetTemplateVarsFn<Event> = (event: Event, globals: {
  * See https://nodemailer.com/message/attachments/ for more information about
  * how attachments work in Nodemailer.
  *
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Email Plugin Types
  */
-export declare type SetAttachmentsFn<Event> = (event: Event) => EmailAttachment[] | Promise<EmailAttachment[]>;
+export type SetAttachmentsFn<Event> = (event: Event) => EmailAttachment[] | Promise<EmailAttachment[]>;
 /**
  * @description
  * Optional address-related fields for sending the email.
  *
  * @since 1.1.0
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Email Plugin Types
  */
 export interface OptionalAddressFields {
@@ -460,7 +427,7 @@ export interface OptionalAddressFields {
  * A function used to set the {@link OptionalAddressFields}.
  *
  * @since 1.1.0
- * @docsCategory EmailPlugin
+ * @docsCategory core plugins/EmailPlugin
  * @docsPage Email Plugin Types
  */
-export declare type SetOptionalAddressFieldsFn<Event> = (event: Event) => OptionalAddressFields | Promise<OptionalAddressFields>;
+export type SetOptionalAddressFieldsFn<Event> = (event: Event) => OptionalAddressFields | Promise<OptionalAddressFields>;

package/package.json

@@ -1,44 +1,44 @@
 {
-  "name": "@vendure/email-plugin",
-  "version": "2.0.0-next.9",
-  "license": "MIT",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "files": [
-    "lib/**/*",
-    "templates/**/*",
-    "dev-mailbox.html"
-  ],
-  "scripts": {
-    "watch": "tsc -p ./tsconfig.build.json --watch",
-    "build": "rimraf lib && tsc -p ./tsconfig.build.json",
-    "lint": "tslint --fix --project ./",
-    "test": "jest --config ./jest.config.js"
-  },
-  "homepage": "https://www.vendure.io/",
-  "funding": "https://github.com/sponsors/michaelbromley",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@types/nodemailer": "^6.4.0",
-    "dateformat": "^3.0.3",
-    "express": "^4.17.1",
-    "fs-extra": "^10.0.0",
-    "handlebars": "^4.7.6",
-    "mjml": "^4.7.1",
-    "nodemailer": "^6.4.13"
-  },
-  "devDependencies": {
-    "@types/dateformat": "^3.0.1",
-    "@types/express": "^4.17.8",
-    "@types/fs-extra": "^9.0.1",
-    "@types/handlebars": "^4.1.0",
-    "@types/mjml": "^4.0.4",
-    "@vendure/common": "^2.0.0-next.9",
-    "@vendure/core": "^2.0.0-next.9",
-    "rimraf": "^3.0.2",
-    "typescript": "4.5.5"
-  },
-  "gitHead": "a47a8bbf4c0933b6a7a9cb3a518f8761d1b6e022"
+    "name": "@vendure/email-plugin",
+    "version": "2.0.1",
+    "license": "MIT",
+    "main": "lib/index.js",
+    "types": "lib/index.d.ts",
+    "files": [
+        "lib/**/*",
+        "templates/**/*",
+        "dev-mailbox.html"
+    ],
+    "scripts": {
+        "watch": "tsc -p ./tsconfig.build.json --watch",
+        "build": "rimraf lib && tsc -p ./tsconfig.build.json",
+        "lint": "eslint --fix .",
+        "test": "vitest --config ./vitest.config.ts --run"
+    },
+    "homepage": "https://www.vendure.io/",
+    "funding": "https://github.com/sponsors/michaelbromley",
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@types/nodemailer": "^6.4.0",
+        "dateformat": "^3.0.3",
+        "express": "^4.17.1",
+        "fs-extra": "^10.0.0",
+        "handlebars": "^4.7.6",
+        "mjml": "^4.7.1",
+        "nodemailer": "^6.4.13"
+    },
+    "devDependencies": {
+        "@types/dateformat": "^3.0.1",
+        "@types/express": "^4.17.8",
+        "@types/fs-extra": "^9.0.1",
+        "@types/handlebars": "^4.1.0",
+        "@types/mjml": "^4.0.4",
+        "@vendure/common": "^2.0.1",
+        "@vendure/core": "^2.0.1",
+        "rimraf": "^3.0.2",
+        "typescript": "4.9.5"
+    },
+    "gitHead": "d55a4f405d13c8031a4910513bfc240e859e75ed"
 }