fix: rewrite SDK field names in OData filter/orderby/select/expand [PLT-102084] (#536)

* fix: rewrite SDK field names in OData filter/orderby/select/expand

Field maps applied SDK-side renames on responses only, so consumers had
to remember two names per field: the SDK name for reading the response
and the API name for filter/orderby/select/expand. Filtering by the SDK
name was silently forwarded to the API and rejected.

Add a token-aware rewriter that walks OData expressions, preserves
quoted string literals, and rewrites identifier tokens via the reversed
`{Entity}Map`. Wire it into `PaginationHelpers.getAll` and into the
direct `addPrefixToKeys` sites used by `getById` / `getByName` /
`processes.start` / bucket read-write URIs across Jobs, Queues, Assets,
Buckets, Processes, Attachments, and Tasks.

Refs: PLT-102084

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: address convention review comments

- Replace `as any` mock-resolved values with typed factory helpers
  (createMockTasks, createMockBuckets, createMockOrchestratorProcesses)
- Remove unused rewriteODataIdentifiers entry from transform mock —
  only rewriteODataRequestFields is reached through service paths
- Type rewriteODataIdentifiers requestMap as FieldMapping for
  consistency with the rest of transform.ts

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor: narrow PR scope to Jobs; rename helper to transformOptions

Per discussion, scoping this PR to a single service (Jobs) so reviewers
can evaluate the approach in isolation. Other affected services
(Queues, Assets, Buckets, Processes, Attachments, Tasks) will be picked
up in follow-up PRs that reuse the same plumbing introduced here.

Also renames the public helper rewriteODataRequestFields → transformOptions
to mirror the existing transformRequest naming. transformRequest is for
request bodies (object keys), transformOptions is for OData query options
(strings with embedded identifiers); same reversed-map mechanism under
the hood.

Behavior change: none beyond what's already shipping for Jobs.

* refactor: simplify rewriteODataIdentifiers with regex alternation

Replace the ~30-line char-by-char state machine with a 4-line
String.prototype.replace using a regex that alternates between
single-quoted literals (with '' escape) and OData identifiers.

The regex engine handles both states for free via alternation and
greedy identifier matching:
  '(?:[^']|'')*'      atomic quoted literal (identifiers inside don't
                      get a separate match)
  [A-Za-z_][A-Za-z0-9_]*  full identifier token (no substring collisions)

All 17 transform.test.ts cases pass unchanged — same invariants
(literal-atomicity, full-token matching, empty-map no-op).

* refactor: call transformOptions in service layer for symmetry with transformRequest

Removes the fieldMap config option from PaginationHelpers / GetAllConfig
and moves the transformOptions call into JobService.getAll, mirroring
the existing pattern where services call transformRequest directly on
request bodies before delegating to the HTTP/pagination layer.

Benefits:
- PaginationHelpers stays generic — no service-specific concept like
  "field map" in the shared helper.
- One convention across the SDK: services own request-side translation,
  whether the data is a body (transformRequest) or OData query options
  (transformOptions). The helpers layer plumbs only.
- Unit test asserts the post-translation shape directly (filter contains
  releaseName, not processName) rather than asserting a wiring detail.

No behavior change.

* fix(tests): address claude bot review comments

- Rename misleading operator-collision test: the assertion proves the
  rewriter DOES rewrite operator-named map keys, so the test name must
  not say "does not rewrite operators".
- Drop the `null as unknown as string` cast — `transformOptions`'s
  generic accepts the wider type directly.

* fix: drop redundant `as T` cast on transformOptions return

transformOptions's generic signature `<T extends Record<string, any>>(options: T, ...): T`
already returns T; the explicit cast was redundant.

* fix(jobs): address PR review feedback

- Consolidate JSDoc filter example: drop the unrelated `state eq 'Running'`
  case and the verbose "SDK field names" preamble; keep a single example
  demonstrating filter + orderby with the renamed processName and createdTime.
