@liquidcommerce/elements-sdk 2.7.8 → 2.7.10

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

@@ -1 +1,398 @@
-to be created...
+# TypeScript Types Reference
+
+All public types are exported from the main package entry point. Import them using the `type` keyword for optimal tree-shaking.
+
+## Importing Types
+
+```typescript
+import { Elements } from '@liquidcommerce/elements-sdk';
+import type {
+  ILiquidCommerceElementsClient,
+  ILiquidCommerceElementsConfig,
+  IInjectProductElement,
+  IInjectedComponent
+} from '@liquidcommerce/elements-sdk';
+```
+
+For the checkout-only build:
+
+```typescript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+import type {
+  IElementsCheckoutClient,
+  IElementsCheckoutActions,
+  ILiquidCommerceElementsCheckoutClientConfig,
+  IInjectedComponent
+} from '@liquidcommerce/elements-sdk/checkout';
+```
+
+---
+
+## Client Types
+
+### ILiquidCommerceElementsClient
+
+Main SDK client interface returned by `Elements()`.
+
+```typescript
+interface ILiquidCommerceElementsClient {
+  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: ILiquidCommerceElementsUIMethod;
+  actions: ILiquidCommerceElementsActions;
+  getInjectedComponents(): Map<string, IInjectedComponent>;
+  destroy(): void;
+}
+```
+
+### ILiquidCommerceElementsBuilderClient
+
+Builder-pattern client interface returned by `ElementsBuilder()`.
+
+```typescript
+interface ILiquidCommerceElementsBuilderClient {
+  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;
+  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: ILiquidCommerceElementsActions;
+  destroy(): void;
+}
+```
+
+### IElementsCheckoutClient
+
+Checkout-only client interface returned by `ElementsCheckout()`.
+
+```typescript
+interface IElementsCheckoutClient {
+  injectCheckout(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>;
+  actions: { checkout: IElementsCheckoutActions };
+  destroy(): void;
+}
+```
+
+---
+
+## Configuration Types
+
+### ILiquidCommerceElementsConfig
+
+```typescript
+interface ILiquidCommerceElementsConfig {
+  env?: ElementsEnv;
+  promoTicker?: IPromoTicker[];
+  customTheme?: IClientCustomThemeConfig;
+  debugMode?: DebugMode;
+  checkout?: ILiquidCommerceElementsCheckoutConfig;
+  proxy?: IElementsProxyConfig;
+  development?: ILiquidCommerceElementsDevelopmentConfig;
+}
+```
+
+### ILiquidCommerceElementsCheckoutClientConfig
+
+Same shape as `ILiquidCommerceElementsConfig`, used for the checkout-only client.
+
+### IClientCustomThemeConfig
+
+```typescript
+interface IClientCustomThemeConfig {
+  global?: UpdateComponentGlobalConfigs;
+  product?: UpdateProductComponent;
+  address?: UpdateAddressComponent;
+  cart?: UpdateCartComponent;
+  checkout?: UpdateCheckoutComponent;
+  productList?: UpdateProductListComponent;
+}
+```
+
+### IElementsProxyConfig
+
+```typescript
+interface IElementsProxyConfig {
+  baseUrl: string;
+  headers?: Record<string, string>;
+}
+```
+
+### ILiquidCommerceElementsDevelopmentConfig
+
+```typescript
+interface ILiquidCommerceElementsDevelopmentConfig {
+  customApiUrl?: string;
+  paymentMethodId?: string;
+  openShadowDom?: boolean;
+}
+```
+
+### ILiquidCommerceElementsCheckoutConfig
+
+```typescript
+interface ILiquidCommerceElementsCheckoutConfig {
+  pageUrl?: string;
+}
+```
+
+See [Configuration Reference](./configuration.md) for detailed property descriptions.
+
+---
+
+## Injection Types
+
+### IInjectProductElement
+
+```typescript
+interface IInjectProductElement {
+  containerId: string;
+  identifier: string;
+}
+```
+
+### IInjectCheckoutParams
+
+```typescript
+interface IInjectCheckoutParams {
+  containerId: string;
+  checkoutId?: string;
+  hideHeader?: boolean;
+}
+```
+
+### IInjectCheckoutBuilderParams
+
+```typescript
+interface IInjectCheckoutBuilderParams extends IInjectCheckoutParams {
+  simulatePresale?: boolean;
+  presaleExpiresInMinutes?: number;
+}
+```
+
+### IInjectProductListParams
+
+```typescript
+interface IInjectProductListParams {
+  containerId: string;
+  slug: string;
+  rows?: number;
+  columns?: number;
+  filters?: ProductListFilterType[];
+  productUrl?: string;
+}
+```
+
+### IInjectProductListSearchParams
+
+```typescript
+interface IInjectProductListSearchParams {
+  containerId: string;
+  slug: string;
+}
+```
+
+### IInjectProductListFiltersParams
+
+```typescript
+interface IInjectProductListFiltersParams {
+  containerId: string;
+  slug: string;
+  filters?: ProductListFilterType[];
+}
+```
+
+### IBuilderInjectElementParams
+
+```typescript
+interface IBuilderInjectElementParams {
+  type: ComponentType;
+  containerId: string;
+  [key: string]: any;
+}
+```
+
+---
+
+## Component Types
+
+### IInjectedComponent
+
+Returned by all injection methods. Provides control over the injected component.
+
+```typescript
+interface IInjectedComponent {
+  getType(): ComponentType;
+  getElement(): HTMLElement;
+  rerender(): void;
+  destroy(): void;
+}
+```
+
+---
+
+## UI Types
+
+### ILiquidCommerceElementsUIMethod
+
+```typescript
+interface ILiquidCommerceElementsUIMethod {
+  cartButton(containerId: string, showItemsCount?: boolean): void;
+  floatingCartButton(showItemsCount?: boolean): void;
+  cartSubtotal(elementId: string): void;
+  cartItemsCount(elementId: string, options?: { hideZero: boolean }): void;
+}
+```
+
+---
+
+## Action Types
+
+### ILiquidCommerceElementsActions
+
+```typescript
+interface ILiquidCommerceElementsActions {
+  product: IProductActions;
+  address: IAddressActions;
+  cart: ICartActions;
+  checkout: ICheckoutActions;
+}
+```
+
+### IElementsCheckoutActions
+
+Checkout actions available in the checkout-only client. Omits drawer-related methods.
+
+```typescript
+interface IElementsCheckoutActions extends Omit<ICheckoutActions, 'openCheckout' | 'closeCheckout' | 'toggleCheckout'> {}
+```
+
+See [Actions API](./actions/) for detailed method signatures.
+
+---
+
+## Enum Types
+
+### ElementsEnv
+
+```typescript
+type ElementsEnv = 'development' | 'staging' | 'production';
+```
+
+### DebugMode
+
+```typescript
+type DebugMode = 'none' | 'console' | 'panel';
+```
+
+### FulfillmentType
+
+```typescript
+type FulfillmentType = 'onDemand' | 'shipping';
+```
+
+### ComponentType
+
+```typescript
+type ComponentType =
+  | 'address' | 'product' | 'cart' | 'checkout'
+  | 'product-list' | 'product-list-card' | 'product-list-filters' | 'product-list-search'
+  | 'drawer' | 'input' | 'engraving-form' | 'engraving-view'
+  | 'buttons-cart-open' | 'powered-by' | 'lce-element'
+  | 'purchase-min-alert' | 'alert' | 'promo-code-ticker'
+  // ...and additional internal component types
+```
+
+### DisplayModeType
+
+```typescript
+type DisplayModeType = 'modal' | 'drawer';
+```
+
+---
+
+## Theme Configuration Types
+
+### UpdateComponentGlobalConfigs
+
+`DeepPartial<IComponentGlobalConfigs>` -- all properties optional.
+
+### UpdateProductComponent
+
+`DeepPartial<IProductComponent>` -- all properties optional.
+
+### UpdateCartComponent
+
+`DeepPartial<ICartComponent>` -- all properties optional.
+
+### UpdateCheckoutComponent
+
+`DeepPartial<ICheckoutComponent>` -- all properties optional.
+
+### UpdateAddressComponent
+
+`DeepPartial<IAddressComponent>` -- all properties optional.
+
+### UpdateProductListComponent
+
+Special structure for updating product list configuration by slug:
+
+```typescript
+interface UpdateProductListComponent {
+  theme?: { backgroundColor?: string };
+  layout?: {
+    lists?: Record<string, DeepPartial<IPLCList>>;
+  };
+}
+```
+
+See [Configuration Reference](./configuration.md) for detailed theme property descriptions.
+
+---
+
+## Promo Ticker Type
+
+### IPromoTicker
+
+```typescript
+interface IPromoTicker {
+  promoCode: string;
+  text: string[];
+  separator: string;
+  activeFrom: string;   // ISO 8601 UTC
+  activeUntil: string;  // ISO 8601 UTC
+}
+```
+
+---
+
+## Utility Types
+
+### DeepPartial
+
+Used internally for theme update types. Makes all properties in `T` recursively optional.
+
+```typescript
+type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+```
+
+---
+
+## See Also
+
+- [Client API](./client.md) - Client initialization and usage
+- [Configuration Reference](./configuration.md) - Detailed config options
+- [Injection Methods](./injection-methods.md) - Component injection API

