@wocart/storefront 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.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, DeliveryDestination } from "../domain.js";
 export interface CartNamespace {
     /**
      * Re-price and re-check a basket against the live catalog.
@@ -21,8 +21,14 @@ 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>>;
 }
 /**
  * Create cart namespace

package/dist/client/cart.js

@@ -19,8 +19,9 @@ import { localizedPath } from "./paths.js";
  */
 export function createCartNamespace(core) {
     return {
-        async validate(items) {
-            return core.post(localizedPath(core.config, "/store/cart/validate"), { items }, { schema: CartValidationSchema, operation: STOREFRONT_OPERATIONS.cartValidate });
+        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 });
         },
     };
 }

package/dist/domain.d.ts

@@ -175,6 +175,20 @@ export declare const AbandonedCheckoutInputSchema: z.ZodObject<{
  * `items[]` line: absent — not null — is the common wire shape.
  */
 export type AbandonedCheckoutInput = z.infer<typeof AbandonedCheckoutInputSchema>;
+/**
+ * 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,16 @@ export const AbandonedCheckoutInputSchema = z.object({
     fbc: z.string().max(500).optional(),
     fbp: z.string().max(500).optional(),
 });
+/**
+ * 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,10 @@ 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 `{ items, 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, MAX_BASKET_LINES, WilayaIdSchema, } from "../domain.js";
 import { createProxyEndpoint, } from "./proxy.js";
 export const REVIEWS_PAGE_DEFAULT = 20;
 export const REVIEWS_PAGE_MAX = 50;
@@ -33,6 +33,7 @@ const otpVerifyInput = z.object({
 });
 const cartValidateInput = z.object({
     items: z.array(BasketLineInputSchema).min(1).max(MAX_BASKET_LINES),
+    destination: DeliveryDestinationSchema.optional(),
 });
 const abandonedConvertInput = z.object({
     sessionId: z.string().uuid(),
@@ -87,7 +88,7 @@ export function createStorefrontRoutes(options) {
             method: "POST",
             inputSchema: cartValidateInput,
             successBody: (data) => ({ success: true, data }),
-            call: (client, { items }) => client.cart.validate(items),
+            call: (client, { items, destination }) => destination ? client.cart.validate(items, { destination }) : client.cart.validate(items),
         }),
         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.3.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",