@liquidcommerce/elements-sdk 2.6.0-beta.6 → 2.6.0-beta.60

package/docs/v1/reference/error-handling.md

@@ -0,0 +1,70 @@
+# Error Handling
+
+The SDK emits errors as events and (when applicable) throws a custom `SDKError`. Your app should handle both.
+
+## SDKError
+
+All SDK errors use a custom error class:
+
+```typescript
+class SDKError extends Error {
+  constructor(message: string, reThrow?: boolean);
+  name: 'SDKError';
+  isSdk: boolean;
+  reThrow: boolean;
+}
+```
+
+## Catching Errors
+
+```javascript
+try {
+  await window.LiquidCommerce.elements.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 so your app keeps running:
+
+```javascript
+window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid */]);
+console.log('App still working');
+```
+
+## Error Events
+
+Listen for failure events to show user-friendly messages or trigger retries:
+
+```javascript
+// Cart add failed
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  console.error('Failed to add:', event.detail.data.error);
+});
+
+// Address failed
+window.addEventListener('lce:actions.address_failed', (event) => {
+  console.error('Address error:', event.detail.data.error);
+});
+
+// Checkout submit failed
+window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
+  console.error('Checkout failed:', event.detail.data.error);
+});
+```
+
+## UI Errors
+
+When a component fails to load, the SDK renders an error view inside the container and logs details to the console.
+
+## Related Docs
+
+- [Events Guide](../guides/events.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/performance.md

@@ -0,0 +1,54 @@
+# Performance Guide
+
+The SDK is optimized out of the box. These tweaks help reduce load time and layout shift.
+
+## 1) Load Non-Blocking
+
+```html
+<script defer data-liquid-commerce-elements ...></script>
+```
+
+## 2) Use the Checkout-Only Build When Appropriate
+
+If you only need checkout, use the tree-shaken build:
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+```
+
+## 3) Inject Components When Needed
+
+Inject above-the-fold products first, then load the rest:
+
+```javascript
+await client.injectProductElement([
+  { containerId: 'hero-product', identifier: '001' }
+]);
+
+setTimeout(async () => {
+  await client.injectProductElement([
+    { containerId: 'related-1', identifier: '002' },
+    { containerId: 'related-2', identifier: '003' }
+  ]);
+}, 1000);
+```
+
+## 4) Reserve Space to Prevent Layout Shift
+
+```css
+#product {
+  min-height: 600px;
+}
+```
+
+## 5) Let the SDK Handle Media Optimization
+
+The SDK automatically:
+- Lazy loads images
+- Uses responsive image sizes
+- Virtualizes carousel images
+
+## Related Docs
+
+- [Best Practices](../guides/best-practices.md)
+- [Product Component](../guides/product-component.md)

package/docs/v1/reference/troubleshooting.md