package/docs/v1/examples/advanced-patterns.md

@@ -88,6 +88,108 @@ const client = await Elements('YOUR_API_KEY', {
 });
 ```
 
+## 7) Cleanup on SPA Navigation
+
+```javascript
+let client = null;
+
+async function mountElements() {
+  client = await Elements('YOUR_API_KEY', { env: 'production' });
+  await client.injectProductElement([
+    { containerId: 'product', identifier: '00619947000020' }
+  ]);
+}
+
+function unmountElements() {
+  if (client) {
+    client.destroy();
+    client = null;
+  }
+}
+
+// React example
+useEffect(() => {
+  mountElements();
+  return () => unmountElements();
+}, []);
+```
+
+## 8) Checkout-Only Page
+
+For a dedicated checkout page, use the tree-shaken checkout build:
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+
+const client = await ElementsCheckout('YOUR_API_KEY', {
+  env: 'production'
+});
+
+await client.injectCheckout({
+  containerId: 'checkout',
+  checkoutId: new URLSearchParams(window.location.search).get('lce_checkout'),
+  hideHeader: false
+});
+```
+
+## 9) Promo Ticker with Time Windows
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  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'
+    },
+    {
+      promoCode: 'FALL10',
+      text: ['10% Off Fall Collection'],
+      separator: '|',
+      activeFrom: '2026-09-01T00:00:00Z',
+      activeUntil: '2026-11-30T23:59:59Z'
+    }
+  ]
+});
+```
+
+## 10) Product List with Filters and Search
+
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+await client.injectProductListSearch({
+  containerId: 'search-box',
+  slug: 'whiskey-collection'
+});
+
+await client.injectProductListFilters({
+  containerId: 'sidebar-filters',
+  slug: 'whiskey-collection',
+  filters: ['price', 'brands', 'sizes', 'fulfillment']
+});
+
+await client.injectProductList({
+  containerId: 'product-grid',
+  slug: 'whiskey-collection',
+  rows: 4,
+  columns: 3,
+  productUrl: '/products/{identifier}'
+});
+```
+
+## 11) Check Product Availability by State
+
+```javascript
+const availability = await window.LiquidCommerce.elements.actions.product
+  .getProductAvailabilityByState(['00619947000020', '08504405135'], 'CA');
+
+console.log('Availability in CA:', availability);
+```
+
 ## Related Docs
 
 - [Events Guide](../guides/events.md)

