@behio/storefront-sdk 0.4.0 → 0.5.0

package/README.md

@@ -84,6 +84,7 @@ function ProductList() {
 | `wishlist` | Add, remove, check |
 | `reviews` | Submit, list, vote helpful |
 | `addresses` | Address autocomplete with debounce hook |
+| `shipping` | List shipping methods and fetch live carrier quotes (Zaslat.cz + extensible) |
 | `returns` | Submit return requests |
 | `consent` | Cookie consent (GDPR) |
 | `quotes` | B2B quote requests |

package/dist/{chunk-L5KVNLTD.mjs → chunk-3GOQSB25.mjs}

@@ -142,6 +142,7 @@ var BehioStorefront = class {
     this.consent = new ConsentModule(this);
     this.quotes = new QuotesModule(this);
     this.addresses = new AddressModule(this);
+    this.shipping = new ShippingModule(this);
   }
   // --- Public methods ---
   /** Get basic shop info */
@@ -637,11 +638,33 @@ var CartModule = class {
     this.client.emit("cart:updated", res.data);
     return res;
   }
-  /** Add a bundle to the cart (price is locked at the bundle's current price) */
-  async addBundle(bundleId, quantity = 1) {
-    const res = await this.client.request("POST", "/cart/bundles", {
-      body: { bundleId, quantity }
-    });
+  /**
+   * Add a bundle to the cart. Price is snapshotted at the bundle's current
+   * price. Pass either the bundle id or its slug — slug is more ergonomic
+   * for static storefront wiring (`behio.cart.addBundle({slug: "morning-set"})`).
+   *
+   * Respects the bundle's `minQuantity`, `maxQuantity`, and `stockLimit`:
+   * the request rejects with HTTP 400 if the resulting cart line would
+   * violate any of them. The returned error includes the relevant field
+   * (`minQuantity`, `maxQuantity`, or `remaining`) so the storefront can
+   * surface a meaningful message.
+   *
+   * @param identifier Either `{id: bundleId}` or `{slug: bundleSlug}`. As a
+   *                   convenience, passing a plain string is treated as the
+   *                   bundle id for backwards compatibility.
+   * @param quantity   How many bundles to add (defaults to 1). Capped by
+   *                   the bundle's `maxQuantity` if set.
+   */
+  async addBundle(identifier, quantity = 1) {
+    const body = { quantity };
+    if (typeof identifier === "string") {
+      body.bundleId = identifier;
+    } else if ("id" in identifier) {
+      body.bundleId = identifier.id;
+    } else {
+      body.bundleSlug = identifier.slug;
+    }
+    const res = await this.client.request("POST", "/cart/bundles", { body });
     if (res.error) return res;
     this.client.emit("cart:updated", res.data);
     return res;
@@ -863,6 +886,49 @@ var AddressModule = class {
     });
   }
 };
+var ShippingModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Return the configured shipping methods that pass the current
+   * currency + country filter. Fixed-price methods come back with
+   * their `pricing[]` row resolved; live-quote methods come back with
+   * `price` 0 here — call `quote()` to get the real live price.
+   */
+  async listMethods(opts) {
+    const query = {};
+    if (opts?.currency) query.currency = opts.currency;
+    if (opts?.country) query.country = opts.country;
+    if (opts?.cartTotal != null) query.cartTotal = String(opts.cartTotal);
+    if (opts?.cartWeightKg != null) query.cartWeightKg = String(opts.cartWeightKg);
+    return this.client.request(
+      "GET",
+      "/catalog/shipping-methods",
+      { query }
+    );
+  }
+  /**
+   * Quote shipping for a destination address + cart contents. Each
+   * configured method is evaluated:
+   *   - `priceStrategy="fixed"` → resolved from the merchant's per-currency
+   *     `pricing[]` rows + free-shipping threshold check.
+   *   - `priceStrategy="live_quote"` → dispatched to the upstream
+   *     meta-provider (Zaslat, future Shippo / Sendcloud / …) and run
+   *     through the merchant's markup/rounding rules.
+   *
+   * Filter `available: true` for the checkout picker; `available: false`
+   * rows carry a `reason` (`"no_rate_returned"`, `"live_quote_not_implemented"`,
+   * …) you can log but should not display.
+   */
+  async quote(input) {
+    return this.client.request(
+      "POST",
+      "/catalog/shipping/quote",
+      { body: input }
+    );
+  }
+};
 
 export {
   ProductSort,

package/dist/{chunk-YLKO3SUR.js → chunk-KRGDHGTY.js}

@@ -142,6 +142,7 @@ var BehioStorefront = class {
     this.consent = new ConsentModule(this);
     this.quotes = new QuotesModule(this);
     this.addresses = new AddressModule(this);
+    this.shipping = new ShippingModule(this);
   }
   // --- Public methods ---
   /** Get basic shop info */
@@ -637,11 +638,33 @@ var CartModule = class {
     this.client.emit("cart:updated", res.data);
     return res;
   }
-  /** Add a bundle to the cart (price is locked at the bundle's current price) */
-  async addBundle(bundleId, quantity = 1) {
-    const res = await this.client.request("POST", "/cart/bundles", {
-      body: { bundleId, quantity }
-    });
+  /**
+   * Add a bundle to the cart. Price is snapshotted at the bundle's current
+   * price. Pass either the bundle id or its slug — slug is more ergonomic
+   * for static storefront wiring (`behio.cart.addBundle({slug: "morning-set"})`).
+   *
+   * Respects the bundle's `minQuantity`, `maxQuantity`, and `stockLimit`:
+   * the request rejects with HTTP 400 if the resulting cart line would
+   * violate any of them. The returned error includes the relevant field
+   * (`minQuantity`, `maxQuantity`, or `remaining`) so the storefront can
+   * surface a meaningful message.
+   *
+   * @param identifier Either `{id: bundleId}` or `{slug: bundleSlug}`. As a
+   *                   convenience, passing a plain string is treated as the
+   *                   bundle id for backwards compatibility.
+   * @param quantity   How many bundles to add (defaults to 1). Capped by
+   *                   the bundle's `maxQuantity` if set.
+   */
+  async addBundle(identifier, quantity = 1) {
+    const body = { quantity };
+    if (typeof identifier === "string") {
+      body.bundleId = identifier;
+    } else if ("id" in identifier) {
+      body.bundleId = identifier.id;
+    } else {
+      body.bundleSlug = identifier.slug;
+    }
+    const res = await this.client.request("POST", "/cart/bundles", { body });
     if (res.error) return res;
     this.client.emit("cart:updated", res.data);
     return res;
@@ -863,6 +886,49 @@ var AddressModule = class {
     });
   }
 };
