@managesales/storefront 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to `@managesales/storefront`. This project adheres to
+[Semantic Versioning](https://semver.org).
+
+## 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,110 @@
-# @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)
 - [Authentication](#authentication)
 - [Customer account](#customer-account)
 - [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.recover(token)             // rebuild a checkout from a recovery link
+
+// 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()
+
+// 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 +113,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 +126,7 @@ const client = createStorefrontClient({
 });
 ```
 
-## Products
+## Products & search
 
 ```ts
 // List with pagination, search, and sorting
@@ -124,32 +149,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 },
 ]);
 
-// 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, {
@@ -162,44 +185,31 @@ console.log("Order placed:", order.orderNumber);
 **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
 
-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.
+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
-// Register
-const session = await client.auth.register({
-  email: "jane@example.com",
-  password: "SecurePass123!",
-  name: "Jane Doe",
-});
-
-// Login
+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
 
-// Google OAuth (pass a Google ID token)
-await client.auth.loginWithGoogle(googleIdToken);
-
-// Check state / log out
-if (client.auth.isAuthenticated()) {
-  /* show account menu */
-}
+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 +227,17 @@ 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
 ```
 
 ## 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 +256,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. It does not retry on network/5xx errors — wrap calls in
+> your own retry policy if you need that.
 
 ## 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 +280,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 +359,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@managesales/storefront",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Resource-based TypeScript client for building storefronts on the ManageSales Storefront API. Zero runtime dependencies, built-in auth and token refresh.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -16,6 +16,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": false,