@wocart/storefront 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.11.0 — 2026-10-17
+
+### Added
+
+- **Coupons.** `cart.quote` / `cart.validate` take `couponCode` and `phone`
+  (`CartQuoteOptions`) and answer `coupon` (`CouponOutcome`,
+  `CouponOutcomeSchema`): applied — its `discount` already out of `subtotal`
+  and of each line's `lineTotal`, `CartValidationLine.discount` being the
+  line's share, `freeShipping` making the delivery fee 0 — or refused with a
+  `reason` (`CouponRefusalReason`, open), `shortBy` or `startsAt` when it has
+  one. Null without a code; absent from an older server.
+- `CreateOrderInput.couponCode` and `placeOrderInput.couponCode` (an empty
+  box sends none); `CreatedOrder.couponDiscount`. An order whose code does not
+  apply is refused whole with `COUPON_NOT_APPLICABLE`: `couponRefusalOf(result)`
+  reads the refusal, and `executePlaceOrder`'s upstream failure carries it as
+  `couponRefusal`.
+- Shareable coupon links: `COUPON_URL_PARAM` (`?coupon=CODE`) and
+  `couponFromUrl(url)`.
+- `CheckoutDraft.couponCode`.
+
+### Changed
+
+- `CartValidationLine.offerId` names the offer applied to the line, whatever
+  its kind — a coupon never covers that line.
+
+## 1.10.0 — 2026-10-17
+
+### Added
+
+- **Quantity pricing.** `ProductDetail.quantityPricing` (`QuantityPricing`,
+  `QuantityPricingSchema`): a product's price tiers by quantity, each with an
+  optional free delivery — null or absent when it has none.
+  `getQuantityTierViews(pricing, unitPrice)` projects them for tiles (price,
+  per-unit price, saving); the total is the server's cart quote.
+- `CartValidationLine.offerId`: the quantity-pricing offer that priced the
+  line, whose `lineTotal` is then the tier's price. Optional.
+
 ## 1.9.0 — 2026-10-17
 
 ### Added

package/USAGE.md

@@ -223,6 +223,7 @@ server directly.
 | `productImageSource` | Which photo represents a product (cover → gallery fallback) |
 | `getProductView`, `getProductListView` | Pure price, discount, default-variant, and stock values for detail and list projections |
 | `getOfferTierView` | Pure offer-tier price, compare-price, savings, and free-shipping projection; display-only, never order authority |
+| `getQuantityTierViews` | A product's quantity-pricing tiers as tiles show them — price, per-unit price, saving against the unit price, free delivery; display-only, the total is the server's cart quote |
 | `META_CURRENCY`, `buildMetaProductPayload`, `buildMetaViewContentPayload`, `buildMetaAddToCartPayload`, `buildMetaInitiateCheckoutPayload` | Browser-safe Meta event payloads with the platform currency and catalog shape |
 | `createMetaPixelTracker` | Injected browser-pixel dispatch; the theme supplies the vendor global and keeps bootstrap/timing |
 | `createBasketStore`, `createLocalStorageAdapter`, `createMemoryStorageAdapter`, `DEFAULT_BASKET_STORAGE_KEY` | The browser basket, its storage, and the key it persists under (`cod_cart_v1`) |
