@wocart/storefront 1.23.0 → 2.0.0

package/dist/utils/image.js

@@ -1,119 +1,99 @@
 /**
- * Cloudflare Image Resizing Utility
+ * The store's images: where a key is served, and how a photo is asked for at
+ * the size a page shows it.
  *
- * Generates optimized image URLs using Cloudflare's Image Resizing service.
- * Automatically resizes images to exact dimensions and converts to WebP format.
- *
- * Deep module: hides Cloudflare CDN-CGI URL construction, fit modes, format
- * negotiation, and no-op fallback logic behind a simple interface.
- */
-/**
- * Generate an optimized image URL using Cloudflare Image Resizing
- *
- * @param originalUrl - The original image URL from R2
- * @param options - Resize and optimization options
- * @param mediaDomain - Media domain (e.g., "media.example.com" or "https://media.example.com")
- * @returns Optimized image URL
- *
- * @example
- * ```ts
- * const url = optimizeImage(
- *   'https://media.example.com/products/image.jpg',
- *   { width: 400, height: 400 },
- *   'media.example.com'
- * );
- * // Returns: https://media.example.com/cdn-cgi/image/onerror=redirect,width=400,height=400,format=webp,quality=85,fit=cover/products/image.jpg
- * ```
+ * Every image the store's server answers is a `MediaImage` — its key and its
+ * URL — and the store's config carries its `MediaDelivery`: the origin every
+ * key is served from and how that origin resizes. These helpers take that
+ * delivery, so one theme works on every host a store can use.
  */
-export function optimizeImage(originalUrl, options, mediaDomain) {
-    const { width, height, quality = 85, format = "webp", fit = "cover" } = options;
-    return mediaImageUrl(originalUrl, { width, height, format, quality, fit }, mediaDomain) ?? originalUrl;
+export const MEDIA_DELIVERY_KINDS = ["imagekit", "cloudflare", "direct"];
+const MEDIA_FOLDERS = ["products", "landing", "reviews"];
+const KEY_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Whether `value` can be a Media Key: a store folder, then segments of letters, digits, `.`, `_` and `-` that start with a letter or digit. */
+export function isMediaKey(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 512)
+        return false;
+    const [folder, ...rest] = value.split("/");
+    return MEDIA_FOLDERS.includes(folder) && rest.length > 0 && rest.every((segment) => KEY_SEGMENT.test(segment));
 }
 /**
- * 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.
+ * The URL of a key in the store's media — what a theme's `image` field
+ * stores (`products/3f2a9c.webp`). The key is the image's identity; its URL
+ * depends on the store's delivery, so it is derived at render, never stored.
  *
- * `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.
+ * @returns `null` without a delivery, or for a value that is not a Media Key.
  */
