@mcp-abap-adt/adt-clients 10.0.2 → 10.1.0

package/README.md

@@ -364,7 +364,23 @@ implementations pass it internally on reads after create/update.
 See the caveat above — on the system measured, the flag had no effect on object
 reads at all.
 
-**Note:** Long polling is automatically used in `create()` and `update()` methods of all `AdtObject` implementations to ensure objects are ready before proceeding with subsequent operations.
+**Note:** `create()` and `update()` request long polling on their follow-up reads
+where the handler supports it. Read that as "asked for", not "ensured" — the
+caveat above stands, and nothing in this library can make the system answer
+sooner than it does.
+
+What the library does guarantee is that a read which came back empty is not
+written back. ADT answers a read of a not-yet-ready object with **HTTP 200 and
+an empty body**, never a 404, so a read-modify-write update used to patch that
+empty body — changing nothing, because there was nothing to change — and PUT the
+result. Since 10.1.0 that read fails with `XmlPatchError`, naming the object:
+
+```
+Cannot update domain ZAC_DOM01: the read returned an empty body.
+```
+
+A slow system therefore surfaces as a read error, not as a write the server
+rejects for a reason that points nowhere near the cause.
 
 ### Creating Behavior Implementation Classes
 

package/dist/core/dataElement/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/core/dataElement/update.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,OAAO,EACR,MAAM,0BAA0B,CAAC;AAgBlC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAIxD;;GAEG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,eAAe,EAC3B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmCjE;AAqID;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,eAAe,EAC3B,MAAM,EAAE,wBAAwB,EAChC,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,CAkEvB;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,eAAe,EAC3B,IAAI,EAAE,wBAAwB,EAC9B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EACnE,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,CAEvB"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/core/dataElement/update.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,OAAO,EACR,MAAM,0BAA0B,CAAC;AAgBlC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAIxD;;GAEG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,eAAe,EAC3B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmCjE;AAqID;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,eAAe,EAC3B,MAAM,EAAE,wBAAwB,EAChC,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,CAqEvB;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,eAAe,EAC3B,IAAI,EAAE,wBAAwB,EAC9B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EACnE,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,CAEvB"}

package/dist/core/dataElement/update.js

@@ -171,7 +171,7 @@ async function updateDataElement(connection, params, lockHandle, logger) {
         timeout: (0, timeouts_1.getTimeout)('default'),
         headers: { Accept: contentTypes_1.ACCEPT_DATA_ELEMENT },
     });
-    const currentXml = (0, xmlPatch_1.extractXmlString)(currentResponse.data);
+    const currentXml = (0, xmlPatch_1.extractXmlString)(currentResponse.data, `data element ${params.data_element_name}`);
     // 2. Patch only changed fields
     const updatedXml = patchDataElementXml(currentXml, params);
     // Debug: log XML when DEBUG_ADT_LIBS is enabled

package/dist/core/domain/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/core/domain/update.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAe9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAsEnD;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,eAAe,EAC3B,IAAI,EAAE,mBAAmB,EACzB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,CAAC,CAiCvB"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/core/domain/update.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAe9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAsEnD;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,eAAe,EAC3B,IAAI,EAAE,mBAAmB,EACzB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,CAAC,CAoCvB"}

package/dist/core/domain/update.js

@@ -69,7 +69,7 @@ async function updateDomain(connection, args, lockHandle) {
         timeout: (0, timeouts_1.getTimeout)('default'),
         headers: { Accept: contentTypes_1.ACCEPT_DOMAIN },
     });
-    const currentXml = (0, xmlPatch_1.extractXmlString)(currentResponse.data);
+    const currentXml = (0, xmlPatch_1.extractXmlString)(currentResponse.data, `domain ${args.domain_name}`);
     // 2. Patch only changed fields
     const updatedXml = patchDomainXml(currentXml, args);
     // 3. PUT

package/dist/core/functionGroup/update.js

@@ -60,9 +60,7 @@ async function updateFunctionGroup(connection, params, contentTypes) {
         }
         // Get current XML
         const currentResponse = await (0, read_1.getFunctionGroup)(connection, params.function_group_name, undefined);
