@behio/storefront-sdk 1.9.0 → 1.18.0

package/README.md

@@ -2,11 +2,11 @@
 
 **Headless e-commerce SDK for building custom storefronts.**
 
-Behio gives you a complete e-commerce backend — products, inventory, orders, customers, discounts, multi-currency, multi-language — and lets you design the storefront however you want. No themes, no templates, no vendor lock-in.
+Behio gives you a complete e-commerce backend (products, inventory, orders, customers, discounts, multi-currency, multi-language) and lets you design the storefront however you want. Merchants run on it worldwide, with local tax rules, carriers and payment gateways handled natively. No themes, no templates, no vendor lock-in.
 
 ## Why Behio?
 
-- **You own the frontend.** Next.js, React, Vue, Nuxt, Astro, or plain JS — the backend doesn't care.
+- **You own the frontend.** Next.js, React, Vue, Nuxt, Astro, or plain JS, the backend doesn't care.
 - **Production-ready in minutes.** Catalog, cart, checkout, customer accounts, orders, CMS, discount codes, gift cards, loyalty programs, and more.
 - **Built for developers.** Full TypeScript types, auto-completing, modern React hooks with TanStack Query.
 - **Scale-ready.** Redis caching, rate limiting, webhooks, atomic checkout (no double-spend, no overselling).
