Product System Types

This document provides a comprehensive reference for all TypeScript interfaces and types used within the Product management system. These types ensure type safety, enable IDE autocompletion, and serve as documentation for the data structures used throughout the application.

Core Product Types

Product Entity Types

// Main Product interface from SDK
interface Product {
  id: string;
  externalId: string;
  externalSource: string;
  productStatus: ProductStatus;
  attributeValues: ProductAttributeValue[];
  productPictures: ProductPicture[];
  tags: ProductTag[];
  info: ProductInfo;
  createdAt: string;
  updatedAt: string;
}

// Product basic information
interface ProductInfo {
  sku: string;
  name: string;
  description: string;
  brand: string;
  unit: ProductUnit;
}

// Product status enumeration
type ProductStatus =
  | "ACTIVE"
  | "INACTIVE"
  | "DISCONTINUED"
  | "PENDING"
  | "DRAFT";

// Product unit configuration
interface ProductUnit {
  type: string;
  unit: string;
}

Product Variant Types

// Product variant interface
interface ProductVariant {
  id: string;
  skuProduct: string;
  skuVariant: string;
  default: boolean;
  status: string;
  info: ProductVariantInfo;
  attributeValues: ProductAttributeValue[];
  productPictures: ProductPicture[];
  mainImageUrl: string;
  gtin: string;
  ean: string;
  externalId: string;
  description?: string;
  productMediaInfoDTO?: ProductMediaInfoDTO;
}

// Product variant information
interface ProductVariantInfo {
  name: string;
  description: string;
  sku: string;
  mpn: string;
  ean: string;
}

// Product variant response wrapper
interface ProductVariantRes {
  variant: ProductVariant;
  productPictures: ProductMediaInfo[];
}

Product Attribute Types

// Product attribute value structure
interface ProductAttributeValue {
  attribute: ProductAttribute;
  value: any; // Value type varies based on attribute type
}

// Product attribute definition
interface ProductAttribute {
  externalId: string;
  type: ProductAttributeType;
  label: string;
  description?: string;
  required?: boolean;
}

// Supported attribute types
type ProductAttributeType =
  | "TEXT"
  | "LIST_TEXT"
  | "METRIC"
  | "LIST_METRIC"
  | "COLOR"
  | "LIST_COLOR"
  | "BOOLEAN"
  | "DATE"
  | "NUMBER";

// Metric attribute value
interface MetricAttributeValue {
  selectedValue: number;
  unit: string;
}

// Color attribute value
interface ColorAttributeValue {
  label: string;
  hexCode: string;
}

Product Media Types

// Product picture structure
interface ProductPicture {
  urls: MediaInfoDTO[];
  isMain: boolean;
  type: string;
}

// Media information DTO
interface MediaInfoDTO {
  url: string;
  width?: number;
  height?: number;
  mimeType?: string;
  size?: number;
}

// Product media info structure
interface ProductMediaInfoDTO {
  images: MediaInfoDTO[];
  videos?: MediaInfoDTO[];
  documents?: MediaInfoDTO[];
}

// Product media info (alternative structure)
interface ProductMediaInfo {
  url: string;
  type: "image" | "video" | "document";
  isMain: boolean;
  order: number;
}

Product Tag Types

// Product tag structure
interface ProductTag {
  name: string;
  category: ProductTagCategory;
  color?: string;
  description?: string;
}

// Product tag categories
type ProductTagCategory =
  | "PRODUCT_CATEGORY"
  | "BRAND"
  | "FEATURE"
  | "PROMOTION"
  | "CUSTOM";

Request and Response Types

Product Request Types

// Get product by ID request
interface GetProductRequest {
  productIdentifier: string;
  productIdType?: ProductIdType;
  locale?: string;
}

// Product identifier types
type ProductIdType = "EXTERNAL_ID" | "SKU" | "ID";

// Get product variants request
interface GetProductVariantsRequest {
  productSku: string;
  locale?: string;
  pageable?: Pageable;
}

// Get related products request
interface GetRelatedProductsRequest {
  productIdentifier: string;
  productIdType?: ProductIdType;
  locale?: string;
  currency?: string;
  pageable?: Pageable;
  withAggregation?: boolean;
}

