Commerce Engine Developer Portal

The SDK provides 100% type safety with auto-generated types from OpenAPI specifications, complete IntelliSense support, and compile-time error prevention.

Why Type Safety Matters

IntelliSense Support

Complete autocomplete for all API methods, parameters, and response data

Compile-time Checking

Catch errors during development, not at runtime

Self-Documenting Code

Types serve as always up-to-date documentation

Refactoring Safety

Confidently refactor with IDE support for finding all usages

Auto-Generated Types

All types are automatically generated from the OpenAPI specification, ensuring they’re always in sync with the API:

// Types are generated from OpenAPI spec and always current
import type { 
  Product, 
  Cart, 
  Order, 
  Customer,
  ApiResult 
} from '@commercengine/storefront-sdk';

ApiResult Pattern

Every API operation returns a type-safe ApiResult<T>:

// Type signature automatically inferred
const productResult: ApiResult<Product> = await client.catalog.getProduct('id');

if (productResult.success) {
  // TypeScript knows productResult.data is of type Product
  console.log(productResult.data.name); // ✅ string
  console.log(productResult.data.selling_price); // ✅ number
  console.log(productResult.data.images); // ✅ ProductImage[]
} else {
  // TypeScript knows productResult.error is ApiErrorResponse
  console.log(productResult.error.code); // ✅ string
  console.log(productResult.error.message); // ✅ string
}

IntelliSense in Action

Method Parameters

Complete autocomplete for all API parameters:

// IntelliSense shows all available options
const products = await client.catalog.listProducts({
  limit: 20,                    // ✅ number
  category_id: 'electronics',   // ✅ string | undefined
  sort_by: 'price_low_to_high', // ✅ Specific string literals
  min_price: 100,               // ✅ number | undefined
  max_price: 500                // ✅ number | undefined
});

Response Data Access

Full type safety when accessing response data:

if (products.success) {
  products.data.forEach(product => {
    // Full IntelliSense for Product interface
    product.id;              // ✅ string
    product.name;            // ✅ string
    product.selling_price;   // ✅ number
    product.listing_price;   // ✅ number
    product.images;          // ✅ ProductImage[]
    product.category;        // ✅ Category
    product.variants;        // ✅ ProductVariant[]
    
    // TypeScript prevents accessing non-existent properties
    product.nonExistent;     // ❌ Compile error
  });
}

Cart Operations

Type-safe cart management:

// Creating cart with typed item structure
const cart = await client.cart.createCart({
  items: [{
    product_id: 'prod_123',    // ✅ string (required)
    variant_id: null,          // ✅ string | null (required)
    quantity: 2                // ✅ number (required)
  }]
});

if (cart.success) {
  // Cart object with full type safety
  cart.data.id;                    // ✅ string
  cart.data.cart_items;            // ✅ CartItem[]
  cart.data.grand_total;           // ✅ number
  cart.data.currency;              // ✅ Currency
  cart.data.shipping_address;      // ✅ CustomerAddress | null
}

Advanced Type Features

Discriminated Unions

Type-safe handling of different response states:

// ApiResult is a discriminated union
type ApiResult<T> = 
  | { success: true; data: T }
  | { success: false; error: ApiErrorResponse };

// TypeScript narrows types based on success field
const result = await client.auth.loginWithEmail({ email: '[email protected]' });

if (result.success) {
  // TypeScript knows result.data exists and is LoginResponse
  result.data.otp_token;  // ✅ string
  result.error;           // ❌ TypeScript error: doesn't exist
} else {
  // TypeScript knows result.error exists and is ApiErrorResponse  
  result.error.code;      // ✅ string
  result.data;            // ❌ TypeScript error: doesn't exist
}

Generic Type Constraints

Type-safe configuration with constraints:

// TokenStorage interface with generic constraints
interface TokenStorage<T = StoredTokens> {
  getTokens(): Promise<T | null>;
  setTokens(tokens: T): Promise<void>;
  clearTokens(): Promise<void>;
}

// Implementation must satisfy interface
class CustomTokenStorage implements TokenStorage {
  async getTokens(): Promise<StoredTokens | null> {
    // Implementation must return correct type
    return { accessToken: '...', refreshToken: '...' };
  }
  
  // ... other methods with type safety
}

Framework Integration Types

React Hook Types

// Custom hook with full type safety
function useProducts(categoryId?: string): {
  products: Product[] | null;
  loading: boolean;
  error: ApiErrorResponse | null;
} {
  const [products, setProducts] = useState<Product[] | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<ApiErrorResponse | null>(null);
  
  useEffect(() => {
    async function fetchProducts() {
      const result = await client.catalog.listProducts({
        category_id: categoryId,
        limit: 50
      });
      
      if (result.success) {
        setProducts(result.data);     // ✅ Type-safe assignment
      } else {
        setError(result.error);       // ✅ Type-safe error handling
      }
      
      setLoading(false);
    }
    
    fetchProducts();
  }, [categoryId]);
  
  return { products, loading, error };
}

Component Props

// Type-safe component props
interface ProductCardProps {
  product: Product;               // ✅ Generated Product type
  onAddToCart: (productId: string, variantId: string | null) => void;
}

const ProductCard: React.FC<ProductCardProps> = ({ product, onAddToCart }) => {
  return (
    <div>
      <h3>{product.name}</h3>          {/* ✅ Type-safe access */}
      <p>${product.selling_price}</p>  {/* ✅ Known to be number */}
      
      <button onClick={() => onAddToCart(product.id, null)}>
        Add to Cart
      </button>
    </div>
  );
};

Type Utilities

Exported Utility Types

