@dx-do/client 6.2.2 → 6.3.0

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 */
@@ -73721,6 +73941,18 @@ function detectIPv4() {
     }
     return '127.0.0.1';
 }
+/**
+ * Coalesce a missing *or empty* value to a fallback.
+ *
+ * `??` only catches `null`/`undefined`, but an explicit `""` is a valid string
+ * that would flow straight through. That breaks `temp_fields`: a blank component
+ * collapses one of its space-separated slots, shifting every later field's
+ * position when the SaaS Kafka consumer parses `agentbase_msg`. Treat `""`
+ * exactly like an omitted value.
+ */
+function orDefault(value, fallback) {
+    return value ? value : fallback;
+}
 /**
  * Service for querying and ingesting log analytics data.
  */
@@ -73749,14 +73981,17 @@ class LogsService {
         exports.LogIngest.LogIngestOptionsSchema.parse(options);
         const cohortId = this.dxSaasService.dxdoConfiguration.dxConfiguration.cohortId;
         const tenantIdUpper = cohortId.toUpperCase();
-        const logtype = options.logtype ?? 'generic';
-        const host = options.host ?? require$$0$4.hostname();
-        const ip = options.ip ?? detectIPv4();
-        const agentInstance = options.agentInstance ?? 'dx-do';
-        const agentName = options.agentName ?? 'Logs Collector';
-        const containerId = options.containerId ?? host;
-        const containerName = options.containerName ?? agentInstance;
-        const file = options.file ?? 'dx-do.cli';
+        // `orDefault` (not `??`) so an explicit empty string is treated as omitted —
+        // a blank value in any temp_fields component shifts every downstream
+        // positional field. See the temp_fields comment below.
+        const logtype = orDefault(options.logtype, 'generic');
+        const host = orDefault(options.host, require$$0$4.hostname());
+        const ip = orDefault(options.ip, detectIPv4());
+        const agentInstance = orDefault(options.agentInstance, 'dx-do');
+        const agentName = orDefault(options.agentName, 'Logs Collector');
+        const containerId = orDefault(options.containerId, host);
+        const containerName = orDefault(options.containerName, agentInstance);
+        const file = orDefault(options.file, 'dx-do.cli');
         const tag = `${logtype} logs`;
         // temp_fields must have exactly 9 space-separated components before the message
         // is appended by the SaaS filter (agentbase_msg = temp_fields + " " + message).
@@ -75427,19 +75662,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) {
@@ -75529,12 +75835,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 });