docs(server): Add lots and lots of documentation to the source

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

@@ -41,6 +41,15 @@ export type EmailTypeConfig<T extends string, E extends VendureEvent = any> = {
     templates: TemplateByChannel<EmailContext<T, E>>;
 };
 
+/**
+ * @description
+ * An object describing each possible type of transactional email, plus which events
+ * trigger those emails, as well as the location of the templates to handle each
+ * email type. Search the repo for the `default-email-types.ts` file for an example of how
+ * the email types are defined.
+ *
+ * @docsCategory email
+ */
 export type EmailTypes<T extends string> = { [emailType in T]: EmailTypeConfig<T> };
 
 export function configEmailType<T extends string, E extends VendureEvent = VendureEvent>(
@@ -49,8 +58,24 @@ export function configEmailType<T extends string, E extends VendureEvent = Vendu
     return config;
 }
 
+/**
+ * @description
+ * The EmailGenerator uses the {@link EmailContext} and template to generate the email body
+ *
+ * @docsCategory email
+ */
 export interface EmailGenerator<T extends string = any, E extends VendureEvent = any> {
+    /**
+     * @description
+     * Any neccesary setup can be performed here.
+     */
     onInit?(config: ConfigService): void | Promise<void>;
+
+    /**
+     * @description
+     * Given a subject and body from an email template, this method generates the final
+     * interpolated email text.
+     */
     generate(
         subject: string,
         body: string,

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

@@ -88,6 +88,12 @@ export interface TestingTransportOptions {
     onSend: (context: GeneratedEmailContext) => void;
 }
 
+/**
+ * @description
+ * A union of all the possible transport options for sending emails.
+ *
+ * @docsCategory email
+ */
 export type EmailTransportOptions =
     | SMTPTransportOptions
     | SendmailTransportOptions

server/src/config/entity-id-strategy/entity-id-strategy.ts

@@ -1,5 +1,13 @@
 import { ID } from '../../../../shared/shared-types';
 
+/**
+ * @description
+ * Defines the type of primary key used for all entities in the database.
+ * "increment" uses an auto-incrementing integer, whereas "uuid" uses a
+ * uuid string.
+ *
+ * @docsCategory entities
+ */
 export type PrimaryKeyType = 'increment' | 'uuid';
 
 /**
@@ -8,7 +16,8 @@ export type PrimaryKeyType = 'increment' | 'uuid';
  * database, as well as how they are transformed when being passed from the API to the
  * service layer.
  *
- * @docsCategory
+ * @docsCategory entities
+ * @docsWeight 1
  */
 export interface EntityIdStrategy<T extends ID = ID> {
     readonly primaryKeyType: PrimaryKeyType;

server/src/config/order-merge-strategy/order-merge-strategy.ts

@@ -12,5 +12,10 @@ import { Order } from '../../entity/order/order.entity';
  * @docsCategory orders
  */
 export interface OrderMergeStrategy {
+    /**
+     * @description
+     * Merges the lines of the guest Order with those of the existing Order which is associated
+     * with the active customer.
+     */
     merge(guestOrder: Order, existingOrder: Order): OrderLine[];
 }

server/src/config/payment-method/payment-method-handler.ts

@@ -20,6 +20,12 @@ export type OnTransitionStartFn<T extends PaymentMethodArgs> = (
     data: PaymentTransitionData,
 ) => OnTransitionStartReturnType;
 
+/**
+ * @description
+ * This object is the return value of the {@link CreatePaymentFn}.
+ *
+ * @docsCategory payment
+ */
 export interface PaymentConfig {
     amount: number;
     state: PaymentState;
@@ -27,25 +33,109 @@ export interface PaymentConfig {
     metadata?: PaymentMetadata;
 }
 
+/**
+ * @description
+ * This function contains the logic for creating a payment. See {@link PaymentMethodHandler} for an example.
+ *
+ * @docsCategory payment
+ */
 export type CreatePaymentFn<T extends PaymentMethodArgs> = (
     order: Order,
     args: ConfigArgValues<T>,
     metadata: PaymentMetadata,
 ) => PaymentConfig | Promise<PaymentConfig>;
 
+/**
+ * @description
+ * Defines the object which is used to construct the {@link PaymentMethodHandler}.
+ *
+ * @docsCategory payment
+ */
 export interface PaymentMethodConfigOptions<T extends PaymentMethodArgs = PaymentMethodArgs> {
+    /**
+     * @description
+     * A unique code used to identify this handler.
+     */
     code: string;
+    /**
+     * @description
+     * A human-readable name for the payment method.
+     */
     name: string;
+    /**
+     * @description
+     * This function provides the actual logic for creating a payment. For example,
+     * it may call out to a third-party service with the data and should return a
+     * {@link PaymentConfig} object contains the details of the payment.
+     */
     createPayment: CreatePaymentFn<T>;
+    /**
+     * @description
+     * Optional provider-specific arguments which, when specified, are
+     * editable in the admin-ui. Typically args could be used to store an API key
+     * for a payment provider service.
+     *
+     * @example
+     * ```ts
+     * args: {
+     *   apiKey: 'string',
+     * }
+     * ```
+     */
     args: T;
+    /**
+     * @description
+     * This function, when specified, will be invoked before any transition from one {@link PaymentState} to another.
+     * The return value (a sync / async `boolean`) is used to determine whether the transition is permitted.
+     */
     onStateTransitionStart?: OnTransitionStartFn<T>;
 }
 
 /**
+ * @description
  * A PaymentMethodHandler contains the code which is used to generate a Payment when a call to the
  * `addPaymentToOrder` mutation is made. If contains any necessary steps of interfacing with a
  * third-party payment gateway before the Payment is created and can also define actions to fire
  * when the state of the payment is changed.
+ *
+ * @example
+ * ```ts
+ * // A mock 3rd-party payment SDK
+ * import gripeSDK from 'gripe';
+ *
+ * export const examplePaymentHandler = new PaymentMethodHandler({
+ *     code: 'example-payment-provider',
+ *     name: 'Example Payment Provider',
+ *     args: {
+ *         apiKey: 'string',
+ *     },
+ *     createPayment: async (order, args, metadata): Promise<PaymentConfig> => {
+ *         try {
+ *             const result = await gripeSDK.charges.create({
+ *                 apiKey: args.apiKey,
+ *                 amount: order.total,
+ *                 source: metadata.authToken,
+ *             });
+ *             return {
+ *                 amount: order.total,
+ *                 state: 'Settled' as 'Settled',
+ *                 transactionId: result.id.toString(),
+ *                 metadata: result.outcome,
+ *             };
+ *         } catch (err) {
+ *             return {
+ *                 amount: order.total,
+ *                 state: 'Declined' as 'Declined',
+ *                 metadata: {
+ *                     errorMessage: err.message,
+ *                 },
+ *             };
+ *         }
+ *     },
+ * });
+ * ```
+ *
+ * @docsCategory payment
  */
 export class PaymentMethodHandler<T extends PaymentMethodArgs = PaymentMethodArgs> {
     readonly code: string;
@@ -62,6 +152,10 @@ export class PaymentMethodHandler<T extends PaymentMethodArgs = PaymentMethodArg
         this.onTransitionStartFn = config.onStateTransitionStart;
     }
 
+    /**
+     * @description
+     * Called internally to create a new Payment
+     */
     async createPayment(order: Order, args: ConfigArg[], metadata: PaymentMetadata) {
         const paymentConfig = await this.createPaymentFn(order, argsArrayToHash(args), metadata);
         return {
@@ -70,6 +164,14 @@ export class PaymentMethodHandler<T extends PaymentMethodArgs = PaymentMethodArg
         };
     }
 
+    /**
+     * @description
+     * This function is called before the state of a Payment is transitioned. If the PaymentMethodHandler
+     * was instantiated with a `onStateTransitionStart` function, that function will be invoked and its
+     * return value used to determine whether the transition can occur.
+     *
+     * @docsCategory payment
+     */
     onStateTransitionStart(
         fromState: PaymentState,
         toState: PaymentState,

server/src/config/promotion/promotion-action.ts

@@ -34,6 +34,12 @@ export interface PromotionOrderActionConfig<T extends PromotionActionArgs> exten
     execute: ExecutePromotionOrderActionFn<T>;
 }
 
+/**
+ * @description
+ * An abstract class which is extended by {@link PromotionItemAction} and {@link PromotionOrderAction}.
+ *
+ * @docsCategory promotions
+ */
 export abstract class PromotionAction<T extends PromotionActionArgs = {}> {
     readonly code: string;
     readonly args: PromotionActionArgs;
@@ -49,7 +55,23 @@ export abstract class PromotionAction<T extends PromotionActionArgs = {}> {
 }
 
 /**
- * Represents a PromotionAction which applies to individual OrderItems.
+ * @description
+ * Represents a PromotionAction which applies to individual {@link OrderItem}s.
+ *
+ * @example
+ * ```ts
+ * // Applies a percentage discount to each OrderItem
+ * const itemPercentageDiscount = new PromotionItemAction({
+ *     code: 'item_percentage_discount',
+ *     args: { discount: 'percentage' },
+ *     execute(orderItem, orderLine, args) {
+ *         return -orderLine.unitPrice * (args.discount / 100);
+ *     },
+ *     description: 'Discount every item by { discount }%',
+ * });
+ * ```
+ *
+ * @docsCategory promotions
  */
 export class PromotionItemAction<T extends PromotionActionArgs = {}> extends PromotionAction<T> {
     private readonly executeFn: ExecutePromotionItemActionFn<T>;
@@ -64,7 +86,23 @@ export class PromotionItemAction<T extends PromotionActionArgs = {}> extends Pro
 }
 
 /**
- * Represents a PromotionAction which applies to the Order as a whole.
+ * @description
+ * Represents a PromotionAction which applies to the {@link Order} as a whole.
+ *
+ * @example
+ * ```ts
+ * // Applies a percentage discount to the entire Order
+ * const orderPercentageDiscount = new PromotionOrderAction({
+ *     code: 'order_percentage_discount',
+ *     args: { discount: 'percentage' },
+ *     execute(order, args) {
+ *         return -order.subTotal * (args.discount / 100);
+ *     },
+ *     description: 'Discount order by { discount }%',
+ * });
+ * ```
+ *
+ * @docsCategory promotions
  */
 export class PromotionOrderAction<T extends PromotionActionArgs = {}> extends PromotionAction<T> {
     private readonly executeFn: ExecutePromotionOrderActionFn<T>;

server/src/config/promotion/promotion-condition.ts

@@ -9,19 +9,42 @@ export type PromotionConditionArgType = 'int' | 'money' | 'string' | 'datetime'
 export type PromotionConditionArgs = ConfigArgs<PromotionConditionArgType>;
 
 /**
+ * @description
  * An object containing utility methods which may be used in promotion `check` functions
  * in order to determine whether a promotion should be applied.
+ *
+ * @docsCategory promotions
  */
 export interface PromotionUtils {
+    /**
+     * @description
+     * Checks a given {@link OrderLine} against the facetValueIds and returns
+     * `true` if the associated {@link ProductVariant} & {@link Product} together
+     * have *all* the specified {@link FacetValue}s.
+     */
     hasFacetValues: (orderLine: OrderLine, facetValueIds: ID[]) => Promise<boolean>;
 }
 
+/**
+ * @description
+ * A function which checks whether or not a given {@link Order} satisfies the {@link PromotionCondition}.
+ *
+ * @docsCategory promotions
+ */
 export type CheckPromotionConditionFn<T extends PromotionConditionArgs> = (
     order: Order,
     args: ConfigArgValues<T>,
     utils: PromotionUtils,
 ) => boolean | Promise<boolean>;
 
+/**
+ * @description
+ * PromotionConditions are used to create {@link Promotion}s. The purpose of a PromotionCondition
+ * is to check the order against a particular predicate function (the `check` function) and to return
+ * `true` if the Order satisfies the condition, or `false` if it does not.
+ *
+ * @docsCategory promotions
+ */
 export class PromotionCondition<T extends PromotionConditionArgs = {}> {
     readonly code: string;
     readonly description: string;

server/src/config/shipping-method/shipping-calculator.ts

@@ -10,6 +10,12 @@ export type CalculateShippingFn<T extends ShippingCalculatorArgs> = (
     args: ConfigArgValues<T>,
 ) => number | Promise<number>;
 
+/**
+ * @description
+ * The ShippingCalculator is used by a {@link ShippingMethod} to calculate the price of shipping on a given {@link Order}.
+ *
+ * @docsCategory shipping
+ */
 export class ShippingCalculator<T extends ShippingCalculatorArgs = {}> {
     readonly code: string;
     readonly description: string;
@@ -23,6 +29,10 @@ export class ShippingCalculator<T extends ShippingCalculatorArgs = {}> {
         this.calculateFn = config.calculate;
     }
 
+    /**
+     * @description
+     * Calculates the price of shipping for the given Order.
+     */
     calculate(order: Order, args: ConfigArg[]): number | Promise<number> {
         return this.calculateFn(order, argsArrayToHash(args));
     }

server/src/config/shipping-method/shipping-eligibility-checker.ts

@@ -10,6 +10,13 @@ export type CheckShippingEligibilityCheckerFn<T extends ShippingEligibilityCheck
     args: ConfigArgValues<T>,
 ) => boolean | Promise<boolean>;
 
+/**
+ * @description
+ * The ShippingEligibilityChecker class is used to check whether an order qualifies for a
+ * given {@link ShippingMethod}.
+ *
+ * @docsCategory shipping
+ */
 export class ShippingEligibilityChecker<T extends ShippingEligibilityCheckerArgs = {}> {
     readonly code: string;
     readonly description: string;
@@ -28,7 +35,11 @@ export class ShippingEligibilityChecker<T extends ShippingEligibilityCheckerArgs
         this.checkFn = config.check;
     }
 
-    check(order: Order, args: ConfigArg[]) {
+    /**
+     * @description
+     * Check the given Order to determine whether it is eligible.
+     */
+    check(order: Order, args: ConfigArg[]): boolean | Promise<boolean> {
         return this.checkFn(order, argsArrayToHash(args));
     }
 }

server/src/config/tax/default-tax-calculation-strategy.ts

@@ -6,6 +6,12 @@ import { TaxRateService } from '../../service/services/tax-rate.service';
 
 import { TaxCalculationArgs, TaxCalculationStrategy } from './tax-calculation-strategy';
 
+/**
+ * @description
+ * A default tax calculation function.
+ *
+ * @docsCategory tax
+ */
 export class DefaultTaxCalculationStrategy implements TaxCalculationStrategy {
     calculate(args: TaxCalculationArgs): TaxCalculationResult {
         const { inputPrice, activeTaxZone, ctx, taxCategory, taxRateService } = args;

server/src/config/tax/default-tax-zone-strategy.ts

@@ -2,6 +2,12 @@ import { Channel, Order, Zone } from '../../entity';
 
 import { TaxZoneStrategy } from './tax-zone-strategy';
 
+/**
+ * @description
+ * A default method of determining Zone for tax calculations.
+ *
+ * @docsCategory tax
+ */
 export class DefaultTaxZoneStrategy implements TaxZoneStrategy {
     determineTaxZone(zones: Zone[], channel: Channel, order?: Order): Zone {
         return channel.defaultTaxZone;

server/src/config/tax/tax-calculation-strategy.ts

@@ -3,6 +3,12 @@ import { TaxCategory, Zone } from '../../entity';
 import { TaxCalculationResult } from '../../service/helpers/tax-calculator/tax-calculator';
 import { TaxRateService } from '../../service/services/tax-rate.service';
 
+/**
+ * @description
+ * The arguments passed the the `calculate` method of the configured {@link TaxCalculationStrategy}.
+ *
+ * @docsCategory tax
+ */
 export interface TaxCalculationArgs {
     inputPrice: number;
     taxCategory: TaxCategory;

server/src/config/tax/tax-zone-strategy.ts

@@ -2,7 +2,7 @@ import { Channel, Order, Zone } from '../../entity';
 
 /**
  * @description
- * Defines how the active Zone is determined for the purposes of calculating taxes.
+ * Defines how the active {@link Zone} is determined for the purposes of calculating taxes.
  *
  * @docsCategory tax
  */

server/src/config/vendure-config.ts

@@ -30,6 +30,7 @@ import { VendurePlugin } from './vendure-plugin/vendure-plugin';
  * The AuthOptions define how authentication is managed.
  *
  * @docsCategory auth
+ * @docsWeight 0
  */
 export interface AuthOptions {
     /**
@@ -38,7 +39,7 @@ export interface AuthOptions {
      * NEVER set the to true in production. It exists
      * only to aid certain development tasks.
      *
-     * @default true
+     * @default false
      */
     disableAuth?: boolean;
     /**
@@ -158,33 +159,49 @@ export interface OrderMergeOptions {
  * @description
  * The AssetOptions define how assets (images and other files) are named and stored, and how preview images are generated.
  *
+ * {{% alert %}}
+ * If you are using the `DefaultAssetServerPlugin`,
+ * it is not necessary to configure these options.
+ * {{% /alert %}}
+ *
  * @docsCategory assets
+ * @docsWeight 0
  */
 export interface AssetOptions {
     /**
      * @description
      * Defines how asset files and preview images are named before being saved.
+     *
+     * @default DefaultAssetNamingStrategy
      */
     assetNamingStrategy: AssetNamingStrategy;
     /**
      * @description
      * Defines the strategy used for storing uploaded binary files.
+     *
+     * @default NoAssetStorageStrategy
      */
     assetStorageStrategy: AssetStorageStrategy;
     /**
      * @description
      * Defines the strategy used for creating preview images of uploaded assets.
+     *
+     * @default NoAssetPreviewStrategy
      */
     assetPreviewStrategy: AssetPreviewStrategy;
     /**
      * @description
      * The max file size in bytes for uploaded assets.
+     *
+     * @default 20971520
      */
     uploadMaxFileSize?: number;
 }
 
 /**
  * @docsCategory promotions
+ *
+ * @docsWeight 0
  */
 export interface PromotionOptions {
     /**
@@ -200,7 +217,8 @@ export interface PromotionOptions {
 }
 
 /**
- * @docsCategory orders
+ * @docsCategory shipping
+ * @docsWeight 0
  */
 export interface ShippingOptions {
     /**
@@ -210,39 +228,58 @@ export interface ShippingOptions {
     shippingEligibilityCheckers?: Array<ShippingEligibilityChecker<any>>;
     /**
      * @description
-     * An array of available ShippingCalculator for use in configuring ShippingMethods
+     * An array of available ShippingCalculators for use in configuring ShippingMethods
      */
     shippingCalculators?: Array<ShippingCalculator<any>>;
 }
 
 /**
+ * @description
+ * Defines how transactional emails (account verification, order confirmation etc) are generated and sent.
+ *
+ * {{% alert %}}
+ * It is usually not recommended to configure these yourself.
+ * You should use the `DefaultEmailPlugin`.
+ * {{% /alert %}}
+ *
  * @docsCategory email
+ * @docsWeight 0
  */
 export interface EmailOptions<EmailType extends string> {
     /**
      * @description
      * Path to the email template files.
+     *
+     * @default __dirname
      */
     emailTemplatePath: string;
     /**
      * @description
      * Configuration for the creation and templating of each email type
+     *
+     * @default {}
      */
     emailTypes?: EmailTypes<EmailType>;
     /**
      * @description
      * The EmailGenerator uses the EmailContext and template to generate the email body
+     *
+     * @default NoopEmailGenerator
      */
     generator?: EmailGenerator;
     /**
      * @description
      * Configuration for the transport (email sending) method
+     *
+     * @default NoopTransportOptions
      */
     transport: EmailTransportOptions;
 }
 
 /**
  * @docsCategory payment
+ *
+ * @docsWeight 0
  */
 export interface PaymentOptions {
     /**
@@ -254,27 +291,38 @@ export interface PaymentOptions {
 
 /**
  * @docsCategory tax
+ *
+ * @docsWeight 0
  */
 export interface TaxOptions {
     /**
      * @description
      * Defines the strategy used to determine the applicable Zone used in tax calculations.
+     *
+     * @default DefaultTaxZoneStrategy
      */
     taxZoneStrategy: TaxZoneStrategy;
     /**
      * @description
      * Defines the strategy used for calculating taxes.
+     *
+     * @default DefaultTaxCalculationStrategy
      */
     taxCalculationStrategy: TaxCalculationStrategy;
 }
 
 /**
- * @docsCategory
+ * @description
+ * Options related to importing & exporting data.
+ *
+ * @docsCategory import-export
  */
 export interface ImportExportOptions {
     /**
      * @description
      * The directory in which assets to be imported are located.
+     *
+     * @default __dirname
      */
     importAssetsDir?: string;
 }
@@ -296,6 +344,8 @@ export interface VendureConfig {
     /**
      * @description
      * The path to the GraphQL API.
+     *
+     * @default 'api'
      */
     apiPath?: string;
     /**
@@ -313,16 +363,22 @@ export interface VendureConfig {
      * The name of the property which contains the token of the
      * active channel. This property can be included either in
      * the request header or as a query string.
+     *
+     * @default 'vendure-token'
      */
     channelTokenKey?: string;
     /**
      * @description
-     * Set the CORS handling for the server.
+     * Set the CORS handling for the server. See the [express CORS docs](https://github.com/expressjs/cors#configuration-options).
+     *
+     * @default { origin: true, credentials: true }
      */
     cors?: boolean | CorsOptions;
     /**
      * @description
      * Defines custom fields which can be used to extend the built-in entities.
+     *
+     * @default {}
      */
     customFields?: CustomFields;
     /**
@@ -334,11 +390,15 @@ export interface VendureConfig {
      * @description
      * The token for the default channel. If not specified, a token
      * will be randomly generated.
+     *
+     * @default null
      */
     defaultChannelToken?: string | null;
     /**
      * @description
      * The default languageCode of the app.
+     *
+     * @default LanguageCode.en
      */
     defaultLanguageCode?: LanguageCode;
     /**
@@ -352,11 +412,15 @@ export interface VendureConfig {
      * in the database, and the encoding & decoding of those ids when exposing
      * entities via the API. The default uses a simple auto-increment integer
      * strategy.
+     *
+     * @default new AutoIncrementIdStrategy()
      */
     entityIdStrategy?: EntityIdStrategy<any>;
     /**
      * @description
-     * Set the hostname of the server.
+     * Set the hostname of the server. If not set, the server will be available on localhost.
+     *
+     * @default ''
      */
     hostname?: string;
     /**
@@ -378,6 +442,8 @@ export interface VendureConfig {
     /**
      * @description
      * Custom Express middleware for the server.
+     *
+     * @default []
      */
     middleware?: Array<{ handler: RequestHandler; route: string }>;
     /**
@@ -388,11 +454,15 @@ export interface VendureConfig {
     /**
      * @description
      * An array of plugins.
+     *
+     * @default []
      */
     plugins?: VendurePlugin[];
     /**
      * @description
      * Which port the Vendure server should listen on.
+     *
+     * @default 3000
      */
     port: number;
     /**
@@ -408,6 +478,8 @@ export interface VendureConfig {
     /**
      * @description
      * When set to true, no application logging will be output to the console.
+     *
+     * @default false
      */
     silent?: boolean;
     /**

server/src/config/vendure-plugin/vendure-plugin.ts

@@ -3,6 +3,12 @@ import { DocumentNode } from 'graphql';
 import { Type } from '../../../../shared/shared-types';
 import { VendureConfig } from '../vendure-config';
 
+/**
+ * @description
+ * A function which allows any injectable provider to be injected into the `onBootstrap` method of a {@link VendurePlugin}.
+ *
+ * @docsCategory plugin
+ */
 export type InjectorFn = <T>(type: Type<T>) => T;
 
 /**
@@ -14,7 +20,7 @@ export type InjectorFn = <T>(type: Type<T>) => T;
  * As well as configuring the app, a plugin may also extend the GraphQL schema by extending existing types or adding
  * entirely new types. Database entities and resolvers can also be defined to handle the extended GraphQL types.
  *
- * @docsCategory
+ * @docsCategory plugin
  */
 export interface VendurePlugin {
     /**

server/src/email/email-context.ts

@@ -2,9 +2,20 @@ import { LanguageCode } from '../../../shared/generated-types';
 
 import { VendureEvent } from '../event-bus/vendure-event';
 
+/**
+ * @description
+ * The EmailContext contains all the neccesary data required to generate an email
+ * (subject, body).
+ *
+ * @docsCategory email
+ */
 export class EmailContext<T extends string = any, E extends VendureEvent = any> {
     public readonly type: T;
     public readonly recipient: string;
+    /**
+     * @description
+     * The {@link VendureEvent} which triggered this email
+     */
     public readonly event: E;
     public readonly languageCode: LanguageCode;
     public readonly channelCode: string;
@@ -25,6 +36,11 @@ export class EmailContext<T extends string = any, E extends VendureEvent = any>
     }
 }
 
+/**
+ *
+ *
+ * @docsCateogry email
+ */
 export class GeneratedEmailContext<T extends string = any, E extends VendureEvent = any> extends EmailContext<
     T,
     E

server/src/entity/address/address.entity.ts

@@ -6,6 +6,12 @@ import { Country } from '../country/country.entity';
 import { CustomAddressFields } from '../custom-entity-fields';
 import { Customer } from '../customer/customer.entity';
 
+/**
+ * @description
+ * Represent's a {@link Customer}'s address.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Address extends VendureEntity implements HasCustomFields {
     constructor(input?: DeepPartial<Address>) {

server/src/entity/administrator/administrator.entity.ts

@@ -4,6 +4,12 @@ import { DeepPartial } from '../../../../shared/shared-types';
 import { VendureEntity } from '../base/base.entity';
 import { User } from '../user/user.entity';
 
+/**
+ * @description
+ * An administrative user who has access to the admin ui.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Administrator extends VendureEntity {
     constructor(input?: DeepPartial<Administrator>) {

server/src/entity/asset/asset.entity.ts

@@ -8,6 +8,13 @@ import { VendureEntity } from '../base/base.entity';
 import { CustomCustomerFields } from '../custom-entity-fields';
 import { User } from '../user/user.entity';
 
+/**
+ * @description
+ * An Asset represents a file such as an image which can be associated with certain other entities
+ * such as Products.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Asset extends VendureEntity {
     constructor(input?: DeepPartial<Asset>) {

server/src/entity/base/base.entity.ts

@@ -6,7 +6,11 @@ import { primaryKeyType } from '../../config/config-helpers';
 const keyType = primaryKeyType();
 
 /**
- * This is the base class from which all entities inherit.
+ * @description
+ * This is the base class from which all entities inherit. The type of
+ * the `id` property is defined by the {@link EntityIdStrategy}.
+ *
+ * @docsCategory entities
  */
 export abstract class VendureEntity {
     protected constructor(input?: DeepPartial<VendureEntity>) {

server/src/entity/channel/channel.entity.ts

@@ -5,6 +5,13 @@ import { DeepPartial } from '../../../../shared/shared-types';
 import { VendureEntity } from '../base/base.entity';
 import { Zone } from '../zone/zone.entity';
 
+/**
+ * @description
+ * A Channel represents a distinct sales channel and configures defaults for that
+ * channel.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Channel extends VendureEntity {
     constructor(input?: DeepPartial<Channel>) {

server/src/entity/country/country.entity.ts

@@ -6,6 +6,14 @@ import { VendureEntity } from '../base/base.entity';
 
 import { CountryTranslation } from './country-translation.entity';
 
+/**
+ * @description
+ * A country to which is available when creating / updating an {@link Address}. Countries are
+ * grouped together into {@link Zone}s which are in turn used to determine applicable shipping
+ * and taxes for an {@link Order}.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Country extends VendureEntity implements Translatable {
     constructor(input?: DeepPartial<Country>) {

server/src/entity/customer-group/customer-group.entity.ts

@@ -4,6 +4,13 @@ import { DeepPartial } from '../../../../shared/shared-types';
 import { VendureEntity } from '../base/base.entity';
 import { Customer } from '../customer/customer.entity';
 
+/**
+ * @description
+ * A grouping of {@link Customer}s which enables features such as group-based promotions
+ * or tax rules.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class CustomerGroup extends VendureEntity {
     constructor(input?: DeepPartial<CustomerGroup>) {

server/src/entity/customer/customer.entity.ts

@@ -10,6 +10,14 @@ import { CustomerGroup } from '../customer-group/customer-group.entity';
 import { Order } from '../order/order.entity';
 import { User } from '../user/user.entity';
 
+/**
+ * @description
+ * This entity represents a customer of the store, typically an individual person. A Customer can be
+ * a guest, in which case it has no associated {@link User}. Customers with registered account will
+ * have an associated User entity.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Customer extends VendureEntity implements HasCustomFields, SoftDeletable {
     constructor(input?: DeepPartial<Customer>) {

server/src/entity/facet-value/facet-value.entity.ts

@@ -8,6 +8,12 @@ import { Facet } from '../facet/facet.entity';
 
 import { FacetValueTranslation } from './facet-value-translation.entity';
 
+/**
+ * @description
+ * A particular value of a {@link Facet}.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class FacetValue extends VendureEntity implements Translatable, HasCustomFields {
     constructor(input?: DeepPartial<FacetValue>) {

server/src/entity/facet/facet.entity.ts

@@ -8,6 +8,17 @@ import { FacetValue } from '../facet-value/facet-value.entity';
 
 import { FacetTranslation } from './facet-translation.entity';
 
+/**
+ * @description
+ * A Facet is a class of properties which can be applied to a {@link Product} or {@link ProductVariant}.
+ * They are used to enable [faceted search](https://en.wikipedia.org/wiki/Faceted_search) whereby products
+ * can be filtered along a number of dimensions (facets).
+ *
+ * For example, there could be a Facet named "Brand" which has a number of {@link FacetValue}s representing
+ * the various brands of product, e.g. "Apple", "Samsung", "Dell", "HP" etc.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Facet extends VendureEntity implements Translatable, HasCustomFields {
     constructor(input?: DeepPartial<Facet>) {

server/src/entity/order-item/order-item.entity.ts

@@ -6,6 +6,12 @@ import { Calculated } from '../../common/calculated-decorator';
 import { VendureEntity } from '../base/base.entity';
 import { OrderLine } from '../order-line/order-line.entity';
 
+/**
+ * @description
+ * An individual item of an {@link OrderLine}.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class OrderItem extends VendureEntity {
     constructor(input?: DeepPartial<OrderItem>) {

server/src/entity/order-line/order-line.entity.ts

@@ -10,6 +10,12 @@ import { Order } from '../order/order.entity';
 import { ProductVariant } from '../product-variant/product-variant.entity';
 import { TaxCategory } from '../tax-category/tax-category.entity';
 
+/**
+ * @description
+ * A single line on an {@link Order} which contains one or more {@link OrderItem}s.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class OrderLine extends VendureEntity {
     constructor(input?: DeepPartial<OrderLine>) {

server/src/entity/order/order.entity.ts

@@ -18,6 +18,17 @@ import { OrderLine } from '../order-line/order-line.entity';
 import { Payment } from '../payment/payment.entity';
 import { ShippingMethod } from '../shipping-method/shipping-method.entity';
 
+/**
+ * @description
+ * An Order is created whenever a {@link Customer} adds an item to the cart. It contains all the
+ * information required to fulfill an order: which {@link ProductVariant}s in what quantities;
+ * the shipping address and price; any applicable promotions; payments etc.
+ *
+ * An Order exists in a well-defined state according to the {@link OrderState} type. A state machine
+ * is used to govern the transition from one state to another.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Order extends VendureEntity {
     constructor(input?: DeepPartial<Order>) {

server/src/entity/payment-method/payment-method.entity.ts

@@ -8,6 +8,13 @@ import { VendureEntity } from '../base/base.entity';
 import { Order } from '../order/order.entity';
 import { Payment, PaymentMetadata } from '../payment/payment.entity';
 
+/**
+ * @description
+ * A PaymentMethod is created automatically according to the configured {@link PaymentMethodHandler}s defined
+ * in the {@link PaymentOptions} config.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class PaymentMethod extends VendureEntity {
     constructor(input?: DeepPartial<PaymentMethod>) {

server/src/entity/payment/payment.entity.ts

@@ -7,6 +7,13 @@ import { Order } from '../order/order.entity';
 
 export type PaymentMetadata = { [key: string]: string | number | boolean };
 
+/**
+ * @description
+ * A Payment represents a single payment transaction and exists in a well-defined state
+ * defined by the {@link PaymentState} type.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Payment extends VendureEntity {
     constructor(input?: DeepPartial<Payment>) {

server/src/entity/product-category/product-category.entity.ts

@@ -21,6 +21,12 @@ import { FacetValue } from '../facet-value/facet-value.entity';
 
 import { ProductCategoryTranslation } from './product-category-translation.entity';
 
+/**
+ * @description
+ * A ProductCategory is a grouping of {@link Product}s based on {@link FacetValue}s.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 // TODO: It would be ideal to use the TypeORM built-in tree support, but unfortunately it is incomplete
 // at this time - does not support moving or deleting. See https://github.com/typeorm/typeorm/issues/2032

server/src/entity/product-option-group/product-option-group.entity.ts

@@ -9,6 +9,12 @@ import { ProductOption } from '../product-option/product-option.entity';
 
 import { ProductOptionGroupTranslation } from './product-option-group-translation.entity';
 
+/**
+ * @description
+ * A grouping of one or more {@link ProductOption}s.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class ProductOptionGroup extends VendureEntity implements Translatable, HasCustomFields {
     constructor(input?: DeepPartial<ProductOptionGroup>) {

server/src/entity/product-option/product-option.entity.ts

@@ -9,6 +9,12 @@ import { ProductOptionGroup } from '../product-option-group/product-option-group
 
 import { ProductOptionTranslation } from './product-option-translation.entity';
 
+/**
+ * @description
+ * A ProductOption is used to differentiate {@link ProductVariant}s from one another.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class ProductOption extends VendureEntity implements Translatable, HasCustomFields {
     constructor(input?: DeepPartial<ProductOption>) {

server/src/entity/product-variant/product-variant.entity.ts

@@ -15,6 +15,15 @@ import { TaxRate } from '../tax-rate/tax-rate.entity';
 import { ProductVariantPrice } from './product-variant-price.entity';
 import { ProductVariantTranslation } from './product-variant-translation.entity';
 
+/**
+ * @description
+ * A ProductVariant represents a single stock keeping unit (SKU) in the store's inventory.
+ * Whereas a {@link Product} is a "container" of variants, the variant itself holds the
+ * data on price, tax category etc. When one adds items to their cart, they are adding
+ * ProductVariants, not Products.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class ProductVariant extends VendureEntity implements Translatable, HasCustomFields {
     constructor(input?: DeepPartial<ProductVariant>) {

server/src/entity/product/product.entity.ts

@@ -13,6 +13,13 @@ import { ProductVariant } from '../product-variant/product-variant.entity';
 
 import { ProductTranslation } from './product-translation.entity';
 
+/**
+ * @description
+ * A Product contains one or more {@link ProductVariant}s and serves as a container for those variants,
+ * providing an overall name, description etc.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Product extends VendureEntity
     implements Translatable, HasCustomFields, ChannelAware, SoftDeletable {

server/src/entity/promotion/promotion.entity.ts

@@ -28,6 +28,16 @@ export interface ApplyOrderActionArgs {
     utils: PromotionUtils;
 }
 
+/**
+ * @description
+ * A Promotion is used to define a set of conditions under which promotions actions (typically discounts)
+ * will be applied to an Order.
+ *
+ * Each assigned {@link PromotionCondition} is checked against the Order, and if they all return `true`,
+ * then each assign {@link PromotionItemAction} / {@link PromotionOrderAction} is applied to the Order.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Promotion extends AdjustmentSource implements ChannelAware, SoftDeletable {
     type = AdjustmentType.PROMOTION;

server/src/entity/role/role.entity.ts

@@ -6,6 +6,13 @@ import { ChannelAware } from '../../common/types/common-types';
 import { VendureEntity } from '../base/base.entity';
 import { Channel } from '../channel/channel.entity';
 
+/**
+ * @description
+ * A Role represents a collection of permissions which determine the authorization
+ * level of a {@link User}.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Role extends VendureEntity implements ChannelAware {
     constructor(input?: DeepPartial<Role>) {

server/src/entity/session/session.entity.ts

@@ -6,6 +6,13 @@ import { Customer } from '../customer/customer.entity';
 import { Order } from '../order/order.entity';
 import { User } from '../user/user.entity';
 
+/**
+ * @description
+ * A Session is created when a user makes a request to the API. A Session can be an AnonymousSession
+ * in the case of un-authenticated users, otherwise it is an AuthenticatedSession.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 @TableInheritance({ column: { type: 'varchar', name: 'type' } })
 export abstract class Session extends VendureEntity {

server/src/entity/shipping-method/shipping-method.entity.ts

@@ -10,6 +10,16 @@ import { ShippingEligibilityChecker } from '../../config/shipping-method/shippin
 import { Channel } from '../channel/channel.entity';
 import { Order } from '../order/order.entity';
 
+/**
+ * @description
+ * A ShippingMethod is used to apply a shipping price to an {@link Order}. It is composed of a
+ * {@link ShippingEligibilityChecker} and a {@link ShippingCalculator}. For a given Order,
+ * the `checker` is used to determine whether this ShippingMethod can be used. If yes, then
+ * the ShippingMethod can be applied and the `calculator` is used to determine the price of
+ * shipping.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class ShippingMethod extends AdjustmentSource implements ChannelAware {
     type = AdjustmentType.SHIPPING;

server/src/entity/tax-category/tax-category.entity.ts

@@ -3,6 +3,12 @@ import { Column, Entity } from 'typeorm';
 import { DeepPartial } from '../../../../shared/shared-types';
 import { VendureEntity } from '../base/base.entity';
 
+/**
+ * @description
+ * A TaxCategory defines what type of taxes to apply to a {@link ProductVariant}.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class TaxCategory extends VendureEntity {
     constructor(input?: DeepPartial<TaxCategory>) {

server/src/entity/tax-rate/tax-rate.entity.ts

@@ -8,6 +8,16 @@ import { CustomerGroup } from '../customer-group/customer-group.entity';
 import { TaxCategory } from '../tax-category/tax-category.entity';
 import { Zone } from '../zone/zone.entity';
 
+/**
+ * @description
+ * A TaxRate defines the rate of tax to apply to a {@link ProductVariant} based on three factors:
+ *
+ * 1. the ProductVariant's {@link TaxCategory}
+ * 2. the applicable {@link Zone} ("applicable" being defined by the configured {@link TaxZoneStrategy})
+ * 3. the {@link CustomerGroup} of the current Customer
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class TaxRate extends AdjustmentSource {
     readonly type = AdjustmentType.TAX;

server/src/entity/user/user.entity.ts

@@ -5,6 +5,13 @@ import { VendureEntity } from '../base/base.entity';
 import { CustomUserFields } from '../custom-entity-fields';
 import { Role } from '../role/role.entity';
 
+/**
+ * @description
+ * A User represents any authenticated user of the Vendure API. This includes both
+ * {@link Administrator}s as well as registered {@link Customer}s.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class User extends VendureEntity implements HasCustomFields {
     constructor(input?: DeepPartial<User>) {

server/src/entity/zone/zone.entity.ts

@@ -4,6 +4,13 @@ import { DeepPartial } from '../../../../shared/shared-types';
 import { VendureEntity } from '../base/base.entity';
 import { Country } from '../country/country.entity';
 
+/**
+ * @description
+ * A Zone is a grouping of one or more {@link Country} entities. It is used for
+ * calculating applicable shipping and taxes.
+ *
+ * @docsCategory entities
+ */
 @Entity()
 export class Zone extends VendureEntity {
     constructor(input?: DeepPartial<Zone>) {

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

@@ -8,16 +8,20 @@ export type EventHandler<T extends VendureEvent> = (event: T) => void;
 export type UnsubscribeFn = () => void;
 
 /**
+ * @description
  * The EventBus is used to globally publish events which can then be subscribed to.
+ *
+ * @docsCategory events
  */
 @Injectable()
 export class EventBus {
     private subscriberMap = new Map<Type<VendureEvent>, Array<EventHandler<any>>>();
 
     /**
+     * @description
      * Publish an event which any subscribers can react to.
      */
-    publish(event: VendureEvent) {
+    publish(event: VendureEvent): void {
         const eventType = (event as any).constructor;
         const handlers = this.subscriberMap.get(eventType);
         if (handlers) {
@@ -29,6 +33,7 @@ export class EventBus {
     }
 
     /**
+     * @description
      * Subscribe to the given event type. Returns an unsubscribe function which can be used
      * to unsubscribe the handler from the event.
      */

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

@@ -1,7 +1,12 @@
 /**
+ * @description
  * The base class for all events used by the EventBus system.
+ *
+ * @docsCategory events
  */
 export abstract class VendureEvent {
-    public readonly createdAt = new Date();
-    protected constructor() {}
+    public readonly createdAt: Date;
+    protected constructor() {
+        this.createdAt = new Date();
+    }
 }

server/src/service/helpers/order-state-machine/order-state.ts

@@ -3,8 +3,11 @@ import { Transitions } from '../../../common/finite-state-machine';
 import { Order } from '../../../entity/order/order.entity';
 
 /**
+ * @description
  * These are the default states of the Order process. They can be augmented via
- * the orderProcessOptions property in VendureConfig.
+ * the `transtitions` property in the {@link OrderProcessOptions}.
+ *
+ * @docsCategory orders
  */
 export type OrderState =
     | 'AddingItems'

server/src/service/helpers/payment-state-machine/payment-state.ts

@@ -3,8 +3,10 @@ import { Order } from '../../../entity/order/order.entity';
 import { Payment } from '../../../entity/payment/payment.entity';
 
 /**
- * These are the default states of the Order process. They can be augmented via
- * the orderProcessOptions property in VendureConfig.
+ * @description
+ * These are the default states of the payment process.
+ *
+ * @docsCategory payment
  */
 export type PaymentState = 'Authorized' | 'Settled' | 'Declined' | 'Refunded' | 'Cancelled';
 
@@ -26,6 +28,13 @@ export const paymentStateTransitions: Transitions<PaymentState> = {
     },
 };
 
+/**
+ * @description
+ * The data which is passed to the `onStateTransitionStart` function configured when constructing
+ * a new `PaymentMethodHandler`
+ *
+ * @docsCategory payment
+ */
 export interface PaymentTransitionData {
     payment: Payment;
     order: Order;

shared/shared-types.ts

@@ -29,17 +29,41 @@ export type PaginatedList<T> = {
 };
 
 /**
- * An entity ID
+ * @description
+ * An entity ID. Depending on the configured {@link EntityIdStrategy}, it will be either
+ * a `string` or a `number`;
+ *
+ * @docsCategory entities
+ * @docsWeight 0
  */
 export type ID = string | number;
 
+/**
+ * @description
+ * A data type for a custom field.
+ *
+ * @docsCategory custom-fields
+ */
 export type CustomFieldType = 'string' | 'localeString' | 'int' | 'float' | 'boolean' | 'datetime';
 
+/**
+ * @description
+ * Configures a custom field on an entity in the {@link CustomFields} config object.
+ *
+ * @docsCategory custom-fields
+ */
 export interface CustomFieldConfig {
     name: string;
     type: CustomFieldType;
 }
 
+/**
+ * @description
+ * The certain entities can have additional fields added to them by defining an array of {@link CustomFieldConfig}
+ * objects on against the corresponding key.
+ *
+ * @docsCategory custom-fields
+ */
 export interface CustomFields {
     Address?: CustomFieldConfig[];
     Customer?: CustomFieldConfig[];