@wocart/storefront 1.13.0 → 1.14.0

package/CHANGELOG.md

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

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) |

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/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.13.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",