package/docs/v1/examples/checkout-flow.md

@@ -27,7 +27,7 @@ A two-page setup: a product page that adds to cart and redirects to a dedicated
     data-cart-badge-button="header-cart"
     data-checkout-url="https://yoursite.com/checkout?lce_checkout={token}"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
 </head>
 <body>
@@ -63,7 +63,7 @@ When users click checkout, the cart redirects to your hosted checkout page with
     data-checkout-container="checkout"
     data-checkout-param="lce_checkout"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
 </head>
 <body>

package/docs/v1/examples/multi-product-page.md

@@ -24,7 +24,7 @@ Show multiple products on a single page using declarative attributes or programm
     data-container-3="product-3"
     data-product-3="08068660001"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
 
   <style>
@@ -53,7 +53,7 @@ Show multiple products on a single page using declarative attributes or programm
   data-token="YOUR_API_KEY"
   data-env="production"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <script data-liquid-commerce-elements-products type="application/json">

package/docs/v1/examples/simple-product-page.md

@@ -32,7 +32,7 @@ A minimal, production-ready product page using the CDN build with a single Produ
     data-product-1="00619947000020"
     data-cart-badge-button="header-cart"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
 
   <style>

package/docs/v1/getting-started/concepts.md

@@ -68,7 +68,7 @@ When using the CDN, the SDK auto-initializes on page load:
   data-token="YOUR_API_KEY"
   data-env="production"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 ```
 
@@ -135,7 +135,7 @@ Configure components using HTML data attributes:
   data-container-1="product"
   data-product-1="00619947000020"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <div id="product"></div>
@@ -187,7 +187,7 @@ You can use declarative initialization and programmatic control:
   data-token="YOUR_API_KEY"
   data-env="production"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <script>

package/docs/v1/getting-started/installation.md

@@ -26,7 +26,7 @@ Add the following script tag to your page's `<head>` section:
   data-token="YOUR_API_KEY"
   data-env="production"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 ```
 
