> 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/business-profile/interface.md).

# Interface Documentation

## Overview

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

## Core Interfaces

### IBusinessProfile

The main interface for business profile entities, extending the base entity interface.

```typescript
interface IBusinessProfile extends IBase {
  published: ActiveEnum;                      // Publication status
  name: string;                              // Business name
  username?: string;                         // Unique business username
  facilities?: FacilityEnum[];               // Available facilities
  socialNetworkLinks?: ISocialNetworkLink[]; // Social media links
  bookingSettings: IBookingSettings;         // Booking configuration
  businessSettings: IBusinessSettings;       // Business configuration
  notificationSettings?: INotificationSettings; // Notification preferences
  paymentSettings?: IPaymentSettings;        // Payment configuration
  panelSettings?: IPanelSettings;           // Panel UI settings
  publicPageSettings?: IPublicPageSettings; // Public page settings
  addresses?: IBusinessAddress[];           // Business addresses
  schedules?: ISchedule[];                  // Operating schedules
  specialSchedules?: ISpecialSchedule[];    // Special schedules
  contacts?: IContact[];                    // Contact information
  gallery?: IMedia[];                       // Gallery images
  logo?: IMedia;                           // Business logo
  banners?: IMedia[];                      // Banner images
  description?: string;                     // Business description
  feature?: string;                        // Featured information
}
```

### IBusinessProfileRepository

Repository interface defining data access operations for business profiles.

```typescript
interface IBusinessProfileRepository extends IBaseRepository<IBusinessProfile> {
  findByUsername(username: string): Promise<IBusinessProfile | null>;
  findByIdentifier(identifier: string): Promise<IBusinessProfile | null>;
  updateSettings<T>(tenantId: string, settings: T, settingsType: string): Promise<void>;
}
```

## Data Transfer Objects (DTOs)

### BusinessProfileDto

Main DTO for business profile data transfer between layers.

```typescript
class BusinessProfileDto extends BaseEntityDto {
  object?: 'BusinessProfileDto';
  published?: ActiveEnum;
  name?: string;
  username?: string;
  description?: string;
  feature?: string;
  facilities?: FacilityEnum[];
  logo?: MediaDto;
  banners?: MediaDto[];
  gallery?: MediaDto[];
  addresses?: AddressDto[];
  contacts?: ContactDto[];
  schedules?: ScheduleDto[];
  specialSchedules?: SpecialScheduleDto[];
  socialNetworkLinks?: SocialNetworkLinkDto[];
  bookingSettings?: BookingSettingsClientDto;
  businessSettings?: BusinessSettingsDto;
  paymentSettings?: PaymentSettingsDto;
  panelSettings?: PanelSettingsDto;
  publicPageSettings?: PublicPageSettingsDto;
  notificationSettings?: NotificationSettingsDto;
  businessTariffPlanType?: BusinessTariffPlanType;
}
```

**Validation Rules:**

* `name`: Optional string for business identification
* `published`: Optional ActiveEnum value (YES/NO)
* `username`: Optional unique identifier
* `facilities`: Optional array of FacilityEnum values
* All nested objects have their own validation requirements

### Business Settings DTOs

#### BusinessSettingsDto

```typescript
class BusinessSettingsDto {
  timeZone?: string;                    // IANA timezone identifier
  currencies?: CurrencyEnum[];          // Supported currencies
  baseCurrency?: CurrencyEnum;          // Primary currency
  languages?: LanguageCodeEnum[];       // Supported languages
  baseLanguage?: LanguageCodeEnum;      // Primary language
  emailLanguage?: LanguageCodeEnum;     // Email communication language
  availableLanguages?: LanguageCodeEnum[]; // Available interface languages
  dateFormat?: DateFormatEnum;          // Date display format
  timeFormat?: TimeFormatEnum;          // Time display format
}
```

#### BookingSettingsClientDto

```typescript
class BookingSettingsClientDto {
  autoActionSettings?: AutoActionSettingsDto;
  earliestBooking?: number;             // Hours in advance
  latestBooking?: number;               // Hours in advance (max)
  slotSettings?: SlotSettingsDto;
  autoBookOrder?: boolean;              // Auto-confirm bookings
  paymentRequirement?: PaymentRequirementEnum;
  mandatoryAttendeeProperties?: AttendeePropertyEnum[];
}
```

#### PaymentSettingsDto

```typescript
class PaymentSettingsDto {
  stripeSettings?: StripeSettingsDto;
  paypalSettings?: PaypalSettingsDto;
  squareSettings?: SquareSettingsDto;
  defaultPaymentMethod?: PaymentMethodEnum;
  acceptedPaymentMethods?: PaymentMethodEnum[];
  currencySettings?: CurrencySettingsDto;
  taxSettings?: TaxSettingsDto;
}
```

