@vendure/docs 0.0.0-202601161541

package/docs/reference/core-plugins/graphiql-plugin/index.md

@@ -0,0 +1,89 @@
+---
+title: "GraphiqlPlugin"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## GraphiqlPlugin
+
+<GenerationInfo sourceFile="packages/graphiql-plugin/src/plugin.ts" sourceLine="64" packageName="@vendure/graphiql-plugin" />
+
+This plugin provides a GraphiQL UI for exploring and testing the Vendure GraphQL APIs.
+
+It adds routes `/graphiql/admin` and `/graphiql/shop` which serve the GraphiQL interface
+for the respective APIs.
+
+## Installation
+
+```ts
+import { GraphiqlPlugin } from '@vendure/graphiql-plugin';
+
+const config: VendureConfig = {
+  // Add an instance of the plugin to the plugins array
+  plugins: [
+    GraphiqlPlugin.init({
+      route: 'graphiql', // Optional, defaults to 'graphiql'
+    }),
+  ],
+};
+```
+
+## Custom API paths
+
+By default, the plugin automatically reads the Admin API and Shop API paths from your Vendure configuration.
+
+If you need to override these paths, you can specify them explicitly:
+
+```typescript
+GraphiQLPlugin.init({
+    route: 'my-custom-route', // defaults to `graphiql`
+});
+```
+
+## Query parameters
+
+You can add the following query parameters to the GraphiQL URL:
+
+- `?query=...` - Pre-populate the query editor with a GraphQL query.
+- `?embeddedMode=true` - This renders the editor in embedded mode, which hides the header and
+   the API switcher. This is useful for embedding GraphiQL in other applications such as documentation.
+   In this mode, the editor also does not persist changes across reloads.
+
+```ts title="Signature"
+class GraphiqlPlugin implements NestModule {
+    static options: Required<GraphiqlPluginOptions>;
+    constructor(processContext: ProcessContext, configService: ConfigService, graphiQLService: GraphiQLService)
+    init(options: GraphiqlPluginOptions = {}) => Type<GraphiqlPlugin>;
+    configure(consumer: MiddlewareConsumer) => ;
+}
+```
+* Implements: <code>NestModule</code>
+
+
+
+<div className="members-wrapper">
+
+### options
+
+<MemberInfo kind="property" type={`Required&#60;GraphiqlPluginOptions&#62;`}   />
+
+
+### constructor
+
+<MemberInfo kind="method" type={`(processContext: <a href='/reference/typescript-api/common/process-context#processcontext'>ProcessContext</a>, configService: ConfigService, graphiQLService: GraphiQLService) => GraphiqlPlugin`}   />
+
+
+### init
+
+<MemberInfo kind="method" type={`(options: GraphiqlPluginOptions = {}) => Type&#60;<a href='/reference/core-plugins/graphiql-plugin/#graphiqlplugin'>GraphiqlPlugin</a>&#62;`}   />
+
+
+### configure
+
+<MemberInfo kind="method" type={`(consumer: MiddlewareConsumer) => `}   />
+
+
+
+
+</div>

package/docs/reference/core-plugins/harden-plugin/default-vendure-complexity-estimator.md

@@ -0,0 +1,30 @@
+---
+title: "DefaultVendureComplexityEstimator"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## defaultVendureComplexityEstimator
+
+<GenerationInfo sourceFile="packages/harden-plugin/src/middleware/query-complexity-plugin.ts" sourceLine="98" packageName="@vendure/harden-plugin" />
+
+A complexity estimator which takes into account List and PaginatedList types and can
+be further configured by providing a customComplexityFactors object.
+
+When selecting PaginatedList types, the "take" argument is used to estimate a complexity
+factor. If the "take" argument is omitted, a default factor of 1000 is applied.
+
+```ts title="Signature"
+function defaultVendureComplexityEstimator(customComplexityFactors: { [path: string]: number }, logFieldScores: boolean): void
+```
+Parameters
+
+### customComplexityFactors
+
+<MemberInfo kind="parameter" type={`{ [path: string]: number }`} />
+
+### logFieldScores
+
+<MemberInfo kind="parameter" type={`boolean`} />
+

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

