@controlium/utils 1.0.2-alpha.2 → 1.0.2-alpha.3

package/dist/esm/apiUtils/APIUtils.js

@@ -0,0 +1,226 @@
+import { Agent, Headers, ProxyAgent, fetch } from 'undici';
+import { Log, LogLevels, Utils } from '../index';
+export class EAAPIUtils {
+    /**
+     * Verify if HTTP server listening
+     * @param url
+     * Protocol and domain of HTTP Server (IE. http://localhost:4200)
+     * @param timeoutMS
+     * Maximum time (in Milliseconds to wait for response)
+     * @returns boolean
+     * true if Server alive and responding
+     * false if no response with timeout
+     * @abstract
+     * A fetch 'HEAD' request is used to obtain a header from the server.  If no
+     * response then it is assumed nothing listening
+     */
+    static async isWebServerListening(url, timeoutMS) {
+        try {
+            await fetch(url, { method: 'HEAD', signal: AbortSignal.timeout(timeoutMS) });
+            return true;
+        }
+        catch (err) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (err && typeof err === 'object' && 'errors' in err && Array.isArray(err.errors)) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const agg = err;
+                for (const e of agg.errors) {
+                    Log.writeLine(LogLevels.FrameworkInformation, `Error:\n${e.code} (${e.message})`);
+                    if (e.message.includes('ECONNREFUSED')) {
+                        return false;
+                    }
+                }
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                Log.writeLine(LogLevels.FrameworkInformation, `Error:\n${err['code'] ?? 'no code'} (${err.message})`);
+                if (err.message.includes('ECONNREFUSED')) {
+                    return false;
+                }
+            }
+            // We are only interested in if ECONNREFUSED.  All else means there be _something_ listening...
+            return true;
+        }
+    }
+    /**
+     * Waits for coherent response from given HTTP url
+     * @param url
+     * Protocol and domain of HTTP Server (IE. http://localhost:4200)
+     * @param maxSecondsToWait
+     * Maximum time to wait (in seconds) for a coherent response from given url
+     * @param maxResponseTimeMS (optional, default 1000)
+     * Maximum time for a response (in milliseconds) to a http HEAD request
+     * @returns
+     * Promise of boolean
+     * true - Webserver on given url is alive and responding
+     * false - No response from given url within timeout.
+     * @abstract
+     * URL is polled
+     */
+    static async waitForWebServerListening(url, maxSecondsToWait, { maxResponseTimeMS = 1000 } = {}) {
+        const pollIntervalMs = 500;
+        Log.writeLine(LogLevels.TestInformation, `Waiting for AUT at ${url} to become available (overall timeout: ${maxSecondsToWait} seconds)...`);
+        const startTime = Date.now();
+        let elapsed = 0;
+        while (!await this.isWebServerListening(url, maxResponseTimeMS)) {
+            const oldElapsed = elapsed;
+            elapsed = Math.floor((Date.now() - startTime) / 1000);
+            if (elapsed >= maxSecondsToWait) {
+                Log.writeLine(LogLevels.Error, `Timeout reached: Server did not respond within ${maxSecondsToWait} seconds.`);
+                return false;
+            }
+            // Stick a confidence message out every 4 seconds
+            if ((oldElapsed != elapsed) && (elapsed % 4 == 0)) {
+                Log.writeLine(LogLevels.TestInformation, `Waiting for AUT: Waited ${elapsed} seconds so far (Max wait ${maxSecondsToWait} seconds)`);
+            }
+            await Utils.sleep(pollIntervalMs, false);
+        }
+        return true;
+    }
+    /**
+     * Perform a single HTTP/HTTPS operation based on the details of the Request envelope
+     * @param httpRequest - Details of Request to be performed
+     * @returns Full response
+     * @throws Error if there is any fail that results in a Response not being received.
+     * The caller-supplied timeout (or the default 10s) is enforced as a hard failsafe via AbortSignal.
+     */
+    static async performHTTPOperation(httpRequest) {
+        const API_DEFAULT_TIMEOUT = 10000;
+        let dispatcher;
+        try {
+            if (Utils.isNullOrUndefined(httpRequest.timeout)) {
+                Log.writeLine(LogLevels.FrameworkDebug, `No API Timeout defined.  Setting to ${Utils.msToHMS(API_DEFAULT_TIMEOUT)}`);
+                httpRequest.timeout = API_DEFAULT_TIMEOUT;
+            }
+            const builtUrl = this.buildURL(httpRequest);
+            Log.writeLine(LogLevels.FrameworkInformation, `Built URL: [${builtUrl}]`);
+            dispatcher = this.buildDispatcher(httpRequest);
+            const headers = this.buildHeaders(httpRequest.headers);
+            this.doRequestLogging(httpRequest.method ?? 'GET', builtUrl, headers, httpRequest.body);
+            const body = Utils.isNullOrUndefined(httpRequest.body)
+                ? undefined
+                : typeof httpRequest.body === 'string'
+                    ? httpRequest.body
+                    : JSON.stringify(httpRequest.body);
+            const fetchResponse = await fetch(builtUrl, {
+                method: httpRequest.method ?? 'GET',
+                headers,
+                body,
+                redirect: 'follow',
+                signal: AbortSignal.timeout(httpRequest.timeout),
+                dispatcher,
+            });
+            const responseBody = await fetchResponse.text();
+            this.doResponseLogging(fetchResponse.status, fetchResponse.statusText, responseBody);
+            return {
+                status: fetchResponse.status,
+                statusMessage: fetchResponse.statusText,
+                body: responseBody,
+            };
+        }
+        catch (err) {
+            Log.writeLine(LogLevels.Error, `HTTP OPERATION ERROR: ${err}`);
+            throw err;
+        }
+        finally {
+            await dispatcher?.close();
+        }
+    }
+    static buildURL(httpRequest) {
+        let builtUrl = httpRequest.protocol;
+        builtUrl += '://';
+        builtUrl += httpRequest.host.endsWith('/')
+            ? httpRequest.host.substring(0, httpRequest.host.length - 1)
+            : httpRequest.host;
+        builtUrl += '/';
+        builtUrl += httpRequest.resourcePath.startsWith('/')
+            ? httpRequest.resourcePath.substring(1, httpRequest.resourcePath.length)
+            : httpRequest.resourcePath;
+        if (!Utils.isNullOrUndefined(httpRequest.queryString)) {
+            const queryString = httpRequest.queryString;
+            builtUrl += '?';
+            builtUrl += queryString.startsWith('?')
+                ? queryString.substring(1, queryString.length)
+                : queryString;
+        }
+        return builtUrl;
+    }
+    static buildDispatcher(httpRequest) {
+        if (!Utils.isNullOrUndefined(httpRequest.proxy)) {
+            const proxyAgent = new ProxyAgent({
+                uri: httpRequest.proxy,
+                connect: { timeout: httpRequest.timeout, rejectUnauthorized: false },
+            });
+            Log.writeLine(LogLevels.FrameworkInformation, `Proxy configured: [${httpRequest.proxy}]`);
+            return proxyAgent;
+        }
+        return new Agent({ connect: { timeout: httpRequest.timeout } });
+    }
+    static buildHeaders(httpHeaders) {
+        const headers = new Headers();
+        for (const [key, value] of Object.entries(httpHeaders)) {
+            if (!Utils.isNull(value)) {
+                headers.append(key, String(value));
+            }
+        }
+        return headers;
+    }
+    static doRequestLogging(method, url, headers, body) {
+        Log.writeLine(LogLevels.FrameworkInformation, `HTTP [${method}] to [${url}]:-`);
+        Log.writeLine(LogLevels.FrameworkInformation, '  Headers;');
+        let headersStr = '';
+        headers.forEach((value, key) => {
+            headersStr += `${headersStr === '' ? '' : '\n'}    "${key}": "${value}"`;
+        });
+        Log.writeLine(LogLevels.FrameworkInformation, headersStr === '' ? '    <No headers!>' : headersStr);
+        if (Log.loggingLevel >= LogLevels.FrameworkDebug) {
+            Log.writeLine(LogLevels.FrameworkDebug, '  Request (full body);');
+            const bodyStr = Utils.isNullOrUndefined(body)
+                ? '    <No body!>'
+                : typeof body === 'string' ? body : JSON.stringify(body, null, 2);
+            Log.writeLine(LogLevels.FrameworkDebug, bodyStr, { maxLines: 1024, suppressMultilinePreamble: true });
+        }
+        else {
+            Log.writeLine(LogLevels.FrameworkInformation, '  Body;');
+            const bodyStr = Utils.isNullOrUndefined(body)
+                ? ''
+                : typeof body === 'string' ? body : JSON.stringify(body);
+            if (!bodyStr) {
+                Log.writeLine(LogLevels.FrameworkInformation, '    <No body!>');
+            }
+            else {
+                let indented = '';
+                bodyStr.split(/\r?\n/).forEach((line) => {
+                    indented += `${indented === '' ? '' : '\n'}    ${line}`;
+                });
+                Log.writeLine(LogLevels.FrameworkInformation, indented);
+            }
+        }
+    }
+    static doResponseLogging(status, statusText, body) {
+        Log.writeLine(LogLevels.FrameworkInformation, 'HTTP Response:-');
+        Log.writeLine(LogLevels.FrameworkInformation, `  Status [${status}] - [${statusText}]`);
+        Log.writeLine(LogLevels.FrameworkInformation, '  Body;');
+        let indented = '';
+        if (body) {
+            body.split(/\r?\n/).forEach((line) => {
+                indented += `${indented === '' ? '' : '\n'}    ${line}`;
+            });
+        }
+        Log.writeLine(LogLevels.FrameworkInformation, indented === '' ? '    <No body!>' : indented);
+        Log.writeLine(LogLevels.FrameworkInformation, 'HTTP Response end');
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-namespace
+(function (EAAPIUtils) {
+    /**
+     * Generic Http call methods
+     */
+    let HttpMethods;
+    (function (HttpMethods) {
+        HttpMethods["POST"] = "POST";
+        HttpMethods["GET"] = "GET";
+        HttpMethods["PUT"] = "PUT";
+    })(HttpMethods = EAAPIUtils.HttpMethods || (EAAPIUtils.HttpMethods = {}));
+    EAAPIUtils.APPLICATION_JSON = 'application/json';
+})(EAAPIUtils || (EAAPIUtils = {}));

package/dist/esm/mock/mock.js

@@ -1,13 +1,13 @@
+import { STATUS_CODES } from 'node:http';
 import { randomUUID } from 'node:crypto';
-import { JSONPath } from 'jsonpath-plus';
 import { Utils } from '../utils/utils';
-import { Log, LogLevels } from '..';
+import { JsonUtils, Log, Logger, LogLevels } from '..';
 /**
  * Static HTTP request interception and mocking utility for test suites.
  *
  * `Mock` is designed to sit between a test framework's network interceptor
  * (e.g. Playwright's `page.route`) and the application under test. Every
- * outgoing request from the AUT is forwarded to {@link Mock.intercept}, which
+ * outgoing request from the AUT must be forwarded to {@link Mock.processInterceptedRequest}, which
  * decides how to handle it based on the registered listeners.
  *
  * **Default-deny**: any request that does not match a listener is blocked and
@@ -26,7 +26,7 @@ import { Log, LogLevels } from '..';
  *
  * `Mock` runs in the same process as the test framework. When a `passthrough`
  * listener matches, `Mock` fetches the real response itself and returns it
- * directly. {@link Mock.intercept} always resolves to a {@link Mock.InterceptResult}
+ * directly. {@link Mock.processInterceptedRequest} always resolves to a {@link Mock.InterceptResult}
  * with `action: 'fulfill'` or `action: 'block'`.
  *
  * ### Delegate mode
@@ -34,7 +34,7 @@ import { Log, LogLevels } from '..';
  * Enable with `Mock.delegateMode = true` when `Mock` is hosted in a remote
  * server (e.g. a mock proxy) and the caller — not `Mock` — is better placed
  * to perform the real network fetch. In this mode, when a `passthrough`
- * listener matches, {@link Mock.intercept} returns `action: 'passthrough'`
+ * listener matches, {@link Mock.processInterceptedRequest} returns `action: 'passthrough'`
  * plus a `correlationId`. The caller fetches the real response and reports it
  * back via {@link Mock.completePassthrough}, allowing `Mock` to record the
  * full transaction. Use {@link Mock.getPendingTransactions} to detect
@@ -81,7 +81,7 @@ export class Mock {
     // ── Configuration ──────────────────────────────────────────────────────────
     /**
      * When `true`, passthrough requests are delegated to the caller rather than
-     * fetched by `Mock` itself. {@link Mock.intercept} returns
+     * fetched by `Mock` itself. {@link Mock.processInterceptedRequest} returns
      * `action: 'passthrough'` with a `correlationId` for the caller to use when
      * reporting the real response back via {@link Mock.completePassthrough}.
      *
@@ -163,10 +163,10 @@ export class Mock {
                 Mock.throwError('addListener', `[matchers[${index}]] must not be empty`);
             }
             try {
-                JSONPath({ path: matcher, json: {}, wrap: true });
+                JsonUtils.getMatchingJSONPropertyCount({}, matcher);
             }
             catch (e) {
-                Mock.throwError('addListener', `[matchers[${index}]] is not valid JSONPath syntax: "${matcher}". ${e.message}`);
+                Mock.throwError('addListener', `Matcher item [${index}] is not valid JSONPath syntax: "${matcher}". ${e.message}`);
             }
         });
         if (action !== 'block' && action !== 'passthrough') {
@@ -180,6 +180,10 @@ export class Mock {
             if (response.headers !== undefined && (typeof response.headers !== 'object' || response.headers === null || Array.isArray(response.headers))) {
                 Mock.throwError('addListener', `[action.headers] must be a plain object if provided`);
             }
+            if (Utils.isUndefined(action.statusText))
+                action.statusText = STATUS_CODES[action.status] ?? undefined;
+            else if (action.statusText === '_undefined')
+                action.statusText = undefined;
         }
         Utils.assertType(delayMs, 'number', 'addListener', 'delayMs');
         if (!Number.isFinite(delayMs) || delayMs < 0) {
@@ -250,7 +254,7 @@ export class Mock {
      * | Matched → block | `'block'` | `'blocked'` |
      * | No listener matched | `'block'` | `'unmatched'` |
      *
-     * @param request - The intercepted request. Must be a non-null object with
+     * @param interceptedRequest - The intercepted request. Must be a non-null object with
      *   non-empty `url` and `method` string properties.
      *
      * @returns A promise resolving to a {@link Mock.InterceptResult}.
@@ -270,24 +274,24 @@ export class Mock {
      *   abortRequest();
      * }
      */
-    static async intercept(request) {
-        if (request === null || request === undefined || typeof request !== 'object' || Array.isArray(request)) {
-            Mock.throwError('intercept', `[request] must be a non-null object, got [${request === null ? 'null' : typeof request}]`);
+    static async processInterceptedRequest(interceptedRequest) {
+        if (interceptedRequest === null || interceptedRequest === undefined || typeof interceptedRequest !== 'object' || Array.isArray(interceptedRequest)) {
+            Mock.throwError('intercept', `[request] must be a non-null object, got [${interceptedRequest === null ? 'null' : typeof interceptedRequest}]`);
         }
-        if (typeof request.url !== 'string' || request.url.trim().length === 0) {
-            Mock.throwError('intercept', `[request.url] must be a non-empty string, got [${typeof request.url}]`);
+        if (typeof interceptedRequest.url !== 'string' || interceptedRequest.url.trim().length === 0) {
+            Mock.throwError('intercept', `[request.url] must be a non-empty string, got [${typeof interceptedRequest.url}]`);
         }
-        if (typeof request.method !== 'string' || request.method.trim().length === 0) {
-            Mock.throwError('intercept', `[request.method] must be a non-empty string, got [${typeof request.method}]`);
+        if (typeof interceptedRequest.method !== 'string' || interceptedRequest.method.trim().length === 0) {
+            Mock.throwError('intercept', `[request.method] must be a non-empty string, got [${typeof interceptedRequest.method}]`);
         }
-        if (request.headers !== undefined && request.headers !== null && (typeof request.headers !== 'object' || Array.isArray(request.headers))) {
+        if (interceptedRequest.headers !== undefined && interceptedRequest.headers !== null && (typeof interceptedRequest.headers !== 'object' || Array.isArray(interceptedRequest.headers))) {
             Mock.throwError('intercept', `[request.headers] must be a plain object if provided`);
         }
-        Log.writeLine(LogLevels.FrameworkDebug, `Mock.intercept: ${request.method} ${request.url}`);
-        const listener = Mock.findMatch(request);
+        Log.writeLine(LogLevels.FrameworkDebug, `Mock.intercept: ${interceptedRequest.method} ${interceptedRequest.url}`);
+        const listener = Mock.findMatch(interceptedRequest);
         if (!listener) {
             Log.writeLine(LogLevels.FrameworkDebug, `Mock.intercept: no listener matched — blocking`);
-            Mock.record({ type: 'unmatched', request });
+            Mock.record({ type: 'unmatched', request: interceptedRequest });
             return { action: 'block' };
         }
         Log.writeLine(LogLevels.FrameworkDebug, `Mock.intercept: matched listener <${listener.name}>`);
@@ -297,7 +301,7 @@ export class Mock {
         }
         if (listener.action === 'block') {
             Log.writeLine(LogLevels.FrameworkDebug, `Mock.intercept: blocking request`);
-            Mock.record({ type: 'blocked', listenerName: listener.name, request });
+            Mock.record({ type: 'blocked', listenerName: listener.name, request: interceptedRequest });
             return { action: 'block' };
         }
         if (listener.action === 'passthrough') {
@@ -308,18 +312,18 @@ export class Mock {
                     correlationId,
                     timestamp: new Date(),
                     listenerName: listener.name,
-                    request,
+                    request: interceptedRequest,
                 });
                 return { action: 'passthrough', correlationId };
             }
             Log.writeLine(LogLevels.FrameworkDebug, `Mock.intercept: passing through to real endpoint`);
-            const response = await Mock.fetchReal(request);
-            Mock.record({ type: 'passthrough', listenerName: listener.name, request, response });
+            const response = await Mock.fetchReal(interceptedRequest);
+            Mock.record({ type: 'passthrough', listenerName: listener.name, request: interceptedRequest, response });
             return { action: 'fulfill', response };
         }
         const response = listener.action;
         Log.writeLine(LogLevels.FrameworkDebug, `Mock.intercept: returning mocked response (status ${response.status})`);
-        Mock.record({ type: 'mocked', listenerName: listener.name, request, response });
+        Mock.record({ type: 'mocked', listenerName: listener.name, request: interceptedRequest, response });
         return { action: 'fulfill', response };
     }
     /**
@@ -327,10 +331,10 @@ export class Mock {
      * fetched. Records the full transaction and removes the pending entry.
      *
      * Only relevant when {@link Mock.delegateMode} is `true`. The `correlationId`
-     * must match one previously returned by {@link Mock.intercept}.
+     * must match one previously returned by {@link Mock.processInterceptedRequest}.
      *
      * @param correlationId - The UUID returned in the `action: 'passthrough'`
-     *   result from {@link Mock.intercept}. Must be a non-empty string that
+     *   result from {@link Mock.processInterceptedRequest}. Must be a non-empty string that
      *   matches a pending transaction.
      *
      * @param response - The real response the caller received from the endpoint.
@@ -442,20 +446,30 @@ export class Mock {
         throw new Error(errorText);
     }
     static findMatch(request) {
+        Logger.writeLine(LogLevels.FrameworkInformation, `Checking if any listeners for [${request.url} (${request.method})]`);
         for (const listener of Mock.listeners.values()) {
             try {
-                const allMatch = listener.matchers.every((path) => {
+                const allMatch = listener.matchers.every((matcher) => {
                     try {
-                        const results = JSONPath({ path, json: request, wrap: true });
-                        return Array.isArray(results) && results.length > 0;
+                        const x = JSON.stringify(request, null, 2);
+                        Logger.writeLine(LogLevels.TestInformation, x);
+                        const matched = JsonUtils.getMatchingJSONPropertyCount([request], matcher) > 0;
+                        if (matched) {
+                            Logger.writeLine(LogLevels.FrameworkDebug, `Matched on [${matcher}]`);
+                            return true;
+                        }
+                        return false;
                     }
                     catch (e) {
-                        Log.writeLine(LogLevels.Warning, `Mock: JSONPath evaluation error in listener <${listener.name}> for path "${path}": ${e.message} — treating as non-match`);
+                        Log.writeLine(LogLevels.Warning, `Mock: JSONPath evaluation error in listener <${listener.name}> for path "${matcher}": ${e.message} — treating as non-match`);
                         return false;
                     }
                 });
                 if (allMatch)
                     return listener;
+                else {
+                    Logger.writeLine(LogLevels.FrameworkDebug, 'No matches');
+                }
             }
             catch (e) {
                 Log.writeLine(LogLevels.Warning, `Mock: Unexpected error evaluating listener <${listener.name}>: ${e.message} — skipping`);

package/dist/esm/utils/utils.js

@@ -2,7 +2,8 @@ import { exec, spawn } from 'child_process';
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import path from "path";
 import { decodeHTML } from "entities";
-import { decode as jwtDecode, sign as jwtSign } from "jsonwebtoken";
+import { createRequire } from 'module';
+const { sign: jwtSign, decode: jwtDecode } = createRequire(import.meta.url)('jsonwebtoken');
 import psTree from "ps-tree";
 // import { Detokeniser } from "./Detokeniser"; Claude, just masking this out for now...
 import { JsonUtils } from "../index";
@@ -98,7 +99,7 @@ export class Utils {
             return true;
         }
     }
-    /**
+    /**2
      * Safely checks if a value is `null`.
      *
      * @param obj - Value to check.

package/dist/types/apiUtils/APIUtils.d.ts

@@ -0,0 +1,90 @@
+export declare class EAAPIUtils {
+    /**
+     * Verify if HTTP server listening
+     * @param url
+     * Protocol and domain of HTTP Server (IE. http://localhost:4200)
+     * @param timeoutMS
+     * Maximum time (in Milliseconds to wait for response)
+     * @returns boolean
+     * true if Server alive and responding
+     * false if no response with timeout
+     * @abstract
+     * A fetch 'HEAD' request is used to obtain a header from the server.  If no
+     * response then it is assumed nothing listening
+     */
+    static isWebServerListening(url: string, timeoutMS: number): Promise<boolean>;
+    /**
+     * Waits for coherent response from given HTTP url
+     * @param url
+     * Protocol and domain of HTTP Server (IE. http://localhost:4200)
+     * @param maxSecondsToWait
+     * Maximum time to wait (in seconds) for a coherent response from given url
+     * @param maxResponseTimeMS (optional, default 1000)
+     * Maximum time for a response (in milliseconds) to a http HEAD request
+     * @returns
+     * Promise of boolean
+     * true - Webserver on given url is alive and responding
+     * false - No response from given url within timeout.
+     * @abstract
+     * URL is polled
+     */
+    static waitForWebServerListening(url: string, maxSecondsToWait: number, { maxResponseTimeMS }?: {
+        maxResponseTimeMS?: number;
+    }): Promise<boolean>;
+    /**
+     * Perform a single HTTP/HTTPS operation based on the details of the Request envelope
+     * @param httpRequest - Details of Request to be performed
+     * @returns Full response
+     * @throws Error if there is any fail that results in a Response not being received.
+     * The caller-supplied timeout (or the default 10s) is enforced as a hard failsafe via AbortSignal.
+     */
+    static performHTTPOperation(httpRequest: EAAPIUtils.HTTPRequest): Promise<EAAPIUtils.HTTPResponse>;
+    private static buildURL;
+    private static buildDispatcher;
+    private static buildHeaders;
+    private static doRequestLogging;
+    private static doResponseLogging;
+}
+export declare namespace EAAPIUtils {
+    /**
+     * Generic HTTP call Header items
+     */
+    type HTTPHeaders = {
+        [key: string]: string | string[] | number | boolean | null;
+    };
+    /**
+     * Generic HTTP call Request envelope
+     */
+    type HTTPRequest = {
+        proxy?: string;
+        method?: string;
+        protocol: 'http' | 'https';
+        host: string;
+        resourcePath: string;
+        queryString?: string;
+        headers: HTTPHeaders;
+        body?: string | object;
+        timeout?: number;
+    };
+    /**
+     * Generic Http call methods
+     */
+    enum HttpMethods {
+        POST = "POST",
+        GET = "GET",
+        PUT = "PUT"
+    }
+    const APPLICATION_JSON = "application/json";
+    /**
+     * Generic HTTP call Response envelope
+     */
+    type HTTPResponse = {
+        status: number;
+        statusMessage: string;
+        body: string;
+    };
+    type HTTPInteraction = {
+        request: HTTPRequest;
+        response: HTTPResponse;
+    };
+}

package/dist/types/mock/mock.d.ts

@@ -3,7 +3,7 @@
  *
  * `Mock` is designed to sit between a test framework's network interceptor
  * (e.g. Playwright's `page.route`) and the application under test. Every
- * outgoing request from the AUT is forwarded to {@link Mock.intercept}, which
+ * outgoing request from the AUT must be forwarded to {@link Mock.processInterceptedRequest}, which
  * decides how to handle it based on the registered listeners.
  *
  * **Default-deny**: any request that does not match a listener is blocked and
@@ -22,7 +22,7 @@
  *
  * `Mock` runs in the same process as the test framework. When a `passthrough`
  * listener matches, `Mock` fetches the real response itself and returns it
- * directly. {@link Mock.intercept} always resolves to a {@link Mock.InterceptResult}
+ * directly. {@link Mock.processInterceptedRequest} always resolves to a {@link Mock.InterceptResult}
  * with `action: 'fulfill'` or `action: 'block'`.
  *
  * ### Delegate mode
@@ -30,7 +30,7 @@
  * Enable with `Mock.delegateMode = true` when `Mock` is hosted in a remote
  * server (e.g. a mock proxy) and the caller — not `Mock` — is better placed
  * to perform the real network fetch. In this mode, when a `passthrough`
- * listener matches, {@link Mock.intercept} returns `action: 'passthrough'`
+ * listener matches, {@link Mock.processInterceptedRequest} returns `action: 'passthrough'`
  * plus a `correlationId`. The caller fetches the real response and reports it
  * back via {@link Mock.completePassthrough}, allowing `Mock` to record the
  * full transaction. Use {@link Mock.getPendingTransactions} to detect
@@ -81,7 +81,7 @@ export declare class Mock {
     private static _delegateMode;
     /**
      * When `true`, passthrough requests are delegated to the caller rather than
-     * fetched by `Mock` itself. {@link Mock.intercept} returns
+     * fetched by `Mock` itself. {@link Mock.processInterceptedRequest} returns
      * `action: 'passthrough'` with a `correlationId` for the caller to use when
      * reporting the real response back via {@link Mock.completePassthrough}.
      *
@@ -176,7 +176,7 @@ export declare class Mock {
      * | Matched → block | `'block'` | `'blocked'` |
      * | No listener matched | `'block'` | `'unmatched'` |
      *
-     * @param request - The intercepted request. Must be a non-null object with
+     * @param interceptedRequest - The intercepted request. Must be a non-null object with
      *   non-empty `url` and `method` string properties.
      *
      * @returns A promise resolving to a {@link Mock.InterceptResult}.
@@ -196,16 +196,16 @@ export declare class Mock {
      *   abortRequest();
      * }
      */
-    static intercept(request: Mock.Request): Promise<Mock.InterceptResult>;
+    static processInterceptedRequest(interceptedRequest: Mock.Request): Promise<Mock.InterceptResult>;
     /**
      * Completes a delegated passthrough by supplying the real response the caller
      * fetched. Records the full transaction and removes the pending entry.
      *
      * Only relevant when {@link Mock.delegateMode} is `true`. The `correlationId`
-     * must match one previously returned by {@link Mock.intercept}.
+     * must match one previously returned by {@link Mock.processInterceptedRequest}.
      *
      * @param correlationId - The UUID returned in the `action: 'passthrough'`
-     *   result from {@link Mock.intercept}. Must be a non-empty string that
+     *   result from {@link Mock.processInterceptedRequest}. Must be a non-empty string that
      *   matches a pending transaction.
      *
      * @param response - The real response the caller received from the endpoint.
@@ -303,6 +303,8 @@ export declare namespace Mock {
     interface Response {
         /** HTTP status code, e.g. `200`, `404`. Must be 100–599. */
         status: number;
+        /** HTTP status text, eg. 'ok' or 'Internal Server Error' etc */
+        statusText?: string;
         /** Response headers as a plain key/value object. */
         headers?: Record<string, string>;
         /** Response body. Objects are serialised to JSON by the framework adapter. */
@@ -318,7 +320,7 @@ export declare namespace Mock {
      */
     type ListenerAction = 'block' | 'passthrough' | Response;
     /**
-     * The result returned by {@link Mock.intercept} to the framework adapter.
+     * The result returned by {@link Mock.processInterceptedRequest} to the framework adapter.
      *
      * - `action: 'fulfill'` — return `response` to the AUT.
      * - `action: 'block'` — abort the request; the AUT receives nothing.
@@ -366,13 +368,13 @@ export declare namespace Mock {
         response?: Response;
     }
     /**
-     * A delegated passthrough that has been issued by {@link Mock.intercept} but
+     * A delegated passthrough that has been issued by {@link Mock.processInterceptedRequest} but
      * not yet completed via {@link Mock.completePassthrough}.
      *
      * Only created when {@link Mock.delegateMode} is `true`.
      */
     interface PendingTransaction {
-        /** The UUID issued by {@link Mock.intercept} to identify this passthrough. */
+        /** The UUID issued by {@link Mock.processInterceptedRequest} to identify this passthrough. */
         correlationId: string;
         /** Wall-clock time at which the passthrough was issued. */
         timestamp: Date;

package/dist/types/utils/utils.d.ts

@@ -70,21 +70,21 @@ export declare class Utils {
      * @param obj - Value to check.
      * @returns `true` if `null` or `undefined`, otherwise `false`.
      */
-    static isNullOrUndefined(obj?: unknown): boolean;
-    /**
+    static isNullOrUndefined(obj?: unknown): obj is null | undefined;
+    /**2
      * Safely checks if a value is `null`.
      *
      * @param obj - Value to check.
      * @returns `true` if `null`, otherwise `false`.
      */
-    static isNull(obj?: unknown): boolean;
+    static isNull(obj?: unknown): obj is null;
     /**
      * Safely checks if a value is `undefined`.
      *
      * @param obj - Value to check.
      * @returns `true` if `undefined`, otherwise `false`.
      */
-    static isUndefined(obj?: unknown): boolean;
+    static isUndefined(obj?: unknown): obj is undefined;
     /**
      * Checks whether a value evaluates to `true` according to common conventions.
      *