@wocart/storefront 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ follows [semantic versioning](https://semver.org/): breaking changes ship only
 in a new major version, and an export is marked `@deprecated` for at least one
 minor release before a major removes it.
 
+## 1.5.0 — 2026-10-15
+
+### Added
+
+- **`products.page(filters)`** returns one page of products and whether another
+  follows (`{ items, hasNext }`). It asks the server for one row more than the
+  page, so the answer is exact without a count query. A page is 24 by default
+  and at most 99 (one below the server's 100-row cap). A failed read is an empty
+  final page, as `list` degrades. Themes stop re-deriving paging from `list`.
+- `ProductPage` type.
+- **`rewardUnitPrice`** on an offer: what one gift unit is worth at list price
+  (the gift variant's price, or the gift product's). `getOfferTierView` states
+  the saving at that value and the share of the list value it is. Without it,
+  the product's own price stands in, as before.
+
 ## 1.4.0 — 2026-10-15
 
 ### Added

package/dist/client/products.d.ts

@@ -12,7 +12,11 @@
  * half-shaped product into a theme.
  */
 import { type ClientCore, type ClientResult } from "./core.js";
-import type { Product, ProductList, ProductListFilters, Review, ReviewInput, ReviewListPagination } from "../types.js";
+import type { Product, ProductList, ProductPage, ProductListFilters, Review, ReviewInput, ReviewListPagination } from "../types.js";
+/** Page size when a caller names none — the storefront's default grid. */
+export declare const PRODUCT_PAGE_DEFAULT = 24;
+/** One below the server's 100-row cap, so the extra row that proves a next page fits. */
+export declare const PRODUCT_PAGE_MAX = 99;
 export interface ProductsNamespace {
     /**
      * Get a single product by its public URL handle
@@ -26,6 +30,12 @@ export interface ProductsNamespace {
      * @returns Array of products
      */
     list(filters?: ProductListFilters): Promise<ProductList[]>;
+    /**
+     * One page of products, and whether another page follows. The server is
+     * asked for one row more than the page, so the answer is exact without a
+     * count query. A failed read is an empty final page, as `list` degrades.
+     */
+    page(filters?: ProductListFilters): Promise<ProductPage>;
     /**
      * Reviews sub-namespace
      */

package/dist/client/products.js

@@ -16,10 +16,29 @@ import { IdResponseSchema, ProductListSchema, ProductSchema, ReviewListEnvelopeS
 import { STOREFRONT_OPERATIONS } from "../domain.js";
 import { localizedPath } from "./paths.js";
 import { isNotFoundAnswer, reportDegradedRead } from "./core.js";
+/** Page size when a caller names none — the storefront's default grid. */
+export const PRODUCT_PAGE_DEFAULT = 24;
+/** One below the server's 100-row cap, so the extra row that proves a next page fits. */
+export const PRODUCT_PAGE_MAX = 99;
 /**
  * Create products namespace
  */
 export function createProductsNamespace(core) {
+    const list = async (filters) => {
+        try {
+            const products = await core.get(localizedPath(core.config, "/store/products", {
+                categoryId: filters?.categoryId || undefined,
+                featured: filters?.featured ? "true" : undefined,
+                limit: filters?.limit === undefined ? undefined : String(filters.limit),
+                offset: filters?.offset ? String(filters.offset) : undefined,
+            }), z.array(ProductListSchema), { operation: STOREFRONT_OPERATIONS.productsList });
+            return products ?? [];
+        }
+        catch (error) {
+            reportDegradedRead(core.config, error, "products.list");
+            return [];
+        }
+    };
     return {
         async get(handle) {
             try {
@@ -32,20 +51,11 @@ export function createProductsNamespace(core) {
                 return null;
             }
         },
-        async list(filters) {
-            try {
-                const products = await core.get(localizedPath(core.config, "/store/products", {
-                    categoryId: filters?.categoryId || undefined,
-                    featured: filters?.featured ? "true" : undefined,
-                    limit: filters?.limit === undefined ? undefined : String(filters.limit),
-                    offset: filters?.offset ? String(filters.offset) : undefined,
-                }), z.array(ProductListSchema), { operation: STOREFRONT_OPERATIONS.productsList });
-                return products ?? [];
-            }
-            catch (error) {
-                reportDegradedRead(core.config, error, "products.list");
-                return [];
-            }
+        list,
+        async page(filters) {
+            const size = Math.min(Math.max(1, filters?.limit ?? PRODUCT_PAGE_DEFAULT), PRODUCT_PAGE_MAX);
+            const rows = await list({ ...filters, limit: size + 1 });
+            return { items: rows.slice(0, size), hasNext: rows.length > size };
         },
         reviews: {
             async list(productId, pagination) {

package/dist/offer-view.d.ts

@@ -6,5 +6,5 @@ export interface OfferTierView {
     price: number;
     comparePrice: number | null;
 }
-export type OfferTierInput = Pick<Offer, "discountType" | "triggerQuantity" | "rewardQuantity">;
+export type OfferTierInput = Pick<Offer, "discountType" | "triggerQuantity" | "rewardQuantity" | "rewardUnitPrice">;
 export declare function getOfferTierView(offer: OfferTierInput, basePrice: number, comparePrice: number | null): OfferTierView;

package/dist/offer-view.js

@@ -1,13 +1,17 @@
 export function getOfferTierView(offer, basePrice, comparePrice) {
     const isFreeShipping = offer.discountType === "free_shipping";
-    const quantityTotal = offer.triggerQuantity + offer.rewardQuantity;
+    // A gift that is another product (or a variant priced apart) is worth its own
+    // price; without one, the product's price stands in for it.
+    const giftPrice = offer.rewardUnitPrice ?? basePrice;
+    const savingsAmount = isFreeShipping ? 0 : offer.rewardQuantity * giftPrice;
+    const price = basePrice * offer.triggerQuantity;
+    // The share of what the shopper would have paid for everything, gifts included.
+    const listValue = price + savingsAmount;
     return {
         isFreeShipping,
-        savePct: isFreeShipping || quantityTotal <= 0
-            ? 0
-            : Math.round((offer.rewardQuantity / quantityTotal) * 100),
-        savingsAmount: isFreeShipping ? 0 : offer.rewardQuantity * basePrice,
-        price: basePrice * offer.triggerQuantity,
+        savePct: isFreeShipping || listValue <= 0 ? 0 : Math.round((savingsAmount / listValue) * 100),
+        savingsAmount,
+        price,
         comparePrice: comparePrice === null ? null : comparePrice * offer.triggerQuantity,
     };
 }

package/dist/schemas.d.ts

@@ -41,6 +41,7 @@ export declare const OfferSchema: z.ZodObject<{
     rewardProductName: z.ZodString;
     rewardVariantId: z.ZodNullable<z.ZodString>;
     rewardVariantLabel: z.ZodNullable<z.ZodString>;
+    rewardUnitPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 export declare const CategorySchema: z.ZodObject<{
     id: z.ZodString;
@@ -214,6 +215,7 @@ export declare const ProductSchema: z.ZodObject<{
         rewardProductName: z.ZodString;
         rewardVariantId: z.ZodNullable<z.ZodString>;
         rewardVariantLabel: z.ZodNullable<z.ZodString>;
+        rewardUnitPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const StorePagePublicSchema: z.ZodObject<{
@@ -617,6 +619,7 @@ export declare const LandingPageSchema: z.ZodObject<{
             rewardProductName: z.ZodString;
             rewardVariantId: z.ZodNullable<z.ZodString>;
             rewardVariantLabel: z.ZodNullable<z.ZodString>;
+            rewardUnitPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     tracking: z.ZodObject<{

package/dist/schemas.js

@@ -38,6 +38,9 @@ export const OfferSchema = z.object({
     rewardProductName: z.string(),
     rewardVariantId: z.string().nullable(),
     rewardVariantLabel: z.string().nullable(),
+    // What one gift unit is worth at list price. Optional: a server that predates
+    // it omits the field, and the product's own price stands in for the gift.
+    rewardUnitPrice: z.number().nullish(),
 });
 const productCategorySchema = z.object({
     id: z.string(),

package/dist/types.d.ts

@@ -415,6 +415,12 @@ export interface ProductListFilters {
     /** Products to skip — with `limit`, pages through the whole catalog. */
     offset?: number;
 }
+/** One page of products from `products.page()`. */
+export interface ProductPage {
+    items: ProductList[];
+    /** True when another page follows this one. */
+    hasNext: boolean;
+}
 /** `products.reviews.list()` paging — named for the same reason. */
 export interface ReviewListPagination {
     limit?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/storefront",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",