@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tm1-client/services/fallback.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Guard for blanket fallback catch blocks. Rethrows systemic transport/auth
+ * errors and any non-TM1Error (programming errors, unexpected throws); returns
+ * for expected, handleable codes (NOT_FOUND / PERMISSION_DENIED / TM1_ERROR /
+ * UNSUPPORTED_OPERATION / CONFLICT / VALIDATION_ERROR) so the existing
+ * fallback or skip behavior is preserved.
+ *
+ * Usage:
+ *   try { ...primary... }
+ *   catch (e) { rethrowIfSystemic(e); ...fallback... }
+ */
+export declare function rethrowIfSystemic(e: unknown): void;
+/**
+ * Stricter variant for transaction-log windowing/probe paths: rethrows
+ * everything `rethrowIfSystemic` does AND `PERMISSION_DENIED`. Here a permission
+ * denial (e.g. cube-level security on a filtered query) must surface — swallowing
+ * it would return an empty window that reads as "no transactions in range",
+ * hiding the fact the caller simply cannot see the data. Use this instead of
+ * `rethrowIfSystemic` wherever an empty result is otherwise indistinguishable
+ * from "access denied".
+ */
+export declare function rethrowIfSystemicOrDenied(e: unknown): void;
+/**
+ * True when TM1 refused the SHAPE of the query rather than the request itself.
+ *
+ * This is a different axis from `rethrowIfSystemic*`, not a competing
+ * classification: those two answer "may this error be swallowed at all?", this
+ * one answers "is re-asking the same resource with a different OData query
+ * even capable of helping?". Use it AFTER the systemic guard, never instead of
+ * it.
+ *
+ * Only two answers qualify. TM1 rejects a `$select`/`$expand` it cannot parse
+ * or does not implement with 400 (its catch-all for a malformed query option)
+ * or 501; both land as `TM1_ERROR` because `classifyHttpError` only special-
+ * cases 401/403/404/409. `UNSUPPORTED_OPERATION` is the same verdict raised by
+ * our own version gates.
+ *
+ * Everything else is deliberately excluded. A 404 says the collection is not
+ * there — no rewording of the query brings it back. A 500 is a server fault or
+ * a transient, and retrying it three more times with broader queries just
+ * multiplies the outage (see P7: four sequential full scans at ~30 s each).
+ */
+export declare function isUnsupportedQueryShape(e: unknown): boolean;
+//# sourceMappingURL=fallback.d.ts.map

package/dist/tm1-client/services/fallback.js

@@ -0,0 +1,72 @@
+import { TM1Error, TM1ErrorCode } from "../../types.js";
+/**
+ * Transport/auth failures that must NEVER be swallowed by a fallback or
+ * "feature not present" catch block. If one of these surfaces, the caller's
+ * fallback path (e.g. v12 Files → v11 Blobs, $select downgrade, skip private
+ * scope) would mask a real outage — returning empty/partial data as if the
+ * server simply lacked the feature.
+ */
+const SYSTEMIC_CODES = new Set([
+    TM1ErrorCode.AUTH_FAILED,
+    TM1ErrorCode.CONNECTION_FAILED,
+    TM1ErrorCode.LOCK_TIMEOUT,
+]);
+/**
+ * Guard for blanket fallback catch blocks. Rethrows systemic transport/auth
+ * errors and any non-TM1Error (programming errors, unexpected throws); returns
+ * for expected, handleable codes (NOT_FOUND / PERMISSION_DENIED / TM1_ERROR /
+ * UNSUPPORTED_OPERATION / CONFLICT / VALIDATION_ERROR) so the existing
+ * fallback or skip behavior is preserved.
+ *
+ * Usage:
+ *   try { ...primary... }
+ *   catch (e) { rethrowIfSystemic(e); ...fallback... }
+ */
+export function rethrowIfSystemic(e) {
+    if (e instanceof TM1Error && !SYSTEMIC_CODES.has(e.code))
+        return;
+    throw e;
+}
+/**
+ * Stricter variant for transaction-log windowing/probe paths: rethrows
+ * everything `rethrowIfSystemic` does AND `PERMISSION_DENIED`. Here a permission
+ * denial (e.g. cube-level security on a filtered query) must surface — swallowing
+ * it would return an empty window that reads as "no transactions in range",
+ * hiding the fact the caller simply cannot see the data. Use this instead of
+ * `rethrowIfSystemic` wherever an empty result is otherwise indistinguishable
+ * from "access denied".
+ */
+export function rethrowIfSystemicOrDenied(e) {
+    if (e instanceof TM1Error && e.code === TM1ErrorCode.PERMISSION_DENIED)
+        throw e;
+    rethrowIfSystemic(e);
+}
+/**
+ * True when TM1 refused the SHAPE of the query rather than the request itself.
+ *
+ * This is a different axis from `rethrowIfSystemic*`, not a competing
+ * classification: those two answer "may this error be swallowed at all?", this
+ * one answers "is re-asking the same resource with a different OData query
+ * even capable of helping?". Use it AFTER the systemic guard, never instead of
+ * it.
+ *
+ * Only two answers qualify. TM1 rejects a `$select`/`$expand` it cannot parse
+ * or does not implement with 400 (its catch-all for a malformed query option)
+ * or 501; both land as `TM1_ERROR` because `classifyHttpError` only special-
+ * cases 401/403/404/409. `UNSUPPORTED_OPERATION` is the same verdict raised by
+ * our own version gates.
+ *
+ * Everything else is deliberately excluded. A 404 says the collection is not
+ * there — no rewording of the query brings it back. A 500 is a server fault or
+ * a transient, and retrying it three more times with broader queries just
+ * multiplies the outage (see P7: four sequential full scans at ~30 s each).
+ */
+export function isUnsupportedQueryShape(e) {
+    if (!(e instanceof TM1Error))
+        return false;
+    if (e.code === TM1ErrorCode.UNSUPPORTED_OPERATION)
+        return true;
+    return (e.code === TM1ErrorCode.TM1_ERROR &&
+        (e.httpStatus === 400 || e.httpStatus === 501));
+}
+//# sourceMappingURL=fallback.js.map

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