### Location and Contact DTOs

#### AddressDto

```typescript
class AddressDto {
  _id?: string;
  street: string;
  city: string;
  state?: string;
  zipCode?: string;
  country: string;
  coordinates?: {
    latitude: number;
    longitude: number;
  };
  isPrimary?: boolean;
}
```

#### ContactDto

```typescript
class ContactDto {
  _id?: string;
  type: ContactTypeEnum;        // PHONE | EMAIL | WEBSITE | FAX
  value: string;
  label?: string;
  isPrimary?: boolean;
  isPublic?: boolean;
}
```

#### SocialNetworkLinkDto

```typescript
class SocialNetworkLinkDto {
  _id?: string;
  platform: SocialPlatformEnum; // FACEBOOK | INSTAGRAM | TWITTER | LINKEDIN
  url: string;
  username?: string;
  isActive?: boolean;
}
```

### Schedule DTOs

#### ScheduleDto

```typescript
class ScheduleDto {
  _id?: string;
  dayOfWeek: DayOfWeekEnum;     // MONDAY | TUESDAY | ... | SUNDAY
  isOpen: boolean;
  openTime?: string;            // HH:mm format
  closeTime?: string;           // HH:mm format
  breaks?: BreakDto[];
  timeZone?: string;
}
```

#### SpecialScheduleDto

```typescript
class SpecialScheduleDto {
  _id?: string;
  date: string;                 // YYYY-MM-DD format
  type: SpecialScheduleTypeEnum; // HOLIDAY | CLOSURE | EXTENDED_HOURS
  isOpen: boolean;
  openTime?: string;
  closeTime?: string;
  description?: string;
  isRecurring?: boolean;
  recurrencePattern?: RecurrencePatternDto;
}
```

## Enumerations

### ActiveEnum

```typescript
enum ActiveEnum {
  NO = 0,
  YES = 1
}
```

### FacilityEnum

```typescript
enum FacilityEnum {
  PARKING = 'PARKING',
  WIFI = 'WIFI',
  ACCESSIBILITY = 'ACCESSIBILITY',
  CARD_PAYMENT = 'CARD_PAYMENT',
  CASH_PAYMENT = 'CASH_PAYMENT',
  APPOINTMENT_ONLY = 'APPOINTMENT_ONLY',
  WALK_INS_WELCOME = 'WALK_INS_WELCOME',
  AIR_CONDITIONING = 'AIR_CONDITIONING',
  WAITING_AREA = 'WAITING_AREA',
  ONLINE_BOOKING = 'ONLINE_BOOKING'
}
```

### ContactTypeEnum

```typescript
enum ContactTypeEnum {
  PHONE = 'PHONE',
  EMAIL = 'EMAIL',
  WEBSITE = 'WEBSITE',
  FAX = 'FAX',
  MOBILE = 'MOBILE'
}
```

### SocialPlatformEnum

```typescript
enum SocialPlatformEnum {
  FACEBOOK = 'FACEBOOK',
  INSTAGRAM = 'INSTAGRAM',
  TWITTER = 'TWITTER',
  LINKEDIN = 'LINKEDIN',
  YOUTUBE = 'YOUTUBE',
  TIKTOK = 'TIKTOK'
}
```

## Use Case Interfaces

### GetBusinessProfileParams

```typescript
interface GetBusinessProfileParams {
  ctx: TenantActorContext;
}
```

### UpdateBusinessProfileParams

```typescript
interface UpdateBusinessProfileParams {
  ctx: TenantActorContext;
  profile: BusinessProfileDto;
}
```

### UpdateBusinessPaymentSettingsParams

```typescript
interface UpdateBusinessPaymentSettingsParams {
  ctx: TenantActorContext;
  settings: PaymentSettingsDto;
}
```

### Media Management Use Case Interfaces

#### UpdateClientLogoParams

```typescript
interface UpdateClientLogoParams {
  ctx: TenantActorContext;
  file: Express.Multer.File;
}
```

#### DeleteClientLogoParams

```typescript
interface DeleteClientLogoParams {
  ctx: TenantActorContext;
}
```

#### UpdateClientBannerParams

```typescript
interface UpdateClientBannerParams {
  ctx: TenantActorContext;
  bannerItemId: string;
  file: Express.Multer.File;
}
```

#### UpdateClientGalleryParams

```typescript
interface UpdateClientGalleryParams {
  ctx: TenantActorContext;
  galleryItemId: string;
  file: Express.Multer.File;
}
```

## Value Objects Interfaces

### IBookingSettings

