feat(integration-service): add Execution passthrough

[maninder-uipath]

Summary

PR 4/4 of the Integration Service stack. Adds the Execution passthrough.

• execute() via @uipath/uipath-typescript/is-execution — runs an arbitrary HTTP operation against a connection instance and returns the full response envelope without throwing on non-2xx
• Reuses ELEMENT_ENDPOINTS.INSTANCE.EXECUTE
• Unit tests, OAuth scope docs

Stack

• Base: feat/is-elements — merge the lower PRs first; GitHub will retarget this to main.

🤖 Generated with Claude Code

[claude]

Convention violation: Execution must extend BaseService.

The project convention states: "Services follow the pattern: extend BaseService, call super(uiPath), use this.get() / this.post() etc." Every other HTTP service class in the repo extends BaseService — Execution is the sole exception.

The current implementation accesses SDKInternalsRegistry.get() directly to obtain both the tokenManager and config. If the class extended BaseService, it could use the already-available protected getValidAuthToken() for the token. The only remaining dependency is config.baseUrl/orgName/tenantName for URL construction, which can be captured in the constructor after super():

Suggested change

	class Execution {
	class Execution extends BaseService {
	private readonly execConfig: { baseUrl: string; orgName: string; tenantName: string };
	constructor(instance: IUiPath) {
	super(instance);
	const { config } = SDKInternalsRegistry.get(instance);
	this.execConfig = config;
	}

Then replace tokenManager.getValidToken() on line 37 with this.getValidAuthToken(), and swap config.* references to this.execConfig.*. This keeps the direct registry access scoped to the config-only concern, and routes token management through the standard base-class path.

[claude]

Missing distributed-tracing headers.

ApiClient.request() generates a traceparent / x-uipath-traceparent-id header pair on every request using crypto.randomUUID(). By using raw fetch(), execute() is invisible to the platform's distributed-tracing infrastructure — a significant observability blind-spot given this is a passthrough that proxies calls into third-party connectors.

Add the trace headers alongside Authorization:

Suggested change

	const headers: Record<string, string> = {
	Authorization: `Bearer ${token}`,
	};
	const traceId = crypto.randomUUID().replace(/-/g, '');
	const spanId = crypto.randomUUID().replace(/-/g, '').slice(0, 16);
	const traceparentValue = `00-${traceId}-${spanId}-01`;
	const headers: Record<string, string> = {
	Authorization: `Bearer ${token}`,
	[TRACEPARENT]: traceparentValue,
	[UIPATH_TRACEPARENT_ID]: traceparentValue,
	};

TRACEPARENT and UIPATH_TRACEPARENT_ID are already exported from src/utils/constants/headers.ts.

[claude]

Rule violation: as unknown as cast is prohibited.

The project rule is explicit: "NEVER use as unknown as type casts." This cast exists because TokenManager's public interface doesn't include getValidToken in the MockableTokenManager shape defined in tests/utils/setup.ts, so the test works around the type by force-casting.

The root cause is that Execution bypasses BaseService and calls tokenManager.getValidToken() directly (see the service-level comment). Once Execution extends BaseService and uses this.getValidAuthToken(), the token flows through the mock ApiClient — which already has getValidToken: vi.fn().mockResolvedValue(...) in createMockApiClient() — and this entire buildDeps() workaround disappears.

[claude]

Review findings

Three issues found across the new is-execution module:

New inline comments posted

1. execution.ts:19 — Execution doesn't extend BaseService
   Convention violation: every HTTP service must extend BaseService. Fix: extend it in the constructor, capture config from the registry for URL building, and replace the direct tokenManager.getValidToken() call with this.getValidAuthToken().

2. execution.ts:50-52 — Missing distributed-tracing headers
   Raw fetch() omits the traceparent / x-uipath-traceparent-id headers that ApiClient adds to every request. execute() calls are invisible to the platform's tracing infrastructure as a result.

3. execution.test.ts:16-18 — as unknown as cast in test setup
   Prohibited by project rules. This is a downstream symptom of issue 1 — once Execution extends BaseService and routes token access through ApiClient, the cast and the buildDeps() workaround are no longer needed.