@shopware/helpers 1.7.0 → 1.7.2

package/README.md

@@ -2,9 +2,9 @@
 
 Welcome to `@shopware/helpers` package.
 
-For getting started documentation visit [https://frontends.shopware.com/](https://frontends.shopware.com/)
+For getting started documentation visit [https://developer.shopware.com/frontends/](https://developer.shopware.com/frontends/)
 
-Documentation specific for this package: [helpers](https://frontends.shopware.com/packages/helpers.html)
+Documentation specific for this package: [helpers](https://developer.shopware.com/frontends/packages/helpers.html)
 
 ## Reusable classes
 
@@ -49,11 +49,11 @@ const optimizedUrl = getBackgroundImageUrl(
 
 ### 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 |
+| 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`
 
@@ -85,11 +85,11 @@ const srcset = generateCdnSrcSet(
 
 ### 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 |
+| 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.
 
@@ -102,20 +102,20 @@ Builds an optimized CDN image URL with size parameters based on rendered element
 ```ts
 import { buildCdnImageUrl } from "@shopware/helpers";
 
-const url = buildCdnImageUrl(
-  "https://cdn.shopware.store/.../image.jpg",
-  { width: 724, height: 760 },
-);
+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 |
+| 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.
 
@@ -125,12 +125,8 @@ Returns an empty string if `src` is falsy. Returns the original `src` if URL par
 
 Full changelog for stable version is available [here](https://github.com/shopware/frontends/blob/main/packages/helpers/CHANGELOG.md)
 
-### Latest changes: 1.7.0
-
-### Minor Changes
-
-- [#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
+### Latest changes: 1.7.2
 
 ### 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
+- [#2594](https://github.com/shopware/frontends/pull/2594) [`f16c5a0`](https://github.com/shopware/frontends/commit/f16c5a0785d6187b73c3edcf37feab7c90bd7988) Thanks [@patzick](https://github.com/patzick)! - Add helpers for resolving canonical SEO paths and detecting technical Shopware URLs.

package/dist/index.d.mts

@@ -526,6 +526,32 @@ declare function isLandingPage<T extends {
     apiAlias: string;
 }>(entity: T | LandingPage): entity is LandingPage;
 
+declare const TECHNICAL_ROUTE_MAP: {
+    readonly "/navigation/": "frontend.navigation.page";
+    readonly "/detail/": "frontend.detail.page";
+    readonly "/landingPage/": "frontend.landing.page";
+};
+type RouteNameFromPathInfo = (typeof TECHNICAL_ROUTE_MAP)[keyof typeof TECHNICAL_ROUTE_MAP];
+type RouteInfoFromPathInfo = {
+    routeName: RouteNameFromPathInfo;
+    foreignKey: string;
+};
+declare function normalizePath(path: string): string;
+declare function isTechnicalPath(path: string): boolean;
+/**
+ * Check whether an absolute or relative URL points to a technical Shopware
+ * route. Query parameters and fragments are ignored.
+ */
+declare function isTechnicalUrl(url: string, baseUrl?: string): boolean;
+declare function getRouteFromPathInfo(path: string): RouteInfoFromPathInfo | null;
+/**
+ * Get the canonical path for a mapped technical Shopware URL.
+ *
+ * Returns `null` for SEO URLs, synthetic technical fallbacks without an SEO
+ * mapping, and invalid mappings that would redirect to another technical URL.
+ */
+declare function getCanonicalPathForTechnicalPath(path: string, seoUrl?: object | null): string | null;
+
 /**
  * Get translated property from the given object.
  *
@@ -755,4 +781,5 @@ declare function canUseQuoteActions<T extends {
     };
 }>(quote: T): boolean;
 
-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 };
+export { buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCanonicalPathForTechnicalPath, 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, getRouteFromPathInfo, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, isTechnicalPath, isTechnicalUrl, normalizePath, relativeUrlSlash, urlIsAbsolute };
+export type { BackgroundImageOptions, HelpersCssClasses, LayoutConfiguration, RouteInfoFromPathInfo, RouteNameFromPathInfo, TierPrice, UiMediaGalleryItem, UiMediaGalleryItemUrl, UiProductOption, UiProductProperty, UiProductReview, UrlRouteOutput };

package/dist/index.d.ts

@@ -526,6 +526,32 @@ declare function isLandingPage<T extends {
     apiAlias: string;
 }>(entity: T | LandingPage): entity is LandingPage;
 
+declare const TECHNICAL_ROUTE_MAP: {
+    readonly "/navigation/": "frontend.navigation.page";
+    readonly "/detail/": "frontend.detail.page";
+    readonly "/landingPage/": "frontend.landing.page";
+};
+type RouteNameFromPathInfo = (typeof TECHNICAL_ROUTE_MAP)[keyof typeof TECHNICAL_ROUTE_MAP];
+type RouteInfoFromPathInfo = {
+    routeName: RouteNameFromPathInfo;
+    foreignKey: string;
+};
+declare function normalizePath(path: string): string;
+declare function isTechnicalPath(path: string): boolean;
+/**
+ * Check whether an absolute or relative URL points to a technical Shopware
+ * route. Query parameters and fragments are ignored.
+ */
+declare function isTechnicalUrl(url: string, baseUrl?: string): boolean;
+declare function getRouteFromPathInfo(path: string): RouteInfoFromPathInfo | null;
+/**
+ * Get the canonical path for a mapped technical Shopware URL.
+ *
+ * Returns `null` for SEO URLs, synthetic technical fallbacks without an SEO
+ * mapping, and invalid mappings that would redirect to another technical URL.
+ */
+declare function getCanonicalPathForTechnicalPath(path: string, seoUrl?: object | null): string | null;
+
 /**
  * Get translated property from the given object.
  *
@@ -755,4 +781,5 @@ declare function canUseQuoteActions<T extends {
     };
 }>(quote: T): boolean;
 
-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 };
+export { buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCanonicalPathForTechnicalPath, 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, getRouteFromPathInfo, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, isTechnicalPath, isTechnicalUrl, normalizePath, relativeUrlSlash, urlIsAbsolute };
+export type { BackgroundImageOptions, HelpersCssClasses, LayoutConfiguration, RouteInfoFromPathInfo, RouteNameFromPathInfo, TierPrice, UiMediaGalleryItem, UiMediaGalleryItemUrl, UiProductOption, UiProductProperty, UiProductReview, UrlRouteOutput };

package/dist/index.mjs

@@ -352,6 +352,50 @@ function isLandingPage(entity) {
   return entity.apiAlias === "landing_page";
 }
 
+const TECHNICAL_ROUTE_MAP = {
+  "/navigation/": "frontend.navigation.page",
+  "/detail/": "frontend.detail.page",
+  "/landingPage/": "frontend.landing.page"
+};
+function normalizePath(path) {
+  return path.endsWith("/") && path !== "/" ? path.slice(0, -1) : path;
+}
+function isTechnicalPath(path) {
+  const normalizedPath = normalizePath(path);
+  return Object.keys(TECHNICAL_ROUTE_MAP).some(
+    (prefix) => normalizedPath.startsWith(prefix)
+  );
+}
+function isTechnicalUrl(url, baseUrl = "http://localhost") {
+  try {
+    return isTechnicalPath(new URL(url, baseUrl).pathname);
+  } catch {
+    return false;
+  }
+}
+function getRouteFromPathInfo(path) {
+  const normalizedPath = normalizePath(path);
+  for (const [prefix, routeName] of Object.entries(TECHNICAL_ROUTE_MAP)) {
+    if (!normalizedPath.startsWith(prefix)) continue;
+    const foreignKey = normalizedPath.slice(prefix.length);
+    if (!foreignKey || foreignKey.includes("/")) return null;
+    return {
+      routeName,
+      foreignKey
+    };
+  }
+  return null;
+}
+function getCanonicalPathForTechnicalPath(path, seoUrl) {
+  if (!isTechnicalPath(path) || !seoUrl || !("seoPathInfo" in seoUrl) || typeof seoUrl.seoPathInfo !== "string") {
+    return null;
+  }
+  const seoPathInfo = seoUrl.seoPathInfo.replace(/^\/+/, "");
+  const canonicalPath = seoPathInfo ? normalizePath(`/${seoPathInfo}`) : "/";
+  if (isTechnicalPath(canonicalPath)) return null;
+  return canonicalPath;
+}
+
 const getFilter = (code, aggregation) => {
   return {
     label: getTranslatedProperty(aggregation, "name") || code,
@@ -536,4 +580,4 @@ function canUseQuoteActions(quote) {
   return ["replied"].includes(quote.stateMachineState?.technicalName ?? "");
 }
 
-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 };
+export { buildCdnImageUrl, buildUrlPrefix, canUseQuoteActions, downloadFile, encodeUrlPath, generateCdnSrcSet, getBackgroundImageUrl, getBiggestThumbnailUrl, getCanonicalPathForTechnicalPath, 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, getRouteFromPathInfo, getShippingMethodDeliveryTime, getShippingMethodIcon, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, isProductOnSale, isProductTopSeller, isTechnicalPath, isTechnicalUrl, normalizePath, relativeUrlSlash, urlIsAbsolute };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopware/helpers",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "Shopware helpers for accessing API data",
   "author": "Shopware",
   "type": "module",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/shopware/frontends.git"
   },
-  "homepage": "https://frontends.shopware.com/packages/helpers.html",
+  "homepage": "https://developer.shopware.com/frontends/packages/helpers.html",
   "keywords": [
     "shopware",
     "api",
@@ -32,20 +32,19 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "1.8.3",
-    "@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": "4.0.18",
+    "@typescript/native-preview": "7.0.0-dev.20260205.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "happy-dom": "20.10.6",
+    "unbuild": "3.6.1",
+    "vitest": "4.1.10",
     "tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "unbuild && pnpm build:types",
     "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",
+    "lint": "oxlint . && oxfmt --check .",
+    "lint:fix": "oxlint --fix . && oxfmt --write . && pnpm run typecheck",
     "typecheck": "tsgo --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"