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.

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.

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

Data Transfer Objects (DTOs)

AbsenceDto

Main DTO for absence data transfer between layers.

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.

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.

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

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

GetAbsenceUseCaseParams

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

GetPagedAbsencesUseCaseParams

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

UpdateAbsenceUseCaseParams

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

DeleteAbsenceUseCaseParams

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

Domain Value Objects

AbsenceSearchCriteria

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

ISlot

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

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

Command and Query Interfaces

Commands

CreateAbsenceCommand

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

UpdateAbsenceCommand

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

DeleteAbsenceCommand

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

Queries

GetAbsenceByIdQuery

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

GetPagedAbsencesQuery

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

Message Interfaces

Event Messages

AbsenceCreatedMessage

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

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

AbsenceUpdatedMessage

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

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

AbsenceDeletedMessage

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

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

WebSocket Messages

AbsenceCreatedWsMessage

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

AbsenceUpdatedWsMessage

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

AbsenceDeletedWsMessage

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

Cache Interfaces

AbsenceCacheKeys

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

Repository Filter Interfaces

GetBusySlotsWithFilterParams

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

Context Interfaces

TenantActorContext

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

Validation and Error Interfaces

AbsenceDomainError

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

AbsenceErrorCode

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

Integration Interfaces

IMessageQueueService

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

IWebSocketGateway

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