@ffschrattenecker/tm1-mcp-server 7.0.1 → 8.0.0

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

@@ -10,12 +10,15 @@ import { mapSettledWithConcurrency } from "../../lib/concurrency.js";
 import { TM1Error, TM1ErrorCode } from "../../types.js";
 import { BatchUnsupportedError } from "./batch-service.js";
 import { rethrowIfSystemic } from "./fallback.js";
+import { escapeOdataLiteral, odataKey } from "./odata-page.js";
 // Max in-flight per-element REST calls within a single bulkUpsert pass. Bounds
 // pressure on TM1's worker pool (mirrors the cap the feeder-audit fan-out uses)
 // while removing the serialized 2-3N round-trips on an explicitly-bulk op.
 const BULK_UPSERT_CONCURRENCY = 8;
-// OData key encoder: double ' per OData literal rules, then percent-encode.
-const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+// Names per `consolidatedAmong` request. Keeps the generated $filter well
+// inside any proxy URL limit while still costing one round-trip for the
+// element count a normal write carries.
+const CONSOLIDATED_PROBE_CHUNK = 50;
 // TM1 signals "element already exists" with different HTTP statuses across
 // versions: some return 409 Conflict, but v11.x (REST 11.8) returns 400 with
 // the message "An element with name ... already exists". Detect both so bulk
@@ -101,11 +104,11 @@ export class ElementService {
      * all-1, and a PATCH that sets 1 to 1 is a round trip for nothing.
      */
     async applyEdgeWeights(dimensionName, hierarchyName, parentName, components) {
-        const base = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')`;
+        const base = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')`;
         for (const c of components) {
             if (c.weight === undefined || c.weight === 1)
                 continue;
-            await this.http.request("PATCH", `${base}/Edges(ParentName='${enc(parentName)}',ComponentName='${enc(c.name)}')`, { Weight: c.weight });
+            await this.http.request("PATCH", `${base}/Edges(ParentName='${odataKey(parentName)}',ComponentName='${odataKey(c.name)}')`, { Weight: c.weight });
         }
     }
     /**
@@ -118,7 +121,7 @@ export class ElementService {
      */
     async exists(dimensionName, hierarchyName, elementName) {
         try {
-            await this.http.request("GET", `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(elementName)}')?$select=Name`);
+            await this.http.request("GET", `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements('${odataKey(elementName)}')?$select=Name`);
             return true;
         }
         catch (e) {
@@ -128,7 +131,7 @@ export class ElementService {
         }
     }
     async create(dimensionName, hierarchyName, element) {
-        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements`;
+        const path = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements`;
         const body = {
             Name: element.name,
             Type: element.type,
@@ -137,7 +140,7 @@ export class ElementService {
             element.components &&
             element.components.length > 0) {
             body.Components = element.components.map((c) => ({
-                "@odata.id": `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(c.name)}')`,
+                "@odata.id": `Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements('${odataKey(c.name)}')`,
             }));
         }
         await this.http.request("POST", path, body);
@@ -150,7 +153,21 @@ export class ElementService {
      * PATCH /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{name}')
      */
     async update(dimensionName, hierarchyName, elementName, update) {
-        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(elementName)}')`;
+        const path = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements('${odataKey(elementName)}')`;
+        // Read the prior type so an in-place conversion is reported: turning a
+        // Numeric element into Consolidated/String discards its leaf cell values.
+        // Same probe and outage guard as bulkUpsert; an unreadable type reports
+        // nothing rather than guessing.
+        let from = null;
+        if (update.type !== undefined) {
+            const existing = await this.http
+                .request("GET", `${path}?$select=Type`)
+                .catch((e) => {
+                rethrowIfSystemic(e);
+                return null;
+            });
+            from = existing ? normalizeElementType(existing.Type) : null;
+        }
         const body = {};
         if (update.newName !== undefined) {
             body.Name = update.newName;
@@ -160,7 +177,7 @@ export class ElementService {
         }
         if (update.components !== undefined) {
             body.Components = update.components.map((c) => ({
-                "@odata.id": `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(c.name)}')`,
+                "@odata.id": `Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements('${odataKey(c.name)}')`,
             }));
         }
         await this.http.request("PATCH", path, body);