@@ -0,0 +1,106 @@
+---
+title: "HardenPluginOptions"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## HardenPluginOptions
+
+<GenerationInfo sourceFile="packages/harden-plugin/src/types.ts" sourceLine="10" packageName="@vendure/harden-plugin" />
+
+Options that can be passed to the `.init()` static method of the HardenPlugin.
+
+```ts title="Signature"
+interface HardenPluginOptions {
+    maxQueryComplexity?: number;
+    queryComplexityEstimators?: ComplexityEstimator[];
+    logComplexityScore?: boolean;
+    customComplexityFactors?: {
+        [path: string]: number;
+    };
+    hideFieldSuggestions?: boolean;
+    apiMode?: 'dev' | 'prod';
+    skip?: (context: GraphQLRequestContext<any>) => Promise<boolean> | boolean;
+}
+```
+
+<div className="members-wrapper">
+
+### maxQueryComplexity
+
+<MemberInfo kind="property" type={`number`} default={`1000`}   />
+
+Defines the maximum permitted complexity score of a query. The complexity score is based
+on the number of fields being selected as well as other factors like whether there are nested
+lists.
+
+A query which exceeds the maximum score will result in an error.
+### queryComplexityEstimators
+
+<MemberInfo kind="property" type={`ComplexityEstimator[]`}   />
+
+An array of custom estimator functions for calculating the complexity of a query. By default,
+the plugin will use the <a href='/reference/core-plugins/harden-plugin/default-vendure-complexity-estimator#defaultvendurecomplexityestimator'>defaultVendureComplexityEstimator</a> which is specifically
+tuned to accurately estimate Vendure queries.
+### logComplexityScore
+
+<MemberInfo kind="property" type={`boolean`} default={`false`}   />
+
+When set to `true`, the complexity score of each query will be logged at the Verbose
+log level, and a breakdown of the calculation for each field will be logged at the Debug level.
+
+This is very useful for tuning your complexity scores.
+### customComplexityFactors
+
+<MemberInfo kind="property" type={`{         [path: string]: number;     }`}   />
+
+This object allows you to tune the complexity weight of specific fields. For example,
+if you have a custom `stockLocations` field defined on the `ProductVariant` type, and
+you know that it is a particularly expensive operation to execute, you can increase
+its complexity like this:
+
+*Example*
+
+```ts
+HardenPlugin.init({
+  maxQueryComplexity: 650,
+  customComplexityFactors: {
+    'ProductVariant.stockLocations': 10
+  }
+}),
+```
+### hideFieldSuggestions
+
+<MemberInfo kind="property" type={`boolean`} default={`true`}   />
+
+Graphql-js will make suggestions about the names of fields if an invalid field name is provided.
+This would allow an attacker to find out the available fields by brute force even if introspection
+is disabled.
+
+Setting this option to `true` will prevent these suggestion error messages from being returned,
+instead replacing the message with a generic "Invalid request" message.
+### apiMode
+
+<MemberInfo kind="property" type={`'dev' | 'prod'`} default={`'prod'`}   />
+
+When set to `'prod'`, the plugin will disable dev-mode features of the GraphQL APIs:
+
+- introspection
+- GraphQL playground
+### skip
+
+<MemberInfo kind="property" type={`(context: GraphQLRequestContext&#60;any&#62;) =&#62; Promise&#60;boolean&#62; | boolean`}   />
+
+Allows you to skip the complexity check for certain requests.
+
+*Example*
+
+```ts
+HardenPlugin.init({
+  skip: (context) => context.request.http.headers['x-storefront-ssr-auth'] === 'some-secret-token'
+}),
+```
+
+
+</div>

package/docs/reference/core-plugins/harden-plugin/index.md

