@wocart/storefront 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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

package/USAGE.md

@@ -1000,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.

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. */

package/package.json

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