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

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

@@ -0,0 +1,443 @@
+/**
+ * # Cart Service
+ *
+ * This module provides all functionalities related to shopping cart management.
+ *
+ * ## Features:
+ * - 🛒 Create, retrieve, update, and delete carts
+ * - 📦 Manage cart lines (add, update, remove items)
+ * - 💳 Initialize orders from carts (checkout)
+ * - 📋 Support for buying lists
+ *
+ * Each method is described with its input parameters, output responses, and example usages.
+ *
+ * @module services/cart
+ * @since 2.17.0
+ */
+import { BaseService } from "../base.service";
+import type { RequestContext } from "../../client/transport";
+import type { GetCartsParams, CreateCartParams, DeleteCartParams, GetCartParams, UpdateCartParams, InitializeOrdersParams, GetCartLinesParams, UpdateCartLinesParams, UpdateCartLinesByVariantParams, DeleteCartLinesParams, GetCartsResponse, CreateCartResponse, GetCartResponse, DeleteCartsResponse, GetCartLinesResponse, UpdateCartLinesResponse, UpdateCartLinesByVariantResponse, DeleteCartLinesResponse } from "./types";
+/**
+ * Service for shopping cart operations.
+ *
+ * Provides comprehensive cart management capabilities:
+ * - 🛒 Cart CRUD operations
+ * - 📦 Cart line management
+ * - 💳 Checkout functionality
+ * - 📋 Buying list support
+ *
+ * @example
+ * ```typescript
+ * import { createDjustClient } from '@djust-b2b/djust-front-sdk';
+ *
+ * const client = createDjustClient({
+ *   baseUrl: 'https://api.djust.io',
+ *   clientId: 'your-client-id',
+ *   apiKey: 'your-api-key',
+ * });
+ *
+ * // Create a cart
+ * const cart = await client.cart.createCart({ name: 'My Cart' });
+ *
+ * // Add items
+ * await client.cart.updateCartLines({
+ *   cartId: cart.id,
+ *   linesToUpdate: [{ offerPriceId: 'offer-1', quantity: 2, updateAction: 'add' }],
+ * });
+ *
+ * // Checkout
+ * const orderId = await client.cart.initializeOrders({ cartId: cart.id });
+ * ```
+ */
+export declare class CartService extends BaseService {
+    readonly serviceName = "cart";
+    /**
+     * 🗑️ Deletes all carts associated with the user.
+     *
+     * This method sends a request to delete all carts of the logged-in user.
+     *
+     * 🛠 **Endpoint**: `DELETE /v2/shop/carts [CART-135]`
+     *
+     * | Parameter | Type | Required | Description |
+     * |-----------|------|----------|-------------|
+     * | *(none)*  | -    | -        | This method does not require any parameters. |
+     *
+     * 📤 **Returns**:
+     * A `Promise<DeleteCartsResponse>` containing the details of the deleted carts.
+     *
+     * @example
+     * ```typescript
+     * const deletedCarts = await client.cart.deleteCarts();
+     * console.log(`Deleted ${deletedCarts.length} carts`);
+     * ```
+     *
+     * @param context - Optional request context for SSR.
+     * @returns An array of objects containing the details of the deleted carts.
+     */
+    deleteCarts(context?: RequestContext): Promise<DeleteCartsResponse>;
+    /**
+     * 🛒 Retrieves all active carts of the logged-in user.
+     *
+     * This method allows fetching the list of active carts based on the provided parameters.
+     *
+     * 🛠 **Endpoint**: `GET /v2/shop/carts [CART-550]`
+     *
+     * | Parameter   | Type              | Required | Description                                      |
+     * |-------------|-------------------|----------|--------------------------------------------------|
+     * | `currency`  | `string`          | ✅       | The currency in which to display the carts.      |
+     * | `pageable`  | `PageableParams`  | ✅       | The pagination parameters (page, size, sort).    |
+     * | `status`    | `CartStatus[]`    | ❌       | Filter by cart status.                           |
+     * | `type`      | `CartType[]`      | ❌       | Filter by cart type (CART, BUYING_LIST).         |
+     *
+     * 📤 **Returns**:
+     * A `Promise<GetCartsResponse>` containing the paginated list of carts.
+     *
+     * @example
+     * ```typescript
+     * const { content: carts, totalElements } = await client.cart.getCarts({
+     *   currency: 'EUR',
+     *   pageable: { page: 0, size: 10 },
+     * });
+     *
+     * console.log(`Found ${totalElements} carts`);
+     * carts.forEach(cart => console.log(cart.name));
+     * ```
+     *
+     * @param params - The parameters for retrieving the carts.
+     * @param context - Optional request context for SSR.
+     * @throws {ValidationError} If required parameters are missing.
+     * @returns A paginated response containing the list of carts.
+     */
+    getCarts(params: GetCartsParams, context?: RequestContext): Promise<GetCartsResponse>;
+    /**
+     * 🛒 Creates a new cart.
+     *
+     * This method creates a new shopping cart or buying list with the specified name.
+     *
+     * 🛠 **Endpoint**: `POST /v2/shop/carts [CART-100]`
+     *
+     * | Parameter | Type        | Required | Description                                           |
+     * |-----------|-------------|----------|-------------------------------------------------------|
+     * | `name`    | `string`    | ✅       | The name of the cart to create.                       |
+     * | `type`    | `CartType`  | ❌       | The type: `CART` (default) or `BUYING_LIST`.          |
+     *
+     * 📤 **Returns**:
+     * A `Promise<CreateCartResponse>` containing the created cart details.
+     *
+     * @example
+     * ```typescript
+     * // Create a standard cart
+     * const cart = await client.cart.createCart({
+     *   name: 'My Shopping Cart',
+     * });
+     *
+     * // Create a buying list
+     * const buyingList = await client.cart.createCart({
+     *   name: 'Weekly Supplies',
+     *   type: 'BUYING_LIST',
+     * });
+     * ```
+     *
+     * @param params - The parameters for creating the cart.
+     * @param context - Optional request context for SSR.
+     * @throws {ValidationError} If the `name` parameter is missing.
+     * @returns The created cart object.
+     */
+    createCart(params: CreateCartParams, context?: RequestContext): Promise<CreateCartResponse>;
+    /**
+     * 🗑️ Deletes a specific cart.
+     *
+     * This method deletes the cart identified by its ID.
+     *
+     * 🛠 **Endpoint**: `DELETE /v2/shop/carts/{cartId} [CART-136]`
+     *
+     * | Parameter | Type     | Required | Description                    |
+     * |-----------|----------|----------|--------------------------------|
+     * | `cartId`  | `string` | ✅       | The unique identifier of the cart to delete. |
+     *
+     * 📤 **Returns**:
+     * A `Promise<void>` that resolves when the cart is successfully deleted.
+     *
+     * @example
+     * ```typescript
+     * await client.cart.deleteCart({
+     *   cartId: '123e4567-e89b-12d3-a456-426614174000',
+     * });
+     * console.log('Cart deleted successfully');
+     * ```
+     *
+     * @param params - The parameters for deleting the cart.
+     * @param context - Optional request context for SSR.
+     * @throws {ValidationError} If the `cartId` parameter is missing.
+     * @throws {NotFoundError} If the cart is not found.
+     */
+    deleteCart(params: DeleteCartParams, context?: RequestContext): Promise<void>;
+    /**
+     * 🛒 Retrieves a specific cart with its details.
+     *
+     * This method fetches detailed information about a cart, including its lines and pricing.
+     *
+     * 🛠 **Endpoint**: `GET /v2/shop/carts/{cartId} [CART-551]`
+     *
+     * | Parameter      | Type     | Required | Description                                      |
+     * |----------------|----------|----------|--------------------------------------------------|
+     * | `cartId`       | `string` | ✅       | The unique identifier of the cart.               |
+     * | `currency`     | `string` | ✅       | The currency in which to display prices.         |
+     * | `nbFirstLines` | `number` | ❌       | Number of first lines to include in response.    |
+     *
+     * 📤 **Returns**:
+     * A `Promise<GetCartResponse>` containing the cart details with lines and pricing.
+     *
+     * @example
+     * ```typescript
+     * const cart = await client.cart.getCart({
+     *   cartId: '123e4567-e89b-12d3-a456-426614174000',
+     *   currency: 'EUR',
+     *   nbFirstLines: 5,
+     * });
+     *
+     * console.log(`Cart: ${cart.name}`);
+     * console.log(`Total: ${cart.totalPrice} ${cart.currency}`);
+     * console.log(`Items: ${cart.lines.length}`);
+     * ```
+     *
+     * @param params - The parameters for retrieving the cart.
+     * @param context - Optional request context for SSR.
+     * @throws {ValidationError} If required parameters are missing.
+     * @throws {NotFoundError} If the cart is not found.
+     * @returns The cart details with lines and pricing.
+     */
+    getCart(params: GetCartParams, context?: RequestContext): Promise<GetCartResponse>;
+    /**
+     * ✏️ Updates a cart's name or type.
+     *
+     * This method allows updating the name and/or type of an existing cart.
+     *
+     * 🛠 **Endpoint**: `PUT /v2/shop/carts/{cartId} [CART-101]`
+     *
+     * | Parameter | Type       | Required | Description                              |
+     * |-----------|------------|----------|------------------------------------------|
+     * | `cartId`  | `string`   | ✅       | The unique identifier of the cart.       |
+     * | `name`    | `string`   | ✅       | The new name for the cart.               |
+     * | `type`    | `CartType` | ❌       | The new type (CART or BUYING_LIST).      |
+     *
+     * 📤 **Returns**:
+     * A `Promise<void>` that resolves when the cart is successfully updated.
+     *
+     * @example
+     * ```typescript
+     * await client.cart.updateCart({
+     *   cartId: '123e4567-e89b-12d3-a456-426614174000',
+     *   name: 'Updated Cart Name',
+     * });
+     * ```
+     *
+     * @param params - The parameters for updating the cart.
+     * @param context - Optional request context for SSR.
+     * @throws {ValidationError} If required parameters are missing.
+     * @throws {NotFoundError} If the cart is not found.
+     */
+    updateCart(params: UpdateCartParams, context?: RequestContext): Promise<void>;
+    /**
+     * 💳 Initializes orders from a cart (checkout).
+     *
+     * This method converts a cart into one or more commercial orders.
+     * This is the main checkout operation that triggers order creation.
+     *
+     * 🛠 **Endpoint**: `POST /v2/shop/carts/{cartId}/initialize-orders [CART-110]`
+     *
+     * | Parameter | Type     | Required | Description                              |
+     * |-----------|----------|----------|------------------------------------------|
+     * | `cartId`  | `string` | ✅       | The unique identifier of the cart.       |
+     *
+     * 📤 **Returns**:
+     * A `Promise<string>` containing the created order's business ID.
+     *
+     * ⚠️ **Important**:
+     * - The cart must have valid shipping and billing addresses configured.
+     * - All cart lines must have valid offers.
+     * - Payment method must be set if required.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const orderId = await client.cart.initializeOrders({
+     *     cartId: '123e4567-e89b-12d3-a456-426614174000',
+     *   });
+     *   console.log(`Order created: ${orderId}`);
+     *   // Redirect to order confirmation page
+     * } catch (error) {
+     *   console.error('Checkout failed:', error.message);
+     * }
+     * ```
+     *
+     * @param params - The parameters for initializing orders.
+     * @param context - Optional request context for SSR.
+     * @throws {ValidationError} If the `cartId` parameter is missing.
+     * @throws {NotFoundError} If the cart is not found.
+     * @throws {SDKError} If checkout fails (missing address, invalid offers, etc.).
+     * @returns The created order's business ID.
+     */
+    initializeOrders(params: InitializeOrdersParams, context?: RequestContext): Promise<string>;
+    /**
+     * 📦 Retrieves cart lines with pagination.
+     *
+     * This method fetches the items in a cart with optional filtering and pagination.
+     *
+     * 🛠 **Endpoint**: `GET /v2/shop/carts/{cartId}/lines [CART-552]`
+     *
+     * | Parameter          | Type             | Required | Description                                |
+     * |--------------------|------------------|----------|--------------------------------------------|
+     * | `cartId`           | `string`         | ✅       | The unique identifier of the cart.         |
+     * | `currency`         | `string`         | ✅       | The currency for price display.            |
+     * | `pageable`         | `PageableParams` | ✅       | Pagination parameters.                     |
+     * | `supplierId`       | `string`         | ❌       | Filter by supplier.                        |
+     * | `productVariantId` | `string`         | ❌       | Filter by product variant.                 |
+     * | `offerPriceId`     | `string`         | ❌       | Filter by offer price.                     |
+     *
+     * 📤 **Returns**:
+     * A `Promise<GetCartLinesResponse>` containing the paginated list of cart lines.
+     *
+     * @example
+     * ```typescript
+     * const { content: lines, totalElements } = await client.cart.getCartLines({
+     *   cartId: '123e4567-e89b-12d3-a456-426614174000',
+     *   currency: 'EUR',
+     *   pageable: { page: 0, size: 20 },
+     * });
+     *
+     * lines.forEach(line => {
+     *   console.log(`${line.productName}: ${line.quantity} x ${line.unitPrice}`);
+     * });
+     * ```
+     *
+     * @param params - The parameters for retrieving cart lines.
+     * @param context - Optional request context for SSR.
+     * @throws {ValidationError} If required parameters are missing.
+     * @returns A paginated response containing the cart lines.
+     */
+    getCartLines(params: GetCartLinesParams, context?: RequestContext): Promise<GetCartLinesResponse>;
+    /**
+     * ✏️ Updates cart lines (add, update, or remove items).
+     *
+     * This method allows batch operations on cart lines: adding new items,
+     * updating quantities, or removing items.
+     *
+     * 🛠 **Endpoint**: `PUT /v2/shop/carts/{cartId}/lines [CART-102]`
+     *
+     * | Parameter       | Type                | Required | Description                           |
+     * |-----------------|---------------------|----------|---------------------------------------|
+     * | `cartId`        | `string`            | ✅       | The unique identifier of the cart.    |
+     * | `linesToUpdate` | `CartLineToAdd[]`   | ✅       | Array of line updates to apply.       |
+     *
+     * **Line Update Structure**:
+     * | Field          | Type     | Required | Description                             |
+     * |----------------|----------|----------|-----------------------------------------|
+     * | `offerPriceId` | `string` | ✅       | The offer price identifier.             |
+     * | `quantity`     | `number` | ✅       | The quantity to set (0 to remove).      |
+     * | `updateAction` | `string` | ❌       | Action: `add`, `update`, or `delete`.   |
+     *
+     * 📤 **Returns**:
+     * A `Promise<UpdateCartLinesResponse>` with the updated cart lines.
+     *
+     * @example
+     * ```typescript
+     * // Add items to cart
+     * await client.cart.updateCartLines({
+     *   cartId: 'cart-123',
+     *   linesToUpdate: [
+     *     { offerPriceId: 'offer-1', quantity: 2, updateAction: 'add' },
+     *     { offerPriceId: 'offer-2', quantity: 5, updateAction: 'add' },
+     *   ],
+     * });
+     *
+     * // Update quantity
+     * await client.cart.updateCartLines({
+     *   cartId: 'cart-123',
+     *   linesToUpdate: [
+     *     { offerPriceId: 'offer-1', quantity: 10, updateAction: 'update' },
+     *   ],
+     * });
+     *
+     * // Remove item
+     * await client.cart.updateCartLines({
+     *   cartId: 'cart-123',
+     *   linesToUpdate: [
+     *     { offerPriceId: 'offer-2', quantity: 0, updateAction: 'delete' },
+     *   ],
+     * });
+     * ```
+     *
+     * @param params - The parameters for updating cart lines.
+     * @param context - Optional request context for SSR.
+     * @throws {ValidationError} If required parameters are missing.
+     * @throws {NotFoundError} If the cart or offer is not found.
+     * @returns The updated cart lines information.
+     */
+    updateCartLines(params: UpdateCartLinesParams, context?: RequestContext): Promise<UpdateCartLinesResponse>;
+    /**
+     * ✏️ Updates cart lines by product variant.
+     *
+     * This method allows updating cart lines using product variant identifiers
+     * instead of offer price IDs.
+     *
+     * 🛠 **Endpoint**: `PUT /v2/shop/carts/{cartId}/lines-by-variant [CART-103]`
+     *
+     * | Parameter       | Type                      | Required | Description                        |
+     * |-----------------|---------------------------|----------|------------------------------------|
+     * | `cartId`        | `string`                  | ✅       | The unique identifier of the cart. |
+     * | `linesToUpdate` | `CartLineToAddByVariant[]`| ✅       | Array of line updates by variant.  |
+     *
+     * 📤 **Returns**:
+     * A `Promise<UpdateCartLinesByVariantResponse>` with the updated cart lines.
+     *
+     * @example
+     * ```typescript
+     * await client.cart.updateCartLinesByVariant({
+     *   cartId: 'cart-123',
+     *   linesToUpdate: [
+     *     { productVariantId: 'variant-1', quantity: 3 },
+     *     { productVariantId: 'variant-2', quantity: 1 },
+     *   ],
+     * });
+     * ```
+     *
+     * @param params - The parameters for updating cart lines by variant.
+     * @param context - Optional request context for SSR.
+     * @throws {ValidationError} If required parameters are missing.
+     * @returns The updated cart lines information.
+     */
+    updateCartLinesByVariant(params: UpdateCartLinesByVariantParams, context?: RequestContext): Promise<UpdateCartLinesByVariantResponse>;
+    /**
+     * 🗑️ Deletes specific lines from a cart.
+     *
+     * This method removes specific items from a cart by their offer price IDs.
+     *
+     * 🛠 **Endpoint**: `DELETE /v2/shop/carts/{cartId}/lines [CART-137]`
+     *
+     * | Parameter         | Type       | Required | Description                            |
+     * |-------------------|------------|----------|----------------------------------------|
+     * | `cartId`          | `string`   | ✅       | The unique identifier of the cart.     |
+     * | `lineIdsToDelete` | `string[]` | ✅       | Array of offer price IDs to remove.    |
+     *
+     * 📤 **Returns**:
+     * A `Promise<DeleteCartLinesResponse>` with information about deleted lines.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.cart.deleteCartLines({
+     *   cartId: 'cart-123',
+     *   lineIdsToDelete: ['offer-1', 'offer-2', 'offer-3'],
+     * });
+     * console.log(`Deleted ${result.deletedCount} lines`);
+     * ```
+     *
+     * @param params - The parameters for deleting cart lines.
+     * @param context - Optional request context for SSR.
+     * @throws {ValidationError} If required parameters are missing.
+     * @throws {NotFoundError} If the cart is not found.
+     * @returns Information about the deleted lines.
+     */
+    deleteCartLines(params: DeleteCartLinesParams, context?: RequestContext): Promise<DeleteCartLinesResponse>;
+}
+//# sourceMappingURL=cart.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cart.service.d.ts","sourceRoot":"","sources":["../../../src/services/cart/cart.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,8BAA8B,EAC9B,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,gCAAgC,EAChC,uBAAuB,EACxB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,WAAY,SAAQ,WAAW;IAC1C,QAAQ,CAAC,WAAW,UAAU;IAE9B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAUzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,QAAQ,CACZ,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,gBAAgB,CAAC;IAoB5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,UAAU,CACd,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,kBAAkB,CAAC;IAgB9B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,UAAU,CACd,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,OAAO,CACX,MAAM,EAAE,aAAa,EACrB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,eAAe,CAAC;IAgB3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,UAAU,CACd,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;IAgBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACG,gBAAgB,CACpB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,MAAM,CAAC;IAclB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACG,YAAY,CAChB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,oBAAoB,CAAC;IAqBhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;IACG,eAAe,CACnB,MAAM,EAAE,qBAAqB,EAC7B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,uBAAuB,CAAC;IAanC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,wBAAwB,CAC5B,MAAM,EAAE,8BAA8B,EACtC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,gCAAgC,CAAC;IAe5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,eAAe,CACnB,MAAM,EAAE,qBAAqB,EAC7B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,uBAAuB,CAAC;CAcpC"}