// Get product offers request
interface GetProductOffersRequest {
  productIdentifier: string;
  productIdType?: ProductIdType;
  currency?: string;
  locale?: string;
  withoutPrices?: boolean;
  pageable?: Pageable;
}

// Get product variant offers request
interface GetProductVariantOffersRequest {
  productIdentifier: string;
  productIdType?: ProductIdType;
  currency?: string;
}

// Pagination interface
interface Pageable {
  page?: number;
  size?: number;
  sort?: string[];
}

Product Response Types

// Get product response
interface GetProductResponse {
  success: boolean;
  product: Product;
}

// Get product variants response
interface GetProductVariantsResponse {
  success: boolean;
  variants: ProductVariantsPage;
}

// Product variants page structure
interface ProductVariantsPage {
  content: ProductVariant[];
  pageable: Pageable;
  totalElements: number;
  totalPages: number;
  size: number;
  number: number;
  first: boolean;
  last: boolean;
  empty?: boolean;
}

// Get related products response
interface GetRelatedProductsResponse {
  productThumbnails: ProductThumbnail[];
  aggregations?: ProductAggregations;
  totalElements: number;
}

// Product thumbnail for listings
interface ProductThumbnail {
  sku: string;
  name: string;
  description?: string;
  mainPictureUrl?: string;
  brand?: string;
  status: ProductStatus;
}

// Product aggregations for filtering
interface ProductAggregations {
  brands: BrandAggregation[];
  categories: CategoryAggregation[];
  priceRanges: PriceRangeAggregation[];
}

interface BrandAggregation {
  brand: string;
  count: number;
}

interface CategoryAggregation {
  category: string;
  count: number;
}

interface PriceRangeAggregation {
  min: number;
  max: number;
  count: number;
}

// Get product offers response
interface GetProductOffersResponse {
  offers: ProductOffer[];
  pagination: PaginationInfo;
}

// Get product variant offers response
interface GetProductVariantOffersResponse {
  offers: ProductVariantOffer[];
  totalElements: number;
}

// Pagination info
interface PaginationInfo {
  page: number;
  size: number;
  totalElements: number;
  totalPages: number;
  first: boolean;
  last: boolean;
}

Review and Rating Types

// Get product reviews request
interface GetReviewRequest {
  productIdentifier: string;
  productIdType?: ProductIdType;
  pageable?: Pageable;
}

// Create product review request
interface CreateReviewRequest {
  message: string;
  productSku: string;
  rating: number;
}

// Update product review request
interface UpdateReviewRequest {
  productReviewId: string;
  message: string;
  rating: number;
}

// Get product review response
interface GetProductReviewResponse {
  reviews: ProductReview[];
  statistics: ReviewStatistics;
  pagination: PaginationInfo;
}

// Put product review response
interface PutProductReviewResponse {
  success: boolean;
  review: ProductReview;
}

// Product review structure
interface ProductReview {
  id: string;
  productSku: string;
  userId: string;
  userName: string;
  message: string;
  rating: number;
  createdAt: string;
  updatedAt: string;
  helpful: number;
  verified: boolean;
}

// Review statistics
interface ReviewStatistics {
  averageRating: number;
  totalReviews: number;
  ratingDistribution: RatingDistribution[];
}

// Rating distribution
interface RatingDistribution {
  rating: number;
  count: number;
  percentage: number;
}

Offer and Pricing Types

// Product offer structure
interface ProductOffer {
  id: string;
  productSku: string;
  supplierId: string;
  supplierName: string;
  price: ProductPrice;
  availability: ProductAvailability;
  validFrom: string;
  validTo?: string;
  minimumQuantity: number;
  packageSize: number;
}

// Product variant offer
interface ProductVariantOffer {
  id: string;
  variantSku: string;
  productSku: string;
  supplierId: string;
  price: ProductPrice;
  availability: ProductAvailability;
  specifications: VariantSpecifications;
}

