@lime-bundles/widget 3.2.2 → 3.4.0

package/dist/index.d.cts

@@ -1,5 +1,64 @@
+import { BuyerResolver } from '@lime-bundles/core';
+
+/**
+ * <lime-bundle> Web Component — renders Lime Bundles on any storefront.
+ *
+ * ## The two modes
+ *
+ * Single-bundle (pinned):
+ *   <lime-bundle
+ *     shop-domain="my-shop.myshopify.com"
+ *     storefront-token="shpat_..."
+ *     bundle-gid="gid://shopify/Metaobject/42"
+ *   ></lime-bundle>
+ *
+ * Product-aware (matches classic Liquid theme block behaviour — one snippet
+ * on the product page renders every active bundle configured against that
+ * product):
+ *   <lime-bundle
+ *     shop-domain="my-shop.myshopify.com"
+ *     storefront-token="shpat_..."
+ *   ></lime-bundle>
+ *
+ * Product resolution cascade (when no `bundle-gid` is set):
+ *   1. explicit `product-handle` attribute
+ *   2. <meta name="shopify:product-handle" content="..."> on the page
+ *   3. /products/<handle> segment of window.location.pathname
+ *   4. fallthrough: renders nothing, fires `lime-bundle:error`
+ *
+ * ## Add-to-cart behaviour
+ *
+ * Merchants who do nothing get a default: the widget calls Shopify's
+ * Storefront Cart API (tokenless — no extra scopes required) and redirects
+ * the browser to the returned checkoutUrl. One-click-to-checkout is the
+ * right UX for most merchants pasting the widget into Webflow / Wix /
+ * Squarespace / static HTML.
+ *
+ * Merchants with their own cart state (Hydrogen's useCart, a custom cart
+ * drawer, etc.) opt out by attaching a listener that calls
+ * `event.preventDefault()`:
+ *
+ *   document.querySelector("lime-bundle").addEventListener(
+ *     "lime-bundle:add-to-cart",
+ *     (ev) => {
+ *       ev.preventDefault();           // suppress the default redirect
+ *       myCart.linesAdd(ev.detail.lines);
+ *     },
+ *   );
+ *
+ * The event is always dispatched; only the default action is conditional.
+ */
+
 declare class LimeBundleElement extends HTMLElement {
     static observedAttributes: string[];
+    /**
+     * B2B buyer identity. Set programmatically — `element.buyer = {...}` or
+     * `element.buyer = () => fetchToken()`. NEVER expose as an HTML attribute
+     * because the customer access token would land in DOM snapshots (Sentry,
+     * analytics, browser extensions) and Referer headers. See the package
+     * README ("Markets & B2B").
+     */
+    buyer: BuyerResolver | undefined;
     private shadow;
     private bundles;
     private abortController;
@@ -28,16 +87,38 @@ declare class LimeBundleElement extends HTMLElement {
     private get productHandleAttr();
     private get appUrl();
     private get analyticsEnabled();
+    private get country();
+    private get language();
+    private get marketId();
+    /**
+     * Returns the @inContext-wrapped query when any context field is set;
+     * otherwise the plain query. Keeps responses publicly cacheable when
+     * no buyer/country/language is set.
+     */
+    private wrapQueryForContext;
+    /**
+     * Returns true if this bundle should be hidden for the current market.
+     * For "all" bundles, always returns false (visible). For "specific"
+     * bundles, returns true when no marketId was set or when the bundle's
+     * marketIds doesn't include the configured market.
+     */
+    private isMarketHidden;
     private fetchBundle;
     /**
-     * Resolve the visitor's A/B bucket for every bundle with an active test
-     * and merge Variant B overrides where applicable. Runs in parallel; any
-     * assignment failure logs internally but still renders Variant A (safe
-     * default). The `getABTestAssignment` helper persists the bucket via a
-     * first-party cookie; variant attribution is recorded server-side from
-     * the analytics events the widget already emits.
+     * Resolve the visitor's assigned variant for every primary bundle in a link
+     * group. Runs in parallel; any assignment failure logs internally and still
+     * renders the primary (safe default). The `getLinkGroupAssignment` helper
+     * persists the bucket via a first-party cookie; variant attribution is
+     * recorded server-side from the cart-line `_lime_bundle_gid` + `_lime_link_group`
+     * attributes the cart-add path stamps when an assignment lands on a non-primary
+     * variant.
+     *
+     * When the assignment points to a non-primary variant the SDK swaps in that
+     * variant's `ParsedBundle` from the primary's `linkGroup.variants` list. The
+     * variant data must already be present in the storefront query response — the
+     * SDK does NOT issue a separate metaobject fetch on the hot path.
      */
-    private applyABVariants;
+    private applyLinkGroupVariants;
     private fetchSingleBundle;
     private fetchProductBundles;
     /**

package/dist/index.d.ts

@@ -1,5 +1,64 @@
+import { BuyerResolver } from '@lime-bundles/core';
+
+/**
+ * <lime-bundle> Web Component — renders Lime Bundles on any storefront.
+ *
+ * ## The two modes
+ *
+ * Single-bundle (pinned):
+ *   <lime-bundle
+ *     shop-domain="my-shop.myshopify.com"
+ *     storefront-token="shpat_..."
+ *     bundle-gid="gid://shopify/Metaobject/42"
+ *   ></lime-bundle>
+ *
+ * Product-aware (matches classic Liquid theme block behaviour — one snippet
+ * on the product page renders every active bundle configured against that
+ * product):
+ *   <lime-bundle
+ *     shop-domain="my-shop.myshopify.com"
+ *     storefront-token="shpat_..."
+ *   ></lime-bundle>
+ *
+ * Product resolution cascade (when no `bundle-gid` is set):
+ *   1. explicit `product-handle` attribute
+ *   2. <meta name="shopify:product-handle" content="..."> on the page
+ *   3. /products/<handle> segment of window.location.pathname
+ *   4. fallthrough: renders nothing, fires `lime-bundle:error`
+ *
+ * ## Add-to-cart behaviour
+ *
+ * Merchants who do nothing get a default: the widget calls Shopify's
+ * Storefront Cart API (tokenless — no extra scopes required) and redirects
+ * the browser to the returned checkoutUrl. One-click-to-checkout is the
+ * right UX for most merchants pasting the widget into Webflow / Wix /
+ * Squarespace / static HTML.
+ *
+ * Merchants with their own cart state (Hydrogen's useCart, a custom cart
+ * drawer, etc.) opt out by attaching a listener that calls
+ * `event.preventDefault()`:
+ *
+ *   document.querySelector("lime-bundle").addEventListener(
+ *     "lime-bundle:add-to-cart",
+ *     (ev) => {
+ *       ev.preventDefault();           // suppress the default redirect
+ *       myCart.linesAdd(ev.detail.lines);
+ *     },
+ *   );
+ *
+ * The event is always dispatched; only the default action is conditional.
+ */
+
 declare class LimeBundleElement extends HTMLElement {
     static observedAttributes: string[];
+    /**
+     * B2B buyer identity. Set programmatically — `element.buyer = {...}` or
+     * `element.buyer = () => fetchToken()`. NEVER expose as an HTML attribute
+     * because the customer access token would land in DOM snapshots (Sentry,
+     * analytics, browser extensions) and Referer headers. See the package
+     * README ("Markets & B2B").
+     */
+    buyer: BuyerResolver | undefined;
     private shadow;
     private bundles;
     private abortController;
@@ -28,16 +87,38 @@ declare class LimeBundleElement extends HTMLElement {
     private get productHandleAttr();
     private get appUrl();
     private get analyticsEnabled();
+    private get country();
+    private get language();
+    private get marketId();
+    /**
+     * Returns the @inContext-wrapped query when any context field is set;
+     * otherwise the plain query. Keeps responses publicly cacheable when
+     * no buyer/country/language is set.
+     */
+    private wrapQueryForContext;
+    /**
+     * Returns true if this bundle should be hidden for the current market.
+     * For "all" bundles, always returns false (visible). For "specific"
+     * bundles, returns true when no marketId was set or when the bundle's
+     * marketIds doesn't include the configured market.
+     */
+    private isMarketHidden;
     private fetchBundle;
     /**
-     * Resolve the visitor's A/B bucket for every bundle with an active test
-     * and merge Variant B overrides where applicable. Runs in parallel; any
-     * assignment failure logs internally but still renders Variant A (safe
-     * default). The `getABTestAssignment` helper persists the bucket via a
-     * first-party cookie; variant attribution is recorded server-side from
-     * the analytics events the widget already emits.
+     * Resolve the visitor's assigned variant for every primary bundle in a link
+     * group. Runs in parallel; any assignment failure logs internally and still
+     * renders the primary (safe default). The `getLinkGroupAssignment` helper
+     * persists the bucket via a first-party cookie; variant attribution is
+     * recorded server-side from the cart-line `_lime_bundle_gid` + `_lime_link_group`
+     * attributes the cart-add path stamps when an assignment lands on a non-primary
+     * variant.
+     *
+     * When the assignment points to a non-primary variant the SDK swaps in that
+     * variant's `ParsedBundle` from the primary's `linkGroup.variants` list. The
+     * variant data must already be present in the storefront query response — the
+     * SDK does NOT issue a separate metaobject fetch on the hot path.
      */
-    private applyABVariants;
+    private applyLinkGroupVariants;
     private fetchSingleBundle;
     private fetchProductBundles;
     /**

package/dist/index.js

@@ -12,8 +12,9 @@ import {
   reportAddToCart,
   injectCustomCss,
   sanitizeCustomCss,
-  getABTestAssignment,
-  applyABVariantB
+  getLinkGroupAssignment,
+  hasInContext,
+  withInContext
 } from "@lime-bundles/core";
 
 // src/renderers/fixed.ts
@@ -4137,8 +4138,19 @@ var LimeBundleElement = class extends HTMLElement {
     "product-handle",
     "app-url",
     "analytics",
-    "locale"
+    "locale",
+    "country",
+    "language",
+    "market-id"
   ];
+  /**
+   * B2B buyer identity. Set programmatically — `element.buyer = {...}` or
+   * `element.buyer = () => fetchToken()`. NEVER expose as an HTML attribute
+   * because the customer access token would land in DOM snapshots (Sentry,
+   * analytics, browser extensions) and Referer headers. See the package
+   * README ("Markets & B2B").
+   */
+  buyer = void 0;
   shadow;
   bundles = [];
   abortController = null;
@@ -4201,6 +4213,40 @@ var LimeBundleElement = class extends HTMLElement {
   get analyticsEnabled() {
     return this.getAttribute("analytics") !== "false";
   }
+  get country() {
+    return this.getAttribute("country") ?? void 0;
+  }
+  get language() {
+    return this.getAttribute("language") ?? void 0;
+  }
+  get marketId() {
+    return this.getAttribute("market-id") ?? void 0;
+  }
+  /**
+   * Returns the @inContext-wrapped query when any context field is set;
+   * otherwise the plain query. Keeps responses publicly cacheable when
+   * no buyer/country/language is set.
+   */
+  wrapQueryForContext(query) {
+    return hasInContext({
+      shopDomain: this.shopDomain,
+      accessToken: this.storefrontToken,
+      country: this.country,
+      language: this.language,
+      buyer: this.buyer
+    }) ? withInContext(query) : query;
+  }
+  /**
+   * Returns true if this bundle should be hidden for the current market.
+   * For "all" bundles, always returns false (visible). For "specific"
+   * bundles, returns true when no marketId was set or when the bundle's
+   * marketIds doesn't include the configured market.
+   */
+  isMarketHidden(bundle) {
+    if (bundle.marketVisibility !== "specific") return false;
+    if (!this.marketId) return true;
+    return !bundle.marketIds.includes(this.marketId);
+  }
   async fetchBundle() {
     if (!this.shopDomain || !this.storefrontToken) {
       this.renderError(
@@ -4214,7 +4260,10 @@ var LimeBundleElement = class extends HTMLElement {
     this.renderLoading();
     const client = createStorefrontClient({
       shopDomain: this.shopDomain,
-      accessToken: this.storefrontToken
+      accessToken: this.storefrontToken,
+      country: this.country,
+      language: this.language,
+      buyer: this.buyer
     });
     try {
       let bundlePromise;
@@ -4253,7 +4302,7 @@ var LimeBundleElement = class extends HTMLElement {
         const sanitized = sanitizeCustomCss(css.shop.metafield.value);
         if (sanitized.ok) this.shopCustomCss = sanitized.css;
       }
-      await this.applyABVariants();
+      await this.applyLinkGroupVariants();
       this.renderBundles();
     } catch (err) {
       if (controller.signal.aborted) return;
@@ -4265,40 +4314,54 @@ var LimeBundleElement = class extends HTMLElement {
     }
   }
   /**
-   * Resolve the visitor's A/B bucket for every bundle with an active test
-   * and merge Variant B overrides where applicable. Runs in parallel; any
-   * assignment failure logs internally but still renders Variant A (safe
-   * default). The `getABTestAssignment` helper persists the bucket via a
-   * first-party cookie; variant attribution is recorded server-side from
-   * the analytics events the widget already emits.
+   * Resolve the visitor's assigned variant for every primary bundle in a link
+   * group. Runs in parallel; any assignment failure logs internally and still
+   * renders the primary (safe default). The `getLinkGroupAssignment` helper
+   * persists the bucket via a first-party cookie; variant attribution is
+   * recorded server-side from the cart-line `_lime_bundle_gid` + `_lime_link_group`
+   * attributes the cart-add path stamps when an assignment lands on a non-primary
+   * variant.
+   *
+   * When the assignment points to a non-primary variant the SDK swaps in that
+   * variant's `ParsedBundle` from the primary's `linkGroup.variants` list. The
+   * variant data must already be present in the storefront query response — the
+   * SDK does NOT issue a separate metaobject fetch on the hot path.
    */
-  async applyABVariants() {
+  async applyLinkGroupVariants() {
     if (this.bundles.length === 0) return;
+    const bundleLookupByMetaobjectId = /* @__PURE__ */ new Map();
+    for (const b of this.bundles) {
+      bundleLookupByMetaobjectId.set(b.id, b);
+    }
     const results = await Promise.all(
       this.bundles.map(async (bundle) => {
-        if (!bundle.abTestId || !bundle.abVariantB) return bundle;
+        const lg = bundle.linkGroup;
+        if (!lg || !lg.isPrimary || !lg.variants || lg.variants.length < 2) {
+          return bundle;
+        }
         try {
-          const assignment = await getABTestAssignment(
-            bundle.abTestId,
-            bundle.id
+          const assignment = await getLinkGroupAssignment(lg.id, lg.variants);
+          if (!assignment) return bundle;
+          if (assignment.variantMetaobjectId === bundle.id) return bundle;
+          const swap = bundleLookupByMetaobjectId.get(
+            assignment.variantMetaobjectId
           );
-          if (assignment?.variant === "B") {
-            return applyABVariantB(bundle);
-          }
+          if (!swap) return bundle;
+          return swap;
         } catch (err) {
           console.warn(
-            `[lime-bundle] A/B assignment failed for bundle ${bundle.id}; falling back to Variant A.`,
+            `[lime-bundle] link-group assignment failed for bundle ${bundle.id}; falling back to primary.`,
             err
           );
+          return bundle;
         }
-        return bundle;
       })
     );
     this.bundles = results;
   }
   async fetchSingleBundle(client, signal) {
     const data = await client.query(
-      BUNDLE_METAOBJECT_QUERY,
+      this.wrapQueryForContext(BUNDLE_METAOBJECT_QUERY),
       { id: this.bundleGid },
       { signal }
     );
@@ -4310,11 +4373,11 @@ var LimeBundleElement = class extends HTMLElement {
       data.metaobject.id,
       data.metaobject.fields
     );
-    this.bundles = parsed ? [parsed] : [];
+    this.bundles = parsed && !this.isMarketHidden(parsed) ? [parsed] : [];
   }
   async fetchProductBundles(client, signal, productHandle) {
     const data = await client.query(
-      BUNDLES_FOR_PRODUCT_QUERY,
+      this.wrapQueryForContext(BUNDLES_FOR_PRODUCT_QUERY),
       { handle: productHandle },
       { signal }
     );
@@ -4326,7 +4389,7 @@ var LimeBundleElement = class extends HTMLElement {
     const bundles = [];
     for (const ref of refs) {
       const parsed = parseMetaobjectBundle(ref.id, ref.fields);
-      if (parsed) bundles.push(parsed);
+      if (parsed && !this.isMarketHidden(parsed)) bundles.push(parsed);
     }
     this.bundles = bundles;
   }