-        const currentXml = typeof currentResponse.data === 'string'
-            ? currentResponse.data
-            : JSON.stringify(currentResponse.data);
+        const currentXml = (0, xmlPatch_1.extractXmlString)(currentResponse.data, `function group ${params.function_group_name}`);
         // Update metadata
         const updateResponse = await updateFunctionGroupMetadata(connection, params.function_group_name, currentXml, params.description, lockHandle, params.transport_request, contentTypes);
         // Unlock if we locked it

package/dist/core/package/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/core/package/update.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,oBAAoB,EACrB,MAAM,0BAA0B,CAAC;AA4ElC;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,eAAe,EAC3B,MAAM,EAAE,oBAAoB,EAC5B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,CAAC,CAuCvB;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,eAAe,EAC3B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,YAAY,CAAC,CAkBvB"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/core/package/update.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,oBAAoB,EACrB,MAAM,0BAA0B,CAAC;AA4ElC;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,eAAe,EAC3B,MAAM,EAAE,oBAAoB,EAC5B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,CAAC,CA0CvB;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,eAAe,EAC3B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,YAAY,CAAC,CAkBvB"}

package/dist/core/package/update.js

@@ -61,7 +61,7 @@ async function updatePackage(connection, params, lockHandle) {
         timeout: (0, timeouts_1.getTimeout)('default'),
         headers: { Accept: contentTypes_1.ACCEPT_PACKAGE },
     });
-    const currentXml = (0, xmlPatch_1.extractXmlString)(currentResponse.data);
+    const currentXml = (0, xmlPatch_1.extractXmlString)(currentResponse.data, `package ${params.package_name}`);
     // 2. Patch only changed fields
     const updatedXml = patchPackageXml(currentXml, params);
     // 3. PUT

package/dist/core/tabletype/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/core/tabletype/update.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAEV,eAAe,EACf,YAAY,EACZ,OAAO,EACR,MAAM,0BAA0B,CAAC;AAalC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AA0CtD;;GAEG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,eAAe,EAC3B,MAAM,EAAE,sBAAsB,EAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,CAsDvB"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/core/tabletype/update.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAEV,eAAe,EACf,YAAY,EACZ,OAAO,EACR,MAAM,0BAA0B,CAAC;AAalC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AA0CtD;;GAEG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,eAAe,EAC3B,MAAM,EAAE,sBAAsB,EAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,CAyDvB"}

package/dist/core/tabletype/update.js