@@ -625,8 +626,26 @@ if (!product) {
 ~~~
 
 Product detail includes the product fields, parsed variant options and tags,
-the category, variants, images, review statistics, and offers. The server
-decides whether a product is publicly available.
+the category, variants, images, review statistics, quantity pricing, and
+offers. The server decides whether a product is publicly available.
+
+**Quantity pricing** (`product.quantityPricing`, null when the product has
+none) prices a product by how many are bought — "1 for 2,000 DA, 2 for 3,500
+DA, 3 for 4,500 DA". The highest tier the quantity reaches prices every unit
+at its per-unit price, and a tier may include free delivery for a basket of
+that product alone. A product has at most one offer per order, so it has
+either quantity pricing or offers in `offers`, never both at once.
+
+~~~ts
+const tiles = product.quantityPricing ? getQuantityTierViews(product.quantityPricing, product.price) : [];
+// tiles: [{ quantity, price, perUnit, savingsAmount, savePct, freeShipping }]
+~~~
+
+Show the tiers as choices; never compute the total yourself. The cart quote
+(`POST /api/cart/validate`) answers what the shopper pays — each line's
+`lineTotal` already priced by its tier (`offerId` names the offer), and the
+delivery — and the order charges exactly that. A tier locked to one variant
+(`triggerVariantId`) counts and prices only that variant.
 
 ### Product lists
 
@@ -1040,7 +1059,44 @@ variant details. The displayed price can be included for the request shape,
 but the server is authoritative and recalculates the actual amount.
 
 CreatedOrder contains the order ID, customer-facing order number, product
-price, delivery fee, and total, all in whole DZD.
+price, delivery fee, and total, all in whole DZD — and `couponDiscount`, what
+the order's coupon took off.
+
+### Coupons
+
+A coupon is a code the shopper types. It applies after offers, only to the
+products no offer applied to, and the server alone decides whether it applies
+and what it takes off. A theme asks, then shows the answer.
+
+Ask the cart quote with the code — and the phone once the shopper has typed
+one, so a coupon for selected customers or one use per customer is judged
+before the order:
+
+~~~ts
+const quoted = await store.cart.quote(form, { destination, couponCode, phone });
+if (quoted.success && quoted.data.coupon) {
+  const coupon = quoted.data.coupon;
+  // applied: coupon.discount is already out of quoted.data.subtotal and of each
+  //          line's lineTotal (line.discount is its share); coupon.freeShipping
+  //          means delivery.fee is 0.
+  // refused: coupon.reason — not_found, not_started (startsAt), expired,
+  //          used_up, identify_first, not_eligible, already_used,
+  //          no_eligible_products, below_minimum_subtotal / _quantity (shortBy),
+  //          delivery_already_free. An unknown reason gets the theme's general sentence.
+}
+~~~
+
+`CartQuoteOptions` names what a quote may be asked besides its lines.
+
+Send the code with the order as `couponCode` (`placeOrderInput` keeps it; an
+empty box sends none). An order whose code does not apply is refused whole —
+never placed without the discount the shopper expected — with the code
+`COUPON_NOT_APPLICABLE`; `couponRefusalOf(result)` reads its refusal, and
+`executePlaceOrder` hands it back as `couponRefusal` so the form can show it on
+the code's field.
+
+A shareable link carries a code in the query (`COUPON_URL_PARAM`, `?coupon=RAMADAN10`);
+`couponFromUrl(url)` reads it so the theme can fill the code box.
 
 ### OTP
 

package/dist/actions.d.ts

@@ -36,7 +36,7 @@
 import { z } from "zod";
 import type { StoreClient } from "./client/index.js";
 import type { DomainError } from "./domain.js";
-import type { CreatedOrder } from "./types.js";
+import type { CouponRefusal, CreatedOrder } from "./types.js";
 /**
  * The order form's input whitelist.
  *
@@ -85,6 +85,7 @@ export declare const placeOrderInput: z.ZodObject<{
         offerId: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
     }, z.core.$strip>>>, unknown>;
     landingPageSlug: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    couponCode: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
 }, z.core.$strip>;
 export type PlaceOrderInput = z.infer<typeof placeOrderInput>;
 /**
@@ -106,6 +107,8 @@ export type PlaceOrderResult = {
     error: string;
     errorKind: "upstream";
     domainError: DomainError;
+    /** Set when the order was refused for its code: the form shows it on the code's field. */
+    couponRefusal: CouponRefusal | null;
 };
 /**
  * Execute the placeOrder action's handler body: enforce the

package/dist/actions.js

@@ -34,6 +34,7 @@
  * without Astro.
  */
 import { z } from "zod";
