@wocart/storefront 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.12.0 — 2026-10-17
+
+### Added
+
+- **Variant picker.** `initialVariant(product)`, `pickOption(product,
+  selection, option, value)`, `optionStates(product, selection)` and
+  `variantFor(variants, selection)` (`OptionSelection`, `OptionState`,
+  `PickerVariant`): the variant a page opens on, the variant a picked value
+  means — always one that exists — and each value's state.
+- `CouponRefusalReason` names `offer_applied`: every line of the basket is
+  already priced by an offer, and a code covers only lines no offer holds.
+
+### Fixed
+
+- `getProductView(product).defaultVariant` is the merchant's default only
+  when it can be sold, else the first variant that can — never a sold-out or
+  switched-off one while another is in stock.
+
+## 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

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 |
+| `initialVariant`, `pickOption`, `optionStates`, `variantFor` | Option buttons: the variant a page opens on, the variant a picked value means, each value's state (available, sold out, not made) |
 | `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 |
@@ -647,6 +648,33 @@ Show the tiers as choices; never compute the total yourself. The cart quote
 delivery — and the order charges exactly that. A tier locked to one variant
 (`triggerVariantId`) counts and prices only that variant.
 
+`product.offers` lists only offers the shopper can earn today: an offer whose
+reward is out of stock, or a tier that costs what the catalog does, is left
+out until it can give something.
+
+**Option buttons.** Never derive a variant from each option's first value: a
+shirt made in white M and blue L has no "white L". `getProductView(product)
+.defaultVariant` (the same as `initialVariant(product)`) is the variant a page
+opens on — the merchant's default when it can be sold, else the first that
+can. When the shopper picks a value, `pickOption` names the variant they mean
+and the selection to show, keeping most of their other choices; the buttons
+then always show a variant that exists, the one the order is placed for.
+
+~~~ts
+let selection = getProductView(product).defaultVariant?.variations ?? {};
+function choose(option: string, value: string) {
+  const picked = pickOption(product, selection, option, value);
+  if (!picked.variant) return;
+  selection = picked.selection;
+  render(picked.variant, optionStates(product, selection));
+  // optionStates: { Colour: { White: "available", Black: "sold_out", Blue: "unavailable" }, … }
+}
+~~~
+
+The picker reads only `variations`, `active`, `inventory`, `position` and
+`isDefault` of each variant (`PickerVariant`), so a page may hand it a
+lighter copy.
+
 ### Product lists
 
 ~~~ts
@@ -1059,7 +1087,45 @@ 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, offer_applied (an offer already prices
+//          every line), 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

@@ -35,6 +35,10 @@ export * from "./schemas.js";
 export * from "./domain.js";
 export * from "./product-view.js";
 export { getOfferTierView, getQuantityTierViews } from "./offer-view.js";
+export { COUPON_NOT_APPLICABLE, COUPON_URL_PARAM, couponFromUrl, couponRefusalOf } from "./coupon.js";
+export { initialVariant, optionStates, pickOption, variantFor } from "./variant-picker.js";
+export type { OptionSelection, OptionState, PickerVariant } from "./variant-picker.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";

package/dist/index.js

@@ -26,5 +26,7 @@ export * from "./schemas.js";
 export * from "./domain.js";
 export * from "./product-view.js";
 export { getOfferTierView, getQuantityTierViews } from "./offer-view.js";
+export { COUPON_NOT_APPLICABLE, COUPON_URL_PARAM, couponFromUrl, couponRefusalOf } from "./coupon.js";
+export { initialVariant, optionStates, pickOption, variantFor } from "./variant-picker.js";
 export { createAbandonedCheckoutTracker } from "./abandoned-checkout.js";
 export { META_CURRENCY, buildMetaAddToCartPayload, buildMetaInitiateCheckoutPayload, buildMetaProductPayload, buildMetaViewContentPayload, createMetaPixelTracker, } from "./meta-tracking.js";

package/dist/product-view.js

@@ -1,3 +1,4 @@
+import { initialVariant } from "./variant-picker.js";
 function discountOf(basePrice, comparePrice) {
     if (comparePrice == null || comparePrice <= basePrice) {
         return { hasDiscount: false, discountPct: 0 };
@@ -17,9 +18,7 @@ function stockOf(product) {
     };
 }
 export function getProductView(product) {
-    const defaultVariant = product.hasVariants
-        ? (product.variants.find((variant) => variant.isDefault) ?? product.variants[0] ?? null)
-        : null;
+    const defaultVariant = product.hasVariants ? initialVariant(product) : null;
     const basePrice = defaultVariant?.price ?? product.price;
     const comparePrice = defaultVariant?.compareAtPrice ?? product.compareAtPrice ?? null;
     return {

package/dist/schemas.d.ts

@@ -713,6 +713,7 @@ export declare const CartValidationLineSchema: z.ZodObject<{
     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";
@@ -726,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;
@@ -736,6 +755,7 @@ export declare const CartValidationSchema: z.ZodObject<{
         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";
@@ -765,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;
@@ -772,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

@@ -351,8 +351,10 @@ export const CartValidationLineSchema = z.object({
     quantity: z.number().int(),
     unitPrice: z.number(),
     lineTotal: z.number(),
-    /** The quantity-pricing offer that set `lineTotal`; absent from a server that predates offers on lines. */
+    /** 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(),
 });
@@ -362,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(),
@@ -378,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(),
@@ -385,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

@@ -310,10 +310,12 @@ export interface CartValidationLine {
     quantity: number;
     /** CURRENT catalog price — the cart's optimistic price is display-only. */
     unitPrice: number;
-    /** What the line costs: unit price × quantity, or its quantity-pricing tier's price. */
+    /** What the line costs, offers and the coupon applied. */
     lineTotal: number;
-    /** The quantity-pricing offer that set `lineTotal`; null or absent at the catalog price. */
+    /** 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;
     /**
@@ -349,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" | "offer_applied" | "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;
@@ -365,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 {
@@ -431,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/dist/variant-picker.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Choosing a variant with option buttons — the rule every product page needs,
+ * so no theme guesses it.
+ *
+ * A page opens on a variant that can be sold, its buttons showing that
+ * variant's values. A value picked that does not combine with the other
+ * choices moves the selection to the variant that has it and keeps most of
+ * them, so what the buttons show is always a variant that exists — the one
+ * the order is placed for. Each value can be told apart: available, sold out,
+ * or not made with the other choices.
+ */
+import type { ProductVariant } from "./types.js";
+/** What the picker reads of a variant — a page may hand it a lighter copy than `ProductVariant`. */
+export type PickerVariant = Pick<ProductVariant, "variations" | "active" | "inventory" | "position" | "isDefault">;
+/** Option name → chosen value, as a product's `variantOptions` name them. */
+export type OptionSelection = Readonly<Record<string, string>>;
+export type OptionState = "available" | "sold_out" | "unavailable";
+interface Catalog<V extends PickerVariant> {
+    readonly variants: readonly V[];
+    readonly trackInventory: boolean;
+}
+/** The variant whose every option has the value `selection` gives it, or null. */
+export declare function variantFor<V extends PickerVariant>(variants: readonly V[], selection: OptionSelection): V | null;
+/**
+ * The variant a product page opens on: the merchant's default when it can be
+ * sold, else the first that can, else the default (or first) shown sold out.
+ */
+export declare function initialVariant<V extends PickerVariant>(product: Catalog<V>): V | null;
+/**
+ * The shopper picks `value` for `option`. The variant they mean is the one
+ * with that value that keeps most of their other choices — one that can be
+ * sold before one that cannot, then the catalog's order. Null, with the
+ * selection unchanged, when no variant has the value.
+ */
+export declare function pickOption<V extends PickerVariant>(product: Catalog<V>, selection: OptionSelection, option: string, value: string): {
+    variant: V | null;
+    selection: OptionSelection;
+};
+/**
+ * Each value of each option, given the other choices: `available` when a
+ * variant with it and the other choices can be sold, `sold_out` when that
+ * variant exists without stock, `unavailable` when it is not made.
+ */
+export declare function optionStates<V extends PickerVariant>(product: Catalog<V> & {
+    readonly variantOptions?: readonly {
+        readonly name: string;
+        readonly values: readonly {
+            readonly value: string;
+        }[];
+    }[] | null;
+}, selection: OptionSelection): Record<string, Record<string, OptionState>>;
+export {};

package/dist/variant-picker.js

@@ -0,0 +1,46 @@
+const live = (variant) => variant.active;
+const sellable = (product, variant) => live(variant) && (!product.trackInventory || variant.inventory > 0);
+const byPosition = (a, b) => a.position - b.position;
+/** The variant whose every option has the value `selection` gives it, or null. */
+export function variantFor(variants, selection) {
+    return variants.find((variant) => live(variant) && Object.entries(variant.variations).every(([option, value]) => selection[option] === value)) ?? null;
+}
+/**
+ * The variant a product page opens on: the merchant's default when it can be
+ * sold, else the first that can, else the default (or first) shown sold out.
+ */
+export function initialVariant(product) {
+    const ordered = product.variants.filter(live).sort(byPosition);
+    const preferred = ordered.find((variant) => variant.isDefault) ?? ordered[0] ?? null;
+    if (preferred && sellable(product, preferred))
+        return preferred;
+    return ordered.find((variant) => sellable(product, variant)) ?? preferred;
+}
+/**
+ * The shopper picks `value` for `option`. The variant they mean is the one
+ * with that value that keeps most of their other choices — one that can be
+ * sold before one that cannot, then the catalog's order. Null, with the
+ * selection unchanged, when no variant has the value.
+ */
+export function pickOption(product, selection, option, value) {
+    const kept = (variant) => Object.entries(selection).filter(([name, chosen]) => variant.variations[name] === chosen).length;
+    const candidates = product.variants.filter((variant) => live(variant) && variant.variations[option] === value);
+    const best = candidates.sort((a, b) => kept(b) - kept(a) || Number(sellable(product, b)) - Number(sellable(product, a)) || byPosition(a, b))[0];
+    return best ? { variant: best, selection: { ...best.variations } } : { variant: null, selection };
+}
+/**
+ * Each value of each option, given the other choices: `available` when a
+ * variant with it and the other choices can be sold, `sold_out` when that
+ * variant exists without stock, `unavailable` when it is not made.
+ */
+export function optionStates(product, selection) {
+    const states = {};
+    for (const option of product.variantOptions ?? []) {
+        states[option.name] = {};
+        for (const { value } of option.values) {
+            const match = variantFor(product.variants, { ...selection, [option.name]: value });
+            states[option.name][value] = match === null ? "unavailable" : sellable(product, match) ? "available" : "sold_out";
+        }
+    }
+    return states;
+}

package/package.json

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