@liquidcommerce/elements-sdk 2.6.0-beta.9 → 2.6.0-beta.91

package/docs/v1/api/actions/product-actions.md

@@ -0,0 +1,204 @@
+# Product Actions API
+
+Product actions allow you to programmatically retrieve product information.
+
+## actions.product.getDetails()
+
+Retrieve details of a loaded product.
+
+### Signature
+
+```typescript
+getDetails(identifier: string): IBaseProductEventData
+```
+
+### Parameters
+
+| Parameter    | Type   | Required | Description             |
+|--------------|--------|----------|-------------------------|
+| `identifier` | string | Yes      | Product UPC, SKU, or ID |
+
+### Returns
+
+```typescript
+// Inherits all IProduct fields except `sizes` (see below for the overridden `sizes` shape)
+interface IBaseProductEventData {
+  identifier: string;
+  name: string;
+  description: string;
+  priceInfo: IProductPriceInfo | null;  // { currency, minimum, average, maximum }
+  selectedSizeId: string | null;
+  selectedFulfillmentType: FulfillmentType;
+  selectedFulfillmentId: string | null;
+  productHasAvailability: boolean;
+  fulfillmentHasAvailability: boolean;
+  sizes: Record<string, IProductSizeEventData>;
+  images: string[];
+  brand: string;
+  category: string;
+  // ... additional IProduct fields
+}
+```
+
+### Example
+
+```javascript
+const productData = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
+
+console.log(productData.name);        // "Premium Whiskey"
+console.log(productData.priceInfo?.minimum / 100); // 49.99
+console.log(productData.sizes[productData.selectedSizeId]?.size); // "750ml"
+console.log(productData.selectedSizeId); // "size_123"
+```
+
+### Errors
+
+**Throws `SDKError` if:**
+- Identifier is empty or invalid
+- Product has not been loaded yet (a non-existent product surfaces as this same error)
+
+```javascript
+try {
+  const data = window.LiquidCommerce.elements.actions.product.getDetails('invalid_id');
+} catch (error) {
+  console.error('Product not found:', error.message);
+}
+```
+
+### Use Cases
+
+#### Display Product Info Elsewhere
+
+```javascript
+const product = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
+
+document.getElementById('product-name').textContent = product.name;
+document.getElementById('product-price').textContent = `$${product.priceInfo?.minimum / 100}`;
+```
+
+#### Sync with Analytics
+
+```javascript
+window.addEventListener('lce:actions.product_loaded', () => {
+  const product = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
+  
+  gtag('event', 'view_item', {
+    items: [{
+      item_id: product.identifier,
+      item_name: product.name,
+      price: product.priceInfo?.minimum / 100,
+      item_brand: product.brand
+    }]
+  });
+});
+```
+
+#### Custom Product Comparison
+
+```javascript
+const product1 = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
+const product2 = window.LiquidCommerce.elements.actions.product.getDetails('08504405135');
+
+if (product1.priceInfo?.minimum < product2.priceInfo?.minimum) {
+  console.log(`${product1.name} is cheaper`);
+}
+```
+
+---
+
+## actions.product.getProductAvailabilityByState()
+
+Check product availability across states.
+
+### Signature
+
+```typescript
+getProductAvailabilityByState(
+  identifiers: string[],
+  state?: string
+): Promise<IProductAvailabilityResponse>
+```
+
+### Parameters
+
+| Parameter     | Type     | Required | Description                              |
+|---------------|----------|----------|------------------------------------------|
+| `identifiers` | string[] | Yes      | Array of product UPCs, SKUs, or IDs      |
+| `state`       | string   | No       | Two-letter state code (e.g., `'NY'`)     |
+
+### Returns
+
+Resolves to an `IProductAvailabilityResponse`:
+
+```typescript
+interface IProductAvailabilityResponse {
+  products: IProduct[];
+  retailers: Record<string /* retailer ID */, IRetailer>;
+}
+
+interface IRetailer {
+  id: string;
+  name: string;
+  address: IRetailerAddress;          // IAddressAddress & IAddressCoordinates
+  addressFormatted: string;
+  shippingFulfillment: IFulfillment | null;
+  onDemandFulfillment: IFulfillment | null;
+}
+
+interface IFulfillment {
+  id: string;
+  type: FulfillmentType;              // 'shipping' | 'onDemand'
+  doesAllowGiftCards: boolean;
+  doesAllowPromos: boolean;
+  expectation: string;
+  engravingExpectation: string;
+  fee: number;
+  timezone: string;
+  hourStatus: { isOpen: boolean; openTime: string; isClosed: boolean; closeTime: string };
+}
+
+interface IProduct {
+  id: string; name: string; description: string; htmlDescription: string;
+  images: string[]; brand: string; region: string; country: string;
+  material: string; abv: string; proof: string; age: string; color: string;
+  flavor: string; variety: string; appellation: string; vintage: string;
+  tastingNotes: string; catPath: string; category: string; classification: string;
+  type: string; subType: string; salsifyGrouping: string;
+  priceInfo: IProductPriceInfo | null;  // { currency, minimum, average, maximum } — cents
+  sizes: Record<string /* size ID */, IProductSize>;
+}
+```
+
+### Example
+
+```javascript
+// Check availability in a specific state
+const availabilityCA = await window.LiquidCommerce.elements.actions.product
+  .getProductAvailabilityByState(['00619947000020', '08504405135'], 'CA');
+
+// Omit the state to query without a state filter
+// (state: undefined is sent — the SDK does NOT derive it from the stored address)
+const availability = await window.LiquidCommerce.elements.actions.product
+  .getProductAvailabilityByState(['00619947000020']);
+```
+
+### Errors
+
+**Throws `SDKError` if:**
+- No identifiers provided or array is empty
+- API request fails
+
+---
+
+## Notes
+
+- Product must be injected and loaded before calling `getDetails()`
+- `getDetails()` is synchronous - returns immediately
+- `getProductAvailabilityByState()` is async - returns a Promise
+- Prices are always in cents (divide by 100 for dollars)
+- Selected values reflect current user selection in the component
+
+## See Also
+
+- [Product Component Guide](../../guides/product-component.md)
+- [Product Events](../../guides/events.md#product-events)

package/docs/v1/api/client.md

@@ -0,0 +1,517 @@
+# Client API
+
+The Elements client is the main interface for interacting with the SDK. It provides methods for injecting components, managing UI elements, and performing actions.
+
+## Initialization
+
+### Elements()
+
+Initialize the full SDK client.
+
+```typescript
+function Elements(
+  apiKey: string,
+  config: ILiquidCommerceElementsConfig
+): Promise<ILiquidCommerceElementsClient | null>
+```
+
+**Parameters:**
+
+| Parameter | Type                          | Required | Description                 |
+|-----------|-------------------------------|----------|-----------------------------|
+| `apiKey`  | string                        | Yes      | Your LiquidCommerce API key |
+| `config`  | ILiquidCommerceElementsConfig | Yes      | Configuration object        |
+
+**Returns:** Promise that resolves to the client instance, or `null` if initialization fails.
+
+**Example:**
+
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  debugMode: 'console',
+  customTheme: { /* theme config */ }
+});
+```
+
+### ElementsCheckout()
+
+Initialize the checkout-only client (tree-shaken build).
+
+```typescript
+function ElementsCheckout(
+  apiKey: string,
+  config: ILiquidCommerceElementsCheckoutClientConfig
+): Promise<IElementsCheckoutClient | null>
+```
+
+**Parameters:**
+
+| Parameter | Type                                        | Required | Description                 |
+|-----------|---------------------------------------------|----------|-----------------------------|
+| `apiKey`  | string                                      | Yes      | Your LiquidCommerce API key |
+| `config`  | ILiquidCommerceElementsCheckoutClientConfig | Yes      | Checkout configuration      |
+
+**Example:**
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+
+const client = await ElementsCheckout('YOUR_API_KEY', {
+  env: 'production'
+});
+```
+
+### ElementsBuilder()
+
+Initialize the builder client, which exposes manual `inject*` / `update*` methods for fully programmatic composition.
+
+```typescript
+function ElementsBuilder(
+  apiKey: string,
+  config: ILiquidCommerceElementsBuilderConfig
+): Promise<ILiquidCommerceElementsBuilderClient | null>
+```
+
+**Parameters:**
+
+| Parameter | Type                                 | Required | Description                 |
+|-----------|--------------------------------------|----------|-----------------------------|
+| `apiKey`  | string                               | Yes      | Your LiquidCommerce API key |
+| `config`  | ILiquidCommerceElementsBuilderConfig | Yes      | Builder configuration object (same shape as `ILiquidCommerceElementsConfig`) |
+
+**Returns:** Promise that resolves to the builder client instance (`ILiquidCommerceElementsBuilderClient`), or `null` if initialization fails or it is called outside the browser.
+
+**Example:**
+
+```javascript
+import { ElementsBuilder } from '@liquidcommerce/elements-sdk';
+
+const builder = await ElementsBuilder('YOUR_API_KEY', {
+  env: 'production'
+});
+```
+
+## Configuration
+
+### ILiquidCommerceElementsConfig
+
+Complete configuration interface for the full SDK.
+
+```typescript
+interface ILiquidCommerceElementsConfig {
+  // Optional
+  env?: ElementsEnv;  // defaults to 'production' ('development' | 'staging' | 'production')
+  debugMode?: DebugMode;  // 'none' | 'console' | 'panel'
+  customTheme?: IClientCustomThemeConfig;
+  promoTicker?: IPromoTicker[];
+  proxy?: IElementsProxyConfig;
+  checkout?: ILiquidCommerceElementsCheckoutConfig;
+  development?: ILiquidCommerceElementsDevelopmentConfig;
+}
+```
+
+#### Environment
+
+```typescript
+type ElementsEnv = 'development' | 'staging' | 'production';
+```
+
+Determines which API environment to use.
+
+#### Debug Mode
+
+```typescript
+type DebugMode = 'none' | 'console' | 'panel';
+```
+
+- `'none'`: No debug output (production default)
+- `'console'`: Log debug info to browser console
+- `'panel'`: Show debug panel on page
+
+#### Custom Theme
+
+```typescript
+interface IClientCustomThemeConfig {
+  global?: UpdateComponentGlobalConfigs;
+  product?: UpdateProductComponent;
+  address?: UpdateAddressComponent;
+  cart?: UpdateCartComponent;
+  checkout?: UpdateCheckoutComponent;
+  productList?: UpdateProductListComponent;
+}
+```
+
+See [Configuration Reference](./configuration.md) for detailed theme options.
+
+#### Promo Ticker
+
+```typescript
+interface IPromoTicker {
+  promoCode: string;
+  text: string[];
+  separator: string;
+  activeFrom: string;  // ISO 8601 UTC format
+  activeUntil: string;  // ISO 8601 UTC format
+}
+```
+
+**Example:**
+
+```javascript
+promoTicker: [{
+  promoCode: 'SUMMER20',
+  text: ['20% Off Summer Sale', 'Free Shipping on $50+'],
+  separator: '•',
+  activeFrom: '2026-06-01T00:00:00Z',
+  activeUntil: '2026-08-31T23:59:59Z'
+}]
+```
+
+#### Proxy Configuration
+
+```typescript
+interface IElementsProxyConfig {
+  baseUrl: string;
+  headers?: Record<string, string>;
+}
+```
+
+**Example:**
+
+```javascript
+proxy: {
+  baseUrl: 'https://yoursite.com/api/elements-proxy',
+  headers: {
+    'X-Custom-Header': 'value'
+  }
+}
+```
+
+See [Proxy Setup Guide](../integration/proxy-setup.md) for implementation.
+
+#### Checkout Configuration
+
+```typescript
+interface ILiquidCommerceElementsCheckoutConfig {
+  pageUrl?: string;  // Optional. URL pattern with {token} placeholder
+}
+```
+
+**Example:**
+
+```javascript
+checkout: {
+  pageUrl: 'https://yoursite.com/checkout?lce_checkout={token}'
+}
+```
+
+#### Development Configuration
+
+```typescript
+interface ILiquidCommerceElementsDevelopmentConfig {
+  customApiUrl?: string;
+  openShadowDom?: boolean;
+  mockMode?: boolean;  // enable mock data responses (sends 'X-Liquid-Api-Mock-Mode' header)
+}
+```
+
+**Example:**
+
+```javascript
+development: {
+  customApiUrl: 'http://localhost:3000/api',
+  openShadowDom: true  // Use an OPEN (inspectable) Shadow DOM instead of the default closed mode; forced off in production
+}
+```
+
+## Global Access
+
+After initialization, each client is available globally under the `window.LiquidCommerce` namespace:
+
+```javascript
+window.LiquidCommerce.elements          // full client (from Elements())
+window.LiquidCommerce.elementsBuilder   // builder client (from ElementsBuilder())
+window.LiquidCommerce.elementsCheckout  // checkout-only client (from ElementsCheckout())
+```
+
+This allows access from anywhere in your application:
+
+```javascript
+// From any script
+window.LiquidCommerce.elements.actions.cart.openCart();
+```
+
+## Client Ready Event
+
+Listen for client initialization:
+
+```javascript
+window.addEventListener('lce:actions.client_ready', ( event ) => {
+  const { isReady, version, timestamp } = event.detail.data;
+
+  console.log(`Elements SDK v${version} ready`);
+
+  // Safe to use client
+  window.LiquidCommerce.elements.injectProductElement([...]);
+});
+```
+
+## Client Interface
+
+### ILiquidCommerceElementsClient
+
+The main client interface:
+
+```typescript
+interface ILiquidCommerceElementsClient {
+  // Injection methods
+  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 methods
+  ui: ILiquidCommerceElementsUIMethod;
+
+  // Actions
+  actions: ILiquidCommerceElementsActions;
+
+  // Component management
+  getInjectedComponents(): Map<string, IInjectedComponent>;
+
+  // Cleanup
+  destroy(): void;
+}
+```
+
+## Methods Overview
+
+### Injection Methods
+
+- `injectProductElement()` - Inject product displays
+- `injectAddressElement()` - Inject address input
+- `injectCartElement()` - Inject cart (rarely needed)
+- `injectCheckoutElement()` - Inject checkout
+- `injectProductList()` - Inject product catalog
+- `injectProductListSearch()` - Inject search box
+- `injectProductListFilters()` - Inject filter panel
+
+See [Injection Methods](./injection-methods.md) for details.
+
+### UI Methods
+
+- `ui.cartButton()` - Add cart button
+- `ui.floatingCartButton()` - Add floating cart button
+- `ui.cartSubtotal()` - Display cart subtotal
+- `ui.cartItemsCount()` - Display item count
+
+See [UI Helpers](./ui-helpers.md) for details.
+
+### Actions
+
+- `actions.product.*` - Product actions
+- `actions.address.*` - Address actions
+- `actions.cart.*` - Cart actions
+- `actions.checkout.*` - Checkout actions
+
+See [Actions](./actions/) for details.
+
+### Component Management
+
+```javascript
+// Get all injected components
+const components = client.getInjectedComponents();
+
+// Get specific component
+const productComponent = components.get('product-1');
+
+// Component methods
+productComponent.getType();      // 'product'
+productComponent.getElement();   // <div id="product-1">...</div>
+productComponent.rerender();     // Force rerender
+productComponent.destroy();      // Remove from DOM and clean up
+```
+
+### destroy()
+
+Remove the client and all injected components, cleaning up event listeners and internal state.
+
+```javascript
+client.destroy();
+```
+
+## Error Handling
+
+### SDKError
+
+All SDK errors use the custom `SDKError` class:
+
+```typescript
+class SDKError extends Error {
+  constructor(message: string, reThrow?: boolean);
+
+  name: 'SDKError';
+  isSdk: boolean;
+  reThrow: boolean;
+}
+```
+### Catching Errors
+
+```javascript
+try {
+  await client.injectProductElement([
+    { containerId: 'product', identifier: 'invalid_id' }
+  ]);
+} catch (error) {
+  if (error.name === 'SDKError') {
+    console.error('SDK Error:', error);
+  }
+}
+```
+
+### Error Isolation
+
+The SDK catches and contains its own errors:
+
+```javascript
+// Even if SDK throws, your app continues
+window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid */]);
+
+// Your code still runs
+console.log('App still working');
+```
+
+## TypeScript Support
+
+### Importing Types
+
+```typescript
+import { Elements } from '@liquidcommerce/elements-sdk';
+import type {
+  ILiquidCommerceElementsClient,
+  ILiquidCommerceElementsConfig,
+  IInjectProductElement,
+  IInjectedComponent
+} from '@liquidcommerce/elements-sdk';
+
+const config: ILiquidCommerceElementsConfig = {
+  env: 'production'
+};
+
+const client: ILiquidCommerceElementsClient = await Elements('KEY', config);
+```
+
+### Type Exports
+
+All public interfaces are exported from the main package:
+
+```typescript
+import type {
+  // Client types
+  ILiquidCommerceElementsClient,
+  ILiquidCommerceElementsConfig,
+
+  // Injection types
+  IInjectProductElement,
+  IInjectCheckoutParams,
+  IInjectedComponent,
+
+  // Configuration types
+  IClientCustomThemeConfig,
+  IComponentGlobalConfigs,
+  IProductComponent,
+  ICartComponent,
+  ICheckoutComponent,
+  IAddressComponent,
+
+  // Enum types
+  ElementsEnv,
+  DebugMode,
+  FulfillmentType,
+  ComponentType
+} from '@liquidcommerce/elements-sdk';
+```
+
+See [TypeScript Types](./typescript-types.md) for complete type reference.
+
+## Best Practices
+
+### Single Client Instance
+
+Create one client instance and reuse it:
+
+```javascript
+// Good
+const client = await Elements('KEY', { env: 'production' });
+await client.injectProductElement([...]);
+await client.injectCartElement('cart');
+
+// Bad - creates multiple instances
+await Elements('KEY', { env: 'production' });
+await Elements('KEY', { env: 'production' });
+```
+
+### Use Global Access
+
+After initialization, use `window.LiquidCommerce.elements`:
+
+```javascript
+// Initialize once
+await Elements('KEY', { env: 'production' });
+
+// Use globally
+window.LiquidCommerce.elements.actions.cart.openCart();
+window.LiquidCommerce.elements.ui.cartButton('cart-btn');
+```
+
+### Check Client Ready
+
+Wait for client ready before using:
+
+```javascript
+if (window.LiquidCommerce?.elements) {
+  // Client is ready
+  window.LiquidCommerce.elements.actions.cart.openCart();
+} else {
+  // Wait for client ready
+  window.addEventListener('lce:actions.client_ready', () => {
+    window.LiquidCommerce.elements.actions.cart.openCart();
+  });
+}
+```
+
+### Handle Initialization Failures
+
+```javascript
+const client = await Elements('KEY', { env: 'production' });
+
+if (!client) {
+  console.error('Failed to initialize Elements SDK');
+  // Show fallback UI or error message
+  showErrorPage();
+  return;
+}
+
+// Client initialized successfully
+await client.injectProductElement([...]);
+```
+
+## See Also
+
+- [Injection Methods](./injection-methods.md) - Component injection API
+- [UI Helpers](./ui-helpers.md) - UI helper methods
+- [Actions](./actions/) - Action APIs
+- [Configuration](./configuration.md) - Configuration options
+- [TypeScript Types](./typescript-types.md) - Type definitions