@liquidcommerce/elements-sdk 2.6.0-beta.7 → 2.6.0-beta.71

package/docs/v1/api/client.md

@@ -0,0 +1,495 @@
+# 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;
+  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;  // 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 under the `window.LiquidCommerce` namespace:
+
+```javascript
+window.LiquidCommerce.elements
+```
+
+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,
+
+  // 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.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