@reblu/site-next 1.12.0 → 1.14.0

package/dist/cart.d.ts

@@ -0,0 +1,92 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as zustand_middleware from 'zustand/middleware';
+import * as zustand from 'zustand';
+
+/**
+ * `CartProvider` — mount this once near the root layout (inside a Client
+ * Component boundary). It owns the ONE explicit-hydration call
+ * `useCartStore.persist.rehydrate()` requires (`store.ts`'s `skipHydration`
+ * doc) — a SITE that forgets to mount it gets an always-empty cart that never
+ * reads back whatever a previous visit (or page reload) persisted.
+ */
+declare function CartProvider({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * `useCartStore` — the SDK's cart state (REB-829). Ported verbatim (same
+ * shape, same quantity-clamping rules) from demo-site's local
+ * `lib/store/cart-store.ts`, which every SITE was otherwise expected to
+ * hand-copy. `CART_STORAGE_KEY` stays exactly `'shop-cart'` on purpose: a
+ * SITE migrating from the local copy keeps its visitors' existing carts.
+ *
+ * `skipHydration: true` (zustand persist) is load-bearing for SSR: without
+ * it, zustand's persist middleware reads `localStorage` synchronously during
+ * module evaluation, which throws (or silently desyncs) on the server. The
+ * `CartProvider` (`./provider`) calls `useCartStore.persist.rehydrate()`
+ * inside a `useEffect`, so hydration only ever happens client-side, after
+ * mount — the same explicit-hydration contract the SITE README documents.
+ */
+declare const CART_STORAGE_KEY = "shop-cart";
+interface CartItem {
+    productId: string;
+    variantId?: string | null;
+    name: string;
+    variantName?: string;
+    /** Integer cents — every Reblu shop price travels as cents, never a float. */
+    unitPrice: number;
+    quantity: number;
+    imageUrl?: string;
+    /** `null` means untracked/unlimited stock — never clamp against it. */
+    maxStock: number | null;
+    /** Basis points, e.g. `2100` = 21%. `null`/`undefined` = unknown or exempt. */
+    taxRateBps?: number | null;
+    taxRateName?: string | null;
+}
+interface CartStore {
+    items: CartItem[];
+    addItem: (item: CartItem) => void;
+    removeItem: (productId: string, variantId?: string | null) => void;
+    updateQuantity: (productId: string, variantId: string | null | undefined, quantity: number) => void;
+    clearCart: () => void;
+    getTotal: () => number;
+    getItemCount: () => number;
+}
+declare const useCartStore: zustand.UseBoundStore<Omit<zustand.StoreApi<CartStore>, "setState" | "persist"> & {
+    setState(partial: CartStore | Partial<CartStore> | ((state: CartStore) => CartStore | Partial<CartStore>), replace?: false | undefined): unknown;
+    setState(state: CartStore | ((state: CartStore) => CartStore), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<zustand_middleware.PersistOptions<CartStore, CartStore, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: CartStore) => void) => () => void;
+        onFinishHydration: (fn: (state: CartStore) => void) => () => void;
+        getOptions: () => Partial<zustand_middleware.PersistOptions<CartStore, CartStore, unknown>>;
+    };
+}>;
+
+interface UseCartResult {
+    items: CartItem[];
+    /** Sum of every line's `unitPrice * quantity`, in integer cents. */
+    total: number;
+    /** Sum of every line's `quantity`. */
+    itemCount: number;
+    addItem: (item: CartItem) => void;
+    removeItem: (productId: string, variantId?: string | null) => void;
+    updateQuantity: (productId: string, variantId: string | null | undefined, quantity: number) => void;
+    clearCart: () => void;
+}
+/**
+ * `useCart` — the ergonomic entry point for a SITE's cart UI: a single
+ * selector call that re-renders only on `items` changes, with `total`/
+ * `itemCount` derived inline (cheap — a plain `reduce` over a typically-small
+ * array) rather than via `useCartStore`'s own `getTotal`/`getItemCount`
+ * selectors, which are stable function references and would NOT trigger a
+ * re-render on their own. A SITE that wants raw store access (existing
+ * per-field selectors, e.g. `useCartStore((s) => s.addItem)`) can still
+ * import `useCartStore` directly — this hook doesn't replace it.
+ */
+declare function useCart(): UseCartResult;
+
+export { CART_STORAGE_KEY, type CartItem, CartProvider, type CartStore, type UseCartResult, useCart, useCartStore };

