@managesales/storefront 1.0.0 → 1.0.1

package/README.md

@@ -1,77 +1,315 @@
 # @managesales/storefront
 
+[![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** — like Shopify's Storefront API client. Built-in auth, automatic token refresh, typed
-responses, and **zero runtime dependencies**.
+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.
+
+- 🧩 **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
+
+---
+
+## Table of contents
+
+- [What is this?](#what-is-this)
+- [Installation](#installation)
+- [Quick start](#quick-start-30-seconds)
+- [Create a client](#create-a-client)
+- [Products](#products)
+- [Collections](#collections)
+- [Cart & checkout](#cart--checkout)
+- [Authentication](#authentication)
+- [Customer account](#customer-account)
+- [Error handling](#error-handling)
+- [More resources](#more-resources)
+- [TypeScript support](#typescript-support)
+- [Browser & Node support](#browser--node-support)
+- [No-npm alternative](#no-npm-alternative)
+- [License](#license)
+
+---
 
-> 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.
+## What is this?
 
-## Install
+`@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
-# or: pnpm add @managesales/storefront / yarn add @managesales/storefront
+# pnpm add @managesales/storefront
+# yarn add @managesales/storefront
+# bun add @managesales/storefront
 ```
 
-## Usage
+## Quick start (30 seconds)
 
 ```ts
 import { createStorefrontClient } from "@managesales/storefront";
 
 const client = createStorefrontClient({
-  workspaceId: "ws_123", // required — identifies your storefront
+  workspaceId: "ws_123", // your store's workspace ID — Settings → API
 });
 
-const products = await client.products.list();
+// Browse products — no authentication required
+const { data: products, total } = await client.products.list({ limit: 12 });
+console.log(`${total} products`, products);
 ```
 
-The backend URL defaults to production. Point it elsewhere (self-hosted, staging, local) at runtime
-— the URL must include the `/api/v1` prefix:
+That's it — public catalog data needs no auth. Add [authentication](#authentication) only when
+customers log in.
+
+## Create a client
 
 ```ts
+import { createStorefrontClient } from "@managesales/storefront";
+
 const client = createStorefrontClient({
   workspaceId: "ws_123",
-  apiUrl: "https://your-backend.example.com/api/v1",
 });
 ```
 
-For SSR / edge runtimes you can inject a custom `fetch`:
+| 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. |
+| `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",
+  customFetch: fetch,
+  locale: "en",
+});
+```
+
+## Products
+
+```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
+// 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);
+```
+
+## 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.
+
+```ts
+// 1. Create a checkout from cart 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)
+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);
+
+// 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
+// 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.
+
+```ts
+// Register
+const session = await client.auth.register({
+  email: "jane@example.com",
+  password: "SecurePass123!",
+  name: "Jane Doe",
+});
+
+// Login
+await client.auth.login("jane@example.com", "SecurePass123!");
+
+// Google OAuth (pass a Google ID token)
+await client.auth.loginWithGoogle(googleIdToken);
+
+// Check state / log out
+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`:
+
+```ts
+// app/api/storefront/[...path]/route.ts
+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 (see [Authentication](#authentication)).
 
 ```ts
-createStorefrontClient({ workspaceId: "ws_123", customFetch: fetch });
+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
 ```
 
-Errors thrown by the client are instances of `StorefrontError` (exposes `status` and the API
-message), so you can branch on failures precisely.
+## Error handling
+
+Every non-2xx response throws a `StorefrontError` with structured fields, so you can branch
+precisely:
+
+```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
+  }
+}
+```
+
+## 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!" });
+```
+
+## TypeScript support
+
+Written in TypeScript and shipped with declaration files — no `@types/*` package needed. 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();
+```
 
-## Works everywhere
+## Browser & Node support
 
-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`).
+- **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.
+- **Module formats** — ships both **ESM** (`import`) and **CommonJS** (`require`).
 
-## 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 not to add a dependency? The exact same 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 all 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.1",
   "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",