docs(server): Add some documentation

server/src/config/email/email-options.ts

@@ -35,9 +35,31 @@ export type CreateContextResult = {
     channelCode: string;
 };
 
+/**
+ * @description
+ * An object which configures an particular type of transactional email.
+ *
+ * @docsCategory email
+ */
 export type EmailTypeConfig<T extends string, E extends VendureEvent = any> = {
+    /**
+     * @description
+     * Specifies the {@link VendureEvent} which triggers this type of email.
+     */
     triggerEvent: Type<E>;
+    /**
+     * @description
+     * A function which creates a context object for the email, specifying the recipient
+     * email address, the languageCode of the email and the current Channel.
+     *
+     * A return value of `undefined` means that no email will be generated and sent.
+     */
     createContext: (event: E) => CreateContextResult | undefined;
+    /**
+     * @description
+     * An object which describes how to resolve the template for the email depending on
+     * the current Channel and LanguageCode.
+     */
     templates: TemplateByChannel<EmailContext<T, E>>;
 };
 
@@ -48,6 +70,42 @@ export type EmailTypeConfig<T extends string, E extends VendureEvent = any> = {
  * email type. Search the repo for the `default-email-types.ts` file for an example of how
  * the email types are defined.
  *
+ * When defining an email type, the helper function `configEmailType` may be used to
+ * provide better type-safety.
+ *
+ * @example
+ * ```ts
+ * export const defaultEmailTypes: EmailTypes<DefaultEmailType> = {
+ *  'order-confirmation': configEmailType({
+ *    triggerEvent: OrderStateTransitionEvent,
+ *    createContext: e => {
+ *      const customer = e.order.customer;
+ *      if (customer && e.toState === 'PaymentSettled') {
+ *        return {
+ *          recipient: customer.emailAddress,
+ *          languageCode: e.ctx.languageCode,
+ *          channelCode: e.ctx.channel.code,
+ *        };
+ *      }
+ *    },
+ *    templates: {
+ *      defaultChannel: {
+ *        defaultLanguage: {
+ *          templateContext: emailContext => ({ order: emailContext.event.order }),
+ *          subject: `Order confirmation for #{{ order.code }}`,
+ *          templatePath: 'order-confirmation/order-confirmation.hbs',
+ *        },
+ *        de: {
+ *          // config for German-language templates
+ *        }
+ *      },
+ *      'other-channel-code': {
+ *        // config for a different Channel
+ *      }
+ *    },
+ *  }),
+ * ```
+ *
  * @docsCategory email
  */
 export type EmailTypes<T extends string> = { [emailType in T]: EmailTypeConfig<T> };

server/src/config/email/email-transport-options.ts

@@ -15,23 +15,50 @@ export interface SMTPCredentials {
  */
 export interface SMTPTransportOptions {
     type: 'smtp';
-    /** the hostname or IP address to connect to (defaults to ‘localhost’) */
+    /**
+     * @description
+     * the hostname or IP address to connect to (defaults to ‘localhost’)
+     */
     host: string;
-    /** the port to connect to (defaults to 25 or 465) */
+    /**
+     * @description
+     * The port to connect to (defaults to 25 or 465)
+     */
     port: number;
-    /** defines authentication data */
+    /**
+     * @description
+     * Defines authentication data
+     */
     auth: SMTPCredentials;
-    /** defines if the connection should use SSL (if true) or not (if false) */
+    /**
+     * @description
+     * Defines if the connection should use SSL (if true) or not (if false)
+     */
     secure?: boolean;
-    /** turns off STARTTLS support if true */
+    /**
+     * @description
+     * Turns off STARTTLS support if true
+     */
     ignoreTLS?: boolean;
-    /** forces the client to use STARTTLS. Returns an error if upgrading the connection is not possible or fails. */
+    /**
+     * @description
+     * Forces the client to use STARTTLS. Returns an error if upgrading the connection is not possible or fails.
+     */
     requireTLS?: boolean;
-    /** optional hostname of the client, used for identifying to the server */
+    /**
+     * @description
+     * Optional hostname of the client, used for identifying to the server
+     */
     name?: string;
-    /** the local interface to bind to for network connections */
+    /**
+     * @description
+     * The local interface to bind to for network connections
+     */
     localAddress?: string;
-    /** defines preferred authentication method, e.g. ‘PLAIN’ */
+    /**
+     * @description
+     * Defines preferred authentication method, e.g. ‘PLAIN’
+     */
     authMethod?: string;
 }
 

server/src/event-bus/event-bus.ts

@@ -12,6 +12,7 @@ export type UnsubscribeFn = () => void;
  * The EventBus is used to globally publish events which can then be subscribed to.
  *
  * @docsCategory events
+ * @docsWeight 0
  */
 @Injectable()
 export class EventBus {

server/src/event-bus/events/account-registration-event.ts

@@ -3,8 +3,11 @@ import { User } from '../../entity/user/user.entity';
 import { VendureEvent } from '../vendure-event';
 
 /**
+ * @description
  * This event is fired when a new user registers an account, either as a stand-alone signup or after
  * placing an order.
+ *
+ * @docsCategory events
  */
 export class AccountRegistrationEvent extends VendureEvent {
     constructor(public ctx: RequestContext, public user: User) {

server/src/event-bus/events/catalog-modification-event.ts

@@ -2,6 +2,14 @@ import { RequestContext } from '../../api/common/request-context';
 import { Product, ProductVariant } from '../../entity';
 import { VendureEvent } from '../vendure-event';
 
+/**
+ * @description
+ * This event is fired whenever the catalog is modified in some way, i.e. a
+ * {@link Product} or {@link ProductVariant} is modified is created, updated, or
+ * deleted.
+ *
+ * @docsCategory events
+ */
 export class CatalogModificationEvent extends VendureEvent {
     constructor(public ctx: RequestContext, public entity: Product | ProductVariant) {
         super();

server/src/event-bus/events/order-state-transition-event.ts

@@ -4,6 +4,12 @@ import { Order } from '../../entity/order/order.entity';
 import { OrderState } from '../../service/helpers/order-state-machine/order-state';
 import { VendureEvent } from '../vendure-event';
 
+/**
+ * @description
+ * This event is fired whenever an {@link Order} transitions from one {@link OrderState} to another.
+ *
+ * @docsCategory events
+ */
 export class OrderStateTransitionEvent extends VendureEvent {
     constructor(
         public fromState: OrderState,

server/src/event-bus/vendure-event.ts

@@ -3,6 +3,7 @@
  * The base class for all events used by the EventBus system.
  *
  * @docsCategory events
+ * @docsWeight 1
  */
 export abstract class VendureEvent {
     public readonly createdAt: Date;

server/src/plugin/default-asset-server-plugin/default-asset-server-plugin.ts

@@ -10,8 +10,35 @@ import { DefaultAssetPreviewStrategy } from './default-asset-preview-strategy';
 import { DefaultAssetStorageStrategy } from './default-asset-storage-strategy';
 import { transformImage } from './transform-image';
 
+/**
+ * @description
+ * Specifies the way in which an asset preview image will be resized to fit in the
+ * proscribed dimensions:
+ *
+ * * crop: crops the image to cover both provided dimensions
+ * * resize: Preserving aspect ratio, resizes the image to be as large as possible
+ * while ensuring its dimensions are less than or equal to both those specified.
+ *
+ * @docsCategory plugin
+ */
 export type ImageTransformMode = 'crop' | 'resize';
 
+/**
+ * @description
+ * A configuration option for an image size preset for the DefaultAssetServerPlugin.
+ *
+ * Presets allow a shorthand way to generate a thumbnail preview of an asset. For example,
+ * the built-in "tiny" preset generates a 50px x 50px cropped preview, which can be accessed
+ * by appending the string `preset=tiny` to the asset url:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?preset=tiny`
+ *
+ * is equivalent to:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?w=50&h=50&mode=crop`
+ *
+ * @docsCategory plugin
+ */
 export interface ImageTransformPreset {
     name: string;
     width: number;
@@ -19,13 +46,49 @@ export interface ImageTransformPreset {
     mode: ImageTransformMode;
 }
 
+/**
+ * @description
+ * The configuration options for the DefaultAssetServerPlugin.
+ *
+ * @docsCategory plugin
+ */
 export interface DefaultAssetServerOptions {
     hostname?: string;
+    /**
+     * @description
+     * The local port that the server will run on. Note that the DefaultAssetServerPlugin
+     * includes a proxy server which allows the asset server to be accessed on the same
+     * port as the main Vendure server.
+     */
     port: number;
+    /**
+     * @description
+     * The proxy route to the asset server.
+     */
     route: string;
+    /**
+     * @description
+     * The local directory to which assets will be uploaded.
+     */
     assetUploadDir: string;
+    /**
+     * @description
+     * The max width in pixels of a generated preview image.
+     *
+     * @default 1600
+     */
     previewMaxWidth?: number;
+    /**
+     * @description
+     * The max height in pixels of a generated preview image.
+     *
+     * @default 1600
+     */
     previewMaxHeight?: number;
+    /**
+     * @description
+     * An array of additional {@link ImageTransformPreset} objects.
+     */
     presets?: ImageTransformPreset[];
 }
 

server/src/plugin/default-email-plugin/default-email-plugin.ts

@@ -4,8 +4,23 @@ import { InternalServerError } from '../../common/error/errors';
 import { EmailTransportOptions, VendureConfig, VendurePlugin } from '../../config';
 import { defaultEmailTypes, HandlebarsMjmlGenerator } from '../../email';
 
+/**
+ * @description
+ * Configuration for the DefaultEmailPlugin.
+ *
+ * @docsCategory plugin
+ */
 export interface DefaultEmailPluginOptions {
+    /**
+     * @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`.
+     */
     templatePath: string;
+    /**
+     * @description
+     * Configures how the emails are sent.
+     */
     transport: EmailTransportOptions;
 }