// Product price structure
interface ProductPrice {
  amount: number;
  currency: Currency;
  priceType: PriceType;
  taxIncluded: boolean;
  discounts?: PriceDiscount[];
}

// Currency enumeration
type Currency = "EUR" | "USD" | "GBP" | "CHF";

// Price type enumeration
type PriceType = "UNIT" | "PACKAGE" | "BULK" | "TIERED";

// Price discount structure
interface PriceDiscount {
  type: DiscountType;
  value: number;
  minimumQuantity?: number;
  validFrom: string;
  validTo?: string;
}

// Discount type enumeration
type DiscountType = "PERCENTAGE" | "FIXED_AMOUNT" | "BULK_DISCOUNT";

// Product availability
interface ProductAvailability {
  inStock: boolean;
  quantity?: number;
  availableFrom?: string;
  leadTime?: number;
  location?: string;
}

// Variant specifications
interface VariantSpecifications {
  weight?: number;
  dimensions?: ProductDimensions;
  material?: string;
  color?: string;
  size?: string;
}

// Product dimensions
interface ProductDimensions {
  length: number;
  width: number;
  height: number;
  unit: "mm" | "cm" | "m" | "in" | "ft";
}

Composable Types

useProduct Types

// Product API composable type
type ProductApi = {
  getProductbyId: (params: GetProductRequest) => Promise<GetProductResponse>;
  getRelatedProducts: (
    params: GetRelatedProductsRequest
  ) => Promise<GetRelatedProductsResponse | null>;
  getProductPaginatedOffers: (
    params: GetProductOffersRequest
  ) => Promise<GetProductOffersResponse | null>;
  getProductReviews: (
    params: GetReviewRequest
  ) => Promise<GetProductReviewResponse | null>;
  createProductReview: (
    params: CreateReviewRequest
  ) => Promise<GetProductReviewResponse | null>;
  updateProductReview: (
    params: UpdateReviewRequest
  ) => Promise<PutProductReviewResponse | null>;
  getProductVariants: (
    params: GetProductVariantsRequest
  ) => Promise<GetProductVariantsResponse | null>;
  getProductVariantOffers: (
    params: GetProductVariantOffersRequest
  ) => Promise<GetProductVariantOffersResponse | null>;
};

// Product getters composable type
type ProductGetters = {
  getProductStatus: (product: Product) => string;
  getProductAttributeValues: (product: Product) => ProductAttributeValue[];
  getProductAttributeValuebyExternalId: (
    product: Product,
    externalId: string
  ) => string;
  getMainProductPictureUrls: (product: Product) => MediaInfoDTO[] | null;
  getProductPictures: (product: Product) => ProductPicture[];
  getProductTags: (product: Product) => string[];
  getProductExternalId: (product: Product) => string;
  getProductExternalSource: (product: Product) => string;
  getProductName: (product: Product) => string;
  getProductDescription: (product: Product) => string;
  getProductBrand: (product: Product) => string;
  getProductSku: (product: Product) => string;
  getProductUnitType: (product: Product) => string;
  getProductUnitUnit: (product: Product) => string;
  getRelatedProductsList: (product: Product) => string;
};

// Product helpers composable type (currently empty)
type ProductHelpers = {};

// Complete useProduct composable type
type UseProduct = ProductApi & ProductGetters & ProductHelpers;

useProductVariant Types

// Product variant getters composable type
type ProductVariantGetters = {
  getProductVariantDefault: (product: ProductVariant) => boolean;
  getProductVariantId: (product: ProductVariant) => string;
  getProductSkuFromVariant: (product: ProductVariant) => string;
  getProductVariantSku: (product: ProductVariant) => string;
  getProductMpn: (product: ProductVariant) => string;
  getProductVariantName: (product: ProductVariant) => string;
  getProductVariantDescription: (product: ProductVariant) => string;
  getProductVariantMainImageUrl: (product: ProductVariant) => string;
  getProductVariantMediaInfo: (
    product: ProductVariant
  ) => ProductMediaInfoDTO | {};
  getProductVariantPictures: (product: ProductVariantRes) => ProductMediaInfo[];
  getProductVariantAttributeValues: (
    product: ProductVariant
  ) => ProductAttributeValue[];
  getProductVariantGtin: (product: ProductVariant) => string;
  getProductVariantEan: (product: ProductVariant) => string;
  getProductVariantExternalId: (product: ProductVariant) => string;
  getProductVariantStatus: (product: ProductVariant) => string;
  getProductVariantFromOffer: (offer: OfferRes) => ProductVariantRes;
  getProductVariantAttributeValuebyExternalId: (
    product: ProductVariant,
    externalId: string
  ) => string | null;
};

