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

package/dist/types/detokeniser/detokeniser.d.ts

@@ -10,9 +10,6 @@
  * - **expression** — what to compute (type-specific)
  * - **format** — how to format the result (type-specific, often optional)
  *
- * The delimiter `|` and the `[[` / `]]` endstops are configurable via {@link Detokeniser.delimiter} and
- * {@link Detokeniser.tokenStartEndChars}, but the defaults cover the vast majority of use cases.
- *
  * ---
  * ## Built-in token types
  *
@@ -117,54 +114,26 @@
  *
  * ---
  * ## Extending with callbacks
- * Custom token types are registered via {@link Detokeniser.addCallbackSync} (for sync processing) or
- * {@link Detokeniser.addCallbackAsync} (for async processing). Callbacks are tried in registration
- * order; return `undefined` to pass to the next callback. If all callbacks return `undefined` and no
- * built-in handler matched, an error is thrown.
+ * Custom token types are registered via {@link Detokeniser.addCallback}. Both sync and async handlers
+ * share the same registration method and callback list. Callbacks are tried in registration order;
+ * return `undefined` to pass to the next callback. If all callbacks return `undefined` and no built-in
+ * handler matched, an error is thrown.
+ *
+ * Async callbacks are silently skipped when {@link Detokeniser.do} (sync) is used — use
+ * {@link Detokeniser.doAsync} if your callback returns a Promise.
  *
