feat(mediaurls): option to add revision query param to media URLs in Release (#243)

---------

Co-authored-by: Lukas Schneider (Neo Reply) <131265055+neo-reply-lukas@users.noreply.github.com>
Co-authored-by: jodeleit-es <>

Author: jodeleit-es

src/modules/CaaSMapper.spec.ts

@@ -144,16 +144,32 @@ describe('CaaSMapper', () => {
   })
 
   describe('buildMediaUrl', () => {
-    it('should return the url as-is in release mode', () => {
+    it('should return the url as-is in release mode when includeRevisionInMediaUrls is false', () => {
       const api = createApi()
       api.contentMode = FSXAContentMode.RELEASE
+      api.includeRevisionInMediaUrls = false
       const mapper = new CaaSMapper(api, 'de', {}, createLogger())
       const url = 'https://e-spirit.local/some/resource'
       expect(mapper.buildMediaUrl(url)).toEqual(url)
+      expect(mapper.buildMediaUrl(url, 5593)).toEqual(url)
     })
-    it('should append the revision as a query param if given in preview mode', () => {
+    it('should append the revision as a query param if given when includeRevisionInMediaUrls is true', () => {
       const api = createApi()
-      api.contentMode = FSXAContentMode.PREVIEW
+      api.includeRevisionInMediaUrls = true
+      const mapper = new CaaSMapper(api, 'de', {}, createLogger())
+      const url = 'https://e-spirit.local/some/resource'
+      expect(mapper.buildMediaUrl(url)).toEqual(url)
+      expect(mapper.buildMediaUrl(url, 5593)).toEqual(`${url}?rev=5593`)
+      // check media string construction
+      expect(mapper.buildMediaUrl(`${url}?prev`, 5593)).toEqual(
+        `${url}?prev&rev=5593`
+      )
+    })
+
+    it('should append the revision as a query param if includeRevisionInMediaUrls is true and content mode is release', () => {
+      const api = createApi()
+      api.contentMode = FSXAContentMode.RELEASE
+      api.includeRevisionInMediaUrls = true
       const mapper = new CaaSMapper(api, 'de', {}, createLogger())
       const url = 'https://e-spirit.local/some/resource'
       expect(mapper.buildMediaUrl(url)).toEqual(url)

src/modules/CaaSMapper.ts

@@ -231,7 +231,7 @@ export class CaaSMapper {
   }
 
   buildMediaUrl(url: string, rev?: number) {
-    if (rev && this.api.contentMode === FSXAContentMode.PREVIEW) {
+    if (rev && this.api.includeRevisionInMediaUrls) {
       url += `${url.includes('?') ? '&' : '?'}rev=${rev}`
     }
     return url

src/modules/FSXARemoteApi.spec.ts

@@ -86,6 +86,22 @@ describe('FSXARemoteAPI', () => {
         new FSXARemoteApi(config)
       }).toThrow(FSXAApiErrors.UNKNOWN_CONTENT_MODE)
     })
+    it('should default includeRevisionInMediaUrls to true in preview mode', () => {
+      config.contentMode = 'preview'
+      remoteApi = new FSXARemoteApi(config)
+      expect(remoteApi.includeRevisionInMediaUrls).toBe(true)
+    })
+    it('should default includeRevisionInMediaUrls to false in release mode', () => {
+      config.contentMode = 'release'
+      remoteApi = new FSXARemoteApi(config)
+      expect(remoteApi.includeRevisionInMediaUrls).toBe(false)
+    })
+    it('should allow overriding includeRevisionInMediaUrls in release mode', () => {
+      config.contentMode = 'release'
+      config.includeRevisionInMediaUrls = true
+      remoteApi = new FSXARemoteApi(config)
+      expect(remoteApi.includeRevisionInMediaUrls).toBe(true)
+    })
   })
   describe('buildAuthorizationHeaders', () => {
     it('should return the correct authorization object', () => {

src/modules/FSXARemoteApi.ts

@@ -30,7 +30,7 @@ import {
   removeFromSeoRouteMap,
   removeFromStructure,
 } from '../utils'
-import { FSXAApiErrors, HttpStatus } from './../enums'
+import { FSXAApiErrors, FSXAContentMode, HttpStatus } from './../enums'
 import { LogLevel } from './Logger'
 import { denormalizeResolvedReferences } from './MappingUtils'
 import { ComparisonQueryOperatorEnum, QueryBuilder } from './QueryBuilder'
@@ -74,6 +74,7 @@ export class FSXARemoteApi implements FSXAApi {
   private _caasItemFilter?: CaasItemFilter
   private _logLevel: LogLevel
   private _enableEventStream: boolean = false
+  private _includeRevisionInMediaUrls: boolean = false
 
   /**
    * The constructor of this class initializes the configuration for the api.
@@ -90,6 +91,7 @@ export class FSXARemoteApi implements FSXAApi {
    * @param config.customMapper optional {@link CustomMapper CustomMapper}
    * @param config.filterOptions optional {@link RemoteApiFilterOptions RemoteApiFilterOptions} (EXPERIMENTAL)
    * @param config.logLevel the used {@link LogLevel LogLevel} for the API `(default LogLevel.ERROR)` - optional
+   * @param config.includeRevisionInMediaUrls whether to append `rev` query param to media URLs `(default: true in preview, false in release)`
    */
   constructor({
     apikey,
@@ -103,6 +105,7 @@ export class FSXARemoteApi implements FSXAApi {
     customMapper,
     filterOptions,
     logLevel = LogLevel.ERROR,
+    includeRevisionInMediaUrls = contentMode === FSXAContentMode.PREVIEW, // default to true in preview, false in release
   }: FSXARemoteApiConfig) {
     this.apikey = apikey
     this.caasURL = caasURL
@@ -118,6 +121,7 @@ export class FSXARemoteApi implements FSXAApi {
     this._queryBuilder = new QueryBuilder(this._logger)
     this._navigationItemFilter = filterOptions?.navigationItemFilter
     this._caasItemFilter = filterOptions?.caasItemFilter
+    this._includeRevisionInMediaUrls = includeRevisionInMediaUrls
 
     this._logger.debug('FSXARemoteApi created', {
       caasURL,
@@ -129,6 +133,7 @@ export class FSXARemoteApi implements FSXAApi {
       customMapper: this._customMapper,
       navigationItemFilter: this._navigationItemFilter,
       caasItemFilter: this._caasItemFilter,
+      includeRevisionInMediaUrls: this._includeRevisionInMediaUrls
     })
   }
 
@@ -635,7 +640,7 @@ export class FSXARemoteApi implements FSXAApi {
         mapperLocale,
         {
           customMapper: this._customMapper,
-          maxReferenceDepth: this._maxReferenceDepth,
+          maxReferenceDepth: this._maxReferenceDepth
         },
         new Logger(this._logLevel, 'CaaSMapper')
       )
@@ -1043,6 +1048,20 @@ export class FSXARemoteApi implements FSXAApi {
     this._contentMode = value
   }
 
+  /**
+   * @returns whether revision query parameter `rev` is appended to media URLs
+   */
+  public get includeRevisionInMediaUrls() {
+    return this._includeRevisionInMediaUrls
+  }
+
+  /**
+   * Sets whether revision query parameter `rev` is appended to media URLs
+   */
+  public set includeRevisionInMediaUrls(value: boolean) {
+    this._includeRevisionInMediaUrls = value
+  }
+
   /**
    * @returns the configured log level
    */

src/types.ts

@@ -1033,6 +1033,7 @@ export type FSXARemoteApiConfig = {
   customMapper?: CustomMapper
   filterOptions?: RemoteApiFilterOptions
   enableEventStream?: boolean
+  includeRevisionInMediaUrls?: boolean
 }
 
 export type FilterContextProvider = () => unknown | null