@managesales/storefront 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to `@managesales/storefront`. This project adheres to
+[Semantic Versioning](https://semver.org).
+
+## 1.1.0 — 2026-07-11
+
+### Added
+- **Stateful cart** — `client.cart.create()` / `client.cart.current()` return a `StorefrontCart` with
+  `addLineItem` (auto-enriches price/name from `products.get`, merges duplicate product+variant
+  lines), `updateLineItem`, `removeLineItem`, `clear`, and `checkout()` to materialize the cart
+  straight into a checkout session. Persisted to `localStorage` by default (`persistCart: false` to
+  opt out); safe to import under SSR/Node with no DOM. `client.cart.recover(token)` is unchanged.
+- **`orders` and `customers` alias namespaces** — `client.orders.list()` and
+  `client.customers.{login,register,loginWithGoogle,logout,isAuthenticated,setTokens,me,orders,addresses}`
+  are convenience references onto the existing `auth`/`customer` methods (no duplicated logic, no new
+  backend calls).
+- **Configurable request retries** — network errors and 5xx/408/425/429 responses on idempotent
+  (`GET`/`HEAD`) requests are now retried automatically with exponential backoff, honoring a
+  `Retry-After` response header as a delay floor. Configure via
+  `createStorefrontClient({ retry: { retries, baseDelayMs, maxDelayMs, retryOnStatus } })`, or pass
+  `retry: false` to disable. Non-idempotent requests (`POST`/`PUT`/`PATCH`/`DELETE`) are never
+  retried once a response is received from the server; a network failure that never reached the
+  server (e.g. `fetch` throwing) is retried regardless of method, since no side effect could have
+  occurred yet.
+
+### Fixed
+- `checkout.create` now sends line items under the `lines` key (matching the `/checkout` endpoint's
+  actual request shape) instead of `items`. Note this only corrects the request envelope — direct
+  callers must still supply every field the backend requires (see next item).
+- `CheckoutLineItem` now includes the backend-required `productName` (string) and `unitPrice`
+  (number) fields, plus optional `imageUrl`. The previous `{ productId, variantId?, quantity }`
+  shape type-checked but was always rejected by the real `/checkout` endpoint's validation for
+  direct `client.checkout.create()` callers; `cart.checkout()` was unaffected since `CartLine`
+  already carried both fields. Callers who don't want to supply `productName`/`unitPrice` by hand
+  should use the stateful cart (`cart.addLineItem`), which auto-enriches them from `products.get`.
+
+## 1.0.2 — 2026-07-11
+
+### Docs
+- Rewrote the README as a full developer landing page: human-readable title and tagline, feature
+  overview, all-package-manager install, a copy-paste quick start, a complete **API organization**
+  reference, framework examples (React / Next.js / Node.js), server-side auth (SSR) guide, error
+  handling, TypeScript guide, a **Versioning** policy, and this changelog.
+
+## 1.0.1 — 2026-07-11
+
+### Docs
+- Expanded the README with per-resource examples and browser/Node runtime support notes.
+
+## 1.0.0 — 2026-07-11
+
+### Added
+- Initial public release. Resource-based Storefront SDK with namespaces for products, collections,
+  checkout, cart recovery, auth, customer, blog, bookings, and forms.
+- Built-in customer auth with automatic access-token refresh on `401`.
+- `StorefrontError` class exposing `status`, `code`, `message`, and `details`.
+- Dual ESM + CommonJS builds with bundled TypeScript declarations. Zero runtime dependencies.

package/README.md

@@ -1,84 +1,116 @@
-# @managesales/storefront
+# ManageSales Storefront SDK
+
+**Build custom storefronts on top of the ManageSales Commerce Platform.**
 
 [![npm version](https://img.shields.io/npm/v/@managesales/storefront.svg)](https://www.npmjs.com/package/@managesales/storefront)
 [![license](https://img.shields.io/npm/l/@managesales/storefront.svg)](./LICENSE)
 [![types](https://img.shields.io/npm/types/@managesales/storefront.svg)](#typescript-support)
 [![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#browser--node-support)
 
-Resource-based TypeScript client for building online storefronts on the **ManageSales Storefront
-API** — think Shopify's Storefront API client, for ManageSales. Browse products, run checkout, and
-manage customer accounts with a typed, ergonomic client instead of hand-rolled `fetch` calls.
+`@managesales/storefront` is a typed, resource-based client for the ManageSales Storefront API —
+like Shopify's Storefront client, for ManageSales. Everything you need to ship a storefront:
 
-- 🧩 **Resource namespaces** — `client.products`, `client.checkout`, `client.customer`, …
-- 🔐 **Auth built in** — customer login + automatic access-token refresh
-- 📦 **Zero runtime dependencies** — one small file, uses the platform `fetch`
-- 🟦 **Fully typed** — ships `.d.ts`; responses and params are typed end to end
-- 🌐 **Runs everywhere** — dual ESM + CommonJS, browser / Node 18+ / Deno / Bun / edge
+- 🛍️ **Products** — list, search, and fetch details
+- 🗂️ **Collections** — browse categories and their products
+- 👤 **Customers** — registration, login, profile, order history
+- 🛒 **Checkout** — line items, coupons, complete purchases (+ abandoned-cart recovery)
+- 🔎 **Search** — full-text product search
+- 🟦 **TypeScript** — first-class types, no `@types` needed
+- ⚡ **SSR-ready** — inject a custom `fetch`; server-side auth pattern built in
+- 📦 **Zero dependencies** — one small file, dual ESM + CommonJS
 
 ---
 
 ## Table of contents
 
-- [What is this?](#what-is-this)
 - [Installation](#installation)
-- [Quick start](#quick-start-30-seconds)
+- [Quick start](#quick-start)
+- [API organization](#api-organization)
 - [Create a client](#create-a-client)
-- [Products](#products)
+- [Products & search](#products--search)
 - [Collections](#collections)
 - [Cart & checkout](#cart--checkout)
+- [Stateful cart](#stateful-cart)
 - [Authentication](#authentication)
 - [Customer account](#customer-account)
+- [Retries](#retries)
 - [Error handling](#error-handling)
-- [More resources](#more-resources)
 - [TypeScript support](#typescript-support)
+- [Framework examples](#framework-examples)
 - [Browser & Node support](#browser--node-support)
+- [Versioning](#versioning)
+- [Changelog](#changelog)
 - [No-npm alternative](#no-npm-alternative)
 - [License](#license)
 
----
-
-## What is this?
-
-`@managesales/storefront` is the official client SDK for the **ManageSales Storefront API** — the
-public, customer-facing API behind a ManageSales store. Use it to build a custom storefront
-(product pages, search, cart, checkout, customer login) in any JavaScript/TypeScript framework,
-while the SDK handles request headers, workspace scoping, error parsing, pagination, and token
-refresh for you.
-
-It talks to the same API you can also reach directly over HTTP (`/storefront-api/*`) — the SDK is
-just the typed, batteries-included way to do it.
-
 ## Installation
 
 ```bash
 npm install @managesales/storefront
-# pnpm add @managesales/storefront
-# yarn add @managesales/storefront
-# bun add @managesales/storefront
+pnpm add @managesales/storefront
+yarn add @managesales/storefront
+bun add @managesales/storefront
 ```
 
-## Quick start (30 seconds)
+## Quick start
+
+Copy-paste, add your workspace ID, and you're fetching live catalog data — no auth required:
 
 ```ts
 import { createStorefrontClient } from "@managesales/storefront";
 
 const client = createStorefrontClient({
-  workspaceId: "ws_123", // your store's workspace ID — Settings → API
+  workspaceId: "ws_123", // your store — Settings → API
 });
 
-// Browse products — no authentication required
-const { data: products, total } = await client.products.list({ limit: 12 });
-console.log(`${total} products`, products);
+const { data: products } = await client.products.list({ limit: 12 });
+console.log(products);
 ```
 
-That's it — public catalog data needs no auth. Add [authentication](#authentication) only when
-customers log in.
+## API organization
 
-## Create a client
+Every resource is a namespace on the client. Public resources need no auth; customer resources
+require a logged-in session.
 
 ```ts
-import { createStorefrontClient } from "@managesales/storefront";
+// Catalog (public)
+client.products.list(params?)          // paginated list
+client.products.get(idOrSlug)          // product details
+client.products.search(query, params?) // full-text search
+client.collections.list(params?)
+client.collections.get(idOrSlug)       // collection + its products
+
+// Cart & checkout (public)
+client.checkout.create(lineItems)      // start a checkout from line items
+client.checkout.get(checkoutId)
+client.checkout.applyCoupon(checkoutId, code)
+client.checkout.complete(checkoutId, payment?)
+client.cart.create()  /  client.cart.current()   // stateful cart — see Stateful cart
+client.cart.recover(token)             // rebuild a checkout from a recovery link
+client.orders.list(params?)            // alias for client.customer.orders(params?)
+
+// Auth & customer (customer session)
+client.auth.register({ email, password, name })
+client.auth.login(email, password)
+client.auth.loginWithGoogle(idToken)
+client.auth.logout()
+client.auth.isAuthenticated()
+client.auth.setTokens(access, refresh) // restore a session (e.g. from cookies)
+client.customer.me()
+client.customer.orders(params?)        // order history
+client.customer.addresses()
+// client.customers.* — alias namespace bundling auth + customer under one name
+// (client.customers.login === client.auth.login, client.customers.me === client.customer.me, ...)
+
+// Content (public)
+client.blog.list(params?)   /  client.blog.get(slug)
+client.bookings.services()  /  client.bookings.availability(params)  /  client.bookings.book(data)
+client.forms.get(idOrSlug)  /  client.forms.submit(formId, data)     /  client.forms.uploadFile(formId, file)
+```
 
+## Create a client
+
+```ts
 const client = createStorefrontClient({
   workspaceId: "ws_123",
 });
@@ -87,12 +119,11 @@ const client = createStorefrontClient({
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `workspaceId` | `string` | ✅ | Identifies your store. Found in **Settings → API**. |
-| `apiUrl` | `string` | — | Backend base URL **including** the `/api/v1` prefix. Defaults to ManageSales cloud; override for self-hosted/staging/local. |
-| `customFetch` | `typeof fetch` | — | Inject a `fetch` implementation for SSR/edge runtimes or Node < 18. |
+| `apiUrl` | `string` | — | Backend base URL **including** the `/api/v1` prefix. Defaults to ManageSales cloud; override for self-hosted / staging / local. |
+| `customFetch` | `typeof fetch` | — | Inject a `fetch` for SSR / edge runtimes or Node < 18. |
 | `locale` | `string` | — | Default locale for localized content (e.g. `"en"`). |
 
 ```ts
-// Point at your own backend and inject a custom fetch:
 const client = createStorefrontClient({
   workspaceId: "ws_123",
   apiUrl: "https://api.mystore.com/api/v1",
@@ -101,7 +132,7 @@ const client = createStorefrontClient({
 });
 ```
 
-## Products
+## Products & search
 
 ```ts
 // List with pagination, search, and sorting
@@ -124,32 +155,30 @@ const { data: results } = await client.products.search("organic cotton");
 ## Collections
 
 ```ts
-// List collections
 const { data: collections } = await client.collections.list();
 
-// Get a collection with its products
 const summer = await client.collections.get("summer-sale");
-console.log(summer.name, summer.products.length);
+console.log(summer.name, summer.products.length); // collection + its products
 ```
 
 ## Cart & checkout
 
-The SDK models a cart as a set of checkout line items. Assemble items in your UI, create a checkout
-session, optionally apply a coupon, then complete it.
+Assemble line items in your UI, create a checkout session, optionally apply a coupon, then complete
+it:
 
 ```ts
-// 1. Create a checkout from cart line items
+// 1. Create a checkout from line items
 const session = await client.checkout.create([
-  { productId: "prod_123", variantId: "var_456", quantity: 2 },
-  { productId: "prod_789", quantity: 1 },
+  { productId: "prod_123", variantId: "var_456", productName: "Blue T-Shirt", quantity: 2, unitPrice: 24.99 },
+  { productId: "prod_789", productName: "Canvas Tote", quantity: 1, unitPrice: 18 },
 ]);
 
-// 2. Re-fetch a session (e.g. after a page reload)
+// 2. Re-fetch a session (e.g. after a reload)
 const current = await client.checkout.get(session.id);
 
 // 3. Apply a coupon
 const discounted = await client.checkout.applyCoupon(session.id, "SAVE10");
-console.log("Discount:", discounted.discount, "Total:", discounted.total);
+console.log(discounted.discount, discounted.total);
 
 // 4. Complete the purchase
 const order = await client.checkout.complete(session.id, {
@@ -159,47 +188,73 @@ const order = await client.checkout.complete(session.id, {
 console.log("Order placed:", order.orderNumber);
 ```
 
+> `productName` and `unitPrice` are required on every line item passed directly to
+> `client.checkout.create()` — the backend validates them. If you'd rather not look these up
+> yourself, use the [stateful cart](#stateful-cart) instead: `cart.addLineItem` auto-enriches
+> `productName`/`unitPrice` (and `imageUrl`) via `products.get`, so cart callers only ever supply
+> `productId`/`variantId`/`quantity`.
+
 **Abandoned-cart recovery** — turn a recovery link back into a checkout session:
 
 ```ts
-// URL: https://yourstore.com/recover?token=abc123
 const token = new URLSearchParams(location.search).get("token")!;
 const recovered = await client.cart.recover(token);
 ```
 
-## Authentication
+## Stateful cart
 
-Most storefront pages need **no auth**. When a customer logs in, the SDK stores the access + refresh
-tokens internally and refreshes them automatically on `401` — you never handle tokens by hand.
+For a persistent, imperative cart — add/update/remove lines, then check out in one call — use
+`client.cart` instead of assembling line items by hand:
 
 ```ts
-// Register
-const session = await client.auth.register({
-  email: "jane@example.com",
-  password: "SecurePass123!",
-  name: "Jane Doe",
-});
+// Create a fresh cart, or resume one already persisted for this workspace
+const cart = client.cart.create(); // client.cart.current() resumes a persisted cart instead
 
-// Login
-await client.auth.login("jane@example.com", "SecurePass123!");
+// Add items — price, name, and image are looked up automatically via products.get()
+await cart.addLineItem({ productId: "prod_123", variantId: "var_456", quantity: 2 });
+await cart.addLineItem({ productId: "prod_123", variantId: "var_456", quantity: 1 }); // merges into the existing line
 
-// Google OAuth (pass a Google ID token)
-await client.auth.loginWithGoogle(googleIdToken);
+console.log(cart.itemCount); // 3
+console.log(cart.subtotal);  // sum of unitPrice * quantity across all lines
 
-// Check state / log out
-if (client.auth.isAuthenticated()) {
-  /* show account menu */
-}
+cart.updateLineItem(cart.lines[0].id, 5); // set a line's quantity (quantity <= 0 removes it)
+cart.removeLineItem(cart.lines[0].id);
+cart.clear();
+
+// Turn the cart directly into a checkout session
+const session = await cart.checkout({ clearOnSuccess: true });
+console.log(session.id, session.total);
+```
+
+By default the cart is persisted to `localStorage` under a per-workspace key, so `client.cart.current()`
+resumes it after a page reload. Pass `persistCart: false` to `createStorefrontClient` to keep it
+in-memory only (tests, SSR, multi-cart UIs). All storage access is guarded, so the SDK still imports
+and runs fine under Node/SSR where `localStorage` doesn't exist — the cart simply won't persist.
+
+> `cart.checkout()` forwards the cart's line items to `client.checkout.create()` under the hood, so
+> coupons/payment on the returned session work exactly as in [Cart & checkout](#cart--checkout).
+
+## Authentication
+
+Most pages need **no auth**. When a customer logs in, the SDK stores the access + refresh tokens and
+**auto-refreshes on `401`** — you never handle tokens by hand.
+
+```ts
+await client.auth.register({ email: "jane@example.com", password: "SecurePass123!", name: "Jane Doe" });
+await client.auth.login("jane@example.com", "SecurePass123!");
+await client.auth.loginWithGoogle(googleIdToken); // pass a Google ID token
+
+if (client.auth.isAuthenticated()) { /* show account menu */ }
 await client.auth.logout();
 ```
 
 ### Server-side (recommended)
 
-For production, run the SDK on your server (Next.js route handlers, Express, etc.) with httpOnly
-cookies so tokens never reach the browser. Restore a session from cookies with `setTokens`:
+For production, run the SDK on your server with httpOnly cookies so tokens never reach the browser.
+Restore a session with `setTokens`:
 
 ```ts
-// app/api/storefront/[...path]/route.ts
+// app/api/storefront/[...path]/route.ts (Next.js)
 import { createStorefrontClient } from "@managesales/storefront";
 import { cookies } from "next/headers";
 
@@ -217,18 +272,48 @@ export async function GET() {
 
 ## Customer account
 
-Requires a logged-in session (see [Authentication](#authentication)).
+Requires a logged-in session.
 
 ```ts
-const me = await client.customer.me();                       // profile
+const me = await client.customer.me();                             // profile
 const { data: orders } = await client.customer.orders({ page: 1 }); // order history
-const addresses = await client.customer.addresses();         // saved addresses
+const addresses = await client.customer.addresses();               // saved addresses
+```
+
+`client.customers` mirrors `auth` + `customer` under one namespace, and `client.orders.list()` is a
+shorthand for `client.customer.orders()` — same functions, same requests, just organized differently:
+
+```ts
+await client.customers.login("jane@example.com", "SecurePass123!"); // === client.auth.login
+const { data: orders } = await client.orders.list({ page: 1 });     // === client.customer.orders({ page: 1 })
+```
+
+## Retries
+
+Network failures and `408` / `425` / `429` / `5xx` responses to idempotent (`GET`/`HEAD`) requests are
+retried automatically with exponential backoff, honoring a `Retry-After` response header as a delay
+floor when the server sends one. Non-idempotent requests (`POST`/`PUT`/`PATCH`/`DELETE`) are retried
+**only** when the request never reached the server (e.g. `fetch` itself throws) — never after a server
+response, since the side effect may already have happened.
+
+```ts
+const client = createStorefrontClient({
+  workspaceId: "ws_123",
+  retry: {
+    retries: 2,          // default: 2 additional attempts after the first
+    baseDelayMs: 300,     // default: 300 — base for exponential backoff
+    maxDelayMs: 4000,     // default: 4000 — cap on any single backoff delay
+    retryOnStatus: [408, 425, 429, 500, 502, 503, 504], // default shown
+  },
+});
+
+// Disable retries entirely
+const noRetryClient = createStorefrontClient({ workspaceId: "ws_123", retry: false });
 ```
 
 ## Error handling
 
-Every non-2xx response throws a `StorefrontError` with structured fields, so you can branch
-precisely:
+Every non-2xx response throws a `StorefrontError` with structured fields:
 
 ```ts
 import { StorefrontError } from "@managesales/storefront";
@@ -247,30 +332,13 @@ try {
 }
 ```
 
-## More resources
-
-The client also exposes `client.blog`, `client.bookings`, and `client.forms`:
-
-```ts
-const { data: posts } = await client.blog.list({ limit: 10 });
-const post = await client.blog.get("how-to-style-leather");
-
-const services = await client.bookings.services();
-const slots = await client.bookings.availability({ serviceId: "svc_1", date: "2026-08-15" });
-const booking = await client.bookings.book({
-  serviceId: "svc_1",
-  date: "2026-08-15",
-  startTime: "10:00",
-  customer: { name: "Jane Doe", email: "jane@example.com" },
-});
-
-const form = await client.forms.get("contact-us");
-await client.forms.submit(form.id, { name: "Jane", email: "jane@example.com", message: "Hi!" });
-```
+> **Resilience:** the client automatically retries a request **once** with a refreshed token when a
+> `401` indicates an expired access token, and separately retries transient network/5xx failures per
+> the [Retries](#retries) config.
 
 ## TypeScript support
 
-Written in TypeScript and shipped with declaration files — no `@types/*` package needed. Params and
+Written in TypeScript and shipped with declaration files — no `@types/*` package. Params and
 responses are fully typed, including generics like `PaginatedResponse<Product>`:
 
 ```ts
@@ -288,18 +356,77 @@ const client = createStorefrontClient(config);
 const page: PaginatedResponse<Product> = await client.products.list();
 ```
 
+## Framework examples
+
+**React**
+
+```tsx
+import { useEffect, useState } from "react";
+import { createStorefrontClient, type Product } from "@managesales/storefront";
+
+const client = createStorefrontClient({ workspaceId: "ws_123" });
+
+export function ProductGrid() {
+  const [products, setProducts] = useState<Product[]>([]);
+  useEffect(() => {
+    client.products.list({ limit: 12 }).then((res) => setProducts(res.data));
+  }, []);
+  return <ul>{products.map((p) => <li key={p.id}>{p.name}</li>)}</ul>;
+}
+```
+
+**Next.js (Server Component)**
+
+```tsx
+// app/page.tsx
+import { createStorefrontClient } from "@managesales/storefront";
+
+const client = createStorefrontClient({ workspaceId: "ws_123" });
+
+export default async function Home() {
+  const { data: products } = await client.products.list({ limit: 12 });
+  return <ProductGrid products={products} />;
+}
+```
+
+**Node.js**
+
+```ts
+import { createStorefrontClient } from "@managesales/storefront";
+
+const client = createStorefrontClient({ workspaceId: "ws_123" });
+
+const { data } = await client.products.list({ page: 1, limit: 20 });
+console.log(data);
+```
+
 ## Browser & Node support
 
 - **Zero dependencies** — uses the platform's global `fetch`.
 - **Node.js ≥ 18** (global `fetch`). On older Node, pass `customFetch` (e.g. `undici`).
 - **Browsers** — all modern evergreen browsers.
-- **Deno, Bun, and edge runtimes** (Cloudflare Workers, Vercel Edge) — supported; inject
-  `customFetch` where a global isn't available.
+- **Deno, Bun, edge runtimes** (Cloudflare Workers, Vercel Edge) — supported; inject `customFetch`
+  where a global isn't available.
 - **Module formats** — ships both **ESM** (`import`) and **CommonJS** (`require`).
 
+## Versioning
+
+Follows [Semantic Versioning](https://semver.org):
+
+- **patch** (`x.y.Z`) — docs and bug fixes, no API change
+- **minor** (`x.Y.z`) — additive, backward-compatible API
+- **major** (`X.y.z`) — breaking changes to the client surface
+
+The SDK version tracks the ManageSales Storefront API contract it targets. See the
+[Changelog](#changelog).
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for release notes.
+
 ## No-npm alternative
 
-Prefer not to add a dependency? The exact same client is served as a single file — download it from
+Prefer no dependency? The identical client is served as a single file — download it from
 **Developers → SDKs** in the app, or curl it:
 
 ```bash
@@ -308,7 +435,7 @@ curl -o managesales-storefront.ts \
 ```
 
 Then `import { createStorefrontClient } from "./managesales-storefront"`. The npm package, the curl
-endpoint, and the in-app download are all generated from one source, so they're always identical.
+endpoint, and the in-app download are generated from one source, so they're always identical.
 
 ## License