@managesales/storefront 1.0.0 → 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,77 +1,366 @@
-# @managesales/storefront
+# ManageSales Storefront SDK
 
-Resource-based TypeScript client for building online storefronts on the **ManageSales Storefront
-API** — like Shopify's Storefront API client. Built-in auth, automatic token refresh, typed
-responses, and **zero runtime dependencies**.
+**Build custom storefronts on top of the ManageSales Commerce Platform.**
 
-> The same client is also available without npm: `curl` it from the backend at
-> `GET /api/v1/sdk/storefront.ts`, or download it from **Developers → SDKs** in the app. All three
-> surfaces are generated from one source, so they're always identical.
+[![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)
 
-## Install
+`@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:
+
+- 🛍️ **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
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [API organization](#api-organization)
+- [Create a client](#create-a-client)
+- [Products & search](#products--search)
+- [Collections](#collections)
+- [Cart & checkout](#cart--checkout)
+- [Authentication](#authentication)
+- [Customer account](#customer-account)
+- [Error handling](#error-handling)
+- [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)
+
+## Installation
 
 ```bash
 npm install @managesales/storefront
-# or: pnpm add @managesales/storefront / yarn add @managesales/storefront
+pnpm add @managesales/storefront
+yarn add @managesales/storefront
+bun add @managesales/storefront
 ```
 
-## Usage
+## 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", // required — identifies your storefront
+  workspaceId: "ws_123", // your store — Settings → API
 });
 
-const products = await client.products.list();
+const { data: products } = await client.products.list({ limit: 12 });
+console.log(products);
 ```
 
-The backend URL defaults to production. Point it elsewhere (self-hosted, staging, local) at runtime
-— the URL must include the `/api/v1` prefix:
+## API organization
+
+Every resource is a namespace on the client. Public resources need no auth; customer resources
+require a logged-in session.
+
+```ts
+// 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",
+});
+```
+
+| 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` for SSR / edge runtimes or Node < 18. |
+| `locale` | `string` | — | Default locale for localized content (e.g. `"en"`). |
 
 ```ts
 const client = createStorefrontClient({
   workspaceId: "ws_123",
-  apiUrl: "https://your-backend.example.com/api/v1",
+  apiUrl: "https://api.mystore.com/api/v1",
+  customFetch: fetch,
+  locale: "en",
+});
+```
+
+## Products & search
+
+```ts
+// List with pagination, search, and sorting
+const { data: products, total } = await client.products.list({
+  page: 1,
+  limit: 20,
+  search: "red shoes",
+  sort: "price",
+  order: "asc",
 });
+
+// Product details — by ID or slug
+const product = await client.products.get("leather-jacket");
+console.log(product.name, product.price, product.variants);
+
+// Full-text search
+const { data: results } = await client.products.search("organic cotton");
+```
+
+## Collections
+
+```ts
+const { data: collections } = await client.collections.list();
+
+const summer = await client.collections.get("summer-sale");
+console.log(summer.name, summer.products.length); // collection + its products
+```
+
+## Cart & checkout
+
+Assemble line items in your UI, create a checkout session, optionally apply a coupon, then complete
+it:
+
+```ts
+// 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 reload)
+const current = await client.checkout.get(session.id);
+
+// 3. Apply a coupon
+const discounted = await client.checkout.applyCoupon(session.id, "SAVE10");
+console.log(discounted.discount, discounted.total);
+
+// 4. Complete the purchase
+const order = await client.checkout.complete(session.id, {
+  paymentMethod: "card",
+  token: "tok_visa_xxx",
+});
+console.log("Order placed:", order.orderNumber);
+```
+
+**Abandoned-cart recovery** — turn a recovery link back into a checkout session:
+
+```ts
+const token = new URLSearchParams(location.search).get("token")!;
+const recovered = await client.cart.recover(token);
+```
+
+## 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 with httpOnly cookies so tokens never reach the browser.
+Restore a session with `setTokens`:
+
+```ts
+// app/api/storefront/[...path]/route.ts (Next.js)
+import { createStorefrontClient } from "@managesales/storefront";
+import { cookies } from "next/headers";
+
+export async function GET() {
+  const client = createStorefrontClient({ workspaceId: "ws_123" });
+
+  const access = cookies().get("sf_access_token")?.value;
+  const refresh = cookies().get("sf_refresh_token")?.value;
+  if (access && refresh) client.auth.setTokens(access, refresh);
+
+  const products = await client.products.list({ limit: 20 });
+  return Response.json(products);
+}
+```
+
+## Customer account
+
+Requires a logged-in session.
+
+```ts
+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
+```
+
+## Error handling
+
+Every non-2xx response throws a `StorefrontError` with structured fields:
+
+```ts
+import { StorefrontError } from "@managesales/storefront";
+
+try {
+  await client.products.get("does-not-exist");
+} catch (err) {
+  if (err instanceof StorefrontError) {
+    console.log(err.status);  // 404
+    console.log(err.code);    // "NOT_FOUND"
+    console.log(err.message); // "Product not found"
+    console.log(err.details); // full error body from the API
+  } else {
+    throw err; // network / unexpected
+  }
+}
+```
+
+> **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. Params and
+responses are fully typed, including generics like `PaginatedResponse<Product>`:
+
+```ts
+import {
+  createStorefrontClient,
+  StorefrontError,
+  type StorefrontConfig,
+  type Product,
+  type PaginatedResponse,
+} from "@managesales/storefront";
+
+const config: StorefrontConfig = { workspaceId: "ws_123" };
+const client = createStorefrontClient(config);
+
+const page: PaginatedResponse<Product> = await client.products.list();
 ```
 
-For SSR / edge runtimes you can inject a custom `fetch`:
+## 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
-createStorefrontClient({ workspaceId: "ws_123", customFetch: fetch });
+import { createStorefrontClient } from "@managesales/storefront";
+
+const client = createStorefrontClient({ workspaceId: "ws_123" });
+
+const { data } = await client.products.list({ page: 1, limit: 20 });
+console.log(data);
 ```
 
-Errors thrown by the client are instances of `StorefrontError` (exposes `status` and the API
-message), so you can branch on failures precisely.
+## 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, 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).
 
-## Works everywhere
+## Changelog
 
-Ships dual **ESM + CommonJS** builds with type declarations — usable from Next.js, Remix, Nuxt,
-Astro, plain Node (`import` or `require`), Vite, and the browser. Requires Node ≥ 18 (for global
-`fetch`).
+See [CHANGELOG.md](./CHANGELOG.md) for release notes.
 
-## Maintainers
+## No-npm alternative
 
-This package is **generated**, not hand-written. `src/index.ts` is produced by
-`scripts/generate.ts`, which calls the canonical `generateStorefrontSdk` function in the backend
-(`backend/src/modules/storefront/sdk/storefront-sdk-source.ts`) — the exact same function that
-serves `GET /api/v1/sdk/storefront.ts`. This guarantees the npm package, the curl endpoint, and the
-in-app Download never drift.
+Prefer no dependency? The identical client is served as a single file — download it from
+**Developers → SDKs** in the app, or curl it:
 
 ```bash
-npm run build   # regenerate src/index.ts from the backend, then compile to dist/
-npm publish     # requires the @managesales npm org + an automation token
+curl -o managesales-storefront.ts \
+  "https://managesales-backend-phase1test.up.railway.app/api/v1/sdk/storefront.ts"
 ```
 
-- Bump the version in **both** `package.json` and the backend's `STOREFRONT_SDK_VERSION`; the build
-  fails fast if they disagree.
-- Override the baked default backend URL at build time with `PUBLIC_API_URL` (must include
-  `/api/v1`).
-- The build imports the generator across the monorepo. If this package is ever extracted to its own
-  repo, vendor `storefront-sdk-source.ts` into `scripts/` instead.
+Then `import { createStorefrontClient } from "./managesales-storefront"`. The npm package, the curl
+endpoint, and the in-app download are generated from one source, so they're always identical.
 
 ## License
 
-Apache-2.0. See [LICENSE](./LICENSE).
+[Apache-2.0](./LICENSE) © ManageSales

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@managesales/storefront",
-  "version": "1.0.0",
+  "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,