feat: append optional image filenames in HTML and JSON pipeline output (#72)

- Add transformImages step to productHTMLPipe and productJSONPipe that
  appends filename to media URLs when present on image objects
- Update isMediaBusFile check in create-pictures to handle URLs with
  filename path segment

Author: sagarsane

package-lock.json

@@ -47,7 +47,7 @@
   "dependencies": {
     "@adobe/helix-html-pipeline": "6.27.9",
     "@adobe/helix-shared-utils": "3.0.2",
-    "@dylandepass/helix-product-shared": "1.5.2",
+    "@dylandepass/helix-product-shared": "1.6.0",
     "dayjs": "1.11.19",
     "github-slugger": "2.0.0",
     "hast-util-from-html": "^2.0.3",

package.json

@@ -16,6 +16,7 @@ import addHeadingIds from './steps/add-heading-ids.js';
 import { getPathInfo, validatePathInfo } from './utils/path.js';
 import initConfig from './steps/init-config.js';
 import fetchProductBusContent from './steps/fetch-productbus.js';
+import transformImages from './steps/transform-images.js';
 import fetchEdgeContent from './steps/fetch-edge-product.js';
 import { setLastModified } from './utils/last-modified.js';
 import html from './steps/make-html.js';
@@ -71,6 +72,7 @@ export async function productHTMLPipe(state, req) {
       return res;
     }
 
+    transformImages(state);
     state.timer?.update('render');
     await html(state);
 

src/product-html-pipe.js

@@ -15,6 +15,7 @@ import { cleanupHeaderValue } from '@adobe/helix-shared-utils';
 import { validatePathInfo } from './utils/path.js';
 import initConfig from './steps/init-config.js';
 import fetchProductBusContent from './steps/fetch-productbus.js';
+import transformImages from './steps/transform-images.js';
 import { setLastModified } from './utils/last-modified.js';
 import { set404CacheHeaders, setProductCacheHeaders } from './steps/set-cache-headers.js';
 
@@ -60,6 +61,8 @@ export async function productJSONPipe(state, req) {
       throw new PipelineStatusError(res.status, res.error);
     }
 
+    transformImages(state);
+
     // set surrogate keys
     await setProductCacheHeaders(state, req, res);
 

src/product-json-pipe.js

@@ -55,9 +55,8 @@ export function createOptimizedPicture(src, alt = '', title = undefined) {
     height = props.get('height');
   }
 
-  // Extract filename and check if it starts with 'media_'
-  const filename = pathname.substring(pathname.lastIndexOf('/') + 1);
-  const isMediaBusFile = filename.startsWith('media_');
+  // Matches media bus URLs: /media_{sha1hash}.ext or /media_{sha1hash}/filename.ext
+  const isMediaBusFile = /^\/media_[a-f0-9]+(?:\/[^/]+)?\.[a-z0-9]+$/i.test(pathname);
 
   // If not a media file, return a simple picture with just an img tag (no optimization)
   if (!isMediaBusFile) {

src/steps/create-pictures.js

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { appendFilenameToMediaUrl } from '@dylandepass/helix-product-shared';
+
+function transformImage(image) {
+  if (!image || typeof image !== 'object') {
+    return;
+  }
+  image.url = appendFilenameToMediaUrl(image.url, image.filename);
+}
+
+export default function transformImages(state) {
+  const data = state?.content?.data;
+  if (!data || typeof data !== 'object') {
+    return;
+  }
+
+  if (Array.isArray(data.images)) {
+    data.images.forEach(transformImage);
+  }
+  if (Array.isArray(data.variants)) {
+    data.variants.forEach((variant) => (variant?.images || []).forEach(transformImage));
+  }
+}

src/steps/transform-images.js

@@ -0,0 +1,16 @@
+{
+  "sku": "product-with-image-filename",
+  "name": "Test Product",
+  "type": "simple",
+  "images": [
+    {
+      "url": "./media_a1b2c3d4e5f6789012345678901234567890abcd.png",
+      "filename": "test-product-image"
+    }
+  ],
+  "price": {
+    "currency": "USD",
+    "regular": "99.99",
+    "final": "99.99"
+  }
+}

test/fixtures/product/product-with-image-filename.json

@@ -92,6 +92,34 @@ describe('Product HTML Pipe Test', () => {
     fetchMock.unmockGlobal();
   });
 
+  it('transforms image URLs with filename in rendered HTML', async () => {
+    const fetchMockGlobal = fetchMock.mockGlobal();
+    fetchMockGlobal.get('https://main--site--org.aem.live/products/product-with-image-filename', { status: 404 });
+
+    const s3Loader = new FileS3Loader();
+    const state = DEFAULT_STATE(DEFAULT_CONFIG, {
+      log: console,
+      s3Loader,
+      ref: 'main',
+      path: '/products/product-with-image-filename',
+      partition: 'live',
+      timer: { update: () => {} },
+    });
+    state.info = getPathInfo('/products/product-with-image-filename');
+
+    const resp = await productHTMLPipe(
+      state,
+      new PipelineRequest(new URL('https://acme.com/products/product-with-image-filename')),
+    );
+
+    assert.strictEqual(resp.status, 200);
+    assert.ok(
+      resp.body.includes('./media_a1b2c3d4e5f6789012345678901234567890abcd/test-product-image.png'),
+      'Rendered HTML should contain the filename-appended image URL',
+    );
+    fetchMock.unmockGlobal();
+  });
+
   it('renders a configurable product html from repoless site', async () => {
     const fetchMockGlobal = fetchMock.mockGlobal();
     // Mock edge content fetch to return 404 (no authored content)

test/product-html-pipe.test.js

@@ -232,6 +232,32 @@ describe('Product JSON Pipe Test', () => {
     assert.strictEqual(resp.status, 200);
   });
 
+  it('transforms image URLs with filename in JSON output', async () => {
+    const s3Loader = new FileS3Loader();
+
+    const state = DEFAULT_STATE({
+      log: console,
+      s3Loader,
+      ref: 'main',
+      path: '/products/product-with-image-filename.json',
+      partition: 'live',
+      timer: { update: () => {} },
+    });
+    state.info = getPathInfo('/products/product-with-image-filename.json');
+
+    const resp = await productJSONPipe(
+      state,
+      new PipelineRequest(new URL('https://acme.com/products/product-with-image-filename.json')),
+    );
+
+    assert.strictEqual(resp.status, 200);
+    const body = JSON.parse(resp.body);
+    assert.strictEqual(
+      body.images[0].url,
+      './media_a1b2c3d4e5f6789012345678901234567890abcd/test-product-image.png',
+    );
+  });
+
   it('handles state with timer but no update method correctly', async () => {
     const s3Loader = new FileS3Loader();
     s3Loader.statusCodeOverrides = {

test/product-json-pipe.test.js

@@ -12,7 +12,7 @@
 
 /* eslint-env mocha */
 import assert from 'assert';
-import { constructImageUrl } from '../../src/steps/create-pictures.js';
+import { constructImageUrl, createOptimizedPicture } from '../../src/steps/create-pictures.js';
 
 describe('constructImageUrl', () => {
   const baseState = {
@@ -109,3 +109,18 @@ describe('constructImageUrl', () => {
     assert.strictEqual(result, 'https://main--helix-pages--adobe.aem.network/images/products/featured/test.jpg');
   });
 });
+
+describe('createOptimizedPicture', () => {
+  it('creates optimized sources for media hash URL with filename segment', () => {
+    const picture = createOptimizedPicture(
+      './media_13f34abcff863c53e25028911749e9a9d1d6f1c4/blue-ceramic-mug.jpg',
+      'A blue mug',
+      'A blue mug',
+    );
+
+    assert.strictEqual(picture.tagName, 'picture');
+    assert.ok(Array.isArray(picture.children));
+    assert.ok(picture.children.length > 1, 'expected optimized source elements');
+    assert.strictEqual(picture.children[0].tagName, 'source');
+  });
+});