> 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/absence-management/interface.md).

# Interface Documentation

## Overview

This document describes the interfaces, types, and contracts used in the Absence Management module. These interfaces define the structure of data objects, repository contracts, and service interfaces used throughout the system.

## Core Interfaces

### IAbsence

The main interface for absence entities, extending the base entity interface.

```typescript
interface IAbsence extends IBase {
  note?: string;                    // Optional description or notes
  start: string;                    // Start date/time (ISO string)
  end: string;                      // End date/time (ISO string)
  entireBusiness?: boolean;         // Affects entire business if true
  memberIds?: string[];             // Array of member ID strings
  members?: IMember[];              // Populated member objects
  locations?: ILocation[];          // Affected locations
  type: AbsenceTypeEnum;           // Type of absence
  timeZone: string;                // Timezone identifier
  meta?: IMeta;                    // Metadata information
}
```

### IAbsenceRepository

Repository interface defining data access operations for absences.

```typescript
interface IAbsenceRepository extends IBaseRepository<IAbsence> {
  getAbsencesWithFilter(params: GetBusySlotsWithFilterParams): Promise<ISlot[]>;
}
```

## Data Transfer Objects (DTOs)

### AbsenceDto

Main DTO for absence data transfer between layers.

```typescript
class AbsenceDto extends BaseEntityDto {
  object?: 'AbsenceDto';
  note?: string;
  start: string;
  end: string;
  type?: AbsenceTypeEnum;
  entireBusiness?: boolean;
  members?: MemberDto[];
  locations?: LocationDto[];
  timeZone?: string;
  meta?: MetaDto;
}
```

**Validation Rules:**

* `start`: Required string (ISO date format)
* `end`: Required string (ISO date format)
* `type`: Optional enum value (vacation, holiday, break)
* `entireBusiness`: Optional boolean
* `members`: Optional array of MemberDto objects
* `locations`: Optional array of LocationDto objects
* `timeZone`: Optional string
* `note`: Optional string

### AbsencePaginationDto

DTO for pagination parameters when querying absences.

```typescript
class AbsencePaginationDto extends PaginationRequestDto {
  // Inherits pagination fields from base class
  // Additional absence-specific filtering can be added here
}
```

## Enumerations

### AbsenceTypeEnum

Defines the types of absences supported by the system.

```typescript
enum AbsenceTypeEnum {
  vacation = 'vacation',
  holiday = 'holiday',
  break = 'break'
}
```

**Values:**

* `vacation`: Personal time off
* `holiday`: Business holidays
* `break`: Short breaks or temporary unavailability

## Use Case Interfaces

### CreateAbsenceUseCaseParams

```typescript
interface CreateAbsenceUseCaseParams {
  ctx: TenantActorContext;
  absence: AbsenceDto;
}
```

### GetAbsenceUseCaseParams

```typescript
interface GetAbsenceUseCaseParams {
  ctx: TenantActorContext;
  absenceId: string;
}
```

### GetPagedAbsencesUseCaseParams

```typescript
interface GetPagedAbsencesUseCaseParams {
  ctx: TenantActorContext;
  pagination: AbsencePaginationDto;
}
```

### UpdateAbsenceUseCaseParams

```typescript
interface UpdateAbsenceUseCaseParams {
  ctx: TenantActorContext;
  absenceId: string;
  update: AbsenceDto;
}
```

### DeleteAbsenceUseCaseParams

```typescript
interface DeleteAbsenceUseCaseParams {
  ctx: TenantActorContext;
  absenceId: string;
}
```

## Domain Value Objects

### AbsenceSearchCriteria

```typescript
interface AbsenceSearchCriteria {
  memberIds?: string[];
  startDate?: string;
  endDate?: string;
  types?: AbsenceTypeEnum[];
  entireBusinessOnly?: boolean;
}
```

### ISlot

Interface representing a time slot, used in absence conflict detection.

```typescript
interface ISlot {
  start: string;
  end: string;
  memberId?: string;
  absenceId?: string;
  type?: string;
}
```

## Command and Query Interfaces

### Commands

#### CreateAbsenceCommand

```typescript
class CreateAbsenceCommand implements ITenantAware {
  constructor(
    public readonly tenantId: string,
    public readonly absenceDto: AbsenceDto
  ) {}
}
```

#### UpdateAbsenceCommand

```typescript
class UpdateAbsenceCommand implements ITenantAware {
  constructor(
    public readonly tenantId: string,
    public readonly absence: AbsenceDto
  ) {}
}
```

#### DeleteAbsenceCommand

```typescript
class DeleteAbsenceCommand {
  constructor(
    public readonly tenantId: string,
    public readonly absenceId: string
  ) {}
}
```