+import { couponRefusalOf } from "./coupon.js";
 import { toLocalAlgerianMobile } from "./phone.js";
 function parseOptionalArrayInput(value) {
     if (!value || value === "[]")
@@ -149,6 +150,9 @@ export const placeOrderInput = z.object({
     // Landing page attribution — best-effort: unknown/draft slug leaves
     // the order unattributed, never blocked (platform extension, LP feature).
     landingPageSlug: z.preprocess((v) => (v === "" || v == null ? undefined : v), z.string().min(1).max(60).optional()),
+    // The code the shopper typed; an empty box sends none. Whether it applies
+    // is the server's to say — a refusal comes back as `couponRefusal`.
+    couponCode: z.preprocess((v) => (typeof v === "string" && v.trim() === "") || v == null ? undefined : v, z.string().max(64).optional()),
 });
 /**
  * Collect the shopper's attribution headers so the server records the
@@ -195,6 +199,7 @@ export async function executePlaceOrder(input, request, client) {
             error: result.error,
             errorKind: "upstream",
             domainError: result.domainError,
+            couponRefusal: couponRefusalOf(result),
         };
     }
     return { success: true, data: result.data };

package/dist/client/cart.d.ts

@@ -24,19 +24,28 @@ export interface CartNamespace {
      *
      * 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.
+     * total of its own making. With a `couponCode`, it carries `coupon`: applied,
+     * or refused with the reason the order would be refused for.
      */
-    validate(items: readonly BasketLineInput[], options?: {
-        destination?: DeliveryDestination;
-    }): Promise<ClientResult<CartValidation>>;
+    validate(items: readonly BasketLineInput[], options?: CartQuoteOptions): 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>>;
+    quote(lines: CartQuoteLines, options?: CartQuoteOptions): Promise<ClientResult<CartValidation>>;
+}
+/** What a quote is asked besides its lines. */
+export interface CartQuoteOptions {
+    /** Where it would be delivered: the answer then carries `delivery`. */
+    destination?: DeliveryDestination;
+    /** The code the shopper typed: the answer then carries `coupon`. */
+    couponCode?: string;
+    /**
+     * The phone the shopper typed, once there is one: a coupon for selected
+     * customers, or one use per customer, is then judged before the order.
+     */
+    phone?: string;
 }
 /**
  * Create cart namespace

package/dist/client/cart.js

@@ -19,9 +19,14 @@ import { localizedPath } from "./paths.js";
  */
 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 });
