# TypeScript Types Reference

All public types are exported from the main package entry point. Import them using the `type` keyword for optimal tree-shaking.

## Importing Types

```typescript
import { Elements } from '@liquidcommerce/elements-sdk';
import type {
  ILiquidCommerceElementsClient,
  ILiquidCommerceElementsConfig,
  IInjectProductElement,
  IInjectedComponent
} from '@liquidcommerce/elements-sdk';
```

For the checkout-only build:

```typescript
import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
import type {
  IElementsCheckoutClient,
  IElementsCheckoutActions,
  ILiquidCommerceElementsCheckoutClientConfig,
  IInjectedComponent
} from '@liquidcommerce/elements-sdk/checkout';
```

---

## Client Types

### ILiquidCommerceElementsClient

Main SDK client interface returned by `Elements()`.

```typescript
interface ILiquidCommerceElementsClient {
  injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>;
  injectAddressElement(containerId: string, options?: IAddressOptions): Promise<IInjectedComponent | null>;
  injectCartElement(containerId: string): Promise<IInjectedComponent | null>;
  injectCheckoutElement(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>;
  injectProductList(params: IInjectProductListParams): Promise<void>;
  injectProductListSearch(params: IInjectProductListSearchParams): Promise<void>;
  injectProductListFilters(params: IInjectProductListFiltersParams): Promise<void>;
  ui: ILiquidCommerceElementsUIMethod;
  actions: ILiquidCommerceElementsActions;
  getInjectedComponents(): Map<string, IInjectedComponent>;
  destroy(): void;
}
```

### ILiquidCommerceElementsBuilderClient

Builder-pattern client interface returned by `ElementsBuilder()`.

```typescript
interface ILiquidCommerceElementsBuilderClient {
  updateComponentGlobalConfigs(configs: UpdateComponentGlobalConfigs): Promise<void>;
  updateProductComponent(configs: UpdateProductComponent): Promise<void>;
  updateAddressComponent(configs: UpdateAddressComponent): void;
  updateCartComponent(configs: UpdateCartComponent): void;
  updateCheckoutComponent(configs: UpdateCheckoutComponent): void;
  updateProductListComponent(configs: UpdateProductListComponent): void;
  injectElement(params: IBuilderInjectElementParams): Promise<IInjectedComponent | null>;
  injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>;
  injectAddressElement(containerId: string, options?: IAddressOptions): Promise<IInjectedComponent | null>;
  injectCartElement(containerId: string): Promise<IInjectedComponent | null>;
  injectCheckoutElement(params: IInjectCheckoutBuilderParams): Promise<IInjectedComponent | null>;
  injectProductList(params: IInjectProductListParams): Promise<void>;
  actions: ILiquidCommerceElementsActions;
  destroy(): void;
}
```

### IElementsCheckoutClient

Checkout-only client interface returned by `ElementsCheckout()`.

```typescript
interface IElementsCheckoutClient {
  injectCheckout(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>;
  actions: { checkout: IElementsCheckoutActions };
  destroy(): void;
}
```

---

## Configuration Types

### ILiquidCommerceElementsConfig

```typescript
interface ILiquidCommerceElementsConfig {
  env?: ElementsEnv;
  promoTicker?: IPromoTicker[];
  customTheme?: IClientCustomThemeConfig;
  debugMode?: DebugMode;
  checkout?: ILiquidCommerceElementsCheckoutConfig;
  proxy?: IElementsProxyConfig;
  development?: ILiquidCommerceElementsDevelopmentConfig;
}
```

### ILiquidCommerceElementsBuilderConfig

Same shape as `ILiquidCommerceElementsConfig`, used by `ElementsBuilder()`.

### ILiquidCommerceElementsCheckoutClientConfig

Same shape as `ILiquidCommerceElementsConfig`, used for the checkout-only client.

### IClientCustomThemeConfig

```typescript
interface IClientCustomThemeConfig {
  global?: UpdateComponentGlobalConfigs;
  product?: UpdateProductComponent;
  address?: UpdateAddressComponent;
  cart?: UpdateCartComponent;
  checkout?: UpdateCheckoutComponent;
  productList?: UpdateProductListComponent;
}
```

### IElementsProxyConfig

```typescript
interface IElementsProxyConfig {
  baseUrl: string;
  headers?: Record<string, string>;
}
```

### ILiquidCommerceElementsDevelopmentConfig

```typescript
interface ILiquidCommerceElementsDevelopmentConfig {
  customApiUrl?: string;
  openShadowDom?: boolean;
  mockMode?: boolean;  // when true, sends an 'X-Liquid-Api-Mock-Mode' header to receive mock data
}
```

### ILiquidCommerceElementsCheckoutConfig

```typescript
interface ILiquidCommerceElementsCheckoutConfig {
  pageUrl?: string;
}
```

See [Configuration Reference](./configuration.md) for detailed property descriptions.

---

## Injection Types

### IInjectProductElement

```typescript
interface IInjectProductElement {
  containerId: string;
  identifier: string;
}
```

### IInjectCheckoutParams

```typescript
interface IInjectCheckoutParams {
  containerId: string;
  checkoutId?: string;
  hideHeader?: boolean;
}
```