-export function mediaImageUrl(originalUrl, params, mediaDomain) {
-    if (!mediaDomain || !originalUrl)
-        return null;
-    const mediaOrigin = mediaOriginOf(mediaDomain);
-    let original;
-    try {
-        original = new URL(originalUrl);
-    }
-    catch {
-        return null;
-    }
-    if (mediaOrigin === null || original.origin !== mediaOrigin)
-        return null;
+export function mediaUrl(key, delivery) {
+    return delivery && isMediaKey(key) ? `${delivery.origin}/${key}` : null;
+}
+const IMAGEKIT_CROP = {
+    cover: "c-maintain_ratio",
+    crop: "c-maintain_ratio",
+    "scale-down": "c-at_max",
+    contain: "c-at_max_enlarge",
+    squeeze: "c-force",
+    pad: "cm-pad_resize",
+};
+function imagekitUrl(url, params) {
+    const options = [];
+    if (params.width)
+        options.push(`w-${params.width}`);
+    if (params.height)
+        options.push(`h-${params.height}`);
+    if (params.fit)
+        options.push(IMAGEKIT_CROP[params.fit]);
+    if (params.quality)
+        options.push(`q-${params.quality}`);
+    if (params.format)
+        options.push(`f-${params.format === "jpeg" ? "jpg" : params.format}`);
+    if (options.length === 0)
+        return url;
+    return `${url}${url.includes("?") ? "&" : "?"}tr=${options.join(",")}`;
+}
+function cloudflareUrl(url, params) {
     const options = ["onerror=redirect"];
-    for (const key of ["width", "height", "format", "quality", "fit"]) {
-        const value = params[key];
+    for (const name of ["width", "height", "format", "quality", "fit"]) {
+        const value = params[name];
         if (value !== undefined && value !== "")
-            options.push(`${key}=${value}`);
-    }
-    const imagePath = `${original.pathname.replace(/^\/+/, "")}${original.search}${original.hash}`;
-    return `${mediaOrigin}/cdn-cgi/image/${options.join(",")}/${imagePath}`;
-}
-/** The media domain (`media.example.com`, with or without a scheme) as an HTTPS origin, or `null`. */
-function mediaOriginOf(mediaDomain) {
-    try {
-        return new URL(`https://${mediaDomain.replace(/^https?:\/\//, "")}`).origin;
-    }
-    catch {
-        return null;
+            options.push(`${name}=${value}`);
     }
+    const { origin, pathname, search } = new URL(url);
+    return `${origin}/cdn-cgi/image/${options.join(",")}/${pathname.replace(/^\/+/, "")}${search}`;
 }
 /**
- * The public URL of an object in the store's media bucket, from its key —
- * what a theme's `image` field stores (`products/3f2a9c.webp`). The key is
- * the image's identity; the URL depends on where the store serves its media,
- * so it is derived here, at render, never stored. Pass the result to
- * `mediaImageUrl` or Astro's `<Image>` to resize it.
+ * A photo of the store's media at the size and format a page shows it, from
+ * the delivery's own resizer: ImageKit's `?tr=` or Cloudflare's
+ * `/cdn-cgi/image/` (which falls back to the original when a resize fails).
  *
- * @returns `null` when there is no media domain, or the key cannot name an
- * object: empty, too long, an empty, `.` or `..` segment (a leading slash
- * makes an empty one), whitespace, control characters, a backslash, `?` or `#`.
+ * @returns `null` without a delivery, for a URL not served by it, or for a
+ * `direct` delivery, which does not resize — show the original then.
  */
-export function mediaUrl(key, mediaDomain) {
-    if (!mediaDomain || typeof key !== "string" || key.length === 0 || key.length > 512)
-        return null;
-    if (/[\s\\?#\u0000-\u001f\u007f]/.test(key))
-        return null;
-    const segments = key.split("/");
-    if (segments.some((segment) => segment === "" || segment === "." || segment === ".."))
+export function mediaImageUrl(url, params, delivery) {
+    if (!delivery || delivery.kind === "direct" || typeof url !== "string" || !url.startsWith(`${delivery.origin}/`))
         return null;
-    const origin = mediaOriginOf(mediaDomain);
-    return origin === null ? null : `${origin}/${segments.map(encodeURIComponent).join("/")}`;
+    return delivery.kind === "imagekit" ? imagekitUrl(url, params) : cloudflareUrl(url, params);
 }
 /**
  * The same photo at several widths, with width descriptors
  * (`… 360w, … 720w`), for an `<img>` whose `sizes` says how wide it shows —
- * a phone then downloads a phone-sized file. Each size is converted to the
- * best format the browser takes (`format=auto`).
+ * a phone then downloads a phone-sized file, in the best format it takes.
  *
- * @returns `null` when there is no media domain, the URL is not on it, or no
+ * @returns `null` when the photo cannot be resized (see `mediaImageUrl`) or no
  * width is a positive whole number.
  */
-export function mediaImageSrcset(src, widths, options = {}) {
+export function mediaImageSrcset(src, widths, options) {
     const sizes = [...new Set(widths.filter((width) => Number.isInteger(width) && width > 0))].sort((a, b) => a - b);
     if (sizes.length === 0)
         return null;
-    const { ratio, quality, mediaDomain } = options;
+    const { ratio, quality, delivery } = options;
     const cropped = ratio !== undefined && Number.isFinite(ratio) && ratio > 0;
     const encoding = quality === undefined ? {} : { quality };
     const entries = [];
     for (const width of sizes) {
         const url = mediaImageUrl(src, cropped
             ? { width, height: Math.max(1, Math.round(width * ratio)), fit: "cover", format: "auto", ...encoding }
-            : { width, fit: "scale-down", format: "auto", ...encoding }, mediaDomain);
+            : { width, fit: "scale-down", format: "auto", ...encoding }, delivery);
         if (url === null)
             return null;
         entries.push(`${url} ${width}w`);
@@ -121,17 +101,17 @@ export function mediaImageSrcset(src, widths, options = {}) {
     return entries.join(", ");
 }
 /**
- * A picked image as a theme draws it: its URL on the store's media domain,
- * its alt text (empty when the merchant wrote none), its size, and its focal
- * point as `object-position`, so a cropped photo keeps what matters in view.
+ * A picked image as a theme draws it: its URL in the store's media, its alt
+ * text (empty when the merchant wrote none), its size, and its focal point as
+ * `object-position`, so a cropped photo keeps what matters in view.
  *
- * @returns `null` when no image is picked, the key cannot name an object, or
- * the store has no media domain.
+ * @returns `null` when no image is picked, the key is not a Media Key, or there
+ * is no delivery.
  */
-export function pictureOf(image, mediaDomain) {
+export function pictureOf(image, delivery) {
     if (!image)
         return null;
-    const src = mediaUrl(image.key, mediaDomain);
+    const src = mediaUrl(image.key, delivery);
     if (src === null)
         return null;
     const percent = (value) => `${Math.round(Math.min(1, Math.max(0, value)) * 100)}%`;
@@ -144,76 +124,3 @@ export function pictureOf(image, mediaDomain) {
         position: focal && Number.isFinite(focal.x) && Number.isFinite(focal.y) ? `${percent(focal.x)} ${percent(focal.y)}` : undefined,
     };
 }
-/**
- * Predefined image sizes for common use cases
- */
-export const IMAGE_SIZES = {
-    // Product cards (grid view)
-    CARD: { width: 400, height: 400, quality: 85 },
-    // Product gallery main image
-    GALLERY_MAIN: { width: 800, height: 800, quality: 90 },
-    // Product gallery thumbnails
-    GALLERY_THUMB: { width: 80, height: 80, quality: 80 },
-    // Hero/banner images
-    HERO: { width: 1200, height: 600, quality: 90 },
-    // Category images
-    CATEGORY: { width: 300, height: 200, quality: 85 },
-    // Logo/brand images
-    LOGO: { width: 200, height: 80, quality: 90, fit: "contain" },
-};
-/**
- * Quick helper functions for common image sizes
- *
- * These take the media domain per call. Theme code usually binds it once with
- * `createImageHelpers(mediaDomain)` and uses the returned helpers, so a call
- * site can never forget the domain and silently ship an unoptimized image.
- */
-export const getCardImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.CARD, mediaDomain);
-export const getGalleryImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.GALLERY_MAIN, mediaDomain);
-export const getThumbnailImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.GALLERY_THUMB, mediaDomain);
-export const getHeroImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.HERO, mediaDomain);
-export const getCategoryImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.CATEGORY, mediaDomain);
-export const getLogoImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.LOGO, mediaDomain);
-/**
- * Generate responsive image srcset for different screen sizes
- *
- * @param originalUrl - The original image URL
- * @param baseWidth - Base width for 1x display
- * @param baseHeight - Base height for 1x display
- * @param mediaDomain - Media domain
- * @returns srcset string for responsive images
- *
- * @example
- * ```ts
- * const srcset = generateSrcSet(
- *   'https://media.example.com/products/image.jpg',
- *   400,
- *   400,
- *   'media.example.com'
- * );
- * // Returns: "url 1x, url 1.5x, url 2x"
- * ```
- */
-export function generateSrcSet(originalUrl, baseWidth, baseHeight, mediaDomain) {
-    const sizes = [
-        { width: baseWidth, height: baseHeight, density: "1x" },
-        { width: Math.round(baseWidth * 1.5), height: Math.round(baseHeight * 1.5), density: "1.5x" },
-        { width: baseWidth * 2, height: baseHeight * 2, density: "2x" },
-    ];
-    return sizes
-        .map((size) => `${optimizeImage(originalUrl, size, mediaDomain)} ${size.density}`)
-        .join(", ");
-}
-export function createImageHelpers(mediaDomain) {
-    return {
-        optimizeImage: (originalUrl, options, domain = mediaDomain) => optimizeImage(originalUrl, options, domain),
-        generateSrcSet: (originalUrl, baseWidth, baseHeight, domain = mediaDomain) => generateSrcSet(originalUrl, baseWidth, baseHeight, domain),
-        IMAGE_SIZES,
-        getCardImage: (url) => getCardImage(url, mediaDomain),
-        getGalleryImage: (url) => getGalleryImage(url, mediaDomain),
-        getThumbnailImage: (url) => getThumbnailImage(url, mediaDomain),
-        getHeroImage: (url) => getHeroImage(url, mediaDomain),
-        getCategoryImage: (url) => getCategoryImage(url, mediaDomain),
-        getLogoImage: (url) => getLogoImage(url, mediaDomain),
-    };
-}

package/dist/utils/product-image.d.ts

@@ -9,29 +9,29 @@
  *
  * Kept as a function rather than an inline fallback so it is one rule with one
  * test, and so a cart, a checkout summary and a product card cannot disagree
- * about which photo a product "is". Pair it with `getThumbnailImage` /
- * `getCardImage` to turn the answer into a resized URL.
+ * about which photo a product "is". Pair it with `mediaImageUrl` to turn the
+ * answer into a resized URL.
  */
 /** The least an uploaded image must carry to be usable as a source. */
 export interface ProductImageSourceInput {
     coverImage?: {
-        src?: string | null;
+        url?: string | null;
     } | null;
     images?: Array<{
-        src?: string | null;
+        url?: string | null;
     }> | null;
 }
 /**
  * The product's representative image URL, or `null` when it has none.
  *
  * Prefers the merchant's chosen cover, falls back to the first usable gallery
- * image, and treats a blank `src` as no image at all — so a caller renders its
+ * image, and treats a blank `url` as no image at all — so a caller renders its
  * placeholder exactly when the product genuinely has no photograph.
  *
  * @example
  * ```ts
  * const src = productImageSource(product); // Product | ProductList
- * const thumbnail = src ? getThumbnailImage(src) : null;
+ * const thumbnail = src ? mediaImageUrl(src, { width: 160, height: 160, fit: "cover" }, config.media) : null;
  * ```
  */
 export declare function productImageSource(product: ProductImageSourceInput | null | undefined): string | null;

package/dist/utils/product-image.js

@@ -9,20 +9,20 @@
  *
  * Kept as a function rather than an inline fallback so it is one rule with one
  * test, and so a cart, a checkout summary and a product card cannot disagree
- * about which photo a product "is". Pair it with `getThumbnailImage` /
- * `getCardImage` to turn the answer into a resized URL.
+ * about which photo a product "is". Pair it with `mediaImageUrl` to turn the
+ * answer into a resized URL.
  */
 /**
  * The product's representative image URL, or `null` when it has none.
  *
  * Prefers the merchant's chosen cover, falls back to the first usable gallery
- * image, and treats a blank `src` as no image at all — so a caller renders its
+ * image, and treats a blank `url` as no image at all — so a caller renders its
  * placeholder exactly when the product genuinely has no photograph.
  *
  * @example
  * ```ts
  * const src = productImageSource(product); // Product | ProductList
- * const thumbnail = src ? getThumbnailImage(src) : null;
+ * const thumbnail = src ? mediaImageUrl(src, { width: 160, height: 160, fit: "cover" }, config.media) : null;
  * ```
  */
 export function productImageSource(product) {
@@ -30,9 +30,9 @@ export function productImageSource(product) {
         return null;
     const candidates = [product.coverImage, ...(product.images ?? [])];
     for (const candidate of candidates) {
-        const src = candidate?.src;
-        if (typeof src === "string" && src.trim().length > 0)
-            return src;
+        const url = candidate?.url;
+        if (typeof url === "string" && url.trim().length > 0)
+            return url;
     }
     return null;
 }

package/package.json

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