musora-content-services 1.4.2 → 1.4.3

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.4.3](https://github.com/railroadmedia/musora-content-services/compare/v1.4.2...v1.4.3) (2025-03-31)
+
 ### [1.4.2](https://github.com/railroadmedia/musora-content-services/compare/v1.4.1...v1.4.2) (2025-03-28)
 
 ### [1.4.1](https://github.com/railroadmedia/musora-content-services/compare/v1.4.0...v1.4.1) (2025-03-25)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musora-content-services",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "A package for Musoras content services ",
   "main": "src/index.js",
   "type": "module",

package/src/services/imageSRCBuilder.js

@@ -0,0 +1,139 @@
+/**
+ * Builds an optimized image URL using both Sanity and Cloudflare Image Resizing services
+ *
+ * This function takes a Sanity CDN URL and image transformation parameters, then:
+ * 1. Adds appropriate transformation parameters to the Sanity URL
+ * 2. Wraps the resulting URL with Cloudflare's Image Resizing service
+ * 3. Maps compatible parameters between the two services for optimal results
+ *
+ * @param {string} url - The original image URL, typically from Sanity CDN
+ * @param {Object} options - Image transformation options
+ * @param {number} [options.width] - Desired image width in pixels
+ * @param {number} [options.height] - Desired image height in pixels
+ * @param {number} [options.quality] - Image quality (1-100)
+ * @param {string} [options.fit] - Resize strategy: 'cover', 'contain', 'scale-down', 'none'
+ * @param {string} [options.gravity] - Content positioning: 'auto', 'top', 'bottom', 'left', 'right', etc.
+ * @param {string} [options.crop] - Sanity-specific crop mode
+ * @param {string} [options.format] - Image format: 'auto', 'webp', 'jpeg', 'png', etc.
+ * @param {number} [options.blur] - Blur amount
+ * @param {number} [options.sharpen] - Sharpen amount
+ * @param {number} [options.saturation] - Saturation adjustment
+ * @param {number} [options.brightness] - Brightness adjustment
+ * @param {number} [options.contrast] - Contrast adjustment
+ * @param {number} [options.gamma] - Gamma adjustment
+ * @param {number} [options.rotate] - Rotation angle in degrees
+ * @param {number} [options.dpr] - Device pixel ratio for responsive images
+ * @param {string} [options.background] - Background color (e.g., '#FFFFFF')
+ * @param {number} [options.padding] - Padding to add around the image
+ * @param {boolean} [options.anim] - Whether to preserve animation in GIFs
+ * @param {string} [options.onerror] - Error handling strategy
+ * @param {string} [options.compression] - Compression strategy
+ * @param {string} [options.fetchFormat] - Format to request from origin
+ * @param {string} [options.sampling] - Chroma subsampling strategy
+ * @param {string} [options.metadata] - Metadata to preserve
+ *
+ * @returns {string} The fully constructed image URL with transformations
+ */
+export function buildImageSRC(url, options = {}) {
+  // Process Sanity URL first if applicable
+  if (url.includes('cdn.sanity.io')) {
+    url = applySanityTransformations(url, options)
+  }
+
+  // Then apply Cloudflare transformations
+  return applyCloudflareWrapper(url, options)
+}
+
+/**
+ * Applies Sanity-specific image transformations to a Sanity CDN URL
+ *
+ * @param {string} url - The Sanity CDN URL
+ * @param {Object} options - Image transformation options
+ * @returns {string} URL with Sanity transformations applied
+ * @private
+ */
+export function applySanityTransformations(url, options) {
+  const { width, height, quality } = options
+
+  const sanityOptions = []
+
+  // Dimensions
+  if (width) sanityOptions.push(`w=${width}`)
+  if (height) sanityOptions.push(`h=${height}`)
+  if (quality) sanityOptions.push(`q=${quality}`)
+
+  // Add parameters to Sanity URL
+  const sanityQuery = sanityOptions.length > 0 ? `?${sanityOptions.join('&')}` : ''
+  return `${url}${sanityQuery}`
+}
+
+/**
+ * Wraps a URL with Cloudflare's Image Resizing service and applies transformations
+ *
+ * @param {string} url - The source URL (can be any image URL)
+ * @param {Object} options - Image transformation options
+ * @returns {string} URL with Cloudflare transformations applied
+ * @private
+ */
+export function applyCloudflareWrapper(url, options) {
+  const {
+    width,
+    height,
+    quality,
+    fit,
+    gravity,
+    format,
+    blur,
+    sharpen,
+    brightness,
+    contrast,
+    gamma,
+    rotate,
+    dpr,
+    background,
+    padding,
+    anim,
+    onerror,
+    compression,
+    fetchFormat,
+    sampling,
+    metadata,
+  } = options
+
+  const cloudflareOptions = []
+
+  // Build Cloudflare options - required parameters
+  if (width) cloudflareOptions.push(`width=${width}`)
+  if (height) cloudflareOptions.push(`height=${height}`)
+  if (quality) cloudflareOptions.push(`quality=${quality}`)
+
+  // Add optional Cloudflare parameters
+  if (format) cloudflareOptions.push(`format=${format}`)
+  if (fit) cloudflareOptions.push(`fit=${fit}`)
+  if (gravity) cloudflareOptions.push(`gravity=${gravity}`)
+
+  if (sharpen !== null && sharpen !== undefined) cloudflareOptions.push(`sharpen=${sharpen}`)
+  if (blur !== null && blur !== undefined) cloudflareOptions.push(`blur=${blur}`)
+  if (brightness !== null && brightness !== undefined)
+    cloudflareOptions.push(`brightness=${brightness}`)
+  if (contrast !== null && contrast !== undefined) cloudflareOptions.push(`contrast=${contrast}`)
+  if (gamma !== null && gamma !== undefined) cloudflareOptions.push(`gamma=${gamma}`)
+  if (rotate !== null && rotate !== undefined) cloudflareOptions.push(`rotate=${rotate}`)
+  if (dpr !== null && dpr !== undefined) cloudflareOptions.push(`dpr=${dpr}`)
+
+  if (metadata !== null && metadata !== undefined) cloudflareOptions.push(`metadata=${metadata}`)
+  if (onerror !== null && onerror !== undefined) cloudflareOptions.push(`onerror=${onerror}`)
+  if (anim === false) cloudflareOptions.push('anim=false')
+  if (background !== null && background !== undefined)
+    cloudflareOptions.push(`background=${background}`)
+  if (fetchFormat !== null && fetchFormat !== undefined)
+    cloudflareOptions.push(`fetchFormat=${fetchFormat}`)
+  if (compression !== null && compression !== undefined)
+    cloudflareOptions.push(`compression=${compression}`)
+  if (sampling !== null && sampling !== undefined) cloudflareOptions.push(`sampling=${sampling}`)
+  if (padding !== null && padding !== undefined) cloudflareOptions.push(`padding=${padding}`)
+
+  const optionsString = cloudflareOptions.length > 0 ? cloudflareOptions.join(',') : ''
+
+  return `https://www.musora.com/cdn-cgi/image/${optionsString}/${url}`
+}

package/src/services/imageSRCVerify.js

@@ -0,0 +1,114 @@
+/**
+ * Verifies if an image URL follows best practices for optimization
+ *
+ * This function checks whether:
+ * 1. Sanity CDN images include query parameters for optimization
+ * 2. Direct S3 images are avoided (should use CDN instead)
+ *
+ * @param {string} src - The image source URL to verify
+ * @returns {void}
+ *
+ * @example
+ * // Check a direct Sanity URL
+ * verifyImageSRC('https://cdn.sanity.io/images/4032r8py/staging/504c4e3393170f937a579de6f3c75c457b0c9e65-640x360.jpg');
+ *
+ * @example
+ * // Check a Sanity URL inside a Cloudflare URL
+ * verifyImageSRC('https://www.musora.com/cdn-cgi/image/width=500,quality=95/https://cdn.sanity.io/images/4032r8py/staging/504c4e3393170f937a579de6f3c75c457b0c9e65-640x360.jpg');
+ */
+export function verifyImageSRC(src) {
+  // Exit early if the URL is empty
+  if (!src) return
+
+  // Check for S3 direct URLs
+  if (isBucketUrl(src)) {
+    warnAboutDirectS3Url(src)
+    return
+  }
+
+  // Check for Sanity URLs
+  if (src.includes('cdn.sanity.io')) {
+    verifySanityUrl(src)
+  }
+}
+
+/**
+ * Checks if a URL is a direct link to an S3 bucket
+ *
+ * @param {string} url - The URL to check
+ * @returns {boolean} True if the URL is a direct S3 bucket URL
+ * @private
+ */
+export function isBucketUrl(url) {
+  // Check for common S3 patterns
+  return (
+    url.includes('.s3.amazonaws.com') ||
+    url.includes('s3.us-') ||
+    url.includes('amazonaws.com/') ||
+    (url.includes('musora-') && url.includes('.s3.'))
+  )
+}
+
+/**
+ * Issues a warning about using direct S3 URLs instead of a CDN
+ *
+ * @param {string} url - The S3 URL that triggered the warning
+ * @private
+ */
+function warnAboutDirectS3Url(url) {
+  // Only warn in development mode
+  if (process.env.NODE_ENV !== 'production') {
+    console.warn(`WARNING: Direct S3 bucket URL detected: ${url}
+    This is not recommended. Use Cloudfront or another CDN for better performance.`)
+  }
+}
+
+/**
+ * Extracts a Sanity URL from a potentially Cloudflare-wrapped URL
+ *
+ * @param {string} url - The URL to process
+ * @returns {string} The extracted Sanity URL
+ * @private
+ */
+export function extractSanityUrl(url) {
+  // If this is a Cloudflare URL, extract the Sanity portion
+  if (url.includes('/cdn-cgi/image/')) {
+    // Split the URL to get the portion after /cdn-cgi/image/[parameters]/
+    const parts = url.split('/cdn-cgi/image/')
+    if (parts.length > 1) {
+      // Get everything after the first / that follows the Cloudflare parameters
+      const cfParamsAndSanityUrl = parts[1]
+      const slashIndex = cfParamsAndSanityUrl.indexOf('/', 0)
+      if (slashIndex !== -1) {
+        let sanityUrl = cfParamsAndSanityUrl.substring(slashIndex + 1)
+        return sanityUrl
+      }
+    }
+  }
+
+  // If not a Cloudflare URL or extraction failed, return the original URL
+  return url
+}
+
+/**
+ * Verifies if a Sanity CDN image URL includes optimization parameters
+ *
+ * @param {string} src - The Sanity image URL to verify
+ * @private
+ */
+function verifySanityUrl(src) {
+  // Extract the Sanity URL if it's wrapped in a Cloudflare URL
+  const sanityUrl = extractSanityUrl(src)
+
+  // Check if the Sanity URL has parameters (any query string)
+  const hasParameters = sanityUrl.includes('?')
+
+  // Warn if no parameters are found
+  if (!hasParameters) {
+    // Only warn in development mode
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn(`WARNING: Sanity CDN URL without parameters detected: ${src}
+    This may cause performance issues. Consider adding image transformations using the buildImageSRC MCS service.`)
+    }
+  }
+}

