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

# Interface Documentation

## Overview

This document provides comprehensive TypeScript interface definitions, DTOs (Data Transfer Objects), enums, and contracts for the Member Management module. These interfaces define the structure of data used throughout the member management system.

## Core Interfaces

### IMember

The core interface defining a team member entity.

```typescript
interface IMember extends IBase {
  roles: IRole[];                   // Advanced role system with permissions
  firstName?: string;               // Member's first name (optional)
  lastName?: string;                // Member's last name (optional)
  phone?: string;                   // Contact phone number (optional)
  email: string;                    // Primary email address (required, unique)
  avatar?: IMedia;                  // Profile avatar image reference
  memberContext: IMemberContext;    // Connection to account and business
  language?: LanguageCodeEnum;      // Preferred interface language
  referal?: IReferal;               // Referral information
  assignments?: IAssignments;       // Service and responsibility assignments
  role: RoleEnum;                   // Primary role (legacy, kept for compatibility)
  profileStatus?: MemberProfileStatusEnum; // Current member status
  createdAt?: string;               // Record creation timestamp
  updatedAt?: string;               // Last modification timestamp
}
```

### IMemberContext

Interface defining the relationship between a member, their account, and business client.

```typescript
interface IMemberContext extends IBase {
  account: IAccount;                // Reference to user account
  client: IClient;                  // Reference to business client
  stateHistory?: StateHistory[];    // State change tracking
  createdAt?: string;               // Context creation timestamp
  updatedAt?: string;               // Last modification timestamp
}
```

### IMemberRepository

Repository interface for member data operations.

```typescript
interface IMemberRepository extends IRepository<IMember> {
  findById(id: string): Promise<IMember | null>;
  findByEmail(email: string): Promise<IMember | null>;
  findByTenant(tenantId: string): Promise<IMember[]>;
  findPopulatedById(id: string): Promise<IMember | null>;
  updateItem(id: string, item: Partial<IMember>): Promise<IMember>;
  createItem(item: IMember): Promise<IMember>;
  all(): Promise<IMember[]>;
  // Additional repository methods...
}
```

## Data Transfer Objects (DTOs)

### MemberDto

Primary DTO for member data transfer in API operations.

```typescript
@Exclude()
export class MemberDto extends BaseEntityDto {
  @ApiProperty({ example: 'MemberDto' })
  @IsString()
  @IsOptional()
  @Expose()
  object?: 'MemberDto';

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  firstName?: string;

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  lastName?: string;

  @ApiProperty()
  @IsString()
  @Expose()
  email: string;                    // Required field

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  phone?: string;

  @ApiProperty()
  @Type(() => MediaDto)
  @IsOptional()
  @Expose()
  avatar?: MediaDto;

  @ApiProperty({
    enum: RoleEnum,
    default: RoleEnum.SPECIALIST
  })
  @IsEnum(RoleEnum)
  @IsOptional()
  @Expose()
  role?: RoleEnum;

  @ApiProperty({
    isArray: true,
    type: () => RoleDto,
    description: 'Array of roles assigned to the member. Each role can have its own set of permissions.'
  })
  @IsArray()
  @Type(() => RoleDto)
  @IsOptional()
  @Expose()
  roles?: RoleDto[];

  @ApiProperty({
    enum: MemberProfileStatusEnum,
    default: MemberProfileStatusEnum.active
  })
  @IsEnum(MemberProfileStatusEnum)
  @IsOptional()
  @Expose()
  profileStatus?: MemberProfileStatusEnum;

  @ApiProperty()
  @Type(() => AssignmentsDto)
  @IsOptional()
  @Expose()
  assignments?: AssignmentsDto;

  @ApiProperty({
    enum: LanguageCodeEnum,
    default: LanguageCodeEnum.en
  })
  @IsEnum(LanguageCodeEnum)
  @IsOptional()
  @Expose()
  language?: LanguageCodeEnum;

  @ApiProperty()
  @Type(() => ReferalDto)
  @IsOptional()
  @Expose()
  referal?: ReferalDto;
}
```

### AddMemberDto

DTO specifically for member creation operations.

