Interface Documentation

Overview

This document provides comprehensive documentation of all TypeScript interfaces, DTOs, enums, and type definitions used in the Customer Management module. These interfaces ensure type safety, establish clear contracts between layers, and facilitate integration with other modules in the Bee O'clock ecosystem.

Core Interfaces

Customer Entity Interface

interface ICustomer extends IBase {
  firstName?: string;           // Customer first name
  lastName?: string;            // Customer last name  
  phone?: string;              // Normalized phone number (numbers only)
  email?: string;              // Validated email address
  note?: string;               // Internal business notes
  customerType?: CustomerTypeEnum; // Customer classification type
  createdAt?: string;          // Creation timestamp (ISO string)
  updatedAt?: string;          // Last update timestamp (ISO string)
}

Base Entity Interface

interface IBase {
  _id?: string;                // MongoDB ObjectId as string
  state?: string;              // Entity state (active, inactive, deleted)
  stateHistory?: IStateHistoryEntry[]; // State change audit trail
  _version?: string;           // Optimistic locking version
}

Data Transfer Objects (DTOs)

CustomerDto

Primary DTO for customer data transfer across API boundaries.

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

  @ApiProperty({ example: 'John' })
  @IsString()
  @IsOptional()
  @Expose()
  firstName?: string;

  @ApiProperty({ example: 'Smith' })
  @IsString()
  @IsOptional()
  @Expose()
  lastName?: string;

  @ApiProperty({ example: '+0000000000000' })
  @IsString()
  @IsOptional()
  @Expose()
  phone?: string;

  @ApiProperty({ example: '[email protected]' })
  @IsString()
  @IsOptional()
  @Expose()
  email?: string;

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

  @ApiProperty({
    enum: CustomerTypeEnum,
    default: CustomerTypeEnum.regular
  })
  @IsEnum(CustomerTypeEnum)
  @IsOptional()
  @Expose()
  customerType?: CustomerTypeEnum;
}

CustomerPaginationDto

DTO for customer pagination parameters.

@Exclude()
export class CustomerPaginationDto extends PaginationDto {
  
  @ApiPropertyOptional({ example: 'john' })
  @IsString()
  @IsOptional()
  @Expose()
  search?: string;

  @ApiPropertyOptional({ 
    enum: CustomerTypeEnum,
    description: 'Filter customers by type'
  })
  @IsEnum(CustomerTypeEnum)
  @IsOptional()
  @Expose()
  customerType?: CustomerTypeEnum;

  @ApiPropertyOptional({ 
    example: 'firstName',
    description: 'Field to sort by'
  })
  @IsString()
  @IsOptional()
  @Expose()
  sortBy?: string;

  @ApiPropertyOptional({ 
    enum: ['asc', 'desc'],
    example: 'asc',
    description: 'Sort direction'
  })
  @IsEnum(['asc', 'desc'])
  @IsOptional()
  @Expose()
  sortDirection?: 'asc' | 'desc';
}

CustomerFilterDto

DTO for advanced customer filtering options.

@Exclude()
export class CustomerFilterDto {
  
  @ApiPropertyOptional()
  @IsString()
  @IsOptional()
  @Expose()
  search?: string;

  @ApiPropertyOptional({ enum: CustomerTypeEnum })
  @IsEnum(CustomerTypeEnum)
  @IsOptional()
  @Expose()
  customerType?: CustomerTypeEnum;

  @ApiPropertyOptional()
  @IsDateString()
  @IsOptional()
  @Expose()
  createdAfter?: string;

  @ApiPropertyOptional()
  @IsDateString()
  @IsOptional()
  @Expose()
  createdBefore?: string;

  @ApiPropertyOptional()
  @IsBoolean()
  @IsOptional()
  @Expose()
  hasEmail?: boolean;

  @ApiPropertyOptional()
  @IsBoolean()
  @IsOptional()
  @Expose()
  hasPhone?: boolean;
}

Order Integration DTOs

AttendantDto

DTO representing a customer as an attendee in order services.

@Exclude()
export class AttendantDto {

  @ApiProperty({ example: 'AttendantDto' })
  @IsString()
  @IsOptional()
  @Expose()
  object?: 'AttendantDto';