+    const quote = async (lines, options = {}) => {
+        const { destination, couponCode, phone } = options;
+        return core.post(localizedPath(core.config, "/store/cart/validate"), {
+            ...lines,
+            ...(destination ? { destination } : {}),
+            ...(couponCode?.trim() ? { couponCode } : {}),
+            ...(phone?.trim() ? { phone } : {}),
+        }, { schema: CartValidationSchema, operation: STOREFRONT_OPERATIONS.cartValidate });
     };
     return {
         validate: (items, options) => quote({ items: [...items] }, options),

package/dist/coupon.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Coupons on the storefront: the code a shareable link brings, and the
+ * refusal an order comes back with.
+ *
+ * What a code does is the server's to say — the cart quote answers `coupon`
+ * (applied, or refused with a reason) and the order is refused whole when its
+ * code does not apply. A theme shows those answers; it never decides one.
+ */
+import type { ClientResult } from "./domain.js";
+import type { CouponRefusal } from "./types.js";
+/** The error code of an order refused for its code. */
+export declare const COUPON_NOT_APPLICABLE = "COUPON_NOT_APPLICABLE";
+/** The query parameter a shareable coupon link carries: `/products/robe?coupon=RAMADAN10`. */
+export declare const COUPON_URL_PARAM = "coupon";
+/** The code a URL brings, trimmed; null when it brings none. */
+export declare function couponFromUrl(url: URL): string | null;
+/** Why an order was refused for its code, or null when it was refused — or placed — for anything else. */
+export declare function couponRefusalOf(result: ClientResult<unknown>): CouponRefusal | null;

package/dist/coupon.js

@@ -0,0 +1,19 @@
+/** The error code of an order refused for its code. */
+export const COUPON_NOT_APPLICABLE = "COUPON_NOT_APPLICABLE";
+/** The query parameter a shareable coupon link carries: `/products/robe?coupon=RAMADAN10`. */
+export const COUPON_URL_PARAM = "coupon";
+/** The code a URL brings, trimmed; null when it brings none. */
+export function couponFromUrl(url) {
+    const code = url.searchParams.get(COUPON_URL_PARAM)?.trim();
+    return code ? code.slice(0, 64) : null;
+}
+/** Why an order was refused for its code, or null when it was refused — or placed — for anything else. */
+export function couponRefusalOf(result) {
+    if (result.success || result.domainError.code !== COUPON_NOT_APPLICABLE || typeof result.reason !== "string")
+        return null;
+    return {
+        reason: result.reason,
+        ...(typeof result.shortBy === "number" ? { shortBy: result.shortBy } : {}),
+        ...(typeof result.startsAt === "string" ? { startsAt: result.startsAt } : {}),
+    };
+}

package/dist/domain.d.ts

@@ -272,6 +272,8 @@ export interface CheckoutDraft {
     readonly customFieldResponses: readonly CheckoutFieldAnswer[];
     readonly otpProof: OtpProof | null;
     readonly attribution: CheckoutAttribution;
+    /** The code the shopper typed, if any; the server decides whether it applies. */
+    readonly couponCode?: string | null;
 }
 /** Proof that the checkout phone was verified or that the provider failed open. */
 export declare const OtpProofSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -292,6 +294,7 @@ export declare const OrderSchema: z.ZodObject<{
     price: z.ZodNumber;
     deliveryFee: z.ZodNumber;
     total: z.ZodNumber;
+    couponDiscount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 export type Order = z.infer<typeof OrderSchema>;
 /** Server-owned decision for the thank-you page's conversion event. */

package/dist/domain.js

@@ -189,6 +189,7 @@ export const OrderSchema = z.object({
     price: z.number().finite().nonnegative(),
     deliveryFee: z.number().finite().nonnegative(),
     total: z.number().finite().nonnegative(),
+    couponDiscount: z.number().finite().nonnegative().nullish(),
 });
 /** Server-owned decision for the thank-you page's conversion event. */
 export const TrackingDecisionSchema = z.object({

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

@@ -35,9 +35,10 @@ export interface StorefrontRoutes<C extends AstroAPIContext> {
     readonly otpVerify: StorefrontApiRoute<C>;
     /**
      * 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.
+     * variantSelections, offerId, … }`, each with an optional `destination`,
+     * `couponCode` and `phone` → `{ success: true, data: CartValidation }`.
+     * With a destination, `data.delivery` is the fee and total the order will
+     * charge; with a code, `data.coupon` is what it does.
      */
     readonly cartValidate: StorefrontApiRoute<C>;
     /** POST an `AbandonedCheckoutInput` → 204. */

package/dist/endpoints/storefront-routes.js

@@ -32,16 +32,23 @@ const otpVerifyInput = z.object({
     requestId: z.string().min(1).max(200),
     code: z.string().min(1).max(16),
 });
+/** What a quote is asked besides its lines (`CartQuoteOptions`). */
+const quoteAsks = {
+    destination: DeliveryDestinationSchema.optional(),
+    couponCode: z.string().max(64).optional(),
+    phone: z.string().max(32).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.
+ * server's quote takes — each with an optional destination to quote to, the
+ * code typed and the phone typed.
  */
 const cartValidateInput = z.union([
     z.object({
         items: z.array(BasketLineInputSchema).min(1).max(MAX_BASKET_LINES),
-        destination: DeliveryDestinationSchema.optional(),
+        ...quoteAsks,
     }),
-    ProductQuoteInputSchema.extend({ destination: DeliveryDestinationSchema.optional() }),
+    ProductQuoteInputSchema.extend(quoteAsks),
 ]);
 const abandonedConvertInput = z.object({
     sessionId: z.string().uuid(),
@@ -125,7 +132,11 @@ export function createStorefrontRoutes(options) {
             method: "POST",
             inputSchema: cartValidateInput,
             successBody: (data) => ({ success: true, data }),
-            call: (client, { destination, ...lines }) => client.cart.quote(lines, destination ? { destination } : undefined),
+            call: (client, { destination, couponCode, phone, ...lines }) => client.cart.quote(lines, {
+                ...(destination ? { destination } : {}),
+                ...(couponCode !== undefined ? { couponCode } : {}),
+                ...(phone !== undefined ? { phone } : {}),
+            }),
         }),
         abandonedUpsert: route({
             method: "POST",

package/dist/index.d.ts

@@ -34,8 +34,10 @@ export * from "./types.js";
 export * from "./schemas.js";
 export * from "./domain.js";
 export * from "./product-view.js";
-export { getOfferTierView } from "./offer-view.js";
-export type { OfferTierInput, OfferTierView } from "./offer-view.js";
+export { getOfferTierView, getQuantityTierViews } from "./offer-view.js";
+export { COUPON_NOT_APPLICABLE, COUPON_URL_PARAM, couponFromUrl, couponRefusalOf } from "./coupon.js";
+export type { CartQuoteOptions } from "./client/cart.js";
+export type { OfferTierInput, OfferTierView, QuantityTierView } from "./offer-view.js";
 export { createAbandonedCheckoutTracker } from "./abandoned-checkout.js";
 export type { AbandonedCheckoutPorts, AbandonedCheckoutSnapshot, AbandonedCheckoutStorage, AbandonedCheckoutTracker, } from "./abandoned-checkout.js";
 export { META_CURRENCY, buildMetaAddToCartPayload, buildMetaInitiateCheckoutPayload, buildMetaProductPayload, buildMetaViewContentPayload, createMetaPixelTracker, } from "./meta-tracking.js";

package/dist/index.js

@@ -25,6 +25,7 @@ export * from "./types.js";
 export * from "./schemas.js";
 export * from "./domain.js";
 export * from "./product-view.js";
-export { getOfferTierView } from "./offer-view.js";
+export { getOfferTierView, getQuantityTierViews } from "./offer-view.js";
+export { COUPON_NOT_APPLICABLE, COUPON_URL_PARAM, couponFromUrl, couponRefusalOf } from "./coupon.js";
 export { createAbandonedCheckoutTracker } from "./abandoned-checkout.js";
 export { META_CURRENCY, buildMetaAddToCartPayload, buildMetaInitiateCheckoutPayload, buildMetaProductPayload, buildMetaViewContentPayload, createMetaPixelTracker, } from "./meta-tracking.js";

package/dist/offer-view.d.ts

@@ -1,4 +1,4 @@
-import type { Offer } from "./types.js";
+import type { Offer, QuantityPricing } from "./types.js";
 export interface OfferTierView {
     isFreeShipping: boolean;
     savePct: number;
@@ -8,3 +8,20 @@ export interface OfferTierView {
 }
 export type OfferTierInput = Pick<Offer, "discountType" | "triggerQuantity" | "rewardQuantity" | "rewardUnitPrice">;
 export declare function getOfferTierView(offer: OfferTierInput, basePrice: number, comparePrice: number | null): OfferTierView;
+export interface QuantityTierView {
+    quantity: number;
+    /** What that many units cost. */
+    price: number;
+    /** What one unit costs within the tier, rounded to the dinar. */
+    perUnit: number;
+    /** What the tier saves against buying that many at `unitPrice`; 0 when it saves nothing. */
+    savingsAmount: number;
+    savePct: number;
+    freeShipping: boolean;
+}
+/**
+ * The tiers of a product's quantity pricing as tiles show them: price, per-unit
+ * price and saving against the product's unit price. Presentation only — the
+ * total for a quantity is the server's cart quote.
+ */
+export declare function getQuantityTierViews(pricing: Pick<QuantityPricing, "tiers">, unitPrice: number): QuantityTierView[];

package/dist/offer-view.js

@@ -15,3 +15,24 @@ export function getOfferTierView(offer, basePrice, comparePrice) {
         comparePrice: comparePrice === null ? null : comparePrice * offer.triggerQuantity,
     };
 }
+/**
+ * The tiers of a product's quantity pricing as tiles show them: price, per-unit
+ * price and saving against the product's unit price. Presentation only — the
+ * total for a quantity is the server's cart quote.
+ */
+export function getQuantityTierViews(pricing, unitPrice) {
+    return [...pricing.tiers]
+        .sort((a, b) => a.quantity - b.quantity)
+        .map((tier) => {
+        const listValue = unitPrice * tier.quantity;
+        const savingsAmount = Math.max(0, listValue - tier.price);
+        return {
+            quantity: tier.quantity,
+            price: tier.price,
+            perUnit: Math.round(tier.price / tier.quantity),
+            savingsAmount,
+            savePct: listValue > 0 ? Math.round((savingsAmount / listValue) * 100) : 0,
+            freeShipping: tier.freeShipping,
+        };
+    });
+}

package/dist/schemas.d.ts

@@ -43,6 +43,21 @@ export declare const OfferSchema: z.ZodObject<{
     rewardVariantLabel: z.ZodNullable<z.ZodString>;
     rewardUnitPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
+/**
+ * Quantity pricing — price tiers by quantity ("2 for 3,500 DA"). The highest
+ * tier the quantity reaches prices every unit at its per-unit price; the
+ * server's cart quote is the total.
+ */
+export declare const QuantityPricingSchema: z.ZodObject<{
+    offerId: z.ZodString;
+    name: z.ZodString;
+    triggerVariantId: z.ZodNullable<z.ZodString>;
+    tiers: z.ZodArray<z.ZodObject<{
+        quantity: z.ZodNumber;
+        price: z.ZodNumber;
+        freeShipping: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const CategorySchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -201,6 +216,16 @@ export declare const ProductSchema: z.ZodObject<{
         avgRating: z.ZodNumber;
         reviewCount: z.ZodNumber;
     }, z.core.$strip>>;
+    quantityPricing: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        offerId: z.ZodString;
+        name: z.ZodString;
+        triggerVariantId: z.ZodNullable<z.ZodString>;
+        tiers: z.ZodArray<z.ZodObject<{
+            quantity: z.ZodNumber;
+            price: z.ZodNumber;
+            freeShipping: z.ZodBoolean;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     offers: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
@@ -629,6 +654,16 @@ export declare const LandingPageSchema: z.ZodObject<{
             avgRating: z.ZodNumber;
             reviewCount: z.ZodNumber;
         }, z.core.$strip>>;
+        quantityPricing: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            offerId: z.ZodString;
+            name: z.ZodString;
+            triggerVariantId: z.ZodNullable<z.ZodString>;
+            tiers: z.ZodArray<z.ZodObject<{
+                quantity: z.ZodNumber;
+                price: z.ZodNumber;
+                freeShipping: z.ZodBoolean;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         offers: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             name: z.ZodString;
@@ -677,6 +712,8 @@ export declare const CartValidationLineSchema: z.ZodObject<{
     quantity: z.ZodNumber;
     unitPrice: z.ZodNumber;
     lineTotal: z.ZodNumber;
+    offerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    discount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     maxQuantity: z.ZodNullable<z.ZodNumber>;
     blocker: z.ZodNullable<z.ZodEnum<{
         missing: "missing";
@@ -690,6 +727,24 @@ export declare const CartRewardSchema: z.ZodObject<{
     productName: z.ZodNullable<z.ZodString>;
     quantity: z.ZodNumber;
 }, z.core.$strip>;
+/**
+ * What the code the quote was asked with did: applied, or refused with the
+ * reason the order would be refused for. `reason` is an open string — a reason
+ * this SDK has not seen yet still validates — and `shortBy` / `startsAt` come
+ * with the reasons that have them.
+ */
+export declare const CouponOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    code: z.ZodString;
+    applied: z.ZodLiteral<true>;
+    discount: z.ZodNumber;
+    freeShipping: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    code: z.ZodString;
+    applied: z.ZodLiteral<false>;
+    reason: z.ZodString;
+    shortBy: z.ZodOptional<z.ZodNumber>;
+    startsAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "applied">;
 export declare const CartValidationSchema: z.ZodObject<{
     lines: z.ZodArray<z.ZodObject<{
         productId: z.ZodString;
@@ -699,6 +754,8 @@ export declare const CartValidationSchema: z.ZodObject<{
         quantity: z.ZodNumber;
         unitPrice: z.ZodNumber;
         lineTotal: z.ZodNumber;
+        offerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        discount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         maxQuantity: z.ZodNullable<z.ZodNumber>;
         blocker: z.ZodNullable<z.ZodEnum<{
             missing: "missing";
@@ -728,6 +785,18 @@ export declare const CartValidationSchema: z.ZodObject<{
         fee: z.ZodNull;
         total: z.ZodNull;
     }, z.core.$strip>], "available">>;
+    coupon: z.ZodOptional<z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        code: z.ZodString;
+        applied: z.ZodLiteral<true>;
+        discount: z.ZodNumber;
+        freeShipping: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodObject<{
+        code: z.ZodString;
+        applied: z.ZodLiteral<false>;
+        reason: z.ZodString;
+        shortBy: z.ZodOptional<z.ZodNumber>;
+        startsAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "applied">>>;
 }, z.core.$strip>;
 export declare const CreatedOrderSchema: z.ZodObject<{
     orderId: z.ZodString;
@@ -735,6 +804,7 @@ export declare const CreatedOrderSchema: z.ZodObject<{
     price: z.ZodNumber;
     deliveryFee: z.ZodNumber;
     total: z.ZodNumber;
+    couponDiscount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 export declare const OrderTrackingSchema: z.ZodObject<{
     pixelId: z.ZodNullable<z.ZodString>;

package/dist/schemas.js

@@ -42,6 +42,21 @@ export const OfferSchema = z.object({
     // it omits the field, and the product's own price stands in for the gift.
     rewardUnitPrice: z.number().nullish(),
 });
+/**
+ * Quantity pricing — price tiers by quantity ("2 for 3,500 DA"). The highest
+ * tier the quantity reaches prices every unit at its per-unit price; the
+ * server's cart quote is the total.
+ */
+export const QuantityPricingSchema = z.object({
+    offerId: z.string(),
+    name: z.string(),
+    triggerVariantId: z.string().nullable(),
+    tiers: z.array(z.object({
+        quantity: z.number().int(),
+        price: z.number().int(),
+        freeShipping: z.boolean(),
+    })),
+});
 const productCategorySchema = z.object({
     id: z.string(),
     name: z.string(),
@@ -122,6 +137,11 @@ export const ProductSchema = z.object({
     variants: z.array(ProductVariantSchema),
     images: z.array(ProductImageSchema),
     reviewStats: reviewStatsSchema.nullable(),
+    /**
+     * The product's live quantity pricing; null or absent when it has none
+     * (absent from a server that predates it).
+     */
+    quantityPricing: QuantityPricingSchema.nullish(),
     offers: z.array(OfferSchema),
 });
 export const StorePagePublicSchema = z.object({
@@ -331,6 +351,10 @@ export const CartValidationLineSchema = z.object({
     quantity: z.number().int(),
     unitPrice: z.number(),
     lineTotal: z.number(),
+    /** The offer applied to the line; absent from a server that predates offers on lines. */
+    offerId: z.string().nullish(),
+    /** The line's share of the coupon's discount, already out of `lineTotal`; absent from a server that predates coupons. */
+    discount: z.number().nullish(),
     maxQuantity: z.number().nullable(),
     blocker: z.enum(["missing", "unlisted", "out_of_stock"]).nullable(),
 });
@@ -340,6 +364,16 @@ export const CartRewardSchema = z.object({
     productName: z.string().nullable(),
     quantity: z.number().int(),
 });
+/**
+ * What the code the quote was asked with did: applied, or refused with the
+ * reason the order would be refused for. `reason` is an open string — a reason
+ * this SDK has not seen yet still validates — and `shortBy` / `startsAt` come
+ * with the reasons that have them.
+ */
+export const CouponOutcomeSchema = z.discriminatedUnion("applied", [
+    z.object({ code: z.string(), applied: z.literal(true), discount: z.number(), freeShipping: z.boolean() }),
+    z.object({ code: z.string(), applied: z.literal(false), reason: z.string(), shortBy: z.number().optional(), startsAt: z.string().optional() }),
+]);
 export const CartValidationSchema = z.object({
     lines: z.array(CartValidationLineSchema),
     subtotal: z.number(),
@@ -356,6 +390,8 @@ export const CartValidationSchema = z.object({
         z.object({ available: z.literal(false), fee: z.null(), total: z.null() }),
     ])
         .optional(),
+    /** The code's outcome: null without one; absent from a server that predates coupons. */
+    coupon: CouponOutcomeSchema.nullish(),
 });
 export const CreatedOrderSchema = z.object({
     orderId: z.string(),
@@ -363,6 +399,8 @@ export const CreatedOrderSchema = z.object({
     price: z.number(),
     deliveryFee: z.number(),
     total: z.number(),
+    /** What the coupon took off; absent from a server that predates coupons. */
+    couponDiscount: z.number().nullish(),
 });
 export const OrderTrackingSchema = z.object({
     pixelId: z.string().nullable(),

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ProductSchema, ProductListSchema, CategorySchema, ProductImageSchema, ProductVariantSchema, OfferSchema, PageDocumentPayloadSchema } from "./schemas.js";
+import { ProductSchema, ProductListSchema, CategorySchema, ProductImageSchema, ProductVariantSchema, OfferSchema, QuantityPricingSchema, PageDocumentPayloadSchema } from "./schemas.js";
 export type Product = z.infer<typeof ProductSchema>;
 export type ProductList = z.infer<typeof ProductListSchema>;
 /** Compact catalog projection used in grids, cards and search results. */
@@ -10,6 +10,9 @@ export type Category = z.infer<typeof CategorySchema>;
 export type ProductImage = z.infer<typeof ProductImageSchema>;
 export type ProductVariant = z.infer<typeof ProductVariantSchema>;
 export type Offer = z.infer<typeof OfferSchema>;
+/** A product's quantity pricing — `ProductDetail.quantityPricing`. */
+export type QuantityPricing = z.infer<typeof QuantityPricingSchema>;
+export type QuantityPricingTier = QuantityPricing["tiers"][number];
 /**
  * One store's saved composition document for one surface. Transport shape
  * only — `sections` items are `unknown`; the theme
@@ -307,7 +310,12 @@ export interface CartValidationLine {
     quantity: number;
     /** CURRENT catalog price — the cart's optimistic price is display-only. */
     unitPrice: number;
+    /** What the line costs, offers and the coupon applied. */
     lineTotal: number;
+    /** The offer applied to the line; null or absent when none. */
+    offerId?: string | null | undefined;
+    /** The line's share of the coupon's discount, already out of `lineTotal`; null or absent without one. */
+    discount?: number | null | undefined;
     /** Units still available; null when the product is not stock-tracked. */
     maxQuantity: number | null;
     /**
@@ -343,7 +351,31 @@ export interface CartValidation {
      * deliver there, and an order to it is refused.
      */
     delivery?: CartDeliveryQuote | undefined;
+    /** What the code the quote was asked with did; null without one, absent from a server that predates coupons. */
+    coupon?: CouponOutcome | null | undefined;
 }
+/**
+ * Why a code does not apply. Open: a server may name a reason this SDK has not
+ * seen yet, and a theme then shows its general sentence.
+ */
+export type CouponRefusalReason = "not_found" | "not_started" | "expired" | "used_up" | "identify_first" | "not_eligible" | "already_used" | "no_eligible_products" | "below_minimum_subtotal" | "below_minimum_quantity" | "delivery_already_free" | (string & {});
+export interface CouponRefusal {
+    reason: CouponRefusalReason;
+    /** The dinars (`below_minimum_subtotal`) or items (`below_minimum_quantity`) still missing. */
+    shortBy?: number | undefined;
+    /** When a `not_started` code begins. */
+    startsAt?: string | undefined;
+}
+/** A code applied — `discount` already out of the lines, delivery free with `freeShipping` — or refused. */
+export type CouponOutcome = {
+    code: string;
+    applied: true;
+    discount: number;
+    freeShipping: boolean;
+} | ({
+    code: string;
+    applied: false;
+} & CouponRefusal);
 export type CartDeliveryQuote = {
     available: true;
     fee: number;
@@ -359,8 +391,10 @@ export interface CreatedOrder {
     orderNumber: string;
     price: number;
     deliveryFee: number;
-    /** price + deliveryFee, after any offer. */
+    /** price + deliveryFee, offers and the coupon applied. */
     total: number;
+    /** What the coupon took off; null or absent without one. */
+    couponDiscount?: number | null | undefined;
 }
 /** One basket line in a create-order body. */
 export interface CreateOrderItemInput {
@@ -425,6 +459,8 @@ export interface CreateOrderInput {
     items?: CreateOrderItemInput[] | undefined;
     /** Landing-page attribution — best-effort; an unknown slug never blocks. */
     landingPageSlug?: string | undefined;
+    /** The code the shopper typed. An order whose code does not apply is refused whole (`couponRefusalOf`). */
+    couponCode?: string | undefined;
 }
 /**
  * The order's tracking destination — which Meta pixel it belongs to and

package/package.json

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