- * @see {@link Detokeniser.addCallbackSync}
- * @see {@link Detokeniser.addCallbackAsync}
+ * @see {@link Detokeniser.addCallback}
  * @see {@link Detokeniser.do}
  * @see {@link Detokeniser.doAsync}
  */
 export declare class Detokeniser {
-    private static _endTokenChar;
-    private static _startTokenChar;
+    private static readonly _endTokenChar;
+    private static readonly _startTokenChar;
     private static EscapeChar;
-    private static _delimiter;
-    private static _asyncCallbacks;
-    private static _syncCallbacks;
-    /**
-     * Gets the current single-character delimiter used to separate token parts.
-     * Default: `|`
-     */
-    static get delimiter(): string;
-    /**
-     * Sets the single-character delimiter used to separate token parts.
-     * The new value applies to all subsequent {@link Detokeniser.do} / {@link Detokeniser.doAsync} calls.
-     * @param newDelimiter - Exactly one character
-     * @throws If `newDelimiter` is not exactly one character
-     * @example
-     * Detokeniser.delimiter = ':';
-     * Detokeniser.do('[[random:digits:6]]'); // → e.g. '482910'
-     * Detokeniser.reset();                   // restore default '|'
-     */
-    static set delimiter(newDelimiter: string);
-    /**
-     * Sets the start and end token sequences.
-     * @param startEndChars - An even-length string whose first half is the start sequence and second half the end sequence.
-     * @example Detokeniser.tokenStartEndChars = "[[]]"; // start = "[[", end = "]]"
-     * @remarks Start and end sequences must differ. Minimum total length is 2 (one char each).
-     */
-    static set tokenStartEndChars(startEndChars: string);
-    /**
-     * Gets the current token start/end sequences concatenated (e.g. `"[[]]"`).
-     */
-    static get tokenStartEndChars(): string;
+    private static readonly _delimiter;
+    private static _callbacks;
     /**
      * Resets the Detokeniser to factory defaults:
-     * - Token endstops restored to `[[` / `]]`
-     * - Delimiter restored to `|`
      * - Escape char restored to `/`
      * - All registered sync and async callbacks cleared
      *
@@ -174,90 +143,48 @@ export declare class Detokeniser {
      */
     static reset(): void;
     /**
-     * Registers a synchronous custom token handler.
+     * Registers a custom token handler. Both sync and async handlers are registered via this method
+     * and share the same callback list.
+     *
+     * Callbacks are tried in registration order. The first to return a non-`undefined` value wins.
+     * Return `undefined` to pass to the next callback. If all callbacks return `undefined` and no
+     * built-in handler matched, an error is thrown.
      *
-     * When {@link Detokeniser.do} encounters a token not handled by the built-in set, it invokes each
-     * registered sync callback in registration order. The first to return a non-`undefined` string wins.
-     * Return `undefined` to pass to the next callback. If all callbacks return `undefined`, an error is thrown.
+     * Async callbacks (those returning a `Promise`) are silently skipped when {@link Detokeniser.do}
+     * is used — register an async callback only if you intend to call {@link Detokeniser.doAsync}.
      *
-     * @param callback - `(delimiter: string, token: string) => string | undefined`
-     *   - `delimiter` — current delimiter character (default `|`)
-     *   - `token` — full token body without `[[` / `]]`, e.g. `"mytype|arg1|arg2"`
+     * @param callback - `(token: string) => string | undefined | Promise<string | undefined>`
+     *   - `token` — full token body without `[[` / `]]`, e.g. `"mytype|arg1|arg2"` (delimiter is always `|`)
      *
      * @example
-     * // Handle [[env|VAR_NAME]] tokens
-     * Detokeniser.addCallbackSync((delimiter, token) => {
-     *   const [type, name] = token.split(delimiter);
-     *   if (type.toLowerCase() !== 'env') return undefined;
+     * // Sync handler for [[env|VAR_NAME]] tokens
+     * Detokeniser.addCallback((token) => {
+     *   const [type, name] = token.split('|');
+     *   if (type !== 'env') return undefined;
      *   return process.env[name] ?? '';
      * });
      * Detokeniser.do('Path: [[env|HOME]]'); // → 'Path: /home/user'
      *
      * @example
-     * // Multiple callbacks — each handles one type, passes on the rest
-     * Detokeniser.addCallbackSync((delimiter, token) => {
-     *   const [type, value] = token.split(delimiter);
-     *   if (type === 'upper') return value.toUpperCase();
-     *   return undefined;
-     * });
-     * Detokeniser.addCallbackSync((delimiter, token) => {
-     *   const [type, value] = token.split(delimiter);
-     *   if (type === 'lower') return value.toLowerCase();
-     *   return undefined;
-     * });
-     * Detokeniser.do('[[upper|hello]] [[lower|WORLD]]'); // → 'HELLO world'
-     *
-     * @see {@link Detokeniser.resetSyncCallbacks} to remove all sync callbacks
-     * @see {@link Detokeniser.addCallbackAsync} for async token handlers
-     */
-    static addCallbackSync(callback: Detokeniser.Callback_Sync): void;
-    /**
-     * Registers an asynchronous custom token handler.
-     *
-     * Works identically to {@link Detokeniser.addCallbackSync} but is invoked by {@link Detokeniser.doAsync}.
-     * Async callbacks are tried in registration order; the first to return a non-`undefined` value wins.
-     * Return `undefined` to pass to the next callback.
-     *
-     * @param asyncCallback - `(delimiter: string, token: string) => Promise<string | undefined>`
-     *   - `delimiter` — current delimiter character (default `|`)
-     *   - `token` — full token body without `[[` / `]]`, e.g. `"mytype|arg1|arg2"`
-     *
-     * @example
-     * // Handle [[db|table|column|whereClause]] tokens
-     * Detokeniser.addCallbackAsync(async (delimiter, token) => {
-     *   const [type, table, column, where] = token.split(delimiter);
-     *   if (type.toLowerCase() !== 'db') return undefined;
+     * // Async handler for [[db|table|column|where]] tokens
+     * Detokeniser.addCallback(async (token) => {
+     *   const [type, table, column, where] = token.split('|');
+     *   if (type !== 'db') return undefined;
      *   const row = await db.query(`SELECT ${column} FROM ${table} WHERE ${where} LIMIT 1`);
      *   return String(row[column]);
      * });
      * const result = await Detokeniser.doAsync('ID: [[db|users|id|active=1]]');
      *
-     * @example
-     * // Combine with nested tokens — inner tokens resolve before the callback is called
-     * Detokeniser.addCallbackAsync(async (delimiter, token) => {
-     *   const [type, key] = token.split(delimiter);
-     *   if (type !== 'cache') return undefined;
-     *   return await redis.get(key);
-     * });
-     * // [[random|digits|8]] resolves first, then [[cache|...]] receives the result
-     * await Detokeniser.doAsync('Val: [[cache|prefix-[[random|digits|8]]]]');
-     *
-     * @see {@link Detokeniser.resetAsyncCallbacks} to remove all async callbacks
-     * @see {@link Detokeniser.addCallbackSync} for synchronous token handlers
-     */
-    static addCallbackAsync(asyncCallback: Detokeniser.Callback_Async): void;
-    /**
-     * Removes all registered sync callbacks. Built-in token handlers are unaffected.
-     * Use between tests or scenarios to ensure callback isolation.
-     * @see {@link Detokeniser.reset} to also clear async callbacks and restore all defaults
+     * @see {@link Detokeniser.resetCallbacks} to remove all registered callbacks
+     * @see {@link Detokeniser.doAsync} for async token resolution
      */
-    static resetSyncCallbacks(): void;
+    static addCallback(callback: Detokeniser.Callback): void;
     /**
-     * Removes all registered async callbacks. Built-in token handlers are unaffected.
+     * Removes all registered callbacks. Built-in token handlers are unaffected.
      * Use between tests or scenarios to ensure callback isolation.
-     * @see {@link Detokeniser.reset} to also clear sync callbacks and restore all defaults
+     * @see {@link Detokeniser.reset} to also restore all defaults
      */
-    static resetAsyncCallbacks(): void;
+    static resetCallbacks(): void;
     /**
      * Synchronously resolves all tokens in the given string and returns the result.
      *
@@ -311,8 +238,8 @@ export declare class Detokeniser {
      *
      * @example
      * // Async callback for database-driven tokens
-     * Detokeniser.addCallbackAsync(async (delim, token) => {
-     *   const [type, key] = token.split(delim);
+     * Detokeniser.addCallbackAsync(async (token) => {
+     *   const [type, key] = token.split('|');
      *   if (type !== 'db') return undefined;
      *   return await fetchFromDatabase(key);
      * });
@@ -365,24 +292,16 @@ export declare class Detokeniser {
     private static doRandomFloat;
 }
 /**
- * Signature for an asynchronous custom token handler registered via {@link Detokeniser.addCallbackAsync}.
+ * Signature for a custom token handler registered via {@link Detokeniser.addCallback}.
  *
- * @param delimiter - Current delimiter character (default `|`)
- * @param token - Full token body without `[[` / `]]` endstops, e.g. `"mytype|arg1|arg2"`
- * @returns Promise resolving to the replacement string, or `undefined` to pass to the next handler
- */
-export interface Detokeniser_Callback_Async {
-    (delimiter: string, token: string): Promise<string | undefined>;
-}
-/**
- * Signature for a synchronous custom token handler registered via {@link Detokeniser.addCallbackSync}.
+ * May be synchronous or asynchronous. Async callbacks (returning a `Promise`) are silently skipped
+ * by {@link Detokeniser.do} and only invoked by {@link Detokeniser.doAsync}.
  *
- * @param delimiter - Current delimiter character (default `|`)
- * @param token - Full token body without `[[` / `]]` endstops, e.g. `"mytype|arg1|arg2"`
- * @returns The replacement string, or `undefined` to pass to the next handler
+ * @param token - Full token body without `[[` / `]]` endstops, e.g. `"mytype|arg1|arg2"` (delimiter is always `|`)
+ * @returns The replacement string, a Promise resolving to it, or `undefined` to pass to the next handler
  */
-export interface Detokeniser_Callback_Sync {
-    (delimiter: string, token: string): string | undefined;
+export interface Detokeniser_Callback {
+    (token: string): string | undefined | Promise<string | undefined>;
 }
 /**
  * Options passed to {@link Detokeniser.do} and {@link Detokeniser.doAsync}.
@@ -396,7 +315,6 @@ export interface Detokeniser_DoOptions {
     contextParameters?: Record<string, unknown>;
 }
 export declare namespace Detokeniser {
-    type Callback_Async = Detokeniser_Callback_Async;
-    type Callback_Sync = Detokeniser_Callback_Sync;
+    type Callback = Detokeniser_Callback;
     type DoOptions = Detokeniser_DoOptions;
 }

package/dist/types/index.d.ts

@@ -16,3 +16,4 @@ export { JsonUtils } from "./jsonUtils/jsonUtils";
 export { StringUtils } from "./stringUtils/stringUtils";
 export { Utils, ExistingFileWriteActions } from "./utils/utils";
 export type { AssertTypeMap, ActionAndParams } from "./utils/utils";
+export { Mock } from "./mock/mock";

package/dist/types/logger/types.d.ts

@@ -130,7 +130,9 @@ export interface WriteLineOptions {
      * //   "MyTest.someStep (myTest.ts:45:3)"
      * Logger.writeLine(Logger.Levels.TestInformation, message, { stackOffset: 1 });
      *
-     * @remarks Not yet implemented — reserved for a future release.
+     * Values less than 1 are treated as 0 (no offset). Values that would exceed
+     * the available stack depth are clipped to the outermost frame.
+     *
      */
     stackOffset?: number;
 }

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

@@ -0,0 +1,393 @@
+/**
+ * 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 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
+ * recorded as an `unmatched` transaction. The test suite has full control —
+ * nothing reaches the network unless explicitly permitted.
+ *
+ * **All transactions are stored** regardless of outcome, so test steps can
+ * later inspect real and mocked traffic via {@link Mock.getTransactions}.
+ *
+ * All methods are static — no instantiation is required. Call {@link Mock.reset}
+ * in `beforeEach` / `afterEach` hooks to start each test with a clean slate.
+ *
+ * ---
+ *
+ * ### Local mode (default)
+ *
+ * `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.processInterceptedRequest} always resolves to a {@link Mock.InterceptResult}
+ * with `action: 'fulfill'` or `action: 'block'`.
+ *
+ * ### Delegate mode
+ *
+ * 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.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
+ * passthrough calls that were never completed.
+ *
+ * @example
+ * ```typescript
+ * // Local mode — Playwright adapter
+ * Mock.reset();
+ * Mock.addListener('get-users',
+ *   ['$[?(@.url =~ /api\\/users/)]', '$[?(@.method == "GET")]'],
+ *   { status: 200, body: [{ id: 1, name: 'Alice' }] }
+ * );
+ *
+ * await page.route('**\/*', async (route) => {
+ *   const result = await Mock.intercept({
+ *     url: route.request().url(),
+ *     method: route.request().method(),
+ *     headers: await route.request().allHeaders(),
+ *   });
+ *   if (result.action === 'fulfill') {
+ *     await route.fulfill({ status: result.response.status });
+ *   } else {
+ *     await route.abort();
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Delegate mode — remote mock server
+ * Mock.delegateMode = true;
+ *
+ * // In the interceptor callback:
+ * const result = await Mock.intercept(request);
+ * if (result.action === 'passthrough') {
+ *   const real = await myFetch(request);
+ *   Mock.completePassthrough(result.correlationId, real);
+ *   return real;
+ * }
+ * ```
+ */
+export declare class Mock {
+    private static listeners;
+    private static transactions;
+    private static transactionCounter;
+    private static pendingTransactions;
+    private static _delegateMode;
+    /**
+     * When `true`, passthrough requests are delegated to the caller rather than
+     * 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}.
+     *
+     * Defaults to `false` (local mode — `Mock` fetches passthroughs itself).
+     *
+     * @example
+     * Mock.delegateMode = true;
+     */
+    static set delegateMode(value: boolean);
+    static get delegateMode(): boolean;
+    /**
+     * Registers a named listener that matches intercepted requests and defines
+     * how `Mock` should respond to them.
+     *
+     * Listeners are evaluated in registration order. The first listener whose
+     * every matcher returns a result wins. If a listener with the same `name`
+     * already exists it is replaced and a warning is logged.
+     *
+     * @param name - Unique name for this listener. Used as the key in the
+     *   listener store and appears in transaction records and log output.
+     *   Must be a non-empty string.
+     *
+     * @param matchers - One or more JSONPath expressions evaluated against the
+     *   {@link Mock.Request} object. All expressions must return at least one
+     *   result for the listener to match (AND logic). Each expression is
+     *   validated for syntactic correctness at registration time — an invalid
+     *   expression throws immediately rather than silently failing at intercept
+     *   time. Must be a non-empty array of non-empty strings.
+     *
+     * @param action - What to do when this listener matches:
+     *   - `'block'` — abort the request and return `action: 'block'` to the caller.
+     *   - `'passthrough'` — forward the request to the real endpoint (or delegate
+     *     to the caller in {@link Mock.delegateMode}) and return the real response.
+     *   - {@link Mock.Response} — return the supplied response object directly
+     *     without touching the network. `status` must be a valid HTTP status
+     *     code (100–599).
+     *
+     * @param delayMs - Optional delay in milliseconds applied before the
+     *   response is returned, whether mocked, real, or blocked. Useful for
+     *   simulating slow networks. Must be a non-negative finite number.
+     *   Defaults to `0` (no delay).
+     *
+     * @throws {Error} If any argument fails validation.
+     *
+     * @example
+     * // Block all requests to an analytics endpoint
+     * Mock.addListener('block-analytics', ['$[?(@.url =~ /analytics/)]'], 'block');
+     *
+     * @example
+     * // Return a mock response with a 2-second simulated delay
+     * Mock.addListener('slow-login',
+     *   ['$[?(@.url =~ /api\\/login/)]'],
+     *   { status: 200, headers: { 'content-type': 'application/json' }, body: { token: 'abc' } },
+     *   2000
+     * );
+     */
+    static addListener(name: string, matchers: string[], action: Mock.ListenerAction, delayMs?: number): void;
+    /**
+     * Removes a previously registered listener by name.
+     *
+     * If no listener with the given name exists, a warning is logged and the
+     * call is a no-op.
+     *
+     * @param name - Name of the listener to remove. Must be a non-empty string.
+     * @throws {Error} If `name` is not a non-empty string.
+     *
+     * @example
+     * Mock.removeListener('get-users');
+     */
+    static removeListener(name: string): void;
+    /**
+     * Removes all registered listeners.
+     *
+     * Transaction history and pending transactions are unaffected. Use
+     * {@link Mock.reset} to clear everything in a single call.
+     */
+    static clearListeners(): void;
+    /**
+     * Processes an intercepted HTTP request and returns a {@link Mock.InterceptResult}
+     * describing what the caller should do.
+     *
+     * Listeners are evaluated in registration order; the first full match wins.
+     * Every request — matched or not — is recorded in the transaction history.
+     * If the matching listener has a `delayMs`, the delay is applied before the
+     * result is returned.
+     *
+     * | Situation | `action` returned | Transaction type |
+     * |---|---|---|
+     * | Matched → mock response | `'fulfill'` | `'mocked'` |
+     * | Matched → passthrough, local mode | `'fulfill'` | `'passthrough'` |
+     * | Matched → passthrough, delegate mode | `'passthrough'` | pending until {@link Mock.completePassthrough} |
+     * | Matched → block | `'block'` | `'blocked'` |
+     * | No listener matched | `'block'` | `'unmatched'` |
+     *
+     * @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}.
+     *
+     * @throws {Error} If `request` fails validation.
+     *
+     * @example
+     * const result = await Mock.intercept(request);
+     * if (result.action === 'fulfill') {
+     *   respondWith(result.response);
+     * } else if (result.action === 'passthrough') {
+     *   // delegate mode only
+     *   const real = await fetch(request.url);
+     *   Mock.completePassthrough(result.correlationId, real);
+     *   respondWith(real);
+     * } else {
+     *   abortRequest();
+     * }
+     */
+    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.processInterceptedRequest}.
+     *
+     * @param correlationId - The UUID returned in the `action: 'passthrough'`
+     *   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.
+     *   Must be a valid {@link Mock.Response} with a status code of 100–599.
+     *
+     * @throws {Error} If `correlationId` is invalid, unknown, or already completed.
+     * @throws {Error} If `response` fails validation.
+     *
+     * @example
+     * const result = await Mock.intercept(request);
+     * if (result.action === 'passthrough') {
+     *   const real = await myFetch(request);
+     *   Mock.completePassthrough(result.correlationId, real);
+     * }
+     */
+    static completePassthrough(correlationId: string, response: Mock.Response): void;
+    /**
+     * Returns all completed transactions in chronological order.
+     *
+     * Includes mocked, passthrough (completed), blocked, and unmatched entries.
+     * Delegated passthroughs awaiting {@link Mock.completePassthrough} appear in
+     * {@link Mock.getPendingTransactions} instead.
+     *
+     * @returns A read-only array of {@link Mock.Transaction} objects.
+     *
+     * @example
+     * const blocked = Mock.getTransactions().filter(t => t.type === 'blocked');
+     */
+    static getTransactions(): readonly Mock.Transaction[];
+    /**
+     * Clears all completed transactions and resets the transaction counter.
+     *
+     * Pending passthrough transactions and registered listeners are unaffected.
+     * Use {@link Mock.reset} to clear everything in a single call.
+     */
+    static clearTransactions(): void;
+    /**
+     * Returns all delegated passthrough transactions that have not yet been
+     * completed via {@link Mock.completePassthrough}.
+     *
+     * Use this in test assertions to verify no passthrough calls were abandoned,
+     * or to diagnose remote fetch failures.
+     *
+     * Only populated when {@link Mock.delegateMode} is `true`.
+     *
+     * @returns A read-only array of {@link Mock.PendingTransaction} objects.
+     *
+     * @example
+     * // Assert no orphaned passthroughs after a test
+     * expect(Mock.getPendingTransactions()).toHaveLength(0);
+     */
+    static getPendingTransactions(): readonly Mock.PendingTransaction[];
+    /**
+     * Clears all listeners, completed transactions, pending transactions, and
+     * resets delegate mode to `false`.
+     *
+     * Call this in `beforeEach` or `afterEach` hooks to guarantee a clean slate
+     * between tests.
+     *
+     * @example
+     * beforeEach(() => {
+     *   Mock.reset();
+     *   Mock.addListener('static-assets', [...], 'passthrough');
+     * });
+     */
+    static reset(): void;
+    private static throwError;
+    private static findMatch;
+    private static fetchReal;
+    private static record;
+}
+export declare namespace Mock {
+    /**
+     * Represents an HTTP request as seen by the interceptor.
+     *
+     * The `url`, `method`, and `headers` fields are required. Additional
+     * properties (e.g. framework-specific metadata) may be included and are
+     * available to JSONPath matchers.
+     */
+    interface Request {
+        /** The fully-qualified request URL. */
+        url: string;
+        /** HTTP method in uppercase, e.g. `'GET'`, `'POST'`. */
+        method: string;
+        /** Request headers as a plain key/value object. */
+        headers: Record<string, string>;
+        /** Parsed request body, if present. */
+        body?: unknown;
+        /** Any additional properties provided by the framework adapter. */
+        [key: string]: unknown;
+    }
+    /**
+     * Represents an HTTP response returned to the AUT, whether real or mocked.
+     */
+    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. */
+        body?: unknown;
+    }
+    /**
+     * Defines what a listener does when it matches a request.
+     *
+     * - `'block'` — abort the request; the AUT receives no response.
+     * - `'passthrough'` — forward to the real endpoint (or delegate to the caller
+     *   in {@link Mock.delegateMode}) and return the actual response.
+     * - {@link Response} — return the supplied mock response without hitting the network.
+     */
+    type ListenerAction = 'block' | 'passthrough' | Response;
+    /**
+     * 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.
+     * - `action: 'passthrough'` — only in {@link Mock.delegateMode}. Fetch the
+     *   real response using `request` details and report it back via
+     *   {@link Mock.completePassthrough} using the supplied `correlationId`.
+     */
+    type InterceptResult = {
+        action: 'fulfill';
+        response: Response;
+    } | {
+        action: 'block';
+    } | {
+        action: 'passthrough';
+        correlationId: string;
+    };
+    /**
+     * Describes the outcome of a single completed intercepted request.
+     *
+     * - `'mocked'` — a mock {@link Response} was returned.
+     * - `'passthrough'` — the request was forwarded and the real response returned.
+     * - `'blocked'` — the request was explicitly blocked by a listener.
+     * - `'unmatched'` — no listener matched; the request was blocked by default.
+     */
+    type TransactionType = 'mocked' | 'passthrough' | 'blocked' | 'unmatched';
+    /**
+     * A record of a single completed intercepted request and its outcome.
+     *
+     * Delegated passthroughs awaiting completion appear in
+     * {@link Mock.getPendingTransactions} as {@link PendingTransaction} until
+     * {@link Mock.completePassthrough} is called.
+     */
+    interface Transaction {
+        /** Auto-incremented identifier, e.g. `'txn-1'`. Resets on {@link Mock.reset}. */
+        id: string;
+        /** Wall-clock time at which the request was intercepted. */
+        timestamp: Date;
+        /** Name of the listener that matched, if any. Absent for `'unmatched'` transactions. */
+        listenerName?: string;
+        /** How the request was handled. */
+        type: TransactionType;
+        /** The intercepted request. */
+        request: Request;
+        /** The response returned to the AUT. Absent for `'blocked'` and `'unmatched'` transactions. */
+        response?: Response;
+    }
+    /**
+     * 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.processInterceptedRequest} to identify this passthrough. */
+        correlationId: string;
+        /** Wall-clock time at which the passthrough was issued. */
+        timestamp: Date;
+        /** Name of the listener that triggered the passthrough. */
+        listenerName: string;
+        /** The original intercepted request. */
+        request: Request;
+    }
+    /** @internal */
+    interface Listener {
+        name: string;
+        matchers: string[];
+        action: ListenerAction;
+        delayMs: number;
+    }
+}