@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/tm1-client/http.js

@@ -0,0 +1,547 @@
+import { createConnectionProfile, } from "./connection/profile.js";
+import { TM1Error, TM1ErrorCode } from "../types.js";
+import { PRODUCT, VERSION } from "../version.js";
+import { getTm1Dispatcher, tm1Fetch } from "./dispatcher.js";
+import { tm1Events } from "../lib/tm1-events.js";
+import { maskSecretValues } from "../lib/mask-secrets.js";
+const MAX_NETWORK_RETRIES = 3;
+const BACKOFF_BASE_MS = 1000;
+const USER_AGENT = `${PRODUCT}/${VERSION}`;
+// R2-22: any successful mutating HTTP call invalidates the callgraph
+// reference-index cache. Cheap (Map.clear()) and rebuild is lazy on next
+// read — over-invalidation on non-graph-affecting calls (write_cells,
+// upload_file, CheckRules) costs at most one rebuild. The alternative —
+// per-service hooks across 17 mutation methods — risks drift as new
+// mutating methods are added.
+function isSafeHttpMethod(method) {
+    return method === "GET" || method === "HEAD";
+}
+// Link an external AbortSignal (e.g. from RequestHandlerExtra.signal) to a
+// locally-owned timeout AbortController. Returns an unsubscribe function the
+// caller must invoke in `finally` to avoid leaking the listener after the
+// request resolves. If the external signal is already aborted, propagates the
+// reason immediately.
+function linkAbortSignals(local, external) {
+    if (!external)
+        return () => undefined;
+    if (external.aborted) {
+        local.abort(external.reason);
+        return () => undefined;
+    }
+    const onAbort = () => local.abort(external.reason);
+    external.addEventListener("abort", onAbort, { once: true });
+    return () => external.removeEventListener("abort", onAbort);
+}
+export class TM1HttpClient {
+    // config is private: it carries credentials (TM1Config.password), so it must
+    // not be reachable as `client.config` from the service layer or leak into the
+    // compiled .d.ts public surface. Services get only what they need —
+    // `version` (numeric getter) for version-conditional paths and `logger`
+    // for structured logs.
+    config;
+    logger;
+    sessionManager;
+    // v11↔v12 URL-rerooting seam. v11: identity (paths unchanged). v12: rewrites
+    // `/api/v1/...` to the database-rooted `/{instance}/api/v1/Databases('{db}')/...`.
+    profile;
+    constructor(config, sessionManager, logger) {
+        this.config = config;
+        this.sessionManager = sessionManager;
+        this.logger = logger;
+        this.profile = createConnectionProfile(config);
+    }
+    /**
+     * TM1 major version (11 | 12) — the single numeric source of truth for
+     * version-conditional service code. Branch on this, never on the display
+     * string (`tm1Version`): a v12 connection can carry a "11.x"-looking
+     * TM1_VERSION string, but `version` is always authoritative.
+     */
+    get version() {
+        return this.config.version;
+    }
+    /**
+     * TM1 server version STRING (e.g. "11.8.…") — DISPLAY ONLY (server_info
+     * output, log fields, user-facing error messages). Do NOT branch on this;
+     * use the numeric `version` getter instead.
+     */
+    get tm1Version() {
+        return this.config.tm1Version;
+    }
+    /**
+     * Make an authenticated HTTP request to the TM1 REST API.
+     *
+     * - Ensures an active session via SessionManager
+     * - On 401: re-authenticates once and retries
+     * - On network error for safe methods (GET/HEAD): retries up to 3 times with exponential backoff (1s, 2s, 4s)
+     * - On network error for non-safe methods (POST/PUT/PATCH/DELETE): does NOT retry — these are not idempotent
+     *   and a retry could spawn duplicate side-effects (e.g. parallel TI runs on tm1.Execute)
+     * - On other HTTP errors: classifies and throws TM1Error
+     */
+    /** @internal — for Service-layer use; not part of the public consumer API. */
+    async request(method, path, body, opts) {
+        const url = `${this.config.baseUrl}${this.profile.resolveApiPath(path)}`;
+        const isSafeMethod = isSafeHttpMethod(method);
+        const allowRetry = opts?.retry !== false;
+        const maxAttempts = isSafeMethod && allowRetry ? MAX_NETWORK_RETRIES : 0;
+        let lastError;
+        for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+            if (attempt > 0) {
+                const delayMs = BACKOFF_BASE_MS * Math.pow(2, attempt - 1);
+                this.logger.warn({ attempt, delayMs, endpoint: path }, "Retrying after network error");
+                await sleep(delayMs);
+            }
+            try {
+                const cookie = await this.sessionManager.ensureSession();
+                const response = await this.executeRequest(url, method, cookie, body, opts?.timeoutMs, opts?.signal);
+                if (response.status === 401) {
+                    this.logger.warn({ endpoint: path }, "Received 401, re-authenticating");
+                    // Pass the cookie that got the 401 so a concurrent request that
+                    // already rotated the session short-circuits to the fresh cookie
+                    // instead of forcing another logout+login (staggered-401 churn).
+                    const newCookie = await this.sessionManager.authenticate(cookie);
+                    const retryResponse = await this.executeRequest(url, method, newCookie, body, opts?.timeoutMs, opts?.signal);
+                    if (retryResponse.status === 401) {
+                        throw new TM1Error({
+                            code: TM1ErrorCode.AUTH_FAILED,
+                            message: "Authentication failed after re-authentication attempt",
+                            httpStatus: 401,
+                            endpoint: path,
+                        });
+                    }
+                    const retryResult = await this.handleResponse(retryResponse, path);
+                    if (!isSafeMethod) {
+                        tm1Events.emit("mutation", { method, path });
+                    }
+                    return retryResult;
+                }
+                const result = await this.handleResponse(response, path);
+                if (!isSafeMethod) {
+                    tm1Events.emit("mutation", { method, path });
+                }
+                return result;
+            }
+            catch (error) {
+                if (error instanceof TM1Error) {
+                    throw error;
+                }
+                if (isTimeoutError(error)) {
+                    const ms = opts?.timeoutMs ?? this.config.requestTimeoutMs;
+                    throw new TM1Error({
+                        code: TM1ErrorCode.LOCK_TIMEOUT,
+                        message: `Request to ${path} timed out after ${ms}ms`,
+                        endpoint: path,
+                        hint: isSafeMethod
+                            ? "Query timed out — result set may be too large. Add filters or reduce scope. If a lock is suspected, use tm1_list_threads to diagnose."
+                            : "Request timed out — TM1 server may be waiting on a lock held by another session. Use tm1_list_threads to diagnose and cancel the blocking thread.",
+                    });
+                }
+                if (opts?.signal?.aborted) {
+                    throw error;
+                }
+                if (this.isNetworkError(error)) {
+                    lastError = error;
+                    this.logger.error({ err: error, attempt, endpoint: path }, "Network error during request");
+                    continue;
+                }
+                throw new TM1Error({
+                    code: TM1ErrorCode.CONNECTION_FAILED,
+                    message: error instanceof Error ? error.message : String(error),
+                    endpoint: path,
+                });
+            }
+        }
+        throw new TM1Error({
+            code: TM1ErrorCode.CONNECTION_FAILED,
+            message: isSafeMethod
+                ? `Request failed after ${MAX_NETWORK_RETRIES} retries: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+                : `Request failed (no retry for ${method}): ${lastError instanceof Error ? lastError.message : String(lastError)}`,
+            endpoint: path,
+        });
+    }
+    /**
+     * Make an authenticated HTTP request that returns raw text (not JSON).
+     * Used for file content downloads where the response is CSV/TXT/etc.
+     * Re-auths once on 401 like request().
+     */
+    /** @internal — for Service-layer use; not part of the public consumer API. */
+    async requestRaw(method, path, opts) {
+        const url = `${this.config.baseUrl}${this.profile.resolveApiPath(path)}`;
+        const effectiveTimeout = opts?.timeoutMs ?? this.config.requestTimeoutMs;
+        const cookie = await this.sessionManager.ensureSession();
+        const headers = {
+            Cookie: `TM1SessionId=${cookie}`,
+            Accept: "*/*",
+            "User-Agent": USER_AGENT,
+            "TM1-SessionContext": USER_AGENT,
+            "TM1-Session-Context": USER_AGENT,
+        };
+        const response = await this.withReauth((c) => {
+            const hdrs = { ...headers, Cookie: `TM1SessionId=${c}` };
+            return this.sendOnce(url, method, hdrs, undefined, effectiveTimeout, opts?.signal);
+        }, cookie, path, effectiveTimeout);
+        if (!response.ok) {
+            let body = "";
+            try {
+                body = await response.text();
+            }
+            catch {
+                /* ignore */
+            }
+            throw this.classifyHttpError(response.status, path, body || undefined);
+        }
+        const text = await response.text();
+        if (!isSafeHttpMethod(method)) {
+            tm1Events.emit("mutation", { method, path });
+        }
+        return text;
+    }
+    /**
+     * Make an authenticated HTTP request with a binary body (Buffer/Uint8Array).
+     * Used for blob/file uploads where the body is raw bytes (not JSON).
+     * Sends Content-Type: application/octet-stream by default.
+     * Re-auths once on 401 like request(). No network-error retries (non-safe methods).
+     */
+    /** @internal — for Service-layer use; not part of the public consumer API. */
+    async requestBinary(method, path, body, contentType = "application/octet-stream", opts) {
+        const url = `${this.config.baseUrl}${this.profile.resolveApiPath(path)}`;
+        const effectiveTimeout = opts?.timeoutMs ?? this.config.requestTimeoutMs;
+        const cookie = await this.sessionManager.ensureSession();
+        const response = await this.withReauth((c) => this.sendOnce(url, method, {
+            Cookie: `TM1SessionId=${c}`,
+            Accept: "application/json,*/*",
+            "Content-Type": contentType,
+            "User-Agent": USER_AGENT,
+            "TM1-SessionContext": USER_AGENT,
+            "TM1-Session-Context": USER_AGENT,
+        }, body, effectiveTimeout, opts?.signal), cookie, path, effectiveTimeout);
+        if (!response.ok) {
+            let errBody = "";
+            try {
+                errBody = await response.text();
+            }
+            catch {
+                /* ignore */
+            }
+            throw this.classifyHttpError(response.status, path, errBody || undefined);
+        }
+        if (!isSafeHttpMethod(method)) {
+            tm1Events.emit("mutation", { method, path });
+        }
+    }
+    /**
+     * Low-level single fetch with timeout + AbortSignal wiring.
+     * Does NOT handle 401, retries, or error classification — callers own that.
+     */
+    async sendOnce(url, method, headers, body, timeoutMs, externalSignal) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(new DOMException("Request timed out", "TimeoutError")), timeoutMs);
+        const unlink = linkAbortSignals(controller, externalSignal);
+        try {
+            return await tm1Fetch(url, {
+                method,
+                headers,
+                body,
+                signal: controller.signal,
+                dispatcher: getTm1Dispatcher(this.config),
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+            unlink();
+        }
+    }
+    /**
+     * Wraps a send function with cookie-refresh-on-401 and timeout→LOCK_TIMEOUT mapping.
+     * Used by requestRaw and requestBinary (which have no network-retry loop).
+     * On 401: calls sessionManager.authenticate() and retries once with the new cookie.
+     * The caller is responsible for obtaining the initial cookie via ensureSession().
+     */
+    async withReauth(send, initialCookie, path, effectiveTimeout) {
+        let response;
+        try {
+            response = await send(initialCookie);
+        }
+        catch (err) {
+            if (isTimeoutError(err)) {
+                throw new TM1Error({
+                    code: TM1ErrorCode.LOCK_TIMEOUT,
+                    message: `Request to ${path} timed out after ${effectiveTimeout}ms`,
+                    endpoint: path,
+                });
+            }
+            throw err;
+        }
+        if (response.status === 401) {
+            const newCookie = await this.sessionManager.authenticate(initialCookie);
+            try {
+                response = await send(newCookie);
+            }
+            catch (err) {
+                if (isTimeoutError(err)) {
+                    throw new TM1Error({
+                        code: TM1ErrorCode.LOCK_TIMEOUT,
+                        message: `Request to ${path} timed out after ${effectiveTimeout}ms`,
+                        endpoint: path,
+                    });
+                }
+                throw err;
+            }
+        }
+        return response;
+    }
+    async executeRequest(url, method, cookie, body, timeoutMs, externalSignal) {
+        const headers = {
+            Cookie: `TM1SessionId=${cookie}`,
+            Accept: "application/json",
+            "Accept-Encoding": "gzip, deflate",
+            "User-Agent": USER_AGENT,
+            "TM1-SessionContext": USER_AGENT,
+            "TM1-Session-Context": USER_AGENT,
+        };
+        const isWriteMethod = method === "POST" || method === "PUT" || method === "PATCH";
+        if (body !== undefined || isWriteMethod) {
+            headers["Content-Type"] = "application/json";
+        }
+        const serializedBody = body !== undefined
+            ? JSON.stringify(body)
+            : isWriteMethod
+                ? ""
+                : undefined;
+        return this.sendOnce(url, method, headers, serializedBody, timeoutMs ?? this.config.requestTimeoutMs, externalSignal);
+    }
+    async handleResponse(response, endpoint) {
+        if (response.ok) {
+            const text = await response.text();
+            if (response.status === 204 || !text) {
+                return undefined;
+            }
+            this.logger.debug({ endpoint, status: response.status }, "Request successful");
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new TM1Error({
+                    code: TM1ErrorCode.TM1_ERROR,
+                    message: `TM1 returned a non-JSON response body (status ${response.status}) for ${endpoint}. ` +
+                        `This usually means a proxy or gateway returned HTML/text instead of the TM1 REST API.`,
+                    httpStatus: response.status,
+                    endpoint,
+                });
+            }
+        }
+        let details;
+        let errorBody;
+        try {
+            errorBody = await response.text();
+            if (errorBody) {
+                const parsed = JSON.parse(errorBody);
+                details = odataErrorText(parsed) ?? errorBody;
+            }
+        }
+        catch {
+            /* ignore parse errors */
+        }
+        const error = this.classifyHttpError(response.status, endpoint, details);
+        this.logger.error({ endpoint, status: response.status, code: error.code }, error.message);
+        throw error;
+    }
+    classifyHttpError(status, endpoint, details) {
+        return classifyHttpError(status, endpoint, details);
+    }
+    isNetworkError(error) {
+        return isNetworkErrorImpl(error);
+    }
+}
+/**
+ * Map an HTTP status + TM1 error text onto a TM1Error. Module-level (not just a
+ * TM1HttpClient method) because `$batch` sub-responses arrive as plain
+ * {status, body} records inside a 200 envelope — BatchService has to classify
+ * them itself, and must do it identically to a standalone request rather than
+ * with a drifting copy of these rules.
+ */
+export function classifyHttpError(status, endpoint, rawDetails) {
+    // S4/S5: sanitize ONCE, here, where the server's own text enters our error
+    // model. Everything downstream reads the TM1Error this builds — the
+    // logger.error() in handleResponse and the MCP error envelope alike — so
+    // masking here covers both exits with no chance of one being forgotten.
+    //
+    // This is the gap key-based redaction cannot close: pino's `redact` masks a
+    // field NAMED password, but a TM1 failure such as
+    // "[ODBC Driver] login failed for PWD=hunter2" is a plain message string, and
+    // it went to the log and back to the client verbatim.
+    const details = rawDetails === undefined ? undefined : maskSecretValues(rawDetails);
+    {
+        // TM1 signals object-level security denial via the error MESSAGE, often
+        // with HTTP 400 (not 403) — e.g. reading a control cube as a non-admin
+        // returns 400 {"error":{"code":"65","message":"ObjectSecurityNoReadRights"}}.
+        // Classify by message so the caller gets PERMISSION_DENIED + its actionable
+        // hint instead of a generic TM1_ERROR. Verified live with a cube-only user.
+        if (details &&
+            /No(Read|Write|Admin)Rights|ObjectSecurity|SecurityAccess|not\s+authori[sz]ed/i.test(details)) {
+            return new TM1Error({
+                code: TM1ErrorCode.PERMISSION_DENIED,
+                message: details,
+                httpStatus: status,
+                endpoint,
+                details,
+            });
+        }
+        switch (status) {
+            case 401:
+                return new TM1Error({
+                    code: TM1ErrorCode.AUTH_FAILED,
+                    message: details ?? "Authentication failed",
+                    httpStatus: status,
+                    endpoint,
+                    details,
+                });
+            case 403:
+                return new TM1Error({
+                    code: TM1ErrorCode.PERMISSION_DENIED,
+                    message: details ?? "Permission denied",
+                    httpStatus: status,
+                    endpoint,
+                    details,
+                });
+            case 404:
+                return new TM1Error({
+                    code: TM1ErrorCode.NOT_FOUND,
+                    message: details ?? "Resource not found",
+                    httpStatus: status,
+                    endpoint,
+                    details,
+                });
+            case 409:
+                return new TM1Error({
+                    code: TM1ErrorCode.CONFLICT,
+                    message: details ?? "Resource conflict",
+                    httpStatus: status,
+                    endpoint,
+                    details,
+                });
+            default:
+                return new TM1Error({
+                    code: TM1ErrorCode.TM1_ERROR,
+                    message: details ?? `TM1 API error (HTTP ${status})`,
+                    httpStatus: status,
+                    endpoint,
+                    details,
+                });
+        }
+    }
+}
+/**
+ * Is this a transient transport failure worth retrying (as opposed to our own
+ * timeout, a caller cancellation, or an application-level error)?
+ */
+function isNetworkErrorImpl(error) {
+    {
+        // TimeoutError is our own request timeout — handled separately as LOCK_TIMEOUT,
+        // never treated as a retryable network blip.
+        if (error instanceof DOMException && error.name === "TimeoutError") {
+            return false;
+        }
+        // AbortError is never a retryable network blip. Our own request timeout
+        // aborts with name "TimeoutError" (handled above → LOCK_TIMEOUT). A plain
+        // "AbortError" can only come from a caller-supplied signal (cancellation),
+        // which must propagate immediately — retrying a cancelled request 3× is a
+        // bug. The request loop also guards opts.signal.aborted before reaching
+        // here; this is the defensive backstop for any other abort source. Match on
+        // name (not just DOMException) since some fetch impls throw a plain Error.
+        if (error instanceof Error && error.name === "AbortError") {
+            return false;
+        }
+        // Primary, robust path: undici surfaces the OS-level failure on the wrapped
+        // cause's `.code` (e.g. ECONNREFUSED, ENOTFOUND, ETIMEDOUT, ECONNRESET). Some
+        // raw socket errors expose `.code` directly. Classifying by code is stable
+        // across Node/undici versions and locale, unlike message-substring matching.
+        const causeCode = errorCodeOf(error.cause);
+        if (causeCode !== undefined && NETWORK_ERROR_CODES.has(causeCode)) {
+            return true;
+        }
+        const directCode = errorCodeOf(error);
+        if (directCode !== undefined && NETWORK_ERROR_CODES.has(directCode)) {
+            return true;
+        }
+        // Fallback: undici wraps every fetch-level network failure in
+        // `TypeError: fetch failed`. This catches wrappers whose cause carries no
+        // recognised code (or no cause at all) — preserves the old TypeError branch.
+        if (error instanceof TypeError) {
+            return true;
+        }
+        // Last-resort backstop: an error that stringified a network failure into its
+        // message without exposing a code or cause (rare, but the old code matched
+        // it — kept so nothing is silently dropped). Not the primary classifier.
+        if (error instanceof Error) {
+            const msg = error.message.toLowerCase();
+            return (msg.includes("fetch failed") ||
+                msg.includes("econnrefused") ||
+                msg.includes("enotfound") ||
+                msg.includes("etimedout") ||
+                msg.includes("network"));
+        }
+        return false;
+    }
+}
+/**
+ * OS/undici-level error codes that indicate a transient network failure worth
+ * retrying (connection refused, DNS failure, timeout, socket reset, etc.).
+ * undici exposes these on `err.cause.code`; raw sockets on `err.code`.
+ */
+const NETWORK_ERROR_CODES = new Set([
+    "ECONNREFUSED", // connection actively refused (server down / wrong port)
+    "ENOTFOUND", // DNS: host not found
+    "EAI_AGAIN", // DNS: temporary resolution failure
+    "ETIMEDOUT", // OS-level connect/read timeout
+    "ECONNRESET", // socket reset by peer
+    "ECONNABORTED", // connection aborted mid-flight
+    "EPIPE", // broken pipe writing to a closed socket
+    "EHOSTUNREACH", // host unreachable
+    "ENETUNREACH", // network unreachable
+    "ENETDOWN", // network is down
+    "UND_ERR_CONNECT_TIMEOUT", // undici connect timeout
+    "UND_ERR_SOCKET", // undici socket error (e.g. other side closed)
+]);
+/**
+ * Read a string `.code` off an unknown error-ish value, narrowing safely under
+ * strict TS (`cause`/`error` are `unknown`). Returns undefined if absent or not
+ * a string.
+ */
+function errorCodeOf(value) {
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    const code = value.code;
+    return typeof code === "string" ? code : undefined;
+}
+/**
+ * Pull the message out of an OData error body. TM1 writes it two ways —
+ * `error.message` as a plain string, or `error.message.value` — so both are
+ * read, and anything else yields undefined so the caller can fall back to the
+ * raw body. Returning only strings matters: the previous chained-optional
+ * version could hand a whole object to a `string` field when `message` was an
+ * object without `value`.
+ */
+function odataErrorText(parsed) {
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const err = parsed.error;
+    if (typeof err !== "object" || err === null)
+        return undefined;
+    const message = err.message;
+    if (typeof message === "string")
+        return message;
+    if (typeof message === "object" && message !== null) {
+        const value = message.value;
+        if (typeof value === "string")
+            return value;
+    }
+    return undefined;
+}
+function isTimeoutError(error) {
+    return error instanceof DOMException && error.name === "TimeoutError";
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=http.js.map

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

@@ -0,0 +1,123 @@
+import { TM1Error } from "../../types.js";
+import type { TM1HttpClient } from "../http.js";
+/**
+ * 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 declare const BATCH_PROBE_ID = "__tm1_mcp_batch_probe__";
+export declare const BATCH_MAX_REQUESTS = 200;
+export declare const BATCH_MAX_PAYLOAD_BYTES = 1000000;
+export interface BatchRequest {
+    /** Caller-chosen correlation id. Must be unique within one execute() call. */
+    id: string;
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    /** Same `/api/v1/...` form the other services use; rerooted for v12 by the profile. */
+    path: string;
+    body?: unknown;
+}
+export type BatchSubResult = {
+    id: string;
+    status: number;
+    ok: true;
+    body: unknown;
+} | {
+    id: string;
+    status: number;
+    ok: false;
+    error: TM1Error;
+};
+/**
+ * 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 declare class BatchUnsupportedError extends Error {
+    constructor(reason: string);
+}
+export declare class BatchService {
+    private readonly http;
+    private supported;
+    private probeSpent;
+    constructor(http: TM1HttpClient);
+    /** True once a probe has established the server rejects `$batch` outright. */
+    get isKnownUnsupported(): boolean;
+    /**
+     * 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.
+     */
+    private markUnsupported;
+    /**
+     * 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.
+     */
+    private counterProbe;
+    /**
+     * 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
+     */
+    execute(requests: BatchRequest[]): Promise<BatchSubResult[]>;
+    private executeChunk;
+}
+//# sourceMappingURL=batch-service.d.ts.map