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

# TypeScript Types

> Complete type definitions for the SDK

The SDK is written in TypeScript and exports all type definitions. Install via npm to get full IntelliSense support.

<Info>
  All async SDK methods return `SDKResponse<T>` — a wrapper containing `data`, `error`, and `status` fields.
  See the **Response** tab below for the full definition.
</Info>

<Tabs>
  <Tab title="Config">
    ## Configuration Types

    ```typescript theme={"system"}
    interface ShoppexConfig {
      storeSlug: string;
      locale?: string;
      currency?: string;
      apiBaseUrl?: string;
    }

    interface ShoppexInitOptions {
      locale?: string;
      currency?: string;
      apiBaseUrl?: string;
    }
    ```
  </Tab>

  <Tab title="Response">
    ## API Response Types

    ```typescript theme={"system"}
    interface SDKResponse<T> {
      success: boolean;
      data?: T;
      message?: string;
    }
    ```
  </Tab>

  <Tab title="Store">
    ## Store Types

    ```typescript theme={"system"}
    interface Shop {
      id: string;
      name: string;
      slug: string;
      domain?: string;
      description?: string;
      currency: string;
      logo?: string;
      banner?: string;
      rating?: number;
      tos_enabled?: boolean;
    }
    ```
  </Tab>

  <Tab title="Product">
    ## Product Types

    ```typescript theme={"system"}
    interface ProductCategory {
      uniqid: string;
      title: string;
    }

    interface Product {
      uniqid: string;
      title: string;
      slug?: string;
      description?: string;
      price: string;           // String for precision
      price_display?: string;  // Formatted display price
      currency: string;
      stock?: number;
      cdn_image_url?: string | null;    // Card/listing/search image
      detail_image_url?: string | null; // PDP/gallery/zoom image
      images: ProductImage[];
      variants?: ProductVariant[];
      addons?: ProductAddon[];
      price_variants?: PriceVariant[];
      custom_fields?: string | unknown[] | null;
      categories?: ProductCategory[];
    }

    interface ProductImage {
      id: string;
      url: string;
      cloudflare_image_id?: string;
      alt?: string;
    }

    interface ProductVariant {
      id: string;
      title: string;
      price?: number;
      stock?: number;
    }

    interface ProductAddon {
      id: string;
      name: string;
      price: number;
      required?: boolean;
    }

    interface PriceVariant {
      id: string;
      label: string;
      price: number;
    }

    interface CustomFieldDefinition {
      id: string;
      name: string;
      type: 'text' | 'textarea' | 'select' | 'checkbox';
      required?: boolean;
      options?: string[];
    }
    ```

    <Info>
      Image fields have different jobs:

      * `cdn_image_url` is the optimized storefront cover for cards and lists
      * `detail_image_url` is the higher-resolution primary image for product detail pages
      * `images[]` contains the gallery

      If you run a headless storefront, you should normally keep cards on `cdn_image_url` and switch your PDP hero/gallery to `detail_image_url`.
    </Info>
  </Tab>

  <Tab title="Cart">
    ## Cart Types

    ```typescript theme={"system"}
    interface CartItem {
      product_id: string;
      variant_id: string;
      quantity: number;
      addons?: CartAddon[];
      custom_fields?: Record<string, string>;
      price_variant_id?: string;
    }

    interface CartAddon {
      id: string;
      quantity?: number;
    }

    interface CartAddOptions {
      addons?: CartAddon[];
      custom_fields?: Record<string, string>;
      price_variant_id?: string;
    }

    interface CartUpdateOptions {
      quantity?: number;
      addons?: CartAddon[];
      custom_fields?: Record<string, string>;
      price_variant_id?: string;
    }
    ```
  </Tab>

  <Tab title="Checkout">
    ## Checkout Types

    ```typescript theme={"system"}
    interface CheckoutOptions {
      autoRedirect?: boolean;
      locale?: string;
    }

    interface CheckoutResult {
      success: boolean;
      redirectUrl?: string;
      message?: string;
    }

    interface CouponValidation {
      valid: boolean;
      discount?: number;
      discount_type?: 'percentage' | 'fixed';
      message?: string;
    }
    ```

    ## Invoice Types

    ```typescript theme={"system"}
    interface Invoice {
      uniqid: string;
      status: string;
      total: number;
      currency: string;
      gateway?: string;
      products: InvoiceProduct[];
      created_at: string;
    }

    interface InvoiceProduct {
      product_id: string;
      title: string;
      quantity: number;
      price: number;
    }
    ```

    ## Review Types

    ```typescript theme={"system"}
    interface Feedback {
      id: string;
      rating: number;
      comment?: string;
      created_at: string;
    }
    ```
  </Tab>

  <Tab title="Error">
    ## Error Types

    ```typescript theme={"system"}
    class ShoppexError extends Error {
      readonly code: string;
      readonly statusCode?: number;
    }

    class NotInitializedError extends ShoppexError {
      // Thrown when SDK methods are called before init()
      // code: 'NOT_INITIALIZED'
    }

    class NetworkError extends ShoppexError {
      // Thrown on HTTP/network failures
      // code: 'NETWORK_ERROR'
    }

    class ValidationError extends ShoppexError {
      // Thrown on input validation failures
      // code: 'VALIDATION_ERROR'
      readonly invalidFields?: string[];
    }

    class CartError extends ShoppexError {
      // Thrown on cart operation errors
      // code: 'BASKET_ERROR'
    }
    ```
  </Tab>
</Tabs>

## Usage with TypeScript

```typescript theme={"system"}
import shoppex, {
  type Product,
  type ProductVariant,
  type CartItem,
  type Invoice,
  type SDKResponse
} from '@shoppexio/storefront';

// Initialize
shoppex.init('my-store');

// Typed responses
async function loadProducts(): Promise<Product[]> {
  const response: SDKResponse<Product[]> = await shoppex.getProducts();

  if (!response.success || !response.data) {
    throw new Error(response.message || 'Failed to load products');
  }

  return response.data;
}

// Type-safe cart operations
function addProductToCart(product: Product, variant?: ProductVariant): void {
  shoppex.addToCart(
    product.uniqid,
    variant?.id ?? '',
    1
  );
}

// Typed invoice handling
async function checkOrderStatus(invoiceId: string): Promise<string> {
  const { data } = await shoppex.getInvoiceStatus(invoiceId);
  return data.status;
}
```

<Tip>
  See the individual API reference pages for detailed usage examples of each type:
  [Products](/sdk/api/products), [Cart](/sdk/api/cart), [Checkout](/sdk/api/checkout), and [Store](/sdk/api/store).
</Tip>