@behio/storefront-sdk 0.1.2 → 0.1.4

package/README.md

@@ -14,343 +14,114 @@ This SDK is the fastest way to connect your Next.js, React, or any JavaScript ap
 - **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 for clients
-- Brands that want their storefront to look and feel unique
-- SaaS apps that need built-in commerce
-- Headless migrations from Shopify, WooCommerce, PrestaShop
-
-## Get started
-
-```bash
-npm install @behio/storefront-sdk
-```
-
-## Two entry points
-
-```typescript
-// Core — works everywhere (Node.js, browser, Deno, Bun, edge)
-import { BehioStorefront } from '@behio/storefront-sdk';
-
-// React — hooks + provider for Next.js / React apps
-import { BehioProvider, useProducts, useCart, useAuth } from '@behio/storefront-sdk/react';
-```
+**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.
 
 ---
 
-## Core SDK
+## 🚀 Get started
 
-### Setup
+Pick your integration path:
 
-```typescript
-import { BehioStorefront } from '@behio/storefront-sdk';
+### [👉 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.
 
-const shop = new BehioStorefront({
-  apiKey: 'pk_live_xxx',              // Your API key — this identifies your e-shop
-  baseUrl: 'https://api.behio.com',   // Optional, defaults to https://api.behio.com
-  locale: 'cs',                        // Optional default locale
-  currency: 'CZK',                     // Optional default currency
-  timeout: 30000,                      // Optional request timeout (ms)
-  retries: 1,                          // Optional retries on network/5xx errors
-});
-```
-
-### Catalog
+### [👉 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.
 
-```typescript
-// List products with filters
-const products = await shop.catalog.getProducts({
-  page: 1,
-  limit: 24,
-  category: 'electronics',
-  label: 'new',
-  priceMin: 100,
-  priceMax: 5000,
-  sort: 'price_asc',  // price_asc | price_desc | name_asc | name_desc | newest | featured
-  inStock: true,
-  search: 'keyboard',
-  customFields: { material: 'aluminum', weight_min: 500 },
-});
-// → { items: ProductListItem[], total, page, limit, totalPages }
-
-// Product detail
-const product = await shop.catalog.getProduct('mechanical-keyboard-rgb');
-// → { id, slug, name, price, variants, volumePricing, images, categories, labels, seo, ... }
-
-// Categories (tree structure)
-const { categories } = await shop.catalog.getCategories('cs');
-
-// Labels
-const { labels } = await shop.catalog.getLabels();
-
-// Featured products
-const featured = await shop.catalog.getFeatured();
-
-// Search
-const results = await shop.catalog.search('gaming mouse', { limit: 10 });
-
-// Available filters (for dynamic filter UI)
-const { filters } = await shop.catalog.getFilters();
-// → [{ key: 'material', name: 'Material', type: 'TEXT', values: ['aluminum', 'plastic'] }]
-```
-
-### Auth
-
-```typescript
-// Register
-const tokens = await shop.auth.register({
-  email: 'customer@example.com',
-  password: 'SecurePass123!',
-  firstName: 'Jan',
-  lastName: 'Novak',
-});
-// → { accessToken: 'eyJ...', refreshToken: 'uuid' }
-// Tokens are automatically stored on the client instance
-
-// Login
-await shop.auth.login({ email: 'customer@example.com', password: 'SecurePass123!' });
-
-// Check if logged in
-shop.auth.isLoggedIn(); // true
-
-// Refresh token (rotates — old token invalidated)
-await shop.auth.refresh();
-
-// Logout
-await shop.auth.logout();
-
-// Password reset flow
-await shop.auth.forgotPassword('customer@example.com');
-await shop.auth.resetPassword('reset-token-from-email', 'NewPassword456!');
-
-// Email verification
-await shop.auth.verifyEmail('verification-token-from-email');
-
-// Manual token management (e.g. restore from localStorage)
-shop.setTokens({ accessToken: '...', refreshToken: '...' });
-shop.clearTokens();
-```
-
-### Cart
-
-```typescript
-// Add item (creates session automatically for anonymous users)
-const cart = await shop.cart.addItem({ productId: 'product-id', quantity: 2 });
-// Cart session token is auto-saved internally
-
-// Get cart
-const cart = await shop.cart.get();
-// → { items: [...], subtotal, discountTotal, grandTotal, currency, itemCount }
-
-// Update quantity
-await shop.cart.updateQuantity('cart-item-id', 5);
-
-// Remove item
-await shop.cart.removeItem('cart-item-id');
-
-// Discount codes
-await shop.cart.applyDiscount('SAVE20');
-await shop.cart.removeDiscount();
-
-// Merge anonymous cart after login
-await shop.auth.login({ email: '...', password: '...' });
-await shop.cart.merge();
-
-// Clear cart
-await shop.cart.clear();
-```
-
-### Checkout
-
-```typescript
-const order = await shop.checkout.createOrder({
-  email: 'customer@example.com',
-  phone: '+420123456789',
-  customerNote: 'Gift wrap please',
-  shippingAddress: {
-    firstName: 'Jan',
-    lastName: 'Novak',
-    street: 'Hlavni 123',
-    city: 'Praha',
-    zip: '11000',
-    country: 'CZ',
-  },
-  billingAddress: {
-    firstName: 'Jan',
-    lastName: 'Novak',
-    street: 'Hlavni 123',
-    city: 'Praha',
-    zip: '11000',
-    country: 'CZ',
-  },
-});
-// → { orderNumber: 'ORD-123', status: 'PENDING', items, grandTotal, trackingToken, ... }
-```
-
-### Orders
-
-```typescript
-// List customer orders (requires auth)
-const orders = await shop.orders.list({ page: 1, limit: 10 });
+---
 
-// Order detail
-const order = await shop.orders.get('ORD-123');
+## 📚 Table of contents
 
-// Cancel (only PENDING orders)
-await shop.orders.cancel('ORD-123');
+**Setup**
+- [Install](#install)
+- [Get your API key](#get-your-api-key)
 
-// Track by token (no auth needed — shareable link)
-const order = await shop.orders.track('tracking-token-uuid');
-```
+**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)
 
