@liquidcommerce/elements-sdk 2.6.0-beta.12 → 2.6.0-beta.121

package/docs/v1/api/client.md

@@ -0,0 +1,664 @@
+# 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 | No       | 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 | No       | Checkout configuration      |
+
+**Example:**
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+
+const client = await ElementsCheckout('YOUR_API_KEY', {
+  env: 'production'
+});
+```
+
+The checkout-only client exposes `injectCheckout()`, `injectExpressCheckout()`, `actions.checkout`
+and `destroy()`.
+
+#### injectExpressCheckout()
+
+Injects only the Apple Pay and Google Pay wallet buttons, anywhere on the page, without the rest of
+the checkout UI. Confirming the wallet sheet places the order outright — the wallet's contact and
+billing details are sent to the checkout, so the shopper never fills a checkout form.
+
+```typescript
+injectExpressCheckout(params: IInjectExpressCheckoutParams): Promise<IInjectedComponent | null>
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `containerId` | string | Yes | ID of an element that already exists in the DOM |
+| `checkoutId` | string | No | Checkout token to bind the buttons to. Omit to use the checkout already loaded |
+| `variant` | `'buttons' \| 'section'` | No | `'buttons'` (default) is the wallet row alone; `'section'` adds the "Express Checkout" heading and OR divider |
+
+A checkout is prepared at injection time rather than when a button is tapped: Stripe gives the
+wallet's click handler one second to open its sheet, which is not enough time to create a checkout
+and a payment session. Without a `checkoutId` the checkout already in the store is reused, so the
+buttons can be injected beside a checkout the page has already loaded; the checkout-only client has
+no cart to fall back on, so it throws when there is no loaded checkout to attach to. Inject again
+with a new token whenever the address or fulfillment changes — the amounts the sheet shows come from
+the checkout the buttons were prepared against.
+
+The buttons only render where the shopper's platform offers a wallet, and the block hides itself
+entirely otherwise. Subscribe to `lce:actions.checkout_express_checkout_availability` to know which
+state you are in. Both wallets require an HTTPS origin on a domain registered with Stripe, each
+subdomain separately — see the
+[checkout component guide](../guides/checkout-component.md#express-checkout-apple-pay-and-google-pay).
+
+```javascript
+await client.injectExpressCheckout({
+  containerId: 'express-checkout-container'
+});
+```
+
+The full client exposes the same component as `injectExpressCheckoutElement()`, with the same
+parameters. It differs in one way: with no `checkoutId` and no checkout loaded, it prepares one from
+the current cart rather than throwing.
+
+```javascript
+await client.injectExpressCheckoutElement({
+  containerId: 'pdp-express-checkout'
+});
+```
+
+### 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 | No       | 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' ('staging' | 'production')
+  debugMode?: DebugMode;  // 'none' | 'console' | 'panel'
+  customTheme?: IClientCustomThemeConfig;
+  promoTicker?: IPromoTicker[];
+  proxy?: IElementsProxyConfig;
+  gtm?: IElementsGTMConfig;
+  checkout?: ILiquidCommerceElementsCheckoutConfig;
+  development?: ILiquidCommerceElementsDevelopmentConfig;
+}
+```
+
+#### Environment
+
+```typescript
+type ElementsEnv = '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.
+
+#### GTM Configuration
+
+```typescript
+interface IElementsGTMConfig {
+  gatewayUrl?: string;
+}
+```
+
+**Example:**
+
+```javascript
+gtm: {
+  gatewayUrl: 'https://www.yoursite.com/metrics/'
+}
+```
+
+Set this when your site serves its own GTM container through Google tag gateway. See [Analytics → Google tag gateway](../reference/analytics.md#google-tag-gateway).
+
+#### 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([...]);
+}, { once: true });
+```
+
+## 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;
+}
+```
+
+### ILiquidCommerceElementsBuilderClient
+
+The builder client (returned by `ElementsBuilder()`) exposes the same `inject*` methods plus a set of `update*Component` methods for applying theme/layout changes at runtime:
+
+```typescript
+interface ILiquidCommerceElementsBuilderClient {
+  // Runtime theme/layout updates (builder-only)
+  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;
+
+  // Injection methods
+  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
+  actions: ILiquidCommerceElementsActions;
+
+  // Cleanup
+  destroy(): void;
+}
+```
+
+#### Runtime theme updates (`update*Component`)
+
+These methods are **builder-only** — they exist on the client returned by `ElementsBuilder()` and are **not** available on the full `Elements()` client. Each method applies theme changes to its scope and, when the passed `configs` include a non-empty `layout`, triggers targeted rerenders of only the components affected by those layout fields.
+
+Return types are not uniform:
+
+- `updateComponentGlobalConfigs()` and `updateProductComponent()` return `Promise<void>` (they may await product rerenders) — `await` them.
+- `updateCartComponent()`, `updateCheckoutComponent()`, `updateAddressComponent()`, and `updateProductListComponent()` return `void` (synchronous).
+
+```javascript
+const builder = await ElementsBuilder('YOUR_API_KEY', { env: 'production' });
+
+// Asynchronous — await these
+await builder.updateComponentGlobalConfigs({
+  theme: { primaryColor: '#0a7d33', buttonCornerRadius: '8px' },
+  layout: { allowPromoCodes: true }
+});
+await builder.updateProductComponent({
+  theme: { backgroundColor: '#ffffff' },
+  layout: { addToCartButtonText: 'Add to bag' }
+});
+
+// Synchronous — no await needed
+builder.updateCartComponent({ layout: { drawerHeaderText: 'Your bag' } });
+builder.updateCheckoutComponent({ layout: { placeOrderButtonText: 'Pay now' } });
+```
+
+#### injectCheckoutElement (builder)
+
+The builder's `injectCheckoutElement()` accepts `IInjectCheckoutBuilderParams`, which extends `IInjectCheckoutParams` with two **preview-only** fields:
+
+```typescript
+interface IInjectCheckoutBuilderParams extends IInjectCheckoutParams {
+  simulatePresale?: boolean;         // simulate a presale lock in builder mode
+  presaleExpiresInMinutes?: number;  // minutes until the simulated lock expires (defaults to 15)
+}
+```
+
+`simulatePresale` and `presaleExpiresInMinutes` only take effect in the builder preview and have no counterpart on the full `Elements()` client's `injectCheckoutElement()`.
+
+```javascript
+await builder.injectCheckoutElement({
+  containerId: 'checkout',
+  simulatePresale: true,
+  presaleExpiresInMinutes: 30
+});
+```
+
+## 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'
+};
+
+// Elements() resolves to `null` on failure, so the type is nullable.
+const client: ILiquidCommerceElementsClient | null = 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();
+  }, { once: true });
+}
+```
+
+### 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