@@ -0,0 +1,169 @@
+---
+title: "HardenPlugin"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## HardenPlugin
+
+<GenerationInfo sourceFile="packages/harden-plugin/src/harden.plugin.ts" sourceLine="146" packageName="@vendure/harden-plugin" />
+
+The HardenPlugin hardens the Shop and Admin GraphQL APIs against attacks and abuse.
+
+- It analyzes the complexity on incoming graphql queries and rejects queries that are too complex and
+  could be used to overload the resources of the server.
+- It disables dev-mode API features such as introspection and the GraphQL playground app.
+- It removes field name suggestions to prevent trial-and-error schema sniffing.
+
+It is a recommended plugin for all production configurations.
+
+## Installation
+
+`yarn add @vendure/harden-plugin`
+
+or
+
+`npm install @vendure/harden-plugin`
+
+Then add the `HardenPlugin`, calling the `.init()` method with <a href='/reference/core-plugins/harden-plugin/harden-plugin-options#hardenpluginoptions'>HardenPluginOptions</a>:
+
+*Example*
+
+```ts
+import { HardenPlugin } from '@vendure/harden-plugin';
+
+const config: VendureConfig = {
+  // Add an instance of the plugin to the plugins array
+  plugins: [
+     HardenPlugin.init({
+       maxQueryComplexity: 650,
+       apiMode: process.env.APP_ENV === 'dev' ? 'dev' : 'prod',
+     }),
+  ],
+};
+```
+
+## Setting the max query complexity
+
+The `maxQueryComplexity` option determines how complex a query can be. The complexity of a query relates to how many, and how
+deeply-nested are the fields being selected, and is intended to roughly correspond to the amount of server resources that would
+be required to resolve that query.
+
+The goal of this setting is to prevent attacks in which a malicious actor crafts a very complex query in order to overwhelm your
+server resources. Here's an example of a request which would likely overwhelm a Vendure server:
+
+```GraphQL
+query EvilQuery {
+  products {
+    items {
+      collections {
+        productVariants {
+          items {
+            product {
+              collections {
+                productVariants {
+                  items {
+                    product {
+                      variants {
+                        name
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+This evil query has a complexity score of 2,443,203 - much greater than the default of 1,000!
+
+The complexity score is calculated by the [graphql-query-complexity library](https://www.npmjs.com/package/graphql-query-complexity),
+and by default uses the <a href='/reference/core-plugins/harden-plugin/default-vendure-complexity-estimator#defaultvendurecomplexityestimator'>defaultVendureComplexityEstimator</a>, which is tuned specifically to the Vendure Shop API.
+
+:::caution
+Note: By default, if the "take" argument is omitted from a list query (e.g. the `products` or `collections` query), a default factor of 1000 is applied.
+:::
+
+The optimal max complexity score will vary depending on:
+
+- The requirements of your storefront and other clients using the Shop API
+- The resources available to your server
+
+You should aim to set the maximum as low as possible while still being able to service all the requests required.
+This will take some manual tuning.
+While tuning the max, you can turn on the `logComplexityScore` to get a detailed breakdown of the complexity of each query, as well as how
+that total score is derived from its child fields:
+
+*Example*
+
+```ts
+import { HardenPlugin } from '@vendure/harden-plugin';
+
+const config: VendureConfig = {
+  // A detailed summary is logged at the "debug" level
+  logger: new DefaultLogger({ level: LogLevel.Debug }),
+  plugins: [
+     HardenPlugin.init({
+       maxQueryComplexity: 650,
+       logComplexityScore: true,
+     }),
+  ],
+};
+```
+
+With logging configured as above, the following query:
+
+```GraphQL
+query ProductList {
+  products(options: { take: 5 }) {
+    items {
+      id
+      name
+      featuredAsset {
+        preview
+      }
+    }
+  }
+}
+```
+will log the following breakdown:
+
+```sh
+debug 16/12/22, 14:12 - [HardenPlugin] Calculating complexity of [ProductList]
+debug 16/12/22, 14:12 - [HardenPlugin] Product.id: ID!     childComplexity: 0, score: 1
+debug 16/12/22, 14:12 - [HardenPlugin] Product.name: String!       childComplexity: 0, score: 1
+debug 16/12/22, 14:12 - [HardenPlugin] Asset.preview: String!      childComplexity: 0, score: 1
+debug 16/12/22, 14:12 - [HardenPlugin] Product.featuredAsset: Asset        childComplexity: 1, score: 2
+debug 16/12/22, 14:12 - [HardenPlugin] ProductList.items: [Product!]!      childComplexity: 4, score: 20
+debug 16/12/22, 14:12 - [HardenPlugin] Query.products: ProductList!        childComplexity: 20, score: 35
+verbose 16/12/22, 14:12 - [HardenPlugin] Query complexity [ProductList]: 35
+```
+
+```ts title="Signature"
+class HardenPlugin {
+    static options: HardenPluginOptions;
+    init(options: HardenPluginOptions) => ;
+}
+```
+
+<div className="members-wrapper">
+
+### options
+
+<MemberInfo kind="property" type={`<a href='/reference/core-plugins/harden-plugin/harden-plugin-options#hardenpluginoptions'>HardenPluginOptions</a>`}   />
+
+
+### init
+
+<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/harden-plugin/harden-plugin-options#hardenpluginoptions'>HardenPluginOptions</a>) => `}   />
+
+
+
+
+</div>