@@ -55,7 +55,7 @@ While the `<head>` section is recommended, the script can be placed anywhere on
     data-token="YOUR_API_KEY"
     data-env="production"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
 </head>
 <body>
@@ -77,7 +77,7 @@ If you only need checkout functionality (without product displays or cart), use
   data-token="YOUR_API_KEY"
   data-env="production"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/checkout/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/checkout/elements.js"
 ></script>
 ```
 

package/docs/v1/getting-started/quick-start.md

@@ -33,7 +33,7 @@ Add the Elements SDK script tag to your HTML `<head>`:
     data-token="YOUR_API_KEY"
     data-env="production"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
 </head>
 <body>
@@ -70,7 +70,7 @@ Add product configuration using HTML data attributes on the script tag:
   data-container-1="product-display"
   data-product-1="00619947000020"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 ```
 
@@ -103,7 +103,7 @@ Here's the complete HTML for a working product page:
     data-container-1="product-display"
     data-product-1="00619947000020"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
   
   <style>
@@ -150,7 +150,7 @@ If you prefer JavaScript over HTML attributes:
     data-token="YOUR_API_KEY"
     data-env="production"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
   
   <script defer>
@@ -216,7 +216,7 @@ To display multiple products on one page:
   data-product-3="08068660001"
   
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <div id="product-1"></div>
@@ -347,7 +347,7 @@ Try this complete example with your API key:
     data-container-1="product"
     data-product-1="00619947000020"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
   
   <style>

package/docs/v1/guides/address-component.md

@@ -200,7 +200,7 @@ Create a dedicated page for address selection:
     data-token="YOUR_API_KEY"
     data-env="production"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
 </head>
 <body>