-### Customer Profile
+**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)
 
-```typescript
-const profile = await shop.customer.getProfile();
-await shop.customer.updateProfile({ firstName: 'Jana', phone: '+420987654321' });
-await shop.customer.changePassword('oldPassword', 'newPassword');
-
-// Addresses
-const { items: addresses } = await shop.customer.getAddresses();
-await shop.customer.createAddress({
-  type: 'SHIPPING', isDefault: true,
-  firstName: 'Jan', lastName: 'Novak',
-  street: 'Hlavni 1', city: 'Praha', zip: '11000', country: 'CZ',
-});
-await shop.customer.updateAddress('address-id', { street: 'Nova 42' });
-await shop.customer.deleteAddress('address-id');
-```
+---
 
-### CMS Pages
+## Install
 
-```typescript
-const { pages } = await shop.pages.list('cs');
-const about = await shop.pages.get('about-us', 'cs');
-// → { slug, title, content (JSON), seoTitle, seoDescription }
+```bash
+npm install @behio/storefront-sdk
+# or
+yarn add @behio/storefront-sdk
+# or
+pnpm add @behio/storefront-sdk
 ```
 
-### Error Handling
+The SDK has two entry points:
 
 ```typescript
-import { BehioApiError, BehioNetworkError } from '@behio/storefront-sdk';
+// Core — works everywhere (Node.js, browser, Deno, Bun, edge runtimes)
+import { BehioStorefront } from '@behio/storefront-sdk';
 
-try {
-  await shop.auth.login({ email: 'wrong', password: 'bad' });
-} catch (err) {
-  if (err instanceof BehioApiError) {
-    err.status;        // 401
-    err.code;          // 'INVALID_CREDENTIALS'
-    err.message;       // "Invalid email or password"
-    err.isRetryable;   // false
-    err.is('INVALID_CREDENTIALS'); // true
-  }
-  if (err instanceof BehioNetworkError) {
-    err.code;          // 'TIMEOUT' | 'NETWORK_ERROR'
-    err.isRetryable;   // true
-  }
-}
+// React — hooks + provider for Next.js / React apps
+import { BehioProvider, useProducts, useCart, useAuth } from '@behio/storefront-sdk/react';
 ```
 
-Error codes: `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `VALIDATION_ERROR`, `RATE_LIMITED`, `CART_EMPTY`, `PRODUCT_NOT_FOUND`, `INVALID_CREDENTIALS`, `INVALID_DISCOUNT`, `DISCOUNT_EXPIRED`, `TOKEN_EXPIRED`, `EMAIL_ALREADY_EXISTS`, `ORDER_NOT_CANCELLABLE`, `INTERNAL_ERROR`, `NETWORK_ERROR`, `TIMEOUT`
-
-### Constants
-
-Type-safe constants for enums — autocomplete, iterable, zero runtime cost:
+## Get your API key
 