  @ApiProperty({ type: () => CustomerDto })
  @Type(() => CustomerDto)
  @IsOptional()
  @Expose()
  customer?: CustomerDto;

  @ApiProperty({ 
    description: 'Indicates if this is the first time the attendant is visiting the business' 
  })
  @IsOptional()
  @IsBoolean()
  @Expose()
  firstTime?: boolean;
}

PublicAttendantDto

DTO for customer information in public order creation (client-facing).

@Exclude()
export class PublicAttendantDto {

  @ApiPropertyOptional()
  @IsString()
  @IsOptional()
  @Expose()
  @Transform(from_object_id)
  _id?: string;

  @ApiPropertyOptional({ example: 'John' })
  @IsString()
  @IsOptional()
  @Expose()
  firstName?: string;

  @ApiPropertyOptional({ example: 'Smith' })
  @IsString()
  @IsOptional()
  @Expose()
  lastName?: string;

  @ApiPropertyOptional({ example: '[phone]' })
  @IsString()
  @IsOptional()
  @Expose()
  @IsPhone({
    message: 'Invalid phone number format'
  })
  phone?: string;

  @ApiPropertyOptional({ example: '[email protected]' })
  @IsString()
  @IsOptional()
  @Expose()
  @IsEmail({
    message: 'Invalid email format'
  })
  email?: string;
}

Enumerations

CustomerTypeEnum

Defines different types of customers in the system.

export enum CustomerTypeEnum {
  regular = 'regular',           // Regular registered customer with full profile
  unregistered = 'unregistered', // Customer without full registration
  new = 'new',                   // First-time customer
  anonymous = 'anonymous'        // Anonymous customer (public orders)
}

CustomerStateEnum

Defines possible states for customer entities.

export enum CustomerStateEnum {
  active = 'active',           // Customer is active and can book services
  inactive = 'inactive',       // Customer is temporarily inactive
  suspended = 'suspended',     // Customer is suspended due to policy violation
  deleted = 'deleted'          // Customer is soft-deleted
}

Use Case Interfaces

Customer Use Case Parameters

// Create Customer
export interface CreateCustomerUseCaseParams {
  ctx: TenantActorContext;
  customer: CustomerDto;
}

// Get Customer
export interface GetCustomerUseCaseParams {
  ctx: TenantActorContext;
  customerId: string;
}

// Update Customer
export interface UpdateCustomerUseCaseParams {
  ctx: TenantActorContext;
  customerId: string;
  update: CustomerDto;
}

// Delete Customer
export interface DeleteCustomerUseCaseParams {
  ctx: TenantActorContext;
  customerId: string;
}

// Get Paged Customers
export interface GetPagedCustomersUseCaseParams {
  ctx: TenantActorContext;
  pagination: CustomerPaginationDto;
}

Customer Validation Parameters

export interface CustomerValidationParams {
  tenantId: string;
  customer: CustomerDto;
  validationFunction: (dto: CustomerDto) => boolean;
  errorMessage: string;
}

Domain Value Objects

Customer Contact Information

interface ICustomerContact {
  email?: string;              // Validated email address
  phone?: string;              // Normalized phone number
  preferredContactMethod?: ContactMethodEnum; // Preferred communication method
  allowMarketing?: boolean;    // Marketing communication consent
}

Customer Preferences

interface ICustomerPreferences {
  language?: LanguageCodeEnum;     // Preferred language
  timezone?: string;               // Preferred timezone
  communicationPreferences?: {
    email?: boolean;              // Email notifications enabled
    sms?: boolean;               // SMS notifications enabled
    push?: boolean;              // Push notifications enabled
  };
  appointmentPreferences?: {
    preferredTimeSlots?: string[]; // Preferred appointment times
    reminderPreference?: number;   // Reminder time in minutes
  };
}

Command and Query Interfaces

Command Interfaces

// Add Regular Customer Command
export interface IAddRegularCustomerCommand extends ITenantAware {
  tenantId: string;
  customer: CustomerDto;
}

// Update Customer Command
export interface IUpdateCustomerCommand extends ITenantAware {
  tenantId: string;
  customerId: string;
  customer: CustomerDto;
}

// Delete Customer Command
export interface IDeleteCustomerCommand extends ITenantAware {
  tenantId: string;
  customerId: string;
}

