@ffschrattenecker/tm1-mcp-server 7.0.2 → 8.0.0

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

@@ -5,14 +5,15 @@
 // as deprecated wrappers during the migration period (Phase 1 of the
 // god-class split — see docs/ARCHITECTURE.md).
 import { TM1Error, TM1ErrorCode } from "../../types.js";
-import { filterClause, nameFilterPredicates, pageClauses, readCount, } from "./odata-page.js";
+import { filterClause, nameFilterPredicates, pageClauses, readCount, odataKey, } from "./odata-page.js";
 import { classifyExecution } from "./process-status.js";
-// OData key encoder: double ' per OData literal rules, then percent-encode.
-const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+import { DimensionOrderCache } from "./dimension-order.js";
 export class CubeService {
     http;
-    constructor(http) {
+    dimOrder;
+    constructor(http, dimOrder = new DimensionOrderCache(http)) {
         this.http = http;
+        this.dimOrder = dimOrder;
     }
     async list(opts = {}) {
         // Without a top-level $select TM1 returns every cube property — including
@@ -41,13 +42,12 @@ export class CubeService {
             : { items, total: readCount(response) };
     }
     /**
-     * Return ordered dimension-name list of a cube.
+     * Return ordered dimension-name list of a cube. Cached per connection —
+     * see dimension-order.ts.
      * GET /api/v1/Cubes('{name}')?$expand=Dimensions($select=Name)
      */
     async getDimensionNames(cubeName) {
-        const path = `/api/v1/Cubes('${enc(cubeName)}')?$expand=Dimensions($select=Name)`;
-        const response = await this.http.request("GET", path);
-        return response.Dimensions.map((d) => d.Name);
+        return this.dimOrder.get(cubeName);
     }
     /**
      * Cheap existence probe: a single GET with $select=Name (404 → false)
@@ -62,7 +62,7 @@ export class CubeService {
      */
     async exists(cubeName) {
         try {
-            await this.http.request("GET", `/api/v1/Cubes('${enc(cubeName)}')?$select=Name`);
+            await this.http.request("GET", `/api/v1/Cubes('${odataKey(cubeName)}')?$select=Name`);
             return true;
         }
         catch (e) {
@@ -79,7 +79,7 @@ export class CubeService {
         await this.http.request("POST", "/api/v1/Cubes", {
             Name: name,
             Dimensions: dimensionNames.map((d) => ({
-                "@odata.id": `Dimensions('${enc(d)}')`,
+                "@odata.id": `Dimensions('${odataKey(d)}')`,
             })),
         });
     }
@@ -88,21 +88,21 @@ export class CubeService {
      * DELETE /api/v1/Cubes('{name}')
      */
     async delete(name) {
-        await this.http.request("DELETE", `/api/v1/Cubes('${enc(name)}')`);
+        await this.http.request("DELETE", `/api/v1/Cubes('${odataKey(name)}')`);
     }
     /**
      * Get the rules text for a cube.
      * GET /api/v1/Cubes('{name}')/Rules
      */
     async getRules(cubeName) {
-        const path = `/api/v1/Cubes('${enc(cubeName)}')/Rules`;
+        const path = `/api/v1/Cubes('${odataKey(cubeName)}')/Rules`;
         // TM1 returns 404/204 both for "cube missing" and "cube has no rules";
         // an empty 200 body (response undefined) also means "no rules". For any
         // of those, probe `/Cubes('X')?$select=Name` to disambiguate so callers
         // get a clear NOT_FOUND for typos instead of a silently-empty rulesText.
         const empty = async () => {
             try {
-                await this.http.request("GET", `/api/v1/Cubes('${enc(cubeName)}')?$select=Name`);
+                await this.http.request("GET", `/api/v1/Cubes('${odataKey(cubeName)}')?$select=Name`);
             }
             catch (probeErr) {
                 if (probeErr instanceof TM1Error && probeErr.httpStatus === 404) {
@@ -173,7 +173,7 @@ export class CubeService {
      * text, so it travels in `rulesText` like every other statement.
      */
     async updateRules(cubeName, rulesText) {
-        const cubePath = `/api/v1/Cubes('${enc(cubeName)}')`;
+        const cubePath = `/api/v1/Cubes('${odataKey(cubeName)}')`;
         await this.http.request("PATCH", cubePath, { Rules: rulesText });
     }
     /**
@@ -181,7 +181,7 @@ export class CubeService {
      * POST /api/v1/Cubes('{name}')/tm1.CheckRules with { Rules: "..." }
      */
     async checkRule(cubeName, ruleText) {
-        const path = `/api/v1/Cubes('${enc(cubeName)}')/tm1.CheckRules`;
+        const path = `/api/v1/Cubes('${odataKey(cubeName)}')/tm1.CheckRules`;
         const response = await this.http.request("POST", path, { Rules: ruleText });
         return (response.value ?? []).map((e) => ({
             message: e.Message,
@@ -189,33 +189,17 @@ export class CubeService {
         }));
     }
     /**
-     * Clear cube cells.
-     *
-     * A **full** clear runs an ephemeral TI with CubeClearData(). tm1.Clear is
-     * not an alternative on either build: 11.8 and 12.5 both answer
-     * "'tm1.Clear' resource can not be resolved on type 'Cube'" for a cube that
-     * exists, and neither declares a clear action anywhere in $metadata — Cube
-     * carries only Lock and Unlock. CubeClearData() is the only route measured
-     * to work.
+     * Clear every cell in a cube.
      *
-     * A **partial** clear would need tuple selectors, which only tm1.Clear
-     * offers, so no server reachable here can do one. Callers get
-     * UNSUPPORTED_OPERATION pointing at bedrock `}bedrock.cube.data.clear`
-     * rather than a request that is known to 404.
+     * The clear runs an ephemeral TI with CubeClearData(). tm1.Clear is not an
+     * alternative on either build: 11.8 and 12.5 both answer "'tm1.Clear'
+     * resource can not be resolved on type 'Cube'" for a cube that exists, and
+     * neither declares a clear action anywhere in $metadata — Cube carries only
+     * Lock and Unlock. CubeClearData() is the only route measured to work, and
+     * it takes a cube name and nothing else, so there is no region to scope.
      */
-    async clear(cubeName, dimensions, tuples) {
-        const isFullClear = dimensions.every((_, i) => (tuples[i] ?? []).length === 0);
-        if (!isFullClear)
-            throw this.partialClearUnsupported(cubeName);
-        await this.clearViaTI(cubeName);
-    }
-    /** Same verdict for both versions: no tuple-selective clear on this server. */
-    partialClearUnsupported(cubeName) {
-        return new TM1Error({
-            code: TM1ErrorCode.UNSUPPORTED_OPERATION,
-            message: `Partial clearCube is not supported on TM1 ${this.http.tm1Version} (no tm1.Clear endpoint). Implement a TI process with bedrock '}bedrock.cube.data.clear' or custom CellPutN loop and call via tm1_execute_process.`,
-            endpoint: `/api/v1/Cubes('${cubeName}')/tm1.Clear`,
-        });
+    async clear(cubeName, opts) {
+        await this.clearViaTI(cubeName, opts);
     }
     /**
      * Unload a cube from memory. Forces TM1 to discard the in-memory fed-cell
@@ -225,10 +209,10 @@ export class CubeService {
      * POST /api/v1/Cubes('{cube}')/tm1.Unload
      */
     async unload(cubeName) {
-        await this.http.request("POST", `/api/v1/Cubes('${enc(cubeName)}')/tm1.Unload`);
+        await this.http.request("POST", `/api/v1/Cubes('${odataKey(cubeName)}')/tm1.Unload`);
     }
     // 11.x fallback: deploy ephemeral TI with CubeClearData(), execute, delete.
-    async clearViaTI(cubeName) {
+    async clearViaTI(cubeName, opts) {
         // Cap the sanitized cube name so the temp process name stays under TM1's
         // ~256-char process-name limit (prefix + timestamp suffix add ~25 chars).
         const safeName = cubeName.replace(/[^A-Za-z0-9_]/g, "_").slice(0, 200);
@@ -244,8 +228,29 @@ export class CubeService {
             EpilogProcedure: "",
             DataSource: { Type: "None" },
         });
+        let timedOut = false;
         try {
-            const result = await this.http.request("POST", `/api/v1/Processes('${enc(procName)}')/tm1.ExecuteWithReturn`, {});
+            const result = await this.http
+                .request("POST", `/api/v1/Processes('${odataKey(procName)}')/tm1.ExecuteWithReturn`, {}, opts)
+                .catch((err) => {
+                // A client-side timeout does not stop the TI — but deleting the
+                // process does, when it is still waiting on a lock (measured on
+                // 12.5: the cube kept its data). So on a timeout the process is left
+                // in place to finish; 11.8 held the DELETE until the TI was done
+                // anyway. Reporting a bare timeout would tell the model the cube
+                // still holds its data — the one reading this must not give.
+                if (err instanceof TM1Error &&
+                    err.code === TM1ErrorCode.LOCK_TIMEOUT) {
+                    timedOut = true;
+                    throw new TM1Error({
+                        code: TM1ErrorCode.LOCK_TIMEOUT,
+                        message: `Cube clear for '${cubeName}' did not answer within the request timeout, but the clear keeps running on the server — expect the cube to end up empty. Do not retry; check it with tm1_get_cube_stats once the server is idle. The temporary process '${procName}' was left in place so the clear can finish; delete it afterwards with tm1_delete_process.`,
+                        endpoint: err.endpoint,
+                        hint: "Pass a larger timeoutMs for big cubes or a busy server so the call waits for the clear to finish.",
+                    });
+                }
+                throw err;
+            });
             // ExecuteWithReturn returns HTTP 200 even when the process aborts; the real
             // outcome is in ProcessExecuteStatusCode. Without this check an aborted
             // clear (e.g. lock, security) would be reported as a successful clear.
@@ -277,13 +282,14 @@ export class CubeService {
                     message: verdict.outcome === "rolled_back"
                         ? `Cube clear via TI was rolled back for cube '${cubeName}' (status: ${verdict.processErrorStatus}). Nothing was cleared — the cube is unchanged.`
                         : `Cube clear via TI could not be confirmed for cube '${cubeName}': ${verdict.processErrorStatus} The clear may or may not have run — check the cube before retrying.`,
-                    endpoint: `/api/v1/Processes('${enc(procName)}')/tm1.ExecuteWithReturn`,
+                    endpoint: `/api/v1/Processes('${odataKey(procName)}')/tm1.ExecuteWithReturn`,
                 });
             }
         }
         finally {
             try {
-                await this.http.request("DELETE", `/api/v1/Processes('${enc(procName)}')`);
+                if (!timedOut)
+                    await this.http.request("DELETE", `/api/v1/Processes('${odataKey(procName)}')`);
             }
             catch (cleanupErr) {
                 this.http.logger.warn({ proc: procName, err: String(cleanupErr) }, "Failed to delete ephemeral clearCube TI process — manual cleanup needed");

package/dist/tm1-client/services/dimension-order.d.ts

@@ -0,0 +1,13 @@
+import type { TM1HttpClient } from "../http.js";
+export declare class DimensionOrderCache {
+    private readonly http;
+    private readonly now;
+    private readonly entries;
+    constructor(http: TM1HttpClient, now?: () => number);
+    /**
+     * Ordered dimension names of `cubeName`.
+     * GET /api/v1/Cubes('{name}')?$expand=Dimensions($select=Name)
+     */
+    get(cubeName: string): Promise<string[]>;
+}
+//# sourceMappingURL=dimension-order.d.ts.map

package/dist/tm1-client/services/dimension-order.js

@@ -0,0 +1,42 @@
+import { tm1NameKey } from "../../lib/tm1-name.js";
+import { odataKey as enc } from "./odata-page.js";
+const TTL_MS = 60_000;
+const INERT_PATHS = [/\/ExecuteMDX/i, /\/Cellsets/i];
+export class DimensionOrderCache {
+    http;
+    now;
+    entries = new Map();
+    constructor(http, now = Date.now) {
+        this.http = http;
+        this.now = now;
+        // Test doubles stub only request(); a real client always has the hook.
+        if (typeof http.onMutation === "function") {
+            http.onMutation((e) => {
+                if (!INERT_PATHS.some((re) => re.test(e.path)))
+                    this.entries.clear();
+            });
+        }
+    }
+    /**
+     * Ordered dimension names of `cubeName`.
+     * GET /api/v1/Cubes('{name}')?$expand=Dimensions($select=Name)
+     */
+    get(cubeName) {
+        const key = tm1NameKey(cubeName);
+        const hit = this.entries.get(key);
+        if (hit && this.now() - hit.at < TTL_MS)
+            return hit.dims;
+        // The promise is cached, so concurrent callers share one request; a
+        // failure is evicted so the next call retries instead of replaying it.
+        const dims = this.http
+            .request("GET", `/api/v1/Cubes('${enc(cubeName)}')?$expand=Dimensions($select=Name)`)
+            .then((r) => r.Dimensions.map((d) => d.Name));
+        this.entries.set(key, { dims, at: this.now() });
+        dims.catch(() => {
+            if (this.entries.get(key)?.dims === dims)
+                this.entries.delete(key);
+        });
+        return dims;
+    }
+}
+//# sourceMappingURL=dimension-order.js.map

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

@@ -3,9 +3,7 @@
 // sibling services. See docs/ARCHITECTURE.md for the layering.
 import { TM1Error, TM1ErrorCode } from "../../types.js";
 import { freeCellset } from "./cellset-transform.js";
-import { filterClause, nameFilterPredicates, pageClauses, readCount, } from "./odata-page.js";
-// OData key encoder: double ' per OData literal rules, then percent-encode.
-const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+import { filterClause, nameFilterPredicates, pageClauses, readCount, odataKey, } from "./odata-page.js";
 /**
  * Decode a TM1 `}DimensionProperties.LAST_TIME_UPDATED` cell — a 14-digit
  * `YYYYMMDDHHMMSS` stamp in server-local time — to a naive-local ISO string
@@ -112,7 +110,7 @@ export class DimensionService {
     async create(name) {
         await this.http.request("POST", "/api/v1/Dimensions", { Name: name });
         try {
-            await this.http.request("POST", `/api/v1/Dimensions('${enc(name)}')/Hierarchies`, { Name: name });
+            await this.http.request("POST", `/api/v1/Dimensions('${odataKey(name)}')/Hierarchies`, { Name: name });
         }
         catch (err) {
             if (err instanceof TM1Error && err.httpStatus === 409) {
@@ -126,7 +124,7 @@ export class DimensionService {
      * DELETE /api/v1/Dimensions('{name}')
      */
     async delete(name) {
-        await this.http.request("DELETE", `/api/v1/Dimensions('${enc(name)}')`);
+        await this.http.request("DELETE", `/api/v1/Dimensions('${odataKey(name)}')`);
     }
     /**
      * Read per-dimension last-modified timestamps from the `}DimensionProperties`
@@ -173,7 +171,7 @@ export class DimensionService {
      */
     async resolveDefaultMember(dimensionName, hierarchyName) {
         const hier = hierarchyName ?? dimensionName;
-        const base = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hier)}')`;
+        const base = `/api/v1/Dimensions('${odataKey(dimensionName)}')/Hierarchies('${odataKey(hier)}')`;
         // Tier 1: explicit DefaultMember attribute.
         try {
             const dm = await this.http.request("GET", `${base}/DefaultMember?$select=Name,Level`);

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

@@ -66,7 +66,12 @@ export declare class ElementService {
      * Update an existing element (rename, type change, replace components).
      * PATCH /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{name}')
      */
-    update(dimensionName: string, hierarchyName: string, elementName: string, update: ElementUpdate): Promise<void>;
+    update(dimensionName: string, hierarchyName: string, elementName: string, update: ElementUpdate): Promise<{
+        typeChange: {
+            from: string;
+            to: string;
+        } | null;
+    }>;
     /**
      * Delete an element. May fail if the element is referenced in rules.
      * DELETE /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements('{name}')
@@ -141,10 +146,26 @@ export declare class ElementService {
         truncated: boolean;
     }>;
     /**
-     * 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
+     */
+    getType(dimensionName: string, hierarchyName: string, elementName: string): Promise<{
+        name: string;
+        type: string;
+    } | null>;
+    /**
+     * 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=...
      */
-    move(dimensionName: string, hierarchyName: string, elementName: string, newParent: string, weight?: number): Promise<void>;
+    consolidatedAmong(dimensionName: string, hierarchyName: string, names: string[]): Promise<string[]>;
     /**
      * Bulk upsert elements into a hierarchy. Two-pass to ensure leaves exist
      * before consolidations reference them: pass 1 creates/upserts every element
@@ -197,7 +218,7 @@ export declare class ElementService {
      * `}ElementAttributes_{Dim}`. Routes through CellService.executeMdx for the
      * cellset round-trip.
      */
-    getAttributeValues(dimensionName: string, elementName: string): Promise<ElementAttributeValue[]>;
+    getAttributeValues(dimensionName: string, elementName: string, hierarchyName?: string): Promise<ElementAttributeValue[]>;
     /**
      * Attribute values for a window of elements — every element of the
      * dimension's default hierarchy, name-sorted, `limit` at a time. One MDX
@@ -222,16 +243,19 @@ export declare class ElementService {
     /**
      * Set a single attribute value. See {@link updateAttributeValues}.
      */
-    updateAttributeValue(dimensionName: string, elementName: string, attributeName: string, value: number | string): Promise<void>;
+    updateAttributeValue(dimensionName: string, elementName: string, attributeName: string, value: number | string, hierarchyName?: string): Promise<void>;
     /**
      * 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.
@@ -240,6 +264,6 @@ export declare class ElementService {
         elementName: string;
         attributeName: string;
         value: number | string;
-    }>): Promise<void>;
+    }>, hierarchyName?: string): Promise<void>;
 }
 //# sourceMappingURL=element-service.d.ts.map