@vendure/docs 0.0.0-202601161541

package/docs/guides/core-concepts/channels/index.md

@@ -0,0 +1,154 @@
+---
+title: "Channels"
+---
+
+Channels are a feature of Vendure which allows multiple sales channels to be represented in a single Vendure instance. A Channel allows you to:
+
+* Set Channel-specific currency, language, tax and shipping defaults
+* Assign only specific products to the channel (with channel-specific prices)
+* Create administrator roles limited to one or more channels
+* Assign specific stock locations, assets, facets, collections, promotions, and other entities to the channel
+* Have orders and customers associated with specific channels.
+
+This is useful for a number of use-cases, including:
+
+- **Multi-tenancy**: Each channel can be configured with its own set of products, shipping methods, payment methods, etc. This
+  allows you to run multiple shops from a single Vendure server.
+- **Multi-vendor**: Each channel can represent a distinct vendor or seller, which can be used to implement a marketplace.
+- **Region-specific stores**: Each channel can be configured with its own set of languages, currencies, tax rates, etc. This
+  allows you to run multiple stores for different regions from a single Vendure server.
+- **Distinct sales channels**: Each channel can represent a sales channel of a single business, with one channel for the online
+  store, one for selling via Amazon, one for selling via Facebook etc.
+
+
+Every Vendure server always has a **default Channel**, which contains _all_ entities. Subsequent channels can then contain a subset of channel-aware entities.
+
+![Channels high level](./channels.webp)
+
+## Channel-aware entities
+
+Many entities are channel-aware, meaning that they can be associated with a multiple channels. The following entities are channel-aware:
+
+- [`Asset`](/reference/typescript-api/entities/asset/)
+- [`Collection`](/reference/typescript-api/entities/collection/)
+- [`Customer`](/reference/typescript-api/entities/customer/)
+- [`Facet`](/reference/typescript-api/entities/facet/)
+- [`FacetValue`](/reference/typescript-api/entities/facet-value/)
+- [`Order`](/reference/typescript-api/entities/order/)
+- [`PaymentMethod`](/reference/typescript-api/entities/payment-method/)
+- [`Product`](/reference/typescript-api/entities/product/)
+- [`ProductVariant`](/reference/typescript-api/entities/product-variant/)
+- [`Promotion`](/reference/typescript-api/entities/promotion/)
+- [`Role`](/reference/typescript-api/entities/role/)
+- [`ShippingMethod`](/reference/typescript-api/entities/shipping-method/)
+- [`StockLocation`](/reference/typescript-api/entities/stock-location/)
+
+## Channels & Sellers
+
+Each channel is also assigned a single [`Seller`](/reference/typescript-api/entities/seller/). This entity is used to represent
+the vendor or seller of the products in the channel. This is useful for implementing a marketplace, where each channel represents
+a distinct vendor. The `Seller` entity can be extended with [custom fields](/guides/developer-guide/custom-fields/) to store additional information about the seller, such as a logo, contact details etc.
+
+## Channels, Currencies & Prices
+
+Each Channel has a set of `availableCurrencyCodes`, and one of these is designated as the `defaultCurrencyCode`, which sets the default currency for all monetary values in that channel.
+
+![Default currencies](./default-currency.webp)
+
+Internally, there is a one-to-many relation from [`ProductVariant`](/reference/typescript-api/entities/product-variant/) to [`ProductVariantPrice`](/reference/typescript-api/entities/product-variant-price). So the ProductVariant does _not_ hold a price for the product - this is actually stored on the `ProductVariantPrice` entity, and there will be at least one for each Channel to which the ProductVariant has been assigned.
+
+![Product variant prices](./variant-prices.webp)
+
+In this diagram we can see that every channel has at least 1 `ProductVariantPrice`. In the case of the UK Channel, there are 2 prices assigned - one for
+GBP and one for USD. This means that you are able to define multiple prices in different currencies on a single product variant for a single channel.
+
+:::info
+**Note:** in the diagram above that the ProductVariant is **always assigned to the default Channel**, and thus will have a price in the default channel too. Likewise, the default Channel also has a defaultCurrencyCode. Depending on your requirements, you may or may not make use of the default Channel.
+:::
+
+### Keeping prices synchronized
+
+When you have products assigned to multiple channels, updates to the price of a product in one channel will not automatically
+be reflected in other channels. For instance, in the diagram above, both the Default channel and the UK channel have a price
+in USD for the same product variant. 
+
+If an administrator of the UK channel changes the USD price to $20, the price in the Default channel will remain at $30. This
+is the default behavior, and is controlled by the [ProductVariantPriceUpdateStrategy](/reference/typescript-api/configuration/product-variant-price-update-strategy).
+
+If you want to keep prices synchronized across all channels, you can set the `syncPricesAcrossChannels` property of the
+[DefaultProductVariantPriceUpdateStrategy](/reference/typescript-api/configuration/product-variant-price-update-strategy#defaultproductvariantpriceupdatestrategy)
+to `true`. This will ensure that when the price of a product variant is updated in one channel, the price in all other channels
+(of that particular currency) will be updated to match.
+
+```ts
+import { DefaultProductVariantPriceUpdateStrategy, VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+    // ...
+    // highlight-start
+    productVariantPriceUpdateStrategy: new DefaultProductVariantPriceUpdateStrategy({
+        syncPricesAcrossChannels: true,
+    }),
+    // highlight-end
+    // ...
+};
+```
+
+You may however require even more sophisticated logic. For instance, you may want a one-way synchronization, where the price
+in the Default channel is always the master price, and the prices in other channels are updated to match. In this case, you
+can create a custom `ProductVariantPriceUpdateStrategy` which implements the desired logic.
+
+## Use cases
+
+### Single shop
+
+This is the simplest set-up. You just use the default Channel for everything.
+
+### Multiple separate shops
+
+Let's say you are running multiple distinct businesses, each with its own distinct inventory and possibly different currencies. In this case, you set up a Channel for each shop and create the Product & Variants in the relevant shop's Channel.
+
+The default Channel can then be used by the superadmin for administrative purposes, but other than that the default Channel would not be used. Storefronts would only target a specific shop's Channel.
+
+### Multiple shops sharing inventory
+
+Let's say you have a single inventory but want to split it between multiple shops. There might be overlap in the inventory, e.g. the US & EU shops share 80% of inventory, and then the rest is specific to either shop.
+
+In this case, you can create the entire inventory in the default Channel and then assign the Products & ProductVariants to each Channel as needed, setting the price as appropriate for the currency used by each shop.
+
+:::caution
+**Note:** When creating a new Product & ProductVariants inside a sub-Channel, it will also **always get assigned to the default Channel**. If your sub-Channel uses a different currency from the default Channel, you should be aware that in the default Channel, that ProductVariant will be assigned the **same price** as it has in the sub-Channel. If the currency differs between the Channels, you need to make sure to set the correct price in the default Channel if you are exposing it to Customers via a storefront. 
+:::
+
+### Multi-vendor marketplace
+
+This is the most advanced use of channels. For a detailed guide to this use-case, see our [Multi-vendor marketplace guide](/guides/how-to/multi-vendor-marketplaces/).
+
+
+## Specifying channel in the GraphQL API
+
+To specify which channel to use when making an API call, set the `'vendure-token'` header to match the token of the desired Channel.
+
+For example, if we have a UK Channel with the token set to "uk-channel" as shown in this screenshot:
+
+![UK Channel](./channel-token.webp)
+
+Then we can make a GraphQL API call to the UK Channel by setting the `'vendure-token'` header to `'uk-channel'`:
+
+```ts title="GraphQL API call to UK Channel"
+const { loading, error, data } = useQuery(GET_PRODUCT_LIST, {
+    context: {
+        // highlight-start
+        headers: {
+            'vendure-token': 'uk-channel',
+        },
+        // highlight-end
+    },
+});
+```
+
+:::note
+This is an example using Apollo Client in React. The same principle applies to any GraphQL client library - set the `'vendure-token'` header to the token of the desired Channel.
+:::
+
+With the above header set, the API call will be made to the UK Channel, and the response will contain only the entities which are assigned to that Channel.

package/docs/guides/core-concepts/collections/index.mdx

@@ -0,0 +1,125 @@
+---
+title: 'Collections'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+[`Collections`](/reference/typescript-api/entities/collection/) are used to categorize and organize your catalog. A collection
+contains multiple product variants, and a product variant can belong to multiple collections. Collections can be nested to
+create a hierarchy of categories, which is typically used to create a menu structure in the storefront.
+
+![Collections](./collections.webp)
+
+Collections are not _only_ used as the basis of storefront navigation. They are a general-purpose organization tool which can be used
+for many purposes, such as:
+
+- Creating a collection of "new arrivals" which is used on the homepage.
+- Creating a collection of "best sellers" which is used to display a list of popular products.
+- Creating a collection of "sale items" which is used to apply a discount to all products in the collection, via a promotion.
+
+## Collection filters
+
+The specific product variants that belong to a collection are determined by the collection's [`CollectionFilters`](/reference/typescript-api/configuration/collection-filter/).
+A collection filter is a piece of logic which is used to determine whether a product variant should be included in the collection. By default, Vendure
+includes a number of collection filters:
+
+- **Filter by facet values**: Include all product variants which have a specific set of facet values.
+- **Filter by product variant name**: Include all product variants whose name matches a specific string.
+- **Manually select product variants**: Allows manual selection of individual product variants.
+- **Manually select products**: Allows manual selection of entire products, and then includes all variants of those products.
+
+![Collection filters](./collection-filters.webp)
+
+It is also possible to create your own custom collection filters, which can be used to implement more complex logic. See the section on [creating a collection filter](#creating-a-collection-filter) for more details.
+
+### Filter inheritance
+
+When a collection is nested within another collection, the child collection can inherit the parent's collection filters. This means that the child collection
+will _combine_ its own filters with the parent's filters.
+
+![Filter inheritance](./filter-inheritance.webp)
+
+In the example above, we have a parent collection "Menswear", with a child collection "Mens' Casual". The parent collection has a filter which includes all
+product variants with the "clothing" and "mens" facet values. The child collection is set to inherit the parent's filters, and has an additional filter which
+includes all product variants with the "casual" facet value.
+
+Thus, the child collection will include all product variants which have the "clothing", "mens" and "casual" facet values.
+
+:::note
+When filter inheritance is enabled, a child collection will contain a **subset** of the product variants of its parent collection.
+
+In order to create a child collection which contains product variants _not_ contained by the parent collection, you must disable filter inheritance
+in the child collection.
+:::
+
+### Creating a collection filter
+
+You can create your own custom collection filters with the [`CollectionFilter`](/reference/typescript-api/configuration/collection-filter/) class. This class
+is a [configurable operation](/guides/developer-guide/strategies-configurable-operations/#configurable-operations) where the specific
+filtering logic is implemented in the `apply()` method passed to its constructor.
+
+The `apply()` method receives an instance of the [TypeORM SelectQueryBuilder](https://typeorm.io/select-query-builder) which should have filtering logic
+added to it using the `.andWhere()` method.
+
+Here's an example of a collection filter which filters by SKU:
+
+```ts title="src/config/sku-collection-filter.ts"
+import { CollectionFilter, LanguageCode } from '@vendure/core';
+
+export const skuCollectionFilter = new CollectionFilter({
+    args: {
+        // The `args` object defines the user-configurable arguments
+        // which will get passed to the filter's `apply()` function.
+        sku: {
+            type: 'string',
+            label: [{ languageCode: LanguageCode.en, value: 'SKU' }],
+            description: [
+                {
+                    languageCode: LanguageCode.en,
+                    value: 'Matches any product variants with an SKU containing this value',
+                },
+            ],
+        },
+    },
+    code: 'variant-sku-filter',
+    description: [{ languageCode: LanguageCode.en, value: 'Filter by matching SKU' }],
+
+    // This is the function that defines the logic of the filter.
+    apply: (qb, args) => {
+        // Sometimes syntax differs between database types, so we use
+        // the `type` property of the connection options to determine
+        // which syntax to use.
+        const LIKE = qb.connection.options.type === 'postgres' ? 'ILIKE' : 'LIKE';
+
+        return qb.andWhere(`productVariant.sku ${LIKE} :sku`, {
+            sku: `%${args.sku}%`
+        });
+    },
+});
+```
+
+In the `apply()` method, the product variant entity is aliased as `'productVariant'`.
+
+This custom filter is then added to the defaults in your config:
+
+```ts title="src/vendure-config.ts"
+import { defaultCollectionFilters, VendureConfig } from '@vendure/core';
+import { skuCollectionFilter } from './config/sku-collection-filter';
+
+export const config: VendureConfig = {
+    // ...
+    catalogOptions: {
+        collectionFilters: [
+            ...defaultCollectionFilters,
+            // highlight-next-line
+            skuCollectionFilter
+        ],
+    },
+};
+```
+
+:::info
+To see some more advanced collection filter examples, you can look at the source code of the
+[default collection filters](https://github.com/vendurehq/vendure/blob/master/packages/core/src/config/catalog/default-collection-filters.ts).
+:::

package/docs/guides/core-concepts/customers/index.mdx

@@ -0,0 +1,21 @@
+---
+title: "Customers"
+---
+
+A [`Customer`](/reference/typescript-api/entities/customer/) is a person who can buy from your shop. A customer can have one or more
+[`Addresses`](/reference/typescript-api/entities/address/), which are used for shipping and billing.
+
+If a customer has registered an account, they will have an associated [`User`](/reference/typescript-api/entities/user/). The user
+entity is used for authentication and authorization. **Guest checkouts** are also possible, in which case a customer will not have a user.
+
+:::info
+See the [Auth guide](/guides/core-concepts/auth/#customer-auth) for a detailed explanation of the relationship between
+customers and users.
+:::
+
+![Customer](./customer.webp)
+
+Customers can be organized into [`CustomerGroups`](/reference/typescript-api/entities/customer-group/). These groups can be used in
+logic relating to promotions, shipping rules, payment rules etc. For example, you could create a "VIP" customer group and then create
+a promotion which grants members of this group free shipping. Or a "B2B" group which is used in a custom tax calculator to
+apply a different tax rate to B2B customers.

package/docs/guides/core-concepts/email/index.mdx

@@ -0,0 +1,155 @@
+---
+title: "Email & Notifications"
+---
+
+A typical ecommerce application needs to notify customers of certain events, such as when they place an order or
+when their order has been shipped. This is usually done via email, but can also be done via SMS or push notifications.
+
+## Email
+
+Email is the most common way to notify customers of events, so a default Vendure installation includes our [EmailPlugin](/reference/core-plugins/email-plugin).
+
+The EmailPlugin by default uses [Nodemailer](https://nodemailer.com/about/) to send emails via a variety of
+different transports, including SMTP, SendGrid, Mailgun, and more.
+The plugin is configured with a list of [EmailEventHandlers](/reference/core-plugins/email-plugin/email-event-handler) which are responsible for
+sending emails in response to specific events.
+
+:::note
+This guide will cover some of the main concepts of the EmailPlugin, but for a more in-depth look at how to configure
+and use it, see the [EmailPlugin API docs](/reference/core-plugins/email-plugin).
+:::
+
+Here's an illustration of the flow of an email being sent:
+
+![Email plugin flow](./email-plugin-flow.webp)
+
+All emails are triggered by a particular [Event](/guides/developer-guide/events/) - in this case when the state of an
+Order changes. The EmailPlugin ships with a set of [default email handlers](https://github.com/vendurehq/vendure/blob/master/packages/email-plugin/src/default-email-handlers.ts),
+one of which is responsible for sending "order confirmation" emails.
+
+### EmailEventHandlers
+
+Let's take a closer look at a simplified version of the `orderConfirmationHandler`:
+
+```ts
+import { OrderStateTransitionEvent } from '@vendure/core';
+import { EmailEventListener, transformOrderLineAssetUrls, hydrateShippingLines } from '@vendure/email-plugin';
+
+// The 'order-confirmation' string is used by the EmailPlugin to identify
+// which template to use when rendering the email.
+export const orderConfirmationHandler = new EmailEventListener('order-confirmation')
+    .on(OrderStateTransitionEvent)
+    // Only send the email when the Order is transitioning to the
+    // "PaymentSettled" state and the Order has a customer associated with it.
+    .filter(
+        event =>
+            event.toState === 'PaymentSettled'
+            && !!event.order.customer,
+    )
+    // We commonly need to load some additional data to be able to render the email
+    // template. This is done via the `loadData()` method. In this method we are
+    // mutating the Order object to ensure that product images are correctly
+    // displayed in the email, as well as fetching shipping line data from the database.
+    .loadData(async ({ event, injector }) => {
+        transformOrderLineAssetUrls(event.ctx, event.order, injector);
+        const shippingLines = await hydrateShippingLines(event.ctx, event.order, injector);
+        return { shippingLines };
+    })
+    // Here we are setting the recipient of the email to be the
+    // customer's email address.
+    .setRecipient(event => event.order.customer!.emailAddress)
+    // We can interpolate variables from the EmailPlugin's configured
+    // `globalTemplateVars` object.
+    .setFrom('{{ fromAddress }}')
+    // We can also interpolate variables made available by the
+    // `setTemplateVars()` method below
+    .setSubject('Order confirmation for #{{ order.code }}')
+    // The object returned here defines the variables which are
+    // available to the email template.
+    .setTemplateVars(event => ({ order: event.order, shippingLines: event.data.shippingLines }))
+```
+
+To recap:
+
+- The handler listens for a specific event
+- It optionally filters those events to determine whether an email should be sent
+- It specifies the details of the email to be sent, including the recipient, subject, template variables, etc.
+
+The full range of methods available when setting up an EmailEventHandler can be found in the [EmailEventHandler API docs](/reference/core-plugins/email-plugin/email-event-handler).
+
+### Email variables
+
+In the example above, we used the `setTemplateVars()` method to define the variables which are available to the email template.
+Additionally, there are global variables which are made available to _all_ email templates & EmailEventHandlers. These are
+defined in the `globalTemplateVars` property of the EmailPlugin config:
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+import { EmailPlugin } from '@vendure/email-plugin';
+
+export const config: VendureConfig = {
+    // ...
+    plugins: [
+        EmailPlugin.init({
+            // ...
+            // highlight-start
+            globalTemplateVars: {
+                fromAddress: '"MyShop" <noreply@myshop.com>',
+                verifyEmailAddressUrl: 'https://www.myshop.com/verify',
+                passwordResetUrl: 'https://www.myshop.com/password-reset',
+                changeEmailAddressUrl: 'https://www.myshop.com/verify-email-address-change'
+            },
+            // highlight-end
+        }),
+    ],
+};
+```
+
+### Email integrations
+
+The EmailPlugin is designed to be flexible enough to work with many different email services. The default
+configuration uses Nodemailer to send emails via SMTP, but you can easily configure it to use a different
+transport. For instance:
+
+- [AWS SES](https://www.vendure.io/marketplace/aws-ses)
+- [SendGrid](https://www.vendure.io/marketplace/sendgrid)
+
+## Other notification methods
+
+The pattern of listening for events and triggering some action in response is not limited to emails. You can
+use the same pattern to trigger other actions, such as sending SMS messages or push notifications. For instance,
+let's say you wanted to create a plugin which sends an SMS message to the customer when their order is shipped.
+
+:::note
+This is just a simplified example to illustrate the pattern.
+:::
+
+```ts title="src/plugins/sms-plugin/sms-plugin.ts"
+import { OnModuleInit } from '@nestjs/common';
+import { PluginCommonModule, VendurePlugin, EventBus } from '@vendure/core';
+import { OrderStateTransitionEvent } from '@vendure/core';
+
+// A custom service which sends SMS messages
+// using a third-party SMS provider such as Twilio.
+import { SmsService } from './sms.service';
+
+@VendurePlugin({
+    imports: [PluginCommonModule],
+    providers: [SmsService],
+})
+export class SmsPlugin implements OnModuleInit {
+    constructor(
+        private eventBus: EventBus,
+        private smsService: SmsService,
+    ) {}
+
+    onModuleInit() {
+        this.eventBus
+            .ofType(OrderStateTransitionEvent)
+            .filter(event => event.toState === 'Shipped')
+            .subscribe(event => {
+                this.smsService.sendOrderShippedMessage(event.order);
+            });
+    }
+}
+```

package/docs/guides/core-concepts/images-assets/index.mdx

@@ -0,0 +1,42 @@
+---
+title: "Images & Assets"
+---
+
+[`Assets`](/reference/typescript-api/entities/asset/) are used to store files such as images, videos, PDFs, etc. Assets can be
+assigned to **products**, **variants** and **collections** by default. By using [custom fields](/guides/developer-guide/custom-fields/) it is
+possible to assign assets to other entities. For example, for implementing customer profile images.
+
+The handling of assets in Vendure is implemented in a modular way, allowing you full control over the way assets
+are stored, named, imported and previewed.
+
+![Asset creation and retrieval](./asset-flow.webp)
+
+1. An asset is created by uploading an image. Internally the [`createAssets` mutation](/reference/graphql-api/admin/mutations/#createassets) will be executed.
+2. The [`AssetNamingStrategy`](/reference/typescript-api/assets/asset-naming-strategy/) is used to generate file names for the source image and the preview. This is useful for normalizing file names as well as handling name conflicts.
+3. The [`AssetPreviewStrategy`](/reference/typescript-api/assets/asset-preview-strategy) generates a preview image of the asset. For images, this typically involves creating a version with constraints on the maximum dimensions. It could also be used to e.g. generate a preview image for uploaded PDF files, videos or other non-image assets (such functionality would require a custom `AssetPreviewStrategy` to be defined).
+4. The source file as well as the preview image are then passed to the [`AssetStorageStrategy`](/reference/typescript-api/assets/asset-storage-strategy) which stores the files to some form of storage. This could be the local disk or an object store such as AWS S3 or Minio.
+5. When an asset is later read, e.g. when a customer views a product detail page which includes an image of the product, the `AssetStorageStrategy` can be used to
+read the file from the storage location.
+
+
+## AssetServerPlugin
+
+Vendure comes with the `@vendure/asset-server-plugin` package pre-installed. This provides the [`AssetServerPlugin`](/reference/core-plugins/asset-server-plugin/) which provides many advanced features to make working with
+assets easier.
+
+The plugin provides a ready-made set of strategies for handling assets, but also allows you to replace these defaults with
+your own implementations. For example, here are instructions on how to replace the default storage strategy with one
+that stores your assets on AWS S3 or Minio: [configure S3 asset storage](/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy#configures3assetstorage)
+
+It also features a powerful image transformation API, which allows you to specify the dimensions, crop, and image format
+using query parameters.
+
+:::info
+See the [AssetServerPlugin docs](/reference/core-plugins/asset-server-plugin/) for a detailed description of all the features.
+:::
+
+## Asset Tags
+
+Assets can be tagged. A [`Tag`](/reference/typescript-api/entities/tag/) is a simple text label that can be applied to an asset. An asset can have multiple tags or none. Tags are useful for organizing assets, since assets are otherwise organized as a flat list with no concept of a directory structure.
+
+![Asset tags](./asset-tags.webp)