@behio/storefront-sdk 0.4.0 → 0.6.0

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;
@@ -89,13 +140,40 @@ interface ProductListItem {
     labels: ProductLabel[];
     isFeatured: boolean;
 }
+/** A single responsive derivative (size + format) of a media image. */
+interface ProductMediaVariant {
+    variant: 'thumb' | 'medium' | 'large' | 'xlarge';
+    format: 'jpeg' | 'webp' | 'avif';
+    url: string;
+    width: number;
+    height: number;
+}
+/**
+ * A product gallery entry (image or video), sourced from the inventory item
+ * so it is shared across every storefront listing the product. Images carry
+ * responsive `variants` (webp/avif/jpeg in three sizes) for fast LCP; pick
+ * the smallest format the client supports.
+ */
+interface ProductMedia {
+    id: string;
+    type: 'IMAGE' | 'VIDEO';
+    /** Original uploaded file URL. */
+    url: string;
+    alt?: string | null;
+    isCover: boolean;
+    order: number;
+    variants: ProductMediaVariant[];
+}
 interface ProductDetail extends ProductListItem {
     longDescription?: string;
+    /** @deprecated Legacy per-listing images. Prefer `media`. */
     images: Array<{
         url: string;
         alt?: string;
         order: number;
     }>;
+    /** Product gallery (images + videos) with responsive derivatives. */
+    media: ProductMedia[];
     categories: Array<{
         id: string;
         slug: string;
@@ -277,6 +355,20 @@ interface CheckoutInput {
     email: string;
     phone?: string;
     customerNote?: string;
+    /**
+     * Chosen shipping method. Required whenever the eshop has at least one
+     * enabled shipping method — the backend rejects the order without it.
+     * Prefer also sending `shippingQuoteId` from `shipping.quote()`; with only
+     * the method id the backend re-quotes the cart server-side.
+     */
+    shippingMethodId?: string;
+    /**
+     * Quote id from `shipping.quote()` — pins the exact server-computed price
+     * the customer saw. Expired quotes are re-quoted automatically; a consumed
+     * or foreign quote is rejected.
+     */
+    shippingQuoteId?: string;
+    paymentMethodId?: string;
 }
 type OrderStatus = (typeof OrderStatuses)[keyof typeof OrderStatuses];
 type PaymentStatus = (typeof PaymentStatuses)[keyof typeof PaymentStatuses];
@@ -321,6 +413,13 @@ interface OrderDetail extends OrderListItem {
     fulfillmentStatus: FulfillmentStatus;
     statusHistory: OrderStatusHistory[];
     trackingToken?: string;
+    /**
+     * For redirect payment gateways (GoPay, ...), the hosted URL the
+     * storefront must send the customer to in order to pay. Present only on
+     * the order returned by `checkout.createOrder()`. Null/absent for
+     * offline methods (bank transfer, COD) and zero-total orders.
+     */
+    paymentRedirectUrl?: string | null;
 }
 interface CustomerProfile {
     id: string;
@@ -454,10 +553,91 @@ 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;
+    /** "fixed" = price known upfront; "live_quote" = must call shipping.quote() with address. */
+    priceStrategy: "fixed" | "live_quote";
+    currency: string | null;
+    /** Final customer-facing price. Null for live_quote methods (call quote() to resolve). */
+    price: number | null;
+    /** Per-currency base price from the merchant's config. Null for live_quote. */
+    basePrice: number | null;
+    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;
+    /** Server-generated quote ID. Null for fixed-price methods. Pass to checkout for tamper-proof pricing. */
+    quoteId: string | null;
+    /** Quote expiry (epoch ms). Null for fixed-price methods. */
+    expiresAt: number | null;
+}
 interface CrossSellItem {
     productId: string;
     slug: string | null;
@@ -526,18 +706,75 @@ interface SubmitReviewInput {
     authorEmail?: string;
     imageUrls?: string[];
 }
+interface ReturnableOrderItem {
+    orderItemId: string;
+    productName: string;
+    /** Quantity ordered */
+    quantity: number;
+    /** Units still returnable (ordered minus active return claims) */
+    returnableQuantity: number;
+}
+/**
+ * Result of the guest order lookup used by the EU withdrawal form:
+ * the customer enters their order number + email and gets back the
+ * internal ids needed to submit a return. No account required.
+ */
+interface ReturnableOrder {
+    orderId: string;
+    orderNumber: string;
+    status: string;
+    items: ReturnableOrderItem[];
+    createdAt: number;
+}
+interface ReturnRequestItem {
+    id: string;
+    orderItemId: string;
+    productName: string;
+    quantity: number;
+    reason: string | null;
+    imageUrls: string[];
+}
+/** Returned by `returns.submit()` — the acknowledged withdrawal request. */
 interface ReturnRequest {
     id: string;
+    eshopId: string;
     orderId: string;
+    /** REQUESTED | APPROVED | SHIPPED_BACK | RECEIVED | REFUNDED | REJECTED | CLOSED */
+    status: string;
+    reason: string;
+    customerNote: string | null;
+    items: ReturnRequestItem[];
+    createdAt: number;
+}
+interface ReturnStatusItem {
+    id: string;
+    productName: string;
+    quantity: number;
+    reason: string | null;
+}
+/** Returned by `returns.getStatus()` — the full public view of a return. */
+interface ReturnStatus {
+    id: string;
+    orderNumber: string;
+    /** REQUESTED | APPROVED | SHIPPED_BACK | RECEIVED | REFUNDED | REJECTED | CLOSED */
     status: string;
     reason: string;
     customerNote: string | null;
-    refundAmount: number | null;
     refundMethod: string | null;
+    refundAmount: number | null;
+    refundedAt: number | null;
+    returnTrackingNumber: string | null;
+    items: ReturnStatusItem[];
     createdAt: number;
+    updatedAt: number;
 }
 interface SubmitReturnInput {
     orderId: string;
+    /**
+     * Email used on the order. Required — it is the ownership gate for guest
+     * withdrawals; the backend rejects submissions whose email doesn't match.
+     */
+    email: string;
     reason: string;
     customerNote?: string;
     items: {
@@ -617,6 +854,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). */
@@ -727,6 +965,12 @@ declare class CatalogModule {
     }>>;
     /** Check a gift card code — returns validity and remaining balance */
     checkGiftCard(code: string): Promise<SdkResult<GiftCardBalance>>;
+    /** List configured payment methods (filtered by currency). */
+    listPaymentMethods(opts?: {
+        currency?: string;
+    }): Promise<SdkResult<{
+        items: CheckoutPaymentMethod[];
+    }>>;
 }
 declare class AuthModule {
     private client;
@@ -767,8 +1011,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 */
@@ -861,8 +1125,14 @@ declare class ReviewsModule {
 declare class ReturnsModule {
     private client;
     constructor(client: BehioStorefront);
+    /**
+     * Guest order lookup for the EU withdrawal form: order number + the email
+     * used on the order resolve to the order id and per-item returnable
+     * quantities. POST so the email never appears in a URL.
+     */
+    lookupOrder(orderNumber: string, email: string): Promise<SdkResult<ReturnableOrder>>;
     submit(input: SubmitReturnInput): Promise<SdkResult<ReturnRequest>>;
-    getStatus(returnId: string, email: string): Promise<SdkResult<ReturnRequest>>;
+    getStatus(returnId: string, email: string): Promise<SdkResult<ReturnStatus>>;
 }
 declare class ConsentModule {
     private client;
@@ -910,5 +1180,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 ProductMedia, type ProductMediaVariant, 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 ReturnRequestItem, type ReturnStatus, type ReturnStatusItem, type ReturnableOrder, type ReturnableOrderItem, 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 };