-```typescript
-import {
-  ProductSort,
-  OrderStatuses,
-  PaymentStatuses,
-  FulfillmentStatuses,
-  AddressTypes,
-} from '@behio/storefront-sdk';
+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
 
-// Product sorting
-shop.catalog.getProducts({ sort: ProductSort.PRICE_ASC });
-// ProductSort.PRICE_ASC | PRICE_DESC | NAME_ASC | NAME_DESC | NEWEST | FEATURED
+The API key identifies your e-shop. No shop domain needed.
 
-// Order status checks
-if (order.status === OrderStatuses.SHIPPED) { ... }
-// OrderStatuses.PENDING | CONFIRMED | PROCESSING | SHIPPED | DELIVERED | CANCELLED | REFUNDED
+---
 
-// Payment status
-if (order.paymentStatus === PaymentStatuses.PAID) { ... }
+# 🎯 Next.js / React path
 
-// Fulfillment
-if (order.fulfillmentStatus === FulfillmentStatuses.FULFILLED) { ... }
+You can build your Next.js storefront in **two ways** — pick one or mix them:
 
-// Address types
-shop.customer.createAddress({ type: AddressTypes.SHIPPING, ... });
+### [A. Client-side hooks](#1-setup-the-provider) 🪝
+`BehioProvider` + hooks like `useProducts`, `useCart`, `useAuth`. Fast interactivity, automatic state management, optimistic updates.
 
-// Iterate for dropdowns/selects
-Object.values(ProductSort);      // ['price_asc', 'price_desc', ...]
-Object.values(OrderStatuses);    // ['PENDING', 'CONFIRMED', ...]
-```
+**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.
 
-### Events
+### [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.
 
-```typescript
-// Listen to SDK 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(`Rate limit: ${remaining} left`));
+**Best for:** SEO-critical pages, checkout, auth forms, sensitive mutations.
+**Upside:** More secure — private API key, better perceived performance, progressive enhancement.
 
-// Unsubscribe
-const unsub = shop.on('error', handler);
-unsub(); // stop listening
-```
+### Recommendation
 
-### Interceptors
-
-```typescript
-// Log every request
-shop.addRequestInterceptor((config) => {
-  console.log(`${config.method} ${config.url}`);
-  return config;
-});
-
-// Log every response
-shop.addResponseInterceptor((response) => {
-  console.log(`Status ${response.status}`);
-});
-
-// Add custom headers
-shop.addRequestInterceptor((config) => {
-  config.headers['X-Custom'] = 'value';
-  return config;
-});
-```
-
-### Auto token refresh
-
-When an authenticated request gets 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 fails too → clears tokens, throws the original error
-
-No code needed — it just works.
+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)
 
 ---
 
-## React / Next.js SDK
+## 1. Setup the provider
 
-### Setup (Next.js App Router)
+Create a client wrapper for the provider:
 
 ```tsx
-// app/providers.tsx — client component wrapper
+// 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!}
-      baseUrl="/api"          // Next.js proxy to avoid CORS
+      apiKey={process.env.NEXT_PUBLIC_BEHIO_API_KEY!}  // e.g. "pk_live_6d3f255..."
+      baseUrl={process.env.NEXT_PUBLIC_BEHIO_API_URL}  // optional — defaults to https://api.behio.com
       locale="cs"
       currency="CZK"
       storage="cookies"       // "cookies" | "localStorage" | "memory"
@@ -361,8 +132,10 @@ export function Providers({ children }: { children: React.ReactNode }) {
 }
 ```
 
+Use it in your root layout (stays as a server component):
+
 ```tsx
-// app/layout.tsx — server component (no "use client" needed)
+// app/layout.tsx
 import { Providers } from './providers';
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
@@ -376,60 +149,78 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-Next.js rewrite in `next.config.ts`:
+Set your env variables:
+
+```bash
+# .env.local
+NEXT_PUBLIC_BEHIO_API_KEY=pk_live_xxxxxxxxxxxx
+NEXT_PUBLIC_BEHIO_API_URL=https://api.behio.com       # production
+# NEXT_PUBLIC_BEHIO_API_URL=http://localhost:7007     # local dev
+
+# For server-side (Server Actions, RSC) — NEVER expose to client
+BEHIO_API_KEY=sk_live_xxxxxxxxxxxx
+BEHIO_API_URL=https://api.behio.com
+```
+
+**Optional:** Hide the backend URL behind a proxy. Add a Next.js rewrite in `next.config.ts` and set `baseUrl="/api"`:
 ```typescript
 async rewrites() {
   return [{ source: '/api/:path*', destination: 'https://api.behio.com/:path*' }];
 }
 ```
 
-### useProducts — Product listing with filters
+## 2. Fetch data with hooks
+
+All catalog data available via React hooks. Each hook returns `{ data, isLoading, error, refetch }`.
 
 ```tsx
 'use client';
-import { useProducts } from '@behio/storefront-sdk/react';
+import { useShopInfo, useProducts, useProduct, useCategories, formatPrice } from '@behio/storefront-sdk/react';
 
