npm package: @hoxhaolsi/elements-sdk
Description: elements sdk
Author: LiquidCommerce Tech
Latest version: 0.9.13

# Elements SDK

The Elements SDK is a powerful and flexible toolkit designed to help partners integrate e-commerce components into their websites with minimal effort. By using the Elements SDK, clients with an existing partner account can quickly create a fully functional e-commerce website with just a few lines of code. This SDK is a product of LiquidCommerce, designed to simplify e-commerce integration.

## Key Features

- **Ease of Integration**: Add e-commerce functionality to your website with minimal setup.
- **Customizable Components**: Render and customize components like product detail pages, carts, addresses, and checkout.
- **Event Subscriptions**: Subscribe to various events such as add-to-cart, checkout, and more to enhance interactivity.
- **Preview Mode**: Visualize components in a static, non-functional mode for design and builder tools.

## Installation

### NPM
```bash
pnpm add @liquidcommerce/elements-sdk
```

### Browser
```html
<script id="liquidScriptConfigs" data-liquid-element-id="#product-detail" data-liquid-token="your-elements-api-key" data-liquid-product="your-product-upc" type="text/javascript" src="./elements-script.js"></script>
```

## Usage

### 1. Initialize the SDK
```javascript
import { ElementsSDK } from '@liquidcommerce/elements-sdk';

const API_KEY = 'your-api-key';
const GOOGLE_API_KEY = 'your-google-api-key';
const ELEMENTS_API_KEY = 'your-elements-api-key';

const sdk = ElementsSDK.init({
  apiKey: API_KEY,
  googleApiKey: GOOGLE_API_KEY,
  elementsApiKey: ELEMENTS_API_KEY,
});
```

### 2. Render Components

#### Product Detail Page (PDP)
```html
<div id="product-detail"></div>

<script>
sdk.inject('product-detail', sdk.ComponentType.PDP, {
  upc: 'your-product-upc',
});
</script>
```

#### Cart Component
```html
<div id="cart"></div>

<script>
sdk.inject('cart', sdk.ComponentType.CART, { previewMode: false });
</script>
```

#### Address Component
```html
<div id="address"></div>

<script>
sdk.inject('address', sdk.ComponentType.ADDRESS, {
  previewMode: false,
  injectedByPdp: false,
});
</script>
```

#### Checkout Component
```html
<div id="checkout"></div>

<script>
sdk.inject('checkout', sdk.ComponentType.CHECKOUT, {});
</script>
```

### 3. Preview Mode

Preview mode is designed for visualizing components as static screenshots or mockups. It is not intended for functional usage. To enable preview mode, set `previewMode: true` in the component options. This is typically used in builder tools or design environments.

Example:
```html
<div id="cart"></div>

<script>
sdk.inject('cart', sdk.ComponentType.CART, { previewMode: true });
</script>
```

### 4. Subscriptions

You can subscribe to various events triggered by the SDK components. Below are some examples:

#### Add to Cart Event
```javascript
sdk.subscribe(sdk.EventType.ADD_TO_CART, (data) => {
  console.log('Add to Cart Event:', data);
});
```

#### Checkout Event
```javascript
sdk.subscribe(sdk.EventType.CHECKOUT, (data) => {
  console.log('Checkout Event:', data);
});
```

#### Quantity Decrease Event
```javascript
sdk.subscribe(sdk.EventType.PDP_QTY_DECREASE, (data) => {
  console.log('Quantity Decrease Event:', data);
  console.log('Quantity is:', data.quantity);
});
```

### 5. Window-Based Subscriptions

The SDK also supports a window-based subscription system for additional flexibility.

#### Add to Cart Event
```javascript
window.actions.subscribe(sdk.EventType.ADD_TO_CART, (data) => {
  console.log('Window Actions - Add to Cart:', data);
});
```

#### Quantity Decrease Event
```javascript
window.actions.subscribe(sdk.EventType.PDP_QTY_DECREASE, (data) => {
  console.log('Window Actions - Quantity Decrease:', data);
  console.log('Quantity is:', data.quantity);
});
```

#### Email Input Event
```javascript
window.form.subscribe(sdk.EventType.EMAIL_INPUT, (data) => {
  console.log('Window Form - Email Input:', data);
  console.log('Email is:', data.value);
});
```

## Demos

We provide two demos to help you get started quickly:

### 1. Simple HTML Demo

Navigate to the `demo/umd/` folder and open the `index.html` file in your browser. You can also use a live server to preview the demo.

### 2. React Demo

Navigate to the `demo-react/elements-demo/` folder and follow these steps:

1. Install dependencies:
   ```bash
   npm install
   ```
2. Start the development server:
   ```bash
   npm start
   ```
3. Open the demo in your browser to explore the React-based implementation.

## Development

1. Install dependencies:
```bash
pnpm install
```

2. Start development server:
```bash
pnpm dev
```

3. Build for production:
```bash
pnpm build
```

## License

MIT