Products and Offers

This documentation provides a comprehensive overview of the Product management system within the Nuxt 3 e-commerce B2B application. The system consists of two main composables: useProduct and useProductVariant that handle product data retrieval, manipulation, and related operations.

System Architecture

The Product system is built around two complementary composables that work together to provide complete product management functionality:

graph TB
    subgraph "Product Management Architecture"
        User[User Interface]

        subgraph "Composables Layer"
            UP[useProduct]
            UPV[useProductVariant]
        end

        subgraph "useProduct Structure"
            UPA[useProductApi]
            UPG[useProductGetters]
            UPH[useProductHelpers]
        end

        subgraph "useProductVariant Structure"
            UPVA[useProductVariantApi]
            UPVG[useProductVariantGetters]
            UPVH[useProductVariantHelpers]
        end

        subgraph "Backend Integration"
            SDK[Djust SDK]
            API[API Routes]
        end
    end

    User --> UP
    User --> UPV

    UP --> UPA
    UP --> UPG
    UP --> UPH

    UPV --> UPVA
    UPV --> UPVG
    UPV --> UPVH

    UPA --> SDK
    UPVA --> SDK
    SDK --> API

    style UP fill:#e1f5fe
    style UPV fill:#f3e5f5
    style SDK fill:#e8f5e8

Data Structure Overview

The Product system manages several key data types and their relationships:

Core Functionality

Product Operations Flow

sequenceDiagram
    participant U as User
    participant C as Component
    participant UP as useProduct
    participant SDK as Djust SDK
    participant API as API Server

    U->>C: Request Product Details
    C->>UP: getProductbyId(params)
    UP->>SDK: useFetch('/api/product/{id}')
    SDK->>API: GET /api/product/{productId}
    API-->>SDK: Product Data
    SDK-->>UP: GetProductResponse
    UP->>UP: Process Response
    UP-->>C: Formatted Product
    C-->>U: Display Product

    Note over UP,SDK: Error handling at each step
    Note over API: Authentication & validation

Product Variant Operations Flow

sequenceDiagram
    participant U as User
    participant C as Component
    participant UPV as useProductVariant
    participant UP as useProduct
    participant SDK as Djust SDK

    U->>C: Request Variant Details
    C->>UPV: getProductVariantId(variant)
    UPV->>UPV: Extract ID from variant
    UPV-->>C: Variant ID

    alt Get Full Variant Data
        C->>UP: getProductVariants(params)
        UP->>SDK: API Call
        SDK-->>UP: Variants List
        UP-->>C: Variant Details
    end

    C-->>U: Display Variant Info

Authentication Overview

The Product system operates in both authenticated and unauthenticated modes, providing different levels of data access based on the user's authentication status. All product API endpoints are accessible without authentication, but return filtered public data for unauthenticated users and complete data for authenticated users.

Authentication Flow

Product Access Authentication Flow

sequenceDiagram
    participant User as User
    participant Component as Vue Component
    participant Product as useProduct
    participant API as Product API
    participant AuthService as Auth Service

    User->>Component: Request Product Data
    Component->>Product: getProductbyId(params)
    Product->>API: API Request (with optional auth token)

    API->>AuthService: Check Authentication Token (if present)

    alt Authenticated User
        AuthService-->>API: Valid Token & Permissions
        API-->>Product: Complete Product Data (all offers, pricing, stock)
        Product-->>Component: Full Product Information
        Component-->>User: Display Complete Product
    else Unauthenticated User
        AuthService-->>API: No Token or Invalid Token
        API-->>Product: Public Product Data (public offers only)
        Product-->>Component: Limited Product Information
        Component-->>User: Display Public Product Data
    end

    Note over API: Server filters data based on authentication status
    Note over API: Same response format in both cases

Data Filtering Based on Authentication

Public vs Authenticated Data Access

The Product system provides different levels of data access based on authentication status:

Main Features

1. Product Data Retrieval

The system provides comprehensive product data access through specialized getter functions:

• Basic Information: Name, description, SKU, brand, external identifiers
• Media Management: Main images, product pictures, media URLs
• Attribute Processing: Product attributes with type-specific value extraction
• Status Management: Product status, availability, and lifecycle state

2. Product Variant Management

Product variants are handled through dedicated functionality:

• Variant Identification: Unique IDs, SKUs, external identifiers
• Attribute Values: Type-aware attribute value extraction (LIST_TEXT, METRIC, COLOR)
• Media Assets: Variant-specific images and media information
• Offer Integration: Seamless integration with pricing offers

3. API Integration

The system integrates with multiple backend endpoints:

• Product Details: /api/product/{productId} - Get detailed product information
• Related Products: /api/product/{productId}/related-products - Fetch related items
• Product Offers: /api/product/{productId}/offers - Get product pricing offers
• Product Variants: /api/product-variants/{productSku} - List product variations
• Variant Offers: /api/product-variants/{productVariantId}/offers - Variant pricing
• Product Reviews: /api/product/{productId}/reviews - Review management

Key Points

Performance Considerations

• Lazy Loading: Product data is fetched on-demand to optimize initial load times
• Pagination Support: Large product lists and offers support pagination
• Caching Strategy: Leverages Nuxt's built-in caching for repeated requests
• Image Optimization: Media URLs are processed for optimal delivery

Security & Authentication

• JWT Integration: All API calls include authentication headers
• Permission Validation: Backend validates user permissions for product access
• Data Sanitization: User inputs are validated before API calls
• Error Boundary: Comprehensive error handling prevents data exposure

Flexibility & Configuration

• Multi-locale Support: Products support internationalization through locale parameters
• Currency Handling: Product pricing adapts to user's currency settings
• Customizable Pagination: Configurable page sizes and navigation
• Attribute Type Support: Handles various attribute types (text, metric, color, list)

Integration Capabilities

• SDK Abstraction: Clean separation between frontend logic and backend communication
• Type Safety: Full TypeScript support with SDK-generated interfaces
• Composable Architecture: Modular structure allows selective feature usage
• Error Propagation: Consistent error handling across all product operations

Best Practices

Composable Usage

When working with the Product system, follow these recommended patterns:

// ✅ Correct: Use destructuring for specific functionality
const { getProductbyId, getProductName, getProductStatus } = useProduct();
const { getProductVariantId, getProductVariantAttributeValues } =
  useProductVariant();

// ✅ Correct: Handle loading states
const isLoading = ref(false);
const product = ref(null);

const fetchProduct = async (productId: string) => {
  isLoading.value = true;
  try {
    const response = await getProductbyId({ productIdentifier: productId });
    product.value = response.product;
  } catch (error) {
    console.error("Failed to fetch product:", error);
  } finally {
    isLoading.value = false;
  }
};

Error Handling

Implement comprehensive error handling for robust applications:

// ✅ Correct: Comprehensive error handling
try {
  const productResponse = await getProductbyId(params);
  if (!productResponse.success || !productResponse.product) {
    throw new Error("Product not found");
  }
  return productResponse.product;
} catch (error) {
  // Log error for debugging
  console.error("Product fetch failed:", error);

  // Show user-friendly message
  useToast().add({
    title: "Error",
    description: "Unable to load product details. Please try again.",
    color: "red",
  });

  return null;
}

Performance Optimization

Optimize product data handling for better user experience:

// ✅ Correct: Optimize image loading
const getOptimizedProductImages = (product: Product) => {
  const pictures = getProductPictures(product);
  return pictures
    ?.filter((pic) => pic.urls?.length > 0)
    .map((pic) => pic.urls[0]) // Use first URL for optimization
    .slice(0, 5); // Limit to 5 images
};

// ✅ Correct: Implement proper pagination
const loadProducts = async (page: number = 0, size: number = 20) => {
  return await getProductPaginatedOffers({
    productIdentifier: productId,
    pageable: { page, size },
  });
};

Detailed Documentation

This overview provides the foundation for understanding the Product management system. For detailed implementation guides, API specifications, and advanced usage patterns, refer to the following specialized documentation:

Function Documentation

• Get Product by ID - Retrieve detailed product information
• Get Product Variants - List product variants with pagination
• Get Product Paginated Offers - Retrieve product pricing and supplier offers
• Get Product Variant Offers - Get variant-specific pricing and availability

System Documentation

• Types & Interfaces - Complete TypeScript interface definitions
• Error Handling - Comprehensive error management strategies
• Authentication Integration - Product system authentication requirements

The Product system serves as a critical foundation for the e-commerce platform, providing reliable, performant, and secure access to product data across the entire application ecosystem.