@adobe/spacecat-shared-utils 1.74.0 → 1.76.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-utils-v1.76.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.75.0...@adobe/spacecat-shared-utils-v1.76.0) (2025-11-20)
+
+
+### Features
+
+* **utils,http-utils:** trigger release for trace ID propagation ([#1154](https://github.com/adobe/spacecat-shared/issues/1154)) ([fb48149](https://github.com/adobe/spacecat-shared/commit/fb481497725e49dab18812b4ba1ba7186e35a8f9)), closes [#1152](https://github.com/adobe/spacecat-shared/issues/1152) [#1152](https://github.com/adobe/spacecat-shared/issues/1152) [#1097](https://github.com/adobe/spacecat-shared/issues/1097) [#1097](https://github.com/adobe/spacecat-shared/issues/1097) [#1097](https://github.com/adobe/spacecat-shared/issues/1097) [#1152](https://github.com/adobe/spacecat-shared/issues/1152) [adobe/spacecat-audit-worker#1520](https://github.com/adobe/spacecat-audit-worker/issues/1520)
+
+# [@adobe/spacecat-shared-utils-v1.75.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.74.0...@adobe/spacecat-shared-utils-v1.75.0) (2025-11-19)
+
+
+### Features
+
+* add aggregation key to get Oppty SC API ([#1148](https://github.com/adobe/spacecat-shared/issues/1148)) ([07bf485](https://github.com/adobe/spacecat-shared/commit/07bf485a5534a066899abf9488ef71301d8cb3e1))
+
 # [@adobe/spacecat-shared-utils-v1.74.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.73.1...@adobe/spacecat-shared-utils-v1.74.0) (2025-11-17)
 
 

package/README.md

@@ -2,6 +2,8 @@
 
 This repository contains a collection of shared utility functions used across various SpaceCat projects. These utilities provide a range of checks and validations, from basic data type validation to more complex checks like ISO date strings and URL validation.
 
+> **v1.76.0**: Added trace ID propagation support for distributed tracing across SpaceCat services.
+
 ## Installation
 
 To install the SpaceCat Shared Utilities, you can use npm:
@@ -45,6 +47,40 @@ The library includes the following utility functions:
 - `hasText(str)`: Checks if the given string is not empty.
 - `dateAfterDays(number)`: Calculates the date after a specified number of days from the current date.
 
+## Log Wrapper
+
+The `logWrapper` enhances your Lambda function logs by automatically prepending `jobId` (from message) and `traceId` (from AWS X-Ray) to all log statements. This improves log traceability across distributed services.
+
+### Features
+- Automatically extracts AWS X-Ray trace ID
+- Includes jobId from message when available  
+- Enhances `context.log` directly - **no code changes needed**
+- Works seamlessly with existing log levels (info, error, debug, warn, trace, etc.)
+
+### Usage
+
+```javascript
+import { logWrapper, sqsEventAdapter } from '@adobe/spacecat-shared-utils';
+
+async function run(message, context) {
+  const { log } = context;
+  
+  // Use context.log as usual - trace IDs are added automatically
+  log.info('Processing started'); 
+  // Output: [jobId=xxx] [traceId=1-xxx-xxx] Processing started
+}
+
+export const main = wrap(run)
+  .with(sqsEventAdapter)
+  .with(logWrapper)  // Add this line early in the wrapper chain
+  .with(dataAccess)
+  .with(sqs)
+  .with(secrets)
+  .with(helixStatus);
+```
+
+**Note:** The `logWrapper` enhances `context.log` directly. All existing code using `context.log` will automatically include trace IDs and job IDs in logs without any code changes.
+
 ## SQS Event Adapter
 
 The library also includes an SQS event adapter to convert an SQS record into a function parameter. This is useful when working with AWS Lambda functions that are triggered by an SQS event. Usage:
@@ -62,6 +98,21 @@ export const main = wrap(run)
   .with(helixStatus);
 ````
 
+## AWS X-Ray Integration
+
+### getTraceId()
+
+Extracts the current AWS X-Ray trace ID from the segment. Returns `null` if not in AWS Lambda or no segment is available.
+
+```javascript
+import { getTraceId } from '@adobe/spacecat-shared-utils';
+
+const traceId = getTraceId();
+// Returns: '1-5e8e8e8e-5e8e8e8e5e8e8e8e5e8e8e8e' or null
+```
+
+This function is automatically used by `logWrapper` to include trace IDs in logs.
+
 ## Testing
 
 This library includes a comprehensive test suite to ensure the reliability of the utility functions. To run the tests, use the following command:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-utils",
-  "version": "1.74.0",
+  "version": "1.76.0",
   "description": "Shared modules of the Spacecat Services - utils",
   "type": "module",
   "exports": {

package/src/aggregation/aggregation-strategies.js

@@ -0,0 +1,248 @@
+/*
+ * Copyright 2025 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.
+ */
+
+/**
+ * Accessibility suggestion aggregation strategies
+ *
+ * Defines how HTML elements with accessibility issues are grouped into database suggestions.
+ * Each granularity level has a function that builds an aggregation key from suggestion data.
+ */
+
+/**
+ * Granularity levels for suggestion aggregation
+ * @enum {string}
+ */
+export const Granularity = {
+  /** One suggestion per HTML element - url|type|selector (e.g., page1|color-contrast|div.header) */
+  INDIVIDUAL: 'INDIVIDUAL',
+
+  /**
+   * One suggestion per issue type per page - url|type (e.g., page1|color-contrast)
+   */
+  PER_PAGE_PER_COMPONENT: 'PER_PAGE_PER_COMPONENT',
+
+  /** One suggestion per page - url (e.g., page1) */
+  PER_PAGE: 'PER_PAGE',
+
+  /**
+   * One suggestion per component type across all pages - type|selector
+   */
+  PER_COMPONENT: 'PER_COMPONENT',
+
+  /** One suggestion per issue type globally - type (e.g., color-contrast) */
+  PER_TYPE: 'PER_TYPE',
+};
+
+/**
+ * Generic key builder that concatenates non-empty values with pipe separator
+ * @param {...string} parts - Variable number of key parts to concatenate
+ * @returns {string} Concatenated key
+ * @private - exported for testing purposes
+ */
+export function buildKey(...parts) {
+  return parts.filter((part) => part != null && part !== '').join('|');
+}
+
+/**
+ * Builds aggregation key for INDIVIDUAL granularity
+ * Key format: url|type|selector|source
+ * @private - exported for testing purposes
+ */
+export function buildIndividualKey({
+  url, issueType, targetSelector, source,
+}) {
+  return buildKey(url, issueType, targetSelector, source);
+}
+
+/**
+ * Builds aggregation key for PER_PAGE_PER_COMPONENT granularity
+ * Key format: url|type|source
+ */
+function buildPerPagePerComponentKey({ url, issueType, source }) {
+  return buildKey(url, issueType, source);
+}
+
+/**
+ * Builds aggregation key for PER_PAGE granularity
+ * Key format: url|source
+ */
+function buildPerPageKey({ url, source }) {
+  return buildKey(url, source);
+}
+
+/**
+ * Builds aggregation key for COMPONENT granularity
+ * Key format: type|selector
+ */
+function buildComponentKey({ issueType, targetSelector }) {
+  return buildKey(issueType, targetSelector);
+}
+
+/**
+ * Builds aggregation key for GLOBAL granularity
+ * Key format: type
+ */
+function buildGlobalKey({ issueType }) {
+  return buildKey(issueType);
+}
+
+/**
+ * Registry of key-building functions by granularity level
+ */
+export const GRANULARITY_KEY_BUILDERS = {
+  [Granularity.INDIVIDUAL]: buildIndividualKey,
+  [Granularity.PER_PAGE_PER_COMPONENT]: buildPerPagePerComponentKey,
+  [Granularity.PER_PAGE]: buildPerPageKey,
+  [Granularity.PER_COMPONENT]: buildComponentKey,
+  [Granularity.PER_TYPE]: buildGlobalKey,
+};
+
+/**
+ * Maps issue types to their aggregation granularity
+ * Based on the nature of each issue and how they should be grouped
+ */
+export const ISSUE_GRANULARITY_MAP = {
+  'color-contrast': Granularity.INDIVIDUAL,
+  list: Granularity.PER_COMPONENT,
+  'aria-roles': Granularity.PER_PAGE_PER_COMPONENT,
+  'image-alt': Granularity.PER_PAGE_PER_COMPONENT,
+  'link-in-text-block': Granularity.PER_PAGE_PER_COMPONENT,
+  'link-name': Granularity.PER_PAGE_PER_COMPONENT,
+  'target-size': Granularity.PER_PAGE_PER_COMPONENT,
+  listitem: Granularity.PER_COMPONENT,
+  label: Granularity.PER_PAGE_PER_COMPONENT,
+  'aria-prohibited-attr': Granularity.PER_TYPE,
+  'button-name': Granularity.PER_PAGE_PER_COMPONENT,
+  'frame-title': Granularity.PER_PAGE_PER_COMPONENT,
+  'aria-valid-attr-value': Granularity.PER_PAGE_PER_COMPONENT,
+  'aria-allowed-attr': Granularity.PER_TYPE,
+  'aria-hidden-focus': Granularity.PER_PAGE_PER_COMPONENT,
+  'nested-interactive': Granularity.PER_PAGE_PER_COMPONENT,
+  'html-has-lang': Granularity.PER_PAGE,
+  'meta-viewport': Granularity.PER_PAGE,
+  'aria-required-children': Granularity.PER_PAGE_PER_COMPONENT,
+  'aria-required-parent': Granularity.PER_PAGE_PER_COMPONENT,
+  'meta-refresh': Granularity.PER_PAGE,
+  'role-img-alt': Granularity.PER_PAGE_PER_COMPONENT,
+  'aria-input-field-name': Granularity.PER_PAGE_PER_COMPONENT,
+  'scrollable-region-focusable': Granularity.PER_PAGE_PER_COMPONENT,
+  'select-name': Granularity.PER_PAGE_PER_COMPONENT,
+};
+
+/**
+ * Gets the granularity level for a specific issue type
+ *
+ * @param {string} issueType - The issue type (e.g., "color-contrast")
+ * @returns {string} The granularity level (defaults to PER_PAGE_PER_COMPONENT)
+ */
+export function getGranularityForIssueType(issueType) {
+  return ISSUE_GRANULARITY_MAP[issueType] || Granularity.PER_PAGE_PER_COMPONENT;
+}
+
+/**
+ * Builds an aggregation key for grouping HTML elements during processing
+ *
+ * @param {string} issueType - The issue type
+ * @param {string} url - Page URL
+ * @param {string} targetSelector - CSS selector for the element
+ * @param {string} source - Optional source identifier
+ * @returns {string} The aggregation key based on the issue type's granularity
+ */
+export function buildAggregationKey(issueType, url, targetSelector, source) {
+  const granularity = getGranularityForIssueType(issueType);
+  const keyBuilder = GRANULARITY_KEY_BUILDERS[granularity];
+
+  /* c8 ignore start - defensive code */
+  if (!keyBuilder) {
+    return buildIndividualKey({
+      url, issueType, targetSelector, source,
+    });
+  }
+  /* c8 ignore stop */
+
+  return keyBuilder({
+    url, issueType, targetSelector, source,
+  });
+}
+
+/**
+ * Builds an aggregation key from suggestion data.
+ * Extracts the necessary fields from a suggestion object and calls buildAggregationKey.
+ *
+ * @param {Object} suggestionData - The suggestion data object
+ * @param {string} suggestionData.url - Page URL
+ * @param {Array} suggestionData.issues - Array of issues
+ * @param {string} suggestionData.source - Optional source
+ * @returns {string|null} The aggregation key based on the issue type's granularity,
+ *   or null if no issues
+ */
+export function buildAggregationKeyFromSuggestion(suggestionData) {
+  // Handle null, undefined, or non-object inputs
+  if (!suggestionData || typeof suggestionData !== 'object') {
+    return null;
+  }
+
+  const { url, issues, source } = suggestionData;
+
+  if (!issues || issues.length === 0) {
+    return null;
+  }
+
+  const firstIssue = issues[0];
+  if (!firstIssue || !firstIssue.type) {
+    return null;
+  }
+
+  const issueType = firstIssue.type;
+  const htmlWithIssue = firstIssue.htmlWithIssues?.[0];
+  // Support both snake_case and camelCase for backwards compatibility
+  const targetSelector = htmlWithIssue?.target_selector || htmlWithIssue?.targetSelector || '';
+
+  return buildAggregationKey(issueType, url, targetSelector, source);
+}
+
+/**
+ * Builds a database-level key for matching suggestions across audit runs.
+ * Used by syncSuggestions to identify existing suggestions.
+ *
+ * This ALWAYS uses INDIVIDUAL granularity (url|type|selector|source) to ensure
+ * each HTML element gets its own suggestion in the database. This prevents
+ * incorrect merging of different HTML elements.
+ *
+ * IMPORTANT: This maintains backwards compatibility with the original buildKey logic
+ * by including a trailing pipe when selector is empty (url|type|).
+ *
+ * @param {Object} suggestionData - The suggestion data object
+ * @param {string} suggestionData.url - Page URL
+ * @param {Array} suggestionData.issues - Array of issues
+ * @param {string} suggestionData.source - Optional source
+ * @returns {string} The key for suggestion matching
+ */
+export function buildSuggestionKey(suggestionData) {
+  const { url, issues, source } = suggestionData;
+
+  if (!issues || issues.length === 0) {
+    return url;
+  }
+
+  const firstIssue = issues[0];
+  const issueType = firstIssue.type;
+  const targetSelector = firstIssue.htmlWithIssues?.[0]?.target_selector || '';
+
+  // Always build INDIVIDUAL-level key for database uniqueness
+  // Backwards compatible: url|type|selector|source or url|type| when selector is empty
+  let key = `${url}|${issueType}|${targetSelector}`;
+  if (source) {
+    key += `|${source}`;
+  }
+  return key;
+}

package/src/index.d.ts

@@ -66,6 +66,36 @@ export function sqsWrapper(fn: (message: object, context: object) => Promise<Res
 export function sqsEventAdapter(fn: (message: object, context: object) => Promise<Response>):
   (request: object, context: object) => Promise<Response>;
 
+/**
+ * A higher-order function that wraps a given function and enhances logging by appending
+ * a `jobId` and `traceId` to log messages when available.
+ * @param fn - The original function to be wrapped
+ * @returns A wrapped function that enhances logging
+ */
+export function logWrapper(fn: (message: object, context: object) => Promise<Response>):
+  (message: object, context: object) => Promise<Response>;
+
+/**
+ * Instruments an AWS SDK v3 client with X-Ray tracing when running in AWS Lambda.
+ * @param client - The AWS SDK v3 client to instrument
+ * @returns The instrumented client (or original client if not in Lambda)
+ */
+export function instrumentAWSClient<T>(client: T): T;
+
+/**
+ * Extracts the trace ID from the current AWS X-Ray segment.
+ * @returns The trace ID if available, or null if not in AWS Lambda or no segment found
+ */
+export function getTraceId(): string | null;
+
+/**
+ * Adds the x-trace-id header to a headers object if a trace ID is available.
+ * @param headers - The headers object to augment
+ * @param context - The context object that may contain traceId
+ * @returns The headers object with x-trace-id added if available
+ */
+export function addTraceIdHeader(headers?: Record<string, string>, context?: object): Record<string, string>;
+
 /**
  * Prepends 'https://' schema to the URL if it's not already present.
  * @param url - The URL to modify.

package/src/index.js

@@ -52,7 +52,7 @@ export { sqsWrapper } from './sqs.js';
 export { sqsEventAdapter } from './sqs.js';
 
 export { logWrapper } from './log-wrapper.js';
-export { instrumentAWSClient } from './xray.js';
+export { instrumentAWSClient, getTraceId, addTraceIdHeader } from './xray.js';
 
 export {
   composeBaseURL,
@@ -108,3 +108,15 @@ export * as schemas from './schemas.js';
 
 export { detectLocale } from './locale-detect/locale-detect.js';
 export { prettifyLogForwardingConfig } from './cdn-helpers.js';
+
+export {
+  buildAggregationKey,
+  buildAggregationKeyFromSuggestion,
+  buildSuggestionKey,
+  buildIndividualKey,
+  buildKey,
+  getGranularityForIssueType,
+  Granularity,
+  GRANULARITY_KEY_BUILDERS,
+  ISSUE_GRANULARITY_MAP,
+} from './aggregation/aggregation-strategies.js';

package/src/log-wrapper.js

@@ -10,47 +10,63 @@
  * governing permissions and limitations under the License.
  */
 
+import { getTraceId } from './xray.js';
+
 /**
  * A higher-order function that wraps a given function and enhances logging by appending
- * a `jobId` to log messages when available. This improves traceability of logs associated
- * with specific jobs or processes.
+ * a `jobId` and `traceId` to log messages when available. This improves traceability of logs
+ * associated with specific jobs or processes.
  *
  * The wrapper checks if a `log` object exists in the `context` and whether the `message`
- * contains a `jobId`. If found, log methods (e.g., `info`, `error`, etc.) will prepend the
- * `jobId` to all log statements where `context.contextualLog` is used. If no `jobId` is found,
- * logging will remain unchanged.
+ * contains a `jobId`. It also extracts the AWS X-Ray trace ID if available. If found, log
+ * methods (e.g., `info`, `error`, etc.) will prepend the `jobId` and/or `traceId` to all log
+ * statements. All existing code using `context.log` will automatically include these markers.
  *
  * @param {function} fn - The original function to be wrapped, called with the provided
  * message and context after logging enhancement.
  * @returns {function(object, object): Promise<Response>} - A wrapped function that enhances
  * logging and returns the result of the original function.
  *
- * `context.contextualLog` will include logging methods with `jobId` prefixed, or fall back
- * to the existing `log` object if no `jobId` is provided.
+ * `context.log` will be enhanced in place to include `jobId` and/or `traceId` prefixed to all
+ * log messages. No code changes needed - existing `context.log` calls work automatically.
  */
 export function logWrapper(fn) {
   return async (message, context) => {
     const { log } = context;
 
     if (log && !context.contextualLog) {
+      const markers = [];
+
+      // Extract jobId from message if available
       if (typeof message === 'object' && message !== null && 'jobId' in message) {
         const { jobId } = message;
-        const jobIdMarker = `[jobId=${jobId}]`;
+        markers.push(`[jobId=${jobId}]`);
+      }
+
+      // Extract traceId from AWS X-Ray
+      const traceId = getTraceId();
+      if (traceId) {
+        markers.push(`[traceId=${traceId}]`);
+      }
+
+      // If we have markers, enhance the log object directly
+      if (markers.length > 0) {
+        const markerString = markers.join(' ');
 
         // Define log levels
         const logLevels = ['info', 'error', 'debug', 'warn', 'trace', 'verbose', 'silly', 'fatal'];
 
-        // Enhance the log object to include jobId in all log statements
-        context.contextualLog = logLevels.reduce((accumulator, level) => {
+        // Enhance context.log directly to include markers in all log statements
+        context.log = logLevels.reduce((accumulator, level) => {
           if (typeof log[level] === 'function') {
-            accumulator[level] = (...args) => log[level](jobIdMarker, ...args);
+            accumulator[level] = (...args) => log[level](markerString, ...args);
           }
           return accumulator;
         }, {});
-      } else {
-        log.debug('No jobId found in the provided message. Log entries will be recorded without a jobId.');
-        context.contextualLog = log;
       }
+
+      // Mark that we've processed this context
+      context.contextualLog = context.log;
     }
 
     return fn(message, context);

package/src/sqs.js

@@ -12,7 +12,7 @@
 
 import { Response } from '@adobe/fetch';
 import { SendMessageCommand, SQSClient } from '@aws-sdk/client-sqs';
-import { instrumentAWSClient } from './xray.js';
+import { instrumentAWSClient, getTraceId } from './xray.js';
 
 import { hasText, isNonEmptyArray } from './functions.js';
 import { isAWSLambda } from './runtimes.js';
@@ -46,8 +46,16 @@ class SQS {
 
   /**
    * Send a message to an SQS queue. For FIFO queues, messageGroupId is required.
+   * Automatically includes traceId in the message payload if available from:
+   * 1. The message itself (if explicitly set by caller, e.g. from context.traceId)
+   * 2. AWS X-Ray segment (current Lambda execution trace)
+   *
+   * Special handling for Jobs Dispatcher and similar scenarios:
+   * - Set traceId to null to opt-out of trace propagation (each worker gets its own trace)
+   *
    * @param {string} queueUrl - The URL of the SQS queue.
    * @param {object} message - The message body to send.
+   *   Can include traceId for propagation or set to null to opt-out.
    * @param {string} messageGroupId - (Optional) The message group ID for FIFO queues.
    * @return {Promise<void>}
    */
@@ -57,6 +65,23 @@ class SQS {
       timestamp: new Date().toISOString(),
     };
 
+    // Handle traceId based on explicit setting or auto-generation
+    // Three cases:
+    // 1. Property not in message → auto-add X-Ray traceId
+    // 2. Property set to null → explicit opt-out (e.g., Jobs Dispatcher)
+    // 3. Property has a value → use that value
+    if (!('traceId' in message)) {
+      // Case 1: No traceId property - auto-add X-Ray trace
+      const traceId = getTraceId();
+      if (traceId) {
+        body.traceId = traceId;
+      }
+    } else if (message.traceId === null) {
+      // Case 2: Explicitly null - opt-out of trace propagation
+      delete body.traceId;
+    }
+    // Case 3: Has a value - already in body from spread, keep it
+
     const params = {
       MessageBody: JSON.stringify(body),
       QueueUrl: queueUrl,
@@ -71,7 +96,7 @@ class SQS {
 
     try {
       const data = await this.sqsClient.send(msgCommand);
-      this.log.debug(`Success, message sent. MessageID:  ${data.MessageId}`);
+      this.log.debug(`Success, message sent. MessageID: ${data.MessageId}${body.traceId ? `, TraceID: ${body.traceId}` : ''}`);
     } catch (e) {
       const { type, code, message: msg } = e;
       this.log.error(`Message sent failed. Type: ${type}, Code: ${code}, Message: ${msg}`);
@@ -95,6 +120,7 @@ export function sqsWrapper(fn) {
 /**
  * Wrapper to turn an SQS record into a function param
  * Inspired by https://github.com/adobe/helix-admin/blob/main/src/index.js#L108-L133
+ * Extracts traceId from the message payload if present and stores it in context for propagation.
  *
  * @param {UniversalAction} fn
  * @returns {function(object, UniversalContext): Promise<Response>}
@@ -124,7 +150,12 @@ export function sqsEventAdapter(fn) {
 
     try {
       message = JSON.parse(record.body);
-      log.debug(`Received message with id: ${record.messageId}`);
+      log.debug(`Received message with id: ${record.messageId}${message.traceId ? `, traceId: ${message.traceId}` : ''}`);
+
+      // Store traceId in context if present in the message for downstream propagation
+      if (message.traceId) {
+        context.traceId = message.traceId;
+      }
     } catch (e) {
       log.warn('Function was not invoked properly, message body is not a valid JSON', e);
       return badRequest('Event does not contain a valid message body');

package/src/xray.js

@@ -16,3 +16,48 @@ import { isAWSLambda } from './runtimes.js';
 export function instrumentAWSClient(client) {
   return isAWSLambda() ? AWSXray.captureAWSv3Client(client) : client;
 }
+
+/**
+ * Extracts the trace ID from the current AWS X-Ray segment.
+ * This function is designed to work in AWS Lambda environments where X-Ray tracing is enabled.
+ *
+ * @returns {string|null} The trace ID if available, or null if not in Lambda or no segment
+ */
+export function getTraceId() {
+  if (!isAWSLambda()) {
+    return null;
+  }
+
+  const segment = AWSXray.getSegment();
+  if (!segment) {
+    return null;
+  }
+
+  // Get the root trace ID
+  const effectiveSegment = segment.segment || segment;
+  return effectiveSegment.trace_id;
+}
+
+/**
+ * Adds the x-trace-id header to a headers object if a trace ID is available.
+ * Checks for traceId from:
+ * 1. Explicit context.traceId (from incoming HTTP request or SQS message)
+ * 2. AWS X-Ray segment (current Lambda execution)
+ *
+ * @param {object} headers - The headers object to augment
+ * @param {object} context - The context object that may contain traceId
+ * @returns {object} The headers object with x-trace-id added if available
+ */
+export function addTraceIdHeader(headers = {}, context = {}) {
+  // Priority: 1) context.traceId (propagated from incoming request), 2) X-Ray traceId
+  const traceId = context.traceId || getTraceId();
+
+  if (traceId) {
+    return {
+      ...headers,
+      'x-trace-id': traceId,
+    };
+  }
+
+  return headers;
+}