@vendure/docs 0.0.0-202601161541

package/docs/reference/typescript-api/testing/test-server-options.md

@@ -0,0 +1,47 @@
+---
+title: "TestServerOptions"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## TestServerOptions
+
+<GenerationInfo sourceFile="packages/testing/src/types.ts" sourceLine="14" packageName="@vendure/testing" />
+
+Configuration options used to initialize an instance of the <a href='/reference/typescript-api/testing/test-server#testserver'>TestServer</a>.
+
+```ts title="Signature"
+interface TestServerOptions {
+    productsCsvPath?: string;
+    initialData: InitialData;
+    customerCount?: number;
+    logging?: boolean;
+}
+```
+
+<div className="members-wrapper">
+
+### productsCsvPath
+
+<MemberInfo kind="property" type={`string`}   />
+
+The path to an optional CSV file containing product data to import.
+### initialData
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/import-export/initial-data#initialdata'>InitialData</a>`}   />
+
+An object containing non-product data which is used to populate the database.
+### customerCount
+
+<MemberInfo kind="property" type={`number`} default={`10`}   />
+
+The number of fake Customers to populate into the database.
+### logging
+
+<MemberInfo kind="property" type={`boolean`} default={`false`}   />
+
+Set this to `true` to log some information about the database population process.
+
+
+</div>

package/docs/reference/typescript-api/testing/test-server.md

@@ -0,0 +1,60 @@
+---
+title: "TestServer"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## TestServer
+
+<GenerationInfo sourceFile="packages/testing/src/test-server.ts" sourceLine="17" packageName="@vendure/testing" />
+
+A real Vendure server against which the e2e tests should be run.
+
+```ts title="Signature"
+class TestServer {
+    public app: INestApplication;
+    constructor(vendureConfig: Required<VendureConfig>)
+    init(options: TestServerOptions) => Promise<void>;
+    bootstrap() => ;
+    destroy() => ;
+}
+```
+
+<div className="members-wrapper">
+
+### app
+
+<MemberInfo kind="property" type={`INestApplication`}   />
+
+
+### constructor
+
+<MemberInfo kind="method" type={`(vendureConfig: Required&#60;<a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>&#62;) => TestServer`}   />
+
+
+### init
+
+<MemberInfo kind="method" type={`(options: <a href='/reference/typescript-api/testing/test-server-options#testserveroptions'>TestServerOptions</a>) => Promise&#60;void&#62;`}   />
+
+Bootstraps an instance of Vendure server and populates the database according to the options
+passed in. Should be called in the `beforeAll` function.
+
+The populated data is saved into an .sqlite file for each test file. On subsequent runs, this file
+is loaded so that the populate step can be skipped, which speeds up the tests significantly.
+### bootstrap
+
+<MemberInfo kind="method" type={`() => `}   />
+
+Bootstraps a Vendure server instance. Generally the `.init()` method should be used, as that will also
+populate the test data. However, the `bootstrap()` method is sometimes useful in tests which need to
+start and stop a Vendure instance multiple times without re-populating data.
+### destroy
+
+<MemberInfo kind="method" type={`() => `}   />
+
+Destroy the Vendure server instance and clean up all resources.
+Should be called after all tests have run, e.g. in an `afterAll` function.
+
+
+</div>

package/docs/reference/typescript-api/testing/testing-logger.md

