@behio/storefront-sdk 0.1.8 → 0.1.10

package/README.md

@@ -788,49 +788,342 @@ 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 ("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:**
+
+- `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} products · save {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} /pc regular price)
+              </span>
+            )}
+          </li>
+        ))}
+      </ul>
+
+      <div className="price-box">
+        <strong>{bundle.bundlePrice} {bundle.currency}</strong>
+        {bundle.savings > 0 && (
+          <p>
+            Individually it would cost <s>{bundle.itemsSum} {bundle.currency}</s> —
+            you save <strong>{bundle.savings} {bundle.currency}</strong>
+            ({bundle.savingsPercent}%)
+          </p>
+        )}
+        <button onClick={addToCart}>Add the whole bundle to cart</button>
+      </div>
+    </article>
+  );
+}
 ```
 
+**Behind the scenes at checkout.** When the customer buys a bundle, Behio
+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.
+
+---
+
 ### 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** — 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 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** — 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.
+
+**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; // hide empty section
+  return (
+    <section>
+      <h2>{title}</h2>
+      <div className="carousel">
+        {items.map((item) => (
+          <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}</span>
+            {item.stockCached === 0 && <span className="text-red">Sold out</span>}
+          </a>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function ProductDetail({ slug }: { slug: string }) {
+  const { data: crossSell } = useCrossSell(slug);
+
+  return (
+    <>
+      {/* ... product info ... */}
+
+      <CrossSellSection
+        title="Frequently bought together"
+        items={crossSell?.crossSell ?? []}
+      />
+      <CrossSellSection
+        title="You might also like"
+        items={crossSell?.related ?? []}
+      />
+      <CrossSellSection
+        title="Want a premium version?"
+        items={crossSell?.upsell ?? []}
+      />
+    </>
+  );
+}
+```
+
+**Tip — merge into a single section.** If you have sparse data and want
+to keep it simple, combine all three into one list:
 
-// 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.** 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).
+
+**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.
+
+**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.
+
+**Where to use it.**
+
+- **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.
+
+**Fields returned:**
+
+- `id`, `name`, `slug` — promotion identity
+- `type` — `FLASH_SALE` / `SEASONAL` / `CLEARANCE` / `BOGO` / `BUNDLE` / `LOYALTY`
+- `discountType` — `PERCENTAGE` / `FIXED_AMOUNT` / `FREE_SHIPPING` / `BUY_X_GET_Y`
+- `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';
 
-// 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 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 ?? [];
 
-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;
+
+  // Highest-priority promotion (the BE already sorts by priority DESC,
+  // then 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>Use code <code>{promo.name}</code> at checkout to redeem</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>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>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}`;
+    case 'FREE_SHIPPING': return 'Free shipping';
+    case 'BUY_X_GET_Y': return `${p.discountValue}+1 FREE`;
+    default: return 'SALE';
+  }
+}
 ```
 
+**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 }) {
+  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>
+  );
+}
+```
+
+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
 
 ### Catalog

package/package.json

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