@@ -83,7 +83,7 @@ async function updateTableType(connection, params, lockHandle, logger) {
     // 1. GET current XML
     const { getTableTypeMetadata } = await Promise.resolve().then(() => __importStar(require('./read')));
     const currentResponse = await getTableTypeMetadata(connection, tableTypeName, undefined, logger);
-    const currentXml = (0, xmlPatch_1.extractXmlString)(currentResponse.data);
+    const currentXml = (0, xmlPatch_1.extractXmlString)(currentResponse.data, `table type ${params.tabletype_name}`);
     // 2. Patch only changed fields
     const updatedXml = patchTableTypeXml(currentXml, params);
     // 3. PUT

package/dist/utils/xmlPatch.d.ts

@@ -1,27 +1,77 @@
 /**
- * XML patch utilities for read-modify-write update pattern.
+ * XML patch utilities for the read-modify-write update pattern.
  *
- * Instead of building XML from scratch (which loses unknown fields like abapLanguageVersion),
- * these helpers modify specific values in the original XML string obtained from GET.
+ * Instead of building XML from scratch (which loses unknown fields like
+ * abapLanguageVersion), these helpers modify specific values in the original
+ * XML string obtained from GET.
+ *
+ * **Every patch here fails loudly when it cannot find its target.** That is the
+ * point of this module's error handling, and it was learned from a live
+ * failure: a full test run reported
+ *
+ * ```
+ * update FAILED (HTTP 400): The description is missing for ZAC_DOM01
+ * ```
+ *
+ * on a domain whose description was present in the configuration all along. The
+ * chain was:
+ *
+ * 1. the GET came back slow, or the object was not yet ready — ADT answers such
+ *    reads with **200 and an empty body**, never a 404, so nothing upstream had
+ *    a status to react to;
+ * 2. `patchXmlAttribute` was asked to set `adtcore:description` and found no
+ *    attribute to replace. Being `String.replace`, it returned the input
+ *    unchanged — silently;
+ * 3. the PUT went out without a description, and the server rejected it.
+ *
+ * The ABAP system's varying response time is the trigger, and nothing here can
+ * change that. What these helpers control is what a slow read turns into: a
+ * read error naming the object, or a malformed write blamed on the server. It
+ * used to be the second.
  */
+/** Raised when a patch cannot find what it was asked to change. */
+export declare class XmlPatchError extends Error {
+    constructor(message: string);
+}
 /**
  * Replace an XML attribute value.
  * Example: `adtcore:description="old"` → `adtcore:description="new"`
+ *
+ * @throws {XmlPatchError} when the attribute is absent
  */
 export declare function patchXmlAttribute(xml: string, attrName: string, newValue: string): string;
 /**
  * Replace XML element text content.
  * Handles both `<tag>content</tag>` and self-closing `<tag/>`.
+ *
+ * @throws {XmlPatchError} when the element is absent
  */
 export declare function patchXmlElement(xml: string, tagName: string, newValue: string): string;
 /**
- * Replace an XML attribute on a specific element.
+ * Set an XML attribute on a specific element.
  * Example: `<pak:superPackage adtcore:name="OLD"/>` → `<pak:superPackage adtcore:name="NEW"/>`
+ *
+ * Unlike the other patches this one **adds** the attribute when the element is
+ * there without it, because that is a state ADT genuinely produces for an unset
+ * reference — probed on a live system:
+ *
+ * ```
+ * <doma:valueTableRef/>    a domain with no value table
+ * <pak:superPackage/>      a package with no parent
+ * ```
+ *
+ * Refusing those would forbid ever setting a value table or a super package for
+ * the first time. Only a missing *element* means the XML is not what the caller
+ * thinks it is, and only that throws.
+ *
+ * @throws {XmlPatchError} when the element itself is absent
  */
 export declare function patchXmlElementAttribute(xml: string, elementTag: string, attrName: string, newValue: string): string;
 /**
  * Replace an entire XML block (from opening to closing tag) with new content.
  * Handles both `<tag>...</tag>` (including nested content) and self-closing `<tag/>`.
+ *
+ * @throws {XmlPatchError} when the block is absent
  */
 export declare function patchXmlBlock(xml: string, tagName: string, newContent: string): string;
 /**
@@ -29,7 +79,16 @@ export declare function patchXmlBlock(xml: string, tagName: string, newContent:
  */
 export declare function patchIf<T>(xml: string, value: T | undefined | null, patchFn: (xml: string, val: T) => string): string;
 /**
- * Extract raw XML string from response data.
+ * Take the XML out of a response, refusing anything that cannot be patched.
+ *
+ * This used to `JSON.stringify` a non-string body and hand back the result,
+ * which is not XML and matches no patch — turning a bad read into a bad write
+ * one step earlier than the patches did. An empty body passed through just as
+ * quietly, and an empty body is exactly what ADT returns for an object that is
+ * not ready yet.
+ *
+ * @param what object being read, named in the error (e.g. `'domain ZAC_DOM01'`)
+ * @throws {XmlPatchError} when the body is not usable XML
  */
-export declare function extractXmlString(data: unknown): string;
+export declare function extractXmlString(data: unknown, what?: string): string;
 //# sourceMappingURL=xmlPatch.d.ts.map

package/dist/utils/xmlPatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xmlPatch.d.ts","sourceRoot":"","sources":["../../src/utils/xmlPatch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,MAAM,CAGR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,MAAM,CAYR;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,MAAM,CAGR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI,EAC3B,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,MAAM,GACvC,MAAM,CAGR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAGtD"}
+{"version":3,"file":"xmlPatch.d.ts","sourceRoot":"","sources":["../../src/utils/xmlPatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,mEAAmE;AACnE,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AA2BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,MAAM,CAOR;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,MAAM,CASR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,MAAM,CAuBR;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,MAAM,CAOR;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI,EAC3B,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,MAAM,GACvC,MAAM,CAGR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,SAAW,GAAG,MAAM,CAiBvE"}

package/dist/utils/xmlPatch.js

@@ -1,52 +1,132 @@
 "use strict";
 /**
- * XML patch utilities for read-modify-write update pattern.
+ * XML patch utilities for the read-modify-write update pattern.
  *
- * Instead of building XML from scratch (which loses unknown fields like abapLanguageVersion),
- * these helpers modify specific values in the original XML string obtained from GET.
+ * Instead of building XML from scratch (which loses unknown fields like
+ * abapLanguageVersion), these helpers modify specific values in the original
+ * XML string obtained from GET.
+ *
+ * **Every patch here fails loudly when it cannot find its target.** That is the
+ * point of this module's error handling, and it was learned from a live
+ * failure: a full test run reported
+ *
+ * ```
+ * update FAILED (HTTP 400): The description is missing for ZAC_DOM01
+ * ```
+ *
+ * on a domain whose description was present in the configuration all along. The
+ * chain was:
+ *
+ * 1. the GET came back slow, or the object was not yet ready — ADT answers such
+ *    reads with **200 and an empty body**, never a 404, so nothing upstream had
+ *    a status to react to;
+ * 2. `patchXmlAttribute` was asked to set `adtcore:description` and found no
+ *    attribute to replace. Being `String.replace`, it returned the input
+ *    unchanged — silently;
+ * 3. the PUT went out without a description, and the server rejected it.
+ *
+ * The ABAP system's varying response time is the trigger, and nothing here can
+ * change that. What these helpers control is what a slow read turns into: a
+ * read error naming the object, or a malformed write blamed on the server. It
+ * used to be the second.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.XmlPatchError = void 0;
 exports.patchXmlAttribute = patchXmlAttribute;
 exports.patchXmlElement = patchXmlElement;
 exports.patchXmlElementAttribute = patchXmlElementAttribute;
 exports.patchXmlBlock = patchXmlBlock;
 exports.patchIf = patchIf;
 exports.extractXmlString = extractXmlString;
+/** Raised when a patch cannot find what it was asked to change. */
+class XmlPatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'XmlPatchError';
+    }
+}
+exports.XmlPatchError = XmlPatchError;
+/**
+ * Apply a replacement, refusing to pass the XML through untouched.
+ *
+ * A caller reaches a patch only when it intends the change — `patchIf` skips
+ * the call entirely for an absent value — so "no match" always means the PUT
+ * would not carry what the caller asked for. There is no case where quietly
+ * returning the input is the right answer.
+ */
+function replaceOrThrow(xml, regex, replacement, target) {
+    if (!regex.test(xml)) {
+        throw new XmlPatchError(`Cannot patch ${target}: it is not present in the XML being updated. ` +
+            'This usually means the preceding read returned an empty or partial ' +
+            'body — ADT answers a read of a not-yet-ready object with HTTP 200 and ' +
+            'no content rather than an error.');
+    }
+    return xml.replace(regex, replacement);
+}
 /**
  * Replace an XML attribute value.
  * Example: `adtcore:description="old"` → `adtcore:description="new"`
+ *
+ * @throws {XmlPatchError} when the attribute is absent
  */
 function patchXmlAttribute(xml, attrName, newValue) {
-    const regex = new RegExp(`${attrName}="[^"]*"`);
-    return xml.replace(regex, `${attrName}="${escapeXmlAttr(newValue)}"`);
+    return replaceOrThrow(xml, new RegExp(`${attrName}="[^"]*"`), `${attrName}="${escapeXmlAttr(newValue)}"`, `attribute ${attrName}`);
 }
 /**
  * Replace XML element text content.
  * Handles both `<tag>content</tag>` and self-closing `<tag/>`.
+ *
+ * @throws {XmlPatchError} when the element is absent
  */
 function patchXmlElement(xml, tagName, newValue) {
-    // Match <tag>...</tag> or <tag/> (self-closing)
     const regex = new RegExp(`<${tagName}>([^<]*)</${tagName}>|<${tagName}\\s*/>`);
-    if (newValue === '' || newValue === undefined) {
-        return xml.replace(regex, `<${tagName}/>`);
-    }
-    return xml.replace(regex, `<${tagName}>${escapeXmlText(newValue)}</${tagName}>`);
+    const replacement = newValue === '' || newValue === undefined
+        ? `<${tagName}/>`
+        : `<${tagName}>${escapeXmlText(newValue)}</${tagName}>`;
+    return replaceOrThrow(xml, regex, replacement, `element <${tagName}>`);
 }
 /**
- * Replace an XML attribute on a specific element.
+ * Set an XML attribute on a specific element.
  * Example: `<pak:superPackage adtcore:name="OLD"/>` → `<pak:superPackage adtcore:name="NEW"/>`
+ *
+ * Unlike the other patches this one **adds** the attribute when the element is
+ * there without it, because that is a state ADT genuinely produces for an unset
+ * reference — probed on a live system:
+ *
+ * ```
+ * <doma:valueTableRef/>    a domain with no value table
+ * <pak:superPackage/>      a package with no parent
+ * ```
+ *
+ * Refusing those would forbid ever setting a value table or a super package for
+ * the first time. Only a missing *element* means the XML is not what the caller
+ * thinks it is, and only that throws.
+ *
+ * @throws {XmlPatchError} when the element itself is absent
  */
 function patchXmlElementAttribute(xml, elementTag, attrName, newValue) {
-    const regex = new RegExp(`(<${elementTag}[^>]*?)${attrName}="[^"]*"`);
-    return xml.replace(regex, `$1${attrName}="${escapeXmlAttr(newValue)}"`);
+    const value = escapeXmlAttr(newValue);
+    const withAttribute = new RegExp(`(<${elementTag}[^>]*?)${attrName}="[^"]*"`);
+    if (withAttribute.test(xml)) {
+        return xml.replace(withAttribute, `$1${attrName}="${value}"`);
+    }
+    const element = new RegExp(`<${elementTag}(\\s[^>]*?)?(/?)>`);
+    if (element.test(xml)) {
+        return xml.replace(element, (_match, attrs, selfClosing) => `<${elementTag}${attrs ?? ''} ${attrName}="${value}"${selfClosing}>`);
+    }
+    throw new XmlPatchError(`Cannot patch attribute ${attrName}: element <${elementTag}> is not present ` +
+        'in the XML being updated. This usually means the preceding read returned ' +
+        'an empty or partial body — ADT answers a read of a not-yet-ready object ' +
+        'with HTTP 200 and no content rather than an error.');
 }
 /**
  * Replace an entire XML block (from opening to closing tag) with new content.
  * Handles both `<tag>...</tag>` (including nested content) and self-closing `<tag/>`.
+ *
+ * @throws {XmlPatchError} when the block is absent
  */
 function patchXmlBlock(xml, tagName, newContent) {
-    const regex = new RegExp(`<${tagName}[\\s\\S]*?</${tagName}>|<${tagName}\\s*/>`);
-    return xml.replace(regex, newContent);
+    return replaceOrThrow(xml, new RegExp(`<${tagName}[\\s\\S]*?</${tagName}>|<${tagName}\\s*/>`), newContent, `block <${tagName}>`);
 }
 /**
  * Conditionally apply a patch only if value is defined.
@@ -57,12 +137,29 @@ function patchIf(xml, value, patchFn) {
     return patchFn(xml, value);
 }
 /**
- * Extract raw XML string from response data.
+ * Take the XML out of a response, refusing anything that cannot be patched.
+ *
+ * This used to `JSON.stringify` a non-string body and hand back the result,
+ * which is not XML and matches no patch — turning a bad read into a bad write
+ * one step earlier than the patches did. An empty body passed through just as
+ * quietly, and an empty body is exactly what ADT returns for an object that is
+ * not ready yet.
+ *
+ * @param what object being read, named in the error (e.g. `'domain ZAC_DOM01'`)
+ * @throws {XmlPatchError} when the body is not usable XML
  */
-function extractXmlString(data) {
-    if (typeof data === 'string')
-        return data;
-    return JSON.stringify(data);
+function extractXmlString(data, what = 'object') {
+    if (typeof data !== 'string') {
+        const kind = data === null || data === undefined ? String(data) : typeof data;
+        throw new XmlPatchError(`Cannot update ${what}: the read returned ${kind}, not XML.`);
+    }
+    const xml = data.trim();
+    if (xml === '' || !xml.startsWith('<')) {
+        throw new XmlPatchError(`Cannot update ${what}: the read returned ${xml === '' ? 'an empty body' : 'a body that is not XML'}. ` +
+            'ADT answers a read of a not-yet-ready object with HTTP 200 and no ' +
+            'content, so the status alone does not show this.');
+    }
+    return data;
 }
 /** Escape special characters for XML attribute values */
 function escapeXmlAttr(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/adt-clients",
-  "version": "10.0.2",
+  "version": "10.1.0",
   "description": "ADT clients for SAP ABAP systems - AdtClient and AdtRuntimeClient",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",