@behio/storefront-sdk 1.18.0 → 2.0.0

package/README.md

@@ -26,42 +26,94 @@ const storefront = new BehioStorefront({
   apiKey: 'pk_live_your_key',
 });
 
-// Fetch products
-const { items } = await storefront.catalog.getProducts({ limit: 12 });
-
-// Add to cart
-await storefront.cart.addItem({ productId: items[0].id, quantity: 1 });
-
-// Checkout
-const order = await storefront.checkout.createOrder({
-  email: 'customer@example.com',
-  shippingAddress: { firstName: 'Jan', lastName: 'Novak', street: 'Vodickova 12', city: 'Praha', zip: '11000', country: 'CZ' },
+// Fetch products and check the typed result.
+const products = await storefront.catalog.getProducts({limit: 12});
+if (products.error || !products.data.items.length) throw new Error('No products available');
+await storefront.cart.addItem({productId: products.data.items[0].id, quantity: 1});
+
+// After the customer enters addresses and selects shipping/payment:
+const previewResult = await storefront.checkout.preview(checkoutInput);
+if (previewResult.error) throw new Error(previewResult.error.message);
+// Render previewResult.data.grandTotal. Wait for the customer to submit.
+const orderResult = await storefront.checkout.createOrder({
+  ...checkoutInput,
+  previewToken: previewResult.data.previewToken,
 });
+if (orderResult.error) throw new Error(orderResult.error.message);
+// Redirect to paymentRedirectUrl, or display the receipt for orderResult.data.
+
 ```
 
+Paid orders may briefly return `contentDeliveryPending: true` while purchased
+files and course access are being assigned. Render this state in the initial
+receipt HTML and refresh the authenticated order detail until it clears. Tell
+the customer that payment was received and that they do not need to place a
+second order. Existing downloads remain usable while other content is pending.
+Behio stores this work with the payment transaction and retries interrupted or
+failed delivery after restart. Repeating delivery preserves access expiry,
+download counters and course progress.
+
+## Product resources and variant pages
+
+Render `resolveVariantContent(product, selectedVariant).assetGroups` in the
+initial HTML. A variant with public resources replaces the parent's groups; an
+empty or absent array inherits them. Render every group and respect item order,
+localized titles and sanitized descriptions. Files are normal public links,
+images open at full size, uploaded videos use native controls, and external
+YouTube/Vimeo players load after an explicit click. Preserve Vimeo's unlisted
+privacy hash. These groups never contain purchased download URLs.
+
+`requiresShipping` and `isDigital` belong to the selected variant. Use them for
+its delivery information; the cart remains authoritative for the whole order.
+`catalogSiblings` contains separate product pages: render real localized links
+and mark `isCurrent`, preserving the remaining axes in the variant picker.
+Disable values that have no purchasable variant; use `isPurchasable` so zero-stock
+BACKORDER options remain selectable. Clear incompatible axis selections.
+
+Product reviews must also be present in the first HTML. Fetch page one on the
+server and pass it as `initialData` to `useProductReviews`; page and limit identify
+the cache entry. Use the selected variant's ID and own rating, render photos and
+merchant replies, and distinguish failures from an empty list. Verified purchase
+requires authenticated order ownership. A helpful vote with `success: false` is
+a duplicate; errors must roll back optimistic counts.
+
 ## React Hooks
 
+Catalog pricing supports a request-specific `country` alongside `currency` and
+customer authentication. `new BehioStorefront({apiKey, country: 'SK', currency:
+'EUR'})` resolves country rules on every catalog surface. `setCountry()` changes
+that default; explicit per-call country values win. It does not change the cart:
+use `cart.setDestination()` for that. The Next.js adapter reads `behio_country`
+for the initial server render. Keep authenticated responses private and include
+both currency and country in guest cache keys.
+When initializing a new cart, `cart.setCurrency()` and `cart.setDestination()`
+save its returned session before the next mutation. Templates should initialize
+this context before the first product or bundle is added, including after the
+previous cart expires.
+
 ```tsx
-import { BehioProvider, useProducts, useCart, useAddToCart } from '@behio/storefront-sdk/react';
+import { BehioProvider, useProducts, useCart } from '@behio/storefront-sdk/react';
 
 function App() {
   return (
-    <BehioProvider client={storefront}>
+    <BehioProvider apiKey="pk_live_your_key">
       <ProductList />
     </BehioProvider>
   );
 }
 
 function ProductList() {
-  const { data, isLoading } = useProducts({ limit: 12 });
-  const addToCart = useAddToCart();
+  const { items, isLoading, error } = useProducts({ limit: 12 });
+  const { addItem, isAdding } = useCart();
 
   if (isLoading) return <div>Loading...</div>;
 
-  return data.items.map(p => (
+  if (error) return <p role="alert">Products could not be loaded.</p>;
+
+  return items.map(p => (
     <div key={p.id}>
-      <h3>{p.name}, {p.price} {p.currency}</h3>
-      <button onClick={() => addToCart.mutateAsync({ productId: p.id, quantity: 1 })}>
+      <h3>{p.name}, {p.price ? `${p.price.amount} ${p.price.currency}` : "Sign in to view price"}</h3>
+      <button disabled={isAdding || !p.isPurchasable} onClick={() => addItem(p.id, 1).catch(() => window.alert("The item could not be added."))}>
         Add to Cart
       </button>
     </div>
@@ -69,6 +121,15 @@ function ProductList() {
 }
 ```
 
+The example above shows browser hook usage. Production templates render the
+initial catalog/cart on the server and hydrate their data. HTTP-only sessions
+stay behind Server Actions or a session-bound API. `useCart()` returns `cart`,
+`isEmpty`, `itemCount` and its mutation methods. Update/removal retain the last
+complete server snapshot while pending and accept the entire successful response,
+even when query fetching is disabled. Failed writes do not roll back newer cache
+values. `isEmpty` includes bundle lines; `itemCount` uses server bundle quantities.
+The provider notifies hooks after restoring browser session storage.
+
 ## What's Included
 
 ### SDK Modules
@@ -78,7 +139,7 @@ function ProductList() {
 | `catalog` | Products, categories, labels, search, filters, bundles, cross-sell, promotions |
 | `auth` | Register, login, logout, password reset, token refresh |
 | `cart` | Items, discounts, gift cards, bundles, cart merge |
-| `checkout` | Create orders with atomic stock/payment validation |
+| `checkout` | Preview the final total and create orders with a signed price review |
 | `orders` | List, detail, tracking, cancel |
 | `customer` | Profile, addresses, password change |
 | `wishlist` | Add, remove, check |
@@ -94,7 +155,7 @@ function ProductList() {
 
 ### React Hooks (30+)
 
-`useProducts` · `useProduct` · `useCategories` · `useCategoryProducts` · `useFeaturedProducts` · `useLabels` · `useProductSearch` · `useFilters` · `useBundles` · `useBundle` · `useCrossSell` · `useProductPromotions` · `useGiftCardBalance` · `useCart` · `useAddToCart` · `useUpdateCartItem` · `useRemoveCartItem` · `useCheckout` · `useOrders` · `useOrder` · `useOrderTracking` · `useCustomerProfile` · `useAddresses` · `useAddressAutocomplete` · `useWishlist` · `useProductReviews` · `useSubmitReview` · `useShopInfo` · `useShopSeo` · `useCartCount` · `useBlogs` · `useBlogPosts` · `useBlogPost` · `useSiteForm` · `useSiteFormSubmit`
+`useProducts` · `useProduct` · `useCategories` · `useFeatured` · `useLabels` · `useSearch` · `useFilters` · `useBundles` · `useBundle` · `useCrossSell` · `useProductPromotions` · `useGiftCardBalance` · `useCart` · `useCheckout` · `useOrders` · `useOrder` · `useCustomer` · `useAddresses` · `useAddressAutocomplete` · `useWishlist` · `useProductReviews` · `useSubmitReview` · `useShopInfo` · `useShopSeo` · `useCartCount` · `useBlogs` · `useBlogPosts` · `useBlogPost` · `useSiteForm` · `useSiteFormSubmit`
 
 ### Framework Support
 
@@ -122,3 +183,132 @@ Full API reference, framework guides, and examples:
 ## License
 
 MIT
+
+## Checkout price review and merchant policies
+
+Call `checkout.preview(input)` after the shopper completes delivery and payment choices.
+Render its `grandTotal`, then send its `previewToken` with the final `createOrder` input.
+The token lasts five minutes and is bound to the current cart, prices and choices. A
+changed or expired review returns `be.storefront.checkoutChanged`: refresh the display
+and wait for the shopper to submit again. `useCheckoutPreview` is available for React;
+Server Actions are preferred when storing the guest receipt token in an HttpOnly cookie.
+
+`discountTotal` includes loyalty and gift-card deductions. Receipt snapshots add
+`paymentFee`, `roundingAdjustment`, `loyaltyDiscount`, and `giftCardDeducted`; null denotes
+an older order. Never double-subtract a breakdown. Use `cart.checkoutLimits` for min/max
+values in cart currency. Checkout flags, account/password policy, appearance, maintenance,
+SEO and currency display come from the typed shop contract. See the checkout documentation
+for independent legal consents and the exact preview lifecycle.
+
+
+Physical delivery uses `product.requiresShipping` and `cart.requiresShipping`, independently
+of downloadable bonuses. Online-only orders need a billing address and omit shipping.
+`CourseListItem.isRevoked` and `DigitalDownload.isRevoked` distinguish withdrawn access
+from expiry. Course purchases have independent access periods; retries do not extend
+access, and refunding one purchase preserves another valid purchase.
+
+Delivery progress uses `Cart.shippingSubtotal`, after product promotions and before order coupons/loyalty/gift cards. `shippingPromotionApplied` marks an active free-delivery promotion. Method thresholds already include the shop-wide threshold converted into the requested currency. Online carts (`requiresShipping: false`) have no delivery progress.
+
+Guest course purchases are linked to an account only after its email address is
+verified, even when email verification is optional for registration. Purchases
+made while authenticated belong to that account. A different checkout receipt
+email cannot claim another account’s courses. Unverified accounts cannot extend
+their access using guest purchases sent to the same address. Render a verification
+notice for unverified customers in the course area without revealing guest purchases.
+
+Show customer cancellation only for an owned `PENDING` and `UNPAID` order.
+The backend checks both states while holding the order lock; payment can change
+after the page loads, so keep a visible error and refresh the order after rejection.
+Cancellation restores the actual remaining stock deduction once. Warehouse
+allocation identifiers are internal and must never be rendered by a template.
+
+### Canonical discovery URLs
+
+`catalog.getSitemap(locale?)` follows canonical variant indexing and bound-domain
+product selection. Its entries and `ProductDetail.seo` expose optional
+`localizedSlugs` in 1.20, mapping enabled languages to actual canonical slugs.
+Use those for hreflang and language links; omit unknown translations instead
+of inventing them. Crawler clients must be sessionless. In Next metadata routes,
+call `connection()` before dynamic SDK fetches and verify a production build.
+
+### Catalog availability and price privacy
+
+A failed price entitlement lookup returns HTTP 503 with `be.storefront.pricingUnavailable`; unrestricted guest pricing is never a fallback. With `throwOnAvailabilityError: true`, catch known SDK availability exceptions only where an explicit server-rendered error and retry replace the failed content. A `{data, error}` check alone cannot handle that exception path. Never treat an outage as zero reviews, zero products, a free offer, or a 404.
+
+### Complete category filters
+
+`catalog.getCategoryProducts(slug, query)` shares the full `ProductsQuery` serializer with `getProducts`. Price bounds retain zero, boolean filters retain false, arrays use repeated parameters and public parameter/facet selections use JSON. Category, main-list and featured availability follow the same published-variant and stock-mode rules in the backend.
+
+### Bundle offers and galleries (2.0, unreleased)
+
+`catalog.getBundles({locale, currency, country})` and `getBundle(slug, options)`
+return explicit `priceHidden`, `isPurchasable` and `unavailableReason` alongside
+nullable prices and savings. Never render a null price as zero. Honor
+`quantityRules.minimum`, `step` and nullable `maximum` for additional complete
+sets in the current visitor basket. The server accounts for component steps,
+ordinary rows, other bundles, shared stock and merchant limits. Bundle list/detail
+requests carry the cart session and customer, return private `no-store` data, and
+must not enter shared caches. Hidden stock does not expose a numerical ceiling. React bundle
+hooks accept the same context plus server `initialData` and separate query caches
+by that context. They wait for session restoration; cart and auth hooks refresh
+their ranges after basket or identity changes. Direct core bundle mutations need
+cart refresh plus cancellation/invalidation of both bundle query prefixes.
+API errors require a retry state; they are not an empty catalog.
+
+Merge a product's listing `images` with its shared `media` and deduplicate safe
+URLs. A shared video must not hide additional listing photos. Render the image
+links in the first HTML, then enhance thumbnail selection and native video.
+
+Bundle checkout previews resolve the current explicit currency offer and component
+rules. Submit the preview token with the confirmed order; handle `checkoutChanged`
+by showing a new preview. Pending orders hold the bundle quota, terminal
+cancellation/refund releases it, and reopening must claim it again. Stock modes
+ALWAYS_AVAILABLE and MADE_TO_ORDER override saved tracked-stock limits throughout
+cart, checkout and order transitions, while retaining exact inventory movements.
+
+Cart bundle lines return the **current** offer in the legacy-named
+`bundlePriceSnapshot` field. Stored cart and order snapshots are unchanged by a
+read. Show `priceChanged` and use `quantityControls.decreaseTo` / `increaseTo`
+for exact resulting whole-set quantities; null disables that direction. Keep
+server validation errors next to the row. Older servers can omit these controls. Native
+server-bound quantity/remove forms work before hydration. Bundle components keep
+their own tax rates and their allocated price participates in coupon targeting;
+cart reads recheck coupon eligibility after merchant or cart changes.
+
+Version 2 changes bundle catalog prices and `CartBundleLine.bundlePriceSnapshot`
+to nullable values. Update consumers before upgrading: null is unavailable,
+never a free offer. An invalid bundle stays in the cart with `isPurchasable: false`
+and an `unavailableReason`; keep its remove control. `QUANTITY_UNAVAILABLE` may
+be repairable by changing the quantity. When `cart.totalsAvailable === false`,
+hide monetary totals and disable checkout in both cart and mini cart. Do not
+interpret the remaining numeric summary fields as a payable quote. The server
+rechecks component publication, sale windows, quantity, stock and domain selection
+before a bundle mutation. The SDK retains the session returned when an anonymous
+visitor first adds a bundle, so subsequent reads address the same cart.
+
+### Retained product rows (2.0, unreleased)
+
+SDK 2 sends `X-Behio-Cart-Contract: 2` on every cart request. This opts into
+nullable current prices. On the same v1 route, clients without this header
+retain numeric, same-currency stored price snapshots when the current offer
+disappears. That compatibility projection is not purchase authorization:
+preview and checkout always validate the current offer. An old client still
+needs upgrading to display the new availability and repair controls. Snapshots
+never bypass hidden-price authentication or relabel a foreign currency.
+
+A product row also reports `isPurchasable` and `unavailableReason`. Its unit,
+line and tax amounts, plus `product.currentPrice`, are nullable when there is
+no current currency price. Do not revive an old snapshot or show null as zero.
+Keep the row removable; `cart.totalsAvailable` applies to products and bundles.
+
+Prefer `item.quantityControls.decreaseTo` and `increaseTo` for cart steppers.
+A null target disables that direction. These targets account for units of the
+same product inside bundles, other listings sharing its stock, merchant minima,
+step multiples and maximums. They can jump directly to a valid repair after a
+merchant edit. Existing fractional units keep their fraction when no merchant
+step is configured. The server validates the resulting basket before writing;
+show returned errors next to the native form and reread the authoritative cart.
+
+Domain-bound availability is preserved in currency, destination, code, merge,
+and removal responses. Analytics must omit unknown amounts and must not emit a
+payable cart value when `totalsAvailable` is false.

package/dist/{chunk-W2P2D3EZ.mjs → chunk-SCFR6JH7.mjs}

@@ -181,6 +181,7 @@ var BehioStorefront = class {
     this.shopDomain = config.shopDomain;
     this.defaultLocale = config.locale;
     this.defaultCurrency = config.currency;
+    this.setCountry(config.country);
     this.fetchFn = config.fetch || globalThis.fetch.bind(globalThis);
     this.timeout = config.timeout ?? 3e4;
     this.retries = config.retries ?? 1;
@@ -342,6 +343,14 @@ var BehioStorefront = class {
   getCurrency() {
     return this.defaultCurrency;
   }
+  /** Set the catalog's delivery country. Use cart.setDestination separately for the cart. */
+  setCountry(country) {
+    const normalized = country?.trim().toUpperCase();
+    this.defaultCountry = normalized && /^[A-Z]{2}$/.test(normalized) ? normalized : void 0;
+  }
+  getCountry() {
+    return this.defaultCountry;
+  }
   /** Set the default locale sent on every catalog request (per-call wins). */
   setLocale(locale) {
     this.defaultLocale = locale || void 0;
@@ -497,12 +506,16 @@ var BehioStorefront = class {
     if (this.defaultCurrency && !params.has("currency")) {
       params.set("currency", this.defaultCurrency);
     }
+    if (this.defaultCountry && path.startsWith("/catalog/") && !params.has("country")) {
+      params.set("country", this.defaultCountry);
+    }
     const qs = params.toString();
     const url = `${this.baseUrl}/storefront/v1${path}${qs ? `?${qs}` : ""}`;
     const headers = {
       "X-Api-Key": this.apiKey,
       "Content-Type": "application/json"
     };
+    if (path === "/cart" || path.startsWith("/cart/")) headers["X-Behio-Cart-Contract"] = "2";
     if (this.shopDomain) {
       headers["X-Shop-Domain"] = this.shopDomain;
     }
@@ -629,42 +642,46 @@ var BehioStorefront = class {
     throw new BehioNetworkError("Request failed after retries");
   }
 };
+function catalogProductsQuery(query) {
+  const q = {};
+  if (query) {
+    if (query.page !== void 0) q.page = query.page;
+    if (query.limit !== void 0) q.limit = query.limit;
+    if (query.category) q.category = query.category;
+    if (query.label) q.label = query.label;
+    if (query.priceMin !== void 0) q.priceMin = query.priceMin;
+    if (query.priceMax !== void 0) q.priceMax = query.priceMax;
+    if (query.currency) q.currency = query.currency;
+    if (query.country) q.country = query.country;
+    if (query.locale) q.locale = query.locale;
+    if (query.sort) q.sort = query.sort;
+    if (query.inStock !== void 0) q.inStock = query.inStock;
+    if (query.ratingMin !== void 0) q.ratingMin = query.ratingMin;
+    if (query.search) q.search = query.search;
+    if (query.parameters) q.parameters = JSON.stringify(query.parameters);
+    if (query.facets) q.facets = JSON.stringify(query.facets);
+    if (query.ids && query.ids.length > 0) q.ids = query.ids;
+    if (query.slugs && query.slugs.length > 0) q.slugs = query.slugs;
+    if (query.labels && query.labels.length > 0) q.labels = query.labels;
+    if (query.categories && query.categories.length > 0)
+      q.categories = query.categories;
+    if (query.excludeIds && query.excludeIds.length > 0)
+      q.excludeIds = query.excludeIds;
+    if (query.excludeCategories && query.excludeCategories.length > 0)
+      q.excludeCategories = query.excludeCategories;
+    if (query.hasDiscount !== void 0) q.hasDiscount = query.hasDiscount;
+    if (query.isFeatured !== void 0) q.isFeatured = query.isFeatured;
+    if (query.createdAfter !== void 0) q.createdAfter = query.createdAfter;
+  }
+  return q;
+}
 var CatalogModule = class {
   constructor(client) {
     this.client = client;
   }
   /** List products with filtering, pagination, search */
   async getProducts(query) {
-    const q = {};
-    if (query) {
-      if (query.page) q.page = query.page;
-      if (query.limit) q.limit = query.limit;
-      if (query.category) q.category = query.category;
-      if (query.label) q.label = query.label;
-      if (query.priceMin) q.priceMin = query.priceMin;
-      if (query.priceMax) q.priceMax = query.priceMax;
-      if (query.currency) q.currency = query.currency;
-      if (query.country) q.country = query.country;
-      if (query.locale) q.locale = query.locale;
-      if (query.sort) q.sort = query.sort;
-      if (query.inStock !== void 0) q.inStock = query.inStock;
-      if (query.ratingMin !== void 0) q.ratingMin = query.ratingMin;
-      if (query.search) q.search = query.search;
-      if (query.parameters) q.parameters = JSON.stringify(query.parameters);
-      if (query.facets) q.facets = JSON.stringify(query.facets);
-      if (query.ids && query.ids.length > 0) q.ids = query.ids;
-      if (query.slugs && query.slugs.length > 0) q.slugs = query.slugs;
-      if (query.labels && query.labels.length > 0) q.labels = query.labels;
-      if (query.categories && query.categories.length > 0)
-        q.categories = query.categories;
-      if (query.excludeIds && query.excludeIds.length > 0)
-        q.excludeIds = query.excludeIds;
-      if (query.excludeCategories && query.excludeCategories.length > 0)
-        q.excludeCategories = query.excludeCategories;
-      if (query.hasDiscount !== void 0) q.hasDiscount = query.hasDiscount;
-      if (query.isFeatured !== void 0) q.isFeatured = query.isFeatured;
-      if (query.createdAfter !== void 0) q.createdAfter = query.createdAfter;
-    }
+    const q = catalogProductsQuery(query);
     return this.client.request(
       "GET",
       "/catalog/products",
@@ -706,14 +723,7 @@ var CatalogModule = class {
   }
   /** Get products in a category */
   async getCategoryProducts(slug, query) {
-    const q = {};
-    if (query) {
-      if (query.page) q.page = query.page;
-      if (query.limit) q.limit = query.limit;
-      if (query.sort) q.sort = query.sort;
-      if (query.locale) q.locale = query.locale;
-      if (query.currency) q.currency = query.currency;
-    }
+    const q = catalogProductsQuery(query);
     return this.client.request(
       "GET",
       `/catalog/categories/${slug}/products`,
@@ -747,7 +757,7 @@ var CatalogModule = class {
       "GET",
       "/catalog/featured",
       {
-        query: { locale: options?.locale, currency: options?.currency }
+        query: { locale: options?.locale, currency: options?.currency, country: options?.country }
       }
     );
   }
@@ -805,9 +815,10 @@ var CatalogModule = class {
     if (query) {
       if (query.category) q.category = query.category;
       if (query.label) q.label = query.label;
-      if (query.priceMin) q.priceMin = query.priceMin;
-      if (query.priceMax) q.priceMax = query.priceMax;
+      if (query.priceMin !== void 0) q.priceMin = query.priceMin;
+      if (query.priceMax !== void 0) q.priceMax = query.priceMax;
       if (query.currency) q.currency = query.currency;
+      if (query.country) q.country = query.country;
       if (query.locale) q.locale = query.locale;
       if (query.inStock !== void 0) q.inStock = query.inStock;
       if (query.ratingMin !== void 0) q.ratingMin = query.ratingMin;
@@ -829,12 +840,12 @@ var CatalogModule = class {
     return this.getProducts({ search: query, ...options });
   }
   /** List all active bundles */
-  async getBundles() {
-    return this.client.request("GET", "/catalog/bundles");
+  async getBundles(options) {
+    return this.client.request("GET", "/catalog/bundles", { query: { ...options } });
   }
   /** Get a single bundle by slug */
-  async getBundle(slug) {
-    return this.client.request("GET", `/catalog/bundles/${slug}`);
+  async getBundle(slug, options) {
+    return this.client.request("GET", `/catalog/bundles/${encodeURIComponent(slug)}`, { query: { ...options } });
   }
   /**
    * One product group ("collection") by slug with its products as standard
@@ -847,7 +858,7 @@ var CatalogModule = class {
       "GET",
       `/catalog/product-groups/${encodeURIComponent(slug)}`,
       {
-        query: { locale: options?.locale, currency: options?.currency }
+        query: { locale: options?.locale, currency: options?.currency, country: options?.country }
       }
     );
   }
@@ -862,7 +873,7 @@ var CatalogModule = class {
     return this.client.request(
       "GET",
       `/catalog/products/${encodeURIComponent(productSlug)}/cross-sell`,
-      { query: { locale: options?.locale, currency: options?.currency } }
+      { query: { locale: options?.locale, currency: options?.currency, country: options?.country } }
     );
   }
   /** Active promotions applicable to a product (with countdown end time) */
@@ -1070,6 +1081,7 @@ var CartModule = class {
       body: { currency }
     });
     if (res.error) return res;
+    if (res.data.sessionToken) this.client.setCartSession(res.data.sessionToken);
     this.client.emit("cart:updated", res.data);
     return res;
   }
@@ -1090,6 +1102,7 @@ var CartModule = class {
       body: input
     });
     if (res.error) return res;
+    if (res.data.sessionToken) this.client.setCartSession(res.data.sessionToken);
     this.client.emit("cart:updated", res.data);
     return res;
   }
@@ -1174,14 +1187,15 @@ var CartModule = class {
       body
     });
     if (res.error) return res;
+    if (res.data.sessionToken) this.client.setCartSession(res.data.sessionToken);
     this.client.emit("cart:updated", res.data);
     return res;
   }
-  /** Update quantity of a bundle already in the cart */
-  async updateBundleQuantity(bundleId, quantity) {
+  /** Update by CartBundleLine.id; legacy catalog bundle IDs are accepted by the API */
+  async updateBundleQuantity(lineId, quantity) {
     const res = await this.client.request(
       "PATCH",
-      `/cart/bundles/${bundleId}`,
+      `/cart/bundles/${lineId}`,
       {
         body: { quantity }
       }
@@ -1190,11 +1204,11 @@ var CartModule = class {
     this.client.emit("cart:updated", res.data);
     return res;
   }
-  /** Remove a bundle from the cart */
-  async removeBundle(bundleId) {
+  /** Remove by CartBundleLine.id; scoped to the current visitor cart */
+  async removeBundle(lineId) {
     const res = await this.client.request(
       "DELETE",
-      `/cart/bundles/${bundleId}`
+      `/cart/bundles/${lineId}`
     );
     if (res.error) return res;
     this.client.emit("cart:updated", res.data);
@@ -1228,6 +1242,12 @@ var CheckoutModule = class {
   constructor(client) {
     this.client = client;
   }
+  /** Recalculate the current cart including shipping, fees, benefits and rounding.
+   * No order, stock claim, payment or gift-card redemption is created. Required
+   * legal consents are enforced only on createOrder, not while quoting. */
+  async preview(input) {
+    return this.client.request("POST", "/checkout/preview", { body: input });
+  }
   /** Create order from cart */
   async createOrder(input) {
     const res = await this.client.request("POST", "/checkout", {