+var ShippingModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Return the configured shipping methods that pass the current
+   * currency + country filter. Fixed-price methods come back with
+   * their `pricing[]` row resolved; live-quote methods come back with
+   * `price` 0 here — call `quote()` to get the real live price.
+   */
+  async listMethods(opts) {
+    const query = {};
+    if (_optionalChain([opts, 'optionalAccess', _25 => _25.currency])) query.currency = opts.currency;
+    if (_optionalChain([opts, 'optionalAccess', _26 => _26.country])) query.country = opts.country;
+    if (_optionalChain([opts, 'optionalAccess', _27 => _27.cartTotal]) != null) query.cartTotal = String(opts.cartTotal);
+    if (_optionalChain([opts, 'optionalAccess', _28 => _28.cartWeightKg]) != null) query.cartWeightKg = String(opts.cartWeightKg);
+    return this.client.request(
+      "GET",
+      "/catalog/shipping-methods",
+      { query }
+    );
+  }
+  /**
+   * Quote shipping for a destination address + cart contents. Each
+   * configured method is evaluated:
+   *   - `priceStrategy="fixed"` → resolved from the merchant's per-currency
+   *     `pricing[]` rows + free-shipping threshold check.
+   *   - `priceStrategy="live_quote"` → dispatched to the upstream
+   *     meta-provider (Zaslat, future Shippo / Sendcloud / …) and run
+   *     through the merchant's markup/rounding rules.
+   *
+   * Filter `available: true` for the checkout picker; `available: false`
+   * rows carry a `reason` (`"no_rate_returned"`, `"live_quote_not_implemented"`,
+   * …) you can log but should not display.
+   */
+  async quote(input) {
+    return this.client.request(
+      "POST",
+      "/catalog/shipping/quote",
+      { body: input }
+    );
+  }
+};
 
 
 

package/dist/index.d.mts

@@ -50,10 +50,50 @@ interface ShopSeo {
     ogDescription: string | null;
     ogImage: string | null;
 }
