@behio/storefront-sdk 0.1.8 → 0.1.9

package/README.md

@@ -788,49 +788,336 @@ const { data: pages } = usePages('cs');
 const { data: page } = usePage('about-us', 'cs');
 ```
 
-### useBundles
-```typescript
-import { useBundles, useBundle } from '@behio/storefront-sdk/react';
+### useBundles / useBundle
+
+**What it is.** A "bundle" is a merchant-curated set of products sold together
+at a single fixed price that's (usually) lower than buying the components
+individually — think *starter kit*, *holiday gift set*, *3-for-2 deals*, or
+*"breakfast combo"*. The merchant defines what goes in (which products, what
+quantities, what cover image) and sets one total price for the whole thing.
+
+**Why it matters.** Bundles are one of the highest-ROI features in e-commerce:
+they raise average order value without having to discount individual products,
+they give customers a clear "good deal" signal (the savings badge), and they
+let you clear slow-moving inventory by pairing it with fast-movers. Most eshop
+platforms treat bundles as paid add-ons or plugins — here it's native.
+
+**Where you use it.**
+
+- **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").
+- **Dedicated `/bundles` page** — marketing landing for all active sets.
+
+**What's in the data:**
+
+- `bundlePrice` — what the customer pays for the whole set
+- `itemsSum` — what the components would cost individually (sum of default prices)
+- `savings` — `itemsSum - bundlePrice` (absolute savings in the currency)
+- `savingsPercent` — pre-computed percent so you don't have to do the math in JSX
+- `items[]` — the components with their quantities (for display and stock check)
+- `endsAt` — optional expiry timestamp; if set, the bundle auto-deactivates
+
+```tsx
+import { useBundles, useBundle, useCart, useBehio } from '@behio/storefront-sdk/react';
 
-// List
-const { data } = useBundles();
-data?.items.forEach((b) => console.log(b.name, b.savingsPercent, '%'));
+// ---- Homepage hero: all active bundles ----
+function BundlesGrid() {
+  const { data, isLoading } = useBundles();
+  if (isLoading) return <Skeleton />;
+  if (!data?.items.length) return null; // no active bundles → hide section
+
+  return (
+    <section className="grid grid-cols-3 gap-4">
+      {data.items.map((bundle) => (
+        <a key={bundle.id} href={`/bundle/${bundle.slug}`} className="relative">
+          {bundle.coverImage && <img src={bundle.coverImage} alt={bundle.name} />}
+          <h3>{bundle.name}</h3>
+          <div>
+            <strong>{bundle.bundlePrice} {bundle.currency}</strong>
+            {bundle.savings > 0 && (
+              <>
+                <s>{bundle.itemsSum} {bundle.currency}</s>
+                <span className="badge">-{bundle.savingsPercent}%</span>
+              </>
+            )}
+          </div>
+          <p>{bundle.items.length} produktů ušetříte {bundle.savings} {bundle.currency}</p>
+        </a>
+      ))}
+    </section>
+  );
+}
 
-// Detail
-const { data: bundle } = useBundle('startovaci-balicek');
-// bundle: { name, bundlePrice, itemsSum, savings, items: [{ productId, quantity, ... }] }
+// ---- Bundle detail page with "Add to cart" ----
+function BundleDetail({ slug }: { slug: string }) {
+  const { data: bundle, isLoading } = useBundle(slug);
+  const { client } = useBehio();
+  const { refresh } = useCart();
 
-// Add to cart — uses existing useCart hook
-const { cart, refresh } = useCart();
-await shop.cart.addBundle(bundle.id, 1);
-await refresh();
+  if (isLoading) return <Skeleton />;
+  if (!bundle) return <NotFound />;
+
+  async function addToCart() {
+    await client.cart.addBundle(bundle.id, 1);
+    await refresh(); // cart badge updates everywhere
+  }
+
+  return (
+    <article>
+      <h1>{bundle.name}</h1>
+      <p>{bundle.description}</p>
+
+      <ul>
+        {bundle.items.map((item) => (
+          <li key={item.productId}>
+            {item.quantity}× {item.name}
+            {item.defaultPrice && (
+              <span className="text-muted">
+                ({item.defaultPrice} {bundle.currency} /ks běžně)
+              </span>
+            )}
+          </li>
+        ))}
+      </ul>
+
+      <div className="price-box">
+        <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>
+            ({bundle.savingsPercent}%)
+          </p>
+        )}
+        <button onClick={addToCart}>Přidat celý balíček do košíku</button>
+      </div>
+    </article>
+  );
+}
 ```
 
