@ffschrattenecker/tm1-mcp-server 7.0.2 → 8.1.0

package/dist/secrets-cli.js

@@ -0,0 +1,218 @@
+// `tm1-mcp-server secrets <command>` — manage the keychain entries of a
+// connection (see ./secrets.ts). No command ever prints a secret value.
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseDotenv } from "dotenv";
+import { connectionsDir } from "./connections.js";
+import { isSecretKey, keychainAccount, keychainStore, plaintextSecretKeys, SECRET_KEYS, } from "./secrets.js";
+const USAGE = `Usage: tm1-mcp-server secrets <command> <connection> [KEY]
+
+  set <connection> [KEY]     store a secret (prompted, or read from stdin)
+  list <connection>          show which secrets are stored (never the values)
+  delete <connection> [KEY]  remove one secret, or all of the connection's
+  migrate <connection>       move the plaintext secrets of <connection>/.env
+                             into the keychain and set TM1_SECRETS=keychain
+
+KEY is one of ${SECRET_KEYS.join(", ")} (default TM1_PASSWORD).
+<connection> is a folder under ~/.tm1/mcp-servers (or $TM1_CONNECTIONS_DIR).`;
+export async function runSecretsCli(args, env, io = processIo, store) {
+    const [command, connection, keyArg, ...extra] = args;
+    if (!command || command === "help" || command === "--help") {
+        io.out(USAGE);
+        return command ? 0 : 2;
+    }
+    if (!connection || extra.length > 0) {
+        io.err(USAGE);
+        return 2;
+    }
+    if (keyArg !== undefined && !isSecretKey(keyArg)) {
+        io.err(`Unknown KEY "${keyArg}". One of: ${SECRET_KEYS.join(", ")}.`);
+        return 2;
+    }
+    const folder = join(connectionsDir(env), connection);
+    const envFile = join(folder, ".env");
+    if (!existsSync(envFile)) {
+        io.err(`No connection "${connection}": ${envFile} does not exist.`);
+        return 2;
+    }
+    let keychain;
+    try {
+        keychain = store ?? (await keychainStore());
+    }
+    catch (err) {
+        io.err(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    switch (command) {
+        case "set": {
+            const key = keyArg ?? "TM1_PASSWORD";
+            const value = await io.readSecret(`${key} for ${connection}: `);
+            if (value === "") {
+                io.err("Empty value — nothing stored.");
+                return 1;
+            }
+            // Pasted or piped junk becomes a wrong password, and wrong passwords
+            // lock TM1 accounts.
+            if (/[\r\n]/.test(value)) {
+                io.err("The value spans several lines — nothing stored.");
+                return 1;
+            }
+            keychain.set(connection, key, value);
+            io.out(`Stored ${keychainAccount(connection, key)}.`);
+            const marker = parseDotenv(readFileSync(envFile)).TM1_SECRETS;
+            if (marker?.trim().toLowerCase() !== "keychain") {
+                io.out(`The .env does not set TM1_SECRETS=keychain yet, so the server ` +
+                    `ignores this entry. Run \`secrets migrate ${connection}\` or add it.`);
+            }
+            return 0;
+        }
+        case "list": {
+            for (const key of SECRET_KEYS) {
+                const stored = keychain.get(connection, key) !== undefined;
+                io.out(`${key.padEnd(18)} ${stored ? "stored" : "-"}`);
+            }
+            return 0;
+        }
+        case "delete": {
+            const keys = keyArg ? [keyArg] : SECRET_KEYS;
+            for (const key of keys) {
+                if (keychain.delete(connection, key)) {
+                    io.out(`Deleted ${keychainAccount(connection, key)}.`);
+                }
+                else if (keyArg) {
+                    io.out(`No entry ${keychainAccount(connection, key)}.`);
+                }
+            }
+            return 0;
+        }
+        case "migrate":
+            return migrate(connection, envFile, keychain, io);
+        default:
+            io.err(`Unknown command "${command}".\n${USAGE}`);
+            return 2;
+    }
+}
+/**
+ * Move the plaintext secrets of one `.env` into the keychain. Order matters:
+ * every secret is stored and read back BEFORE the file changes, and the new
+ * file is checked to parse to exactly the old settings minus the secrets. No
+ * plaintext backup is kept — that would defeat the point.
+ */
+function migrate(connection, envFile, keychain, io) {
+    const text = readFileSync(envFile, "utf8");
+    const before = parseDotenv(text);
+    const keys = plaintextSecretKeys(before);
+    if (keys.length === 0) {
+        io.out(`${envFile} holds no plaintext secret.`);
+        return 0;
+    }
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const kept = [];
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/.exec(line);
+        const name = match?.[1];
+        if (name && (keys.includes(name) || name === "TM1_SECRETS")) {
+            const value = match[2].trim();
+            const quote = value[0];
+            if ((quote === '"' || quote === "'" || quote === "`") &&
+                value.indexOf(quote, 1) === -1) {
+                io.err(`${name} in ${envFile} is a multi-line value; move it by hand.`);
+                return 1;
+            }
+            continue;
+        }
+        kept.push(line);
+    }
+    while (kept.length > 0 && kept[kept.length - 1] === "")
+        kept.pop();
+    kept.push("TM1_SECRETS=keychain", "");
+    const next = kept.join(eol);
+    const after = parseDotenv(next);
+    // A blank value (TM1_PASSWORD= for a blank-password account) is no secret
+    // and stays in the file.
+    const expected = {
+        ...before,
+        TM1_SECRETS: "keychain",
+    };
+    for (const key of keys)
+        delete expected[key];
+    if (JSON.stringify(sorted(after)) !== JSON.stringify(sorted(expected))) {
+        io.err(`Could not rewrite ${envFile} safely; nothing changed.`);
+        return 1;
+    }
+    for (const key of keys) {
+        const value = before[key];
+        keychain.set(connection, key, value);
+        if (keychain.get(connection, key) !== value) {
+            io.err(`Reading ${keychainAccount(connection, key)} back returned a different ` +
+                `value; ${envFile} left unchanged.`);
+            return 1;
+        }
+        io.out(`Stored ${keychainAccount(connection, key)}.`);
+    }
+    const tmp = `${envFile}.tmp`;
+    writeFileSync(tmp, next);
+    renameSync(tmp, envFile);
+    io.out(`Removed ${keys.join(", ")} from ${envFile} and set TM1_SECRETS=keychain. ` +
+        `Restart the MCP client to pick up the change.`);
+    return 0;
+}
+function sorted(obj) {
+    return Object.entries(obj).sort(([a], [b]) => a.localeCompare(b));
+}
+const processIo = {
+    out: (line) => process.stdout.write(`${line}\n`),
+    err: (line) => process.stderr.write(`${line}\n`),
+    readSecret: (prompt) => process.stdin.isTTY ? promptHidden(prompt) : readPipedStdin(),
+};
+/**
+ * `echo secret | tm1-mcp-server secrets set …` — a leading BOM (PowerShell
+ * pipes) and one trailing newline dropped. Git Bash's mintty is no TTY to
+ * Node either, so typed input lands here too, echoed: say so.
+ */
+async function readPipedStdin() {
+    process.stderr.write("Reading the secret from stdin until EOF. In a terminal that is no TTY to " +
+        "Node (Git Bash/mintty) the input is echoed; pipe the value or use " +
+        "PowerShell/cmd instead.\n");
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return stripPipedInput(Buffer.concat(chunks).toString("utf8"));
+}
+export function stripPipedInput(raw) {
+    return raw.replace(/^\uFEFF/, "").replace(/\r?\n$/, "");
+}
+function promptHidden(prompt) {
+    return new Promise((resolve, reject) => {
+        const stdin = process.stdin;
+        process.stderr.write(prompt);
+        stdin.setRawMode(true);
+        stdin.setEncoding("utf8");
+        stdin.resume();
+        let value = "";
+        const done = (err) => {
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdin.off("data", onData);
+            process.stderr.write("\n");
+            if (err)
+                reject(err);
+            else
+                resolve(value);
+        };
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === "\r" || ch === "\n")
+                    return done();
+                if (ch === "\u0003")
+                    return done(new Error("Aborted."));
+                if (ch === "\u007f" || ch === "\b")
+                    value = value.slice(0, -1);
+                else
+                    value += ch;
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+//# sourceMappingURL=secrets-cli.js.map

package/dist/secrets.d.ts

@@ -0,0 +1,39 @@
+/** Every `.env` key that holds a credential. */
+export declare const SECRET_KEYS: readonly ["TM1_PASSWORD", "TM1_CLIENT_SECRET", "TM1_ACCESS_TOKEN", "TM1_API_KEY", "TM1_CAM_PASSPORT"];
+export type SecretKey = (typeof SECRET_KEYS)[number];
+export declare const KEYCHAIN_SERVICE = "tm1-mcp-server";
+export declare function isSecretKey(key: string): key is SecretKey;
+export declare function keychainAccount(connection: string, key: SecretKey): string;
+/** The Windows Credential Manager target name of one entry. */
+export declare function keychainTarget(connection: string, key: SecretKey): string;
+/** Secret keys that carry a non-empty plaintext value in `env`. */
+export declare function plaintextSecretKeys(env: NodeJS.ProcessEnv): SecretKey[];
+/**
+ * True when the connection keeps its secrets in the keychain. Throws on an
+ * unknown TM1_SECRETS value, and when a keychain connection still carries a
+ * plaintext secret — which of the two should win is not guessable, and a
+ * stale one is exactly the kind of wrong password that locks an account.
+ * An empty value (`TM1_PASSWORD=`, a blank-password account) is no conflict.
+ */
+export declare function usesKeychain(env: NodeJS.ProcessEnv): boolean;
+/** The OS store, narrowed to what the server and the CLI need. */
+export interface SecretStore {
+    get(connection: string, key: SecretKey): string | undefined;
+    set(connection: string, key: SecretKey, value: string): void;
+    /** True when an entry existed. */
+    delete(connection: string, key: SecretKey): boolean;
+}
+/**
+ * The OS keychain. The native binding is imported on first use, so a
+ * platform without a prebuilt binary only breaks connections that ask for it.
+ */
+export declare function keychainStore(): Promise<SecretStore>;
+/**
+ * `env` with every secret the keychain holds for `connection` filled in. The
+ * result goes straight into loadConfig and is never written to process.env,
+ * so child processes do not inherit it.
+ */
+export declare function withKeychainSecrets(connection: string, env: NodeJS.ProcessEnv, store?: SecretStore): Promise<NodeJS.ProcessEnv>;
+/** Appended to a config error on a keychain connection: how to fix it. */
+export declare function keychainHint(connection: string): string;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.js

@@ -0,0 +1,128 @@
+// Connection secrets kept in the OS keychain instead of the `.env`.
+//
+// A connection folder opts in with `TM1_SECRETS=keychain`. Its `.env` then
+// carries no secret; each one lives in the OS store (Windows Credential
+// Manager, macOS Keychain, Linux Secret Service) under
+//
+//   service "tm1-mcp-server", account "<connection>/<KEY>"
+//   Windows target name "<connection>/<KEY>.tm1-mcp-server"
+//
+// The Windows target name is the library default ("<account>.<service>"),
+// pinned by keychainTarget() because a stdlib-only reader — the tm1-api
+// skill's tm1.py calls CredReadW via ctypes — looks the entry up by it. The
+// blob is UTF-16LE. Entry.withTarget() is deliberately not used: in
+// @napi-rs/keyring 2.1.0 on Windows a fresh Entry reads back "" for it.
+//
+// Discovery never reads the store: loadConfig(env, { deferSecrets: true })
+// accepts the folder, and the secrets are read when the connection is first
+// used (ConnectionRegistry.get). Listing connections therefore never touches
+// the keychain, and a missing entry fails that one connection, not startup.
+//
+// What this protects: the secret no longer sits in a file that gets synced,
+// backed up, committed, pasted or read into an agent's context. What it does
+// not: any process running as the same OS user can read the store too.
+import { TM1Error, TM1ErrorCode } from "./types.js";
+/** Every `.env` key that holds a credential. */
+export const SECRET_KEYS = [
+    "TM1_PASSWORD",
+    "TM1_CLIENT_SECRET",
+    "TM1_ACCESS_TOKEN",
+    "TM1_API_KEY",
+    "TM1_CAM_PASSPORT",
+];
+export const KEYCHAIN_SERVICE = "tm1-mcp-server";
+export function isSecretKey(key) {
+    return SECRET_KEYS.includes(key);
+}
+export function keychainAccount(connection, key) {
+    return `${connection}/${key}`;
+}
+/** The Windows Credential Manager target name of one entry. */
+export function keychainTarget(connection, key) {
+    return `${keychainAccount(connection, key)}.${KEYCHAIN_SERVICE}`;
+}
+/** Secret keys that carry a non-empty plaintext value in `env`. */
+export function plaintextSecretKeys(env) {
+    return SECRET_KEYS.filter((key) => Boolean(env[key]));
+}
+/**
+ * True when the connection keeps its secrets in the keychain. Throws on an
+ * unknown TM1_SECRETS value, and when a keychain connection still carries a
+ * plaintext secret — which of the two should win is not guessable, and a
+ * stale one is exactly the kind of wrong password that locks an account.
+ * An empty value (`TM1_PASSWORD=`, a blank-password account) is no conflict.
+ */
+export function usesKeychain(env) {
+    const raw = env.TM1_SECRETS?.trim().toLowerCase();
+    if (!raw)
+        return false;
+    if (raw !== "keychain") {
+        throw new Error(`Invalid TM1_SECRETS: "${env.TM1_SECRETS}". Expected "keychain" or unset.`);
+    }
+    const plain = plaintextSecretKeys(env);
+    if (plain.length > 0) {
+        throw new Error(`TM1_SECRETS=keychain, but the .env still sets ${plain.join(", ")}. ` +
+            `Remove ${plain.length === 1 ? "it" : "them"} from the .env ` +
+            `(\`tm1-mcp-server secrets migrate <connection>\` does both steps).`);
+    }
+    return true;
+}
+let osStore;
+/**
+ * The OS keychain. The native binding is imported on first use, so a
+ * platform without a prebuilt binary only breaks connections that ask for it.
+ */
+export function keychainStore() {
+    osStore ??= import("@napi-rs/keyring").then(({ Entry }) => {
+        const entry = (connection, key) => new Entry(KEYCHAIN_SERVICE, keychainAccount(connection, key));
+        return {
+            get: (connection, key) => entry(connection, key).getPassword() ?? undefined,
+            set: (connection, key, value) => entry(connection, key).setPassword(value),
+            delete: (connection, key) => entry(connection, key).deletePassword(),
+        };
+    }, (err) => {
+        osStore = undefined;
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`The OS keychain is not available on this platform (${reason}).`);
+    });
+    return osStore;
+}
+/**
+ * `env` with every secret the keychain holds for `connection` filled in. The
+ * result goes straight into loadConfig and is never written to process.env,
+ * so child processes do not inherit it.
+ */
+export async function withKeychainSecrets(connection, env, store) {
+    let resolved;
+    try {
+        resolved = store ?? (await keychainStore());
+    }
+    catch (err) {
+        throw new TM1Error({
+            code: TM1ErrorCode.VALIDATION_ERROR,
+            message: `Connection "${connection}" keeps its secrets in the OS keychain: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    const out = { ...env };
+    for (const key of SECRET_KEYS) {
+        let value;
+        try {
+            value = resolved.get(connection, key);
+        }
+        catch (err) {
+            throw new TM1Error({
+                code: TM1ErrorCode.VALIDATION_ERROR,
+                message: `Reading ${keychainAccount(connection, key)} from the OS keychain failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/** Appended to a config error on a keychain connection: how to fix it. */
+export function keychainHint(connection) {
+    return (` The secrets of "${connection}" are read from the OS keychain; store the ` +
+        `missing one with \`npx tm1-mcp-server secrets set ${connection} <KEY>\`.`);
+}
+//# sourceMappingURL=secrets.js.map

package/dist/session-manager.d.ts

@@ -8,6 +8,7 @@ export declare class SessionManager {
     private sessionCookie;
     private authInFlight;
     private keepAliveTimer;
+    private rejectedLogin;
     private readonly config;
     private readonly logger;
     private readonly profile;

package/dist/session-manager.js

@@ -2,6 +2,7 @@ import { createLogger } from "./logger.js";
 import { createConnectionProfile, } from "./tm1-client/connection/profile.js";
 import { getTm1Dispatcher, tm1Fetch } from "./tm1-client/dispatcher.js";
 import { PRODUCT, VERSION } from "./version.js";
+import { TM1Error, TM1ErrorCode } from "./types.js";
 const USER_AGENT = `${PRODUCT}/${VERSION}`;
 export class TimeoutError extends Error {
     timeoutMs;
@@ -31,6 +32,13 @@ export class SessionManager {
     sessionCookie = null;
     authInFlight = null;
     keepAliveTimer = null;
+    // Set once TM1 rejects the configured credentials (401/403 on login).
+    // Credentials come from env and cannot change without a restart, so every
+    // later attempt would be rejected the same way — and each one counts
+    // against MaximumLoginAttempts. Latching here keeps one failed login from
+    // becoming dozens (fan-out tools, the 401 retry, the keep-alive timer)
+    // and locking the account.
+    rejectedLogin = null;
     config;
     logger;
     profile;
@@ -61,6 +69,9 @@ export class SessionManager {
      * requests are using — the "staggered-401 re-auth churn" cascade.
      */
     async authenticate(staleCookie) {
+        if (this.rejectedLogin) {
+            throw this.rejectedLogin;
+        }
         if (staleCookie !== undefined &&
             this.sessionCookie !== null &&
             this.sessionCookie !== staleCookie) {
@@ -105,6 +116,19 @@ export class SessionManager {
         }));
         // Always consume body to release connection
         await response.text();
+        if (response.status === 401 || response.status === 403) {
+            this.rejectedLogin = new TM1Error({
+                code: TM1ErrorCode.AUTH_FAILED,
+                message: `Authentication failed with status ${response.status}: ${response.statusText}. ` +
+                    "No further login attempts are made, so the account is not locked out; " +
+                    "fix the credentials and restart the MCP server.",
+                httpStatus: response.status,
+                endpoint: loginReq.url,
+            });
+            this.logger.error({ endpoint: loginReq.url, status: response.status }, "Authentication rejected; login attempts stopped until restart");
+            this.stopKeepAlive();
+            throw this.rejectedLogin;
+        }
         if (!response.ok) {
             this.logger.error({ endpoint: loginReq.url, status: response.status }, "Authentication failed");
             throw new Error(`Authentication failed with status ${response.status}: ${response.statusText}`);

package/dist/tm1-client/connection/profile.js

@@ -1,6 +1,4 @@
-// OData single-quote escaping for a key segment (double the apostrophes),
-// then URL-encode. Mirrors the `enc` helper used across the service layer.
-const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+import { odataKey } from "../services/odata-page.js";
 function buildBasicToken(user, password) {
     return "Basic " + Buffer.from(`${user}:${password}`).toString("base64");
 }
@@ -79,7 +77,7 @@ function createV12Profile(config) {
     const database = config.database ?? "";
     // encodeURIComponent (not `enc`) for the instance: it's a bare path segment,
     // not an OData quoted key — no apostrophe-doubling needed, just percent-encoding.
-    const dbRoot = `/${encodeURIComponent(instance)}/api/v1/Databases('${enc(database)}')`;
+    const dbRoot = `/${encodeURIComponent(instance)}/api/v1/Databases('${odataKey(database)}')`;
     return {
         // Replacement FUNCTION, not a string: String.replace treats "$&"/"$$"/"$1"
         // in a string replacement specially, which would corrupt dbRoot if instance

package/dist/tm1-client/dispatcher.d.ts

@@ -1,5 +1,5 @@
 import { Agent } from "undici";
 import type { TM1Config } from "../config.js";
-export declare function getTm1Dispatcher(config: TM1Config): Agent | undefined;
+export declare function getTm1Dispatcher(config: TM1Config): Agent;
 export declare function tm1Fetch(url: string, init: RequestInit): Promise<Response>;
 //# sourceMappingURL=dispatcher.d.ts.map

package/dist/tm1-client/dispatcher.js

@@ -6,14 +6,26 @@
 //
 // The Agent is cached so connection-pooling stays effective across requests.
 import { Agent, fetch as undiciFetch } from "undici";
-let cachedAgent;
+//
+// headersTimeout/bodyTimeout are switched off on purpose. undici's defaults
+// (300 s each) end any request that has not answered after five minutes with
+// UND_ERR_HEADERS_TIMEOUT — measured: a 400 s budget died at 300.8 s on both
+// fetch paths. A TI process runs as long as it runs and TM1 has no timeout
+// for it, so the only limit is our own per-request AbortSignal (timeoutMs),
+// which http.ts maps to LOCK_TIMEOUT.
+const agents = new Map();
 export function getTm1Dispatcher(config) {
-    if (config.ssl.rejectUnauthorized)
-        return undefined;
-    if (!cachedAgent) {
-        cachedAgent = new Agent({ connect: { rejectUnauthorized: false } });
+    const verify = config.ssl.rejectUnauthorized;
+    let agent = agents.get(verify);
+    if (!agent) {
+        agent = new Agent({
+            connect: { rejectUnauthorized: verify },
+            headersTimeout: 0,
+            bodyTimeout: 0,
+        });
+        agents.set(verify, agent);
     }
-    return cachedAgent;
+    return agent;
 }
 // Node's BUILT-IN fetch silently drops Set-Cookie headers when handed a
 // dispatcher from the npm undici package (cross-instance Headers handling;

package/dist/tm1-client/http.d.ts

@@ -2,6 +2,7 @@ import type pino from "pino";
 import { type TM1Config } from "../config.js";
 import type { SessionManager } from "../session-manager.js";
 import { TM1Error } from "../types.js";
+import { type Tm1MutationEvent } from "../lib/tm1-events.js";
 export interface RequestOptions {
     timeoutMs?: number;
     signal?: AbortSignal;
@@ -13,6 +14,15 @@ export declare class TM1HttpClient {
     protected readonly sessionManager: SessionManager;
     private readonly profile;
     constructor(config: TM1Config, sessionManager: SessionManager, logger: pino.Logger);
+    private readonly mutationListeners;
+    /**
+     * @internal — subscribe to THIS connection's successful mutations. Unlike
+     * the process-global `tm1Events` bus, listeners die with the client, so a
+     * per-connection cache needs no unsubscribe and never sees another
+     * connection's writes.
+     */
+    onMutation(listener: (e: Tm1MutationEvent) => void): void;
+    private emitMutation;
     /**
      * TM1 major version (11 | 12) — the single numeric source of truth for
      * version-conditional service code. Branch on this, never on the display
@@ -45,6 +55,17 @@ export declare class TM1HttpClient {
      */
     /** @internal — for Service-layer use; not part of the public consumer API. */
     requestRaw(method: string, path: string, opts?: RequestOptions): Promise<string>;
+    /**
+     * Same request as requestRaw, but hands back the bytes instead of a string.
+     *
+     * requestRaw decodes the body as UTF-8, which silently destroys anything
+     * that is not text — a spreadsheet read that way comes back as replacement
+     * characters. Callers that may face binary content use this and decide how
+     * to present it.
+     */
+    /** @internal — for Service-layer use; not part of the public consumer API. */
+    requestRawBytes(method: string, path: string, opts?: RequestOptions): Promise<Buffer>;
+    private fetchRaw;
     /**
      * Make an authenticated HTTP request with a binary body (Buffer/Uint8Array).
      * Used for blob/file uploads where the body is raw bytes (not JSON).

package/dist/tm1-client/http.js

@@ -51,6 +51,24 @@ export class TM1HttpClient {
         this.logger = logger;
         this.profile = createConnectionProfile(config);
     }
+    mutationListeners = [];
+    /**
+     * @internal — subscribe to THIS connection's successful mutations. Unlike
+     * the process-global `tm1Events` bus, listeners die with the client, so a
+     * per-connection cache needs no unsubscribe and never sees another
+     * connection's writes.
+     */
+    onMutation(listener) {
+        this.mutationListeners.push(listener);
+    }
+    emitMutation(method, path) {
+        if (isSafeHttpMethod(method))
+            return;
+        const e = { method, path, connectionId: connectionIdOf(this.config) };
+        tm1Events.emit("mutation", e);
+        for (const listener of this.mutationListeners)
+            listener(e);
+    }
     /**
      * TM1 major version (11 | 12) — the single numeric source of truth for
      * version-conditional service code. Branch on this, never on the display
@@ -110,23 +128,11 @@ export class TM1HttpClient {
                         });
                     }
                     const retryResult = await this.handleResponse(retryResponse, path);
-                    if (!isSafeMethod) {
-                        tm1Events.emit("mutation", {
-                            method,
-                            path,
-                            connectionId: connectionIdOf(this.config),
-                        });
-                    }
+                    this.emitMutation(method, path);
                     return retryResult;
                 }
                 const result = await this.handleResponse(response, path);
-                if (!isSafeMethod) {
-                    tm1Events.emit("mutation", {
-                        method,
-                        path,
-                        connectionId: connectionIdOf(this.config),
-                    });
-                }
+                this.emitMutation(method, path);
                 return result;
             }
             catch (error) {
@@ -174,6 +180,22 @@ export class TM1HttpClient {
      */
     /** @internal — for Service-layer use; not part of the public consumer API. */
     async requestRaw(method, path, opts) {
+        return (await this.fetchRaw(method, path, opts)).text();
+    }
+    /**
+     * Same request as requestRaw, but hands back the bytes instead of a string.
+     *
+     * requestRaw decodes the body as UTF-8, which silently destroys anything
+     * that is not text — a spreadsheet read that way comes back as replacement
+     * characters. Callers that may face binary content use this and decide how
+     * to present it.
+     */
+    /** @internal — for Service-layer use; not part of the public consumer API. */
+    async requestRawBytes(method, path, opts) {
+        const res = await this.fetchRaw(method, path, opts);
+        return Buffer.from(await res.arrayBuffer());
+    }
+    async fetchRaw(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();
@@ -198,15 +220,8 @@ export class TM1HttpClient {
             }
             throw this.classifyHttpError(response.status, path, body || undefined);
         }
-        const text = await response.text();
-        if (!isSafeHttpMethod(method)) {
-            tm1Events.emit("mutation", {
-                method,
-                path,
-                connectionId: connectionIdOf(this.config),
-            });
-        }
-        return text;
+        this.emitMutation(method, path);
+        return response;
     }
     /**
      * Make an authenticated HTTP request with a binary body (Buffer/Uint8Array).
@@ -237,13 +252,7 @@ export class TM1HttpClient {
             }
             throw this.classifyHttpError(response.status, path, errBody || undefined);
         }
-        if (!isSafeHttpMethod(method)) {
-            tm1Events.emit("mutation", {
-                method,
-                path,
-                connectionId: connectionIdOf(this.config),
-            });
-        }
+        this.emitMutation(method, path);
     }
     /**
      * Low-level single fetch with timeout + AbortSignal wiring.