Interface Documentation

Overview

This document provides comprehensive TypeScript interface definitions, DTOs, enums, and contracts used throughout the Service Management module. The service management system handles bookable services with complex configuration options, multilingual support, and flexible pricing models.

Core Data Transfer Objects (DTOs)

ServiceDto

The main service data transfer object containing all service information.

interface ServiceDto extends BaseEntityDto {
  object?: 'ServiceDto';
  configuration?: ServiceConfigurationDto;
  presentation?: PresentationDto;
  prepaymentPolicy?: PrepaymentPolicyDto;
  languageVersions: LanguageVersionDto[];
  durationVersions?: DurationVersionDto[];
  schedules?: ScheduleDto[];
  order?: number | null;
}

Properties:

• object: Object type identifier for serialization

• configuration: Service configuration settings

• presentation: Visual presentation and branding

• prepaymentPolicy: Payment requirements and policies

• languageVersions: Service details in multiple languages (required)

• durationVersions: Available duration and pricing options

• schedules: Available time slots and scheduling rules

• order: Display order for service listing

ServiceConfigurationDto

Configuration settings that define service behavior.

interface ServiceConfigurationDto {
  object?: 'ServiceConfigurationDto';
  duration?: DurationConfigurationDto;
}

Properties:

• duration: Duration configuration options

DurationConfigurationDto

Defines how service duration is managed.

interface DurationConfigurationDto {
  object?: 'DurationConfigurationDto';
  durationVersionType: DurationVersionTypeEnum;
}

Properties:

• durationVersionType: Type of duration configuration (RANGE, VARIABLE)

PresentationDto

Visual presentation and media configuration.

interface PresentationDto {
  object?: 'PresentationDto';
  banners: MediaDto[];
  color?: string | null;
}

Properties:

• banners: Array of banner images and media

• color: Hex color code or color name for theming

PrepaymentPolicyDto

Payment policy and prepayment requirements.

interface PrepaymentPolicyDto {
  object?: 'PrepaymentPolicyDto';
  isRequired: boolean;
  isPercentage?: boolean;
  value?: string;
  minimalCancelTime?: string;
}

Properties:

• isRequired: Whether prepayment is mandatory

• isPercentage: Whether value is percentage or fixed amount

• value: Prepayment amount or percentage

• minimalCancelTime: Minimum cancellation time in seconds

DurationVersionDto

Specific duration option with pricing.

interface DurationVersionDto {
  object?: 'DurationVersionDto';
  breakInSeconds?: number;
  durationInSeconds: number;
  prices?: PriceDto[];
}

Properties:

• breakInSeconds: Break time after service completion

• durationInSeconds: Service duration in seconds (required)

• prices: Available pricing options for this duration

PriceDto

Pricing information for services.

interface PriceDto {
  object?: 'PriceDto';
  price: number;
  currency?: CurrencyCodeEnum;
  preferredLanguages?: LanguageCodeEnum[];
}

Properties:

• price: Price amount (required)

• currency: Currency code (default: USD)

• preferredLanguages: Languages this price applies to

ServicePaginationDto

Pagination parameters for service listing.

interface ServicePaginationDto extends PaginationDto {
  phrase?: string;
}

Properties:

• phrase: Search phrase for filtering services by title or description

• Inherits: page, size from PaginationDto

PublicServiceDto

Public-facing service information (limited data for client apps).

interface PublicServiceDto {
  _id?: string;
  object?: 'PublicServiceDto';
  languageVersions: LanguageVersionDto[];
  durationVersions?: DurationVersionDto[];
  presentation?: PresentationDto;
  schedules?: ScheduleDto[];
  order?: number | null;
}

Properties:

• Contains only public information (no internal configuration)

• Used for customer-facing service displays

RequestPublicServiceDto

Service data used in public order creation.

interface RequestPublicServiceDto {
  _id: string;
  object?: 'RequestPublicServiceDto';
  languageVersions: LanguageVersionDto[];
  durationVersions?: DurationVersionDto[];
  presentation?: PresentationDto;
}

Properties:

• Service snapshot for order processing

• Immutable service data preserved in orders

Domain Interfaces

IService

Core service domain interface.

interface IService extends IBase {
  presentation: IPresentation;
  configuration?: IServiceConfiguration;
  prepaymentPolicy: IPaymentPolicy;
  schedules?: ISchedule[];
  languageVersions: ILanguageVersion[];
  durationVersions: IDurationVersion[];
  specialists?: ISpecialist[];
  requiredResources?: IRequiredResource[];
  createdAt?: string;
  updatedAt?: string;
  order?: number | null;
}

Properties:

• Extends IBase for common entity properties

• Contains all service domain properties

• Used for domain logic and validation

IPresentation

Presentation value object interface.

interface IPresentation {
  color?: string;
  banners: IMedia[];
}

Properties:

• color: Hex color or color name for theming

• banners: Array of media items for service display

IDurationVersion

Duration version value object interface.

interface IDurationVersion {
  breakInSeconds: number;
  durationInSeconds: number;
  prices: IPrice[];
}

Properties:

• breakInSeconds: Break time after service

• durationInSeconds: Service duration

• prices: Array of pricing options

IServiceConfiguration

Service configuration value object interface.

interface IServiceConfiguration {
  duration?: IDurationConfiguration;
}

Properties:

• duration: Duration-related configuration

IPaymentPolicy

Payment policy value object interface.

interface IPaymentPolicy {
  isRequired: boolean;
  isPercentage?: boolean;
  value?: string;
  minimalCancelTime?: string;
}

Properties:

• Defines prepayment requirements and cancellation policies

IPrice

Price value object interface.

interface IPrice {
  price: number;
  currency: CurrencyCodeEnum;
  preferredLanguages?: LanguageCodeEnum[];
}

Properties:

• price: Numeric price value

• currency: Currency code for the price

• preferredLanguages: Target languages for this price

Enumerations

DurationVersionTypeEnum

Defines how service duration is handled.

enum DurationVersionTypeEnum {
  RANGE = 'RANGE',
  VARIABLE = 'VARIABLE'
}

Values:

• RANGE: Fixed duration range with breaks

• VARIABLE: Variable duration based on customer needs

CurrencyCodeEnum

ISO 4217 currency codes for pricing.

enum CurrencyCodeEnum {
  USD = 'USD',
  EUR = 'EUR', 
  GBP = 'GBP',
  CAD = 'CAD',
  AUD = 'AUD',
  JPY = 'JPY',
  CHF = 'CHF',
  CNY = 'CNY',
  SEK = 'SEK',
  NOK = 'NOK',
  DKK = 'DKK',
  PLN = 'PLN',
  CZK = 'CZK',
  HUF = 'HUF',
  RUB = 'RUB',
  BRL = 'BRL',
  MXN = 'MXN',
  ZAR = 'ZAR',
  INR = 'INR',
  KRW = 'KRW',
  SGD = 'SGD',
  NZD = 'NZD'
}

Usage:

• Used for pricing in different currencies

• Supports international businesses

• Validates currency format in pricing

LanguageCodeEnum

ISO 639-1 language codes for internationalization.

enum LanguageCodeEnum {
  en = 'en',
  es = 'es', 
  fr = 'fr',
  de = 'de',
  it = 'it',
  pt = 'pt',
  ru = 'ru',
  ja = 'ja',
  ko = 'ko',
  zh = 'zh',
  ar = 'ar',
  hi = 'hi',
  tr = 'tr',
  pl = 'pl',
  nl = 'nl',
  sv = 'sv',
  da = 'da',
  no = 'no',
  fi = 'fi',
  el = 'gr',
  he = 'he',
  th = 'th',
  vi = 'vi',
  cs = 'cs',
  hu = 'hu',
  ro = 'ro',
  sk = 'sk',
  bg = 'bg',
  hr = 'hr',
  sl = 'si',
  et = 'ee',
  lv = 'lv',
  lt = 'lt',
  uk = 'ua',
  ca = 'ca'
}

Usage:

• Multilingual service descriptions

• Language-specific pricing

• Localized service information

Shared DTOs and Interfaces

LanguageVersionDto

Multilingual content structure.

interface LanguageVersionDto {
  object?: 'LanguageVersionDto';
  language: LanguageCodeEnum;
  title: string;
  description?: string;
}

Properties:

• language: Language code for this version

• title: Service title in specified language

• description: Optional detailed description

MediaDto

Media file information.

interface MediaDto extends BaseEntityDto {
  object?: 'MediaDto';
  url?: string;
  mimeType?: string;
  filename?: string;
  size?: number;
  description?: string;
}

Properties:

• url: Media file URL

• mimeType: MIME type of the file

• filename: Original filename

• size: File size in bytes

• description: Media description

ScheduleDto

Service availability schedule.

interface ScheduleDto {
  object?: 'ScheduleDto';
  weekDays: number[];
  startTime: string;
  endTime: string;
  timezone?: string;
}

Properties:

• weekDays: Array of weekday numbers (1=Monday, 7=Sunday)

• startTime: Start time in HH:mm format

• endTime: End time in HH:mm format

• timezone: Optional timezone identifier

RequiredResourceDto

Resource requirements for services.

interface RequiredResourceDto {
  object?: 'RequiredResourceDto';
  resourceId: string;
  quantity: number;
  isRequired: boolean;
}

Properties:

• resourceId: Reference to resource entity

• quantity: Number of resources needed

• isRequired: Whether resource is mandatory

Validation Constraints

Service Validation Rules

// Service title validation
@IsString()
@IsNotEmpty()
@MaxLength(200)
title: string;

// Service description validation  
@IsString()
@IsOptional()
@MaxLength(2000)
description?: string;

// Duration validation
@IsInt()
@Min(300) // Minimum 5 minutes
@Max(86400) // Maximum 24 hours
durationInSeconds: number;

// Price validation
@IsNumber()
@Min(0)
@Max(999999.99)
price: number;

// Break time validation
@IsInt()
@Min(0)
@Max(3600) // Maximum 1 hour break
breakInSeconds?: number;

// Order validation
@IsInt()
@Min(0)
@IsOptional()
order?: number;

// Color validation
@IsString()
@IsOptional()
@Matches(/^#[0-9A-Fa-f]{6}$|^[a-zA-Z]+$/)
color?: string;

Language Version Validation

// At least one language version required
@IsArray()
@ArrayMinSize(1)
@ValidateNested({ each: true })
@Type(() => LanguageVersionDto)
languageVersions: LanguageVersionDto[];

// Language code validation
@IsEnum(LanguageCodeEnum)
language: LanguageCodeEnum;

// Title validation per language
@IsString()
@IsNotEmpty()
@MaxLength(200)
title: string;

Duration Version Validation

// At least one duration version for bookable services
@IsArray()
@ArrayMinSize(1)
@ValidateNested({ each: true })
@Type(() => DurationVersionDto)
durationVersions: DurationVersionDto[];

// Duration must be positive
@IsInt()
@Min(1)
durationInSeconds: number;

// At least one price per duration
@IsArray()
@ArrayMinSize(1)
@ValidateNested({ each: true })
@Type(() => PriceDto)
prices: PriceDto[];

Type Guards and Utilities

Service Type Guards

// Check if service is bookable
function isBookableService(service: ServiceDto): boolean {
  return !!(service.durationVersions && service.durationVersions.length > 0);
}

// Check if service has prepayment requirement
function requiresPrepayment(service: ServiceDto): boolean {
  return service.prepaymentPolicy?.isRequired === true;
}

// Check if service has media
function hasMedia(service: ServiceDto): boolean {
  return !!(service.presentation?.banners?.length);
}

// Check if service is multilingual
function isMultilingual(service: ServiceDto): boolean {
  return service.languageVersions.length > 1;
}

Price Utilities

// Get price for specific currency
function getPriceForCurrency(
  durationVersion: DurationVersionDto, 
  currency: CurrencyCodeEnum
): PriceDto | undefined {
  return durationVersion.prices?.find(p => p.currency === currency);
}

// Get price for language
function getPriceForLanguage(
  durationVersion: DurationVersionDto,
  language: LanguageCodeEnum
): PriceDto | undefined {
  return durationVersion.prices?.find(
    p => p.preferredLanguages?.includes(language)
  );
}

// Format price for display
function formatPrice(price: PriceDto): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: price.currency || 'USD'
  }).format(price.price);
}

Duration Utilities

// Convert seconds to human readable format
function formatDuration(seconds: number): string {
  const hours = Math.floor(seconds / 3600);
  const minutes = Math.floor((seconds % 3600) / 60);
  
  if (hours > 0) {
    return `${hours}h ${minutes}m`;
  }
  return `${minutes}m`;
}

// Calculate total appointment time (duration + break)
function getTotalAppointmentTime(durationVersion: DurationVersionDto): number {
  return durationVersion.durationInSeconds + (durationVersion.breakInSeconds || 0);
}

