@lime-bundles/react 1.0.0 → 2.1.0

package/README.md

@@ -1,6 +1,8 @@
 # @lime-bundles/react
 
-React components and hooks for Lime Bundles on Hydrogen, Next.js, Vite, Remix, or any React renderer. BYO-cart: you pass an `onAddToCart` callback; Lime Bundles renders the UI and fires analytics.
+React components and hooks for the **Lime Bundles Shopify app**. Use on Hydrogen, Next.js, Vite, Remix, or any React renderer. If you're not a merchant using Lime Bundles, this package probably isn't what you're looking for.
+
+Bring your own cart via an `onAddToCart` callback; the SDK handles data fetching, rendering, and analytics.
 
 ## Install
 
@@ -10,10 +12,10 @@ npm install @lime-bundles/react @lime-bundles/core
 
 Peer dependencies: `react >=18`, `react-dom >=18`.
 
-## Components
+## Drop-in components
 
 ```tsx
-import { FixedBundle, VolumeBundle, MixMatchBundle } from "@lime-bundles/react";
+import { FixedBundle } from "@lime-bundles/react";
 
 <FixedBundle
   shopDomain="my-shop.myshopify.com"
@@ -26,107 +28,99 @@ import { FixedBundle, VolumeBundle, MixMatchBundle } from "@lime-bundles/react";
 />
 ```
 
-All three components share the same `BundleComponentProps` shape:
+Same props for `<VolumeBundle>` and `<MixMatchBundle>`.
+
+### Props: `BundleComponentProps`
 
 | Prop | Type | Required | Notes |
 |---|---|:-:|---|
-| `shopDomain` | `string` | ✓ | Your shop domain. |
-| `storefrontAccessToken` | `string` | ✓ | Public Storefront Access Token. |
+| `shopDomain` | `string` | ✓ | Your `*.myshopify.com` domain. |
+| `storefrontAccessToken` | `string` | ✓ | Generated in `/app/settings/headless`. |
 | `bundleGid` | `string` | ✓ | Bundle metaobject GID. |
-| `onAddToCart` | `(lines: CartLineInput[]) => Promise<void>` | ✓ | Must return a Promise. Components `await` it for loading states. |
-| `appUrl` | `string` |  | Required only if `analyticsEnabled !== false`. |
-| `analyticsEnabled` | `boolean` |  | Default `true`. Set `false` to disable impression / add-to-cart POSTs. |
-| `onError` | `(error: Error) => void` |  | Fires on `StorefrontApiError`, `BundleParseError`, or errors thrown from `onAddToCart`. |
-| `locale` | `string` |  | BCP-47 locale tag. |
+| `onAddToCart` | `(lines: CartLineInput[]) => Promise<void>` | ✓ | Must return a Promise; components await it for loading states. |
+| `appUrl` | `string` |  | Required only if analytics are enabled. |
+| `analyticsEnabled` | `boolean` |  | Default `true`. `false` suppresses impression + add-to-cart POSTs. |
+| `onError` | `(error: Error) => void` |  | Fires on fetch, parse, or cart failure. |
+| `locale` | `string` |  | BCP-47 tag forwarded to the Storefront API. |
 | `className` | `string` |  | Applied to the outer wrapper. |
 
-The `CartLineInput` shape matches Shopify Hydrogen's. A structural-compat type test guards this across versions.
+`CartLineInput` matches Shopify Hydrogen's shape. A structural-compat test guards the contract across versions. Always preserve `attributes[]` so `_lime_bundle_gid` reaches Shopify; the `orders/create` webhook keys off it for purchase attribution.
 
 ## Hooks
 
-### `useBundleData`
+### `useBundleData({ shopDomain, storefrontAccessToken, bundleGid })`
 
-Client-side hook. Returns a discriminated union locked at v1.0.0:
+Fetches a single bundle by GID. Discriminated-union result.
 
 ```tsx
 import { useBundleData } from "@lime-bundles/react";
 
 function MyBundle({ bundleGid }: { bundleGid: string }) {
-  const result = useBundleData({
-    shopDomain: "my-shop.myshopify.com",
-    storefrontAccessToken: TOKEN,
-    bundleGid,
-  });
-
+  const result = useBundleData({ shopDomain, storefrontAccessToken, bundleGid });
   if (result.status === "loading") return <Skeleton />;
   if (result.status === "error") return <Error message={result.error.message} />;
-
-  // result.status === "success": result.bundle is a ParsedBundle
   return <pre>{JSON.stringify(result.bundle, null, 2)}</pre>;
 }
 ```
 