+/**
+ * Money amount displayed to a customer in a chosen currency.
+ *
+ * Two cases:
+ *  - **Fixed price** (preferred): merchant configured an explicit price for
+ *    this currency. `isApproximate` is `false`/absent and `fxSource` is `null`.
+ *  - **Approximate / FX-converted**: no fixed price for the requested
+ *    currency, so Behio converted from the eshop's default currency using
+ *    today's rate from `fxSource` (CNB or Frankfurter/ECB) plus the eshop's
+ *    safety margin. UI should show a `≈` hint and offer the base price too.
+ */
+/**
+ * Payment method available at checkout. Returned by
+ * `GET /storefront/v1/catalog/payment-methods` filtered for the customer's
+ * chosen currency. Credentials (API keys, merchant ids) stay server-side
+ * — only customer-safe fields appear here.
+ */
+interface CheckoutPaymentMethod {
+    id: string;
+    /** Merchant-chosen label, e.g. "Kartou (Stripe)" or "Převodem na účet". */
+    name: string;
+    description?: string | null;
+    /** Provider id: "stripe" | "gopay" | "comgate" | "bank_transfer" | "cod" | "custom". */
+    provider: string;
+    /** Currencies this method accepts. Empty = any. */
+    currencies: string[];
+    /** Optional fee added to the order total (e.g. COD surcharge). */
+    fee?: number | null;
+    feeCurrency?: string | null;
+    /** Customer-safe slice of config: bank account, IBAN, instructions, … */
+    publicConfig?: Record<string, unknown>;
+}
 interface ProductPrice {
     amount: number;
     currency: string;
     compareAtPrice?: number | null;
+    /** `true` when this amount was FX-converted from the eshop default currency. */
+    isApproximate?: boolean;
+    /** Provider id ("cnb" | "frankfurter" | "manual") when FX-converted. */
+    fxSource?: string | null;
+    /** Original amount in the eshop default currency before conversion. */
+    baseAmount?: number | null;
+    /** ISO code of the currency `baseAmount` is denominated in. */
+    baseCurrency?: string | null;
 }
 interface ProductVolumePrice {
     minQuantity: number;
@@ -68,6 +108,17 @@ interface ProductVariant {
     price: ProductPrice;
     inStock: boolean;
     stockQuantity?: number;
+    /**
+     * Cover image URL for the variant. Falls back to the parent product's
+     * cover when the variant has no photo of its own — see `imageIsInherited`.
+     */
+    imageUrl?: string | null;
+    /**
+     * `true` when `imageUrl` is borrowed from the parent product because the
+     * variant has no cover image of its own. Use this to render a hint like
+     * "default photo" or to render the picture in a subtler style.
+     */
+    imageIsInherited: boolean;
 }
 interface ProductLabel {
     id: string;
@@ -454,10 +505,85 @@ interface Bundle {
     coverImage: string | null;
     endsAt: number | null;
     itemsSum: number;
+    /** Absolute saving vs buying the components separately, in `currency`. */
     savings: number;
+    /** Percentage saving, 0–100. 0 when `itemsSum` is zero. */
     savingsPercent: number;
+    /** Minimum bundles per order. Default 1. */
+    minQuantity: number;
+    /** Maximum bundles per order. `null` = uncapped. */
+    maxQuantity: number | null;
+    /** Lifetime stock limit. `null` = uncapped. Once exceeded, add-to-cart fails. */
+    stockLimit: number | null;
+    /** Lifetime units sold (materialized counter). Used for "X sold" badges. */
+    soldCount: number;
     items: BundleItem[];
 }
+/**
+ * Shape returned by `behio.shipping.listMethods()` — the merchant's
+ * configured shipping methods filtered by cart currency + destination
+ * country. Use this for the "always-on" picker; for live quotes, prefer
+ * `behio.shipping.quote()` which can dispatch to the meta-provider
+ * (Zaslat, Shippo, …) for a live carrier rate per address.
+ */
+interface ShippingMethodSummary {
+    id: string;
+    name: string;
+    description: string | null;
+    /** Internal routing id ("zaslat", "ppl_direct", "manual", …). Not for display. */
+    provider: string;
+    currency: string | null;
+    /** Final customer-facing price. Equals `basePrice` unless free-shipping kicks in. */
+    price: number;
+    /** Per-currency base price from the merchant's config. */
+    basePrice: number;
+    isFreeShipping: boolean;
+    freeShippingThreshold: number | null;
+    /** "address" | "pickup_point" | "in_store" | "digital". */
+    deliveryType: string;
+    supportsPickupPoints: boolean;
+    etaDaysMin: number | null;
+    etaDaysMax: number | null;
+    allowedCountries: string[];
+    /** Customer-safe config fields the merchant filled in (pickup address, instructions). */
+    publicConfig: Record<string, unknown>;
+}
+/**
+ * Input for `behio.shipping.quote()`. At minimum requires the destination
+ * country — passing more (zip, weight per item, cart total) lets the
+ * meta-provider return better-fitting carriers and triggers free-shipping
+ * thresholds correctly.
+ */
+interface ShippingQuoteInput {
+    destinationAddress: {
+        country: string;
+        zip?: string;
+        city?: string;
+        street?: string;
+    };
+    items?: Array<{
+        whItemId: string;
+        quantity: number;
+        weightKg?: number;
+    }>;
+    cartTotal?: number;
+    currency?: string;
+}
+/**
+ * One option returned by `behio.shipping.quote()`. Methods configured for
+ * fixed pricing always come back with `available: true` and the merchant's
+ * configured price. Methods configured for live quoting come back available
+ * only when the upstream meta-provider returned a rate for the destination
+ * — otherwise `available: false` with a `reason` (e.g. `"no_rate_returned"`,
+ * `"live_quote_not_implemented"`). Filter `available: true` in your
+ * checkout picker.
+ */
+interface ShippingQuote extends ShippingMethodSummary {
+    /** `"fixed"` uses `pricing` rows; `"live_quote"` came from the upstream provider. */
+    strategy: "fixed" | "live_quote";
+    available: boolean;
+    reason: string | null;
+}
 interface CrossSellItem {
     productId: string;
     slug: string | null;
@@ -617,6 +743,7 @@ declare class BehioStorefront {
     readonly consent: ConsentModule;
     readonly quotes: QuotesModule;
     readonly addresses: AddressModule;
+    readonly shipping: ShippingModule;
     /** Get basic shop info */
     getShopInfo(): Promise<SdkResult<ShopInfo>>;
     /** Get SEO metadata for the shop homepage in the given locale (defaults to shop default). */
@@ -767,8 +894,28 @@ declare class CartModule {
     applyGiftCard(code: string): Promise<SdkResult<Cart>>;
     /** Remove a gift card from the cart */
     removeGiftCard(): Promise<SdkResult<Cart>>;
-    /** Add a bundle to the cart (price is locked at the bundle's current price) */
-    addBundle(bundleId: string, quantity?: number): Promise<SdkResult<Cart>>;
+    /**
+     * Add a bundle to the cart. Price is snapshotted at the bundle's current
+     * price. Pass either the bundle id or its slug — slug is more ergonomic
+     * for static storefront wiring (`behio.cart.addBundle({slug: "morning-set"})`).
+     *
+     * Respects the bundle's `minQuantity`, `maxQuantity`, and `stockLimit`:
+     * the request rejects with HTTP 400 if the resulting cart line would
+     * violate any of them. The returned error includes the relevant field
+     * (`minQuantity`, `maxQuantity`, or `remaining`) so the storefront can
+     * surface a meaningful message.
+     *
+     * @param identifier Either `{id: bundleId}` or `{slug: bundleSlug}`. As a
+     *                   convenience, passing a plain string is treated as the
+     *                   bundle id for backwards compatibility.
+     * @param quantity   How many bundles to add (defaults to 1). Capped by
+     *                   the bundle's `maxQuantity` if set.
+     */
+    addBundle(identifier: string | {
+        id: string;
+    } | {
+        slug: string;
+    }, quantity?: number): Promise<SdkResult<Cart>>;
     /** Update quantity of a bundle already in the cart */
     updateBundleQuantity(bundleId: string, quantity: number): Promise<SdkResult<Cart>>;
     /** Remove a bundle from the cart */
@@ -910,5 +1057,46 @@ declare class AddressModule {
     /** Get full structured address from a suggestion's placeId */
     getDetail(placeId: string): Promise<SdkResult<AddressDetail>>;
 }
+/**
+ * Storefront shipping module — list configured methods and fetch live
+ * quotes for a destination + cart. Use `listMethods` for the always-on
+ * picker (sidebar, info page) and `quote` once the customer enters a
+ * destination address so live-quote providers (Zaslat etc.) can return
+ * destination-specific prices.
+ */
+declare class ShippingModule {
+    private client;
+    constructor(client: BehioStorefront);
+    /**
+     * Return the configured shipping methods that pass the current
+     * currency + country filter. Fixed-price methods come back with
+     * their `pricing[]` row resolved; live-quote methods come back with
+     * `price` 0 here — call `quote()` to get the real live price.
+     */
+    listMethods(opts?: {
+        currency?: string;
+        country?: string;
+        cartTotal?: number;
+        cartWeightKg?: number;
+    }): Promise<SdkResult<{
+        items: ShippingMethodSummary[];
+    }>>;
+    /**
+     * Quote shipping for a destination address + cart contents. Each
+     * configured method is evaluated:
+     *   - `priceStrategy="fixed"` → resolved from the merchant's per-currency
+     *     `pricing[]` rows + free-shipping threshold check.
+     *   - `priceStrategy="live_quote"` → dispatched to the upstream
+     *     meta-provider (Zaslat, future Shippo / Sendcloud / …) and run
+     *     through the merchant's markup/rounding rules.
+     *
+     * Filter `available: true` for the checkout picker; `available: false`
+     * rows carry a `reason` (`"no_rate_returned"`, `"live_quote_not_implemented"`,
+     * …) you can log but should not display.
+     */
+    quote(input: ShippingQuoteInput): Promise<SdkResult<{
+        items: ShippingQuote[];
+    }>>;
+}
 
-export { type ActivePromotion, type AddToCartInput, type AddressDetail, type AddressSuggestion, type AddressType, AddressTypes, type AuthTokens, BehioApiError, type BehioErrorCode, type BehioEventHandler, type BehioEventType, BehioNetworkError, BehioStorefront, type BehioStorefrontConfig, type Bundle, type BundleItem, type Cart, type CartDiscount, type CartItem, type CartItemProduct, type Category, type CategoryDetail, type CheckoutAddress, type CheckoutInput, type CookieConsent, type CookieConsentInput, type CrossSellItem, type CustomerAddress, type CustomerProfile, type DataGroupFieldType, type FilterField, type FulfillmentStatus, FulfillmentStatuses, type GiftCardBalance, type LoginInput, type MessageResponse, type OrderDetail, type OrderItem, type OrderListItem, type OrderStatus, type OrderStatusHistory, OrderStatuses, type Page, type PageDetail, type PaginatedResponse, type PaymentStatus, PaymentStatuses, type ProductDetail, type ProductLabel, type ProductListItem, type ProductPrice, type ProductReview, type ProductReviewsResponse, ProductSort, type ProductSortValue, type ProductVariant, type ProductVolumePrice, type ProductsQuery, type QuoteRequest, type RegisterInput, type RequestInterceptor, type RequestInterceptorConfig, type ResponseInterceptor, type ResponseInterceptorData, type ReturnRequest, type SdkError, type SdkResult, type ShopInfo, type ShopSeo, type SubmitQuoteInput, type SubmitReturnInput, type SubmitReviewInput, type WishlistItem, err, ok, toSdkError };
+export { type ActivePromotion, type AddToCartInput, type AddressDetail, type AddressSuggestion, type AddressType, AddressTypes, type AuthTokens, BehioApiError, type BehioErrorCode, type BehioEventHandler, type BehioEventType, BehioNetworkError, BehioStorefront, type BehioStorefrontConfig, type Bundle, type BundleItem, type Cart, type CartDiscount, type CartItem, type CartItemProduct, type Category, type CategoryDetail, type CheckoutAddress, type CheckoutInput, type CheckoutPaymentMethod, type CookieConsent, type CookieConsentInput, type CrossSellItem, type CustomerAddress, type CustomerProfile, type DataGroupFieldType, type FilterField, type FulfillmentStatus, FulfillmentStatuses, type GiftCardBalance, type LoginInput, type MessageResponse, type OrderDetail, type OrderItem, type OrderListItem, type OrderStatus, type OrderStatusHistory, OrderStatuses, type Page, type PageDetail, type PaginatedResponse, type PaymentStatus, PaymentStatuses, type ProductDetail, type ProductLabel, type ProductListItem, type ProductPrice, type ProductReview, type ProductReviewsResponse, ProductSort, type ProductSortValue, type ProductVariant, type ProductVolumePrice, type ProductsQuery, type QuoteRequest, type RegisterInput, type RequestInterceptor, type RequestInterceptorConfig, type ResponseInterceptor, type ResponseInterceptorData, type ReturnRequest, type SdkError, type SdkResult, type ShippingMethodSummary, type ShippingQuote, type ShippingQuoteInput, type ShopInfo, type ShopSeo, type SubmitQuoteInput, type SubmitReturnInput, type SubmitReviewInput, type WishlistItem, err, ok, toSdkError };

package/dist/index.d.ts

@@ -50,10 +50,50 @@ interface ShopSeo {
     ogDescription: string | null;
     ogImage: string | null;
 }
+/**
+ * Money amount displayed to a customer in a chosen currency.
+ *
+ * Two cases:
+ *  - **Fixed price** (preferred): merchant configured an explicit price for
+ *    this currency. `isApproximate` is `false`/absent and `fxSource` is `null`.
+ *  - **Approximate / FX-converted**: no fixed price for the requested
+ *    currency, so Behio converted from the eshop's default currency using
+ *    today's rate from `fxSource` (CNB or Frankfurter/ECB) plus the eshop's
+ *    safety margin. UI should show a `≈` hint and offer the base price too.
+ */
+/**
+ * Payment method available at checkout. Returned by
+ * `GET /storefront/v1/catalog/payment-methods` filtered for the customer's
+ * chosen currency. Credentials (API keys, merchant ids) stay server-side
+ * — only customer-safe fields appear here.
+ */
+interface CheckoutPaymentMethod {
+    id: string;
+    /** Merchant-chosen label, e.g. "Kartou (Stripe)" or "Převodem na účet". */
+    name: string;
+    description?: string | null;
+    /** Provider id: "stripe" | "gopay" | "comgate" | "bank_transfer" | "cod" | "custom". */
+    provider: string;
+    /** Currencies this method accepts. Empty = any. */
+    currencies: string[];
+    /** Optional fee added to the order total (e.g. COD surcharge). */
+    fee?: number | null;
+    feeCurrency?: string | null;
+    /** Customer-safe slice of config: bank account, IBAN, instructions, … */
+    publicConfig?: Record<string, unknown>;
+}
 interface ProductPrice {
     amount: number;
     currency: string;
     compareAtPrice?: number | null;
+    /** `true` when this amount was FX-converted from the eshop default currency. */
+    isApproximate?: boolean;
+    /** Provider id ("cnb" | "frankfurter" | "manual") when FX-converted. */
+    fxSource?: string | null;
+    /** Original amount in the eshop default currency before conversion. */
+    baseAmount?: number | null;
+    /** ISO code of the currency `baseAmount` is denominated in. */
+    baseCurrency?: string | null;
 }
 interface ProductVolumePrice {
     minQuantity: number;
@@ -68,6 +108,17 @@ interface ProductVariant {
     price: ProductPrice;
     inStock: boolean;
     stockQuantity?: number;
+    /**
+     * Cover image URL for the variant. Falls back to the parent product's
+     * cover when the variant has no photo of its own — see `imageIsInherited`.
+     */
+    imageUrl?: string | null;
+    /**
+     * `true` when `imageUrl` is borrowed from the parent product because the
+     * variant has no cover image of its own. Use this to render a hint like
+     * "default photo" or to render the picture in a subtler style.
+     */
+    imageIsInherited: boolean;
 }
 interface ProductLabel {
     id: string;
@@ -454,10 +505,85 @@ interface Bundle {
     coverImage: string | null;
     endsAt: number | null;
     itemsSum: number;
+    /** Absolute saving vs buying the components separately, in `currency`. */
     savings: number;
+    /** Percentage saving, 0–100. 0 when `itemsSum` is zero. */
     savingsPercent: number;
+    /** Minimum bundles per order. Default 1. */
+    minQuantity: number;
+    /** Maximum bundles per order. `null` = uncapped. */
+    maxQuantity: number | null;
+    /** Lifetime stock limit. `null` = uncapped. Once exceeded, add-to-cart fails. */
+    stockLimit: number | null;
+    /** Lifetime units sold (materialized counter). Used for "X sold" badges. */
+    soldCount: number;
     items: BundleItem[];
 }
+/**
+ * Shape returned by `behio.shipping.listMethods()` — the merchant's
+ * configured shipping methods filtered by cart currency + destination
+ * country. Use this for the "always-on" picker; for live quotes, prefer
+ * `behio.shipping.quote()` which can dispatch to the meta-provider
+ * (Zaslat, Shippo, …) for a live carrier rate per address.
+ */
+interface ShippingMethodSummary {
+    id: string;
+    name: string;
+    description: string | null;
+    /** Internal routing id ("zaslat", "ppl_direct", "manual", …). Not for display. */
+    provider: string;
+    currency: string | null;
+    /** Final customer-facing price. Equals `basePrice` unless free-shipping kicks in. */
+    price: number;
+    /** Per-currency base price from the merchant's config. */
+    basePrice: number;
+    isFreeShipping: boolean;
+    freeShippingThreshold: number | null;
+    /** "address" | "pickup_point" | "in_store" | "digital". */
+    deliveryType: string;
+    supportsPickupPoints: boolean;
+    etaDaysMin: number | null;
+    etaDaysMax: number | null;
+    allowedCountries: string[];
+    /** Customer-safe config fields the merchant filled in (pickup address, instructions). */
+    publicConfig: Record<string, unknown>;
+}
+/**
+ * Input for `behio.shipping.quote()`. At minimum requires the destination
+ * country — passing more (zip, weight per item, cart total) lets the
+ * meta-provider return better-fitting carriers and triggers free-shipping
+ * thresholds correctly.
+ */
+interface ShippingQuoteInput {
+    destinationAddress: {
+        country: string;
+        zip?: string;
+        city?: string;
+        street?: string;
+    };
+    items?: Array<{
+        whItemId: string;
+        quantity: number;
+        weightKg?: number;
+    }>;
+    cartTotal?: number;
+    currency?: string;
+}
+/**
+ * One option returned by `behio.shipping.quote()`. Methods configured for
+ * fixed pricing always come back with `available: true` and the merchant's
+ * configured price. Methods configured for live quoting come back available
+ * only when the upstream meta-provider returned a rate for the destination
+ * — otherwise `available: false` with a `reason` (e.g. `"no_rate_returned"`,
+ * `"live_quote_not_implemented"`). Filter `available: true` in your
+ * checkout picker.
+ */
+interface ShippingQuote extends ShippingMethodSummary {
+    /** `"fixed"` uses `pricing` rows; `"live_quote"` came from the upstream provider. */
+    strategy: "fixed" | "live_quote";
+    available: boolean;
+    reason: string | null;
+}
 interface CrossSellItem {
     productId: string;
     slug: string | null;
@@ -617,6 +743,7 @@ declare class BehioStorefront {
     readonly consent: ConsentModule;
     readonly quotes: QuotesModule;
     readonly addresses: AddressModule;
+    readonly shipping: ShippingModule;
     /** Get basic shop info */
     getShopInfo(): Promise<SdkResult<ShopInfo>>;
     /** Get SEO metadata for the shop homepage in the given locale (defaults to shop default). */
@@ -767,8 +894,28 @@ declare class CartModule {
     applyGiftCard(code: string): Promise<SdkResult<Cart>>;
     /** Remove a gift card from the cart */
     removeGiftCard(): Promise<SdkResult<Cart>>;
-    /** Add a bundle to the cart (price is locked at the bundle's current price) */
-    addBundle(bundleId: string, quantity?: number): Promise<SdkResult<Cart>>;
+    /**
+     * Add a bundle to the cart. Price is snapshotted at the bundle's current
+     * price. Pass either the bundle id or its slug — slug is more ergonomic
+     * for static storefront wiring (`behio.cart.addBundle({slug: "morning-set"})`).
+     *
+     * Respects the bundle's `minQuantity`, `maxQuantity`, and `stockLimit`:
+     * the request rejects with HTTP 400 if the resulting cart line would
+     * violate any of them. The returned error includes the relevant field
+     * (`minQuantity`, `maxQuantity`, or `remaining`) so the storefront can
+     * surface a meaningful message.
+     *
+     * @param identifier Either `{id: bundleId}` or `{slug: bundleSlug}`. As a
+     *                   convenience, passing a plain string is treated as the
+     *                   bundle id for backwards compatibility.
+     * @param quantity   How many bundles to add (defaults to 1). Capped by
+     *                   the bundle's `maxQuantity` if set.
+     */
+    addBundle(identifier: string | {
+        id: string;
+    } | {
+        slug: string;
+    }, quantity?: number): Promise<SdkResult<Cart>>;
     /** Update quantity of a bundle already in the cart */
     updateBundleQuantity(bundleId: string, quantity: number): Promise<SdkResult<Cart>>;
     /** Remove a bundle from the cart */
@@ -910,5 +1057,46 @@ declare class AddressModule {
     /** Get full structured address from a suggestion's placeId */
     getDetail(placeId: string): Promise<SdkResult<AddressDetail>>;
 }
+/**
+ * Storefront shipping module — list configured methods and fetch live
+ * quotes for a destination + cart. Use `listMethods` for the always-on
+ * picker (sidebar, info page) and `quote` once the customer enters a
+ * destination address so live-quote providers (Zaslat etc.) can return
+ * destination-specific prices.
+ */
+declare class ShippingModule {
+    private client;
+    constructor(client: BehioStorefront);
+    /**
+     * Return the configured shipping methods that pass the current
+     * currency + country filter. Fixed-price methods come back with
+     * their `pricing[]` row resolved; live-quote methods come back with
+     * `price` 0 here — call `quote()` to get the real live price.
+     */
+    listMethods(opts?: {
+        currency?: string;
+        country?: string;
+        cartTotal?: number;
+        cartWeightKg?: number;
+    }): Promise<SdkResult<{
+        items: ShippingMethodSummary[];
+    }>>;
+    /**
+     * Quote shipping for a destination address + cart contents. Each
+     * configured method is evaluated:
+     *   - `priceStrategy="fixed"` → resolved from the merchant's per-currency
+     *     `pricing[]` rows + free-shipping threshold check.
+     *   - `priceStrategy="live_quote"` → dispatched to the upstream
+     *     meta-provider (Zaslat, future Shippo / Sendcloud / …) and run
+     *     through the merchant's markup/rounding rules.
+     *
+     * Filter `available: true` for the checkout picker; `available: false`
+     * rows carry a `reason` (`"no_rate_returned"`, `"live_quote_not_implemented"`,
+     * …) you can log but should not display.
+     */
+    quote(input: ShippingQuoteInput): Promise<SdkResult<{
+        items: ShippingQuote[];
+    }>>;
+}
 
-export { type ActivePromotion, type AddToCartInput, type AddressDetail, type AddressSuggestion, type AddressType, AddressTypes, type AuthTokens, BehioApiError, type BehioErrorCode, type BehioEventHandler, type BehioEventType, BehioNetworkError, BehioStorefront, type BehioStorefrontConfig, type Bundle, type BundleItem, type Cart, type CartDiscount, type CartItem, type CartItemProduct, type Category, type CategoryDetail, type CheckoutAddress, type CheckoutInput, type CookieConsent, type CookieConsentInput, type CrossSellItem, type CustomerAddress, type CustomerProfile, type DataGroupFieldType, type FilterField, type FulfillmentStatus, FulfillmentStatuses, type GiftCardBalance, type LoginInput, type MessageResponse, type OrderDetail, type OrderItem, type OrderListItem, type OrderStatus, type OrderStatusHistory, OrderStatuses, type Page, type PageDetail, type PaginatedResponse, type PaymentStatus, PaymentStatuses, type ProductDetail, type ProductLabel, type ProductListItem, type ProductPrice, type ProductReview, type ProductReviewsResponse, ProductSort, type ProductSortValue, type ProductVariant, type ProductVolumePrice, type ProductsQuery, type QuoteRequest, type RegisterInput, type RequestInterceptor, type RequestInterceptorConfig, type ResponseInterceptor, type ResponseInterceptorData, type ReturnRequest, type SdkError, type SdkResult, type ShopInfo, type ShopSeo, type SubmitQuoteInput, type SubmitReturnInput, type SubmitReviewInput, type WishlistItem, err, ok, toSdkError };
+export { type ActivePromotion, type AddToCartInput, type AddressDetail, type AddressSuggestion, type AddressType, AddressTypes, type AuthTokens, BehioApiError, type BehioErrorCode, type BehioEventHandler, type BehioEventType, BehioNetworkError, BehioStorefront, type BehioStorefrontConfig, type Bundle, type BundleItem, type Cart, type CartDiscount, type CartItem, type CartItemProduct, type Category, type CategoryDetail, type CheckoutAddress, type CheckoutInput, type CheckoutPaymentMethod, type CookieConsent, type CookieConsentInput, type CrossSellItem, type CustomerAddress, type CustomerProfile, type DataGroupFieldType, type FilterField, type FulfillmentStatus, FulfillmentStatuses, type GiftCardBalance, type LoginInput, type MessageResponse, type OrderDetail, type OrderItem, type OrderListItem, type OrderStatus, type OrderStatusHistory, OrderStatuses, type Page, type PageDetail, type PaginatedResponse, type PaymentStatus, PaymentStatuses, type ProductDetail, type ProductLabel, type ProductListItem, type ProductPrice, type ProductReview, type ProductReviewsResponse, ProductSort, type ProductSortValue, type ProductVariant, type ProductVolumePrice, type ProductsQuery, type QuoteRequest, type RegisterInput, type RequestInterceptor, type RequestInterceptorConfig, type ResponseInterceptor, type ResponseInterceptorData, type ReturnRequest, type SdkError, type SdkResult, type ShippingMethodSummary, type ShippingQuote, type ShippingQuoteInput, type ShopInfo, type ShopSeo, type SubmitQuoteInput, type SubmitReturnInput, type SubmitReviewInput, type WishlistItem, err, ok, toSdkError };

package/dist/index.js

@@ -10,7 +10,7 @@
 
 
 
-var _chunkYLKO3SURjs = require('./chunk-YLKO3SUR.js');
+var _chunkKRGDHGTYjs = require('./chunk-KRGDHGTY.js');
 
 
 
@@ -23,4 +23,4 @@ var _chunkYLKO3SURjs = require('./chunk-YLKO3SUR.js');
 
 
 
-exports.AddressTypes = _chunkYLKO3SURjs.AddressTypes; exports.BehioApiError = _chunkYLKO3SURjs.BehioApiError; exports.BehioNetworkError = _chunkYLKO3SURjs.BehioNetworkError; exports.BehioStorefront = _chunkYLKO3SURjs.BehioStorefront; exports.FulfillmentStatuses = _chunkYLKO3SURjs.FulfillmentStatuses; exports.OrderStatuses = _chunkYLKO3SURjs.OrderStatuses; exports.PaymentStatuses = _chunkYLKO3SURjs.PaymentStatuses; exports.ProductSort = _chunkYLKO3SURjs.ProductSort; exports.err = _chunkYLKO3SURjs.err; exports.ok = _chunkYLKO3SURjs.ok; exports.toSdkError = _chunkYLKO3SURjs.toSdkError;
+exports.AddressTypes = _chunkKRGDHGTYjs.AddressTypes; exports.BehioApiError = _chunkKRGDHGTYjs.BehioApiError; exports.BehioNetworkError = _chunkKRGDHGTYjs.BehioNetworkError; exports.BehioStorefront = _chunkKRGDHGTYjs.BehioStorefront; exports.FulfillmentStatuses = _chunkKRGDHGTYjs.FulfillmentStatuses; exports.OrderStatuses = _chunkKRGDHGTYjs.OrderStatuses; exports.PaymentStatuses = _chunkKRGDHGTYjs.PaymentStatuses; exports.ProductSort = _chunkKRGDHGTYjs.ProductSort; exports.err = _chunkKRGDHGTYjs.err; exports.ok = _chunkKRGDHGTYjs.ok; exports.toSdkError = _chunkKRGDHGTYjs.toSdkError;

package/dist/index.mjs

@@ -10,7 +10,7 @@ import {
   err,
   ok,
   toSdkError
-} from "./chunk-L5KVNLTD.mjs";
+} from "./chunk-3GOQSB25.mjs";
 export {
   AddressTypes,
   BehioApiError,

package/dist/react.js

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
-var _chunkYLKO3SURjs = require('./chunk-YLKO3SUR.js');
+var _chunkKRGDHGTYjs = require('./chunk-KRGDHGTY.js');
 
 // src/react/provider.tsx
 var _react = require('react');
@@ -114,7 +114,7 @@ function BehioProvider({
   const storageAdapter = _react.useMemo.call(void 0, () => resolveStorage(storageOption), [storageOption]);
   const clientRef = _react.useRef.call(void 0, null);
   if (!clientRef.current) {
-    clientRef.current = new (0, _chunkYLKO3SURjs.BehioStorefront)({
+    clientRef.current = new (0, _chunkKRGDHGTYjs.BehioStorefront)({
       apiKey,
       baseUrl,
       locale,

package/dist/react.mjs

@@ -1,6 +1,6 @@
 import {
   BehioStorefront
-} from "./chunk-L5KVNLTD.mjs";
+} from "./chunk-3GOQSB25.mjs";
 
 // src/react/provider.tsx
 import { useRef, useEffect, useMemo } from "react";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@behio/storefront-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "TypeScript SDK for Behio Headless E-Shop — core client + React hooks",
   "author": "Behio",
   "license": "MIT",