@cimplify/sdk 0.6.6 → 0.6.8

package/dist/react.mjs

@@ -1,4 +1,4 @@
-import { createContext, useContext, useState, useEffect, useRef, useMemo, useCallback } from 'react';
+import { createContext, useContext, useState, useEffect, useRef, useMemo, useCallback, useSyncExternalStore } from 'react';
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 
 // src/react/index.tsx
@@ -404,9 +404,11 @@ function CimplifyCheckout({
   const elementsRef = useRef(null);
   const activeCheckoutRef = useRef(null);
   const initialAppearanceRef = useRef(appearance);
+  const hasWarnedInlineAppearanceRef = useRef(false);
   const isMountedRef = useRef(true);
   const demoRunRef = useRef(0);
   const isDemoCheckout = demoMode ?? client.getPublicKey().trim().length === 0;
+  const isTestMode = client.isTestMode();
   const emitStatus = useCallback(
     (nextStatus, context = {}) => {
       setStatus(nextStatus);
@@ -420,6 +422,14 @@ function CimplifyCheckout({
       setOrderType(resolvedOrderTypes[0] || "pickup");
     }
   }, [resolvedOrderTypes, orderType]);
+  useEffect(() => {
+    if (appearance && appearance !== initialAppearanceRef.current && !hasWarnedInlineAppearanceRef.current) {
+      hasWarnedInlineAppearanceRef.current = true;
+      console.warn(
+        "[Cimplify] `appearance` prop reference changed after mount. Elements keep the initial appearance to avoid iframe remount. Memoize appearance with useMemo() to remove this warning."
+      );
+    }
+  }, [appearance]);
   useEffect(() => {
     let cancelled = false;
     async function bootstrap() {
@@ -626,6 +636,19 @@ function CimplifyCheckout({
     return /* @__PURE__ */ jsx("div", { className, "data-cimplify-checkout": "", children: /* @__PURE__ */ jsx("p", { "data-cimplify-error": "", style: { fontSize: "14px", color: "#b91c1c" }, children: errorMessage || "Unable to initialize checkout. Please refresh and try again." }) });
   }
   return /* @__PURE__ */ jsxs("div", { className, "data-cimplify-checkout": "", children: [
+    isTestMode && !isDemoCheckout && /* @__PURE__ */ jsx(
+      "p",
+      {
+        "data-cimplify-test-mode": "",
+        style: {
+          marginBottom: "10px",
+          fontSize: "12px",
+          fontWeight: 600,
+          color: "#92400e"
+        },
+        children: "Test mode - no real charges"
+      }
+    ),
     /* @__PURE__ */ jsx("div", { "data-cimplify-section": "auth", children: /* @__PURE__ */ jsx("div", { ref: isDemoCheckout ? void 0 : authMountRef }) }),
     /* @__PURE__ */ jsx("div", { "data-cimplify-section": "order-type", style: { marginTop: "12px" }, children: /* @__PURE__ */ jsx(
       "div",
@@ -688,17 +711,88 @@ function CimplifyCheckout({
 }
 
 // src/types/common.ts
+function money(value) {
+  return value;
+}
+function moneyFromNumber(value) {
+  return value.toFixed(2);
+}
+function currencyCode(value) {
+  return value;
+}
 var ErrorCode = {
   // General
   UNKNOWN_ERROR: "UNKNOWN_ERROR",
   NETWORK_ERROR: "NETWORK_ERROR",
   TIMEOUT: "TIMEOUT",
+  UNAUTHORIZED: "UNAUTHORIZED",
   NOT_FOUND: "NOT_FOUND"};
+var DOCS_ERROR_BASE_URL = "https://docs.cimplify.io/reference/error-codes";
+function docsUrlForCode(code) {
+  return `${DOCS_ERROR_BASE_URL}#${code.toLowerCase().replace(/_/g, "-")}`;
+}
+var ERROR_SUGGESTIONS = {
+  UNKNOWN_ERROR: "An unexpected error occurred. Capture the request/response payload and retry with exponential backoff.",
+  NETWORK_ERROR: "Check the shopper's connection and retry. If this persists, inspect CORS, DNS, and API reachability.",
+  TIMEOUT: "The request exceeded the timeout. Retry once, then poll order status before charging again.",
+  UNAUTHORIZED: "Authentication is missing or expired. Ensure a valid access token is set and refresh the session if needed.",
+  FORBIDDEN: "The key/session lacks permission for this resource. Verify business ownership and API key scope.",
+  NOT_FOUND: "The requested resource does not exist or is not visible in this environment.",
+  VALIDATION_ERROR: "One or more fields are invalid. Validate required fields and enum values before retrying.",
+  CART_EMPTY: "The cart has no items. Redirect back to menu/catalogue and require at least one line item.",
+  CART_EXPIRED: "This cart is no longer active. Recreate a new cart and re-add shopper selections.",
+  CART_NOT_FOUND: "Cart could not be located. It may have expired or belongs to a different key/location.",
+  ITEM_UNAVAILABLE: "The selected item is unavailable at this location/time. Prompt the shopper to pick an alternative.",
+  VARIANT_NOT_FOUND: "The requested variant no longer exists. Refresh product data and require re-selection.",
+  VARIANT_OUT_OF_STOCK: "The selected variant is out of stock. Show in-stock variants and block checkout for this line.",
+  ADDON_REQUIRED: "A required add-on is missing. Ensure required modifier groups are completed before add-to-cart.",
+  ADDON_MAX_EXCEEDED: "Too many add-ons were selected. Enforce max selections client-side before submission.",
+  CHECKOUT_VALIDATION_FAILED: "Checkout payload failed validation. Verify customer, order type, and address fields are complete.",
+  DELIVERY_ADDRESS_REQUIRED: "Delivery orders require an address. Collect and pass address info before processing checkout.",
+  CUSTOMER_INFO_REQUIRED: "Customer details are required. Ensure name/email/phone are available before checkout.",
+  PAYMENT_FAILED: "Payment provider rejected or failed processing. Show retry/change-method options to the shopper.",
+  PAYMENT_CANCELLED: "Payment was cancelled by the shopper or provider flow. Allow a safe retry path.",
+  INSUFFICIENT_FUNDS: "Payment method has insufficient funds. Prompt shopper to use another method.",
+  CARD_DECLINED: "Card was declined. Ask shopper to retry or switch payment method.",
+  INVALID_OTP: "Authorization code is invalid. Let shopper re-enter OTP/PIN and retry.",
+  OTP_EXPIRED: "Authorization code expired. Request a new OTP and re-submit authorization.",
+  AUTHORIZATION_FAILED: "Additional payment authorization failed. Retry authorization or change payment method.",
+  PAYMENT_ACTION_NOT_COMPLETED: "Required payment action was not completed. Resume provider flow and poll for status.",
+  SLOT_UNAVAILABLE: "Selected schedule slot is unavailable. Refresh available slots and ask shopper to reselect.",
+  BOOKING_CONFLICT: "The requested booking conflicts with an existing reservation. Pick another slot/resource.",
+  SERVICE_NOT_FOUND: "Requested service no longer exists. Refresh service catalogue and retry selection.",
+  OUT_OF_STOCK: "Inventory is depleted for this item. Remove it or reduce quantity before checkout.",
+  INSUFFICIENT_QUANTITY: "Requested quantity exceeds available inventory. Reduce quantity and retry.",
+  BUSINESS_ID_REQUIRED: "Business context could not be resolved. Verify the public key and business bootstrap call.",
+  INVALID_CART: "Cart is invalid for checkout. Sync cart state, ensure items exist, then retry.",
+  ORDER_TYPE_REQUIRED: "Order type is required. Provide one of delivery, pickup, or dine_in before checkout.",
+  NO_PAYMENT_ELEMENT: "PaymentElement is required for processCheckout(). Mount it before triggering checkout.",
+  PAYMENT_NOT_MOUNTED: "PaymentElement iframe is not mounted. Mount it in the DOM before processCheckout().",
+  AUTH_INCOMPLETE: "AuthElement has not completed authentication. Wait for AUTHENTICATED before checkout.",
+  AUTH_LOST: "Session was cleared during checkout. Re-authenticate and restart checkout safely.",
+  ALREADY_PROCESSING: "Checkout is already in progress. Disable duplicate submits until completion.",
+  CHECKOUT_NOT_READY: "Checkout elements are still initializing. Wait for readiness before submit.",
+  CANCELLED: "Checkout was cancelled. Preserve cart state and allow shopper to retry.",
+  REQUEST_TIMEOUT: "Provider call timed out. Poll payment/order status before issuing another charge attempt.",
+  POPUP_BLOCKED: "Browser blocked provider popup. Ask shopper to enable popups and retry.",
+  FX_QUOTE_FAILED: "Failed to lock FX quote. Retry currency quote or fallback to base currency."
+};
+var ERROR_HINTS = Object.fromEntries(
+  Object.entries(ERROR_SUGGESTIONS).map(([code, suggestion]) => [
+    code,
+    {
+      docs_url: docsUrlForCode(code),
+      suggestion
+    }
+  ])
+);
 var CimplifyError = class extends Error {
-  constructor(code, message, retryable = false) {
+  constructor(code, message, retryable = false, docs_url, suggestion) {
     super(message);
     this.code = code;
     this.retryable = retryable;
+    this.docs_url = docs_url;
+    this.suggestion = suggestion;
     this.name = "CimplifyError";
   }
   /** User-friendly message safe to display */
@@ -706,6 +800,28 @@ var CimplifyError = class extends Error {
     return this.message;
   }
 };
+function getErrorHint(code) {
+  return ERROR_HINTS[code];
+}
+function enrichError(error, options = {}) {
+  const hint = getErrorHint(error.code);
+  if (hint) {
+    if (!error.docs_url) {
+      error.docs_url = hint.docs_url;
+    }
+    if (!error.suggestion) {
+      error.suggestion = hint.suggestion;
+    }
+  } else if (!error.docs_url) {
+    error.docs_url = docsUrlForCode(error.code || ErrorCode.UNKNOWN_ERROR);
+  }
+  if (options.isTestMode && !error.message.includes("pk_test_")) {
+    error.message = `${error.message}
+
+\u2139 Your API key is a test-mode key (pk_test_...). Verify test data/session before retrying.`;
+  }
+  return error;
+}
 
 // src/types/result.ts
 function ok(value) {
@@ -715,13 +831,18 @@ function err(error) {
   return { ok: false, error };
 }
 
+// src/query/builder.ts
+function escapeQueryValue(value) {
+  return value.replace(/'/g, "\\'");
+}
+
 // src/catalogue.ts
 function toCimplifyError(error) {
-  if (error instanceof CimplifyError) return error;
+  if (error instanceof CimplifyError) return enrichError(error);
   if (error instanceof Error) {
-    return new CimplifyError("UNKNOWN_ERROR", error.message, false);
+    return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, error.message, false));
   }
-  return new CimplifyError("UNKNOWN_ERROR", String(error), false);
+  return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, String(error), false));
 }
 async function safe(promise) {
   try {
@@ -795,7 +916,7 @@ var CatalogueQueries = class {
     let query = "products";
     const filters = [];
     if (options?.category) {
-      filters.push(`@.category_id=='${options.category}'`);
+      filters.push(`@.category_id=='${escapeQueryValue(options.category)}'`);
     }
     if (options?.featured !== void 0) {
       filters.push(`@.featured==${options.featured}`);
@@ -804,7 +925,7 @@ var CatalogueQueries = class {
       filters.push(`@.in_stock==${options.in_stock}`);
     }
     if (options?.search) {
-      filters.push(`@.name contains '${options.search}'`);
+      filters.push(`@.name contains '${escapeQueryValue(options.search)}'`);
     }
     if (options?.min_price !== void 0) {
       filters.push(`@.price>=${options.min_price}`);
@@ -835,7 +956,9 @@ var CatalogueQueries = class {
   }
   async getProductBySlug(slug) {
     const filteredResult = await safe(
-      this.client.query(`products[?(@.slug=='${slug}')]`)
+      this.client.query(
+        `products[?(@.slug=='${escapeQueryValue(slug)}')]`
+      )
     );
     if (!filteredResult.ok) return filteredResult;
     const exactMatch = findProductBySlug(filteredResult.value, slug);
@@ -887,7 +1010,7 @@ var CatalogueQueries = class {
   }
   async getCategoryBySlug(slug) {
     const result = await safe(
-      this.client.query(`categories[?(@.slug=='${slug}')]`)
+      this.client.query(`categories[?(@.slug=='${escapeQueryValue(slug)}')]`)
     );
     if (!result.ok) return result;
     if (!result.value.length) {
@@ -896,7 +1019,11 @@ var CatalogueQueries = class {
     return ok(result.value[0]);
   }
   async getCategoryProducts(categoryId) {
-    return safe(this.client.query(`products[?(@.category_id=='${categoryId}')]`));
+    return safe(
+      this.client.query(
+        `products[?(@.category_id=='${escapeQueryValue(categoryId)}')]`
+      )
+    );
   }
   async getCollections() {
     return safe(this.client.query("collections"));
@@ -906,7 +1033,9 @@ var CatalogueQueries = class {
   }
   async getCollectionBySlug(slug) {
     const result = await safe(
-      this.client.query(`collections[?(@.slug=='${slug}')]`)
+      this.client.query(
+        `collections[?(@.slug=='${escapeQueryValue(slug)}')]`
+      )
     );
     if (!result.ok) return result;
     if (!result.value.length) {
@@ -919,7 +1048,9 @@ var CatalogueQueries = class {
   }
   async searchCollections(query, limit = 20) {
     return safe(
-      this.client.query(`collections[?(@.name contains '${query}')]#limit(${limit})`)
+      this.client.query(
+        `collections[?(@.name contains '${escapeQueryValue(query)}')]#limit(${limit})`
+      )
     );
   }
   async getBundles() {
@@ -930,7 +1061,9 @@ var CatalogueQueries = class {
   }
   async getBundleBySlug(slug) {
     const result = await safe(
-      this.client.query(`bundles[?(@.slug=='${slug}')]`)
+      this.client.query(
+        `bundles[?(@.slug=='${escapeQueryValue(slug)}')]`
+      )
     );
     if (!result.ok) return result;
     if (!result.value.length) {
@@ -940,7 +1073,9 @@ var CatalogueQueries = class {
   }
   async searchBundles(query, limit = 20) {
     return safe(
-      this.client.query(`bundles[?(@.name contains '${query}')]#limit(${limit})`)
+      this.client.query(
+        `bundles[?(@.name contains '${escapeQueryValue(query)}')]#limit(${limit})`
+      )
     );
   }
   async getComposites(options) {
@@ -980,9 +1115,9 @@ var CatalogueQueries = class {
   }
   async search(query, options) {
     const limit = options?.limit ?? 20;
-    let searchQuery = `products[?(@.name contains '${query}')]`;
+    let searchQuery = `products[?(@.name contains '${escapeQueryValue(query)}')]`;
     if (options?.category) {
-      searchQuery = `products[?(@.name contains '${query}' && @.category_id=='${options.category}')]`;
+      searchQuery = `products[?(@.name contains '${escapeQueryValue(query)}' && @.category_id=='${escapeQueryValue(options.category)}')]`;
     }
     searchQuery += `#limit(${limit})`;
     return safe(this.client.query(searchQuery));
@@ -999,7 +1134,7 @@ var CatalogueQueries = class {
   async getMenu(options) {
     let query = "menu";
     if (options?.category) {
-      query = `menu[?(@.category=='${options.category}')]`;
+      query = `menu[?(@.category=='${escapeQueryValue(options.category)}')]`;
     }
     if (options?.limit) {
       query += `#limit(${options.limit})`;
@@ -1016,11 +1151,11 @@ var CatalogueQueries = class {
 
 // src/cart.ts
 function toCimplifyError2(error) {
-  if (error instanceof CimplifyError) return error;
+  if (error instanceof CimplifyError) return enrichError(error);
   if (error instanceof Error) {
-    return new CimplifyError("UNKNOWN_ERROR", error.message, false);
+    return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, error.message, false));
   }
-  return new CimplifyError("UNKNOWN_ERROR", String(error), false);
+  return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, String(error), false));
 }
 async function safe2(promise) {
   try {
@@ -1180,6 +1315,19 @@ var ORDER_MUTATION = {
   UPDATE_CUSTOMER: "order.update_order_customer"
 };
 
+// src/utils/price.ts
+function parsePrice(value) {
+  if (value === void 0 || value === null) {
+    return 0;
+  }
+  if (typeof value === "number") {
+    return isNaN(value) ? 0 : value;
+  }
+  const cleaned = value.replace(/[^\d.-]/g, "");
+  const parsed = parseFloat(cleaned);
+  return isNaN(parsed) ? 0 : parsed;
+}
+
 // src/utils/payment.ts
 var PAYMENT_SUCCESS_STATUSES = /* @__PURE__ */ new Set([
   "success",
@@ -1280,6 +1428,8 @@ function normalizeStatusResponse(response) {
   }
   const res = response;
   const normalizedStatus = normalizePaymentStatusValue(res.status ?? void 0);
+  const normalizedAmount = typeof res.amount === "string" ? money(res.amount) : typeof res.amount === "number" && Number.isFinite(res.amount) ? moneyFromNumber(res.amount) : void 0;
+  const normalizedCurrency = typeof res.currency === "string" && res.currency.trim().length > 0 ? currencyCode(res.currency) : void 0;
   const paidValue = res.paid === true;
   const derivedPaid = paidValue || [
     "success",
@@ -1292,8 +1442,8 @@ function normalizeStatusResponse(response) {
   return {
     status: normalizedStatus,
     paid: derivedPaid,
-    amount: res.amount,
-    currency: res.currency,
+    amount: normalizedAmount,
+    currency: normalizedCurrency,
     reference: res.reference,
     message: res.message || ""
   };
@@ -1859,11 +2009,11 @@ var CheckoutResolver = class {
 
 // src/checkout.ts
 function toCimplifyError3(error) {
-  if (error instanceof CimplifyError) return error;
+  if (error instanceof CimplifyError) return enrichError(error);
   if (error instanceof Error) {
-    return new CimplifyError("UNKNOWN_ERROR", error.message, false);
+    return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, error.message, false));
   }
-  return new CimplifyError("UNKNOWN_ERROR", String(error), false);
+  return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, String(error), false));
 }
 async function safe3(promise) {
   try {
@@ -1985,14 +2135,17 @@ var CheckoutService = class {
       pay_currency: data.pay_currency,
       fx_quote_id: data.fx_quote_id
     };
-    const baseCurrency = (cart.pricing.currency || checkoutData.pay_currency || "GHS").toUpperCase();
+    const baseCurrency = currencyCode(
+      (cart.pricing.currency || checkoutData.pay_currency || "GHS").toUpperCase()
+    );
     const payCurrency = data.pay_currency?.trim().toUpperCase();
+    const payCurrencyCode = payCurrency ? currencyCode(payCurrency) : void 0;
     const cartTotalAmount = Number.parseFloat(cart.pricing.total_price || "0");
-    if (payCurrency && payCurrency !== baseCurrency && !checkoutData.fx_quote_id && Number.isFinite(cartTotalAmount) && cartTotalAmount > 0) {
+    if (payCurrencyCode && payCurrencyCode !== baseCurrency && !checkoutData.fx_quote_id && Number.isFinite(cartTotalAmount) && cartTotalAmount > 0) {
       const fxQuoteResult = await this.client.fx.lockQuote({
         from: baseCurrency,
-        to: payCurrency,
-        amount: cartTotalAmount
+        to: payCurrencyCode,
+        amount: cart.pricing.total_price
       });
       if (!fxQuoteResult.ok) {
         return ok(
@@ -2003,7 +2156,7 @@ var CheckoutService = class {
           )
         );
       }
-      checkoutData.pay_currency = payCurrency;
+      checkoutData.pay_currency = payCurrencyCode;
       checkoutData.fx_quote_id = fxQuoteResult.value.id;
     }
     data.on_status_change?.("processing", {});
@@ -2039,11 +2192,11 @@ var CheckoutService = class {
 
 // src/orders.ts
 function toCimplifyError4(error) {
-  if (error instanceof CimplifyError) return error;
+  if (error instanceof CimplifyError) return enrichError(error);
   if (error instanceof Error) {
-    return new CimplifyError("UNKNOWN_ERROR", error.message, false);
+    return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, error.message, false));
   }
-  return new CimplifyError("UNKNOWN_ERROR", String(error), false);
+  return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, String(error), false));
 }
 async function safe4(promise) {
   try {
@@ -2300,11 +2453,11 @@ var AuthService = class {
 
 // src/business.ts
 function toCimplifyError7(error) {
-  if (error instanceof CimplifyError) return error;
+  if (error instanceof CimplifyError) return enrichError(error);
   if (error instanceof Error) {
-    return new CimplifyError("UNKNOWN_ERROR", error.message, false);
+    return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, error.message, false));
   }
-  return new CimplifyError("UNKNOWN_ERROR", String(error), false);
+  return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, String(error), false));
 }
 async function safe7(promise) {
   try {
@@ -2651,12 +2804,15 @@ var FxService = class {
 
 // src/elements.ts
 function toCheckoutError(code, message, recoverable) {
+  const hint = getErrorHint(code);
   return {
     success: false,
     error: {
       code,
       message,
-      recoverable
+      recoverable,
+      docs_url: hint?.docs_url,
+      suggestion: hint?.suggestion
     }
   };
 }
@@ -2697,6 +2853,7 @@ var CimplifyElements = class {
     this.paymentData = null;
     this.checkoutInProgress = false;
     this.activeCheckoutAbort = null;
+    this.hasWarnedMissingAuthElement = false;
     this.businessIdResolvePromise = null;
     this.client = client;
     this.businessId = businessId ?? null;
@@ -2792,6 +2949,12 @@ var CimplifyElements = class {
         );
       }
       const authElement = this.elements.get(ELEMENT_TYPES.AUTH);
+      if (!authElement && !this.hasWarnedMissingAuthElement) {
+        this.hasWarnedMissingAuthElement = true;
+        console.warn(
+          "[Cimplify] processCheckout() called without AuthElement mounted. For best conversion and Link enrollment, mount <AuthElement> before checkout."
+        );
+      }
       if (authElement && !this.accessToken) {
         return toCheckoutError(
           "AUTH_INCOMPLETE",
@@ -3228,28 +3391,37 @@ function isRetryable(error) {
   }
   return false;
 }
-function toNetworkError(error) {
+function toNetworkError(error, isTestMode) {
   if (error instanceof DOMException && error.name === "AbortError") {
-    return new CimplifyError(
-      ErrorCode.TIMEOUT,
-      "Request timed out. Please check your connection and try again.",
-      true
+    return enrichError(
+      new CimplifyError(
+        ErrorCode.TIMEOUT,
+        "Request timed out. Please check your connection and try again.",
+        true
+      ),
+      { isTestMode }
     );
   }
   if (error instanceof TypeError && error.message.includes("fetch")) {
-    return new CimplifyError(
-      ErrorCode.NETWORK_ERROR,
-      "Network error. Please check your internet connection.",
-      true
+    return enrichError(
+      new CimplifyError(
+        ErrorCode.NETWORK_ERROR,
+        "Network error. Please check your internet connection.",
+        true
+      ),
+      { isTestMode }
     );
   }
   if (error instanceof CimplifyError) {
-    return error;
+    return enrichError(error, { isTestMode });
   }
-  return new CimplifyError(
-    ErrorCode.UNKNOWN_ERROR,
-    error instanceof Error ? error.message : "An unknown error occurred",
-    false
+  return enrichError(
+    new CimplifyError(
+      ErrorCode.UNKNOWN_ERROR,
+      error instanceof Error ? error.message : "An unknown error occurred",
+      false
+    ),
+    { isTestMode }
   );
 }
 function deriveUrls() {
@@ -3311,6 +3483,9 @@ var CimplifyClient = class {
   getPublicKey() {
     return this.publicKey;
   }
+  isTestMode() {
+    return this.publicKey.trim().startsWith("pk_test_");
+  }
   setAccessToken(token) {
     const previous = this.accessToken;
     this.accessToken = token;
@@ -3432,7 +3607,7 @@ var CimplifyClient = class {
           signal: controller.signal
         });
         clearTimeout(timeoutId);
-        if (response.ok || response.status >= 400 && response.status < 500) {
+        if (response.ok) {
           this.hooks.onRequestSuccess?.({
             ...context,
             status: response.status,
@@ -3440,6 +3615,21 @@ var CimplifyClient = class {
           });
           return response;
         }
+        if (response.status >= 400 && response.status < 500) {
+          this.hooks.onRequestError?.({
+            ...context,
+            error: new CimplifyError(
+              `HTTP_${response.status}`,
+              `Request failed with status ${response.status}`,
+              false
+            ),
+            status: response.status,
+            durationMs: Date.now() - startTime,
+            retryCount,
+            retryable: false
+          });
+          return response;
+        }
         if (response.status >= 500 && attempt < this.maxRetries) {
           retryCount++;
           const delay = this.retryDelay * Math.pow(2, attempt);
@@ -3452,15 +3642,22 @@ var CimplifyClient = class {
           await sleep(delay);
           continue;
         }
-        this.hooks.onRequestSuccess?.({
+        this.hooks.onRequestError?.({
           ...context,
+          error: new CimplifyError(
+            "SERVER_ERROR",
+            `Server error ${response.status} after ${retryCount} retries`,
+            false
+          ),
           status: response.status,
-          durationMs: Date.now() - startTime
+          durationMs: Date.now() - startTime,
+          retryCount,
+          retryable: false
         });
         return response;
       } catch (error) {
         lastError = error;
-        const networkError = toNetworkError(error);
+        const networkError = toNetworkError(error, this.isTestMode());
         const errorRetryable = isRetryable(error);
         if (!errorRetryable || attempt >= this.maxRetries) {
           this.hooks.onRequestError?.({
@@ -3483,7 +3680,7 @@ var CimplifyClient = class {
         await sleep(delay);
       }
     }
-    const finalError = toNetworkError(lastError);
+    const finalError = toNetworkError(lastError, this.isTestMode());
     this.hooks.onRequestError?.({
       ...context,
       error: finalError,
@@ -3601,22 +3798,40 @@ var CimplifyClient = class {
   async handleRestResponse(response) {
     const json = await response.json();
     if (!response.ok) {
-      throw new CimplifyError(
-        json.error?.error_code || "API_ERROR",
-        json.error?.error_message || "An error occurred",
-        false
+      const error = enrichError(
+        new CimplifyError(
+          json.error?.error_code || "API_ERROR",
+          json.error?.error_message || "An error occurred",
+          false
+        ),
+        { isTestMode: this.isTestMode() }
       );
+      if (response.status === 401 || error.code === ErrorCode.UNAUTHORIZED) {
+        console.warn(
+          "[Cimplify] Received 401 Unauthorized. Access token may be missing/expired. Refresh authentication and retry the request."
+        );
+      }
+      throw error;
     }
     return json.data;
   }
   async handleResponse(response) {
     const json = await response.json();
     if (!json.success || json.error) {
-      throw new CimplifyError(
-        json.error?.code || "UNKNOWN_ERROR",
-        json.error?.message || "An unknown error occurred",
-        json.error?.retryable || false
+      const error = enrichError(
+        new CimplifyError(
+          json.error?.code || "UNKNOWN_ERROR",
+          json.error?.message || "An unknown error occurred",
+          json.error?.retryable || false
+        ),
+        { isTestMode: this.isTestMode() }
       );
+      if (response.status === 401 || error.code === ErrorCode.UNAUTHORIZED) {
+        console.warn(
+          "[Cimplify] Received 401 Unauthorized. Access token may be missing/expired. Refresh authentication and retry the request."
+        );
+      }
+      throw error;
     }
     return json.data;
   }
@@ -3803,6 +4018,9 @@ function CimplifyProvider({
       const nextLocations = locationsResult.ok && Array.isArray(locationsResult.value) ? locationsResult.value : [];
       const initialLocation = resolveInitialLocation(nextLocations);
       setBusiness(nextBusiness);
+      if (nextBusiness?.id) {
+        resolvedClient.setBusinessId(nextBusiness.id);
+      }
       setLocations(nextLocations);
       if (initialLocation) {
         setCurrentLocationState(initialLocation);
@@ -3861,6 +4079,1809 @@ function useCimplify() {
   }
   return context;
 }
+function useOptionalCimplify() {
+  return useContext(CimplifyContext);
+}
+var productsCache = /* @__PURE__ */ new Map();
+var productsInflight = /* @__PURE__ */ new Map();
+function buildProductsCacheKey(client, locationId, options) {
+  return JSON.stringify({
+    key: client.getPublicKey(),
+    location_id: locationId || "__none__",
+    options
+  });
+}
+function useProducts(options = {}) {
+  const context = useOptionalCimplify();
+  const client = options.client ?? context?.client;
+  if (!client) {
+    throw new Error("useProducts must be used within CimplifyProvider or passed { client }.");
+  }
+  const enabled = options.enabled ?? true;
+  const locationId = client.getLocationId();
+  const previousLocationIdRef = useRef(locationId);
+  const requestIdRef = useRef(0);
+  const queryOptions = useMemo(
+    () => ({
+      category: options.category,
+      collection: options.collection,
+      search: options.search,
+      featured: options.featured,
+      limit: options.limit
+    }),
+    [options.category, options.collection, options.featured, options.limit, options.search]
+  );
+  const cacheKey = useMemo(
+    () => buildProductsCacheKey(client, locationId, queryOptions),
+    [client, locationId, queryOptions]
+  );
+  const cached = productsCache.get(cacheKey);
+  const [products, setProducts] = useState(cached?.products ?? []);
+  const [isLoading, setIsLoading] = useState(enabled && !cached);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    if (previousLocationIdRef.current !== locationId) {
+      productsCache.clear();
+      productsInflight.clear();
+      previousLocationIdRef.current = locationId;
+    }
+  }, [locationId]);
+  const load = useCallback(
+    async (force = false) => {
+      if (!enabled) {
+        setIsLoading(false);
+        return;
+      }
+      const nextRequestId = ++requestIdRef.current;
+      setError(null);
+      if (!force) {
+        const cacheEntry = productsCache.get(cacheKey);
+        if (cacheEntry) {
+          setProducts(cacheEntry.products);
+          setIsLoading(false);
+          return;
+        }
+      }
+      setIsLoading(true);
+      try {
+        const existing = productsInflight.get(cacheKey);
+        const promise = existing ?? (async () => {
+          const result = await client.catalogue.getProducts(queryOptions);
+          if (!result.ok) {
+            throw result.error;
+          }
+          return result.value;
+        })();
+        if (!existing) {
+          productsInflight.set(
+            cacheKey,
+            promise.finally(() => {
+              productsInflight.delete(cacheKey);
+            })
+          );
+        }
+        const value = await promise;
+        productsCache.set(cacheKey, { products: value });
+        if (nextRequestId === requestIdRef.current) {
+          setProducts(value);
+          setError(null);
+        }
+      } catch (loadError) {
+        if (nextRequestId === requestIdRef.current) {
+          setError(loadError);
+        }
+      } finally {
+        if (nextRequestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [cacheKey, client, enabled, queryOptions]
+  );
+  useEffect(() => {
+    void load(false);
+  }, [load]);
+  const refetch = useCallback(async () => {
+    productsCache.delete(cacheKey);
+    await load(true);
+  }, [cacheKey, load]);
+  return { products, isLoading, error, refetch };
+}
+var productCache = /* @__PURE__ */ new Map();
+var productInflight = /* @__PURE__ */ new Map();
+function isLikelySlug(value) {
+  return /^[a-z0-9-]+$/.test(value);
+}
+function buildProductCacheKey(client, locationId, slugOrId) {
+  return JSON.stringify({
+    key: client.getPublicKey(),
+    location_id: locationId || "__none__",
+    slug_or_id: slugOrId
+  });
+}
+function useProduct(slugOrId, options = {}) {
+  const context = useOptionalCimplify();
+  const client = options.client ?? context?.client;
+  if (!client) {
+    throw new Error("useProduct must be used within CimplifyProvider or passed { client }.");
+  }
+  const enabled = options.enabled ?? true;
+  const locationId = client.getLocationId();
+  const previousLocationIdRef = useRef(locationId);
+  const requestIdRef = useRef(0);
+  const normalizedSlugOrId = useMemo(() => (slugOrId || "").trim(), [slugOrId]);
+  const cacheKey = useMemo(
+    () => buildProductCacheKey(client, locationId, normalizedSlugOrId),
+    [client, locationId, normalizedSlugOrId]
+  );
+  const cached = productCache.get(cacheKey);
+  const [product, setProduct] = useState(cached?.product ?? null);
+  const [isLoading, setIsLoading] = useState(
+    enabled && normalizedSlugOrId.length > 0 && !cached
+  );
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    if (previousLocationIdRef.current !== locationId) {
+      productCache.clear();
+      productInflight.clear();
+      previousLocationIdRef.current = locationId;
+    }
+  }, [locationId]);
+  const load = useCallback(
+    async (force = false) => {
+      if (!enabled || normalizedSlugOrId.length === 0) {
+        setProduct(null);
+        setIsLoading(false);
+        return;
+      }
+      const nextRequestId = ++requestIdRef.current;
+      setError(null);
+      if (!force) {
+        const cacheEntry = productCache.get(cacheKey);
+        if (cacheEntry) {
+          setProduct(cacheEntry.product);
+          setIsLoading(false);
+          return;
+        }
+      }
+      setIsLoading(true);
+      try {
+        const existing = productInflight.get(cacheKey);
+        const promise = existing ?? (async () => {
+          const result = isLikelySlug(normalizedSlugOrId) ? await client.catalogue.getProductBySlug(normalizedSlugOrId) : await client.catalogue.getProduct(normalizedSlugOrId);
+          if (!result.ok) {
+            throw result.error;
+          }
+          return result.value;
+        })();
+        if (!existing) {
+          productInflight.set(
+            cacheKey,
+            promise.finally(() => {
+              productInflight.delete(cacheKey);
+            })
+          );
+        }
+        const value = await promise;
+        productCache.set(cacheKey, { product: value });
+        if (nextRequestId === requestIdRef.current) {
+          setProduct(value);
+          setError(null);
+        }
+      } catch (loadError) {
+        if (nextRequestId === requestIdRef.current) {
+          setError(loadError);
+        }
+      } finally {
+        if (nextRequestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [cacheKey, client, enabled, normalizedSlugOrId]
+  );
+  useEffect(() => {
+    void load(false);
+  }, [load]);
+  const refetch = useCallback(async () => {
+    productCache.delete(cacheKey);
+    await load(true);
+  }, [cacheKey, load]);
+  return { product, isLoading, error, refetch };
+}
+var categoriesCache = /* @__PURE__ */ new Map();
+var categoriesInflight = /* @__PURE__ */ new Map();
+function buildCategoriesCacheKey(client) {
+  return client.getPublicKey() || "__demo__";
+}
+function useCategories(options = {}) {
+  const context = useOptionalCimplify();
+  const client = options.client ?? context?.client;
+  if (!client) {
+    throw new Error("useCategories must be used within CimplifyProvider or passed { client }.");
+  }
+  const enabled = options.enabled ?? true;
+  const cacheKey = useMemo(() => buildCategoriesCacheKey(client), [client]);
+  const cached = categoriesCache.get(cacheKey);
+  const [categories, setCategories] = useState(cached ?? []);
+  const [isLoading, setIsLoading] = useState(enabled && !cached);
+  const [error, setError] = useState(null);
+  const load = useCallback(
+    async (force = false) => {
+      if (!enabled) {
+        setIsLoading(false);
+        return;
+      }
+      setError(null);
+      if (!force) {
+        const cachedCategories = categoriesCache.get(cacheKey);
+        if (cachedCategories) {
+          setCategories(cachedCategories);
+          setIsLoading(false);
+          return;
+        }
+      }
+      setIsLoading(true);
+      try {
+        const existing = categoriesInflight.get(cacheKey);
+        const promise = existing ?? (async () => {
+          const result = await client.catalogue.getCategories();
+          if (!result.ok) {
+            throw result.error;
+          }
+          return result.value;
+        })();
+        if (!existing) {
+          categoriesInflight.set(
+            cacheKey,
+            promise.finally(() => {
+              categoriesInflight.delete(cacheKey);
+            })
+          );
+        }
+        const value = await promise;
+        categoriesCache.set(cacheKey, value);
+        setCategories(value);
+      } catch (loadError) {
+        setError(loadError);
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [cacheKey, client, enabled]
+  );
+  useEffect(() => {
+    void load(false);
+  }, [load]);
+  const refetch = useCallback(async () => {
+    categoriesCache.delete(cacheKey);
+    await load(true);
+  }, [cacheKey, load]);
+  return { categories, isLoading, error, refetch };
+}
+var CART_STORAGE_PREFIX = "cimplify:cart:v2";
+var DEFAULT_TAX_RATE = 0.08875;
+var cartStores = /* @__PURE__ */ new Map();
+function toNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+  return 0;
+}
+function roundMoney(value) {
+  return Math.max(0, Number(value.toFixed(2)));
+}
+function clampQuantity(quantity) {
+  if (!Number.isFinite(quantity)) {
+    return 1;
+  }
+  return Math.max(1, Math.floor(quantity));
+}
+function normalizeOptionIds(value) {
+  if (!value || value.length === 0) {
+    return void 0;
+  }
+  const normalized = Array.from(
+    new Set(
+      value.map((entry) => entry.trim()).filter((entry) => entry.length > 0)
+    )
+  ).sort();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function buildLineKey(productId, options) {
+  const parts = [productId];
+  if (options.locationId) {
+    parts.push(`l:${options.locationId}`);
+  }
+  if (options.variantId) {
+    parts.push(`v:${options.variantId}`);
+  }
+  const addOnOptionIds = normalizeOptionIds(options.addOnOptionIds);
+  if (addOnOptionIds && addOnOptionIds.length > 0) {
+    parts.push(`a:${addOnOptionIds.join(",")}`);
+  }
+  if (options.bundleSelections && options.bundleSelections.length > 0) {
+    parts.push(`b:${JSON.stringify(options.bundleSelections)}`);
+  }
+  if (options.compositeSelections && options.compositeSelections.length > 0) {
+    parts.push(`c:${JSON.stringify(options.compositeSelections)}`);
+  }
+  if (options.quoteId) {
+    parts.push(`q:${options.quoteId}`);
+  }
+  return parts.join("|");
+}
+function calculateLineSubtotal(item) {
+  let unitPrice = parsePrice(item.product.default_price);
+  if (item.variant?.price_adjustment) {
+    unitPrice += parsePrice(item.variant.price_adjustment);
+  }
+  for (const option of item.addOnOptions || []) {
+    if (option.default_price) {
+      unitPrice += parsePrice(option.default_price);
+    }
+  }
+  return roundMoney(unitPrice * item.quantity);
+}
+function calculateSummary(items) {
+  const subtotal = roundMoney(items.reduce((sum, item) => sum + calculateLineSubtotal(item), 0));
+  const tax = roundMoney(subtotal * DEFAULT_TAX_RATE);
+  return {
+    subtotal,
+    tax,
+    total: roundMoney(subtotal + tax)
+  };
+}
+function toProductFromServerItem(item, businessId) {
+  return {
+    id: item.item_id,
+    business_id: businessId,
+    category_id: item.category_id,
+    name: item.name,
+    slug: item.item_id,
+    description: item.description,
+    image_url: item.image_url,
+    default_price: item.base_price,
+    product_type: "product",
+    inventory_type: "none",
+    variant_strategy: "fetch_all",
+    is_active: item.is_available,
+    created_at: item.created_at,
+    updated_at: item.updated_at,
+    metadata: {
+      from_sdk: true
+    }
+  };
+}
+function mapServerCart(serverCart) {
+  const items = serverCart.items.map((item) => {
+    const variant = item.variant_info || item.variant_name ? {
+      id: item.variant_info?.id || item.variant_id || "",
+      name: item.variant_info?.name || item.variant_name || "Variant",
+      price_adjustment: item.variant_info?.price_adjustment
+    } : void 0;
+    const quoteId = typeof item.metadata?.quote_id === "string" ? item.metadata.quote_id : void 0;
+    return {
+      id: item.id,
+      product: toProductFromServerItem(item, serverCart.business_id),
+      quantity: clampQuantity(item.quantity),
+      locationId: serverCart.location_id,
+      variantId: item.variant_id,
+      variant,
+      quoteId,
+      addOnOptionIds: item.add_on_option_ids || void 0,
+      addOnOptions: (item.add_on_options || []).map((option) => ({
+        id: option.id,
+        name: option.name,
+        default_price: option.price
+      })),
+      bundleSelections: item.bundle_selections || void 0,
+      compositeSelections: item.composite_selections || void 0,
+      specialInstructions: item.special_instructions
+    };
+  });
+  return {
+    items,
+    subtotal: roundMoney(toNumber(serverCart.pricing.subtotal)),
+    tax: roundMoney(toNumber(serverCart.pricing.tax_amount)),
+    total: roundMoney(toNumber(serverCart.pricing.total_price)),
+    currency: serverCart.pricing.currency || "USD"
+  };
+}
+function buildStorageKey(storeKey) {
+  return `${CART_STORAGE_PREFIX}:${storeKey}`;
+}
+function createEmptySnapshot(currency) {
+  return {
+    items: [],
+    subtotal: 0,
+    tax: 0,
+    total: 0,
+    currency,
+    isLoading: true
+  };
+}
+function createCartStore(params) {
+  const { client, storeKey, locationId, isDemoMode, currency } = params;
+  const storageKey = buildStorageKey(storeKey);
+  const listeners = /* @__PURE__ */ new Set();
+  let snapshot = createEmptySnapshot(currency);
+  let initialized = false;
+  let initializePromise = null;
+  function emit() {
+    listeners.forEach((listener) => {
+      listener();
+    });
+  }
+  function setSnapshot(nextSnapshot) {
+    snapshot = nextSnapshot;
+    persistSnapshot();
+    emit();
+  }
+  function updateSnapshot(updater) {
+    setSnapshot(updater(snapshot));
+  }
+  function persistSnapshot() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    try {
+      window.localStorage.setItem(
+        storageKey,
+        JSON.stringify({
+          items: snapshot.items,
+          subtotal: snapshot.subtotal,
+          tax: snapshot.tax,
+          total: snapshot.total,
+          currency: snapshot.currency
+        })
+      );
+    } catch {
+    }
+  }
+  function hydrateFromStorage() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    try {
+      const raw = window.localStorage.getItem(storageKey);
+      if (!raw) {
+        return;
+      }
+      const parsed = JSON.parse(raw);
+      if (!parsed || !Array.isArray(parsed.items)) {
+        return;
+      }
+      snapshot = {
+        items: parsed.items,
+        subtotal: toNumber(parsed.subtotal),
+        tax: toNumber(parsed.tax),
+        total: toNumber(parsed.total),
+        currency: typeof parsed.currency === "string" && parsed.currency ? parsed.currency : currency,
+        isLoading: !isDemoMode
+      };
+      emit();
+    } catch {
+    }
+  }
+  async function sync() {
+    if (isDemoMode) {
+      updateSnapshot((current) => ({
+        ...current,
+        isLoading: false
+      }));
+      return;
+    }
+    updateSnapshot((current) => ({
+      ...current,
+      isLoading: true
+    }));
+    const result = await client.cart.get();
+    if (!result.ok) {
+      updateSnapshot((current) => ({
+        ...current,
+        isLoading: false
+      }));
+      throw result.error;
+    }
+    const next = mapServerCart(result.value);
+    setSnapshot({
+      ...next,
+      isLoading: false
+    });
+  }
+  async function maybeResolveQuoteId(product, quantity, options) {
+    if (options.quoteId) {
+      return options.quoteId;
+    }
+    const addOnOptionIds = normalizeOptionIds(options.addOnOptionIds);
+    const requiresQuote = Boolean(
+      options.variantId || addOnOptionIds && addOnOptionIds.length > 0 || options.bundleSelections && options.bundleSelections.length > 0 || options.compositeSelections && options.compositeSelections.length > 0
+    );
+    if (!requiresQuote || isDemoMode) {
+      return void 0;
+    }
+    const quoteResult = await client.catalogue.fetchQuote({
+      product_id: product.id,
+      quantity,
+      location_id: options.locationId || locationId || void 0,
+      variant_id: options.variantId,
+      add_on_option_ids: addOnOptionIds,
+      bundle_selections: options.bundleSelections,
+      composite_selections: options.compositeSelections
+    });
+    if (!quoteResult.ok) {
+      throw quoteResult.error;
+    }
+    return quoteResult.value.quote_id;
+  }
+  async function addItem(product, quantity = 1, options = {}) {
+    const resolvedQuantity = clampQuantity(quantity);
+    const normalizedOptions = {
+      ...options,
+      locationId: options.locationId || locationId || void 0,
+      addOnOptionIds: normalizeOptionIds(options.addOnOptionIds)
+    };
+    const maybeProductWithVariants = product;
+    if (Array.isArray(maybeProductWithVariants.variants) && maybeProductWithVariants.variants.length > 0 && !normalizedOptions.variantId) {
+      console.warn(
+        "[Cimplify] addItem() called without variantId for a product that has variants. Default variant pricing will be used."
+      );
+    }
+    const previousSnapshot = snapshot;
+    const lineKey = buildLineKey(product.id, normalizedOptions);
+    const optimisticItem = {
+      id: `tmp_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,
+      product,
+      quantity: resolvedQuantity,
+      locationId: normalizedOptions.locationId,
+      variantId: normalizedOptions.variantId,
+      variant: normalizedOptions.variant,
+      quoteId: normalizedOptions.quoteId,
+      addOnOptionIds: normalizedOptions.addOnOptionIds,
+      addOnOptions: normalizedOptions.addOnOptions,
+      bundleSelections: normalizedOptions.bundleSelections,
+      compositeSelections: normalizedOptions.compositeSelections,
+      specialInstructions: normalizedOptions.specialInstructions
+    };
+    updateSnapshot((current) => {
+      const existingIndex = current.items.findIndex((item) => {
+        const itemKey = buildLineKey(item.product.id, {
+          locationId: item.locationId,
+          variantId: item.variantId,
+          quoteId: item.quoteId,
+          addOnOptionIds: item.addOnOptionIds,
+          bundleSelections: item.bundleSelections,
+          compositeSelections: item.compositeSelections
+        });
+        return itemKey === lineKey;
+      });
+      const nextItems = [...current.items];
+      if (existingIndex >= 0) {
+        const existing = nextItems[existingIndex];
+        nextItems[existingIndex] = {
+          ...existing,
+          quantity: existing.quantity + resolvedQuantity
+        };
+      } else {
+        nextItems.push(optimisticItem);
+      }
+      const summary = calculateSummary(nextItems);
+      return {
+        ...current,
+        items: nextItems,
+        subtotal: summary.subtotal,
+        tax: summary.tax,
+        total: summary.total
+      };
+    });
+    if (isDemoMode) {
+      return;
+    }
+    try {
+      const quoteId = await maybeResolveQuoteId(product, resolvedQuantity, normalizedOptions);
+      const result = await client.cart.addItem({
+        item_id: product.id,
+        quantity: resolvedQuantity,
+        variant_id: normalizedOptions.variantId,
+        quote_id: quoteId,
+        add_on_options: normalizedOptions.addOnOptionIds,
+        special_instructions: normalizedOptions.specialInstructions,
+        bundle_selections: normalizedOptions.bundleSelections,
+        composite_selections: normalizedOptions.compositeSelections
+      });
+      if (!result.ok) {
+        throw result.error;
+      }
+      await sync();
+    } catch (error) {
+      snapshot = previousSnapshot;
+      persistSnapshot();
+      emit();
+      throw error;
+    }
+  }
+  async function removeItem(itemId) {
+    const previousSnapshot = snapshot;
+    updateSnapshot((current) => {
+      const nextItems = current.items.filter((item) => item.id !== itemId);
+      const summary = calculateSummary(nextItems);
+      return {
+        ...current,
+        items: nextItems,
+        subtotal: summary.subtotal,
+        tax: summary.tax,
+        total: summary.total
+      };
+    });
+    if (isDemoMode) {
+      return;
+    }
+    try {
+      const result = await client.cart.removeItem(itemId);
+      if (!result.ok) {
+        throw result.error;
+      }
+      await sync();
+    } catch (error) {
+      snapshot = previousSnapshot;
+      persistSnapshot();
+      emit();
+      throw error;
+    }
+  }
+  async function updateQuantity(itemId, quantity) {
+    if (quantity <= 0) {
+      await removeItem(itemId);
+      return;
+    }
+    const resolvedQuantity = clampQuantity(quantity);
+    const previousSnapshot = snapshot;
+    updateSnapshot((current) => {
+      const nextItems = current.items.map(
+        (item) => item.id === itemId ? {
+          ...item,
+          quantity: resolvedQuantity
+        } : item
+      );
+      const summary = calculateSummary(nextItems);
+      return {
+        ...current,
+        items: nextItems,
+        subtotal: summary.subtotal,
+        tax: summary.tax,
+        total: summary.total
+      };
+    });
+    if (isDemoMode) {
+      return;
+    }
+    try {
+      const result = await client.cart.updateQuantity(itemId, resolvedQuantity);
+      if (!result.ok) {
+        throw result.error;
+      }
+      await sync();
+    } catch (error) {
+      snapshot = previousSnapshot;
+      persistSnapshot();
+      emit();
+      throw error;
+    }
+  }
+  async function clearCart() {
+    const previousSnapshot = snapshot;
+    updateSnapshot((current) => ({
+      ...current,
+      items: [],
+      subtotal: 0,
+      tax: 0,
+      total: 0
+    }));
+    if (isDemoMode) {
+      return;
+    }
+    try {
+      const result = await client.cart.clear();
+      if (!result.ok) {
+        throw result.error;
+      }
+      await sync();
+    } catch (error) {
+      snapshot = previousSnapshot;
+      persistSnapshot();
+      emit();
+      throw error;
+    }
+  }
+  async function initialize() {
+    if (initialized) {
+      if (initializePromise) {
+        await initializePromise;
+      }
+      return;
+    }
+    initialized = true;
+    hydrateFromStorage();
+    if (isDemoMode) {
+      updateSnapshot((current) => ({
+        ...current,
+        isLoading: false
+      }));
+      return;
+    }
+    initializePromise = sync().catch(() => {
+      updateSnapshot((current) => ({
+        ...current,
+        isLoading: false
+      }));
+    });
+    await initializePromise;
+    initializePromise = null;
+  }
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    initialize,
+    addItem,
+    removeItem,
+    updateQuantity,
+    clearCart,
+    sync
+  };
+}
+function getStoreKey(client, locationId, isDemoMode) {
+  return [
+    client.getPublicKey() || "__demo__",
+    locationId || "__no_location__",
+    isDemoMode ? "demo" : "live"
+  ].join(":");
+}
+function getOrCreateStore(params) {
+  const { client, locationId, isDemoMode, currency } = params;
+  const storeKey = getStoreKey(client, locationId, isDemoMode);
+  const existing = cartStores.get(storeKey);
+  if (existing) {
+    return existing;
+  }
+  const created = createCartStore({
+    client,
+    storeKey,
+    locationId,
+    isDemoMode,
+    currency
+  });
+  cartStores.set(storeKey, created);
+  return created;
+}
+function useCart(options = {}) {
+  const context = useOptionalCimplify();
+  const client = options.client ?? context?.client;
+  if (!client) {
+    throw new Error("useCart must be used within CimplifyProvider or passed { client }.");
+  }
+  const locationId = options.locationId ?? client.getLocationId();
+  const isDemoMode = options.demoMode ?? context?.isDemoMode ?? client.getPublicKey().trim().length === 0;
+  const currency = options.currency ?? context?.currency ?? "USD";
+  const store = useMemo(
+    () => getOrCreateStore({
+      client,
+      locationId,
+      isDemoMode,
+      currency
+    }),
+    [client, currency, isDemoMode, locationId]
+  );
+  const snapshot = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot
+  );
+  useEffect(() => {
+    void store.initialize();
+  }, [store]);
+  const addItem = useCallback(
+    async (product, quantity, addOptions) => {
+      await store.addItem(product, quantity, addOptions);
+    },
+    [store]
+  );
+  const removeItem = useCallback(
+    async (itemId) => {
+      await store.removeItem(itemId);
+    },
+    [store]
+  );
+  const updateQuantity = useCallback(
+    async (itemId, quantity) => {
+      await store.updateQuantity(itemId, quantity);
+    },
+    [store]
+  );
+  const clearCart = useCallback(async () => {
+    await store.clearCart();
+  }, [store]);
+  const sync = useCallback(async () => {
+    try {
+      await store.sync();
+    } catch (syncError) {
+      throw syncError;
+    }
+  }, [store]);
+  const itemCount = useMemo(
+    () => snapshot.items.reduce((sum, item) => sum + item.quantity, 0),
+    [snapshot.items]
+  );
+  return {
+    items: snapshot.items,
+    itemCount,
+    subtotal: snapshot.subtotal,
+    tax: snapshot.tax,
+    total: snapshot.total,
+    currency: snapshot.currency,
+    isEmpty: itemCount === 0,
+    isLoading: snapshot.isLoading,
+    addItem,
+    removeItem,
+    updateQuantity,
+    clearCart,
+    sync
+  };
+}
+var orderCache = /* @__PURE__ */ new Map();
+var orderInflight = /* @__PURE__ */ new Map();
+function buildOrderCacheKey(client, orderId) {
+  return `${client.getPublicKey() || "__demo__"}:${orderId}`;
+}
+function useOrder(orderId, options = {}) {
+  const context = useOptionalCimplify();
+  const client = options.client ?? context?.client;
+  if (!client) {
+    throw new Error("useOrder must be used within CimplifyProvider or passed { client }.");
+  }
+  const normalizedOrderId = useMemo(() => (orderId || "").trim(), [orderId]);
+  const enabled = options.enabled ?? true;
+  const poll = options.poll ?? false;
+  const pollInterval = options.pollInterval ?? 5e3;
+  const requestIdRef = useRef(0);
+  const cacheKey = useMemo(
+    () => buildOrderCacheKey(client, normalizedOrderId),
+    [client, normalizedOrderId]
+  );
+  const cached = orderCache.get(cacheKey);
+  const [order, setOrder] = useState(cached?.order ?? null);
+  const [isLoading, setIsLoading] = useState(
+    enabled && normalizedOrderId.length > 0 && !cached
+  );
+  const [error, setError] = useState(null);
+  const load = useCallback(
+    async (force = false) => {
+      if (!enabled || normalizedOrderId.length === 0) {
+        setOrder(null);
+        setIsLoading(false);
+        return;
+      }
+      const nextRequestId = ++requestIdRef.current;
+      setError(null);
+      if (!force) {
+        const cacheEntry = orderCache.get(cacheKey);
+        if (cacheEntry) {
+          setOrder(cacheEntry.order);
+          setIsLoading(false);
+          return;
+        }
+      }
+      setIsLoading(true);
+      try {
+        const existing = orderInflight.get(cacheKey);
+        const promise = existing ?? (async () => {
+          const result = await client.orders.get(normalizedOrderId);
+          if (!result.ok) {
+            throw result.error;
+          }
+          return result.value;
+        })();
+        if (!existing) {
+          orderInflight.set(
+            cacheKey,
+            promise.finally(() => {
+              orderInflight.delete(cacheKey);
+            })
+          );
+        }
+        const value = await promise;
+        orderCache.set(cacheKey, { order: value });
+        if (nextRequestId === requestIdRef.current) {
+          setOrder(value);
+          setError(null);
+        }
+      } catch (loadError) {
+        if (nextRequestId === requestIdRef.current) {
+          setError(loadError);
+        }
+      } finally {
+        if (nextRequestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [cacheKey, client, enabled, normalizedOrderId]
+  );
+  useEffect(() => {
+    void load(false);
+  }, [load]);
+  useEffect(() => {
+    if (!poll || !enabled || normalizedOrderId.length === 0) {
+      return;
+    }
+    const timer = window.setInterval(() => {
+      void load(true);
+    }, Math.max(1e3, pollInterval));
+    return () => {
+      window.clearInterval(timer);
+    };
+  }, [enabled, load, normalizedOrderId.length, poll, pollInterval]);
+  const refetch = useCallback(async () => {
+    orderCache.delete(cacheKey);
+    await load(true);
+  }, [cacheKey, load]);
+  return { order, isLoading, error, refetch };
+}
+var LOCATION_STORAGE_KEY2 = "cimplify_location_id";
+function readStoredLocationId() {
+  if (typeof window === "undefined" || !window.localStorage) {
+    return null;
+  }
+  const value = window.localStorage.getItem(LOCATION_STORAGE_KEY2);
+  if (!value) {
+    return null;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+function writeStoredLocationId(locationId) {
+  if (typeof window === "undefined" || !window.localStorage) {
+    return;
+  }
+  if (!locationId) {
+    window.localStorage.removeItem(LOCATION_STORAGE_KEY2);
+    return;
+  }
+  window.localStorage.setItem(LOCATION_STORAGE_KEY2, locationId);
+}
+function resolveLocation(locations, preferredId) {
+  if (locations.length === 0) {
+    return null;
+  }
+  if (preferredId) {
+    const found = locations.find((location) => location.id === preferredId);
+    if (found) {
+      return found;
+    }
+  }
+  return locations[0];
+}
+function useLocations(options = {}) {
+  const context = useOptionalCimplify();
+  if (context && (!options.client || context.client === options.client)) {
+    return {
+      locations: context.locations,
+      currentLocation: context.currentLocation,
+      setCurrentLocation: context.setCurrentLocation,
+      isLoading: !context.isReady
+    };
+  }
+  const client = options.client;
+  const [locations, setLocations] = useState([]);
+  const [currentLocation, setCurrentLocationState] = useState(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const setCurrentLocation = useCallback(
+    (location) => {
+      setCurrentLocationState(location);
+      if (client) {
+        client.setLocationId(location.id);
+      }
+      writeStoredLocationId(location.id);
+    },
+    [client]
+  );
+  useEffect(() => {
+    if (!client) {
+      setLocations([]);
+      setCurrentLocationState(null);
+      setIsLoading(false);
+      return;
+    }
+    const activeClient = client;
+    let cancelled = false;
+    async function loadLocations() {
+      setIsLoading(true);
+      const result = await activeClient.business.getLocations();
+      if (cancelled) {
+        return;
+      }
+      if (!result.ok) {
+        setLocations([]);
+        setCurrentLocationState(null);
+        setIsLoading(false);
+        return;
+      }
+      const nextLocations = result.value;
+      const preferredId = activeClient.getLocationId() ?? readStoredLocationId();
+      const resolved = resolveLocation(nextLocations, preferredId);
+      setLocations(nextLocations);
+      setCurrentLocationState(resolved);
+      activeClient.setLocationId(resolved?.id || null);
+      writeStoredLocationId(resolved?.id || null);
+      setIsLoading(false);
+    }
+    void loadLocations();
+    return () => {
+      cancelled = true;
+    };
+  }, [client]);
+  return {
+    locations,
+    currentLocation,
+    setCurrentLocation,
+    isLoading
+  };
+}
+var collectionsCache = /* @__PURE__ */ new Map();
+var collectionsInflight = /* @__PURE__ */ new Map();
+function buildCollectionsCacheKey(client, locationId) {
+  return JSON.stringify({
+    key: client.getPublicKey(),
+    location_id: locationId || "__none__"
+  });
+}
+function useCollections(options = {}) {
+  const context = useOptionalCimplify();
+  const client = options.client ?? context?.client;
+  if (!client) {
+    throw new Error("useCollections must be used within CimplifyProvider or passed { client }.");
+  }
+  const enabled = options.enabled ?? true;
+  const locationId = client.getLocationId();
+  const previousLocationIdRef = useRef(locationId);
+  const requestIdRef = useRef(0);
+  const cacheKey = useMemo(
+    () => buildCollectionsCacheKey(client, locationId),
+    [client, locationId]
+  );
+  const cached = collectionsCache.get(cacheKey);
+  const [collections, setCollections] = useState(cached?.collections ?? []);
+  const [isLoading, setIsLoading] = useState(enabled && !cached);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    if (previousLocationIdRef.current !== locationId) {
+      collectionsCache.clear();
+      collectionsInflight.clear();
+      previousLocationIdRef.current = locationId;
+    }
+  }, [locationId]);
+  const load = useCallback(
+    async (force = false) => {
+      if (!enabled) {
+        setIsLoading(false);
+        return;
+      }
+      const nextRequestId = ++requestIdRef.current;
+      setError(null);
+      if (!force) {
+        const cacheEntry = collectionsCache.get(cacheKey);
+        if (cacheEntry) {
+          setCollections(cacheEntry.collections);
+          setIsLoading(false);
+          return;
+        }
+      }
+      setIsLoading(true);
+      try {
+        const existing = collectionsInflight.get(cacheKey);
+        const promise = existing ?? (async () => {
+          const result = await client.catalogue.getCollections();
+          if (!result.ok) {
+            throw result.error;
+          }
+          return result.value;
+        })();
+        if (!existing) {
+          collectionsInflight.set(cacheKey, promise);
+          promise.finally(() => {
+            collectionsInflight.delete(cacheKey);
+          }).catch(() => void 0);
+        }
+        const value = await promise;
+        collectionsCache.set(cacheKey, { collections: value });
+        if (nextRequestId === requestIdRef.current) {
+          setCollections(value);
+          setError(null);
+        }
+      } catch (loadError) {
+        if (nextRequestId === requestIdRef.current) {
+          setError(loadError);
+        }
+      } finally {
+        if (nextRequestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [cacheKey, client, enabled]
+  );
+  useEffect(() => {
+    void load(false);
+  }, [load]);
+  const refetch = useCallback(async () => {
+    collectionsCache.delete(cacheKey);
+    await load(true);
+  }, [cacheKey, load]);
+  return { collections, isLoading, error, refetch };
+}
+var collectionCache = /* @__PURE__ */ new Map();
+var collectionInflight = /* @__PURE__ */ new Map();
+function isLikelySlug2(value) {
+  return /^[a-z0-9-]+$/.test(value);
+}
+function buildCollectionCacheKey(client, locationId, idOrSlug) {
+  return JSON.stringify({
+    key: client.getPublicKey(),
+    location_id: locationId || "__none__",
+    collection: idOrSlug
+  });
+}
+function useCollection(idOrSlug, options = {}) {
+  const context = useOptionalCimplify();
+  const client = options.client ?? context?.client;
+  if (!client) {
+    throw new Error("useCollection must be used within CimplifyProvider or passed { client }.");
+  }
+  const enabled = options.enabled ?? true;
+  const locationId = client.getLocationId();
+  const previousLocationIdRef = useRef(locationId);
+  const requestIdRef = useRef(0);
+  const normalizedIdOrSlug = useMemo(() => (idOrSlug || "").trim(), [idOrSlug]);
+  const cacheKey = useMemo(
+    () => buildCollectionCacheKey(client, locationId, normalizedIdOrSlug),
+    [client, locationId, normalizedIdOrSlug]
+  );
+  const cached = collectionCache.get(cacheKey);
+  const [collection, setCollection] = useState(cached?.collection ?? null);
+  const [products, setProducts] = useState(cached?.products ?? []);
+  const [isLoading, setIsLoading] = useState(
+    enabled && normalizedIdOrSlug.length > 0 && !cached
+  );
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    if (previousLocationIdRef.current !== locationId) {
+      collectionCache.clear();
+      collectionInflight.clear();
+      previousLocationIdRef.current = locationId;
+    }
+  }, [locationId]);
+  const load = useCallback(
+    async (force = false) => {
+      if (!enabled || normalizedIdOrSlug.length === 0) {
+        setCollection(null);
+        setProducts([]);
+        setIsLoading(false);
+        return;
+      }
+      const nextRequestId = ++requestIdRef.current;
+      setError(null);
+      if (!force) {
+        const cacheEntry = collectionCache.get(cacheKey);
+        if (cacheEntry) {
+          setCollection(cacheEntry.collection);
+          setProducts(cacheEntry.products);
+          setIsLoading(false);
+          return;
+        }
+      }
+      setIsLoading(true);
+      try {
+        const existing = collectionInflight.get(cacheKey);
+        const promise = existing ?? (async () => {
+          const collectionResult = isLikelySlug2(normalizedIdOrSlug) ? await client.catalogue.getCollectionBySlug(normalizedIdOrSlug) : await client.catalogue.getCollection(normalizedIdOrSlug);
+          if (!collectionResult.ok) {
+            throw collectionResult.error;
+          }
+          const productsResult = await client.catalogue.getCollectionProducts(
+            collectionResult.value.id
+          );
+          if (!productsResult.ok) {
+            throw productsResult.error;
+          }
+          return {
+            collection: collectionResult.value,
+            products: productsResult.value
+          };
+        })();
+        if (!existing) {
+          collectionInflight.set(cacheKey, promise);
+          promise.finally(() => {
+            collectionInflight.delete(cacheKey);
+          }).catch(() => void 0);
+        }
+        const value = await promise;
+        collectionCache.set(cacheKey, value);
+        if (nextRequestId === requestIdRef.current) {
+          setCollection(value.collection);
+          setProducts(value.products);
+          setError(null);
+        }
+      } catch (loadError) {
+        if (nextRequestId === requestIdRef.current) {
+          setError(loadError);
+        }
+      } finally {
+        if (nextRequestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [cacheKey, client, enabled, normalizedIdOrSlug]
+  );
+  useEffect(() => {
+    void load(false);
+  }, [load]);
+  const refetch = useCallback(async () => {
+    collectionCache.delete(cacheKey);
+    await load(true);
+  }, [cacheKey, load]);
+  return { collection, products, isLoading, error, refetch };
+}
+var bundleCache = /* @__PURE__ */ new Map();
+var bundleInflight = /* @__PURE__ */ new Map();
+function isLikelySlug3(value) {
+  return /^[a-z0-9-]+$/.test(value);
+}
+function buildBundleCacheKey(client, locationId, idOrSlug) {
+  return JSON.stringify({
+    key: client.getPublicKey(),
+    location_id: locationId || "__none__",
+    bundle: idOrSlug
+  });
+}
+function useBundle(idOrSlug, options = {}) {
+  const context = useOptionalCimplify();
+  const client = options.client ?? context?.client;
+  if (!client) {
+    throw new Error("useBundle must be used within CimplifyProvider or passed { client }.");
+  }
+  const enabled = options.enabled ?? true;
+  const locationId = client.getLocationId();
+  const previousLocationIdRef = useRef(locationId);
+  const requestIdRef = useRef(0);
+  const normalizedIdOrSlug = useMemo(() => (idOrSlug || "").trim(), [idOrSlug]);
+  const cacheKey = useMemo(
+    () => buildBundleCacheKey(client, locationId, normalizedIdOrSlug),
+    [client, locationId, normalizedIdOrSlug]
+  );
+  const cached = bundleCache.get(cacheKey);
+  const [bundle, setBundle] = useState(cached?.bundle ?? null);
+  const [isLoading, setIsLoading] = useState(
+    enabled && normalizedIdOrSlug.length > 0 && !cached
+  );
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    if (previousLocationIdRef.current !== locationId) {
+      bundleCache.clear();
+      bundleInflight.clear();
+      previousLocationIdRef.current = locationId;
+    }
+  }, [locationId]);
+  const load = useCallback(
+    async (force = false) => {
+      if (!enabled || normalizedIdOrSlug.length === 0) {
+        setBundle(null);
+        setIsLoading(false);
+        return;
+      }
+      const nextRequestId = ++requestIdRef.current;
+      setError(null);
+      if (!force) {
+        const cacheEntry = bundleCache.get(cacheKey);
+        if (cacheEntry) {
+          setBundle(cacheEntry.bundle);
+          setIsLoading(false);
+          return;
+        }
+      }
+      setIsLoading(true);
+      try {
+        const existing = bundleInflight.get(cacheKey);
+        const promise = existing ?? (async () => {
+          const result = isLikelySlug3(normalizedIdOrSlug) ? await client.catalogue.getBundleBySlug(normalizedIdOrSlug) : await client.catalogue.getBundle(normalizedIdOrSlug);
+          if (!result.ok) {
+            throw result.error;
+          }
+          return result.value;
+        })();
+        if (!existing) {
+          bundleInflight.set(cacheKey, promise);
+          promise.finally(() => {
+            bundleInflight.delete(cacheKey);
+          }).catch(() => void 0);
+        }
+        const value = await promise;
+        bundleCache.set(cacheKey, { bundle: value });
+        if (nextRequestId === requestIdRef.current) {
+          setBundle(value);
+          setError(null);
+        }
+      } catch (loadError) {
+        if (nextRequestId === requestIdRef.current) {
+          setError(loadError);
+        }
+      } finally {
+        if (nextRequestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [cacheKey, client, enabled, normalizedIdOrSlug]
+  );
+  useEffect(() => {
+    void load(false);
+  }, [load]);
+  const refetch = useCallback(async () => {
+    bundleCache.delete(cacheKey);
+    await load(true);
+  }, [cacheKey, load]);
+  return { bundle, isLoading, error, refetch };
+}
+var compositeCache = /* @__PURE__ */ new Map();
+var compositeInflight = /* @__PURE__ */ new Map();
+function shouldFetchByProductId(idOrProductId, byProductId) {
+  if (typeof byProductId === "boolean") {
+    return byProductId;
+  }
+  return idOrProductId.startsWith("prod_");
+}
+function buildCompositeCacheKey(client, locationId, idOrProductId, byProductId) {
+  return JSON.stringify({
+    key: client.getPublicKey(),
+    location_id: locationId || "__none__",
+    composite: idOrProductId,
+    by_product_id: byProductId
+  });
+}
+function useComposite(idOrProductId, options = {}) {
+  const context = useOptionalCimplify();
+  const client = options.client ?? context?.client;
+  if (!client) {
+    throw new Error("useComposite must be used within CimplifyProvider or passed { client }.");
+  }
+  const enabled = options.enabled ?? true;
+  const locationId = client.getLocationId();
+  const previousLocationIdRef = useRef(locationId);
+  const requestIdRef = useRef(0);
+  const priceRequestIdRef = useRef(0);
+  const normalizedIdOrProductId = useMemo(
+    () => (idOrProductId || "").trim(),
+    [idOrProductId]
+  );
+  const byProductId = useMemo(
+    () => shouldFetchByProductId(normalizedIdOrProductId, options.byProductId),
+    [normalizedIdOrProductId, options.byProductId]
+  );
+  const cacheKey = useMemo(
+    () => buildCompositeCacheKey(client, locationId, normalizedIdOrProductId, byProductId),
+    [byProductId, client, locationId, normalizedIdOrProductId]
+  );
+  const cached = compositeCache.get(cacheKey);
+  const [composite, setComposite] = useState(cached?.composite ?? null);
+  const [isLoading, setIsLoading] = useState(
+    enabled && normalizedIdOrProductId.length > 0 && !cached
+  );
+  const [error, setError] = useState(null);
+  const [priceResult, setPriceResult] = useState(null);
+  const [isPriceLoading, setIsPriceLoading] = useState(false);
+  useEffect(() => {
+    if (previousLocationIdRef.current !== locationId) {
+      compositeCache.clear();
+      compositeInflight.clear();
+      previousLocationIdRef.current = locationId;
+    }
+  }, [locationId]);
+  const load = useCallback(
+    async (force = false) => {
+      if (!enabled || normalizedIdOrProductId.length === 0) {
+        setComposite(null);
+        setPriceResult(null);
+        setIsLoading(false);
+        return;
+      }
+      const nextRequestId = ++requestIdRef.current;
+      setError(null);
+      if (!force) {
+        const cacheEntry = compositeCache.get(cacheKey);
+        if (cacheEntry) {
+          setComposite(cacheEntry.composite);
+          setIsLoading(false);
+          return;
+        }
+      }
+      setIsLoading(true);
+      try {
+        const existing = compositeInflight.get(cacheKey);
+        const promise = existing ?? (async () => {
+          const result = byProductId ? await client.catalogue.getCompositeByProductId(normalizedIdOrProductId) : await client.catalogue.getComposite(normalizedIdOrProductId);
+          if (!result.ok) {
+            throw result.error;
+          }
+          return result.value;
+        })();
+        if (!existing) {
+          compositeInflight.set(cacheKey, promise);
+          promise.finally(() => {
+            compositeInflight.delete(cacheKey);
+          }).catch(() => void 0);
+        }
+        const value = await promise;
+        compositeCache.set(cacheKey, { composite: value });
+        if (nextRequestId === requestIdRef.current) {
+          setComposite(value);
+          setPriceResult(null);
+          setError(null);
+        }
+      } catch (loadError) {
+        if (nextRequestId === requestIdRef.current) {
+          setError(loadError);
+        }
+      } finally {
+        if (nextRequestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [byProductId, cacheKey, client, enabled, normalizedIdOrProductId]
+  );
+  useEffect(() => {
+    void load(false);
+  }, [load]);
+  const calculatePrice = useCallback(
+    async (selections, overrideLocationId) => {
+      if (!composite) {
+        return null;
+      }
+      const nextRequestId = ++priceRequestIdRef.current;
+      setIsPriceLoading(true);
+      try {
+        const result = await client.catalogue.calculateCompositePrice(
+          composite.id,
+          selections,
+          overrideLocationId
+        );
+        if (!result.ok) {
+          throw result.error;
+        }
+        if (nextRequestId === priceRequestIdRef.current) {
+          setPriceResult(result.value);
+          setError(null);
+        }
+        return result.value;
+      } catch (loadError) {
+        if (nextRequestId === priceRequestIdRef.current) {
+          setError(loadError);
+        }
+        return null;
+      } finally {
+        if (nextRequestId === priceRequestIdRef.current) {
+          setIsPriceLoading(false);
+        }
+      }
+    },
+    [client, composite]
+  );
+  const refetch = useCallback(async () => {
+    compositeCache.delete(cacheKey);
+    await load(true);
+  }, [cacheKey, load]);
+  return { composite, isLoading, error, refetch, calculatePrice, priceResult, isPriceLoading };
+}
+function useSearch(options = {}) {
+  const context = useOptionalCimplify();
+  const client = options.client ?? context?.client;
+  if (!client) {
+    throw new Error("useSearch must be used within CimplifyProvider or passed { client }.");
+  }
+  const minLength = Math.max(0, options.minLength ?? 2);
+  const debounceMs = Math.max(0, options.debounceMs ?? 300);
+  const limit = Math.max(1, options.limit ?? 20);
+  const [query, setQueryState] = useState("");
+  const [results, setResults] = useState([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const requestIdRef = useRef(0);
+  const timerRef = useRef(null);
+  useEffect(() => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    const trimmedQuery = query.trim();
+    if (trimmedQuery.length < minLength) {
+      setResults([]);
+      setError(null);
+      setIsLoading(false);
+      return;
+    }
+    const nextRequestId = ++requestIdRef.current;
+    setError(null);
+    setIsLoading(true);
+    timerRef.current = setTimeout(() => {
+      void (async () => {
+        try {
+          const result = await client.catalogue.searchProducts(trimmedQuery, {
+            limit,
+            category: options.category
+          });
+          if (!result.ok) {
+            throw result.error;
+          }
+          if (nextRequestId === requestIdRef.current) {
+            setResults(result.value);
+            setError(null);
+          }
+        } catch (loadError) {
+          if (nextRequestId === requestIdRef.current) {
+            setError(loadError);
+          }
+        } finally {
+          if (nextRequestId === requestIdRef.current) {
+            setIsLoading(false);
+          }
+        }
+      })();
+    }, debounceMs);
+    return () => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+  }, [client, debounceMs, limit, minLength, options.category, query]);
+  const setQuery = useCallback((nextQuery) => {
+    setQueryState(nextQuery);
+  }, []);
+  const clear = useCallback(() => {
+    requestIdRef.current += 1;
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    setQueryState("");
+    setResults([]);
+    setError(null);
+    setIsLoading(false);
+  }, []);
+  return { results, isLoading, error, query, setQuery, clear };
+}
+var quoteCache = /* @__PURE__ */ new Map();
+var quoteInflight = /* @__PURE__ */ new Map();
+function buildQuoteCacheKey(client, locationId, inputSignature) {
+  return JSON.stringify({
+    key: client.getPublicKey(),
+    location_id: locationId || "__none__",
+    input: inputSignature
+  });
+}
+function isQuoteExpired(quote) {
+  if (!quote?.expires_at) {
+    return false;
+  }
+  const expiresAt = Date.parse(quote.expires_at);
+  if (!Number.isFinite(expiresAt)) {
+    return false;
+  }
+  return expiresAt <= Date.now();
+}
+function normalizeInput(input, fallbackLocationId) {
+  const productId = input.productId.trim();
+  const variantId = input.variantId?.trim();
+  const locationId = input.locationId?.trim() || fallbackLocationId || void 0;
+  return {
+    product_id: productId,
+    variant_id: variantId && variantId.length > 0 ? variantId : void 0,
+    location_id: locationId && locationId.length > 0 ? locationId : void 0,
+    quantity: input.quantity,
+    add_on_option_ids: input.addOnOptionIds,
+    bundle_selections: input.bundleSelections,
+    composite_selections: input.compositeSelections
+  };
+}
+function useQuote(input, options = {}) {
+  const context = useOptionalCimplify();
+  const client = options.client ?? context?.client;
+  if (!client) {
+    throw new Error("useQuote must be used within CimplifyProvider or passed { client }.");
+  }
+  const enabled = options.enabled ?? true;
+  const autoRefresh = options.autoRefresh ?? true;
+  const refreshBeforeExpiryMs = Math.max(0, options.refreshBeforeExpiryMs ?? 3e4);
+  const locationId = client.getLocationId();
+  const requestIdRef = useRef(0);
+  const refreshTimerRef = useRef(null);
+  const expiryTimerRef = useRef(null);
+  const inputSignature = useMemo(() => JSON.stringify(input ?? null), [input]);
+  const normalizedInput = useMemo(() => {
+    if (!input) {
+      return null;
+    }
+    const normalized = normalizeInput(input, locationId);
+    return normalized.product_id.length > 0 ? normalized : null;
+  }, [inputSignature, locationId]);
+  const cacheKey = useMemo(
+    () => buildQuoteCacheKey(client, locationId, inputSignature),
+    [client, inputSignature, locationId]
+  );
+  const cached = quoteCache.get(cacheKey);
+  const [quote, setQuote] = useState(cached?.quote ?? null);
+  const [isLoading, setIsLoading] = useState(enabled && normalizedInput !== null && !cached);
+  const [error, setError] = useState(null);
+  const [isExpired, setIsExpired] = useState(isQuoteExpired(cached?.quote ?? null));
+  const [messages, setMessages] = useState(cached?.quote?.ui_messages ?? []);
+  const load = useCallback(
+    async (force = false) => {
+      if (!enabled || !normalizedInput) {
+        setQuote(null);
+        setMessages([]);
+        setIsExpired(false);
+        setError(null);
+        setIsLoading(false);
+        return;
+      }
+      const nextRequestId = ++requestIdRef.current;
+      setError(null);
+      if (!force) {
+        const cacheEntry = quoteCache.get(cacheKey);
+        if (cacheEntry) {
+          setQuote(cacheEntry.quote);
+          setMessages(cacheEntry.quote?.ui_messages ?? []);
+          setIsExpired(isQuoteExpired(cacheEntry.quote));
+          setIsLoading(false);
+          return;
+        }
+      }
+      setIsLoading(true);
+      try {
+        const existing = quoteInflight.get(cacheKey);
+        const promise = existing ?? (async () => {
+          const result = await client.catalogue.fetchQuote(normalizedInput);
+          if (!result.ok) {
+            throw result.error;
+          }
+          return result.value;
+        })();
+        if (!existing) {
+          quoteInflight.set(cacheKey, promise);
+          promise.finally(() => {
+            quoteInflight.delete(cacheKey);
+          }).catch(() => void 0);
+        }
+        const value = await promise;
+        quoteCache.set(cacheKey, { quote: value });
+        if (nextRequestId === requestIdRef.current) {
+          setQuote(value);
+          setMessages(value.ui_messages ?? []);
+          setIsExpired(isQuoteExpired(value));
+          setError(null);
+        }
+      } catch (loadError) {
+        if (nextRequestId === requestIdRef.current) {
+          setError(loadError);
+        }
+      } finally {
+        if (nextRequestId === requestIdRef.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [cacheKey, client, enabled, normalizedInput]
+  );
+  useEffect(() => {
+    void load(false);
+  }, [load]);
+  const refresh = useCallback(async () => {
+    if (!enabled || !normalizedInput) {
+      return;
+    }
+    if (!quote?.quote_id) {
+      await load(true);
+      return;
+    }
+    const nextRequestId = ++requestIdRef.current;
+    setError(null);
+    setIsLoading(true);
+    try {
+      const result = await client.catalogue.refreshQuote({
+        quote_id: quote.quote_id,
+        ...normalizedInput
+      });
+      if (!result.ok) {
+        throw result.error;
+      }
+      const refreshed = result.value.quote;
+      quoteCache.set(cacheKey, { quote: refreshed });
+      if (nextRequestId === requestIdRef.current) {
+        setQuote(refreshed);
+        setMessages(refreshed.ui_messages ?? []);
+        setIsExpired(isQuoteExpired(refreshed));
+        setError(null);
+      }
+    } catch (refreshError) {
+      if (nextRequestId === requestIdRef.current) {
+        setError(refreshError);
+      }
+    } finally {
+      if (nextRequestId === requestIdRef.current) {
+        setIsLoading(false);
+      }
+    }
+  }, [cacheKey, client, enabled, load, normalizedInput, quote]);
+  useEffect(() => {
+    if (expiryTimerRef.current) {
+      clearTimeout(expiryTimerRef.current);
+      expiryTimerRef.current = null;
+    }
+    const expiresAt = quote?.expires_at ? Date.parse(quote.expires_at) : NaN;
+    if (!Number.isFinite(expiresAt)) {
+      setIsExpired(false);
+      return;
+    }
+    const expired = expiresAt <= Date.now();
+    setIsExpired(expired);
+    if (!expired) {
+      expiryTimerRef.current = setTimeout(() => {
+        setIsExpired(true);
+      }, Math.max(0, expiresAt - Date.now()));
+    }
+    return () => {
+      if (expiryTimerRef.current) {
+        clearTimeout(expiryTimerRef.current);
+        expiryTimerRef.current = null;
+      }
+    };
+  }, [quote?.expires_at, quote?.quote_id]);
+  useEffect(() => {
+    if (refreshTimerRef.current) {
+      clearTimeout(refreshTimerRef.current);
+      refreshTimerRef.current = null;
+    }
+    if (!autoRefresh || !enabled || !quote?.expires_at) {
+      return;
+    }
+    const expiresAt = Date.parse(quote.expires_at);
+    if (!Number.isFinite(expiresAt)) {
+      return;
+    }
+    const delay = Math.max(0, expiresAt - Date.now() - refreshBeforeExpiryMs);
+    refreshTimerRef.current = setTimeout(() => {
+      void refresh();
+    }, delay);
+    return () => {
+      if (refreshTimerRef.current) {
+        clearTimeout(refreshTimerRef.current);
+        refreshTimerRef.current = null;
+      }
+    };
+  }, [autoRefresh, enabled, quote?.expires_at, quote?.quote_id, refresh, refreshBeforeExpiryMs]);
+  return { quote, isLoading, error, refresh, isExpired, messages };
+}
 var ElementsContext = createContext({
   elements: null,
   isReady: false
@@ -4021,4 +6042,4 @@ function useCheckout() {
   return { submit, process, isLoading };
 }
 
-export { Ad, AdProvider, AddressElement, AuthElement, CimplifyCheckout, CimplifyProvider, ElementsProvider, PaymentElement, useAds, useCheckout, useCimplify, useElements, useElementsReady };
+export { Ad, AdProvider, AddressElement, AuthElement, CimplifyCheckout, CimplifyProvider, ElementsProvider, PaymentElement, useAds, useBundle, useCart, useCategories, useCheckout, useCimplify, useCollection, useCollections, useComposite, useElements, useElementsReady, useLocations, useOptionalCimplify, useOrder, useProduct, useProducts, useQuote, useSearch };