@managesales/storefront 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,67 @@
 All notable changes to `@managesales/storefront`. This project adheres to
 [Semantic Versioning](https://semver.org).
 
+## 1.2.0 — 2026-07-21
+
+### Added
+- **`discounts` namespace** — `client.discounts.validate(code, { subtotal | items, customerId? })`
+  previews a discount code against a cart *before* creating a checkout session. Returns
+  `{ valid: true, discountId, code, label, amount, freeShipping }` or
+  `{ valid: false, reason }` with a customer-safe explanation — no try/catch needed for
+  "invalid code" UI states. Validation never consumes coupon usage.
+- **`client.discounts.automatic()`** — lists the store's active automatic promotions
+  (`AutomaticPromotion[]`: title, type, value, minimums, end date) for display, e.g. promo
+  banners. Coupon codes are never exposed by this endpoint.
+- **`checkout.applyGiftCard(checkoutId, code)`** — applies a gift card to an open checkout
+  session (the backend endpoint existed; the SDK now exposes it).
+- **`couponCode` option at checkout creation** — `checkout.create(items, { couponCode })` and
+  `cart.checkout({ couponCode })` apply the code server-side in the same round-trip as session
+  creation.
+
+### Fixed
+- **`checkout.applyCoupon` sent the wrong field name and always failed.** The request body was
+  `{ couponCode }`, but the API accepts `{ code }` and rejects unknown fields — every
+  `applyCoupon` call returned a 400. It now sends `{ code }`.
+- **`CheckoutSession` type now matches the actual API response.** The session's real fields are
+  `lines`, `discountAmount`, `discountCode`, `discountLabel`, `taxAmount`, `shippingAmount`,
+  `giftCardAmount`, `availableShippingMethods`, etc. The previously-declared `items`, `tax`,
+  `discount`, and `couponCode` members were never populated at runtime; they remain as optional
+  `@deprecated` aliases so existing code still compiles. `shipping` was previously typed as a
+  number but is actually the shipping *address object* on the wire — it is now typed correctly
+  (`CheckoutShippingAddress`).
+
+## 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

package/README.md

@@ -30,8 +30,10 @@ like Shopify's Storefront client, for ManageSales. Everything you need to ship a
 - [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)
 - [TypeScript support](#typescript-support)
 - [Framework examples](#framework-examples)
@@ -78,12 +80,19 @@ client.products.search(query, params?) // full-text search
 client.collections.list(params?)
 client.collections.get(idOrSlug)       // collection + its products
 
+// Discounts (public)
+client.discounts.validate(code, { subtotal | items })  // preview a code before checkout
+client.discounts.automatic()           // active automatic promotions (for banners)
+
 // Cart & checkout (public)
-client.checkout.create(lineItems)      // start a checkout from line items
+client.checkout.create(lineItems, { couponCode? })     // start a checkout from line items
 client.checkout.get(checkoutId)
 client.checkout.applyCoupon(checkoutId, code)
+client.checkout.applyGiftCard(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 })
@@ -95,6 +104,8 @@ 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)
@@ -155,26 +166,56 @@ const summer = await client.collections.get("summer-sale");
 console.log(summer.name, summer.products.length); // collection + its products
 ```
 
+## Discounts
+
+Preview a discount code against the customer's cart **before** creating a checkout session — ideal
+for a "promo code" field with instant feedback. Validation never consumes the coupon's usage:
+
+```ts
+const check = await client.discounts.validate("SAVE10", { subtotal: 68 });
+// or derive the subtotal from line items:
+// await client.discounts.validate("SAVE10", { items: [{ quantity: 2, unitPrice: 24.99 }] });
+
+if (check.valid) {
+  console.log(`${check.label} — saves ${check.amount}`); // "Summer Sale (SAVE10) — saves 6.80"
+} else {
+  console.log(check.reason); // customer-safe, e.g. "Minimum order amount of 50 required"
+}
+```
+
+Show the store's running automatic promotions (no code needed to redeem — great for banners):
+
+```ts
+const promos = await client.discounts.automatic();
+// [{ id, title: "Free shipping over $100", type: "free_shipping", value: 0, minOrderAmount: 100, ... }]
+```
+
 ## Cart & checkout
 
-Assemble line 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 or gift card,
+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 },
-]);
+// 1. Create a checkout from line items — optionally applying a coupon in the same call
+const session = await client.checkout.create(
+  [
+    { 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 },
+  ],
+  { couponCode: "SAVE10" },
+);
 
 // 2. Re-fetch a session (e.g. after a reload)
 const current = await client.checkout.get(session.id);
 
-// 3. Apply a coupon
+// 3. Apply (or change) a coupon on an open session
 const discounted = await client.checkout.applyCoupon(session.id, "SAVE10");
-console.log(discounted.discount, discounted.total);
+console.log(discounted.discountAmount, discounted.total);
+
+// 4. Apply a gift card
+const withGiftCard = await client.checkout.applyGiftCard(session.id, "GC-XXXX-XXXX");
 
-// 4. Complete the purchase
+// 5. Complete the purchase
 const order = await client.checkout.complete(session.id, {
   paymentMethod: "card",
   token: "tok_visa_xxx",
@@ -182,6 +223,12 @@ 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
@@ -189,6 +236,39 @@ const token = new URLSearchParams(location.search).get("token")!;
 const recovered = await client.cart.recover(token);
 ```
 
+## Stateful cart
+
+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
+// 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
+
+// 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
+
+console.log(cart.itemCount); // 3
+console.log(cart.subtotal);  // sum of unitPrice * quantity across all lines
+
+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 — optionally with a coupon
+const session = await cart.checkout({ clearOnSuccess: true, couponCode: "SAVE10" });
+console.log(session.id, session.discountAmount, 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
@@ -235,6 +315,37 @@ const { data: orders } = await client.customer.orders({ page: 1 }); // order his
 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:
@@ -257,8 +368,8 @@ try {
 ```
 
 > **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.
+> `401` indicates an expired access token, and separately retries transient network/5xx failures per
+> the [Retries](#retries) config.
 
 ## TypeScript support
 

package/dist/index.cjs

@@ -15,6 +15,18 @@ function createStorefrontClient(config) {
   const fetchFn = config.customFetch ?? globalThis.fetch.bind(globalThis);
   let accessToken = null;
   let refreshToken = null;
+  const RETRY_DEFAULTS = {
+    retries: 2,
+    baseDelayMs: 300,
+    maxDelayMs: 4e3,
+    retryOnStatus: [408, 425, 429, 500, 502, 503, 504]
+  };
+  const rc = config.retry === false ? { ...RETRY_DEFAULTS, retries: 0 } : { ...RETRY_DEFAULTS, ...config.retry || {} };
+  const IDEMPOTENT = /* @__PURE__ */ new Set(["GET", "HEAD"]);
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  function backoff(attempt) {
+    return Math.min(rc.maxDelayMs, Math.round(Math.random() * rc.baseDelayMs * Math.pow(2, attempt)));
+  }
   async function request(method, path, options) {
     const url = new URL(`${apiUrl}${path}`);
     if (options?.params) {
@@ -31,11 +43,32 @@ function createStorefrontClient(config) {
     if (options?.body) {
       headers["Content-Type"] = "application/json";
     }
-    const res = await fetchFn(url.toString(), {
+    const fetchOptions = {
       method,
       headers,
       body: options?.body ? JSON.stringify(options.body) : void 0
-    });
+    };
+    let attempt = 0;
+    let res;
+    while (true) {
+      try {
+        res = await fetchFn(url.toString(), fetchOptions);
+      } catch (err) {
+        if (attempt < rc.retries) {
+          await sleep(backoff(attempt));
+          attempt++;
+          continue;
+        }
+        throw err;
+      }
+      if (attempt < rc.retries && rc.retryOnStatus.includes(res.status) && IDEMPOTENT.has(method)) {
+        const ra = Number(res.headers.get("retry-after"));
+        await sleep(Number.isFinite(ra) && ra > 0 ? ra * 1e3 : backoff(attempt));
+        attempt++;
+        continue;
+      }
+      break;
+    }
     if (res.status === 401 && options?.auth && refreshToken) {
       const refreshed = await refreshSession();
       if (refreshed) {
@@ -119,10 +152,22 @@ function createStorefrontClient(config) {
       return request("GET", `/storefront-api/collections/${idOrSlug}`);
     }
   };
+  const discounts = {
+    /** Preview a discount code against a cart before checkout. Never consumes usage. */
+    async validate(code, input) {
+      return request("POST", "/storefront-api/discounts/validate", { body: { code, ...input || {} } });
+    },
+    /** Active automatic promotions for display (codes are never exposed) */
+    async automatic() {
+      return request("GET", "/storefront-api/discounts/automatic");
+    }
+  };
   const checkout = {
     /** Create a checkout session from cart items */
-    async create(items) {
-      return request("POST", "/checkout", { body: { items } });
+    async create(items, opts) {
+      const body = { lines: items };
+      if (opts && opts.couponCode) body.couponCode = opts.couponCode;
+      return request("POST", "/checkout", { body });
     },
     /** Retrieve an existing checkout session */
     async get(checkoutId) {
@@ -130,7 +175,11 @@ function createStorefrontClient(config) {
     },
     /** Apply a coupon or discount code */
     async applyCoupon(checkoutId, couponCode) {
-      return request("POST", `/checkout/${checkoutId}/coupon`, { body: { couponCode } });
+      return request("POST", `/checkout/${checkoutId}/coupon`, { body: { code: couponCode } });
+    },
+    /** Apply a gift card to the checkout */
+    async applyGiftCard(checkoutId, code) {
+      return request("POST", `/checkout/${checkoutId}/gift-card`, { body: { code } });
     },
     /** Complete checkout — process payment and create order */
     async complete(checkoutId, payment) {
@@ -254,23 +303,167 @@ function createStorefrontClient(config) {
       return res.json();
     }
   };
+  const CART_KEY = "managesales_cart_" + config.workspaceId;
+  const hasLS = () => {
+    try {
+      return config.persistCart !== false && typeof localStorage !== "undefined";
+    } catch {
+      return false;
+    }
+  };
+  const loadCart = () => {
+    if (!hasLS()) return null;
+    try {
+      const s = localStorage.getItem(CART_KEY);
+      return s ? JSON.parse(s) : null;
+    } catch {
+      return null;
+    }
+  };
+  const saveCart = (st) => {
+    if (!hasLS()) return;
+    try {
+      localStorage.setItem(CART_KEY, JSON.stringify(st));
+    } catch {
+    }
+  };
+  let __lineSeq = 0;
+  const genId = (p) => typeof crypto !== "undefined" && crypto.randomUUID ? p + crypto.randomUUID() : p + Date.now() + "_" + ++__lineSeq;
+  const nowIso = () => (/* @__PURE__ */ new Date()).toISOString();
+  const freshCart = () => ({ id: genId("cart_"), lines: [], createdAt: nowIso(), updatedAt: nowIso() });
+  function makeCart(state) {
+    const persist = () => {
+      state.updatedAt = nowIso();
+      saveCart(state);
+    };
+    const cartObj = {
+      get id() {
+        return state.id;
+      },
+      get lines() {
+        return state.lines;
+      },
+      get itemCount() {
+        return state.lines.reduce((n, l) => n + l.quantity, 0);
+      },
+      get subtotal() {
+        return state.lines.reduce((s, l) => s + l.unitPrice * l.quantity, 0);
+      },
+      // Supplying unitPrice alone does not skip the lookup — productName must also be
+      // provided, otherwise this falls through to the products.get() network lookup below.
+      async addLineItem(input) {
+        let line;
+        if (input.unitPrice != null && input.productName) {
+          line = {
+            id: genId("line_"),
+            productId: input.productId,
+            variantId: input.variantId,
+            quantity: input.quantity,
+            unitPrice: input.unitPrice,
+            productName: input.productName,
+            imageUrl: input.imageUrl
+          };
+        } else {
+          const p = await products.get(input.productId);
+          const v = input.variantId && Array.isArray(p.variants) ? p.variants.find((x) => x.id === input.variantId) : void 0;
+          line = {
+            id: genId("line_"),
+            productId: input.productId,
+            variantId: input.variantId,
+            quantity: input.quantity,
+            unitPrice: v && v.price != null ? v.price : p.price,
+            productName: p.name,
+            imageUrl: Array.isArray(p.images) && p.images.length > 0 ? p.images[0].url : void 0
+          };
+        }
+        const existing = state.lines.find((l) => l.productId === line.productId && l.variantId === line.variantId);
+        if (existing) existing.quantity += line.quantity;
+        else state.lines.push(line);
+        persist();
+        return cartObj;
+      },
+      updateLineItem(lineId, quantity) {
+        const l = state.lines.find((x) => x.id === lineId);
+        if (l) {
+          if (quantity <= 0) state.lines = state.lines.filter((x) => x.id !== lineId);
+          else l.quantity = quantity;
+          persist();
+        }
+        return cartObj;
+      },
+      removeLineItem(lineId) {
+        state.lines = state.lines.filter((x) => x.id !== lineId);
+        persist();
+        return cartObj;
+      },
+      clear() {
+        state.lines = [];
+        persist();
+        return cartObj;
+      },
+      async checkout(opts) {
+        const session = await checkout.create(
+          state.lines.map((l) => ({
+            productId: l.productId,
+            variantId: l.variantId,
+            productName: l.productName,
+            quantity: l.quantity,
+            unitPrice: l.unitPrice,
+            imageUrl: l.imageUrl
+          })),
+          opts && opts.couponCode ? { couponCode: opts.couponCode } : void 0
+        );
+        if (opts && opts.clearOnSuccess) cartObj.clear();
+        return session;
+      }
+    };
+    return cartObj;
+  }
   const cart = {
+    /** Create a new, empty cart (replaces any persisted cart) */
+    create() {
+      const st = freshCart();
+      saveCart(st);
+      return makeCart(st);
+    },
+    /** Get the current cart — loaded from storage if persisted, otherwise a fresh one */
+    current() {
+      return makeCart(loadCart() || freshCart());
+    },
     /** Recover an abandoned cart by recovery token */
     async recover(token) {
       return request("GET", `/abandoned-carts/recover/${token}`);
     }
   };
+  const orders = {
+    /** Get customer's order history (delegates to `customer.orders`) */
+    list: (params) => customer.orders(params)
+  };
+  const customers = {
+    login: auth.login,
+    register: auth.register,
+    loginWithGoogle: auth.loginWithGoogle,
+    logout: auth.logout,
+    isAuthenticated: auth.isAuthenticated,
+    setTokens: auth.setTokens,
+    me: customer.me,
+    orders: customer.orders,
+    addresses: customer.addresses
+  };
   return {
     store,
     products,
     collections,
+    discounts,
     checkout,
     auth,
     customer,
     blog,
     bookings,
     forms,
-    cart
+    cart,
+    orders,
+    customers
   };
 }