feat(orchestrator): getByName for Assets + Processes, encoded folder header, meta-tag fallback [PLT-92768]

[deepeshrai-tech]

Summary

Prerequisite SDK work for the coded-apps bindings/overwrites initiative (PLT-92768 / PLT-93599). Adds name-based resource lookup for two Orchestrator services and wires the folder-context plumbing that the runtime overwrite flow depends on.

• assets.getByName(name, { folderPath?, folderKey? }) — OData $filter=Name eq '…' + $top=1 on the folder-scoped endpoint.
• processes.getByName(name, { folderPath?, folderKey? }) — same shape against /odata/Releases.
• X-UIPATH-FolderPath-Encoded replaces the raw X-UIPATH-FolderPath header (OR team's recommendation; URL-encoded transport is safer for special characters in paths). Both folderPath and folderKey are accepted simultaneously — OR's middleware prefers folderPath.
• Init-time folder context via meta tags. The SDK now reads <meta name="uipath:folder-key"> (auto-injected by jamjam on coded-app deployments) and uses it as the default folder context when the caller doesn't pass one. Resolution chain: call-site args > new UiPath({ folderKey }) > meta tag > no folder header.
• Input validation + better not-found errors. New utils/validation/name-validator.ts throws ValidationError with descriptive messages for non-string names, empty names, and non-string folder fields — the guard TS types can't enforce for JS callers. Not-found errors now include the folder context (path or key) to make debugging easier

Usage

import { Assets } from '@uipath/uipath-typescript/assets';
import { Processes } from '@uipath/uipath-typescript/processes';

const assets = new Assets(sdk);
const processes = new Processes(sdk);

// Call-site wins
const a = await assets.getByName('ApiKey', { folderPath: 'Shared/Finance' });
const b = await assets.getByName('ApiKey', { folderKey: 'bc2d…' });

// Folder resolved from <meta name="uipath:folder-key"> 
const c = await assets.getByName('ApiKey');

// Same semantics for processes
const p = await processes.getByName('MyProcess', { folderPath: 'Shared/Finance' });

Not-done / follow-ups

• Unit + integration tests for getByName (this PR is a draft for visual verification first)
• docs/oauth-scopes.md update
• Same getByName on Buckets / Queues — tracked separately

Screen.Recording.2026-04-21.at.5.57.59.PM.mov

[claude]

The "Mutually exclusive" wording conflicts with the implementation and the PR description.

The PR description says: "Both folderPath and folderKey are accepted; Orchestrator middleware prefers folderPath when both are sent, so the SDK passes them straight through." The getByName implementation confirms this — it calls createHeaders({ [FOLDER_PATH]: folderPath, [FOLDER_KEY]: folderKey }) and sends whatever is non-undefined.

Calling them mutually exclusive tells users one of them will be ignored or that passing both is invalid, when it's actually valid (and the server's preference behaviour is the documented tie-breaker).

Suggested replacement:

Suggested change

	/**
	* Folder path to scope the asset lookup (e.g. 'Shared/Finance').
	* Mutually exclusive with folderKey.
	*/
	folderPath?: string;
	/**
	* Folder key (GUID) to scope the asset lookup.
	* Mutually exclusive with folderPath.
	*/
	folderKey?: string;
	export interface AssetGetByNameOptions extends BaseOptions {
	/**
	* Folder path to scope the asset lookup (e.g. 'Shared/Finance').
	* Sent as the `X-UIPATH-FolderPath` header. When provided alongside
	* `folderKey`, the server prefers `folderPath`.
	*/
	folderPath?: string;
	/**
	* Folder key (GUID) to scope the asset lookup.
	* Sent as the `X-UIPATH-FolderKey` header. When provided alongside
	* `folderPath`, the server prefers `folderPath`.
	*/
	folderKey?: string;
	}

[claude]

Per the post-implementation checklist in agent_docs/rules.md, every public method requires unit tests (success + error paths) and an integration test in tests/integration/shared/orchestrator/ before merging.

The "Not-done list" in the PR description calls these out explicitly — flagging here so this doesn't slip through on merge. Minimum needed:

Unit tests (tests/unit/services/orchestrator/assets.test.ts):

• getByName returns a transformed asset when the OData response has one item
• getByName throws NotFoundError when the value array is empty
• getByName sends X-UIPATH-FolderPath / X-UIPATH-FolderKey headers (only those provided)
• getByName OData-escapes single quotes in the name (Name eq 'O''Brien')

Integration test (tests/integration/shared/orchestrator/assets.test.ts):

• getByName resolves an existing asset by name + folderPath
• transform validation: camelCase fields present, PascalCase originals absent

[claude]

as unknown as string is explicitly banned by conventions.md ("NEVER use as unknown as type casts — refactor to make types flow naturally"). Sample apps are part of the repo and set the example for SDK consumers.

asset.valueType is AssetValueType (a string enum), so it already is a string at runtime. The fix is to widen the AssetRow.valueType field type to AssetValueType (preferred, preserves autocomplete) or cast with the direct widening asset.valueType as string which TypeScript allows between a string enum and string without the double cast:

Suggested change

	valueType: asset.valueType as unknown as string,
	valueType: asset.valueType,

and change AssetRow.valueType from string to AssetValueType.

[claude]

Review summary — 3 new findings

1. Doc inaccuracy in AssetGetByNameOptions (assets.types.ts L76–85)
The JSDoc calls folderPath and folderKey mutually exclusive, but both headers are forwarded and the server simply prefers folderPath when both are present. Suggested fix is in the inline comment.

2. Missing unit and integration tests (assets.ts L147)
Required by the checklist before merging. Inline comment lists the specific cases: empty-result NotFoundError path, header forwarding, OData quote-escaping, and transform validation.

3. Banned double cast in sample code (AssetList.tsx L76)
Conventions prohibit this pattern. Since AssetValueType is a string enum, changing AssetRow.valueType to AssetValueType removes the need for any cast.

[sonarqubecloud]

Quality Gate failed

Failed conditions
10.8% Duplication on New Code (required ≤ 3%)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE