> For the complete documentation index, see [llms.txt](https://docs.beeoclock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.beeoclock.com/services/service-management/interface.md).

# 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.

```typescript
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.

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

**Properties:**

* `duration`: Duration configuration options

### DurationConfigurationDto

Defines how service duration is managed.

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

**Properties:**

* `durationVersionType`: Type of duration configuration (RANGE, VARIABLE)

### PresentationDto

Visual presentation and media configuration.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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).

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
interface IServiceConfiguration {
  duration?: IDurationConfiguration;
}
```

**Properties:**

* `duration`: Duration-related configuration

### IPaymentPolicy

Payment policy value object interface.

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

**Properties:**

* Defines prepayment requirements and cancellation policies

### IPrice

Price value object interface.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
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

```typescript
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

```typescript
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

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

### Event Interfaces

```typescript
// 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;
}
```