Merge branch 'master' into minor

.github/ISSUE_TEMPLATE/bug_report.md

@@ -3,7 +3,7 @@ name: Bug report
 about: Something not working as it should
 title: ''
 labels: "type: bug \U0001F41B"
-assignees: michaelbromley
+assignees: ''
 
 ---
 

README.md

@@ -6,7 +6,7 @@ An open-source headless commerce platform built on [Node.js](https://nodejs.org)
 ![Publish & Install](https://github.com/vendure-ecommerce/vendure/workflows/Publish%20&%20Install/badge.svg)
 [![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lernajs.io/)
 
-![vendure_github_banner (1)](https://github.com/vendure-ecommerce/vendure/assets/6275952/0e25b1c7-a648-44a1-ba00-60012f0e7aaa)
+![vendure-github-social-banner](https://github.com/vendure-ecommerce/vendure/assets/24294584/ada25fa3-185d-45ce-896d-bece3685a829)
 
 
 ### [www.vendure.io](https://www.vendure.io/)

docs/README.md

@@ -1,6 +1,6 @@
 # Website
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator.
 
 ### Installation
 

docs/docs/guides/core-concepts/money/index.mdx

@@ -8,6 +8,8 @@ This is a common practice in financial applications, as it avoids the rounding e
 
 For example, here's the response from a query for a product's variant prices:
 
+
+
 ```json
 {
   "data": {
@@ -120,7 +122,7 @@ then you should also use the `Money` scalar for any monetary values.
 
 ## The `@Money()` decorator
 
-When [defining new database entities](/guides/developer-guide/database-entity//), if you need to store a monetary value, then rather than using the TypeORM `@Column()`
+When [defining new database entities](/guides/developer-guide/database-entity), if you need to store a monetary value, then rather than using the TypeORM `@Column()`
 decorator, you should use Vendure's [`@Money()` decorator](/reference/typescript-api/money/money-decorator).
 
 Using this decorator allows Vendure to correctly store the value in the database according to the configured `MoneyStrategy` (see below).
@@ -234,4 +236,4 @@ export function formatCurrency(value: number, currencyCode: string, locale?: str
         return majorUnits.toFixed(3);
     }
 }
-```
+```

docs/docs/guides/core-concepts/payment/index.md

@@ -255,7 +255,7 @@ The `metadata` field is used to store the specific data required by the payment
 The `metadata` field is required, so if your payment provider does not require any additional data, you can simply pass an empty object: `metadata: {}`.
 :::
 
-3. This mutation internally invokes the [PaymentMethodHandler's `createPayment()` function](/reference/typescript-api/payment/payment-method-config-options/#createpayment). This function returns a [CreatePaymentResult object](/reference/typescript-api/payment/payment-method-types#createpaymentfn) which is used to create a new [Payment](reference/typescript-api/entities/payment). If the Payment amount equals the order total, then the Order is transitioned to either the `PaymentAuthorized` or `PaymentSettled` state and the customer checkout flow is complete.
+3. This mutation internally invokes the [PaymentMethodHandler's `createPayment()` function](/reference/typescript-api/payment/payment-method-config-options/#createpayment). This function returns a [CreatePaymentResult object](/reference/typescript-api/payment/payment-method-types#createpaymentfn) which is used to create a new [Payment](/reference/typescript-api/entities/payment). If the Payment amount equals the order total, then the Order is transitioned to either the `PaymentAuthorized` or `PaymentSettled` state and the customer checkout flow is complete.
 
 ### Single-step
 

docs/docs/guides/developer-guide/custom-fields/index.md

@@ -637,6 +637,16 @@ const config = {
 };
 ```
 
+:::note
+
+The `requiresPermission` property only affects the _Admin API_. Access to a custom field via the _Shop API_ is controlled by the `public` property.
+
+If you need special logic to control access to a custom field in the Shop API, you can set `public: false` and then implement
+a custom [field resolver](/guides/developer-guide/extend-graphql-api/#add-fields-to-existing-types) which contains the necessary logic, and returns
+the entity's custom field value if the current customer meets the requirements.
+
+:::
+
 ### Properties for `string` fields
 
 In addition to the common properties, the `string` custom fields have some type-specific properties:

docs/docs/guides/developer-guide/events/index.mdx

@@ -242,7 +242,7 @@ export class ProductReviewService {
 
 ### Entity events
 
-There is a special event class [`VendureEntityEvent`](/reference/typescript-api/events/vendure-entity-event) for events relating to the creation, update or deletion of entities. Let's say you have a custom entity (see [defining a database entity](/guides/developer-guide/database-entity//)) `BlogPost` and you want to trigger an event whenever a new `BlogPost` is created, updated or deleted:
+There is a special event class [`VendureEntityEvent`](/reference/typescript-api/events/vendure-entity-event) for events relating to the creation, update or deletion of entities. Let's say you have a custom entity (see [defining a database entity](/guides/developer-guide/database-entity)) `BlogPost` and you want to trigger an event whenever a new `BlogPost` is created, updated or deleted:
 
 ```ts title="src/plugins/blog/events/blog-post-event.ts"
 import { ID, RequestContext, VendureEntityEvent } from '@vendure/core';

docs/docs/guides/developer-guide/extend-graphql-api/index.md

@@ -191,7 +191,7 @@ export class BannerPlugin {}
 
 If you have defined a new database entity, it is likely that you'll want to expose this entity in your GraphQL API. To do so, you'll need to define a corresponding GraphQL type.
 
-Using the `ProductReview` entity from the [Define a database entity guide](/guides/developer-guide/database-entity//), let's see how we can expose it as a new type in the API.
+Using the `ProductReview` entity from the [Define a database entity guide](/guides/developer-guide/database-entity), let's see how we can expose it as a new type in the API.
 
 As a reminder, here is the `ProductReview` entity:
 

docs/docs/guides/developer-guide/importing-data/index.md

@@ -47,7 +47,7 @@ Here's an explanation of each column:
 
 ### Importing Custom Field Data
 
-If you have [CustomFields]({{< relref "customizing-models" >}}) defined on your Product or ProductVariant entities, this data can also be encoded in the import csv:
+If you have [CustomFields](/guides/developer-guide/custom-fields/) defined on your Product or ProductVariant entities, this data can also be encoded in the import csv:
 
 * `product:<customFieldName>`: The value of this column will populate `Product.customFields[customFieldName]`. 
 * `variant:<customFieldName>`: The value of this column will populate `ProductVariant.customFields[customFieldName]`. 

docs/docs/guides/developer-guide/migrating-from-v1/breaking-api-changes.md

@@ -127,7 +127,7 @@ const order = await this.connection
 
 With [#1545](https://github.com/vendure-ecommerce/vendure/issues/1545) we have changed the way we model stock levels in order to support multiple stock locations. This means that the `ProductVariant.stockOnHand` and `ProductVariant.stockAllocated` properties no longer exist on the `ProductVariant` entity in TypeScript.
 
-Instead, this information is now located at `ProductVariant.stockLevels`, which is an array of [StockLevel]({{< relref "stock-level" >}}) entities.
+Instead, this information is now located at `ProductVariant.stockLevels`, which is an array of [StockLevel](/reference/typescript-api/entities/stock-level) entities.
 
 ### New return type for Channel, TaxCategory & Zone lists
 
@@ -166,7 +166,7 @@ If you are using the `@vendure/ui-devkit` package to generate custom ui extensio
 - The Admin UI component `vdr-product-selector` has been renamed to `vdr-product-variant-selector` to more accurately represent what it does. If you are using `vdr-product-selector` if any ui extensions code, update it to use the new selector.
 
 ### Other breaking API changes
-- **End-to-end tests using Jest** will likely run into issues due to our move towards using some dependencies that make use of ES modules. We have found the best solution to be to migrate tests over to [Vitest](https://vitest.dev), which can handle this and is also significantly faster than Jest. See the updated [Testing guide]({{< relref "/guides/developer-guide/testing" >}}) for instructions on getting started with Vitest.
+- **End-to-end tests using Jest** will likely run into issues due to our move towards using some dependencies that make use of ES modules. We have found the best solution to be to migrate tests over to [Vitest](https://vitest.dev), which can handle this and is also significantly faster than Jest. See the updated [Testing guide](/guides/developer-guide/testing) for instructions on getting started with Vitest.
 - Internal `ErrorResult` classes now take a single object argument rather than multiple args.
 - All monetary values are now represented in the GraphQL APIs with a new `Money` scalar type. If you use [graphql-code-generator](https://the-guild.dev/graphql/codegen), you'll want to tell it to treat this scalar as a number:
     ```ts
@@ -210,4 +210,4 @@ If you are using the `@vendure/ui-devkit` package to generate custom ui extensio
 - If you are using the **BullMQJobQueuePlugin**, the minimum Redis recommended version is 6.2.0.
 - The `WorkerHealthIndicator` which was deprecated in v1.3.0 has been removed, as well as the `jobQueueOptions.enableWorkerHealthCheck` config option.
 - The `CustomerGroupEntityEvent` (fired on creation, update or deletion of a CustomerGroup) has been renamed to `CustomerGroupEvent`, and the former `CustomerGroupEvent` (fired when Customers are added to or removed from a group) has been renamed to `CustomerGroupChangeEvent`.
-- We introduced the [plugin compatibility API]({{< relref "vendure-plugin-metadata" >}}#compatibility) to allow plugins to indicate what version of Vendure they are compatible with. To avoid bootstrap messages you should add this property to your plugins.
+- We introduced the [plugin compatibility API](/guides/developer-guide/plugins/#step-7-specify-compatibility) to allow plugins to indicate what version of Vendure they are compatible with. To avoid bootstrap messages you should add this property to your plugins.

docs/docs/guides/developer-guide/migrating-from-v1/database-migration.md

@@ -7,11 +7,11 @@ sidebar_position: 2
 
 Vendure v2 introduces a number of breaking changes to the database schema, some of which require quite complex migrations in order to preserve existing data. To make this process as smooth as possible, we have created a migration tool which will handle the hard parts for you!
 
-{{< alert "warning" >}}
+:::warning
 **Important!** It is _critical_ that you back up your production data prior to attempting this migration.
 
 **Note for MySQL/MariaDB users:** transactions for migrations are [not supported by these databases](https://dev.mysql.com/doc/refman/5.7/en/cannot-roll-back.html). This means that if the migration fails for some reason, the statements that have executed will not get rolled back, and your DB schema can be left in an inconsistent state from which is it can be hard to recover. Therefore, it is doubly critical that you have a good backup that you can easily restore prior to attempting this migration.
-{{< /alert >}}
+:::
 
 1. Make sure all your Vendure packages to the latest v2 versions.
 2. Use your package manager to install the [v2 migration tool](https://github.com/vendure-ecommerce/v2-migration-tool): `npm install @vendure/migrate-v2`

docs/docs/guides/developer-guide/uploading-files/index.md

@@ -99,7 +99,7 @@ extend type Mutation {
 
 ### Resolver
 
-The resolver will make use of the built-in [AssetService]({{< relref "asset-service" >}}) to handle the processing of the uploaded file into an Asset.
+The resolver will make use of the built-in [AssetService](/reference/typescript-api/services/asset-service) to handle the processing of the uploaded file into an Asset.
 
 ```ts title="src/plugins/customer-avatar/api/customer-avatar.resolver.ts"
 import { Args, Mutation, Resolver } from '@nestjs/graphql';

docs/docs/guides/extending-the-admin-ui/custom-timeline-components/index.md

@@ -34,7 +34,7 @@ import {
                 <vdr-object-tree [value]="entry.data"></vdr-object-tree>
             </vdr-history-entry-detail>
         </div>
-        <div *ngIf="entry.data.valid">Tax ID {{ entry.data.taxId }} could not be verified</div>
+        <div *ngIf="!entry.data.valid">Tax ID {{ entry.data.taxId }} could not be verified</div>
     `,
     standalone: true,
     imports: [SharedModule],

docs/docs/guides/getting-started/graphql-intro/index.mdx

@@ -6,10 +6,12 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
 :::info
+
 Vendure uses [GraphQL](https://graphql.org/) as its API layer.
 
 This is an introduction to GraphQL for those who are new to it. If you are already familiar with GraphQL, you may choose
 to skip this section.
+
 :::
 
 ## What is GraphQL?

docs/docs/guides/storefront/order-workflow/index.md

@@ -5,29 +5,29 @@ showtoc: true
 
 # Order Workflow
 
-An Order is a collection of one or more ProductVariants which can be purchased by a Customer. Orders are represented internally by the [Order entity]({{< relref "order" >}}) and in the GraphQL API by the [Order type]({{< relref "/reference/graphql-api/shop/object-types#order" >}}).
+An Order is a collection of one or more ProductVariants which can be purchased by a Customer. Orders are represented internally by the [Order entity](/reference/typescript-api/entities/order/) and in the GraphQL API by the [Order type](/reference/graphql-api/admin/enums/#ordertype).
 
 ## Order State
 
-Every Order has a `state` property of type [`OrderState`]({{< relref "order-process" >}}#orderstate). The following diagram shows the default states and how an Order transitions from one to the next.
+Every Order has a `state` property of type [`OrderState`](/reference/typescript-api/orders/order-process/#orderstate). The following diagram shows the default states and how an Order transitions from one to the next.
 
-{{% alert %}}
-Note that this default workflow can be modified to better fit your business processes. See the [Customizing the Order Process guide]({{< relref "customizing-the-order-process" >}}).
-{{< /alert >}}
+:::note
+Note that this default workflow can be modified to better fit your business processes. See the [Customizing the Order Process guide](/guides/core-concepts/orders/#custom-order-processes).
+:::
 
 ![./order_state_diagram.png](./order_state_diagram.png)
 
 ## Structure of an Order
 
-In Vendure an [Order]({{< relref "order" >}}) consists of one or more [OrderLines]({{< relref "order-line" >}}) (representing a given quantity of a particular SKU).
+In Vendure an [Order](/reference/typescript-api/entities/order) consists of one or more [OrderLines](/reference/typescript-api/entities/order-line) (representing a given quantity of a particular SKU).
 
 Here is a simplified diagram illustrating this relationship:
 
 ![./order_class_diagram.png](./order_class_diagram.png)
 
 ## Shop client order workflow
 
-The [GraphQL Shop API Guide]({{< relref "/guides/storefront/shop-api-guide" >}}#order-flow) lists the GraphQL operations you will need to implement this workflow in your storefront client application.
+The [GraphQL Shop API Guide](/guides/storefront/active-order) lists the GraphQL operations you will need to implement this workflow in your storefront client application.
 
 In this section, we'll cover some examples of how these operations would look in your storefront.
 
@@ -228,4 +228,4 @@ query OrderByCode($code: String!) {
 
 In the above examples, the active Order is always associated with the current session and is therefore implicit - which is why there is no need to pass an ID to each of the above operations.
 
-Sometimes you _do_ want to be able to explicitly specify the Order you wish to operate on. In this case, you need to define a custom [ActiveOrderStrategy]({{< relref "active-order-strategy" >}}).
+Sometimes you _do_ want to be able to explicitly specify the Order you wish to operate on. In this case, you need to define a custom [ActiveOrderStrategy](/reference/typescript-api/orders/active-order-strategy).