@liquidcommerce/elements-sdk 2.4.1 → 2.4.3

package/dist/types/core/client/client-action.service.d.ts

@@ -32,6 +32,7 @@ export interface ICheckoutActions {
     closeCheckout: () => void;
     toggleCheckout: () => void;
     addProduct: (params: IAddProductParams[], openCheckout?: boolean) => Promise<void>;
+    addPresaleProduct: (params: IAddProductParams) => Promise<void>;
     applyPromoCode: (promoCode: string) => Promise<void>;
     removePromoCode: () => Promise<void>;
     applyGiftCard: (code: string) => Promise<void>;

package/dist/types/core/pubsub/interfaces/checkout.interface.d.ts

@@ -66,10 +66,12 @@ export interface ICheckoutGiftCardFailedEventData {
 export interface ICheckoutProductAddEventData {
     itemsAdded: number;
     identifiers: string[];
+    isPresale?: boolean;
 }
 export interface ICheckoutProductAddFailedEventData {
     identifiers: string[];
     error: string;
+    isPresale?: boolean;
 }
 export interface ICheckoutItemEventData {
     liquidId: string;

package/dist/types/core/pubsub/pubsub.service.d.ts

@@ -1,6 +1,7 @@
 import type { IElementsActionsEventsMap, IElementsFormsEventsMap, SpecificActionEvent, SpecificFormEvent } from '@/core/pubsub/interfaces';
 export declare class PubSubService {
     private readonly logger;
+    private clientReadyEvent;
     constructor();
     private readonly eventPrefix;
     static getInstance(): PubSubService;
@@ -8,5 +9,5 @@ export declare class PubSubService {
     publishForm<K extends SpecificFormEvent>(eventType: K, data: IElementsFormsEventsMap[K]): void;
     private publishSpecific;
     private dispatchNativeEvents;
-    private generateEventId;
+    private setupClientReadyBuffering;
 }

package/dist/types/core/singleton-manager.service.d.ts

@@ -1,12 +1,12 @@
 import type { IClientConfigs } from '@/core/client/client-config.service';
-import type { LiquidCommerceElementsClientConstructor } from '@/interfaces/core.interface';
+import type { LiquidCommerceElementsBuilderClientConstructor, LiquidCommerceElementsClientConstructor } from '@/interfaces/core.interface';
 export declare class SingletonManager {
     private static instances;
     private static clientConstructor;
     private static getInstances;
     private constructor();
-    static setClientConstructor(lceConstructor: LiquidCommerceElementsClientConstructor): void;
-    static getClientConstructor(): LiquidCommerceElementsClientConstructor | null;
+    static setClientConstructor(lceConstructor: LiquidCommerceElementsClientConstructor | LiquidCommerceElementsBuilderClientConstructor): void;
+    static getClientConstructor(): LiquidCommerceElementsClientConstructor | LiquidCommerceElementsBuilderClientConstructor | null;
     static getClassInstance<T>(className: string, instanceCreator: () => T): T;
     static getClient<T>(clientConfigs: IClientConfigs): Promise<T>;
 }

package/dist/types/core/store/store.service.d.ts

@@ -40,6 +40,5 @@ export declare class StoreService {
     private saveStore;
     private loadPersistedState;
     private loadFromDBPersistence;
-    private addBeforeUnloadHandler;
     private getAddressDataFromId;
 }

package/dist/types/elements-base-client.d.ts

@@ -0,0 +1,49 @@
+import { AuthService } from '@/core/auth.service';
+import { ClientActionService } from '@/core/client/client-action.service';
+import { ClientConfigService, type IClientConfigs } from '@/core/client/client-config.service';
+import { CommandService } from '@/core/command/command.service';
+import { DebugPanelService } from '@/core/debug-panel/debug-panel.service';
+import { FingerPrintService } from '@/core/fingerprint.service';
+import { GoogleTagManagerService } from '@/core/google-tag-manager.service';
+import { LoggerFactory } from '@/core/logger/logger-factory';
+import { StoreService } from '@/core/store';
+import { TelemetryService } from '@/core/telemetry/telemetry.service';
+import { type ComponentType } from '@/enums';
+import type { IInjectedComponent, ILiquidCommerceElementsActions, IProcessInjectElementParams } from '@/interfaces/core.interface';
+import { ApiClientService } from '@/modules/api-client';
+import { ThemeProviderService } from '@/modules/theme-provider';
+export declare abstract class ElementsBaseClient {
+    protected readonly authService: AuthService;
+    protected readonly clientConfig: ClientConfigService;
+    protected readonly store: StoreService;
+    protected readonly commands: CommandService;
+    protected readonly apiClient: ApiClientService;
+    protected readonly themeProvider: ThemeProviderService;
+    protected readonly fingerPrintService: FingerPrintService;
+    protected readonly googleTagManager: GoogleTagManagerService;
+    protected readonly clientAction: ClientActionService;
+    protected readonly telemetry: TelemetryService;
+    protected readonly debugPanel: DebugPanelService;
+    protected readonly logger: ReturnType<typeof LoggerFactory.get>;
+    protected clientPrepared: boolean;
+    protected componentFactoryInitialized: boolean;
+    protected cartDrawerCreated: boolean;
+    protected gtmInitialized: boolean;
+    protected injectedComponents: Map<string, IInjectedComponent>;
+    constructor(clientConfigs: IClientConfigs);
+    prepare(): Promise<void>;
+    private prepareEssentialServices;
+    private deferHeavyInitialization;
+    private initializeHeavyServices;
+    get actions(): ILiquidCommerceElementsActions;
+    protected processInjectElement(params: IProcessInjectElementParams): Promise<IInjectedComponent | null>;
+    protected ensureCartDrawerExists(): void;
+    protected ensureAllComponentsRegistered(): void;
+    protected createInjectedComponentWrapper(containerId: string, type: ComponentType, element: HTMLElement): IInjectedComponent;
+    protected rerenderInjectedComponentsByType(type: ComponentType): void;
+    protected isElementsEnabled(): boolean;
+    protected injectDisabledElementsError(containerId: string, componentName: ComponentType): void;
+    private registerEssentialComponents;
+    protected registerComponents(): void;
+    protected registerAllComponents(): void;
+}

package/dist/types/elements-builder-client.d.ts

@@ -0,0 +1,2 @@
+import type { ILiquidCommerceElementsBuilderClient, ILiquidCommerceElementsBuilderConfig } from '@/interfaces/core.interface';
+export declare function ElementsBuilder(apiKey: string, config: ILiquidCommerceElementsBuilderConfig): Promise<ILiquidCommerceElementsBuilderClient | null>;

package/dist/types/elements-client-helper.d.ts

@@ -1 +1,4 @@
+import { type ComponentType } from '@/enums';
 export declare function deepMergeConfigs<T extends Record<string, any>>(target: T, source: Partial<T>): T;
+export declare const layoutFieldToComponentTypes: Map<string, ComponentType[]>;
+export declare function getComponentTypesForLayoutFields(parentPath: string, layoutFields: Record<string, any>): ComponentType[];

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from './elements-builder-client';
 export * from './elements-client';
 export * from './enums';
 export * from './interfaces/configs';

package/dist/types/index.umd.d.ts

@@ -1,2 +1,2 @@
-import { Elements } from './index';
-export { Elements };
+import { Elements, ElementsBuilder } from './index';
+export { Elements, ElementsBuilder };

package/dist/types/interfaces/configs/checkout.interface.d.ts

@@ -18,6 +18,7 @@ export interface ICheckoutLayout {
     drawerHeaderText: string;
     placeOrderButtonText: string;
     placeOrderButtonShowRequiredFields: boolean;
+    checkoutCompleted: ICheckoutCompleted;
 }
 export interface ICheckoutCompleted {
     customLogo: string;
@@ -25,7 +26,6 @@ export interface ICheckoutCompleted {
 }
 export interface ICheckoutTheme {
     backgroundColor: string;
-    checkoutCompleted: ICheckoutCompleted;
 }
 export interface ICheckoutComponent {
     theme: ICheckoutTheme;

package/dist/types/interfaces/core.interface.d.ts

@@ -17,12 +17,17 @@ export interface IClientCustomThemeConfig {
     cart?: UpdateCartComponent;
     checkout?: UpdateCheckoutComponent;
 }
+export interface ILiquidCommerceElementsBuilderConfig {
+    env?: ElementsEnv;
+    promoTicker?: IPromoTicker[];
+    customTheme?: IClientCustomThemeConfig;
+    debugMode?: DebugMode;
+}
 export interface ILiquidCommerceElementsConfig {
     env?: ElementsEnv;
     promoTicker?: IPromoTicker[];
     customTheme?: IClientCustomThemeConfig;
     proxy?: IElementsProxyConfig;
-    isBuilder?: boolean;
     debugMode?: DebugMode;
 }
 export interface IInjectProductElement {
@@ -34,17 +39,10 @@ export interface IBuilderInjectElementParams {
     containerId: string;
     [key: string]: any;
 }
-export interface ILiquidCommerceElementsBuilderMethod {
-    updateComponentGlobalConfigs(configs: UpdateComponentGlobalConfigs): Promise<void>;
-    updateProductComponent(configs: UpdateProductComponent): Promise<void>;
-    updateAddressComponent(configs: UpdateAddressComponent): void;
-    updateCartComponent(configs: UpdateCartComponent): void;
-    updateCheckoutComponent(configs: UpdateCheckoutComponent): void;
-    injectElement(params: IBuilderInjectElementParams): Promise<void>;
-    injectProductElement(params: IInjectProductElement[]): Promise<void>;
-    injectAddressElement(containerId: string, options?: IAddressOptions): Promise<void>;
-    injectCartElement(containerId: string): Promise<void>;
-    injectCheckoutElement(containerId: string): Promise<void>;
+export interface IInjectedComponent {
+    getType(): ComponentType;
+    getElement(): HTMLElement;
+    rerender(): void;
 }
 export interface IProcessInjectElementParams {
     type: ComponentType;
@@ -64,13 +62,30 @@ export interface ILiquidCommerceElementsActions {
     cart: ICartActions;
     checkout: ICheckoutActions;
 }
+export interface ILiquidCommerceElementsBuilderClient {
+    updateComponentGlobalConfigs(configs: UpdateComponentGlobalConfigs): Promise<void>;
+    updateProductComponent(configs: UpdateProductComponent): Promise<void>;
+    updateAddressComponent(configs: UpdateAddressComponent): void;
+    updateCartComponent(configs: UpdateCartComponent): void;
+    updateCheckoutComponent(configs: UpdateCheckoutComponent): 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(containerId: string, options?: {
+        simulatePresale?: boolean;
+        presaleExpiresInMinutes?: number;
+    }): Promise<IInjectedComponent | null>;
+    actions: ILiquidCommerceElementsActions;
+}
 export interface ILiquidCommerceElementsClient {
-    builder: ILiquidCommerceElementsBuilderMethod;
-    injectProductElement(params: IInjectProductElement[]): Promise<void>;
-    injectAddressElement(containerId: string, options?: IAddressOptions): Promise<void>;
-    injectCartElement(containerId: string): Promise<void>;
-    injectCheckoutElement(containerId: string): Promise<void>;
+    injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>;
+    injectAddressElement(containerId: string, options?: IAddressOptions): Promise<IInjectedComponent | null>;
+    injectCartElement(containerId: string): Promise<IInjectedComponent | null>;
+    injectCheckoutElement(containerId: string): Promise<IInjectedComponent | null>;
     ui: ILiquidCommerceElementsUIMethod;
     actions: ILiquidCommerceElementsActions;
+    getInjectedComponents(): Map<string, IInjectedComponent>;
 }
 export type LiquidCommerceElementsClientConstructor = new (clientConfigs: IClientConfigs) => ILiquidCommerceElementsClient;
+export type LiquidCommerceElementsBuilderClientConstructor = new (clientConfigs: IClientConfigs) => ILiquidCommerceElementsBuilderClient;

package/dist/types/modules/cart/components/index.d.ts

@@ -1,5 +1,7 @@
 export * from './cart-body.component';
 export * from './cart-footer.component';
+export * from './cart-fulfillment.component';
+export * from './cart-fulfillment.component';
 export * from './cart-header.component';
 export * from './cart-item.component';
 export * from './cart-item-quantity-price.component';

package/dist/types/modules/theme-provider/services/font-manager.service.d.ts

@@ -2,6 +2,7 @@ import type { IFontFamily } from '@/interfaces/configs';
 export declare class FontManagerService {
     private googleFontsUrl;
     private defaultFontFamilies;
+    private readonly fontsLinkAttribute;
     loadGoogleFonts(fonts: IFontFamily[], globalDisplay?: string): void;
     updateGoogleFonts(fonts: IFontFamily[], globalDisplay?: string): void;
     private injectGoogleFontsResourceHints;

package/dist/types/modules/ui-components/lce-element/lce-element.component.d.ts

@@ -2,8 +2,10 @@ import type { ComponentType } from '@/enums';
 export declare class LceElementComponent extends HTMLElement {
     private _initialized;
     protected _container: ShadowRoot | null;
+    private _wrappedComponentRerender;
     constructor();
     initialize(contentType: ComponentType, contentElement: HTMLElement): void;
+    rerender(context?: string): void;
     private applyBasicStyles;
     private isCSSStyleSheetSupported;
     private applyThemeStyles;

package/docs/ACTIONS.md

@@ -530,7 +530,43 @@ window.addEventListener('lce:actions.checkout_product_add_failed', function(even
 });
 ```
 
-**Real Business Use**: Perfect for "Buy Now" buttons, one-click purchasing, express checkout flows, or any scenario where you want to skip the cart and go straight to checkout.
+#### Add Presale Product to Checkout
+```javascript
+// Add a single presale product directly to checkout (bypasses cart, always opens checkout drawer)
+// The method automatically validates product availability and fulfillment options
+await actions.checkout.addPresaleProduct({
+  identifier: 'presale-product-123',
+  fulfillmentType: 'shipping',
+  quantity: 1
+});
+
+// Listen for success/failure feedback (same events as regular addProduct)
+window.addEventListener('lce:actions.checkout_product_add_success', function(event) {
+  const { itemsAdded, identifiers, isPresale } = event.detail.data;
+  if (isPresale) {
+    console.log(`✅ Added ${itemsAdded} presale product to checkout:`, identifiers);
+    showSuccessMessage('Presale item ready for checkout!');
+  }
+});
+
+window.addEventListener('lce:actions.checkout_product_add_failed', function(event) {
+  const { identifiers, error, isPresale } = event.detail.data;
+  if (isPresale) {
+    console.log(`❌ Failed to add presale product to checkout:`, identifiers, error);
+    showErrorMessage('Could not proceed with presale checkout. Please try again.');
+  }
+});
+```
+
+**Key Features:**
+- **Product Availability Validation**: Automatically fetches and validates product data
+- **Fulfillment Type Support**: Checks if the requested fulfillment type is available
+- **Presale Verification**: Ensures the product is actually a presale item
+- **Always Opens Checkout**: Automatically opens checkout drawer after adding presale product
+- **Address Requirement**: Opens address input if location is not available
+- **Error Handling**: Comprehensive error handling with detailed feedback
+
+**Real Business Use**: Perfect for "Buy Now" buttons, one-click purchasing, express checkout flows, or any scenario where you want to skip the cart and go straight to checkout. The `addPresaleProduct` method is specifically designed for presale items that need to bypass the regular cart flow and go directly to checkout.
 
 #### Pre-fill Customer Information
 ```javascript

package/docs/CONFIGURATION.md

@@ -308,34 +308,161 @@ data-env="production"
 data-debug-mode="console"
 ```
 
-#### `data-cart-id`
+#### `data-cart-button`
 
 **Type:** `string`
 
-Container ID for cart button.
+Container ID, CSS selector, or position-prefixed selector for simple cart button (no badge).
 
 ```html
-data-cart-id="header-cart"
+<!-- Simple ID (with or without # prefix) -->
+data-cart-button="header-cart"              <!-- Works with or without # -->
+data-cart-button="#header-cart"             <!-- Also works with # prefix -->
+
+<!-- CSS Selector (from browser inspect tool) -->
+data-cart-button=".header .nav-links"
+data-cart-button="#main-navigation"
+
+<!-- Position-prefixed selectors -->
+data-cart-button="above:.header .logo"      <!-- Place above the target -->
+data-cart-button="below:#main-navigation"  <!-- Place below the target -->
+data-cart-button="below:main-navigation"   <!-- Also works without # prefix -->
+data-cart-button="replace:.old-cart"       <!-- Replace the target -->
+data-cart-button="inside:.header .nav"     <!-- Place inside the target (default) -->
 ```
 
-#### `data-show-cart-items`
+#### `data-cart-badge-button`
 
-**Type:** flag (no value)
+**Type:** `string`
 
-Show item count on cart button.
+Container ID, CSS selector, or position-prefixed selector for cart button with item count badge.
 
 ```html
-data-show-cart-items
+<!-- Simple ID (with or without # prefix) -->
+data-cart-badge-button="header-cart"        <!-- Works with or without # -->
+data-cart-badge-button="#header-cart"       <!-- Also works with # prefix -->
+
+<!-- CSS Selector (from browser inspect tool) -->
+data-cart-badge-button=".header .nav-links"
+data-cart-badge-button="#main-navigation"
+
+<!-- Position-prefixed selectors -->
+data-cart-badge-button="above:.header .logo"      <!-- Place above the target -->
+data-cart-badge-button="below:#main-navigation"  <!-- Place below the target -->
+data-cart-badge-button="replace:.old-cart"       <!-- Replace the target -->
+data-cart-badge-button="inside:.header .nav"     <!-- Place inside the target (default) -->
 ```
 
-#### `data-hide-cart-floating-button`
+**Position Prefixes:**
+- `above:` - Place above the target element
+- `below:` - Place below the target element  
+- `replace:` - Replace the target element
+- `inside:` - Place inside the target element (default)
+
+#### `data-cart-button-hidden`
 
 **Type:** flag (no value)
 
-Hide the default floating cart button.
+Hide cart button completely.
 
 ```html
-data-hide-cart-floating-button
+data-cart-button-hidden
+```
+
+### Cart Button Examples
+
+**Simple cart button (no badge):**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button="header-cart"
+  src="elements.js">
+</script>
+```
+
+**Cart button with item count badge:**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="header-cart"
+  src="elements.js">
+</script>
+```
+
+**Using position-prefixed selectors:**
+```html
+<!-- Place inside the target element (default) -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="inside:.header .nav-links"
+  src="elements.js">
+</script>
+
+<!-- Place above the target element -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button="above:.header .logo"
+  src="elements.js">
+</script>
+
+<!-- Place below the target element -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="below:#main-navigation"
+  src="elements.js">
+</script>
+
+<!-- Replace the target element -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button="replace:.old-cart-button"
+  src="elements.js">
+</script>
+```
+
+**No cart button:**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button-hidden
+  src="elements.js">
+</script>
+```
+
+**Default behavior (floating cart button with badge):**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  src="elements.js">
+</script>
+```
+
+### Getting CSS Selectors from Browser
+
+**Super Easy Method:**
+1. **Right-click** on any element where you want the cart button
+2. Select **"Inspect"** or **"Inspect Element"**
+3. In developer tools, **right-click** on the highlighted element
+4. Select **"Copy" → "Copy selector"**
+5. Paste the selector into your `data-cart-button` or `data-cart-badge-button` attribute
+
+**Example:**
+```html
+<!-- After copying selector from browser inspect tool -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="body > div.container > header > nav > div.nav-links"
+  src="elements.js">
+</script>
 ```
 
 ### Product Configuration

package/docs/TROUBLESHOOTING.md

@@ -102,9 +102,26 @@ console.log('Container:', container);  // Should not be null
 // 2. Wait for DOM
 window.addEventListener('DOMContentLoaded', async () => {
   const client = await Elements('YOUR_API_KEY', { env: 'production' });
-  await client.injectProductElement([
+  const components = await client.injectProductElement([
     { containerId: 'product-container', identifier: 'product-123' }
   ]);
+  
+  // Check if injection was successful
+  if (components.length > 0) {
+    console.log('Product component injected successfully');
+    // components[0].rerender() - Rerender if needed
+    // components[0].getElement() - Get container element
+    // components[0].getType() - Get component type
+  } else {
+    console.log('Product injection failed');
+  }
+  
+  // Debug: Check all injected components
+  const allComponents = client.getInjectedComponents();
+  console.log('All injected components:', allComponents);
+  allComponents.forEach((component, containerId) => {
+    console.log(`Container: ${containerId}, Type: ${component.getType()}`);
+  });
 });
 
 // 3. Monitor product loading

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.4.1",
+  "version": "2.4.3",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -71,11 +71,11 @@
     "embeddable commerce"
   ],
   "devDependencies": {
-    "@biomejs/biome": "2.2.6",
+    "@biomejs/biome": "2.2.7",
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@rollup/plugin-alias": "^5.1.1",
-    "@rollup/plugin-commonjs": "^28.0.8",
+    "@rollup/plugin-commonjs": "^28.0.9",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-replace": "^6.0.2",
@@ -87,14 +87,14 @@
     "@semantic-release/npm": "^13.1.1",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^24.9.0",
+    "@types/node": "^24.9.1",
     "conventional-changelog-cli": "^5.0.0",
     "husky": "^9.1.7",
     "process": "^0.11.10",
     "rollup": "^4.52.5",
     "rollup-obfuscator": "^4.1.1",
     "rollup-plugin-typescript2": "^0.36.0",
-    "semantic-release": "^24.2.9",
+    "semantic-release": "^25.0.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   },