@wocart/storefront 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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
+
+- **`cart.quote(lines, { destination })`** quotes what an order would cost for
+  a basket, or for one product exactly as its order form posts it: a quantity,
+  a variant per unit (`variantSelections`), an offer tier (`offerId`). The
+  server builds the lines the way the order does, so a product page's delivery
+  and total are the order's own. `validate(items, options)` is now its basket
+  form.
+- `ProductQuoteInputSchema`, `CartQuoteLinesSchema` and the `ProductQuoteInput`
+  and `CartQuoteLines` types.
+- The `cartValidate` route accepts a product form as well as a basket, each
+  with an optional `destination`.
+
 ## 1.3.0 — 2026-10-15
 
 ### Added

package/dist/client/cart.d.ts

@@ -13,7 +13,7 @@
  */
 import type { ClientCore, ClientResult } from "./core.js";
 import type { CartValidation } from "../types.js";
-import type { BasketLineInput, DeliveryDestination } from "../domain.js";
+import type { BasketLineInput, CartQuoteLines, DeliveryDestination } from "../domain.js";
 export interface CartNamespace {
     /**
      * Re-price and re-check a basket against the live catalog.
@@ -29,6 +29,14 @@ export interface CartNamespace {
     validate(items: readonly BasketLineInput[], options?: {
         destination?: DeliveryDestination;
     }): Promise<ClientResult<CartValidation>>;
+    /**
+     * Quote what an order would cost, for a basket or for one product exactly as
+     * its order form posts it (quantity, variants per unit, offer tier). The lines
+     * are built the way the order builds them, so the quote and the order agree.
+     */
+    quote(lines: CartQuoteLines, options?: {
+        destination?: DeliveryDestination;
+    }): Promise<ClientResult<CartValidation>>;
 }
 /**
  * Create cart namespace

package/dist/client/cart.js

@@ -18,10 +18,13 @@ import { localizedPath } from "./paths.js";
  * Create cart namespace
  */
 export function createCartNamespace(core) {
+    // A closure rather than `this`: a theme may destructure `store.cart`.
+    const quote = async (lines, options) => {
+        const destination = options?.destination;
+        return core.post(localizedPath(core.config, "/store/cart/validate"), destination ? { ...lines, destination } : lines, { schema: CartValidationSchema, operation: STOREFRONT_OPERATIONS.cartValidate });
+    };
     return {
-        async validate(items, options) {
-            const destination = options?.destination;
-            return core.post(localizedPath(core.config, "/store/cart/validate"), destination ? { items, destination } : { items }, { schema: CartValidationSchema, operation: STOREFRONT_OPERATIONS.cartValidate });
-        },
+        validate: (items, options) => quote({ items: [...items] }, options),
+        quote,
     };
 }

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/domain.d.ts