```typescript
@Exclude()
export class AddMemberDto {
  @ApiProperty({ example: 'AddMemberDto' })
  @IsString()
  @IsOptional()
  @Expose()
  object?: 'AddMemberDto';

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  firstName?: string;

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  lastName?: string;

  @ApiProperty()
  @IsString()
  @IsEmail()
  @Expose()
  email: string;                    // Required for creation

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  phone?: string;

  @ApiProperty({
    enum: RoleEnum,
    default: RoleEnum.SPECIALIST
  })
  @IsEnum(RoleEnum)
  @IsOptional()
  @Expose()
  role?: RoleEnum;

  @ApiProperty({
    enum: LanguageCodeEnum,
    default: LanguageCodeEnum.en
  })
  @IsEnum(LanguageCodeEnum)
  @IsOptional()
  @Expose()
  language?: LanguageCodeEnum;

  @ApiProperty()
  @Type(() => ReferalDto)
  @IsOptional()
  @Expose()
  referal?: ReferalDto;
}
```

### MemberPaginationDto

DTO for paginated member list requests with filtering and sorting.

```typescript
@Exclude()
export class MemberPaginationDto extends PaginationDto {
  @ApiProperty({ example: 'MemberPaginationDto' })
  @IsString()
  @IsOptional()
  @Expose()
  object?: 'MemberPaginationDto';

  @ApiProperty({ required: false })
  @IsString()
  @IsOptional()
  @Expose()
  search?: string;                  // Search in name and email

  @ApiProperty({
    enum: RoleEnum,
    required: false
  })
  @IsEnum(RoleEnum)
  @IsOptional()
  @Expose()
  role?: RoleEnum;                  // Filter by role

  @ApiProperty({
    enum: MemberProfileStatusEnum,
    required: false
  })
  @IsEnum(MemberProfileStatusEnum)
  @IsOptional()
  @Expose()
  profileStatus?: MemberProfileStatusEnum; // Filter by status

  @ApiProperty({ required: false })
  @IsString()
  @IsOptional()
  @Expose()
  sortBy?: string;                  // Field to sort by

  @ApiProperty({
    enum: ['asc', 'desc'],
    required: false
  })
  @IsEnum(['asc', 'desc'])
  @IsOptional()
  @Expose()
  sortDirection?: 'asc' | 'desc';   // Sort direction
}
```

### MemberContextDto

DTO for member context operations linking accounts to business clients.

```typescript
@Exclude()
export class MemberContextDto extends BaseEntityDto {
  @ApiProperty({ example: 'MemberContextDto' })
  @IsString()
  @IsOptional()
  @Expose()
  object?: 'MemberContextDto';

  @ApiProperty()
  @Type(() => AccountDto)
  @IsOptional()
  @Expose()
  account?: AccountDto;

  @ApiProperty()
  @Type(() => ClientDto)
  @IsOptional()
  @Expose()
  client?: ClientDto;

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  status?: string;
}
```

### MemberContextPaginationDto

DTO for paginated member context requests.

```typescript
@Exclude()
export class MemberContextPaginationDto extends PaginationDto {
  @ApiProperty({ example: 'MemberContextPaginationDto' })
  @IsString()
  @IsOptional()
  @Expose()
  object?: 'MemberContextPaginationDto';

  @ApiProperty({ required: false })
  @IsOptional()
  @Expose()
  account?: ObjectId;               // Filter by account

  @ApiProperty({ required: false })
  @IsBoolean()
  @IsOptional()
  @Expose()
  populateClient?: boolean;         // Include client details

  @ApiProperty({ required: false })
  @IsBoolean()
  @IsOptional()
  @Expose()
  populateAccount?: boolean;        // Include account details
}
```

## Assignment DTOs

### AssignmentsDto

DTO for managing member service assignments.

```typescript
@Exclude()
export class AssignmentsDto {
  @ApiProperty({ example: 'AssignmentsDto' })
  @IsString()
  @IsOptional()
  @Expose()
  object?: 'AssignmentsDto';

  @ApiProperty()
  @IsOptional()
  @Type(() => AssignmentServiceDto)
  @Expose()
  service?: AssignmentServiceDto;   // Service assignment configuration
}
```

### AssignmentServiceDto

DTO for service assignment configuration.

