@vendure/docs 0.0.0-202601161541

package/docs/reference/core-plugins/email-plugin/email-plugin-options.md

@@ -0,0 +1,154 @@
+---
+title: "EmailPluginOptions"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## EmailPluginOptions
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="77" packageName="@vendure/email-plugin" />
+
+Configuration for the EmailPlugin.
+
+```ts title="Signature"
+interface EmailPluginOptions {
+    templatePath?: string;
+    templateLoader?: TemplateLoader;
+    transport:
+        | EmailTransportOptions
+        | ((
+              injector?: Injector,
+              ctx?: RequestContext,
+          ) => EmailTransportOptions | Promise<EmailTransportOptions>);
+    handlers: Array<EmailEventHandler<string, any>>;
+    globalTemplateVars?: { [key: string]: any } | GlobalTemplateVarsFn;
+    emailSender?: EmailSender;
+    emailGenerator?: EmailGenerator;
+}
+```
+
+<div className="members-wrapper">
+
+### templatePath
+
+<MemberInfo kind="property" type={`string`}   />
+
+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.
+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;)`}   />
+
+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
+emails, and how those emails are generated.
+### globalTemplateVars
+
+<MemberInfo kind="property" type={`{ [key: string]: any } | <a href='/reference/core-plugins/email-plugin/email-plugin-options#globaltemplatevarsfn'>GlobalTemplateVarsFn</a>`}   />
+
+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. Use the GlobalTemplateVarsFn if you need to retrieve variables from Vendure or
+plugin services.
+### 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
+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
+better match with custom email sending functionality.
+
+
+</div>
+
+
+## GlobalTemplateVarsFn
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="64" packageName="@vendure/email-plugin" since="2.3.0" />
+
+Allows you to dynamically load the "globalTemplateVars" key async and access Vendure services
+to create the object. This is not a requirement. You can also specify a simple static object if your
+projects doesn't need to access async or dynamic values.
+
+*Example*
+
+```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;
+     }
+  [...]
+})
+
+```
+
+```ts title="Signature"
+type GlobalTemplateVarsFn = (
+    ctx: RequestContext,
+    injector: Injector,
+) => Promise<{ [key: string]: any }>
+```
+
+
+## EmailPluginDevModeOptions
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="150" packageName="@vendure/email-plugin" />
+
+Configuration for running the EmailPlugin in development mode.
+
+```ts title="Signature"
+interface EmailPluginDevModeOptions extends Omit<EmailPluginOptions, 'transport'> {
+    devMode: true;
+    outputPath: string;
+    route: string;
+}
+```
+* Extends: <code>Omit&#60;<a href='/reference/core-plugins/email-plugin/email-plugin-options#emailpluginoptions'>EmailPluginOptions</a>, 'transport'&#62;</code>
+
+
+
+<div className="members-wrapper">
+
+### devMode
+
+<MemberInfo kind="property" type={`true`}   />
+
+
+### outputPath
+
+<MemberInfo kind="property" type={`string`}   />
+
+The path to which html email files will be saved rather than being sent.
+### route
+
+<MemberInfo kind="property" type={`string`}   />
+
+The route to the dev mailbox server.
+
+
+</div>

package/docs/reference/core-plugins/email-plugin/email-plugin-types.md

@@ -0,0 +1,276 @@
+---
+title: "Email Plugin Types"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## EventWithContext
+
+<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
+to use when generating the email.
+
+```ts title="Signature"
+type EventWithContext = VendureEvent & { ctx: RequestContext }
+```
+
+
+## EventWithAsyncData
+
+<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.
+
+```ts title="Signature"
+type EventWithAsyncData<Event extends EventWithContext, R> = Event & { data: R }
+```
+
+
+## EmailDetails
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="288" packageName="@vendure/email-plugin" />
+
+The final, generated email details to be sent.
+
+```ts title="Signature"
+interface EmailDetails<Type extends 'serialized' | 'unserialized' = 'unserialized'> {
+    from: string;
+    recipient: string;
+    subject: string;
+    body: string;
+    attachments: Array<Type extends 'serialized' ? SerializedAttachment : Attachment>;
+    cc?: string;
+    bcc?: string;
+    replyTo?: string;
+}
+```
+
+<div className="members-wrapper">
+
+### from
+
+<MemberInfo kind="property" type={`string`}   />
+
+
+### recipient
+
+<MemberInfo kind="property" type={`string`}   />
+
+
+### subject
+
+<MemberInfo kind="property" type={`string`}   />
+
+
+### body
+
+<MemberInfo kind="property" type={`string`}   />
+
+
+### attachments
+
+<MemberInfo kind="property" type={`Array&#60;Type extends 'serialized' ? SerializedAttachment : Attachment&#62;`}   />
+
+
+### cc
+
+<MemberInfo kind="property" type={`string`}   />
+
+
+### bcc
+
+<MemberInfo kind="property" type={`string`}   />
+
+
+### replyTo
+
+<MemberInfo kind="property" type={`string`}   />
+
+
+
+
+</div>
+
+
+## LoadDataFn
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="322" 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>.
+
+```ts title="Signature"
+type LoadDataFn<Event extends EventWithContext, R> = (context: {
+    event: Event;
+    injector: Injector;
+}) => Promise<R>
+```
+
+
+## EmailAttachment
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="341" 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
+only uses the `path` property to define a filesystem path or a URL pointing to
+the attachment file.
+
+```ts title="Signature"
+type EmailAttachment = Omit<Attachment, 'raw'> & { path?: string }
+```
+
+
+## LoadTemplateInput
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="402" packageName="@vendure/email-plugin" />
+
+The object passed to the <a href='/reference/core-plugins/email-plugin/template-loader#templateloader'>TemplateLoader</a> `loadTemplate()` method.
+
+```ts title="Signature"
+interface LoadTemplateInput {
+    type: string;
+    templateName: string;
+    templateVars: any;
+}
+```
+
+<div className="members-wrapper">
+
+### type
+
+<MemberInfo kind="property" type={`string`}   />
+
+The type corresponds to the string passed to the EmailEventListener constructor.
+### templateName
+
+<MemberInfo kind="property" type={`string`}   />
+
+The template name is specified by the EmailEventHander's call to
+the `addTemplate()` method, and will default to `body.hbs`
+### templateVars
+
+<MemberInfo kind="property" type={`any`}   />
+
+The variables defined by the globalTemplateVars as well as any variables defined in the
+EmailEventHandler's `setTemplateVars()` method.
+
+
+</div>
+
+
+## SetTemplateVarsFn
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="435" 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().
+
+```ts title="Signature"
+type SetTemplateVarsFn<Event> = (
+    event: Event,
+    globals: { [key: string]: any },
+) => { [key: string]: any }
+```
+
+
+## SetAttachmentsFn
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="449" 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
+how attachments work in Nodemailer.
+
+```ts title="Signature"
+type SetAttachmentsFn<Event> = (event: Event) => EmailAttachment[] | Promise<EmailAttachment[]>
+```
+
+
+## SetSubjectFn
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="457" packageName="@vendure/email-plugin" />
+
+A function used to define the subject to be sent with the email.
+
+```ts title="Signature"
+type SetSubjectFn<Event> = (
+    event: Event,
+    ctx: RequestContext,
+    injector: Injector,
+) => string | Promise<string>
+```
+
+
+## OptionalAddressFields
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="471" packageName="@vendure/email-plugin" since="1.1.0" />
+
+Optional address-related fields for sending the email.
+
+```ts title="Signature"
+interface OptionalAddressFields {
+    cc?: string;
+    bcc?: string;
+    replyTo?: string;
+}
+```
+
+<div className="members-wrapper">
+
+### cc
+
+<MemberInfo kind="property" type={`string`}   />
+
+Comma separated list of recipients email addresses that will appear on the _Cc:_ field
+### bcc
+
+<MemberInfo kind="property" type={`string`}   />
+
+Comma separated list of recipients email addresses that will appear on the _Bcc:_ field
+### replyTo
+
+<MemberInfo kind="property" type={`string`}   />
+
+An email address that will appear on the _Reply-To:_ field
+
+
+</div>
+
+
+## SetOptionalAddressFieldsFn
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="497" 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>.
+
+```ts title="Signature"
+type SetOptionalAddressFieldsFn<Event> = (
+    event: Event,
+) => OptionalAddressFields | Promise<OptionalAddressFields>
+```
+
+
+## SetMetadataFn
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="509" packageName="@vendure/email-plugin" since="3.1.0" />
+
+A function used to set the <a href='/reference/core-plugins/email-plugin/email-plugin-types#emailmetadata'>EmailMetadata</a>.
+
+```ts title="Signature"
+type SetMetadataFn<Event> = (event: Event) => EmailMetadata | Promise<EmailMetadata>
+```
+
+
+## EmailMetadata
+
+<GenerationInfo sourceFile="packages/email-plugin/src/types.ts" sourceLine="519" packageName="@vendure/email-plugin" since="3.1.0" />
+
+Metadata that can be attached to an email via the <a href='/reference/core-plugins/email-plugin/email-event-handler#emaileventhandler'>EmailEventHandler</a>`.setMetadata()` method.
+
+```ts title="Signature"
+type EmailMetadata = Record<string, any>
+```