### Queries

#### GetAbsenceByIdQuery

```typescript
class GetAbsenceByIdQuery implements ITenantAware {
  constructor(
    public readonly tenantId: string,
    public readonly absenceId: string
  ) {}
}
```

#### GetPagedAbsencesQuery

```typescript
class GetPagedAbsencesQuery implements ITenantAware {
  constructor(
    public readonly tenantId: string,
    public readonly criteria: AbsenceSearchCriteria,
    public readonly pagination: PaginationRequestDto
  ) {}
}
```

## Message Interfaces

### Event Messages

#### AbsenceCreatedMessage

```typescript
interface AbsenceCreatedMessagePayload {
  tenantId: string;
  absence: AbsenceDto;
}

class AbsenceCreatedMessage extends BaseMessage<AbsenceCreatedMessagePayload> {
  constructor(params: AbsenceCreatedMessagePayload) {
    super(Queue.notificationQueue, 'absence-created', params);
  }
}
```

#### AbsenceUpdatedMessage

```typescript
interface AbsenceUpdatedMessagePayload {
  tenantId: string;
  absence: AbsenceDto;
}

class AbsenceUpdatedMessage extends BaseMessage<AbsenceUpdatedMessagePayload> {
  constructor(params: AbsenceUpdatedMessagePayload) {
    super(Queue.notificationQueue, 'absence-updated', params);
  }
}
```

#### AbsenceDeletedMessage

```typescript
interface AbsenceDeletedMessagePayload {
  tenantId: string;
  absence: AbsenceDto;
}

class AbsenceDeletedMessage extends BaseMessage<AbsenceDeletedMessagePayload> {
  constructor(params: AbsenceDeletedMessagePayload) {
    super(Queue.notificationQueue, 'absence-deleted', params);
  }
}
```

### WebSocket Messages

#### AbsenceCreatedWsMessage

```typescript
interface AbsenceCreatedWsMessage {
  type: 'absence-created';
  payload: { absence: AbsenceDto };
}
```

#### AbsenceUpdatedWsMessage

```typescript
interface AbsenceUpdatedWsMessage {
  type: 'absence-updated';
  payload: { absence: AbsenceDto };
}
```

#### AbsenceDeletedWsMessage

```typescript
interface AbsenceDeletedWsMessage {
  type: 'absence-deleted';
  payload: { absence: AbsenceDto };
}
```

## Cache Interfaces

### AbsenceCacheKeys

```typescript
enum AbsenceCacheKeys {
  GET_ABSENCE = 'GET_ABSENCE',
  GET_PAGED_ABSENCES = 'GET_PAGED_ABSENCES'
}
```

## Repository Filter Interfaces

### GetBusySlotsWithFilterParams

```typescript
interface GetBusySlotsWithFilterParams {
  specialistIds?: string[];
  start: string;
  end: string;
  state?: string;
}
```

## Context Interfaces

### TenantActorContext

```typescript
interface TenantActorContext {
  tenantId: string;
  actor: {
    issuerId: string;
    type: ActorTypeEnum;
    // Additional actor properties
  };
}
```

## Validation and Error Interfaces

### AbsenceDomainError

```typescript
class AbsenceDomainError extends Error {
  constructor(
    public readonly code: AbsenceErrorCode,
    message: string,
    public readonly fields: string[]
  ) {
    super(message);
  }
}
```

### AbsenceErrorCode

```typescript
enum AbsenceErrorCode {
  absenceNotFound = 'ABSENCE_NOT_FOUND',
  invalidDateRange = 'INVALID_DATE_RANGE',
  invalidAssignment = 'INVALID_ASSIGNMENT',
  permissionDenied = 'PERMISSION_DENIED'
}
```

## Integration Interfaces

### IMessageQueueService

```typescript
interface IMessageQueueService {
  emitEvent<T>(event: BaseMessage<T>): Promise<void>;
}
```

### IWebSocketGateway

```typescript
interface IWebSocketGateway {
  sendMessage<T>(tenantId: string, message: T): void;
}
```

## Usage Guidelines

1. **DTO Validation**: Always validate DTOs using class-validator decorators
2. **Type Safety**: Use TypeScript interfaces to ensure type safety across layers
3. **Error Handling**: Implement proper error handling using domain-specific exceptions
4. **Message Contracts**: Maintain consistent message interfaces for event-driven communication
5. **Cache Keys**: Use enum-defined cache keys for consistent cache management
6. **Context Propagation**: Always pass TenantActorContext for proper authorization and tenancy

## Interface Evolution

When modifying interfaces:

1. Consider backward compatibility
2. Use optional properties for new fields
3. Update validation rules accordingly
4. Document breaking changes
5. Version the API if necessary