```typescript
@Exclude()
export class AssignmentServiceDto {
  @ApiProperty({ example: 'AssignmentServiceDto' })
  @IsString()
  @IsOptional()
  @Expose()
  object?: 'AssignmentServiceDto';

  @ApiProperty()
  @IsBoolean()
  @Expose()
  full: boolean;                    // Can provide all services

  @ApiProperty({
    type: AssignedServiceDto,
    isArray: true
  })
  @Type(() => AssignedServiceDto)
  @IsArray()
  @IsOptional()
  @Expose()
  include?: AssignedServiceDto[];   // Specific service assignments
}
```

### AssignedServiceDto

DTO for individual service assignment references.

```typescript
@Exclude()
export class AssignedServiceDto {
  @ApiProperty({ example: 'AssignedServiceDto' })
  @IsString()
  @IsOptional()
  @Expose()
  object?: 'AssignedServiceDto';

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  service?: string;                 // Service ObjectId reference

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  serviceId?: string;               // Service identifier
}
```

## Value Objects

### IAssignments

Interface for member assignments and responsibilities.

```typescript
interface IAssignments {
  service: IAssignmentService;      // Service assignment configuration
}
```

### IAssignmentService

Interface for service assignment configuration.

```typescript
interface IAssignmentService {
  full: boolean;                    // Member can provide all services
  include?: IAssignedService[];     // Specific service assignments
}
```

### IAssignedService

Interface for individual service assignment.

```typescript
interface IAssignedService {
  service?: ObjectId;               // Reference to Service entity
  serviceId?: string;               // Service identifier string
}
```

### IReferal

Interface for member referral information.

```typescript
interface IReferal {
  code?: string;                    // Referral code
  source?: string;                  // Referral source
  referredBy?: string;              // Who referred this member
  referralDate?: string;            // When referral was made
  incentiveApplied?: boolean;       // Whether referral incentive was applied
}
```

### ReferalDto

DTO for referral information.

```typescript
@Exclude()
export class ReferalDto {
  @ApiProperty({ example: 'ReferalDto' })
  @IsString()
  @IsOptional()
  @Expose()
  object?: 'ReferalDto';

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  code?: string;

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  source?: string;

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  referredBy?: string;

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  referralDate?: string;

  @ApiProperty()
  @IsBoolean()
  @IsOptional()
  @Expose()
  incentiveApplied?: boolean;
}
```

## Enumerations

### RoleEnum

Enumeration defining member roles within the business.

```typescript
export enum RoleEnum {
  ADMIN = 'ADMIN',                  // Full business administration access
  SPECIALIST = 'SPECIALIST',        // Service provider with specific assignments
  RECEPTION = 'RECEPTION',          // Front desk and customer service
  MANAGER = 'MANAGER',              // Management level access
  OWNER = 'OWNER'                   // Business owner with full control
}
```

**Role Descriptions:**

* **ADMIN**: Complete business administration, user management, settings
* **SPECIALIST**: Service delivery, schedule management, customer interaction
* **RECEPTION**: Customer service, appointment booking, basic administration
* **MANAGER**: Team oversight, reporting, operational management
* **OWNER**: Ultimate authority, business configuration, financial access

### MemberProfileStatusEnum

Enumeration defining member profile status states.

```typescript
export enum MemberProfileStatusEnum {
  active = 'active',                // Member is active and available
  deleted = 'deleted',              // Member has been soft deleted
  suspended = 'suspended'           // Member is temporarily suspended
}
```

**Status Descriptions:**

* **active**: Member can access the system and provide services
* **deleted**: Member has been removed but data is preserved for audit
* **suspended**: Member access is temporarily disabled

### LanguageCodeEnum

Enumeration for supported interface languages.

