tm1npm 1.6.0 → 2.0.0

package/src/services/RestService.ts

@@ -1,5 +1,12 @@
 import axios, { AxiosInstance, AxiosResponse, AxiosRequestConfig } from 'axios';
+import * as https from 'https';
+import * as fs from 'fs';
 import { TM1RestException, TM1TimeoutException } from '../exceptions/TM1Exception';
+import { formatUrl, CaseAndSpaceInsensitiveSet, caseAndSpaceInsensitiveEquals } from '../utils/Utils';
+
+type UrlTopology = 'base_url' | 'v11' | 'ibm_cloud' | 'pa_proxy' | 's2s';
+
+const PRODUCT_VERSION_AUTH_SUFFIX = '/Configuration/ProductVersion/$value';
 
 export enum AuthenticationMode {
     BASIC = 1,
@@ -28,6 +35,9 @@ export interface RestServiceConfig {
     timeout?: number;
     cancelAtTimeout?: boolean;
     asyncRequestsMode?: boolean;
+    asyncPollingInitialDelay?: number;
+    asyncPollingMaxDelay?: number;
+    asyncPollingBackoffFactor?: number;
     connectionPoolSize?: number;
     poolConnections?: number;
     instance?: string;
@@ -39,6 +49,42 @@ export interface RestServiceConfig {
     apiKey?: string;
     accessToken?: string;
     tenant?: string;
+
+    // v12 / Cloud URL components
+    iamUrl?: string;
+    paUrl?: string;
+    cpdUrl?: string;
+
+    // SSO / CAM
+    gateway?: string;
+
+    // Integrated Windows Auth / Kerberos (config surface; auth flow unchanged)
+    integratedLogin?: boolean;
+    integratedLoginDomain?: string;
+    integratedLoginService?: string;
+    integratedLoginHost?: string;
+    integratedLoginDelegate?: boolean;
+
+    // Network / TLS
+    proxies?: { http?: string; https?: string };
+    sslContext?: https.Agent;
+    cert?: string | [string, string];
+
+    // Reconnect behavior (mirrors tm1py kwargs)
+    reConnectOnSessionTimeout?: boolean;
+    reConnectOnRemoteDisconnect?: boolean;
+    remoteDisconnectMaxRetries?: number;
+    remoteDisconnectRetryDelay?: number;
+    remoteDisconnectMaxDelay?: number;
+}
+
+export interface RequestOptions extends Omit<AxiosRequestConfig, 'timeout'> {
+    asyncRequestsMode?: boolean;
+    returnAsyncId?: boolean;
+    timeout?: number;
+    cancelAtTimeout?: boolean;
+    idempotent?: boolean;
+    verifyResponse?: boolean;
 }
 
 export class RestService {
@@ -53,55 +99,300 @@ export class RestService {
     private static readonly DEFAULT_CONNECTION_POOL_SIZE = 10;
     private static readonly DEFAULT_POOL_CONNECTIONS = 1;
 
+    private static readonly SESSION_COOKIE_NAMES = ['TM1SessionId', 'paSession'] as const;
+
     private axiosInstance!: AxiosInstance;
     private config: RestServiceConfig;
-    private sessionId?: string;
+    private sessionCookies: Map<string, string> = new Map();
     private sandboxName?: string;
     private isConnected: boolean = false;
     private _serverVersion?: string;
+    private _asyncRequestsMode: boolean;
+    private _cancelAtTimeout: boolean;
+    private _timeout: number;
+    private _asyncPollingInitialDelay: number;
+    private _asyncPollingMaxDelay: number;
+    private _asyncPollingBackoffFactor: number;
+    private _reConnectOnSessionTimeout: boolean;
+    private _reConnectOnRemoteDisconnect: boolean;
+    private _remoteDisconnectMaxRetries: number;
+    private _remoteDisconnectRetryDelay: number;
+    private _remoteDisconnectMaxDelay: number;
+    private _isAdmin?: boolean;
+    private _isDataAdmin?: boolean;
+    private _isSecurityAdmin?: boolean;
+    private _isOpsAdmin?: boolean;
+    private _activeUserGroupsPromise?: Promise<CaseAndSpaceInsensitiveSet>;
 
     public get version(): string | undefined {
         return this._serverVersion;
     }
 
+    // Sync accessors for cached role flags. Return false before the first
+    // is_*_admin() call resolves — callers that need the real value must
+    // await is_admin() / is_data_admin() / etc. first.
+    public get isAdmin(): boolean { return this._isAdmin ?? false; }
+    public get isDataAdmin(): boolean { return this._isDataAdmin ?? false; }
+    public get isSecurityAdmin(): boolean { return this._isSecurityAdmin ?? false; }
+    public get isOpsAdmin(): boolean { return this._isOpsAdmin ?? false; }
+
     constructor(config: RestServiceConfig) {
         this.config = { ...config };
+        this._asyncRequestsMode = config.asyncRequestsMode ?? false;
+        this._cancelAtTimeout = config.cancelAtTimeout ?? false;
+        this._timeout = config.timeout ?? 60;
+        this._asyncPollingInitialDelay = config.asyncPollingInitialDelay ?? 0.1;
+        this._asyncPollingMaxDelay = config.asyncPollingMaxDelay ?? 1.0;
+        this._asyncPollingBackoffFactor = config.asyncPollingBackoffFactor ?? 2.0;
+        this._reConnectOnSessionTimeout = config.reConnectOnSessionTimeout ?? true;
+        this._reConnectOnRemoteDisconnect = config.reConnectOnRemoteDisconnect ?? true;
+        this._remoteDisconnectMaxRetries = config.remoteDisconnectMaxRetries ?? 5;
+        this._remoteDisconnectRetryDelay = config.remoteDisconnectRetryDelay ?? 1;
+        this._remoteDisconnectMaxDelay = config.remoteDisconnectMaxDelay ?? 30;
+
+        // Pre-populate admin flags for the built-in ADMIN user (mirrors tm1py)
+        if (config.user && caseAndSpaceInsensitiveEquals(config.user, 'ADMIN')) {
+            this._isAdmin = true;
+            this._isDataAdmin = true;
+            this._isSecurityAdmin = true;
+            this._isOpsAdmin = true;
+        }
+
         this.setupAxiosInstance();
+        if (this.config.sessionId) {
+            // Mirror tm1py's _set_session_id_cookie: v12 topologies use paSession,
+            // v11 and baseUrl overrides use TM1SessionId.
+            const topo = this.determineTopology();
+            const cookieName = (topo === 'ibm_cloud' || topo === 'pa_proxy' || topo === 's2s')
+                ? 'paSession'
+                : 'TM1SessionId';
+            this.sessionCookies.set(cookieName, this.config.sessionId);
+        }
+    }
+
+    private getSessionCookieValue(): string | undefined {
+        for (const name of RestService.SESSION_COOKIE_NAMES) {
+            const value = this.sessionCookies.get(name);
+            if (value) return value;
+        }
+        return undefined;
+    }
+
+    private buildCookieHeader(): string | undefined {
+        if (this.sessionCookies.size === 0) return undefined;
+        const parts: string[] = [];
+        for (const [name, value] of this.sessionCookies) {
+            parts.push(`${name}=${value}`);
+        }
+        return parts.join('; ');
+    }
+
+    private parseSetCookieHeaders(setCookie: string[] | string | undefined): void {
+        if (!setCookie) return;
+        const list = RestService.normaliseSetCookie(setCookie);
+        for (const raw of list) {
+            const firstSegment = raw.split(';')[0];
+            const eqIdx = firstSegment.indexOf('=');
+            if (eqIdx <= 0) continue;
+            // Strip CR/LF/NUL defensively to block header-injection via compromised response
+            const sanitize = (s: string) => s.replace(/[\r\n\0]/g, '').trim();
+            const name = sanitize(firstSegment.slice(0, eqIdx));
+            const value = sanitize(firstSegment.slice(eqIdx + 1));
+            if (!(RestService.SESSION_COOKIE_NAMES as readonly string[]).includes(name)) continue;
+            if (value === '') {
+                this.sessionCookies.delete(name);
+            } else {
+                this.sessionCookies.set(name, value);
+            }
+        }
+    }
+
+    private removeAuthorizationHeader(): void {
+        delete this.axiosInstance.defaults.headers.common['Authorization'];
+    }
+
+    private deleteHeaderCaseInsensitive(headers: Record<string, unknown> | undefined, name: string): void {
+        if (!headers) return;
+        // axios 1.x may supply an AxiosHeaders instance with case-insensitive lookup; plain objects
+        // (common in retry paths and test mocks) are case-sensitive and require explicit iteration
+        const target = name.toLowerCase();
+        for (const key of Object.keys(headers)) {
+            if (key.toLowerCase() === target) {
+                delete (headers as Record<string, unknown>)[key];
+            }
+        }
     }
 
     private setupAxiosInstance(): void {
         const baseURL = this.buildBaseUrl();
-        
-        this.axiosInstance = axios.create({
+
+        const axiosConfig: AxiosRequestConfig = {
             baseURL,
-            timeout: (this.config.timeout || 60) * 1000,
+            timeout: this._timeout * 1000,
             headers: {
                 ...RestService.HEADERS,
                 ...(this.config.sessionContext && { 'TM1-SessionContext': this.config.sessionContext })
             }
-        });
+        };
+
+        if (this.config.proxies) {
+            const proxyUrl = this.config.proxies.https || this.config.proxies.http;
+            if (proxyUrl) {
+                const parsed = new URL(proxyUrl);
+                axiosConfig.proxy = {
+                    host: parsed.hostname,
+                    port: parsed.port
+                        ? parseInt(parsed.port, 10)
+                        : (parsed.protocol === 'https:' ? 443 : 80),
+                    protocol: parsed.protocol.replace(':', ''),
+                    ...(parsed.username && {
+                        auth: {
+                            username: decodeURIComponent(parsed.username),
+                            password: decodeURIComponent(parsed.password)
+                        }
+                    })
+                };
+            }
+        }
+
+        if (this.config.sslContext) {
+            axiosConfig.httpsAgent = this.config.sslContext;
+        } else if (this.config.cert) {
+            const [certPath, keyPath] = Array.isArray(this.config.cert)
+                ? this.config.cert
+                : [this.config.cert, undefined];
+            axiosConfig.httpsAgent = new https.Agent({
+                cert: fs.readFileSync(certPath),
+                key: keyPath ? fs.readFileSync(keyPath) : undefined
+            });
+        }
+
+        this.axiosInstance = axios.create(axiosConfig);
 
         this.setupInterceptors();
     }
 
     private buildBaseUrl(): string {
-        if (this.config.baseUrl) {
-            return this.config.baseUrl;
+        return this.resolveRoots().serviceRoot;
+    }
+
+    /**
+     * Pick the deployment topology based on the provided config, mirroring
+     * tm1py's _determine_auth_mode + _construct_service_and_auth_root dispatch.
+     *
+     * Note: authUrl is intentionally excluded from the v12 signal set because
+     * tm1npm historically uses authUrl for CAM SSO (unlike tm1py, where auth_url
+     * is a v12-only field). apiKey is also excluded to avoid collision with the
+     * existing BASIC_API_KEY auth flow.
+     */
+    private determineTopology(): UrlTopology {
+        const c = this.config;
+        const hasV12Signal = !!(c.instance || c.database || c.iamUrl || c.paUrl || c.tenant);
+        // tm1py's _construct_service_and_auth_root routes v12 modes (IBM Cloud / PA
+        // Proxy / S2S) through their dedicated constructors even if base_url is
+        // supplied. Only non-v12 configs fall through to the base_url override.
+        if (!hasV12Signal) return c.baseUrl ? 'base_url' : 'v11';
+        if (c.iamUrl) return 'ibm_cloud';
+        if (c.address && c.user && !c.instance) return 'pa_proxy';
+        return 's2s';
+    }
+
+    /**
+     * Resolve the TM1 service root and auth root URLs for the configured topology.
+     * Mirrors tm1py's _construct_service_and_auth_root return tuple.
+     */
+    private resolveRoots(): { serviceRoot: string; authRoot: string } {
+        switch (this.determineTopology()) {
+            case 'base_url':  return this.rootsFromBaseUrl();
+            case 'ibm_cloud': return this.rootsIbmCloud();
+            case 'pa_proxy':  return this.rootsPaProxy();
+            case 's2s':       return this.rootsS2s();
+            case 'v11':
+            default:          return this.rootsV11();
         }
+    }
 
+    private rootsV11(): { serviceRoot: string; authRoot: string } {
         const protocol = this.config.ssl ? 'https' : 'http';
         const address = this.config.address || 'localhost';
-        const port = this.config.port || 8001;
-        
-        return `${protocol}://${address}:${port}/api/v1`;
+        const port = this.config.port ?? 8001;
+        const serviceRoot = `${protocol}://${address}:${port}/api/v1`;
+        return { serviceRoot, authRoot: serviceRoot + PRODUCT_VERSION_AUTH_SUFFIX };
+    }
+
+    private rootsIbmCloud(): { serviceRoot: string; authRoot: string } {
+        const { address, tenant, database, ssl } = this.config;
+        if (!address || !tenant || !database) {
+            throw new Error("'address', 'tenant' and 'database' must be provided to connect to TM1 > v12 in IBM Cloud");
+        }
+        if (!ssl) {
+            throw new Error("'ssl' must be true to connect to TM1 > v12 in IBM Cloud");
+        }
+        const t = encodeURIComponent(tenant);
+        const d = encodeURIComponent(database);
+        const serviceRoot = `https://${address}/api/${t}/v0/tm1/${d}`;
+        return { serviceRoot, authRoot: serviceRoot + PRODUCT_VERSION_AUTH_SUFFIX };
+    }
+
+    private rootsPaProxy(): { serviceRoot: string; authRoot: string } {
+        const { address, database, ssl } = this.config;
+        if (!address || !database) {
+            throw new Error("'address' and 'database' must be provided to connect to TM1 > v12 using PA Proxy");
+        }
+        const protocol = ssl ? 'https' : 'http';
+        const d = encodeURIComponent(database);
+        const serviceRoot = `${protocol}://${address}/tm1/${d}/api/v1`;
+        const authRoot = `${protocol}://${address}/login`;
+        return { serviceRoot, authRoot };
+    }
+
+    private rootsS2s(): { serviceRoot: string; authRoot: string } {
+        const { instance, database, ssl, port } = this.config;
+        if (!instance || !database) {
+            throw new Error("'instance' and 'database' arguments are required for v12 authentication with 'address'");
+        }
+        const protocol = ssl ? 'https' : 'http';
+        const address = this.config.address && this.config.address.length > 0
+            ? this.config.address
+            : 'localhost';
+        const portPart = port != null ? `:${port}` : '';
+        const i = encodeURIComponent(instance);
+        const d = encodeURIComponent(database);
+        const serviceRoot = `${protocol}://${address}${portPart}/${i}/api/v1/Databases('${d}')`;
+        const authRoot = `${protocol}://${address}${portPart}/${i}/auth/v1/session`;
+        return { serviceRoot, authRoot };
+    }
+
+    private rootsFromBaseUrl(): { serviceRoot: string; authRoot: string } {
+        const base = this.config.baseUrl!;
+        if (this.config.address) {
+            throw new Error("Base URL and Address cannot be specified at the same time");
+        }
+        if (/api\/v1\/Databases/.test(base)) {
+            if (!this.config.authUrl) {
+                throw new Error("Auth_url missing — when connecting to planning analytics engine using base_url, you must specify a corresponding auth_url");
+            }
+            return { serviceRoot: base, authRoot: this.config.authUrl };
+        }
+        // Recognize baseUrl shapes documented in docs/connection-guide.md
+        // (TM1 11 IBM Cloud `/tm1/api/tm1`, TM1 12 PaaS/access-token `/v0/tm1/...`)
+        // and use them verbatim. Only fall through to /api/v1 suffixing when the
+        // URL clearly lacks any TM1 API path — matching tm1py's fallback.
+        const trimmed = base.replace(/\/+$/, '');
+        // Each alternative is $-anchored (after trailing-slash trim above) so the
+        // match intent is explicit: the URL already ends in a TM1 API suffix.
+        const hasApiSuffix = /\/api\/v1$|\/v0\/tm1\/[^/]+$|\/tm1\/api\/tm1$/.test(trimmed);
+        const serviceRoot = hasApiSuffix ? trimmed : `${trimmed}/api/v1`;
+        return { serviceRoot, authRoot: serviceRoot + PRODUCT_VERSION_AUTH_SUFFIX };
     }
 
     private setupInterceptors(): void {
         // Request interceptor
         this.axiosInstance.interceptors.request.use(
             (config) => {
-                if (this.sessionId) {
-                    config.headers['TM1SessionId'] = this.sessionId;
+                const cookieHeader = this.buildCookieHeader();
+                if (cookieHeader) {
+                    config.headers['Cookie'] = cookieHeader;
                 }
                 if (this.sandboxName) {
                     config.headers['TM1-Sandbox'] = this.sandboxName;
@@ -113,29 +404,34 @@ export class RestService {
 
         // Response interceptor with retry logic
         this.axiosInstance.interceptors.response.use(
-            (response) => response,
+            (response) => {
+                this.parseSetCookieHeaders(response.headers?.['set-cookie']);
+                return response;
+            },
             async (error) => {
+                if (error.response) {
+                    this.parseSetCookieHeaders(error.response.headers?.['set-cookie']);
+                }
                 const originalRequest = error.config;
 
                 // Handle timeout errors
-                if (error.code === 'ECONNABORTED' || error.message.includes('timeout')) {
+                if (error.code === 'ECONNABORTED' || error.message?.includes?.('timeout')) {
                     throw new TM1TimeoutException(`Request timeout: ${error.message}`);
                 }
 
-                // Handle authentication errors with retry
-                if (error.response?.status === 401 && !originalRequest._retry) {
+                // Handle authentication errors with retry. Guarded by this.isConnected so a 401
+                // during disconnect()'s tm1.Close POST cannot recurse back into reAuthenticate().
+                if (error.response?.status === 401 && originalRequest && !originalRequest._retry
+                    && this.isConnected && this._reConnectOnSessionTimeout) {
                     originalRequest._retry = true;
 
                     try {
-                        // Attempt re-authentication
                         await this.reAuthenticate();
 
-                        // Update the request with new session/token
-                        if (this.sessionId) {
-                            originalRequest.headers['TM1SessionId'] = this.sessionId;
-                        }
+                        // Stale values would defeat the rebuild by the request interceptor on replay
+                        this.deleteHeaderCaseInsensitive(originalRequest.headers, 'Cookie');
+                        this.deleteHeaderCaseInsensitive(originalRequest.headers, 'Authorization');
 
-                        // Retry the original request
                         return this.axiosInstance(originalRequest);
                     } catch (reAuthError) {
                         // Re-authentication failed, throw original error
@@ -144,7 +440,7 @@ export class RestService {
                 }
 
                 // Handle connection errors with retry
-                if (this.shouldRetryRequest(error) && this.canRetryRequest(originalRequest)) {
+                if (originalRequest && this.shouldRetryRequest(error) && this.canRetryRequest(originalRequest)) {
                     return this.retryRequest(originalRequest);
                 }
 
@@ -163,6 +459,7 @@ export class RestService {
      * Determine if a request should be retried
      */
     private shouldRetryRequest(error: any): boolean {
+        if (!this._reConnectOnRemoteDisconnect) return false;
         // Retry on network errors, timeouts, and 5xx server errors
         return !error.response ||
                error.code === 'ECONNRESET' ||
@@ -175,21 +472,45 @@ export class RestService {
      * Check if a request can be retried
      */
     private canRetryRequest(config: any): boolean {
+        if (config._idempotent === false) {
+            return false;
+        }
         // Don't retry if already retried maximum times
         config._retryCount = config._retryCount || 0;
-        return config._retryCount < 3;
+        return config._retryCount < this._remoteDisconnectMaxRetries;
     }
 
     /**
-     * Retry a failed request with exponential backoff
+     * Retry a failed request with exponential backoff, reconnecting the
+     * session before replay. Mirrors tm1py's _handle_remote_disconnect,
+     * which calls _manage_http_adapter() + connect() prior to retrying
+     * so a dropped session is re-established rather than replayed dead.
      */
     private async retryRequest(config: any): Promise<any> {
         config._retryCount = config._retryCount || 0;
         config._retryCount++;
 
-        const retryDelay = Math.pow(2, config._retryCount) * 1000; // Exponential backoff
+        const baseDelay = this._remoteDisconnectRetryDelay * Math.pow(2, config._retryCount - 1);
+        const retryDelay = Math.min(baseDelay, this._remoteDisconnectMaxDelay) * 1000;
         await new Promise(resolve => setTimeout(resolve, retryDelay));
 
+        // Re-establish session before replay. Clear sessionCookies first so
+        // connect() runs a full setupAuthentication (mirrors tm1py, whose
+        // connect() always re-runs _start_session / _set_session_id_cookie
+        // regardless of prior cookie state). Without this, a stale cookie
+        // from a server-invalidated session would be reused, the probe GET
+        // would 401, and the whole retry path would silently fail.
+        // Flip isConnected=false so the 401 re-auth branch cannot recurse
+        // through the probe.
+        this.sessionCookies.clear();
+        this.isConnected = false;
+        await this.connect();
+
+        // Drop stale Cookie/Authorization on the original config — the request
+        // interceptor rebuilds Cookie from sessionCookies on replay.
+        this.deleteHeaderCaseInsensitive(config.headers, 'Cookie');
+        this.deleteHeaderCaseInsensitive(config.headers, 'Authorization');
+
         return this.axiosInstance(config);
     }
 
@@ -207,24 +528,197 @@ export class RestService {
         }
     }
 
+    private *waitTimeGenerator(timeout: number): Generator<number> {
+        let delay = this._asyncPollingInitialDelay;
+        let elapsed = 0;
+
+        if (timeout) {
+            while (elapsed < timeout) {
+                yield delay;
+                elapsed += delay;
+                delay = Math.min(delay * this._asyncPollingBackoffFactor, this._asyncPollingMaxDelay);
+            }
+        } else {
+            while (true) {
+                yield delay;
+                delay = Math.min(delay * this._asyncPollingBackoffFactor, this._asyncPollingMaxDelay);
+            }
+        }
+    }
+
+    private async _executeSyncRequest(
+        method: string,
+        url: string,
+        data?: any,
+        timeout?: number,
+        idempotent?: boolean,
+        axiosExtras?: Partial<AxiosRequestConfig>
+    ): Promise<AxiosResponse> {
+        const config: AxiosRequestConfig = {
+            method: method as AxiosRequestConfig['method'],
+            url,
+            data,
+            ...axiosExtras
+        };
+
+        if (timeout !== undefined) {
+            config.timeout = timeout * 1000;
+        }
+
+        (config as any)._idempotent = idempotent ?? false;
+
+        return this.axiosInstance.request(config);
+    }
+
+    private async _executeAsyncRequest(
+        method: string,
+        url: string,
+        data?: any,
+        timeout?: number,
+        cancelAtTimeout?: boolean,
+        returnAsyncId?: boolean,
+        idempotent?: boolean,
+        axiosExtras?: Partial<AxiosRequestConfig>
+    ): Promise<AxiosResponse | string> {
+        const preferValue = returnAsyncId ? 'respond-async' : 'respond-async,wait=55';
+        const config: AxiosRequestConfig = {
+            method: method as AxiosRequestConfig['method'],
+            url,
+            data,
+            ...axiosExtras,
+            headers: {
+                ...axiosExtras?.headers,
+                Prefer: preferValue
+            }
+        };
+
+        if (timeout !== undefined) {
+            config.timeout = timeout * 1000;
+        }
+
+        (config as any)._idempotent = idempotent ?? false;
+
+        const response = await this.axiosInstance.request(config);
+
+        if (response.status !== 202) {
+            // Server completed synchronously. If the caller asked for an async
+            // ID (returnAsyncId: true) there is none to return — hand back the
+            // full response so the caller can inspect the result directly.
+            return response;
+        }
+
+        const location = response.headers['location'] || '';
+        const match = typeof location === 'string' ? location.match(/\('([^']+)'\)/) : null;
+        const asyncId = match ? match[1] : undefined;
+
+        if (!asyncId) {
+            throw new TM1RestException(
+                `Async request returned 202 but no valid async ID in Location header: ${location}`
+            );
+        }
+
+        if (returnAsyncId) {
+            return asyncId;
+        }
+
+        return this._pollAsyncResponse(
+            asyncId,
+            timeout ?? this._timeout,
+            cancelAtTimeout ?? this._cancelAtTimeout
+        );
+    }
+
+    private async _pollAsyncResponse(
+        asyncId: string,
+        timeout: number,
+        cancelAtTimeout: boolean
+    ): Promise<AxiosResponse> {
+        for (const wait of this.waitTimeGenerator(timeout)) {
+            const response = await this.retrieve_async_response(asyncId);
+
+            if (response.status === 200 || response.status === 201) {
+                this.verifyAsyncResultHeader(response);
+                return response;
+            }
+
+            await new Promise(resolve => setTimeout(resolve, wait * 1000));
+        }
+
+        if (cancelAtTimeout) {
+            try {
+                await this.cancel_async_operation(asyncId);
+            } catch (cancelError) {
+                console.warn(`Failed to cancel async operation ${asyncId} at timeout:`, cancelError);
+            }
+        }
+
+        throw new TM1TimeoutException(
+            `Async operation ${asyncId} timed out after ${timeout} seconds`,
+            timeout
+        );
+    }
+
+    private async _request(
+        method: string,
+        url: string,
+        data?: any,
+        options?: RequestOptions
+    ): Promise<AxiosResponse | string> {
+        const timeout = options?.timeout ?? this._timeout;
+        const cancelAtTimeout = options?.cancelAtTimeout ?? this._cancelAtTimeout;
+        const asyncMode = options?.returnAsyncId || (options?.asyncRequestsMode ?? this._asyncRequestsMode);
+        const verifyResponse = options?.verifyResponse ?? true;
+        const idempotent = options?.idempotent ?? false;
+        const {
+            asyncRequestsMode: _asyncModeOpt,
+            returnAsyncId,
+            cancelAtTimeout: _cancelAtTimeoutOpt,
+            idempotent: _idempotentOpt,
+            verifyResponse: _verifyResponseOpt,
+            timeout: _timeoutOpt,
+            ...axiosExtras
+        } = options ?? {};
+
+        if (!verifyResponse && axiosExtras.validateStatus === undefined) {
+            axiosExtras.validateStatus = () => true;
+        }
+
+        if (asyncMode) {
+            return this._executeAsyncRequest(
+                method,
+                url,
+                data,
+                timeout,
+                cancelAtTimeout,
+                returnAsyncId,
+                idempotent,
+                axiosExtras
+            );
+        }
+
+        return this._executeSyncRequest(method, url, data, timeout, idempotent, axiosExtras);
+    }
+
     public async connect(): Promise<void> {
         try {
-            // Set up authentication based on configuration
-            await this.setupAuthentication();
-
-            // Test connection
-            const response = await this.axiosInstance.get('/Configuration/ServerName');
-            
-            // Extract session ID from response headers
-            const setCookie = response.headers['set-cookie'];
-            if (setCookie) {
-                for (const cookie of setCookie) {
-                    const match = cookie.match(/TM1SessionId=([^;]+)/);
-                    if (match) {
-                        this.sessionId = match[1];
-                        break;
-                    }
-                }
+            if (this.getSessionCookieValue() === undefined) {
+                await this.setupAuthentication();
+            }
+
+            // Mark probe non-idempotent so the response interceptor's retry
+            // branch skips it. Without this, a retry-triggered connect() whose
+            // probe also fails would spawn another connect(), recursively,
+            // bypassing remoteDisconnectMaxRetries (each probe has its own
+            // fresh _retryCount).
+            await this.axiosInstance.get(
+                '/Configuration/ServerName',
+                { _idempotent: false } as AxiosRequestConfig
+            );
+
+            // Strip Authorization only if the session cookie is established; Bearer/API-key
+            // modes that never issue a cookie must keep Authorization to stay authenticated
+            if (this.getSessionCookieValue()) {
+                this.removeAuthorizationHeader();
             }
 
             this.isConnected = true;
@@ -234,39 +728,57 @@ export class RestService {
     }
 
     public async disconnect(): Promise<void> {
-        if (this.isConnected && this.sessionId) {
+        const shouldClose = this.isConnected;
+        // Flip isConnected first so a 401 on tm1.Close cannot trigger reAuthenticate recursion
+        this.isConnected = false;
+        if (shouldClose) {
             try {
                 await this.axiosInstance.post('/ActiveSession/tm1.Close', {});
             } catch (error) {
                 // Ignore errors during disconnect
             }
-            this.isConnected = false;
-            this.sessionId = undefined;
         }
+        this.sessionCookies.clear();
     }
 
-    public async get(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse> {
-        return this.axiosInstance.get(url, config);
+    /**
+     * When `returnAsyncId: true`, the caller receives the async id string
+     * iff the server returns `202 Accepted`. If TM1 short-circuits with
+     * `200/201`, the full `AxiosResponse` is returned instead — the
+     * declared `Promise<string>` return type is a best-effort narrowing.
+     */
+    public async get(url: string, options: RequestOptions & { returnAsyncId: true }): Promise<string | AxiosResponse>;
+    public async get(url: string, options?: RequestOptions): Promise<AxiosResponse>;
+    public async get(url: string, options?: RequestOptions): Promise<AxiosResponse | string> {
+        return this._request('GET', url, undefined, { idempotent: true, ...options });
     }
 
-    public async post(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse> {
-        return this.axiosInstance.post(url, data, config);
+    public async post(url: string, data: any, options: RequestOptions & { returnAsyncId: true }): Promise<string | AxiosResponse>;
+    public async post(url: string, data?: any, options?: RequestOptions): Promise<AxiosResponse>;
+    public async post(url: string, data?: any, options?: RequestOptions): Promise<AxiosResponse | string> {
+        return this._request('POST', url, data, options);
     }
 
-    public async patch(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse> {
-        return this.axiosInstance.patch(url, data, config);
+    public async patch(url: string, data: any, options: RequestOptions & { returnAsyncId: true }): Promise<string | AxiosResponse>;
+    public async patch(url: string, data?: any, options?: RequestOptions): Promise<AxiosResponse>;
+    public async patch(url: string, data?: any, options?: RequestOptions): Promise<AxiosResponse | string> {
+        return this._request('PATCH', url, data, options);
     }
 
-    public async put(url: string, data?: any, config?: AxiosRequestConfig): Promise<AxiosResponse> {
-        return this.axiosInstance.put(url, data, config);
+    public async put(url: string, data: any, options: RequestOptions & { returnAsyncId: true }): Promise<string | AxiosResponse>;
+    public async put(url: string, data?: any, options?: RequestOptions): Promise<AxiosResponse>;
+    public async put(url: string, data?: any, options?: RequestOptions): Promise<AxiosResponse | string> {
+        return this._request('PUT', url, data, options);
     }
 
-    public async delete(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse> {
-        return this.axiosInstance.delete(url, config);
+    public async delete(url: string, options: RequestOptions & { returnAsyncId: true }): Promise<string | AxiosResponse>;
+    public async delete(url: string, options?: RequestOptions): Promise<AxiosResponse>;
+    public async delete(url: string, options?: RequestOptions): Promise<AxiosResponse | string> {
+        return this._request('DELETE', url, undefined, options);
     }
 
     public getSessionId(): string | undefined {
-        return this.sessionId;
+        return this.getSessionCookieValue();
     }
 
     public setSandbox(sandboxName?: string): void {
@@ -278,7 +790,10 @@ export class RestService {
     }
 
     public isLoggedIn(): boolean {
-        return this.isConnected && !!this.sessionId;
+        return this.isConnected && (
+            !!this.getSessionCookieValue() ||
+            !!this.axiosInstance.defaults.headers.common['Authorization']
+        );
     }
 
     public async getApiMetadata(): Promise<any> {
@@ -286,181 +801,347 @@ export class RestService {
         return response.data;
     }
 
+    // =========================================================================
+    // Authentication helpers — mirror tm1py's _build_authorization_token*,
+    // _generate_*_access_token, and _start_session flows
+    // =========================================================================
+
     /**
-     * Set up authentication based on configuration
+     * Build an httpsAgent option that skips TLS verification when verify is false.
      */
-    private async setupAuthentication(): Promise<void> {
-        // Access Token authentication (TM1 12+ with JWT tokens)
-        if (this.config.accessToken) {
-            this.axiosInstance.defaults.headers.common['Authorization'] = `Bearer ${this.config.accessToken}`;
-            return;
-        }
+    private static insecureAgentOption(
+        verify?: boolean | string
+    ): { httpsAgent: https.Agent } | Record<string, never> {
+        return verify === false
+            ? { httpsAgent: new https.Agent({ rejectUnauthorized: false }) }
+            : {};
+    }
 
-        // API Key authentication (TM1 12+ PAaaS)
-        if (this.config.apiKey) {
-            if (this.config.user === 'apikey') {
-                // IBM Cloud API Key style
-                this.axiosInstance.defaults.headers.common['Authorization'] = `Basic ${Buffer.from(`apikey:${this.config.apiKey}`).toString('base64')}`;
-            } else {
-                // Basic API Key style
-                this.axiosInstance.defaults.headers.common['API-Key'] = this.config.apiKey;
+    /**
+     * Normalise a Set-Cookie header value (string | string[] | undefined) into a string[].
+     */
+    private static normaliseSetCookie(raw: string | string[] | undefined): string[] {
+        if (!raw) return [];
+        return Array.isArray(raw) ? raw : [raw];
+    }
+
+    /**
+     * Extract a named cookie value from raw Set-Cookie headers.
+     */
+    private static extractCookieValue(
+        raw: string | string[] | undefined,
+        name: string
+    ): string | undefined {
+        const prefix = name + '=';
+        for (const header of RestService.normaliseSetCookie(raw)) {
+            const segment = header.split(';')[0];
+            if (segment.startsWith(prefix)) {
+                return segment.slice(prefix.length);
             }
-            return;
         }
+        return undefined;
+    }
 
-        // CAM (Cognos Access Manager) authentication
-        if (this.config.authUrl && this.config.camPassport) {
-            await this.setupCamAuthentication();
-            return;
-        }
+    /**
+     * Build Basic Authorization header.
+     * Mirrors tm1py's _build_authorization_token_basic.
+     */
+    private static _buildAuthorizationTokenBasic(user: string, password: string): string {
+        return 'Basic ' + Buffer.from(`${user}:${password}`).toString('base64');
+    }
 
-        // CAM SSO authentication
-        if (this.config.authUrl && this.config.user && this.config.password && this.config.namespace) {
-            await this.setupCamSsoAuthentication();
-            return;
-        }
+    /**
+     * Build CAMNamespace Authorization header.
+     * Mirrors tm1py's _build_authorization_token_cam (non-gateway path).
+     */
+    private static _buildAuthorizationTokenCam(
+        user: string,
+        password: string,
+        namespace: string
+    ): string {
+        return 'CAMNamespace ' + Buffer.from(`${user}:${password}:${namespace}`).toString('base64');
+    }
 
-        // Service-to-Service authentication
-        if (this.config.applicationClientId && this.config.applicationClientSecret) {
-            await this.setupServiceToServiceAuthentication();
-            return;
+    /**
+     * Build CAMPassport Authorization token via gateway SSO.
+     * Mirrors tm1py's _build_authorization_token_cam (gateway path).
+     * Makes a GET request to the gateway URL with CAMNamespace as a query
+     * parameter and extracts the cam_passport cookie from the response.
+     *
+     * Note: tm1py uses HttpNegotiateAuth (NTLM/Kerberos) for gateway requests,
+     * which is Windows-only. This implementation sends a plain GET and relies on
+     * the gateway being accessible without NTLM. For environments requiring NTLM,
+     * pass a pre-obtained cam_passport via config.camPassport instead.
+     */
+    private static async _buildAuthorizationTokenCamSso(
+        gateway: string,
+        namespace: string,
+        verify?: boolean | string
+    ): Promise<string> {
+        const response = await axios.get(gateway, {
+            params: { CAMNamespace: namespace },
+            ...RestService.insecureAgentOption(verify)
+        });
+        if (response.status !== 200) {
+            throw new Error(
+                'Failed to authenticate through CAM. Expected status_code 200, received status_code: ' +
+                response.status
+            );
         }
-
-        // Basic authentication (default)
-        if (this.config.user && this.config.password) {
-            const credentials = Buffer.from(`${this.config.user}:${this.config.password}`).toString('base64');
-            this.axiosInstance.defaults.headers.common['Authorization'] = `Basic ${credentials}`;
-
-            // Add namespace for TM1 Cloud
-            if (this.config.namespace) {
-                this.axiosInstance.defaults.headers.common['TM1-Namespace'] = this.config.namespace;
-            }
-            return;
+        const passport = RestService.extractCookieValue(
+            response.headers['set-cookie'], 'cam_passport'
+        );
+        if (!passport) {
+            throw new Error(
+                "Failed to authenticate through CAM. HTTP response does not contain 'cam_passport' cookie"
+            );
         }
-
-        throw new Error('No valid authentication configuration provided');
+        return 'CAMPassport ' + passport;
     }
 
     /**
-     * Set up CAM (Cognos Access Manager) authentication
+     * Generate IBM IAM Cloud access token.
+     * Mirrors tm1py's _generate_ibm_iam_cloud_access_token.
      */
-    private async setupCamAuthentication(): Promise<void> {
-        if (!this.config.authUrl || !this.config.camPassport) {
-            throw new Error('CAM authentication requires authUrl and camPassport');
+    private async _generateIbmIamCloudAccessToken(): Promise<string> {
+        const { iamUrl, apiKey } = this.config;
+        if (!iamUrl || !apiKey) {
+            throw new Error("'iamUrl' and 'apiKey' must be provided to generate access token from IBM Cloud");
         }
-
-        try {
-            const authResponse = await axios.post(this.config.authUrl, {
-                parameters: [{
-                    name: 'CAMPassport',
-                    value: this.config.camPassport
-                }]
-            }, {
-                headers: {
-                    'Content-Type': 'application/json'
-                }
-            });
-
-            if (authResponse.data && authResponse.data.sessionId) {
-                this.sessionId = authResponse.data.sessionId;
-                this.axiosInstance.defaults.headers.common['TM1SessionId'] = this.sessionId;
-            } else {
-                throw new Error('CAM authentication failed: No session ID returned');
-            }
-        } catch (error) {
-            throw new Error(`CAM authentication failed: ${error}`);
+        const payload = `grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=${encodeURIComponent(apiKey)}`;
+        const headers = {
+            'Accept': 'application/json',
+            'Content-Type': 'application/x-www-form-urlencoded'
+        };
+        const response = await axios.post(iamUrl, payload, {
+            headers,
+            ...RestService.insecureAgentOption(this.config.verify)
+        });
+        if (!response.data?.access_token) {
+            throw new Error(`Failed to generate access_token from URL: '${iamUrl}'`);
         }
+        return response.data.access_token;
     }
 
     /**
-     * Set up CAM SSO authentication
+     * Generate CPD (Cloud Pak for Data) access token.
+     * Mirrors tm1py's _generate_cpd_access_token.
      */
-    private async setupCamSsoAuthentication(): Promise<void> {
-        if (!this.config.authUrl || !this.config.user || !this.config.password || !this.config.namespace) {
-            throw new Error('CAM SSO authentication requires authUrl, user, password, and namespace');
+    private async _generateCpdAccessToken(
+        credentials: { username: string; password: string }
+    ): Promise<string> {
+        const { cpdUrl } = this.config;
+        if (!cpdUrl) {
+            throw new Error("'cpdUrl' must be provided to authenticate via CPD/Cloud Pak for Data");
         }
+        const url = `${cpdUrl}/v1/preauth/signin`;
+        const headers = { 'Content-Type': 'application/json;charset=UTF-8' };
+        const response = await axios.post(url, credentials, {
+            headers,
+            ...RestService.insecureAgentOption(this.config.verify)
+        });
+        if (!response.data?.token) {
+            throw new Error(`Failed to generate CPD access token from URL: '${url}'`);
+        }
+        return response.data.token;
+    }
 
-        try {
-            const authPayload = {
-                username: this.config.user,
-                password: this.config.password,
-                namespace: this.config.namespace
-            };
-
-            const authResponse = await axios.post(this.config.authUrl, authPayload, {
-                headers: {
-                    'Content-Type': 'application/json'
-                }
-            });
-
-            if (authResponse.data && authResponse.data.token) {
-                this.axiosInstance.defaults.headers.common['Authorization'] = `Bearer ${authResponse.data.token}`;
-            } else if (authResponse.data && authResponse.data.sessionId) {
-                this.sessionId = authResponse.data.sessionId;
-                this.axiosInstance.defaults.headers.common['TM1SessionId'] = this.sessionId;
-            } else {
-                throw new Error('CAM SSO authentication failed: No token or session ID returned');
-            }
-        } catch (error) {
-            throw new Error(`CAM SSO authentication failed: ${error}`);
+    /**
+     * Authenticate with PA Proxy using a CPD JWT token.
+     * Mirrors tm1py's PA_PROXY flow in _start_session.
+     */
+    private async _authenticateWithPaProxy(jwt: string): Promise<void> {
+        const authRoot = this.resolveRoots().authRoot;
+        const headers = { 'Content-Type': 'application/x-www-form-urlencoded' };
+        const payload = `jwt=${jwt}`;
+        const response = await axios.post(authRoot, payload, {
+            headers,
+            ...RestService.insecureAgentOption(this.config.verify)
+        });
+        const setCookie = response.headers['set-cookie'];
+        const csrfValue = RestService.extractCookieValue(setCookie, 'ba-sso-csrf');
+        if (csrfValue) {
+            this.axiosInstance.defaults.headers.common['ba-sso-authenticity'] = csrfValue;
         }
+        this.parseSetCookieHeaders(setCookie);
     }
 
     /**
-     * Set up Service-to-Service authentication
+     * Authenticate Service-to-Service (v12).
+     * Mirrors tm1py's SERVICE_TO_SERVICE flow in _start_session:
+     * Uses Basic auth with applicationClientId:applicationClientSecret,
+     * then POSTs {"User": user} to the auth endpoint.
      */
-    private async setupServiceToServiceAuthentication(): Promise<void> {
-        if (!this.config.applicationClientId || !this.config.applicationClientSecret) {
-            throw new Error('Service-to-Service authentication requires applicationClientId and applicationClientSecret');
+    private async _authenticateServiceToService(): Promise<void> {
+        const { applicationClientId, applicationClientSecret, user } = this.config;
+        if (!applicationClientId || !applicationClientSecret) {
+            throw new Error(
+                'Service-to-Service authentication requires applicationClientId and applicationClientSecret'
+            );
         }
 
-        try {
-            const tokenEndpoint = this.config.authUrl || `${this.buildBaseUrl()}/oauth/token`;
+        // Guard: v11 and plain baseUrl topologies resolve authRoot to a metadata
+        // probe URL, not a token endpoint. Require explicit authUrl in those cases.
+        if (!this.config.authUrl) {
+            const topo = this.determineTopology();
+            const baseUrlIsV12 = topo === 'base_url'
+                && /api\/v1\/Databases/.test(this.config.baseUrl ?? '');
+            if (topo === 'v11' || (topo === 'base_url' && !baseUrlIsV12)) {
+                throw new Error(
+                    "'authUrl' is required for Service-to-Service authentication on v11 topology"
+                );
+            }
+        }
 
-            const tokenPayload = {
-                grant_type: 'client_credentials',
-                client_id: this.config.applicationClientId,
-                client_secret: this.config.applicationClientSecret
-            };
+        const authRoot = this.config.authUrl || this.resolveRoots().authRoot;
+        const basicAuth = Buffer.from(
+            `${applicationClientId}:${applicationClientSecret}`
+        ).toString('base64');
 
-            const tokenResponse = await axios.post(tokenEndpoint, tokenPayload, {
-                headers: {
-                    'Content-Type': 'application/x-www-form-urlencoded'
-                }
-            });
+        this.axiosInstance.defaults.headers.common['Authorization'] = `Basic ${basicAuth}`;
 
-            if (tokenResponse.data && tokenResponse.data.access_token) {
-                this.axiosInstance.defaults.headers.common['Authorization'] = `Bearer ${tokenResponse.data.access_token}`;
-            } else {
-                throw new Error('Service-to-Service authentication failed: No access token returned');
+        const response = await axios.post(
+            authRoot,
+            JSON.stringify({ User: user }),
+            {
+                headers: {
+                    ...RestService.HEADERS,
+                    'Authorization': `Basic ${basicAuth}`
+                },
+                ...RestService.insecureAgentOption(this.config.verify)
             }
-        } catch (error) {
-            throw new Error(`Service-to-Service authentication failed: ${error}`);
-        }
+        );
+
+        this.parseSetCookieHeaders(response.headers['set-cookie']);
     }
 
     /**
-     * Get the authentication mode being used
+     * Determine the authentication mode from config.
+     * Mirrors tm1py's _determine_auth_mode, using the URL topology as the
+     * primary discriminator for v12 modes.
      */
     public getAuthenticationMode(): AuthenticationMode {
-        if (this.config.accessToken) {
-            return AuthenticationMode.ACCESS_TOKEN;
-        }
-        if (this.config.apiKey) {
-            return this.config.user === 'apikey' ?
-                AuthenticationMode.IBM_CLOUD_API_KEY :
-                AuthenticationMode.BASIC_API_KEY;
-        }
-        if (this.config.authUrl && this.config.camPassport) {
-            return AuthenticationMode.CAM;
-        }
-        if (this.config.authUrl && this.config.user && this.config.password && this.config.namespace) {
-            return AuthenticationMode.CAM_SSO;
+        const topo = this.determineTopology();
+        const c = this.config;
+
+        switch (topo) {
+            case 'ibm_cloud':
+                return AuthenticationMode.IBM_CLOUD_API_KEY;
+            case 'pa_proxy':
+                return AuthenticationMode.PA_PROXY;
+            case 's2s':
+                return AuthenticationMode.SERVICE_TO_SERVICE;
+
+            case 'v11':
+            case 'base_url':
+            default: {
+                // v11 / base_url: check auth-specific config flags
+                if (c.accessToken) return AuthenticationMode.ACCESS_TOKEN;
+                if (c.apiKey) return AuthenticationMode.BASIC_API_KEY;
+                if (c.applicationClientId && c.applicationClientSecret) {
+                    return AuthenticationMode.SERVICE_TO_SERVICE;
+                }
+                if (c.camPassport) return AuthenticationMode.CAM;
+                if (c.gateway && c.namespace) return AuthenticationMode.CAM_SSO;
+                if (c.integratedLogin) return AuthenticationMode.WIA;
+                if (c.namespace) return AuthenticationMode.CAM;
+                return AuthenticationMode.BASIC;
+            }
         }
-        if (this.config.applicationClientId && this.config.applicationClientSecret) {
-            return AuthenticationMode.SERVICE_TO_SERVICE;
+    }
+
+    /**
+     * Set up authentication based on configuration.
+     * Mirrors tm1py's _start_session routing.
+     */
+    private async setupAuthentication(): Promise<void> {
+        const authMode = this.getAuthenticationMode();
+        const password = this.config.decodeB64 && this.config.password
+            ? RestService.b64_decode_password(this.config.password)
+            : this.config.password;
+
+        switch (authMode) {
+            case AuthenticationMode.ACCESS_TOKEN:
+                this.axiosInstance.defaults.headers.common['Authorization'] =
+                    `Bearer ${this.config.accessToken}`;
+                break;
+
+            case AuthenticationMode.BASIC_API_KEY:
+                if (this.config.user === 'apikey') {
+                    this.axiosInstance.defaults.headers.common['Authorization'] =
+                        RestService._buildAuthorizationTokenBasic('apikey', this.config.apiKey!);
+                } else {
+                    this.axiosInstance.defaults.headers.common['API-Key'] = this.config.apiKey!;
+                }
+                break;
+
+            case AuthenticationMode.IBM_CLOUD_API_KEY: {
+                const accessToken = await this._generateIbmIamCloudAccessToken();
+                this.axiosInstance.defaults.headers.common['Authorization'] =
+                    `Bearer ${accessToken}`;
+                break;
+            }
+
+            case AuthenticationMode.PA_PROXY: {
+                if (!this.config.user || !password) {
+                    throw new Error('PA Proxy authentication requires user and password');
+                }
+                const jwt = await this._generateCpdAccessToken({
+                    username: this.config.user,
+                    password
+                });
+                await this._authenticateWithPaProxy(jwt);
+                break;
+            }
+
+            case AuthenticationMode.SERVICE_TO_SERVICE:
+                await this._authenticateServiceToService();
+                break;
+
+            case AuthenticationMode.CAM_SSO: {
+                // CAM_SSO is only reached when gateway is set (see getAuthenticationMode)
+                const token = await RestService._buildAuthorizationTokenCamSso(
+                    this.config.gateway!,
+                    this.config.namespace!,
+                    this.config.verify
+                );
+                this.axiosInstance.defaults.headers.common['Authorization'] = token;
+                break;
+            }
+
+            case AuthenticationMode.CAM: {
+                if (this.config.camPassport) {
+                    this.axiosInstance.defaults.headers.common['Authorization'] =
+                        'CAMPassport ' + this.config.camPassport;
+                } else if (this.config.namespace && this.config.user && password) {
+                    this.axiosInstance.defaults.headers.common['Authorization'] =
+                        RestService._buildAuthorizationTokenCam(
+                            this.config.user, password, this.config.namespace
+                        );
+                } else {
+                    throw new Error(
+                        'CAM authentication requires either camPassport or user/password/namespace'
+                    );
+                }
+                break;
+            }
+
+            case AuthenticationMode.WIA:
+                throw new Error(
+                    'Windows Integrated Authentication (WIA) is not supported in Node.js. ' +
+                    'Use CAM or Basic authentication instead.'
+                );
+
+            case AuthenticationMode.BASIC:
+            default: {
+                if (!this.config.user || !password) {
+                    throw new Error('No valid authentication configuration provided');
+                }
+                this.axiosInstance.defaults.headers.common['Authorization'] =
+                    RestService._buildAuthorizationTokenBasic(this.config.user, password);
+                break;
+            }
         }
-        return AuthenticationMode.BASIC;
     }
 
     /**
@@ -513,10 +1194,10 @@ export class RestService {
     } {
         return {
             isConnected: this.isConnected,
-            sessionId: this.sessionId,
+            sessionId: this.getSessionCookieValue(),
             authMode: this.getAuthenticationMode(),
             baseUrl: this.buildBaseUrl(),
-            timeout: (this.config.timeout || 60) * 1000,
+            timeout: this._timeout,
             sandbox: this.sandboxName
         };
     }
@@ -618,14 +1299,17 @@ export class RestService {
      * Check if currently connected to TM1
      */
     public is_connected(): boolean {
-        return this.isConnected && !!this.sessionId;
+        return this.isConnected && (
+            !!this.getSessionCookieValue() ||
+            !!this.axiosInstance.defaults.headers.common['Authorization']
+        );
     }
 
     /**
      * Get the current session ID
      */
     public session_id(): string | undefined {
-        return this.sessionId;
+        return this.getSessionCookieValue();
     }
 
     /**
@@ -652,55 +1336,71 @@ export class RestService {
     }
 
     /**
-     * Check if current user is admin
+     * Fetch the active user's group names as a CaseAndSpaceInsensitiveSet so
+     * membership tests are case- and whitespace-insensitive (mirrors tm1py).
+     * Concurrent callers (e.g. Promise.all([is_admin(), is_data_admin(), ...]))
+     * coalesce onto a single in-flight request.
+     */
+    private fetchActiveUserGroupNames(): Promise<CaseAndSpaceInsensitiveSet> {
+        if (this._activeUserGroupsPromise) return this._activeUserGroupsPromise;
+
+        const clear = () => { this._activeUserGroupsPromise = undefined; };
+        const fetch = this.get('/ActiveUser/Groups').then(
+            (response) => {
+                clear();
+                const set = new CaseAndSpaceInsensitiveSet();
+                const value = response.data?.value ?? [];
+                for (const group of value) {
+                    if (group?.Name) set.add(group.Name);
+                }
+                return set;
+            },
+            (err) => { clear(); throw err; }
+        );
+
+        this._activeUserGroupsPromise = fetch;
+        return fetch;
+    }
+
+    /**
+     * Check if current user is admin. Result is cached after the first
+     * computation, and pre-populated when the configured user is ADMIN.
      */
     public async is_admin(): Promise<boolean> {
-        try {
-            const response = await this.get('/ActiveUser/Groups');
-            const groups = response.data.value || [];
-            return groups.some((g: any) => g.Name === 'ADMIN');
-        } catch (error) {
-            return false;
-        }
+        if (this._isAdmin !== undefined) return this._isAdmin;
+        const groups = await this.fetchActiveUserGroupNames();
+        this._isAdmin = groups.has('ADMIN');
+        return this._isAdmin;
     }
 
     /**
-     * Check if current user is data admin
+     * Check if current user is data admin (member of Admin or DataAdmin).
      */
     public async is_data_admin(): Promise<boolean> {
-        try {
-            const response = await this.get('/ActiveUser/Groups');
-            const groups = response.data.value || [];
-            return groups.some((g: any) => g.Name === 'ADMIN' || g.Name === 'DataAdmin');
-        } catch (error) {
-            return false;
-        }
+        if (this._isDataAdmin !== undefined) return this._isDataAdmin;
+        const groups = await this.fetchActiveUserGroupNames();
+        this._isDataAdmin = groups.has('Admin') || groups.has('DataAdmin');
+        return this._isDataAdmin;
     }
 
     /**
-     * Check if current user is ops admin
+     * Check if current user is ops admin (member of Admin or OperationsAdmin).
      */
     public async is_ops_admin(): Promise<boolean> {
-        try {
-            const response = await this.get('/ActiveUser/Groups');
-            const groups = response.data.value || [];
-            return groups.some((g: any) => g.Name === 'ADMIN' || g.Name === 'OperationsAdmin');
-        } catch (error) {
-            return false;
-        }
+        if (this._isOpsAdmin !== undefined) return this._isOpsAdmin;
+        const groups = await this.fetchActiveUserGroupNames();
+        this._isOpsAdmin = groups.has('Admin') || groups.has('OperationsAdmin');
+        return this._isOpsAdmin;
     }
 
     /**
-     * Check if current user is security admin
+     * Check if current user is security admin (member of Admin or SecurityAdmin).
      */
     public async is_security_admin(): Promise<boolean> {
-        try {
-            const response = await this.get('/ActiveUser/Groups');
-            const groups = response.data.value || [];
-            return groups.some((g: any) => g.Name === 'ADMIN' || g.Name === 'SecurityAdmin');
-        } catch (error) {
-            return false;
-        }
+        if (this._isSecurityAdmin !== undefined) return this._isSecurityAdmin;
+        const groups = await this.fetchActiveUserGroupNames();
+        this._isSecurityAdmin = groups.has('Admin') || groups.has('SecurityAdmin');
+        return this._isSecurityAdmin;
     }
 
     /**
@@ -734,82 +1434,124 @@ export class RestService {
         return headers;
     }
 
+    /**
+     * Insert `tm1.compact=v0` into the Accept header (after the
+     * `application/json` segment) and return the previous header value.
+     * Mirrors tm1py's add_compact_json_header.
+     */
+    public add_compact_json_header(): string {
+        const original = (this.axiosInstance.defaults.headers.common['Accept'] as string | undefined) ?? '';
+        const parts = original.split(';');
+        // Insertion point matters: must come immediately after `application/json`
+        parts.splice(1, 0, 'tm1.compact=v0');
+        this.axiosInstance.defaults.headers.common['Accept'] = parts.join(';');
+        return original;
+    }
+
+    /**
+     * Decode a Base64-encoded password to its UTF-8 plaintext form
+     * (mirrors tm1py's b64_decode_password).
+     */
+    public static b64_decode_password(encryptedPassword: string): string {
+        return Buffer.from(encryptedPassword, 'base64').toString('utf-8');
+    }
+
+    /**
+     * Coerce a boolean/number/string config value to a boolean. Strings
+     * are stripped of whitespace and lowercased before comparison with
+     * `'true'` (mirrors tm1py's translate_to_boolean).
+     */
+    public static translate_to_boolean(value: unknown): boolean {
+        if (typeof value === 'boolean') return value;
+        if (typeof value === 'number') return Boolean(value);
+        if (typeof value === 'string') {
+            return value.replace(/\s+/g, '').toLowerCase() === 'true';
+        }
+        throw new Error(
+            `Invalid argument: '${String(value)}'. Must be type 'boolean', 'number', or 'string'`
+        );
+    }
+
     /**
      * Cancel an async operation by ID
      */
     public async cancel_async_operation(async_id: string): Promise<void> {
-        try {
-            await this.post(`/AsyncOperations('${async_id}')/tm1.Cancel`);
-        } catch (error) {
-            throw new TM1RestException(`Failed to cancel async operation ${async_id}: ${error}`);
-        }
+        await this.delete(formatUrl("/_async('{}')", async_id), { asyncRequestsMode: false });
     }
 
     /**
      * Retrieve async operation response
      */
-    public async retrieve_async_response(async_id: string): Promise<any> {
-        try {
-            const response = await this.get(`/AsyncOperations('${async_id}')`);
-            // Axios treats 2xx as success, but 202 means the operation is still running
-            if (response.status === 202) {
-                throw new TM1RestException('Async operation still running', 202, response);
-            }
-            return response.data;
-        } catch (error: any) {
-            if (error instanceof TM1RestException) {
-                throw error;
-            }
-            const status = error?.status ?? error?.response?.status;
-            throw new TM1RestException(
-                `Failed to retrieve async response ${async_id}: ${error}`,
-                status,
-                error?.response
-            );
-        }
+    public async retrieve_async_response(async_id: string): Promise<AxiosResponse> {
+        // tm1py's retrieve_async_response returns the raw response without
+        // raising on non-2xx because its caller (_poll_async_response) gates
+        // on status_code in [200, 201]. Mirror that: accept all statuses so
+        // transient 404s (resource not yet materialized) or 202s (still
+        // running) flow through to the polling loop rather than aborting it.
+        return this.get(formatUrl("/_async('{}')", async_id), {
+            asyncRequestsMode: false,
+            verifyResponse: false,
+            validateStatus: () => true
+        }) as Promise<AxiosResponse>;
     }
 
     /**
-     * Get async operation status
+     * TM1 v12 returns completed async results with HTTP 200 and encodes
+     * the true operation status in the `asyncresult` header (e.g.
+     * "500 Internal Server Error"). Mirror tm1py's
+     * `_transform_async_response` by throwing on any embedded non-2xx
+     * status so callers are not handed a 500 as "success".
      */
-    public async get_async_operation_status(async_id: string): Promise<string> {
-        try {
-            const response = await this.get(`/AsyncOperations('${async_id}')/Status/$value`);
-            return response.data;
-        } catch (error) {
-            throw new TM1RestException(`Failed to get async operation status ${async_id}: ${error}`);
-        }
+    private verifyAsyncResultHeader(response: AxiosResponse): void {
+        const headerValue = response.headers?.['asyncresult'];
+        if (typeof headerValue !== 'string') return;
+        const embeddedStatus = parseInt(headerValue.trim().split(/\s+/)[0], 10);
+        if (Number.isNaN(embeddedStatus)) return;
+        if (embeddedStatus >= 200 && embeddedStatus < 300) return;
+        throw new TM1RestException(
+            `Async operation failed with status ${headerValue}`,
+            embeddedStatus,
+            response
+        );
     }
 
     /**
-     * Wait for async operation to complete
+     * Wait for async operation to complete using a fixed polling cadence.
+     *
+     * Unlike the internal dispatcher's {@link waitTimeGenerator} (capped
+     * exponential backoff), this public helper polls every
+     * {@link poll_interval_seconds} seconds so existing callers who tuned
+     * the cadence keep their original behavior.
      */
     public async wait_for_async_operation(
         async_id: string,
         timeout_seconds: number = 300,
-        poll_interval_seconds: number = 1
+        poll_interval_seconds: number = 1,
+        cancel_at_timeout: boolean = false
     ): Promise<any> {
-        const start_time = Date.now();
-        const timeout_ms = timeout_seconds * 1000;
-        const poll_interval_ms = poll_interval_seconds * 1000;
+        const deadline = Date.now() + timeout_seconds * 1000;
 
-        while (Date.now() - start_time < timeout_ms) {
-            const status = await this.get_async_operation_status(async_id);
-
-            if (status === 'Completed' || status === 'CompletedSuccessfully') {
-                return await this.retrieve_async_response(async_id);
+        while (Date.now() < deadline) {
+            const response = await this.retrieve_async_response(async_id);
+            if (response.status === 200 || response.status === 201) {
+                this.verifyAsyncResultHeader(response);
+                return response.data;
             }
+            await new Promise(resolve => setTimeout(resolve, poll_interval_seconds * 1000));
+        }
 
-            if (status === 'Failed' || status === 'CompletedWithError') {
-                const response = await this.retrieve_async_response(async_id);
-                throw new TM1RestException(`Async operation failed: ${JSON.stringify(response)}`);
+        if (cancel_at_timeout) {
+            try {
+                await this.cancel_async_operation(async_id);
+            } catch (cancelError) {
+                console.warn(`Failed to cancel async operation ${async_id} at timeout:`, cancelError);
             }
-
-            // Wait before polling again
-            await new Promise(resolve => setTimeout(resolve, poll_interval_ms));
         }
 
-        throw new TM1TimeoutException(`Async operation ${async_id} timed out after ${timeout_seconds} seconds`);
+        throw new TM1TimeoutException(
+            `Async operation ${async_id} timed out after ${timeout_seconds} seconds`,
+            timeout_seconds
+        );
     }
 
     /**
@@ -885,4 +1627,4 @@ export class RestService {
             throw new TM1RestException(`Failed to get data directory: ${error}`);
         }
     }
-}
+}