@wocart/storefront 1.3.0 → 1.4.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.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/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/package.json

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