@abapify/adt-client 0.4.1 → 0.4.3

package/dist/index.mjs

@@ -1,7 +1,9 @@
 import { exception } from "@abapify/adt-schemas";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Agent, fetch } from "undici";
 import { adtContract, createAdtClient as createAdtClient$1 } from "@abapify/adt-contracts";
-import { mkdirSync, writeFileSync } from "fs";
-import { dirname, join } from "path";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 //#region src/utils/session.ts
 /**
@@ -183,13 +185,17 @@ var ETagManager = class {
 /**
 * Session Manager - Orchestrates cookies and CSRF tokens
 */
-var SessionManager = class {
+var SessionManager = class SessionManager {
+	logger;
+	fetchFn;
+	static SESSION_PATH_PREFIX = "/sap/bc/adt/core/http/sessions/";
 	cookieStore = new CookieStore();
 	csrfManager = new CsrfTokenManager();
 	etagManager = new ETagManager();
 	securitySessionActive = false;
-	constructor(logger) {
+	constructor(logger, fetchFn = globalThis.fetch) {
 		this.logger = logger;
+		this.fetchFn = fetchFn;
 	}
 	/**
 	* Process response to update session state
@@ -266,6 +272,31 @@ var SessionManager = class {
 		this.etagManager.clear(url);
 	}
 	/**
+	* Reject session paths that could send cleanup requests off-target.
+	* Only relative paths under the ADT sessions endpoint (or same-origin
+	* absolute URLs with that path) are accepted.
+	*/
+	isTrustedSessionPath({ baseUrl, sessionPath }) {
+		try {
+			const parsed = new URL(sessionPath, baseUrl);
+			const base = new URL(baseUrl);
+			return parsed.origin === base.origin && parsed.pathname.startsWith(SessionManager.SESSION_PATH_PREFIX);
+		} catch {
+			return false;
+		}
+	}
+	extractTrustedSessionPath({ baseUrl, body }) {
+		const sessionPath = body.match(/href="([^"]*\/sessions\/[^"]*)"/)?.[1];
+		if (!sessionPath || !this.isTrustedSessionPath({
+			baseUrl,
+			sessionPath
+		})) {
+			this.logger?.warn("Session: Created security session returned an untrusted path");
+			return;
+		}
+		return sessionPath;
+	}
+	/**
 	* Initialize CSRF token using the Eclipse ADT security session flow:
 	*
 	* 1. GET /sessions + x-sap-security-session: create  → create security session
@@ -275,86 +306,205 @@ var SessionManager = class {
 	* The CSRF token survives the session deletion and remains valid for
 	* all subsequent lock/unlock operations. Deleting the session frees
 	* the slot — SAP allows only one security session per user.
-	*
-	* @param baseUrl - SAP system base URL
-	* @param authHeader - Authorization header (Basic/Bearer), or undefined for cookie auth
-	* @param client - SAP client number
-	* @param language - SAP language
-	*/
-	async initializeCsrf(baseUrl, authHeader, client, language) {
-		const sessionsUrl = new URL("/sap/bc/adt/core/http/sessions", baseUrl);
-		if (client) sessionsUrl.searchParams.append("sap-client", client);
-		if (language) sessionsUrl.searchParams.append("sap-language", language);
-		/** Build common headers, optionally including Authorization and cookies */
-		const baseHeaders = () => {
-			const h = {
-				Accept: "application/vnd.sap.adt.core.http.session.v3+xml",
-				"X-sap-adt-sessiontype": "stateful"
-			};
-			if (authHeader) h.Authorization = authHeader;
-			const cookie = this.cookieStore.getCookieHeader();
-			if (cookie) h.Cookie = cookie;
-			return h;
+	*/
+	resolveInitializeCsrfArgs(...args) {
+		if (args.length === 1) {
+			const first = args[0];
+			if (first !== null) {
+				if (typeof first === "object") return first;
+			}
+		}
+		return {
+			authHeader: typeof args[0] === "string" ? args[0] : void 0,
+			client: typeof args[1] === "string" ? args[1] : void 0,
+			language: typeof args[2] === "string" ? args[2] : void 0,
+			signal: args[3] instanceof AbortSignal ? args[3] : void 0
 		};
+	}
+	async initializeCsrf(baseUrl, ...args) {
+		const { authHeader, client, language, signal } = this.resolveInitializeCsrfArgs(...args);
+		signal?.throwIfAborted();
+		const sessionsUrl = this.buildSessionsUrl(baseUrl, client, language);
+		let sessionPath;
 		try {
-			this.logger?.debug("Session: Creating security session");
-			const createResponse = await fetch(sessionsUrl.toString(), {
-				method: "GET",
-				headers: {
-					...baseHeaders(),
-					"x-sap-security-session": "create"
-				}
-			});
-			if (!createResponse.ok) {
-				this.logger?.warn(`Session: Security session creation failed with status ${createResponse.status}`);
+			sessionPath = await this.createSecuritySession(baseUrl, sessionsUrl, authHeader, signal);
+			if (!sessionPath) return false;
+			if (!await this.acquireCsrfToken(sessionsUrl, authHeader, signal)) {
+				this.deleteSecuritySessionWithFallback({
+					sessionPath,
+					baseUrl,
+					authHeader,
+					client,
+					language
+				}).catch(() => void 0);
 				return false;
 			}
-			this.processResponse(createResponse);
-			const sessionPath = (await createResponse.text()).match(/href="([^"]*\/sessions\/[^"]*)"/)?.[1];
-			this.logger?.debug("Session: Fetching CSRF token");
-			const csrfResponse = await fetch(sessionsUrl.toString(), {
+			const acquiredCsrfToken = this.csrfManager.getCached();
+			if (acquiredCsrfToken) await this.deleteSecuritySession({
+				sessionPath,
+				csrfToken: acquiredCsrfToken,
+				baseUrl,
+				authHeader,
+				client,
+				signal
+			});
+			signal?.throwIfAborted();
+			return true;
+		} catch (error) {
+			return this.handleCsrfInitializationError(error, {
+				baseUrl,
+				authHeader,
+				client,
+				language,
+				sessionPath,
+				signal
+			});
+		}
+	}
+	buildSessionsUrl(baseUrl, client, language) {
+		const url = new URL("/sap/bc/adt/core/http/sessions", baseUrl);
+		if (client) url.searchParams.append("sap-client", client);
+		if (language) url.searchParams.append("sap-language", language);
+		return url;
+	}
+	buildSessionHeaders(authHeader) {
+		const headers = {
+			Accept: "application/vnd.sap.adt.core.http.session.v3+xml",
+			"X-sap-adt-sessiontype": "stateful"
+		};
+		if (authHeader) headers.Authorization = authHeader;
+		const cookie = this.cookieStore.getCookieHeader();
+		if (cookie) headers.Cookie = cookie;
+		return headers;
+	}
+	async createSecuritySession(baseUrl, sessionsUrl, authHeader, signal) {
+		this.logger?.debug("Session: Creating security session");
+		const response = await this.fetchFn(sessionsUrl, {
+			method: "GET",
+			headers: {
+				...this.buildSessionHeaders(authHeader),
+				"x-sap-security-session": "create"
+			},
+			signal
+		});
+		signal?.throwIfAborted();
+		if (!response.ok) {
+			this.logger?.warn(`Session: Security session creation failed with status ${response.status}`);
+			return;
+		}
+		this.processResponse(response);
+		const body = await response.text();
+		signal?.throwIfAborted();
+		return this.extractTrustedSessionPath({
+			baseUrl,
+			body
+		});
+	}
+	async acquireCsrfToken(sessionsUrl, authHeader, signal) {
+		this.logger?.debug("Session: Fetching CSRF token");
+		const response = await this.fetchFn(sessionsUrl, {
+			method: "GET",
+			headers: {
+				...this.buildSessionHeaders(authHeader),
+				"x-sap-security-session": "use",
+				"x-csrf-token": "Fetch"
+			},
+			signal
+		});
+		signal?.throwIfAborted();
+		if (!response.ok) {
+			this.logger?.warn(`Session: CSRF fetch failed with status ${response.status}`);
+			return false;
+		}
+		this.processResponse(response);
+		if (!this.csrfManager.hasCached()) {
+			this.logger?.warn("Session: CSRF fetch succeeded but no token found in response");
+			return false;
+		}
+		this.securitySessionActive = true;
+		this.logger?.debug("Session: CSRF token acquired");
+		return true;
+	}
+	async deleteSecuritySession({ sessionPath, csrfToken, baseUrl, authHeader, client, signal }) {
+		if (!this.isTrustedSessionPath({
+			baseUrl,
+			sessionPath
+		})) {
+			this.logger?.warn("Session: Refusing to delete security session with untrusted path");
+			return;
+		}
+		const deleteUrl = new URL(sessionPath, baseUrl);
+		if (client) deleteUrl.searchParams.append("sap-client", client);
+		try {
+			this.logger?.debug(`Session: Deleting security session ${sessionPath}`);
+			await this.fetchFn(deleteUrl, {
+				method: "DELETE",
+				headers: {
+					...this.buildSessionHeaders(authHeader),
+					"x-sap-security-session": "use",
+					"x-csrf-token": csrfToken
+				},
+				signal: signal ?? AbortSignal.timeout(5e3)
+			});
+			this.logger?.debug("Session: Security session deleted");
+		} catch {
+			this.logger?.debug("Session: Failed to delete security session (will expire)");
+		}
+	}
+	async fetchSecuritySessionCsrfToken({ baseUrl, authHeader, client, language, signal }) {
+		const sessionsUrl = this.buildSessionsUrl(baseUrl, client, language);
+		try {
+			this.logger?.debug("Session: Fetching CSRF token for security session cleanup");
+			const response = await this.fetchFn(sessionsUrl, {
 				method: "GET",
 				headers: {
-					...baseHeaders(),
+					...this.buildSessionHeaders(authHeader),
 					"x-sap-security-session": "use",
 					"x-csrf-token": "Fetch"
-				}
+				},
+				signal: signal ?? AbortSignal.timeout(5e3)
 			});
-			if (!csrfResponse.ok) {
-				this.logger?.warn(`Session: CSRF fetch failed with status ${csrfResponse.status}`);
-				return false;
-			}
-			this.processResponse(csrfResponse);
-			if (!this.csrfManager.hasCached()) {
-				this.logger?.warn("Session: CSRF fetch succeeded but no token found in response");
-				return false;
-			}
-			this.securitySessionActive = true;
-			this.logger?.debug("Session: CSRF token acquired");
-			if (sessionPath) {
-				const deleteUrl = new URL(sessionPath, baseUrl);
-				if (client) deleteUrl.searchParams.append("sap-client", client);
-				try {
-					this.logger?.debug(`Session: Deleting security session ${sessionPath}`);
-					await fetch(deleteUrl.toString(), {
-						method: "DELETE",
-						headers: {
-							...baseHeaders(),
-							"x-sap-security-session": "use",
-							"x-csrf-token": this.csrfManager.getCached()
-						}
-					});
-					this.logger?.debug("Session: Security session deleted");
-				} catch {
-					this.logger?.debug("Session: Failed to delete security session (will expire)");
-				}
+			if (!response.ok) {
+				this.logger?.debug(`Session: Cleanup CSRF fetch failed with status ${response.status}`);
+				return;
 			}
-			return true;
-		} catch (error) {
-			this.logger?.error(`Session: CSRF initialization error: ${error instanceof Error ? error.message : String(error)}`);
-			return false;
+			const setCookieHeader = response.headers.get("set-cookie");
+			if (setCookieHeader) this.cookieStore.parseCookies(setCookieHeader);
+			return this.csrfManager.extractFromHeader(response.headers.get("x-csrf-token"));
+		} catch {
+			this.logger?.debug("Session: Failed to fetch cleanup CSRF token");
+			return;
 		}
 	}
+	async deleteSecuritySessionWithFallback({ sessionPath, baseUrl, authHeader, client, language, signal }) {
+		const token = await this.fetchSecuritySessionCsrfToken({
+			baseUrl,
+			authHeader,
+			client,
+			language,
+			signal
+		});
+		if (token) await this.deleteSecuritySession({
+			sessionPath,
+			csrfToken: token,
+			baseUrl,
+			authHeader,
+			client,
+			signal
+		});
+	}
+	handleCsrfInitializationError(error, { baseUrl, authHeader, client, language, sessionPath, signal }) {
+		if (sessionPath) this.deleteSecuritySessionWithFallback({
+			sessionPath,
+			baseUrl,
+			authHeader,
+			client,
+			language
+		}).catch(() => void 0);
+		if (signal?.aborted) throw error;
+		this.logger?.error(`Session: CSRF initialization error: ${error instanceof Error ? error.message : String(error)}`);
+		return false;
+	}
 	/**
 	* Clear all session state (cookies and CSRF)
 	*/
@@ -498,35 +648,166 @@ function parseAdtException(xml) {
 * Create an AdtError from HTTP response details
 */
 function createAdtError(status, statusText, url, method, rawBody) {
+	const exception = parseAdtException(rawBody);
 	return new AdtError({
 		status,
 		statusText,
 		url,
 		method,
 		rawBody,
-		exception: parseAdtException(rawBody)
+		exception
 	});
 }
 
+//#endregion
+//#region src/cancellation.ts
+const adtAbortSignal = new AsyncLocalStorage();
+/**
+* Runs an ADT operation with an execution-scoped abort signal. Async local
+* storage keeps concurrent clients and invocations isolated without mutating
+* shared client state.
+*/
+async function runWithAdtAbortSignal(signal, operation) {
+	signal.throwIfAborted();
+	return await adtAbortSignal.run(signal, operation);
+}
+function activeAdtAbortSignal() {
+	return adtAbortSignal.getStore();
+}
+
 //#endregion
 //#region src/adapter.ts
+/**
+* A response exceeded an explicit byte cap before its body was retained.
+* Deliberately carries size metadata only, never response text.
+*/
+var AdtResponseTooLargeError = class extends Error {
+	maxBytes;
+	receivedBytes;
+	code = "ADT_RESPONSE_TOO_LARGE";
+	constructor(maxBytes, receivedBytes) {
+		super(`ADT response exceeds the ${maxBytes}-byte limit.`);
+		this.maxBytes = maxBytes;
+		this.receivedBytes = receivedBytes;
+		this.name = "AdtResponseTooLargeError";
+	}
+};
+function contentLengthExceedsLimit(contentLength, maxBytes) {
+	if (!contentLength || !/^\d+$/.test(contentLength)) return void 0;
+	const parsed = Number(contentLength);
+	return Number.isSafeInteger(parsed) && parsed > maxBytes ? parsed : void 0;
+}
+async function abortResponse(response, abortController) {
+	abortController.abort();
+	try {
+		await response.body?.cancel();
+	} catch {}
+}
+async function readResponseTextBounded(response, maxBytes, abortController) {
+	const declaredBytes = contentLengthExceedsLimit(response.headers.get("content-length"), maxBytes);
+	if (declaredBytes !== void 0) {
+		await abortResponse(response, abortController);
+		throw new AdtResponseTooLargeError(maxBytes, declaredBytes);
+	}
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const chunks = [];
+	let receivedBytes = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (!value) continue;
+			const nextReceivedBytes = receivedBytes + value.byteLength;
+			if (nextReceivedBytes > maxBytes) {
+				abortController.abort();
+				try {
+					await reader.cancel();
+				} catch {}
+				throw new AdtResponseTooLargeError(maxBytes, nextReceivedBytes);
+			}
+			chunks.push(value);
+			receivedBytes = nextReceivedBytes;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const combined = new Uint8Array(receivedBytes);
+	let offset = 0;
+	for (const chunk of chunks) {
+		combined.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(combined);
+}
+function executionAbortController() {
+	const abortController = new AbortController();
+	const executionSignal = activeAdtAbortSignal();
+	if (!executionSignal) return {
+		abortController,
+		dispose: () => void 0
+	};
+	const abortFromExecution = () => abortController.abort(executionSignal.reason);
+	if (executionSignal.aborted) abortFromExecution();
+	else executionSignal.addEventListener("abort", abortFromExecution, { once: true });
+	return {
+		abortController,
+		dispose: () => executionSignal.removeEventListener("abort", abortFromExecution)
+	};
+}
 function createAdtAdapter(config) {
-	const { baseUrl, username, password, cookieHeader, authorizationHeader, client, language, logger, plugins = [], onSessionExpired } = config;
+	const { baseUrl, username, password, cookieHeader, authorizationHeader, client, language, logger, plugins = [], onSessionExpired, headersTimeoutMs } = config;
+	const dispatcher = headersTimeoutMs === void 0 ? void 0 : new Agent({ headersTimeout: headersTimeoutMs });
+	/** Merge the optional Undici dispatcher into a fetch RequestInit. */
+	function withDispatcher(init) {
+		return dispatcher ? {
+			...init,
+			dispatcher
+		} : init;
+	}
+	/** Keep a configured Agent paired with the Undici fetch ABI that created it. */
+	async function requestFetch(input, init) {
+		if (!dispatcher) return globalThis.fetch(input, init);
+		return await fetch(input, init);
+	}
+	/**
+	* Route a session-manager request through the same paired Undici
+	* fetch/dispatcher used for the final adapter request, so the
+	* configured headersTimeout applies to the entire write flow
+	* (CSRF handshake included), not just the last hop.
+	*/
+	async function sessionFetch(input, init) {
+		return requestFetch(input.toString(), withDispatcher(init ?? {}));
+	}
+	/**
+	* Resolve `options.url` against the configured `baseUrl` and reject
+	* absolute URLs that would send credentials to a different origin.
+	*/
+	function resolveAdtUrl(requestUrl) {
+		const resolved = new URL(requestUrl, baseUrl);
+		const baseOrigin = new URL(baseUrl).origin;
+		if (resolved.origin !== baseOrigin) throw new RangeError(`Refusing to fetch ${resolved.origin} — ADT requests must target the configured base origin ${baseOrigin}`);
+		return resolved;
+	}
 	const isSamlAuth = !!cookieHeader;
 	const basicCredentials = `${username}:${password}`;
 	const authHeader = authorizationHeader ?? (isSamlAuth ? void 0 : `Basic ${Buffer.from(basicCredentials).toString("base64")}`);
-	const sessionManager = new SessionManager(logger);
+	const sessionManager = new SessionManager(logger, sessionFetch);
 	if (cookieHeader) sessionManager.injectCookie(cookieHeader);
 	return {
 		async request(options) {
+			const executionSignal = activeAdtAbortSignal();
+			executionSignal?.throwIfAborted();
 			logger?.debug("=== ADAPTER REQUEST START ===");
 			logger?.debug("options.url:", options.url);
 			logger?.debug("options.method:", options.method);
 			logger?.debug("options.body:", options.body ? "present" : "undefined");
 			logger?.debug("options.bodySchema:", options.bodySchema ? "present" : "undefined");
-			const url = new URL(options.url, baseUrl);
+			const url = resolveAdtUrl(options.url);
 			if (options.query) Object.entries(options.query).forEach(([key, value]) => {
-				url.searchParams.append(key, String(value));
+				(Array.isArray(value) ? value : [value]).forEach((entry) => {
+					if (entry !== void 0) url.searchParams.append(key, String(entry));
+				});
 			});
 			if (client) url.searchParams.append("sap-client", client);
 			if (language) url.searchParams.append("sap-language", language);
@@ -537,7 +818,12 @@ function createAdtAdapter(config) {
 				"PATCH"
 			].includes(options.method.toUpperCase()) && !sessionManager.hasCsrfToken()) {
 				logger?.debug("Adapter: Initializing CSRF token before write operation");
-				await sessionManager.initializeCsrf(baseUrl, authHeader, client, language);
+				await sessionManager.initializeCsrf(baseUrl, {
+					authHeader,
+					client,
+					language,
+					signal: executionSignal
+				});
 			}
 			const headers = {
 				"X-sap-adt-sessiontype": sessionManager.getSessionTypeHeader(),
@@ -568,41 +854,39 @@ function createAdtAdapter(config) {
 			logger?.debug("bodySerializableSchema: " + (bodySerializableSchema ? "present" : "undefined"));
 			logger?.debug("Body type: " + typeof body);
 			logger?.debug("Body value: " + (body ? JSON.stringify(body).substring(0, 500) : "UNDEFINED/NULL"));
-			if (body !== void 0 && body !== null) if (typeof body === "string") {
-				requestBody = body;
-				logger?.debug("Body: using raw string");
-				logger?.debug("Body content (first 200 chars):", requestBody.substring(0, 200));
-			} else if (bodySerializableSchema) try {
-				logger?.debug("Calling bodySerializableSchema.build with body: " + JSON.stringify(body).substring(0, 300));
-				requestBody = bodySerializableSchema.build(body);
-				logger?.debug("Body: serialized using Serializable.build()");
-				logger?.debug("Body output type: " + typeof requestBody);
-				logger?.debug("Body output length: " + requestBody?.length);
-				logger?.debug("Body content (first 500 chars): " + requestBody?.substring(0, 500));
-			} catch (buildError) {
-				logger?.error("Schema build() threw error: " + (buildError instanceof Error ? buildError.message : String(buildError)));
-				logger?.error("Stack: " + (buildError instanceof Error ? buildError.stack : "N/A"));
-				throw buildError;
-			}
-			else {
-				requestBody = JSON.stringify(body);
-				logger?.debug("Body: serialized as JSON");
+			if (body !== void 0 && body !== null) {
+				if (typeof body === "string") {
+					requestBody = body;
+					logger?.debug("Body: using raw string");
+					logger?.debug("Body content (first 200 chars):", requestBody.substring(0, 200));
+				} else if (bodySerializableSchema) try {
+					logger?.debug("Calling bodySerializableSchema.build with body: " + JSON.stringify(body).substring(0, 300));
+					requestBody = bodySerializableSchema.build(body);
+					logger?.debug("Body: serialized using Serializable.build()");
+					logger?.debug("Body output type: " + typeof requestBody);
+					logger?.debug("Body output length: " + requestBody?.length);
+					logger?.debug("Body content (first 500 chars): " + requestBody?.substring(0, 500));
+				} catch (buildError) {
+					logger?.error("Schema build() threw error: " + (buildError instanceof Error ? buildError.message : String(buildError)));
+					logger?.error("Stack: " + (buildError instanceof Error ? buildError.stack : "N/A"));
+					throw buildError;
+				}
+				else {
+					requestBody = JSON.stringify(body);
+					logger?.debug("Body: serialized as JSON");
+				}
 			}
 			logger?.debug(`HTTP ${options.method} ${url.toString()}`);
 			{
-				const safeHeaders = {
-					...headers,
-					...headers.Authorization ? { Authorization: headers.Authorization.substring(0, 10) + "***" } : {},
-					...headers.Cookie ? { Cookie: "***" } : {},
-					...headers["x-csrf-token"] ? { "x-csrf-token": "***" } : {}
-				};
-				logger?.debug("Request headers: " + JSON.stringify(safeHeaders, null, 2));
+				const headerNames = Object.keys(headers).sort();
+				logger?.debug("Request headers (names only): " + JSON.stringify(headerNames));
 			}
-			const response = await fetch(url.toString(), {
+			const response = await requestFetch(url.toString(), withDispatcher({
 				method: options.method,
 				headers,
-				body: requestBody
-			});
+				body: requestBody,
+				signal: executionSignal
+			}));
 			sessionManager.processResponse(response, url.pathname);
 			logger?.debug(`Response: ${response.status} ${response.statusText}`);
 			logger?.debug("Response headers: " + JSON.stringify(Object.fromEntries(response.headers.entries()), null, 2));
@@ -622,10 +906,12 @@ function createAdtAdapter(config) {
 				logger?.error(`Request failed - ${adtError.message} (${options.method} ${url.toString()})`);
 				if (adtError.exception) logger?.error(`ADT Exception: namespace=${adtError.exception.namespace}, type=${adtError.exception.type}`);
 				if (errorBody && !adtError.exception) logger?.error(`Response body: ${errorBody}`);
-				if (response.status === 403) if (!(adtError.exception?.type === "ExceptionResourceNoAccess" && (adtError.message.includes("currently editing") || adtError.message.includes("is being edited")))) {
-					sessionManager.clear();
-					logger?.warn("Session cleared due to 403 Forbidden response");
-				} else logger?.warn("Lock conflict (403) — session preserved (object locked by another session)");
+				if (response.status === 403) {
+					if (!(adtError.exception?.type === "ExceptionResourceNoAccess" && (adtError.message.includes("currently editing") || adtError.message.includes("is being edited")))) {
+						sessionManager.clear();
+						logger?.warn("Session cleared due to 403 Forbidden response");
+					} else logger?.warn("Lock conflict (403) — session preserved (object locked by another session)");
+				}
 				throw adtError;
 			}
 			const contentType = response.headers.get("content-type") || "";
@@ -649,9 +935,10 @@ function createAdtAdapter(config) {
 			}
 			let data;
 			if (contentType.includes("application/json") || contentType.includes("+json")) data = JSON.parse(rawText);
-			else if (contentType.includes("text/") || contentType.includes("xml")) if (serializableSchema && contentType.includes("xml")) data = serializableSchema.parse(rawText);
-			else data = rawText;
-			else data = rawText;
+			else if (contentType.includes("text/") || contentType.includes("xml")) {
+				if (serializableSchema && contentType.includes("xml")) data = serializableSchema.parse(rawText);
+				else data = rawText;
+			} else data = rawText;
 			if (plugins.length > 0) {
 				const context = {
 					rawText,
@@ -672,6 +959,32 @@ function createAdtAdapter(config) {
 		},
 		clearETag(url) {
 			sessionManager.clearETag(url);
+		},
+		async readTextBounded(options, maxBytes) {
+			if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) throw new RangeError("maxBytes must be a non-negative safe integer.");
+			const url = resolveAdtUrl(options.url);
+			if (client) url.searchParams.append("sap-client", client);
+			if (language) url.searchParams.append("sap-language", language);
+			const headers = {
+				"X-sap-adt-sessiontype": sessionManager.getSessionTypeHeader(),
+				...sessionManager.getRequestHeaders("GET", url.pathname),
+				...options.headers
+			};
+			if (authHeader) headers.Authorization = authHeader;
+			const { abortController, dispose } = executionAbortController();
+			try {
+				const response = await requestFetch(url.toString(), withDispatcher({
+					method: "GET",
+					headers,
+					signal: abortController.signal
+				}));
+				sessionManager.processResponse(response, url.pathname);
+				const text = await readResponseTextBounded(response, maxBytes, abortController);
+				if (!response.ok) throw createAdtError(response.status, response.statusText, url.toString(), "GET", text);
+				return text;
+			} finally {
+				dispose();
+			}
 		}
 	};
 }
@@ -682,6 +995,7 @@ function createAdtAdapter(config) {
 * Transport Service - orchestrates CTS operations
 */
 var TransportService = class {
+	adt;
 	constructor(adt) {
 		this.adt = adt;
 	}
@@ -698,7 +1012,8 @@ var TransportService = class {
 	async get(trkorr) {
 		const data = await this.adt.cts.transportrequests.get(trkorr);
 		const unwrapped = data?.root && typeof data.root === "object" ? data.root : data;
-		const request = unwrapped?.request ?? unwrapped;
+		const wanted = trkorr.trim().toUpperCase();
+		const request = this.findUnit(unwrapped?.task, wanted) ?? this.findUnit(unwrapped?.request, wanted) ?? unwrapped?.request ?? unwrapped?.task ?? unwrapped;
 		return this.mapToTransport(request);
 	}
 	/**
@@ -727,6 +1042,17 @@ var TransportService = class {
 		throw new Error("Transport release via service layer not yet implemented.");
 	}
 	/**
+	* Find a request/task unit whose number matches the wanted transport id.
+	* Handles both single-object and array shapes from ts-xsd.
+	*/
+	findUnit(node, wanted) {
+		if (!node) return void 0;
+		return (Array.isArray(node) ? node : [node]).find((item) => {
+			const u = item;
+			return String(u?.trkorr ?? u?.number ?? "").toUpperCase() === wanted;
+		});
+	}
+	/**
 	* Extract requests array from various response formats
 	*/
 	extractRequests(response) {
@@ -750,6 +1076,8 @@ var TransportService = class {
 			status: data.trstatus ?? data.status,
 			type: data.trfunction ?? data.type,
 			target: data.tarsystem ?? data.target,
+			parent: data.parent,
+			lastChangedTimestamp: data.lastchanged_timestamp ?? data.lastChangedTimestamp,
 			tasks: this.extractTasks(data)
 		};
 	}
@@ -764,7 +1092,11 @@ var TransportService = class {
 			return {
 				number: String(t.trkorr ?? t.number ?? ""),
 				owner: t.as4user ?? t.owner,
-				status: t.trstatus ?? t.status
+				status: t.trstatus ?? t.status,
+				desc: t.as4text ?? t.desc,
+				type: t.trfunction ?? t.type,
+				parent: t.parent,
+				lastChangedTimestamp: t.lastchanged_timestamp ?? t.lastChangedTimestamp
 			};
 		});
 	}
@@ -798,6 +1130,7 @@ function toUserInfoList(entries) {
 * User Service - orchestrates user lookup operations
 */
 var UserService = class {
+	adt;
 	constructor(adt) {
 		this.adt = adt;
 	}
@@ -832,6 +1165,224 @@ function createUserService(adt) {
 	return new UserService(adt);
 }
 
+//#endregion
+//#region src/services/source-history.ts
+var SourceHistoryProtocolError = class extends Error {
+	code;
+	ordinal;
+	constructor(code, message, ordinal) {
+		super(message);
+		this.code = code;
+		this.ordinal = ordinal;
+		this.name = "SourceHistoryProtocolError";
+	}
+};
+/**
+* An immutable source body crossed its configured byte limit.
+* This error intentionally does not retain the source URI or any source text.
+*/
+var SourceVersionTooLargeError = class extends Error {
+	maxBytes;
+	receivedBytes;
+	code = "SOURCE_VERSION_TOO_LARGE";
+	constructor(maxBytes, receivedBytes) {
+		super(`Source version exceeds the ${maxBytes}-byte limit.`);
+		this.maxBytes = maxBytes;
+		this.receivedBytes = receivedBytes;
+		this.name = "SourceVersionTooLargeError";
+	}
+};
+const ADT_PATH_PREFIX = "/sap/bc/adt/";
+const TRAVERSAL_SEGMENT = /(?:^|\/)(?:\.{1,2}|%2e(?:%2e)?)(?:\/|$)/i;
+const TRANSPORT_NUMBER = /^[A-Z0-9]{10}$/;
+function asOptionalString(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function asArray(value) {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+}
+/**
+* Validate a server-relative ADT URI before it reaches the authenticated
+* adapter. This deliberately rejects absolute and protocol-relative URLs so a
+* source-history link cannot redirect credentials to another origin.
+*/
+function isUnsafeAdtUri(uri) {
+	if (uri !== uri.trim()) return true;
+	if (!uri.startsWith(ADT_PATH_PREFIX)) return true;
+	if (uri.startsWith("//")) return true;
+	if (uri.includes("#")) return true;
+	if (uri.includes("\\")) return true;
+	return TRAVERSAL_SEGMENT.test(uri);
+}
+function assertAdtUri(uri) {
+	if (isUnsafeAdtUri(uri)) throw new SourceHistoryProtocolError("SOURCE_HISTORY_URI_UNSAFE", "Source-history URI must be a server-relative SAP ADT path.");
+	return uri;
+}
+function isUnsafeRelativeHref(href) {
+	if (href.startsWith("//")) return true;
+	if (href.includes("\\")) return true;
+	if (href.includes(":")) return true;
+	return TRAVERSAL_SEGMENT.test(href);
+}
+function resolveRelativeAdtUri(href, versionsUri) {
+	const validatedBase = assertAdtUri(versionsUri);
+	const collectionBase = validatedBase.endsWith("/") ? validatedBase : `${validatedBase}/`;
+	const resolved = new URL(href, `https://adt.invalid${collectionBase}`);
+	return assertAdtUri(`${resolved.pathname}${resolved.search}${resolved.hash}`);
+}
+function resolveAdtUri(href, versionsUri) {
+	if (href.startsWith("/")) return assertAdtUri(href);
+	if (isUnsafeRelativeHref(href)) throw new SourceHistoryProtocolError("SOURCE_HISTORY_URI_UNSAFE", "Source-history link must stay within the SAP ADT origin.");
+	return resolveRelativeAdtUri(href, versionsUri);
+}
+function normalizeLinks(value) {
+	return asArray(value).filter((link) => Boolean(link) && typeof link === "object");
+}
+function isContentLink(link) {
+	const rel = asOptionalString(link.rel)?.toLowerCase();
+	return Boolean(rel?.endsWith("/content") || rel === "content");
+}
+function isPlainTextContentLink(link) {
+	const contentType = asOptionalString(link.type)?.toLowerCase();
+	return Boolean(contentType?.startsWith("text/plain"));
+}
+/**
+* Some SAP source-version feeds represent the immutable source body with the
+* standard Atom `content` element rather than an Atom link. Treat it exactly
+* like a content link, but only when it is explicitly plain text.
+*/
+function contentElementAsLink(entry) {
+	const content = entry.content;
+	if (!content) return void 0;
+	if (typeof content !== "object") return void 0;
+	if (Array.isArray(content)) return void 0;
+	const src = asOptionalString(content.src);
+	if (!src) return void 0;
+	const type = asOptionalString(content.type);
+	if (!type) return void 0;
+	if (!type.toLowerCase().startsWith("text/plain")) return void 0;
+	return {
+		href: src,
+		type
+	};
+}
+function isTransportRel(rel) {
+	return rel.endsWith("/transport") || rel.endsWith("/transport/request");
+}
+function transportFromTitle(link) {
+	const title = asOptionalString(link.title)?.toUpperCase();
+	if (!title) return void 0;
+	if (TRANSPORT_NUMBER.test(title)) return title;
+}
+function transportFromHref(link) {
+	const href = asOptionalString(link.href);
+	if (!href) return void 0;
+	const lastSegment = (href.split(/[?#]/, 1)[0]?.split("/").filter((segment) => segment !== ""))?.pop();
+	if (!lastSegment) return void 0;
+	try {
+		const candidate = decodeURIComponent(lastSegment).toUpperCase();
+		return TRANSPORT_NUMBER.test(candidate) ? candidate : void 0;
+	} catch {
+		return;
+	}
+}
+function transportFromLink(link) {
+	const rel = asOptionalString(link.rel)?.toLowerCase();
+	if (!rel || !isTransportRel(rel)) return void 0;
+	return transportFromTitle(link) ?? transportFromHref(link);
+}
+function authorName(value) {
+	return asOptionalString(asArray(value).find((candidate) => Boolean(candidate) && typeof candidate === "object")?.name);
+}
+/**
+* Normalize the parsed Atom versions feed while preserving SAP's feed order.
+* The result contains references and provenance only; source bodies are fetched
+* separately and are never retained by this function.
+*/
+function assertSourceVersionPayload(payload) {
+	if (!payload || typeof payload !== "object") throw new SourceHistoryProtocolError("SOURCE_VERSION_FEED_INVALID", "SAP ADT source-history response is not an Atom feed.");
+	if (!("feed" in payload)) throw new SourceHistoryProtocolError("SOURCE_VERSION_FEED_INVALID", "SAP ADT source-history response is not an Atom feed.");
+	return payload;
+}
+function assertSourceVersionFeed(feed) {
+	if (!feed) throw invalidFeedError();
+	if (typeof feed !== "object") throw invalidFeedError();
+	if (Array.isArray(feed)) throw invalidFeedError();
+	return feed;
+}
+function invalidFeedError() {
+	return new SourceHistoryProtocolError("SOURCE_VERSION_FEED_INVALID", "SAP ADT source-history feed has an invalid root.");
+}
+function readSourceVersionEntries(feed) {
+	if (feed.entry === void 0) return [];
+	const entries = asArray(feed.entry);
+	if (entries.some((entry) => !entry || typeof entry !== "object")) throw new SourceHistoryProtocolError("SOURCE_VERSION_FEED_INVALID", "SAP ADT source-history feed contains an invalid entry.");
+	return entries;
+}
+function extractContentLink(entry, ordinal) {
+	const links = normalizeLinks(entry.link);
+	const contentLink = links.find(isContentLink) ?? links.find(isPlainTextContentLink) ?? contentElementAsLink(entry);
+	const href = contentLink && asOptionalString(contentLink.href);
+	if (!contentLink || !href) throw new SourceHistoryProtocolError("SOURCE_VERSION_CONTENT_LINK_MISSING", `Source-history entry ${ordinal} has no immutable content link.`, ordinal);
+	return {
+		...contentLink,
+		href
+	};
+}
+function extractEntryTransports(links) {
+	return [...new Set(links.map(transportFromLink).filter((transport) => Boolean(transport)))];
+}
+function sourceVersionRefFromEntry(entry, ordinal, versionsUri) {
+	const id = asOptionalString(entry.id);
+	if (!id) throw new SourceHistoryProtocolError("SOURCE_VERSION_ID_MISSING", `Source-history entry ${ordinal} has no stable version id.`, ordinal);
+	const contentLink = extractContentLink(entry, ordinal);
+	return {
+		id,
+		ordinal,
+		title: asOptionalString(entry.title),
+		sourceUri: resolveAdtUri(contentLink.href, versionsUri),
+		contentType: asOptionalString(contentLink.type),
+		etag: asOptionalString(contentLink.etag),
+		updatedAt: asOptionalString(entry.updated),
+		author: authorName(entry.author),
+		transports: extractEntryTransports(normalizeLinks(entry.link))
+	};
+}
+function normalizeSourceVersionFeed(payload, versionsUri) {
+	assertAdtUri(versionsUri);
+	return readSourceVersionEntries(assertSourceVersionFeed(assertSourceVersionPayload(payload).feed)).map((entry, ordinal) => sourceVersionRefFromEntry(entry, ordinal, versionsUri));
+}
+var SourceHistoryService = class {
+	adt;
+	boundedSourceReader;
+	constructor(adt, boundedSourceReader) {
+		this.adt = adt;
+		this.boundedSourceReader = boundedSourceReader;
+	}
+	async listVersions(versionsUri) {
+		assertAdtUri(versionsUri);
+		return normalizeSourceVersionFeed(await this.adt.repository.sourceversions.list({ versionsUri }), versionsUri);
+	}
+	async readVersionSource(sourceUri) {
+		assertAdtUri(sourceUri);
+		return this.adt.repository.sourceversions.get({ sourceUri });
+	}
+	async readVersionSourceBounded(sourceUri, maxBytes) {
+		assertAdtUri(sourceUri);
+		if (!this.boundedSourceReader) throw new Error("Bounded source reads are not configured.");
+		try {
+			return await this.boundedSourceReader(sourceUri, maxBytes);
+		} catch (error) {
+			if (error instanceof AdtResponseTooLargeError) throw new SourceVersionTooLargeError(error.maxBytes, error.receivedBytes);
+			throw error;
+		}
+	}
+};
+function createSourceHistoryService(adt, boundedSourceReader) {
+	return new SourceHistoryService(adt, boundedSourceReader);
+}
+
 //#endregion
 //#region src/client.ts
 /**
@@ -859,10 +1410,41 @@ function createAdtClient(config) {
 		};
 		return adapter.request(requestOptions);
 	};
+	const readTextBounded = async (url, maxBytes, options) => adapter.readTextBounded({
+		url,
+		headers: options?.headers
+	}, maxBytes);
 	return {
+		/**
+		* Typed ADT REST contracts
+		* Direct access to speci-generated client methods
+		*/
 		adt: adtClient,
-		services: { transports: createTransportService(adtClient) },
+		/**
+		* Services layer - business logic orchestration
+		* Higher-level operations that combine multiple contract calls
+		*/
+		services: {
+			transports: createTransportService(adtClient),
+			sourceHistory: createSourceHistoryService(adtClient, (sourceUri, maxBytes) => readTextBounded(sourceUri, maxBytes, { headers: { Accept: "text/plain" } }))
+		},
+		/**
+		* Generic fetch utility for arbitrary ADT endpoints
+		* Useful for debugging, testing, or accessing undocumented APIs
+		*
+		* @param url - The ADT endpoint path (e.g., '/sap/bc/adt/core/http/sessions')
+		* @param options - Request options (method, headers, body)
+		* @returns Raw response
+		*/
 		fetch: fetchFn,
+		/**
+		* Read an authenticated plain-text endpoint while enforcing a byte limit.
+		*/
+		readTextBounded,
+		/**
+		* Clear cached ETag for a specific URL, or all ETags if no URL given.
+		* Use after operations that may invalidate server-side ETags.
+		*/
 		clearETag: (url) => adapter.clearETag(url)
 	};
 }
@@ -873,6 +1455,7 @@ function createAdtClient(config) {
 * Logging plugin - logs requests and responses
 */
 var LoggingPlugin = class {
+	logger;
 	name = "logging";
 	constructor(logger = console.log) {
 		this.logger = logger;
@@ -897,6 +1480,7 @@ var LoggingPlugin = class {
 * Similar to v1's FileLogger functionality
 */
 var FileLoggingPlugin = class {
+	config;
 	name = "file-logging";
 	constructor(config) {
 		this.config = config;
@@ -965,5 +1549,5 @@ var FileLoggingPlugin = class {
 };
 
 //#endregion
-export { CookieStore, CsrfTokenManager, FileLoggingPlugin, LoggingPlugin, SessionManager, TransportService, UserService, adtContract, createAdtAdapter, createAdtClient, createTransportService, createUserService };
+export { AdtResponseTooLargeError, CookieStore, CsrfTokenManager, FileLoggingPlugin, LoggingPlugin, SessionManager, SourceHistoryProtocolError, SourceHistoryService, SourceVersionTooLargeError, TransportService, UserService, adtContract, assertAdtUri, createAdtAdapter, createAdtClient, createSourceHistoryService, createTransportService, createUserService, normalizeSourceVersionFeed, runWithAdtAbortSignal };
 //# sourceMappingURL=index.mjs.map