@behio/storefront-sdk 0.2.0 → 0.3.0

package/README.md

@@ -1,1393 +1,120 @@
 # @behio/storefront-sdk
 
-**Build your own e-shop. Keep 100% control over the frontend.**
+**Headless e-commerce SDK for building custom storefronts.**
 
-Behio is a headless e-commerce platform that gives you a complete backend — products, inventory, orders, customers, discounts, multi-currency, multi-language, payments — and lets *you* design the storefront however you want. No themes, no templates, no vendor lock-in.
-
-This SDK is the fastest way to connect your Next.js, React, or any JavaScript app to the Behio Storefront API.
+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.
 
 ## Why Behio?
 
-- **You own the frontend.** Build it in Next.js, Astro, Nuxt, SvelteKit, React Native — or use plain HTML. The backend doesn't care.
-- **Production-ready e-commerce backend in minutes.** Product catalog, cart, checkout, customer accounts, orders, tracking, CMS pages, discount codes, volume pricing, multi-warehouse inventory — all included.
-- **Built for developers.** Type-safe, auto-completing, fully documented. Modern React hooks with TanStack Query under the hood. Automatic token refresh, optimistic cart updates, SSR prefetch support.
-- **Scale-ready.** Redis caching, rate limiting, webhooks, API keys with scoped permissions. From MVP to millions of orders on the same stack.
-- **Admin UI you don't have to build.** Behio comes with a full admin dashboard for managing products, orders, customers, CMS content, and analytics. You focus on the customer experience.
-
-**Perfect for:** agencies building custom e-shops, brands that want a unique storefront, SaaS apps that need built-in commerce, headless migrations from Shopify / WooCommerce.
-
----
-
-## 🚀 Get started
-
-Pick your integration path:
-
-### [👉 Next.js / React — with hooks, auto-caching, SSR](#-nextjs--react-path)
-The fastest way. React hooks for everything, automatic state management, SSR prefetch built-in.
-
-### [👉 Vanilla JavaScript / Node.js — core client only](#-vanilla-js--nodejs-path)
-Works anywhere: browsers, Node.js, Deno, Bun, Cloudflare Workers, edge runtimes. No React required.
-
----
-
-## 📚 Table of contents
-
-**Setup**
-- [Install](#install)
-- [Get your API key](#get-your-api-key)
-
-**Integration paths**
-- [Next.js / React path](#-nextjs--react-path) → [Setup provider](#1-setup-the-provider) → [Fetch data](#2-fetch-data-with-hooks) → [Cart & checkout](#3-cart--checkout) → [Authentication](#4-customer-authentication) → [Server Actions](#5-server-actions--forms)
-- [Vanilla JS path](#-vanilla-js--nodejs-path) → [Create client](#1-create-a-client) → [Use it](#2-call-any-endpoint)
-
-**Reference**
-- [All React hooks](#all-react-hooks)
-- [All API methods](#all-api-methods)
-- [Types](#types)
-- [Constants / Enums](#constants--enums)
-- [Error handling](#error-handling)
-- [Events & interceptors](#events--interceptors)
-- [Auto token refresh](#auto-token-refresh)
-- [Cart session management](#cart-session-management)
-
----
+- **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).
 
 ## Install
 
 ```bash
 npm install @behio/storefront-sdk
-# or
-yarn add @behio/storefront-sdk
-# or
-pnpm add @behio/storefront-sdk
-```
-
-The SDK has two entry points:
-
-```typescript
-// Core — works everywhere (Node.js, browser, Deno, Bun, edge runtimes)
-import { BehioStorefront } from '@behio/storefront-sdk';
-
-// React — hooks + provider for Next.js / React apps
-import { BehioProvider, useProducts, useCart, useAuth } from '@behio/storefront-sdk/react';
-```
-
-## Get your API key
-
-1. Log in to your Behio admin dashboard
-2. Go to your e-shop → **Settings** → **API Keys**
-3. Create a **Public key** (starts with `pk_live_`) — safe for browsers
-4. Optionally create a **Private key** (starts with `sk_live_`) — for server-side only
-
-The API key identifies your e-shop. No shop domain needed.
-
----
-
-# 🎯 Next.js / React path
-
-You can build your Next.js storefront in **two ways** — pick one or mix them:
-
-### [A. Client-side hooks](#1-setup-the-provider) 🪝
-`BehioProvider` + hooks like `useProducts`, `useCart`, `useAuth`. Fast interactivity, automatic state management, optimistic updates.
-
-**Best for:** SPAs, logged-in dashboards, product browsing, cart UI, live filters.
-**Downside:** API key is public (uses `NEXT_PUBLIC_BEHIO_API_KEY`), runs in the browser.
-
-### [B. Server Components + Server Actions](#b-server-components--server-actions) 🔒
-Use the core `BehioStorefront` directly in RSC and server actions. API key never leaves the server, tokens in httpOnly cookies, forms work without JS.
-
-**Best for:** SEO-critical pages, checkout, auth forms, sensitive mutations.
-**Upside:** More secure — private API key, better perceived performance, progressive enhancement.
-
-### Recommendation
-
-Mix both:
-- **Server Components** for the first paint (product pages, categories, SEO)
-- **Client hooks** for interactive bits (cart, search, filters, logged-in area)
-- **Server Actions** for anything sensitive (checkout, auth, customer profile)
-
----
-
-## 1. Setup the provider
-
-Create a client wrapper for the provider:
-
-```tsx
-// app/providers.tsx
-'use client';
-import { BehioProvider } from '@behio/storefront-sdk/react';
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <BehioProvider
-      apiKey={process.env.NEXT_PUBLIC_BEHIO_API_KEY!}  // e.g. "pk_live_6d3f255..."
-      locale="cs"
-      currency="CZK"
-      storage="cookies"       // "cookies" | "localStorage" | "memory"
-    >
-      {children}
-    </BehioProvider>
-  );
-}
-```
-
-Use it in your root layout (stays as a server component):
-
-```tsx
-// app/layout.tsx
-import { Providers } from './providers';
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html>
-      <body>
-        <Providers>{children}</Providers>
-      </body>
-    </html>
-  );
-}
-```
-
-Set your env variables:
-
-```bash
-# .env.local
-NEXT_PUBLIC_BEHIO_API_KEY=pk_live_xxxxxxxxxxxx
-
-# For server-side (Server Actions, RSC) — NEVER expose to client
-BEHIO_API_KEY=sk_live_xxxxxxxxxxxx
-```
-
-## 2. Fetch data with hooks
-
-All catalog data available via React hooks. Each hook returns `{ data, isLoading, error, refetch }`.
-
-```tsx
-'use client';
-import { useShopInfo, useProducts, useProduct, useCategories, formatPrice } from '@behio/storefront-sdk/react';
-
-export function HomePage() {
-  const { data: shop } = useShopInfo();
-  const { data: products } = useProducts({ limit: 12, sort: 'newest' });
-  const { data: cats } = useCategories();
-
-  return (
-    <div>
-      <h1>{shop?.name}</h1>
-      <nav>
-        {cats?.map(c => <a key={c.id} href={`/category/${c.slug}`}>{c.name}</a>)}
-      </nav>
-      <div className="grid grid-cols-4 gap-4">
-        {products?.items.map(p => (
-          <div key={p.id}>
-            <h3>{p.name}</h3>
-            <p>{formatPrice(p.price.amount, p.price.currency)}</p>
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-}
 ```
 
-**SSR prefetch** (App Router server components):
+## Quick Start
 
 ```tsx
-// app/products/[slug]/page.tsx (server component)
 import { BehioStorefront } from '@behio/storefront-sdk';
-import { ProductDetail } from './ProductDetail';
 
-export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
-  const { slug } = await params;
-  const shop = new BehioStorefront({
-    apiKey: process.env.BEHIO_API_KEY!,
-  });
-  const initialData = await shop.catalog.getProduct(slug);
-  return <ProductDetail slug={slug} initialData={initialData} />;
-}
-```
-
-```tsx
-// ProductDetail.tsx (client component — hydrates with SSR data)
-'use client';
-import { useProduct } from '@behio/storefront-sdk/react';
-
-export function ProductDetail({ slug, initialData }) {
-  const { data: product } = useProduct(slug, { initialData });
-  return <h1>{product?.name}</h1>;
-}
-```
-
-→ [All available hooks](#all-react-hooks)
-
-## 3. Cart & checkout
-
-`useCart` gives you everything — state, mutations, computed values, optimistic updates.
-
-```tsx
-'use client';
-import { useCart, useCartCount, formatPrice } from '@behio/storefront-sdk/react';
-
-export function CartButton() {
-  const count = useCartCount();  // lightweight — just the number
-  return <span>Cart ({count})</span>;
-}
-
-export function CartPage() {
-  const {
-    cart, isEmpty, itemCount,
-    addItem, updateQuantity, removeItem, clear,
-    applyDiscount, removeDiscount,
-  } = useCart();
-
-  if (isEmpty) return <p>Your cart is empty</p>;
-
-  return (
-    <div>
-      {cart?.items.map(item => (
-        <div key={item.id}>
-          <span>{item.product.name}</span>
-          <button onClick={() => updateQuantity(item.id, item.quantity - 1)}>-</button>
-          <span>{item.quantity}</span>
-          <button onClick={() => updateQuantity(item.id, item.quantity + 1)}>+</button>
-          <button onClick={() => removeItem(item.id)}>Remove</button>
-        </div>
-      ))}
-      <p>Total: {formatPrice(cart?.grandTotal ?? 0, cart?.currency ?? 'CZK')}</p>
-    </div>
-  );
-}
-```
-
-Checkout:
-
-```tsx
-'use client';
-import { useCheckout } from '@behio/storefront-sdk/react';
-
-export function CheckoutForm() {
-  const { createOrder, isCreating, order } = useCheckout();
-
-  if (order) return <h2>Order #{order.orderNumber} confirmed!</h2>;
-
-  return (
-    <form onSubmit={async (e) => {
-      e.preventDefault();
-      await createOrder({
-        email: 'customer@example.com',
-        shippingAddress: { firstName: 'Jan', lastName: 'Novak', street: 'Hlavni 1', city: 'Praha', zip: '11000', country: 'CZ' },
-        billingAddress: { firstName: 'Jan', lastName: 'Novak', street: 'Hlavni 1', city: 'Praha', zip: '11000', country: 'CZ' },
-      });
-    }}>
-      {/* form fields */}
-      <button disabled={isCreating}>{isCreating ? 'Processing...' : 'Place order'}</button>
-    </form>
-  );
-}
-```
-
-→ [Cart session management](#cart-session-management)
-
-## 4. Customer authentication
-
-Register, login, logout — with automatic token persistence and anonymous cart merge.
-
-```tsx
-'use client';
-import { useAuth } from '@behio/storefront-sdk/react';
-
-export function AuthSection() {
-  const { isLoggedIn, customer, login, logout, isLoggingIn, loginError } = useAuth();
-
-  if (isLoggedIn) {
-    return (
-      <>
-        <p>Welcome, {customer?.firstName || customer?.email}</p>
-        <button onClick={logout}>Logout</button>
-      </>
-    );
-  }
-
-  return (
-    <form onSubmit={async (e) => {
-      e.preventDefault();
-      const fd = new FormData(e.currentTarget);
-      await login(fd.get('email') as string, fd.get('password') as string);
-    }}>
-      <input name="email" type="email" />
-      <input name="password" type="password" />
-      {loginError && <p>{loginError.message}</p>}
-      <button disabled={isLoggingIn}>Login</button>
-    </form>
-  );
-}
-```
-
-Once logged in, authenticated hooks work automatically:
-
-```tsx
-import { useOrders, useCustomer, useAddresses } from '@behio/storefront-sdk/react';
-
-const { data: orders } = useOrders();
-const { data: profile, updateProfile } = useCustomer();
-const { addresses, createAddress, deleteAddress } = useAddresses();
-```
-
-→ [Auto token refresh](#auto-token-refresh)
-
-<a id="b-server-components--server-actions"></a>
-## 5. Server Components & Server Actions (secure path)
-
-For the **most secure** integration — API key stays on the server, tokens in httpOnly cookies, forms work without JavaScript (progressive enhancement).
-
-**Server Component — data fetching:**
-
-```tsx
-// app/products/page.tsx (server component — no "use client")
-import { BehioStorefront } from '@behio/storefront-sdk';
-
-export default async function ProductsPage() {
-  const shop = new BehioStorefront({
-    apiKey: process.env.BEHIO_API_KEY!,         // ← private, server-only
-  });
-
-  const products = await shop.catalog.getProducts({ limit: 24 });
-
-  return (
-    <div>
-      {products.items.map(p => (
-        <a key={p.id} href={`/products/${p.slug}`}>
-          <h3>{p.name}</h3>
-          <p>{p.price.amount} {p.price.currency}</p>
-        </a>
-      ))}
-    </div>
-  );
-}
-```
-
-**Server Actions — mutations:**
-
-```tsx
-// app/actions.ts
-'use server';
-import { BehioStorefront } from '@behio/storefront-sdk';
-import { cookies } from 'next/headers';
-
-function getShop() {
-  return new BehioStorefront({
-    apiKey: process.env.BEHIO_API_KEY!,
-  });
-}
-
-export async function loginAction(_: unknown, formData: FormData) {
-  const shop = getShop();
-  try {
-    const result = await shop.auth.login({
-      email: formData.get('email') as string,
-      password: formData.get('password') as string,
-    });
-
-    const cookieStore = await cookies();
-    cookieStore.set('behio_access', result.accessToken, {
-      httpOnly: true, secure: true, sameSite: 'lax', maxAge: 900,
-    });
-    cookieStore.set('behio_refresh', result.refreshToken, {
-      httpOnly: true, secure: true, sameSite: 'lax', maxAge: 30 * 86400,
-    });
-
-    return { success: true, error: null };
-  } catch (err) {
-    return { success: false, error: err instanceof Error ? err.message : 'Login failed' };
-  }
-}
-
-export async function addToCartAction(productId: string, quantity = 1) {
-  const shop = getShop();
-  const cookieStore = await cookies();
-  const cartSession = cookieStore.get('behio_cart_session')?.value;
-  if (cartSession) shop.setCartSession(cartSession);
-
-  const result = await shop.cart.addItem({ productId, quantity });
-
-  if (result.newSessionToken) {
-    cookieStore.set('behio_cart_session', result.newSessionToken, {
-      sameSite: 'lax', maxAge: 30 * 86400,
-    });
-  }
-  return result;
-}
-```
-
-```tsx
-// app/auth/page.tsx
-'use client';
-import { useActionState } from 'react';
-import { loginAction } from '../actions';
-
-export default function LoginPage() {
-  const [state, formAction, isPending] = useActionState(loginAction, { success: false, error: null });
-
-  return (
-    <form action={formAction}>
-      <input name="email" type="email" placeholder="Email" required />
-      <input name="password" type="password" placeholder="Password" required />
-      {state.error && <p>{state.error}</p>}
-      <button disabled={isPending}>{isPending ? 'Logging in...' : 'Login'}</button>
-    </form>
-  );
-}
-```
-
----
-
-# 🛠 Vanilla JS / Node.js path
-
-For Node.js backends, serverless functions, CLI tools, Deno, Bun, or any non-React JavaScript environment.
-
-## 1. Create a client
-
-```typescript
-import { BehioStorefront } from '@behio/storefront-sdk';
-
-const shop = new BehioStorefront({
-  apiKey: 'pk_live_xxx',
-  locale: 'cs',                       // optional
-  currency: 'CZK',                    // optional
-  timeout: 30000,                     // optional — request timeout (ms)
-  retries: 1,                         // optional — retry failed requests
-});
-```
-
-## 2. Call any endpoint
-
-Every API method returns a Promise. Types are fully auto-completed.
-
-```typescript
-// Catalog
-const products = await shop.catalog.getProducts({
-  limit: 20,
-  sort: 'newest',
-  categories: ['electronics', 'books'], // array filters sent as repeated query params
-  hasDiscount: true,
+const storefront = new BehioStorefront({
+  apiKey: 'pk_live_your_key',
 });
-const product = await shop.catalog.getProduct('my-product-slug');
-const { categories } = await shop.catalog.getCategories();
 
-// Auth
-const tokens = await shop.auth.register({ email: '...', password: '...' });
-await shop.auth.login({ email: '...', password: '...' });
+// Fetch products
+const { items } = await storefront.catalog.getProducts({ limit: 12 });
 
-// Cart
-await shop.cart.addItem({ productId: 'xxx', quantity: 2 });
-const cart = await shop.cart.get();
-await shop.cart.applyDiscount('SAVE20');
+// Add to cart
+await storefront.cart.addItem({ productId: items[0].id, quantity: 1 });
 
 // Checkout
-const order = await shop.checkout.createOrder({
+const order = await storefront.checkout.createOrder({
   email: 'customer@example.com',
-  shippingAddress: { /* ... */ },
-  billingAddress: { /* ... */ },
-});
-
-// Orders (auth required)
-const orders = await shop.orders.list();
-const detail = await shop.orders.get('ORD-123');
-
-// Public order tracking
-const tracked = await shop.orders.track('tracking-token-uuid');
-```
-
-→ [All API methods](#all-api-methods)
-
----
-
-# 📖 Reference
-
-## All React hooks
-
-| Hook | Purpose | Auth required |
-|------|---------|---------------|
-| [`useShopInfo()`](#useshopinfo) | E-shop info (name, currencies, languages) | No |
-| [`useShopSeo(opts?)`](#useshopseo) | Per-locale SEO metadata for the homepage | No |
-| [`useProducts(query?)`](#useproducts) | Product list with filters, pagination, search | No |
-| [`useProduct(slug)`](#useproduct) | Product detail | No |
-| [`useCategories(locale?)`](#usecategories) | Category tree | No |
-| [`useLabels(locale?)`](#uselabels) | Product labels/tags | No |
-| [`useFeatured()`](#usefeatured) | Featured products | No |
-| [`useFilters()`](#usefilters) | Dynamic filter fields | No |
-| [`useSearch(query)`](#usesearch) | Debounced product search | No |
-| [`useCart()`](#usecart) | Cart state + actions | No |
-| [`useCartCount()`](#usecartcount) | Cart item count (lightweight) | No |
-| [`useAuth()`](#useauth) | Login, register, logout | No |
-| [`useCheckout()`](#usecheckout) | Create order | No* |
-| [`useOrders(opts?)`](#useorders) | Order list | Yes |
-| [`useOrder(num)`](#useorder) | Order detail + cancel | Yes |
-| [`useCustomer()`](#usecustomer) | Profile + update | Yes |
-| [`useAddresses()`](#useaddresses) | Address CRUD | Yes |
-| [`usePages()` / `usePage(slug)`](#usepages) | CMS pages | No |
-| [`useBundles()` / `useBundle(slug)`](#usebundles) | Active bundles (sets) with auto-computed savings | No |
-| [`useCrossSell(productSlug)`](#usecrosssell) | Related / upsell / cross-sell products per product | No |
-| [`useProductPromotions(productSlug)`](#useproductpromotions) | Active promotions applicable to a product (with countdown) | No |
-
-\* Guest checkout works without auth if the e-shop allows it.
-
-### useShopInfo
-```typescript
-const { data, isLoading, error } = useShopInfo();
-// data: ShopInfo
-```
-
-### useShopSeo
-
-Returns per-locale SEO metadata (title, description, keywords, OG tags). Falls back to the shop's default locale when `locale` is omitted, and to `metaTitle / metaDescription` on the shop itself if there's no per-locale override.
-
-```tsx
-const { data: seo } = useShopSeo({ locale: 'cs' });
-// data: { locale, title, description, keywords, ogTitle, ogDescription, ogImage }
-```
-
-**Server-side / SSR** — use the core client directly to fetch at request time and pass as `initialData`:
-
-```tsx
-// app/[locale]/page.tsx (Next.js RSC)
-import { BehioStorefront } from '@behio/storefront-sdk';
-import type { Metadata } from 'next';
-
-const shop = new BehioStorefront({ apiKey: process.env.BEHIO_API_KEY! });
-
-export async function generateMetadata({ params }: { params: { locale: string } }): Promise<Metadata> {
-  const seo = await shop.getShopSeo(params.locale);
-  return {
-    title: seo.title ?? undefined,
-    description: seo.description ?? undefined,
-    openGraph: {
-      title: seo.ogTitle ?? seo.title ?? undefined,
-      description: seo.ogDescription ?? seo.description ?? undefined,
-      images: seo.ogImage ? [seo.ogImage] : undefined,
-    },
-  };
-}
-
-export default async function Home({ params }: { params: { locale: string } }) {
-  const seo = await shop.getShopSeo(params.locale);
-  // Pass to client component for React Query hydration:
-  // <ClientHome initialSeo={seo} />
-}
-```
-
-Client hydration:
-```tsx
-'use client';
-import { useShopSeo } from '@behio/storefront-sdk/react';
-
-export function ClientHome({ initialSeo }: { initialSeo: ShopSeo }) {
-  const { data } = useShopSeo({ locale: 'cs', initialData: initialSeo });
-  return <h1>{data.title}</h1>;
-}
-```
-
-### useProducts
-
-Supports **both** traditional pagination and infinite scroll from one hook.
-
-```typescript
-const {
-  items,          // flat array (all pages merged) — for infinite scroll
-  data,           // PaginatedResponse (current page) — for traditional pagination
-  total, totalPages, currentPage, limit,
-
-  // Traditional pagination
-  page, setPage,
-
-  // Infinite scroll
-  loadMore, hasMore, isLoadingMore,
-
-  // State
-  isLoading, isFetching, error, isError, refetch,
-} = useProducts({
-  page: 1,
-  limit: 24,
-
-  // Scalar filters
-  category: 'electronics',        // single category slug
-  label: 'new',                   // single label slug
-  priceMin: 100,
-  priceMax: 5000,
-  currency: 'CZK',
-  locale: 'cs',
-  sort: 'price_asc',              // or ProductSort.PRICE_ASC
-  inStock: true,
-  search: 'keyboard',
-  customFields: { material: 'aluminum' },
-
-  // Array filters — sent as repeated query params (?ids=a&ids=b)
-  ids: ['prod_1', 'prod_2'],            // filter to specific IDs
-  slugs: ['red-shoes', 'blue-hat'],     // filter to specific slugs
-  categories: ['electronics', 'books'], // OR logic (in ANY of these)
-  labels: ['sale', 'new'],              // AND logic (must have ALL)
-  excludeIds: ['prod_999'],             // exclude specific IDs (e.g. related products)
-  excludeCategories: ['archive'],       // exclude products in these categories
-
-  // Boolean / time filters
-  hasDiscount: true,                    // only products with compareAtPrice
-  isFeatured: true,                     // only featured products
-  createdAfter: Date.now() - 7 * 864e5, // created in last 7 days (epoch ms)
-
-  // Hook options
-  enabled: true,                        // skip fetch until true
-  initialData: prefetchedData,          // SSR hydration
+  shippingAddress: { firstName: 'Jan', lastName: 'Novak', street: 'Vodickova 12', city: 'Praha', zip: '11000', country: 'CZ' },
 });
 ```
 
-**Infinite scroll example:**
-```tsx
-const { items, loadMore, hasMore, isLoadingMore } = useProducts({ limit: 24 });
-
-return (
-  <>
-    {items.map(p => <ProductCard key={p.id} product={p} />)}
-    {hasMore && <button onClick={loadMore} disabled={isLoadingMore}>Load more</button>}
-  </>
-);
-```
-
-**Traditional pagination example:**
-```tsx
-const { data, page, setPage, totalPages } = useProducts({ limit: 24 });
-
-return (
-  <>
-    {data?.items.map(p => <ProductCard key={p.id} product={p} />)}
-    <Pagination page={page} total={totalPages} onChange={setPage} />
-  </>
-);
-```
-
-### useProduct
-```typescript
-const { data, isLoading, error } = useProduct('product-slug', {
-  locale: 'cs',
-  currency: 'CZK',
-  initialData: prefetchedData,  // for SSR hydration
-});
-// data: ProductDetail
-```
-
-### useCategories
-```typescript
-const { data, isLoading } = useCategories('cs');
-// data: Category[]  (tree structure with children)
-```
-
-### useLabels
-```typescript
-const { data } = useLabels('cs');
-// data: ProductLabel[]
-```
-
-### useFeatured
-```typescript
-const { data } = useFeatured();
-// data: PaginatedResponse<ProductListItem>
-```
-
-### useFilters
-```typescript
-const { data } = useFilters();
-// data: FilterField[] — use to build dynamic filter UI
-```
-
-### useSearch
-```typescript
-const { data, isLoading } = useSearch(query, { debounceMs: 300, limit: 10 });
-// Debounced — only fetches after user stops typing
-```
-
-### useCart
-```typescript
-const {
-  cart,              // Cart | null
-  isLoading, error,
-  isEmpty,           // boolean
-  itemCount,         // number
-  // Actions
-  addItem,           // (productId, quantity?) => Promise
-  updateQuantity,    // (itemId, quantity) => Promise
-  removeItem,        // (itemId) => Promise
-  clear,             // () => Promise
-  applyDiscount,     // (code) => Promise
-  removeDiscount,    // () => Promise
-  merge,             // () => Promise — merges anonymous cart after login
-  // States
-  isAdding, isUpdating, isRemoving,
-} = useCart();
-```
-
-### useCartCount
-```typescript
-const count = useCartCount();
-// number — lightweight, reads from cache first
-```
-
-### useAuth
-```typescript
-const {
-  isLoggedIn, customer,
-  login,           // (email, password) => Promise
-  register,        // (input) => Promise
-  logout,          // () => Promise
-  forgotPassword,  // (email) => Promise
-  resetPassword,   // (token, newPassword) => Promise
-  verifyEmail,     // (token) => Promise
-  isLoggingIn, isRegistering,
-  loginError, registerError,
-} = useAuth();
-```
-
-### useCheckout
-```typescript
-const {
-  createOrder,     // (input) => Promise<OrderDetail>
-  isCreating, error,
-  order,           // OrderDetail | null — last created order
-  reset,           // () => void
-} = useCheckout();
-```
-
-### useOrders
-```typescript
-const { data, isLoading } = useOrders({ page: 1, limit: 10 });
-// data: PaginatedResponse<OrderListItem>
-```
-
-### useOrder
-```typescript
-const { data, cancel, isCancelling } = useOrder('ORD-123');
-// data: OrderDetail
-```
-
-### useCustomer
-```typescript
-const { data, updateProfile, isUpdating } = useCustomer();
-// data: CustomerProfile
-```
-
-### useAddresses
-```typescript
-const {
-  addresses,
-  createAddress, updateAddress, deleteAddress,
-  isCreating, isDeleting,
-} = useAddresses();
-```
-
-### usePages
-```typescript
-const { data: pages } = usePages('cs');
-const { data: page } = usePage('about-us', 'cs');
-```
-
-### 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
+## React Hooks
 
 ```tsx
-import { useBundles, useBundle, useCart, useBehio } from '@behio/storefront-sdk/react';
-
-// ---- 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
+import { BehioProvider, useProducts, useCart, useAddToCart } from '@behio/storefront-sdk/react';
 
+function App() {
   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>
-  );
-}
-
-// ---- Bundle detail page with "Add to cart" ----
-function BundleDetail({ slug }: { slug: string }) {
-  const { data: bundle, isLoading } = useBundle(slug);
-  const { client } = useBehio();
-  const { refresh } = useCart();
-
-  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
-
-**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 ?? []}
-      />
-    </>
+    <BehioProvider client={storefront}>
+      <ProductList />
+    </BehioProvider>
   );
 }
-```
-
-**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 = [
-  ...(crossSell?.crossSell ?? []),
-  ...(crossSell?.related ?? []),
-  ...(crossSell?.upsell ?? []),
-].slice(0, 6);
-```
-
----
-
-### useProductPromotions
-
-**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.
+function ProductList() {
+  const { data, isLoading } = useProducts({ limit: 12 });
+  const addToCart = useAddToCart();
 
-**Where to use it.**
+  if (isLoading) return <div>Loading...</div>;
 
-- **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';
-
-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 ?? [];
-
-  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} />}
+  return data.items.map(p => (
+    <div key={p.id}>
+      <h3>{p.name} — {p.price} {p.currency}</h3>
+      <button onClick={() => addToCart.mutateAsync({ productId: p.id, quantity: 1 })}>
+        Add to Cart
+      </button>
     </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:
+## What's Included
 
-```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>
-  );
-}
-```
+### SDK Modules
 
-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`.
+| Module | Description |
+|--------|-------------|
+| `catalog` | Products, categories, labels, search, filters, bundles, cross-sell, promotions |
+| `auth` | Register, login, logout, password reset, token refresh |
+| `cart` | Items, discounts, gift cards, bundles, cart merge |
+| `checkout` | Create orders with atomic stock/payment validation |
+| `orders` | List, detail, tracking, cancel |
+| `customer` | Profile, addresses, password change |
+| `wishlist` | Add, remove, check |
+| `reviews` | Submit, list, vote helpful |
+| `addresses` | Google Places autocomplete with debounce hook |
+| `returns` | Submit return requests |
+| `consent` | Cookie consent (GDPR) |
+| `quotes` | B2B quote requests |
+| `pages` | CMS pages |
 
-## All API methods
+### React Hooks (30+)
 
-### Catalog
-```typescript
-shop.catalog.getProducts(query?)            → PaginatedResponse<ProductListItem>
-shop.catalog.getProduct(slug)                → ProductDetail
-shop.catalog.getCategories(locale?)          → { categories: Category[] }
-shop.catalog.getCategory(slug, locale?)      → CategoryDetail
-shop.catalog.getCategoryProducts(slug, q?)   → PaginatedResponse<ProductListItem>
-shop.catalog.getLabels(locale?)              → { labels: ProductLabel[] }
-shop.catalog.getFeatured()                   → PaginatedResponse<ProductListItem>
-shop.catalog.getFilters()                    → { filters: FilterField[] }
-shop.catalog.search(query, opts?)            → PaginatedResponse<ProductListItem>
-shop.catalog.getBundles()                    → { items: Bundle[] }
-shop.catalog.getBundle(slug)                 → Bundle
-shop.catalog.getCrossSell(productSlug)       → { related, upsell, crossSell: CrossSellItem[] }
-shop.catalog.getProductPromotions(slug)      → { items: ActivePromotion[] }
-```
+`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`
 
-### Cart — bundles
-```typescript
-shop.cart.addBundle(bundleId, quantity?)     → Cart
-shop.cart.updateBundleQuantity(id, qty)      → Cart
-shop.cart.removeBundle(bundleId)             → Cart
-```
-
-### Auth
-```typescript
-shop.auth.register(input)                    → AuthTokens
-shop.auth.login(input)                       → AuthTokens
-shop.auth.refresh(token?)                    → AuthTokens
-shop.auth.logout(token?)                     → MessageResponse
-shop.auth.forgotPassword(email)              → MessageResponse
-shop.auth.resetPassword(token, password)     → MessageResponse
-shop.auth.verifyEmail(token)                 → MessageResponse
-shop.auth.isLoggedIn()                       → boolean
-```
+### Framework Support
 
-### Cart
-```typescript
-shop.cart.get()                              → Cart
-shop.cart.addItem({ productId, quantity })   → Cart & { newSessionToken? }
-shop.cart.updateQuantity(itemId, qty)        → Cart
-shop.cart.removeItem(itemId)                 → Cart
-shop.cart.clear()                            → void
-shop.cart.merge()                            → Cart
-shop.cart.applyDiscount(code)                → Cart
-shop.cart.removeDiscount()                   → Cart
-```
+- **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)
 
-### Checkout
-```typescript
-shop.checkout.createOrder(input)             → OrderDetail
-```
+### Built-in Features
 
-### Orders
-```typescript
-shop.orders.list(opts?)                      → PaginatedResponse<OrderListItem>
-shop.orders.get(orderNumber)                 → OrderDetail
-shop.orders.cancel(orderNumber)              → OrderDetail
-shop.orders.track(trackingToken)             → OrderDetail   // no auth needed
-```
+- Automatic JWT token refresh on 401
+- Configurable retry with backoff (5xx, 429)
+- Rate limit tracking and warnings
+- Request/response interceptors
+- Event system (auth, cart, order lifecycle)
+- Cart session persistence
 
-### Customer
-```typescript
-shop.customer.getProfile()                   → CustomerProfile
-shop.customer.updateProfile(data)            → CustomerProfile
-shop.customer.changePassword(current, new)   → MessageResponse
-shop.customer.getAddresses()                 → { items: CustomerAddress[] }
-shop.customer.createAddress(data)            → CustomerAddress
-shop.customer.updateAddress(id, data)        → CustomerAddress
-shop.customer.deleteAddress(id)              → void
-```
-
-### Pages
-```typescript
-shop.pages.list(locale?)                     → { pages: Page[] }
-shop.pages.get(slug, locale?)                → PageDetail
-```
-
-### Instance utilities
-```typescript
-shop.getShopInfo()                           → ShopInfo
-shop.getShopSeo(locale?)                     → ShopSeo (per-locale SEO for SSR/metadata)
-shop.setTokens({ accessToken, refreshToken })
-shop.clearTokens()
-shop.getAccessToken()                        → string | undefined
-shop.getRefreshToken()                       → string | undefined
-shop.setCartSession(token)
-shop.getCartSession()                        → string | undefined
-shop.clearCartSession()
-shop.on(event, handler)                      → unsubscribe fn
-shop.addRequestInterceptor(fn)               → unsubscribe fn
-shop.addResponseInterceptor(fn)              → unsubscribe fn
-shop.getRateLimitInfo()                      → { remaining, reset }
-```
+## Documentation
 
-## Types
+Full API reference, framework guides, and examples:
 
-```typescript
-ProductListItem {
-  id, slug, name, shortDescription?, sku, gtin?,
-  price: ProductPrice,
-  inStock, stockQuantity?, image?,
-  labels: ProductLabel[], isFeatured
-}
-
-ProductDetail extends ProductListItem {
-  longDescription?,
-  images[], categories[], variants[],
-  volumePricing[], customFields, seo,
-  weight?, weightUnit?,
-}
-
-ProductPrice { amount: number, currency: string, compareAtPrice?: number | null }
-
-Cart {
-  id, sessionToken?,
-  items: CartItem[],
-  subtotal, discountTotal, discount?,
-  grandTotal, currency, itemCount
-}
-
-CartItem {
-  id, product: CartItemProduct,
-  quantity, unitPrice, totalPrice,
-  priceChanged, volumePriceApplied
-}
-
-OrderDetail {
-  orderNumber, status, paymentStatus, fulfillmentStatus,
-  items[], shippingAddress, billingAddress,
-  subtotal, taxTotal, shippingTotal, discountTotal, grandTotal, currency,
-  statusHistory[], trackingToken?
-}
-
-CustomerProfile {
-  id, email, firstName?, lastName?, phone?, emailVerified
-}
-```
-
-## Constants / Enums
-
-Type-safe constants for common values — autocomplete, iterable, zero runtime cost.
-
-```typescript
-import {
-  ProductSort,
-  OrderStatuses,
-  PaymentStatuses,
-  FulfillmentStatuses,
-  AddressTypes,
-} from '@behio/storefront-sdk';
-
-// Use in queries
-shop.catalog.getProducts({ sort: ProductSort.PRICE_ASC });
-
-// Type-safe comparisons
-if (order.status === OrderStatuses.SHIPPED) { /* ... */ }
-if (order.paymentStatus === PaymentStatuses.PAID) { /* ... */ }
-
-// Iterate for dropdowns
-Object.values(ProductSort);      // ['price_asc', 'price_desc', ...]
-Object.values(OrderStatuses);    // ['PENDING', 'CONFIRMED', ...]
-```
-
-Available constants:
-- `ProductSort`: `PRICE_ASC`, `PRICE_DESC`, `NAME_ASC`, `NAME_DESC`, `NEWEST`, `FEATURED`
-- `OrderStatuses`: `PENDING`, `CONFIRMED`, `PROCESSING`, `SHIPPED`, `DELIVERED`, `CANCELLED`, `REFUNDED`
-- `PaymentStatuses`: `UNPAID`, `PAID`, `PARTIALLY_REFUNDED`, `REFUNDED`
-- `FulfillmentStatuses`: `UNFULFILLED`, `PARTIALLY_FULFILLED`, `FULFILLED`
-- `AddressTypes`: `SHIPPING`, `BILLING`
-
-## Error handling
-
-```typescript
-import { BehioApiError, BehioNetworkError } from '@behio/storefront-sdk';
-
-try {
-  await shop.auth.login({ email: 'wrong', password: 'bad' });
-} catch (err) {
-  if (err instanceof BehioApiError) {
-    err.status;        // HTTP status (401)
-    err.code;          // Typed error code ('INVALID_CREDENTIALS')
-    err.message;       // Human-readable message
-    err.body;          // Full API response
-    err.isRetryable;   // boolean
-    err.is('INVALID_CREDENTIALS');  // typed helper
-  }
-  if (err instanceof BehioNetworkError) {
-    err.code;          // 'NETWORK_ERROR' | 'TIMEOUT'
-    err.isRetryable;   // always true
-  }
-}
-```
-
-**Error codes:** `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `VALIDATION_ERROR`, `CONFLICT`, `RATE_LIMITED`, `CART_EMPTY`, `PRODUCT_NOT_FOUND`, `INVALID_CREDENTIALS`, `INVALID_DISCOUNT`, `DISCOUNT_EXPIRED`, `TOKEN_EXPIRED`, `TOKEN_INVALID`, `EMAIL_ALREADY_EXISTS`, `ORDER_NOT_CANCELLABLE`, `INTERNAL_ERROR`, `NETWORK_ERROR`, `TIMEOUT`, `UNKNOWN`
-
-## Events & interceptors
-
-```typescript
-// Events
-shop.on('auth:login', (data) => console.log('Logged in'));
-shop.on('auth:logout', () => console.log('Logged out'));
-shop.on('auth:token-refresh', () => console.log('Token refreshed'));
-shop.on('cart:updated', (cart) => console.log('Cart changed'));
-shop.on('order:created', (order) => console.log('Order placed'));
-shop.on('error', (err) => console.error('API error', err));
-shop.on('rate-limit-warning', ({ remaining }) => console.warn(`${remaining} left`));
-
-// Unsubscribe
-const unsub = shop.on('error', handler);
-unsub();
-
-// Request interceptor — modify outgoing requests
-shop.addRequestInterceptor((config) => {
-  config.headers['X-Custom'] = 'value';
-  return config;
-});
-
-// Response interceptor — observe all responses
-shop.addResponseInterceptor((res) => {
-  console.log(`${res.status}`);
-});
-```
-
-Event types: `auth:login`, `auth:logout`, `auth:token-refresh`, `auth:token-refresh-failed`, `cart:updated`, `cart:cleared`, `order:created`, `error`, `request`, `response`, `rate-limit-warning`
-
-## Auto token refresh
-
-When any authenticated request returns 401, the SDK automatically:
-1. Calls `auth.refresh()` with the stored refresh token
-2. Retries the original request with the new access token
-3. If refresh also fails → clears tokens, throws original error
-
-No code needed. A concurrent-request lock prevents multiple simultaneous refreshes.
-
-## Cart session management
-
-Anonymous users get a `sessionToken` automatically on first `addItem`. It's stored in cookies/localStorage via `BehioProvider` (or manually via `shop.setCartSession()`).
-
-After login, call `shop.cart.merge()` (or use `useCart().merge()`) to combine the anonymous cart with the customer account. The React `useAuth()` hook does this automatically.
-
----
-
-## React Query keys (for manual cache invalidation)
-
-```typescript
-['behio', 'shop-info']
-['behio', 'products', queryString]
-['behio', 'product', slug]
-['behio', 'categories', locale?]
-['behio', 'labels', locale?]
-['behio', 'featured']
-['behio', 'filters']
-['behio', 'search', query]
-['behio', 'cart']
-['behio', 'customer']
-['behio', 'addresses']
-['behio', 'orders', params]
-['behio', 'order', orderNumber]
-['behio', 'pages', locale?]
-['behio', 'page', slug, locale?]
-```
+**[sdk.behio.com](https://sdk.behio.com)**
 
 ## License