- Simplify getById's option-prep into a single `apiFieldOptions` chain:
  transformOptions → addPrefixToKeys in two lines, no intermediate
  `rewrittenOptions` / `keysToPrefix` variables.
- Add an integration test that exercises SDK-renamed fields end-to-end:
  `orderby: 'createdTime desc'` and `select: 'key,processName,state,createdTime'`.
  The Orchestrator API would 400 on either of those without the rewriter,
  so this test fails if the rewrite pipeline regresses.

* refactor: remove chained renames from transformData

The previous implementation iterated the fieldMapping entries and mutated
`result` in place — which meant a map with both `a → b` and `b → c` would
chain through both renames whenever the input had `a`, producing `c`
instead of `b`. ProcessMap's `releaseKey → processKey` + `processKey →
packageKey` entries are the canonical example; the chain was a latent
quirk waiting to misbehave on a response that contained both keys.

The new implementation walks `Object.entries(data)` and looks each key up
in the mapping exactly once. Renames are independent — `a → b` does not
compose with `b → c` because the result is built fresh and never re-read
inside the loop. The original key is dropped (no source + target
coexistence in the result).

Side effects:
- Strictly cheaper: O(D) iterations with no upfront shallow copy and no
  `delete` calls. The previous code was O(D + M) plus V8 hidden-class
  transitions on every delete.
- Output key order now matches the input's iteration order, which is
  slightly more predictable.
- All 1898 pre-existing unit tests still pass — no test mock contained
  both ends of a ProcessMap chain, so the chained behaviour was never
  actually exercised. The removal is observably a no-op for existing
  inputs.

7 new tests pin the no-chain contract:
  - basic rename
  - passthrough of unmapped keys
  - original key dropped (no source + target coexistence)
  - no chaining (`a → b → c` map produces `b`, not `c`)
  - both ends of a chain present in input produce independent renames
  - array recursion
  - empty input

* feat(processes): expose processKey on ProcessStartResponse

The Orchestrator start endpoint returns the originating process's
ReleaseKey alongside the job's own Key. With the no-chaining
transformData, ProcessMap's `releaseKey → processKey` entry now
delivers that as `processKey` on the response without accidentally
re-renaming it to `packageKey` (which the old chained transform did).

Adding the typed field surfaces it on the public response. No
behaviour change at runtime — the field was already being populated
by the rename pipeline; it just wasn't declared on the type.

* docs(processes): trim processKey JSDoc

* fix(transform): handle null/undefined input in transformData

The previous chained implementation tolerated null/undefined via the
shallow spread (`{ ...null }` is `{}`). The refactored implementation
called `Object.entries(data)` which throws `TypeError: Cannot convert
undefined or null to object`.

The CI integration test `attachments.integration.test.ts` exposed this:
`AttachmentService.getById` calls `transformData(camelCased.blobFileAccess,
BucketMap)`, and when an OData `select` excludes `blobFileAccess`, the
field arrives undefined. The old code returned `{}` silently; the new
code threw.

Restore null/undefined tolerance with an early return that passes the
value through unchanged. Add two unit tests pinning the behaviour.

* refactor(transform): tighten transformOptions per review comments

- Drop the `any` from the generic constraint. Switch to
  `T extends object` (matching `transformRequest`'s pattern) and cast
  the spread destination to `Record<string, unknown>` so we keep one
  named cast instead of leaking `any` through the signature and the
  internal result type.
- Remove the `!options || !responseMap` runtime guard. Both parameters
  are non-optional in the type contract, and the two current call sites
  in jobs.ts already guard `options?` before invoking. Per
  conventions.md: don't add validation for scenarios that can't happen.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ninja-shreyash

src/models/orchestrator/jobs.models.ts

@@ -42,8 +42,9 @@ export interface JobServiceModel {
    * const folderJobs = await jobs.getAll({ folderId: <folderId> });
    *
    * // With filtering
-   * const runningJobs = await jobs.getAll({
-   *   filter: "state eq 'Running'"
+   * const recentInvoiceJobs = await jobs.getAll({
+   *   filter: "processName eq 'InvoiceBot'",
+   *   orderby: 'createdTime desc',
    * });
    *
    * // First page with pagination

src/models/orchestrator/processes.types.ts

@@ -305,9 +305,11 @@ export interface ProcessStartResponse extends ProcessProperties, FolderPropertie
   sourceType: JobSourceType;
   batchExecutionKey: string;
   info: string | null;
-  createdTime: string; 
+  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;

src/services/orchestrator/jobs/jobs.ts

@@ -1,7 +1,7 @@
 import { FolderScopedService } from '../../folder-scoped';
 import { RawJobGetResponse, JobGetAllOptions, JobGetByIdOptions, JobStopOptions, JobResumeOptions } from '../../../models/orchestrator/jobs.types';
 import { JobServiceModel, JobGetResponse, createJobWithMethods } from '../../../models/orchestrator/jobs.models';
-import { addPrefixToKeys, pascalToCamelCaseKeys, transformData } from '../../../utils/transform';
+import { addPrefixToKeys, pascalToCamelCaseKeys, transformOptions, transformData } from '../../../utils/transform';
 import { JOB_ENDPOINTS } from '../../../utils/constants/endpoints';
 import { ODATA_PAGINATION, ODATA_OFFSET_PARAMS, ODATA_PREFIX } from '../../../utils/constants/common';
 import { JobMap, JOB_KEY_RESOLUTION_CHUNK_SIZE } from '../../../models/orchestrator/jobs.constants';
@@ -55,8 +55,9 @@ export class JobService extends FolderScopedService implements JobServiceModel {
    * const folderJobs = await jobs.getAll({ folderId: <folderId> });
    *
    * // With filtering
-   * const runningJobs = await jobs.getAll({
-   *   filter: "state eq 'Running'"
+   * const recentInvoiceJobs = await jobs.getAll({
+   *   filter: "processName eq 'InvoiceBot'",
+   *   orderby: 'createdTime desc',
    * });
    *
    * // First page with pagination
@@ -87,6 +88,11 @@ export class JobService extends FolderScopedService implements JobServiceModel {
       return createJobWithMethods(rawJob, this);
     };
 
+    // Rewrite renamed SDK field names → API names inside OData strings
+    // before delegating, mirroring the transformRequest pattern used for
+    // request bodies.
+    const apiOptions = options ? transformOptions(options, JobMap) : options;
+
     return PaginationHelpers.getAll({
       serviceAccess: this.createPaginationServiceAccess(),
       getEndpoint: () => JOB_ENDPOINTS.GET_ALL,
@@ -102,7 +108,7 @@ export class JobService extends FolderScopedService implements JobServiceModel {
           countParam: ODATA_OFFSET_PARAMS.COUNT_PARAM,
         },
       },
-    }, options) as any;
+    }, apiOptions) as any;
   }
 
   /**
@@ -142,8 +148,8 @@ export class JobService extends FolderScopedService implements JobServiceModel {
     }
 
     const headers = createHeaders({ [FOLDER_ID]: folderId });
-    const keysToPrefix = Object.keys(options ?? {});
-    const apiOptions = options ? addPrefixToKeys(options, ODATA_PREFIX, keysToPrefix) : {};
+    const apiFieldOptions = options ? transformOptions(options, JobMap) : {};
+    const apiOptions = addPrefixToKeys(apiFieldOptions, ODATA_PREFIX, Object.keys(apiFieldOptions));
 
     const response = await this.get<Record<string, unknown>>(
       JOB_ENDPOINTS.GET_BY_KEY(id),

src/utils/transform.ts

@@ -16,19 +16,28 @@ export type FieldMapping = {
 };
 
 /**
- * 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
- * 
+ *
  * @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' },
@@ -39,29 +48,35 @@ export type FieldMapping = {
  * //   { 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 }
  * ```
  */
 export function transformData<T extends object>(
   data: T | T[],
   fieldMapping: FieldMapping
 ): T {
+  // 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 as T;
+  }
+
   // Handle array of objects
   if (Array.isArray(data)) {
     return data.map(item => transformData(item, fieldMapping)) as unknown as T;
   }
 
