docs(core): Add doc blocks to services

packages/core/src/entity/history-entry/customer-history-entry.entity.ts

@@ -5,6 +5,12 @@ import { Customer } from '../customer/customer.entity';
 
 import { HistoryEntry } from './history-entry.entity';
 
+/**
+ * @description
+ * Represents an event in the history of a particular {@link Customer}.
+ *
+ * @docsCategory entities
+ */
 @ChildEntity()
 export class CustomerHistoryEntry extends HistoryEntry {
     constructor(input: DeepPartial<CustomerHistoryEntry>) {

packages/core/src/entity/history-entry/history-entry.entity.ts

@@ -4,6 +4,13 @@ import { Column, Entity, ManyToOne, TableInheritance } from 'typeorm';
 import { Administrator } from '../administrator/administrator.entity';
 import { VendureEntity } from '../base/base.entity';
 
+/**
+ * @description
+ * An abstract entity representing an entry in the history of an Order ({@link OrderHistoryEntry})
+ * or a Customer ({@link CustomerHistoryEntry}).
+ *
+ * @docsCategory entities
+ */
 @Entity()
 @TableInheritance({ column: { type: 'varchar', name: 'discriminator' } })
 export abstract class HistoryEntry extends VendureEntity {

packages/core/src/entity/history-entry/order-history-entry.entity.ts

@@ -5,6 +5,12 @@ import { Order } from '../order/order.entity';
 
 import { HistoryEntry } from './history-entry.entity';
 
+/**
+ * @description
+ * Represents an event in the history of a particular {@link Order}.
+ *
+ * @docsCategory entities
+ */
 @ChildEntity()
 export class OrderHistoryEntry extends HistoryEntry {
     constructor(input: DeepPartial<OrderHistoryEntry>) {

packages/core/src/service/services/administrator.service.ts

@@ -22,6 +22,12 @@ import { patchEntity } from '../helpers/utils/patch-entity';
 import { RoleService } from './role.service';
 import { UserService } from './user.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link Administrator} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class AdministratorService {
     constructor(
@@ -34,10 +40,15 @@ export class AdministratorService {
         private customFieldRelationService: CustomFieldRelationService,
     ) {}
 
+    /** @internal */
     async initAdministrators() {
         await this.ensureSuperAdminExists();
     }
 
+    /**
+     * @description
+     * Get a paginated list of Administrators.
+     */
     findAll(
         ctx: RequestContext,
         options?: ListQueryOptions<Administrator>,
@@ -55,6 +66,10 @@ export class AdministratorService {
             }));
     }
 
+    /**
+     * @description
+     * Get an Administrator by id.
+     */
     findOne(ctx: RequestContext, administratorId: ID): Promise<Administrator | undefined> {
         return this.connection.getRepository(ctx, Administrator).findOne(administratorId, {
             relations: ['user', 'user.roles'],
@@ -64,6 +79,10 @@ export class AdministratorService {
         });
     }
 
+    /**
+     * @description
+     * Get an Administrator based on the User id.
+     */
     findOneByUserId(ctx: RequestContext, userId: ID): Promise<Administrator | undefined> {
         return this.connection.getRepository(ctx, Administrator).findOne({
             where: {
@@ -73,6 +92,10 @@ export class AdministratorService {
         });
     }
 
+    /**
+     * @description
+     * Create a new Administrator.
+     */
     async create(ctx: RequestContext, input: CreateAdministratorInput): Promise<Administrator> {
         const administrator = new Administrator(input);
         administrator.user = await this.userService.createAdminUser(ctx, input.emailAddress, input.password);
@@ -91,6 +114,10 @@ export class AdministratorService {
         return createdAdministrator;
     }
 
+    /**
+     * @description
+     * Update an existing Administrator.
+     */
     async update(ctx: RequestContext, input: UpdateAdministratorInput): Promise<Administrator> {
         const administrator = await this.findOne(ctx, input.id);
         if (!administrator) {
@@ -128,6 +155,7 @@ export class AdministratorService {
     }
 
     /**
+     * @description
      * Assigns a Role to the Administrator's User entity.
      */
     async assignRole(ctx: RequestContext, administratorId: ID, roleId: ID): Promise<Administrator> {
@@ -144,6 +172,10 @@ export class AdministratorService {
         return administrator;
     }
 
+    /**
+     * @description
+     * Soft deletes an Administrator (sets the `deletedAt` field).
+     */
     async softDelete(ctx: RequestContext, id: ID) {
         const administrator = await this.connection.getEntityOrThrow(ctx, Administrator, id, {
             relations: ['user'],
@@ -157,8 +189,11 @@ export class AdministratorService {
     }
 
     /**
+     * @description
      * There must always exist a SuperAdmin, otherwise full administration via API will
      * no longer be possible.
+     *
+     * @internal
      */
     private async ensureSuperAdminExists() {
         const { superadminCredentials } = this.configService.authOptions;

packages/core/src/service/services/asset.service.ts

@@ -60,6 +60,12 @@ export interface EntityAssetInput {
     featuredAssetId?: ID | null;
 }
 
+/**
+ * @description
+ * Contains methods relating to {@link Asset} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class AssetService {
     private permittedMimeTypes: Array<{ type: string; subtype: string }> = [];

packages/core/src/service/services/auth.service.ts

@@ -27,7 +27,10 @@ import { LogoutEvent } from '../../event-bus/events/logout-event';
 import { SessionService } from './session.service';
 
 /**
- * The AuthService manages both authenticated and anonymous Sessions.
+ * @description
+ * Contains methods relating to {@link Session}, {@link AuthenticatedSession} & {@link AnonymousSession} entities.
+ *
+ * @docsCategory services
  */
 @Injectable()
 export class AuthService {
@@ -39,6 +42,7 @@ export class AuthService {
     ) {}
 
     /**
+     * @description
      * Authenticates a user's credentials and if okay, creates a new session.
      */
     async authenticate(

packages/core/src/service/services/channel.service.ts

@@ -31,6 +31,12 @@ import { patchEntity } from '../helpers/utils/patch-entity';
 
 import { GlobalSettingsService } from './global-settings.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link Channel} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class ChannelService {
     private allChannels: SelfRefreshingCache<Channel[], [RequestContext]>;

packages/core/src/service/services/collection.service.ts

@@ -50,6 +50,12 @@ export type ApplyCollectionFiltersJobData = {
     applyToChangedVariantsOnly?: boolean;
 };
 
+/**
+ * @description
+ * Contains methods relating to {@link Collection} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class CollectionService implements OnModuleInit {
     private rootCollection: Translated<Collection> | undefined;

packages/core/src/service/services/country.service.ts

@@ -22,6 +22,12 @@ import { translateDeep } from '../helpers/utils/translate-entity';
 
 import { ZoneService } from './zone.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link Country} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class CountryService {
     constructor(

packages/core/src/service/services/customer-group.service.ts

@@ -25,6 +25,12 @@ import { patchEntity } from '../helpers/utils/patch-entity';
 
 import { HistoryService } from './history.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link CustomerGroup} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class CustomerGroupService {
     constructor(

packages/core/src/service/services/customer.service.ts

@@ -62,6 +62,12 @@ import { CountryService } from './country.service';
 import { HistoryService } from './history.service';
 import { UserService } from './user.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link Customer} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class CustomerService {
     constructor(

packages/core/src/service/services/facet-value.service.ts

@@ -24,6 +24,12 @@ import { translateDeep } from '../helpers/utils/translate-entity';
 
 import { ChannelService } from './channel.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link FacetValue} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class FacetValueService {
     constructor(

packages/core/src/service/services/facet.service.ts

@@ -25,6 +25,12 @@ import { translateDeep } from '../helpers/utils/translate-entity';
 import { ChannelService } from './channel.service';
 import { FacetValueService } from './facet-value.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link Facet} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class FacetService {
     constructor(

packages/core/src/service/services/fulfillment.service.ts

@@ -21,6 +21,12 @@ import { CustomFieldRelationService } from '../helpers/custom-field-relation/cus
 import { FulfillmentState } from '../helpers/fulfillment-state-machine/fulfillment-state';
 import { FulfillmentStateMachine } from '../helpers/fulfillment-state-machine/fulfillment-state-machine';
 
+/**
+ * @description
+ * Contains methods relating to {@link Fulfillment} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class FulfillmentService {
     constructor(

packages/core/src/service/services/global-settings.service.ts

@@ -9,6 +9,12 @@ import { GlobalSettings } from '../../entity/global-settings/global-settings.ent
 import { CustomFieldRelationService } from '../helpers/custom-field-relation/custom-field-relation.service';
 import { patchEntity } from '../helpers/utils/patch-entity';
 
+/**
+ * @description
+ * Contains methods relating to the {@link GlobalSettings} entity.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class GlobalSettingsService {
     constructor(

packages/core/src/service/services/history.service.ts

@@ -137,7 +137,10 @@ export interface UpdateCustomerHistoryEntryArgs<T extends keyof CustomerHistoryE
 }
 
 /**
- * The HistoryService is reponsible for creating and retrieving HistoryEntry entities.
+ * @description
+ * Contains methods relating to {@link HistoryEntry} entities.
+ *
+ * @docsCategory services
  */
 @Injectable()
 export class HistoryService {

packages/core/src/service/services/order-testing.service.ts

@@ -26,8 +26,11 @@ import { ShippingCalculator } from '../helpers/shipping-calculator/shipping-calc
 import { translateDeep } from '../helpers/utils/translate-entity';
 
 /**
+ * @description
  * This service is responsible for creating temporary mock Orders against which tests can be run, such as
  * testing a ShippingMethod or Promotion.
+ *
+ * @docsCategory services
  */
 @Injectable()
 export class OrderTestingService {

packages/core/src/service/services/order.service.ts

@@ -123,6 +123,12 @@ import { ProductVariantService } from './product-variant.service';
 import { PromotionService } from './promotion.service';
 import { StockMovementService } from './stock-movement.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link Order} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class OrderService {
     constructor(

packages/core/src/service/services/payment-method.service.ts

@@ -28,6 +28,12 @@ import { patchEntity } from '../helpers/utils/patch-entity';
 
 import { ChannelService } from './channel.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link PaymentMethod} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class PaymentMethodService {
     constructor(

packages/core/src/service/services/payment.service.ts

@@ -32,6 +32,12 @@ import { RefundStateMachine } from '../helpers/refund-state-machine/refund-state
 
 import { PaymentMethodService } from './payment-method.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link Payment} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class PaymentService {
     constructor(

packages/core/src/service/services/product-option-group.service.ts

@@ -16,6 +16,12 @@ import { CustomFieldRelationService } from '../helpers/custom-field-relation/cus
 import { TranslatableSaver } from '../helpers/translatable-saver/translatable-saver';
 import { translateDeep } from '../helpers/utils/translate-entity';
 
+/**
+ * @description
+ * Contains methods relating to {@link ProductOptionGroup} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class ProductOptionGroupService {
     constructor(

packages/core/src/service/services/product-option.service.ts

@@ -17,6 +17,12 @@ import { CustomFieldRelationService } from '../helpers/custom-field-relation/cus
 import { TranslatableSaver } from '../helpers/translatable-saver/translatable-saver';
 import { translateDeep } from '../helpers/utils/translate-entity';
 
+/**
+ * @description
+ * Contains methods relating to {@link ProductOption} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class ProductOptionService {
     constructor(

packages/core/src/service/services/product-variant.service.ts

@@ -50,6 +50,12 @@ import { RoleService } from './role.service';
 import { StockMovementService } from './stock-movement.service';
 import { TaxCategoryService } from './tax-category.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link ProductVariant} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class ProductVariantService {
     constructor(

packages/core/src/service/services/product.service.ts

@@ -42,6 +42,12 @@ import { ProductVariantService } from './product-variant.service';
 import { RoleService } from './role.service';
 import { TaxRateService } from './tax-rate.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link Product} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class ProductService {
     private readonly relations = ['featuredAsset', 'assets', 'channels', 'facetValues', 'facetValues.facet'];

packages/core/src/service/services/promotion.service.ts

@@ -40,6 +40,12 @@ import { patchEntity } from '../helpers/utils/patch-entity';
 
 import { ChannelService } from './channel.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link Promotion} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class PromotionService {
     availableConditions: PromotionCondition[] = [];

packages/core/src/service/services/role.service.ts

@@ -36,6 +36,12 @@ import { patchEntity } from '../helpers/utils/patch-entity';
 
 import { ChannelService } from './channel.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link Role} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class RoleService {
     constructor(

packages/core/src/service/services/search.service.ts

@@ -6,14 +6,18 @@ import { Logger } from '../../config/logger/vendure-logger';
 import { Job } from '../../job-queue/job';
 
 /**
+ * @description
  * This service allows a concrete search service to override its behaviour
  * by passing itself to the `adopt()` method.
+ *
+ * @docsCategory services
  */
 @Injectable()
 export class SearchService {
     private override: Pick<SearchService, 'reindex'> | undefined;
 
     /**
+     * @description
      * Adopt a concrete search service implementation to pass through the
      * calls to.
      */

packages/core/src/service/services/session.service.ts

@@ -19,6 +19,12 @@ import { getUserChannelsPermissions } from '../helpers/utils/get-user-channels-p
 
 import { OrderService } from './order.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link Session} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class SessionService implements EntitySubscriberInterface {
     private sessionCacheStrategy: SessionCacheStrategy;

packages/core/src/service/services/shipping-method.service.ts

@@ -27,6 +27,12 @@ import { translateDeep } from '../helpers/utils/translate-entity';
 
 import { ChannelService } from './channel.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link ShippingMethod} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class ShippingMethodService {
     constructor(

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

@@ -24,6 +24,12 @@ import { ListQueryBuilder } from '../helpers/list-query-builder/list-query-build
 
 import { GlobalSettingsService } from './global-settings.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link StockMovement} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class StockMovementService {
     shippingEligibilityCheckers: ShippingEligibilityChecker[];

packages/core/src/service/services/tag.service.ts

@@ -15,6 +15,12 @@ import { VendureEntity } from '../../entity/base/base.entity';
 import { Tag } from '../../entity/tag/tag.entity';
 import { ListQueryBuilder } from '../helpers/list-query-builder/list-query-builder';
 
+/**
+ * @description
+ * Contains methods relating to {@link Tag} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class TagService {
     constructor(private connection: TransactionalConnection, private listQueryBuilder: ListQueryBuilder) {}

packages/core/src/service/services/tax-category.service.ts

@@ -15,6 +15,12 @@ import { TaxCategory } from '../../entity/tax-category/tax-category.entity';
 import { TaxRate } from '../../entity/tax-rate/tax-rate.entity';
 import { patchEntity } from '../helpers/utils/patch-entity';
 
+/**
+ * @description
+ * Contains methods relating to {@link TaxCategory} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class TaxCategoryService {
     constructor(private connection: TransactionalConnection) {}

packages/core/src/service/services/tax-rate.service.ts

@@ -24,6 +24,12 @@ import { patchEntity } from '../helpers/utils/patch-entity';
 
 const activeTaxRatesKey = 'active-tax-rates';
 
+/**
+ * @description
+ * Contains methods relating to {@link TaxRate} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class TaxRateService {
     private readonly defaultTaxRate = new TaxRate({

packages/core/src/service/services/user.service.ts

@@ -25,6 +25,12 @@ import { VerificationTokenGenerator } from '../helpers/verification-token-genera
 
 import { RoleService } from './role.service';
 
+/**
+ * @description
+ * Contains methods relating to {@link User} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class UserService {
     constructor(

packages/core/src/service/services/zone.service.ts

@@ -21,6 +21,12 @@ import { Zone } from '../../entity/zone/zone.entity';
 import { patchEntity } from '../helpers/utils/patch-entity';
 import { translateDeep } from '../helpers/utils/translate-entity';
 
+/**
+ * @description
+ * Contains methods relating to {@link Zone} entities.
+ *
+ * @docsCategory services
+ */
 @Injectable()
 export class ZoneService {
     /**