@wocart/storefront 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.14.0 — 2026-10-18
+
+### Added
+
+- `mediaImageUrl(url, params, mediaDomain)` (`MediaImageParams`): the
+  Cloudflare resizing URL of a media-domain image, served by the media domain
+  itself, so it works wherever the storefront is hosted; `null` for any other
+  image. Every image helper builds its URL with it, and so does
+  `@wocart/theme/image-service`.
+
+### Changed
+
+- Every resizing URL starts with `onerror=redirect`: when a resize fails,
+  Cloudflare redirects to the original image instead of answering with an
+  error.
+
+## 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

@@ -214,6 +214,7 @@ server directly.
 | Export | Use it for |
 | --- | --- |
 | `formatMoney`, `optimizeImage`, `generateSrcSet` | Money text and image URLs |
+| `mediaImageUrl` | The Cloudflare resizing URL of a media-domain image, served by the media domain itself (any storefront host); `null` for any other image — the builder behind every image helper and `@wocart/theme/image-service` |
 | `createImageHelpers(mediaDomain)`, `getCardImage`, `getGalleryImage`, `getThumbnailImage`, `getHeroImage`, `getCategoryImage`, `getLogoImage` | The bound image toolkit (`IMAGE_SIZES` holds the presets) |
 | `WILAYAS`, `ALGERIA_COMMUNES`, `communesForWilaya` | Reference data: 58 wilayas, 1,551 communes, one wilaya's rows |
 | `normalizeAlgerianPhone`, `toLocalAlgerianMobile` | The one Algerian phone rule (accept/format) |
@@ -1000,10 +1001,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/index.d.ts

@@ -11,8 +11,8 @@
  */
 export { formatMoney } from "./utils/money.js";
 export type { MoneyFormatOptions } from "./utils/money.js";
-export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, } from "./utils/image.js";
-export type { ImageHelpers, ImageResizeOptions } from "./utils/image.js";
+export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, mediaImageUrl, } from "./utils/image.js";
+export type { ImageHelpers, ImageResizeOptions, MediaImageParams } from "./utils/image.js";
 export { productImageSource } from "./utils/product-image.js";
 export type { ProductImageSourceInput } from "./utils/product-image.js";
 export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";

package/dist/index.js

@@ -10,7 +10,7 @@
  * Internal modules stay reachable only through their intentional entry points.
  */
 export { formatMoney } from "./utils/money.js";
-export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, } from "./utils/image.js";
+export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, mediaImageUrl, } from "./utils/image.js";
 export { productImageSource } from "./utils/product-image.js";
 export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";
 export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";

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/dist/utils/image.d.ts

@@ -29,10 +29,30 @@ export interface ImageResizeOptions {
  *   { width: 400, height: 400 },
  *   'media.example.com'
  * );
- * // Returns: https://media.example.com/cdn-cgi/image/width=400,height=400,format=webp,quality=85,fit=cover/products/image.jpg
+ * // Returns: https://media.example.com/cdn-cgi/image/onerror=redirect,width=400,height=400,format=webp,quality=85,fit=cover/products/image.jpg
  * ```
  */
 export declare function optimizeImage(originalUrl: string, options: ImageResizeOptions, mediaDomain?: string): string;
+/** What `mediaImageUrl` can ask Cloudflare for; an omitted value is left to Cloudflare's default. */
+export interface MediaImageParams {
+    width?: number;
+    height?: number;
+    quality?: number;
+    format?: string;
+    fit?: "scale-down" | "contain" | "cover" | "crop" | "pad" | "squeeze";
+}
+/**
+ * The Cloudflare Image Resizing URL of an image on the media domain, served
+ * by the media domain itself (`https://<media>/cdn-cgi/image/<options>/<path>`)
+ * — so it works wherever the storefront is hosted, as long as the media
+ * domain's zone has Image Transformations on.
+ *
+ * `onerror=redirect` comes first: when a resize fails, Cloudflare redirects to
+ * the original image instead of answering with an error.
+ *
+ * @returns `null` when there is no media domain, or the URL is not on it.
+ */
+export declare function mediaImageUrl(originalUrl: string, params: MediaImageParams, mediaDomain?: string): string | null;
 /**
  * Predefined image sizes for common use cases
  */

package/dist/utils/image.js

@@ -22,39 +22,46 @@
  *   { width: 400, height: 400 },
  *   'media.example.com'
  * );
- * // Returns: https://media.example.com/cdn-cgi/image/width=400,height=400,format=webp,quality=85,fit=cover/products/image.jpg
+ * // Returns: https://media.example.com/cdn-cgi/image/onerror=redirect,width=400,height=400,format=webp,quality=85,fit=cover/products/image.jpg
  * ```
  */
 export function optimizeImage(originalUrl, options, mediaDomain) {
-    // No-op when mediaDomain is empty or URL doesn't match
-    if (!mediaDomain || !originalUrl) {
-        return originalUrl;
-    }
-    const normalizedDomain = `https://${mediaDomain.replace(/^https?:\/\//, "")}`;
+    const { width, height, quality = 85, format = "webp", fit = "cover" } = options;
+    return mediaImageUrl(originalUrl, { width, height, format, quality, fit }, mediaDomain) ?? originalUrl;
+}
+/**
+ * The Cloudflare Image Resizing URL of an image on the media domain, served
+ * by the media domain itself (`https://<media>/cdn-cgi/image/<options>/<path>`)
+ * — so it works wherever the storefront is hosted, as long as the media
+ * domain's zone has Image Transformations on.
+ *
+ * `onerror=redirect` comes first: when a resize fails, Cloudflare redirects to
+ * the original image instead of answering with an error.
+ *
+ * @returns `null` when there is no media domain, or the URL is not on it.
+ */
+export function mediaImageUrl(originalUrl, params, mediaDomain) {
+    if (!mediaDomain || !originalUrl)
+        return null;
     let mediaOrigin;
     let original;
     try {
-        mediaOrigin = new URL(normalizedDomain).origin;
+        mediaOrigin = new URL(`https://${mediaDomain.replace(/^https?:\/\//, "")}`).origin;
         original = new URL(originalUrl);
     }
     catch {
-        return originalUrl;
+        return null;
     }
-    // Only optimize a URL from the configured media origin
-    if (original.origin !== mediaOrigin) {
-        return originalUrl;
+    if (original.origin !== mediaOrigin)
+        return null;
+    const options = ["onerror=redirect"];
+    for (const key of ["width", "height", "format", "quality", "fit"]) {
+        const value = params[key];
+        if (value !== undefined && value !== "")
+            options.push(`${key}=${value}`);
     }
-    const { width, height, quality = 85, format = "webp", fit = "cover" } = options;
     const imagePath = `${original.pathname.replace(/^\/+/, "")}${original.search}${original.hash}`;
-    // Build the Cloudflare Image Resizing URL
-    const resizeParams = [
-        `width=${width}`,
-        `height=${height}`,
-        `format=${format}`,
-        `quality=${quality}`,
-        `fit=${fit}`,
-    ].join(",");
-    return `${mediaOrigin}/cdn-cgi/image/${resizeParams}/${imagePath}`;
+    return `${mediaOrigin}/cdn-cgi/image/${options.join(",")}/${imagePath}`;
 }
 /**
  * Predefined image sizes for common use cases

package/package.json

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