```typescript
export enum LanguageCodeEnum {
  en = 'en',                        // English
  es = 'es',                        // Spanish
  fr = 'fr',                        // French
  de = 'de',                        // German
  it = 'it',                        // Italian
  pt = 'pt',                        // Portuguese
  nl = 'nl',                        // Dutch
  pl = 'pl',                        // Polish
  ru = 'ru',                        // Russian
  zh = 'zh',                        // Chinese
  ja = 'ja',                        // Japanese
  ko = 'ko',                        // Korean
  ar = 'ar',                        // Arabic
  hi = 'hi',                        // Hindi
  tr = 'tr',                        // Turkish
  sv = 'sv',                        // Swedish
  da = 'da',                        // Danish
  no = 'no',                        // Norwegian
  fi = 'fi',                        // Finnish
  cs = 'cs',                        // Czech
  hu = 'hu',                        // Hungarian
  ro = 'ro',                        // Romanian
  bg = 'bg',                        // Bulgarian
  hr = 'hr',                        // Croatian
  sk = 'sk',                        // Slovak
  sl = 'sl',                        // Slovenian
  et = 'et',                        // Estonian
  lv = 'lv',                        // Latvian
  lt = 'lt',                        // Lithuanian
  uk = 'uk',                        // Ukrainian
  el = 'gr',                        // Greek
  he = 'he',                        // Hebrew
  th = 'th',                        // Thai
  vi = 'vi',                        // Vietnamese
  id = 'id',                        // Indonesian
  ms = 'ms',                        // Malay
  tl = 'tl',                        // Filipino
  sw = 'sw',                        // Swahili
  am = 'am',                        // Amharic
  bn = 'bn',                        // Bengali
  gu = 'gu',                        // Gujarati
  kn = 'kn',                        // Kannada
  ml = 'ml',                        // Malayalam
  mr = 'mr',                        // Marathi
  ne = 'ne',                        // Nepali
  or = 'or',                        // Odia
  pa = 'pa',                        // Punjabi
  si = 'si',                        // Sinhala
  ta = 'ta',                        // Tamil
  te = 'te',                        // Telugu
  ur = 'ur',                        // Urdu
  my = 'my',                        // Myanmar
  km = 'km',                        // Khmer
  lo = 'lo',                        // Lao
  ka = 'ka',                        // Georgian
  hy = 'hy',                        // Armenian
  az = 'az',                        // Azerbaijani
  kk = 'kk',                        // Kazakh
  ky = 'ky',                        // Kyrgyz
  mn = 'mn',                        // Mongolian
  ps = 'ps',                        // Pashto
  fa = 'fa',                        // Persian
  sd = 'sd',                        // Sindhi
  uz = 'uz',                        // Uzbek
  tk = 'tk',                        // Turkmen
  tg = 'tg'                         // Tajik
}
```

## Use Case Parameter Interfaces

### AddMemberUseCaseParams

Parameters for the add new member use case.

```typescript
interface AddMemberUseCaseParams {
  ctx: TenantActorContext;          // Request context with tenant and actor
  accountId: string;                // Account ID for member association
  member: MemberDto;                // Member data for creation
}
```

### DeleteMemberUseCaseParams

Parameters for the delete member use case.

```typescript
interface DeleteMemberUseCaseParams {
  ctx: TenantActorContext;          // Request context with tenant and actor
  memberId: string;                 // ID of member to delete
}
```

### GetMemberByIdUseCaseParams

Parameters for getting a member by ID.

```typescript
interface GetMemberByIdUseCaseParams {
  ctx: TenantActorContext;          // Request context with tenant and actor
  memberId: string;                 // ID of member to retrieve
}
```

### GetPagedMembersUseCaseParams

Parameters for getting paginated member list.

```typescript
interface GetPagedMembersUseCaseParams {
  ctx: TenantActorContext;          // Request context with tenant and actor
  params: MemberPaginationDto;      // Pagination and filtering parameters
}
```

### UpdateMemberUseCaseParams

Parameters for updating member information.

```typescript
interface UpdateMemberUseCaseParams {
  ctx: TenantActorContext;          // Request context with tenant and actor
  member: MemberDto;                // Updated member data
}
```

### UpdateMemberAssignmentUseCaseParams

Parameters for updating member service assignments.

```typescript
interface UpdateMemberAssignmentUseCaseParams {
  ctx: TenantActorContext;          // Request context with tenant and actor
  memberId: string;                 // ID of member to update
  assignment: AssignmentsDto;       // New assignment configuration
}
```

## CQRS Command Interfaces

### CreateMemberCommand

Command for creating a new member.

```typescript
interface CreateMemberCommand {
  tenantId: string;                 // Business tenant ID
  member: IMember;                  // Member data to create
}
```

### UpdateMemberCommand

Command for updating member information.

```typescript
interface UpdateMemberCommand {
  tenantId: string;                 // Business tenant ID
  memberId: string;                 // ID of member to update
  updates: Partial<IMember>;        // Fields to update
}
```

### DeleteMemberCommand

Command for deleting a member.

