@ffschrattenecker/tm1-mcp-server 6.0.0

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

@@ -0,0 +1,455 @@
+// Batch domain service. Owns the one OData endpoint that is not tied to a TM1
+// object type: POST /api/v1/$batch. It folds many independent REST calls into a
+// single HTTP round-trip and hands each sub-response back to the caller
+// separately.
+//
+// Verified live (TM1 v11 11.8.02900.8 and v12 / PA Engine 12.5.9):
+//   - Only the OData 4.01 **JSON** batch format is accepted. A multipart/mixed
+//     body is rejected with 400 "No acceptable mime type specified. $batch
+//     produces application/json responses!".
+//   - The batch is NOT atomic. `atomicityGroup` is refused outright: 400
+//     "$batch implementation DOES NOT support atomicity groups, hence the
+//     'atomicityGroup' property MUST NOT be defined".
+//   - Continue-on-error is the DEFAULT: with [ok, fail, ok] all three run and
+//     both successes are committed; a leading failure does not stop the rest.
+//   - The envelope is HTTP 200 even when sub-requests fail; each entry carries
+//     its own `status` and error `body`.
+//
+// That combination is what makes this safe for the bulk paths: partial success
+// is the server's native behaviour, so per-item success/failure reporting is
+// preserved rather than collapsed into one all-or-nothing result.
+//
+// Scope: exactly one consumer today — `ElementService.bulkUpsert`
+// (`element-service.ts`), which folds the per-element writes of
+// tm1_bulk_upsert_elements into one round-trip. It stays a service of its own
+// rather than moving into ElementService for two reasons that outlive the
+// single caller: `$batch` is the one endpoint bound to no TM1 object type, so
+// it belongs to no other service by the rule in docs/ARCHITECTURE.md; and the
+// `supported` verdict below is CONNECTION-scoped, probed once and reused, so it
+// cannot live inside a per-object-type service without being re-probed per
+// caller. `TM1Client` exposes it as `client.batch` for the live suite, which
+// asserts the probe's behaviour directly.
+//
+// See docs/ARCHITECTURE.md for the layering.
+import { TM1Error, TM1ErrorCode } from "../../types.js";
+import { classifyHttpError } from "../http.js";
+import { rethrowIfSystemic } from "./fallback.js";
+const BATCH_PATH = "/api/v1/$batch";
+// The counter-probe's sub-request: the cheapest read in the API surface, and
+// the one this codebase already trusts as a reachability check — the v11 login
+// round-trip IS a GET of it (`connection/profile.ts`), and `ServerService`
+// reads the same scalar on v12 for the ProductVersion the Configuration body
+// omits. So it is known to exist and to be answerable on both versions, it
+// takes no arguments, and it mutates nothing.
+const BATCH_PROBE_PATH = "/api/v1/Configuration/ProductVersion";
+/**
+ * Correlation id of the counter-probe's single sub-request. Namespaced so it
+ * can never collide with a caller id, and recognisable in a server-side log.
+ */
+export const BATCH_PROBE_ID = "__tm1_mcp_batch_probe__";
+// Sub-requests per HTTP round-trip. TM1 accepts far larger batches (5000
+// element creates succeeded live) but processes them SEQUENTIALLY server-side,
+// so a huge batch just builds one very long request: 5000 creates took ~47s,
+// well past a normal 30s request timeout, and a timeout mid-batch leaves an
+// unknown amount committed. Chunking keeps each round-trip bounded and gives
+// natural progress boundaries, while still collapsing ~200 calls into one.
+export const BATCH_MAX_REQUESTS = 200;
+// Serialized bytes per HTTP round-trip. The request COUNT alone does not bound
+// the payload: 200 sub-requests carrying long element names, MDX, or a
+// Components list are easily megabytes, and the request counter is still
+// happily under its cap when the body hits a hard limit somewhere on the way.
+// The limit that bites first is almost never TM1's — it is whatever sits in
+// front of it: nginx caps request bodies at 1 MiB by default
+// (`client_max_body_size 1m`), and that is the smallest default in the usual
+// deployment shapes. A body over the limit comes back 400/413, which is in
+// UNSUPPORTED_STATUSES, so an oversized chunk would be misread as "this server
+// has no $batch" and silently re-drive every write down the caller's fallback
+// path. Budget 1_000_000 bytes: just under that 1 MiB floor, leaving ~48 KB of
+// headroom for request headers, the auth cookie and the envelope itself. Big
+// enough that ordinary bulk work (a 200-element create batch is ~25 KB) never
+// notices it, small enough to keep the pathological payload off the wire.
+export const BATCH_MAX_PAYLOAD_BYTES = 1_000_000;
+// A batch performs N operations in one HTTP call, so the per-call default
+// timeout is the wrong budget for it. Scale with the chunk size instead.
+const BATCH_TIMEOUT_BASE_MS = 30_000;
+const BATCH_TIMEOUT_PER_REQUEST_MS = 200;
+/**
+ * Thrown when the server cannot serve `$batch` at all (endpoint absent, method
+ * refused, or an envelope we cannot read). Distinct from a sub-request failure,
+ * which is reported per item. Callers catch ONLY this to fall back to their
+ * per-request path — never a sub-request error, and never a systemic
+ * transport/auth failure (those propagate).
+ *
+ * GUARANTEE for those callers: this is raised only before the first successful
+ * batch on the connection — i.e. only ever out of the caller's FIRST pass.
+ *
+ * What that does NOT mean: "nothing was committed". TM1's `$batch` is
+ * non-atomic (verified live against 11.8: a failing sub-request leaves its
+ * siblings in the same envelope committed), and an ambiguous status such as 500
+ * can arrive after the server already applied part of the envelope. A caller
+ * that restarts per-request MAY therefore re-issue writes that already took
+ * effect.
+ *
+ * The requirement on callers is therefore: THE FIRST PASS MUST BE REPLAY-SAFE.
+ * `ElementService.bulkUpsert` satisfies this because its first pass is
+ * create-only, and re-creating an existing element degrades to the upsert path.
+ * A future caller whose first pass mutates existing state must NOT rely on this
+ * error to fall back. See `BatchService.markUnsupported`.
+ */
+export class BatchUnsupportedError extends Error {
+    constructor(reason) {
+        super(`TM1 $batch is not usable on this server: ${reason}`);
+        this.name = "BatchUnsupportedError";
+    }
+}
+// Statuses that can mean "this server has no usable $batch endpoint". The
+// obvious ones are 501 Not Implemented / 405 Method Not Allowed / 404 Not Found,
+// but a server or gateway that does not know the endpoint may just as well
+// answer 400 ("invalid URL"), 403, or 500 — and every one of those would
+// otherwise fail the whole bulk operation instead of falling back to the
+// caller's per-request path.
+//
+// Read this set ONLY together with `markUnsupported`: a status here counts as
+// "unsupported" exclusively before the first successful batch on this
+// connection. Once `$batch` has demonstrably worked, a 400 means "your payload
+// was bad" and must propagate rather than silently re-drive the caller's writes.
+//
+// 400 is the one member of this set that is genuinely AMBIGUOUS even before the
+// first success, so it alone gets a counter-probe first (`counterProbe`). See
+// PROBE_STATUS below for why the others do not.
+const UNSUPPORTED_STATUSES = new Set([400, 403, 404, 405, 500, 501]);
+// The only status worth counter-probing. The other members of
+// UNSUPPORTED_STATUSES are unambiguous *given what this service controls*: the
+// URL and the method are constants (`POST /api/v1/$batch`), so nothing in the
+// caller's payload can produce them, and a probe could not come back with a
+// different answer than the chunk already got.
+//
+//   404 / 405 / 501 — verdicts about the URL and the METHOD. The endpoint is
+//     not routed, POST is refused there, or the feature is declared
+//     unimplemented. All three are payload-independent by construction.
+//   403 — a verdict about the caller's IDENTITY, not about the body. The
+//     identity is the same for the probe (same session, same cookie), so the
+//     probe would return 403 again by construction: a probe that cannot change
+//     its answer is pure cost.
+//   500 — ambiguous in the abstract, but deliberately excluded. Unlike a 400,
+//     a 500 can arrive AFTER the server already applied part of the envelope
+//     (`$batch` is non-atomic; see BatchUnsupportedError's docstring), and the
+//     per-request fallback is the path whose replay-safety the caller contract
+//     already guarantees. Marking the connection supported and hard-failing
+//     instead would trade a safe, slow recovery for an abort of unknown commit
+//     extent. A 500 is also frequently transient, so a passing probe would not
+//     even establish that the caller's payload was at fault.
+//
+// 400, by contrast, is doubly overloaded AND safe to be strict about: a
+// gateway that does not know the endpoint answers "invalid URL" 400, while TM1
+// answers 400 for a payload it refuses (duplicate sub-request ids,
+// `atomicityGroup`, a body past a proxy's limit). An envelope-level 400 means
+// the envelope was rejected as a whole, before any sub-request ran — so there
+// is no partial commit to protect, and propagating it is the honest outcome.
+const PROBE_STATUS = 400;
+/**
+ * Pull TM1's human-readable error text out of a sub-response body.
+ *
+ * Mirrors `handleResponse`'s extraction in http.ts — INCLUDING its final
+ * raw-body fallback. That fallback is load-bearing, not cosmetic: callers
+ * classify by message text (e.g. `isAlreadyExists` substring-matches
+ * "already exists"), so returning `undefined` for a body that does not nest
+ * under `error.message` would downgrade a recognisable error into a generic
+ * "TM1 API error (HTTP 400)" and break bulk upsert's idempotency.
+ */
+function extractErrorDetails(body) {
+    if (body === null || body === undefined)
+        return undefined;
+    if (typeof body === "string")
+        return body || undefined;
+    if (typeof body !== "object")
+        return String(body);
+    const err = body.error;
+    if (err !== null && typeof err === "object") {
+        const message = err.message;
+        if (typeof message === "string")
+            return message;
+        if (message !== null && typeof message === "object") {
+            const value = message.value;
+            if (typeof value === "string")
+                return value;
+        }
+    }
+    // Unrecognised shape — hand back the raw body text, as http.ts does.
+    try {
+        return JSON.stringify(body) || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function toRelativeUrl(path) {
+    return path.replace(/^\/api\/v1\//, "");
+}
+function prepare(request) {
+    const sub = {
+        id: request.id,
+        method: request.method,
+        // Sub-request URLs are relative to the batch endpoint's service root.
+        // Callers pass the same absolute `/api/v1/...` path they would give
+        // http.request(), so strip that prefix here — for v12 the profile
+        // reroots the `$batch` URL itself, and the relative sub-URL rides along.
+        url: toRelativeUrl(request.path),
+        ...(request.body === undefined
+            ? {}
+            : {
+                headers: { "Content-Type": "application/json" },
+                body: request.body,
+            }),
+    };
+    // Measure what actually goes on the wire — the whole sub-object, not just
+    // the raw body — and in BYTES: an element name in umlauts or CJK costs two
+    // to three times its `String.length`.
+    return {
+        request,
+        sub,
+        bytes: Buffer.byteLength(JSON.stringify(sub), "utf8") + 1,
+    };
+}
+/**
+ * Split prepared sub-requests into chunks bounded by BOTH caps: a chunk closes
+ * when one more sub-request would push it past the request count OR past the
+ * serialized byte budget.
+ *
+ * A sub-request larger than the entire budget still goes out — alone, in its
+ * own chunk. Dropping it would silently lose a write, and refusing to place it
+ * would spin forever; the `chunk.length > 0` guard is what buys both.
+ */
+function chunkRequests(prepared) {
+    const chunks = [];
+    let chunk = [];
+    let bytes = 0;
+    for (const item of prepared) {
+        if (chunk.length > 0 &&
+            (chunk.length >= BATCH_MAX_REQUESTS ||
+                bytes + item.bytes > BATCH_MAX_PAYLOAD_BYTES)) {
+            chunks.push(chunk);
+            chunk = [];
+            bytes = 0;
+        }
+        chunk.push(item);
+        bytes += item.bytes;
+    }
+    if (chunk.length > 0)
+        chunks.push(chunk);
+    return chunks;
+}
+export class BatchService {
+    http;
+    // Tri-state support verdict, remembered for the lifetime of the client so a
+    // server without $batch is probed once, not once per bulk operation.
+    supported = null;
+    // Whether the counter-probe has already been spent on this connection. Set
+    // BEFORE the probe goes out, so an inconclusive probe (systemic failure) is
+    // still counted: the bound is "at most once", not "once per undecided 400".
+    // Without it a bulk operation that keeps failing 400 would issue one extra
+    // round-trip per attempt — a probe storm on top of an already failing run.
+    probeSpent = false;
+    constructor(http) {
+        this.http = http;
+    }
+    /** True once a probe has established the server rejects `$batch` outright. */
+    get isKnownUnsupported() {
+        return this.supported === false;
+    }
+    /**
+     * Record a "this server has no usable `$batch`" verdict — but ONLY while no
+     * batch has ever succeeded on this connection.
+     *
+     * That precondition is the whole safety argument for the caller's fallback.
+     * `BatchUnsupportedError` makes callers restart their operation on the
+     * per-request path. While `supported === null` no chunk has ever come back
+     * 200, so the failure can only be in the caller's FIRST pass. Note what that
+     * bounds: WHICH writes may be replayed, not WHETHER anything was committed —
+     * `$batch` is non-atomic, so sub-requests processed before the failure stay
+     * committed. Callers must keep that first pass replay-safe.
+     *
+     * Once `supported === true`, a later failure — a flaky gateway answering
+     * chunk 2 with HTML or a 400 — is a real error and is propagated verbatim, so
+     * a half-finished batch is never silently replayed. That is what keeps the
+     * destructive later passes (type PATCH, Components) out of the fallback
+     * window entirely: they only ever run after a batch has already succeeded.
+     *
+     * NOTE: for HTTP 400 the caller in `executeChunk` runs `counterProbe` BEFORE
+     * reaching here, so a payload-caused 400 never gets this far. This method
+     * still sees every other unsupported status directly.
+     *
+     * Returns the error to throw, or `undefined` when the verdict was refused.
+     */
+    markUnsupported(reason) {
+        if (this.supported !== null)
+            return undefined;
+        this.supported = false;
+        return new BatchUnsupportedError(reason);
+    }
+    /**
+     * Settle an ambiguous first-call 400 by asking the endpoint the simplest
+     * question there is: one minimal, side-effect-free GET in a well-formed
+     * envelope.
+     *
+     * Judges the ENVELOPE only, exactly as `executeChunk` does — a readable
+     * `responses` array means `$batch` is served here, whatever status the probe's
+     * own sub-request came back with. That distinction is load-bearing: a
+     * locked-down account may well be refused `Configuration/ProductVersion`
+     * (reported INSIDE the envelope), and reading that as "no $batch" would
+     * reintroduce the very misdiagnosis this probe exists to remove.
+     *
+     * Returns `true` when `$batch` demonstrably works, `false` when the endpoint
+     * refuses even this envelope. THROWS on a systemic transport/auth/timeout
+     * failure: that proves nothing either way, so the caller must draw no
+     * conclusion and the outage surfaces instead — same rule `executeChunk`
+     * already applies via `rethrowIfSystemic`.
+     *
+     * Does not go through `execute`/`executeChunk`, so it cannot recurse into
+     * itself or into the unsupported-detection path.
+     */
+    async counterProbe() {
+        const payload = {
+            requests: [
+                {
+                    id: BATCH_PROBE_ID,
+                    method: "GET",
+                    url: toRelativeUrl(BATCH_PROBE_PATH),
+                },
+            ],
+        };
+        let envelope;
+        try {
+            envelope = await this.http.request("POST", BATCH_PATH, payload, {
+                // Same budget a 1-request chunk gets. Deliberately not a short
+                // fail-fast timeout: a timeout maps to LOCK_TIMEOUT, which is systemic
+                // and would surface instead of the caller's 400 — turning a slow-but-
+                // working server into a hard failure where today it merely falls back.
+                timeoutMs: BATCH_TIMEOUT_BASE_MS + BATCH_TIMEOUT_PER_REQUEST_MS,
+            });
+        }
+        catch (err) {
+            rethrowIfSystemic(err);
+            return false;
+        }
+        return Array.isArray(envelope?.responses);
+    }
+    /**
+     * Run `requests` in as few round-trips as possible and return one result per
+     * request, in the order given.
+     *
+     * A failing sub-request is DATA, not an exception: it comes back as
+     * `{ok:false, error}` so the caller can report partial success. Only a
+     * whole-envelope failure throws — `BatchUnsupportedError` if the server has no
+     * `$batch`, or the underlying TM1Error for a transport/auth/timeout failure.
+     *
+     * POST /api/v1/$batch
+     */
+    async execute(requests) {
+        if (requests.length === 0)
+            return [];
+        if (this.supported === false) {
+            throw new BatchUnsupportedError("a previous probe on this connection was rejected");
+        }
+        const results = [];
+        // Chunks stay SERIAL. These are mutations: overlapping envelopes would make
+        // "how much committed before the failure" unanswerable, and TM1 processes a
+        // batch sequentially server-side anyway, so there is nothing to win.
+        for (const chunk of chunkRequests(requests.map(prepare))) {
+            results.push(...(await this.executeChunk(chunk)));
+        }
+        return results;
+    }
+    async executeChunk(chunk) {
+        // Sub-objects were built (and measured) once during chunking.
+        const payload = { requests: chunk.map((c) => c.sub) };
+        let envelope;
+        try {
+            envelope = await this.http.request("POST", BATCH_PATH, payload, {
+                timeoutMs: BATCH_TIMEOUT_BASE_MS + chunk.length * BATCH_TIMEOUT_PER_REQUEST_MS,
+            });
+        }
+        catch (err) {
+            // A transport/auth/timeout failure is NOT evidence that $batch is
+            // missing. Swallowing it into "unsupported" would silently re-run every
+            // write down the fallback path on a network blip.
+            rethrowIfSystemic(err);
+            if (err instanceof TM1Error &&
+                err.httpStatus !== undefined &&
+                UNSUPPORTED_STATUSES.has(err.httpStatus)) {
+                // A 400 before the first success is ambiguous: missing endpoint, or a
+                // payload this server refuses? Getting that wrong pins the connection
+                // to "no $batch" for the whole session and silently drops every later
+                // bulk write onto the N-times-slower per-request path. So counter-probe
+                // once — but only while the verdict is still open, and only for the one
+                // status where the answer can differ (see PROBE_STATUS).
+                if (err.httpStatus === PROBE_STATUS &&
+                    this.supported === null &&
+                    !this.probeSpent) {
+                    this.probeSpent = true;
+                    if (await this.counterProbe()) {
+                        // $batch works here; the 400 was about the caller's payload. Record
+                        // that so no later failure ever reaches the fallback path, and let
+                        // the original error through as the real failure it is. The
+                        // caller's writes are NOT retried here — an envelope-level 400 was
+                        // refused whole, and re-driving it would just fail again.
+                        this.supported = true;
+                        throw err;
+                    }
+                }
+                const unsupported = this.markUnsupported(`POST ${BATCH_PATH} returned HTTP ${err.httpStatus}`);
+                if (unsupported)
+                    throw unsupported;
+            }
+            throw err;
+        }
+        const responses = envelope?.responses;
+        if (!Array.isArray(responses)) {
+            // 200 but not an OData batch envelope — a proxy or a look-alike endpoint.
+            // Treat as unsupported rather than guessing at the shape, but only if
+            // $batch never worked here; mid-operation this is a hard error (see
+            // markUnsupported).
+            const unsupported = this.markUnsupported(`response had no "responses" array`);
+            if (unsupported)
+                throw unsupported;
+            throw new TM1Error({
+                code: TM1ErrorCode.TM1_ERROR,
+                message: `TM1 $batch returned a 200 response without a "responses" array after $batch had already worked on this connection`,
+                endpoint: BATCH_PATH,
+            });
+        }
+        this.supported = true;
+        // OData does not promise response order, so correlate by id.
+        const byId = new Map();
+        for (const raw of responses) {
+            if (raw && raw.id !== undefined)
+                byId.set(String(raw.id), raw);
+        }
+        return chunk.map(({ request: req }) => {
+            const raw = byId.get(req.id);
+            if (!raw) {
+                return {
+                    id: req.id,
+                    status: 0,
+                    ok: false,
+                    error: new TM1Error({
+                        code: TM1ErrorCode.TM1_ERROR,
+                        message: `TM1 $batch returned no response for request id "${req.id}"`,
+                        endpoint: req.path,
+                    }),
+                };
+            }
+            const status = typeof raw.status === "number" ? raw.status : 0;
+            if (status >= 200 && status < 300) {
+                return { id: req.id, status, ok: true, body: raw.body };
+            }
+            return {
+                id: req.id,
+                status,
+                ok: false,
+                error: classifyHttpError(status, req.path, extractErrorDetails(raw.body)),
+            };
+        });
+    }
+}
+//# sourceMappingURL=batch-service.js.map

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

@@ -0,0 +1,71 @@
+import type { CalculationTraceNode, CellValue, FedCellDescriptor, FeederTraceResult, MdxResult } from "../../types.js";
+import type { RequestOptions, TM1HttpClient } from "../http.js";
+export declare class CellService {
+    private readonly http;
+    constructor(http: TM1HttpClient);
+    /**
+     * Get a single cell value via a 1-tuple MDX query.
+     *
+     * TM1 11.8 returns 0 cells for `SELECT {} ON COLUMNS WHERE (...)` — the
+     * empty axis collapses the cellset. Put the first element on COLUMNS and
+     * the rest in WHERE to force a 1-cell cellset. Each element is qualified
+     * with its dimension to avoid name collisions in control cubes.
+     */
+    getValue(cubeName: string, elements: string[]): Promise<CellValue>;
+    /**
+     * Execute an MDX query and return structured cells + axes. Supports
+     * pagination via top/skip on the Cells expand. opts.timeoutMs overrides the
+     * 30s default for heavy queries.
+     * POST /api/v1/ExecuteMDX
+     */
+    executeMdx(mdx: string, top?: number, skip?: number, opts?: RequestOptions): Promise<MdxResult>;
+    /**
+     * Write multiple cells via the cellset PATCH path.
+     *
+     * TM1 11.8's Cube /tm1.Update action rejects every documented payload
+     * variant ("Invalid CellDescriptor property" / "Unexpected entity reference
+     * type" / "Expecting Object or EntityBind"). The cellset PATCH path is the
+     * supported route in 11.8:
+     *   1. POST /api/v1/ExecuteMDX with a slice MDX over the target cell
+     *   2. PATCH /api/v1/Cellsets('{id}')/Cells(0) with {Value}
+     *   3. DELETE /api/v1/Cellsets('{id}')
+     *
+     * Values can be numeric (for N-cubes) or strings (for string cells). Writes
+     * to consolidated cells are rejected by TM1.
+     *
+     * Prefer TI processes for reproducible data loads. Use this REST path only
+     * for ad-hoc / debugging writes.
+     */
+    writeCells(cubeName: string, dimensions: string[], cells: Array<{
+        elements: string[];
+        value: number | string;
+    }>): Promise<void>;
+    /**
+     * Resolve the cube's dimension order and build Tuple@odata.bind paths for
+     * the cell-bound trace actions. Elements address the default hierarchy
+     * (same name as the dimension) — alternate hierarchies are not supported
+     * by these diagnostics tools.
+     */
+    private tupleBinds;
+    /**
+     * Check the feeders of a cell: returns the cells fed by this cell with a
+     * Fed flag per target — Fed=false marks a broken/missing feeder. v11 only.
+     * POST /api/v1/Cubes('{cube}')/tm1.CheckFeeders
+     */
+    checkFeeders(cubeName: string, elements: string[], opts?: RequestOptions): Promise<FedCellDescriptor[]>;
+    /**
+     * Trace the feeders of a cell: returns the cells this cell feeds plus the
+     * feeder statements involved. v11 only.
+     * POST /api/v1/Cubes('{cube}')/tm1.TraceFeeders
+     */
+    traceFeeders(cubeName: string, elements: string[], opts?: RequestOptions): Promise<FeederTraceResult>;
+    /**
+     * Trace how a cell value is calculated: recursive component tree with
+     * per-component type (consolidation/rule), status, value, and rule
+     * statements. The server returns the full tree; maxDepth/maxComponents
+     * truncate client-side to keep responses bounded. v11 only.
+     * POST /api/v1/Cubes('{cube}')/tm1.TraceCellCalculation
+     */
+    traceCellCalculation(cubeName: string, elements: string[], maxDepth?: number, maxComponents?: number, opts?: RequestOptions): Promise<CalculationTraceNode>;
+}
+//# sourceMappingURL=cell-service.d.ts.map