package/test/imageSRCBuilder.test.js

@@ -0,0 +1,37 @@
+const { buildImageSRC, applySanityTransformations } = require('../src/services/imageSRCBuilder.js')
+
+describe('imageSRCBuilder', function () {
+  beforeEach(() => {})
+
+  test('applySanityTransformations', async () => {
+    const url =
+      'https://cdn.sanity.io/images/4032r8py/production/83c3b6e7354a46c605804c093f707daa4e3f8f25-8000x4500.png'
+    const width = 500
+    const height = 100
+    const quality = 95
+    const resultingURL = applySanityTransformations(url, {
+      width: width,
+      quality: quality,
+      height: height,
+    })
+    const expected = `${url}?w=${width}&h=${height}&q=${quality}`
+
+    expect(resultingURL).toStrictEqual(expected)
+  })
+
+  test('buildImageSRC', async () => {
+    const url = 'https://d2vyvo0tyx8ig5.cloudfront.net/books/foundations/level-2.jpg'
+    const width = 500
+    const height = 100
+    const quality = 95
+    const resultingURL = buildImageSRC(url, {
+      width: width,
+      quality: quality,
+      height: height,
+    })
+
+    const expected = `https://www.musora.com/cdn-cgi/image/width=${width},height=${height},quality=${quality}/${url}`
+
+    expect(resultingURL).toStrictEqual(expected)
+  })
+})