```typescript
interface IBookingSettings {
  autoActionSettings?: IAutoActionSettings;
  earliestBooking?: number;
  latestBooking?: number;
  slotSettings?: ISlotSettings;
  autoBookOrder?: boolean;
  paymentRequirement?: PaymentRequirementEnum;
  mandatoryAttendeeProperties?: AttendeePropertyEnum[];
}
```

### IBusinessSettings

```typescript
interface IBusinessSettings {
  timeZone?: string;
  currencies?: CurrencyEnum[];
  baseCurrency?: CurrencyEnum;
  languages?: LanguageCodeEnum[];
  baseLanguage?: LanguageCodeEnum;
  emailLanguage?: LanguageCodeEnum;
  availableLanguages?: LanguageCodeEnum[];
  dateFormat?: DateFormatEnum;
  timeFormat?: TimeFormatEnum;
}
```

### IPaymentSettings

```typescript
interface IPaymentSettings {
  stripeSettings?: IStripeSettings;
  paypalSettings?: IPaypalSettings;
  squareSettings?: ISquareSettings;
  defaultPaymentMethod?: PaymentMethodEnum;
  acceptedPaymentMethods?: PaymentMethodEnum[];
  currencySettings?: ICurrencySettings;
  taxSettings?: ITaxSettings;
}
```

### IPanelSettings

```typescript
interface IPanelSettings {
  orderServiceColorMode: OrderServiceColorModeEnum;
  theme?: ThemeEnum;
  language?: LanguageCodeEnum;
  timezone?: string;
  dateFormat?: DateFormatEnum;
  timeFormat?: TimeFormatEnum;
}
```

### INotificationSettings

```typescript
interface INotificationSettings {
  reminderSettings?: IReminderSettings;
  smsNotificationSettings?: ISmsNotificationSettings;
  emailNotificationSettings?: IEmailNotificationSettings;
  pushNotificationSettings?: IPushNotificationSettings;
}
```

## Command and Query Interfaces

### Commands

#### CreateBusinessProfileCommand

```typescript
class CreateBusinessProfileCommand implements ITenantAware {
  constructor(
    public readonly tenantId: string,
    public readonly params: IBusinessProfile
  ) {}
}
```

#### UpdateBusinessProfileCommand

```typescript
class UpdateBusinessProfileCommand implements ITenantAware {
  constructor(
    public readonly tenantId: string,
    public readonly profile: BusinessProfileDto
  ) {}
}
```

#### UpdateBusinessPaymentSettingsCommand

```typescript
class UpdateBusinessPaymentSettingsCommand implements ITenantAware {
  constructor(
    public readonly tenantId: string,
    public readonly settings: PaymentSettingsDto
  ) {}
}
```

#### Media Management Commands

**UpsertClientLogoCommand**

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

**DeleteClientLogoCommand**

```typescript
class DeleteClientLogoCommand implements ITenantAware {
  constructor(
    public readonly tenantId: string
  ) {}
}
```

### Queries

#### GetBusinessProfileQuery

```typescript
class GetBusinessProfileQuery implements ITenantAware {
  constructor(
    public readonly tenantId: string
  ) {}
}
```

#### GetBusinessProfileByIdentifierQuery

```typescript
class GetBusinessProfileByIdentifierQuery implements ITenantAware {
  constructor(
    public readonly tenantId: string
  ) {}
}
```

#### GetBusinessSettingsQuery

```typescript
class GetBusinessSettingsQuery implements ITenantAware {
  constructor(
    public readonly tenantId: string
  ) {}
}
```

#### GetBusinessBookingSettingsQuery

```typescript
class GetBusinessBookingSettingsQuery implements ITenantAware {
  constructor(
    public readonly tenantId: string
  ) {}
}
```

## Cache Interfaces

### BusinessCacheKeys

```typescript
enum BusinessCacheKeys {
  GET_BUSINESS_PROFILE = 'GET_BUSINESS_PROFILE',
  GET_BUSINESS_SETTINGS = 'GET_BUSINESS_SETTINGS',
  GET_BUSINESS_BOOKING_SETTINGS = 'GET_BUSINESS_BOOKING_SETTINGS',
  GET_CLIENT_LOGO = 'GET_CLIENT_LOGO',
  GET_CLIENT_BANNERS = 'GET_CLIENT_BANNERS',
  GET_CLIENT_GALLERY = 'GET_CLIENT_GALLERY'
}
```

## Media Management Interfaces

### IMedia

```typescript
interface IMedia {
  _id: string;
  filename: string;
  originalName: string;
  mimeType: string;
  size: number;
  url: string;
  thumbnailUrl?: string;
  alt?: string;
  title?: string;
  description?: string;
  uploadedAt: Date;
  uploadedBy: string;
}
```

### MediaDto

