@liquidcommerce/elements-sdk 2.7.0 → 2.7.1

package/docs/v1/api/client.md

@@ -0,0 +1,482 @@
+# 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'
+});
+```
+
+## Configuration
+
+### ILiquidCommerceElementsConfig
+
+Complete configuration interface for the full SDK.
+
+```typescript
+interface ILiquidCommerceElementsConfig {
+  // Required
+  env: ElementsEnv;  // 'development' | 'staging' | 'production'
+
+  // Optional
+  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;
+}
+```
+
+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;  // URL pattern with {token} placeholder
+}
+```
+
+**Example:**
+
+```javascript
+checkout: {
+  pageUrl: 'https://yoursite.com/checkout?lce_checkout={token}'
+}
+```
+
+#### Development Configuration
+
+```typescript
+interface ILiquidCommerceElementsDevelopmentConfig {
+  customApiUrl?: string;
+  paymentMethodId?: string;
+  openShadowDom?: boolean;
+}
+```
+
+**Example:**
+
+```javascript
+development: {
+  customApiUrl: 'http://localhost:3000/api',
+  paymentMethodId: 'pm_test_123',  // For testing without Stripe form
+  openShadowDom: true  // Disable Shadow DOM for debugging
+}
+```
+
+## Global Access
+
+After initialization, the client is available globally:
+
+```javascript
+window.elements
+```
+
+This allows access from anywhere in your application:
+
+```javascript
+// From any script
+window.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.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>;
+}
+```
+
+## 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
+```
+
+## 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.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,
+
+  // Action types
+  IProductActions,
+  ICartActions,
+  ICheckoutActions,
+  IAddressActions,
+  IAddProductParams,
+
+  // 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.elements`:
+
+```javascript
+// Initialize once
+await Elements('KEY', { env: 'production' });
+
+// Use globally
+window.elements.actions.cart.openCart();
+window.elements.ui.cartButton('cart-btn');
+```
+
+### Check Client Ready
+
+Wait for client ready before using:
+
+```javascript
+if (window.elements) {
+  // Client is ready
+  window.elements.actions.cart.openCart();
+} else {
+  // Wait for client ready
+  window.addEventListener('lce:actions.client_ready', () => {
+    window.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

package/docs/v1/api/configuration.md

@@ -0,0 +1 @@
+to be created...

package/docs/v1/api/injection-methods.md

@@ -0,0 +1,247 @@
+# Injection Methods API
+
+Methods for injecting SDK components into your page.
+
+## injectProductElement()
+
+Inject one or more product displays.
+
+### Signature
+
+```typescript
+injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductElement {
+  containerId: string;  // ID of container element
+  identifier: string;   // Product Identifier
+}
+```
+
+### Example
+
+```javascript
+await client.injectProductElement([
+  { containerId: 'product-1', identifier: '00619947000020' },
+  { containerId: 'product-2', identifier: '08504405135' }
+]);
+```
+
+### Returns
+
+Array of injected component objects.
+
+---
+
+## injectAddressElement()
+
+Inject standalone address component.
+
+### Signature
+
+```typescript
+injectAddressElement(
+  containerId: string,
+  options?: IAddressOptions
+): Promise<IInjectedComponent | null>
+```
+
+### Example
+
+```javascript
+await client.injectAddressElement('address-container', {
+  onAddressSet: (address) => {
+    console.log('Address set:', address);
+  }
+});
+```
+
+---
+
+## injectCartElement()
+
+Inject standalone cart (rarely needed - cart drawer is automatic).
+
+### Signature
+
+```typescript
+injectCartElement(containerId: string): Promise<IInjectedComponent | null>
+```
+
+### Example
+
+```javascript
+await client.injectCartElement('cart-container');
+```
+
+---
+
+## injectCheckoutElement()
+
+Inject hosted checkout page.
+
+### Signature
+
+```typescript
+injectCheckoutElement(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>
+```
+
+### Parameters
+
+```typescript
+interface IInjectCheckoutParams {
+  containerId: string;
+  checkoutId?: string;   // Optional checkout token to load
+  hideHeader?: boolean;  // Hide checkout header
+}
+```
+
+### Example
+
+```javascript
+await client.injectCheckoutElement({
+  containerId: 'checkout',
+  checkoutId: 'cart_abc123',
+  hideHeader: false
+});
+```
+
+---
+
+## injectProductList()
+
+Inject product catalog/listing.
+
+### Signature
+
+```typescript
+injectProductList(params: IInjectProductListParams): Promise<void>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductListParams {
+  containerId: string;
+  rows?: number;             // Default: 3
+  columns?: number;          // Default: 4
+  filters?: ProductListFilterType[];
+  productUrl?: string;       // URL pattern with {identifier}
+}
+```
+
+### Example
+
+```javascript
+await client.injectProductList({
+  containerId: 'products',
+  rows: 4,
+  columns: 3,
+  filters: ['price', 'brand', 'category'],
+  productUrl: '/product/{identifier}'
+});
+```
+
+---
+
+## injectProductListSearch()
+
+Inject product search box.
+
+### Signature
+
+```typescript
+injectProductListSearch(params: IInjectProductListSearchParams): Promise<void>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductListSearchParams {
+  containerId: string;
+}
+```
+
+### Example
+
+```javascript
+await client.injectProductListSearch({
+  containerId: 'search-box'
+});
+```
+
+---
+
+## injectProductListFilters()
+
+Inject product filter panel.
+
+### Signature
+
+```typescript
+injectProductListFilters(params: IInjectProductListFiltersParams): Promise<void>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductListFiltersParams {
+  containerId: string;
+  filters: ProductListFilterType[];
+}
+```
+
+### Example
+
+```javascript
+await client.injectProductListFilters({
+  containerId: 'filters',
+  filters: ['price', 'brand', 'fulfillment']
+});
+```
+
+---
+
+## Component Management
+
+### getInjectedComponents()
+
+Retrieve all injected components.
+
+```typescript
+getInjectedComponents(): Map<string, IInjectedComponent>
+```
+
+```javascript
+const components = client.getInjectedComponents();
+
+// Get specific component
+const product = components.get('product-1');
+
+// Rerender component
+product.rerender();
+
+// Get container element
+const container = product.getElement();
+
+// Get component type
+const type = product.getType(); // 'product'
+```
+
+### IInjectedComponent Interface
+
+```typescript
+interface IInjectedComponent {
+  getType(): ComponentType;
+  getElement(): HTMLElement;
+  rerender(): void;
+}
+```
+
+## See Also
+
+- [Client API](./client.md)
+- [Component Guides](../guides/)

package/docs/v1/api/typescript-types.md

@@ -0,0 +1 @@
+to be created...