Relevant source files

The following files were used as context for generating this wiki page: - [src/services/checkout/CheckoutFlow.ts](https://github.com/VpkDevs/MarketSage/blob/main/src/services/checkout/CheckoutFlow.ts) - [src/services/checkout/PlatformHandlers.ts](https://github.com/VpkDevs/MarketSage/blob/main/src/services/checkout/PlatformHandlers.ts) - [src/common/models/unifiedClient/UnifiedBrowserManager.ts](https://github.com/VpkDevs/MarketSage/blob/main/src/common/models/unifiedClient/UnifiedBrowserManager.ts) - [src/common/types/index.ts](https://github.com/VpkDevs/MarketSage/blob/main/src/common/types/index.ts) - [tests/e2e/userScenarios.test.ts](https://github.com/VpkDevs/MarketSage/blob/main/tests/e2e/userScenarios.test.ts)

# Checkout & Platform Handlers ## Introduction The **Checkout & Platform Handlers** system is a core component of the MarketSage platform designed to orchestrate the transition from a unified shopping experience to platform-specific purchase fulfillment. Since MarketSage aggregates products from multiple marketplaces like AliExpress, Temu, and DHGate, this system manages the complexity of split-cart checkouts and guided browser automation. The primary purpose of this module is to group items by their respective platforms, validate cart data, and generate the necessary URLs or instructions to lead the user through a sequential checkout process. It acts as the bridge between the [Unified Browser Manager](#unified-browser-management) and the external marketplace web environments. Sources: [src/services/checkout/CheckoutFlow.ts](), [src/common/models/unifiedClient/UnifiedBrowserManager.ts:169-188]() ## System Architecture & Data Flow The architecture follows a hierarchical structure where the `UnifiedBrowserManager` initiates the session, the `CheckoutFlow` manages the UI and sequence, and individual `PlatformHandlers` manage the specifics of each marketplace. ### Unified Checkout Flow The process begins by converting the unified cart into a checkout session where items are grouped by their origin platform. ```mermaid flowchart TD UC[Unified Cart] --> GP[Group by Platform] GP --> CS[Create Checkout Session] CS --> CF[CheckoutFlow Controller] CF --> PH[Platform-Specific Handlers] PH --> TU[Temu URL Generation] PH --> AE[AliExpress URL Generation] PH --> DH[DHGate URL Generation] TU & AE & DH --> UI[Guided Checkout UI] ``` Sources: [src/common/models/unifiedClient/UnifiedBrowserManager.ts:169-195](), [src/services/checkout/CheckoutFlow.ts:16-27]() ### Checkout Session Lifecycle A checkout session tracks the progress across multiple platforms simultaneously. | Field | Type | Description | | :--- | :--- | :--- | | `sessionId` | `string` | Unique identifier for the checkout attempt. | | `platforms` | `PlatformCheckout[]` | Status and items for each individual marketplace. | | `status` | `string` | Overall session status: `started`, `in-progress`, `completed`, `failed`. | | `startedAt` | `number` | Unix timestamp of session initiation. | Sources: [src/common/models/unifiedClient/UnifiedBrowserManager.ts:47-53]() ## Component Breakdown ### Platform Handlers The system utilizes an abstract base class pattern to ensure consistent validation and URL generation across different marketplaces. Each handler is responsible for enforcing platform-specific constraints such as maximum items per request or URL length limits. ```mermaid classDiagram class PlatformHandler { <> +validateItems(items: CartItem[]) +prepareCheckout(items: CartItem[]) Promise~string~ } class BasePlatformHandler { <> #BASE_URL: string #MAX_ITEMS_PER_REQUEST: number #URL_MAX_LENGTH: number +validateItems(items: CartItem[]) #handleTruncation(items: CartItem[]) } class TemuHandler { +prepareCheckout(items: CartItem[]) } class AliExpressHandler { +prepareCheckout(items: CartItem[]) } class DHGateHandler { +prepareCheckout(items: CartItem[]) } PlatformHandler <|.. BasePlatformHandler BasePlatformHandler <|-- TemuHandler BasePlatformHandler <|-- AliExpressHandler BasePlatformHandler <|-- DHGateHandler ``` Sources: [src/services/checkout/PlatformHandlers.ts:25-50]() ### Execution Logic: CheckoutFlow The `CheckoutFlow` class manages the state machine for the user's browser tabs and instructions. It ensures that the user is not overwhelmed by multiple checkouts at once by processing platforms sequentially. ```mermaid sequenceDiagram participant CF as CheckoutFlow participant UI as Checkout UI participant PH as PlatformHandler participant BT as Browser Tab CF->>CF: groupItemsByPlatform() CF->>UI: initializeCheckoutUI(groups) loop For each Platform Group CF->>UI: showInstructions(platform) CF->>PH: prepareCheckout(items) PH-->>CF: return checkoutUrl CF->>BT: openPlatformTab(url) CF->>CF: monitorCheckoutProgress() CF->>UI: completeStep(platform) end ``` Sources: [src/services/checkout/CheckoutFlow.ts:16-36]() ## Platform-Specific Configurations Each platform has unique constraints that the handlers must respect to prevent errors during the external checkout process. | Platform | Base URL | Max Items | Key Parameters | | :--- | :--- | :--- | :--- | | **Temu** | `https://www.temu.com/cart/bulk-add` | 100 | `id`, `qty`, `var` | | **AliExpress** | `https://cart.aliexpress.com/add_cart_items` | 50 | `sku`, `quantity`, `seller` | | **DHGate** | `https://www.dhgate.com/cart.do` | 30 | `act`, `pid`, `qty`, `var` | Sources: [src/services/checkout/PlatformHandlers.ts:88-166]() ## Cart Validation Logic Before any checkout session is initiated, the items undergo strict validation to ensure data integrity and prevent API failures on the target marketplaces. 1. **Empty Check**: Ensures the cart is not empty. 2. **Identity Verification**: Validates that every item has a non-empty `id`. 3. **Quantity Constraints**: Checks that quantity is an integer, at least 1, and does not exceed the `MAX_QUANTITY_PER_ITEM` (default: 999). 4. **Price Safety**: Validates that price, if provided, is a non-negative number. 5. **URL Length**: Ensures the generated query string does not exceed 2048 characters to prevent browser truncation. Sources: [src/services/checkout/PlatformHandlers.ts:33-65]() ```typescript // Example of validation logic in BasePlatformHandler validateItems(items: CartItem[]): void { if (!items?.length) { throw new CartValidationError('No items provided for checkout'); } items.forEach((item, index) => { if (!item.id?.trim()) { throw new CartValidationError(`Item at index ${index} has invalid ID`); } if (!Number.isInteger(item.quantity) || item.quantity < 1) { throw new CartValidationError(`Item ${item.id} has invalid quantity`); } }); } ``` Sources: [src/services/checkout/PlatformHandlers.ts:33-47]() ## Conclusion The Checkout & Platform Handlers system provides a robust and scalable way to handle multi-marketplace transactions. By abstracting platform-specific logic into dedicated handlers and managing the user journey through a centralized flow, MarketSage ensures that users can purchase products from diverse sources with a consistent, guided experience while maintaining technical compliance with various marketplace APIs.