@@ -0,0 +1,140 @@
+---
+title: "TestingLogger"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## TestingLogger
+
+<GenerationInfo sourceFile="packages/testing/src/testing-logger.ts" sourceLine="55" packageName="@vendure/testing" />
+
+The TestingLogger can be used in unit tests or e2e tests to make assertions on whether the various
+Logger methods have been called, and which arguments.
+
+Here's some examples of how to use it in e2e tests and unit tests. In both cases we are using
+the Jest testing framework, but the TestingLogger should work with other similar frameworks
+(e.g. replacing `jest.fn()` with `jasmine.createSpy()`).
+
+*Example*
+
+```ts
+// e2e test example
+import { createTestEnvironment, TestingLogger } from '@vendure/testing';
+
+const testingLogger = new TestingLogger(() => jest.fn());
+
+const { server, adminClient, shopClient } = createTestEnvironment({
+  ...testConfig,
+  logger: testingLogger,
+});
+
+// e2e testing setup omitted
+
+it('should log an error', async () => {
+  // The `errorSpy` property exposes the Jest mock function
+  testingLogger.errorSpy.mockClear();
+
+  await doSomethingThatErrors();
+
+  expect(testingLogger.errorSpy).toHaveBeenCalled();
+});
+```
+
+*Example*
+
+```ts
+// unit test example
+import { Test } from '@nestjs/testing';
+import { Logger } from '@vendure/core';
+import { TestingLogger } from '@vendure/testing';
+
+beforeEach(async () => {
+  const moduleRef = await Test.createTestingModule({
+    // Nest testing setup omitted
+  }).compile();
+
+  Logger.useLogger(testingLogger);
+  moduleRef.useLogger(new Logger());
+}
+```
+
+```ts title="Signature"
+class TestingLogger<Spy extends (...args: any[]) => any> implements VendureLogger {
+    constructor(createSpyFn: () => Spy)
+    debugSpy: Spy;
+    errorSpy: Spy;
+    infoSpy: Spy;
+    verboseSpy: Spy;
+    warnSpy: Spy;
+    debug(message: string, context?: string) => void;
+    error(message: string, context?: string, trace?: string) => void;
+    info(message: string, context?: string) => void;
+    verbose(message: string, context?: string) => void;
+    warn(message: string, context?: string) => void;
+}
+```
+* Implements: <code><a href='/reference/typescript-api/logger/vendure-logger#vendurelogger'>VendureLogger</a></code>
+
+
+
+<div className="members-wrapper">
+
+### constructor
+
+<MemberInfo kind="method" type={`(createSpyFn: () =&#62; Spy) => TestingLogger`}   />
+
+
+### debugSpy
+
+<MemberInfo kind="property" type={`Spy`}   />
+
+
+### errorSpy
+
+<MemberInfo kind="property" type={`Spy`}   />
+
+
+### infoSpy
+
+<MemberInfo kind="property" type={`Spy`}   />
+
+
+### verboseSpy
+
+<MemberInfo kind="property" type={`Spy`}   />
+
+
+### warnSpy
+
+<MemberInfo kind="property" type={`Spy`}   />
+
+
+### debug
+
+<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />
+
+
+### error
+
+<MemberInfo kind="method" type={`(message: string, context?: string, trace?: string) => void`}   />
+
+
+### info
+
+<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />
+
+
+### verbose
+
+<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />
+
+
+### warn
+
+<MemberInfo kind="method" type={`(message: string, context?: string) => void`}   />
+
+
+
+
+</div>

package/docs/reference/typescript-api/worker/bootstrap-worker.md