// Check if duration is valid
function isValidDuration(seconds: number): boolean {
  return seconds >= 300 && seconds <= 86400; // 5 minutes to 24 hours
}

Error Types

Service-Specific Exceptions

// Service not found
interface ServiceNotFoundException {
  name: 'ServiceNotFoundException';
  message: string;
  serviceId: string;
}

// Service creation failure
interface ServiceCreationException {
  name: 'ServiceCreationException';  
  message: string;
  validationErrors: string[];
}

// Service update failure
interface ServiceUpdationException {
  name: 'ServiceUpdationException';
  message: string;
  serviceId: string;
  validationErrors: string[];
}

// Service deletion failure
interface ServiceDeletionException {
  name: 'ServiceDeletionException';
  message: string;
  serviceId: string;
  reason: string;
}

Validation Error Types

// Language version validation error
interface LanguageVersionValidationError {
  field: 'languageVersions';
  code: 'INVALID_LANGUAGE_VERSION';
  message: string;
  language?: LanguageCodeEnum;
  index?: number;
}

// Duration version validation error
interface DurationVersionValidationError {
  field: 'durationVersions';
  code: 'INVALID_DURATION_VERSION';
  message: string;
  index?: number;
  durationInSeconds?: number;
}

// Price validation error
interface PriceValidationError {
  field: 'prices';
  code: 'INVALID_PRICE';
  message: string;
  priceIndex?: number;
  currency?: CurrencyCodeEnum;
  value?: number;
}

Constants and Defaults

Service Constants

const SERVICE_CONSTANTS = {
  MIN_DURATION_SECONDS: 300, // 5 minutes
  MAX_DURATION_SECONDS: 86400, // 24 hours
  MAX_BREAK_SECONDS: 3600, // 1 hour
  MAX_TITLE_LENGTH: 200,
  MAX_DESCRIPTION_LENGTH: 2000,
  DEFAULT_CURRENCY: CurrencyCodeEnum.USD,
  DEFAULT_LANGUAGE: LanguageCodeEnum.en,
  MAX_PRICE: 999999.99,
  MIN_PRICE: 0,
  MAX_MEDIA_SIZE: 10485760, // 10MB
  ALLOWED_MEDIA_TYPES: ['image/jpeg', 'image/png', 'image/webp'],
  DEFAULT_DURATION_TYPE: DurationVersionTypeEnum.RANGE
} as const;

Default Service Template

const DEFAULT_SERVICE_TEMPLATE: Partial<ServiceDto> = {
  object: 'ServiceDto',
  configuration: {
    duration: {
      durationVersionType: DurationVersionTypeEnum.RANGE
    }
  },
  prepaymentPolicy: {
    isRequired: false
  },
  presentation: {
    banners: [],
    color: '#007bff'
  },
  languageVersions: [],
  durationVersions: [],
  schedules: [],
  order: null
};

Integration Patterns

Repository Interface

interface IServiceRepository {
  findById(id: string): Promise<IService | null>;
  findByTenant(tenantId: string): Promise<IService[]>;
  findPaged(tenantId: string, pagination: ServicePaginationDto): Promise<PaginatedResult<IService>>;
  create(service: IService): Promise<string>;
  update(id: string, service: Partial<IService>): Promise<void>;
  delete(id: string): Promise<number>;
  search(tenantId: string, phrase: string): Promise<IService[]>;
}

Mapper Interface

interface IServiceMapper {
  toDtoFromPersistence(service: IService): ServiceDto;
  toPersistenceFromDto(dto: ServiceDto): IService;
  toPublicDto(service: IService): PublicServiceDto;
  toRequestDto(service: IService): RequestPublicServiceDto;
}

Event Interfaces

// Service created event
interface ServiceCreatedEvent {
  type: 'SERVICE_CREATED';
  tenantId: string;
  serviceId: string;
  service: ServiceDto;
  timestamp: string;
}

// Service updated event  
interface ServiceUpdatedEvent {
  type: 'SERVICE_UPDATED';
  tenantId: string;
  serviceId: string;
  previousService: ServiceDto;
  updatedService: ServiceDto;
  timestamp: string;
}

// Service deleted event
interface ServiceDeletedEvent {
  type: 'SERVICE_DELETED';
  tenantId: string;
  serviceId: string;
  service: ServiceDto;
  timestamp: string;
}