@behio/storefront-sdk 0.1.9 → 0.1.10

package/README.md

@@ -806,10 +806,10 @@ platforms treat bundles as paid add-ons or plugins — here it's native.
 
 - **Homepage / landing pages** — list active bundles as hero cards with cover
   image + `-25%` badge. Drives impulse purchase.
-- **Category pages** — show a relevant bundle ("vše na grilování") next to
-  individual products in the same category.
-- **Cart / checkout** — suggest a bundle as upsell ("Přidejte ještě tohle a
-  dostanete celý set s 20% slevou").
+- **Category pages** — show a relevant bundle ("Everything for grilling") next
+  to individual products in the same category.
+- **Cart / checkout** — suggest a bundle as upsell ("Add these two more items
+  and get the whole set with a 20% discount").
 - **Dedicated `/bundles` page** — marketing landing for all active sets.
 
 **What's in the data:**
@@ -845,7 +845,7 @@ function BundlesGrid() {
               </>
             )}
           </div>
-          <p>{bundle.items.length} produktů ušetříte {bundle.savings} {bundle.currency}</p>
+          <p>{bundle.items.length} products · save {bundle.savings} {bundle.currency}</p>
         </a>
       ))}
     </section>
@@ -877,7 +877,7 @@ function BundleDetail({ slug }: { slug: string }) {
             {item.quantity}× {item.name}
             {item.defaultPrice && (
               <span className="text-muted">
-                ({item.defaultPrice} {bundle.currency} /ks běžně)
+                ({item.defaultPrice} {bundle.currency} /pc regular price)
               </span>
             )}
           </li>
@@ -888,12 +888,12 @@ function BundleDetail({ slug }: { slug: string }) {
         <strong>{bundle.bundlePrice} {bundle.currency}</strong>
         {bundle.savings > 0 && (
           <p>
-            Jednotlivě by stálo <s>{bundle.itemsSum} {bundle.currency}</s> —
-            ušetříte <strong>{bundle.savings} {bundle.currency}</strong>
+            Individually it would cost <s>{bundle.itemsSum} {bundle.currency}</s> —
+            you save <strong>{bundle.savings} {bundle.currency}</strong>
             ({bundle.savingsPercent}%)
           </p>
         )}
-        <button onClick={addToCart}>Přidat celý balíček do košíku</button>
+        <button onClick={addToCart}>Add the whole bundle to cart</button>
       </div>
     </article>
   );
@@ -901,10 +901,10 @@ function BundleDetail({ slug }: { slug: string }) {
 ```
 
 **Behind the scenes at checkout.** When the customer buys a bundle, Behio
-rozpadá balíček do order-itemů s proporčně rozpočítanou cenou podle
-defaultních cen komponent (zachováno pro účetnictví a skladové odpisy), ale
-total na faktuře odpovídá `bundlePrice` — zákazník vidí jednu celistvou
-položku, sklady se odepisují správně z komponent.
+splits it into individual order items with prices distributed proportionally
+based on each component's default price (this is kept so accounting and
+stock decrements work correctly). The invoice total matches `bundlePrice` —
+the customer sees one line item, inventory is decremented component-by-component.
 
 ---
 
@@ -913,45 +913,46 @@ položku, sklady se odepisují správně z komponent.
 **What it is.** Three related lists of product recommendations shown on a
 product detail page:
 
-- **Related (Podobné)** — alternativy ke stejnému účelu (jiné vodítko, jiné
-  krmivo). Když tě tenhle produkt zaujal, tady jsou jiné stejné kategorie.
-- **Upsell (Lepší varianta)** — dražší / vybavenější verze. „Vidíš levný
-  obojek? Tady je verze s koženým prošitím za 2×." Cílem je zvýšit
-  average order value.
-- **Cross-sell (Často kupováno s)** — komplementární produkty. K obojku
-  vodítko, k misce čistič. Čistý AOV boost na PDP a v košíku.
+- **Related** — alternatives for the same need (another leash, another dog
+  food). "If this one caught your eye, here are similar options in the same
+  category."
+- **Upsell** — a better / more premium version. "Looking at the basic collar?
+  Here's the leather-stitched premium version for 2× the price." Goal: raise
+  average order value by steering to a better margin.
+- **Cross-sell** — complementary products. Leash for the collar, cleaner for
+  the bowl. Pure AOV boost on PDP and in cart.
 
-**Why to split them.** Každý z těchto typů má jinou UX roli a měla by být
-různě formulována. Když se to smíchá, ztratí se kontext — zákazník nepozná,
-proč mu to zobrazuješ.
+**Why split them.** Each type has a different UX role and should be phrased
+differently. Mixed together they lose context — the customer can't tell why
+they're being shown.
 
 **Where to use it.**
 
-- **Product detail page** — tři samostatné sekce pod popisem (nebo v sidebar
-  sloupci). Nejvyšší konverzní dopad je **Cross-sell "často kupováno s"**
-  přímo u tlačítka "Přidat do košíku".
-- **Cart sidebar** — mini-cross-sell widget ("Nezapomeňte ještě na tohle").
-- **Post-purchase page** — "Chcete ještě tohle?" pro druhou objednávku.
+- **Product detail page** — three separate sections below the description
+  (or in a sidebar column). Highest conversion impact is **Cross-sell
+  "Frequently bought together"** right next to the "Add to cart" button.
+- **Cart sidebar** — mini cross-sell widget ("Don't forget these too").
+- **Post-purchase page** — "Want to add these?" for a follow-up order.
 
-**Pozor.** Endpoint vrací **jen aktivní produkty ve stejném eshopu**. Když
-jsi v adminu nějaký linknul a pak ho deaktivoval/smazal, zmizí ze seznamu
-automaticky — nemusíš to řešit na FE.
+**Note.** The endpoint returns **only active products from the same eshop**.
+If you linked a product in admin and later disabled or deleted it, it drops
+from the list automatically — no need to handle that on the frontend.
 
 ```tsx
 import { useCrossSell, useBehio } from '@behio/storefront-sdk/react';
 
 function CrossSellSection({ title, items }: { title: string; items: CrossSellItem[] }) {
-  if (!items?.length) return null; // nezobrazuj prázdnou sekci
+  if (!items?.length) return null; // hide empty section
   return (
     <section>
       <h2>{title}</h2>
       <div className="carousel">
         {items.map((item) => (
-          <a key={item.productId} href={`/produkt/${item.slug}`} className="card">
+          <a key={item.productId} href={`/product/${item.slug}`} className="card">
             {item.imageUrl && <img src={item.imageUrl} alt={item.name} />}
             <h4>{item.name}</h4>
-            <span>{item.price} Kč</span>
-            {item.stockCached === 0 && <span className="text-red">Vyprodáno</span>}
+            <span>{item.price}</span>
+            {item.stockCached === 0 && <span className="text-red">Sold out</span>}
           </a>
         ))}
       </div>
@@ -967,15 +968,15 @@ function ProductDetail({ slug }: { slug: string }) {
       {/* ... product info ... */}
 
       <CrossSellSection
-        title="Často kupováno s"
+        title="Frequently bought together"
         items={crossSell?.crossSell ?? []}
       />
       <CrossSellSection
-        title="Možná vás zaujme i"
+        title="You might also like"
         items={crossSell?.related ?? []}
       />
       <CrossSellSection
-        title="Chcete raději lepší variantu?"
+        title="Want a premium version?"
         items={crossSell?.upsell ?? []}
       />
     </>
@@ -983,7 +984,8 @@ function ProductDetail({ slug }: { slug: string }) {
 }
 ```
 
-**Tip — merge do jedné sekce.** Pokud máš málo content a chceš to zjednodušit:
+**Tip — merge into a single section.** If you have sparse data and want
+to keep it simple, combine all three into one list:
 
 ```tsx
 const allRecommendations = [
@@ -997,58 +999,61 @@ const allRecommendations = [
 
 ### useProductPromotions
 
-**What it is.** Vrací aktuálně platné akce (`Eshop_Promotion`) týkající se
-konkrétního produktu — tedy všechny promotions, kde `startsAt <= teď < endsAt`
-a produkt spadá do scope akce (může to být `ALL_PRODUCTS`, `SPECIFIC_PRODUCTS`,
-`CATEGORIES` nebo `LABELS`, backend to vyřeší za tebe).
+**What it is.** Returns the currently-active promotions (`Eshop_Promotion`)
+applicable to a given product — i.e. all promotions where
+`startsAt <= now < endsAt` and the product matches the promotion scope
+(`ALL_PRODUCTS`, `SPECIFIC_PRODUCTS`, `CATEGORIES`, or `LABELS`; the backend
+resolves it for you).
 
-**Co to není.** Není to výpočet *konečné ceny po slevě* — na to je samostatná
-vrstva (cart evaluator). Tenhle hook je čistě pro **zobrazovací vrstvu**: badge,
-countdown, upozornění „akční cena do půlnoci".
+**What it is NOT.** It's not a computation of the *final discounted price* —
+that's a separate layer (the cart evaluator). This hook is purely for the
+**display layer**: badges, countdowns, "sale price until midnight" banners.
 
-**Proč je to oddělené.** Konverzně nejsilnější marketingový prvek v eshopu je
-**urgency + scarcity**. „Do konce akce: 2h 14m 37s" přímo na PDP zvyšuje
-conversion rate měřitelně — je to letitá best practice (Amazon Lightning
-Deals, Booking "rezervováno 3× za posledních 24h", atd.). Hook ti dodá data,
-ty uděláš countdown komponentu.
+**Why it's separate.** The most conversion-effective marketing element in
+e-commerce is **urgency + scarcity**. "Sale ends in 2h 14m 37s" right on the
+PDP measurably lifts conversion — it's a well-established best practice
+(Amazon Lightning Deals, Booking.com "3 people booked in the last 24h",
+etc.). The hook delivers the data; you build the countdown component.
 
-**Kde to použít.**
+**Where to use it.**
 
-- **Product card v listu** — badge `-20%` nebo vlajka „AKCE".
-- **Product detail** — velký banner s countdown nad cenou: „Koupíte-li do
-  půlnoci, ušetříte 200 Kč."
-- **Cart** — varování „Vaše sleva vyprší za 5 minut" aby tlačilo k
-  dokončení objednávky.
+- **Product card in a list** — a `-20%` badge or a "SALE" flag.
+- **Product detail** — a large banner with countdown above the price: "Buy
+  before midnight to save $20."
+- **Cart** — a warning like "Your discount expires in 5 minutes" to nudge
+  checkout completion.
 
-**Pole z API:**
+**Fields returned:**
 
-- `id`, `name`, `slug` — identifikace akce
+- `id`, `name`, `slug` — promotion identity
 - `type` — `FLASH_SALE` / `SEASONAL` / `CLEARANCE` / `BOGO` / `BUNDLE` / `LOYALTY`
 - `discountType` — `PERCENTAGE` / `FIXED_AMOUNT` / `FREE_SHIPPING` / `BUY_X_GET_Y`
-- `discountValue` — hodnota (u PERCENTAGE je to %, u FIXED_AMOUNT Kč, …)
-- `endsAt` — timestamp konce. Pokud `null`, akce je na neurčito.
-- `badgeText`, `badgeColor` — merchant ručně nastavil text a barvu badge
-  (např. „-30%" s červenou); pokud oboje `null`, vymysli default podle `discountType`.
-- `showCountdown` — **respect this!** Když merchant nechce countdown, nerender
-  ho. Ne všechny akce (CLEARANCE, LOYALTY) mají smysl odpočítávat.
-- `couponRequired` — akce se uplatní jen po zadání kódu na checkoutu.
-  Na PDP ukaž info box („Použijte kód LETO pro uplatnění"), neukazuj jako
-  automatickou slevu.
+- `discountValue` — the value (% for PERCENTAGE, currency amount for FIXED_AMOUNT, …)
+- `endsAt` — end timestamp. If `null`, the promotion runs indefinitely.
+- `badgeText`, `badgeColor` — merchant-set badge text and color (e.g. "-30%"
+  in red). If both are `null`, fall back to a default derived from `discountType`.
+- `showCountdown` — **respect this!** If the merchant opted out of showing
+  a countdown, don't render one. Not all promotions (CLEARANCE, LOYALTY)
+  make sense to count down.
+- `couponRequired` — the promotion applies only after the customer enters a
+  code at checkout. On the PDP show an info box ("Use code SUMMER at
+  checkout"); don't present it as an automatic discount.
 
 ```tsx
 import { useProductPromotions } from '@behio/storefront-sdk/react';
 import { useEffect, useState } from 'react';
 
 function ProductPromotionBanner({ slug }: { slug: string }) {
-  // Refetch každé 4 minuty aby se promotion aktualizovala když mezitím
-  // skončila jedna a začala další. Pro pouhý countdown nemusíš refetchovat —
-  // countdown děláš lokálně z endsAt.
+  // Refetch every 4 minutes so the promotion list updates when one ends
+  // and another begins. The countdown itself doesn't need a refetch —
+  // it ticks locally off `endsAt`.
   const { data } = useProductPromotions(slug, { refetchIntervalMs: 4 * 60_000 });
   const promotions = data?.items ?? [];
 
   if (!promotions.length) return null;
 
-  // Nejvyšší priority akce (BE už vrací seřazené priority DESC + createdAt ASC)
+  // Highest-priority promotion (the BE already sorts by priority DESC,
+  // then createdAt ASC).
   const promo = promotions[0];
 
   const badge = promo.badgeText ?? formatDefaultBadge(promo);
@@ -1060,7 +1065,7 @@ function ProductPromotionBanner({ slug }: { slug: string }) {
         <span className="badge" style={{ backgroundColor: badgeColor }}>{badge}</span>
         <strong>{promo.name}</strong>
         {promo.couponRequired && (
-          <p>Uplatníte zadáním kódu <code>{promo.name}</code> v košíku</p>
+          <p>Use code <code>{promo.name}</code> at checkout to redeem</p>
         )}
       </div>
       {promo.showCountdown && promo.endsAt && <Countdown endsAt={promo.endsAt} />}
@@ -1076,30 +1081,31 @@ function Countdown({ endsAt }: { endsAt: number }) {
   }, []);
 
   const ms = Math.max(0, endsAt - now);
-  if (ms === 0) return <span>Akce skončila</span>;
+  if (ms === 0) return <span>Sale ended</span>;
 
   const d = Math.floor(ms / 86400_000);
   const h = Math.floor((ms % 86400_000) / 3600_000);
   const m = Math.floor((ms % 3600_000) / 60_000);
   const s = Math.floor((ms % 60_000) / 1000);
 
-  if (d > 0) return <span>Končí za {d}d {h}h {m}m</span>;
-  return <span>Končí za {h}h {m}m {s}s</span>;
+  if (d > 0) return <span>Ends in {d}d {h}h {m}m</span>;
+  return <span>Ends in {h}h {m}m {s}s</span>;
 }
 
 function formatDefaultBadge(p: { discountType: string; discountValue: number }) {
   switch (p.discountType) {
     case 'PERCENTAGE': return `-${p.discountValue}%`;
-    case 'FIXED_AMOUNT': return `-${p.discountValue} Kč`;
-    case 'FREE_SHIPPING': return 'Doprava zdarma';
-    case 'BUY_X_GET_Y': return `${p.discountValue}+1 ZDARMA`;
-    default: return 'AKCE';
+    case 'FIXED_AMOUNT': return `-${p.discountValue}`;
+    case 'FREE_SHIPPING': return 'Free shipping';
+    case 'BUY_X_GET_Y': return `${p.discountValue}+1 FREE`;
+    default: return 'SALE';
   }
 }
 ```
 
-**Pattern — product card badge.** Když chceš jen malou vlaječku na kartě
-produktu v listu (bez countdown), zavolej hook per-card a vezmi první promo:
+**Pattern — product card badge.** If you only need a small flag on a
+product card in a list (no countdown), call the hook per card and pick the
+first promo:
 
 ```tsx
 function ProductCardBadge({ slug }: { slug: string }) {
@@ -1114,9 +1120,9 @@ function ProductCardBadge({ slug }: { slug: string }) {
 }
 ```
 
-Pozor — v listovém kontextu to dělá N dotazů (jeden per karta). Pokud máš
-200 produktů, radši vytvoř vlastní bulk endpoint nebo invaliduj méně často
-přes React Query `staleTime`.
+Heads-up — in list contexts this fires N requests (one per card). For
+a 200-product page, either add a bulk endpoint of your own or keep the
+requests cheap with a long React Query `staleTime`.
 
 ## All API methods
 

package/package.json

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