-  // Handle single object
-  const result = { ...data };
-  
-  for (const [sourceField, targetField] of Object.entries(fieldMapping)) {
-    if (sourceField in result) {
-      const value = result[sourceField as keyof T];
-      delete result[sourceField as keyof T];
-      (result as any)[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: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    const renamedKey = fieldMapping[key] ?? key;
+    result[renamedKey] = value;
   }
-
-  return result;
+  return result as T;
 }
 
 /**
@@ -376,6 +391,86 @@ export function transformRequest<T extends object>(
   return result;
 }
 
+/**
+ * OData query-string keys whose values may contain field identifiers that
+ * need rewriting from SDK names → API names.
+ */
+const ODATA_FIELD_PARAM_KEYS = ['filter', 'orderby', 'select', 'expand'] as const;
+
+/**
+ * Matches one token at a time in an OData expression:
+ *   1. A single-quoted string literal, allowing the `''` escape sequence —
+ *      consumed atomically so identifiers inside the literal can't match.
+ *   2. An OData identifier (`[A-Za-z_][A-Za-z0-9_]*`).
+ * Anything else (whitespace, operators, parens, commas) is left alone by
+ * `String.prototype.replace`, which only substitutes matched substrings.
+ */
+const ODATA_TOKEN_RE = /'(?:[^']|'')*'|[A-Za-z_][A-Za-z0-9_]*/g;
+
+/**
+ * Rewrites SDK field identifiers to API field identifiers inside an OData
+ * expression string (`$filter`, `$orderby`, `$select`, `$expand`).
+ *
+ * Field maps (e.g. `JobMap`) rename API fields → SDK fields on responses, so
+ * SDK consumers see the renamed names. Without this rewrite, the same name
+ * in a `filter` string would be forwarded verbatim and the API (which still
+ * uses the original name) would reject it.
+ *
+ * Quoted string literals (with the OData `''` escape) are preserved exactly:
+ * the token regex consumes them whole, so identifiers inside literals never
+ * match. Identifier tokens are looked up in the reversed field map.
+ *
+ * @example
+ * ```typescript
+ * const requestMap = { processName: 'releaseName' };
+ * rewriteODataIdentifiers("processName eq 'processName'", requestMap);
+ * // "releaseName eq 'processName'"  — identifier rewritten, literal preserved
+ * ```
+ */
+export function rewriteODataIdentifiers(expression: string, requestMap: FieldMapping): string {
+  if (!expression) return expression;
+  return expression.replace(ODATA_TOKEN_RE, (match) =>
+    match.startsWith("'") ? match : (requestMap[match] ?? match),
+  );
+}
+
+/**
+ * Symmetric counterpart of {@link transformRequest} for OData query options:
+ * rewrites SDK field identifiers inside the recognized OData string params
+ * (`filter`, `orderby`, `select`, `expand`) to their API names using the
+ * reversed form of a response field map. Returns a shallow copy with the
+ * relevant values rewritten; other keys pass through unchanged.
+ *
+ * Use at the OData edge so SDK consumers can refer to renamed fields by
+ * their SDK name throughout — for reading the response and for filtering /
+ * sorting / projecting / expanding.
+ *
+ * @param options The OData query options as authored with SDK field names
+ * @param responseMap The response field map (API → SDK); reversed internally
+ *
+ * @example
+ * ```typescript
+ * // JobMap renames releaseName → processName on responses.
+ * transformOptions({ filter: "processName eq 'X'" }, JobMap);
+ * // { filter: "releaseName eq 'X'" }
+ * ```
+ */
+export function transformOptions<T extends object>(
+  options: T,
+  responseMap: FieldMapping,
+): T {
+  const requestMap = reverseMap(responseMap);
+  if (Object.keys(requestMap).length === 0) return options;
+  const result: Record<string, unknown> = { ...(options as Record<string, unknown>) };
+  for (const key of ODATA_FIELD_PARAM_KEYS) {
+    const value = result[key];
+    if (typeof value === 'string') {
+      result[key] = rewriteODataIdentifiers(value, requestMap);
+    }
+  }
+  return result as T;
+}
+
 /**
  * Renames fields in an object in-place
  * @param obj The object to modify

tests/integration/shared/orchestrator/jobs.integration.test.ts

@@ -61,6 +61,27 @@ describe.each(modes)('Orchestrator Jobs - Integration Tests [%s]', (mode) => {
       expect(result.items).toBeDefined();
       expect(Array.isArray(result.items)).toBe(true);
     });
+
+    it('should retrieve jobs filtered and sorted by SDK field names', async () => {
+      const { jobs, folderId } = getJobsService();
+
+      // Uses SDK names that the field map renames:
+      //   processName → releaseName, createdTime → creationTime.
+      // If the rewriter doesn't translate these, the API returns 400.
+      const result = await jobs.getAll({
+        folderId,
+        pageSize: 5,
+        orderby: 'createdTime desc',
+        select: 'key,processName,state,createdTime',
+      });
+
+      expect(result).toBeDefined();
+      expect(Array.isArray(result.items)).toBe(true);
+      // Response is also in SDK shape — `createdTime` is the renamed key.
+      if (result.items.length > 0) {
+        expect(result.items[0]).toHaveProperty('createdTime');
+      }
+    });
   });
 
   describe('getById', () => {

tests/unit/services/orchestrator/jobs.test.ts

@@ -158,6 +158,27 @@ describe('JobService Unit Tests', () => {
       await expect(jobService.getAll()).rejects.toThrow(TEST_CONSTANTS.ERROR_MESSAGE);
     });
 
+    it('should translate SDK field names to API names in filter/orderby before delegating', async () => {
+      vi.mocked(PaginationHelpers.getAll).mockResolvedValue(
+        createMockTransformedJobCollection(),
+      );
+
+      await jobService.getAll({
+        filter: "processName eq 'InvoiceBot' and folderId eq 7",
+        orderby: 'createdTime desc',
+      });
+
+      // Options arriving at PaginationHelpers should already be in API field space:
+      // processName → releaseName, folderId → organizationUnitId, createdTime → creationTime.
+      expect(PaginationHelpers.getAll).toHaveBeenCalledWith(
+        expect.any(Object),
+        expect.objectContaining({
+          filter: "releaseName eq 'InvoiceBot' and organizationUnitId eq 7",
+          orderby: 'creationTime desc',
+        }),
+      );
+    });
+
     it('should attach getOutput method to transformed job objects', async () => {
       const mockResponse = createMockTransformedJobCollection();
       vi.mocked(PaginationHelpers.getAll).mockResolvedValue(mockResponse);
@@ -231,6 +252,25 @@ describe('JobService Unit Tests', () => {
       expect(typeof result.stop).toBe('function');
     });
 
+    it('should rewrite SDK field names in select back to API names', async () => {
+      const mockRawJob = createMockRawJob();
+      mockApiClient.get.mockResolvedValueOnce(mockRawJob);
+
+      await jobService.getById(JOB_TEST_CONSTANTS.JOB_KEY, TEST_CONSTANTS.FOLDER_ID, {
+        select: 'processName,createdTime,folderId',
+      });
+
+      // processName → releaseName, createdTime → creationTime, folderId → organizationUnitId
+      expect(mockApiClient.get).toHaveBeenCalledWith(
+        JOB_ENDPOINTS.GET_BY_KEY(JOB_TEST_CONSTANTS.JOB_KEY),
+        expect.objectContaining({
+          params: expect.objectContaining({
+            $select: 'releaseName,creationTime,organizationUnitId',
+          }),
+        }),
+      );
+    });
+
     it('should pass expand and select options with OData prefix', async () => {
       const mockRawJob = createMockRawJob();
       mockApiClient.get.mockResolvedValueOnce(mockRawJob);