package/dist/cart.js

@@ -0,0 +1,108 @@
+"use client";
+
+// src/cart/provider.tsx
+import { useEffect } from "react";
+
+// src/cart/store.ts
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+var CART_STORAGE_KEY = "shop-cart";
+function isSameItem(a, productId, variantId) {
+  return a.productId === productId && (a.variantId ?? null) === (variantId ?? null);
+}
+function normalizeQuantity(quantity, maxStock) {
+  if (!Number.isFinite(quantity)) return 0;
+  const truncated = Math.trunc(quantity);
+  if (truncated < 1) return 0;
+  if (maxStock === null) return truncated;
+  const maxTruncated = Math.trunc(maxStock);
+  if (maxTruncated < 1) return 0;
+  return Math.min(truncated, maxTruncated);
+}
+var useCartStore = create()(
+  persist(
+    (set, get) => ({
+      items: [],
+      addItem: (item) => {
+        set((state) => {
+          const existing = state.items.find((i) => isSameItem(i, item.productId, item.variantId));
+          if (existing) {
+            if (item.maxStock !== null && Math.trunc(item.maxStock) < 1) {
+              return {
+                items: state.items.filter((i) => !isSameItem(i, item.productId, item.variantId))
+              };
+            }
+            const newQty = normalizeQuantity(existing.quantity + item.quantity, item.maxStock);
+            if (newQty < 1) {
+              return {};
+            }
+            return {
+              items: state.items.map(
+                (i) => isSameItem(i, item.productId, item.variantId) ? { ...i, quantity: newQty, maxStock: item.maxStock } : i
+              )
+            };
+          }
+          const qty = normalizeQuantity(item.quantity, item.maxStock);
+          if (qty < 1) {
+            return {};
+          }
+          return { items: [...state.items, { ...item, quantity: qty }] };
+        });
+      },
+      removeItem: (productId, variantId) => {
+        set((state) => ({
+          items: state.items.filter((i) => !isSameItem(i, productId, variantId))
+        }));
+      },
+      updateQuantity: (productId, variantId, quantity) => {
+        const existing = get().items.find((i) => isSameItem(i, productId, variantId));
+        if (!existing) return;
+        const newQty = normalizeQuantity(quantity, existing.maxStock);
+        if (newQty < 1) {
+          get().removeItem(productId, variantId);
+          return;
+        }
+        set((state) => ({
+          items: state.items.map(
+            (i) => isSameItem(i, productId, variantId) ? { ...i, quantity: newQty } : i
+          )
+        }));
+      },
+      clearCart: () => set({ items: [] }),
+      getTotal: () => get().items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0),
+      getItemCount: () => get().items.reduce((sum, item) => sum + item.quantity, 0)
+    }),
+    {
+      name: CART_STORAGE_KEY,
+      skipHydration: true
+    }
+  )
+);
+
+// src/cart/provider.tsx
+import { Fragment, jsx } from "react/jsx-runtime";
+function CartProvider({ children }) {
+  useEffect(() => {
+    useCartStore.persist.rehydrate();
+  }, []);
+  return /* @__PURE__ */ jsx(Fragment, { children });
+}
+
+// src/cart/use-cart.ts
+function useCart() {
+  const items = useCartStore((s) => s.items);
+  const addItem = useCartStore((s) => s.addItem);
+  const removeItem = useCartStore((s) => s.removeItem);
+  const updateQuantity = useCartStore((s) => s.updateQuantity);
+  const clearCart = useCartStore((s) => s.clearCart);
+  const total = items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0);
+  const itemCount = items.reduce((sum, item) => sum + item.quantity, 0);
+  return { items, total, itemCount, addItem, removeItem, updateQuantity, clearCart };
+}
+export {
+  CART_STORAGE_KEY,
+  CartProvider,
+  useCart,
+  useCartStore
+};
+//# sourceMappingURL=cart.js.map

