From f68be40e699d8900cc0d089b21ad1b5f480331e1 Mon Sep 17 00:00:00 2001 From: Michael Bromley Date: Mon, 9 Oct 2023 17:09:51 +0200 Subject: [PATCH] docs: Fix code blocks, regenerate docs --- .../register-route-component-options.md | 4 +- .../ui-devkit/admin-ui-extension.md | 78 +++--- .../elasticsearch-options.md | 234 +++++++++--------- .../elasticsearch-plugin/index.md | 6 +- .../bull-mqjob-queue-plugin.md | 34 ++- .../bull-mqjob-queue-strategy.md | 2 +- .../payments-plugin/stripe-plugin.md | 108 +++++++- ...duct-variant-price-calculation-strategy.md | 12 +- packages/elasticsearch-plugin/src/options.ts | 12 +- packages/elasticsearch-plugin/src/plugin.ts | 6 +- 10 files changed, 319 insertions(+), 177 deletions(-) diff --git a/docs/docs/reference/admin-ui-api/routes/register-route-component-options.md b/docs/docs/reference/admin-ui-api/routes/register-route-component-options.md index 93d4a06d27..a5cc743c74 100644 --- a/docs/docs/reference/admin-ui-api/routes/register-route-component-options.md +++ b/docs/docs/reference/admin-ui-api/routes/register-route-component-options.md @@ -23,8 +23,8 @@ type RegisterRouteComponentOptions[R], 'Query'>) => BreadcrumbValue; - entityKey?: Component extends BaseDetailComponent ? R : undefined; + entityKey?: Component extends BaseDetailComponent ? R : undefined; variables?: T extends TypedDocumentNode ? Omit : never; routeConfig?: Route; -} & (Component extends BaseDetailComponent ? { entityKey: R } : unknown) +} & (Component extends BaseDetailComponent ? { entityKey: R } : unknown) ``` diff --git a/docs/docs/reference/admin-ui-api/ui-devkit/admin-ui-extension.md b/docs/docs/reference/admin-ui-api/ui-devkit/admin-ui-extension.md index 11d98704b8..ff656ba263 100644 --- a/docs/docs/reference/admin-ui-api/ui-devkit/admin-ui-extension.md +++ b/docs/docs/reference/admin-ui-api/ui-devkit/admin-ui-extension.md @@ -13,24 +13,24 @@ import MemberDescription from '@site/src/components/MemberDescription'; -Defines extensions to the Admin UI application by specifying additional -Angular [NgModules](https://angular.io/guide/ngmodules) which are compiled -into the application. - -See [Extending the Admin UI](/guides/extending-the-admin-ui/getting-started/) for +Defines extensions to the Admin UI application by specifying additional +Angular [NgModules](https://angular.io/guide/ngmodules) which are compiled +into the application. + +See [Extending the Admin UI](/guides/extending-the-admin-ui/getting-started/) for detailed instructions. ```ts title="Signature" -interface AdminUiExtension extends Partial, - Partial, +interface AdminUiExtension extends Partial, + Partial, Partial { id?: string; extensionPath: string; ngModules?: Array; providers?: string[]; - routes?: Array<{ - route: string; - filePath: string; + routes?: Array<{ + route: string; + filePath: string; }>; pathAlias?: string; exclude?: string[]; @@ -46,14 +46,14 @@ interface AdminUiExtension extends Partial, -An optional ID for the extension module. Only used internally for generating +An optional ID for the extension module. Only used internally for generating import paths to your module. If not specified, a unique hash will be used as the id. ### extensionPath -The path to the directory containing the extension module(s). The entire contents of this directory -will be copied into the Admin UI app, including all TypeScript source files, html templates, +The path to the directory containing the extension module(s). The entire contents of this directory +will be copied into the Admin UI app, including all TypeScript source files, html templates, scss style sheets etc. ### ngModules @@ -64,27 +64,27 @@ One or more Angular modules which extend the default Admin UI. -Defines the paths to a file that exports an array of shared providers such as nav menu items, custom form inputs, +Defines the paths to a file that exports an array of shared providers such as nav menu items, custom form inputs, custom detail components, action bar items, custom history entry components. ### routes - + -Defines routes that will be lazy-loaded at the `/extensions/` route. The filePath should point to a file +Defines routes that will be lazy-loaded at the `/extensions/` route. The filePath should point to a file relative to the `extensionPath` which exports an array of Angular route definitions. ### pathAlias -An optional alias for the module so it can be referenced by other UI extension modules. - -By default, Angular modules declared in an AdminUiExtension do not have access to code outside the directory -defined by the `extensionPath`. A scenario in which that can be useful though is in a monorepo codebase where -a common NgModule is shared across different plugins, each defined in its own package. An example can be found -below - note that the main `tsconfig.json` also maps the target module but using a path relative to the project's -root folder. The UI module is not part of the main TypeScript build task as explained in -[Extending the Admin UI](https://www.vendure.io/docs/plugins/extending-the-admin-ui/) but having `paths` -properly configured helps with usual IDE code editing features such as code completion and quick navigation, as +An optional alias for the module so it can be referenced by other UI extension modules. + +By default, Angular modules declared in an AdminUiExtension do not have access to code outside the directory +defined by the `extensionPath`. A scenario in which that can be useful though is in a monorepo codebase where +a common NgModule is shared across different plugins, each defined in its own package. An example can be found +below - note that the main `tsconfig.json` also maps the target module but using a path relative to the project's +root folder. The UI module is not part of the main TypeScript build task as explained in +[Extending the Admin UI](https://www.vendure.io/docs/plugins/extending-the-admin-ui/) but having `paths` +properly configured helps with usual IDE code editing features such as code completion and quick navigation, as well as linting. *Example* @@ -163,7 +163,7 @@ export class SampleUiExtensionModule {} -Optional array specifying filenames or [glob](https://github.com/isaacs/node-glob) patterns that should +Optional array specifying filenames or [glob](https://github.com/isaacs/node-glob) patterns that should be skipped when copying the directory defined by `extensionPath`. *Example* @@ -180,7 +180,7 @@ exclude: ['**/*.spec.ts'] -Defines extensions to the Admin UI translations. Can be used as a stand-alone extension definition which only adds translations +Defines extensions to the Admin UI translations. Can be used as a stand-alone extension definition which only adds translations without adding new UI functionality, or as part of a full AdminUiExtension. ```ts title="Signature" @@ -195,9 +195,9 @@ interface TranslationExtension { LanguageCode]?: string }`} /> -Optional object defining any translation files for the Admin UI. The value should be an object with -the key as a 2-character [ISO 639-1 language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes), -and the value being a [glob](https://github.com/isaacs/node-glob) for any relevant +Optional object defining any translation files for the Admin UI. The value should be an object with +the key as a 2-character [ISO 639-1 language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes), +and the value being a [glob](https://github.com/isaacs/node-glob) for any relevant translation files in JSON format. *Example* @@ -231,7 +231,7 @@ interface StaticAssetExtension { StaticAssetDefinition[]`} /> -Optional array of paths to static assets which will be copied over to the Admin UI app's `/static` +Optional array of paths to static assets which will be copied over to the Admin UI app's `/static` directory. @@ -256,7 +256,7 @@ interface GlobalStylesExtension { -Specifies a path (or array of paths) to global style files (css or Sass) which will be +Specifies a path (or array of paths) to global style files (css or Sass) which will be incorporated into the Admin UI app global stylesheet. @@ -281,7 +281,7 @@ interface SassVariableOverridesExtension { -Specifies a path to a Sass style file containing variable declarations, which will take precedence over +Specifies a path to a Sass style file containing variable declarations, which will take precedence over default values defined in Clarity. @@ -292,7 +292,7 @@ default values defined in Clarity. -A static asset can be provided as a path to the asset, or as an object containing a path and a new +A static asset can be provided as a path to the asset, or as an object containing a path and a new name, which will cause the compiler to copy and then rename the asset. ```ts title="Signature" @@ -320,8 +320,8 @@ interface AdminUiExtensionSharedModule { -Shared modules are directly imported into the main AppModule of the Admin UI -and should be used to declare custom form components and define custom +Shared modules are directly imported into the main AppModule of the Admin UI +and should be used to declare custom form components and define custom navigation items. ### ngModuleFileName @@ -359,14 +359,14 @@ interface AdminUiExtensionLazyModule { -Lazy modules are lazy-loaded at the `/extensions/` route and should be used for +Lazy modules are lazy-loaded at the `/extensions/` route and should be used for modules which define new views for the Admin UI. ### route -The route specifies the route at which the module will be lazy-loaded. E.g. a value -of `'foo'` will cause the module to lazy-load when the `/extensions/foo` route +The route specifies the route at which the module will be lazy-loaded. E.g. a value +of `'foo'` will cause the module to lazy-load when the `/extensions/foo` route is activated. ### ngModuleFileName diff --git a/docs/docs/reference/core-plugins/elasticsearch-plugin/elasticsearch-options.md b/docs/docs/reference/core-plugins/elasticsearch-plugin/elasticsearch-options.md index 9795e67ec9..b22380f104 100644 --- a/docs/docs/reference/core-plugins/elasticsearch-plugin/elasticsearch-options.md +++ b/docs/docs/reference/core-plugins/elasticsearch-plugin/elasticsearch-options.md @@ -24,22 +24,22 @@ interface ElasticsearchOptions { clientOptions?: ClientOptions; indexPrefix?: string; indexSettings?: object; - indexMappingProperties?: { - [indexName: string]: object; + indexMappingProperties?: { + [indexName: string]: object; }; batchSize?: number; searchConfig?: SearchConfig; - customProductMappings?: { - [fieldName: string]: CustomMapping<[Product, ProductVariant[], LanguageCode, Injector]>; + customProductMappings?: { + [fieldName: string]: CustomMapping<[Product, ProductVariant[], LanguageCode, Injector]>; }; - customProductVariantMappings?: { - [fieldName: string]: CustomMapping<[ProductVariant, LanguageCode, Injector]>; + customProductVariantMappings?: { + [fieldName: string]: CustomMapping<[ProductVariant, LanguageCode, Injector]>; }; bufferUpdates?: boolean; hydrateProductRelations?: Array>; hydrateProductVariantRelations?: Array>; - extendSearchInputType?: { - [name: string]: PrimitiveTypeVariations; + extendSearchInputType?: { + [name: string]: PrimitiveTypeVariations; }; extendSearchSortType?: string[]; } @@ -71,9 +71,9 @@ Interval in milliseconds between attempts to connect to the ElasticSearch server -Options to pass directly to the -[Elasticsearch Node.js client](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/index.html). For example, to -set authentication or other more advanced options. +Options to pass directly to the +[Elasticsearch Node.js client](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/index.html). For example, to +set authentication or other more advanced options. Note that if the `node` or `nodes` option is specified, it will override the values provided in the `host` and `port` options. ### indexPrefix @@ -84,7 +84,7 @@ Prefix for the indices created by the plugin. -[These options](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/index-modules.html#index-modules-settings) +[These options](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/index-modules.html#index-modules-settings) are directly passed to index settings. To apply some settings indices will be recreated. *Example* @@ -115,10 +115,10 @@ A more complete example can be found in the discussion thread [How to make elastic plugin to search by substring with stemming](https://github.com/vendure-ecommerce/vendure/discussions/1066). ### indexMappingProperties - + -This option allow to redefine or define new properties in mapping. More about elastic -[mapping](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html) +This option allow to redefine or define new properties in mapping. More about elastic +[mapping](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html) After changing this option indices will be recreated. *Example* @@ -169,21 +169,21 @@ Batch size for bulk operations (e.g. when rebuilding the indices). Configuration of the internal Elasticsearch query. ### customProductMappings -Product, ProductVariant[], LanguageCode, Injector]>; }`} /> - -Custom mappings may be defined which will add the defined data to the -Elasticsearch index and expose that data via the SearchResult GraphQL type, -adding a new `customMappings`, `customProductMappings` & `customProductVariantMappings` fields. - -The `graphQlType` property may be one of `String`, `Int`, `Float`, `Boolean`, `ID` or list -versions thereof (`[String!]` etc) and can be appended with a `!` to indicate non-nullable fields. - -The `public` (default = `true`) property is used to reveal or hide the property in the GraphQL API schema. -If this property is set to `false` it's not accessible in the `customMappings` field but it's still getting -parsed to the elasticsearch index. - -This config option defines custom mappings which are accessible when the "groupByProduct" -input options is set to `true`. In addition, custom variant mappings can be accessed by using +Product, ProductVariant[], LanguageCode, Injector]>; }`} /> + +Custom mappings may be defined which will add the defined data to the +Elasticsearch index and expose that data via the SearchResult GraphQL type, +adding a new `customMappings`, `customProductMappings` & `customProductVariantMappings` fields. + +The `graphQlType` property may be one of `String`, `Int`, `Float`, `Boolean`, `ID` or list +versions thereof (`[String!]` etc) and can be appended with a `!` to indicate non-nullable fields. + +The `public` (default = `true`) property is used to reveal or hide the property in the GraphQL API schema. +If this property is set to `false` it's not accessible in the `customMappings` field but it's still getting +parsed to the elasticsearch index. + +This config option defines custom mappings which are accessible when the "groupByProduct" +input options is set to `true`. In addition, custom variant mappings can be accessed by using the `customProductVariantMappings` field, which is always available. *Example* @@ -209,7 +209,7 @@ customProductMappings: { *Example* -```SDL +```graphql query SearchProducts($input: SearchInput!) { search(input: $input) { totalItems @@ -232,15 +232,15 @@ query SearchProducts($input: SearchInput!) { ``` ### customProductVariantMappings -ProductVariant, LanguageCode, Injector]>; }`} /> +ProductVariant, LanguageCode, Injector]>; }`} /> -This config option defines custom mappings which are accessible when the "groupByProduct" -input options is set to `false`. In addition, custom product mappings can be accessed by using +This config option defines custom mappings which are accessible when the "groupByProduct" +input options is set to `false`. In addition, custom product mappings can be accessed by using the `customProductMappings` field, which is always available. *Example* -```SDL +```graphql query SearchProducts($input: SearchInput!) { search(input: $input) { totalItems @@ -263,20 +263,20 @@ query SearchProducts($input: SearchInput!) { -If set to `true`, updates to Products, ProductVariants and Collections will not immediately -trigger an update to the search index. Instead, all these changes will be buffered and will -only be run via a call to the `runPendingSearchIndexUpdates` mutation in the Admin API. - -This is very useful for installations with a large number of ProductVariants and/or -Collections, as the buffering allows better control over when these expensive jobs are run, -and also performs optimizations to minimize the amount of work that needs to be performed by +If set to `true`, updates to Products, ProductVariants and Collections will not immediately +trigger an update to the search index. Instead, all these changes will be buffered and will +only be run via a call to the `runPendingSearchIndexUpdates` mutation in the Admin API. + +This is very useful for installations with a large number of ProductVariants and/or +Collections, as the buffering allows better control over when these expensive jobs are run, +and also performs optimizations to minimize the amount of work that needs to be performed by the worker. ### hydrateProductRelations EntityRelationPaths<Product>>`} default="[]" since="1.3.0" /> -Additional product relations that will be fetched from DB while reindexing. This can be used -in combination with `customProductMappings` to ensure that the required relations are joined +Additional product relations that will be fetched from DB while reindexing. This can be used +in combination with `customProductMappings` to ensure that the required relations are joined before the `product` object is passed to the `valueFn`. *Example* @@ -298,14 +298,14 @@ before the `product` object is passed to the `valueFn`. EntityRelationPaths<ProductVariant>>`} default="[]" since="1.3.0" /> -Additional variant relations that will be fetched from DB while reindexing. See +Additional variant relations that will be fetched from DB while reindexing. See `hydrateProductRelations` for more explanation and a usage example. ### extendSearchInputType - + -Allows the `SearchInput` type to be extended with new input fields. This allows arbitrary -data to be passed in, which can then be used e.g. in the `mapQuery()` function or +Allows the `SearchInput` type to be extended with new input fields. This allows arbitrary +data to be passed in, which can then be used e.g. in the `mapQuery()` function or custom `scriptFields` functions. *Example* @@ -322,7 +322,7 @@ This allows the search query to include these new fields: *Example* -```GraphQl +```graphql query { search(input: { longitude: 101.7117, @@ -339,7 +339,7 @@ query { -Adds a list of sort parameters. This is mostly important to make the +Adds a list of sort parameters. This is mostly important to make the correct sort order values available inside `input` parameter of the `mapSort` option. *Example* @@ -376,12 +376,12 @@ interface SearchConfig { multiMatchType?: 'best_fields' | 'most_fields' | 'cross_fields' | 'phrase' | 'phrase_prefix' | 'bool_prefix'; boostFields?: BoostFieldsConfig; priceRangeBucketInterval?: number; - mapQuery?: ( - query: any, - input: ElasticSearchInput, - searchConfig: DeepRequired, - channelId: ID, - enabledOnly: boolean, + mapQuery?: ( + query: any, + input: ElasticSearchInput, + searchConfig: DeepRequired, + channelId: ID, + enabledOnly: boolean, ) => any; scriptFields?: { [fieldName: string]: CustomScriptMapping<[ElasticSearchInput]> }; mapSort?: (sort: ElasticSearchSortInput, input: ElasticSearchInput) => ElasticSearchSortInput; @@ -394,29 +394,29 @@ interface SearchConfig { -The maximum number of FacetValues to return from the search query. Internally, this +The maximum number of FacetValues to return from the search query. Internally, this value sets the "size" property of an Elasticsearch aggregation. ### collectionMaxSize -The maximum number of Collections to return from the search query. Internally, this +The maximum number of Collections to return from the search query. Internally, this value sets the "size" property of an Elasticsearch aggregation. ### totalItemsMaxSize -The maximum number of totalItems to return from the search query. Internally, this -value sets the "track_total_hits" property of an Elasticsearch query. -If this parameter is set to "True", accurate count of totalItems will be returned. -If this parameter is set to "False", totalItems will be returned as 0. +The maximum number of totalItems to return from the search query. Internally, this +value sets the "track_total_hits" property of an Elasticsearch query. +If this parameter is set to "True", accurate count of totalItems will be returned. +If this parameter is set to "False", totalItems will be returned as 0. If this parameter is set to integer, accurate count of totalItems will be returned not bigger than integer. ### multiMatchType -Defines the -[multi match type](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-multi-match-query.html#multi-match-types) +Defines the +[multi match type](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-multi-match-query.html#multi-match-types) used when matching against a search term. ### boostFields @@ -427,43 +427,43 @@ Set custom boost values for particular fields when matching against a search ter -The interval used to group search results into buckets according to price range. For example, setting this to -`2000` will group into buckets every $20.00: - -```JSON -{ - "data": { - "search": { - "totalItems": 32, - "priceRange": { - "buckets": [ - { - "to": 2000, - "count": 21 - }, - { - "to": 4000, - "count": 7 - }, - { - "to": 6000, - "count": 3 - }, - { - "to": 12000, - "count": 1 - } - ] - } - } - } -} +The interval used to group search results into buckets according to price range. For example, setting this to +`2000` will group into buckets every $20.00: + +```json +{ + "data": { + "search": { + "totalItems": 32, + "priceRange": { + "buckets": [ + { + "to": 2000, + "count": 21 + }, + { + "to": 4000, + "count": 7 + }, + { + "to": 6000, + "count": 3 + }, + { + "to": 12000, + "count": 1 + } + ] + } + } + } +} ``` ### mapQuery -SearchConfig>, channelId: ID, enabledOnly: boolean, ) => any`} /> +SearchConfig>, channelId: ID, enabledOnly: boolean, ) => any`} /> -This config option allows the the modification of the whole (already built) search query. This allows +This config option allows the the modification of the whole (already built) search query. This allows for e.g. wildcard / fuzzy searches on the index. *Example* @@ -502,17 +502,17 @@ mapQuery: (query, input, searchConfig, channelId, enabledOnly){ -Sets `script_fields` inside the elasticsearch body which allows returning a script evaluation for each hit. - -The script field definition consists of three properties: - -* `graphQlType`: This is the type that will be returned when this script field is queried -via the GraphQL API. It may be one of `String`, `Int`, `Float`, `Boolean`, `ID` or list -versions thereof (`[String!]` etc) and can be appended with a `!` to indicate non-nullable fields. -* `context`: determines whether this script field is available when grouping by product. Can be -`product`, `variant` or `both`. -* `scriptFn`: This is the function to run on each hit. Should return an object with a `script` property, -as covered in the +Sets `script_fields` inside the elasticsearch body which allows returning a script evaluation for each hit. + +The script field definition consists of three properties: + +* `graphQlType`: This is the type that will be returned when this script field is queried +via the GraphQL API. It may be one of `String`, `Int`, `Float`, `Boolean`, `ID` or list +versions thereof (`[String!]` etc) and can be appended with a `!` to indicate non-nullable fields. +* `context`: determines whether this script field is available when grouping by product. Can be +`product`, `variant` or `both`. +* `scriptFn`: This is the function to run on each hit. Should return an object with a `script` property, +as covered in the [Elasticsearch script fields docs](https://www.elastic.co/guide/en/elasticsearch/reference/7.15/search-fields.html#script-fields) *Example* @@ -563,15 +563,15 @@ searchConfig: { -Allows extending the `sort` input of the elasticsearch body as covered in -[Elasticsearch sort docs](https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html) - -The `sort` input parameter contains the ElasticSearchSortInput generated for the default sort parameters "name" and "price". +Allows extending the `sort` input of the elasticsearch body as covered in +[Elasticsearch sort docs](https://www.elastic.co/guide/en/elasticsearch/reference/current/sort-search-results.html) + +The `sort` input parameter contains the ElasticSearchSortInput generated for the default sort parameters "name" and "price". If neither of those are applied it will be empty. *Example* -```TS +```ts mapSort: (sort, input) => { // Assuming `extendSearchSortType: ["priority"]` // Assuming priority is never undefined @@ -594,7 +594,7 @@ A more generic example would be a sort function based on a product location like *Example* -```TS +```ts extendSearchInputType: { latitude: 'Float', longitude: 'Float', @@ -647,9 +647,9 @@ searchConfig: { -Configuration for [boosting](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-multi-match-query.html#field-boost) -the scores of given fields when performing a search against a term. - +Configuration for [boosting](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-multi-match-query.html#field-boost) +the scores of given fields when performing a search against a term. + Boosting a field acts as a score multiplier for matches against that field. ```ts title="Signature" diff --git a/docs/docs/reference/core-plugins/elasticsearch-plugin/index.md b/docs/docs/reference/core-plugins/elasticsearch-plugin/index.md index fdf84296bd..84fcb769c3 100644 --- a/docs/docs/reference/core-plugins/elasticsearch-plugin/index.md +++ b/docs/docs/reference/core-plugins/elasticsearch-plugin/index.md @@ -54,7 +54,7 @@ This plugin extends the default search query of the Shop API, allowing richer qu The [SearchResponse](/reference/graphql-api/admin/object-types/#searchresponse) type is extended with information about price ranges in the result set: -```SDL +```graphql extend type SearchResponse { prices: SearchResponsePriceData! } @@ -86,7 +86,7 @@ This `SearchResponsePriceData` type allows you to query data about the range of ## Example Request & Response -```SDL +```graphql { search (input: { term: "table easel" @@ -121,7 +121,7 @@ This `SearchResponsePriceData` type allows you to query data about the range of } ``` -```JSON +```json { "data": { "search": { diff --git a/docs/docs/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin.md b/docs/docs/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin.md index aca82c9d67..4929843471 100644 --- a/docs/docs/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin.md +++ b/docs/docs/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin.md @@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## BullMQJobQueuePlugin - + 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. @@ -104,6 +104,38 @@ const config: VendureConfig = { }; ``` +## 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. + ```ts title="Signature" class BullMQJobQueuePlugin { static options: BullMQPluginOptions; diff --git a/docs/docs/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-strategy.md b/docs/docs/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-strategy.md index 96e26a4ad3..7fe146400c 100644 --- a/docs/docs/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-strategy.md +++ b/docs/docs/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-strategy.md @@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## BullMQJobQueueStrategy - + This JobQueueStrategy uses [BullMQ](https://docs.bullmq.io/) to implement a push-based job queue on top of Redis. It should not be used alone, but as part of the BullMQJobQueuePlugin. diff --git a/docs/docs/reference/core-plugins/payments-plugin/stripe-plugin.md b/docs/docs/reference/core-plugins/payments-plugin/stripe-plugin.md index 2d34e8d5f8..b70c491bd4 100644 --- a/docs/docs/reference/core-plugins/payments-plugin/stripe-plugin.md +++ b/docs/docs/reference/core-plugins/payments-plugin/stripe-plugin.md @@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## StripePlugin - + Plugin to enable payments through [Stripe](https://stripe.com/docs) via the Payment Intents API. @@ -46,6 +46,7 @@ the Stripe CLI to test your webhook locally. See the _local development_ section }), ] ```` + For all the plugin options, see the StripePluginOptions type. 2. Create a new PaymentMethod in the Admin UI, and select "Stripe payments" as the handler. 3. Set the webhook secret and API key in the PaymentMethod form. @@ -181,7 +182,7 @@ Initialize the Stripe payment plugin ## StripePluginOptions - + Configuration options for the Stripe payments plugin. @@ -193,6 +194,16 @@ interface StripePluginOptions { ctx: RequestContext, order: Order, ) => Stripe.MetadataParam | Promise; + paymentIntentCreateParams?: ( + injector: Injector, + ctx: RequestContext, + order: Order, + ) => AdditionalPaymentIntentCreateParams | Promise; + customerCreateParams?: ( + injector: Injector, + ctx: RequestContext, + order: Order, + ) => AdditionalCustomerCreateParams | Promise; } ``` @@ -210,7 +221,98 @@ the Stripe customer ID, so switching this on will require a database migration / Injector, ctx: RequestContext, order: Order, ) => Stripe.MetadataParam | Promise<Stripe.MetadataParam>`} since="1.9.7" /> -Attach extra metadata to Stripe payment intent +Attach extra metadata to Stripe payment intent creation call. + +*Example* + +```ts +import { EntityHydrator, VendureConfig } from '@vendure/core'; +import { StripePlugin } from '@vendure/payments-plugin/package/stripe'; + +export const config: VendureConfig = { + // ... + plugins: [ + StripePlugin.init({ + metadata: async (injector, ctx, order) => { + const hydrator = injector.get(EntityHydrator); + await hydrator.hydrate(ctx, order, { relations: ['customer'] }); + return { + description: `Order #${order.code} for ${order.customer!.emailAddress}` + }, + } + }), + ], +}; + +Note: If the `paymentIntentCreateParams` is also used and returns a `metadata` key, then the values +returned by both functions will be merged. +### paymentIntentCreateParams + +Injector, ctx: RequestContext, order: Order, ) => AdditionalPaymentIntentCreateParams | Promise<AdditionalPaymentIntentCreateParams>`} since="2.1.0" /> + +Provide additional parameters to the Stripe payment intent creation. By default, +the plugin will already pass the `amount`, `currency`, `customer` and `automatic_payment_methods: { enabled: true }` parameters. + +For example, if you want to provide a `description` for the payment intent, you can do so like this: + +*Example* + +```ts +import { VendureConfig } from '@vendure/core'; +import { StripePlugin } from '@vendure/payments-plugin/package/stripe'; + +export const config: VendureConfig = { + // ... + plugins: [ + StripePlugin.init({ + paymentIntentCreateParams: (injector, ctx, order) => { + return { + description: `Order #${order.code} for ${order.customer?.emailAddress}` + }, + } + }), + ], +}; +``` +### customerCreateParams + +Injector, ctx: RequestContext, order: Order, ) => AdditionalCustomerCreateParams | Promise<AdditionalCustomerCreateParams>`} since="2.1.0" /> + +Provide additional parameters to the Stripe customer creation. By default, +the plugin will already pass the `email` and `name` parameters. + +For example, if you want to provide an address for the customer: + +*Example* + +```ts +import { EntityHydrator, VendureConfig } from '@vendure/core'; +import { StripePlugin } from '@vendure/payments-plugin/package/stripe'; + +export const config: VendureConfig = { + // ... + plugins: [ + StripePlugin.init({ + storeCustomersInStripe: true, + customerCreateParams: async (injector, ctx, order) => { + const entityHydrator = injector.get(EntityHydrator); + const customer = order.customer; + await entityHydrator.hydrate(ctx, customer, { relations: ['addresses'] }); + const defaultBillingAddress = customer.addresses.find(a => a.defaultBillingAddress) ?? customer.addresses[0]; + return { + address: { + line1: defaultBillingAddress.streetLine1 || order.shippingAddress?.streetLine1, + postal_code: defaultBillingAddress.postalCode || order.shippingAddress?.postalCode, + city: defaultBillingAddress.city || order.shippingAddress?.city, + state: defaultBillingAddress.province || order.shippingAddress?.province, + country: defaultBillingAddress.country.code || order.shippingAddress?.countryCode, + }, + }, + } + }), + ], +}; +``` diff --git a/docs/docs/reference/typescript-api/products-stock/product-variant-price-calculation-strategy.md b/docs/docs/reference/typescript-api/products-stock/product-variant-price-calculation-strategy.md index 4669e6cb29..718ee5d5b4 100644 --- a/docs/docs/reference/typescript-api/products-stock/product-variant-price-calculation-strategy.md +++ b/docs/docs/reference/typescript-api/products-stock/product-variant-price-calculation-strategy.md @@ -11,7 +11,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## ProductVariantPriceCalculationStrategy - + Defines how ProductVariant are calculated based on the input price, tax zone and current request context. @@ -45,13 +45,16 @@ interface ProductVariantPriceCalculationStrategy extends InjectableStrategy { ## ProductVariantPriceCalculationArgs - + The arguments passed the `calculate` method of the configured ProductVariantPriceCalculationStrategy. +The `productVariant` argument was added in v2.1.0. + ```ts title="Signature" interface ProductVariantPriceCalculationArgs { inputPrice: number; + productVariant: ProductVariant; taxCategory: TaxCategory; activeTaxZone: Zone; ctx: RequestContext; @@ -65,6 +68,11 @@ interface ProductVariantPriceCalculationArgs { +### productVariant + +ProductVariant`} /> + + ### taxCategory TaxCategory`} /> diff --git a/packages/elasticsearch-plugin/src/options.ts b/packages/elasticsearch-plugin/src/options.ts index f13ae8b966..d72c01b30d 100644 --- a/packages/elasticsearch-plugin/src/options.ts +++ b/packages/elasticsearch-plugin/src/options.ts @@ -207,7 +207,7 @@ export interface ElasticsearchOptions { * ``` * * @example - * ```SDL + * ```graphql * query SearchProducts($input: SearchInput!) { * search(input: $input) { * totalItems @@ -239,7 +239,7 @@ export interface ElasticsearchOptions { * the `customProductMappings` field, which is always available. * * @example - * ```SDL + * ```graphql * query SearchProducts($input: SearchInput!) { * search(input: $input) { * totalItems @@ -329,7 +329,7 @@ export interface ElasticsearchOptions { * This allows the search query to include these new fields: * * @example - * ```GraphQl + * ```graphql * query { * search(input: { * longitude: 101.7117, @@ -439,7 +439,7 @@ export interface SearchConfig { * The interval used to group search results into buckets according to price range. For example, setting this to * `2000` will group into buckets every $20.00: * - * ```JSON + * ```json * { * "data": { * "search": { @@ -585,7 +585,7 @@ export interface SearchConfig { * If neither of those are applied it will be empty. * * @example - * ```TS + * ```ts * mapSort: (sort, input) => { * // Assuming `extendSearchSortType: ["priority"]` * // Assuming priority is never undefined @@ -606,7 +606,7 @@ export interface SearchConfig { * * A more generic example would be a sort function based on a product location like this: * @example - * ```TS + * ```ts * extendSearchInputType: { * latitude: 'Float', * longitude: 'Float', diff --git a/packages/elasticsearch-plugin/src/plugin.ts b/packages/elasticsearch-plugin/src/plugin.ts index dc3ecbf1e7..d3e4bedc4b 100644 --- a/packages/elasticsearch-plugin/src/plugin.ts +++ b/packages/elasticsearch-plugin/src/plugin.ts @@ -97,7 +97,7 @@ function getCustomResolvers(options: ElasticsearchRuntimeOptions) { * * The [SearchResponse](/reference/graphql-api/admin/object-types/#searchresponse) type is extended with information * about price ranges in the result set: - * ```SDL + * ```graphql * extend type SearchResponse { * prices: SearchResponsePriceData! * } @@ -129,7 +129,7 @@ function getCustomResolvers(options: ElasticsearchRuntimeOptions) { * * ## Example Request & Response * - * ```SDL + * ```graphql * { * search (input: { * term: "table easel" @@ -164,7 +164,7 @@ function getCustomResolvers(options: ElasticsearchRuntimeOptions) { * } * ``` * - * ```JSON + * ```json *{ * "data": { * "search": {