```typescript
interface DeleteMemberCommand {
  tenantId: string;                 // Business tenant ID
  memberId: string;                 // ID of member to delete
  actorId: string;                  // ID of user performing deletion
}
```

### UpdateMemberAssignmentCommand

Command for updating member assignments.

```typescript
interface UpdateMemberAssignmentCommand {
  tenantId: string;                 // Business tenant ID
  memberId: string;                 // ID of member to update
  assignments: IAssignments;        // New assignment configuration
}
```

## CQRS Query Interfaces

### GetMemberByIdQuery

Query for retrieving a member by ID.

```typescript
interface GetMemberByIdQuery {
  tenantId: string;                 // Business tenant ID
  memberId: string;                 // ID of member to retrieve
}
```

### GetPagedMembersQuery

Query for retrieving paginated member list.

```typescript
interface GetPagedMembersQuery {
  tenantId: string;                 // Business tenant ID
  pagination: MemberPaginationDto;  // Pagination parameters
}
```

### CheckMemberHasActiveOrdersQuery

Query for checking if member has active orders.

```typescript
interface CheckMemberHasActiveOrdersQuery {
  tenantId: string;                 // Business tenant ID
  specialistId: string;             // ID of specialist/member to check
}
```

### FetchMembersByIdsQuery

Query for fetching multiple members by their IDs.

```typescript
interface FetchMembersByIdsQuery {
  tenantId: string;                 // Business tenant ID
  memberIds: string[];              // Array of member IDs to fetch
}
```

### GetOwnerMemberQuery

Query for retrieving the business owner member.

```typescript
interface GetOwnerMemberQuery {
  tenantId: string;                 // Business tenant ID
}
```

## Event Interfaces

### MemberAddedMessage

Event message for member creation.

```typescript
interface MemberAddedMessage {
  tenantId: string;                 // Business tenant ID
  member: MemberDto;                // Created member data
  createdBy: ActorDto;              // Who created the member
  timestamp: string;                // When the member was created
  invitationSent?: boolean;         // Whether invitation email was sent
}
```

### MemberUpdatedMessage

Event message for member updates.

```typescript
interface MemberUpdatedMessage {
  tenantId: string;                 // Business tenant ID
  memberId: string;                 // ID of updated member
  changes: Partial<MemberDto>;      // What changed
  updatedBy: ActorDto;              // Who made the update
  timestamp: string;                // When the update occurred
}
```

### MemberDeletedMessage

Event message for member deletion.

```typescript
interface MemberDeletedMessage {
  tenantId: string;                 // Business tenant ID
  memberId: string;                 // ID of deleted member
  memberEmail: string;              // Email of deleted member
  deletedBy: ActorDto;              // Who performed the deletion
  timestamp: string;                // When the deletion occurred
  reason?: string;                  // Optional deletion reason
}
```

### MemberAssignmentUpdatedMessage

Event message for assignment updates.

```typescript
interface MemberAssignmentUpdatedMessage {
  tenantId: string;                 // Business tenant ID
  memberId: string;                 // ID of member with updated assignments
  assignments: AssignmentsDto;      // New assignment configuration
  updatedBy: ActorDto;              // Who made the update
  timestamp: string;                // When the update occurred
}
```

## Media Management Interfaces

### MemberAvatarDto

DTO for member avatar operations.

```typescript
@Exclude()
export class MemberAvatarDto {
  @ApiProperty({ example: 'MemberAvatarDto' })
  @IsString()
  @IsOptional()
  @Expose()
  object?: 'MemberAvatarDto';

  @ApiProperty()
  @IsString()
  @Expose()
  memberId: string;                 // ID of member

  @ApiProperty()
  @Type(() => MediaDto)
  @IsOptional()
  @Expose()
  avatar?: MediaDto;                // Avatar media object

  @ApiProperty()
  @IsString()
  @IsOptional()
  @Expose()
  avatarUrl?: string;               // Direct URL to avatar image
}
```

### UpsertMemberAvatarCommand

Command for uploading/updating member avatar.

```typescript
interface UpsertMemberAvatarCommand {
  tenantId: string;                 // Business tenant ID
  memberId: string;                 // ID of member
  file: Express.Multer.File;        // Uploaded file
  uploadedBy: string;               // ID of user uploading
}
```

### DeleteMemberAvatarCommand

Command for deleting member avatar.