@@ -170,13 +187,18 @@ export class ElementService {
             // key must use the NEW parent name.
             update.newName ?? elementName, update.components);
         }
+        return {
+            typeChange: from !== null && update.type !== undefined && from !== update.type
+                ? { from, to: update.type }
+                : null,
+        };
     }
     /**
      * Delete an element. May fail if the element is referenced in rules.
      * DELETE /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{name}')
      */
     async delete(dimensionName, hierarchyName, elementName) {
-        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(elementName)}')`;
+        const path = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements('${odataKey(elementName)}')`;
         await this.http.request("DELETE", path);
     }
     /**
@@ -194,8 +216,8 @@ export class ElementService {
      * the edges expanded — instead of loading the hierarchy.
      */
     async planBulkUpsert(dimensionName, hierarchyName, elements) {
-        const base = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements`;
-        const lit = (n) => `'${n.replace(/'/g, "''")}'`;
+        const base = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements`;
+        const lit = (n) => `'${escapeOdataLiteral(n)}'`;
         const current = new Map();
         const names = [...new Set(elements.map((e) => e.name))];
         for (let i = 0; i < names.length; i += 40) {
@@ -249,7 +271,7 @@ export class ElementService {
      * reports NOT_FOUND instead of claiming a second delete.
      */
     async deleteMany(dimensionName, hierarchyName, elementNames) {
-        const pathOf = (name) => `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(name)}')`;
+        const pathOf = (name) => `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements('${odataKey(name)}')`;
         const failed = (elementName, e) => ({
             elementName,
             deleted: false,
@@ -314,7 +336,7 @@ export class ElementService {
      */
     async scanElementNames(dimensionName, hierarchyName, opts) {
         const { pageSize, maxScan, filter, scopeTotal } = opts;
-        const hierarchyPath = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')`;
+        const hierarchyPath = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')`;
         const basePath = `${hierarchyPath}/Elements?$select=Name&$top=${pageSize}` +
             (filter ? `&$filter=${encodeURIComponent(filter)}` : "");
         // First page carries $count=true so we learn the total in one round-trip
@@ -364,18 +386,46 @@ export class ElementService {
         };
     }
     /**
-     * Add an element as a component of a new parent.
-     * POST /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{newParent}')/Components
+     * Type of one element, or null when the hierarchy has no such element.
+     * Keyed lookup, so TM1 applies its own case- and space-insensitive name
+     * matching and answers with the stored spelling.
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{name}')?$select=Name,Type
      */
-    async move(dimensionName, hierarchyName, elementName, newParent, weight) {
-        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(newParent)}')/Components`;
-        const body = {
-            "@odata.id": `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(elementName)}')`,
-        };
-        await this.http.request("POST", path, body);
-        await this.applyEdgeWeights(dimensionName, hierarchyName, newParent, [
-            { name: elementName, ...(weight !== undefined ? { weight } : {}) },
-        ]);
+    async getType(dimensionName, hierarchyName, elementName) {
+        try {
+            const e = await this.http.request("GET", `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements('${odataKey(elementName)}')?$select=Name,Type`);
+            return { name: e.Name, type: normalizeElementType(e.Type) };
+        }
+        catch (err) {
+            if (err instanceof TM1Error && err.code === TM1ErrorCode.NOT_FOUND) {
+                return null;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Which of `names` are consolidated (Type 3) in this hierarchy.
+     *
+     * One filtered request per chunk of names rather than a GET per element:
+     * the server evaluates `Type eq 3 and (Name eq ...)` and answers with the
+     * hits only, so the response is bounded by the consolidations among the
+     * names asked about, never by the size of the hierarchy.
+     *
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements?$select=Name&$filter=...
+     */
+    async consolidatedAmong(dimensionName, hierarchyName, names) {
+        const hits = [];
+        for (let i = 0; i < names.length; i += CONSOLIDATED_PROBE_CHUNK) {
+            const clause = names
+                .slice(i, i + CONSOLIDATED_PROBE_CHUNK)
+                .map((n) => `Name eq '${n.replace(/'/g, "''")}'`)
+                .join(" or ");
+            const filter = encodeURIComponent(`Type eq 3 and (${clause})`);
+            const page = await this.http.request("GET", `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements?$select=Name&$filter=${filter}`);
+            for (const e of page.value)
+                hits.push(e.Name);
+        }
+        return hits;
     }
     /**
      * Bulk upsert elements into a hierarchy. Two-pass to ensure leaves exist
@@ -436,7 +486,7 @@ export class ElementService {
      */
     async bulkUpsertViaBatch(dimensionName, hierarchyName, elements) {
         const batch = this.batch;
-        const baseUrl = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements`;
+        const baseUrl = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements`;
         // Correlate by element INDEX, not name: names are caller-supplied and could
         // repeat, which would collapse two sub-responses onto one id.
         const idOf = (i) => `e${i}`;
@@ -470,7 +520,7 @@ export class ElementService {
         const probed = await batch.execute(existing.map((i) => ({
             id: idOf(i),
             method: "GET",
-            path: `${baseUrl}('${enc(elements[i].name)}')?$select=Type`,
+            path: `${baseUrl}('${odataKey(elements[i].name)}')?$select=Type`,
         })));
         const typeById = new Map();
         for (const r of probed) {
@@ -498,7 +548,7 @@ export class ElementService {
             patches.push({
                 id: idOf(i),
                 method: "PATCH",
-                path: `${baseUrl}('${enc(el.name)}')`,
+                path: `${baseUrl}('${odataKey(el.name)}')`,
                 body: { Type: el.type },
             });
             // A Numeric->Consolidated / Numeric->String conversion discards the
@@ -523,10 +573,10 @@ export class ElementService {
             components.push({
                 id: idOf(i),
                 method: "PATCH",
-                path: `${baseUrl}('${enc(el.name)}')`,
+                path: `${baseUrl}('${odataKey(el.name)}')`,
                 body: {
                     Components: el.components.map((c) => ({
-                        "@odata.id": `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(c.name)}')`,
+                        "@odata.id": `Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements('${odataKey(c.name)}')`,
                         Weight: c.weight,
                     })),
                 },
@@ -553,7 +603,7 @@ export class ElementService {
                 edges.push({
                     id: `e${edgeOwner.length}`,
                     method: "PATCH",
-                    path: `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Edges(ParentName='${enc(el.name)}',ComponentName='${enc(c.name)}')`,
+                    path: `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Edges(ParentName='${odataKey(el.name)}',ComponentName='${odataKey(c.name)}')`,
                     body: { Weight: c.weight },
                 });
                 edgeOwner.push(i);
@@ -569,7 +619,7 @@ export class ElementService {
      * Fans the calls out with bounded concurrency.
      */
     async bulkUpsertPerRequest(dimensionName, hierarchyName, elements) {
-        const baseUrl = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements`;
+        const baseUrl = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements`;
         // Pass 1: Create/upsert all elements without components. Same-type element
         // writes are independent, so fan them out with bounded concurrency instead
         // of one serialized round-trip each (was 2-3N sequential calls). The cap
@@ -590,7 +640,7 @@ export class ElementService {
                     // element's leaf cell values, so the caller must be told it happened
                     // rather than have it occur silently.
                     const existing = await this.http
-                        .request("GET", `${baseUrl}('${enc(el.name)}')?$select=Type`)
+                        .request("GET", `${baseUrl}('${odataKey(el.name)}')?$select=Type`)
                         .catch((e) => {
                         // A transport/auth outage here must NOT collapse into the
                         // unconditional-PATCH branch below: that would silently change the
@@ -601,12 +651,12 @@ export class ElementService {
                     });
                     const from = existing ? normalizeElementType(existing.Type) : null;
                     if (from && from !== el.type) {
-                        await this.http.request("PATCH", `${baseUrl}('${enc(el.name)}')`, { Type: el.type });
+                        await this.http.request("PATCH", `${baseUrl}('${odataKey(el.name)}')`, { Type: el.type });
                         return { name: el.name, from, to: el.type };
                     }
                     if (!from) {
                         // Type unreadable — preserve prior behaviour and patch unconditionally.
-                        await this.http.request("PATCH", `${baseUrl}('${enc(el.name)}')`, { Type: el.type });
+                        await this.http.request("PATCH", `${baseUrl}('${odataKey(el.name)}')`, { Type: el.type });
                     }
                     return null;
                 }
@@ -636,10 +686,10 @@ export class ElementService {
         // out with the same bounded concurrency.
         const consolidated = elements.filter((el) => el.type === "Consolidated" && el.components && el.components.length > 0);
         const pass2 = await mapSettledWithConcurrency(consolidated, BULK_UPSERT_CONCURRENCY, async (el) => {
-            const path = `${baseUrl}('${enc(el.name)}')`;
+            const path = `${baseUrl}('${odataKey(el.name)}')`;
             const body = {
                 Components: el.components.map((c) => ({
-                    "@odata.id": `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(c.name)}')`,
+                    "@odata.id": `Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/Elements('${odataKey(c.name)}')`,
                     Weight: c.weight,
                 })),
             };
@@ -665,7 +715,7 @@ export class ElementService {
      * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/ElementAttributes
      */
     async listAttributes(dimensionName, hierarchyName) {
-        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/ElementAttributes`;
+        const path = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/ElementAttributes`;
         const response = await this.http.request("GET", path);
         return response.value.map((a) => ({
             name: a.Name,
@@ -679,7 +729,7 @@ export class ElementService {
      * POST /api/v1/Dimensions('{d}')/Hierarchies('{h}')/ElementAttributes
      */
     async createAttribute(dimensionName, hierarchyName, attributeName, attributeType) {
-        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/ElementAttributes`;
+        const path = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hierarchyName)}')/ElementAttributes`;
         await this.http.request("POST", path, {
             Name: attributeName,
             Type: attributeType,
@@ -690,17 +740,26 @@ export class ElementService {
      * `}ElementAttributes_{Dim}`. Routes through CellService.executeMdx for the
      * cellset round-trip.
      */
-    async getAttributeValues(dimensionName, elementName) {
+    async getAttributeValues(dimensionName, elementName, hierarchyName = dimensionName) {
+        // No attribute defined means no }ElementAttributes_ cube, and the MDX
+        // below would fail with a raw syntax error. Nothing to read is the answer.
+        if ((await this.listAttributes(dimensionName, hierarchyName)).length === 0)
+            return [];
         // Escape `]` → `]]` in every bracketed identifier: an element or dimension
         // named e.g. `Foo]` would otherwise break out of its MDX identifier and
         // shift the read onto arbitrary members (MDX injection).
         const esc = (s) => s.replace(/]/g, "]]");
         const dim = esc(dimensionName);
         const elem = esc(elementName);
+        const hier = esc(hierarchyName);
         const ctrlCube = `}ElementAttributes_${dim}`;
         const mdx = `SELECT {[}ElementAttributes_${dim}].MEMBERS} ON COLUMNS ` +
             `FROM [${ctrlCube}] ` +
-            `WHERE ([${dim}].[${elem}])`;
+            // Always name the hierarchy: the attribute cube spans every hierarchy of
+            // the dimension, and v12 refuses a bare name another hierarchy shares
+            // ("Member name A is ambiguous"), while v11 finds a bare name only in
+            // the default hierarchy.
+            `WHERE ([${dim}].[${hier}].[${elem}])`;
         const result = await this.cells.executeMdx(mdx);
         const out = [];
         const tuples = result.axes[0]?.tuples ?? [];
@@ -726,7 +785,7 @@ export class ElementService {
      * `attributeNames` narrows the columns; omitted, every attribute is read.
      */
     async getAttributeValuesPage(dimensionName, opts) {
-        const countPath = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(dimensionName)}')/Elements?$select=Name&$top=1&$count=true`;
+        const countPath = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(dimensionName)}')/Elements?$select=Name&$top=1&$count=true`;
         const counted = await this.http.request("GET", countPath);
         const total = counted["@odata.count"] ?? 0;
         if (opts.limit === 0 || opts.offset >= total)
@@ -756,38 +815,40 @@ export class ElementService {
     /**
      * Set a single attribute value. See {@link updateAttributeValues}.
      */
-    async updateAttributeValue(dimensionName, elementName, attributeName, value) {
-        await this.updateAttributeValues(dimensionName, [
-            { elementName, attributeName, value },
-        ]);
+    async updateAttributeValue(dimensionName, elementName, attributeName, value, hierarchyName = dimensionName) {
+        await this.updateAttributeValues(dimensionName, [{ elementName, attributeName, value }], hierarchyName);
     }
     /**
      * Set attribute values by writing to the `}ElementAttributes_{Dim}` control
      * cube — every update in ONE cellset write (CellService.writeCells).
      *
-     * Values are coerced to the attribute's type, looked up once: a Numeric
+     * The attributes are looked up once. TM1 matches attribute names ignoring
+     * case and spaces, so the lookup compares the same way; an unknown attribute
+     * is NOT_FOUND, raised before anything is written — without the check TM1
+     * answers with a raw MDX syntax error (no attribute at all means no
+     * attribute cube). Values are coerced to the attribute's type: a Numeric
      * attribute takes a number or a numeric string (`"12.5"`), String and Alias
-     * attributes take the value as text. An unknown attribute or a non-numeric
-     * value for a Numeric attribute is a VALIDATION_ERROR that names it, raised
-     * before anything is written.
+     * attributes take the value as text; a non-numeric value for a Numeric
+     * attribute is a VALIDATION_ERROR that names it.
      *
      * Prefer TI processes (CellPutS / AttrPutS) for reproducible deployments;
      * this REST-direct path is for ad-hoc / debugging use.
      */
-    async updateAttributeValues(dimensionName, updates) {
+    async updateAttributeValues(dimensionName, updates, hierarchyName = dimensionName) {
         if (updates.length === 0)
             return;
-        const types = new Map((await this.listAttributes(dimensionName, dimensionName)).map((a) => [
-            a.name,
-            a.type,
-        ]));
+        const attrs = await this.listAttributes(dimensionName, hierarchyName);
+        const key = (n) => n.replace(/\s/g, "").toLowerCase();
+        const types = new Map(attrs.map((a) => [key(a.name), a.type]));
+        const esc = (s) => s.replace(/]/g, "]]");
         const cells = updates.map((u) => {
-            const type = types.get(u.attributeName);
+            const type = types.get(key(u.attributeName));
             if (type === undefined) {
                 throw new TM1Error({
-                    code: TM1ErrorCode.VALIDATION_ERROR,
-                    message: `Attribute '${u.attributeName}' does not exist on dimension '${dimensionName}'.`,
-                    hint: `Known attributes: ${[...types.keys()].join(", ") || "(none)"}. Create it first with tm1_create_element_attribute.`,
+                    code: TM1ErrorCode.NOT_FOUND,
+                    message: attrs.length === 0
+                        ? `Dimension '${dimensionName}' has no attributes; create '${u.attributeName}' with tm1_create_element_attribute first.`
+                        : `Attribute '${u.attributeName}' does not exist on dimension '${dimensionName}'. Existing: ${attrs.map((a) => a.name).join(", ")}.`,
                 });
             }
             let value = String(u.value);
@@ -801,7 +862,10 @@ export class ElementService {
                 }
                 value = n;
             }
-            return { elements: [u.elementName, u.attributeName], value };
+            // Qualified for the same reason as getAttributeValues; writeCells passes
+            // a `[Dim].[Hier].[Elem]` coordinate through unchanged.
+            const member = `[${esc(dimensionName)}].[${esc(hierarchyName)}].[${esc(u.elementName)}]`;
+            return { elements: [member, u.attributeName], value };
         });
         await this.cells.writeCells(`}ElementAttributes_${dimensionName}`, [dimensionName, `}ElementAttributes_${dimensionName}`], cells);
     }

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

@@ -1,26 +1,53 @@
 import type { TM1HttpClient } from "../http.js";
+/** Which storage tree a file operation addresses. */
+export type FileContainer = "files" | "applications";
 export declare class FileService {
     private readonly http;
     constructor(http: TM1HttpClient);
+    /**
+     * 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.
+     */
+    private appsChildren;
+    /**
+     * 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.
+     */
+    private appsResolve;
+    /** URL of the bytes behind a DocumentReference, or a typed refusal. */
+    private appsContentUrl;
     /**
      * 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'.
      */
-    list(path?: string): Promise<string[]>;
+    list(path?: string, container?: FileContainer): Promise<string[]>;
     /**
      * Get the content of a file from TM1 server's blob/file storage.
      * Returns raw text (CSV/TXT/etc).
      * Tries v12 'Files' first, falls back to v11 'Blobs'.
      */
-    getContent(fileName: string): Promise<string>;
+    getContent(fileName: string, container?: FileContainer): Promise<string>;
+    /**
+     * The same read, byte-for-byte. The Applications tree holds spreadsheets and
+     * other binaries, which a UTF-8 decode would quietly destroy.
+     */
+    getContentBytes(fileName: string, container?: FileContainer): Promise<Buffer>;
     /**
      * Check whether a file exists. Tries v12 'Files' first, falls back to 'Blobs'.
      * Implemented as a cheap GET on the entity ($select=Name) — TM1 REST does
      * not expose HEAD on these. 404 → false; other errors propagate.
      */
-    exists(fileName: string): Promise<boolean>;
+    exists(fileName: string, container?: FileContainer): Promise<boolean>;
     /**
      * Upload (create-or-update) a file. Two-step v11 protocol:
      *   1. POST entity into the parent Contents collection (only if missing)
@@ -30,14 +57,14 @@ export declare class FileService {
      * Subfolders only supported on TM1 v12. Caller must ensure parent folders
      * exist (folder-create not yet exposed).
      */
-    upload(fileName: string, content: Uint8Array): Promise<{
+    upload(fileName: string, content: Uint8Array, container?: FileContainer): Promise<{
         created: boolean;
-        root: "Files" | "Blobs";
+        root: "Files" | "Blobs" | "Applications";
     }>;
     /**
      * Delete a file from blob/file storage. Tries 'Files' first, then 'Blobs'.
      */
-    delete(fileName: string): Promise<void>;
+    delete(fileName: string, container?: FileContainer): Promise<void>;
     /**
      * Search file names in a folder using OData $filter.
      * - startswith: case-insensitive prefix match
@@ -48,6 +75,15 @@ export declare class FileService {
         contains?: string[] | undefined;
         operator?: "and" | "or" | undefined;
         path?: string | undefined;
+        container?: FileContainer | undefined;
     }): Promise<string[]>;
+    /**
+     * 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.
+     */
+    private uploadToApplications;
 }
 //# sourceMappingURL=file-service.d.ts.map