@@ -175,6 +175,48 @@ export declare const AbandonedCheckoutInputSchema: z.ZodObject<{
  * `items[]` line: absent — not null — is the common wire shape.
  */
 export type AbandonedCheckoutInput = z.infer<typeof AbandonedCheckoutInputSchema>;
+/**
+ * One product as a product page's order form posts it: a quantity, or a
+ * variant chosen per unit, and an offer tier. The quote reads these the way the
+ * order does, so the page asks with exactly what its form will submit.
+ */
+export declare const ProductQuoteInputSchema: z.ZodObject<{
+    productId: z.ZodString;
+    productName: z.ZodString;
+    quantity: z.ZodOptional<z.ZodNumber>;
+    variantId: z.ZodOptional<z.ZodString>;
+    variantLabel: z.ZodOptional<z.ZodString>;
+    offerId: z.ZodOptional<z.ZodString>;
+    variantSelections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        variantId: z.ZodString;
+        variantLabel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ProductQuoteInput = z.infer<typeof ProductQuoteInputSchema>;
+/** What a quote is asked about: a basket, or one product as its form posts it. */
+export declare const CartQuoteLinesSchema: z.ZodUnion<readonly [z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        productId: z.ZodString;
+        productName: z.ZodString;
+        variantId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        variantLabel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        quantity: z.ZodNumber;
+        pricePerUnit: z.ZodOptional<z.ZodNumber>;
+        offerId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    productId: z.ZodString;
+    productName: z.ZodString;
+    quantity: z.ZodOptional<z.ZodNumber>;
+    variantId: z.ZodOptional<z.ZodString>;
+    variantLabel: z.ZodOptional<z.ZodString>;
+    offerId: z.ZodOptional<z.ZodString>;
+    variantSelections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        variantId: z.ZodString;
+        variantLabel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>]>;
+export type CartQuoteLines = z.infer<typeof CartQuoteLinesSchema>;
 /**
  * Where a basket would be delivered, for a delivery quote. The commune is
  * optional — without it the wilaya's rate applies; with it, the commune's own

package/dist/domain.js

@@ -126,6 +126,31 @@ export const AbandonedCheckoutInputSchema = z.object({
     fbc: z.string().max(500).optional(),
     fbp: z.string().max(500).optional(),
 });
+/**
+ * One product as a product page's order form posts it: a quantity, or a
+ * variant chosen per unit, and an offer tier. The quote reads these the way the
+ * order does, so the page asks with exactly what its form will submit.
+ */
+export const ProductQuoteInputSchema = z.object({
+    productId: z.string().min(1).max(200),
+    productName: z.string().min(1).max(200),
+    quantity: z.number().int().min(1).max(MAX_BASKET_LINE_QUANTITY).optional(),
+    variantId: z.string().min(1).max(200).optional(),
+    variantLabel: z.string().max(200).optional(),
+    offerId: z.string().min(1).max(200).optional(),
+    variantSelections: z
+        .array(z.object({
+        variantId: z.string().min(1).max(200),
+        variantLabel: z.string().max(200).optional(),
+    }))
+        .max(MAX_BASKET_LINE_QUANTITY)
+        .optional(),
+});
+/** What a quote is asked about: a basket, or one product as its form posts it. */
+export const CartQuoteLinesSchema = z.union([
+    z.object({ items: z.array(BasketLineInputSchema).min(1).max(MAX_BASKET_LINES) }),
+    ProductQuoteInputSchema,
+]);
 /**
  * Where a basket would be delivered, for a delivery quote. The commune is
  * optional — without it the wilaya's rate applies; with it, the commune's own

package/dist/endpoints/storefront-routes.d.ts

@@ -33,7 +33,9 @@ export interface StorefrontRoutes<C extends AstroAPIContext> {
     /** POST `{ phone, requestId, code }` → `{ data: OtpVerifyResult }`. */
     readonly otpVerify: StorefrontApiRoute<C>;
     /**
-     * POST `{ items, destination? }` → `{ success: true, data: CartValidation }`.
+     * POST a basket `{ items }` or one product `{ productId, productName, quantity,
+     * variantSelections, offerId, … }`, each with an optional `destination` →
+     * `{ success: true, data: CartValidation }`.
      * With a destination, `data.delivery` is the fee and total the order will charge.
      */
     readonly cartValidate: StorefrontApiRoute<C>;

package/dist/endpoints/storefront-routes.js

@@ -21,7 +21,7 @@
  * (see `createProxyEndpoint`), and the server's diagnostic fields ride along.
  */
 import { z } from "zod";
-import { AbandonedCheckoutInputSchema, BasketLineInputSchema, DeliveryDestinationSchema, MAX_BASKET_LINES, WilayaIdSchema, } from "../domain.js";
+import { AbandonedCheckoutInputSchema, BasketLineInputSchema, DeliveryDestinationSchema, ProductQuoteInputSchema, MAX_BASKET_LINES, WilayaIdSchema, } from "../domain.js";
 import { createProxyEndpoint, } from "./proxy.js";
 export const REVIEWS_PAGE_DEFAULT = 20;
 export const REVIEWS_PAGE_MAX = 50;
@@ -31,10 +31,17 @@ const otpVerifyInput = z.object({
     requestId: z.string().min(1).max(200),
     code: z.string().min(1).max(16),
 });
-const cartValidateInput = z.object({
-    items: z.array(BasketLineInputSchema).min(1).max(MAX_BASKET_LINES),
-    destination: DeliveryDestinationSchema.optional(),
-});
+/**
+ * A basket, or one product as its order form posts it — the same two shapes the
+ * server's quote takes — each with an optional destination to quote to.
+ */
+const cartValidateInput = z.union([
+    z.object({
+        items: z.array(BasketLineInputSchema).min(1).max(MAX_BASKET_LINES),
+        destination: DeliveryDestinationSchema.optional(),
+    }),
+    ProductQuoteInputSchema.extend({ destination: DeliveryDestinationSchema.optional() }),
+]);
 const abandonedConvertInput = z.object({
     sessionId: z.string().uuid(),
     orderId: z.string().min(1).max(200),
@@ -88,7 +95,7 @@ export function createStorefrontRoutes(options) {
             method: "POST",
             inputSchema: cartValidateInput,
             successBody: (data) => ({ success: true, data }),
-            call: (client, { items, destination }) => destination ? client.cart.validate(items, { destination }) : client.cart.validate(items),
+            call: (client, { destination, ...lines }) => client.cart.quote(lines, destination ? { destination } : undefined),
         }),
         abandonedUpsert: route({
             method: "POST",

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.3.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",