@shopware/helpers 1.5.0 → 1.7.0

package/README.md

@@ -30,14 +30,107 @@ export default defineConfig({
 });
 ```
 
+## `getBackgroundImageUrl` helper
+
+The `getBackgroundImageUrl` function generates optimized CSS `url()` values for CMS background images. It extracts the raw URL, calculates the appropriate dimensions based on the media metadata, and applies image transformation parameters.
+
+### Usage
+
+```ts
+import { getBackgroundImageUrl } from "@shopware/helpers";
+
+const optimizedUrl = getBackgroundImageUrl(
+  "url(https://cdn.shopware.store/.../image.jpg)",
+  cmsBlockOrSection, // object with backgroundMedia.metaData.width/height
+  { format: "webp", quality: 85 }, // optional
+);
+// => 'url("https://cdn.shopware.store/.../image.jpg?width=1000&fit=crop,smart&format=webp&quality=85")'
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | CSS `url()` string containing the background image URL |
+| `element` | `{ backgroundMedia?: { metaData?: { width?: number; height?: number } } }` | CMS section or block object with media metadata |
+| `options` | `BackgroundImageOptions` (optional) | Format and quality settings |
+
+### `BackgroundImageOptions`
+
+```ts
+type BackgroundImageOptions = {
+  format?: string; // "webp" | "avif" | "jpg" | "png"
+  quality?: number; // 0-100
+};
+```
+
+When `format` or `quality` are provided, they are appended as query parameters to the image URL. If omitted, only the dimension and fit parameters are applied.
+
+## `generateCdnSrcSet` helper
+
+Generates an HTML `srcset` string using CDN width-based resizing. Useful as a fallback when media has no pre-generated thumbnails — the CDN handles on-the-fly resizing via query parameters.
+
+### Usage
+
+```ts
+import { generateCdnSrcSet } from "@shopware/helpers";
+
+const srcset = generateCdnSrcSet(
+  "https://cdn.shopware.store/.../image.jpg",
+  [400, 800, 1200, 1600], // optional, these are the defaults
+  { format: "webp", quality: 85 }, // optional
+);
+// => "https://cdn.shopware.store/.../image.jpg?width=400&fit=crop,smart&format=webp&quality=85 400w, ...800w, ...1200w, ...1600w"
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `src` | `string \| undefined` | Base image URL |
+| `widths` | `number[]` (optional) | Array of widths to generate (default: `[400, 800, 1200, 1600]`) |
+| `options` | `{ format?: string; quality?: number }` (optional) | Format and quality settings |
+
+Returns `undefined` if `src` is falsy or URL parsing fails.
+
+## `buildCdnImageUrl` helper
+
+Builds an optimized CDN image URL with size parameters based on rendered element dimensions. Adds `width` or `height` (whichever is larger) rounded up to the nearest 100px, plus `fit=crop,smart`.
+
+### Usage
+
+```ts
+import { buildCdnImageUrl } from "@shopware/helpers";
+
+const url = buildCdnImageUrl(
+  "https://cdn.shopware.store/.../image.jpg",
+  { width: 724, height: 760 },
+);
+// => "https://cdn.shopware.store/.../image.jpg?height=800&fit=crop,smart"
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `src` | `string \| undefined` | Base image URL |
+| `dimensions` | `{ width: number; height: number }` | Rendered element dimensions in pixels |
+| `options` | `{ format?: string; quality?: number }` (optional) | Format and quality settings |
+
+Returns an empty string if `src` is falsy. Returns the original `src` if URL parsing fails.
+
 <!-- AUTO GENERATED CHANGELOG -->
 
 ## Changelog
 
 Full changelog for stable version is available [here](https://github.com/shopware/frontends/blob/main/packages/helpers/CHANGELOG.md)
 
-### Latest changes: 1.5.0
+### Latest changes: 1.7.0
 
 ### Minor Changes
 
-- [#1910](https://github.com/shopware/frontends/pull/1910) [`c8fa438`](https://github.com/shopware/frontends/commit/c8fa438b38de6dbc43a2895f2d1906907447c384) Thanks [@mdanilowicz](https://github.com/mdanilowicz)! - Add helper for getting payment and shipping method icon
+- [#2287](https://github.com/shopware/frontends/pull/2287) [`c9bde38`](https://github.com/shopware/frontends/commit/c9bde38d497d5c6c2fbd97700a362eb44ce8881f) Thanks [@mkucmus](https://github.com/mkucmus)! - Add generateCdnSrcSet and buildCdnImageUrl helpers for synthetic responsive image srcset generation via CDN query params
+
+### Patch Changes
+
+- [#2320](https://github.com/shopware/frontends/pull/2320) [`a871c7b`](https://github.com/shopware/frontends/commit/a871c7b6256b75c2e40d93fc0354ba1971420062) Thanks [@mdanilowicz](https://github.com/mdanilowicz)! - Improve getSmallestThumbnailUrl - add media.url fallback when thumbnails are missing or empty

package/dist/index.d.mts

@@ -22,7 +22,7 @@ declare function getProductFreeShipping<T extends {
  * @category Product
  */
 declare function getMainImageUrl<T extends {
-    cover?: {
+    cover: {
         media?: {
             url: string;
         };
@@ -34,9 +34,11 @@ declare function getMainImageUrl<T extends {
         };
     }>;
 } | {
-    cover?: {
+    cover: {
         url: string;
     };
+} | {
+    cover: null;
 }>(object: T): string;
 
 /**
@@ -205,6 +207,18 @@ declare function getProductFromPrice<T extends {
     calculatedPrices?: CalculatedPrice[];
 }>(product: T): number | undefined;
 
+interface ProductWithManufacturer {
+    manufacturer?: {
+        translated?: {
+            name?: string;
+        };
+    };
+}
+/**
+ * Gets the translated name of the product manufacturer
+ */
+declare function getProductManufacturerName(product: ProductWithManufacturer): string;
+
 /**
  * Get product route information for Vue router.
  *
@@ -228,6 +242,24 @@ declare function getProductRoute<T extends {
     };
 };
 
+/**
+ * Checks if a product is on sale based on its price percentage
+ */
+declare function isProductOnSale(product: {
+    calculatedPrice: {
+        listPrice?: {
+            percentage?: number;
+        } | null;
+    };
+}): boolean;
+
+/**
+ * Checks if a product is marked as a top seller
+ */
+declare function isProductTopSeller(product: {
+    markAsTopseller?: boolean;
+}): boolean;
+
 /**
  * Get URL for category.
  * Some link {@link isLinkCategory}
@@ -365,6 +397,10 @@ type LayoutConfiguration = {
  */
 declare function getCmsLayoutConfiguration<T extends CmsBlock | CmsSection | CmsSlot>(content: T): LayoutConfiguration;
 
+type BackgroundImageOptions = {
+    format?: string;
+    quality?: number;
+};
 declare function getBackgroundImageUrl<T extends {
     backgroundMedia?: {
         metaData?: {
@@ -372,7 +408,7 @@ declare function getBackgroundImageUrl<T extends {
             height?: number;
         };
     };
-}>(url: string, element: T): string;
+}>(url: string, element: T, options?: BackgroundImageOptions): string;
 
 type UrlRoute = {
     path?: string;
@@ -418,6 +454,35 @@ declare function getCmsBreadcrumbs<T extends {
     name: string;
 }[];
 
+type CmsPageStructure = {
+    sections: Array<{
+        blocks?: Array<{
+            slots?: Array<{
+                type?: string;
+                data?: unknown;
+                [key: string]: unknown;
+            }>;
+            [key: string]: unknown;
+        }>;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+};
+/**
+ * Extracts the product listing data from a CMS page structure.
+ * Useful for SSR to get listing data early before components render.
+ *
+ * @param cmsPage - The CMS page object (Schemas["CmsPage"])
+ * @returns The product listing result or null if not found
+ *
+ * @example
+ * ```ts
+ * const listing = getProductListingFromCmsPage(cmsPage);
+ * createCategoryListingContext(listing);
+ * ```
+ */
+declare function getProductListingFromCmsPage<T = unknown>(cmsPage: CmsPageStructure): T | null;
+
 type Category = {
     apiAlias: "category";
 };
@@ -475,6 +540,18 @@ type ListingFilter = {
     code: string;
     id: string;
     name: string;
+    options?: Array<{
+        id: string;
+        translated?: {
+            name?: string;
+        };
+    }>;
+    entities?: Array<{
+        id: string;
+        translated?: {
+            name?: string;
+        };
+    }>;
 };
 /**
  * @beta
@@ -543,7 +620,7 @@ declare function getMedia<T extends {
 }>(lineItem: T): ProductMedia[];
 
 /**
- * Returns the smallest thumbnail url from the media object
+ * Returns the smallest thumbnail url from the media object or the media.url if no thumbnails are available
  *
  * @param media image object
  *
@@ -555,8 +632,54 @@ declare function getSmallestThumbnailUrl<T extends {
         width: number;
         url: string;
     }>;
+    url?: string;
 }>(media?: T): string | undefined;
 
+/**
+ * Encodes URL pathname to handle special characters (spaces, commas, etc.)
+ *
+ * @param urlString - The URL string to encode
+ * @returns The URL with encoded pathname
+ *
+ * @public
+ * @category Media
+ */
+declare function encodeUrlPath(urlString: string): string;
+/**
+ * Generates a srcset string using CDN width-based resizing.
+ * Useful as a fallback when media has no pre-generated thumbnails.
+ *
+ * @param src - Base image URL
+ * @param widths - Array of widths to generate (default: [400, 800, 1200, 1600])
+ * @param options - Optional format and quality params
+ * @returns srcset string or undefined if src is invalid
+ *
+ * @public
+ * @category Media
+ */
+declare function generateCdnSrcSet(src: string | undefined, widths?: number[], options?: {
+    format?: string;
+    quality?: number;
+}): string | undefined;
+/**
+ * Builds an optimized CDN image URL with size parameters.
+ * Adds width or height (whichever is larger, width if equal)
+ * rounded up to the nearest 100px.
+ *
+ * @param src - Base image URL
+ * @param dimensions - Rendered element dimensions (width and height)
+ * @returns Optimized image URL string
+ *
+ * @public
+ * @category Media
+ */
+declare function buildCdnImageUrl(src: string | undefined, dimensions: {
+    width: number;
+    height: number;
+}, options?: {
+    format?: string;
+    quality?: number;
+}): string;
 /**
  * Returns the srcset attribute for the image, for available breakpoints
  *
@@ -632,4 +755,4 @@ declare function canUseQuoteActions<T extends {
     };
 }>(quote: T): boolean;
 
-export { type HelpersCssClasses, type LayoutConfiguration, type TierPrice, type UiMediaGalleryItem, type UiMediaGalleryItemUrl, type UiProductOption, type UiProductProperty, type UiProductReview, buildUrlPrefix, canUseQuoteActions, downloadFile, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, relativeUrlSlash, urlIsAbsolute };
+export { type BackgroundImageOptions, type HelpersCssClasses, type LayoutConfiguration, type TierPrice, type UiMediaGalleryItem, type UiMediaGalleryItemUrl, type UiProductOption, type UiProductProperty, type UiProductReview, type UrlRouteOutput, buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductListingFromCmsPage, getProductManufacturerName, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, relativeUrlSlash, urlIsAbsolute };

package/dist/index.d.ts

@@ -22,7 +22,7 @@ declare function getProductFreeShipping<T extends {
  * @category Product
  */
 declare function getMainImageUrl<T extends {
-    cover?: {
+    cover: {
         media?: {
             url: string;
         };
@@ -34,9 +34,11 @@ declare function getMainImageUrl<T extends {
         };
     }>;
 } | {
-    cover?: {
+    cover: {
         url: string;
     };
+} | {
+    cover: null;
 }>(object: T): string;
 
 /**
@@ -205,6 +207,18 @@ declare function getProductFromPrice<T extends {
     calculatedPrices?: CalculatedPrice[];
 }>(product: T): number | undefined;
 
+interface ProductWithManufacturer {
+    manufacturer?: {
+        translated?: {
+            name?: string;
+        };
+    };
+}
+/**
+ * Gets the translated name of the product manufacturer
+ */
+declare function getProductManufacturerName(product: ProductWithManufacturer): string;
+
 /**
  * Get product route information for Vue router.
  *
@@ -228,6 +242,24 @@ declare function getProductRoute<T extends {
     };
 };
 
+/**
+ * Checks if a product is on sale based on its price percentage
+ */
+declare function isProductOnSale(product: {
+    calculatedPrice: {
+        listPrice?: {
+            percentage?: number;
+        } | null;
+    };
+}): boolean;
+
+/**
+ * Checks if a product is marked as a top seller
+ */
+declare function isProductTopSeller(product: {
+    markAsTopseller?: boolean;
+}): boolean;
+
 /**
  * Get URL for category.
  * Some link {@link isLinkCategory}
@@ -365,6 +397,10 @@ type LayoutConfiguration = {
  */
 declare function getCmsLayoutConfiguration<T extends CmsBlock | CmsSection | CmsSlot>(content: T): LayoutConfiguration;
 
+type BackgroundImageOptions = {
+    format?: string;
+    quality?: number;
+};
 declare function getBackgroundImageUrl<T extends {
     backgroundMedia?: {
         metaData?: {
@@ -372,7 +408,7 @@ declare function getBackgroundImageUrl<T extends {
             height?: number;
         };
     };
-}>(url: string, element: T): string;
+}>(url: string, element: T, options?: BackgroundImageOptions): string;
 
 type UrlRoute = {
     path?: string;
@@ -418,6 +454,35 @@ declare function getCmsBreadcrumbs<T extends {
     name: string;
 }[];
 
+type CmsPageStructure = {
+    sections: Array<{
+        blocks?: Array<{
+            slots?: Array<{
+                type?: string;
+                data?: unknown;
+                [key: string]: unknown;
+            }>;
+            [key: string]: unknown;
+        }>;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+};
+/**
+ * Extracts the product listing data from a CMS page structure.
+ * Useful for SSR to get listing data early before components render.
+ *
+ * @param cmsPage - The CMS page object (Schemas["CmsPage"])
+ * @returns The product listing result or null if not found
+ *
+ * @example
+ * ```ts
+ * const listing = getProductListingFromCmsPage(cmsPage);
+ * createCategoryListingContext(listing);
+ * ```
+ */
+declare function getProductListingFromCmsPage<T = unknown>(cmsPage: CmsPageStructure): T | null;
+
 type Category = {
     apiAlias: "category";
 };
@@ -475,6 +540,18 @@ type ListingFilter = {
     code: string;
     id: string;
     name: string;
+    options?: Array<{
+        id: string;
+        translated?: {
+            name?: string;
+        };
+    }>;
+    entities?: Array<{
+        id: string;
+        translated?: {
+            name?: string;
+        };
+    }>;
 };
 /**
  * @beta
@@ -543,7 +620,7 @@ declare function getMedia<T extends {
 }>(lineItem: T): ProductMedia[];
 
 /**
- * Returns the smallest thumbnail url from the media object
+ * Returns the smallest thumbnail url from the media object or the media.url if no thumbnails are available
  *
  * @param media image object
  *
@@ -555,8 +632,54 @@ declare function getSmallestThumbnailUrl<T extends {
         width: number;
         url: string;
     }>;
+    url?: string;
 }>(media?: T): string | undefined;
 
+/**
+ * Encodes URL pathname to handle special characters (spaces, commas, etc.)
+ *
+ * @param urlString - The URL string to encode
+ * @returns The URL with encoded pathname
+ *
+ * @public
+ * @category Media
+ */
+declare function encodeUrlPath(urlString: string): string;
+/**
+ * Generates a srcset string using CDN width-based resizing.
+ * Useful as a fallback when media has no pre-generated thumbnails.
+ *
+ * @param src - Base image URL
+ * @param widths - Array of widths to generate (default: [400, 800, 1200, 1600])
+ * @param options - Optional format and quality params
+ * @returns srcset string or undefined if src is invalid
+ *
+ * @public
+ * @category Media
+ */
+declare function generateCdnSrcSet(src: string | undefined, widths?: number[], options?: {
+    format?: string;
+    quality?: number;
+}): string | undefined;
+/**
+ * Builds an optimized CDN image URL with size parameters.
+ * Adds width or height (whichever is larger, width if equal)
+ * rounded up to the nearest 100px.
+ *
+ * @param src - Base image URL
+ * @param dimensions - Rendered element dimensions (width and height)
+ * @returns Optimized image URL string
+ *
+ * @public
+ * @category Media
+ */
+declare function buildCdnImageUrl(src: string | undefined, dimensions: {
+    width: number;
+    height: number;
+}, options?: {
+    format?: string;
+    quality?: number;
+}): string;
 /**
  * Returns the srcset attribute for the image, for available breakpoints
  *
@@ -632,4 +755,4 @@ declare function canUseQuoteActions<T extends {
     };
 }>(quote: T): boolean;
 
-export { type HelpersCssClasses, type LayoutConfiguration, type TierPrice, type UiMediaGalleryItem, type UiMediaGalleryItemUrl, type UiProductOption, type UiProductProperty, type UiProductReview, buildUrlPrefix, canUseQuoteActions, downloadFile, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, relativeUrlSlash, urlIsAbsolute };
+export { type BackgroundImageOptions, type HelpersCssClasses, type LayoutConfiguration, type TierPrice, type UiMediaGalleryItem, type UiMediaGalleryItemUrl, type UiProductOption, type UiProductProperty, type UiProductReview, type UrlRouteOutput, buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductListingFromCmsPage, getProductManufacturerName, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, relativeUrlSlash, urlIsAbsolute };

package/dist/index.mjs

@@ -91,6 +91,10 @@ function getProductFromPrice(product) {
   return void 0;
 }
 
+function getProductManufacturerName(product) {
+  return product.manufacturer?.translated?.name || "";
+}
+
 function getProductRoute(product) {
   return {
     path: getProductUrl(product),
@@ -101,6 +105,14 @@ function getProductRoute(product) {
   };
 }
 
+function isProductOnSale(product) {
+  return (product.calculatedPrice?.listPrice?.percentage ?? 0) > 0;
+}
+
+function isProductTopSeller(product) {
+  return !!product.markAsTopseller;
+}
+
 function getEntityPrefix(category) {
   switch (category.linkType) {
     case "category":
@@ -248,12 +260,18 @@ const getUrlFromBackgroundImage = (url) => {
   const match = url.match(regex);
   return !match ? url : match[1];
 };
-function getBackgroundImageUrl(url, element) {
+function getBackgroundImageUrl(url, element, options) {
   const backgroundImage = getUrlFromBackgroundImage(url);
   const width = element.backgroundMedia?.metaData?.width ?? 0;
   const height = element.backgroundMedia?.metaData?.height ?? 0;
   const biggestParam = width > height ? `width=${roundUp(width > 1920 ? 1900 : width)}` : `height=${roundUp(height > 1920 ? 1900 : height)}`;
-  const srcPath = `${backgroundImage}?${biggestParam}&fit=crop,smart`;
+  let srcPath = `${backgroundImage}?${biggestParam}&fit=crop,smart`;
+  if (options?.format) {
+    srcPath += `&format=${options.format}`;
+  }
+  if (options?.quality) {
+    srcPath += `&quality=${options.quality}`;
+  }
   return `url("${srcPath}")`;
 }
 
@@ -308,6 +326,12 @@ function getCmsBreadcrumbs(page) {
   ];
 }
 
+function getProductListingFromCmsPage(cmsPage) {
+  const slot = cmsPage.sections.flatMap((section) => section.blocks ?? []).flatMap((block) => block.slots ?? []).find((slot2) => slot2.type === "product-listing");
+  const listing = slot?.data?.listing;
+  return listing ?? null;
+}
+
 function getCmsEntityObject(response) {
   switch (response.resourceType) {
     case "frontend.detail.page":
@@ -410,6 +434,9 @@ function getMedia(lineItem) {
 
 function getSmallestThumbnailUrl(media) {
   if (!media || !media?.thumbnails?.length) {
+    if (media?.url) {
+      return media.url;
+    }
     return;
   }
   const lowest = media.thumbnails.reduce((previous, current) => {
@@ -418,12 +445,66 @@ function getSmallestThumbnailUrl(media) {
   return lowest?.url;
 }
 
+function encodeUrlPath(urlString) {
+  try {
+    const url = new URL(urlString);
+    url.pathname = url.pathname.split("/").map((segment) => encodeURIComponent(decodeURIComponent(segment))).join("/");
+    return url.toString();
+  } catch {
+    return urlString;
+  }
+}
+function generateCdnSrcSet(src, widths = [400, 800, 1200, 1600], options) {
+  if (!src) return void 0;
+  try {
+    return widths.map((w) => {
+      const url = new URL(encodeUrlPath(src));
+      url.searchParams.set("width", String(w));
+      url.searchParams.set("fit", "crop,smart");
+      if (options?.format) {
+        url.searchParams.set("format", options.format);
+      }
+      if (options?.quality) {
+        url.searchParams.set("quality", String(options.quality));
+      }
+      return `${url.toString()} ${w}w`;
+    }).join(", ");
+  } catch {
+    return void 0;
+  }
+}
+function buildCdnImageUrl(src, dimensions, options) {
+  if (!src) return "";
+  try {
+    const url = new URL(encodeUrlPath(src));
+    const DEFAULT_SIZE = 10;
+    const w = dimensions.width ? Math.ceil(dimensions.width / 100) * 100 : DEFAULT_SIZE;
+    const h = dimensions.height ? Math.ceil(dimensions.height / 100) * 100 : DEFAULT_SIZE;
+    if (w > DEFAULT_SIZE || h > DEFAULT_SIZE) {
+      if (dimensions.width >= dimensions.height) {
+        url.searchParams.set("width", String(w));
+      } else {
+        url.searchParams.set("height", String(h));
+      }
+      url.searchParams.set("fit", "crop,smart");
+    }
+    if (options?.format) {
+      url.searchParams.set("format", options.format);
+    }
+    if (options?.quality) {
+      url.searchParams.set("quality", String(options.quality));
+    }
+    return url.toString();
+  } catch {
+    return src;
+  }
+}
 function getSrcSetForMedia(media) {
   if (!media?.thumbnails?.length) {
     return;
   }
   return media.thumbnails.map((thumbnail) => {
-    return thumbnail.url ? `${thumbnail.url} ${thumbnail.width}w` : void 0;
+    return thumbnail.url ? `${encodeUrlPath(thumbnail.url)} ${thumbnail.width}w` : void 0;
   }).filter((value) => !!value).join(", ");
 }
 
@@ -455,4 +536,4 @@ function canUseQuoteActions(quote) {
   return ["replied"].includes(quote.stateMachineState?.technicalName ?? "");
 }
 
-export { buildUrlPrefix, canUseQuoteActions, downloadFile, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, relativeUrlSlash, urlIsAbsolute };
+export { buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getPaymentMethodIcon, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductListingFromCmsPage, getProductManufacturerName, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, relativeUrlSlash, urlIsAbsolute };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopware/helpers",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Shopware helpers for accessing API data",
   "author": "Shopware",
   "type": "module",
@@ -33,19 +33,20 @@
   },
   "devDependencies": {
     "@biomejs/biome": "1.8.3",
-    "@vitest/coverage-v8": "3.2.3",
-    "happy-dom": "18.0.1",
+    "@typescript/native-preview": "7.0.0-dev.20260111.1",
+    "@vitest/coverage-v8": "4.0.18",
+    "happy-dom": "20.8.9",
     "unbuild": "2.0.0",
-    "vitest": "3.2.3",
+    "vitest": "4.0.18",
     "tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "unbuild && pnpm build:types",
-    "build:types": "tsc ./src/*.ts --declaration --allowJs --emitDeclarationOnly --outDir ./temp --skipLibCheck",
+    "build:types": "tsgo ./src/*.ts --ignoreConfig --declaration --allowJs --emitDeclarationOnly --outDir ./temp --skipLibCheck",
     "dev": "unbuild --stub",
     "lint": "biome check .",
     "lint:fix": "biome check . --write && pnpm run typecheck",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"
   }