// Product variant API composable type (currently empty)
type ProductVariantApi = {};

// Product variant helpers composable type (currently empty)
type ProductVariantHelpers = {};

// Complete useProductVariant composable type
type UseProductVariant = ProductVariantApi &
  ProductVariantGetters &
  ProductVariantHelpers;

Utility Types

Search and Filter Types

// Product search filters
interface ProductSearchFilters {
  query?: string;
  brands?: string[];
  categories?: string[];
  priceRange?: {
    min: number;
    max: number;
  };
  attributes?: AttributeFilter[];
  inStock?: boolean;
}

// Attribute filter
interface AttributeFilter {
  attributeId: string;
  values: string[];
  operator: "AND" | "OR";
}

// Product search result
interface ProductSearchResult {
  products: ProductThumbnail[];
  facets: ProductFacets;
  pagination: PaginationInfo;
  query: string;
  filters: ProductSearchFilters;
}

// Product facets for filtering
interface ProductFacets {
  brands: FacetValue[];
  categories: FacetValue[];
  attributes: AttributeFacet[];
  priceRanges: PriceRangeFacet[];
}

// Facet value
interface FacetValue {
  value: string;
  label: string;
  count: number;
  selected: boolean;
}

// Attribute facet
interface AttributeFacet {
  attributeId: string;
  attributeLabel: string;
  values: FacetValue[];
}

// Price range facet
interface PriceRangeFacet {
  min: number;
  max: number;
  count: number;
  label: string;
}

Error Types

// Product API error
interface ProductApiError {
  code: string;
  message: string;
  details?: string;
  statusCode: number;
  timestamp: string;
}

// Product validation error
interface ProductValidationError {
  field: string;
  value: any;
  message: string;
  code: string;
}

// Product not found error
interface ProductNotFoundError {
  productIdentifier: string;
  productIdType: ProductIdType;
  message: string;
}

Common Types

// Common types used across the system
type Locale = "en-GB" | "fr-FR" | "de-DE" | "es-ES" | "it-IT";

// Sort direction
type SortDirection = "ASC" | "DESC";

// Sort option
interface SortOption {
  field: string;
  direction: SortDirection;
}

// API response wrapper
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: ProductApiError;
  timestamp: string;
}

// Loading state
interface LoadingState {
  isLoading: boolean;
  operation?: string;
  progress?: number;
}

Type Guards and Utilities

// Type guards for runtime type checking
function isProduct(obj: any): obj is Product {
  return obj && typeof obj.id === "string" && typeof obj.info === "object";
}

function isProductVariant(obj: any): obj is ProductVariant {
  return (
    obj && typeof obj.id === "string" && typeof obj.skuVariant === "string"
  );
}

function isProductResponse(obj: any): obj is GetProductResponse {
  return (
    obj &&
    typeof obj.success === "boolean" &&
    (obj.product === null || isProduct(obj.product))
  );
}

// Utility types for partial updates
type PartialProduct = Partial<Product>;
type ProductUpdate = Pick<Product, "id"> & Partial<Omit<Product, "id">>;

// Utility types for component props
type ProductCardProps = Pick<Product, "info" | "productPictures"> & {
  showPrice?: boolean;
  onClick?: (product: Product) => void;
};

type VariantSelectorProps = {
  variants: ProductVariant[];
  selectedVariant?: ProductVariant;
  onVariantChange: (variant: ProductVariant) => void;
};

This comprehensive type system ensures type safety throughout the Product management system while providing clear documentation of data structures and their relationships. All types are derived from the actual SDK interfaces and composable implementations to maintain accuracy and consistency.