package/docs/reference/core-plugins/index.md

@@ -0,0 +1,5 @@
+---
+title: "Core Plugins"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->

package/docs/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin.md

@@ -0,0 +1,211 @@
+---
+title: "BullMQJobQueuePlugin"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## BullMQJobQueuePlugin
+
+<GenerationInfo sourceFile="packages/job-queue-plugin/src/bullmq/plugin.ts" sourceLine="190" packageName="@vendure/job-queue-plugin" />
+
+This plugin is a drop-in replacement of the DefaultJobQueuePlugin, which implements a push-based
+job queue strategy built on top of the popular [BullMQ](https://github.com/taskforcesh/bullmq) library.
+
+## Advantages over the DefaultJobQueuePlugin
+
+The advantage of this approach is that jobs are stored in Redis rather than in the database. For more complex
+applications with many job queues and/or multiple worker instances, this can massively reduce the load on the
+DB server. The reason for this is that the DefaultJobQueuePlugin uses polling to check for new jobs. By default
+it will poll every 200ms. A typical Vendure instance uses at least 3 queues (handling emails, collections, search index),
+so even with a single worker instance this results in 15 queries per second to the DB constantly. Adding more
+custom queues and multiple worker instances can easily result in 50 or 100 queries per second. At this point
+performance may be impacted.
+
+Using this plugin, no polling is needed, as BullMQ will _push_ jobs to the worker(s) as and when they are added
+to the queue. This results in significantly more scalable performance characteristics, as well as lower latency
+in processing jobs.
+
+## Installation
+
+Note: To use this plugin, you need to manually install the `bullmq` package:
+
+```shell
+npm install bullmq@^5.4.2
+```
+
+**Note:** The v1.x version of this plugin is designed to work with bullmq v1.x, etc.
+
+*Example*
+
+```ts
+import { BullMQJobQueuePlugin } from '@vendure/job-queue-plugin/package/bullmq';
+
+const config: VendureConfig = {
+  // Add an instance of the plugin to the plugins array
+  plugins: [
+    // DefaultJobQueuePlugin should be removed from the plugins array
+    BullMQJobQueuePlugin.init({
+      connection: {
+        port: 6379
+      }
+    }),
+  ],
+};
+```
+
+### Running Redis locally
+
+To develop with this plugin, you'll need an instance of Redis to connect to. Here's a docker-compose config
+that will set up [Redis](https://redis.io/) as well as [Redis Commander](https://github.com/joeferner/redis-commander),
+which is a web-based UI for interacting with Redis:
+
+```YAML
+version: "3"
+services:
+  redis:
+    image: redis:7.4
+    hostname: redis
+    container_name: redis
+    ports:
+      - "6379:6379"
+  redis-commander:
+    container_name: redis-commander
+    hostname: redis-commander
+    image: rediscommander/redis-commander:latest
+    environment:
+      - REDIS_HOSTS=local:redis:6379
+    ports:
+      - "8085:8081"
+```
+
+## Concurrency
+
+The default concurrency of a single worker is 3, i.e. up to 3 jobs will be processed at the same time.
+You can change the concurrency in the `workerOptions` passed to the `init()` method:
+
+*Example*
+
+```ts
+const config: VendureConfig = {
+  plugins: [
+    BullMQJobQueuePlugin.init({
+      workerOptions: {
+        concurrency: 10,
+      },
+    }),
+  ],
+};
+```
+
+## Removing old jobs
+
+By default, BullMQ will keep completed jobs in the `completed` set and failed jobs in the `failed` set. Over time,
+these sets can grow very large. Since Vendure v2.1, the default behaviour is to remove jobs from these sets after
+30 days or after a maximum of 5,000 completed or failed jobs.
+
+This can be configured using the `removeOnComplete` and `removeOnFail` options:
+
+*Example*
+
+```ts
+const config: VendureConfig = {
+  plugins: [
+    BullMQJobQueuePlugin.init({
+      workerOptions: {
+        removeOnComplete: {
+          count: 500,
+        },
+        removeOnFail: {
+          age: 60 * 60 * 24 * 7, // 7 days
+          count: 1000,
+        },
+      }
+    }),
+  ],
+};
+```
+
+The `count` option specifies the maximum number of jobs to keep in the set, while the `age` option specifies the
+maximum age of a job in seconds. If both options are specified, then the jobs kept will be the ones that satisfy
+both properties.
+
+## Job Priority
+Some jobs are more important than others. For example, sending out a timely email after a customer places an order
+is probably more important than a routine data import task. Sometimes you can get the situation where lower-priority
+jobs are blocking higher-priority jobs.
+
+Let's say you have a data import job that runs periodically and takes a long time to complete. If you have a high-priority
+job that needs to be processed quickly, it could be stuck behind the data import job in the queue. A customer might
+not get their confirmation email for 30 minutes while that data import job is processed!
+
+To solve this problem, you can set the `priority` option on a job. Jobs with a higher priority will be processed before
+jobs with a lower priority. By default, all jobs have a priority of 0 (which is the highest).
+
+Learn more about how priority works in BullMQ in their [documentation](https://docs.bullmq.io/guide/jobs/prioritized).
+
+You can set the priority by using the `setJobOptions` option (introduced in Vendure v3.2.0):
+
+*Example*
+
+```ts
+const config: VendureConfig = {
+  plugins: [
+    BullMQJobQueuePlugin.init({
+      setJobOptions: (queueName, job) => {
+        let priority = 10;
+        switch (queueName) {
+          case 'super-critical-task':
+            priority = 0;
+            break;
+          case 'send-email':
+            priority = 5;
+            break;
+          default:
+            priority = 10;
+        }
+        return { priority };
+      }
+    }),
+  ],
+};
+```
+
+## Setting Redis Prefix
+
+By default, the underlying BullMQ library will use the default Redis key prefix of `bull`. This can be changed by setting the `prefix` option
+in the `queueOptions` and `workerOptions` objects:
+
+```ts
+BullMQJobQueuePlugin.init({
+  workerOptions: {
+    prefix: 'my-prefix'
+  },
+  queueOptions: {
+    prefix: 'my-prefix'
+  }
+}),
+```
+
+```ts title="Signature"
+class BullMQJobQueuePlugin {
+    static options: BullMQPluginOptions;
+    init(options: BullMQPluginOptions) => ;
+}
+```
+
+<div className="members-wrapper">
+
+### options
+
+<MemberInfo kind="property" type={`<a href='/reference/core-plugins/job-queue-plugin/bull-mqplugin-options#bullmqpluginoptions'>BullMQPluginOptions</a>`}   />
+
+
+### init
+
+<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/job-queue-plugin/bull-mqplugin-options#bullmqpluginoptions'>BullMQPluginOptions</a>) => `}   />
+
+Configures the plugin.
+
+
+</div>