-Fetches custom CSS in parallel and injects a scoped `<style>` tag on success. No action needed from you.
+### `useBundlesForProduct({ shopDomain, storefrontAccessToken, productHandle })`
+
+Fetches every active bundle configured against a product. Equivalent to the web component's auto-detect mode. Inactive and out-of-schedule bundles are filtered out.
+
+```tsx
+import { useBundlesForProduct } from "@lime-bundles/react";
+
+const result = useBundlesForProduct({ shopDomain, storefrontAccessToken, productHandle });
+if (result.status === "success") {
+  return result.bundles.map((b) => <FixedBundle key={b.id} bundleGid={b.id} {...cartProps} />);
+}
+```
 
-Unmounting or changing the bundle GID cancels the in-flight request via `AbortController`.
+Both hooks auto-fetch merchant custom CSS and inject it as a scoped `<style>` tag. Unmount / dependency change cancels the in-flight request.
 
-## Async fetcher for RSC / SSR
+## Async fetchers for SSR / RSC
 
-Use `fetchBundleData` in a server component, Next.js `getServerSideProps`, or any non-React async context:
+For Hydrogen loaders, Next.js Server Components, or `getServerSideProps`: skip the hook and use the async helpers directly.
 
 ```ts
-import { fetchBundleData } from "@lime-bundles/react";
+import { fetchBundleData, fetchBundlesForProduct } from "@lime-bundles/react";
 
 const bundle = await fetchBundleData({
-  shopDomain: "my-shop.myshopify.com",
-  storefrontAccessToken: process.env.LIME_BUNDLES_TOKEN!,
-  bundleGid: "gid://shopify/Metaobject/42",
-  buyerIp: request.headers.get("x-forwarded-for")?.split(",")[0].trim() ?? undefined,
+  shopDomain,
+  storefrontAccessToken,
+  bundleGid,
+  buyerIp: request.headers.get("x-forwarded-for")?.split(",")[0].trim(),
 });
 ```
 
-`buyerIp` is required on SSR. Shopify may return `430 Security Rejection` for server-originated traffic on a private token without it. Pull the real client IP from whichever header your host sets (`x-forwarded-for` on Oxygen/Vercel/most hosts, `cf-connecting-ip` on Cloudflare, etc).
-
-Throws:
-- `StorefrontApiError`: network, HTTP, or GraphQL errors.
-- `BundleParseError`: metaobject missing, invalid type, inactive, not started, or expired. `error.reason` is a typed literal.
-
-## The cart contract
+`buyerIp` is mandatory on SSR. Shopify returns 430 Security Rejection for server-originated traffic without it.
 
-`onAddToCart` receives Hydrogen-compatible cart lines:
+## Build your own UI
 