```typescript
interface DeleteMemberAvatarCommand {
  tenantId: string;                 // Business tenant ID
  memberId: string;                 // ID of member
  deletedBy: string;                // ID of user deleting
}
```

## Notification Interfaces

### MemberDeletedNotification

Notification interface for member deletion events.

```typescript
interface MemberDeletedNotification {
  type: 'MEMBER_DELETED';
  tenantId: string;                 // Business tenant ID
  memberId: string;                 // ID of deleted member
  memberName: string;               // Name of deleted member
  memberEmail: string;              // Email of deleted member
  deletedBy: string;                // Who performed deletion
  deletedAt: string;                // When deletion occurred
  notifyChannels: string[];         // Which channels to notify
}
```

## Exception Interfaces

### MemberNotFoundException

Exception for when a member is not found.

```typescript
interface MemberNotFoundException extends NotFoundException {
  memberId: string;                 // ID of member that wasn't found
  message: string;                  // Error message
}
```

### MemberEmailExistsException

Exception for when a member email already exists.

```typescript
interface MemberEmailExistsException extends ConflictException {
  email: string;                    // Email that already exists
  existingMemberId: string;         // ID of existing member with this email
  message: string;                  // Error message
}
```

### MemberCannotDeleteItselfException

Exception for when a member tries to delete themselves.

```typescript
interface MemberCannotDeleteItselfException extends UnprocessableEntityException {
  memberId: string;                 // ID of member attempting self-deletion
  message: string;                  // Error message
}
```

### MemberHasActiveEventsException

Exception for when trying to delete a member with active orders.

```typescript
interface MemberHasActiveEventsException extends UnprocessableEntityException {
  memberId: string;                 // ID of member with active events
  activeOrderCount: number;         // Number of active orders
  message: string;                  // Error message
}
```

### TenantTariffPlanMaxMembersReachedException

Exception for when tariff plan member limit is reached.

```typescript
interface TenantTariffPlanMaxMembersReachedException extends UnprocessableEntityException {
  tenantId: string;                 // Business tenant ID
  currentMemberCount: number;       // Current number of members
  maxAllowed: number;               // Maximum allowed by plan
  planName: string;                 // Name of current tariff plan
  message: string;                  // Error message
}
```

## Cache Key Interfaces

### MemberCacheKeys

Enumeration of cache keys used in member management.

```typescript
export enum MemberCacheKeys {
  GET_MEMBER = 'member:get',        // Individual member cache
  GET_PAGED_MEMBERS = 'member:paged', // Paginated member list cache
  MEMBER_ASSIGNMENTS = 'member:assignments', // Member assignments cache
  MEMBER_AVATAR = 'member:avatar'   // Member avatar cache
}
```

## Validation Interfaces

### MemberValidationResult

Interface for member validation results.

```typescript
interface MemberValidationResult {
  isValid: boolean;                 // Whether validation passed
  errors: string[];                 // Array of validation error messages
  warnings: string[];              // Array of validation warnings
  field?: string;                   // Specific field that failed validation
}
```

### EmailValidationResult

Interface for email validation results.

```typescript
interface EmailValidationResult {
  isValid: boolean;                 // Whether email is valid
  exists: boolean;                  // Whether email already exists
  format: boolean;                  // Whether format is correct
  domain: boolean;                  // Whether domain is valid
  message?: string;                 // Validation message
}
```

## API Response Interfaces

### MemberResponse

Standard response wrapper for member operations.

```typescript
interface MemberResponse<T = MemberDto> {
  success: boolean;                 // Operation success status
  data?: T;                         // Response data
  message?: string;                 // Response message
  error?: string;                   // Error message if failed
  timestamp: string;                // Response timestamp
}
```

### PaginatedMemberResponse

Response interface for paginated member lists.

```typescript
interface PaginatedMemberResponse {
  items: MemberDto[];               // Array of member items
  pagination: {
    page: number;                   // Current page number
    pageSize: number;               // Items per page
    total: number;                  // Total number of items
    totalPages: number;             // Total number of pages
    hasNextPage: boolean;           // Whether there's a next page
    hasPreviousPage: boolean;       // Whether there's a previous page
  };
  filters?: {
    search?: string;                // Applied search filter
    role?: RoleEnum;                // Applied role filter
    profileStatus?: MemberProfileStatusEnum; // Applied status filter
  };
  sort?: {
    field: string;                  // Sort field
    direction: 'asc' | 'desc';      // Sort direction
  };
}
```

