@djust-b2b/djust-front-sdk 3.0.0-beta.9 → 3.0.0

package/lib/services/product/product.service.d.ts

@@ -0,0 +1,452 @@
+/**
+ * # Product Service
+ *
+ * Complete product catalog management for B2B e-commerce.
+ *
+ * ## Features
+ * - Full-text search with autocomplete
+ * - Advanced filtering and faceted navigation
+ * - Product variants and attributes
+ * - Offers and supplier pricing
+ * - Customer reviews and ratings
+ *
+ * @module services/product
+ * @since 2.17.0
+ */
+import { BaseService } from "../base.service";
+import type { RequestContext } from "../../client/transport";
+import type { AutoCompleteSearchParams, GetProductsListParams, GetProductParams, GetProductVariantOffersParams, GetProductVariantSuppliersParams, GetProductOffersParams, GetProductPaginatedOffersParams, GetRelatedProductsParams, GetProductReviewsParams, GetProductStatReviewsParams, GetProductVariantAttributesParams, CreateProductReviewParams, UpdateProductReviewParams, SearchProductsResponse, GetProductsListResponse, GetProductVariantOffersResponse, GetProductVariantSuppliersResponse, GetProductOffersResponse, GetProductPaginatedOffersResponse, GetRelatedProductsResponse, GetProductReviewsResponse, GetProductStatReviewsResponse, GetProductVariantAttributesResponse, CreateProductReviewResponse, UpdateProductReviewResponse } from "./types";
+/**
+ * Service for product catalog operations.
+ *
+ * Provides complete product management:
+ * - Search and discovery
+ * - Product details and variants
+ * - Offers and pricing from multiple suppliers
+ * - Reviews and ratings
+ *
+ * @example
+ * ```typescript
+ * import { createDjustClient } from '@djust-b2b/djust-front-sdk';
+ *
+ * const client = createDjustClient({ baseUrl, clientId, apiKey });
+ *
+ * // Autocomplete search
+ * const results = await client.product.autoCompleteSearch({
+ *   input: 'laptop',
+ *   locale: 'en-US',
+ *   currency: 'USD',
+ * });
+ *
+ * // Get product details
+ * const product = await client.product.getProduct({
+ *   productIdentifier: 'SKU-12345',
+ *   productIdType: 'sku',
+ *   locale: 'en-US',
+ * });
+ * ```
+ */
+export declare class ProductService extends BaseService {
+    readonly serviceName = "product";
+    /**
+     * Search products with autocomplete suggestions.
+     *
+     * Returns matching products based on partial text input, ideal for
+     * implementing search-as-you-type functionality.
+     *
+     * **Endpoint**: `GET /v1/shop/products/autocomplete [PROD-100]`
+     *
+     * | Parameter     | Type             | Required | Description                          |
+     * |---------------|------------------|----------|--------------------------------------|
+     * | `input`       | `string`         | Yes      | Search query text                    |
+     * | `locale`      | `string`         | Yes      | Locale for translations (e.g., en-US)|
+     * | `currency`    | `string`         | Yes      | Currency code for prices (e.g., USD) |
+     * | `aggregation` | `boolean`        | No       | Include faceted aggregations         |
+     * | `productTags` | `string[]`       | No       | Filter by product tags               |
+     * | `pageable`    | `PageableParams` | No       | Pagination settings                  |
+     *
+     * @example
+     * ```typescript
+     * const results = await client.product.autoCompleteSearch({
+     *   input: 'laptop pro',
+     *   locale: 'en-US',
+     *   currency: 'USD',
+     *   aggregation: true,
+     *   pageable: { page: 0, size: 10 },
+     * });
+     *
+     * console.log(`Found ${results.totalElements} products`);
+     * results.content.forEach(product => {
+     *   console.log(`${product.name} - ${product.price} ${results.currency}`);
+     * });
+     * ```
+     *
+     * @param params - Search parameters
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If required parameters are missing
+     * @returns Search results with products and optional aggregations
+     */
+    autoCompleteSearch(params: AutoCompleteSearchParams, context?: RequestContext): Promise<SearchProductsResponse>;
+    /**
+     * Get paginated list of products with advanced filtering.
+     *
+     * Supports faceted search, category navigation, and multiple filter criteria.
+     *
+     * **Endpoint**: `GET /v1/shop/products [PROD-101]`
+     *
+     * | Parameter  | Type             | Required | Description                          |
+     * |------------|------------------|----------|--------------------------------------|
+     * | `locale`   | `string`         | Yes      | Locale for translations              |
+     * | `filters`  | `ProductFilters` | No       | Advanced filter criteria             |
+     * | `pageable` | `PageableParams` | No       | Pagination and sorting               |
+     *
+     * @example
+     * ```typescript
+     * const { content: products, totalElements } = await client.product.getProductsList({
+     *   locale: 'fr-FR',
+     *   filters: {
+     *     categoryId: 'electronics',
+     *     priceMin: 100,
+     *     priceMax: 500,
+     *     inStock: true,
+     *   },
+     *   pageable: { page: 0, size: 20, sort: 'price,asc' },
+     * });
+     * ```
+     *
+     * @param params - Search parameters with filters
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If locale is missing
+     * @returns Paginated product list with total count
+     */
+    getProductsList(params: GetProductsListParams, context?: RequestContext): Promise<GetProductsListResponse>;
+    /**
+     * Get detailed product information by identifier.
+     *
+     * Retrieves full product details including description, images,
+     * specifications, and available variants.
+     *
+     * **Endpoint**: `GET /v1/shop/products/{identifier} [PROD-102]`
+     *
+     * | Parameter           | Type     | Required | Description                    |
+     * |---------------------|----------|----------|--------------------------------|
+     * | `productIdentifier` | `string` | Yes      | Product ID, SKU, or EAN        |
+     * | `productIdType`     | `string` | Yes      | Identifier type: id, sku, ean  |
+     * | `locale`            | `string` | No       | Locale for translations        |
+     *
+     * @example
+     * ```typescript
+     * // Get by SKU
+     * const product = await client.product.getProduct({
+     *   productIdentifier: 'LAPTOP-PRO-15',
+     *   productIdType: 'sku',
+     *   locale: 'en-US',
+     * });
+     *
+     * console.log(product.name);
+     * console.log(product.description);
+     * console.log(product.variants);
+     * ```
+     *
+     * @param params - Product identification parameters
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If required parameters are missing
+     * @throws {NotFoundError} If product is not found
+     * @returns Full product details
+     */
+    getProduct(params: GetProductParams, context?: RequestContext): Promise<GetProductsListResponse>;
+    /**
+     * Get all offers available for a specific product variant.
+     *
+     * Returns pricing from all suppliers for a given variant, allowing
+     * customers to compare prices and select preferred suppliers.
+     *
+     * **Endpoint**: `GET /v1/shop/products/{identifier}/offers [PROD-103]`
+     *
+     * | Parameter           | Type      | Required | Description                   |
+     * |---------------------|-----------|----------|-------------------------------|
+     * | `productIdentifier` | `string`  | Yes      | Variant ID or SKU             |
+     * | `productIdType`     | `string`  | Yes      | Identifier type               |
+     * | `currency`          | `string`  | No       | Currency for prices           |
+     * | `withoutPrice`      | `boolean` | No       | Exclude price calculation     |
+     *
+     * @example
+     * ```typescript
+     * const offers = await client.product.getProductVariantOffers({
+     *   productIdentifier: 'LAPTOP-PRO-15-BLACK',
+     *   productIdType: 'sku',
+     *   currency: 'EUR',
+     * });
+     *
+     * offers.forEach(offer => {
+     *   console.log(`${offer.supplierName}: ${offer.price} ${offer.currency}`);
+     *   console.log(`  Stock: ${offer.stock}, Delivery: ${offer.deliveryTime}`);
+     * });
+     * ```
+     *
+     * @param params - Variant identification parameters
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If required parameters are missing
+     * @returns List of offers from all suppliers
+     */
+    getProductVariantOffers(params: GetProductVariantOffersParams, context?: RequestContext): Promise<GetProductVariantOffersResponse>;
+    /**
+     * Get list of suppliers offering a specific product variant.
+     *
+     * **Endpoint**: `GET /v1/shop/product-variants/{id}/suppliers [PROD-104]`
+     *
+     * | Parameter          | Type     | Required | Description          |
+     * |--------------------|----------|----------|----------------------|
+     * | `productVariantId` | `string` | Yes      | Product variant ID   |
+     *
+     * @example
+     * ```typescript
+     * const suppliers = await client.product.getProductVariantSuppliers({
+     *   productVariantId: '123e4567-e89b-12d3-a456-426614174000',
+     * });
+     *
+     * suppliers.forEach(supplier => {
+     *   console.log(`${supplier.name} - ${supplier.rating} stars`);
+     * });
+     * ```
+     *
+     * @param params - Variant identification
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If productVariantId is missing
+     * @returns List of suppliers with their details
+     */
+    getProductVariantSuppliers(params: GetProductVariantSuppliersParams, context?: RequestContext): Promise<GetProductVariantSuppliersResponse>;
+    /**
+     * Get all offers for a product (all variants).
+     *
+     * @deprecated Use `getProductPaginatedOffers` for better performance
+     *
+     * **Endpoint**: `GET /v1/shop/products/{identifier}/offers [PROD-105]`
+     *
+     * @param params - Product identification parameters
+     * @param context - Optional SSR request context
+     * @returns List of all offers
+     */
+    getProductOffers(params: GetProductOffersParams, context?: RequestContext): Promise<GetProductOffersResponse>;
+    /**
+     * Get paginated offers for a product.
+     *
+     * Recommended method for fetching product offers with pagination support.
+     *
+     * **Endpoint**: `GET /v1/shop/products/{identifier}/offers/paginated [PROD-106]`
+     *
+     * | Parameter           | Type             | Required | Description              |
+     * |---------------------|------------------|----------|--------------------------|
+     * | `productIdentifier` | `string`         | Yes      | Product ID or SKU        |
+     * | `productIdType`     | `string`         | Yes      | Identifier type          |
+     * | `currency`          | `string`         | No       | Currency for prices      |
+     * | `locale`            | `string`         | No       | Locale for translations  |
+     * | `withoutPrices`     | `boolean`        | No       | Exclude price data       |
+     * | `pageable`          | `PageableParams` | No       | Pagination settings      |
+     *
+     * @example
+     * ```typescript
+     * const { content: offers, totalElements } = await client.product.getProductPaginatedOffers({
+     *   productIdentifier: 'LAPTOP-PRO-15',
+     *   productIdType: 'sku',
+     *   currency: 'EUR',
+     *   pageable: { page: 0, size: 10, sort: 'price,asc' },
+     * });
+     *
+     * console.log(`Found ${totalElements} offers`);
+     * ```
+     *
+     * @param params - Product and pagination parameters
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If required parameters are missing
+     * @returns Paginated offers list
+     */
+    getProductPaginatedOffers(params: GetProductPaginatedOffersParams, context?: RequestContext): Promise<GetProductPaginatedOffersResponse>;
+    /**
+     * Get related/recommended products.
+     *
+     * Returns products related to the specified product, useful for
+     * "You may also like" or cross-sell sections.
+     *
+     * **Endpoint**: `GET /v1/shop/products/{identifier}/related [PROD-107]`
+     *
+     * | Parameter           | Type             | Required | Description              |
+     * |---------------------|------------------|----------|--------------------------|
+     * | `productIdentifier` | `string`         | Yes      | Product ID or SKU        |
+     * | `productIdType`     | `string`         | Yes      | Identifier type          |
+     * | `locale`            | `string`         | No       | Locale for translations  |
+     * | `currency`          | `string`         | No       | Currency for prices      |
+     * | `pageable`          | `PageableParams` | No       | Pagination settings      |
+     *
+     * @example
+     * ```typescript
+     * const relatedProducts = await client.product.getRelatedProducts({
+     *   productIdentifier: 'LAPTOP-PRO-15',
+     *   productIdType: 'sku',
+     *   locale: 'en-US',
+     *   currency: 'USD',
+     *   pageable: { page: 0, size: 4 },
+     * });
+     * ```
+     *
+     * @param params - Product identification and pagination
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If required parameters are missing
+     * @returns List of related products
+     */
+    getRelatedProducts(params: GetRelatedProductsParams, context?: RequestContext): Promise<GetRelatedProductsResponse>;
+    /**
+     * Get customer reviews for a product.
+     *
+     * **Endpoint**: `GET /v1/shop/products/{identifier}/reviews [PROD-108]`
+     *
+     * | Parameter           | Type     | Required | Description              |
+     * |---------------------|----------|----------|--------------------------|
+     * | `productIdentifier` | `string` | Yes      | Product ID or SKU        |
+     * | `productIdType`     | `string` | Yes      | Identifier type          |
+     *
+     * @example
+     * ```typescript
+     * const reviews = await client.product.getProductReviews({
+     *   productIdentifier: 'LAPTOP-PRO-15',
+     *   productIdType: 'sku',
+     * });
+     *
+     * reviews.forEach(review => {
+     *   console.log(`${review.rating}/5 - ${review.message}`);
+     *   console.log(`By ${review.authorName} on ${review.createdAt}`);
+     * });
+     * ```
+     *
+     * @param params - Product identification parameters
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If required parameters are missing
+     * @returns List of product reviews
+     */
+    getProductReviews(params: GetProductReviewsParams, context?: RequestContext): Promise<GetProductReviewsResponse>;
+    /**
+     * Get review statistics for a product.
+     *
+     * Returns aggregated statistics including average rating and
+     * rating distribution.
+     *
+     * **Endpoint**: `GET /v1/shop/products/{identifier}/reviews/stats [PROD-109]`
+     *
+     * | Parameter           | Type     | Required | Description              |
+     * |---------------------|----------|----------|--------------------------|
+     * | `productIdentifier` | `string` | Yes      | Product ID or SKU        |
+     * | `productIdType`     | `string` | Yes      | Identifier type          |
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.product.getProductStatReviews({
+     *   productIdentifier: 'LAPTOP-PRO-15',
+     *   productIdType: 'sku',
+     * });
+     *
+     * console.log(`Average: ${stats.averageRating}/5`);
+     * console.log(`Total reviews: ${stats.totalReviews}`);
+     * console.log(`5 stars: ${stats.distribution[5]} reviews`);
+     * ```
+     *
+     * @param params - Product identification parameters
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If required parameters are missing
+     * @returns Review statistics with distribution
+     */
+    getProductStatReviews(params: GetProductStatReviewsParams, context?: RequestContext): Promise<GetProductStatReviewsResponse>;
+    /**
+     * Get attributes for a product variant.
+     *
+     * Returns variant-specific attributes like color, size, material, etc.
+     *
+     * **Endpoint**: `GET /v1/shop/products/{identifier}/variant-attributes [PROD-110]`
+     *
+     * | Parameter           | Type     | Required | Description              |
+     * |---------------------|----------|----------|--------------------------|
+     * | `productIdentifier` | `string` | Yes      | Product/variant ID       |
+     * | `productIdType`     | `string` | Yes      | Identifier type          |
+     * | `locale`            | `string` | No       | Locale for translations  |
+     *
+     * @example
+     * ```typescript
+     * const attributes = await client.product.getProductVariantAttributes({
+     *   productIdentifier: 'LAPTOP-PRO-15-BLACK',
+     *   productIdType: 'sku',
+     *   locale: 'en-US',
+     * });
+     *
+     * attributes.forEach(attr => {
+     *   console.log(`${attr.name}: ${attr.value}`);
+     * });
+     * ```
+     *
+     * @param params - Variant identification parameters
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If required parameters are missing
+     * @returns List of variant attributes
+     */
+    getProductVariantAttributes(params: GetProductVariantAttributesParams, context?: RequestContext): Promise<GetProductVariantAttributesResponse>;
+    /**
+     * Create a new product review.
+     *
+     * Allows authenticated customers to submit reviews for purchased products.
+     *
+     * **Endpoint**: `POST /v1/shop/product-reviews [PROD-111]`
+     *
+     * | Parameter    | Type     | Required | Description                    |
+     * |--------------|----------|----------|--------------------------------|
+     * | `productSku` | `string` | Yes      | Product SKU being reviewed     |
+     * | `rating`     | `number` | Yes      | Rating from 1 to 5             |
+     * | `message`    | `string` | Yes      | Review text content            |
+     *
+     * @example
+     * ```typescript
+     * const review = await client.product.createProductReview({
+     *   productSku: 'LAPTOP-PRO-15',
+     *   rating: 5,
+     *   message: 'Excellent laptop! Great performance and build quality.',
+     * });
+     *
+     * console.log(`Review created with ID: ${review.id}`);
+     * ```
+     *
+     * @param params - Review content parameters
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If required parameters are missing
+     * @throws {AuthError} If user is not authenticated
+     * @returns Created review details
+     */
+    createProductReview(params: CreateProductReviewParams, context?: RequestContext): Promise<CreateProductReviewResponse>;
+    /**
+     * Update an existing product review.
+     *
+     * Allows users to modify their own reviews.
+     *
+     * **Endpoint**: `PUT /v1/shop/product-reviews/{reviewId} [PROD-112]`
+     *
+     * | Parameter         | Type     | Required | Description              |
+     * |-------------------|----------|----------|--------------------------|
+     * | `productReviewId` | `string` | Yes      | Review ID to update      |
+     * | `rating`          | `number` | Yes      | New rating (1-5)         |
+     * | `message`         | `string` | Yes      | New review text          |
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.product.updateProductReview({
+     *   productReviewId: 'review-123',
+     *   rating: 4,
+     *   message: 'Updated review after more usage. Still great, minor issues.',
+     * });
+     * ```
+     *
+     * @param params - Review update parameters
+     * @param context - Optional SSR request context
+     * @throws {ValidationError} If required parameters are missing
+     * @throws {AuthError} If user is not the review author
+     * @throws {NotFoundError} If review doesn't exist
+     * @returns Updated review details
+     */
+    updateProductReview(params: UpdateProductReviewParams, context?: RequestContext): Promise<UpdateProductReviewResponse>;
+}
+//# sourceMappingURL=product.service.d.ts.map

package/lib/services/product/product.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"product.service.d.ts","sourceRoot":"","sources":["../../../src/services/product/product.service.ts"],"names":[],"mappings":"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"}