// Import specific types for custom implementations
import type {
  Product,
  Cart,
  CartItem,
  Order,
  Customer,
  ApiResult,
  ApiErrorResponse,
  StoredTokens,
  CommerceEngineConfig
} from '@commercengine/storefront-sdk';

// Use in your application
interface AppState {
  currentUser: Customer | null;
  cart: Cart | null;
  products: Product[];
}

Type Guards

// Type guards for runtime type checking
function isProduct(item: unknown): item is Product {
  return typeof item === 'object' && 
         item !== null && 
         'id' in item && 
         'name' in item;
}

// Usage with type safety
const data: unknown = await fetch('/some-endpoint');
if (isProduct(data)) {
  // TypeScript knows data is Product
  console.log(data.name);
}

Development Experience

IDE Integration

The SDK works seamlessly with popular IDEs:

VSCode: Full IntelliSense, error squiggles, auto-imports
WebStorm: Complete type information, refactoring support
Vim/Neovim: TypeScript LSP provides full type information

Compile-Time Validation

// These errors are caught at compile time, not runtime:

// ❌ Compile error: quantity must be number
await client.cart.createCart({
  items: [{ product_id: 'id', variant_id: null, quantity: '2' }]
});

// ❌ Compile error: invalid property name
const result = await client.catalog.listProducts({
  limite: 20  // Should be 'limit'
});

// ❌ Compile error: accessing wrong property
if (result.success) {
  console.log(result.data.invalidProperty);
}

Type Safety vs Direct API

// Full type safety and IntelliSense
const result = await client.catalog.getProduct('product-id');

if (result.success) {
  // ✅ TypeScript knows exact structure
  const product: Product = result.data;
  console.log(product.name);           // ✅ Known to be string
  console.log(product.selling_price);  // ✅ Known to be number
  console.log(product.images[0].url);  // ✅ Safe array access
} else {
  // ✅ Typed error handling
  console.error(result.error.code);    // ✅ Known error structure
}

// Full type safety and IntelliSense
const result = await client.catalog.getProduct('product-id');

if (result.success) {
  // ✅ TypeScript knows exact structure
  const product: Product = result.data;
  console.log(product.name);           // ✅ Known to be string
  console.log(product.selling_price);  // ✅ Known to be number
  console.log(product.images[0].url);  // ✅ Safe array access
} else {
  // ✅ Typed error handling
  console.error(result.error.code);    // ✅ Known error structure
}

// No type safety - all runtime errors
const response = await fetch('/catalog/products/product-id');
const data = await response.json();

if (response.ok) {
  // ❌ No type information - could fail at runtime
  console.log(data.name);           // Could be undefined
  console.log(data.selling_price);  // Could be string instead of number
  console.log(data.images[0].url);  // Could throw if images is empty
} else {
  // ❌ Unknown error structure
  console.error(data.message);      // Could be different property name
}

Best Practices

Enable Strict TypeScript

Configure TypeScript for maximum type safety:

tsconfig.json

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true
  }
}

Use Type Assertions Sparingly

Prefer type guards over type assertions:

// ❌ Avoid type assertions
const product = data as Product;

// ✅ Use type guards or SDK methods
const result = await client.catalog.getProduct(id);
if (result.success) {
  const product = result.data; // Already typed correctly
}

Leverage Union Types

Handle different states with discriminated unions:

type LoadingState<T> = 
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: ApiErrorResponse };

const [state, setState] = useState<LoadingState<Product[]>>({ 
  status: 'loading' 
});

Migration Benefits

When migrating from direct API calls:

Catch Errors Early

Find API usage errors during development, not production

Better Documentation

Types serve as always-current API documentation

Faster Development

IntelliSense speeds up development with autocomplete

Confident Refactoring

Change APIs with confidence using IDE refactoring tools

All SDK types are automatically generated from the OpenAPI specification, ensuring they’re always accurate and up-to-date with the actual API responses.

Getting Started

Core Features

Framework Integration

Advanced Usage

Type Safety

Why Type Safety Matters

IntelliSense Support

Compile-time Checking

Self-Documenting Code

Refactoring Safety

Auto-Generated Types

ApiResult Pattern

IntelliSense in Action

Method Parameters

Response Data Access

Cart Operations

Advanced Type Features

Discriminated Unions

Generic Type Constraints

Framework Integration Types

React Hook Types

Component Props

Type Utilities

Exported Utility Types

Type Guards

Development Experience

IDE Integration

Compile-Time Validation

Type Safety vs Direct API

Best Practices

Migration Benefits

Catch Errors Early

Better Documentation

Faster Development

Confident Refactoring

Getting Started

Core Features

Framework Integration

Advanced Usage

​Why Type Safety Matters

IntelliSense Support

Compile-time Checking

Self-Documenting Code

Refactoring Safety

​Auto-Generated Types

​ApiResult Pattern

​IntelliSense in Action

​Method Parameters

​Response Data Access

​Cart Operations

​Advanced Type Features

​Discriminated Unions

​Generic Type Constraints

​Framework Integration Types

​React Hook Types

​Component Props

​Type Utilities

​Exported Utility Types

​Type Guards

​Development Experience

​IDE Integration

​Compile-Time Validation

​Type Safety vs Direct API

​Best Practices

​Migration Benefits

Catch Errors Early

Better Documentation

Faster Development

Confident Refactoring

Why Type Safety Matters

Auto-Generated Types

ApiResult Pattern

IntelliSense in Action

Method Parameters

Response Data Access

Cart Operations

Advanced Type Features

Discriminated Unions

Generic Type Constraints

Framework Integration Types

React Hook Types

Component Props

Type Utilities

Exported Utility Types

Type Guards

Development Experience

IDE Integration

Compile-Time Validation

Type Safety vs Direct API

Best Practices

Migration Benefits