docs(core): Add StockLocationService documentation (#3959)

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
 
-<GenerationInfo sourceFile="packages/core/src/config/catalog/product-variant-price-calculation-strategy.ts" sourceLine="22" packageName="@vendure/core" />
+<GenerationInfo sourceFile="packages/core/src/config/catalog/product-variant-price-calculation-strategy.ts" sourceLine="23" packageName="@vendure/core" />
 
 Defines how ProductVariant are calculated based on the input price, tax zone and current request context.
 
@@ -45,7 +45,7 @@ interface ProductVariantPriceCalculationStrategy extends InjectableStrategy {
 
 ## ProductVariantPriceCalculationArgs
 
-<GenerationInfo sourceFile="packages/core/src/config/catalog/product-variant-price-calculation-strategy.ts" sourceLine="35" packageName="@vendure/core" />
+<GenerationInfo sourceFile="packages/core/src/config/catalog/product-variant-price-calculation-strategy.ts" sourceLine="36" packageName="@vendure/core" />
 
 The arguments passed the `calculate` method of the configured <a href='/reference/typescript-api/products-stock/product-variant-price-calculation-strategy#productvariantpricecalculationstrategy'>ProductVariantPriceCalculationStrategy</a>.
 
@@ -54,6 +54,7 @@ The `productVariant` argument was added in v2.1.0.
 ```ts title="Signature"
 interface ProductVariantPriceCalculationArgs {
     inputPrice: number;
+    productVariantPrice?: ProductVariantPrice;
     productVariant: ProductVariant;
     taxCategory: TaxCategory;
     activeTaxZone: Zone;
@@ -68,6 +69,11 @@ interface ProductVariantPriceCalculationArgs {
 <MemberInfo kind="property" type={`number`}   />
 
 
+### productVariantPrice
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant-price#productvariantprice'>ProductVariantPrice</a>`}   />
+
+
 ### productVariant
 
 <MemberInfo kind="property" type={`<a href='/reference/typescript-api/entities/product-variant#productvariant'>ProductVariant</a>`}   />

docs/docs/reference/typescript-api/services/initializer-service.md

@@ -27,7 +27,7 @@ class InitializerService {
 
 ### constructor
 
-<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, zoneService: <a href='/reference/typescript-api/services/zone-service#zoneservice'>ZoneService</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, administratorService: <a href='/reference/typescript-api/services/administrator-service#administratorservice'>AdministratorService</a>, shippingMethodService: <a href='/reference/typescript-api/services/shipping-method-service#shippingmethodservice'>ShippingMethodService</a>, globalSettingsService: <a href='/reference/typescript-api/services/global-settings-service#globalsettingsservice'>GlobalSettingsService</a>, taxRateService: <a href='/reference/typescript-api/services/tax-rate-service#taxrateservice'>TaxRateService</a>, sellerService: <a href='/reference/typescript-api/services/seller-service#sellerservice'>SellerService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, stockLocationService: StockLocationService) => InitializerService`}   />
+<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, zoneService: <a href='/reference/typescript-api/services/zone-service#zoneservice'>ZoneService</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, administratorService: <a href='/reference/typescript-api/services/administrator-service#administratorservice'>AdministratorService</a>, shippingMethodService: <a href='/reference/typescript-api/services/shipping-method-service#shippingmethodservice'>ShippingMethodService</a>, globalSettingsService: <a href='/reference/typescript-api/services/global-settings-service#globalsettingsservice'>GlobalSettingsService</a>, taxRateService: <a href='/reference/typescript-api/services/tax-rate-service#taxrateservice'>TaxRateService</a>, sellerService: <a href='/reference/typescript-api/services/seller-service#sellerservice'>SellerService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, stockLocationService: <a href='/reference/typescript-api/services/stock-location-service#stocklocationservice'>StockLocationService</a>) => InitializerService`}   />
 
 
 ### onModuleInit

docs/docs/reference/typescript-api/services/stock-level-service.md