@@ -0,0 +1,76 @@
+---
+title: "BootstrapWorker"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## bootstrapWorker
+
+<GenerationInfo sourceFile="packages/core/src/bootstrap.ts" sourceLine="225" packageName="@vendure/core" />
+
+Bootstraps a Vendure worker. Resolves to a <a href='/reference/typescript-api/worker/vendure-worker#vendureworker'>VendureWorker</a> object containing a reference to the underlying
+NestJs [standalone application](https://docs.nestjs.com/standalone-applications) as well as convenience
+methods for starting the job queue and health check server.
+
+Read more about the [Vendure Worker](/guides/developer-guide/worker-job-queue/).
+
+*Example*
+
+```ts
+import { bootstrapWorker } from '@vendure/core';
+import { config } from './vendure-config';
+
+bootstrapWorker(config)
+  .then(worker => worker.startJobQueue())
+  .then(worker => worker.startHealthCheckServer({ port: 3020 }))
+  .catch(err => {
+    console.log(err);
+    process.exit(1);
+  });
+```
+
+```ts title="Signature"
+function bootstrapWorker(userConfig: Partial<VendureConfig>, options?: BootstrapWorkerOptions): Promise<VendureWorker>
+```
+Parameters
+
+### userConfig
+
+<MemberInfo kind="parameter" type={`Partial&#60;<a href='/reference/typescript-api/configuration/vendure-config#vendureconfig'>VendureConfig</a>&#62;`} />
+
+### options
+
+<MemberInfo kind="parameter" type={`<a href='/reference/typescript-api/worker/bootstrap-worker#bootstrapworkeroptions'>BootstrapWorkerOptions</a>`} />
+
+
+
+## BootstrapWorkerOptions
+
+<GenerationInfo sourceFile="packages/core/src/bootstrap.ts" sourceLine="83" packageName="@vendure/core" since="2.2.0" />
+
+Additional options that can be used to configure the bootstrap process of the
+Vendure worker.
+
+```ts title="Signature"
+interface BootstrapWorkerOptions {
+    nestApplicationContextOptions?: NestApplicationContextOptions;
+    ignoreCompatibilityErrorsForPlugins?: Array<DynamicModule | Type<any>>;
+}
+```
+
+<div className="members-wrapper">
+
+### nestApplicationContextOptions
+
+<MemberInfo kind="property" type={`NestApplicationContextOptions`}   />
+
+These options get passed directly to the `NestFactory.createApplicationContext` method.
+### ignoreCompatibilityErrorsForPlugins
+
+<MemberInfo kind="property" type={`Array&#60;DynamicModule | Type&#60;any&#62;&#62;`} default={`[]`}  since="3.1.0"  />
+
+See the `ignoreCompatibilityErrorsForPlugins` option in <a href='/reference/typescript-api/common/bootstrap#bootstrapoptions'>BootstrapOptions</a>.
+
+
+</div>

package/docs/reference/typescript-api/worker/index.md

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

package/docs/reference/typescript-api/worker/vendure-worker.md

@@ -0,0 +1,50 @@
+---
+title: "VendureWorker"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## VendureWorker
+
+<GenerationInfo sourceFile="packages/core/src/worker/vendure-worker.ts" sourceLine="13" packageName="@vendure/core" />
+
+This object is created by calling the <a href='/reference/typescript-api/worker/bootstrap-worker#bootstrapworker'>bootstrapWorker</a> function.
+
+```ts title="Signature"
+class VendureWorker {
+    public app: INestApplicationContext;
+    constructor(app: INestApplicationContext)
+    startJobQueue() => Promise<VendureWorker>;
+    startHealthCheckServer(healthCheckConfig: WorkerHealthCheckConfig) => Promise<VendureWorker>;
+}
+```
+
+<div className="members-wrapper">
+
+### app
+
+<MemberInfo kind="property" type={`INestApplicationContext`}   />
+
+A reference to the `INestApplicationContext` object, which represents
+the NestJS [standalone application](https://docs.nestjs.com/standalone-applications) instance.
+### constructor
+
+<MemberInfo kind="method" type={`(app: INestApplicationContext) => VendureWorker`}   />
+
+
+### startJobQueue
+
+<MemberInfo kind="method" type={`() => Promise&#60;<a href='/reference/typescript-api/worker/vendure-worker#vendureworker'>VendureWorker</a>&#62;`}   />
+
+Starts the job queues running so that the worker can handle background jobs.
+### startHealthCheckServer
+
+<MemberInfo kind="method" type={`(healthCheckConfig: <a href='/reference/typescript-api/worker/worker-health-check-config#workerhealthcheckconfig'>WorkerHealthCheckConfig</a>) => Promise&#60;<a href='/reference/typescript-api/worker/vendure-worker#vendureworker'>VendureWorker</a>&#62;`}  since="1.2.0"  />
+
+Starts a simple http server which can be used as a health check on the worker instance.
+This endpoint can be used by container orchestration services such as Kubernetes to
+verify whether the worker is running.
+
+
+</div>

package/docs/reference/typescript-api/worker/worker-health-check-config.md

@@ -0,0 +1,41 @@
+---
+title: "WorkerHealthCheckConfig"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## WorkerHealthCheckConfig
+
+<GenerationInfo sourceFile="packages/core/src/worker/worker-health.service.ts" sourceLine="14" packageName="@vendure/core" since="1.2.0" />
+
+Specifies the configuration for the Worker's HTTP health check endpoint.
+
+```ts title="Signature"
+interface WorkerHealthCheckConfig {
+    port: number;
+    hostname?: string;
+    route?: string;
+}
+```
+
+<div className="members-wrapper">
+
+### port
+
+<MemberInfo kind="property" type={`number`}   />
+
+The port on which the worker will listen
+### hostname
+
+<MemberInfo kind="property" type={`string`} default={`'localhost'`}   />
+
+The hostname
+### route
+
+<MemberInfo kind="property" type={`string`} default={`'/health'`}   />
+
+The route at which the health check is available.
+
+
+</div>

package/docs/user-guide/catalog/collections.md

@@ -0,0 +1,27 @@
+---
+title: "Collections"
+weight: 2
+---
+
+# Collections
+
+Collections allow you to group ProductVariants together by various criteria. A typical use of Collections is to create a hierarchical category tree which can be used in a navigation menu in your storefront.
+
+## Populating Collections
+
+Collections are _dynamic_, which means that you define a set of rules, and Vendure will automatically populate the Collection with ProductVariants according to those rules.
+
+The rules are defined by **filters**. A Collection can define multiple filters, for example:
+
+* Include all ProductVariants with a certain FacetValue
+* Include all ProductVariants whose name includes the word "sale"
+
+## Nesting Collections
+
+Collections can be nested inside one another, as many levels deep as needed.
+
+When populating a nested Collection, its own filters _plus the filters of all Collections above it_ are used to calculate the contents.
+
+## Public vs Private Collections
+
+A Collection can be made private, meaning that it will not be available in the storefront. This can be useful when you need to organize your inventory for internal purposes.

package/docs/user-guide/catalog/facets.md

@@ -0,0 +1,34 @@
+---
+title: "Facets"
+weight: 1
+---
+
+# Facets
+
+Facets are the primary means to attach structured data to your Products & ProductVariants. Typical uses of Facets include:
+
+* Enabling faceted search & filtering in the storefront
+* Organizing Products into Collections
+* Labelling Products for inclusion in Promotions 
+
+![./screen-facet-list.webp](./screen-facet-list.webp)
+
+A Facet has one or more FacetValues, for example:
+
+* Facet: "Brand"
+* Values: "Apple", "Logitech", "Sony", "LG" ...
+
+## Assigning to Products & Variants
+
+In the Product detail page, you can assign FacetValues by clicking the _ADD FACETS_ button toward the bottom of the Product or ProductVariant views.
+
+![./screen-facet-add.webp](./screen-facet-add.webp)
+
+## Public vs Private Facets
+
+The visibility of a Facet can be set to either _public_ or _private_.
+
+* **Public** facets are visible via the Shop API, meaning they can be listed in the storefront and used for faceted searches.
+* **Private** facets are only visible to Administrators, and cannot be used in storefront faceted searches. 
+
+Private facets can be useful for labelling Products for internal use. For example, you could create a "profit margin" Facet with "high" and "low" values. You wouldn't want to display these in the storefront, but you may want to use them e.g. in Promotion logic.

package/docs/user-guide/catalog/products.md

@@ -0,0 +1,35 @@
+---
+title: "Products"
+---
+
+# Products
+
+Products represent the items you want to sell to your customers.
+
+## Products vs ProductVariants
+
+In Vendure, every Product has one or more _ProductVariants_. You can think of a Product as a "container" which houses the variants: 
+
+![./product-variants.png](./product-variants.png)
+
+In the diagram above you'll notice that it is the ProductVariants which have an SKU (_stock-keeping unit_: a unique product code) and a price.
+
+**Products** provide the overall name, description, slug, images. A product _does not_ have a price, sku, or stock level. 
+
+**ProductVariants** have a price, sku, stock level, tax settings. They are the actual things that get added to orders and purchased.
+
+## Tracking Inventory
+
+Vendure can track the stock levels of each of your ProductVariants. This is done by setting the "track inventory" option to "track" (or "inherit from global settings" if the [global setting](/user-guide/settings/global-settings) is set to track).
+
+![./screen-inventory.webp](./screen-inventory.webp)
+
+When tracking inventory:
+
+* When a customer checks out, the contents of the order will be "allocated". This means that the stock has not yet been sold, but it is no longer available to purchase (no longer _saleable_).
+* Once a Fulfillment has been created (see the Orders section), those allocated items will be converted into sales, meaning the stock level will be lowered by the corresponding quantity.
+* If a customer attempts to add more of a ProductVariant than are currently _saleable_, they will encounter an error.
+
+### Back orders
+
+Back orders can be enabled by setting a **negative value** as the "Out-of-stock threshold". This can be done via [global settings](/user-guide/settings/global-settings) or on a per-variant basis.

package/docs/user-guide/customers/index.md

@@ -0,0 +1,30 @@
+---
+title: "Customers"
+weight: 2
+---
+
+# Customers
+
+A Customer is anybody who has:
+
+* Placed an order
+* Registered an account
+
+The Customers section allows you to view and search for your customers. Clicking "edit" in the list view brings up the detail view, allowing you to edit the customer details and view orders and history.
+
+## Guest, Registered, Verified
+
+* **Guest:** Vendure allows "guest checkouts", which means people may place orders without needing to register an account with the storefront. 
+* **Registered:** When a customer registers for an account (using their email address by default), they are assigned this status.
+* **Verified:** A registered customer becomes verified once they have been able to confirm ownership of their email account. Note that if alternative authentication methods are set up on your store (e.g. Facebook login), then this workflow might be slightly different.
+
+## Customer Groups
+
+Customer Groups can be used for things like:
+
+* Grouping wholesale customers so that alternative tax calculations may be applied
+* Grouping members of a loyalty scheme for access to exclusive Promotions
+* Segmenting customers for other marketing purposes
+
+![./screen-customer-group.webp](./screen-customer-group.webp)
+

package/docs/user-guide/index.md

@@ -0,0 +1,7 @@
+# Vendure User Guide
+
+This section is for store owners and staff who are charged with running a Vendure-based store.
+
+This guide assumes that your Vendure instance is running the AdminUiPlugin.
+
+We will roughly structure this guide to conform to the default layout of the Admin UI main navigation menu. 

package/docs/user-guide/localization/index.md

@@ -0,0 +1,42 @@
+---
+title: "Localization"
+weight: 10
+---
+
+# Localization
+
+Vendure supports **customer-facing** (Shop API) localization by allowing you to define translations for the following objects:
+
+* Collections
+* Countries
+* Facets
+* FacetValue
+* Products
+* ProductOptions
+* ProductOptionGroups
+* ProductVariants
+* ShippingMethods  
+
+Vendure supports **admin-facing** (Admin API and Admin UI) localization by allowing you to define translations for labels and descriptions of the following objects:
+  
+* CustomFields
+* CollectionFilters
+* PaymentMethodHandlers
+* PromotionActions
+* PromotionConditions
+* ShippingCalculators
+* ShippingEligibilityCheckers
+
+## How to enable languages
+
+To select the set of languages you wish to create translations for, set them in the [global settings](/user-guide/settings/global-settings).
+
+Once more than one language is enabled, you will see a language switcher appear when editing the object types listed above.
+
+![../settings/screen-translations.webp](../settings/screen-translations.webp)
+
+## Setting the Admin UI language
+
+Separately, you can change the language used in the Admin UI from the menu in the top right. Note that changing the UI language has no effect on the localization of your products etc.
+
+![./screen-ui-language.webp](./screen-ui-language.webp)

package/docs/user-guide/orders/draft-orders.md

@@ -0,0 +1,28 @@
+---
+title: "Draft Orders"
+---
+
+# Draft Orders
+
+Draft Orders are used when an Administrator would like to manually create an order via the Admin UI. For example, this can be useful when:
+
+- A customer phones up to place an order
+- A customer wants to place an order in person
+- You want to create an order on behalf of a customer, e.g. for a quote.
+- When testing Promotions
+
+To create a Draft Order, click the **"Create draft order"** button from the Order List view.
+
+From there you can:
+
+- Add ProductVariants to the Order using the search input marked "Add item to order"
+- Optionally activate coupon codes to trigger Promotions
+- Set the customer, shipping and billing addresses
+- Select the shipping method
+
+Once ready, click the **"Complete draft"** button to convert this Order from a Draft into a regular Order. At this stage the order can be paid for, and you can manually record the payment details.
+
+:::note
+Note: Draft Orders do not appear in a Customer's order history in the storefront (Shop API) while still
+in the "Draft" state.
+:::