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

# Interface Documentation

## Overview

This document provides comprehensive details on TypeScript interfaces, DTOs, enums, and contracts used throughout the Product Management module. All interfaces are derived from the actual codebase and reflect the current implementation.

## Table of Contents

1. [Core Interfaces](#core-interfaces)
2. [Data Transfer Objects (DTOs)](#data-transfer-objects-dtos)
3. [Domain Value Objects](#domain-value-objects)
4. [Repository Interfaces](#repository-interfaces)
5. [Use Case Interfaces](#use-case-interfaces)
6. [Enums and Constants](#enums-and-constants)
7. [Media and File Interfaces](#media-and-file-interfaces)
8. [Validation Constraints](#validation-constraints)

## Core Interfaces

### IProduct

**File:** `common/module/product/product/domain/persistance/IProduct.ts`

Core product entity interface extending base entity functionality.

```typescript
export interface IProduct extends IBase {
  sku: string;                               // Unique product identifier
  languageVersions: ILanguageVersion[];      // Multi-language content
  price?: IProductPrice;                     // Product pricing information
  tags?: string[];                           // Product categorization tags
  images?: IMedia[];                         // Associated product images
  order?: number;                            // Display order priority
}
```

**Key Features:**

* Extends `IBase` for standard entity properties (\_id, createdAt, updatedAt, etc.)
* Supports multi-language content through `ILanguageVersion`
* Optional pricing with structured price object
* Tag-based categorization system
* Image management through media references
* Ordering support for display purposes

### IProductPrice

**File:** `common/module/product/product/domain/values/product-price.value.ts`

Value object interface for product pricing information.

```typescript
export interface IProductPrice {
  value: number;                             // Price amount
  currency: CurrencyCodeEnum;                // Currency code (USD, EUR, etc.)
}
```

**Key Features:**

* Immutable value object for price representation
* Support for international currencies
* Validation for non-negative values
* Type-safe currency handling

### IProductRepository

**File:** `common/module/product/product/domain/persistance/IProductRepository.ts`

Repository interface defining product data access operations.

```typescript
export interface IProductRepository extends IRepository<IProduct> {
  getPopulatedProductById(id: string): Promise<IProduct>;
  createProduct(product: IProduct): Promise<IProduct>;
  searchProductsWithCriteria(criteria: ProductPaginationDto): Promise<PaginationResultValue<IProduct>>;
}
```

**Key Features:**

* Extends base repository with product-specific operations
* Populated queries for related data (images, etc.)
* Advanced search with pagination and filtering
* CRUD operations with proper typing

### ITag

**File:** `common/module/product/tag/domain/persistance/i-tag.ts`

Product tag entity interface for categorization.

```typescript
export interface ITag extends IBase {
  name: string;                              // Tag name/identifier
}
```

**Key Features:**

* Simple tag structure with unique names
* Extends base entity for standard properties
* Used for product categorization and filtering

## Data Transfer Objects (DTOs)

### ProductDto

**File:** `common/module/product/product/dtos/product.dto.ts`

Main DTO for product data transfer with comprehensive validation.

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

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

  @ApiProperty({
    type: () => LanguageVersionDto,
    isArray: true
  })
  @IsArray()
  @Type(() => LanguageVersionDto)
  @Expose()
  languageVersions: LanguageVersionDto[];
  
  @ApiProperty({
    type: () => ProductPriceDto,
  })
  @Type(() => ProductPriceDto)
  @Expose()
  price: ProductPriceDto;

  @ApiProperty({ type: [String] })
  @IsString({ each: true })
  @IsOptional()
  @Expose()
  tags?: string[];

  @ApiProperty({ type: [MediaDto] })
  @IsOptional()
  @IsArray()
  @Expose()
  images?: MediaDto[];

  @ApiProperty()
  @IsNumber()
  @IsOptional()
  @Expose()
  order?: number | null;
}
```

**Validation Rules:**

* `sku`: Optional string for product identification
* `languageVersions`: Required array of language-specific content
* `price`: Required pricing information with currency
* `tags`: Optional array of string tags for categorization
* `images`: Optional array of media objects for product images
* `order`: Optional numeric value for display ordering

**Features:**

* Class-transformer decorators for serialization control
* Class-validator decorators for input validation
* Swagger/OpenAPI documentation decorators
* Proper type transformation for nested objects

### ProductPriceDto

**File:** `common/module/product/product/dtos/product-price.dto.ts`

DTO for product pricing information with currency support.

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

  @ApiProperty()
  @IsNumber()
  @Expose()
  value: number;

  @ApiProperty({
    enum: CurrencyCodeEnum,
    default: CurrencyCodeEnum.USD
  })
  @IsEnum(CurrencyCodeEnum)
  @Expose()
  currency: CurrencyCodeEnum;
}
```

**Validation Rules:**

* `value`: Required numeric price amount
* `currency`: Required currency code from enum
* `object`: Optional type identifier

**Features:**

* Enum validation for currency codes
* Numeric validation for price values
* Default currency support (USD)
* Type-safe currency handling

### ProductPaginationDto

**File:** `common/module/product/product/dtos/product.pagination.dto.ts`

DTO for paginated product queries with filtering capabilities.

```typescript
@Exclude()
export class ProductPaginationDto extends PaginationDto {
  @ApiPropertyOptional({
    description: 'Search phrase for filtering products by title, description',
    example: 'Product title',
  })
  @IsOptional()
  @IsString()
  @Expose()
  phrase?: string;

  @ApiPropertyOptional()
  @IsOptional()
  @IsString({ each: true })
  @IsArray()
  @Transform(({ value }) => {
    if (Array.isArray(value)) return value;
    return typeof value === 'string' ? value.split(',') : value;
  })
  @Expose()
  tags?: string[];
}
```

**Validation Rules:**

* `phrase`: Optional string for text search across title/description
* `tags`: Optional array of tag names for filtering
* Inherits pagination properties (page, size) from `PaginationDto`

**Features:**

* Text search functionality
* Tag-based filtering with array support
* Automatic string-to-array transformation for tags
* Extends base pagination with product-specific filters

### TagDto

**File:** `common/module/product/tag/dtos/tag.dto.ts`

DTO for product tag management operations.

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

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

**Validation Rules:**

* `name`: Optional string for tag name
* `object`: Optional type identifier
* Inherits base entity properties from `BaseEntityDto`

**Features:**

* Simple tag structure for categorization
* String validation for tag names
* Extends base entity for standard properties

### TagPaginationDto

**File:** `common/module/product/tag/dtos/tag.pagination.dto.ts`

DTO for paginated tag queries with search functionality.

```typescript
@Exclude()
export class TagPaginationDto extends PaginationDto {
  @ApiPropertyOptional({
    description: 'Search phrase for filtering tags by name',
    example: 'wellness',
  })
  @IsOptional()
  @IsString()
  @Expose()
  phrase?: string;
}
```

**Validation Rules:**

* `phrase`: Optional string for tag name search
* Inherits pagination properties from `PaginationDto`

**Features:**

* Text search for tag names
* Simple pagination support
* Lightweight filtering for tag management

## Domain Value Objects

### ProductPrice

**File:** `common/module/product/product/domain/values/product-price.value.ts`

Domain value object implementing price logic with validation.

```typescript
export class ProductPrice extends ValueObject<IProductPrice> implements IProductPrice {
  private constructor(props: IProductPrice) {
    super(props);
  }

  public static create(props: IProductPrice): Result<ProductPrice> {
    // Validation: ensure price is non-negative
    if (props.value < 0) {
      return Result.fail<ProductPrice>('Price must be non-negative.');
    }

    return Result.ok<ProductPrice>(new ProductPrice(props));
  }

  get value(): number {
    return this.props.value;
  }

  get currency(): CurrencyCodeEnum {
    return this.props.currency;
  }
}
```

**Key Features:**

* Immutable value object implementation
* Factory method with validation
* Price non-negativity validation
* Type-safe property access
* Proper error handling with Result pattern

## Repository Interfaces

### Product Repository Operations

The product repository extends the base repository pattern with specialized operations:

```typescript
interface IProductRepository extends IRepository<IProduct> {
  // Get product with populated references (images, etc.)
  getPopulatedProductById(id: string): Promise<IProduct>;
  
  // Create new product with validation
  createProduct(product: IProduct): Promise<IProduct>;
  
  // Advanced search with filtering and pagination
  searchProductsWithCriteria(criteria: ProductPaginationDto): Promise<PaginationResultValue<IProduct>>;
}
```

**Key Operations:**

* **Population**: Automatically populate related data (images, tags)
* **Creation**: Handle product creation with proper validation
* **Search**: Advanced filtering with text search and tag filtering
* **Pagination**: Efficient pagination for large product catalogs

## Use Case Interfaces

### Product Use Case Parameters

Each use case defines specific parameter interfaces for type safety:

#### CreateProductParams

**File:** `common/module/product/product/usecases/create-product.usecase.ts`

```typescript
export interface CreateProductParams {
  ctx: TenantActorContext;                   // Request context with tenant/user info
  product: ProductDto;                       // Product data to create
}
```

#### GetProductParams

**File:** `common/module/product/product/usecases/get-product.usecase.ts`

```typescript
export interface GetProductParams {
  ctx: TenantActorContext;                   // Request context
  productId: string;                         // Product ID to retrieve
}
```

#### UpdateProductParams

**File:** `common/module/product/product/usecases/update-product.usecase.ts`

```typescript
export interface UpdateProductParams {
  ctx: TenantActorContext;                   // Request context
  productId: string;                         // Product ID to update
  product: ProductDto;                       // Updated product data
}
```

#### DeleteProductParams

**File:** `common/module/product/product/usecases/delete-product.usecase.ts`

```typescript
export interface DeleteProductParams {
  ctx: TenantActorContext;                   // Request context
  productId: string;                         // Product ID to delete
}
```

#### GetPagedProductsParams

**File:** `common/module/product/product/usecases/get-paged-products.usecase.ts`

```typescript
export interface GetPagedProductsParams {
  ctx: TenantActorContext;                   // Request context
  pagination: ProductPaginationDto;          // Pagination and filtering criteria
}
```

### Product Tag Use Case Parameters

#### CreateProductTagParams

**File:** `common/module/product/tag/usecases/create-product-tag.usecase.ts`

```typescript
export interface CreateProductTagParams {
  ctx: TenantActorContext;                   // Request context
  tag: TagDto;                               // Tag data to create
}
```

#### GetPagedProductTagsParams

**File:** `common/module/product/tag/usecases/get-paged-product-tags.usecase.ts`

```typescript
export interface GetPagedProductTagsParams {
  ctx: TenantActorContext;                   // Request context
  pagination: TagPaginationDto;              // Pagination and search criteria
}
```

### Product Image Use Case Parameters

#### UpsertProductImageParams

**File:** `common/module/product/product/usecases/upsert-product-image.usecase.ts`

```typescript
export interface UpsertProductImageParams {
  ctx: TenantActorContext;                   // Request context
  productId: string;                         // Product ID for image association
  media: UploadMediaDto;                     // Media metadata
  file: Express.Multer.File;                 // Uploaded file data
}
```

#### DeleteProductImageParams

**File:** `common/module/product/product/usecases/delete-product-image.usecase.ts`

```typescript
export interface DeleteProductImageParams {
  ctx: TenantActorContext;                   // Request context
  productId: string;                         // Product ID
  id: string;                                // Image ID to delete
}
```

## Enums and Constants

### CurrencyCodeEnum

**File:** `common/core/enum/currency-code.enum.ts`

Comprehensive currency code enumeration for international support.

```typescript
export enum CurrencyCodeEnum {
  USD = 'USD',                               // US Dollar
  EUR = 'EUR',                               // Euro
  GBP = 'GBP',                               // British Pound Sterling
  CAD = 'CAD',                               // Canadian Dollar
  AUD = 'AUD',                               // Australian Dollar
  JPY = 'JPY',                               // Japanese Yen
  CHF = 'CHF',                               // Swiss Franc
  CNY = 'CNY',                               // Chinese Yuan
  INR = 'INR',                               // Indian Rupee
  BRL = 'BRL',                               // Brazilian Real
  MXN = 'MXN',                               // Mexican Peso
  ZAR = 'ZAR',                               // South African Rand
  // Additional currencies supported by the platform
}
```

### Permission Enums

**File:** `common/module/permission/domain/enums/permission.enum.ts`

Product-related permission constants for access control.

```typescript
export enum ModulePermissionEnum {
  // Product Management Permissions
  CRUD_PRODUCT = 11000,                      // All product operations
  READ_PRODUCT = 11001,                      // View products
  CREATE_PRODUCT = 11002,                    // Create new products
  EDIT_PRODUCT = 11003,                      // Update existing products
  DELETE_PRODUCT = 11004,                    // Delete products

  // Product Tag Management Permissions
  CRUD_PRODUCT_TAG = 12000,                  // All tag operations
  READ_PRODUCT_TAG = 12001,                  // View product tags
  CREATE_PRODUCT_TAG = 12002,                // Create new tags
  EDIT_PRODUCT_TAG = 12003,                  // Update existing tags
  DELETE_PRODUCT_TAG = 12004,                // Delete tags
}
```

**Permission Hierarchy:**

* `CRUD_*` permissions include all sub-permissions
* Each operation requires specific permission validation
* Permissions are checked at use case level
* Multi-tenant isolation enforced automatically

## Media and File Interfaces

### MediaDto

**File:** `common/module/media/dtos/media.dto.ts`

DTO for media file management and metadata.

```typescript
export interface MediaDto {
  _id: string;                               // Media file ID
  url: string;                               // CDN URL for file access
  type: string;                              // Media type (image, video, etc.)
  mimeType: string;                          // MIME type (image/jpeg, etc.)
  size: number;                              // File size in bytes
  alt?: string;                              // Alternative text for accessibility
  createdAt: string;                         // Creation timestamp
  updatedAt: string;                         // Last update timestamp
}
```

### UploadMediaDto

**File:** `common/module/media/dtos/upload.media.dto.ts`

DTO for media upload operations with metadata.

```typescript
export interface UploadMediaDto {
  alt?: string;                              // Alternative text
  description?: string;                      // Media description
  tags?: string[];                           // Media tags for organization
  // Additional metadata fields as needed
}
```

### File Upload Constraints

**Supported File Types:**

* `image/jpeg` - JPEG images
* `image/png` - PNG images with transparency support
* `image/webp` - Modern WebP format

**Size Limits:**

* Maximum file size: 5MB per image
* Maximum dimensions: 4000x4000 pixels
* Minimum dimensions: 200x200 pixels (recommended)

## Validation Constraints

### Product Validation Rules

#### SKU Validation

```typescript
@IsString()
@IsOptional()
@Length(1, 100)
sku?: string;
```

#### Language Versions Validation

```typescript
@IsArray()
@ArrayNotEmpty()
@ValidateNested({ each: true })
@Type(() => LanguageVersionDto)
languageVersions: LanguageVersionDto[];
```

#### Price Validation

```typescript
@ValidateNested()
@Type(() => ProductPriceDto)
@IsNotEmpty()
price: ProductPriceDto;
```

#### Tags Validation

```typescript
@IsOptional()
@IsArray()
@IsString({ each: true })
@ArrayMaxSize(20)
tags?: string[];
```

#### Order Validation

```typescript
@IsOptional()
@IsNumber()
@Min(0)
@Max(999999)
order?: number;
```

### Price Validation Rules

#### Value Validation

```typescript
@IsNumber()
@IsPositive()
@Max(999999.99)
value: number;
```

#### Currency Validation

```typescript
@IsEnum(CurrencyCodeEnum)
@IsNotEmpty()
currency: CurrencyCodeEnum;
```

### Tag Validation Rules

#### Name Validation

```typescript
@IsString()
@IsNotEmpty()
@Length(1, 50)
@Matches(/^[a-zA-Z0-9-_\s]+$/)
name: string;
```

## Advanced Type Definitions

### Pagination Result Types

```typescript
interface PaginationResultValue<T> {
  items: T[];                                // Array of items
  totalSize: number;                         // Total number of items
  page: number;                              // Current page number
  size: number;                              // Items per page
}
```

### Context Types

```typescript
interface TenantActorContext {
  tenantId: string;                          // Business tenant identifier
  actor: {                                   // User/actor information
    _id: string;                            // User ID
    permissions: string[];                   // User permissions
    roles: string[];                        // User roles
  };
  // Additional context properties
}
```

### Result Pattern Types

```typescript
interface Result<T> {
  isSuccess: boolean;                        // Operation success flag
  isFailure: boolean;                        // Operation failure flag
  error?: string;                           // Error message if failed
  value?: T;                                // Result value if successful
}
```

## Integration Interfaces

### Event Interfaces

Product management integrates with the event system for notifications and auditing:

```typescript
interface ProductCreatedEvent {
  type: 'ProductCreated';
  tenantId: string;
  productId: string;
  product: ProductDto;
  createdBy: string;
  timestamp: Date;
}

interface ProductUpdatedEvent {
  type: 'ProductUpdated';
  tenantId: string;
  productId: string;
  changes: Partial<ProductDto>;
  updatedBy: string;
  timestamp: Date;
}

interface ProductDeletedEvent {
  type: 'ProductDeleted';
  tenantId: string;
  productId: string;
  deletedBy: string;
  timestamp: Date;
}
```

### Cache Interfaces

```typescript
interface ProductCacheKey {
  type: 'product';
  tenantId: string;
  productId: string;
}

interface ProductListCacheKey {
  type: 'product-list';
  tenantId: string;
  criteria: string;                          // Serialized search criteria
}
```

## Type Safety Features

### Strict Typing

* All interfaces use strict TypeScript typing
* Optional vs required properties clearly defined
* Enum constraints for categorical data
* Generic type support for reusable patterns

### Validation Integration

* Class-validator decorators for runtime validation
* Type-safe validation error handling
* Comprehensive error messages
* Custom validation rules for business logic

### Serialization Control

* Class-transformer decorators for data transformation
* Selective property exposure/exclusion
* Nested object transformation
* Type conversion for complex objects

## Migration and Versioning

### Interface Evolution

* Backward compatibility maintained through optional properties
* Deprecation notices for removed features
* Version-specific interface definitions
* Migration guides for breaking changes

### Schema Compatibility

* Database schema evolution support
* Field addition/removal strategies
* Data migration scripts
* Version-aware serialization

This interface documentation provides a complete reference for all types, validation rules, and contracts used in the Product Management module, ensuring type safety and proper integration across the system.