@dx-do/client 6.2.3 → 6.3.1

package/dist/index.cjs.js

@@ -45995,6 +45995,226 @@ exports.OIAlarm = void 0;
     };
 })(exports.OIAlarm || (exports.OIAlarm = {}));
 
+/**
+ * The `service export` / `service export-hierarchy` file format and the
+ * `service import` boundary validator.
+ *
+ * The envelope wraps a re-postable store body ({@link CreateServices.CreateServiceBody})
+ * with provenance metadata. `import` accepts either the envelope or a bare body.
+ */
+exports.ServiceExport = void 0;
+(function (ServiceExport) {
+    ServiceExport.SCHEMA_VERSION = 1;
+    // Structural guard for a store body — does not re-validate every field
+    // (the server is the authority); just enough to reject obviously-wrong files.
+    const BodyShape = v4.z.looseObject({
+        vertices: v4.z.array(v4.z.looseObject({ attributes: v4.z.looseObject({ name: v4.z.string() }) })),
+        edges: v4.z.array(v4.z.looseObject({
+            sourceExternalId: v4.z.string(),
+            targetExternalId: v4.z.string(),
+        })),
+    });
+    const EnvelopeShape = v4.z.looseObject({
+        schemaVersion: v4.z.literal(1),
+        kind: v4.z.enum(['service', 'service-hierarchy']),
+        sourceTenant: v4.z.string().optional(),
+        exportedAt: v4.z.string(),
+        body: BodyShape,
+    });
+    /** Wrap a store body in an export envelope. */
+    function envelope(kind, body, sourceTenant, exportedAt) {
+        return { schemaVersion: ServiceExport.SCHEMA_VERSION, kind, sourceTenant, exportedAt, body };
+    }
+    ServiceExport.envelope = envelope;
+    /**
+     * Validate an import file (already JSON-parsed) and return the store body.
+     * Accepts a full export envelope or a bare `{ vertices, edges }` body.
+     * @throws Error when the input is neither shape.
+     */
+    function parseImport(raw) {
+        const asEnvelope = EnvelopeShape.safeParse(raw);
+        if (asEnvelope.success) {
+            return asEnvelope.data.body;
+        }
+        const asBody = BodyShape.safeParse(raw);
+        if (asBody.success) {
+            return raw;
+        }
+        throw new Error('Import file is neither a service export envelope nor a bare {vertices, edges} body. ' +
+            `Envelope error: ${asEnvelope.error.message}`);
+    }
+    ServiceExport.parseImport = parseImport;
+})(exports.ServiceExport || (exports.ServiceExport = {}));
+
+/**
+ * Pure (HTTP-free) transforms between the Service read shapes and the store
+ * (`/oi/v2/sa/save`) body. Kept separate from {@link ServiceService} so the
+ * edge/weight logic — the part with real correctness risk — is unit-testable.
+ *
+ * Empirical constraints these helpers encode (see plan Phase 0):
+ * - A parent's direct-child health/risk weights must each total ≤ 1.0 (server rejects otherwise).
+ * - `replace=true` makes each saved vertex's outgoing-edge set authoritative, so a
+ *   faithful re-save must carry the whole subtree's vertices + edges.
+ */
+exports.ServiceTransform = void 0;
+(function (ServiceTransform) {
+    /**
+     * Convert a retrieved (read) service vertex into a re-postable store vertex.
+     *
+     * @remarks externalId is keyed by the service **name**, not the server
+     * `SA:<uuid>` id. The store API treats `externalId` as a payload-local handle
+     * and resolves/creates services by `attributes.name`; keying edges by `SA:uuid`
+     * makes the server silently drop them (so a `replace` save wipes the existing
+     * edges and re-adds nothing). Names are tenant-unique, so this is unambiguous
+     * and also makes exports portable across tenants.
+     */
+    function retrievedToServiceVertex(v) {
+        const a = v.attributes;
+        return {
+            externalId: a.name,
+            attributes: {
+                type: 'saService',
+                name: a.name,
+                state: 'ACTIVE',
+                maintenance: a.maintenance ?? false,
+                situationsIncludeChildServices: a.situationsIncludeChildServices ?? false,
+                serviceContent: a.serviceContent ?? [],
+                root_service: null,
+                tags: a.tags ?? [],
+                location: a.location ?? '',
+                description: a.description ?? '',
+                customProperties: a.customProperties ?? [],
+                customMetrics: a.customMetrics ?? [],
+                metrics: a.metrics ?? [],
+            },
+        };
+    }
+    ServiceTransform.retrievedToServiceVertex = retrievedToServiceVertex;
+    /**
+     * Build NAME-keyed store edges from a topology graph, preserving weights +
+     * semantic. Endpoints are mapped from `SA:<uuid>` to service name via the
+     * graph's vertices; edges whose endpoints aren't in `topo.vertices` are
+     * dropped — this is exactly the incoming edge(s) from the root's parent, which
+     * `saTopologyGraph` returns without the parent vertex (and which must not be
+     * re-posted: the parent isn't re-saved, so its edge survives anyway).
+     */
+    function edgesFromTopology(topo) {
+        const idToName = new Map(topo.vertices.map((v) => [v.externalId, v.attributes.name]));
+        return topo.edges
+            .map((e) => ({
+            s: idToName.get(e.sourceExternalId),
+            t: idToName.get(e.targetExternalId),
+            e,
+        }))
+            .filter((x) => x.s !== undefined && x.t !== undefined)
+            .map((x) => ({
+            sourceExternalId: x.s,
+            targetExternalId: x.t,
+            attributes: {
+                health_weight: x.e.attributes?.health_weight ?? 1,
+                risk_weight: x.e.attributes?.risk_weight ?? 1,
+                semantic: 'AggregateOf',
+            },
+        }));
+    }
+    ServiceTransform.edgesFromTopology = edgesFromTopology;
+    /** Merge two store bodies, de-duplicating vertices by externalId and edges by endpoints. */
+    function mergeBodies(a, b) {
+        const vertices = [];
+        const seenV = new Set();
+        for (const v of [...a.vertices, ...b.vertices]) {
+            const key = v.externalId ?? v.attributes.name;
+            if (!seenV.has(key)) {
+                seenV.add(key);
+                vertices.push(v);
+            }
+        }
+        const edges = [];
+        const seenE = new Set();
+        for (const e of [...a.edges, ...b.edges]) {
+            const key = `${e.sourceExternalId}|${e.targetExternalId}`;
+            if (!seenE.has(key)) {
+                seenE.add(key);
+                edges.push(e);
+            }
+        }
+        return { vertices, edges };
+    }
+    ServiceTransform.mergeBodies = mergeBodies;
+    /** Insert or update the parent→child edge with the given weights. */
+    function upsertEdge(edges, source, target, healthWeight, riskWeight) {
+        const next = edges.filter((e) => !(e.sourceExternalId === source && e.targetExternalId === target));
+        next.push({
+            sourceExternalId: source,
+            targetExternalId: target,
+            attributes: {
+                health_weight: healthWeight,
+                risk_weight: riskWeight,
+                semantic: 'AggregateOf',
+            },
+        });
+        return next;
+    }
+    ServiceTransform.upsertEdge = upsertEdge;
+    /** Remove the parent→child edge. */
+    function removeEdge(edges, source, target) {
+        return edges.filter((e) => !(e.sourceExternalId === source && e.targetExternalId === target));
+    }
+    ServiceTransform.removeEdge = removeEdge;
+    /** Edges whose source is the given parent (its direct-child associations). */
+    function childEdges(edges, parent) {
+        return edges.filter((e) => e.sourceExternalId === parent);
+    }
+    ServiceTransform.childEdges = childEdges;
+    /**
+     * Keep only edges whose BOTH endpoints are in the given vertex-id set.
+     *
+     * `saTopologyGraph(root)` returns the root's subtree plus the *incoming* edge(s)
+     * from the root's parent(s) — but not the parent vertices. Re-posting such a
+     * dangling edge is rejected ("vertex referenced by edge is not present in the
+     * input graph"). Dropping it is also correct: the parent is not re-saved, so its
+     * edge to the root is preserved server-side (replace is destructive only per
+     * saved vertex).
+     */
+    function filterEdgesToVertices(edges, vertexIds) {
+        return edges.filter((e) => vertexIds.has(e.sourceExternalId) && vertexIds.has(e.targetExternalId));
+    }
+    ServiceTransform.filterEdgesToVertices = filterEdgesToVertices;
+    /**
+     * Evenly distribute a parent's direct-child weights so each total is ≤ 1.0.
+     * Uses floored thirds (e.g. 3 children → 0.333 each, sum 0.999) to avoid
+     * float drift pushing the total over 100%.
+     */
+    function rebalanceChildren(edges, parent) {
+        const kids = childEdges(edges, parent);
+        if (kids.length === 0)
+            return edges;
+        const w = Math.floor((1 / kids.length) * 1000) / 1000;
+        return edges.map((e) => e.sourceExternalId === parent
+            ? {
+                ...e,
+                attributes: {
+                    health_weight: w,
+                    risk_weight: w,
+                    semantic: 'AggregateOf',
+                },
+            }
+            : e);
+    }
+    ServiceTransform.rebalanceChildren = rebalanceChildren;
+    /** Throw if a parent's direct-child weights exceed 100% (the server's hard limit). */
+    function assertWeightsWithinLimit(edges, parent) {
+        const kids = childEdges(edges, parent);
+        const health = kids.reduce((s, e) => s + (e.attributes?.health_weight ?? 0), 0);
+        const risk = kids.reduce((s, e) => s + (e.attributes?.risk_weight ?? 0), 0);
+        const eps = 1e-6;
+        if (health > 1 + eps || risk > 1 + eps) {
+            throw new Error(`Weight total for parent exceeds 100% (health=${health.toFixed(3)}, risk=${risk.toFixed(3)}). Lower the weights or omit them to auto-distribute evenly.`);
+        }
+    }
+    ServiceTransform.assertWeightsWithinLimit = assertWeightsWithinLimit;
+})(exports.ServiceTransform || (exports.ServiceTransform = {}));
+
 exports.OIService = void 0;
 (function (OIService) {
     /** @internal */
@@ -46466,6 +46686,94 @@ exports.OIService = void 0;
     };
 })(exports.OIService || (exports.OIService = {}));
 