// Add Attendees Command
export interface IAddAttendeesCommand extends ITenantAware {
  tenantId: string;
  attendees: AttendantDto[];
}

// Add Public Attendees Command
export interface IAddPublicAttendeesCommand extends ITenantAware {
  tenantId: string;
  attendees: PublicAttendantDto[];
}

Query Interfaces

// Get Customer By ID Query
export interface IGetCustomerByIdQuery extends ITenantAware {
  tenantId: string;
  customerId: string;
}

// Get Paged Customers Query
export interface IGetPagedCustomersQuery extends ITenantAware {
  tenantId: string;
  pagination: CustomerPaginationDto;
}

// Is Customer Exist Query
export interface IIsCustomerExistQuery extends ITenantAware {
  tenantId: string;
  email?: string;
  phone?: string;
}

Message Interfaces

Customer Event Messages

// Customer Added Message
export interface CustomerAddedMessagePayload {
  tenantId: string;
  customer: CustomerDto;
  createdBy: ActorDto;
  timestamp: string;
}

export class CustomerAddedMessage extends BaseMessage<CustomerAddedMessagePayload> {
  constructor(params: CustomerAddedMessagePayload) {
    super(Queue.customerQueue, 'customer-added', params);
  }
}

// Customer Updated Message
export interface CustomerUpdatedMessagePayload {
  tenantId: string;
  customerId: string;
  customer: CustomerDto;
  updatedBy: ActorDto;
  changedFields: string[];
  timestamp: string;
}

export class CustomerUpdatedMessage extends BaseMessage<CustomerUpdatedMessagePayload> {
  constructor(params: CustomerUpdatedMessagePayload) {
    super(Queue.customerQueue, 'customer-updated', params);
  }
}

// Customer Deleted Message
export interface CustomerDeletedMessagePayload {
  tenantId: string;
  customerId: string;
  deletedBy: ActorDto;
  timestamp: string;
}

export class CustomerDeletedMessage extends BaseMessage<CustomerDeletedMessagePayload> {
  constructor(params: CustomerDeletedMessagePayload) {
    super(Queue.customerQueue, 'customer-deleted', params);
  }
}

Cache Interfaces

Cache Key Definitions

export enum CustomerCacheKeys {
  GET_CUSTOMER = 'customer:get',
  GET_PAGED_CUSTOMERS = 'customer:paged',
  CUSTOMER_SEARCH = 'customer:search',
  CUSTOMER_VALIDATION = 'customer:validation'
}

Cache Strategy Interfaces

export interface ICustomerCacheStrategy {
  getCustomerCacheKey(tenantId: string, customerId: string): string;
  getPagedCustomersCacheKey(tenantId: string, params: CustomerPaginationDto): string;
  getSearchCacheKey(tenantId: string, searchTerm: string): string;
  invalidateCustomerCache(tenantId: string, customerId: string): Promise<void>;
  invalidatePagedCache(tenantId: string): Promise<void>;
}

Repository Filter Interfaces

Customer Repository Filters

export interface ICustomerRepositoryFilter {
  tenantId: string;
  search?: string;
  customerType?: CustomerTypeEnum;
  state?: CustomerStateEnum;
  hasEmail?: boolean;
  hasPhone?: boolean;
  createdAfter?: Date;
  createdBefore?: Date;
  sortBy?: string;
  sortDirection?: 'asc' | 'desc';
  limit?: number;
  offset?: number;
}

Customer Search Criteria

export interface ICustomerSearchCriteria {
  tenantId: string;
  query: string;
  fields: CustomerSearchField[];
  fuzzyMatch?: boolean;
  limit?: number;
}

export enum CustomerSearchField {
  FIRST_NAME = 'firstName',
  LAST_NAME = 'lastName',
  EMAIL = 'email',
  PHONE = 'phone',
  FULL_NAME = 'fullName'
}

Context Interfaces

Tenant Actor Context

export interface TenantActorContext {
  tenantId: string;
  actor: ActorDto;
}

export interface ActorDto {
  issuerId: string;
  issuerType: IssuerTypeEnum;
  roles: string[];
  permissions?: string[];
}

Customer Operation Context

