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

2. Data Transfer Objects (DTOs)

3. Domain Value Objects

4. Repository Interfaces

5. Use Case Interfaces

6. Enums and Constants

7. Media and File Interfaces

8. Validation Constraints

Core Interfaces

IProduct

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

Core product entity interface extending base entity functionality.

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.

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.

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.

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.

@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.

@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.

@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.

@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.

@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.

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:

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

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

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

UpdateProductParams

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

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

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

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

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

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

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

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.

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.

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.

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.

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

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

Language Versions Validation

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

Price Validation

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

Tags Validation

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

Order Validation

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

Price Validation Rules

Value Validation

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

Currency Validation

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

Tag Validation Rules

Name Validation

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

Advanced Type Definitions

Pagination Result Types

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

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

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:

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

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.