@behio/storefront-sdk 0.1.0

package/README.md

@@ -0,0 +1,999 @@
+# @behio/storefront-sdk
+
+TypeScript SDK for **Behio Headless E-Shop** — Storefront API client + React/Next.js hooks.
+
+```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';
+```
+
+---
+
+## Core SDK
+
+### Setup
+
+```typescript
+import { BehioStorefront } from '@behio/storefront-sdk';
+
+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
+
+```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');
+
+// Cancel (only PENDING orders)
+await shop.orders.cancel('ORD-123');
+
+// Track by token (no auth needed — shareable link)
+const order = await shop.orders.track('tracking-token-uuid');
+```
+
+### Customer Profile
+
+```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
+
+```typescript
+const { pages } = await shop.pages.list('cs');
+const about = await shop.pages.get('about-us', 'cs');
+// → { slug, title, content (JSON), seoTitle, seoDescription }
+```
+
+### 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;        // 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
+  }
+}
+```
+
+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:
+
+```typescript
+import {
+  ProductSort,
+  OrderStatuses,
+  PaymentStatuses,
+  FulfillmentStatuses,
+  AddressTypes,
+} from '@behio/storefront-sdk';
+
+// Product sorting
+shop.catalog.getProducts({ sort: ProductSort.PRICE_ASC });
+// ProductSort.PRICE_ASC | PRICE_DESC | NAME_ASC | NAME_DESC | NEWEST | FEATURED
+
+// Order status checks
+if (order.status === OrderStatuses.SHIPPED) { ... }
+// OrderStatuses.PENDING | CONFIRMED | PROCESSING | SHIPPED | DELIVERED | CANCELLED | REFUNDED
+
+// Payment status
+if (order.paymentStatus === PaymentStatuses.PAID) { ... }
+
+// Fulfillment
+if (order.fulfillmentStatus === FulfillmentStatuses.FULFILLED) { ... }
+
+// Address types
+shop.customer.createAddress({ type: AddressTypes.SHIPPING, ... });
+
+// Iterate for dropdowns/selects
+Object.values(ProductSort);      // ['price_asc', 'price_desc', ...]
+Object.values(OrderStatuses);    // ['PENDING', 'CONFIRMED', ...]
+```
+
+### Events
+
+```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`));
+
+// Unsubscribe
+const unsub = shop.on('error', handler);
+unsub(); // stop listening
+```
+
+### 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.
+
+---
+
+## React / Next.js SDK
+
+### Setup (Next.js App Router)
+
+```tsx
+// app/providers.tsx — client component wrapper
+'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
+      locale="cs"
+      currency="CZK"
+      storage="cookies"       // "cookies" | "localStorage" | "memory"
+    >
+      {children}
+    </BehioProvider>
+  );
+}
+```
+
+```tsx
+// app/layout.tsx — server component (no "use client" needed)
+import { Providers } from './providers';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+Next.js rewrite in `next.config.ts`:
+```typescript
+async rewrites() {
+  return [{ source: '/api/:path*', destination: 'https://api.behio.com/:path*' }];
+}
+```
+
+### useProducts — Product listing with filters
+
+```tsx
+'use client';
+import { useProducts } from '@behio/storefront-sdk/react';
+
+export function ProductGrid() {
+  const { data, isLoading } = useProducts({
+    limit: 24,
+    category: 'electronics',
+    sort: 'newest',
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+
+  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>
+  );
+}
+```
+
+### useProduct — Product detail with SSR prefetch
+
+```tsx
+// Server Component — prefetch data
+import { BehioStorefront } from '@behio/storefront-sdk';
+import { ProductDetail } from './ProductDetail';
+
+export default async function ProductPage({ params }: { params: { slug: string } }) {
+  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} />;
+}
+```
+
+```tsx
+// Client Component — hydrates with SSR data, then syncs
+'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>;
+}
+```
+
+### useCart — Full cart management
+
+```tsx
+'use client';
+import { useCart, formatPrice } from '@behio/storefront-sdk/react';
+
+export function Cart() {
+  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>
+          <button onClick={() => removeItem(item.id)}>Remove</button>
+        </div>
+      ))}
+      <p>Total: {formatPrice(cart?.grandTotal ?? 0, cart?.currency ?? 'CZK')}</p>
+    </div>
+  );
+}
+```
+
+### useCartCount — Lightweight badge
+
+```tsx
+'use client';
+import { useCartCount } from '@behio/storefront-sdk/react';
+
+export function NavCartBadge() {
+  const count = useCartCount();
+  return <span>Cart {count > 0 && `(${count})`}</span>;
+}
+```
+
+### useAuth — Authentication
+
+```tsx
+'use client';
+import { useAuth } from '@behio/storefront-sdk/react';
+
+export function AuthSection() {
+  const { isLoggedIn, customer, login, logout, isLoggingIn, loginError } = useAuth();
+
+  if (isLoggedIn) {
+    return (
+      <div>
+        <p>Welcome, {customer?.firstName || customer?.email}</p>
+        <button onClick={logout}>Logout</button>
+      </div>
+    );
+  }
+
+  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" placeholder="Email" />
+      <input name="password" type="password" placeholder="Password" />
+      {loginError && <p>{loginError.message}</p>}
+      <button disabled={isLoggingIn}>{isLoggingIn ? 'Logging in...' : 'Login'}</button>
+    </form>
+  );
+}
+```
+
+### useCheckout — Order creation
+
+```tsx
+'use client';
+import { useCheckout } from '@behio/storefront-sdk/react';
+
+export function CheckoutForm() {
+  const { createOrder, isCreating, order, reset } = useCheckout();
+
+  if (order) return <h2>Order #{order.orderNumber} confirmed!</h2>;
+
+  return (
+    <form onSubmit={async (e) => {
+      e.preventDefault();
+      await createOrder({ email: '...', shippingAddress: { ... }, billingAddress: { ... } });
+    }}>
+      {/* form fields */}
+      <button disabled={isCreating}>{isCreating ? 'Processing...' : 'Place Order'}</button>
+    </form>
+  );
+}
+```
+
+### useSearch — Debounced search
+
+```tsx
+'use client';
+import { useSearch } from '@behio/storefront-sdk/react';
+import { useState } from 'react';
+
+function SearchBar() {
+  const [query, setQuery] = useState('');
+  const { data, isLoading } = useSearch(query, { debounceMs: 400, limit: 5 });
+
+  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>)}
+    </div>
+  );
+}
+```
+
+### Server Actions + Forms
+
+```tsx
+// app/actions.ts — server actions for checkout, auth, etc.
+'use server';
+import { BehioStorefront } from '@behio/storefront-sdk';
+import { cookies } from 'next/headers';
+
+function getShop() {
+  return new BehioStorefront({
+    apiKey: process.env.BEHIO_API_KEY!,
+    baseUrl: process.env.BEHIO_API_URL,
+  });
+}
+
+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 {
+    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 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) {
+  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 });
+  }
+
+  return result;
+}
+```
+
+```tsx
+// app/auth/page.tsx — Login form with useActionState
+'use client';
+import { useActionState } from 'react';
+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>}
+      <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>
+  );
+}
+```
+
+```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';
+
+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);
+
+  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>
+  );
+}
+```
+
+```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}`);
+  }
+
+  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 />
+
+      <textarea name="note" placeholder="Order note (optional)" />
+
+      <button type="submit">Place Order</button>
+    </form>
+  );
+}
+```
+
+### All hooks
+
+| 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 |
+
+\* Guest checkout works without auth if e-shop allows it.
+
+### formatPrice
+
+```typescript
+import { formatPrice } from '@behio/storefront-sdk/react';
+
+formatPrice(1499, 'CZK');          // "1 499,00 Kč"
+formatPrice(24.99, 'EUR');          // "24,99 €"
+formatPrice(1499, 'CZK', 'en');    // "CZK 1,499.00"
+```
+
+---
+
+## How it works
+
+- **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).
+
+---
+
+## API Reference (for AI agents)
+
+### Package exports
+```
+@behio/storefront-sdk          → BehioStorefront, types, BehioApiError, BehioNetworkError
+@behio/storefront-sdk/react    → BehioProvider, all hooks, formatPrice
+```
+
+### Constructor
+```typescript
+new BehioStorefront({ apiKey, baseUrl?, locale?, currency?, timeout?, retries?, retryDelay?, fetch? })
+```
+
+### Instance methods
+```
+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 }
+```
+
+### Sub-modules
+```
+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
+
+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
+
+shop.orders.list(opts?) → PaginatedResponse<OrderListItem>
+shop.orders.get(orderNumber) → OrderDetail
+shop.orders.cancel(orderNumber) → OrderDetail
+shop.orders.track(trackingToken) → OrderDetail
+
+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
+```
+
+### Key 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? }
+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 }
+```
+
+### Const enums (runtime + type-safe)
+```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 }
+```
+
+### React Provider props
+```typescript
+BehioProviderProps {
+  apiKey: string,
+  baseUrl?: string,
+  locale?: string,
+  currency?: string,
+  storage?: 'cookies' | 'localStorage' | 'memory' | StorageAdapter,
+  children: ReactNode,
+}
+```
+
+### React Query keys
+```
+['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?]
+```
+
+### 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