package/test/imageSRCVerify.test.js

@@ -0,0 +1,160 @@
+// Mock console.warn to avoid cluttering test output and to verify warnings
+import { extractSanityUrl, isBucketUrl, verifyImageSRC } from '../src/services/imageSRCVerify.js'
+
+const originalConsoleWarn = console.warn
+const originalConsoleError = console.error
+const originalNodeEnv = process.env.NODE_ENV
+
+describe('Image URL Verification', () => {
+  let consoleWarnMock
+
+  beforeEach(() => {
+    // Mock console.warn and console.error
+    consoleWarnMock = jest.fn()
+    console.warn = consoleWarnMock
+    console.error = jest.fn()
+
+    // Set NODE_ENV to development for all tests
+    process.env.NODE_ENV = 'development'
+  })
+
+  afterEach(() => {
+    // Restore the original console methods and NODE_ENV
+    console.warn = originalConsoleWarn
+    console.error = originalConsoleError
+    process.env.NODE_ENV = originalNodeEnv
+  })
+
+  describe('verifyImageSRC', () => {
+    test('should not warn for Sanity URL with parameters', () => {
+      // Arrange
+      const url =
+        'https://cdn.sanity.io/images/4032r8py/staging/504c4e3393170f937a579de6f3c75c457b0c9e65-640x360.jpg?w=500&q=95'
+
+      // Act
+      verifyImageSRC(url)
+
+      // Assert
+      expect(consoleWarnMock).not.toHaveBeenCalled()
+    })
+
+    test('should warn for Sanity URL without parameters', () => {
+      // Arrange
+      const url =
+        'https://cdn.sanity.io/images/4032r8py/staging/504c4e3393170f937a579de6f3c75c457b0c9e65-640x360.jpg'
+
+      // Act
+      verifyImageSRC(url)
+
+      // Assert
+      expect(consoleWarnMock).toHaveBeenCalled()
+      expect(consoleWarnMock.mock.calls[0][0]).toContain(
+        'WARNING: Sanity CDN URL without parameters detected'
+      )
+    })
+
+    test('should warn for direct S3 bucket URL', () => {
+      // Arrange
+      const url = 'https://musora-images.s3.amazonaws.com/drumeo/images/some-image.jpg'
+
+      // Act
+      verifyImageSRC(url)
+
+      // Assert
+      expect(consoleWarnMock).toHaveBeenCalled()
+      expect(consoleWarnMock.mock.calls[0][0]).toContain('Direct S3 bucket URL detected')
+    })
+
+    test('should not warn when URL is empty', () => {
+      // Arrange
+      const url = ''
+
+      // Act
+      verifyImageSRC(url)
+
+      // Assert
+      expect(consoleWarnMock).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('Cloudflare wrapped Sanity URLs', () => {
+    test('should extract and validate Sanity URL from Cloudflare wrapper', () => {
+      // Arrange
+      const url =
+        'https://www.musora.com/cdn-cgi/image/width=500,quality=95/https://cdn.sanity.io/images/4032r8py/staging/504c4e3393170f937a579de6f3c75c457b0c9e65-640x360.jpg'
+
+      // Act
+      verifyImageSRC(url)
+
+      // Assert
+      expect(consoleWarnMock).toHaveBeenCalled()
+      expect(consoleWarnMock.mock.calls[0][0]).toContain(
+        'WARNING: Sanity CDN URL without parameters detected'
+      )
+    })
+
+    test('should not warn for Cloudflare wrapped Sanity URL with parameters', () => {
+      // Arrange
+      const url =
+        'https://www.musora.com/cdn-cgi/image/width=500,quality=95/https://cdn.sanity.io/images/4032r8py/staging/504c4e3393170f937a579de6f3c75c457b0c9e65-640x360.jpg?w=500&q=95'
+
+      // Act
+      verifyImageSRC(url)
+
+      // Assert
+      expect(consoleWarnMock).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('isBucketUrl', () => {
+    test('should detect standard S3 URLs', () => {
+      // Arrange & Act & Assert
+      expect(isBucketUrl('https://my-bucket.s3.amazonaws.com/image.jpg')).toBe(true)
+      expect(isBucketUrl('https://s3.us-east-1.amazonaws.com/my-bucket/image.jpg')).toBe(true)
+      expect(isBucketUrl('https://musora-images.s3.amazonaws.com/path/to/image.jpg')).toBe(true)
+    })
+
+    test('should not flag non-S3 URLs', () => {
+      // Arrange & Act & Assert
+      expect(isBucketUrl('https://cdn.sanity.io/images/123/production/image.jpg')).toBe(false)
+      expect(isBucketUrl('https://www.musora.com/image.jpg')).toBe(false)
+    })
+  })
+
+  describe('extractSanityUrl', () => {
+    test('should extract Sanity URL from Cloudflare wrapper', () => {
+      // Arrange
+      const wrappedUrl =
+        'https://www.musora.com/cdn-cgi/image/width=500,quality=95/https://cdn.sanity.io/images/123/production/image.jpg'
+      const expectedExtracted = 'https://cdn.sanity.io/images/123/production/image.jpg'
+
+      // Act
+      const result = extractSanityUrl(wrappedUrl)
+
+      // Assert
+      expect(result).toBe(expectedExtracted)
+    })
+
+    test('should return original URL if not Cloudflare wrapped', () => {
+      // Arrange
+      const url = 'https://cdn.sanity.io/images/123/production/image.jpg'
+
+      // Act
+      const result = extractSanityUrl(url)
+
+      // Assert
+      expect(result).toBe(url)
+    })
+
+    test('should handle malformed Cloudflare URLs gracefully', () => {
+      // Arrange
+      const malformedUrl = 'https://www.musora.com/cdn-cgi/image/width=500'
+
+      // Act
+      const result = extractSanityUrl(malformedUrl)
+
+      // Assert
+      expect(result).toBe(malformedUrl)
+    })
+  })
+})