@@ -0,0 +1,72 @@
+# Troubleshooting
+
+Common setup issues and how to resolve them.
+
+## SDK Script Not Loading
+
+**Symptoms:** 404/CORS in Network tab, `window.LiquidCommerce.elements` is undefined.
+
+**Fixes:**
+- Verify the script URL and that the tag includes `data-liquid-commerce-elements`.
+- Check ad blockers; proxy the API if needed.
+- Confirm `data-env` is set correctly.
+
+## Web Components Error
+
+**Symptoms:** Console logs about Custom Elements or Shadow DOM.
+
+**Fix:** Add the Web Components polyfill before the SDK:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
+<script defer data-liquid-commerce-elements ...></script>
+```
+
+## Product Not Showing
+
+**Symptoms:** Empty container or error view.
+
+**Fixes:**
+- Confirm the container ID matches your HTML.
+- Verify the product identifier exists.
+- Check for errors in the console or network tab.
+
+## Cart Drawer Not Opening
+
+**Symptoms:** Add to cart works but cart stays closed.
+
+**Fixes:**
+- Ensure a cart button is configured or call `window.LiquidCommerce.elements.actions.cart.openCart()`.
+- Check for JavaScript errors in the console.
+
+## Checkout Issues
+
+**Symptoms:** Checkout fails to load or submit.
+
+**Fixes:**
+- Verify you are on a supported browser.
+- Look for `checkout_*_failed` events in the console.
+- Check for Stripe-related errors in the browser console.
+
+## Address/Availability Problems
+
+**Symptoms:** Products show unavailable or address prompts fail.
+
+**Fixes:**
+- Make sure the address is set and valid.
+- Listen for `lce:actions.address_failed` to surface errors.
+
+## SSR / Server-Side Rendering
+
+**Symptoms:** Console warning "This SDK is designed for the browser. Calls made during SSR return null."
+
+This is expected behavior. The SDK ships an SSR stub that is automatically resolved when bundled for Node.js (via the `node` export condition in `package.json`). The stub exports all types and enums for TypeScript compatibility and returns `null` from factory functions (`Elements`, `ElementsBuilder`, `ElementsCheckout`).
+
+**No action required** — initialize the SDK in a client-only lifecycle hook (`useEffect`, `onMounted`, etc.) and the real client will activate in the browser.
+
+## Related Docs
+
+- [Installation](../getting-started/installation.md)
+- [Browser Support](./browser-support.md)
+- [Error Handling](./error-handling.md)
+- [Proxy Setup](../integration/proxy-setup.md)

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.6.0-beta.6",
+  "version": "2.6.0-beta.60",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -13,22 +13,28 @@
     "url": "https://github.com/liquidcommerce/elements-sdk/issues"
   },
   "module": "./dist/index.esm.js",
-  "browser": "./umd/elements.js",
   "types": "./dist/types/index.d.ts",
   "packageManager": "pnpm@10.0.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
+      "node": "./dist/ssr-stub.esm.js",
+      "browser": "./dist/index.esm.js",
       "import": "./dist/index.esm.js",
-      "browser": "./umd/elements.js",
       "default": "./dist/index.esm.js"
     },
+    "./checkout": {
+      "types": "./dist/types/index.checkout.d.ts",
+      "node": "./dist/ssr-stub.checkout.esm.js",
+      "browser": "./dist/index.checkout.esm.js",
+      "import": "./dist/index.checkout.esm.js",
+      "default": "./dist/index.checkout.esm.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
-    "umd",
-    "docs",
+    "docs/v1",
     "README.md",
     "LICENSE"
   ],
@@ -39,21 +45,26 @@
   "type": "module",
   "sideEffects": [
     "dist/index.esm.js",
+    "dist/index.checkout.esm.js",
     "umd/elements.js",
+    "umd/elements-checkout.js",
     "src/index.ts",
-    "src/index.umd.ts"
+    "src/index.umd.ts",
+    "src/index.checkout.ts",
+    "src/index.checkout.umd.ts"
   ],
   "scripts": {
     "build": "rollup -c",
-    "build:dev": "rollup -c --environment NODE_ENV:development",
+    "build:checkout": "rollup -c rollup.config.checkout.mjs",
+    "build:all": "pnpm build && pnpm build:checkout",
     "dev": "rollup -c -w",
     "type-check": "tsc --noEmit",
     "lint": "pnpm biome lint --write",
     "format": "biome format --write",
     "check": "pnpm biome check --write .",
-    "fl": "pnpm check && pnpm build:dev",
+    "fl": "pnpm check && pnpm tsc --noEmit",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
-    "clean": "rm -rf dist umd node_modules && pnpm install && pnpm build",
+    "clean": "rm -rf dist umd node_modules && pnpm install && pnpm build:all",
     "prepublishOnly": "pnpm run build",
     "deprecate:old": "npm deprecate @liquidcommerceteam/elements-sdk@\"*\" \"Package moved to @liquidcommerce/elements-sdk\"",
     "prepare": "husky"
@@ -70,9 +81,9 @@
     "embeddable commerce"
   ],
   "devDependencies": {
-    "@biomejs/biome": "2.3.5",
-    "@commitlint/cli": "^20.1.0",
-    "@commitlint/config-conventional": "^20.0.0",
+    "@biomejs/biome": "^2.4.4",
+    "@commitlint/cli": "^20.4.2",
+    "@commitlint/config-conventional": "^20.4.2",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-json": "^6.1.0",
@@ -82,18 +93,18 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.2",
-    "@semantic-release/npm": "^13.1.2",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.4",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^24.10.1",
+    "@types/node": "^25.3.0",
     "conventional-changelog-cli": "^5.0.0",
     "husky": "^9.1.7",
     "process": "^0.11.10",
-    "rollup": "^4.53.3",
+    "rollup": "^4.59.0",
     "rollup-obfuscator": "^4.1.1",
     "rollup-plugin-typescript2": "^0.36.0",
-    "semantic-release": "^25.0.2",
+    "semantic-release": "^25.0.3",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   },

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

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

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

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

package/dist/types/enums/cloud.enum.d.ts

@@ -1,106 +0,0 @@
-export declare enum DAYS_OF_WEEK {
-    MONDAY = "monday",
-    TUESDAY = "tuesday",
-    WEDNESDAY = "wednesday",
-    THURSDAY = "thursday",
-    FRIDAY = "friday",
-    SATURDAY = "saturday",
-    SUNDAY = "sunday"
-}
-export declare const CART_EVENT_ENUM: {
-    readonly OOS: "OutOfStock";
-    readonly ITEMS_NOT_ADDED: "ItemsNotAdded";
-    readonly ITEMS_REQUESTED_NOT_ADDED: "ItemsRequestedNotAdded";
-    readonly ITEM_NOT_ENGRAVED: "ItemEngravingError";
-    readonly ADDRESS_CHANGE: "AddressChange";
-    readonly LOCATION_AVAILABILITY: "LocationAvailability";
-    readonly PARTNER_PRODUCT_CONFIGS: "PartnerProductConfigs";
-    readonly REMOVED_EXISTING_ITEMS: "RemovedExistingCartItems";
-    readonly RETAILER_MIN: "RetailerMinNotMet";
-    readonly NO_ITEMS_IN_CART: "NoItemsInCart";
-    readonly INVALID_ID: "InvalidId";
-    readonly NO_ID: "NoId";
-    readonly CART_CHECKOUT_PROCESSED: "CartCheckoutProcessed";
-    readonly NEW_CART: "NewCart";
-    readonly DEFAULT: "CartError";
-    readonly ITEM_QTY_CHANGE: "ItemQuantityChange";
-    readonly ITEM_ID_NOT_FOUND: "ItemIdNotFound";
-    readonly ITEMS_REMOVED: "ItemsRemoved";
-    readonly COUPON_PROCESSING_ERROR: "CouponProcessingError";
-    readonly COUPON_NOT_FOUND: "CouponNotFound";
-    readonly COUPON_EXPIRED: "CouponExpired";
-    readonly NO_APPLICABLE_DISCOUNT: "NoApplicableDiscount";
-    readonly COUPON_NOT_STARTED: "CouponNotStarted";
-    readonly MINIMUM_ORDER_VALUE_NOT_MET: "MinimumOrderValueNotMet";
-    readonly MINIMUM_ORDER_UNITS_NOT_MET: "MinimumOrderUnitsNotMet";
-    readonly MINIMUM_DISTINCT_ITEMS_NOT_MET: "MinimumDistinctItemsNotMet";
-    readonly QUOTA_EXCEEDED: "QuotaExceeded";
-    readonly USER_LIMIT_EXCEEDED: "UserLimitExceeded";
-    readonly NOT_FIRST_PURCHASE: "NotFirstPurchase";
-    readonly INVALID_COUPON: "InvalidCoupon";
-    readonly INVALID_MEMBERSHIP: "InvalidMembership";
-    readonly INVALID_DOMAIN: "InvalidDomain";
-    readonly INVALID_REQUIREMENTS: "InvalidRequirements";
-    readonly INVALID_ORGANIZATION: "InvalidOrganization";
-    readonly PRODUCT_NOT_ELIGIBLE: "ProductNotEligible";
-    readonly NOT_ENOUGH_PREVIOUS_ORDERS: "NotEnoughPreviousOrders";
-    readonly PRESALE_ITEMS_NOT_ALLOWED: "PresaleItemsNotAllowed";
-    readonly PRESALE_LIMIT_EXCEEDED: "PresaleLimitExceeded";
-    readonly PRESALE_NOT_STARTED: "PresaleNotStarted";
-    readonly PRESALE_EXPIRED: "PresaleExpired";
-    readonly PRESALE_MIXED_CART: "PresaleMixedCart";
-    readonly RETAILER_DOES_NOT_ALLOW_PROMOS: "RetailerDoesNotAllowPromos";
-    readonly RETAILERS_DO_NOT_ALLOW_PROMOS: "RetailersDoNotAllowPromos";
-};
-export type CartEventEnum = (typeof CART_EVENT_ENUM)[keyof typeof CART_EVENT_ENUM];
-export declare const CHECKOUT_EVENT_ENUM: {
-    readonly ERROR_PROCESSING_GIFT_CARDS: "ErrorProcessingGiftCards";
-    readonly INVALID_GIFT_CARD_CODE: "InvalidGiftCardCodes";
-    readonly INVALID_GIFT_CARD_PARTNER: "InvalidGiftCardPartner";
-    readonly INACTIVE_GIFT_CARD: "InactiveGiftCard";
-    readonly GIFT_CARD_ALREADY_IN_USE: "GiftCardAlreadyInUse";
-    readonly GIFT_CARD_EXPIRED: "GiftCardExpired";
-    readonly GIFT_CARD_BALANCE_DEPLETED: "GiftCardBalanceDepleted";
-    readonly RETAILER_ONDEMAND_HOURS_NOT_AVAILABLE: "RetailerOnDemandHoursNotAvailable";
-    readonly ITEM_QTY_CHANGE: "ItemQuantityChange";
-    readonly MAX_QUANTITY_PER_ORDER_EXCEEDED: "MaxQuantityPerOrderExceeded";
-    readonly RETAILER_DOES_NOT_ALLOW_PROMOS: "RetailerDoesNotAllowPromos";
-    readonly RETAILERS_DO_NOT_ALLOW_PROMOS: "RetailersDoNotAllowPromos";
-    readonly RETAILER_DOES_NOT_ALLOW_GIFT_CARDS: "RetailerDoesNotAllowGiftCards";
-    readonly RETAILERS_DO_NOT_ALLOW_GIFT_CARDS: "RetailersDoNotAllowGiftCards";
-};
-export type CheckoutEventEnum = (typeof CHECKOUT_EVENT_ENUM)[keyof typeof CHECKOUT_EVENT_ENUM];
-export declare const ENUM_ADDRESS_TYPE: {
-    readonly SHIPPING: "shipping";
-    readonly BILLING: "billing";
-};
-export type AddressType = (typeof ENUM_ADDRESS_TYPE)[keyof typeof ENUM_ADDRESS_TYPE];
-export declare enum ENUM_FILTER_KEYS {
-    BRANDS = "brands",
-    FLAVOR = "flavor",
-    FULFILLMENT = "fulfillment",
-    TAGS = "tags",
-    REGION = "region",
-    VARIETY = "variety",
-    ENGRAVING = "engraving",
-    PRICE = "price",
-    PRESALE = "presale",
-    AVAILABILITY = "availability",
-    CATEGORIES = "categories",
-    SIZES = "sizes",
-    COLORS = "colors",
-    APPELLATION = "appellation",
-    COUNTRY = "country",
-    VINTAGE = "vintage",
-    MATERIALS = "materials",
-    COLLECTION_TAGS = "collectionTags"
-}
-export interface IFilterValue {
-    value: string;
-    count: number;
-}
-export type FacetFilterKeys = ENUM_FILTER_KEYS.BRANDS | ENUM_FILTER_KEYS.FLAVOR | ENUM_FILTER_KEYS.REGION | ENUM_FILTER_KEYS.VARIETY | ENUM_FILTER_KEYS.ENGRAVING | ENUM_FILTER_KEYS.PRESALE | ENUM_FILTER_KEYS.PRICE | ENUM_FILTER_KEYS.AVAILABILITY | ENUM_FILTER_KEYS.CATEGORIES | ENUM_FILTER_KEYS.SIZES | ENUM_FILTER_KEYS.COLORS | ENUM_FILTER_KEYS.APPELLATION | ENUM_FILTER_KEYS.COUNTRY | ENUM_FILTER_KEYS.VINTAGE | ENUM_FILTER_KEYS.MATERIALS | ENUM_FILTER_KEYS.TAGS;
-export interface IFilterSchema {
-    filterCategory: FacetFilterKeys;
-    filterValues: IFilterValue[];
-}

package/dist/types/interfaces/cloud/cart.interface.d.ts

@@ -1,132 +0,0 @@
-import type { CartEventEnum } from '@/enums';
-import type { ILocation } from '@/interfaces/api/address.interface';
-import type { IProduct, IProductPresale } from '@/interfaces/api/product.interface';
-import type { IRetailer } from './retailer.interface';
-export interface ICartItemEngraving {
-    isEngravable: boolean;
-    hasEngraving: boolean;
-    fee: number;
-    maxCharsPerLine: number;
-    maxLines: number;
-    location: string;
-    lines: string[];
-}
-export interface ICartItemGiftCart {
-    sender: string;
-    message: string;
-    recipients: string[];
-    sendDate: string;
-}
-export interface ICartItemAttributes {
-    engraving: ICartItemEngraving;
-    presale: IProductPresale;
-    giftCard: ICartItemGiftCart;
-}
-export interface ICartItem extends Partial<Omit<IProduct, 'attributes'>> {
-    id: string;
-    retailerId: string;
-    fulfillmentId: string;
-    variantId: string;
-    liquidId: string;
-    salsifyGrouping: string;
-    salsifyPid?: string;
-    partNumber: string;
-    upc: string;
-    sku: string;
-    name: string;
-    brand: string;
-    size: string;
-    volume: string;
-    uom: string;
-    abv: string;
-    proof: string;
-    catPath: string;
-    pack: boolean;
-    packDesc: string;
-    container: string;
-    containerType: string;
-    quantity: number;
-    maxQuantity: number;
-    unitPrice: number;
-    price: number;
-    scheduledFor: string | Date;
-    availableAt: string | Date;
-    images: string[];
-    mainImage: string;
-    attributes: ICartItemAttributes;
-}
-export interface ICartAttributesPromoCode {
-    value: string;
-    discount: number;
-    freeDelivery: boolean;
-    freeServiceFee: boolean;
-    freeShipping: boolean;
-}
-export interface ICartAttributesAmountsFees {
-    shipping: number;
-    onDemand: number;
-}
-export interface ICartAttributesAmountsDiscounts {
-    shipping: number;
-    onDemand: number;
-    engraving: number;
-    service: number;
-    products: number;
-}
-export interface ICartAttributesAmounts {
-    fees: ICartAttributesAmountsFees;
-    discounts: ICartAttributesAmountsDiscounts;
-}
-export interface ICartAttributes {
-    promoCode: ICartAttributesPromoCode;
-    amounts: ICartAttributesAmounts;
-}
-export interface ICartRetailer extends IRetailer {
-    platformFee: number;
-    engravingFee: number;
-    deliveryFee: number;
-    shippingFee: number;
-    subtotal: number;
-    total: number;
-}
-export interface ICartEvent {
-    type: CartEventEnum;
-    message: string;
-    items?: Array<Partial<ICartItem>>;
-}
-export interface ICart {
-    id: string;
-    quantity: number;
-    platformFee: number;
-    deliveryFee: number;
-    engravingFee: number;
-    shippingFee: number;
-    discounts: number;
-    giftCardTotal: number;
-    subtotal: number;
-    total: number;
-    isPresaleLocked: boolean;
-    presaleExpiresAt: string | null;
-    createdAt: string | Date;
-    updatedAt: string | Date;
-    items: ICartItem[];
-    loc: ILocation;
-    retailers: ICartRetailer[];
-    attributes: ICartAttributes;
-    events: ICartEvent[];
-}
-export interface ICartUpdateItem {
-    id?: string;
-    upc?: string;
-    partNumber: string;
-    sku?: string;
-    quantity: number;
-    fulfillmentId: string;
-    engravingLines?: string[];
-    scheduledFor?: string | Date;
-}
-export interface ICartUpdateParams {
-    id: string;
-    items: ICartUpdateItem[];
-    promoCode?: string;
-}

package/dist/types/interfaces/cloud/catalog.interface.d.ts

@@ -1,42 +0,0 @@
-import type { IProduct, IRetailer } from '@/interfaces/api/product.interface';
-export declare enum ENUM_NAVIGATION_ORDER_DIRECTION_TYPE {
-    ASC = "asc",
-    DESC = "desc"
-}
-export declare enum ENUM_ORDER_BY {
-    PRICE = "price"
-}
-export interface ICatalogParams {
-    search?: string;
-    pageToken?: string;
-    entity?: string;
-    page?: number;
-    perPage?: number;
-    visitorId?: string;
-    retailers?: string[];
-    orderBy?: ENUM_ORDER_BY;
-    orderDirection?: ENUM_NAVIGATION_ORDER_DIRECTION_TYPE;
-    filters?: Array<Record<any, any>>;
-    [key: string]: any;
-}
-export interface ICatalog {
-    retailers: Record<string, IRetailer>;
-    products?: IProduct[];
-    navigation?: INavigationSchema;
-}
-export interface ICursorSchema {
-    nextPageToken: string;
-    previousPageToken: string;
-}
-export interface INavigationSchema {
-    id: string;
-    correctedQuery: string;
-    attributionToken: string;
-    currentPage: number;
-    totalPages: number;
-    totalCount: number;
-    availableOrderBy: ENUM_ORDER_BY[];
-    availableOrderDirection: ENUM_NAVIGATION_ORDER_DIRECTION_TYPE[];
-    cursor: ICursorSchema;
-    filters: any[];
-}