@@ -60,7 +60,7 @@ function ProductList() {
 
   return data.items.map(p => (
     <div key={p.id}>
-      <h3>{p.name} — {p.price} {p.currency}</h3>
+      <h3>{p.name}, {p.price} {p.currency}</h3>
       <button onClick={() => addToCart.mutateAsync({ productId: p.id, quantity: 1 })}>
         Add to Cart
       </button>
@@ -89,18 +89,20 @@ function ProductList() {
 | `consent` | Cookie consent (GDPR) |
 | `quotes` | B2B quote requests |
 | `pages` | CMS pages |
+| `blog` | Blogs and published posts (web + e-shop) |
+| `forms` | Merchant-defined forms: definition + validated submit with per-field errors (web + e-shop) |
 
 ### 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`
+`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`
 
 ### Framework Support
 
-- **Next.js** — Server components + client hooks, SSR ready
-- **React + Vite** — Standard SPA setup
-- **Nuxt 3** — Composables with SSR
-- **Vue + Vite** — Provide/inject pattern
-- **Vanilla JS** — Works in any runtime (Node.js, Deno, Bun, Cloudflare Workers)
+- **Next.js**: Server components + client hooks, SSR ready
+- **React + Vite**: Standard SPA setup
+- **Nuxt 3**: Composables with SSR
+- **Vue + Vite**: Provide/inject pattern
+- **Vanilla JS**: Works in any runtime (Node.js, Deno, Bun, Cloudflare Workers)
 
 ### Built-in Features
 

package/dist/{chunk-CY6D2YEI.js → chunk-GAYYRRUL.js}

@@ -33,6 +33,38 @@ var AddressTypes = {
   SHIPPING: "SHIPPING",
   BILLING: "BILLING"
 };
+var BE_CODE_TO_ERROR = {
+  "be.storefront.cartIsEmpty": "CART_EMPTY",
+  "be.storefront.productNotFound": "PRODUCT_NOT_FOUND",
+  "be.storefront.productNotAvailable": "PRODUCT_NOT_FOUND",
+  "be.storefront.invalidEmailOrPassword": "INVALID_CREDENTIALS",
+  "be.storefront.currentPasswordIncorrect": "INVALID_CREDENTIALS",
+  "be.storefront.discountExpired": "DISCOUNT_EXPIRED",
+  "be.storefront.discountExpiredOrLimit": "DISCOUNT_EXPIRED",
+  "be.storefront.invalidDiscountCode": "INVALID_DISCOUNT",
+  "be.storefront.discountInvalid": "INVALID_DISCOUNT",
+  "be.storefront.discountInactive": "INVALID_DISCOUNT",
+  "be.storefront.discountWrongCurrency": "INVALID_DISCOUNT",
+  "be.storefront.discountNotApplicable": "INVALID_DISCOUNT",
+  "be.storefront.discountNotYetValid": "INVALID_DISCOUNT",
+  "be.storefront.discountUsageLimitReached": "INVALID_DISCOUNT",
+  "be.storefront.discountLimitedToGroups": "INVALID_DISCOUNT",
+  "be.storefront.tokenInvalid": "TOKEN_INVALID",
+  "be.storefront.orderAccessTokenInvalid": "TOKEN_INVALID",
+  "be.storefront.resetTokenInvalid": "TOKEN_INVALID",
+  "be.storefront.invalidVerificationToken": "TOKEN_INVALID",
+  "be.storefront.invalidRefreshToken": "TOKEN_INVALID",
+  "be.storefront.refreshTokenExpired": "TOKEN_EXPIRED",
+  "be.storefront.apiKeyExpired": "TOKEN_EXPIRED",
+  "be.storefront.customerEmailTaken": "EMAIL_ALREADY_EXISTS",
+  "be.storefront.orderNotCancellable": "ORDER_NOT_CANCELLABLE",
+  "be.storefront.orderCancelledNotReturnable": "ORDER_NOT_CANCELLABLE",
+  "be.validation.failed": "VALIDATION_ERROR",
+  "be.forms.formNotFound": "NOT_FOUND",
+  "be.forms.validationFailed": "VALIDATION_ERROR",
+  "be.forms.consentRequired": "VALIDATION_ERROR",
+  "be.forms.tooLarge": "VALIDATION_ERROR"
+};
 var BehioApiError = class _BehioApiError extends Error {
   constructor(status, body, message) {
     super(message || `API Error ${status}`);
@@ -49,7 +81,12 @@ var BehioApiError = class _BehioApiError extends Error {
     if (status === 409) return "EMAIL_ALREADY_EXISTS";
     if (status === 429) return "RATE_LIMITED";
     if (status >= 500) return "INTERNAL_ERROR";
-    const msg = (_optionalChain([body, 'optionalAccess', _ => _.message]) || "").toLowerCase();
+    const rawCode = _optionalChain([body, 'optionalAccess', _ => _.code]);
+    if (typeof rawCode === "string") {
+      const mapped = BE_CODE_TO_ERROR[rawCode];
+      if (mapped) return mapped;
+    }
+    const msg = (_optionalChain([body, 'optionalAccess', _2 => _2.message]) || "").toLowerCase();
     if (msg.includes("invalid") && msg.includes("password"))
       return "INVALID_CREDENTIALS";
     if (msg.includes("invalid") && msg.includes("email"))
@@ -157,6 +194,8 @@ var BehioStorefront = class {
     this.orders = new OrdersModule(this);
     this.customer = new CustomerModule(this);
     this.pages = new PagesModule(this);
+    this.blog = new BlogModule(this);
+    this.forms = new FormsModule(this);
     this.wishlist = new WishlistModule(this);
     this.reviews = new ReviewsModule(this);
     this.returns = new ReturnsModule(this);
@@ -317,12 +356,12 @@ var BehioStorefront = class {
     if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
     this.listeners.get(event).add(handler);
     return () => {
-      _optionalChain([this, 'access', _2 => _2.listeners, 'access', _3 => _3.get, 'call', _4 => _4(event), 'optionalAccess', _5 => _5.delete, 'call', _6 => _6(handler)]);
+      _optionalChain([this, 'access', _3 => _3.listeners, 'access', _4 => _4.get, 'call', _5 => _5(event), 'optionalAccess', _6 => _6.delete, 'call', _7 => _7(handler)]);
     };
   }
   /** @internal Emit an event (fire-and-forget, handler errors are swallowed) */
   emit(event, data) {
-    _optionalChain([this, 'access', _7 => _7.listeners, 'access', _8 => _8.get, 'call', _9 => _9(event), 'optionalAccess', _10 => _10.forEach, 'call', _11 => _11((fn) => {
+    _optionalChain([this, 'access', _8 => _8.listeners, 'access', _9 => _9.get, 'call', _10 => _10(event), 'optionalAccess', _11 => _11.forEach, 'call', _12 => _12((fn) => {
       try {
         fn(data);
       } catch (e2) {
@@ -438,7 +477,7 @@ var BehioStorefront = class {
    */
   async rawRequest(method, path, options) {
     const params = new URLSearchParams();
-    if (_optionalChain([options, 'optionalAccess', _12 => _12.query])) {
+    if (_optionalChain([options, 'optionalAccess', _13 => _13.query])) {
       for (const [key, value] of Object.entries(options.query)) {
         if (value === void 0 || value === null || value === "") continue;
         if (Array.isArray(value)) {
@@ -467,7 +506,7 @@ var BehioStorefront = class {
     if (this.shopDomain) {
       headers["X-Shop-Domain"] = this.shopDomain;
     }
-    if (this.accessToken && _optionalChain([options, 'optionalAccess', _13 => _13.auth]) !== false) {
+    if (this.accessToken && _optionalChain([options, 'optionalAccess', _14 => _14.auth]) !== false) {
       headers["Authorization"] = `Bearer ${this.accessToken}`;
     }
     if (this.cartSession) {
@@ -483,10 +522,10 @@ var BehioStorefront = class {
       } catch (e4) {
       }
     }
-    if (_optionalChain([options, 'optionalAccess', _14 => _14.headers])) {
+    if (_optionalChain([options, 'optionalAccess', _15 => _15.headers])) {
       Object.assign(headers, options.headers);
     }
-    const bodyStr = _optionalChain([options, 'optionalAccess', _15 => _15.body]) ? JSON.stringify(options.body) : void 0;
+    const bodyStr = _optionalChain([options, 'optionalAccess', _16 => _16.body]) ? JSON.stringify(options.body) : void 0;
     let interceptedConfig = {
       url,
       method,
@@ -500,7 +539,7 @@ var BehioStorefront = class {
     for (let attempt = 0; attempt <= this.retries; attempt++) {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-      if (_optionalChain([options, 'optionalAccess', _16 => _16.signal])) {
+      if (_optionalChain([options, 'optionalAccess', _17 => _17.signal])) {
         if (options.signal.aborted) {
           clearTimeout(timeoutId);
           throw new BehioNetworkError("Request aborted", false);
@@ -551,9 +590,9 @@ var BehioStorefront = class {
         const apiError = new BehioApiError(
           res.status,
           body,
-          _optionalChain([body, 'optionalAccess', _17 => _17.message]) || `API Error ${res.status}`
+          _optionalChain([body, 'optionalAccess', _18 => _18.message]) || `API Error ${res.status}`
         );
-        if (res.status === 401 && this.refreshToken && _optionalChain([options, 'optionalAccess', _18 => _18.auth]) !== false && !_optionalChain([options, 'optionalAccess', _19 => _19._isRetryAfterRefresh])) {
+        if (res.status === 401 && this.refreshToken && _optionalChain([options, 'optionalAccess', _19 => _19.auth]) !== false && !_optionalChain([options, 'optionalAccess', _20 => _20._isRetryAfterRefresh])) {
           try {
             await this.handleTokenRefresh();
             return this.rawRequest(method, path, {
@@ -605,6 +644,7 @@ var CatalogModule = class {
       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;
@@ -637,7 +677,7 @@ var CatalogModule = class {
       "GET",
       `/catalog/products/${slug}`,
       {
-        query: { locale: _optionalChain([options, 'optionalAccess', _20 => _20.locale]), currency: _optionalChain([options, 'optionalAccess', _21 => _21.currency]) }
+        query: { locale: _optionalChain([options, 'optionalAccess', _21 => _21.locale]), currency: _optionalChain([options, 'optionalAccess', _22 => _22.currency]), country: _optionalChain([options, 'optionalAccess', _23 => _23.country]) }
       }
     );
   }
@@ -691,7 +731,7 @@ var CatalogModule = class {
       "GET",
       `/catalog/menu/${encodeURIComponent(handle)}`,
       {
-        query: { locale: _optionalChain([options, 'optionalAccess', _22 => _22.locale]) }
+        query: { locale: _optionalChain([options, 'optionalAccess', _24 => _24.locale]) }
       }
     );
   }
@@ -707,7 +747,7 @@ var CatalogModule = class {
       "GET",
       "/catalog/featured",
       {
-        query: { locale: _optionalChain([options, 'optionalAccess', _23 => _23.locale]), currency: _optionalChain([options, 'optionalAccess', _24 => _24.currency]) }
+        query: { locale: _optionalChain([options, 'optionalAccess', _25 => _25.locale]), currency: _optionalChain([options, 'optionalAccess', _26 => _26.currency]) }
       }
     );
   }
@@ -722,7 +762,7 @@ var CatalogModule = class {
     return this.client.request(
       "GET",
       "/catalog/filters",
-      { query: { locale: _optionalChain([options, 'optionalAccess', _25 => _25.locale]) } }
+      { query: { locale: _optionalChain([options, 'optionalAccess', _27 => _27.locale]) } }
     );
   }
   /**
@@ -737,7 +777,7 @@ var CatalogModule = class {
     return this.client.request(
       "GET",
       `/catalog/products/${slug}/parameters`,
-      { query: { locale: _optionalChain([options, 'optionalAccess', _26 => _26.locale]) } }
+      { query: { locale: _optionalChain([options, 'optionalAccess', _28 => _28.locale]) } }
     );
   }
   /**
@@ -749,7 +789,7 @@ var CatalogModule = class {
     return this.client.request(
       "GET",
       `/catalog/products/${slug}/parameters/${groupSlug}`,
-      { query: { locale: _optionalChain([options, 'optionalAccess', _27 => _27.locale]) } }
+      { query: { locale: _optionalChain([options, 'optionalAccess', _29 => _29.locale]) } }
     );
   }
   /**
@@ -807,7 +847,7 @@ var CatalogModule = class {
       "GET",
       `/catalog/product-groups/${encodeURIComponent(slug)}`,
       {
-        query: { locale: _optionalChain([options, 'optionalAccess', _28 => _28.locale]), currency: _optionalChain([options, 'optionalAccess', _29 => _29.currency]) }
+        query: { locale: _optionalChain([options, 'optionalAccess', _30 => _30.locale]), currency: _optionalChain([options, 'optionalAccess', _31 => _31.currency]) }
       }
     );
   }
@@ -822,7 +862,7 @@ var CatalogModule = class {
     return this.client.request(
       "GET",
       `/catalog/products/${encodeURIComponent(productSlug)}/cross-sell`,
-      { query: { locale: _optionalChain([options, 'optionalAccess', _30 => _30.locale]), currency: _optionalChain([options, 'optionalAccess', _31 => _31.currency]) } }
+      { query: { locale: _optionalChain([options, 'optionalAccess', _32 => _32.locale]), currency: _optionalChain([options, 'optionalAccess', _33 => _33.currency]) } }
     );
   }
   /** Active promotions applicable to a product (with countdown end time) */
@@ -859,16 +899,27 @@ var CatalogModule = class {
       { body: input }
     );
   }
-  /** List configured payment methods (filtered by currency). */
+  /**
+   * List configured payment methods (filtered by currency). `locale` picks the
+   * language of `instruments[].label` / `swifts[].label` (SDK 1.14.0); pass the
+   * locale of the page so the instrument tiles read in the shopper's language.
+   */
   async listPaymentMethods(opts) {
     const query = {};
-    if (_optionalChain([opts, 'optionalAccess', _32 => _32.currency])) query.currency = opts.currency;
+    if (_optionalChain([opts, 'optionalAccess', _34 => _34.currency])) query.currency = opts.currency;
+    if (_optionalChain([opts, 'optionalAccess', _35 => _35.locale])) query.locale = opts.locale;
+    if (_optionalChain([opts, 'optionalAccess', _36 => _36.country])) query.country = opts.country;
+    if (_optionalChain([opts, 'optionalAccess', _37 => _37.shippingMethodId])) query.shippingMethodId = opts.shippingMethodId;
     return this.client.request(
       "GET",
       "/catalog/payment-methods",
       { query }
     );
   }
+  /** Alias of `listPaymentMethods` (SDK 1.14.0). */
+  paymentMethods(opts) {
+    return this.listPaymentMethods(opts);
+  }
 };
 var AuthModule = class {
   constructor(client) {
@@ -1022,6 +1073,26 @@ var CartModule = class {
     this.client.emit("cart:updated", res.data);
     return res;
   }
+  /**
+   * Tell the cart where the order will ship (and, for B2B, the buyer's VAT
+   * ID) so the VAT breakdown matches the checkout before the address form:
+   * destination-country rate (OSS), 0 % export outside the EU, or reverse
+   * charge for an EU business with a VIES-valid VAT ID. `cart.vatMode` says
+   * which rule applied. SDK 1.17.0.
+   *
+   * ```ts
+   * await client.cart.setDestination({ country: "SK" });
+   * await client.cart.setDestination({ vatId: "SK2020000001" }); // "" clears
+   * ```
+   */
+  async setDestination(input) {
+    const res = await this.client.request("PUT", "/cart/destination", {
+      body: input
+    });
+    if (res.error) return res;
+    this.client.emit("cart:updated", res.data);
+    return res;
+  }
   /** Update item quantity */
   async updateQuantity(itemId, quantity) {
     const res = await this.client.request(
@@ -1173,13 +1244,37 @@ var OrdersModule = class {
   constructor(client) {
     this.client = client;
   }
+  /**
+   * Ask the backend to re-check this order's payment with the gateway.
+   *
+   * Call it on the thank-you page the customer lands on after paying, BEFORE
+   * you read the order. Some gateways (Tatrapay+) have no server-to-server
+   * notification at all, so the customer's return is the only fast way the
+   * payment gets confirmed; for the others it is a safety net for a lost
+   * notification.
+   *
+   * The response is deliberately opaque (`{ok: true}` every time, even for an
+   * order number that does not exist): order numbers are sequential, so
+   * anything else would turn this into a probe for other people's orders.
+   * Read the actual state afterwards through a path that proves entitlement
+   * ({@link get}, {@link track} or the guest access-code flow).
+   *
+   * Never throws for a missing order and never blocks the page: treat a
+   * failure as "not confirmed yet", the backend poller catches up on its own.
+   */
+  async syncPaymentOnReturn(orderNumber) {
+    return this.client.request(
+      "POST",
+      `/payments/return/${orderNumber}`
+    );
+  }
   /** List customer orders (requires auth) */
   async list(options) {
     return this.client.request(
       "GET",
       "/orders",
       {
-        query: { page: _optionalChain([options, 'optionalAccess', _33 => _33.page]), limit: _optionalChain([options, 'optionalAccess', _34 => _34.limit]) }
+        query: { page: _optionalChain([options, 'optionalAccess', _38 => _38.page]), limit: _optionalChain([options, 'optionalAccess', _39 => _39.limit]) }
       }
     );
   }
@@ -1299,7 +1394,10 @@ var CustomerModule = class {
       body: address
     });
   }
-  /** Update address */
+  /**
+   * Update address. Partial: `{isDefault: true}` alone is a valid body. A
+   * changed `vatId` or `country` re-runs the VIES check on the server.
+   */
   async updateAddress(addressId, data) {
     return this.client.request(
       "PATCH",
@@ -1525,6 +1623,59 @@ var PagesModule = class {
     });
   }
 };
+var BlogModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List the site's blogs (active only). */
+  async list(locale) {
+    return this.client.request("GET", "/blogs", {
+      query: { locale }
+    });
+  }
+  /** Published posts of one blog, newest first (featured first), paginated. */
+  async posts(handle, query = {}) {
+    return this.client.request("GET", `/blogs/${handle}/posts`, {
+      query: {
+        locale: query.locale,
+        page: query.page,
+        limit: query.limit,
+        tag: query.tag
+      }
+    });
+  }
+  /** One published post with sanitised HTML content and related posts. */
+  async post(handle, slug, locale) {
+    return this.client.request("GET", `/blogs/${handle}/posts/${slug}`, {
+      query: { locale }
+    });
+  }
+};
+var FormsModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Public definition of one form (fields + settings). 404 for an unknown or inactive slug. */
+  async get(slug) {
+    return this.client.request(
+      "GET",
+      `/forms/${encodeURIComponent(slug)}`
+    );
+  }
+  /**
+   * Submit a response. On `be.forms.validationFailed` the returned error
+   * carries per-field codes: read them with `formFieldErrors(error)`. Other
+   * rejections: `be.forms.consentRequired`, `be.forms.tooLarge`,
+   * `be.forms.formNotFound`; rate limit 10 submits per minute per visitor.
+   */
+  async submit(slug, input) {
+    return this.client.request(
+      "POST",
+      `/forms/${encodeURIComponent(slug)}/submit`,
+      { body: input, auth: false }
+    );
+  }
+};
 var WishlistModule = class {
   constructor(client) {
     this.client = client;
@@ -1674,7 +1825,7 @@ var ConsentModule = class {
     }
     if (result.error) return { data: null, error: result.error };
     return {
-      data: _optionalChain([result, 'access', _35 => _35.data, 'optionalAccess', _36 => _36.consented]) ? result.data.consent : null,
+      data: _optionalChain([result, 'access', _40 => _40.data, 'optionalAccess', _41 => _41.consented]) ? result.data.consent : null,
       error: null
     };
   }
@@ -1761,10 +1912,10 @@ var ShippingModule = class {
    */
   async listMethods(opts) {
     const query = {};
-    if (_optionalChain([opts, 'optionalAccess', _37 => _37.currency])) query.currency = opts.currency;
-    if (_optionalChain([opts, 'optionalAccess', _38 => _38.country])) query.country = opts.country;
-    if (_optionalChain([opts, 'optionalAccess', _39 => _39.cartTotal]) != null) query.cartTotal = String(opts.cartTotal);
-    if (_optionalChain([opts, 'optionalAccess', _40 => _40.cartWeightKg]) != null)
+    if (_optionalChain([opts, 'optionalAccess', _42 => _42.currency])) query.currency = opts.currency;
+    if (_optionalChain([opts, 'optionalAccess', _43 => _43.country])) query.country = opts.country;
+    if (_optionalChain([opts, 'optionalAccess', _44 => _44.cartTotal]) != null) query.cartTotal = String(opts.cartTotal);
+    if (_optionalChain([opts, 'optionalAccess', _45 => _45.cartWeightKg]) != null)
       query.cartWeightKg = String(opts.cartWeightKg);
     return this.client.request(
       "GET",