-export function ProductGrid() {
-  const { data, isLoading } = useProducts({
-    limit: 24,
-    category: 'electronics',
-    sort: 'newest',
-  });
-
-  if (isLoading) return <div>Loading...</div>;
+export function HomePage() {
+  const { data: shop } = useShopInfo();
+  const { data: products } = useProducts({ limit: 12, sort: 'newest' });
+  const { data: cats } = useCategories();
 
   return (
-    <div className="grid grid-cols-4 gap-4">
-      {data?.items.map(product => (
-        <div key={product.id}>
-          <h3>{product.name}</h3>
-          <p>{product.price.amount} {product.price.currency}</p>
-        </div>
-      ))}
+    <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>
   );
 }
 ```
 
-### useProduct — Product detail with SSR prefetch
+**SSR prefetch** (App Router server components):
 
 ```tsx
-// Server Component — prefetch data
+// app/products/[slug]/page.tsx (server component)
 import { BehioStorefront } from '@behio/storefront-sdk';
 import { ProductDetail } from './ProductDetail';
 
-export default async function ProductPage({ params }: { params: { slug: string } }) {
+export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
   const shop = new BehioStorefront({
     apiKey: process.env.BEHIO_API_KEY!,
     baseUrl: process.env.BEHIO_API_URL,
   });
-  const initialData = await shop.catalog.getProduct(params.slug);
-  return <ProductDetail slug={params.slug} initialData={initialData} />;
+  const initialData = await shop.catalog.getProduct(slug);
+  return <ProductDetail slug={slug} initialData={initialData} />;
 }
 ```
 
 ```tsx
-// Client Component — hydrates with SSR data, then syncs
+// ProductDetail.tsx (client component — hydrates with SSR data)
 'use client';
 import { useProduct } from '@behio/storefront-sdk/react';
 
@@ -439,29 +230,35 @@ export function ProductDetail({ slug, initialData }) {
 }
 ```
 
-### useCart — Full cart management
+→ [All available hooks](#all-react-hooks)
+
+## 3. Cart & checkout
+
+`useCart` gives you everything — state, mutations, computed values, optimistic updates.
 
 ```tsx
 'use client';
-import { useCart, formatPrice } from '@behio/storefront-sdk/react';
+import { useCart, useCartCount, formatPrice } from '@behio/storefront-sdk/react';
 
-export function Cart() {
+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,
-    isAdding, isUpdating,
   } = useCart();
 
   if (isEmpty) return <p>Your cart is empty</p>;
 
   return (
     <div>
-      <h2>Cart ({itemCount})</h2>
       {cart?.items.map(item => (
         <div key={item.id}>
           <span>{item.product.name}</span>
-          <span>{formatPrice(item.unitPrice, cart.currency)}</span>
           <button onClick={() => updateQuantity(item.id, item.quantity - 1)}>-</button>
           <span>{item.quantity}</span>
           <button onClick={() => updateQuantity(item.id, item.quantity + 1)}>+</button>
@@ -474,19 +271,38 @@ export function Cart() {
 }
 ```
 
-### useCartCount — Lightweight badge
+Checkout:
 
 ```tsx
 'use client';
-import { useCartCount } from '@behio/storefront-sdk/react';
+import { useCheckout } from '@behio/storefront-sdk/react';
 
-export function NavCartBadge() {
-  const count = useCartCount();
-  return <span>Cart {count > 0 && `(${count})`}</span>;
+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>
+  );
 }
 ```
 
-### useAuth — Authentication
+→ [Cart session management](#cart-session-management)
+
+## 4. Customer authentication
+
+Register, login, logout — with automatic token persistence and anonymous cart merge.
 
 ```tsx
 'use client';
@@ -497,10 +313,10 @@ export function AuthSection() {
 
   if (isLoggedIn) {
     return (
-      <div>
+      <>
         <p>Welcome, {customer?.firstName || customer?.email}</p>
         <button onClick={logout}>Logout</button>
-      </div>
+      </>
     );
   }
 
@@ -510,63 +326,63 @@ export function AuthSection() {
       const fd = new FormData(e.currentTarget);
       await login(fd.get('email') as string, fd.get('password') as string);
     }}>
-      <input name="email" type="email" placeholder="Email" />
-      <input name="password" type="password" placeholder="Password" />
+      <input name="email" type="email" />
+      <input name="password" type="password" />
       {loginError && <p>{loginError.message}</p>}
-      <button disabled={isLoggingIn}>{isLoggingIn ? 'Logging in...' : 'Login'}</button>
+      <button disabled={isLoggingIn}>Login</button>
     </form>
   );
 }
 ```
 
-### useCheckout — Order creation
+Once logged in, authenticated hooks work automatically:
 
 ```tsx
-'use client';
-import { useCheckout } from '@behio/storefront-sdk/react';
+import { useOrders, useCustomer, useAddresses } from '@behio/storefront-sdk/react';
 
-export function CheckoutForm() {
-  const { createOrder, isCreating, order, reset } = useCheckout();
+const { data: orders } = useOrders();
+const { data: profile, updateProfile } = useCustomer();
+const { addresses, createAddress, deleteAddress } = useAddresses();
+```
 
-  if (order) return <h2>Order #{order.orderNumber} confirmed!</h2>;
+→ [Auto token refresh](#auto-token-refresh)
 
-  return (
-    <form onSubmit={async (e) => {
-      e.preventDefault();
-      await createOrder({ email: '...', shippingAddress: { ... }, billingAddress: { ... } });
-    }}>
-      {/* form fields */}
-      <button disabled={isCreating}>{isCreating ? 'Processing...' : 'Place Order'}</button>
-    </form>
-  );
-}
-```
+<a id="b-server-components--server-actions"></a>
+## 5. Server Components & Server Actions (secure path)
 
-### useSearch — Debounced search
+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
-'use client';
-import { useSearch } from '@behio/storefront-sdk/react';
-import { useState } from 'react';
+// 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
+    baseUrl: process.env.BEHIO_API_URL,
+  });
 
-function SearchBar() {
-  const [query, setQuery] = useState('');
-  const { data, isLoading } = useSearch(query, { debounceMs: 400, limit: 5 });
+  const products = await shop.catalog.getProducts({ limit: 24 });
 
   return (
     <div>
-      <input value={query} onChange={e => setQuery(e.target.value)} placeholder="Search..." />
-      {isLoading && <span>Searching...</span>}
-      {data?.items.map(p => <div key={p.id}>{p.name}</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 + Forms
+**Server Actions — mutations:**
 
 ```tsx
-// app/actions.ts — server actions for checkout, auth, etc.
+// app/actions.ts
 'use server';
 import { BehioStorefront } from '@behio/storefront-sdk';
 import { cookies } from 'next/headers';
@@ -578,23 +394,6 @@ function getShop() {
   });
 }
 
-export async function registerAction(formData: FormData) {
-  const shop = getShop();
-  const result = await shop.auth.register({
-    email: formData.get('email') as string,
-    password: formData.get('password') as string,
-    firstName: formData.get('firstName') as string,
-    lastName: formData.get('lastName') as string,
-  });
-
-  // Store tokens in httpOnly cookies (secure, server-side)
-  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 };
-}
-
 export async function loginAction(_: unknown, formData: FormData) {
   const shop = getShop();
   try {
@@ -604,8 +403,12 @@ export async function loginAction(_: unknown, formData: FormData) {
     });
 
     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 });
+    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) {
@@ -613,64 +416,25 @@ export async function loginAction(_: unknown, formData: FormData) {
   }
 }
 
-export async function checkoutAction(formData: FormData) {
-  const shop = getShop();
-
-  // Restore auth from cookies
-  const cookieStore = await cookies();
-  const accessToken = cookieStore.get('behio_access')?.value;
-  const cartSession = cookieStore.get('behio_cart_session')?.value;
-  if (accessToken) shop.setTokens({ accessToken, refreshToken: '' });
-  if (cartSession) shop.setCartSession(cartSession);
-
-  const order = await shop.checkout.createOrder({
-    email: formData.get('email') as string,
-    phone: formData.get('phone') as string || undefined,
-    customerNote: formData.get('note') as string || undefined,
-    shippingAddress: {
-      firstName: formData.get('shipping_firstName') as string,
-      lastName: formData.get('shipping_lastName') as string,
-      street: formData.get('shipping_street') as string,
-      city: formData.get('shipping_city') as string,
-      zip: formData.get('shipping_zip') as string,
-      country: formData.get('shipping_country') as string,
-    },
-    billingAddress: {
-      firstName: formData.get('billing_firstName') as string,
-      lastName: formData.get('billing_lastName') as string,
-      street: formData.get('billing_street') as string,
-      city: formData.get('billing_city') as string,
-      zip: formData.get('billing_zip') as string,
-      country: formData.get('billing_country') as string,
-    },
-  });
-
-  // Clear cart cookie
-  cookieStore.delete('behio_cart_session');
-
-  return { orderNumber: order.orderNumber, trackingToken: order.trackingToken };
-}
-
-export async function addToCartAction(productId: string, quantity: number = 1) {
+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 });
 
-  // Save session token to cookie
   if (result.newSessionToken) {
-    cookieStore.set('behio_cart_session', result.newSessionToken, { sameSite: 'lax', maxAge: 30 * 86400 });
+    cookieStore.set('behio_cart_session', result.newSessionToken, {
+      sameSite: 'lax', maxAge: 30 * 86400,
+    });
   }
-
   return result;
 }
 ```
 
 ```tsx
-// app/auth/page.tsx — Login form with useActionState
+// app/auth/page.tsx
 'use client';
 import { useActionState } from 'react';
 import { loginAction } from '../actions';
@@ -678,297 +442,485 @@ import { loginAction } from '../actions';
 export default function LoginPage() {
   const [state, formAction, isPending] = useActionState(loginAction, { success: false, error: null });
 
-  if (state.success) return <p>Logged in! Redirecting...</p>;
-
   return (
     <form action={formAction}>
       <input name="email" type="email" placeholder="Email" required />
       <input name="password" type="password" placeholder="Password" required />
-      {state.error && <p className="text-red-500">{state.error}</p>}
+      {state.error && <p>{state.error}</p>}
       <button disabled={isPending}>{isPending ? 'Logging in...' : 'Login'}</button>
     </form>
   );
 }
 ```
 
-```tsx
-// app/register/page.tsx — Register with progressive enhancement
-import { registerAction } from '../actions';
-import { redirect } from 'next/navigation';
-
-export default function RegisterPage() {
-  async function handleRegister(formData: FormData) {
-    'use server';
-    await registerAction(formData);
-    redirect('/account');
-  }
+---
 
-  return (
-    <form action={handleRegister}>
-      <input name="firstName" placeholder="First name" />
-      <input name="lastName" placeholder="Last name" />
-      <input name="email" type="email" placeholder="Email" required />
-      <input name="password" type="password" placeholder="Password" required />
-      <button type="submit">Create Account</button>
-    </form>
-  );
-}
-```
+# 🛠 Vanilla JS / Node.js path
 
-```tsx
-// app/products/[slug]/page.tsx — Add to cart with server action
-import { BehioStorefront } from '@behio/storefront-sdk';
-import { addToCartAction } from '../../actions';
-import { formatPrice } from '@behio/storefront-sdk/react';
+For Node.js backends, serverless functions, CLI tools, Deno, Bun, or any non-React JavaScript environment.
 
-export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
-  const { slug } = await params;
-  const shop = new BehioStorefront({ apiKey: process.env.BEHIO_API_KEY!, baseUrl: process.env.BEHIO_API_URL });
-  const product = await shop.catalog.getProduct(slug);
+## 1. Create a client
 
-  return (
-    <div>
-      <h1>{product.name}</h1>
-      <p>{product.longDescription}</p>
-      <p className="text-2xl font-bold">{formatPrice(product.price.amount, product.price.currency)}</p>
-
-      {product.price.compareAtPrice && (
-        <p className="line-through text-gray-500">
-          {formatPrice(product.price.compareAtPrice, product.price.currency)}
-        </p>
-      )}
-
-      <form action={async () => {
-        'use server';
-        await addToCartAction(product.id);
-      }}>
-        <button type="submit" disabled={!product.inStock}>
-          {product.inStock ? 'Add to Cart' : 'Out of Stock'}
-        </button>
-      </form>
-
-      {product.volumePricing.length > 0 && (
-        <table>
-          <thead><tr><th>Quantity</th><th>Price</th></tr></thead>
-          <tbody>
-            {product.volumePricing.map(vp => (
-              <tr key={vp.minQuantity}>
-                <td>{vp.minQuantity}+</td>
-                <td>{formatPrice(vp.price, product.price.currency)}</td>
-              </tr>
-            ))}
-          </tbody>
-        </table>
-      )}
-    </div>
-  );
-}
+```typescript
+import { BehioStorefront } from '@behio/storefront-sdk';
+
+const shop = new BehioStorefront({
+  apiKey: 'pk_live_xxx',
+  baseUrl: 'https://api.behio.com',  // optional
+  locale: 'cs',                       // optional
+  currency: 'CZK',                    // optional
+  timeout: 30000,                     // optional — request timeout (ms)
+  retries: 1,                         // optional — retry failed requests
+});
 ```
 
-```tsx
-// app/checkout/page.tsx — Full checkout form with server action
-import { checkoutAction } from '../actions';
-import { redirect } from 'next/navigation';
-
-export default function CheckoutPage() {
-  async function handleCheckout(formData: FormData) {
-    'use server';
-    const result = await checkoutAction(formData);
-    redirect(`/orders/confirmation?order=${result.orderNumber}`);
-  }
+## 2. Call any endpoint
 
-  return (
-    <form action={handleCheckout}>
-      <h2>Contact</h2>
-      <input name="email" type="email" placeholder="Email" required />
-      <input name="phone" type="tel" placeholder="Phone" />
-
-      <h2>Shipping Address</h2>
-      <input name="shipping_firstName" placeholder="First name" required />
-      <input name="shipping_lastName" placeholder="Last name" required />
-      <input name="shipping_street" placeholder="Street" required />
-      <div style={{ display: 'flex', gap: 8 }}>
-        <input name="shipping_city" placeholder="City" required />
-        <input name="shipping_zip" placeholder="ZIP" required />
-      </div>
-      <input name="shipping_country" placeholder="Country code (CZ)" defaultValue="CZ" required />
-
-      <h2>Billing Address</h2>
-      <input name="billing_firstName" placeholder="First name" required />
-      <input name="billing_lastName" placeholder="Last name" required />
-      <input name="billing_street" placeholder="Street" required />
-      <div style={{ display: 'flex', gap: 8 }}>
-        <input name="billing_city" placeholder="City" required />
-        <input name="billing_zip" placeholder="ZIP" required />
-      </div>
-      <input name="billing_country" placeholder="Country code (CZ)" defaultValue="CZ" required />
+Every API method returns a Promise. Types are fully auto-completed.
 
-      <textarea name="note" placeholder="Order note (optional)" />
+```typescript
+// Catalog
+const products = await shop.catalog.getProducts({ limit: 20, sort: 'newest' });
+const product = await shop.catalog.getProduct('my-product-slug');
+const { categories } = await shop.catalog.getCategories();
 
-      <button type="submit">Place Order</button>
-    </form>
-  );
-}
+// Auth
+const tokens = await shop.auth.register({ email: '...', password: '...' });
+await shop.auth.login({ email: '...', password: '...' });
+
+// Cart
+await shop.cart.addItem({ productId: 'xxx', quantity: 2 });
+const cart = await shop.cart.get();
+await shop.cart.applyDiscount('SAVE20');
+
+// Checkout
+const order = await shop.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 hooks
+→ [All API methods](#all-api-methods)
 
-| Hook | Purpose | Auth |
-|------|---------|------|
-| `useShopInfo()` | E-shop info | No |
-| `useProducts(query?)` | Product list with filters | No |
-| `useProduct(slug)` | Product detail | No |
-| `useCategories(locale?)` | Category tree | No |
-| `useLabels(locale?)` | Labels/tags | No |
-| `useFeatured()` | Featured products | No |
-| `useFilters()` | Dynamic filter fields | No |
-| `useSearch(query)` | Debounced search | No |
-| `useCart()` | Cart state + actions | No |
-| `useCartCount()` | Item count (lightweight) | No |
-| `useAuth()` | Login, register, logout | No |
-| `useCheckout()` | Create order | No* |
-| `useOrders()` | Order list | Yes |
-| `useOrder(num)` | Order detail + cancel | Yes |
-| `useCustomer()` | Profile + update | Yes |
-| `useAddresses()` | Address CRUD | Yes |
-| `usePages()` / `usePage(slug)` | CMS pages | No |
+---
+
+# 📖 Reference
+
+## All React hooks
+
+| Hook | Purpose | Auth required |
+|------|---------|---------------|
+| [`useShopInfo()`](#useshopinfo) | E-shop info (name, currencies, languages) | 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 |
+
+\* Guest checkout works without auth if the e-shop allows it.
+
+### useShopInfo
+```typescript
+const { data, isLoading, error } = useShopInfo();
+// data: ShopInfo
+```
 
-\* Guest checkout works without auth if e-shop allows it.
+### useProducts
+```typescript
+const { data, isLoading, error } = useProducts({
+  page: 1,
+  limit: 24,
+  category: 'electronics',
+  label: 'new',
+  priceMin: 100,
+  priceMax: 5000,
+  sort: 'price_asc',
+  inStock: true,
+  search: 'keyboard',
+  customFields: { material: 'aluminum' },
+});
+// data: PaginatedResponse<ProductListItem>
+```
 
-### formatPrice
+### useProduct
+```typescript
+const { data, isLoading, error } = useProduct('product-slug', {
+  locale: 'cs',
+  currency: 'CZK',
+  initialData: prefetchedData,  // for SSR hydration
+});
+// data: ProductDetail
+```
 
+### useCategories
 ```typescript
-import { formatPrice } from '@behio/storefront-sdk/react';
+const { data, isLoading } = useCategories('cs');
+// data: Category[]  (tree structure with children)
+```
 
-formatPrice(1499, 'CZK');          // "1 499,00 Kč"
-formatPrice(24.99, 'EUR');          // "24,99 €"
-formatPrice(1499, 'CZK', 'en');    // "CZK 1,499.00"
+### useLabels
+```typescript
+const { data } = useLabels('cs');
+// data: ProductLabel[]
 ```
 
----
+### useFeatured
+```typescript
+const { data } = useFeatured();
+// data: PaginatedResponse<ProductListItem>
+```
 
-## How it works
+### useFilters
+```typescript
+const { data } = useFilters();
+// data: FilterField[] — use to build dynamic filter UI
+```
 
-- **Auth**: API key in `X-Api-Key` header identifies your e-shop. Customer JWT in `Authorization` header identifies the logged-in customer.
-- **Cart sessions**: Anonymous carts use `X-Cart-Session` header. Session token auto-managed by SDK.
-- **Token refresh**: 401 → automatic refresh → retry. Transparent to your code.
-- **Cart merge**: After login, anonymous cart automatically merged into customer cart.
-- **React Query**: All hooks use TanStack Query — caching, deduplication, background refetch.
-- **Optimistic updates**: Cart remove/update reflected instantly, rollback on error.
-- **SSR**: Pass `initialData` to hooks for server-prefetched data.
-- **Storage**: Auth tokens + cart session persisted to cookies/localStorage (configurable).
+### 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
+```
 
-## API Reference (for AI agents)
+### 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();
+```
 
-### Package exports
+### useOrders
+```typescript
+const { data, isLoading } = useOrders({ page: 1, limit: 10 });
+// data: PaginatedResponse<OrderListItem>
 ```
-@behio/storefront-sdk          → BehioStorefront, types, BehioApiError, BehioNetworkError
-@behio/storefront-sdk/react    → BehioProvider, all hooks, formatPrice
+
+### useOrder
+```typescript
+const { data, cancel, isCancelling } = useOrder('ORD-123');
+// data: OrderDetail
 ```
 
-### Constructor
+### useCustomer
 ```typescript
-new BehioStorefront({ apiKey, baseUrl?, locale?, currency?, timeout?, retries?, retryDelay?, fetch? })
+const { data, updateProfile, isUpdating } = useCustomer();
+// data: CustomerProfile
 ```
 
-### Instance methods
+### useAddresses
+```typescript
+const {
+  addresses,
+  createAddress, updateAddress, deleteAddress,
+  isCreating, isDeleting,
+} = useAddresses();
 ```
-shop.getShopInfo() → ShopInfo
-shop.setTokens({ accessToken, refreshToken }) / shop.clearTokens()
-shop.setCartSession(token) / shop.getCartSession() / shop.clearCartSession()
-shop.on(event, handler) → unsubscribe fn
-shop.addRequestInterceptor(fn) → unsubscribe fn
-shop.addResponseInterceptor(fn) → unsubscribe fn
-shop.getRateLimitInfo() → { remaining, reset }
+
+### usePages
+```typescript
+const { data: pages } = usePages('cs');
+const { data: page } = usePage('about-us', 'cs');
 ```
 
-### Sub-modules
+## All API methods
+
+### 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.getProducts(query?) → PaginatedResponse<ProductListItem>
-shop.catalog.getProduct(slug) → ProductDetail
-shop.catalog.getCategories(locale?) → { categories: Category[] }
-shop.catalog.getCategory(slug) → CategoryDetail
-shop.catalog.getCategoryProducts(slug, query?) → 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.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
+### 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
+```
 
-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
+### 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
+```
 
-shop.checkout.createOrder(input) → OrderDetail
+### Checkout
+```typescript
+shop.checkout.createOrder(input)             → OrderDetail
+```
 
-shop.orders.list(opts?) → PaginatedResponse<OrderListItem>
-shop.orders.get(orderNumber) → OrderDetail
-shop.orders.cancel(orderNumber) → OrderDetail
-shop.orders.track(trackingToken) → OrderDetail
+### 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
+```
 
-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
+### 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
+```
 
-shop.pages.list(locale?) → { pages: Page[] }
-shop.pages.get(slug, locale?) → PageDetail
+### Pages
+```typescript
+shop.pages.list(locale?)                     → { pages: Page[] }
+shop.pages.get(slug, locale?)                → PageDetail
 ```
 
-### Key types
+### Instance utilities
+```typescript
+shop.getShopInfo()                           → ShopInfo
+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 }
+```
+
+## Types
+
 ```typescript
-ProductListItem { id, slug, name, shortDescription?, sku, gtin?, price: ProductPrice, inStock, stockQuantity?, image?, labels[], isFeatured }
-ProductDetail extends ProductListItem { longDescription?, images[], categories[], variants[], volumePricing[], customFields, seo, weight?, weightUnit? }
+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[], addresses, totals, statusHistory[], trackingToken? }
-CustomerProfile { id, email, firstName?, lastName?, phone?, emailVerified }
-BehioApiError { status, code: BehioErrorCode, body, message, isRetryable, is(code) }
-BehioNetworkError { code: 'NETWORK_ERROR' | 'TIMEOUT', isRetryable }
+
+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
+}
 ```
 
-### Const enums (runtime + type-safe)
+## Constants / Enums
+
+Type-safe constants for common values — autocomplete, iterable, zero runtime cost.
+
 ```typescript
-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 }
+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', ...]
 ```
 
-### React Provider props
+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
-BehioProviderProps {
-  apiKey: string,
-  baseUrl?: string,
-  locale?: string,
-  currency?: string,
-  storage?: 'cookies' | 'localStorage' | 'memory' | StorageAdapter,
-  children: ReactNode,
+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
+  }
 }
 ```
 
-### React Query keys
+**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]
@@ -986,34 +938,6 @@ BehioProviderProps {
 ['behio', 'page', slug, locale?]
 ```
 
-### 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'
-```
-
----
-
-## Next.js full example
-
-```
-app/
-├── layout.tsx              ← BehioProvider
-├── page.tsx                ← useShopInfo + useFeatured
-├── products/
-│   ├── page.tsx            ← useProducts
-│   └── [slug]/page.tsx     ← useProduct (SSR prefetch)
-├── cart/page.tsx            ← useCart
-├── checkout/page.tsx        ← useCheckout
-├── auth/page.tsx            ← useAuth
-├── account/
-│   ├── page.tsx            ← useCustomer
-│   ├── orders/page.tsx     ← useOrders
-│   └── addresses/page.tsx  ← useAddresses
-└── [slug]/page.tsx          ← usePage (CMS)
-```
-
 ## License
 
 MIT