@ffschrattenecker/tm1-mcp-server 6.0.0

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

@@ -0,0 +1,504 @@
+// Server domain service. Owns server-level read endpoints — configuration,
+// message log, transaction log, error-log files. Stateless wrappers; nothing
+// here mutates server state.
+//
+// See docs/ARCHITECTURE.md for the layering.
+import { TM1Error, TM1ErrorCode } from "../../types.js";
+import { rethrowIfSystemicOrDenied } from "./fallback.js";
+// TM1 references the per-run TI error file inside the free-text message, either
+// wrapped in angle brackets (e.g. German `Fehlerdatei: <…log>`) or bare
+// (`see TM1ProcessError_…log`). Both regexes are linear (no nested quantifiers,
+// delimiter excluded from the class) — no ReDoS guard needed for these literals.
+const ANGLE_WRAPPED_LOG = /<([^<>\s]+\.log)>/i;
+const BARE_PROCESS_ERROR_LOG = /TM1ProcessError_[^\s<>'"()]+\.log/i;
+/**
+ * Pull the TM1 error log filename out of a message-log entry's free text, so it
+ * can be fed straight into `tm1_get_error_log_content(filename=…)`. Returns the
+ * exact filename (no surrounding brackets) or undefined when none is mentioned.
+ */
+export function extractErrorFile(message) {
+    const angle = message.match(ANGLE_WRAPPED_LOG);
+    if (angle)
+        return angle[1];
+    const bare = message.match(BARE_PROCESS_ERROR_LOG);
+    return bare ? bare[0] : undefined;
+}
+// The TransactionLogEntries endpoint scans the whole log server-side and is
+// slow; without log-read rights it can hang until the global request timeout.
+// Before the real (orderby + filtered) query we fire a bare `$top=1` probe —
+// NO $orderby, NO $filter, so TM1 can stop after the first row and the result
+// is at most one entry — bounded by a short timeout to fail fast.
+const TXLOG_PROBE_TIMEOUT_MS = 8000;
+// Per-window query timeout. Each windowed/bounded query runs once (no retry),
+// so a timeout means the range is too large/dense — not a transient blip.
+const TXLOG_QUERY_TIMEOUT_MS = 20000;
+// Expanding lookback windows (ms) for the no-`since` adaptive backfill. We walk
+// backward from the anchor, widening until `top` rows are collected or the last
+// window is exhausted — so an open-ended call never triggers a full-log scan.
+const TXLOG_BACKFILL_WINDOWS_MS = [
+    10 * 60_000, // 10 min
+    60 * 60_000, // 1 h
+    6 * 3_600_000, // 6 h
+    24 * 3_600_000, // 1 d
+    3 * 86_400_000, // 3 d
+    7 * 86_400_000, // 7 d
+    30 * 86_400_000, // 30 d
+    90 * 86_400_000, // 90 d
+    365 * 86_400_000, // 1 y
+];
+// Format an epoch-ms instant as an OData UTC literal (second precision, no ms).
+function epochToOData(ms) {
+    return `${new Date(ms).toISOString().slice(0, 19)}Z`;
+}
+/**
+ * Normalize a user timestamp into an OData v4 DateTimeOffset literal for a
+ * TM1 $filter. TM1 rejects a bare `2026-06-08T00:00:00` ("Syntax error … near
+ * -06") — the value MUST carry a timezone. Verified against TM1 11.8: only the
+ * `Z`-suffixed (or ±hh:mm-offset) form parses. Date-only input expands to
+ * start-of-day UTC; a zoneless datetime gets a `Z`; an already-zoned value is
+ * left untouched.
+ */
+export function toOdataDateTime(input) {
+    let t = input.trim();
+    if (/^\d{4}-\d{2}-\d{2}$/.test(t))
+        t = `${t}T00:00:00`;
+    if (!/[zZ]$/.test(t) && !/[+-]\d{2}:\d{2}$/.test(t))
+        t = `${t}Z`;
+    // Validate before it reaches a $filter. Appending "Z" to whatever arrived
+    // turned "yesterday" into "yesterdayZ" and shipped it to TM1, which answers
+    // with an opaque OData parse error naming neither the parameter nor the bad
+    // value. Rejecting here names both.
+    //
+    // Shape check FIRST, then Date.parse — Date.parse alone is too permissive to
+    // be a gate. It accepts V8's legacy formats, so "08/06/2026" parses happily
+    // as 6 August; a caller who meant 8 June would silently get a different day
+    // and a plausible-looking, wrong result. Ambiguous input must fail loudly.
+    const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+    if (!ISO_DATETIME.test(t) || Number.isNaN(Date.parse(t))) {
+        throw new TM1Error({
+            code: TM1ErrorCode.VALIDATION_ERROR,
+            message: `Not a usable timestamp: '${input}'. Expected ISO-8601 — ` +
+                `'2026-06-08', '2026-06-08T14:30:00', or with a zone ` +
+                `('...Z' / '...+02:00'). A value without a zone is read as UTC.`,
+        });
+    }
+    return t;
+}
+// enc stays plain — it also wraps whole $filter/$orderby clauses below, where
+// the inner string literals are already single-quote-escaped via esc().
+const enc = encodeURIComponent;
+// OData entity-key encoder: double ' per OData literal rules, then percent-encode.
+const encKey = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+export class ServerService {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Fetch TM1 server configuration. Merges /Configuration and
+     * /ActiveConfiguration; tolerates ActiveConfiguration being absent on
+     * older builds.
+     */
+    async getInfo() {
+        const cfg = await this.http.request("GET", "/api/v1/Configuration");
+        let active = {};
+        try {
+            active = await this.http.request("GET", "/api/v1/ActiveConfiguration");
+        }
+        catch {
+            // Some TM1 versions don't expose ActiveConfiguration — ignore.
+        }
+        const merged = { ...cfg, ...active };
+        delete merged["@odata.context"];
+        // v12 (Planning Analytics Engine) omits ProductVersion from the
+        // Configuration object body; it is exposed only as a scalar sub-resource.
+        // Fall back to it when the inline field is absent (v11 has it inline, so
+        // this extra request never fires there).
+        let productVersion = String(merged.ProductVersion ?? "");
+        if (!productVersion) {
+            try {
+                const pv = await this.http.request("GET", "/api/v1/Configuration/ProductVersion");
+                if (typeof pv.value === "string") {
+                    productVersion = pv.value;
+                }
+            }
+            catch {
+                // Scalar sub-resource unavailable — leave version empty.
+            }
+        }
+        return {
+            serverName: String(merged.ServerName ?? ""),
+            productVersion,
+            productEdition: merged.ProductEdition !== undefined
+                ? String(merged.ProductEdition)
+                : undefined,
+            adminHost: merged.AdminHost !== undefined ? String(merged.AdminHost) : undefined,
+            dataDirectory: merged.DataBaseDirectory !== undefined
+                ? String(merged.DataBaseDirectory)
+                : undefined,
+            timeZoneId: merged.TimeZoneID !== undefined ? String(merged.TimeZoneID) : undefined,
+            integratedSecurityMode: merged.IntegratedSecurityMode !== undefined
+                ? String(merged.IntegratedSecurityMode)
+                : undefined,
+            extra: merged,
+        };
+    }
+    /**
+     * Get recent TM1 server message log entries (newest first).
+     *
+     * The text/level/time filters are pushed to the server via `$filter` so a
+     * match OLDER than the `top`-row window is still found — filtering only the
+     * newest `top` rows client-side produced false negatives ("no error found")
+     * whenever the matching entry had scrolled past that window. TM1 v11 supports
+     * OData `contains`/`tolower`/`eq`/`ge`/`le` on the MessageLogEntries set.
+     *
+     * Text match is case-insensitive (tolower on both sides) to preserve the prior
+     * client-side `.toLowerCase().includes()` contract. If the server rejects the
+     * filtered query (older/limited builds without full string-function support),
+     * we fall back to fetching the newest `top` rows and filtering in-process —
+     * the same best-effort path as before, so the tool degrades rather than errors.
+     *
+     * GET /api/v1/MessageLogEntries?$orderby=TimeStamp desc&$top={top}[&$filter=…]
+     */
+    async getMessageLog(opts = {}) {
+        const top = opts.top ?? 100;
+        // Inner-literal single-quote escaping per OData; the whole clause is then
+        // URL-encoded with enc() below (mirrors getAuditLog()'s esc()+enc() pattern).
+        const esc = (s) => s.replace(/'/g, "''");
+        const filters = [];
+        if (opts.filter)
+            filters.push(`contains(tolower(Message),'${esc(opts.filter.toLowerCase())}')`);
+        if (opts.level)
+            filters.push(`toupper(Level) eq '${esc(opts.level.toUpperCase())}'`);
+        if (opts.logger)
+            filters.push(`Logger eq '${esc(opts.logger)}'`);
+        if (opts.since)
+            filters.push(`TimeStamp ge ${toOdataDateTime(opts.since)}`);
+        if (opts.until)
+            filters.push(`TimeStamp le ${toOdataDateTime(opts.until)}`);
+        const qs = [`$orderby=${enc("TimeStamp desc")}`, `$top=${top}`];
+        if (filters.length > 0)
+            qs.push(`$filter=${enc(filters.join(" and "))}`);
+        const map = (rows) => rows.map((e) => {
+            const message = e.Message ?? e.Text ?? "";
+            const errorFile = extractErrorFile(message);
+            return {
+                timestamp: e.TimeStamp ?? e.Timestamp ?? "",
+                level: (e.Level ?? "").toUpperCase(),
+                message,
+                ...(errorFile ? { errorFile } : {}),
+            };
+        });
+        if (filters.length === 0) {
+            const response = await this.http.request("GET", `/api/v1/MessageLogEntries?${qs.join("&")}`);
+            return map(response.value);
+        }
+        try {
+            const response = await this.http.request("GET", `/api/v1/MessageLogEntries?${qs.join("&")}`);
+            return map(response.value);
+        }
+        catch (err) {
+            // Systemic transport/auth failures and permission denials must surface —
+            // only a server-side rejection of the filter expression itself should
+            // trigger the degraded client-side fallback.
+            rethrowIfSystemicOrDenied(err);
+            const response = await this.http.request("GET", `/api/v1/MessageLogEntries?$orderby=${enc("TimeStamp desc")}&$top=${top}`);
+            // Degraded path: re-apply the FULL filter set client-side over the
+            // newest-`top` window. Filtering raw rows (pre-map) so Logger/TimeStamp
+            // are available — otherwise since/until/logger would be silently dropped
+            // and out-of-range rows returned mislabeled as matches.
+            let rows = response.value;
+            if (opts.filter) {
+                const needle = opts.filter.toLowerCase();
+                rows = rows.filter((e) => (e.Message ?? e.Text ?? "").toLowerCase().includes(needle));
+            }
+            if (opts.level) {
+                const want = opts.level.toUpperCase();
+                rows = rows.filter((e) => (e.Level ?? "").toUpperCase() === want);
+            }
+            if (opts.logger) {
+                rows = rows.filter((e) => e.Logger === opts.logger);
+            }
+            if (opts.since) {
+                const from = Date.parse(opts.since);
+                if (!Number.isNaN(from)) {
+                    rows = rows.filter((e) => {
+                        const ts = Date.parse(e.TimeStamp ?? e.Timestamp ?? "");
+                        return !Number.isNaN(ts) && ts >= from;
+                    });
+                }
+            }
+            if (opts.until) {
+                const to = Date.parse(opts.until);
+                if (!Number.isNaN(to)) {
+                    rows = rows.filter((e) => {
+                        const ts = Date.parse(e.TimeStamp ?? e.Timestamp ?? "");
+                        return !Number.isNaN(ts) && ts <= to;
+                    });
+                }
+            }
+            return map(rows);
+        }
+    }
+    /**
+     * Fetch recent TM1 audit log entries (metadata/security changes), newest
+     * first. Requires AuditLogOn=T in tm1s.cfg — with auditing disabled the
+     * entity set is empty.
+     * GET /api/v1/AuditLogEntries
+     */
+    async getAuditLog(opts) {
+        const esc = (s) => s.replace(/'/g, "''");
+        const filters = [];
+        if (opts.user)
+            filters.push(`UserName eq '${esc(opts.user)}'`);
+        if (opts.objectType)
+            filters.push(`ObjectType eq '${esc(opts.objectType)}'`);
+        if (opts.objectName)
+            filters.push(`ObjectName eq '${esc(opts.objectName)}'`);
+        if (opts.since)
+            filters.push(`TimeStamp ge ${toOdataDateTime(opts.since)}`);
+        if (opts.until)
+            filters.push(`TimeStamp le ${toOdataDateTime(opts.until)}`);
+        const top = opts.top ?? 100;
+        const qs = [`$top=${top}`, `$orderby=${enc("TimeStamp desc")}`];
+        if (filters.length > 0)
+            qs.push(`$filter=${enc(filters.join(" and "))}`);
+        if (opts.includeDetails)
+            qs.push("$expand=AuditDetails");
+        const response = await this.http.request("GET", `/api/v1/AuditLogEntries?${qs.join("&")}`);
+        const mapDetail = (d) => ({
+            id: d.ID ?? 0,
+            timestamp: d.TimeStamp ?? "",
+            user: d.UserName ?? "",
+            description: d.Description ?? "",
+            objectType: d.ObjectType ?? "",
+            objectName: d.ObjectName ?? "",
+        });
+        return response.value.map((e) => {
+            const entry = mapDetail(e);
+            if (e.AuditDetails !== undefined)
+                entry.details = e.AuditDetails.map(mapDetail);
+            return entry;
+        });
+    }
+    /**
+     * Fetch recent TM1 transaction log entries (cell writes).
+     * GET /api/v1/TransactionLogEntries
+     */
+    async getTransactionLog(opts) {
+        const top = opts.top ?? 100;
+        // Preflight: bare $top=1 (no orderby/filter) — cheap reachability/permission
+        // gate that fails fast instead of hanging.
+        await this.probeTransactionLog();
+        // Explicit lower bound → a single bounded query [since, until]. Coverage is
+        // well-defined by the bound: everything in the span is returned.
+        if (opts.since !== undefined) {
+            const entries = await this.queryTransactionLog({
+                top,
+                cubeName: opts.cubeName,
+                user: opts.user,
+                since: opts.since,
+                until: opts.until,
+            });
+            return {
+                entries,
+                coverage: "complete",
+                scannedFrom: toOdataDateTime(opts.since),
+            };
+        }
+        // No lower bound → adaptive backward windowing from `until` (or now). An
+        // unbounded TransactionLogEntries scan takes minutes-to-hours; instead we
+        // probe expanding windows and stop as soon as we have `top` rows. If a wide
+        // window times out we keep the rows already collected rather than failing.
+        // Coverage: "partial" if we stopped because `top` filled or a window failed
+        // (older matching rows may exist earlier); "complete" if windows exhausted.
+        const anchorMs = opts.until !== undefined
+            ? Date.parse(toOdataDateTime(opts.until))
+            : Date.now();
+        let collected = [];
+        let scannedFromMs = anchorMs;
+        for (const windowMs of TXLOG_BACKFILL_WINDOWS_MS) {
+            const floorMs = anchorMs - windowMs;
+            let entries;
+            try {
+                entries = await this.queryTransactionLog({
+                    top,
+                    cubeName: opts.cubeName,
+                    user: opts.user,
+                    since: epochToOData(floorMs),
+                    until: opts.until,
+                });
+            }
+            catch (err) {
+                // Systemic transport/auth failures (CONNECTION_FAILED, AUTH_FAILED,
+                // LOCK_TIMEOUT) AND permission denials must surface — swallowing them
+                // would return an empty or partial window as if the range simply held no
+                // data (or as if a denied cube were empty). A window timeout (TM1_ERROR
+                // from queryTransactionLog) is expected and just stops widening — but we
+                // stopped short of exhausting the span, so coverage is partial.
+                rethrowIfSystemicOrDenied(err);
+                return {
+                    entries: collected,
+                    coverage: "partial",
+                    scannedFrom: epochToOData(scannedFromMs),
+                };
+            }
+            scannedFromMs = floorMs;
+            collected = entries;
+            if (entries.length >= top) {
+                return {
+                    entries,
+                    coverage: "partial",
+                    scannedFrom: epochToOData(floorMs),
+                };
+            }
+        }
+        return {
+            entries: collected,
+            coverage: "complete",
+            scannedFrom: epochToOData(scannedFromMs),
+        };
+    }
+    /**
+     * Single bounded TransactionLogEntries query. Runs once (retry disabled) under
+     * a dedicated timeout: the endpoint is deterministically slow, so a timeout
+     * means "range too large", not a transient blip. Our own timeout (the
+     * controller abort) and other non-systemic failures become an actionable
+     * "narrow the range" error; systemic transport/auth failures propagate
+     * unmasked and permission denials surface as-is.
+     */
+    async queryTransactionLog(q) {
+        const filters = [];
+        if (q.cubeName)
+            filters.push(`Cube eq '${q.cubeName.replace(/'/g, "''")}'`);
+        if (q.user)
+            filters.push(`User eq '${q.user.replace(/'/g, "''")}'`);
+        if (q.since)
+            filters.push(`TimeStamp ge ${toOdataDateTime(q.since)}`);
+        if (q.until)
+            filters.push(`TimeStamp le ${toOdataDateTime(q.until)}`);
+        const qs = [`$top=${q.top}`, `$orderby=TimeStamp desc`];
+        if (filters.length > 0)
+            qs.push(`$filter=${enc(filters.join(" and "))}`);
+        const path = `/api/v1/TransactionLogEntries?${qs.join("&")}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TXLOG_QUERY_TIMEOUT_MS);
+        try {
+            const response = await this.http.request("GET", path, undefined, { signal: controller.signal, retry: false });
+            return response.value.map((e) => ({
+                timestamp: e.TimeStamp ?? "",
+                user: e.User ?? "",
+                cubeName: e.Cube ?? "",
+                elements: e.Tuple ?? [],
+                oldValue: e.OldValue ?? null,
+                newValue: e.NewValue ?? null,
+            }));
+        }
+        catch (err) {
+            // Our own dedicated timeout aborts via the controller and surfaces as a
+            // raw (non-TM1) abort — that IS the "range too large" signal. For every
+            // other error, systemic transport/auth failures (CONNECTION_FAILED,
+            // AUTH_FAILED, LOCK_TIMEOUT) and unexpected non-TM1 throws must propagate
+            // unmasked, and a permission denial stays actionable; only then do we fall
+            // through and treat the failure as an actionable "narrow the range" error.
+            if (!controller.signal.aborted) {
+                rethrowIfSystemicOrDenied(err);
+            }
+            throw new TM1Error({
+                code: TM1ErrorCode.TM1_ERROR,
+                message: `Transaction log query exceeded ${TXLOG_QUERY_TIMEOUT_MS / 1000}s — the time range is too large or dense.`,
+                endpoint: path,
+                details: err instanceof Error ? err.message : String(err),
+                hint: "Bound the scan with a narrower since/until (from-to) range, or add cubeName/user.",
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Cheap reachability/permission probe for the transaction log. A bare
+     * `$top=1` (no $orderby/$filter) returns at most one row so TM1 can short-
+     * circuit; a dedicated short-timeout AbortController caps the wait. That
+     * timeout (and other non-systemic failures) becomes an actionable TM1_ERROR;
+     * permission denials surface as-is and systemic transport/auth failures
+     * (e.g. CONNECTION_FAILED) propagate unmasked.
+     */
+    async probeTransactionLog() {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TXLOG_PROBE_TIMEOUT_MS);
+        try {
+            await this.http.request("GET", "/api/v1/TransactionLogEntries?$top=1", undefined, { signal: controller.signal });
+        }
+        catch (err) {
+            // Our own probe timeout aborts via the controller and yields the friendly
+            // preflight message. For every other error, systemic transport/auth
+            // failures (CONNECTION_FAILED, AUTH_FAILED, LOCK_TIMEOUT) and unexpected
+            // non-TM1 throws must propagate unmasked, and a permission denial stays
+            // actionable (fail fast); only then do we wrap as a TM1_ERROR preflight.
+            if (!controller.signal.aborted) {
+                rethrowIfSystemicOrDenied(err);
+            }
+            throw new TM1Error({
+                code: TM1ErrorCode.TM1_ERROR,
+                message: `Transaction log preflight failed (timeout ${TXLOG_PROBE_TIMEOUT_MS / 1000}s): the endpoint scans the whole log and may hang or be denied without log-read rights.`,
+                endpoint: "/api/v1/TransactionLogEntries",
+                details: err instanceof Error ? err.message : String(err),
+                hint: "Narrow the query with `since`, `cubeName`, or `user`, or verify the account has transaction-log read rights.",
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * List TI process error log files.
+     *
+     * TM1 v11 OData exposes only `Filename` on this entity set (no LastUpdated /
+     * $select / $orderby support). Sorting is filename-descending — filenames
+     * embed a yyyymmddhhmmss timestamp, so lexical desc sort matches
+     * chronological newest-first. Filters (processName, since, top) are applied
+     * client-side.
+     */
+    async listErrorLogFiles(opts = {}) {
+        const top = opts.top ?? 50;
+        const response = await this.http.request("GET", "/api/v1/ErrorLogFiles");
+        let entries = response.value
+            .map((e) => ({ filename: e.Filename ?? "" }))
+            .filter((e) => e.filename);
+        if (opts.processName) {
+            const proc = opts.processName.toLowerCase();
+            // TM1 v11+ pattern with session hash: TM1ProcessError_<ts>_<id>_<proc>_<hash>.log
+            // TM1 pattern without hash:           TM1ProcessError_<ts>_<id>_<proc>.log
+            // Legacy/manual pattern:              <proc>_<ts>.log
+            entries = entries.filter((e) => {
+                const f = e.filename.toLowerCase();
+                return (f === proc ||
+                    f.startsWith(`${proc}_`) ||
+                    f.endsWith(`_${proc}.log`) ||
+                    f.includes(`_${proc}_`));
+            });
+        }
+        if (opts.since) {
+            const sinceCompact = opts.since.replace(/[^0-9]/g, "").slice(0, 14);
+            if (sinceCompact.length >= 8) {
+                entries = entries.filter((e) => {
+                    const m = e.filename.match(/(?:TM1ProcessError_|_)(\d{14})/) ??
+                        e.filename.match(/_(\d{8,14})\.log$/i);
+                    return m ? m[1] >= sinceCompact.slice(0, m[1].length) : true;
+                });
+            }
+        }
+        entries.sort((a, b) => a.filename < b.filename ? 1 : a.filename > b.filename ? -1 : 0);
+        return entries.slice(0, top);
+    }
+    /**
+     * Fetch the raw text content of a single TI error log file.
+     * GET /api/v1/ErrorLogFiles('<filename>')/Content
+     */
+    async getErrorLogContent(filename) {
+        const path = `/api/v1/ErrorLogFiles('${encKey(filename)}')/Content`;
+        return await this.http.requestRaw("GET", path);
+    }
+}
+//# sourceMappingURL=server-service.js.map

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

@@ -0,0 +1,37 @@
+import type { Subset, SubsetCreate } from "../../types.js";
+import type { TM1HttpClient } from "../http.js";
+export declare class SubsetService {
+    private readonly http;
+    constructor(http: TM1HttpClient);
+    /**
+     * List public + private subsets of a hierarchy.
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Subsets|PrivateSubsets
+     */
+    list(dimensionName: string, hierarchyName: string): Promise<Subset[]>;
+    /**
+     * Get a single subset incl. resolved Elements.
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Subsets('{s}')?$expand=Elements($select=Name)
+     */
+    get(dimensionName: string, hierarchyName: string, subsetName: string, isPrivate?: boolean): Promise<Subset>;
+    /**
+     * Create a public subset. Either MDX-based (expression) or static
+     * (elements). Mixed/empty inputs throw VALIDATION_ERROR.
+     * POST /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Subsets
+     */
+    create(dimensionName: string, hierarchyName: string, subset: SubsetCreate): Promise<void>;
+    /**
+     * Update an existing public subset.
+     * PATCH /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Subsets('{s}')
+     */
+    update(dimensionName: string, hierarchyName: string, subsetName: string, update: {
+        expression?: string | undefined;
+        elements?: string[] | undefined;
+        alias?: string | undefined;
+    }): Promise<void>;
+    /**
+     * Delete a public subset.
+     * DELETE /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Subsets('{s}')
+     */
+    delete(dimensionName: string, hierarchyName: string, subsetName: string): Promise<void>;
+}
+//# sourceMappingURL=subset-service.d.ts.map

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

@@ -0,0 +1,122 @@
+// Subset domain service. Owns the OData calls under
+// /api/v1/Dimensions('{d}')/Hierarchies('{h}')/{Subsets|PrivateSubsets} —
+// list, get, create, update, delete. Subsets are either MDX-based
+// (Expression) or static (Elements list); both shapes are handled here.
+//
+// See docs/ARCHITECTURE.md for the layering.
+import { TM1Error, TM1ErrorCode } from "../../types.js";
+import { rethrowIfSystemic } from "./fallback.js";
+// OData key encoder: double ' per OData literal rules, then percent-encode.
+const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+export class SubsetService {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * List public + private subsets of a hierarchy.
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Subsets|PrivateSubsets
+     */
+    async list(dimensionName, hierarchyName) {
+        const result = [];
+        const fetchScope = async (segment, isPrivate) => {
+            try {
+                const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/${segment}?$select=Name,Expression,Alias`;
+                const response = await this.http.request("GET", path);
+                for (const s of response.value) {
+                    result.push({
+                        name: s.Name,
+                        dimensionName,
+                        hierarchyName,
+                        private: isPrivate,
+                        expression: s.Expression || undefined,
+                        elements: [],
+                        alias: s.Alias || undefined,
+                    });
+                }
+            }
+            catch (e) {
+                rethrowIfSystemic(e);
+                // scope may not exist
+            }
+        };
+        await fetchScope("Subsets", false);
+        await fetchScope("PrivateSubsets", true);
+        return result;
+    }
+    /**
+     * Get a single subset incl. resolved Elements.
+     * GET /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Subsets('{s}')?$expand=Elements($select=Name)
+     */
+    async get(dimensionName, hierarchyName, subsetName, isPrivate = false) {
+        const segment = isPrivate ? "PrivateSubsets" : "Subsets";
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/${segment}('${enc(subsetName)}')?$expand=Elements($select=Name)&$select=Name,Expression,Alias`;
+        const response = await this.http.request("GET", path);
+        return {
+            name: response.Name,
+            dimensionName,
+            hierarchyName,
+            private: isPrivate,
+            expression: response.Expression || undefined,
+            elements: (response.Elements ?? []).map((e) => e.Name),
+            alias: response.Alias || undefined,
+        };
+    }
+    /**
+     * Create a public subset. Either MDX-based (expression) or static
+     * (elements). Mixed/empty inputs throw VALIDATION_ERROR.
+     * POST /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Subsets
+     */
+    async create(dimensionName, hierarchyName, subset) {
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Subsets`;
+        if (subset.expression && subset.elements && subset.elements.length > 0) {
+            throw new TM1Error({
+                code: TM1ErrorCode.VALIDATION_ERROR,
+                message: "Subset must be either MDX-based (expression) OR static (elements), not both.",
+            });
+        }
+        if (!subset.expression &&
+            (!subset.elements || subset.elements.length === 0)) {
+            throw new TM1Error({
+                code: TM1ErrorCode.VALIDATION_ERROR,
+                message: "Subset requires either expression (MDX) or non-empty elements list.",
+            });
+        }
+        const body = { Name: subset.name };
+        if (subset.alias)
+            body.Alias = subset.alias;
+        if (subset.expression) {
+            body.Expression = subset.expression;
+        }
+        else {
+            body["Elements@odata.bind"] = subset.elements.map((e) => `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(e)}')`);
+        }
+        await this.http.request("POST", path, body);
+    }
+    /**
+     * Update an existing public subset.
+     * PATCH /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Subsets('{s}')
+     */
+    async update(dimensionName, hierarchyName, subsetName, update) {
+        const path = `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Subsets('${enc(subsetName)}')`;
+        const body = {};
+        if (update.alias !== undefined)
+            body.Alias = update.alias;
+        if (update.expression !== undefined) {
+            body.Expression = update.expression;
+        }
+        else if (update.elements !== undefined) {
+            body.Expression = "";
+            body["Elements@odata.bind"] = update.elements.map((e) => `Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Elements('${enc(e)}')`);
+        }
+        await this.http.request("PATCH", path, body);
+    }
+    /**
+     * Delete a public subset.
+     * DELETE /api/v1/Dimensions('{d}')/Hierarchies('{h}')/Subsets('{s}')
+     */
+    async delete(dimensionName, hierarchyName, subsetName) {
+        await this.http.request("DELETE", `/api/v1/Dimensions('${enc(dimensionName)}')/Hierarchies('${enc(hierarchyName)}')/Subsets('${enc(subsetName)}')`);
+    }
+}
+//# sourceMappingURL=subset-service.js.map