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.

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.

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.

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

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

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

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

Location and Contact DTOs

AddressDto

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

ContactDto

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

SocialNetworkLinkDto

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

Schedule DTOs

ScheduleDto

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

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

enum ActiveEnum {
  NO = 0,
  YES = 1
}

FacilityEnum

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

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

SocialPlatformEnum

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

Use Case Interfaces

GetBusinessProfileParams

interface GetBusinessProfileParams {
  ctx: TenantActorContext;
}

UpdateBusinessProfileParams

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

UpdateBusinessPaymentSettingsParams

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

Media Management Use Case Interfaces

UpdateClientLogoParams

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

DeleteClientLogoParams

interface DeleteClientLogoParams {
  ctx: TenantActorContext;
}

UpdateClientBannerParams

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

UpdateClientGalleryParams

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

Value Objects Interfaces

IBookingSettings

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

IBusinessSettings

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

IPaymentSettings

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

IPanelSettings

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

INotificationSettings

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

Command and Query Interfaces

Commands

CreateBusinessProfileCommand

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

UpdateBusinessProfileCommand

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

UpdateBusinessPaymentSettingsCommand

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

Media Management Commands

UpsertClientLogoCommand

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

DeleteClientLogoCommand

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

Queries

GetBusinessProfileQuery

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

GetBusinessProfileByIdentifierQuery

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

GetBusinessSettingsQuery

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

GetBusinessBookingSettingsQuery

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

Cache Interfaces

BusinessCacheKeys

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

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

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

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

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

IContactValidation

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

ISocialNetworkLinkValidation

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

Context Interfaces

TenantActorContext

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

Service Integration Interfaces

IMediaService

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

INotificationService

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

IPaymentGatewayService

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

Error Interfaces

BusinessProfileException

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

BusinessProfileErrorCodes

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

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