feat(email-plugin): Publish EmailSendEvent after send attempted

vendure-ecommerce · Feb 20, 2024 · e4175e7 · e4175e7
1 parent 20a6ea6
commit e4175e7
Show file tree

Hide file tree

Showing 23 changed files with 154 additions and 90 deletions.
diff --git a/...docs/reference/core-plugins/email-plugin/email-event-handler-with-async-data.md b/...docs/reference/core-plugins/email-plugin/email-event-handler-with-async-data.md
@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## EmailEventHandlerWithAsyncData
 
-<GenerationInfo sourceFile="packages/email-plugin/src/event-handler.ts" sourceLine="438" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/handler/event-handler.ts" sourceLine="438" packageName="@vendure/email-plugin" />
 
 Identical to the <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a> but with a `data` property added to the `event` based on the result
 of the `.loadData()` function.

diff --git a/docs/docs/reference/core-plugins/email-plugin/email-event-handler.md b/docs/docs/reference/core-plugins/email-plugin/email-event-handler.md
@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## EmailEventHandler
 
-<GenerationInfo sourceFile="packages/email-plugin/src/event-handler.ts" sourceLine="131" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/handler/event-handler.ts" sourceLine="131" packageName="@vendure/email-plugin" />
 
 The EmailEventHandler defines how the EmailPlugin will respond to a given event.
 
