> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Overview

> Overview of SDK clients with type safety and automatic token management

The Commerce Engine TypeScript SDK uses a **public/session split** architecture. Every API domain has a dedicated, type-safe client with automatic token management.

## Public vs Session

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { createStorefront } from "@commercengine/storefront";

const storefront = createStorefront({ /* config */ });

// Public accessor — API-key-backed, no session needed
const publicSdk = storefront.public();
publicSdk.catalog.*   // Products, categories, search
publicSdk.store.*     // Store configuration

// Session accessor — live user session (anonymous or logged-in)
const sdk = storefront.session();
sdk.auth.*            // Authentication & user management
sdk.catalog.*         // Products + reviews (write)
sdk.cart.*            // Cart, wishlist, fulfillment, coupons
sdk.customer.*        // Addresses, loyalty, saved payments
sdk.order.*           // Order creation, tracking, history
sdk.payments.*        // Payment operations
sdk.helpers.*         // Countries, currencies, utilities
```

Use `storefront.public()` for anything that doesn't require a user session (browsing products, fetching store config). Use `storefront.session()` for user-scoped operations (auth, cart, orders).

## Available Clients

### CatalogClient

Available on **both** accessors. The public accessor covers read operations; the session accessor adds write operations like submitting reviews.

**Implements:** [Catalog API](/docs/api-reference/catalog) endpoints\
**Storefront Guide:** [Catalog Management](/docs/storefront/catalog)

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const { data, error } = await storefront.public().catalog.listProducts({
  limit: 20,
  category_id: "cat_123"
});

if (data) {
  data.products.forEach(product => {
    console.log(product.name, product.selling_price);
  });
}
```

### AuthClient

**Accessor:** Session only\
**Implements:** [Authentication API](/docs/api-reference/auth) endpoints\
**Storefront Guide:** [Authentication Best Practices](/docs/storefront/authentication)

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const sdk = storefront.session();
const { data, error } = await sdk.auth.loginWithEmail({
  email: "user@example.com",
  register_if_not_exists: true
});

if (data) {
  console.log("OTP Token:", data.otp_token);
}
```

### CartClient

**Accessor:** Session only\
**Implements:** [Cart API](/docs/api-reference/carts) endpoints\
**Storefront Guide:** [Cart Management](/docs/storefront/cart)

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const sdk = storefront.session();
const { data, error } = await sdk.cart.createCart({
  items: [{ product_id: "prod_123", variant_id: null, quantity: 1 }]
});

if (data) {
  console.log("Total:", data.cart.grand_total);
}
```

### CustomerClient

**Accessor:** Session only\
**Implements:** [Customer API](/docs/api-reference/customers) endpoints\
**Storefront Guide:** [Account Management](/docs/storefront/my-account)

### OrderClient

**Accessor:** Session only\
**Implements:** [Order API](/docs/api-reference/orders) endpoints

### HelpersClient

**Accessor:** Session only\
**Implements:** [Common API](/docs/api-reference/common) endpoints

### StoreClient

**Accessor:** Public only\
**Implements:** Store configuration endpoints

## SDK vs Direct API Calls

<Tabs>
  <Tab title="With SDK">
    ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    // Automatic token management, type safety, error handling
    const { data, error } = await storefront.public().catalog.listProducts({
      limit: 20,
      category_id: "electronics"
    });

    if (data) {
      data.products.forEach(product => {
        console.log(product.name); // ✅ Type-safe
      });
    } else if (error) {
      console.error(error.message);
    }
    ```
  </Tab>

  <Tab title="Direct API Calls">
    ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    // Manual token management, no type safety
    const response = await fetch('/catalog/products?limit=20&category_id=electronics', {
      headers: {
        'Authorization': `Bearer ${await getValidToken()}`,
        '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);
      });
    }
    ```
  </Tab>
</Tabs>

## Cross-References

* **Complete API Documentation:** [API Reference](/docs/api-reference) with live playground
* **Business Logic & Patterns:** [Storefront Guides](/docs/storefront) for e-commerce workflows
* **Error Handling:** [Error Handling Guide](/docs/sdk/error-handling) for error codes and recovery patterns
* **Type Safety:** [Type Safety Guide](/docs/sdk/type-safety) for IntelliSense and generated types