\n );\n}\n```\n\n---\n\n## API\n\n### `CartProvider`\n\n| Prop | Type | Default | Description |\n|---------------------|----------|-----------|--------------------------------------------------|\n| `tenantId` | `string` | required | Tenant/store id. Cart is stored per tenant. |\n| `storageKeyPrefix` | `string` | `\"cart\"` | Prefix for localStorage key (local-only mode). |\n| `children` | `ReactNode` | required | Your app or subtree. |\n| `apiBaseUrl` | `string` | — | When set, enables **API mode** (see below). |\n| `storeId` | `string` | — | Required when `apiBaseUrl` is set. |\n| `getHeaders` | `() => Record` | — | Optional. Return headers for each request (e.g. `{ \"X-User-Id\": userId }` for logged-in users). |\n\n### `useCart()`\n\nReturns:\n\n| Property | Type | Description |\n|-----------------|-------------------------|-------------|\n| `items` | `CartItem[]` | Current line items. |\n| `summary` | `CartSummary` | `{ subtotal, total, itemCount }`. |\n| `tenantId` | `string` | Current tenant id. |\n| `isEmpty` | `boolean` | `items.length === 0`. |\n| `addItem` | `(item, quantity?) => void` | Add or merge by `id`. |\n| `removeItem` | `(id) => void` | Remove line by `id`. |\n| `updateQuantity`| `(id, quantity) => void`| Set quantity; remove if ≤ 0. |\n| `clearCart` | `() => void` | Remove all items. |\n| `isSyncing` | `boolean` | **API mode only.** True while loading or mutating. |\n| `lastError` | `Error \\| null` | **API mode only.** Last API error, clear on next success. |\n| `mergeGuestCart`| `() => Promise` | **API mode only.** Call after login to merge guest cart into user cart. |\n\n### `useCheckout()`\n\n**API mode only.** Returns:\n\n| Property | Type | Description |\n|-----------------|-------------------------|-------------|\n| `startCheckout` | `(body?) => Promise` | `POST /checkout/?tenant_id&store_id` (query when set); empty body unless you pass a JSON `body`. |\n| `isPending` | `boolean` | True while checkout request is in flight. |\n| `error` | `Error \\| null` | Checkout request error. |\n| `result` | `CheckoutResponse \\| null` | Last successful response (`checkout_url`, `order_id`, etc.). |\n\n### Types\n\n- **`CartItem`** — `id` (string or number), optional `name`, `price`, `quantity` (defaults to 1 when adding), and any extra fields.\n- **`CartSummary`** — `{ subtotal, total, itemCount }`.\n- **`CheckoutResponse`** — Typed response from checkout (e.g. `checkout_url`, `order_id`). Import when using `useCheckout`.\n- **`CartContextValue`** — Full context type if you need it.\n\n```ts\nimport type { CartItem, CartSummary, CheckoutResponse } from \"@ecommerce-store/cart-checkout-plugin\";\n```\n\n---\n\n## API mode (backend sync)\n\nWhen you pass `apiBaseUrl` and `storeId`, the plugin switches to **API mode**:\n\n- **Guest session:** The plugin calls `POST /cart/guest/session` to get a guest cart id, stores it in localStorage (key `cart_guest_id:{tenantId}:{storeId}`), and sends it as the `X-Guest-Cart-Id` header on all cart requests.\n- **Logged-in users:** Provide `getHeaders={() => ({ \"X-User-Id\": currentUserId })}`. The plugin sends `X-User-Id` instead of (or with) the guest id. After login, call **`mergeGuestCart()`** so the backend merges the guest cart into the user cart; the plugin then stops using the stored guest id and refetches the cart.\n- **Endpoints used:** `GET /cart/view`, `POST /cart/add`, `PUT /cart/item/{item_id}`, `DELETE /cart/item/{item_id}`, `DELETE /cart/clear?tenant_id&store_id`, `POST /cart/merge-guest-cart`, `POST /checkout/?tenant_id&store_id` (checkout body empty by default). Request bodies and query params use `tenant_id` and `store_id` as required by your API.\n\nExample:\n\n```jsx\n (user ? { \"X-User-Id\": user.id } : {})}\n>\n \n\n\n// After user logs in:\nconst { mergeGuestCart } = useCart();\nawait mergeGuestCart();\n\n// Checkout:\nconst { startCheckout, isPending, result } = useCheckout();\nconst res = await startCheckout();\nif (res?.checkout_url) window.location.href = res.checkout_url;\n```\n\n---\n\n## Multi-tenant behavior\n\n- **Local-only mode:** Each `tenantId` gets its own cart in localStorage under the key `{storageKeyPrefix}:{tenantId}`. Persistence runs only after hydration so the cart is not overwritten on first paint.\n- **API mode:** Cart is stored on the server. Guest cart id is stored per tenant+store and reused across refreshes. Use `mergeGuestCart()` after login to merge guest cart into the user cart.\n\n---\n\n## Building from source\n\n```bash\nnpm install\nnpm run build\n```\n\nOutput is in `dist/`: ESM and CJS bundles plus TypeScript declarations.\n","readmeFilename":"README.md"}