-```ts
-type CartLineInput = {
-  merchandiseId: string;       // variant GID
-  quantity: number;
-  attributes: Array<{ key: string; value: string }>;
-};
-```
-
-Always preserve `attributes[].{key: "_lime_bundle_gid"}` on its way to Shopify. The `orders/create` webhook uses it for purchase attribution.
+Everything the built-in components use is re-exported for DIY consumers: pricing math, CSS-variable flatteners, image CDN transforms, countdown formatter, A/B merge, etc. See the [Build your own UI](./docs/react-nextjs.md#build-your-own-ui-diy-path) doc for the full primitives list.
 
 ## Styling
 
-Override CSS custom properties on any wrapping element:
+Merchant widget styling is applied automatically when you use `<FixedBundle>` / `<VolumeBundle>` / `<MixMatchBundle>`. For DIY UI, apply the config yourself:
 
 ```tsx
-<div style={{ "--lb-primary-color": "#e91e63" } as React.CSSProperties}>
-  <FixedBundle ... />
-</div>
+import { applyWidgetConfigVars } from "@lime-bundles/react";
+
+useEffect(() => {
+  if (ref.current) applyWidgetConfigVars(ref.current, bundle.widgetConfig);
+}, [bundle.widgetConfig]);
 ```
 
-Full reference: [css-variables.md](https://github.com/lime-app-dev/lime-bundles-app/blob/main/docs/headless/css-variables.md).
+Full CSS variable reference: [css-variables.md](./docs/css-variables.md).
 
-## Versioning
+## Version policy
 
-Major versions bump together across `core`, `react`, and `widget`. The hook's `UseBundleDataResult` type and `BundleComponentProps` are locked at v1.0.0.
+`BundleComponentProps`, `UseBundleDataResult`, and `UseBundlesForProductResult` are locked at v2.0.0. All three packages (`core`, `react`, `widget`) bump majors together.
 
 ## License
 
-MIT. See repo root.
+MIT.
 
-## Links
+## Support
 
-- [Hydrogen guide](https://github.com/lime-app-dev/lime-bundles-app/blob/main/docs/headless/hydrogen.md)
-- [React / Next.js guide](https://github.com/lime-app-dev/lime-bundles-app/blob/main/docs/headless/react-nextjs.md)
-- [Report issues](https://github.com/lime-app-dev/lime-bundles-app/issues)
+Merchant support and bug reports: email via the Lime Bundles listing on the Shopify App Store.

package/dist/index.cjs

@@ -20,15 +20,47 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  BundleParseError: () => import_core8.BundleParseError,
+  BUNDLES_FOR_PRODUCT_QUERY: () => import_core10.BUNDLES_FOR_PRODUCT_QUERY,
+  BUNDLE_METAOBJECT_QUERY: () => import_core10.BUNDLE_METAOBJECT_QUERY,
+  BundleParseError: () => import_core9.BundleParseError,
   FixedBundle: () => FixedBundle,
   MixMatchBundle: () => MixMatchBundle,
-  StorefrontApiError: () => import_core8.StorefrontApiError,
+  SHOP_CUSTOM_CSS_QUERY: () => import_core10.SHOP_CUSTOM_CSS_QUERY,
+  StorefrontApiError: () => import_core9.StorefrontApiError,
   VolumeBundle: () => VolumeBundle,
+  WIDGET_CONFIG_DEFAULTS: () => import_core10.WIDGET_CONFIG_DEFAULTS,
+  applyABVariantB: () => import_core10.applyABVariantB,
+  applyWidgetConfigVars: () => import_core10.applyWidgetConfigVars,
+  calculateDiscount: () => import_core10.calculateDiscount,
+  calculateTierSavings: () => import_core10.calculateTierSavings,
+  computeBundleSaleCents: () => import_core10.computeBundleSaleCents,
+  computeFixedPricing: () => import_core10.computeFixedPricing,
+  createStorefrontClient: () => import_core10.createStorefrontClient,
   fetchBundleData: () => fetchBundleData,
+  fetchBundlesForProduct: () => import_core10.fetchBundlesForProduct,
   fetchShopCustomCss: () => fetchShopCustomCss,
+  formatCents: () => import_core10.formatCents,
+  formatCountdown: () => import_core10.formatCountdown,
+  formatMoney: () => import_core10.formatMoney,
+  getABTestAssignment: () => import_core10.getABTestAssignment,
+  getActiveTier: () => import_core10.getActiveTier,
+  hasConsent: () => import_core10.hasConsent,
+  injectCustomCss: () => import_core10.injectCustomCss,
+  mergeWidgetConfig: () => import_core10.mergeWidgetConfig,
+  observeImpression: () => import_core10.observeImpression,
+  parseCents: () => import_core10.parseCents,
+  parseMetaobjectBundle: () => import_core10.parseMetaobjectBundle,
+  parseMetaobjectBundleStrict: () => import_core10.parseMetaobjectBundleStrict,
+  percentageDiscountUnit: () => import_core10.percentageDiscountUnit,
+  reportAddToCart: () => import_core10.reportAddToCart,
+  reportImpression: () => import_core10.reportImpression,
+  sanitizeCustomCss: () => import_core10.sanitizeCustomCss,
+  setConsent: () => import_core10.setConsent,
+  transformImageUrl: () => import_core10.transformImageUrl,
   useAnalytics: () => useAnalytics,
-  useBundleData: () => useBundleData
+  useBundleData: () => useBundleData,
+  useBundlesForProduct: () => useBundlesForProduct,
+  validateQuantity: () => import_core10.validateQuantity
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -328,7 +360,7 @@ function FixedBundle(props) {
             onClick: handleAddToCart,
             disabled: addingToCart,
             "aria-busy": addingToCart,
-            children: addingToCart ? "Adding..." : bundle.widgetConfig.ctaText ?? "Add Bundle to Cart"
+            children: addingToCart ? "Adding..." : bundle.widgetConfig.cta.ctaText ?? "Add Bundle to Cart"
           }
         )
       ]
@@ -554,7 +586,7 @@ function MixMatchBundle(props) {
             onClick: handleAddToCart,
             disabled: addingToCart || !validation.valid,
             "aria-busy": addingToCart,
-            children: addingToCart ? "Adding..." : bundle.widgetConfig.ctaText ?? `Add ${totalQuantity} Items to Cart`
+            children: addingToCart ? "Adding..." : bundle.widgetConfig.cta.ctaText ?? `Add ${totalQuantity} Items to Cart`
           }
         )
       ]
@@ -609,7 +641,12 @@ function VolumeBundle(props) {
   const product = bundle?.products[0];
   const basePrice = product ? parseFloat(product.priceRange.minVariantPrice.amount) : 0;
   const currency = product?.priceRange.minVariantPrice.currencyCode ?? "USD";
-  const tierSavings = bundle ? (0, import_core7.calculateTierSavings)(bundle.volumeTiers, basePrice, quantity) : [];
+  const tierSavings = bundle ? (0, import_core7.calculateTierSavings)(
+    bundle.volumeTiers,
+    basePrice,
+    quantity,
+    bundle.discountConfig.discountType
+  ) : [];
   const activeTier = bundle ? (0, import_core7.getActiveTier)(bundle.volumeTiers, quantity) : null;
   const handleAddToCart = (0, import_react5.useCallback)(async () => {
     if (!bundle || !product) return;
@@ -629,7 +666,7 @@ function VolumeBundle(props) {
     setCartError(null);
     try {
       await onAddToCart(lines);
-      const unitPrice = activeTier ? basePrice * (1 - activeTier.discountValue / 100) : basePrice;
+      const unitPrice = tierSavings.find((ts) => ts.tier === activeTier)?.unitPrice ?? basePrice;
       trackAddToCart({
         productId: product.id,
         quantity,
@@ -712,8 +749,7 @@ function VolumeBundle(props) {
                     "Save ",
                     ts.savingsPercent.toFixed(0),
                     "%"
-                  ] }),
-                  ts.tier.label && /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("span", { className: "lb-bundle__tier-label", role: "cell", children: ts.tier.label })
+                  ] })
                 ]
               },
               ts.tier.minQuantity
@@ -763,7 +799,7 @@ function VolumeBundle(props) {
             onClick: handleAddToCart,
             disabled: addingToCart,
             "aria-busy": addingToCart,
-            children: addingToCart ? "Adding..." : bundle.widgetConfig.ctaText ?? `Add ${quantity} to Cart`
+            children: addingToCart ? "Adding..." : bundle.widgetConfig.cta.ctaText ?? `Add ${quantity} to Cart`
           }
         )
       ]
