@reblu/site-next 1.20.1 → 1.22.0

package/dist/cart.d.cts

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as zustand_middleware from 'zustand/middleware';
 import * as zustand from 'zustand';
+import { ShopCartValidationError, ShopValidateCartInput, ShopCartValidation } from '@reblu/site-contracts';
 
 /**
  * `CartProvider` — mount this once near the root layout (inside a Client
@@ -167,4 +168,137 @@ declare function useCartHydrated(): boolean;
  */
 declare function useCart(): UseCartResult;
 
-export { type AddItemOutcome, type AddItemStatus, CART_STORAGE_KEY, CART_STORE_PERSIST_VERSION, type CartItem, CartProvider, type CartStore, type UseCartResult, __resetCartStoreForTests, useCart, useCartHydrated, useCartStore };
+/**
+ * Cart validation (REB-981). A persisted cart (`localStorage` `shop-cart`)
+ * outlives the catalog it was filled from: a product can be deleted,
+ * deactivated, sold out or repriced between visits. `validateCart` asks the
+ * SITE's validate-cart Route Handler (`createShopValidateCartRoute`) about
+ * every line and APPLIES the answer to the store, so the cart page and the
+ * checkout never show or submit a line nobody can buy.
+ */
+/** Calls validate-cart for the given lines. Must reject (or throw) on failure. */
+type CartValidator = (input: ShopValidateCartInput) => Promise<ShopCartValidation>;
+interface ValidateCartOptions {
+    /**
+     * The SITE's validate-cart Route Handler path, used by the default
+     * validator. Defaults to `'/api/shop/validate-cart'`.
+     */
+    endpoint?: string;
+    /** Replaces the default `fetch`-based validator entirely. */
+    validate?: CartValidator;
+    /**
+     * `true` (default) removes lines whose error says `suggestedAction:
+     * 'remove'` (`not_found`, `inactive`, `out_of_stock`). `false` leaves them
+     * in the cart and only reports them through `lineErrors`.
+     */
+    removeUnavailable?: boolean;
+}
+/** A line the validation removed — `name`/`variantName` come from the persisted line. */
+interface CartRemovedLine {
+    productId: string;
+    variantId: string | null;
+    name: string;
+    variantName?: string;
+    type: ShopCartValidationError['type'];
+    message: string;
+}
+/** A line whose quantity was clamped to the stock still available. */
+interface CartQuantityChange {
+    productId: string;
+    variantId: string | null;
+    name: string;
+    variantName?: string;
+    from: number;
+    to: number;
+}
+/** A line whose `unitPrice` (integer cents) was refreshed from the live price. */
+interface CartPriceChange {
+    productId: string;
+    variantId: string | null;
+    name: string;
+    variantName?: string;
+    from: number;
+    to: number;
+}
+/**
+ * - `valid` — every line is buyable as it stands; nothing changed.
+ * - `adjusted` — the cart was changed (lines removed, quantities clamped or
+ *   prices refreshed) and every error was resolved by those changes. A
+ *   `price_changed` error counts as resolved once its line's new price is
+ *   applied (it is then reported in `priceChanges`, not `lineErrors`). Show
+ *   the changes before letting the visitor pay.
+ * - `invalid` — problems remain that were not applied (lines flagged with
+ *   `removeUnavailable: false`, a cart-wide error, a `price_changed` with no
+ *   new price to apply, an `update_quantity` that would not lower the line),
+ *   or the server answered `valid: false` and nothing was applied. Never
+ *   `valid` when the server said `valid: false`.
+ * - `empty` — no lines; nothing was sent.
+ * - `failed` — the request failed; the cart was left exactly as it was.
+ */
+type CartValidationStatus = 'valid' | 'adjusted' | 'invalid' | 'empty' | 'failed';
+interface CartValidationOutcome {
+    status: CartValidationStatus;
+    removed: CartRemovedLine[];
+    quantityChanges: CartQuantityChange[];
+    priceChanges: CartPriceChange[];
+    /**
+     * Every line error of the response, keyed by {@link cartLineKey}, except a
+     * `price_changed` resolved by the price refresh (REB-998).
+     */
+    lineErrors: Record<string, ShopCartValidationError>;
+    /** Errors that match no cart line (e.g. `empty_cart`) or were not applied. */
+    unresolvedErrors: ShopCartValidationError[];
+    /** Set when `status` is `'failed'`. */
+    error?: unknown;
+}
+declare const DEFAULT_VALIDATE_CART_ENDPOINT = "/api/shop/validate-cart";
+/** Stable key for a cart line: `productId` + `variantId` (absent and `null` are the same line). */
+declare function cartLineKey(productId: string, variantId?: string | null): string;
+/**
+ * Pure: applies a validate-cart response to a list of lines. Lines the
+ * response does not mention (e.g. added while the request was in flight)
+ * are left untouched.
+ */
+declare function applyCartValidation(items: CartItem[], validation: ShopCartValidation, { removeUnavailable }?: Pick<ValidateCartOptions, 'removeUnavailable'>): Omit<CartValidationOutcome, 'status' | 'error'> & {
+    items: CartItem[];
+};
+/**
+ * Validates the persisted cart against live product, stock and price data
+ * and applies the result to `useCartStore`:
+ *
+ * 1. removes lines the API says to remove, reporting their persisted names;
+ * 2. clamps `insufficient_stock` lines to the quantity still available;
+ * 3. refreshes `unitPrice` (and `maxStock`) from the live data.
+ *
+ * Waits for `CartProvider`'s hydration first, so it never validates the
+ * empty pre-hydration cart. Never throws: a failed request resolves to
+ * `status: 'failed'` and leaves the cart untouched. Running it again on an
+ * already-clean cart is a no-op (`status: 'valid'`).
+ */
+declare function validateCart(options?: ValidateCartOptions): Promise<CartValidationOutcome>;
+
+interface UseCartValidationOptions extends ValidateCartOptions {
+    /** Validate once automatically when the cart has hydrated. Defaults to `true`. */
+    auto?: boolean;
+}
+interface UseCartValidationResult extends Omit<CartValidationOutcome, 'status'> {
+    /** `'idle'` before the first run, `'validating'` while a request is in flight. */
+    status: CartValidationStatus | 'idle' | 'validating';
+    /** The error the last run reported for this line, if any. */
+    getLineError: (productId: string, variantId?: string | null) => ShopCartValidationError | undefined;
+    /**
+     * Runs the validation now (e.g. right before submitting the checkout) and
+     * resolves to its outcome. Concurrent calls share the in-flight request.
+     */
+    revalidate: () => Promise<CartValidationOutcome>;
+}
+/**
+ * `useCartValidation` (REB-981) — runs {@link validateCart} once when the
+ * cart has hydrated (cart page mount) and exposes the last outcome, so the
+ * page can show what was removed or adjusted and mark the offending lines.
+ * Call `revalidate()` before checkout. Later cart edits never re-trigger the
+ * automatic run, so it cannot loop.
+ */
+declare function useCartValidation(options?: UseCartValidationOptions): UseCartValidationResult;
+
+export { type AddItemOutcome, type AddItemStatus, CART_STORAGE_KEY, CART_STORE_PERSIST_VERSION, type CartItem, type CartPriceChange, CartProvider, type CartQuantityChange, type CartRemovedLine, type CartStore, type CartValidationOutcome, type CartValidationStatus, type CartValidator, DEFAULT_VALIDATE_CART_ENDPOINT, type UseCartResult, type UseCartValidationOptions, type UseCartValidationResult, type ValidateCartOptions, __resetCartStoreForTests, applyCartValidation, cartLineKey, useCart, useCartHydrated, useCartStore, useCartValidation, validateCart };

package/dist/cart.d.ts

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as zustand_middleware from 'zustand/middleware';
 import * as zustand from 'zustand';
+import { ShopCartValidationError, ShopValidateCartInput, ShopCartValidation } from '@reblu/site-contracts';
 
 /**
  * `CartProvider` — mount this once near the root layout (inside a Client
@@ -167,4 +168,137 @@ declare function useCartHydrated(): boolean;
  */
 declare function useCart(): UseCartResult;
 
-export { type AddItemOutcome, type AddItemStatus, CART_STORAGE_KEY, CART_STORE_PERSIST_VERSION, type CartItem, CartProvider, type CartStore, type UseCartResult, __resetCartStoreForTests, useCart, useCartHydrated, useCartStore };
+/**
+ * Cart validation (REB-981). A persisted cart (`localStorage` `shop-cart`)
+ * outlives the catalog it was filled from: a product can be deleted,
+ * deactivated, sold out or repriced between visits. `validateCart` asks the
+ * SITE's validate-cart Route Handler (`createShopValidateCartRoute`) about
+ * every line and APPLIES the answer to the store, so the cart page and the
+ * checkout never show or submit a line nobody can buy.
+ */
+/** Calls validate-cart for the given lines. Must reject (or throw) on failure. */
+type CartValidator = (input: ShopValidateCartInput) => Promise<ShopCartValidation>;
+interface ValidateCartOptions {
+    /**
+     * The SITE's validate-cart Route Handler path, used by the default
+     * validator. Defaults to `'/api/shop/validate-cart'`.
+     */
+    endpoint?: string;
+    /** Replaces the default `fetch`-based validator entirely. */
+    validate?: CartValidator;
+    /**
+     * `true` (default) removes lines whose error says `suggestedAction:
+     * 'remove'` (`not_found`, `inactive`, `out_of_stock`). `false` leaves them
+     * in the cart and only reports them through `lineErrors`.
+     */
+    removeUnavailable?: boolean;
+}
+/** A line the validation removed — `name`/`variantName` come from the persisted line. */
+interface CartRemovedLine {
+    productId: string;
+    variantId: string | null;
+    name: string;
+    variantName?: string;
+    type: ShopCartValidationError['type'];
+    message: string;
+}
+/** A line whose quantity was clamped to the stock still available. */
+interface CartQuantityChange {
+    productId: string;
+    variantId: string | null;
+    name: string;
+    variantName?: string;
+    from: number;
+    to: number;
+}
+/** A line whose `unitPrice` (integer cents) was refreshed from the live price. */
+interface CartPriceChange {
+    productId: string;
+    variantId: string | null;
+    name: string;
+    variantName?: string;
+    from: number;
+    to: number;
+}
+/**
+ * - `valid` — every line is buyable as it stands; nothing changed.
+ * - `adjusted` — the cart was changed (lines removed, quantities clamped or
+ *   prices refreshed) and every error was resolved by those changes. A
+ *   `price_changed` error counts as resolved once its line's new price is
+ *   applied (it is then reported in `priceChanges`, not `lineErrors`). Show
+ *   the changes before letting the visitor pay.
+ * - `invalid` — problems remain that were not applied (lines flagged with
+ *   `removeUnavailable: false`, a cart-wide error, a `price_changed` with no
+ *   new price to apply, an `update_quantity` that would not lower the line),
+ *   or the server answered `valid: false` and nothing was applied. Never
+ *   `valid` when the server said `valid: false`.
+ * - `empty` — no lines; nothing was sent.
+ * - `failed` — the request failed; the cart was left exactly as it was.
+ */
+type CartValidationStatus = 'valid' | 'adjusted' | 'invalid' | 'empty' | 'failed';
+interface CartValidationOutcome {
+    status: CartValidationStatus;
+    removed: CartRemovedLine[];
+    quantityChanges: CartQuantityChange[];
+    priceChanges: CartPriceChange[];
+    /**
+     * Every line error of the response, keyed by {@link cartLineKey}, except a
+     * `price_changed` resolved by the price refresh (REB-998).
+     */
+    lineErrors: Record<string, ShopCartValidationError>;
+    /** Errors that match no cart line (e.g. `empty_cart`) or were not applied. */
+    unresolvedErrors: ShopCartValidationError[];
+    /** Set when `status` is `'failed'`. */
+    error?: unknown;
+}
+declare const DEFAULT_VALIDATE_CART_ENDPOINT = "/api/shop/validate-cart";
+/** Stable key for a cart line: `productId` + `variantId` (absent and `null` are the same line). */
+declare function cartLineKey(productId: string, variantId?: string | null): string;
+/**
+ * Pure: applies a validate-cart response to a list of lines. Lines the
+ * response does not mention (e.g. added while the request was in flight)
+ * are left untouched.
+ */
+declare function applyCartValidation(items: CartItem[], validation: ShopCartValidation, { removeUnavailable }?: Pick<ValidateCartOptions, 'removeUnavailable'>): Omit<CartValidationOutcome, 'status' | 'error'> & {
+    items: CartItem[];
+};
+/**
+ * Validates the persisted cart against live product, stock and price data
+ * and applies the result to `useCartStore`:
+ *
+ * 1. removes lines the API says to remove, reporting their persisted names;
+ * 2. clamps `insufficient_stock` lines to the quantity still available;
+ * 3. refreshes `unitPrice` (and `maxStock`) from the live data.
+ *
+ * Waits for `CartProvider`'s hydration first, so it never validates the
+ * empty pre-hydration cart. Never throws: a failed request resolves to
+ * `status: 'failed'` and leaves the cart untouched. Running it again on an
+ * already-clean cart is a no-op (`status: 'valid'`).
+ */
+declare function validateCart(options?: ValidateCartOptions): Promise<CartValidationOutcome>;
+
+interface UseCartValidationOptions extends ValidateCartOptions {
+    /** Validate once automatically when the cart has hydrated. Defaults to `true`. */
+    auto?: boolean;
+}
+interface UseCartValidationResult extends Omit<CartValidationOutcome, 'status'> {
+    /** `'idle'` before the first run, `'validating'` while a request is in flight. */
+    status: CartValidationStatus | 'idle' | 'validating';
+    /** The error the last run reported for this line, if any. */
+    getLineError: (productId: string, variantId?: string | null) => ShopCartValidationError | undefined;
+    /**
+     * Runs the validation now (e.g. right before submitting the checkout) and
+     * resolves to its outcome. Concurrent calls share the in-flight request.
+     */
+    revalidate: () => Promise<CartValidationOutcome>;
+}
+/**
+ * `useCartValidation` (REB-981) — runs {@link validateCart} once when the
+ * cart has hydrated (cart page mount) and exposes the last outcome, so the
+ * page can show what was removed or adjusted and mark the offending lines.
+ * Call `revalidate()` before checkout. Later cart edits never re-trigger the
+ * automatic run, so it cannot loop.
+ */
+declare function useCartValidation(options?: UseCartValidationOptions): UseCartValidationResult;
+
+export { type AddItemOutcome, type AddItemStatus, CART_STORAGE_KEY, CART_STORE_PERSIST_VERSION, type CartItem, type CartPriceChange, CartProvider, type CartQuantityChange, type CartRemovedLine, type CartStore, type CartValidationOutcome, type CartValidationStatus, type CartValidator, DEFAULT_VALIDATE_CART_ENDPOINT, type UseCartResult, type UseCartValidationOptions, type UseCartValidationResult, type ValidateCartOptions, __resetCartStoreForTests, applyCartValidation, cartLineKey, useCart, useCartHydrated, useCartStore, useCartValidation, validateCart };