```typescript
class MediaDto {
  _id?: string;
  filename?: string;
  originalName?: string;
  mimeType?: string;
  size?: number;
  url?: string;
  thumbnailUrl?: string;
  alt?: string;
  title?: string;
  description?: string;
  uploadedAt?: Date;
  uploadedBy?: string;
}
```

## Validation Interfaces

### ValidationResult

```typescript
class ValidationResult {
  private constructor(
    public readonly isSuccess: boolean,
    public readonly error?: string
  ) {}

  static ok(): ValidationResult;
  static fail(error: string): ValidationResult;
  isFailureResult(): boolean;
  errorValue(): string;
}
```

### Business Rule Validation Interfaces

#### IBusinessAddressValidation

```typescript
interface IBusinessAddressValidation {
  validateStreet(street: string): ValidationResult;
  validateCity(city: string): ValidationResult;
  validateCountry(country: string): ValidationResult;
  validateCoordinates(lat: number, lng: number): ValidationResult;
}
```

#### IContactValidation

```typescript
interface IContactValidation {
  validateEmail(email: string): ValidationResult;
  validatePhone(phone: string): ValidationResult;
  validateWebsite(url: string): ValidationResult;
}
```

#### ISocialNetworkLinkValidation

```typescript
interface ISocialNetworkLinkValidation {
  validatePlatform(platform: SocialPlatformEnum): ValidationResult;
  validateUrl(url: string, platform: SocialPlatformEnum): ValidationResult;
  validateUsername(username: string): ValidationResult;
}
```

## Context Interfaces

### TenantActorContext

```typescript
interface TenantActorContext {
  tenantId: string;
  actor: {
    issuerId: string;
    type: ActorTypeEnum;
    permissions: string[];
    scope: PermissionScopeEnum;
  };
  requestId?: string;
  timestamp: Date;
}
```

## Service Integration Interfaces

### IMediaService

```typescript
interface IMediaService {
  uploadImage(file: Express.Multer.File, options: UploadOptions): Promise<IMedia>;
  deleteImage(mediaId: string): Promise<void>;
  generateThumbnail(mediaId: string, dimensions: ThumbnailDimensions): Promise<string>;
}
```

### INotificationService

```typescript
interface INotificationService {
  sendBusinessProfileUpdate(profile: BusinessProfileDto): Promise<void>;
  sendSettingsChange(tenantId: string, settingsType: string): Promise<void>;
}
```

### IPaymentGatewayService

```typescript
interface IPaymentGatewayService {
  validateStripeSettings(settings: IStripeSettings): Promise<ValidationResult>;
  validatePaypalSettings(settings: IPaypalSettings): Promise<ValidationResult>;
  testConnection(settings: any, provider: PaymentMethodEnum): Promise<boolean>;
}
```

## Error Interfaces

### BusinessProfileException

```typescript
class BusinessProfileException extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly details?: any
  ) {
    super(message);
  }
}
```

### BusinessProfileErrorCodes

```typescript
enum BusinessProfileErrorCodes {
  PROFILE_NOT_FOUND = 'PROFILE_NOT_FOUND',
  INVALID_SETTINGS = 'INVALID_SETTINGS',
  USERNAME_TAKEN = 'USERNAME_TAKEN',
  MEDIA_UPLOAD_FAILED = 'MEDIA_UPLOAD_FAILED',
  INVALID_PAYMENT_SETTINGS = 'INVALID_PAYMENT_SETTINGS',
  SETTINGS_VALIDATION_FAILED = 'SETTINGS_VALIDATION_FAILED'
}
```

## Module Configuration Interfaces

### BusinessProfileModuleConfig

```typescript
interface BusinessProfileModuleConfig {
  mediaUploadLimits: {
    logoMaxSize: number;
    bannerMaxSize: number;
    galleryMaxSize: number;
  };
  supportedImageFormats: string[];
  cacheSettings: {
    profileTtl: number;
    settingsTtl: number;
  };
  validationRules: {
    requireName: boolean;
    requireAddress: boolean;
    maxSocialLinks: number;
  };
}
```

## 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. **Nested Validation**: Validate nested objects using their respective validation rules
4. **Media Handling**: Use proper interfaces for file upload and management
5. **Settings Management**: Separate concerns for different settings types
6. **Cache Management**: Use enum-defined cache keys for consistency
7. **Error Handling**: Implement domain-specific exceptions for business rules
8. **Context Propagation**: Always pass TenantActorContext for proper authorization

## Interface Evolution

When modifying interfaces:

1. Consider backward compatibility for existing clients
2. Use optional properties for new fields
3. Update validation rules accordingly
4. Document breaking changes
5. Version the API if necessary
6. Update corresponding DTOs and mappers
7. Consider impact on cache invalidation
8. Update media handling if related to file operations