@@ -771,18 +807,104 @@ function VolumeBundle(props) {
   );
 }
 
-// src/index.ts
+// src/hooks/useBundlesForProduct.ts
+var import_react6 = require("react");
 var import_core8 = require("@lime-bundles/core");
+var INITIAL_STATE2 = {
+  status: "loading",
+  bundles: null,
+  error: null
+};
+function useBundlesForProduct(options) {
+  const [state, setState] = (0, import_react6.useState)(
+    INITIAL_STATE2
+  );
+  (0, import_react6.useEffect)(() => {
+    const controller = new AbortController();
+    setState(INITIAL_STATE2);
+    (0, import_core8.fetchBundlesForProduct)({
+      shopDomain: options.shopDomain,
+      storefrontAccessToken: options.storefrontAccessToken,
+      productHandle: options.productHandle,
+      buyerIp: options.buyerIp,
+      signal: controller.signal
+    }).then((bundles) => {
+      if (controller.signal.aborted) return;
+      setState({ status: "success", bundles, error: null });
+    }).catch((err) => {
+      if (controller.signal.aborted) return;
+      setState({
+        status: "error",
+        bundles: null,
+        error: err instanceof Error ? err : new Error(String(err))
+      });
+    });
+    fetchShopCustomCss({
+      shopDomain: options.shopDomain,
+      storefrontAccessToken: options.storefrontAccessToken,
+      signal: controller.signal
+    }).then((css) => {
+      if (controller.signal.aborted) return;
+      (0, import_core8.injectCustomCss)(options.shopDomain, css);
+    }).catch(() => {
+    });
+    return () => {
+      controller.abort();
+    };
+  }, [
+    options.shopDomain,
+    options.storefrontAccessToken,
+    options.productHandle,
+    options.buyerIp
+  ]);
+  return state;
+}
+
+// src/index.ts
+var import_core9 = require("@lime-bundles/core");
+var import_core10 = require("@lime-bundles/core");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BUNDLES_FOR_PRODUCT_QUERY,
+  BUNDLE_METAOBJECT_QUERY,
   BundleParseError,
   FixedBundle,
   MixMatchBundle,
+  SHOP_CUSTOM_CSS_QUERY,
   StorefrontApiError,
   VolumeBundle,
+  WIDGET_CONFIG_DEFAULTS,
+  applyABVariantB,
+  applyWidgetConfigVars,
+  calculateDiscount,
+  calculateTierSavings,
+  computeBundleSaleCents,
+  computeFixedPricing,
+  createStorefrontClient,
   fetchBundleData,
+  fetchBundlesForProduct,
   fetchShopCustomCss,
+  formatCents,
+  formatCountdown,
+  formatMoney,
+  getABTestAssignment,
+  getActiveTier,
+  hasConsent,
+  injectCustomCss,
+  mergeWidgetConfig,
+  observeImpression,
+  parseCents,
+  parseMetaobjectBundle,
+  parseMetaobjectBundleStrict,
+  percentageDiscountUnit,
+  reportAddToCart,
+  reportImpression,
+  sanitizeCustomCss,
+  setConsent,
+  transformImageUrl,
   useAnalytics,
-  useBundleData
+  useBundleData,
+  useBundlesForProduct,
+  validateQuantity
 });
 //# sourceMappingURL=index.cjs.map