### IInjectCheckoutBuilderParams

```typescript
interface IInjectCheckoutBuilderParams extends IInjectCheckoutParams {
  simulatePresale?: boolean;
  presaleExpiresInMinutes?: number;
}
```

### IInjectProductListParams

```typescript
interface IInjectProductListParams {
  containerId: string;
  slug: string;
  rows?: number;
  columns?: number;
  filters?: ProductListFilterType[];
  productUrl?: PLCProductUrl;
}
```

### PLCProductUrl

```typescript
/**
 * Product card link configuration.
 *
 * - String: template with `{upc}` (selected size's UPC) or `{grouping}`
 *   (product's salsifyGrouping ID). Replaced per product card.
 * - Map: keyed by product identifier (UPC or salsifyGrouping ID — same
 *   identifier types accepted by `injectProductElement`). The card looks up
 *   UPC first, then grouping ID. Use this when partner PDPs have
 *   hand-curated URLs that aren't derivable from a single token.
 */
type PLCProductUrl = string | Record<string, string>;
```

### IInjectProductListSearchParams

```typescript
interface IInjectProductListSearchParams {
  containerId: string;
  slug: string;
  filters?: ProductListFilterType[];
}
```

### IInjectProductListFiltersParams

```typescript
interface IInjectProductListFiltersParams {
  containerId: string;
  slug: string;
  filters?: ProductListFilterType[];
}
```

### IBuilderInjectElementParams

```typescript
interface IBuilderInjectElementParams {
  type: ComponentType;
  containerId: string;
  [key: string]: any;
}
```

---

## Component Types

### IInjectedComponent

Returned by all injection methods. Provides control over the injected component.

```typescript
interface IInjectedComponent {
  getType(): ComponentType;
  getElement(): HTMLElement;
  rerender(): void;
  destroy(): void;
}
```

---

## UI Types

### ILiquidCommerceElementsUIMethod

```typescript
interface ILiquidCommerceElementsUIMethod {
  cartButton(containerId: string, showItemsCount?: boolean): void;
  floatingCartButton(showItemsCount?: boolean): void;
  cartSubtotal(elementId: string): void;
  cartItemsCount(elementId: string, options?: { hideZero: boolean }): void;
}
```

---

## Action Types

### ILiquidCommerceElementsActions

```typescript
interface ILiquidCommerceElementsActions {
  product: IProductActions;
  address: IAddressActions;
  cart: ICartActions;
  checkout: ICheckoutActions;
}
```

### IElementsCheckoutActions

Checkout actions available in the checkout-only client. Omits drawer-related methods.

```typescript
interface IElementsCheckoutActions extends Omit<ICheckoutActions, 'openCheckout' | 'closeCheckout' | 'toggleCheckout'> {}
```

See [Actions API](./actions/) for detailed method signatures.

---

## Enum Types

### ElementsEnv

```typescript
type ElementsEnv = 'development' | 'staging' | 'production';
```

### DebugMode

```typescript
type DebugMode = 'none' | 'console' | 'panel';
```

### FulfillmentType

```typescript
type FulfillmentType = 'onDemand' | 'shipping';
```

### ComponentType

```typescript
type ComponentType =
  | 'address' | 'product' | 'cart' | 'checkout'
  | 'product-list' | 'product-list-card' | 'product-list-filters' | 'product-list-search'
  | 'drawer' | 'input' | 'engraving-form' | 'engraving-view'
  | 'buttons-cart-open' | 'powered-by' | 'lce-element'
  | 'purchase-min-alert' | 'alert' | 'promo-code-ticker'
  // ...and additional internal component types
```

### DisplayModeType

```typescript
type DisplayModeType = 'modal' | 'drawer';
```

---

## Theme Configuration Types

### UpdateComponentGlobalConfigs

`DeepPartial<IComponentGlobalConfigs>` -- all properties optional.

### UpdateProductComponent

`DeepPartial<IProductComponent>` -- all properties optional.

### UpdateCartComponent

`DeepPartial<ICartComponent>` -- all properties optional.

### UpdateCheckoutComponent

`DeepPartial<ICheckoutComponent>` -- all properties optional.

### UpdateAddressComponent

`DeepPartial<IAddressComponent>` -- all properties optional.

### UpdateProductListComponent

Special structure for updating product list configuration by slug:

```typescript
interface UpdateProductListComponent {
  theme?: { backgroundColor?: string };
  layout?: {
    lists?: Record<string, DeepPartial<IPLCList>>;
  };
}
```

See [Configuration Reference](./configuration.md) for detailed theme property descriptions.

---

## Promo Ticker Type

### IPromoTicker

```typescript
interface IPromoTicker {
  promoCode: string;
  text: string[];
  separator: string;
  activeFrom: string;   // ISO 8601 UTC
  activeUntil: string;  // ISO 8601 UTC
}
```

---

## Utility Types

### DeepPartial

Used internally for theme update types. Makes all properties in `T` recursively optional.

```typescript
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};
```

---

## See Also

- [Client API](./client.md) - Client initialization and usage
- [Configuration Reference](./configuration.md) - Detailed config options
- [Injection Methods](./injection-methods.md) - Component injection API