+**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.
+
+---
+
 ### useCrossSell
-```typescript
-import { useCrossSell } from '@behio/storefront-sdk/react';
 
-const { data } = useCrossSell(product.slug);
-// data: { related: CrossSellItem[], upsell: CrossSellItem[], crossSell: CrossSellItem[] }
+**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.
+
+**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š.
+
+**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.
+
+**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.
+
+```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
+  return (
+    <section>
+      <h2>{title}</h2>
+      <div className="carousel">
+        {items.map((item) => (
+          <a key={item.productId} href={`/produkt/${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>}
+          </a>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function ProductDetail({ slug }: { slug: string }) {
+  const { data: crossSell } = useCrossSell(slug);
+
+  return (
+    <>
+      {/* ... product info ... */}
+
+      <CrossSellSection
+        title="Často kupováno s"
+        items={crossSell?.crossSell ?? []}
+      />
+      <CrossSellSection
+        title="Možná vás zaujme i"
+        items={crossSell?.related ?? []}
+      />
+      <CrossSellSection
+        title="Chcete raději lepší variantu?"
+        items={crossSell?.upsell ?? []}
+      />
+    </>
+  );
+}
+```
+
+**Tip — merge do jedné sekce.** Pokud máš málo content a chceš to zjednodušit:
 
-// Render sections on product detail page
-<CrossSellSection title="Často kupováno s" items={data?.crossSell} />
-<CrossSellSection title="Podobné produkty" items={data?.related} />
+```tsx
+const allRecommendations = [
+  ...(crossSell?.crossSell ?? []),
+  ...(crossSell?.related ?? []),
+  ...(crossSell?.upsell ?? []),
+].slice(0, 6);
 ```
 
+---
+
 ### useProductPromotions
-```typescript
+
+**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).
+
+**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".
+
+**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.
+
+**Kde to použít.**
+
+- **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.
+
+**Pole z API:**
+
+- `id`, `name`, `slug` — identifikace akce
+- `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.
+
+```tsx
 import { useProductPromotions } from '@behio/storefront-sdk/react';
+import { useEffect, useState } from 'react';
 
-// Auto-refetch every 5 seconds so the countdown stays accurate on long-lived pages
-const { data } = useProductPromotions(product.slug, { refetchIntervalMs: 5000 });
+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.
+  const { data } = useProductPromotions(slug, { refetchIntervalMs: 4 * 60_000 });
+  const promotions = data?.items ?? [];
 
-data?.items.forEach((promo) => {
-  // promo: { name, discountType, discountValue, endsAt, badgeText, badgeColor, ... }
-  // Use endsAt to render a live countdown: new Date(promo.endsAt) - Date.now()
-});
+  if (!promotions.length) return null;
+
+  // Nejvyšší priority akce (BE už vrací seřazené priority DESC + createdAt ASC)
+  const promo = promotions[0];
+
+  const badge = promo.badgeText ?? formatDefaultBadge(promo);
+  const badgeColor = promo.badgeColor ?? '#ef4444';
+
+  return (
+    <div className="promo-banner" style={{ backgroundColor: badgeColor + '20', borderColor: badgeColor }}>
+      <div>
+        <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>
+        )}
+      </div>
+      {promo.showCountdown && promo.endsAt && <Countdown endsAt={promo.endsAt} />}
+    </div>
+  );
+}
+
+function Countdown({ endsAt }: { endsAt: number }) {
+  const [now, setNow] = useState(Date.now());
+  useEffect(() => {
+    const id = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(id);
+  }, []);
+
+  const ms = Math.max(0, endsAt - now);
+  if (ms === 0) return <span>Akce skončila</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>;
+}
+
+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';
+  }
+}
 ```
 
+**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:
+
+```tsx
+function ProductCardBadge({ slug }: { slug: string }) {
+  const { data } = useProductPromotions(slug);
+  const promo = data?.items[0];
+  if (!promo) return null;
+  return (
+    <span className="badge" style={{ background: promo.badgeColor ?? '#ef4444' }}>
+      {promo.badgeText ?? formatDefaultBadge(promo)}
+    </span>
+  );
+}
+```
+
+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`.
+
 ## All API methods
 
 ### Catalog

package/package.json

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