export interface CustomerOperationContext extends TenantActorContext {
  operationType: CustomerOperationType;
  requestId: string;
  timestamp: string;
  metadata?: Record<string, any>;
}

export enum CustomerOperationType {
  CREATE = 'create',
  READ = 'read',
  UPDATE = 'update',
  DELETE = 'delete',
  SEARCH = 'search'
}

Validation and Error Interfaces

Customer Validation Result

export interface ICustomerValidationResult {
  isValid: boolean;
  errors: CustomerValidationError[];
  warnings?: CustomerValidationWarning[];
}

export interface CustomerValidationError {
  field: string;
  message: string;
  code: CustomerValidationErrorCode;
  value?: any;
}

export interface CustomerValidationWarning {
  field: string;
  message: string;
  suggestion?: string;
}

export enum CustomerValidationErrorCode {
  REQUIRED_FIELD_MISSING = 'REQUIRED_FIELD_MISSING',
  INVALID_EMAIL_FORMAT = 'INVALID_EMAIL_FORMAT',
  INVALID_PHONE_FORMAT = 'INVALID_PHONE_FORMAT',
  DUPLICATE_CUSTOMER = 'DUPLICATE_CUSTOMER',
  FIELD_TOO_LONG = 'FIELD_TOO_LONG',
  INVALID_CUSTOMER_TYPE = 'INVALID_CUSTOMER_TYPE'
}

Exception Interfaces

export interface ICustomerException {
  name: string;
  message: string;
  code: string;
  details?: Record<string, any>;
  timestamp: string;
}

// Customer Not Found Exception
export interface ICustomerNotFoundException extends ICustomerException {
  customerId: string;
  tenantId: string;
}

// Customer Creation Exception
export interface ICustomerCreationException extends ICustomerException {
  validationErrors: CustomerValidationError[];
  customerData: Partial<CustomerDto>;
}

// Customer Already Exists Exception
export interface ICustomerAlreadyExistsException extends ICustomerException {
  existingCustomerId: string;
  conflictingField: string;
  conflictingValue: string;
}

Integration Interfaces

Order Integration

export interface IOrderCustomerInfo {
  customer: CustomerDto;       // Primary customer (payer)
  attendees: AttendantDto[];   // Service attendees
  isFirstTimeCustomer: boolean;
  orderHistory?: {
    totalOrders: number;
    lastOrderDate?: string;
    averageOrderValue?: number;
  };
}

Payment Integration

export interface IPaymentCustomerInfo {
  payer: CustomerDto;          // Customer making payment
  billingInfo?: {
    address?: AddressDto;
    paymentMethodPreference?: PaymentMethodEnum;
  };
  paymentHistory?: {
    totalPayments: number;
    lastPaymentDate?: string;
    preferredMethod?: PaymentMethodEnum;
  };
}

Notification Integration

export interface ICustomerNotificationProfile {
  customer: CustomerDto;
  preferences: {
    email: boolean;
    sms: boolean;
    push: boolean;
  };
  contactMethods: {
    email?: string;
    phone?: string;
    deviceTokens?: string[];
  };
  language: LanguageCodeEnum;
  timezone: string;
}

Mapper Interfaces

Customer Mapping Contracts

export interface ICustomerMapper {
  toDto(entity: ICustomer): CustomerDto;
  toDtoArray(entities: ICustomer[]): CustomerDto[];
  toPersistence(dto: CustomerDto): ICustomer;
  toPersistenceFromDto(dto: CustomerDto): ICustomer;
  toDomain(persistence: ICustomer): Customer;
  fromDomain(domain: Customer): ICustomer;
}

export interface IAttendantMapper {
  toDto(entity: IAttendant): AttendantDto;
  toDtoArray(entities: IAttendant[]): AttendantDto[];
  toPersistence(dto: AttendantDto): IAttendant;
  fromCustomerDto(customer: CustomerDto, firstTime: boolean): AttendantDto;
}

Type Utilities

Customer Type Guards

export const isCustomerDto = (obj: any): obj is CustomerDto => {
  return obj && typeof obj === 'object' && obj.object === 'CustomerDto';
};

export const isAttendantDto = (obj: any): obj is AttendantDto => {
  return obj && typeof obj === 'object' && obj.object === 'AttendantDto';
};