## Integration Interfaces

### MemberServiceAssignment

Interface for member-service assignment relationships.

```typescript
interface MemberServiceAssignment {
  memberId: string;                 // ID of assigned member
  serviceId: string;                // ID of assigned service
  canProvide: boolean;              // Whether member can provide this service
  isPreferred: boolean;             // Whether member is preferred for this service
  skillLevel?: number;              // Skill level (1-5 scale)
  assignedAt: string;               // When assignment was made
  assignedBy: string;               // Who made the assignment
}
```

### MemberAvailability

Interface for member availability information.

```typescript
interface MemberAvailability {
  memberId: string;                 // ID of member
  date: string;                     // Date for availability
  timeSlots: {
    start: string;                  // Start time (ISO string)
    end: string;                    // End time (ISO string)
    available: boolean;             // Whether available in this slot
    reason?: string;                // Reason if not available
  }[];
  workingHours: {
    start: string;                  // Working day start time
    end: string;                    // Working day end time
  };
  breaks: {
    start: string;                  // Break start time
    end: string;                    // Break end time
    type: 'lunch' | 'coffee' | 'personal'; // Break type
  }[];
}
```

## Type Definitions

### Member Type Guards

Type guard functions for member-related interfaces.

```typescript
// Type guard for checking if object is a valid MemberDto
function isMemberDto(obj: any): obj is MemberDto {
  return obj && 
         typeof obj === 'object' && 
         typeof obj.email === 'string' &&
         (obj.object === undefined || obj.object === 'MemberDto');
}

// Type guard for checking if member has active status
function isActiveMember(member: IMember): boolean {
  return member.profileStatus === MemberProfileStatusEnum.active;
}

// Type guard for checking if member has specific role
function hasMemberRole(member: IMember, role: RoleEnum): boolean {
  return member.role === role || 
         (member.roles && member.roles.some(r => r.name === role));
}

// Type guard for checking if member can provide service
function canProvideService(member: IMember, serviceId: string): boolean {
  if (!member.assignments?.service) return false;
  
  if (member.assignments.service.full) return true;
  
  return member.assignments.service.include?.some(
    service => service.serviceId === serviceId || service.service === serviceId
  ) || false;
}
```

### Utility Types

Utility types for member management operations.

```typescript
// Partial member for updates
type MemberUpdate = Partial<Pick<IMember, 
  'firstName' | 'lastName' | 'phone' | 'language' | 'profileStatus' | 'assignments'
>>;

// Member creation data
type MemberCreate = Pick<IMember, 'email'> & 
  Partial<Pick<IMember, 'firstName' | 'lastName' | 'phone' | 'role' | 'language'>>;

// Member search criteria
type MemberSearchCriteria = {
  email?: string;
  name?: string;
  role?: RoleEnum;
  profileStatus?: MemberProfileStatusEnum;
  hasAssignments?: boolean;
};

// Member summary for lists
type MemberSummary = Pick<IMember, 
  '_id' | 'firstName' | 'lastName' | 'email' | 'role' | 'profileStatus' | 'createdAt'
>;
```

## Constants

### Default Values

```typescript
export const MEMBER_DEFAULTS = {
  role: RoleEnum.SPECIALIST,
  profileStatus: MemberProfileStatusEnum.active,
  language: LanguageCodeEnum.en,
  assignments: {
    service: {
      full: false,
      include: []
    }
  }
} as const;
```

### Validation Constraints

```typescript
export const MEMBER_CONSTRAINTS = {
  firstName: {
    minLength: 1,
    maxLength: 50
  },
  lastName: {
    minLength: 1,
    maxLength: 50
  },
  email: {
    maxLength: 100,
    pattern: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/
  },
  phone: {
    minLength: 10,
    maxLength: 20,
    pattern: /^[\+]?[1-9][\d]{0,15}$/
  }
} as const;
```

***

This interface documentation provides a comprehensive reference for all TypeScript interfaces, DTOs, enums, and contracts used in the Member Management module. These definitions ensure type safety and clear contracts between different layers of the application.

For implementation details and business logic, refer to the [Use Case Documentation](/services/member-management/usecase.md) and [API Documentation](/services/member-management/api.md).