Checkout & Platform Handlers

Relevant source files

The following files were used as context for generating this wiki page:

• src/services/checkout/CheckoutFlow.ts
• src/services/checkout/PlatformHandlers.ts
• src/common/models/unifiedClient/UnifiedBrowserManager.ts
• src/common/types/index.ts
• tests/e2e/userScenarios.test.ts

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 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.

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.

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.

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

// 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.