@wocart/storefront 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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
+
+- **Delivery quotes.** `cart.validate(items, { destination })` answers
+  `delivery`: the fee and total the order will charge at that wilaya, commune
+  and delivery type — product shipping profiles, commune overrides, the
+  free-delivery threshold and free-shipping offers included — or
+  `available: false` where the store does not deliver. The server computes the
+  quote with the same function it charges orders with. A platform server that
+  predates the quote answers without `delivery`.
+- `DeliveryDestinationSchema`, `DeliveryDestination` and `CartDeliveryQuote`.
+- The `cartValidate` route passes a `destination` through.
+
 ## 1.2.0 — 2026-10-15
 
 ### Added

package/USAGE.md

@@ -745,6 +745,28 @@ type ShippingRate = {
 If the map is empty or one rate is null, show a useful unavailable state. Do
 not silently display zero shipping.
 
+These are the store default profile's wilaya rates — a guide for "delivery
+from X DZD", never the fee an order is charged. The fee also depends on each
+product's own shipping profile, the commune, the free-delivery threshold and
+free-shipping offers. To show what the shopper will pay, quote it:
+
+~~~ts
+const result = await store.cart.validate(items, {
+  destination: { wilayaId: 16, communeId: "c-16-001", deliveryType: "home" },
+});
+
+if (result.success && result.data.delivery) {
+  const quote = result.data.delivery;
+  // quote.available → quote.fee and quote.total are what the order charges.
+  // !quote.available → the store does not deliver there; an order is refused.
+}
+~~~
+
+The quote comes from the same function the order uses, so the fee and total
+it names are the ones charged. A single-product order form quotes the same
+way, with its one product as the only line. From the browser, post
+`{ items, destination }` to the `cartValidate` route.
+
 ### Wilayas and communes
 
 ~~~ts
@@ -1430,8 +1452,9 @@ render null as not found.
 ### The cart total is different after checkout
 
 This is expected when a browser price, offer, stock state, or delivery value
-was stale. Render cart.validate results and treat order creation as the final
-server decision.
+was stale, or when the theme computed a fee or total itself. Show the totals
+cart.validate answers — with a destination for the delivery fee — and treat
+order creation as the final server decision.
 
 ### OTP says unavailable
 

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 } 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.
@@ -21,8 +21,22 @@ export interface CartNamespace {
      * optional variant fields); pricing from their side is never trusted, and
      * each line's product name and variant label come back from the catalog in
      * the client's language.
+     *
+     * With a `destination`, the answer also carries `delivery`: the fee and
+     * total the order would charge there. A theme shows that, never a fee or
+     * total of its own making.
      */
-    validate(items: readonly BasketLineInput[]): Promise<ClientResult<CartValidation>>;
+    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,9 +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) {
-            return core.post(localizedPath(core.config, "/store/cart/validate"), { items }, { schema: CartValidationSchema, operation: STOREFRONT_OPERATIONS.cartValidate });
-        },
+        validate: (items, options) => quote({ items: [...items] }, options),
+        quote,
     };
 }

package/dist/domain.d.ts

@@ -175,6 +175,62 @@ 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
+ * override when the merchant set one.
+ */
+export declare const DeliveryDestinationSchema: z.ZodObject<{
+    wilayaId: z.ZodNumber;
+    communeId: z.ZodOptional<z.ZodString>;
+    deliveryType: z.ZodEnum<{
+        home: "home";
+        stop_desk: "stop_desk";
+    }>;
+}, z.core.$strip>;
+export type DeliveryDestination = z.infer<typeof DeliveryDestinationSchema>;
 /** Shopper's selected delivery mode and destination. Policy decides whether address is required. */
 export declare const DeliverySelectionSchema: z.ZodObject<{
     wilayaId: z.ZodNumber;

package/dist/domain.js

@@ -126,6 +126,41 @@ 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
+ * override when the merchant set one.
+ */
+export const DeliveryDestinationSchema = z.object({
+    wilayaId: WilayaIdSchema,
+    communeId: z.string().min(1).max(200).optional(),
+    deliveryType: z.enum(["home", "stop_desk"]),
+});
 /** Shopper's selected delivery mode and destination. Policy decides whether address is required. */
 export const DeliverySelectionSchema = z.object({
     wilayaId: z.number().int().min(1).max(58),

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

@@ -32,7 +32,12 @@ export interface StorefrontRoutes<C extends AstroAPIContext> {
     readonly otpSend: StorefrontApiRoute<C>;
     /** POST `{ phone, requestId, code }` → `{ data: OtpVerifyResult }`. */
     readonly otpVerify: StorefrontApiRoute<C>;
-    /** POST `{ items }` → `{ 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>;
     /** POST an `AbandonedCheckoutInput` → 204. */
     readonly abandonedUpsert: 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, 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,9 +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),
-});
+/**
+ * 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),
@@ -87,7 +95,7 @@ export function createStorefrontRoutes(options) {
             method: "POST",
             inputSchema: cartValidateInput,
             successBody: (data) => ({ success: true, data }),
-            call: (client, { items }) => client.cart.validate(items),
+            call: (client, { destination, ...lines }) => client.cart.quote(lines, destination ? { destination } : undefined),
         }),
         abandonedUpsert: route({
             method: "POST",

package/dist/schemas.d.ts

@@ -692,6 +692,15 @@ export declare const CartValidationSchema: z.ZodObject<{
         qualified: z.ZodBoolean;
         remaining: z.ZodNumber;
     }, z.core.$strip>;
+    delivery: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        available: z.ZodLiteral<true>;
+        fee: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        available: z.ZodLiteral<false>;
+        fee: z.ZodNull;
+        total: z.ZodNull;
+    }, z.core.$strip>], "available">>;
 }, z.core.$strip>;
 export declare const CreatedOrderSchema: z.ZodObject<{
     orderId: z.ZodString;

package/dist/schemas.js

@@ -314,6 +314,12 @@ export const CartValidationSchema = z.object({
         qualified: z.boolean(),
         remaining: z.number(),
     }),
+    delivery: z
+        .discriminatedUnion("available", [
+        z.object({ available: z.literal(true), fee: z.number(), total: z.number() }),
+        z.object({ available: z.literal(false), fee: z.null(), total: z.null() }),
+    ])
+        .optional(),
 });
 export const CreatedOrderSchema = z.object({
     orderId: z.string(),

package/dist/types.d.ts

@@ -275,7 +275,24 @@ export interface CartValidation {
         qualified: boolean;
         remaining: number;
     };
+    /**
+     * Present when `validate` was given a destination: what the order would
+     * charge there, from the same quote the order itself uses (shipping
+     * profiles, commune overrides, the free-delivery threshold and offers).
+     * `available: false` — fee and total null — means the store does not
+     * deliver there, and an order to it is refused.
+     */
+    delivery?: CartDeliveryQuote | undefined;
 }
+export type CartDeliveryQuote = {
+    available: true;
+    fee: number;
+    total: number;
+} | {
+    available: false;
+    fee: null;
+    total: null;
+};
 /** What POST /store/orders returns on 201. */
 export interface CreatedOrder {
     orderId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/storefront",
-  "version": "1.2.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",