@@ -32,7 +32,7 @@ class StockLevelService {
 
 ### constructor
 
-<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, stockLocationService: StockLocationService, configService: ConfigService) => StockLevelService`}   />
+<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, stockLocationService: <a href='/reference/typescript-api/services/stock-location-service#stocklocationservice'>StockLocationService</a>, configService: ConfigService) => StockLevelService`}   />
 
 
 ### getStockLevel

docs/docs/reference/typescript-api/services/stock-location-service.md

@@ -0,0 +1,119 @@
+---
+title: "StockLocationService"
+isDefaultIndex: false
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+import MemberInfo from '@site/src/components/MemberInfo';
+import GenerationInfo from '@site/src/components/GenerationInfo';
+import MemberDescription from '@site/src/components/MemberDescription';
+
+
+## StockLocationService
+
+<GenerationInfo sourceFile="packages/core/src/service/services/stock-location.service.ts" sourceLine="41" packageName="@vendure/core" />
+
+Contains methods relating to <a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a> entities.
+
+```ts title="Signature"
+class StockLocationService {
+    constructor(requestContextService: RequestContextService, connection: TransactionalConnection, channelService: ChannelService, roleService: RoleService, listQueryBuilder: ListQueryBuilder, configService: ConfigService, requestContextCache: RequestContextCacheService, customFieldRelationService: CustomFieldRelationService, eventBus: EventBus)
+    initStockLocations() => ;
+    findOne(ctx: RequestContext, stockLocationId: ID) => Promise<StockLocation | undefined>;
+    findAll(ctx: RequestContext, options?: ListQueryOptions<StockLocation>, relations?: RelationPaths<StockLocation>) => Promise<PaginatedList<StockLocation>>;
+    create(ctx: RequestContext, input: CreateStockLocationInput) => Promise<StockLocation>;
+    update(ctx: RequestContext, input: UpdateStockLocationInput) => Promise<StockLocation>;
+    delete(ctx: RequestContext, input: DeleteStockLocationInput) => Promise<DeletionResponse>;
+    assignStockLocationsToChannel(ctx: RequestContext, input: AssignStockLocationsToChannelInput) => Promise<StockLocation[]>;
+    removeStockLocationsFromChannel(ctx: RequestContext, input: RemoveStockLocationsFromChannelInput) => Promise<StockLocation[]>;
+    defaultStockLocation(ctx: RequestContext) => ;
+    getAllocationLocations(ctx: RequestContext, orderLine: OrderLine, quantity: number) => ;
+    getReleaseLocations(ctx: RequestContext, orderLine: OrderLine, quantity: number) => ;
+    getSaleLocations(ctx: RequestContext, orderLine: OrderLine, quantity: number) => ;
+    getCancellationLocations(ctx: RequestContext, orderLine: OrderLine, quantity: number) => ;
+}
+```
+
+<div className="members-wrapper">
+
+### constructor
+
+<MemberInfo kind="method" type={`(requestContextService: <a href='/reference/typescript-api/request/request-context-service#requestcontextservice'>RequestContextService</a>, connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, channelService: <a href='/reference/typescript-api/services/channel-service#channelservice'>ChannelService</a>, roleService: <a href='/reference/typescript-api/services/role-service#roleservice'>RoleService</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, configService: ConfigService, requestContextCache: <a href='/reference/typescript-api/cache/request-context-cache-service#requestcontextcacheservice'>RequestContextCacheService</a>, customFieldRelationService: CustomFieldRelationService, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>) => StockLocationService`}   />
+
+
+### initStockLocations
+
+<MemberInfo kind="method" type={`() => `}   />
+
+
+### findOne
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, stockLocationId: <a href='/reference/typescript-api/common/id#id'>ID</a>) => Promise&#60;<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a> | undefined&#62;`}   />
+
+
+### findAll
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, options?: ListQueryOptions&#60;<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>&#62;, relations?: RelationPaths&#60;<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>&#62;) => Promise&#60;<a href='/reference/typescript-api/common/paginated-list#paginatedlist'>PaginatedList</a>&#60;<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>&#62;&#62;`}   />
+
+
+### create
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: CreateStockLocationInput) => Promise&#60;<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>&#62;`}   />
+
+
+### update
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: UpdateStockLocationInput) => Promise&#60;<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>&#62;`}   />
+
+
+### delete
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: DeleteStockLocationInput) => Promise&#60;DeletionResponse&#62;`}   />
+
+Deletes a StockLocation. If `transferToLocationId` is specified in the input, all stock levels
+from the deleted location will be transferred to the target location. The last StockLocation
+cannot be deleted.
+### assignStockLocationsToChannel
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: AssignStockLocationsToChannelInput) => Promise&#60;<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>[]&#62;`}   />
+
+Assigns multiple StockLocations to the specified Channel. Requires the `UpdateStockLocation`
+permission on the target channel.
+### removeStockLocationsFromChannel
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, input: RemoveStockLocationsFromChannelInput) => Promise&#60;<a href='/reference/typescript-api/entities/stock-location#stocklocation'>StockLocation</a>[]&#62;`}   />
+
+Removes multiple StockLocations from the specified Channel. Requires the `DeleteStockLocation`
+permission on the target channel. StockLocations cannot be removed from the default channel.
+### defaultStockLocation
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => `}   />
+
+
+### getAllocationLocations
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, quantity: number) => `}   />
+
+Returns the locations and quantities to use for allocating stock when an OrderLine is created.
+This uses the configured <a href='/reference/typescript-api/products-stock/stock-location-strategy#stocklocationstrategy'>StockLocationStrategy</a>.
+### getReleaseLocations
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, quantity: number) => `}   />
+
+Returns the locations and quantities to use for releasing allocated stock when an OrderLine is cancelled
+or modified. This uses the configured <a href='/reference/typescript-api/products-stock/stock-location-strategy#stocklocationstrategy'>StockLocationStrategy</a>.
+### getSaleLocations
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, quantity: number) => `}   />
+
+Returns the locations and quantities to use for creating sales when an Order is fulfilled.
+This uses the configured <a href='/reference/typescript-api/products-stock/stock-location-strategy#stocklocationstrategy'>StockLocationStrategy</a>.
+### getCancellationLocations
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, orderLine: <a href='/reference/typescript-api/entities/order-line#orderline'>OrderLine</a>, quantity: number) => `}   />
+
+Returns the locations and quantities to use for cancelling sales when an OrderLine is cancelled
+after fulfillment. This uses the configured <a href='/reference/typescript-api/products-stock/stock-location-strategy#stocklocationstrategy'>StockLocationStrategy</a>.
+
+
+</div>

docs/docs/reference/typescript-api/services/stock-movement-service.md

@@ -44,7 +44,7 @@ class StockMovementService {
 
 ### constructor
 
-<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, globalSettingsService: <a href='/reference/typescript-api/services/global-settings-service#globalsettingsservice'>GlobalSettingsService</a>, stockLevelService: <a href='/reference/typescript-api/services/stock-level-service#stocklevelservice'>StockLevelService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, stockLocationService: StockLocationService) => StockMovementService`}   />
+<MemberInfo kind="method" type={`(connection: <a href='/reference/typescript-api/data-access/transactional-connection#transactionalconnection'>TransactionalConnection</a>, listQueryBuilder: <a href='/reference/typescript-api/data-access/list-query-builder#listquerybuilder'>ListQueryBuilder</a>, globalSettingsService: <a href='/reference/typescript-api/services/global-settings-service#globalsettingsservice'>GlobalSettingsService</a>, stockLevelService: <a href='/reference/typescript-api/services/stock-level-service#stocklevelservice'>StockLevelService</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, stockLocationService: <a href='/reference/typescript-api/services/stock-location-service#stocklocationservice'>StockLocationService</a>) => StockMovementService`}   />
 
 
 ### getStockMovementsByProductVariantId