@@ -0,0 +1,53 @@
+import type { TM1HttpClient } from "../http.js";
+export declare class FileService {
+    private readonly http;
+    constructor(http: TM1HttpClient);
+    /**
+     * 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[]>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Upload (create-or-update) a file. Two-step v11 protocol:
+     *   1. POST entity into the parent Contents collection (only if missing)
+     *   2. PUT raw bytes to the entity's /Content
+     * Tries 'Files' (v12) first, falls back to 'Blobs' (v11).
+     *
+     * Subfolders only supported on TM1 v12. Caller must ensure parent folders
+     * exist (folder-create not yet exposed).
+     */
+    upload(fileName: string, content: Uint8Array): Promise<{
+        created: boolean;
+        root: "Files" | "Blobs";
+    }>;
+    /**
+     * Delete a file from blob/file storage. Tries 'Files' first, then 'Blobs'.
+     */
+    delete(fileName: string): Promise<void>;
+    /**
+     * Search file names in a folder using OData $filter.
+     * - startswith: case-insensitive prefix match
+     * - contains: list of case-insensitive substring matches, joined by `operator`
+     */
+    search(opts: {
+        startswith?: string | undefined;
+        contains?: string[] | undefined;
+        operator?: "and" | "or" | undefined;
+        path?: string | undefined;
+    }): Promise<string[]>;
+}
+//# sourceMappingURL=file-service.d.ts.map

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

