@ffschrattenecker/tm1-mcp-server 7.0.1 → 8.0.0

package/dist/tm1-client/services/file-service.js

@@ -1,9 +1,6 @@
 import { TM1Error, TM1ErrorCode } from "../../types.js";
 import { rethrowIfSystemic } from "./fallback.js";
-// OData entity-key encoder: double single quotes per OData literal rules, then
-// percent-encode. Without the doubling a name containing ' breaks the key and
-// makes the object unreachable.
-const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+import { escapeOdataLiteral, odataKey } from "./odata-page.js";
 // Split a user-supplied file path into segments, rejecting "." / ".." so a
 // crafted name cannot traverse outside the Contents root.
 function splitPath(raw) {
@@ -17,23 +14,112 @@ function splitPath(raw) {
     }
     return parts;
 }
+const APPS_ROOT = "/api/v1/Contents('Applications')";
+const DOCUMENT_REFERENCE = "ibm.tm1.api.v1.DocumentReference";
 export class FileService {
     http;
     constructor(http) {
         this.http = http;
     }
+    /**
+     * Entries directly under an Applications URL.
+     *
+     * Follows `@odata.nextLink` if the server sends one. Whether these builds
+     * page this endpoint at all was not observed; a missed page here would not
+     * just shorten a listing, it would make name resolution answer NOT_FOUND for
+     * an entry that exists, so the loop runs either way.
+     */
+    async appsChildren(url) {
+        const entries = [];
+        // v12 leaves `ID` out of this listing unless it is selected (v11 always
+        // sends it); without it every entry resolved to Contents('undefined').
+        let next = `${url}/Contents?$select=ID,Name`;
+        while (next) {
+            const r = await this.http.request("GET", next);
+            for (const e of r.value) {
+                entries.push({
+                    id: e.ID,
+                    name: e.Name,
+                    kind: e["@odata.type"].split(".").pop() ?? "",
+                });
+            }
+            const link = r["@odata.nextLink"];
+            // A nextLink may be absolute. Reduce it to a path: `request` prepends the
+            // base URL. Its v12 rerooting only rewrites a leading `/api/v1`, which a
+            // server-built link no longer carries, so it passes through untouched.
+            next = link?.startsWith("http")
+                ? new URL(link).pathname + new URL(link).search
+                : link;
+        }
+        return entries;
+    }
+    /**
+     * Walk name segments down the Applications tree, one listing per level.
+     *
+     * Costs a request per segment, which the depth of this tree makes cheap, and
+     * buys two things a derived key cannot: the entry's real ID whatever the
+     * server's naming rule is, and its type — so a caller asking for the bytes of
+     * a ViewReference gets told what it actually hit.
+     */
+    async appsResolve(segments) {
+        let url = APPS_ROOT;
+        let entry;
+        for (const seg of segments) {
+            const children = await this.appsChildren(url);
+            const lower = seg.toLowerCase();
+            const hit = children.find((c) => c.name.toLowerCase() === lower) ??
+                // A listing hands documents back under their name, but an ID pasted
+                // straight from a previous response has to keep working too.
+                children.find((c) => c.id.toLowerCase() === lower);
+            if (!hit) {
+                throw new TM1Error({
+                    code: TM1ErrorCode.NOT_FOUND,
+                    message: `'${seg}' not found in the Applications tree`,
+                    endpoint: url,
+                });
+            }
+            url += `/Contents('${odataKey(hit.id)}')`;
+            entry = hit;
+        }
+        return { url, entry };
+    }
+    /** URL of the bytes behind a DocumentReference, or a typed refusal. */
+    appsContentUrl(url, entry) {
+        if (entry === undefined) {
+            throw new TM1Error({
+                code: TM1ErrorCode.VALIDATION_ERROR,
+                message: "The Applications root is not a file",
+                endpoint: url,
+            });
+        }
+        if (entry.kind !== "DocumentReference") {
+            throw new TM1Error({
+                code: TM1ErrorCode.UNSUPPORTED_OPERATION,
+                message: `'${entry.name}' is a ${entry.kind}, which carries no file content`,
+                hint: entry.kind === "Folder"
+                    ? "List it instead — tm1_list_files with container='applications' and this path."
+                    : "Only documents hold bytes. A ViewReference points at a cube view; read it with tm1_get_view.",
+                endpoint: url,
+            });
+        }
+        return `${url}/${DOCUMENT_REFERENCE}/Document/Content`;
+    }
     /**
      * List files in TM1 server's blob/file storage.
      * v12: GET /api/v1/Contents('Files')[/Contents('subdir')...]/Contents?$select=Name
      * v11: same with 'Blobs' instead of 'Files'.
      * Tries v12 'Files' first, falls back to v11 'Blobs'.
      */
-    async list(path) {
+    async list(path, container = "files") {
         const segments = path ? splitPath(path) : [];
+        if (container === "applications") {
+            const { url } = await this.appsResolve(segments);
+            return (await this.appsChildren(url)).map((e) => e.name);
+        }
         const buildUrl = (root) => {
-            let url = `/api/v1/Contents('${enc(root)}')`;
+            let url = `/api/v1/Contents('${odataKey(root)}')`;
             for (const seg of segments) {
-                url += `/Contents('${enc(seg)}')`;
+                url += `/Contents('${odataKey(seg)}')`;
             }
             url += "/Contents?$select=Name";
             return url;
@@ -53,22 +139,33 @@ export class FileService {
      * Returns raw text (CSV/TXT/etc).
      * Tries v12 'Files' first, falls back to v11 'Blobs'.
      */
-    async getContent(fileName) {
+    async getContent(fileName, container = "files") {
+        return (await this.getContentBytes(fileName, container)).toString("utf8");
+    }
+    /**
+     * The same read, byte-for-byte. The Applications tree holds spreadsheets and
+     * other binaries, which a UTF-8 decode would quietly destroy.
+     */
+    async getContentBytes(fileName, container = "files") {
         const parts = splitPath(fileName);
+        if (container === "applications") {
+            const { url, entry } = await this.appsResolve(parts);
+            return this.http.requestRawBytes("GET", this.appsContentUrl(url, entry));
+        }
         const buildUrl = (root) => {
-            let url = `/api/v1/Contents('${enc(root)}')`;
+            let url = `/api/v1/Contents('${odataKey(root)}')`;
             for (const p of parts) {
-                url += `/Contents('${enc(p)}')`;
+                url += `/Contents('${odataKey(p)}')`;
             }
             url += "/Content";
             return url;
         };
         try {
-            return await this.http.requestRaw("GET", buildUrl("Files"));
+            return await this.http.requestRawBytes("GET", buildUrl("Files"));
         }
         catch (e) {
             rethrowIfSystemic(e);
-            return await this.http.requestRaw("GET", buildUrl("Blobs"));
+            return await this.http.requestRawBytes("GET", buildUrl("Blobs"));
         }
     }
     /**
@@ -76,18 +173,28 @@ export class FileService {
      * Implemented as a cheap GET on the entity ($select=Name) — TM1 REST does
      * not expose HEAD on these. 404 → false; other errors propagate.
      */
-    async exists(fileName) {
+    async exists(fileName, container = "files") {
         const parts = splitPath(fileName);
         if (parts.length === 0)
             return false;
+        if (container === "applications") {
+            try {
+                return (await this.appsResolve(parts)).entry !== undefined;
+            }
+            catch (e) {
+                if (e.code === "NOT_FOUND")
+                    return false;
+                throw e;
+            }
+        }
         const buildUrl = (root) => {
             const segs = parts
                 .slice(0, -1)
-                .map((s) => `/Contents('${enc(s)}')`)
+                .map((s) => `/Contents('${odataKey(s)}')`)
                 .join("");
             // parts.length > 0 is guarded above
             const last = parts[parts.length - 1];
-            return `/api/v1/Contents('${enc(root)}')${segs}/Contents('${enc(last)}')?$select=Name`;
+            return `/api/v1/Contents('${odataKey(root)}')${segs}/Contents('${odataKey(last)}')?$select=Name`;
         };
         const probe = async (url) => {
             try {
@@ -114,7 +221,7 @@ export class FileService {
      * Subfolders only supported on TM1 v12. Caller must ensure parent folders
      * exist (folder-create not yet exposed).
      */
-    async upload(fileName, content) {
+    async upload(fileName, content, container = "files") {
         const parts = splitPath(fileName);
         if (parts.length === 0) {
             throw new TM1Error({
@@ -122,15 +229,17 @@ export class FileService {
                 message: "upload: empty file name",
             });
         }
+        if (container === "applications")
+            return this.uploadToApplications(parts, content);
         // parts.length > 0 is guarded above
         const leaf = parts[parts.length - 1];
         const parentSegs = parts
             .slice(0, -1)
-            .map((s) => `/Contents('${enc(s)}')`)
+            .map((s) => `/Contents('${odataKey(s)}')`)
             .join("");
         const tryRoot = async (root) => {
-            const parentUrl = `/api/v1/Contents('${enc(root)}')${parentSegs}/Contents`;
-            const contentUrl = `/api/v1/Contents('${enc(root)}')${parentSegs}/Contents('${enc(leaf)}')/Content`;
+            const parentUrl = `/api/v1/Contents('${odataKey(root)}')${parentSegs}/Contents`;
+            const contentUrl = `/api/v1/Contents('${odataKey(root)}')${parentSegs}/Contents('${odataKey(leaf)}')/Content`;
             const existed = await this.exists(fileName).catch(() => false);
             if (!existed) {
                 await this.http.request("POST", parentUrl, {
@@ -139,7 +248,19 @@ export class FileService {
                     Name: leaf,
                 });
             }
-            await this.http.requestBinary("PUT", contentUrl, content);
+            try {
+                await this.http.requestBinary("PUT", contentUrl, content);
+            }
+            catch (e) {
+                // Same two-request split as the Applications path: an entry this call
+                // created and could not fill is removed again, so a failed upload does
+                // not leave an empty file under the name.
+                if (!existed) {
+                    const url = `/api/v1/Contents('${odataKey(root)}')${parentSegs}/Contents('${odataKey(leaf)}')`;
+                    await this.http.request("DELETE", url).catch(() => undefined);
+                }
+                throw e;
+            }
             return { created: !existed, root };
         };
         try {
@@ -155,7 +276,7 @@ export class FileService {
     /**
      * Delete a file from blob/file storage. Tries 'Files' first, then 'Blobs'.
      */
-    async delete(fileName) {
+    async delete(fileName, container = "files") {
         const parts = splitPath(fileName);
         if (parts.length === 0) {
             throw new TM1Error({
@@ -163,9 +284,28 @@ export class FileService {
                 message: "delete: empty file name",
             });
         }
+        if (container === "applications") {
+            const { url, entry } = await this.appsResolve(parts);
+            // DELETE on a folder takes everything under it with it (see the header
+            // note). This is the single-file contract, so anything that is not a
+            // document is refused here rather than at the server, where it would
+            // already be gone.
+            if (entry !== undefined && entry.kind !== "DocumentReference") {
+                throw new TM1Error({
+                    code: TM1ErrorCode.UNSUPPORTED_OPERATION,
+                    message: `'${entry.name}' is a ${entry.kind}, not a file — refusing to delete it`,
+                    hint: entry.kind === "Folder"
+                        ? "Deleting a folder would delete everything inside it, which this tool does not do. Delete the entries individually, or remove the folder in Architect/PAW."
+                        : "Only documents can be deleted here. A ViewReference points at a cube view; remove it with tm1_delete_view.",
+                    endpoint: url,
+                });
+            }
+            await this.http.request("DELETE", url);
+            return;
+        }
         const buildUrl = (root) => {
-            const segs = parts.map((s) => `/Contents('${enc(s)}')`).join("");
-            return `/api/v1/Contents('${enc(root)}')${segs}`;
+            const segs = parts.map((s) => `/Contents('${odataKey(s)}')`).join("");
+            return `/api/v1/Contents('${odataKey(root)}')${segs}`;
         };
         try {
             await this.http.request("DELETE", buildUrl("Files"));
@@ -185,22 +325,39 @@ export class FileService {
     async search(opts) {
         const operator = opts.operator ?? "and";
         const segments = opts.path ? splitPath(opts.path) : [];
-        const escape = (s) => s.replace(/'/g, "''");
+        if (opts.container === "applications") {
+            // Filtered client-side: the $filter push-down is measured for Blobs, not
+            // for this tree, and an Applications folder holds tens of entries, not
+            // thousands. Same matching rules as the server-side clauses below.
+            const names = await this.list(opts.path, "applications");
+            const starts = opts.startswith?.toLowerCase();
+            const subs = (opts.contains ?? []).map((c) => c.toLowerCase());
+            return names.filter((n) => {
+                const low = n.toLowerCase();
+                if (starts !== undefined && !low.startsWith(starts))
+                    return false;
+                if (subs.length === 0)
+                    return true;
+                return operator === "or"
+                    ? subs.some((c) => low.includes(c))
+                    : subs.every((c) => low.includes(c));
+            });
+        }
         const filters = [];
         if (opts.startswith) {
-            filters.push(`startswith(tolower(Name),tolower('${escape(opts.startswith)}'))`);
+            filters.push(`startswith(tolower(Name),tolower('${escapeOdataLiteral(opts.startswith)}'))`);
         }
         if (opts.contains && opts.contains.length > 0) {
-            const subs = opts.contains.map((s) => `contains(tolower(Name),tolower('${escape(s)}'))`);
+            const subs = opts.contains.map((s) => `contains(tolower(Name),tolower('${escapeOdataLiteral(s)}'))`);
             filters.push(`(${subs.join(` ${operator} `)})`);
         }
         const filter = filters.length > 0
             ? `&$filter=${encodeURIComponent(filters.join(" and "))}`
             : "";
         const buildUrl = (root) => {
-            let url = `/api/v1/Contents('${enc(root)}')`;
+            let url = `/api/v1/Contents('${odataKey(root)}')`;
             for (const seg of segments)
-                url += `/Contents('${enc(seg)}')`;
+                url += `/Contents('${odataKey(seg)}')`;
             url += `/Contents?$select=Name${filter}`;
             return url;
         };
@@ -214,5 +371,45 @@ export class FileService {
             return r.value.map((f) => f.Name);
         }
     }
+    /**
+     * Create-or-update a document in the Applications tree.
+     *
+     * Three steps, each one measured: POST the entity WITHOUT Content (inlining
+     * it is refused — the property is a stream), re-resolve to learn the ID the
+     * server assigned, then PUT the bytes behind the cast.
+     */
+    async uploadToApplications(parts, content) {
+        const leaf = parts[parts.length - 1];
+        const parentParts = parts.slice(0, -1);
+        const { url: parentUrl } = await this.appsResolve(parentParts);
+        const existing = (await this.appsChildren(parentUrl)).find((e) => e.name.toLowerCase() === leaf.toLowerCase());
+        if (existing !== undefined && existing.kind !== "DocumentReference") {
+            throw new TM1Error({
+                code: TM1ErrorCode.UNSUPPORTED_OPERATION,
+                message: `'${leaf}' already exists as a ${existing.kind} and is not a document`,
+                endpoint: parentUrl,
+            });
+        }
+        if (existing === undefined) {
+            await this.http.request("POST", `${parentUrl}/Contents`, {
+                "@odata.type": "#ibm.tm1.api.v1.Document",
+                Name: leaf,
+            });
+        }
+        const { url, entry } = await this.appsResolve([...parentParts, leaf]);
+        try {
+            await this.http.requestBinary("PUT", this.appsContentUrl(url, entry), content);
+        }
+        catch (e) {
+            // Create and write are two requests. If the write fails on an entry this
+            // call created, take it back out — leaving an empty document behind would
+            // report a failed upload while the name now exists.
+            if (existing === undefined) {
+                await this.http.request("DELETE", url).catch(() => undefined);
+            }
+            throw e;
+        }
+        return { created: existing === undefined, root: "Applications" };
+    }
 }
 //# sourceMappingURL=file-service.js.map

package/dist/tm1-client/services/hierarchy-service.d.ts

@@ -1,5 +1,14 @@
 import type { Hierarchy, HierarchyElement } from "../../types.js";
 import type { TM1HttpClient } from "../http.js";
+interface DescendantsResult {
+    element: string;
+    descendants: Array<{
+        name: string;
+        type: HierarchyElement["type"];
+        level: number;
+        depth: number;
+    }>;
+}
 /**
  * A hierarchy plus the size of the element set the request selected, so
  * callers can page without guessing. `totalElements` counts elements that
@@ -93,15 +102,8 @@ export declare class HierarchyService {
     getDescendants(dimensionName: string, hierarchyName: string, element: string, opts?: {
         depth?: number;
         leavesOnly?: boolean;
-    }): Promise<{
-        element: string;
-        descendants: Array<{
-            name: string;
-            type: HierarchyElement["type"];
-            level: number;
-            depth: number;
-        }>;
-    }>;
+    }): Promise<DescendantsResult>;
+    private getDescendantsFromFull;
     /**
      * Resolve ancestors of an element via parent-walk. Handles multi-parent
      * hierarchies — returns the unique flat ancestor set AND every distinct
@@ -115,6 +117,13 @@ export declare class HierarchyService {
         }>;
         paths: string[][];
     }>;
+    /**
+     * One element with a navigation property expanded `levels` deep. Nodes on
+     * the last level come back without that property, which is how callers see
+     * where the request stopped.
+     */
+    private getNested;
+    private getAncestorsFromFull;
     /**
      * Create a new hierarchy inside an existing dimension.
      * POST /api/v1/Dimensions('{d}')/Hierarchies
@@ -126,4 +135,5 @@ export declare class HierarchyService {
      */
     delete(dimensionName: string, hierarchyName: string): Promise<void>;
 }
+export {};
 //# sourceMappingURL=hierarchy-service.d.ts.map

package/dist/tm1-client/services/hierarchy-service.js

@@ -4,9 +4,10 @@
 // client-side. See docs/ARCHITECTURE.md for the layering.
 import { TM1Error, TM1ErrorCode } from "../../types.js";
 import { compileUserRegex } from "../../lib/safe-regex.js";
-import { pageClauseList, readNestedCount } from "./odata-page.js";
-// OData key encoder: double ' per OData literal rules, then percent-encode.
-const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+import { escapeOdataLiteral, odataKey, pageClauseList, readNestedCount, } from "./odata-page.js";
+// How many levels one nested $expand reaches. TM1 answered 20 on 11.8 and
+// 12.5; a hierarchy deeper than that falls back to the full load.
+const NEST_LEVELS = 20;
 // elementType pushes down as the ORDINAL, not the name: `Type eq
 // 'Consolidated'` is accepted and matches nothing — silently, which is
 // worse than an error and is why this filter used to run client-side.
@@ -30,11 +31,10 @@ function elementFilters(opts) {
         filters.push(`Level eq ${opts.level}`);
     if (opts?.levelMax !== undefined)
         filters.push(`Level le ${opts.levelMax}`);
-    const escapeOdata = (s) => s.replace(/'/g, "''");
     if (opts?.nameContains)
-        filters.push(`contains(Name, '${escapeOdata(opts.nameContains)}')`);
+        filters.push(`contains(Name, '${escapeOdataLiteral(opts.nameContains)}')`);
     if (opts?.nameStartsWith)
-        filters.push(`startswith(Name, '${escapeOdata(opts.nameStartsWith)}')`);
+        filters.push(`startswith(Name, '${escapeOdataLiteral(opts.nameStartsWith)}')`);
     const typeOrdinal = opts?.elementType && opts.elementType !== "All"
         ? TYPE_ORDINAL[opts.elementType]
         : undefined;
@@ -87,7 +87,7 @@ export class HierarchyService {
         const pushDown = topN !== undefined && !needsClientPostFilter;
         if (pushDown)
             elementClauses.push(...pageClauseList({ top: topN, skip }));
-        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')?$expand=Elements(${elementClauses.join(";")})`;
+        const path = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')?$expand=Elements(${elementClauses.join(";")})`;
         const rawResponse = await this.http.request("GET", path);
         let filteredElements = rawResponse.Elements;
         if (regex !== undefined)
@@ -175,7 +175,7 @@ export class HierarchyService {
         const clauses = [regex ? "$select=Name,Type,Level" : "$select=Type,Level"];
         if (filters.length > 0)
             clauses.push(`$filter=${filters.join(" and ")}`);
-        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')` +
+        const path = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')` +
             `/Elements?${clauses.join("&")}`;
         const response = await this.http.request("GET", path);
         let rows = response.value ?? [];
@@ -210,7 +210,7 @@ export class HierarchyService {
      * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements?$select=Name,Type
      */
     async getElementTypes(dimensionName, hierarchyName) {
-        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')` +
+        const path = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')` +
             `/Elements?$select=Name,Type`;
         const response = await this.http.request("GET", path);
         return (response.value ?? []).map((e) => ({
@@ -225,6 +225,46 @@ export class HierarchyService {
      * focused subtree, not the whole dimension.
      */
     async getDescendants(dimensionName, hierarchyName, element, opts) {
+        // Fetch only the subtree: Components expanded level by level from the
+        // start element. Measured on a 11,111-element, 5-level dimension (11.8):
+        // 14 KB for a mid-level subtree and 1.4 MB from the top, against 3 MB for
+        // the whole hierarchy with Parents+Edges on every call. TM1 served 20
+        // nested levels on 11.8 and 12.5. Deeper hierarchies fall back below.
+        if ((opts?.depth ?? 0) > NEST_LEVELS) {
+            return this.getDescendantsFromFull(dimensionName, hierarchyName, element, opts);
+        }
+        const levels = opts?.depth ?? NEST_LEVELS;
+        const root = await this.getNested(dimensionName, hierarchyName, element, "Components", "Name,Type,Level", levels);
+        const out = [];
+        const seen = new Set([element]);
+        let frontier = [root];
+        for (let depth = 1; depth <= levels && frontier.length > 0; depth++) {
+            const next = [];
+            for (const node of frontier) {
+                for (const child of node.Components ?? []) {
+                    if (seen.has(child.Name))
+                        continue;
+                    seen.add(child.Name);
+                    const type = child.Type;
+                    // Only a consolidation has children, so type alone decides; an
+                    // empty consolidation is not a leaf either (nothing can be written).
+                    if (!opts?.leavesOnly || type !== "Consolidated") {
+                        out.push({ name: child.Name, type, level: child.Level, depth });
+                    }
+                    next.push(child);
+                }
+            }
+            frontier = next;
+        }
+        // The last expanded level carries no Components. A consolidation there
+        // means the tree goes deeper than the request reached.
+        if (opts?.depth === undefined &&
+            frontier.some((n) => n.Type === "Consolidated")) {
+            return this.getDescendantsFromFull(dimensionName, hierarchyName, element, opts);
+        }
+        return { element, descendants: out };
+    }
+    async getDescendantsFromFull(dimensionName, hierarchyName, element, opts) {
         const hierarchy = await this.get(dimensionName, hierarchyName);
         const byName = new Map();
         for (const e of hierarchy.elements)
@@ -255,7 +295,10 @@ export class HierarchyService {
                 const childNode = byName.get(child.name);
                 if (!childNode)
                     continue;
-                const isLeaf = childNode.children.length === 0;
+                // Type, not just shape: an empty consolidation has no children but is
+                // not a leaf in the sense callers ask for — nothing can be written to
+                // it and it carries no value of its own.
+                const isLeaf = childNode.children.length === 0 && childNode.type !== "Consolidated";
                 if (!opts?.leavesOnly || isLeaf) {
                     out.push({
                         name: childNode.name,
@@ -275,6 +318,69 @@ export class HierarchyService {
      * root-to-element path so consumers can see consolidation alternatives.
      */
     async getAncestors(dimensionName, hierarchyName, element) {
+        // Parents expanded upward from the element: 1 KB on the 11,111-element
+        // test dimension where the full load was 3 MB. A path that reaches the
+        // nesting limit without ending at a root falls back to the full load.
+        const root = await this.getNested(dimensionName, hierarchyName, element, "Parents", "Name,Level", NEST_LEVELS);
+        const ancestorMap = new Map();
+        const paths = [];
+        let truncated = false;
+        const walk = (node, path) => {
+            const parents = node.Parents;
+            if (parents === undefined) {
+                truncated = true;
+                return;
+            }
+            if (parents.length === 0) {
+                paths.push(path);
+                return;
+            }
+            for (const p of parents) {
+                if (path.includes(p.Name))
+                    continue;
+                ancestorMap.set(p.Name, p.Level);
+                walk(p, [...path, p.Name]);
+            }
+        };
+        walk(root, [element]);
+        if (truncated) {
+            return this.getAncestorsFromFull(dimensionName, hierarchyName, element);
+        }
+        const ancestors = [...ancestorMap.entries()]
+            .map(([name, level]) => ({ name, level }))
+            .sort((a, b) => a.level - b.level || a.name.localeCompare(b.name));
+        return { element, ancestors, paths };
+    }
+    /**
+     * One element with a navigation property expanded `levels` deep. Nodes on
+     * the last level come back without that property, which is how callers see
+     * where the request stopped.
+     */
+    async getNested(dimensionName, hierarchyName, element, nav, select, levels) {
+        let expand = `${nav}($select=${select})`;
+        for (let i = 1; i < levels; i++) {
+            expand = `${nav}($select=${select};$expand=${expand})`;
+        }
+        const path = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')` +
+            `/Elements('${odataKey(element)}')?$select=${select}` +
+            (levels > 0 ? `&$expand=${expand}` : "");
+        try {
+            return await this.http.request("GET", path);
+        }
+        catch (e) {
+            if (e instanceof TM1Error && e.code === TM1ErrorCode.NOT_FOUND) {
+                throw new TM1Error({
+                    code: TM1ErrorCode.NOT_FOUND,
+                    message: `Element '${element}' not found in ${dimensionName}.${hierarchyName}`,
+                    httpStatus: e.httpStatus,
+                    // The nested $expand runs to kilobytes; the path alone locates it.
+                    endpoint: e.endpoint?.split("?")[0],
+                });
+            }
+            throw e;
+        }
+    }
+    async getAncestorsFromFull(dimensionName, hierarchyName, element) {
         const hierarchy = await this.get(dimensionName, hierarchyName);
         const byName = new Map();
         for (const e of hierarchy.elements)
@@ -319,14 +425,14 @@ export class HierarchyService {
      * POST /api/v1/Dimensions('{d}')/Hierarchies
      */
     async create(dimensionName, hierarchyName) {
-        await this.http.request("POST", `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies`, { Name: hierarchyName });
+        await this.http.request("POST", `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies`, { Name: hierarchyName });
     }
     /**
      * Delete a hierarchy from a dimension.
      * DELETE /api/v1/Dimensions('{d}')/Hierarchies('{h}')
      */
     async delete(dimensionName, hierarchyName) {
-        await this.http.request("DELETE", `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')`);
+        await this.http.request("DELETE", `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')`);
     }
 }
 //# sourceMappingURL=hierarchy-service.js.map

package/dist/tm1-client/services/monitoring-service.js

@@ -1,7 +1,4 @@
-function encKey(s) {
-    // Double single-quotes for OData escaping, then percent-encode all URL-unsafe chars
-    return encodeURIComponent(String(s).replace(/'/g, "''")).replace(/'/g, "%27");
-}
+import { odataKey } from "./odata-page.js";
 export class MonitoringService {
     http;
     constructor(http) {
@@ -117,7 +114,7 @@ export class MonitoringService {
      * POST /api/v1/Jobs('{id}')/tm1.Cancel
      */
     async cancelJob(jobId) {
-        await this.http.request("POST", `/api/v1/Jobs('${encKey(jobId)}')/tm1.Cancel`, {});
+        await this.http.request("POST", `/api/v1/Jobs('${odataKey(jobId)}')/tm1.Cancel`, {});
     }
 }
 //# sourceMappingURL=monitoring-service.js.map

package/dist/tm1-client/services/odata-page.d.ts

@@ -36,6 +36,12 @@ export declare function readCount(response: {
 export declare function readNestedCount(response: Record<string, unknown> | null | undefined, navigationProperty: string): number | undefined;
 /** Double `'` per OData literal rules so a caller string cannot break out of a literal. */
 export declare function escapeOdataLiteral(value: string): string;
+/**
+ * Entity-key segment for a URL path: `Cubes('${odataKey(name)}')`. Doubles `'`,
+ * then percent-encodes, so `#`, `?`, `%`, `&` and `/` in a TM1 name stay inside
+ * the key. The one encoder for every service — see scripts/check-no-local-enc.mjs.
+ */
+export declare function odataKey(value: string): string;
 /** Join filter predicates with `and` into a `&$filter=…` fragment. Empty string when none. */
 export declare function filterClause(predicates: readonly string[]): string;
 /**