Client Overview

The Commerce Engine TypeScript SDK provides type-safe, token-managed clients for all API domains. Each client automatically handles authentication, token refresh, and provides complete TypeScript support.

​

Why Use SDK Clients?

​

Available Clients

Each client provides the same methods as the corresponding API endpoints, but with enhanced developer experience:

​

AuthClient

Implements: Authentication API endpoints
Key Features: Automatic token refresh, session management, passwordless flows
Storefront Guide: Authentication Best Practices

const authResult = await client.auth.loginWithEmail({
  email: "[email protected]",
  register_if_not_exists: true
});

if (authResult.success) {
  // Token automatically updated in storage
  console.log("Logged in:", authResult.data.user);
}

​

CatalogClient

Implements: Catalog API endpoints
Key Features: Product search, filtering, recommendations with full type safety
Storefront Guide: Catalog Management

const products = await client.catalog.listProducts({
  limit: 20,
  category_id: "cat_123"
});

if (products.success) {
  // Fully typed product objects
  products.data.forEach(product => {
    console.log(product.name, product.selling_price);
  });
}

​

CartClient

Implements: Cart API endpoints
Key Features: Cart state management, automatic price calculations, promotion handling
Storefront Guide: Cart Management

const cartResult = await client.cart.createCart({
  items: [{ product_id: "prod_123", variant_id: null, quantity: 1 }]
});

if (cartResult.success) {
  // Cart with calculated totals, taxes, shipping
  console.log("Total:", cartResult.data.grand_total);
}

​

CustomerClient

Implements: Customer API endpoints
Key Features: Profile management, address book, loyalty tracking
Storefront Guide: Account Management

​

OrderClient

Implements: Order API endpoints
Key Features: Order creation, tracking, returns, payment status

​

ShippingClient

Implements: Shipping API endpoints
Key Features: Serviceability checks, shipping methods, cost calculation

​

HelpersClient

Implements: Common API endpoints
Key Features: Country/state data, validation utilities, location services

​

SDK vs Direct API Calls

// Automatic token management, type safety, error handling
const products = await client.catalog.listProducts({
  limit: 20,
  category_id: "electronics"
});

if (products.success) {
  // Full IntelliSense support
  products.data.forEach(product => {
    console.log(product.name); // ✅ Type-safe
  });
} else {
  // Typed error handling
  console.error(products.error.message);
}

// Automatic token management, type safety, error handling
const products = await client.catalog.listProducts({
  limit: 20,
  category_id: "electronics"
});

if (products.success) {
  // Full IntelliSense support
  products.data.forEach(product => {
    console.log(product.name); // ✅ Type-safe
  });
} else {
  // Typed error handling
  console.error(products.error.message);
}

// Manual token management, no type safety
const response = await fetch('/catalog/products?limit=20&category_id=electronics', {
  headers: {
    'Authorization': `Bearer ${await getValidToken()}`, // Manual token handling
    'Content-Type': 'application/json'
  }
});

const data = await response.json(); // ❌ No type safety
if (response.ok) {
  data.forEach((product: any) => { // ❌ Any type
    console.log(product.name);
  });
} else {
  console.error(data.message); // ❌ Unknown error structure
}

​

Cross-References

Each SDK client method corresponds directly to API endpoints documented in the API Reference. The SDK provides the same functionality with enhanced developer experience:

• Complete API Documentation: API Reference with live playground
• Business Logic & Patterns: Storefront Guides for e-commerce workflows
• SDK-Specific Features: Type safety, automatic token management, error handling