@@ -0,0 +1,218 @@
+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, "''"));
+// Split a user-supplied file path into segments, rejecting "." / ".." so a
+// crafted name cannot traverse outside the Contents root.
+function splitPath(raw) {
+    const parts = raw.split("/").filter(Boolean);
+    if (parts.some((p) => p === "." || p === "..")) {
+        throw new TM1Error({
+            code: TM1ErrorCode.VALIDATION_ERROR,
+            message: `Invalid path "${raw}": "." and ".." segments are not allowed`,
+            endpoint: raw,
+        });
+    }
+    return parts;
+}
+export class FileService {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * 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) {
+        const segments = path ? splitPath(path) : [];
+        const buildUrl = (root) => {
+            let url = `/api/v1/Contents('${enc(root)}')`;
+            for (const seg of segments) {
+                url += `/Contents('${enc(seg)}')`;
+            }
+            url += "/Contents?$select=Name";
+            return url;
+        };
+        try {
+            const r = await this.http.request("GET", buildUrl("Files"));
+            return r.value.map((f) => f.Name);
+        }
+        catch (e) {
+            rethrowIfSystemic(e);
+            const r = await this.http.request("GET", buildUrl("Blobs"));
+            return r.value.map((f) => f.Name);
+        }
+    }
+    /**
+     * 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'.
+     */
+    async getContent(fileName) {
+        const parts = splitPath(fileName);
+        const buildUrl = (root) => {
+            let url = `/api/v1/Contents('${enc(root)}')`;
+            for (const p of parts) {
+                url += `/Contents('${enc(p)}')`;
+            }
+            url += "/Content";
+            return url;
+        };
+        try {
+            return await this.http.requestRaw("GET", buildUrl("Files"));
+        }
+        catch (e) {
+            rethrowIfSystemic(e);
+            return await this.http.requestRaw("GET", buildUrl("Blobs"));
+        }
+    }
+    /**
+     * 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.
+     */
+    async exists(fileName) {
+        const parts = splitPath(fileName);
+        if (parts.length === 0)
+            return false;
+        const buildUrl = (root) => {
+            const segs = parts
+                .slice(0, -1)
+                .map((s) => `/Contents('${enc(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`;
+        };
+        const probe = async (url) => {
+            try {
+                await this.http.request("GET", url);
+                return true;
+            }
+            catch (e) {
+                const code = e.code;
+                if (code === "NOT_FOUND")
+                    return false;
+                throw e;
+            }
+        };
+        if (await probe(buildUrl("Files")))
+            return true;
+        return probe(buildUrl("Blobs"));
+    }
+    /**
+     * Upload (create-or-update) a file. Two-step v11 protocol:
+     *   1. POST entity into the parent Contents collection (only if missing)
+     *   2. PUT raw bytes to the entity's /Content
+     * Tries 'Files' (v12) first, falls back to 'Blobs' (v11).
+     *
+     * Subfolders only supported on TM1 v12. Caller must ensure parent folders
+     * exist (folder-create not yet exposed).
+     */
+    async upload(fileName, content) {
+        const parts = splitPath(fileName);
+        if (parts.length === 0) {
+            throw new TM1Error({
+                code: TM1ErrorCode.VALIDATION_ERROR,
+                message: "upload: empty file name",
+            });
+        }
+        // parts.length > 0 is guarded above
+        const leaf = parts[parts.length - 1];
+        const parentSegs = parts
+            .slice(0, -1)
+            .map((s) => `/Contents('${enc(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 existed = await this.exists(fileName).catch(() => false);
+            if (!existed) {
+                await this.http.request("POST", parentUrl, {
+                    "@odata.type": "#ibm.tm1.api.v1.Document",
+                    ID: leaf,
+                    Name: leaf,
+                });
+            }
+            await this.http.requestBinary("PUT", contentUrl, content);
+            return { created: !existed, root };
+        };
+        try {
+            return await tryRoot("Files");
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "NOT_FOUND")
+                throw e;
+            return await tryRoot("Blobs");
+        }
+    }
+    /**
+     * Delete a file from blob/file storage. Tries 'Files' first, then 'Blobs'.
+     */
+    async delete(fileName) {
+        const parts = splitPath(fileName);
+        if (parts.length === 0) {
+            throw new TM1Error({
+                code: TM1ErrorCode.VALIDATION_ERROR,
+                message: "delete: empty file name",
+            });
+        }
+        const buildUrl = (root) => {
+            const segs = parts.map((s) => `/Contents('${enc(s)}')`).join("");
+            return `/api/v1/Contents('${enc(root)}')${segs}`;
+        };
+        try {
+            await this.http.request("DELETE", buildUrl("Files"));
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "NOT_FOUND")
+                throw e;
+            await this.http.request("DELETE", buildUrl("Blobs"));
+        }
+    }
+    /**
+     * Search file names in a folder using OData $filter.
+     * - startswith: case-insensitive prefix match
+     * - contains: list of case-insensitive substring matches, joined by `operator`
+     */
+    async search(opts) {
+        const operator = opts.operator ?? "and";
+        const segments = opts.path ? splitPath(opts.path) : [];
+        const escape = (s) => s.replace(/'/g, "''");
+        const filters = [];
+        if (opts.startswith) {
+            filters.push(`startswith(tolower(Name),tolower('${escape(opts.startswith)}'))`);
+        }
+        if (opts.contains && opts.contains.length > 0) {
+            const subs = opts.contains.map((s) => `contains(tolower(Name),tolower('${escape(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)}')`;
+            for (const seg of segments)
+                url += `/Contents('${enc(seg)}')`;
+            url += `/Contents?$select=Name${filter}`;
+            return url;
+        };
+        try {
+            const r = await this.http.request("GET", buildUrl("Files"));
+            return r.value.map((f) => f.Name);
+        }
+        catch (e) {
+            rethrowIfSystemic(e);
+            const r = await this.http.request("GET", buildUrl("Blobs"));
+            return r.value.map((f) => f.Name);
+        }
+    }
+}
+//# sourceMappingURL=file-service.js.map

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

@@ -0,0 +1,129 @@
+import type { Hierarchy, HierarchyElement } from "../../types.js";
+import type { TM1HttpClient } from "../http.js";
+/**
+ * A hierarchy plus the size of the element set the request selected, so
+ * callers can page without guessing. `totalElements` counts elements that
+ * survived *every* filter — the server-side `$filter` ones via
+ * `Elements@odata.count`, the client-side ones (elementType, nameRegex) by
+ * counting what is left after filtering. It is therefore always exact, and
+ * always ≥ `elements.length`.
+ */
+export type HierarchyPage = Hierarchy & {
+    totalElements: number;
+};
+/** Element filters shared by {@link HierarchyService.get} and {@link HierarchyService.getCounts}. */
+export interface ElementFilterOpts {
+    level?: number;
+    levelMax?: number;
+    elementType?: "Numeric" | "String" | "Consolidated" | "All";
+    nameContains?: string;
+    nameStartsWith?: string;
+    nameRegex?: string;
+}
+/** Element totals of a (filtered) hierarchy, without the elements. */
+export interface HierarchyCounts {
+    total: number;
+    byType: {
+        Numeric: number;
+        String: number;
+        Consolidated: number;
+    };
+    /** Level → element count. Keys are the level as a string ("0" = leaves). */
+    byLevel: Record<string, number>;
+    maxLevel: number;
+}
+export declare class HierarchyService {
+    private readonly http;
+    constructor(http: TM1HttpClient);
+    /**
+     * Get a specific hierarchy with its elements, including parent/child
+     * relationships. TM1 11.8 does not expose `Children` on Element, only
+     * `Parents` — children are derived client-side. Filtered-out parents are
+     * removed from the surviving elements' parents/children arrays to avoid
+     * dangling references.
+     *
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')?$expand=Elements(...)
+     *
+     * Paging: when no client-side post-filter is needed, `topN`/`skip` are
+     * pushed into the nested Elements expand together with `$orderby=Name` and
+     * `$count=true`. On a live 211k-element dimension that is 48 KB/page against
+     * 67 MB for the unbounded fetch. `$orderby` is not optional — without it
+     * `$skip` walks TM1's internal index order, which shifts on every element
+     * create/delete and would duplicate or drop elements between pages.
+     */
+    get(dimensionName: string, hierarchyName: string, opts?: ElementFilterOpts & {
+        topN?: number;
+        /**
+         * Elements to skip before `topN`. Applied server-side when possible and
+         * after client-side filtering otherwise, so the caller sees the same
+         * pagination semantics either way.
+         */
+        skip?: number;
+    }): Promise<HierarchyPage>;
+    /**
+     * Element totals by type and level for a (filtered) hierarchy — no element
+     * rows. Reads the Elements collection with `$select=Type,Level` (plus Name
+     * only when a regex has to run client-side), so a count over a 200k-element
+     * dimension costs a few MB of wire traffic and a few hundred bytes of reply,
+     * where probing with growing `topN` returned the elements themselves.
+     *
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements?$select=Type,Level
+     */
+    getCounts(dimensionName: string, hierarchyName: string, opts?: ElementFilterOpts): Promise<HierarchyCounts>;
+    /**
+     * Element name + type for a whole hierarchy — nothing else.
+     *
+     * `get()` is the wrong tool for a type lookup: it expands `Parents` and
+     * `Edges` on every element to build the tree and weight the children. This
+     * reads the Elements collection directly with `$select=Name,Type` — no
+     * expand at all — which is the minimum payload for name → type resolution.
+     *
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Elements?$select=Name,Type
+     */
+    getElementTypes(dimensionName: string, hierarchyName: string): Promise<Array<{
+        name: string;
+        type: HierarchyElement["type"];
+    }>>;
+    /**
+     * Resolve descendants of a consolidation element via client-side BFS over
+     * the full hierarchy. Returns a flat list with depth from the start element.
+     * Reuses get() — REST traffic identical, but the LLM-facing payload is a
+     * focused subtree, not the whole dimension.
+     */
+    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;
+        }>;
+    }>;
+    /**
+     * Resolve ancestors of an element via parent-walk. Handles multi-parent
+     * hierarchies — returns the unique flat ancestor set AND every distinct
+     * root-to-element path so consumers can see consolidation alternatives.
+     */
+    getAncestors(dimensionName: string, hierarchyName: string, element: string): Promise<{
+        element: string;
+        ancestors: Array<{
+            name: string;
+            level: number;
+        }>;
+        paths: string[][];
+    }>;
+    /**
+     * Create a new hierarchy inside an existing dimension.
+     * POST /api/v1/Dimensions('{d}')/Hierarchies
+     */
+    create(dimensionName: string, hierarchyName: string): Promise<void>;
+    /**
+     * Delete a hierarchy from a dimension.
+     * DELETE /api/v1/Dimensions('{d}')/Hierarchies('{h}')
+     */
+    delete(dimensionName: string, hierarchyName: string): Promise<void>;
+}
+//# sourceMappingURL=hierarchy-service.d.ts.map