@@ -114,7 +114,7 @@ const config: VendureConfig = {
   // Add an instance of the plugin to the plugins array
   plugins: [
     EmailPlugin.init({
-      handlers: [...defaultEmailHandlers, quoteRequestedHandler],
+      handler: [...defaultEmailHandlers, quoteRequestedHandler],
       templatePath: path.join(__dirname, 'vendure/email/templates'),
       // ... etc
     }),

diff --git a/docs/docs/reference/core-plugins/email-plugin/email-generator.md b/docs/docs/reference/core-plugins/email-plugin/email-generator.md
@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## EmailGenerator
 
-<GenerationInfo sourceFile="packages/email-plugin/src/email-generator.ts" sourceLine="13" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/generator/email-generator.ts" sourceLine="13" packageName="@vendure/email-plugin" />
 
 An EmailGenerator generates the subject and body details of an email.
 
@@ -50,7 +50,7 @@ interpolated email text.
 
 ## HandlebarsMjmlGenerator
 
-<GenerationInfo sourceFile="packages/email-plugin/src/handlebars-mjml-generator.ts" sourceLine="23" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/generator/handlebars-mjml-generator.ts" sourceLine="17" packageName="@vendure/email-plugin" />
 
 Uses Handlebars (https://handlebarsjs.com/) to output MJML (https://mjml.io) which is then
 compiled down to responsive email HTML.

diff --git a/docs/docs/reference/core-plugins/email-plugin/email-plugin-options.md b/docs/docs/reference/core-plugins/email-plugin/email-plugin-options.md
@@ -11,19 +11,19 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## EmailPluginOptions
 
-<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="40" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="41" packageName="@vendure/email-plugin" />
 
 Configuration for the EmailPlugin.
 
 ```ts title="Signature"
 interface EmailPluginOptions {
     templatePath?: string;
     templateLoader?: TemplateLoader;
-    transport:
-        | EmailTransportOptions
-        | ((
-              injector?: Injector,
-              ctx?: RequestContext,
+    transport:
+        | EmailTransportOptions
+        | ((
+              injector?: Injector,
+              ctx?: RequestContext,
           ) => EmailTransportOptions | Promise<EmailTransportOptions>);
     handlers: Array<EmailEventHandler<string, any>>;
     globalTemplateVars?: { [key: string]: any };
@@ -38,43 +38,43 @@ interface EmailPluginOptions {
 
 <MemberInfo kind="property" type={`string`}   />
 
-The path to the location of the email templates. In a default Vendure installation,
+The path to the location of the email templates. In a default Vendure installation,
 the templates are installed to `<project root>/vendure/email/templates`.
 ### templateLoader
 
 <MemberInfo kind="property" type={`<a href='/reference/core-plugins/email-plugin/template-loader#templateloader'>TemplateLoader</a>`}  since="2.0.0"  />
 
-An optional TemplateLoader which can be used to load templates from a custom location or async service.
+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`
 ### transport
 
-<MemberInfo kind="property" type={`| <a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a>         | ((               injector?: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>,               ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>,           ) =&#62; <a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a> | Promise&#60;<a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a>&#62;)`}   />
+<MemberInfo kind="property" type={`| <a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a>         | ((               injector?: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>,               ctx?: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>,           ) =&#62; <a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a> | Promise&#60;<a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a>&#62;)`}   />
 
 Configures how the emails are sent.
 ### handlers
 
 <MemberInfo kind="property" type={`Array&#60;<a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>&#60;string, any&#62;&#62;`}   />
 
-An array of <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>s which define which Vendure events will trigger
+An array of <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>s which define which Vendure events will trigger
 emails, and how those emails are generated.
 ### globalTemplateVars
 
 <MemberInfo kind="property" type={`{ [key: string]: any }`}   />
 
-An object containing variables which are made available to all templates. For example,
-the storefront URL could be defined here and then used in the "email address verification"
+An object containing variables which are made available to all templates. For example,
+the storefront URL could be defined here and then used in the "email address verification"
 email.
 ### emailSender
 
 <MemberInfo kind="property" type={`<a href='/reference/core-plugins/email-plugin/email-sender#emailsender'>EmailSender</a>`} default="<a href='/reference/core-plugins/email-plugin/email-sender#nodemaileremailsender'>NodemailerEmailSender</a>"   />
 
-An optional allowed EmailSender, used to allow custom implementations of the send functionality
+An optional allowed EmailSender, used to allow custom implementations of the send functionality
 while still utilizing the existing emailPlugin functionality.
 ### emailGenerator
 
 <MemberInfo kind="property" type={`<a href='/reference/core-plugins/email-plugin/email-generator#emailgenerator'>EmailGenerator</a>`} default="<a href='/reference/core-plugins/email-plugin/email-generator#handlebarsmjmlgenerator'>HandlebarsMjmlGenerator</a>"   />
 
-An optional allowed EmailGenerator, used to allow custom email generation functionality to
+An optional allowed EmailGenerator, used to allow custom email generation functionality to
 better match with custom email sending functionality.
 
 
@@ -83,7 +83,7 @@ better match with custom email sending functionality.
 
 ## EmailPluginDevModeOptions
 
-<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="110" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="111" packageName="@vendure/email-plugin" />
 
 Configuration for running the EmailPlugin in development mode.
 

diff --git a/docs/docs/reference/core-plugins/email-plugin/email-plugin-types.md b/docs/docs/reference/core-plugins/email-plugin/email-plugin-types.md
@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## EventWithContext
 
-<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="21" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="22" packageName="@vendure/email-plugin" />
 
 A VendureEvent which also includes a `ctx` property containing the current
 <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, which is used to determine the channel and language
@@ -24,7 +24,7 @@ type EventWithContext = VendureEvent & { ctx: RequestContext }
 
 ## EventWithAsyncData
 
-<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="31" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="32" packageName="@vendure/email-plugin" />
 
 A VendureEvent with a <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a> and a `data` property which contains the
 value resolved from the <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>`.loadData()` callback.
@@ -36,7 +36,7 @@ type EventWithAsyncData<Event extends EventWithContext, R> = Event & { data: R }
 
 ## EmailDetails
 
-<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="248" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="249" packageName="@vendure/email-plugin" />
 
 The final, generated email details to be sent.
 
@@ -102,7 +102,7 @@ interface EmailDetails<Type extends 'serialized' | 'unserialized' = 'unserialize
 
 ## LoadDataFn
 
-<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="282" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="283" packageName="@vendure/email-plugin" />
 
 A function used to load async data for use by an <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>.
 
@@ -116,7 +116,7 @@ type LoadDataFn<Event extends EventWithContext, R> = (context: {
 
 ## EmailAttachment
 
-<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="301" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="302" packageName="@vendure/email-plugin" />
 
 An object defining a file attachment for an email. Based on the object described
 [here in the Nodemailer docs](https://nodemailer.com/message/attachments/), but
@@ -130,7 +130,7 @@ type EmailAttachment = Omit<Attachment, 'raw'> & { path?: string }
 
 ## SetTemplateVarsFn
 
-<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="414" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="374" packageName="@vendure/email-plugin" />
 
 A function used to define template variables available to email templates.
 See <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>.setTemplateVars().
@@ -145,7 +145,7 @@ type SetTemplateVarsFn<Event> = (
 
 ## SetAttachmentsFn
 
-<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="428" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="388" packageName="@vendure/email-plugin" />
 
 A function used to define attachments to be sent with the email.
 See https://nodemailer.com/message/attachments/ for more information about
@@ -158,7 +158,7 @@ type SetAttachmentsFn<Event> = (event: Event) => EmailAttachment[] | Promise<Ema
 
 ## OptionalAddressFields
 
-<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="438" packageName="@vendure/email-plugin" since="1.1.0" />
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="398" packageName="@vendure/email-plugin" since="1.1.0" />
 
 Optional address-related fields for sending the email.
 
@@ -194,7 +194,7 @@ An email address that will appear on the _Reply-To:_ field
 
 ## SetOptionalAddressFieldsFn
 
-<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="464" packageName="@vendure/email-plugin" since="1.1.0" />
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="424" packageName="@vendure/email-plugin" since="1.1.0" />
 
 A function used to set the <a href='/reference/core-plugins/email-plugin/email-plugin-types#optionaladdressfields'>OptionalAddressFields</a>.
 

diff --git a/docs/docs/reference/core-plugins/email-plugin/email-send-event.md b/docs/docs/reference/core-plugins/email-plugin/email-send-event.md
@@ -0,0 +1,38 @@
+---
+title: "EmailSendEvent"
+isDefaultIndex: false
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+import MemberInfo from '@site/src/components/MemberInfo';
+import GenerationInfo from '@site/src/components/GenerationInfo';
+import MemberDescription from '@site/src/components/MemberDescription';
+
+
+## EmailSendEvent
+
+<GenerationInfo sourceFile="packages/email-plugin/src/email-send-event.ts" sourceLine="14" packageName="@vendure/email-plugin" since="2.2.0" />
+
+This event is fired when an email sending attempt has been made. If the sending was successful,
+the `success` property will be `true`, and if not, the `error` property will contain the error
+which occurred.
+
+```ts title="Signature"
+class EmailSendEvent extends VendureEvent {
+    constructor(ctx: RequestContext, details: EmailDetails, success: boolean, error?: Error)
+}
+```
+* Extends: <code><a href='/reference/typescript-api/events/vendure-event#vendureevent'>VendureEvent</a></code>
+
+
+
+<div className="members-wrapper">
+
+### constructor
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, details: <a href='/reference/core-plugins/email-plugin/email-plugin-types#emaildetails'>EmailDetails</a>, success: boolean, error?: Error) => EmailSendEvent`}   />
+
+
+
+
+</div>
diff --git a/docs/docs/reference/core-plugins/email-plugin/email-sender.md b/docs/docs/reference/core-plugins/email-plugin/email-sender.md
@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## EmailSender
 
-<GenerationInfo sourceFile="packages/email-plugin/src/email-sender.ts" sourceLine="45" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/sender/email-sender.ts" sourceLine="45" packageName="@vendure/email-plugin" />
 
 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
@@ -40,7 +40,7 @@ const config: VendureConfig = {
   // ...
   plugins: [
     EmailPlugin.init({
-       // ... template, handlers config omitted
+       // ... template, handler config omitted
       transport: { type: 'none' },
        emailSender: new SendgridEmailSender(),
     }),
@@ -71,7 +71,7 @@ interface EmailSender extends InjectableStrategy {
 
 ## NodemailerEmailSender
 
-<GenerationInfo sourceFile="packages/email-plugin/src/nodemailer-email-sender.ts" sourceLine="38" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/sender/nodemailer-email-sender.ts" sourceLine="39" packageName="@vendure/email-plugin" />
 
 Uses the configured transport to send the generated email.
 

diff --git a/docs/docs/reference/core-plugins/email-plugin/email-utils.md b/docs/docs/reference/core-plugins/email-plugin/email-utils.md
@@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
 
 ## transformOrderLineAssetUrls
 
-<GenerationInfo sourceFile="packages/email-plugin/src/default-email-handlers.ts" sourceLine="101" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/handler/default-email-handlers.ts" sourceLine="101" packageName="@vendure/email-plugin" />
 
 Applies the configured `AssetStorageStrategy.toAbsoluteUrl()` function to each of the
 OrderLine's `featuredAsset.preview` properties, so that they can be correctly displayed
@@ -42,7 +42,7 @@ Parameters
 
 ## hydrateShippingLines
 
-<GenerationInfo sourceFile="packages/email-plugin/src/default-email-handlers.ts" sourceLine="122" packageName="@vendure/email-plugin" />
+<GenerationInfo sourceFile="packages/email-plugin/src/handler/default-email-handlers.ts" sourceLine="122" packageName="@vendure/email-plugin" />
 
 Ensures that the ShippingLines are hydrated so that we can use the
 `shippingMethod.name` property in the email template.