@uipath/uipath-typescript 1.4.1 → 1.5.0

package/dist/maestro-processes/index.mjs

@@ -42,6 +42,108 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+/**
+ * Maps API field names (countOf*) to SDK field names (*Count) for InstanceStats,
+ * aligning naming with ElementStats and other count-suffixed conventions.
+ */
+const InstanceStatsMap = {
+    countOfAllInstances: 'totalCount',
+    countOfRunning: 'runningCount',
+    countOfTransitioning: 'transitioningCount',
+    countOfPaused: 'pausedCount',
+    countOfFaulted: 'faultedCount',
+    countOfCompleted: 'completedCount',
+    countOfCancelled: 'cancelledCount',
+    countOfDeleted: 'deletedCount'
+};
+
+/**
+ * Converts a UTC timestamp string (e.g., "5/8/2026 11:20:17 AM") to ISO 8601 UTC format.
+ * Returns the original value if parsing fails.
+ */
+/**
+ * Transforms data by renaming each key in `data` exactly once, using the
+ * mapping (`sourceField → targetField`). Keys not present in the mapping
+ * pass through unchanged. The original (pre-rename) key is dropped — the
+ * result contains only the renamed key.
+ *
+ * Each rename is independent. If the mapping happens to contain chained
+ * entries (`a → b` and `b → c`), they do NOT compose: a field named `a`
+ * in `data` becomes `b` (not `c`), because the renames are applied based
+ * on the original data's keys, not the running result.
+ *
+ * @param data The source data to transform
+ * @param fieldMapping Object mapping source field names to target field names
+ * @returns Transformed data with mapped field names
+ *
+ * @example
+ * ```typescript
+ * // Single object transformation
+ * const data = { id: '123', userName: 'john' };
+ * const mapping = { id: 'userId', userName: 'name' };
+ * const result = transformData(data, mapping);
+ * // result = { userId: '123', name: 'john' }
+ *
+ * // Array transformation
+ * const dataArray = [
+ *   { id: '123', userName: 'john' },
+ *   { id: '456', userName: 'jane' }
+ * ];
+ * const result = transformData(dataArray, mapping);
+ * // result = [
+ * //   { userId: '123', name: 'john' },
+ * //   { userId: '456', name: 'jane' }
+ * // ]
+ *
+ * // No chaining — `a → b` does not become `a → c` even if the map has `b → c`.
+ * transformData({ a: 1 }, { a: 'b', b: 'c' });
+ * // result = { b: 1 }
+ * ```
+ */
+function transformData(data, fieldMapping) {
+    // Pass null/undefined through unchanged — callers (e.g. AttachmentService.getById)
+    // may invoke this on optional fields that an OData `select` excluded.
+    if (data == null) {
+        return data;
+    }
+    // Handle array of objects
+    if (Array.isArray(data)) {
+        return data.map(item => transformData(item, fieldMapping));
+    }
+    // Walk the ORIGINAL data's keys, look up each in the mapping. One rename
+    // per data key — no mutation of an in-progress result, so chains can't form.
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const renamedKey = fieldMapping[key] ?? key;
+        result[renamedKey] = value;
+    }
+    return result;
+}
+/**
+ * Adds a prefix to specified keys in an object, returning a new object.
+ * Only the provided keys are prefixed; all others are left unchanged.
+ *
+ * @param obj The source object
+ * @param prefix The prefix to add (e.g., '$')
+ * @param keys The keys to prefix (e.g., ['expand', 'filter'])
+ * @returns A new object with specified keys prefixed
+ *
+ * @example
+ * addPrefixToKeys({ expand: 'a', foo: 1 }, '$', ['expand']) // { $expand: 'a', foo: 1 }
+ */
+function addPrefixToKeys(obj, prefix, keys) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (keys.includes(key)) {
+            result[`${prefix}${key}`] = value;
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+
 /**
  * Base path constants for different services
  */
@@ -87,6 +189,8 @@ const MAESTRO_ENDPOINTS = {
         INSTANCE_STATUS_BY_DATE: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/InstanceStatusByDate`,
         /** Top processes ranked by total duration */
         TOP_PROCESSES_BY_DURATION: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/TopProcessesByDuration`,
+        /** Instance stats (counts by status + duration percentiles) */
+        INSTANCE_COUNT_BY_STATUS: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/InstanceCountByStatus`,
         /** Element count by status for agentic instances (process and case) */
         ELEMENT_COUNT_BY_STATUS: `${INSIGHTS_RTM_BASE}/agenticInstanceStatus/ElementCountByStatus`,
     },
@@ -117,7 +221,26 @@ function createProcessMethods(processData, service) {
                 throw new Error('Process key is undefined');
             if (!processData.packageId)
                 throw new Error('Package ID is undefined');
-            return service.getElementStats(processData.processKey, processData.packageId, startTime, endTime, packageVersion);
+            return service.getElementStats({
+                processKey: processData.processKey,
+                packageId: processData.packageId,
+                packageVersion,
+                startTime,
+                endTime,
+            });
+        },
+        getInstanceStats(startTime, endTime, packageVersion) {
+            if (!processData.processKey)
+                throw new Error('Process key is undefined');
+            if (!processData.packageId)
+                throw new Error('Package ID is undefined');
+            return service.getInstanceStats({
+                processKey: processData.processKey,
+                packageId: processData.packageId,
+                packageVersion,
+                startTime,
+                endTime,
+            });
         }
     };
 }
@@ -180,24 +303,21 @@ async function fetchInstanceStatusTimeline(postFn, startTime, endTime, isCaseMan
     return response.data ?? [];
 }
 /**
- * Builds the request body for the ElementCountByStatus endpoint.
+ * Builds the commonParams request body for Insights RTM endpoints
+ * that filter by process key, package, time range, and version.
  *
- * @param processKey - Process key to filter by
- * @param packageId - Package identifier
- * @param startTime - Start of the time range to query
- * @param endTime - End of the time range to query
- * @param packageVersion - Package version to filter by
- * @returns Request body for the ElementCountByStatus endpoint
+ * @param request - Process scope + time range to aggregate over
+ * @returns Request body with commonParams
  * @internal
  */
-function buildElementCountByStatusBody(processKey, packageId, startTime, endTime, packageVersion) {
+function buildInsightsCommonBody(request) {
     return {
         commonParams: {
-            processKey,
-            packageId,
-            startTime: startTime.getTime(),
-            endTime: endTime.getTime(),
-            version: packageVersion
+            processKey: request.processKey,
+            packageId: request.packageId,
+            startTime: request.startTime.getTime(),
+            endTime: request.endTime.getTime(),
+            version: request.packageVersion
         }
     };
 }
@@ -256,77 +376,6 @@ const PROCESS_INSTANCE_TOKEN_PARAMS = {
     TOKEN_PARAM: 'nextPage'
 };
 
-/**
- * Converts a UTC timestamp string (e.g., "5/8/2026 11:20:17 AM") to ISO 8601 UTC format.
- * Returns the original value if parsing fails.
- */
-/**
- * Transforms data by mapping fields according to the provided field mapping
- * @param data The source data to transform
- * @param fieldMapping Object mapping source field names to target field names
- * @returns Transformed data with mapped field names
- *
- * @example
- * ```typescript
- * // Single object transformation
- * const data = { id: '123', userName: 'john' };
- * const mapping = { id: 'userId', userName: 'name' };
- * const result = transformData(data, mapping);
- * // result = { userId: '123', name: 'john' }
- *
- * // Array transformation
- * const dataArray = [
- *   { id: '123', userName: 'john' },
- *   { id: '456', userName: 'jane' }
- * ];
- * const result = transformData(dataArray, mapping);
- * // result = [
- * //   { userId: '123', name: 'john' },
- * //   { userId: '456', name: 'jane' }
- * // ]
- * ```
- */
-function transformData(data, fieldMapping) {
-    // Handle array of objects
-    if (Array.isArray(data)) {
-        return data.map(item => transformData(item, fieldMapping));
-    }
-    // Handle single object
-    const result = { ...data };
-    for (const [sourceField, targetField] of Object.entries(fieldMapping)) {
-        if (sourceField in result) {
-            const value = result[sourceField];
-            delete result[sourceField];
-            result[targetField] = value;
-        }
-    }
-    return result;
-}
-/**
- * Adds a prefix to specified keys in an object, returning a new object.
- * Only the provided keys are prefixed; all others are left unchanged.
- *
- * @param obj The source object
- * @param prefix The prefix to add (e.g., '$')
- * @param keys The keys to prefix (e.g., ['expand', 'filter'])
- * @returns A new object with specified keys prefixed
- *
- * @example
- * addPrefixToKeys({ expand: 'a', foo: 1 }, '$', ['expand']) // { $expand: 'a', foo: 1 }
- */
-function addPrefixToKeys(obj, prefix, keys) {
-    const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-        if (keys.includes(key)) {
-            result[`${prefix}${key}`] = value;
-        }
-        else {
-            result[key] = value;
-        }
-    }
-    return result;
-}
-
 /**
  * Maps fields for Incident entities
  */
@@ -2822,22 +2871,22 @@ class MaestroProcessesService extends BaseService {
      * Returns per-element execution counts (success, fail, terminated, paused, in-progress) and
      * duration percentile metrics (min, max, avg, p50, p95, p99) for BPMN elements within a process.
      *
-     * @param processKey - Process key to filter by
-     * @param packageId - Package identifier
-     * @param startTime - Start of the time range to query
-     * @param endTime - End of the time range to query
-     * @param packageVersion - Package version to filter by
+     * @param request - Process scope + time range to aggregate over
      * @returns Promise resolving to an array of {@link ElementStats}
      * @example
      * ```typescript
-     * // Get element metrics for a process
-     * const elements = await maestroProcesses.getElementStats(
-     *   '<processKey>',
-     *   '<packageId>',
-     *   new Date('2026-04-01'),
-     *   new Date(),
-     *   '1.0.1'
-     * );
+     * // First, list processes to find the processKey, packageId, and available versions
+     * const processes = await maestroProcesses.getAll();
+     * const process = processes[0];
+     *
+     * // Get element metrics for that process
+     * const elements = await maestroProcesses.getElementStats({
+     *   processKey: process.processKey,
+     *   packageId: process.packageId,
+     *   packageVersion: process.packageVersions[0],
+     *   startTime: new Date('2026-04-01'),
+     *   endTime: new Date(),
+     * });
      *
      * // Analyze element performance
      * for (const element of elements) {
@@ -2845,12 +2894,58 @@ class MaestroProcessesService extends BaseService {
      *   console.log(`  Success: ${element.successCount}, Failed: ${element.failCount}`);
      *   console.log(`  Avg duration: ${element.avgDurationMs}ms, P95: ${element.p95DurationMs}ms`);
      * }
+     *
+     * // Using bound method on a process — auto-fills processKey and packageId
+     * const boundElements = await process.getElementStats(
+     *   new Date('2026-04-01'),
+     *   new Date(),
+     *   process.packageVersions[0]
+     * );
      * ```
      */
-    async getElementStats(processKey, packageId, startTime, endTime, packageVersion) {
-        const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.ELEMENT_COUNT_BY_STATUS, buildElementCountByStatusBody(processKey, packageId, startTime, endTime, packageVersion));
+    async getElementStats(request) {
+        const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.ELEMENT_COUNT_BY_STATUS, buildInsightsCommonBody(request));
         return data ?? [];
     }
+    /**
+     * Get instance stats for a process.
+     *
+     * Returns total instance counts broken down by status (running, completed, faulted, etc.)
+     * and the average execution duration for all instances of a process within a time range.
+     *
+     * @param request - Process scope + time range to aggregate over
+     * @returns Promise resolving to {@link InstanceStats}
+     * @example
+     * ```typescript
+     * // First, list processes to find the processKey, packageId, and available versions
+     * const processes = await maestroProcesses.getAll();
+     * const process = processes[0];
+     *
+     * // Get instance status breakdown for that process
+     * const counts = await maestroProcesses.getInstanceStats({
+     *   processKey: process.processKey,
+     *   packageId: process.packageId,
+     *   packageVersion: process.packageVersions[0],
+     *   startTime: new Date('2026-04-01'),
+     *   endTime: new Date(),
+     * });
+     *
+     * console.log(`Total: ${counts.totalCount}`);
+     * console.log(`Running: ${counts.runningCount}, Completed: ${counts.completedCount}`);
+     * console.log(`Faulted: ${counts.faultedCount}, Avg duration: ${counts.avgDurationMs}ms`);
+     *
+     * // Using bound method on a process — auto-fills processKey and packageId
+     * const boundCounts = await process.getInstanceStats(
+     *   new Date('2026-04-01'),
+     *   new Date(),
+     *   process.packageVersions[0]
+     * );
+     * ```
+     */
+    async getInstanceStats(request) {
+        const { data } = await this.post(MAESTRO_ENDPOINTS.INSIGHTS.INSTANCE_COUNT_BY_STATUS, buildInsightsCommonBody(request));
+        return transformData(data, InstanceStatsMap);
+    }
 }
 __decorate([
     track('MaestroProcesses.GetAll')
@@ -2876,6 +2971,9 @@ __decorate([
 __decorate([
     track('MaestroProcesses.GetElementStats')
 ], MaestroProcessesService.prototype, "getElementStats", null);
+__decorate([
+    track('MaestroProcesses.GetInstanceStats')
+], MaestroProcessesService.prototype, "getInstanceStats", null);
 
 /**
  * Service class for Maestro Process Incidents

package/dist/processes/index.cjs

@@ -956,7 +956,16 @@ const BUCKET_TOKEN_PARAMS = {
  * Returns the original value if parsing fails.
  */
 /**
- * Transforms data by mapping fields according to the provided field mapping
+ * Transforms data by renaming each key in `data` exactly once, using the
+ * mapping (`sourceField → targetField`). Keys not present in the mapping
+ * pass through unchanged. The original (pre-rename) key is dropped — the
+ * result contains only the renamed key.
+ *
+ * Each rename is independent. If the mapping happens to contain chained
+ * entries (`a → b` and `b → c`), they do NOT compose: a field named `a`
+ * in `data` becomes `b` (not `c`), because the renames are applied based
+ * on the original data's keys, not the running result.
+ *
  * @param data The source data to transform
  * @param fieldMapping Object mapping source field names to target field names
  * @returns Transformed data with mapped field names
@@ -979,21 +988,28 @@ const BUCKET_TOKEN_PARAMS = {
  * //   { userId: '123', name: 'john' },
  * //   { userId: '456', name: 'jane' }
  * // ]
+ *
+ * // No chaining — `a → b` does not become `a → c` even if the map has `b → c`.
+ * transformData({ a: 1 }, { a: 'b', b: 'c' });
+ * // result = { b: 1 }
  * ```
  */
 function transformData(data, fieldMapping) {
+    // Pass null/undefined through unchanged — callers (e.g. AttachmentService.getById)
+    // may invoke this on optional fields that an OData `select` excluded.
+    if (data == null) {
+        return data;
+    }
     // Handle array of objects
     if (Array.isArray(data)) {
         return data.map(item => transformData(item, fieldMapping));
     }
-    // Handle single object
-    const result = { ...data };
-    for (const [sourceField, targetField] of Object.entries(fieldMapping)) {
-        if (sourceField in result) {
-            const value = result[sourceField];
-            delete result[sourceField];
-            result[targetField] = value;
-        }
+    // Walk the ORIGINAL data's keys, look up each in the mapping. One rename
+    // per data key — no mutation of an in-progress result, so chains can't form.
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const renamedKey = fieldMapping[key] ?? key;
+        result[renamedKey] = value;
     }
     return result;
 }

package/dist/processes/index.d.ts

@@ -312,7 +312,10 @@ declare enum JobState {
     Successful = "Successful",
     Stopped = "Stopped",
     Suspended = "Suspended",
-    Resumed = "Resumed"
+    Resumed = "Resumed",
+    Cancelled = "Cancelled",
+    /** Server-side fallback for an unrecognized or missing job state. */
+    Unknown = "Unknown"
 }
 interface BaseOptions {
     expand?: string;
@@ -670,6 +673,8 @@ interface ProcessStartResponse extends ProcessProperties, FolderProperties {
     createdTime: string;
     startingScheduleId: number | null;
     processName: string;
+    /** Key of the process this job was started from. */
+    processKey: string;
     type: JobType;
     inputFile: string | null;
     outputArguments: string | null;

package/dist/processes/index.mjs

@@ -954,7 +954,16 @@ const BUCKET_TOKEN_PARAMS = {
  * Returns the original value if parsing fails.
  */
 /**
- * Transforms data by mapping fields according to the provided field mapping
+ * Transforms data by renaming each key in `data` exactly once, using the
+ * mapping (`sourceField → targetField`). Keys not present in the mapping
+ * pass through unchanged. The original (pre-rename) key is dropped — the
+ * result contains only the renamed key.
+ *
+ * Each rename is independent. If the mapping happens to contain chained
+ * entries (`a → b` and `b → c`), they do NOT compose: a field named `a`
+ * in `data` becomes `b` (not `c`), because the renames are applied based
+ * on the original data's keys, not the running result.
+ *
  * @param data The source data to transform
  * @param fieldMapping Object mapping source field names to target field names
  * @returns Transformed data with mapped field names
@@ -977,21 +986,28 @@ const BUCKET_TOKEN_PARAMS = {
  * //   { userId: '123', name: 'john' },
  * //   { userId: '456', name: 'jane' }
  * // ]
+ *
+ * // No chaining — `a → b` does not become `a → c` even if the map has `b → c`.
+ * transformData({ a: 1 }, { a: 'b', b: 'c' });
+ * // result = { b: 1 }
  * ```
  */
 function transformData(data, fieldMapping) {
+    // Pass null/undefined through unchanged — callers (e.g. AttachmentService.getById)
+    // may invoke this on optional fields that an OData `select` excluded.
+    if (data == null) {
+        return data;
+    }
     // Handle array of objects
     if (Array.isArray(data)) {
         return data.map(item => transformData(item, fieldMapping));
     }
-    // Handle single object
-    const result = { ...data };
-    for (const [sourceField, targetField] of Object.entries(fieldMapping)) {
-        if (sourceField in result) {
-            const value = result[sourceField];
-            delete result[sourceField];
-            result[targetField] = value;
-        }
+    // Walk the ORIGINAL data's keys, look up each in the mapping. One rename
+    // per data key — no mutation of an in-progress result, so chains can't form.
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const renamedKey = fieldMapping[key] ?? key;
+        result[renamedKey] = value;
     }
     return result;
 }

package/dist/queues/index.cjs

@@ -956,7 +956,16 @@ const BUCKET_TOKEN_PARAMS = {
  * Returns the original value if parsing fails.
  */
 /**
- * Transforms data by mapping fields according to the provided field mapping
+ * Transforms data by renaming each key in `data` exactly once, using the
+ * mapping (`sourceField → targetField`). Keys not present in the mapping
+ * pass through unchanged. The original (pre-rename) key is dropped — the
+ * result contains only the renamed key.
+ *
+ * Each rename is independent. If the mapping happens to contain chained
+ * entries (`a → b` and `b → c`), they do NOT compose: a field named `a`
+ * in `data` becomes `b` (not `c`), because the renames are applied based
+ * on the original data's keys, not the running result.
+ *
  * @param data The source data to transform
  * @param fieldMapping Object mapping source field names to target field names
  * @returns Transformed data with mapped field names
@@ -979,21 +988,28 @@ const BUCKET_TOKEN_PARAMS = {
  * //   { userId: '123', name: 'john' },
  * //   { userId: '456', name: 'jane' }
  * // ]
+ *
+ * // No chaining — `a → b` does not become `a → c` even if the map has `b → c`.
+ * transformData({ a: 1 }, { a: 'b', b: 'c' });
+ * // result = { b: 1 }
  * ```
  */
 function transformData(data, fieldMapping) {
+    // Pass null/undefined through unchanged — callers (e.g. AttachmentService.getById)
+    // may invoke this on optional fields that an OData `select` excluded.
+    if (data == null) {
+        return data;
+    }
     // Handle array of objects
     if (Array.isArray(data)) {
         return data.map(item => transformData(item, fieldMapping));
     }
-    // Handle single object
-    const result = { ...data };
-    for (const [sourceField, targetField] of Object.entries(fieldMapping)) {
-        if (sourceField in result) {
-            const value = result[sourceField];
-            delete result[sourceField];
-            result[targetField] = value;
-        }
+    // Walk the ORIGINAL data's keys, look up each in the mapping. One rename
+    // per data key — no mutation of an in-progress result, so chains can't form.
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const renamedKey = fieldMapping[key] ?? key;
+        result[renamedKey] = value;
     }
     return result;
 }

package/dist/queues/index.mjs

@@ -954,7 +954,16 @@ const BUCKET_TOKEN_PARAMS = {
  * Returns the original value if parsing fails.
  */
 /**
- * Transforms data by mapping fields according to the provided field mapping
+ * Transforms data by renaming each key in `data` exactly once, using the
+ * mapping (`sourceField → targetField`). Keys not present in the mapping
+ * pass through unchanged. The original (pre-rename) key is dropped — the
+ * result contains only the renamed key.
+ *
+ * Each rename is independent. If the mapping happens to contain chained
+ * entries (`a → b` and `b → c`), they do NOT compose: a field named `a`
+ * in `data` becomes `b` (not `c`), because the renames are applied based
+ * on the original data's keys, not the running result.
+ *
  * @param data The source data to transform
  * @param fieldMapping Object mapping source field names to target field names
  * @returns Transformed data with mapped field names
@@ -977,21 +986,28 @@ const BUCKET_TOKEN_PARAMS = {
  * //   { userId: '123', name: 'john' },
  * //   { userId: '456', name: 'jane' }
  * // ]
+ *
+ * // No chaining — `a → b` does not become `a → c` even if the map has `b → c`.
+ * transformData({ a: 1 }, { a: 'b', b: 'c' });
+ * // result = { b: 1 }
  * ```
  */
 function transformData(data, fieldMapping) {
+    // Pass null/undefined through unchanged — callers (e.g. AttachmentService.getById)
+    // may invoke this on optional fields that an OData `select` excluded.
+    if (data == null) {
+        return data;
+    }
     // Handle array of objects
     if (Array.isArray(data)) {
         return data.map(item => transformData(item, fieldMapping));
     }
-    // Handle single object
-    const result = { ...data };
-    for (const [sourceField, targetField] of Object.entries(fieldMapping)) {
-        if (sourceField in result) {
-            const value = result[sourceField];
-            delete result[sourceField];
-            result[targetField] = value;
-        }
+    // Walk the ORIGINAL data's keys, look up each in the mapping. One rename
+    // per data key — no mutation of an in-progress result, so chains can't form.
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const renamedKey = fieldMapping[key] ?? key;
+        result[renamedKey] = value;
     }
     return result;
 }

package/dist/tasks/index.cjs

@@ -715,7 +715,16 @@ var PaginationType;
  * Returns the original value if parsing fails.
  */
 /**
- * Transforms data by mapping fields according to the provided field mapping
+ * Transforms data by renaming each key in `data` exactly once, using the
+ * mapping (`sourceField → targetField`). Keys not present in the mapping
+ * pass through unchanged. The original (pre-rename) key is dropped — the
+ * result contains only the renamed key.
+ *
+ * Each rename is independent. If the mapping happens to contain chained
+ * entries (`a → b` and `b → c`), they do NOT compose: a field named `a`
+ * in `data` becomes `b` (not `c`), because the renames are applied based
+ * on the original data's keys, not the running result.
+ *
  * @param data The source data to transform
  * @param fieldMapping Object mapping source field names to target field names
  * @returns Transformed data with mapped field names
@@ -738,21 +747,28 @@ var PaginationType;
  * //   { userId: '123', name: 'john' },
  * //   { userId: '456', name: 'jane' }
  * // ]
+ *
+ * // No chaining — `a → b` does not become `a → c` even if the map has `b → c`.
+ * transformData({ a: 1 }, { a: 'b', b: 'c' });
+ * // result = { b: 1 }
  * ```
  */
 function transformData(data, fieldMapping) {
+    // Pass null/undefined through unchanged — callers (e.g. AttachmentService.getById)
+    // may invoke this on optional fields that an OData `select` excluded.
+    if (data == null) {
+        return data;
+    }
     // Handle array of objects
     if (Array.isArray(data)) {
         return data.map(item => transformData(item, fieldMapping));
     }
-    // Handle single object
-    const result = { ...data };
-    for (const [sourceField, targetField] of Object.entries(fieldMapping)) {
-        if (sourceField in result) {
-            const value = result[sourceField];
-            delete result[sourceField];
-            result[targetField] = value;
-        }
+    // Walk the ORIGINAL data's keys, look up each in the mapping. One rename
+    // per data key — no mutation of an in-progress result, so chains can't form.
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const renamedKey = fieldMapping[key] ?? key;
+        result[renamedKey] = value;
     }
     return result;
 }