@wocart/storefront 1.11.0 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.13.0 — 2026-10-17
+
+### Added
+
+- A cart quote names its offers: `CartValidationLine.offerName`, and each
+  `CartReward` says what will be given — `variantId`, `variantLabel` and the
+  giving offer's `offerName` — in the shopper's language. All absent from an
+  older server.
+
+## 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

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
@@ -972,10 +1000,17 @@ The server re-prices catalog lines, merges duplicate lines, checks stock and
 offers, and calculates free-delivery eligibility. CartValidation contains:
 
 - lines with productId, variantId, variantLabel, productName, quantity,
-  unitPrice, lineTotal, maxQuantity, and blocker;
-- subtotal and rewards;
+  unitPrice, lineTotal (offers and the coupon applied), offerId and
+  offerName (the offer that priced the line), discount, maxQuantity, and
+  blocker;
+- subtotal and rewards — each gift as the order will give it: productName,
+  variantLabel, quantity and the offerName that gives it, free;
 - freeDelivery with fromOffer, threshold, qualified, and remaining.
 
+Show a line at `lineTotal + discount` (the coupon has its own row) and its
+catalog price struck through when an offer brought it down; list each reward
+as its own free row, so the basket reads like the order it becomes.
+
 Line blockers include missing, unlisted, and out_of_stock. The creative
 experience is yours: inline warnings, a highlighted invalid line, a drawer,
 or a guided correction step. The server result is not optional.
@@ -1081,7 +1116,8 @@ if (quoted.success && quoted.data.coupon) {
   //          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),
+  //          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.
 }
 ~~~

package/dist/index.d.ts

@@ -36,6 +36,8 @@ 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";

package/dist/index.js

@@ -27,5 +27,6 @@ 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>>;
+    offerName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     discount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     maxQuantity: z.ZodNullable<z.ZodNumber>;
     blocker: z.ZodNullable<z.ZodEnum<{
@@ -723,8 +724,11 @@ export declare const CartValidationLineSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const CartRewardSchema: z.ZodObject<{
     offerId: z.ZodString;
+    offerName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     productId: z.ZodNullable<z.ZodString>;
     productName: z.ZodNullable<z.ZodString>;
+    variantId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    variantLabel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     quantity: z.ZodNumber;
 }, z.core.$strip>;
 /**
@@ -755,6 +759,7 @@ export declare const CartValidationSchema: z.ZodObject<{
         unitPrice: z.ZodNumber;
         lineTotal: z.ZodNumber;
         offerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        offerName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         discount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         maxQuantity: z.ZodNullable<z.ZodNumber>;
         blocker: z.ZodNullable<z.ZodEnum<{
@@ -766,8 +771,11 @@ export declare const CartValidationSchema: z.ZodObject<{
     subtotal: z.ZodNumber;
     rewards: z.ZodArray<z.ZodObject<{
         offerId: z.ZodString;
+        offerName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         productId: z.ZodNullable<z.ZodString>;
         productName: z.ZodNullable<z.ZodString>;
+        variantId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        variantLabel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         quantity: z.ZodNumber;
     }, z.core.$strip>>;
     freeDelivery: z.ZodObject<{

package/dist/schemas.js

@@ -353,6 +353,8 @@ export const CartValidationLineSchema = z.object({
     lineTotal: z.number(),
     /** The offer applied to the line; absent from a server that predates offers on lines. */
     offerId: z.string().nullish(),
+    /** That offer's name, in the shopper's language; absent from an older server. */
+    offerName: 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(),
@@ -360,8 +362,13 @@ export const CartValidationLineSchema = z.object({
 });
 export const CartRewardSchema = z.object({
     offerId: z.string(),
+    /** The offer's name, in the shopper's language; absent from an older server. */
+    offerName: z.string().nullish(),
     productId: z.string().nullable(),
     productName: z.string().nullable(),
+    /** The variant given and its label; absent from an older server. */
+    variantId: z.string().nullish(),
+    variantLabel: z.string().nullish(),
     quantity: z.number().int(),
 });
 /**

package/dist/types.d.ts

@@ -314,6 +314,8 @@ export interface CartValidationLine {
     lineTotal: number;
     /** The offer applied to the line; null or absent when none. */
     offerId?: string | null | undefined;
+    /** That offer's name, in the shopper's language; null or absent when none. */
+    offerName?: 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. */
@@ -325,10 +327,16 @@ export interface CartValidationLine {
     blocker: "missing" | "unlisted" | "out_of_stock" | null;
 }
 /** A satisfied Buy-X-Get-Y reward, appended server-side at order time. */
+/** A gift the basket earns, as the order will give it: free, beside the lines. */
 export interface CartReward {
     offerId: string;
+    /** The offer's name, in the shopper's language; absent from an older server. */
+    offerName?: string | null | undefined;
     productId: string | null;
     productName: string | null;
+    /** The variant given and its label; null for a product without variants, absent from an older server. */
+    variantId?: string | null | undefined;
+    variantLabel?: string | null | undefined;
     quantity: number;
 }
 /** The catalog's truth about a basket, right now. Read-only — nothing is written. */
@@ -358,7 +366,7 @@ export interface CartValidation {
  * 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 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. */

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.11.0",
+  "version": "1.13.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",