package/dist/cart.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cart/provider.tsx","../src/cart/store.ts","../src/cart/use-cart.ts"],"sourcesContent":["'use client'\n\nimport { useEffect } from 'react'\nimport { useCartStore } from './store'\n\n/**\n * `CartProvider` — mount this once near the root layout (inside a Client\n * Component boundary). It owns the ONE explicit-hydration call\n * `useCartStore.persist.rehydrate()` requires (`store.ts`'s `skipHydration`\n * doc) — a SITE that forgets to mount it gets an always-empty cart that never\n * reads back whatever a previous visit (or page reload) persisted.\n */\nexport function CartProvider({ children }: { children: React.ReactNode }) {\n  useEffect(() => {\n    useCartStore.persist.rehydrate()\n  }, [])\n\n  return <>{children}</>\n}\n","import { create } from 'zustand'\nimport { persist } from 'zustand/middleware'\n\n/**\n * `useCartStore` — the SDK's cart state (REB-829). Ported verbatim (same\n * shape, same quantity-clamping rules) from demo-site's local\n * `lib/store/cart-store.ts`, which every SITE was otherwise expected to\n * hand-copy. `CART_STORAGE_KEY` stays exactly `'shop-cart'` on purpose: a\n * SITE migrating from the local copy keeps its visitors' existing carts.\n *\n * `skipHydration: true` (zustand persist) is load-bearing for SSR: without\n * it, zustand's persist middleware reads `localStorage` synchronously during\n * module evaluation, which throws (or silently desyncs) on the server. The\n * `CartProvider` (`./provider`) calls `useCartStore.persist.rehydrate()`\n * inside a `useEffect`, so hydration only ever happens client-side, after\n * mount — the same explicit-hydration contract the SITE README documents.\n */\nexport const CART_STORAGE_KEY = 'shop-cart'\n\nexport interface CartItem {\n  productId: string\n  variantId?: string | null\n  name: string\n  variantName?: string\n  /** Integer cents — every Reblu shop price travels as cents, never a float. */\n  unitPrice: number\n  quantity: number\n  imageUrl?: string\n  /** `null` means untracked/unlimited stock — never clamp against it. */\n  maxStock: number | null\n  /** Basis points, e.g. `2100` = 21%. `null`/`undefined` = unknown or exempt. */\n  taxRateBps?: number | null\n  taxRateName?: string | null\n}\n\nexport interface CartStore {\n  items: CartItem[]\n  addItem: (item: CartItem) => void\n  removeItem: (productId: string, variantId?: string | null) => void\n  updateQuantity: (\n    productId: string,\n    variantId: string | null | undefined,\n    quantity: number,\n  ) => void\n  clearCart: () => void\n  getTotal: () => number\n  getItemCount: () => number\n}\n\nfunction isSameItem(a: CartItem, productId: string, variantId?: string | null): boolean {\n  return a.productId === productId && (a.variantId ?? null) === (variantId ?? null)\n}\n\n/**\n * REB-829 review finding: neither `addItem` nor `updateQuantity` validated\n * `quantity` — `0`, a negative number, `NaN` (e.g. a stray `parseInt('')`\n * upstream), a non-integer, or `maxStock` itself being `0` (out of stock)\n * all used to leave an invalid line sitting in the cart, silently reaching\n * checkout.\n *\n * Normalizes to a safe POSITIVE INTEGER clamped to `maxStock`. Returns `0`\n * to signal \"not a valid positive quantity\" — callers decide what that\n * means for them: `addItem` ignores the call (never creates/corrupts a\n * line), `updateQuantity` removes the line (same as its pre-existing\n * `quantity <= 0` → remove contract, just now reached by more inputs).\n *\n * `Math.trunc` rounds toward zero (not `Math.floor`, which would round a\n * negative input further negative before the `< 1` check below ever saw it\n * — not a behavioural difference here since any negative result is\n * rejected either way, but `trunc` is the operation that actually means\n * \"drop the fractional part\").\n */\nfunction normalizeQuantity(quantity: number, maxStock: number | null): number {\n  if (!Number.isFinite(quantity)) return 0\n  const truncated = Math.trunc(quantity)\n  if (truncated < 1) return 0\n  if (maxStock === null) return truncated\n  const maxTruncated = Math.trunc(maxStock)\n  if (maxTruncated < 1) return 0\n  return Math.min(truncated, maxTruncated)\n}\n\nexport const useCartStore = create<CartStore>()(\n  persist(\n    (set, get) => ({\n      items: [],\n\n      addItem: (item) => {\n        set((state) => {\n          const existing = state.items.find((i) => isSameItem(i, item.productId, item.variantId))\n\n          if (existing) {\n            // REB-829 review follow-up (a): incoming maxStock is the\n            // FRESHEST stock signal available — if it says 0, the product is\n            // confirmed out of stock right now, so the existing line is\n            // removed outright (same contract as updateQuantity's own\n            // \"quantity resolves to <1 → remove\"), not merely left alone.\n            if (item.maxStock !== null && Math.trunc(item.maxStock) < 1) {\n              return {\n                items: state.items.filter((i) => !isSameItem(i, item.productId, item.variantId)),\n              }\n            }\n\n            const newQty = normalizeQuantity(existing.quantity + item.quantity, item.maxStock)\n            if (newQty < 1) {\n              // Invalid delta (NaN/non-positive quantity) — leave the\n              // existing, previously-valid line untouched rather than\n              // destroying good data because of one bad call.\n              return {}\n            }\n\n            // Refresh maxStock with the incoming value on every successful\n            // merge — the stale-maxStock finding: a stored line used to keep\n            // its ORIGINAL maxStock forever, so a later updateQuantity call\n            // clamped against stock data that could be long out of date.\n            return {\n              items: state.items.map((i) =>\n                isSameItem(i, item.productId, item.variantId)\n                  ? { ...i, quantity: newQty, maxStock: item.maxStock }\n                  : i,\n              ),\n            }\n          }\n\n          const qty = normalizeQuantity(item.quantity, item.maxStock)\n          if (qty < 1) {\n            // Invalid quantity, or maxStock 0 (out of stock) — never create\n            // a line nobody could actually buy.\n            return {}\n          }\n\n          return { items: [...state.items, { ...item, quantity: qty }] }\n        })\n      },\n\n      removeItem: (productId, variantId) => {\n        set((state) => ({\n          items: state.items.filter((i) => !isSameItem(i, productId, variantId)),\n        }))\n      },\n\n      updateQuantity: (productId, variantId, quantity) => {\n        const existing = get().items.find((i) => isSameItem(i, productId, variantId))\n        if (!existing) return\n\n        const newQty = normalizeQuantity(quantity, existing.maxStock)\n        if (newQty < 1) {\n          get().removeItem(productId, variantId)\n          return\n        }\n\n        set((state) => ({\n          items: state.items.map((i) =>\n            isSameItem(i, productId, variantId) ? { ...i, quantity: newQty } : i,\n          ),\n        }))\n      },\n\n      clearCart: () => set({ items: [] }),\n\n      getTotal: () => get().items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0),\n\n      getItemCount: () => get().items.reduce((sum, item) => sum + item.quantity, 0),\n    }),\n    {\n      name: CART_STORAGE_KEY,\n      skipHydration: true,\n    },\n  ),\n)\n","'use client'\n\nimport { useCartStore, type CartItem } from './store'\n\nexport interface UseCartResult {\n  items: CartItem[]\n  /** Sum of every line's `unitPrice * quantity`, in integer cents. */\n  total: number\n  /** Sum of every line's `quantity`. */\n  itemCount: number\n  addItem: (item: CartItem) => void\n  removeItem: (productId: string, variantId?: string | null) => void\n  updateQuantity: (\n    productId: string,\n    variantId: string | null | undefined,\n    quantity: number,\n  ) => void\n  clearCart: () => void\n}\n\n/**\n * `useCart` — the ergonomic entry point for a SITE's cart UI: a single\n * selector call that re-renders only on `items` changes, with `total`/\n * `itemCount` derived inline (cheap — a plain `reduce` over a typically-small\n * array) rather than via `useCartStore`'s own `getTotal`/`getItemCount`\n * selectors, which are stable function references and would NOT trigger a\n * re-render on their own. A SITE that wants raw store access (existing\n * per-field selectors, e.g. `useCartStore((s) => s.addItem)`) can still\n * import `useCartStore` directly — this hook doesn't replace it.\n */\nexport function useCart(): UseCartResult {\n  const items = useCartStore((s) => s.items)\n  const addItem = useCartStore((s) => s.addItem)\n  const removeItem = useCartStore((s) => s.removeItem)\n  const updateQuantity = useCartStore((s) => s.updateQuantity)\n  const clearCart = useCartStore((s) => s.clearCart)\n\n  const total = items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0)\n  const itemCount = items.reduce((sum, item) => sum + item.quantity, 0)\n\n  return { items, total, itemCount, addItem, removeItem, updateQuantity, clearCart }\n}\n"],"mappings":"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","names":[]}

package/dist/collection-BE5dhf-r.d.cts

@@ -0,0 +1,106 @@
+import { ShopProductsParams, ListResult, RebluClient } from '@reblu/site-client';
+import { ShopProductListItem, ShopFacets } from '@reblu/site-contracts';
+
+/**
+ * Parse a `URLSearchParams` (or anything with that shape — `ReadonlyURLSearchParams`
+ * from `next/navigation`, or a plain `new URLSearchParams(record)`) into
+ * `ShopProductsParams`. Hostile/unknown params are dropped: only the known
+ * scalar keys and the two bracket groups are ever read.
+ */
+declare function parseShopSearchParams(searchParams: URLSearchParams): ShopProductsParams;
+/**
+ * Serialize `ShopProductsParams` into a `URLSearchParams` — the inverse of
+ * {@link parseShopSearchParams}. Falsy/empty/undefined fields are omitted, so
+ * `parseShopSearchParams(serializeShopParams(params))` round-trips to `params`
+ * for any already-canonical (non-empty-string, in-range) input — that is the
+ * property the round-trip tests pin.
+ */
+declare function serializeShopParams(params: ShopProductsParams): URLSearchParams;
+/**
+ * Convert Next's `searchParams` route prop —
+ * `Record<string, string | string[] | undefined>`, already URL-decoded, with
+ * a repeated query key grouped into an array — into a `URLSearchParams` for
+ * {@link parseShopSearchParams}.
+ *
+ * NOT the same as `new URLSearchParams(searchParams)`: the native
+ * `URLSearchParams` constructor only accepts `Record<string, string>` —
+ * handed an array value (`{ 'attr[color]': ['red', 'blue'] }`), it calls
+ * `String()` on it, producing ONE entry `attr[color]=red,blue` instead of two
+ * repeated `attr[color]=red` / `attr[color]=blue` entries. That silently
+ * breaks `parseShopSearchParams`'s repeat-count-based array/scalar
+ * distinction (see its own module doc) for every multi-value `attr[<key>]`
+ * filter — this helper is what actually preserves the repeat.
+ */
+declare function toURLSearchParams(searchParams: Record<string, string | string[] | undefined>): URLSearchParams;
+/**
+ * The navigation seam `@reblu/site-blocks`'s `ShopFilters` calls `hrefs` — kept
+ * structurally identical to its `ShopFiltersHrefs` type WITHOUT a package
+ * dependency on `@reblu/site-blocks` (this package has none today, and this
+ * one shape does not warrant adding one). Any object matching this shape is
+ * assignable to `ShopFiltersHrefs` by structural typing.
+ */
+interface ShopFilterHrefs {
+    taxonomy: (axisKey: string, value: string | undefined) => string;
+    attr: (fieldKey: string, value: string) => string;
+    price: (min: number | undefined, max: number | undefined) => string;
+    onSale: (nextActive: boolean) => string;
+    clearAll: () => string;
+}
+/**
+ * Build `ShopFilters`' href set from the CURRENT params and pathname. Every
+ * href preserves every OTHER current param (category, q, sort, every other
+ * taxonomy/attr filter) and resets pagination (`page`) — a filter change is
+ * never silently stuck on page 4 of a now-smaller result set.
+ *
+ * Pure and framework-agnostic (no `next/navigation`): a Server Component calls
+ * it directly with its own `searchParams` prop and route pathname — no
+ * `'use client'` boundary required. See `./use-shop-filter-links` for the
+ * client-side hook that wraps this with `usePathname`/`useSearchParams`.
+ */
+declare function buildShopFilterHrefs(current: ShopProductsParams, pathname: string): ShopFilterHrefs;
+
+/**
+ * `getShopCollection` (REB-809) — fetches the product list AND its facets with
+ * the EXACT SAME params in one call. This is the seam that keeps a shop
+ * collection page correct: facet counts must reflect the same filter context
+ * the product list is showing, and a hand-rolled page that calls
+ * `client.shop.products(params)` and `client.shop.facets(someOtherParams)`
+ * separately is exactly how they drift apart.
+ *
+ * Server-safe (no `'use client'`, no React) — call it directly from an async
+ * Server Component (route `page.tsx`) with the params parsed via
+ * {@link parseShopSearchParams} from that page's `searchParams` prop.
+ */
+interface ShopCollection {
+    products: ListResult<ShopProductListItem>;
+    facets: ShopFacets;
+    /**
+     * R3-002: `'ok'` when `client.shop.facets(...)` actually succeeded;
+     * `'unavailable'` when it failed and `facets` above is the degraded
+     * {@link EMPTY_FACETS} fallback. NOT silent — check this before treating an
+     * empty `facets` as "this tenant configured no filterable axes" when it may
+     * really mean "the facets endpoint is down right now". A logged
+     * `console.warn` (see below) covers the case nobody checks this field.
+     */
+    facetsStatus: 'ok' | 'unavailable';
+}
+/**
+ * R4-facets-failure-takes-down-listing: `products` and `facets` are NOT
+ * equally critical. A product listing with no products is not a listing —
+ * that failure must propagate so the caller's own error handling (or a
+ * thrown-away `try/catch` degrading the whole page) sees it. A product
+ * listing with no FACETS is still a perfectly good listing, just without
+ * filter UI — degrading `facets` to {@link EMPTY_FACETS} on failure, instead
+ * of letting one upstream endpoint's outage take the other down too, is what
+ * `Promise.allSettled` (rather than `Promise.all`) buys here.
+ *
+ * R3-002: that degradation must not be SILENT. `console.warn`, bracket-tagged
+ * `[getShopCollection]` — the same convention `@reblu/site-next` already uses
+ * elsewhere (`route-handlers.ts`'s `[createProxyRoute]`,
+ * `set-password.tsx`'s `[SetPassword]`) — fires once per failed call, and the
+ * returned `facetsStatus: 'unavailable'` lets a caller that wants to act on
+ * it (retry, surface a banner, alert) do so without parsing a log line.
+ */
+declare function getShopCollection(client: RebluClient, params?: ShopProductsParams): Promise<ShopCollection>;
+
+export { type ShopFilterHrefs as S, type ShopCollection as a, buildShopFilterHrefs as b, getShopCollection as g, parseShopSearchParams as p, serializeShopParams as s, toURLSearchParams as t };

package/dist/collection-BE5dhf-r.d.ts

@@ -0,0 +1,106 @@
+import { ShopProductsParams, ListResult, RebluClient } from '@reblu/site-client';
+import { ShopProductListItem, ShopFacets } from '@reblu/site-contracts';
+
+/**
+ * Parse a `URLSearchParams` (or anything with that shape — `ReadonlyURLSearchParams`
+ * from `next/navigation`, or a plain `new URLSearchParams(record)`) into
+ * `ShopProductsParams`. Hostile/unknown params are dropped: only the known
+ * scalar keys and the two bracket groups are ever read.
+ */
+declare function parseShopSearchParams(searchParams: URLSearchParams): ShopProductsParams;
+/**
+ * Serialize `ShopProductsParams` into a `URLSearchParams` — the inverse of
+ * {@link parseShopSearchParams}. Falsy/empty/undefined fields are omitted, so
+ * `parseShopSearchParams(serializeShopParams(params))` round-trips to `params`
+ * for any already-canonical (non-empty-string, in-range) input — that is the
+ * property the round-trip tests pin.
+ */
+declare function serializeShopParams(params: ShopProductsParams): URLSearchParams;
+/**
+ * Convert Next's `searchParams` route prop —
+ * `Record<string, string | string[] | undefined>`, already URL-decoded, with
+ * a repeated query key grouped into an array — into a `URLSearchParams` for
+ * {@link parseShopSearchParams}.
+ *
+ * NOT the same as `new URLSearchParams(searchParams)`: the native
+ * `URLSearchParams` constructor only accepts `Record<string, string>` —
+ * handed an array value (`{ 'attr[color]': ['red', 'blue'] }`), it calls
+ * `String()` on it, producing ONE entry `attr[color]=red,blue` instead of two
+ * repeated `attr[color]=red` / `attr[color]=blue` entries. That silently
+ * breaks `parseShopSearchParams`'s repeat-count-based array/scalar
+ * distinction (see its own module doc) for every multi-value `attr[<key>]`
+ * filter — this helper is what actually preserves the repeat.
+ */
+declare function toURLSearchParams(searchParams: Record<string, string | string[] | undefined>): URLSearchParams;
+/**
+ * The navigation seam `@reblu/site-blocks`'s `ShopFilters` calls `hrefs` — kept
+ * structurally identical to its `ShopFiltersHrefs` type WITHOUT a package
+ * dependency on `@reblu/site-blocks` (this package has none today, and this
+ * one shape does not warrant adding one). Any object matching this shape is
+ * assignable to `ShopFiltersHrefs` by structural typing.
+ */
+interface ShopFilterHrefs {
+    taxonomy: (axisKey: string, value: string | undefined) => string;
+    attr: (fieldKey: string, value: string) => string;
+    price: (min: number | undefined, max: number | undefined) => string;
+    onSale: (nextActive: boolean) => string;
+    clearAll: () => string;
+}
+/**
+ * Build `ShopFilters`' href set from the CURRENT params and pathname. Every
+ * href preserves every OTHER current param (category, q, sort, every other
+ * taxonomy/attr filter) and resets pagination (`page`) — a filter change is
+ * never silently stuck on page 4 of a now-smaller result set.
+ *
+ * Pure and framework-agnostic (no `next/navigation`): a Server Component calls
+ * it directly with its own `searchParams` prop and route pathname — no
+ * `'use client'` boundary required. See `./use-shop-filter-links` for the
+ * client-side hook that wraps this with `usePathname`/`useSearchParams`.
+ */
+declare function buildShopFilterHrefs(current: ShopProductsParams, pathname: string): ShopFilterHrefs;
+
+/**
+ * `getShopCollection` (REB-809) — fetches the product list AND its facets with
+ * the EXACT SAME params in one call. This is the seam that keeps a shop
+ * collection page correct: facet counts must reflect the same filter context
+ * the product list is showing, and a hand-rolled page that calls
+ * `client.shop.products(params)` and `client.shop.facets(someOtherParams)`
+ * separately is exactly how they drift apart.
+ *
+ * Server-safe (no `'use client'`, no React) — call it directly from an async
+ * Server Component (route `page.tsx`) with the params parsed via
+ * {@link parseShopSearchParams} from that page's `searchParams` prop.
+ */
+interface ShopCollection {
+    products: ListResult<ShopProductListItem>;
+    facets: ShopFacets;
+    /**
+     * R3-002: `'ok'` when `client.shop.facets(...)` actually succeeded;
+     * `'unavailable'` when it failed and `facets` above is the degraded
+     * {@link EMPTY_FACETS} fallback. NOT silent — check this before treating an
+     * empty `facets` as "this tenant configured no filterable axes" when it may
+     * really mean "the facets endpoint is down right now". A logged
+     * `console.warn` (see below) covers the case nobody checks this field.
+     */
+    facetsStatus: 'ok' | 'unavailable';
+}
+/**
+ * R4-facets-failure-takes-down-listing: `products` and `facets` are NOT
+ * equally critical. A product listing with no products is not a listing —
+ * that failure must propagate so the caller's own error handling (or a
+ * thrown-away `try/catch` degrading the whole page) sees it. A product
+ * listing with no FACETS is still a perfectly good listing, just without
+ * filter UI — degrading `facets` to {@link EMPTY_FACETS} on failure, instead
+ * of letting one upstream endpoint's outage take the other down too, is what
+ * `Promise.allSettled` (rather than `Promise.all`) buys here.
+ *
+ * R3-002: that degradation must not be SILENT. `console.warn`, bracket-tagged
+ * `[getShopCollection]` — the same convention `@reblu/site-next` already uses
+ * elsewhere (`route-handlers.ts`'s `[createProxyRoute]`,
+ * `set-password.tsx`'s `[SetPassword]`) — fires once per failed call, and the
+ * returned `facetsStatus: 'unavailable'` lets a caller that wants to act on
+ * it (retry, surface a banner, alert) do so without parsing a log line.
+ */
+declare function getShopCollection(client: RebluClient, params?: ShopProductsParams): Promise<ShopCollection>;
+
+export { type ShopFilterHrefs as S, type ShopCollection as a, buildShopFilterHrefs as b, getShopCollection as g, parseShopSearchParams as p, serializeShopParams as s, toURLSearchParams as t };