+/**
+ * The `ess/users/v2/list` user-account listing.
+ *
+ * Hand-modelled from observed responses (no published schema): every field is
+ * inferred from live data across multiple tenants. `looseObject` is used
+ * throughout so undocumented server fields are tolerated rather than dropped or
+ * rejected, and single-observation fields (e.g. {@link UserSchema.shape.authMethod})
+ * are kept as plain strings rather than locked enums.
+ */
+exports.OIUsersV2 = void 0;
+(function (OIUsersV2) {
+    /** One email address attached to a user. */
+    OIUsersV2.EmailIdSchema = v4.z.looseObject({
+        emailAddr: v4.z.string().describe('the email address'),
+        qualifier: v4.z
+            .string()
+            .describe('email category; only "EMAILID" observed in live data'),
+    });
+    /** The user's assigned role. */
+    OIUsersV2.RoleSchema = v4.z.looseObject({
+        name: v4.z
+            .string()
+            .describe('role identifier, e.g. "VIEW105" / "TA" / "PU" / "UZ"'),
+        privileges: v4.z
+            .array(v4.z.unknown())
+            .describe('granted privilege entries; empty in all observed data'),
+        level: v4.z.number().describe('role level; 0 in all observed data'),
+    });
+    /** A single user account. */
+    OIUsersV2.UserSchema = v4.z.looseObject({
+        userRefID: v4.z.number().describe('numeric internal user reference id'),
+        userId: v4.z
+            .string()
+            .describe('login principal; usually the email address upper-cased'),
+        cohort: v4.z
+            .string()
+            .describe('per-user cohort id in dashed, upper-cased GUID form'),
+        firstName: v4.z.string().describe('given name'),
+        lastName: v4.z
+            .string()
+            .optional()
+            .describe('family name; occasionally absent'),
+        statusEnum: v4.z
+            .enum(['ACTIVE', 'INACTIVE'])
+            .describe('account status; only ACTIVE/INACTIVE observed'),
+        emailIds: v4.z
+            .array(OIUsersV2.EmailIdSchema)
+            .describe('email addresses associated with the user'),
+        hasImage: v4.z.boolean().describe('whether a profile image is set'),
+        authMethod: v4.z
+            .string()
+            .describe('authentication method; only "BASIC_AUTH" observed'),
+        dateCreated: v4.z
+            .string()
+            .describe('creation timestamp, ISO-8601 with +0000 offset (not "Z")'),
+        dateModified: v4.z
+            .string()
+            .describe('last-modified timestamp, ISO-8601 with +0000 offset'),
+        startLockTime: v4.z
+            .string()
+            .optional()
+            .describe('lock-start timestamp; present only when the account is locked'),
+        internalAttrs: v4.z
+            .array(v4.z.string().nullable())
+            .describe('internal attribute slots; observed as a length-3 array of nullable strings, semantics undocumented'),
+        tenant: v4.z.string().describe('tenant id the user belongs to'),
+        lockStatus: v4.z
+            .boolean()
+            .describe('whether the account is currently locked'),
+        role: OIUsersV2.RoleSchema.describe('the assigned role'),
+        hasAllDataAccess: v4.z
+            .boolean()
+            .describe('whether the user has unrestricted data access'),
+        userType: v4.z
+            .string()
+            .optional()
+            .describe('account type; the list request filters to USER_ACCOUNT, but the field is not always echoed back'),
+        deleted: v4.z.boolean().describe('soft-delete flag'),
+    });
+    /** The list envelope: a page of users plus the server-side total. */
+    OIUsersV2.UserListResponseSchema = v4.z.looseObject({
+        countTotal: v4.z
+            .number()
+            .describe('total users matching the query on the server, for pagination'),
+        users: v4.z.array(OIUsersV2.UserSchema).describe('the returned page of users'),
+    });
+})(exports.OIUsersV2 || (exports.OIUsersV2 = {}));
+
 /** @internal */
 function createPostmanRequest(request) {
     function createPostmanHeaders(request) {
@@ -63867,6 +64175,50 @@ class AuthorizationService {
     getUsers() {
         return this.dxSaaSService.tenantGet('oi/v2/api/users');
     }
+    /**
+     * Lists users via the ESS users v2 endpoint.
+     *
+     * The path's trailing segment is the cohort id in upper-cased, dashed GUID
+     * form (e.g. `6E82C5F4-8F16-4CD9-8BF0-6263F83054D5`). `oiGet` already injects
+     * the lowercase, dash-less cohort id as the base path segment, so we rebuild
+     * the GUID form here independently of how the config stores it.
+     *
+     * The response type is hand-modelled from observed data ({@link OIUsersV2});
+     * validation is defensive (`safeParse` + `log.warn`), so a server-side shape
+     * change logs a warning but still returns the raw payload to the caller.
+     *
+     * @remarks Response is validated, not thrown — see {@link OIUsersV2}.
+     */
+    async getUsersV2(startIndex = 1, endIndex = 500) {
+        const cohortGuid = this.toGuidCohortId(this.dxSaaSService.getCohortIDForURL());
+        const raw = await this.dxSaaSService.oiGet(`ess/users/v2/list/${cohortGuid}`, {
+            cachebuster: Math.random(),
+            preventCache: Math.random(),
+            start_index: startIndex,
+            end_index: endIndex,
+            sort_by_field: 'DATEMODIFIED',
+            sort_order: 'desc',
+            user_type: 'USER_ACCOUNT',
+        });
+        const result = exports.OIUsersV2.UserListResponseSchema.safeParse(raw);
+        if (!result.success) {
+            this.log.warn('OIUsersV2 response validation warning: ' + result.error.message);
+        }
+        return raw;
+    }
+    /** Reformats a cohort id to upper-cased, dashed GUID form (`8-4-4-4-12`). */
+    toGuidCohortId(cohortId) {
+        const hex = cohortId.replace(/-/g, '').toLowerCase();
+        return [
+            hex.slice(0, 8),
+            hex.slice(8, 12),
+            hex.slice(12, 16),
+            hex.slice(16, 20),
+            hex.slice(20, 32),
+        ]
+            .join('-')
+            .toUpperCase();
+    }
 }
 
 /**
@@ -75442,19 +75794,90 @@ class ServiceService {
         };
         return this.dxSaaSService.oiPost('oi/v2/sa/serviceDetails', serviceDetailRequest);
     }
+    /**
+     * Retrieve a Service — the full read-endpoint envelope (vertices + edges +
+     * paging metadata). Backs the `service detail` and `service export` commands.
+     *
+     * @param serviceName - Service name (URL path segment).
+     * @param subservices - When true, include the service's subservices in the response.
+     */
+    async getService(serviceName, subservices = false) {
+        return this.dxSaaSService.oiGet(`oi/v2/sa/services/${serviceName}`, { subservices });
+    }
+    /**
+     * Returns the full reachable subtree (all descendants + association edges with
+     * weights) for a service via `oi/v2/sa/saTopologyGraph`. Backs the hierarchy
+     * read used by `export-hierarchy`/`associate`/`dissociate`.
+     *
+     * @remarks The documented `oi/v2/sa/service/details/hierarchy` path is not
+     * routable on the tenant gateway; this topology endpoint is the working one.
+     * Its vertex attributes are a subset — use {@link getService} per vertex when
+     * faithful re-save attributes (tags, customProperties, metrics) are needed.
+     */
+    async getServiceTopology(serviceName) {
+        return this.dxSaaSService.oiPost('oi/v2/sa/saTopologyGraph', { serviceName, startTime: Date.now(), endTime: Date.now() });
+    }
+    /**
+     * Builds a faithful, re-postable store body for a service's entire subtree:
+     * topology for structure + a per-vertex {@link getService} for full attributes
+     * (serviceContent, tags, customProperties, metrics). Shared by
+     * `export-hierarchy`, `associate`, and `dissociate`.
+     *
+     * @remarks One GET per vertex — fine for typical (small) hierarchies; reads
+     * are not throttled like saves.
+     */
+    async buildHierarchyBody(rootName) {
+        const topo = await this.getServiceTopology(rootName);
+        const names = new Set([rootName]);
+        topo.vertices.forEach((v) => names.add(v.attributes.name));
+        const vertices = [];
+        const seen = new Set();
+        for (const name of names) {
+            const full = await this.getService(name, false);
+            const fv = full.vertices[0];
+            if (fv && !seen.has(fv.externalId)) {
+                seen.add(fv.externalId);
+                vertices.push(exports.ServiceTransform.retrievedToServiceVertex(fv));
+            }
+        }
+        // Drop edges that reference vertices outside this subtree (e.g. the incoming
+        // edge from the root's parent, which saTopologyGraph returns without the
+        // parent vertex). Re-posting such a dangling edge is rejected by the server.
+        const presentIds = new Set(vertices
+            .map((v) => v.externalId)
+            .filter((id) => id !== undefined));
+        const edges = exports.ServiceTransform.filterEdgesToVertices(exports.ServiceTransform.edgesFromTopology(topo), presentIds);
+        return { vertices, edges };
+    }
+    /** Builds a single-service store body (no edges) for `service export`. */
+    async exportServiceBody(serviceName) {
+        const r = await this.getService(serviceName, false);
+        if (!r.vertices.length) {
+            throw new Error(`No service with name '${serviceName}' found`);
+        }
+        return {
+            vertices: [exports.ServiceTransform.retrievedToServiceVertex(r.vertices[0])],
+            edges: [],
+        };
+    }
+    /**
+     * Resolves a service's server externalId (`SA:<cohort>:<uuid>`).
+     * @throws Error if the service does not exist.
+     */
+    async getServiceExternalId(serviceName) {
+        const r = await this.getService(serviceName, false);
+        const id = r.vertices[0]?.externalId;
+        if (!id)
+            throw new Error(`No service with name '${serviceName}' found`);
+        return id;
+    }
     /** Returns the overview vertex for a named service; throws if not found. */
     async getServiceOverview(serviceName) {
-        return this.dxSaaSService
-            .oiGet(`oi/v2/sa/services/${serviceName}`, {
-            subservices: false,
-        })
-            .then((graph) => {
-            if (graph.vertices.length == 1) {
-                return graph.vertices[0];
-            }
-            else
-                throw new Error(`No Service with name '${serviceName}' Found`);
-        });
+        const response = await this.getService(serviceName, false);
+        if (response.vertices.length === 1) {
+            return response.vertices[0];
+        }
+        throw new Error(`No Service with name '${serviceName}' Found`);
     }
     /** Returns paginated top-level (grouped) services up to `maxRequests` pages. */
     async getTopLevelServices(pageSize = 100, maxRequests = 20) {
@@ -75544,12 +75967,109 @@ class ServiceService {
         sirb.customFilter.and.expressions[0].or.expressions[0].value = serviceName;
         return sirb;
     }
-    /** Creates a new service from the given body; replaces any existing service with the same name. */
-    async createService(createServiceBody) {
-        return this.dxSaaSService.tenantPost('/oi/v2/sa/save', createServiceBody, {
+    /**
+     * Creates/updates one or more services via the store API (`/oi/v2/sa/save`).
+     *
+     * @remarks Edges not present in the payload are removed for the services it
+     * covers — the store API treats the supplied edge set as authoritative.
+     * @param createServiceBody - vertices + edges to store.
+     * @param opts.replace - When true (default), replaces an existing service of the
+     *   same name rather than erroring.
+     * @param opts.autoWeight - When true, the server computes edge health/risk weights,
+     *   overriding any weights supplied in the payload. Omitted by default.
+     */
+    async createService(createServiceBody, opts = {}) {
+        const params = { replace: opts.replace ?? true };
+        if (opts.autoWeight !== undefined) {
+            params['auto_weight'] = opts.autoWeight;
+        }
+        return this.dxSaaSService.tenantPost('/oi/v2/sa/save', createServiceBody, params);
+    }
+    /**
+     * Builds the store body for associating `childName` under `parentName` as a
+     * new `AggregateOf` child, WITHOUT saving (so callers can dry-run it).
+     *
+     * Because `replace=true` makes each saved vertex's edge set authoritative, the
+     * body carries both services' full subtrees. Weights: explicit
+     * `healthWeight`/`riskWeight` are applied to the new edge and validated against
+     * the ≤100% limit; otherwise the parent's direct children are evenly rebalanced.
+     */
+    async buildAssociateBody(parentName, childName, opts = {}) {
+        if (parentName === childName) {
+            throw new Error(`A service cannot be associated with itself ('${parentName}')`);
+        }
+        // Validate both services exist (throws "No service with name … found").
+        await this.getServiceExternalId(parentName);
+        await this.getServiceExternalId(childName);
+        // Bodies are keyed by service name (see ServiceTransform.retrievedToServiceVertex).
+        const body = exports.ServiceTransform.mergeBodies(await this.buildHierarchyBody(parentName), await this.buildHierarchyBody(childName));
+        const explicit = opts.healthWeight !== undefined || opts.riskWeight !== undefined;
+        body.edges = exports.ServiceTransform.upsertEdge(body.edges, parentName, childName, opts.healthWeight ?? 1, opts.riskWeight ?? 1);
+        if (explicit) {
+            exports.ServiceTransform.assertWeightsWithinLimit(body.edges, parentName);
+        }
+        else {
+            body.edges = exports.ServiceTransform.rebalanceChildren(body.edges, parentName);
+        }
+        return body;
+    }
+    /** Associates `childName` under `parentName` and saves it. See {@link buildAssociateBody}. */
+    async associateServices(parentName, childName, opts = {}) {
+        const body = await this.buildAssociateBody(parentName, childName, opts);
+        return this.createService(body, {
             replace: true,
+            autoWeight: opts.autoWeight,
         });
     }
+    /**
+     * Builds the store body for removing the `parentName`→`childName` association,
+     * WITHOUT saving. The child (and its own subtree) is preserved as a now-detached
+     * service.
+     * @throws Error if `childName` is not a direct child of `parentName`.
+     */
+    async buildDissociateBody(parentName, childName) {
+        // Validate both services exist (throws "No service with name … found").
+        await this.getServiceExternalId(parentName);
+        await this.getServiceExternalId(childName);
+        const body = await this.buildHierarchyBody(parentName);
+        const before = body.edges.length;
+        body.edges = exports.ServiceTransform.removeEdge(body.edges, parentName, childName);
+        if (body.edges.length === before) {
+            throw new Error(`'${childName}' is not a direct child of '${parentName}' — nothing to dissociate`);
+        }
+        return body;
+    }
+    /** Removes the `parentName`→`childName` association and saves it. See {@link buildDissociateBody}. */
+    async dissociateServices(parentName, childName) {
+        const body = await this.buildDissociateBody(parentName, childName);
+        return this.createService(body, { replace: true });
+    }
+    /**
+     * Builds the store body for updating a service's content queries, WITHOUT
+     * saving. Re-saves the service's full subtree (via {@link buildHierarchyBody})
+     * so its children edges are preserved — only the target vertex's
+     * `serviceContent` changes.
+     *
+     * @param mode - 'set' replaces the content; 'add' appends to the existing content.
+     * @returns the store body plus the service's previous content (for diffing).
+     * @throws Error if the service does not exist.
+     */
+    async buildServiceContentBody(serviceName, newContent, mode) {
+        const body = await this.buildHierarchyBody(serviceName);
+        const target = body.vertices.find((v) => v.attributes.name === serviceName);
+        if (!target) {
+            throw new Error(`No service with name '${serviceName}' found`);
+        }
+        const previousContent = target.attributes.serviceContent;
+        target.attributes.serviceContent =
+            mode === 'set' ? newContent : [...previousContent, ...newContent];
+        return { body, previousContent };
+    }
+    /** Updates a service's content queries and saves it. See {@link buildServiceContentBody}. */
+    async updateServiceContent(serviceName, newContent, mode) {
+        const { body } = await this.buildServiceContentBody(serviceName, newContent, mode);
+        return this.createService(body, { replace: true });
+    }
     /** Deletes a service by name; optionally deletes child services recursively. */
     async deleteService(serviceName, recursive = false) {
         return this.dxSaaSService.tenantPost('/oi/v2/sa/service/status', { name: serviceName, action: 'delete' }, { recursive });