export const isPublicAttendantDto = (obj: any): obj is PublicAttendantDto => {
  return obj && typeof obj === 'object' && 
         (obj.firstName || obj.lastName || obj.email || obj.phone);
};

Customer Utility Types

// Partial customer for updates
export type CustomerUpdate = Partial<Omit<CustomerDto, '_id' | 'object' | 'createdAt' | '_version'>>;

// Customer creation payload
export type CustomerCreation = Omit<CustomerDto, '_id' | 'createdAt' | 'updatedAt' | '_version' | 'stateHistory'>;

// Customer summary for lists
export type CustomerSummary = Pick<CustomerDto, '_id' | 'firstName' | 'lastName' | 'email' | 'customerType'>;

// Customer search result
export type CustomerSearchResult = CustomerSummary & {
  relevanceScore: number;
  matchedFields: string[];
};

Configuration Interfaces

Customer Module Configuration

export interface ICustomerModuleConfig {
  validation: {
    emailValidation: boolean;
    phoneValidation: boolean;
    duplicateCheck: boolean;
    mandatoryFields: (keyof CustomerDto)[];
  };
  pagination: {
    defaultLimit: number;
    maxLimit: number;
  };
  cache: {
    enabled: boolean;
    ttl: {
      customer: number;
      pagedResults: number;
      searchResults: number;
    };
  };
  security: {
    auditLogging: boolean;
    dataEncryption: boolean;
    accessLogging: boolean;
  };
}

Usage Guidelines

DTO Validation

1. Always use class-validator decorators for automatic validation

2. Apply @Expose() decorators for proper serialization control

3. Use @Type() decorators for nested object transformation

4. Implement proper error handling for validation failures

Type Safety

1. Use TypeScript interfaces for compile-time type checking

2. Implement type guards for runtime type validation

3. Apply generic constraints for reusable type definitions

4. Use discriminated unions for type-safe polymorphism

Error Handling

1. Implement domain-specific exceptions with clear error codes

2. Provide detailed validation results with field-level errors

3. Use Result types for operation outcomes

4. Maintain error message consistency across the module

Message Contracts

1. Define clear event payloads for inter-service communication

2. Version message interfaces for backward compatibility

3. Include correlation IDs for request tracing

4. Implement idempotent message processing

Cache Keys

1. Use enum-defined cache keys for consistency

2. Include tenant context in cache key generation

3. Implement cache invalidation strategies for data consistency

4. Consider cache TTL values based on data volatility

Context Propagation

1. Always pass TenantActorContext for proper authorization

2. Include operation metadata for auditing and debugging

3. Maintain request correlation across service boundaries

4. Implement proper context validation

Interface Evolution

When modifying interfaces:

1. Consider backward compatibility for existing consumers

2. Use optional properties for new fields to maintain compatibility

3. Increment version numbers for breaking changes

4. Update validation rules consistently across DTOs

5. Document migration paths for interface changes

6. Test interface changes thoroughly across all integration points

Performance Considerations

1. Use selective field projection in repository interfaces

2. Implement efficient search interfaces with proper indexing

3. Consider pagination interfaces for large result sets

4. Design cache-friendly interfaces with appropriate granularity

5. Optimize serialization through proper DTO design

Security Considerations

1. Never expose sensitive data in public interfaces

2. Implement proper input validation in all DTOs

3. Use secure context propagation for authorization

4. Audit interface access for compliance requirements

5. Encrypt sensitive fields in persistence interfaces

---

Summary

The Customer Management module interfaces provide a comprehensive type-safe foundation for customer operations within the Bee O'clock ecosystem. Key aspects include:

• Strongly Typed DTOs: Comprehensive data transfer objects with validation

• Domain Interfaces: Clear contracts for business logic and data persistence

• Integration Support: Well-defined interfaces for order and payment integration

• Event-Driven Architecture: Message interfaces for asynchronous communication

• Error Handling: Structured exception and validation interfaces

• Performance Optimization: Cache and search interfaces for efficient operations

• Security Compliance: Secure context and validation interfaces

These interfaces ensure consistency, maintainability, and reliability across the customer management domain while supporting complex business scenarios and integration requirements.