package-lock.json

@@ -52132,7 +52132,7 @@
         "@radix-ui/react-toggle": "^1.1.9",
         "@radix-ui/react-toggle-group": "^1.1.10",
         "@radix-ui/react-tooltip": "^1.2.7",
-        "@swc/core": "^1.13.5",
+        "@swc/core": "1.13.5",
         "@tailwindcss/vite": "^4.1.5",
         "@tanstack/eslint-plugin-query": "^5.66.1",
         "@tanstack/react-query": "^5.66.7",

packages/core/src/service/services/stock-location.service.ts

@@ -32,6 +32,12 @@ import { patchEntity } from '../helpers/utils/patch-entity';
 import { ChannelService } from './channel.service';
 import { RoleService } from './role.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link StockLocation} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 @Instrument()
 export class StockLocationService {
@@ -103,6 +109,12 @@ export class StockLocationService {
         return assertFound(this.findOne(ctx, updatedStockLocation.id));
     }
 
+    /**
+     * @description
+     * Deletes a StockLocation. If `transferToLocationId` is specified in the input, all stock levels
+     * from the deleted location will be transferred to the target location. The last StockLocation
+     * cannot be deleted.
+     */
     async delete(ctx: RequestContext, input: DeleteStockLocationInput): Promise<DeletionResponse> {
         const stockLocation = await this.connection.findOneInChannel(
             ctx,
@@ -169,6 +181,11 @@ export class StockLocationService {
         };
     }
 
+    /**
+     * @description
+     * Assigns multiple StockLocations to the specified Channel. Requires the `UpdateStockLocation`
+     * permission on the target channel.
+     */
     async assignStockLocationsToChannel(
         ctx: RequestContext,
         input: AssignStockLocationsToChannelInput,
@@ -199,6 +216,11 @@ export class StockLocationService {
         );
     }
 
+    /**
+     * @description
+     * Removes multiple StockLocations from the specified Channel. Requires the `DeleteStockLocation`
+     * permission on the target channel. StockLocations cannot be removed from the default channel.
+     */
     async removeStockLocationsFromChannel(
         ctx: RequestContext,
         input: RemoveStockLocationsFromChannelInput,
@@ -228,7 +250,7 @@ export class StockLocationService {
         );
     }
 
-    getAllStockLocations(ctx: RequestContext) {
+    private getAllStockLocations(ctx: RequestContext) {
         return this.requestContextCache.get(ctx, 'StockLocationService.getAllStockLocations', () =>
             this.connection.getRepository(ctx, StockLocation).find(),
         );
@@ -241,6 +263,11 @@ export class StockLocationService {
             .then(items => items[0]);
     }
 
+    /**
+     * @description
+     * Returns the locations and quantities to use for allocating stock when an OrderLine is created.
+     * This uses the configured {@link StockLocationStrategy}.
+     */
     async getAllocationLocations(ctx: RequestContext, orderLine: OrderLine, quantity: number) {
         const { stockLocationStrategy } = this.configService.catalogOptions;
         const stockLocations = await this.getAllStockLocations(ctx);
@@ -253,6 +280,11 @@ export class StockLocationService {
         return allocationLocations;
     }
 
+    /**
+     * @description
+     * Returns the locations and quantities to use for releasing allocated stock when an OrderLine is cancelled
+     * or modified. This uses the configured {@link StockLocationStrategy}.
+     */
     async getReleaseLocations(ctx: RequestContext, orderLine: OrderLine, quantity: number) {
         const { stockLocationStrategy } = this.configService.catalogOptions;
         const stockLocations = await this.getAllStockLocations(ctx);
@@ -265,6 +297,11 @@ export class StockLocationService {
         return releaseLocations;
     }
 
+    /**
+     * @description
+     * Returns the locations and quantities to use for creating sales when an Order is fulfilled.
+     * This uses the configured {@link StockLocationStrategy}.
+     */
     async getSaleLocations(ctx: RequestContext, orderLine: OrderLine, quantity: number) {
         const { stockLocationStrategy } = this.configService.catalogOptions;
         const stockLocations = await this.getAllStockLocations(ctx);
@@ -272,6 +309,11 @@ export class StockLocationService {
         return saleLocations;
     }
 
+    /**
+     * @description
+     * Returns the locations and quantities to use for cancelling sales when an OrderLine is cancelled
+     * after fulfillment. This uses the configured {@link StockLocationStrategy}.
+     */
     async getCancellationLocations(ctx: RequestContext, orderLine: OrderLine, quantity: number) {
         const { stockLocationStrategy } = this.configService.catalogOptions;
         const stockLocations = await this.getAllStockLocations(ctx);