package/docs/reference/core-plugins/email-plugin/email-send-event.md

@@ -0,0 +1,34 @@
+---
+title: "EmailSendEvent"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## 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, metadata?: EmailMetadata)
+}
+```
+* 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, metadata?: <a href='/reference/core-plugins/email-plugin/email-plugin-types#emailmetadata'>EmailMetadata</a>) => EmailSendEvent`}   />
+
+
+
+
+</div>

package/docs/reference/core-plugins/email-plugin/email-sender.md

@@ -0,0 +1,92 @@
+---
+title: "EmailSender"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## EmailSender
+
+<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
+<a href='/reference/core-plugins/email-plugin/email-sender#nodemaileremailsender'>NodemailerEmailSender</a>, 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: VendureConfig = {
+  logger: new DefaultLogger({ level: LogLevel.Debug })
+  // ...
+  plugins: [
+    EmailPlugin.init({
+       // ... template, handler config omitted
+      transport: { type: 'none' },
+       emailSender: new SendgridEmailSender(),
+    }),
+  ],
+};
+```
+
+```ts title="Signature"
+interface EmailSender extends InjectableStrategy {
+    send: (email: EmailDetails, options: EmailTransportOptions) => void | Promise<void>;
+}
+```
+* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>
+
+
+
+<div className="members-wrapper">
+
+### send
+
+<MemberInfo kind="property" type={`(email: <a href='/reference/core-plugins/email-plugin/email-plugin-types#emaildetails'>EmailDetails</a>, options: <a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a>) =&#62; void | Promise&#60;void&#62;`}   />
+
+
+
+
+</div>
+
+
+## NodemailerEmailSender
+
+<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.
+
+```ts title="Signature"
+class NodemailerEmailSender implements EmailSender {
+    send(email: EmailDetails, options: EmailTransportOptions) => ;
+}
+```
+* Implements: <code><a href='/reference/core-plugins/email-plugin/email-sender#emailsender'>EmailSender</a></code>
+
+
+
+<div className="members-wrapper">
+
+### send
+
+<MemberInfo kind="method" type={`(email: <a href='/reference/core-plugins/email-plugin/email-plugin-types#emaildetails'>EmailDetails</a>, options: <a href='/reference/core-plugins/email-plugin/transport-options#emailtransportoptions'>EmailTransportOptions</a>) => `}   />
+
+
+
+
+</div>