package/dist/cart.js

@@ -136,13 +136,241 @@ function useCart() {
   const itemCount = items.reduce((sum, item) => sum + item.quantity, 0);
   return { items, total, itemCount, hydrated, addItem, removeItem, updateQuantity, clearCart };
 }
+
+// src/cart/validate.ts
+var DEFAULT_VALIDATE_CART_ENDPOINT = "/api/shop/validate-cart";
+function cartLineKey(productId, variantId) {
+  return JSON.stringify([productId, variantId ?? null]);
+}
+function emptyOutcome(status) {
+  return {
+    status,
+    removed: [],
+    quantityChanges: [],
+    priceChanges: [],
+    lineErrors: {},
+    unresolvedErrors: []
+  };
+}
+function isValidation(value) {
+  if (!value || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.valid === "boolean" && Array.isArray(v.errors) && Array.isArray(v.items);
+}
+function defaultValidator(endpoint) {
+  return async (input) => {
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input)
+    });
+    if (!res.ok) {
+      throw new Error(`validate-cart failed with HTTP ${res.status}`);
+    }
+    const json = await res.json();
+    const data = json && typeof json === "object" ? json.data : void 0;
+    if (!isValidation(data)) {
+      throw new Error("validate-cart returned an unexpected body");
+    }
+    return data;
+  };
+}
+function waitForHydration() {
+  if (useCartStore.persist.hasHydrated()) return Promise.resolve();
+  return new Promise((resolve) => {
+    const unsubscribe = useCartStore.persist.onFinishHydration(() => {
+      unsubscribe();
+      resolve();
+    });
+  });
+}
+function applyCartValidation(items, validation, { removeUnavailable = true } = {}) {
+  const removed = [];
+  const quantityChanges = [];
+  const priceChanges = [];
+  const lineErrors = {};
+  const unresolvedErrors = [];
+  const byKey = new Map(items.map((item) => [cartLineKey(item.productId, item.variantId), item]));
+  const removeKeys = /* @__PURE__ */ new Set();
+  const newQuantity = /* @__PURE__ */ new Map();
+  const priceErrors = /* @__PURE__ */ new Map();
+  for (const error of validation.errors) {
+    const key = cartLineKey(error.productId, error.variantId);
+    const line = byKey.get(key);
+    if (!line) {
+      unresolvedErrors.push(error);
+      continue;
+    }
+    lineErrors[key] = error;
+    if (error.suggestedAction === "remove" && removeUnavailable) {
+      removeKeys.add(key);
+      removed.push({
+        productId: line.productId,
+        variantId: line.variantId ?? null,
+        name: line.name,
+        ...line.variantName !== void 0 && { variantName: line.variantName },
+        type: error.type,
+        message: error.message
+      });
+    } else if (error.type === "price_changed") {
+      priceErrors.set(key, error);
+    } else if (error.suggestedAction === "update_quantity" && typeof error.newQuantity === "number") {
+      newQuantity.set(key, { to: error.newQuantity, error });
+    } else {
+      unresolvedErrors.push(error);
+    }
+  }
+  const live = new Map(
+    validation.items.map((item) => [cartLineKey(item.productId, item.variantId), item])
+  );
+  const next = [];
+  for (const line of items) {
+    const key = cartLineKey(line.productId, line.variantId);
+    if (removeKeys.has(key)) continue;
+    let updated = line;
+    let priceRefreshed = false;
+    const liveItem = live.get(key);
+    if (liveItem) {
+      if (liveItem.unitPrice !== line.unitPrice) {
+        priceRefreshed = true;
+        priceChanges.push({
+          productId: line.productId,
+          variantId: line.variantId ?? null,
+          name: line.name,
+          ...line.variantName !== void 0 && { variantName: line.variantName },
+          from: line.unitPrice,
+          to: liveItem.unitPrice
+        });
+        updated = { ...updated, unitPrice: liveItem.unitPrice };
+      }
+      if (liveItem.maxStock !== line.maxStock) {
+        updated = { ...updated, maxStock: liveItem.maxStock };
+      }
+    }
+    const priceError = priceErrors.get(key);
+    if (priceError) {
+      if (priceRefreshed) {
+        if (lineErrors[key] === priceError) delete lineErrors[key];
+      } else {
+        unresolvedErrors.push(priceError);
+      }
+    }
+    const clamp = newQuantity.get(key);
+    if (clamp !== void 0) {
+      const to = Math.trunc(clamp.to);
+      if (to < 1) {
+        removed.push({
+          productId: line.productId,
+          variantId: line.variantId ?? null,
+          name: line.name,
+          ...line.variantName !== void 0 && { variantName: line.variantName },
+          type: "out_of_stock",
+          message: lineErrors[key]?.message ?? ""
+        });
+        continue;
+      }
+      if (to < line.quantity) {
+        quantityChanges.push({
+          productId: line.productId,
+          variantId: line.variantId ?? null,
+          name: line.name,
+          ...line.variantName !== void 0 && { variantName: line.variantName },
+          from: line.quantity,
+          to
+        });
+        updated = { ...updated, quantity: to };
+      } else {
+        unresolvedErrors.push(clamp.error);
+      }
+    }
+    next.push(updated);
+  }
+  return { items: next, removed, quantityChanges, priceChanges, lineErrors, unresolvedErrors };
+}
+async function validateCart(options = {}) {
+  await waitForHydration();
+  const items = useCartStore.getState().items;
+  if (items.length === 0) return emptyOutcome("empty");
+  const validate = options.validate ?? defaultValidator(options.endpoint ?? DEFAULT_VALIDATE_CART_ENDPOINT);
+  let validation;
+  try {
+    validation = await validate({
+      items: items.map((i) => ({
+        productId: i.productId,
+        variantId: i.variantId,
+        quantity: i.quantity
+      }))
+    });
+  } catch (error) {
+    return { ...emptyOutcome("failed"), error };
+  }
+  const applied = applyCartValidation(useCartStore.getState().items, validation, options);
+  const { items: nextItems, ...report } = applied;
+  const changed = report.removed.length > 0 || report.quantityChanges.length > 0 || report.priceChanges.length > 0;
+  const current = useCartStore.getState().items;
+  if (nextItems.length !== current.length || nextItems.some((item, i) => item !== current[i])) {
+    useCartStore.setState({ items: nextItems });
+  }
+  const status = report.unresolvedErrors.length > 0 ? "invalid" : changed ? "adjusted" : validation.valid ? "valid" : "invalid";
+  return { status, ...report };
+}
+
+// src/cart/use-cart-validation.ts
+import { useCallback, useEffect as useEffect2, useRef, useState } from "react";
+var IDLE = {
+  removed: [],
+  quantityChanges: [],
+  priceChanges: [],
+  lineErrors: {},
+  unresolvedErrors: []
+};
+function useCartValidation(options = {}) {
+  const { auto = true } = options;
+  const hydrated = useCartHydrated();
+  const [status, setStatus] = useState("idle");
+  const [report, setReport] = useState(IDLE);
+  const optionsRef = useRef(options);
+  useEffect2(() => {
+    optionsRef.current = options;
+  });
+  const inFlight = useRef(null);
+  const autoRan = useRef(false);
+  const revalidate = useCallback(() => {
+    if (inFlight.current) return inFlight.current;
+    setStatus("validating");
+    const run = validateCart(optionsRef.current).then((outcome) => {
+      inFlight.current = null;
+      const { status: nextStatus, ...rest } = outcome;
+      setReport(rest);
+      setStatus(nextStatus);
+      return outcome;
+    });
+    inFlight.current = run;
+    return run;
+  }, []);
+  useEffect2(() => {
+    if (!auto || !hydrated || autoRan.current) return;
+    autoRan.current = true;
+    void revalidate();
+  }, [auto, hydrated, revalidate]);
+  const getLineError = useCallback(
+    (productId, variantId) => report.lineErrors[cartLineKey(productId, variantId)],
+    [report]
+  );
+  return { status, ...report, getLineError, revalidate };
+}
 export {
   CART_STORAGE_KEY,
   CART_STORE_PERSIST_VERSION,
   CartProvider,
+  DEFAULT_VALIDATE_CART_ENDPOINT,
   __resetCartStoreForTests,
+  applyCartValidation,
+  cartLineKey,
   useCart,
   useCartHydrated,
-  useCartStore
+  useCartStore,
+  useCartValidation,
+  validateCart
 };
 //# sourceMappingURL=cart.js.map