@cumulus/cmrjs 20.3.1 → 21.0.0-echo10

package/cmr-utils.js

@@ -22,15 +22,24 @@ const { constructDistributionUrl } = require('@cumulus/distribution-utils');
 const { getBucketAccessUrl } = require('@cumulus/cmr-client/getUrl');
 const { constructCollectionId } = require('@cumulus/message/Collections');
 const { xmlParseOptions, ummVersionToMetadataFormat, } = require('./utils');
+const { updateEcho10XMLGranuleUrAndGranuleIdentifier } = require('./echo10Modifiers');
+const { updateUMMGGranuleURAndGranuleIdentifier } = require('./ummgModifiers');
 /* eslint-disable max-len */
 /**
  * @typedef {import('@cumulus/cmr-client/CMR').CMRConstructorParams} CMRConstructorParams
  * @typedef {import('@cumulus/distribution-utils/dist/types').DistributionBucketMap} DistributionBucketMap
- * @typedef {import('@cumulus/types').ApiFile} ApiFile
+ * @typedef {import('@cumulus/types').ApiFileGranuleIdOptional} ApiFileGranuleIdOptional
+ * @typedef { ApiFileGranuleIdOptional & { filepath?: string }} ApiFileWithFilePath
  */
-/* eslint-enable max-len */
-const log = new Logger({ sender: '@cumulus/cmrjs/src/cmr-utils' });
-const s3CredsEndpoint = 's3credentials';
+/**
+ * @typedef {Object} CmrFile
+ * @property {string} bucket - The S3 bucket name
+ * @property {string} key - The S3 key for the metadata file
+ * @property {string} granuleId - The granule ID associated with the file
+ * @property {string} [etag] - Optional entity tag for file versioning
+ */
+/**
+
 /**
  * @typedef {{
  *   provider: string,
@@ -40,6 +49,30 @@ const s3CredsEndpoint = 's3credentials';
  *   token?: string
  * }} CmrCredentials
  */