package/docs/reference/core-plugins/email-plugin/email-utils.md

@@ -0,0 +1,54 @@
+---
+title: "Email Utils"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## transformOrderLineAssetUrls
+
+<GenerationInfo sourceFile="packages/email-plugin/src/handler/default-email-handlers.ts" sourceLine="106" 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
+in the email template.
+This is required since that step usually happens at the API in middleware, which is not
+applicable in this context. So we need to do it manually.
+
+**Note: Mutates the Order object**
+
+```ts title="Signature"
+function transformOrderLineAssetUrls(ctx: RequestContext, order: Order, injector: Injector): Order
+```
+Parameters
+
+### ctx
+
+<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>`} />
+
+### order
+
+<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`} />
+
+### injector
+
+<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/common/injector#injector'>Injector</a>`} />
+
+
+
+## shippingLinesWithMethod
+
+<GenerationInfo sourceFile="packages/email-plugin/src/handler/default-email-handlers.ts" sourceLine="127" packageName="@vendure/email-plugin" />
+
+Ensures that the ShippingLines have a shippingMethod so that we can use the
+`shippingMethod.name` property in the email template.
+
+```ts title="Signature"
+function shippingLinesWithMethod(order: Order): ShippingLine[]
+```
+Parameters
+
+### order
+
+<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/entities/order#order'>Order</a>`} />
+