+/**
+ * @typedef {Object} Echo10URLObject
+ * @property {string} URL
+ * @property {string} [Type]
+ * @property {string} [Description]
+ * @property {string} [URLDescription]
+ */
+/**
+ * @typedef {Object} Echo10MetadataObject
+ * @property {Object} Granule - The root ECHO10 granule object
+ * @property {{ OnlineAccessURL?: Echo10URLObject[] }} [Granule.OnlineAccessURLs]
+ * @property {{ OnlineResource?: Echo10URLObject[] }} [Granule.OnlineResources]
+ * @property {{ ProviderBrowseUrl?: Echo10URLObject[] }} [Granule.AssociatedBrowseImageUrls]
+ */
+/**
+ * @typedef {Object}  getS3UrlOfFileFile
+ * @property {string} [filename] - Full S3 URI (e.g., s3://bucket/key)
+ * @property {string} [bucket] - Bucket name (used with `key` or `filepath`)
+ * @property {string} [key] - S3 key (used with `bucket`)
+ * @property {string} [filepath] - Alternate key for the file within the bucket
+ */
+/* eslint-enable max-len */
+const log = new Logger({ sender: '@cumulus/cmrjs/src/cmr-utils' });
+const s3CredsEndpoint = 's3credentials';
 function getS3KeyOfFile(file) {
     if (file.filename)
         return parseS3Uri(file.filename).Key;
@@ -49,6 +82,34 @@ function getS3KeyOfFile(file) {
         return file.key;
     throw new Error(`Unable to determine s3 key of file: ${JSON.stringify(file)}`);
 }
+/**
+ * Validates that required granule metadata parameters are provided.
+ * Throws an error if either parameter is missing or falsy.
+ *
+ * @param {Object} params - Parameter object
+ * @param {string} params.producerGranuleId - The original granule identifier (must be non-empty)
+ * @param {string} params.granuleId - The updated granule identifier (must be non-empty)
+ *
+ * @throws {Error} if either `producerGranuleId` or `granuleId` is not provided
+ */
+function checkRequiredMetadataParms({ producerGranuleId, granuleId }) {
+    if (!producerGranuleId) {
+        throw new Error('No producerGranuleId was provided when required for CMR metadata update');
+    }
+    if (!granuleId) {
+        throw new Error('No granuleId was provided when required for CMR Metadata update');
+    }
+}
+/**
+ * Returns the S3 URI for a given file object.
+ *
+ * Accepts multiple file shapes commonly used throughout Cumulus and resolves
+ * them to a valid `s3://bucket/key` URI.
+ *
+ * @param {getS3UrlOfFileFile} file - File object containing filename or bucket/key data
+ * @returns {string} - A string representing the S3 URI (e.g., `s3://bucket/key`)
+ * @throws {Error} if the file does not contain enough information to construct the URI
+ */
 function getS3UrlOfFile(file) {
     if (file.filename)
         return file.filename;
@@ -58,6 +119,15 @@ function getS3UrlOfFile(file) {
         return buildS3Uri(file.bucket, file.key);
     throw new Error(`Unable to determine location of file: ${JSON.stringify(file)}`);
 }
+/**
+ * Returns the file 'name' of a given object.
+ *
+ * Accepts multiple file shapes commonly used throughout Cumulus and resolves
+ * them to a valid `s3://bucket/key` URI.
+ *
+ * @param {ApiFileWithFilePath} file - API File
+ * @returns {string | undefined} - The file name, or undefined if not found
+ */
 function getFilename(file) {
     if (file.fileName)
         return file.fileName;
@@ -115,7 +185,7 @@ function isISOFile(fileobject) {
  * @param {string} granule.granuleId - granule ID
  * @param {Function} filterFunc - function to determine if the given file object is a
       CMR file; defaults to `isCMRFile`
- * @returns {Array<Object>} an array of CMR file objects, each with properties
+ * @returns {Array<CmrFile>} an array of CMR file objects, each with properties
  *    `granuleId`, `bucket`, `key`, and possibly `etag` (if present on input)
  */
 function granuleToCmrFileObject({ granuleId, files = [] }, filterFunc = isCMRFile) {
@@ -139,7 +209,7 @@ function granuleToCmrFileObject({ granuleId, files = [] }, filterFunc = isCMRFil
  * @param {Function} filterFunc - function to determine if the given file object is a
       CMR file; defaults to `isCMRFile`
  *
- * @returns {Array<Object>} - CMR file object array: { etag, bucket, key, granuleId }
+ * @returns {Array<CmrFile>} - CMR file object array: { etag, bucket, key, granuleId }
  */
 function granulesToCmrFileObjects(granules, filterFunc = isCMRFile) {
     return granules.flatMap((granule) => granuleToCmrFileObject(granule, filterFunc));
@@ -153,7 +223,7 @@ function granulesToCmrFileObjects(granules, filterFunc = isCMRFile) {
  * @param {string} cmrFile.metadata - granule xml document
  * @param {Object} cmrClient - a CMR instance
  * @param {string} revisionId - Optional CMR Revision ID
- * @returns {Object} CMR's success response which includes the concept-id
+ * @returns {Promise<Object>} CMR's success response which includes the concept-id
  */
 async function publishECHO10XML2CMR(cmrFile, cmrClient, revisionId) {
     const builder = new xml2js.Builder();
@@ -181,7 +251,7 @@ async function publishECHO10XML2CMR(cmrFile, cmrClient, revisionId) {
  * @param {Object} cmrFile.granuleId - the metadata's granuleId
  * @param {Object} cmrClient - a CMR instance
  * @param {string} revisionId - Optional CMR Revision ID
- * @returns {Object} CMR's success response which includes the concept-id
+ * @returns {Promise<Object>} CMR's success response which includes the concept-id
  */
 async function publishUMMGJSON2CMR(cmrFile, cmrClient, revisionId) {
     const granuleId = cmrFile.metadataObject.GranuleUR;
@@ -327,7 +397,7 @@ function metadataObjectFromCMRFile(cmrFilename, etag) {
  * Build and return an S3 Credentials Object for adding to CMR onlineAccessUrls
  *
  * @param {string} s3CredsUrl - full url pointing to the s3 credential distribution api
- * @returns {Object} Object with attributes required for adding an onlineAccessUrl
+ * @returns {Echo10URLObject} Object with attributes required for adding an onlineAccessUrl
  */
 function getS3CredentialsObject(s3CredsUrl) {
     return {
@@ -341,11 +411,12 @@ function getS3CredentialsObject(s3CredsUrl) {
  * Returns UMM/ECHO10 resource type mapping for CNM file type
  *
  * @param {string} type - CNM resource type to convert to UMM/ECHO10 type
- * @param {string} urlType - url type, distribution or s3
- * @param {boolean} useDirectS3Type - indicate if direct s3 access type is used
- * @returns {( string | undefined )} type - UMM/ECHO10 resource type
+ * @param {string} [urlType = distribution] - url type, distribution or s3
+ * @param {boolean} [useDirectS3Type = false] - indicate if direct s3 access type is used
+ * @returns {string} - UMM/ECHO10 resource type
  */
 function mapCNMTypeToCMRType(type, urlType = 'distribution', useDirectS3Type = false) {
+    /** @type {Record<string, string>} */
     const mapping = {
         ancillary: 'VIEW RELATED INFORMATION',
         data: 'GET DATA',
@@ -354,7 +425,10 @@ function mapCNMTypeToCMRType(type, urlType = 'distribution', useDirectS3Type = f
         metadata: 'EXTENDED METADATA',
         qa: 'EXTENDED METADATA',
     };
-    const mappedType = mapping[type] || 'GET DATA';
+    let mappedType = 'GET DATA';
+    if (type && type in mapping) {
+        mappedType = mapping[type];
+    }
     // The CMR Type for the s3 link of science file is "GET DATA VIA DIRECT ACCESS".
     // For non-science file, the Type for the s3 link is the same as its Type for the HTTPS URL.
     if (urlType === 's3' && mappedType === 'GET DATA' && useDirectS3Type) {
@@ -411,10 +485,10 @@ function mapFileEtags(files) {
  * @param {Object} params - input parameters
  * @param {Object} params.file - file object
  * @param {string} params.distEndpoint - distribution endpoint from config
- * @param {Object} params.urlType - url type, distribution or s3
- * @param {distributionBucketMap} params.distributionBucketMap - Object with bucket:tea-path mapping
- *                                                               for all distribution bucketss
- * @returns {(Object | undefined)} online access url object, undefined if no URL exists
+ * @param {string} [params.urlType = 'distribution'] - url type, distribution or s3
+ * @param {Object} params.distributionBucketMap - Object with bucket:tea-path mapping
+ *                                                               for all distribution buckets
+ * @returns {(string | undefined)} online access url object, undefined if no URL exists
  */
 function generateFileUrl({ file, distEndpoint, urlType = 'distribution', distributionBucketMap, }) {
     if (urlType === 'distribution') {
@@ -442,19 +516,19 @@ function generateFileUrl({ file, distEndpoint, urlType = 'distribution', distrib
 /**
  * Construct online access url for a given file and a url type.
  *
- * @param {Object} params.file - file object
- * @param {string} params.distEndpoint - distribution endpoint from config
- * @param {{ [key: string]: string }} params.bucketTypes - map of bucket name to bucket type
- * @param {Object} params.urlType - url type, distribution or s3
- * @param {distributionBucketMap} params.distributionBucketMap - Object with bucket:tea-path mapping
- *                                                               for all distribution bucketss
- * @param {boolean} [params.useDirectS3Type] - indicate if direct s3 access type is used
- * @returns {(OnlineAccessUrl | undefined)} online access url object, undefined if no URL exists
+ * @param {Object} params
+ * @param {ApiFileWithFilePath} params.file - File object
+ * @param {string} params.distEndpoint - Distribution endpoint from config
+ * @param {{ [key: string]: string }} params.bucketTypes - Map of bucket names to bucket types
+ * @param {'distribution' | 's3'} params.urlType - URL type: 'distribution' or 's3'
+ * @param {DistributionBucketMap} params.distributionBucketMap - Map of bucket to distribution path
+ * @param {boolean} [params.useDirectS3Type=false] - Whether to use direct S3 Type
+ * @returns {Echo10URLObject | undefined} - Online access URL object, or undefined if not applicable
  */
 function constructOnlineAccessUrl({ file, distEndpoint, bucketTypes, urlType = 'distribution', distributionBucketMap, useDirectS3Type = false, }) {
-    const bucketType = bucketTypes[file.bucket];
+    const bucketType = file.bucket ? bucketTypes[file.bucket] : undefined;
     const distributionApiBuckets = ['protected', 'public'];
-    if (distributionApiBuckets.includes(bucketType)) {
+    if (bucketType && distributionApiBuckets.includes(bucketType)) {
         const fileUrl = generateFileUrl({ file, distEndpoint, urlType, distributionBucketMap });
         if (fileUrl) {
             const fileDescription = getFileDescription(file, urlType);
@@ -471,21 +545,23 @@ function constructOnlineAccessUrl({ file, distEndpoint, bucketTypes, urlType = '
 /**
  * Construct a list of online access urls grouped by link type.
  *
- * @param {Array<Object>} params.files - array of file objects
- * @param {string} params.distEndpoint - distribution endpoint from config
- * @param {{ [key: string]: string }} params.bucketTypes - map of bucket name to bucket type
- * @param {string} params.cmrGranuleUrlType - cmrGranuleUrlType from config
- * @param {distributionBucketMap} params.distributionBucketMap - Object with bucket:tea-path mapping
- *                                                               for all distribution bucketss
- * @param {boolean} params.useDirectS3Type - indicate if direct s3 access type is used
- * @returns {Promise<[{URL: string, URLDescription: string}]>} an array of
- *    online access url objects grouped by link type.
+ * @param {Object} params
+ * @param {ApiFileWithFilePath[]} params.files - Array of file objects
+ * @param {string} params.distEndpoint - Distribution endpoint from config
+ * @param {{ [key: string]: string }} params.bucketTypes - Map of bucket name to bucket type
+ * @param {DistributionBucketMap} params.distributionBucketMap - Mapping of bucket to
+ * distribution path
+ * @param {string} [params.cmrGranuleUrlType=both] - Granule URL type: 's3',
+ * 'distribution', or 'both'
+ * @param {boolean} [params.useDirectS3Type=false] - Whether direct S3 URL types are used
+ * @returns {Echo10URLObject[]} Array of online access URL objects
  */
-function constructOnlineAccessUrls({ files, distEndpoint, bucketTypes, cmrGranuleUrlType = 'both', distributionBucketMap, useDirectS3Type = false, }) {
+function constructOnlineAccessUrls({ bucketTypes, cmrGranuleUrlType = 'both', distEndpoint, distributionBucketMap, files, useDirectS3Type = false, }) {
     if (['distribution', 'both'].includes(cmrGranuleUrlType) && !distEndpoint) {
         throw new Error(`cmrGranuleUrlType is ${cmrGranuleUrlType}, but no distribution endpoint is configured.`);
     }
-    const [distributionUrls, s3Urls] = files.reduce(([distributionAcc, s3Acc], file) => {
+    const [distributionUrls, s3Urls] = files.reduce((
+    /** @type {[Echo10URLObject[], Echo10URLObject[]]} */ [distributionAcc, s3Acc], file) => {
         if (['both', 'distribution'].includes(cmrGranuleUrlType)) {
             const url = constructOnlineAccessUrl({
                 file,
@@ -495,7 +571,8 @@ function constructOnlineAccessUrls({ files, distEndpoint, bucketTypes, cmrGranul
                 distributionBucketMap,
                 useDirectS3Type,
             });
-            distributionAcc.push(url);
+            if (url)
+                distributionAcc.push(url);
         }
         if (['both', 's3'].includes(cmrGranuleUrlType)) {
             const url = constructOnlineAccessUrl({
@@ -506,7 +583,8 @@ function constructOnlineAccessUrls({ files, distEndpoint, bucketTypes, cmrGranul
                 distributionBucketMap,
                 useDirectS3Type,
             });
-            s3Acc.push(url);
+            if (url)
+                s3Acc.push(url);
         }
         return [distributionAcc, s3Acc];
     }, [[], []]);
@@ -524,7 +602,7 @@ function constructOnlineAccessUrls({ files, distEndpoint, bucketTypes, cmrGranul
  * @param {DistributionBucketMap} params.distributionBucketMap - Object with bucket:tea-path
  *    mapping for all distribution buckets
  * @param {boolean} params.useDirectS3Type - indicate if direct s3 access type is used
- * @returns {Promise<[{URL: string, string, Description: string, Type: string}]>}
+ * @returns {[{URL: string, string, Description: string, Type: string}]}
  *   an array of online access url objects
  */
 function constructRelatedUrls({ files, distEndpoint, bucketTypes, cmrGranuleUrlType = 'both', distributionBucketMap, useDirectS3Type = false, }) {
@@ -603,8 +681,9 @@ function mergeURLs(original, updated = [], removed = []) {
  * Updates CMR JSON file with stringified 'metadataObject'
  *
  * @param {Object} metadataObject - JSON Object to stringify
- * @param {Object} cmrFile - cmr file object to write body to
- * @returns {Promise} returns promised promiseS3Upload response
+ * @param {CmrFile} cmrFile - cmr file object to write body to
+ * @returns {Promise<{[key: string]: any, ETag?: string | undefined }>} returns promised
+ * promiseS3Upload response
  */
 async function uploadUMMGJSONCMRFile(metadataObject, cmrFile) {
     const tags = await s3GetObjectTagging(cmrFile.bucket, getS3KeyOfFile(cmrFile));
@@ -638,13 +717,19 @@ function shouldUseDirectS3Type(metadataObject) {
 /**
  * Update the UMMG cmr metadata object to have corrected urls
  *
- * @param {Object} params.metadataObject - ummg cmr metadata object
- * @param {Array<ApiFile>} params.files - files with which to update the cmr metadata
- * @param {{ [key: string]: string }} params.bucketTypes - map of bucket names to bucket types
- * @param {string} params.cmrGranuleUrlType
- * @param {DistributionBucketMap} params.distributionBucketMap - Object with bucket:tea-path
- *    mapping for all distribution buckets
- * @returns {Object}
+ * @param {Object} params - Parameters for updating the metadata object
+ * @param {Object} params.metadataObject - The existing UMMG CMR metadata object to update
+ * @param {ApiFileWithFilePath[]} params.files - Array of file
+ * objects used to generate URLs
+ * @param {string} params.distEndpoint - Base URL for distribution endpoints (e.g., CloudFront)
+ * @param {{ [bucket: string]: string }} params.bucketTypes - Map of bucket names
+ * to types (e.g., public, protected)
+ * @param {string} [params.cmrGranuleUrlType='both'] - Type of URLs to generate: 'distribution',
+ * 's3', or 'both'
+ * @param {DistributionBucketMap} params.distributionBucketMap - Mapping of bucket names to
+ * distribution paths
+ *
+ * @returns {Object} - A deep clone of the original metadata object with updated RelatedUrls
  */
 function updateUMMGMetadataObject({ metadataObject, files, distEndpoint, bucketTypes, cmrGranuleUrlType = 'both', distributionBucketMap, }) {
     const updatedMetadataObject = cloneDeep(metadataObject);
@@ -658,6 +743,7 @@ function updateUMMGMetadataObject({ metadataObject, files, distEndpoint, bucketT
         useDirectS3Type,
     });
     const removedURLs = onlineAccessURLsToRemove(files, bucketTypes);
+    /** @type {Array<{ URL: string, Description?: string, Type?: string }>} */
     const originalURLs = get(updatedMetadataObject, 'RelatedUrls', []);
     const mergedURLs = mergeURLs(originalURLs, newURLs, removedURLs);
     set(updatedMetadataObject, 'RelatedUrls', mergedURLs);
@@ -668,21 +754,27 @@ function updateUMMGMetadataObject({ metadataObject, files, distEndpoint, bucketT
  * UMMG cmr.json file with this information.
  *
  * @param {Object} params - parameter object
- * @param {Object} params.cmrFile - cmr.json file whose contents will be updated.
- * @param {Array<Object>} params.files - array of moved file objects.
+ * @param {CmrFile} params.cmrFile - cmr.json file whose contents will be updated.
+ * @param {ApiFileWithFilePath[]} params.files - array of moved file objects.
  * @param {string} params.distEndpoint - distribution endpoint form config.
- * @param {{ [key: string]: string }} params.bucketTypes - map of bucket names to bucket types
+ * @param {{ [bucket: string]: string }} params.bucketTypes - map of bucket names to bucket types
  * @param {string} params.cmrGranuleUrlType - cmrGranuleUrlType from config
  * @param {DistributionBucketMap} params.distributionBucketMap - Object with bucket:tea-path
  *    mapping for all distribution buckets
- * @returns {Promise<{ metadataObject: Object, etag: string}>} an object
+ * @param {string} params.producerGranuleId - producer granule id
+ * @param {string} params.granuleId - granule id
+ * @param {boolean} [params.updateGranuleIdentifiers=false] - whether to update the granule UR/add
+ * producerGranuleID to the CMR metadata object
+ * @param {any} [params.testOverrides] - overrides for testing
+ * @returns {Promise<{ metadataObject: Object, etag: string | undefined}>} an object
  *    containing a `metadataObject` (the updated UMMG metadata object) and the
  *    `etag` of the uploaded CMR file
  */
-async function updateUMMGMetadata({ cmrFile, files, distEndpoint, bucketTypes, cmrGranuleUrlType = 'both', distributionBucketMap, }) {
+async function updateUMMGMetadata({ cmrFile, files, distEndpoint, bucketTypes, cmrGranuleUrlType = 'both', distributionBucketMap, producerGranuleId, granuleId, updateGranuleIdentifiers = false, testOverrides = {}, }) {
+    const { uploadUMMGJSONCMRFileMethod = uploadUMMGJSONCMRFile, metadataObjectFromCMRJSONFileMethod = metadataObjectFromCMRJSONFile, } = testOverrides;
     const filename = getS3UrlOfFile(cmrFile);
-    const metadataObject = await metadataObjectFromCMRJSONFile(filename);
-    const updatedMetadataObject = updateUMMGMetadataObject({
+    const metadataObject = await metadataObjectFromCMRJSONFileMethod(filename);
+    let updatedMetadataObject = updateUMMGMetadataObject({
         metadataObject,
         files,
         distEndpoint,
@@ -690,7 +782,16 @@ async function updateUMMGMetadata({ cmrFile, files, distEndpoint, bucketTypes, c
         cmrGranuleUrlType,
         distributionBucketMap,
     });
-    const { ETag: etag } = await uploadUMMGJSONCMRFile(updatedMetadataObject, cmrFile);
+    if (updateGranuleIdentifiers) {
+        // Type checks are needed as this callers/API are not all typed/ts converted yet
+        checkRequiredMetadataParms({ producerGranuleId, granuleId });
+        updatedMetadataObject = updateUMMGGranuleURAndGranuleIdentifier({
+            granuleUr: granuleId,
+            producerGranuleId,
+            metadataObject: updatedMetadataObject,
+        });
+    }
+    const { ETag: etag } = await uploadUMMGJSONCMRFileMethod(updatedMetadataObject, cmrFile);
     return { metadataObject: updatedMetadataObject, etag };
 }
 /**
@@ -791,22 +892,45 @@ function buildMergedEchoURLObject(URLlist = [], originalURLlist = [], removedURL
     return mergeURLs(originalURLlist, filteredURLObjectList, removedURLs);
 }
 /**
- * Update the Echo10 cmr metadata object to have corrected urls
+ * Updates the OnlineAccessURLs, OnlineResources, and AssociatedBrowseImageUrls
+ * fields of an ECHO10 CMR metadata object with newly constructed URLs.
  *
- * @param {Object} params.metadataObject - xml cmr metadata object
- * @param {Array<Object>} params.files - files with which to update the cmr metadata
- * @param {{ [key: string]: string }} params.bucketTypes - map of bucket names to bucket types
- * @param {string} params.cmrGranuleUrlType
- * @param {DistributionBucketMap} params.distributionBucketMap - Object with bucket:tea-path
- *    mapping for all distribution buckets
- * @returns {Object}
+ * This function:
+ * - Extracts the original URL sets from the ECHO10 XML metadata.
+ * - Constructs new URL entries based on the provided file list and configuration.
+ * - Merges new URLs with original ones, removing outdated or irrelevant URLs.
+ * - Returns a new metadata object with an updated `Granule` field.
+ *
+ * @param {Object} params - Input parameters
+ * @param {Echo10MetadataObject} params.metadataObject - The parsed ECHO10 metadata XML
+ * object (as a JavaScript object), expected to include a `Granule` key
+ * @param {ApiFileWithFilePath[]} params.files - Granule files to generate
+ *  updated URLs from
+ * @param {string} params.distEndpoint - The base distribution endpoint URL
+ * (e.g., CloudFront origin)
+ * @param {{ [bucketName: string]: string }} params.bucketTypes - Mapping of bucket names
+ *  to access types ('public', 'protected', etc.)
+ * @param {string} [params.cmrGranuleUrlType='both'] - Type of URLs to generate
+ *  for CMR: 'distribution', 's3', or 'both'
+ * @param {DistributionBucketMap} params.distributionBucketMap - Maps S3 buckets to their
+ *  distribution URL paths
+ *
+ * @returns {Echo10MetadataObject} A new ECHO10 metadata object with updated
+ *  `Granule.OnlineAccessURLs`, `Granule.OnlineResources`, and `Granule.AssociatedBrowseImageUrls`
+ *  fields
  */
-function updateEcho10XMLMetadataObject({ metadataObject, files, distEndpoint, bucketTypes, cmrGranuleUrlType = 'both', distributionBucketMap, }) {
+function updateEcho10XMLMetadataObjectUrls({ metadataObject, files, distEndpoint, bucketTypes, cmrGranuleUrlType = 'both', distributionBucketMap, }) {
     const metadataGranule = metadataObject.Granule;
     const updatedGranule = { ...metadataGranule };
-    const originalOnlineAccessURLs = [].concat(get(metadataGranule, 'OnlineAccessURLs.OnlineAccessURL', []));
-    const originalOnlineResourceURLs = [].concat(get(metadataGranule, 'OnlineResources.OnlineResource', []));
-    const originalAssociatedBrowseURLs = [].concat(get(metadataGranule, 'AssociatedBrowseImageUrls.ProviderBrowseUrl', []));
+    /** @type {Echo10URLObject[]} */
+    const originalOnlineAccessURLs = /** @type {Echo10URLObject[]} */ (
+    /** @type {Echo10URLObject[]} */ ([]).concat(get(metadataGranule, 'OnlineAccessURLs.OnlineAccessURL') ?? []));
+    /** @type {Echo10URLObject[]} */
+    const originalOnlineResourceURLs = /** @type {Echo10URLObject[]} */ (
+    /** @type {Echo10URLObject[]} */ ([]).concat(get(metadataGranule, 'OnlineResources.OnlineResource') ?? []));
+    /** @type {Echo10URLObject[]} */
+    const originalAssociatedBrowseURLs = /** @type {Echo10URLObject[]} */ (
+    /** @type {Echo10URLObject[]} */ ([]).concat(get(metadataGranule, 'AssociatedBrowseImageUrls.ProviderBrowseUrl') ?? []));
     const removedURLs = onlineAccessURLsToRemove(files, bucketTypes);
     const newURLs = constructOnlineAccessUrls({
         files,
@@ -829,24 +953,34 @@ function updateEcho10XMLMetadataObject({ metadataObject, files, distEndpoint, bu
     };
 }
 /**
- * After files are moved, creates new online access URLs and then updates
- * the S3 ECHO10 CMR XML file with this information.
+ * Updates an ECHO10 CMR XML metadata file on S3 to reflect new URLs and optionally
+ * a new GranuleUR and ProducerGranuleId.
  *
- * @param {Object} params - parameter object
- * @param {Object} params.cmrFile - cmr xml file object to be updated
- * @param {Array<Object>} params.files - array of file objects
- * @param {string} params.distEndpoint - distribution endpoint from config
- * @param {{ [key: string]: string }} params.bucketTypes - map of bucket names to bucket types
- * @param {DistributionBucketMap} params.distributionBucketMap - Object with bucket:tea-path
- *    mapping for all distribution buckets
- * @returns {Promise<{ metadataObject: Object, etag: string}>} an object
- *    containing a `metadataObject` and the `etag` of the uploaded CMR file
+ * @param {Object} params
+ * @param {string} params.granuleId - New GranuleUR to set in metadata
+ * @param {string} params.producerGranuleId - Original ProducerGranuleId to record
+ * @param {CmrFile} params.cmrFile - The cmr xml file to be updated
+ * @param {ApiFileWithFilePath[]} params.files - List of granule files used
+ * to generate OnlineAccess URLs
+ * @param {string} params.distEndpoint - Distribution endpoint for download URLs
+ * @param {{ [bucket: string]: string }} params.bucketTypes - Mapping of bucket names to their types
+ * @param {string} [params.cmrGranuleUrlType]
+ * - Type of URLs to generate ('distribution' | 's3' | 'both')
+ * @param {DistributionBucketMap} params.distributionBucketMap
+ * - Maps buckets to distribution paths
+ * @param {boolean} [params.updateGranuleIdentifiers]
+ * - If true, update the GranuleUR and ProducerGranuleId in metadata
+ * @param {any} [params.testOverrides]
+ * - Optional test overrides for internal functions
+ * @returns {Promise<{ metadataObject: any, etag: string }>}
+ * The updated metadata object and resulting ETag
  */
-async function updateEcho10XMLMetadata({ cmrFile, files, distEndpoint, bucketTypes, cmrGranuleUrlType = 'both', distributionBucketMap, }) {
+async function updateEcho10XMLMetadata({ granuleId, producerGranuleId, cmrFile, files, distEndpoint, bucketTypes, cmrGranuleUrlType = 'both', distributionBucketMap, updateGranuleIdentifiers = false, testOverrides = {}, }) {
+    const { generateEcho10XMLStringMethod = generateEcho10XMLString, uploadEcho10CMRFileMethod = uploadEcho10CMRFile, metadataObjectFromCMRXMLFileMethod = metadataObjectFromCMRXMLFile, } = testOverrides;
     // add/replace the OnlineAccessUrls
     const filename = getS3UrlOfFile(cmrFile);
-    const metadataObject = await metadataObjectFromCMRXMLFile(filename);
-    const updatedMetadataObject = updateEcho10XMLMetadataObject({
+    const metadataObject = await metadataObjectFromCMRXMLFileMethod(filename);
+    let updatedMetadataObject = updateEcho10XMLMetadataObjectUrls({
         metadataObject,
         files,
         distEndpoint,
@@ -854,8 +988,22 @@ async function updateEcho10XMLMetadata({ cmrFile, files, distEndpoint, bucketTyp
         cmrGranuleUrlType,
         distributionBucketMap,
     });
-    const xml = generateEcho10XMLString(updatedMetadataObject.Granule);
-    const { ETag: etag } = await uploadEcho10CMRFile(xml, cmrFile);
+    if (updateGranuleIdentifiers) {
+        // Type checks are needed as this callers/API are not all typed/ts converted yet
+        try {
+            checkRequiredMetadataParms({ producerGranuleId, granuleId });
+        }
+        catch (error) {
+            throw new Error(`updateGranuleIdentifiers was set, but producerGranuleId ${producerGranuleId} or granuleId ${granuleId} is not set.`, { cause: error });
+        }
+        updatedMetadataObject = updateEcho10XMLGranuleUrAndGranuleIdentifier({
+            granuleUr: granuleId,
+            producerGranuleId,
+            xml: updatedMetadataObject,
+        });
+    }
+    const xml = generateEcho10XMLStringMethod(updatedMetadataObject.Granule);
+    const { ETag: etag } = await uploadEcho10CMRFileMethod(xml, cmrFile);
     return { metadataObject: updatedMetadataObject, etag };
 }
 /**
@@ -863,28 +1011,37 @@ async function updateEcho10XMLMetadata({ cmrFile, files, distEndpoint, bucketTyp
  *
  * @param {Object} params - parameter object
  * @param {string} params.granuleId - granuleId
- * @param {Object} params.cmrFile - cmr xml file to be updated
- * @param {Array<ApiFile>} params.files - array of file objects
+ * @param {string} [params.producerGranuleId] - producer granuleId
+ * @param {CmrFile} params.cmrFile - cmr file to be updated
+ * @param {ApiFileWithFilePath[]} params.files - array of file objects
  * @param {string} params.distEndpoint - distribution enpoint from config
  * @param {boolean} params.published - indicate if publish is needed
  * @param {{ [key: string]: string }} params.bucketTypes - map of bucket names to bucket types
  * @param {string} params.cmrGranuleUrlType - type of granule CMR url
+ * @param {boolean} [params.updateGranuleIdentifiers]
+ * - If true, update the GranuleUR and ProducerGranuleId in metadata
+ * @param {any} [params.testOverrides]
+ * - Optional test overrides for internal functions
  * @param {DistributionBucketMap} params.distributionBucketMap - Object with bucket:tea-path
  *    mapping for all distribution buckets
  * @returns {Promise<Object>} CMR file object with the `etag` of the newly
  *    updated metadata file
  */
-async function updateCMRMetadata({ granuleId, cmrFile, files, distEndpoint, published, bucketTypes, cmrGranuleUrlType = 'both', distributionBucketMap, }) {
+async function updateCMRMetadata({ granuleId, producerGranuleId, cmrFile, files, distEndpoint, published, bucketTypes, cmrGranuleUrlType = 'both', updateGranuleIdentifiers = false, distributionBucketMap, testOverrides = {}, }) {
+    const { publish2CMRMethod = publish2CMR, getCmrSettingsMethod = getCmrSettings, } = testOverrides;
     const filename = getS3UrlOfFile(cmrFile);
-    log.debug(`cmrjs.updateCMRMetadata granuleId ${granuleId}, cmrMetadata file ${filename}`);
-    const cmrCredentials = (published) ? await getCmrSettings() : {};
+    log.debug(`cmrjs.updateCMRMetadata granuleId ${granuleId} cmrMetadata file ${filename}`);
+    const cmrCredentials = (published) ? await getCmrSettingsMethod() : {};
     const params = {
-        cmrFile,
-        files,
-        distEndpoint,
         bucketTypes,
+        cmrFile,
         cmrGranuleUrlType,
+        distEndpoint,
         distributionBucketMap,
+        files,
+        granuleId,
+        producerGranuleId: producerGranuleId || granuleId,
+        updateGranuleIdentifiers,
     };
     let metadataObject;
     let etag;
@@ -904,7 +1061,7 @@ async function updateCMRMetadata({ granuleId, cmrFile, files, distEndpoint, publ
             metadataObject,
             granuleId,
         };
-        return { ...await publish2CMR(cmrPublishObject, cmrCredentials), etag };
+        return { ...await publish2CMRMethod(cmrPublishObject, cmrCredentials), etag };
     }
     return { ...cmrFile, etag };
 }
@@ -1144,21 +1301,23 @@ const getCMRCollectionId = (cmrObject, cmrFileName) => {
 };
 module.exports = {
     addEtagsToFileObjects,
+    buildCMRQuery,
     constructCmrConceptLink,
     constructOnlineAccessUrl,
     constructOnlineAccessUrls,
     generateEcho10XMLString,
     generateFileUrl,
-    granuleToCmrFileObject,
-    getCmrSettings,
     getCMRCollectionId,
+    getCmrSettings,
+    getCollectionsByShortNameAndVersion,
     getFileDescription,
     getFilename,
     getGranuleTemporalInfo,
-    getCollectionsByShortNameAndVersion,
     getS3UrlOfFile,
     getUserAccessibleBuckets,
+    getXMLMetadataAsString,
     granulesToCmrFileObjects,
+    granuleToCmrFileObject,
     isCMRFile,
     isCMRFilename,
     isCMRISOFilename,
@@ -1168,15 +1327,18 @@ module.exports = {
     isUMMGFilename,
     mapFileEtags,
     metadataObjectFromCMRFile,
+    parseXmlString,
     publish2CMR,
     reconcileCMRMetadata,
     removeEtagsFromFileObjects,
     removeFromCMR,
-    updateCMRMetadata,
-    updateEcho10XMLMetadataObject,
-    updateUMMGMetadataObject,
     setECHO10Collection,
     setUMMGCollection,
+    updateCMRMetadata,
+    updateEcho10XMLMetadata,
+    updateEcho10XMLMetadataObjectUrls,
+    updateUMMGMetadata,
+    updateUMMGMetadataObject,
     uploadEcho10CMRFile,
     uploadUMMGJSONCMRFile,
 };