@schmock/core 1.2.2 → 1.4.0

package/dist/builder.d.ts

@@ -11,6 +11,9 @@ export declare class CallableMockInstance {
     private logger;
     private requestHistory;
     private callableRef;
+    private server;
+    private serverInfo;
+    private listeners;
     constructor(globalConfig?: Schmock.GlobalConfig);
     defineRoute(route: Schmock.RouteKey, generator: Schmock.Generator, config: Schmock.RouteConfig): this;
     setCallableRef(ref: Schmock.CallableMockInstance): void;
@@ -19,9 +22,16 @@ export declare class CallableMockInstance {
     called(method?: Schmock.HttpMethod, path?: string): boolean;
     callCount(method?: Schmock.HttpMethod, path?: string): number;
     lastRequest(method?: Schmock.HttpMethod, path?: string): Schmock.RequestRecord | undefined;
+    getRoutes(): Schmock.RouteInfo[];
+    getState(): Record<string, unknown>;
+    on(event: string, listener: (data: unknown) => void): this;
+    off(event: string, listener: (data: unknown) => void): this;
+    private emit;
     reset(): void;
     resetHistory(): void;
     resetState(): void;
+    listen(port?: number, hostname?: string): Promise<Schmock.ServerInfo>;
+    close(): void;
     handle(method: Schmock.HttpMethod, path: string, options?: Schmock.RequestOptions): Promise<Schmock.Response>;
     /**
      * Apply configured response delay

package/dist/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AA0EA;;;;GAIG;AACH,qBAAa,oBAAoB;IAQnB,OAAO,CAAC,YAAY;IAPhC,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,WAAW,CAA2C;gBAE1C,YAAY,GAAE,OAAO,CAAC,YAAiB;IAa3D,WAAW,CACT,KAAK,EAAE,OAAO,CAAC,QAAQ,EACvB,SAAS,EAAE,OAAO,CAAC,SAAS,EAC5B,MAAM,EAAE,OAAO,CAAC,WAAW,GAC1B,IAAI;IAqFP,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,oBAAoB,GAAG,IAAI;IAIvD,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI;IAoBlC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE;IAS5E,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAS3D,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAS7D,WAAW,CACT,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAC3B,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,GAAG,SAAS;IAYpC,KAAK,IAAI,IAAI;IAab,YAAY,IAAI,IAAI;IAKpB,UAAU,IAAI,IAAI;IASZ,MAAM,CACV,MAAM,EAAE,OAAO,CAAC,UAAU,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,GAC/B,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;IAoL5B;;;;OAIG;YACW,UAAU;IAcxB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAwDrB;;;;;;;;;;OAUG;YACW,iBAAiB;IAqG/B;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IA0BjB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;CActB"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AA4EA;;;;GAIG;AACH,qBAAa,oBAAoB;IAWnB,OAAO,CAAC,YAAY;IAVhC,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,WAAW,CAA2C;IAC9D,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,SAAS,CAAmD;gBAEhD,YAAY,GAAE,OAAO,CAAC,YAAiB;IAa3D,WAAW,CACT,KAAK,EAAE,OAAO,CAAC,QAAQ,EACvB,SAAS,EAAE,OAAO,CAAC,SAAS,EAC5B,MAAM,EAAE,OAAO,CAAC,WAAW,GAC1B,IAAI;IAqFP,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,oBAAoB,GAAG,IAAI;IAIvD,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI;IAoBlC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE;IAS5E,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;IAS3D,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAS7D,WAAW,CACT,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,EAC3B,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,GAAG,SAAS;IAYpC,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE;IAQhC,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAMnC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAU1D,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAK3D,OAAO,CAAC,IAAI;IAWZ,KAAK,IAAI,IAAI;IAeb,YAAY,IAAI,IAAI;IAKpB,UAAU,IAAI,IAAI;IAWlB,MAAM,CAAC,IAAI,SAAI,EAAE,QAAQ,SAAc,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC;IAmFrE,KAAK,IAAI,IAAI;IAUP,MAAM,CACV,MAAM,EAAE,OAAO,CAAC,UAAU,EAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,GAC/B,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;IAgN5B;;;;OAIG;YACW,UAAU;IAgBxB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAwDrB;;;;;;;;;;OAUG;YACW,iBAAiB;IAqG/B;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IA0BjB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;CActB"}

package/dist/builder.js

@@ -1,4 +1,5 @@
-import { isStatusTuple } from "./constants.js";
+import { createServer } from "node:http";
+import { isStatusTuple, toHttpMethod } from "./constants.js";
 import { PluginError, RouteDefinitionError, RouteNotFoundError, SchmockError, } from "./errors.js";
 import { parseRouteKey } from "./parser.js";
 function errorMessage(error) {
@@ -57,6 +58,9 @@ export class CallableMockInstance {
     logger;
     requestHistory = [];
     callableRef;
+    server;
+    serverInfo;
+    listeners = new Map();
     constructor(globalConfig = {}) {
         this.globalConfig = globalConfig;
         this.logger = new DebugLogger(globalConfig.debug || false);
@@ -179,12 +183,47 @@ export class CallableMockInstance {
         }
         return this.requestHistory[this.requestHistory.length - 1];
     }
+    // ===== Introspection =====
+    getRoutes() {
+        return this.routes.map((r) => ({
+            method: r.method,
+            path: r.path,
+            hasParams: r.params.length > 0,
+        }));
+    }
+    getState() {
+        return this.globalConfig.state || {};
+    }
+    // ===== Lifecycle Events =====
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+        return this;
+    }
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+        return this;
+    }
+    emit(event, data) {
+        const set = this.listeners.get(event);
+        if (set) {
+            for (const listener of set) {
+                listener(data);
+            }
+        }
+    }
     // ===== Reset / Lifecycle =====
     reset() {
+        this.close();
         this.routes = [];
         this.staticRoutes.clear();
         this.plugins = [];
         this.requestHistory = [];
+        this.listeners.clear();
         if (this.globalConfig.state) {
             for (const key of Object.keys(this.globalConfig.state)) {
                 delete this.globalConfig.state[key];
@@ -204,14 +243,96 @@ export class CallableMockInstance {
         }
         this.logger.log("lifecycle", "State cleared");
     }
+    // ===== Standalone Server =====
+    listen(port = 0, hostname = "127.0.0.1") {
+        if (this.server) {
+            throw new SchmockError("Server is already running", "SERVER_ALREADY_RUNNING");
+        }
+        const httpServer = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+            const method = toHttpMethod(req.method ?? "GET");
+            const path = url.pathname;
+            const headers = {};
+            for (const [key, value] of Object.entries(req.headers)) {
+                if (typeof value === "string") {
+                    headers[key] = value;
+                }
+            }
+            const query = {};
+            url.searchParams.forEach((value, key) => {
+                query[key] = value;
+            });
+            const chunks = [];
+            req.on("data", (chunk) => chunks.push(chunk));
+            req.on("end", () => {
+                const raw = Buffer.concat(chunks).toString();
+                let body;
+                const contentType = headers["content-type"] ?? "";
+                if (raw && contentType.includes("json")) {
+                    try {
+                        body = JSON.parse(raw);
+                    }
+                    catch {
+                        body = raw;
+                    }
+                }
+                else if (raw) {
+                    body = raw;
+                }
+                void this.handle(method, path, { headers, body, query }).then((schmockResponse) => {
+                    const responseHeaders = {
+                        ...schmockResponse.headers,
+                    };
+                    if (!responseHeaders["content-type"] &&
+                        schmockResponse.body !== undefined &&
+                        typeof schmockResponse.body !== "string") {
+                        responseHeaders["content-type"] = "application/json";
+                    }
+                    const responseBody = schmockResponse.body === undefined
+                        ? undefined
+                        : typeof schmockResponse.body === "string"
+                            ? schmockResponse.body
+                            : JSON.stringify(schmockResponse.body);
+                    res.writeHead(schmockResponse.status, responseHeaders);
+                    res.end(responseBody);
+                });
+            });
+        });
+        this.server = httpServer;
+        return new Promise((resolve, reject) => {
+            httpServer.on("error", reject);
+            httpServer.listen(port, hostname, () => {
+                const addr = httpServer.address();
+                const actualPort = addr !== null && typeof addr === "object" ? addr.port : port;
+                this.serverInfo = { port: actualPort, hostname };
+                this.logger.log("server", `Listening on ${hostname}:${actualPort}`);
+                resolve(this.serverInfo);
+            });
+        });
+    }
+    close() {
+        if (!this.server) {
+            return;
+        }
+        this.server.close();
+        this.server = undefined;
+        this.serverInfo = undefined;
+        this.logger.log("server", "Server stopped");
+    }
     async handle(method, path, options) {
         const requestId = crypto.randomUUID();
+        const handleStart = performance.now();
         this.logger.log("request", `[${requestId}] ${method} ${path}`, {
             headers: options?.headers,
             query: options?.query,
             bodyType: options?.body ? typeof options.body : "none",
         });
         this.logger.time(`request-${requestId}`);
+        this.emit("request:start", {
+            method,
+            path,
+            headers: options?.headers || {},
+        });
         try {
             // Apply namespace if configured
             let requestPath = path;
@@ -244,18 +365,31 @@ export class CallableMockInstance {
             const matchedRoute = this.findRoute(method, requestPath);
             if (!matchedRoute) {
                 this.logger.log("route", `[${requestId}] No route found for ${method} ${requestPath}`);
+                this.emit("request:notfound", { method, path: requestPath });
                 const error = new RouteNotFoundError(method, path);
                 const response = {
                     status: 404,
                     body: { error: error.message, code: error.code },
                     headers: {},
                 };
+                this.emit("request:end", {
+                    method,
+                    path: requestPath,
+                    status: 404,
+                    duration: performance.now() - handleStart,
+                });
                 this.logger.timeEnd(`request-${requestId}`);
                 return response;
             }
             this.logger.log("route", `[${requestId}] Matched route: ${method} ${matchedRoute.path}`);
             // Extract parameters from the matched route
             const params = this.extractParams(matchedRoute, requestPath);
+            this.emit("request:match", {
+                method,
+                path: requestPath,
+                routePath: matchedRoute.path,
+                params,
+            });
             // Generate initial response from route handler
             const context = {
                 method,
@@ -297,8 +431,8 @@ export class CallableMockInstance {
             }
             // Parse and prepare response
             const response = this.parseResponse(result, matchedRoute.config);
-            // Apply global delay if configured
-            await this.applyDelay();
+            // Apply delay (route-level overrides global)
+            await this.applyDelay(matchedRoute.config.delay);
             // Record request in history
             this.requestHistory.push({
                 method,
@@ -310,6 +444,12 @@ export class CallableMockInstance {
                 timestamp: Date.now(),
                 response: { status: response.status, body: response.body },
             });
+            this.emit("request:end", {
+                method,
+                path: requestPath,
+                status: response.status,
+                duration: performance.now() - handleStart,
+            });
             // Log successful response
             this.logger.log("response", `[${requestId}] Sending response ${response.status}`, {
                 status: response.status,
@@ -330,7 +470,7 @@ export class CallableMockInstance {
                 },
                 headers: {},
             };
-            // Apply global delay if configured (even for error responses)
+            // Apply delay even for error responses
             await this.applyDelay();
             this.logger.log("error", `[${requestId}] Returning error response 500`);
             this.logger.timeEnd(`request-${requestId}`);
@@ -342,16 +482,16 @@ export class CallableMockInstance {
      * Supports both fixed delays and random delays within a range
      * @private
      */
-    async applyDelay() {
-        if (!this.globalConfig.delay) {
+    async applyDelay(routeDelay) {
+        const effectiveDelay = routeDelay ?? this.globalConfig.delay;
+        if (!effectiveDelay) {
             return;
         }
-        const delay = Array.isArray(this.globalConfig.delay)
-            ? Math.random() *
-                (this.globalConfig.delay[1] - this.globalConfig.delay[0]) +
-                this.globalConfig.delay[0]
-            : this.globalConfig.delay;
-        await new Promise((resolve) => setTimeout(resolve, delay));
+        const ms = Array.isArray(effectiveDelay)
+            ? Math.random() * (effectiveDelay[1] - effectiveDelay[0]) +
+                effectiveDelay[0]
+            : effectiveDelay;
+        await new Promise((resolve) => setTimeout(resolve, ms));
     }
     /**
      * Parse and normalize response result into Response object

package/dist/index.d.ts

@@ -24,5 +24,5 @@
 export declare function schmock(config?: Schmock.GlobalConfig): Schmock.CallableMockInstance;
 export { HTTP_METHODS, isHttpMethod, isStatusTuple, ROUTE_NOT_FOUND_CODE, toHttpMethod, } from "./constants.js";
 export { PluginError, ResourceLimitError, ResponseGenerationError, RouteDefinitionError, RouteNotFoundError, RouteParseError, SchemaGenerationError, SchemaValidationError, SchmockError, } from "./errors.js";
-export type { CallableMockInstance, Generator, GeneratorFunction, GlobalConfig, HttpMethod, Plugin, PluginContext, PluginResult, RequestContext, RequestOptions, RequestRecord, Response, ResponseBody, ResponseResult, RouteConfig, RouteKey, StaticData, } from "./types.js";
+export type { CallableMockInstance, Generator, GeneratorFunction, GlobalConfig, HttpMethod, Plugin, PluginContext, PluginResult, RequestContext, RequestOptions, RequestRecord, Response, ResponseBody, ResponseResult, RouteConfig, RouteInfo, RouteKey, ServerInfo, StaticData, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CACrB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,GAC5B,OAAO,CAAC,oBAAoB,CAiC9B;AAGD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,MAAM,EACN,aAAa,EACb,YAAY,EACZ,cAAc,EACd,cAAc,EACd,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,WAAW,EACX,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CACrB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,GAC5B,OAAO,CAAC,oBAAoB,CA6C9B;AAGD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,MAAM,EACN,aAAa,EACb,YAAY,EACZ,cAAc,EACd,cAAc,EACd,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,WAAW,EACX,SAAS,EACT,QAAQ,EACR,UAAU,EACV,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -42,6 +42,18 @@ export function schmock(config) {
         reset: instance.reset.bind(instance),
         resetHistory: instance.resetHistory.bind(instance),
         resetState: instance.resetState.bind(instance),
+        on: ((event, listener) => {
+            instance.on(event, listener);
+            return callableInstance;
+        }),
+        off: ((event, listener) => {
+            instance.off(event, listener);
+            return callableInstance;
+        }),
+        getRoutes: instance.getRoutes.bind(instance),
+        getState: instance.getState.bind(instance),
+        listen: instance.listen.bind(instance),
+        close: instance.close.bind(instance),
     });
     instance.setCallableRef(callableInstance);
     return callableInstance;

package/dist/types.d.ts

@@ -15,4 +15,6 @@ export type PluginContext = Schmock.PluginContext;
 export type PluginResult = Schmock.PluginResult;
 export type StaticData = Schmock.StaticData;
 export type RequestRecord = Schmock.RequestRecord;
+export type ServerInfo = Schmock.ServerInfo;
+export type RouteInfo = Schmock.RouteInfo;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;AAC1C,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;AAC1D,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;AAChE,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;AACpC,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;AAC1C,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;AAC1D,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;AAChE,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;AACpC,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;AAChD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC"}

package/dist/types.js

@@ -1,2 +1,2 @@
-/// <reference path="../../../types/schmock.d.ts" />
+/// <reference path="../schmock.d.ts" />
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schmock/core",
   "description": "Core functionality for Schmock",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,7 +19,7 @@
   },
   "scripts": {
     "build": "bun build:lib && bun build:types",
-    "build:lib": "bun build --minify --outdir=dist src/index.ts",
+    "build:lib": "bun build --minify --target node --outdir=dist src/index.ts",
     "build:types": "rm -f tsconfig.tsbuildinfo && tsc --build",
     "pretest": "rm -f src/*.js src/*.d.ts || true",
     "test": "vitest",

package/src/builder.ts

@@ -1,4 +1,6 @@
-import { isStatusTuple } from "./constants.js";
+import type { Server } from "node:http";
+import { createServer } from "node:http";
+import { isStatusTuple, toHttpMethod } from "./constants.js";
 import {
   PluginError,
   RouteDefinitionError,
@@ -84,6 +86,9 @@ export class CallableMockInstance {
   private logger: DebugLogger;
   private requestHistory: Schmock.RequestRecord[] = [];
   private callableRef: Schmock.CallableMockInstance | undefined;
+  private server: Server | undefined;
+  private serverInfo: Schmock.ServerInfo | undefined;
+  private listeners = new Map<string, Set<(data: unknown) => void>>();
 
   constructor(private globalConfig: Schmock.GlobalConfig = {}) {
     this.logger = new DebugLogger(globalConfig.debug || false);
@@ -251,13 +256,55 @@ export class CallableMockInstance {
     return this.requestHistory[this.requestHistory.length - 1];
   }
 
+  // ===== Introspection =====
+
+  getRoutes(): Schmock.RouteInfo[] {
+    return this.routes.map((r) => ({
+      method: r.method,
+      path: r.path,
+      hasParams: r.params.length > 0,
+    }));
+  }
+
+  getState(): Record<string, unknown> {
+    return this.globalConfig.state || {};
+  }
+
+  // ===== Lifecycle Events =====
+
+  on(event: string, listener: (data: unknown) => void): this {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(listener);
+    return this;
+  }
+
+  off(event: string, listener: (data: unknown) => void): this {
+    this.listeners.get(event)?.delete(listener);
+    return this;
+  }
+
+  private emit(event: string, data: unknown): void {
+    const set = this.listeners.get(event);
+    if (set) {
+      for (const listener of set) {
+        listener(data);
+      }
+    }
+  }
+
   // ===== Reset / Lifecycle =====
 
   reset(): void {
+    this.close();
     this.routes = [];
     this.staticRoutes.clear();
     this.plugins = [];
     this.requestHistory = [];
+    this.listeners.clear();
     if (this.globalConfig.state) {
       for (const key of Object.keys(this.globalConfig.state)) {
         delete this.globalConfig.state[key];
@@ -280,12 +327,108 @@ export class CallableMockInstance {
     this.logger.log("lifecycle", "State cleared");
   }
 
+  // ===== Standalone Server =====
+
+  listen(port = 0, hostname = "127.0.0.1"): Promise<Schmock.ServerInfo> {
+    if (this.server) {
+      throw new SchmockError(
+        "Server is already running",
+        "SERVER_ALREADY_RUNNING",
+      );
+    }
+
+    const httpServer = createServer((req, res) => {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+      const method = toHttpMethod(req.method ?? "GET");
+      const path = url.pathname;
+
+      const headers: Record<string, string> = {};
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (typeof value === "string") {
+          headers[key] = value;
+        }
+      }
+
+      const query: Record<string, string> = {};
+      url.searchParams.forEach((value, key) => {
+        query[key] = value;
+      });
+
+      const chunks: Buffer[] = [];
+      req.on("data", (chunk: Buffer) => chunks.push(chunk));
+      req.on("end", () => {
+        const raw = Buffer.concat(chunks).toString();
+        let body: unknown;
+        const contentType = headers["content-type"] ?? "";
+        if (raw && contentType.includes("json")) {
+          try {
+            body = JSON.parse(raw);
+          } catch {
+            body = raw;
+          }
+        } else if (raw) {
+          body = raw;
+        }
+
+        void this.handle(method, path, { headers, body, query }).then(
+          (schmockResponse) => {
+            const responseHeaders: Record<string, string> = {
+              ...schmockResponse.headers,
+            };
+            if (
+              !responseHeaders["content-type"] &&
+              schmockResponse.body !== undefined &&
+              typeof schmockResponse.body !== "string"
+            ) {
+              responseHeaders["content-type"] = "application/json";
+            }
+
+            const responseBody =
+              schmockResponse.body === undefined
+                ? undefined
+                : typeof schmockResponse.body === "string"
+                  ? schmockResponse.body
+                  : JSON.stringify(schmockResponse.body);
+
+            res.writeHead(schmockResponse.status, responseHeaders);
+            res.end(responseBody);
+          },
+        );
+      });
+    });
+
+    this.server = httpServer;
+
+    return new Promise((resolve, reject) => {
+      httpServer.on("error", reject);
+      httpServer.listen(port, hostname, () => {
+        const addr = httpServer.address();
+        const actualPort =
+          addr !== null && typeof addr === "object" ? addr.port : port;
+        this.serverInfo = { port: actualPort, hostname };
+        this.logger.log("server", `Listening on ${hostname}:${actualPort}`);
+        resolve(this.serverInfo);
+      });
+    });
+  }
+
+  close(): void {
+    if (!this.server) {
+      return;
+    }
+    this.server.close();
+    this.server = undefined;
+    this.serverInfo = undefined;
+    this.logger.log("server", "Server stopped");
+  }
+
   async handle(
     method: Schmock.HttpMethod,
     path: string,
     options?: Schmock.RequestOptions,
   ): Promise<Schmock.Response> {
     const requestId = crypto.randomUUID();
+    const handleStart = performance.now();
     this.logger.log("request", `[${requestId}] ${method} ${path}`, {
       headers: options?.headers,
       query: options?.query,
@@ -293,6 +436,12 @@ export class CallableMockInstance {
     });
     this.logger.time(`request-${requestId}`);
 
+    this.emit("request:start", {
+      method,
+      path,
+      headers: options?.headers || {},
+    });
+
     try {
       // Apply namespace if configured
       let requestPath = path;
@@ -340,12 +489,19 @@ export class CallableMockInstance {
           "route",
           `[${requestId}] No route found for ${method} ${requestPath}`,
         );
+        this.emit("request:notfound", { method, path: requestPath });
         const error = new RouteNotFoundError(method, path);
         const response = {
           status: 404,
           body: { error: error.message, code: error.code },
           headers: {},
         };
+        this.emit("request:end", {
+          method,
+          path: requestPath,
+          status: 404,
+          duration: performance.now() - handleStart,
+        });
         this.logger.timeEnd(`request-${requestId}`);
         return response;
       }
@@ -358,6 +514,13 @@ export class CallableMockInstance {
       // Extract parameters from the matched route
       const params = this.extractParams(matchedRoute, requestPath);
 
+      this.emit("request:match", {
+        method,
+        path: requestPath,
+        routePath: matchedRoute.path,
+        params,
+      });
+
       // Generate initial response from route handler
       const context: Schmock.RequestContext = {
         method,
@@ -410,8 +573,8 @@ export class CallableMockInstance {
       // Parse and prepare response
       const response = this.parseResponse(result, matchedRoute.config);
 
-      // Apply global delay if configured
-      await this.applyDelay();
+      // Apply delay (route-level overrides global)
+      await this.applyDelay(matchedRoute.config.delay);
 
       // Record request in history
       this.requestHistory.push({
@@ -425,6 +588,13 @@ export class CallableMockInstance {
         response: { status: response.status, body: response.body },
       });
 
+      this.emit("request:end", {
+        method,
+        path: requestPath,
+        status: response.status,
+        duration: performance.now() - handleStart,
+      });
+
       // Log successful response
       this.logger.log(
         "response",
@@ -455,7 +625,7 @@ export class CallableMockInstance {
         headers: {},
       };
 
-      // Apply global delay if configured (even for error responses)
+      // Apply delay even for error responses
       await this.applyDelay();
 
       this.logger.log("error", `[${requestId}] Returning error response 500`);
@@ -469,18 +639,20 @@ export class CallableMockInstance {
    * Supports both fixed delays and random delays within a range
    * @private
    */
-  private async applyDelay(): Promise<void> {
-    if (!this.globalConfig.delay) {
+  private async applyDelay(
+    routeDelay?: number | [number, number],
+  ): Promise<void> {
+    const effectiveDelay = routeDelay ?? this.globalConfig.delay;
+    if (!effectiveDelay) {
       return;
     }
 
-    const delay = Array.isArray(this.globalConfig.delay)
-      ? Math.random() *
-          (this.globalConfig.delay[1] - this.globalConfig.delay[0]) +
-        this.globalConfig.delay[0]
-      : this.globalConfig.delay;
+    const ms = Array.isArray(effectiveDelay)
+      ? Math.random() * (effectiveDelay[1] - effectiveDelay[0]) +
+        effectiveDelay[0]
+      : effectiveDelay;
 
-    await new Promise((resolve) => setTimeout(resolve, delay));
+    await new Promise((resolve) => setTimeout(resolve, ms));
   }
 
   /**

package/src/index.ts

@@ -52,6 +52,18 @@ export function schmock(
       reset: instance.reset.bind(instance),
       resetHistory: instance.resetHistory.bind(instance),
       resetState: instance.resetState.bind(instance),
+      on: ((event: string, listener: (data: unknown) => void) => {
+        instance.on(event, listener);
+        return callableInstance;
+      }) as Schmock.CallableMockInstance["on"],
+      off: ((event: string, listener: (data: unknown) => void) => {
+        instance.off(event, listener);
+        return callableInstance;
+      }) as Schmock.CallableMockInstance["off"],
+      getRoutes: instance.getRoutes.bind(instance),
+      getState: instance.getState.bind(instance),
+      listen: instance.listen.bind(instance),
+      close: instance.close.bind(instance),
     },
   );
 
@@ -97,6 +109,8 @@ export type {
   ResponseBody,
   ResponseResult,
   RouteConfig,
+  RouteInfo,
   RouteKey,
+  ServerInfo,
   StaticData,
 } from "./types.js";

package/src/server.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { schmock } from "./index";
+
+describe("Standalone Server", () => {
+  let mock: Schmock.CallableMockInstance;
+
+  afterEach(() => {
+    mock?.close();
+  });
+
+  it("returns actual port when port=0", async () => {
+    mock = schmock();
+    mock("GET /test", { ok: true });
+    const info = await mock.listen(0);
+    expect(info.port).toBeGreaterThan(0);
+    expect(info.hostname).toBe("127.0.0.1");
+  });
+
+  it("propagates request headers", async () => {
+    mock = schmock();
+    mock("GET /headers", ({ headers }) => ({
+      auth: headers.authorization,
+    }));
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/headers`, {
+      headers: { authorization: "Bearer secret" },
+    });
+    const body = await res.json();
+    expect(body.auth).toBe("Bearer secret");
+  });
+
+  it("handles concurrent requests", async () => {
+    mock = schmock();
+    mock("GET /slow", () => ({ value: "done" }));
+    const info = await mock.listen(0);
+
+    const results = await Promise.all(
+      Array.from({ length: 10 }, () =>
+        fetch(`http://127.0.0.1:${info.port}/slow`).then((r) => r.json()),
+      ),
+    );
+
+    for (const body of results) {
+      expect(body.value).toBe("done");
+    }
+  });
+
+  it("parses text body when content-type is not JSON", async () => {
+    mock = schmock();
+    mock("POST /text", ({ body: reqBody }) => ({ received: reqBody }));
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/text`, {
+      method: "POST",
+      headers: { "content-type": "text/plain" },
+      body: "hello world",
+    });
+    const resBody = await res.json();
+    expect(resBody.received).toBe("hello world");
+  });
+
+  it("returns 204 with no body for undefined response", async () => {
+    mock = schmock();
+    mock("DELETE /item", () => undefined);
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/item`, {
+      method: "DELETE",
+    });
+    expect(res.status).toBe(204);
+  });
+
+  it("reset stops the server", async () => {
+    mock = schmock();
+    mock("GET /test", { ok: true });
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/test`);
+    expect(res.status).toBe(200);
+
+    mock.reset();
+
+    try {
+      await fetch(`http://127.0.0.1:${info.port}/test`);
+      expect.unreachable("Should have thrown");
+    } catch {
+      // Expected: connection refused
+    }
+  });
+
+  it("handles route params in server mode", async () => {
+    mock = schmock();
+    mock("GET /users/:id", ({ params }) => ({ id: params.id }));
+    const info = await mock.listen(0);
+
+    const res = await fetch(`http://127.0.0.1:${info.port}/users/42`);
+    const body = await res.json();
+    expect(body.id).toBe("42");
+  });
+
+  it("double listen throws", async () => {
+    mock = schmock();
+    mock("GET /test", { ok: true });
+    await mock.listen(0);
+    expect(() => mock.listen(0)).toThrow("Server is already running");
+  });
+
+  it("close is idempotent", async () => {
+    mock = schmock();
+    mock("GET /test", { ok: true });
+    await mock.listen(0);
+    mock.close();
+    expect(() => mock.close()).not.toThrow();
+  });
+});

package/src/steps/lifecycle-events.steps.ts

@@ -0,0 +1,142 @@
+import { describeFeature, loadFeature } from "@amiceli/vitest-cucumber";
+import { expect } from "vitest";
+import { schmock } from "../index";
+
+const feature = await loadFeature("../../features/lifecycle-events.feature");
+
+describeFeature(feature, ({ Scenario }) => {
+  let mock: Schmock.CallableMockInstance;
+  let events: Array<{ type: string; data: unknown }>;
+  let removedFired: boolean;
+
+  function collectEvent(type: string) {
+    return (data: unknown) => {
+      events.push({ type, data });
+    };
+  }
+
+  Scenario("Events fire at correct times", ({ Given, And, When, Then }) => {
+    Given('a mock with a route "GET /items"', () => {
+      mock = schmock({ state: {} });
+      mock("GET /items", [{ id: 1 }], {});
+    });
+
+    And("I register listeners for all events", () => {
+      events = [];
+      mock.on("request:start", collectEvent("request:start"));
+      mock.on("request:match", collectEvent("request:match"));
+      mock.on("request:notfound", collectEvent("request:notfound"));
+      mock.on("request:end", collectEvent("request:end"));
+    });
+
+    When('I request "GET /items"', async () => {
+      await mock.handle("GET", "/items");
+    });
+
+    Then('the "request:start" event fired', () => {
+      expect(events.some((e) => e.type === "request:start")).toBe(true);
+    });
+
+    And('the "request:match" event fired with routePath "/items"', () => {
+      const match = events.find((e) => e.type === "request:match");
+      expect(match).toBeDefined();
+      const data = match?.data as Record<string, unknown>;
+      expect(data.routePath).toBe("/items");
+    });
+
+    And('the "request:end" event fired with status 200', () => {
+      const end = events.find((e) => e.type === "request:end");
+      expect(end).toBeDefined();
+      const data = end?.data as Record<string, unknown>;
+      expect(data.status).toBe(200);
+    });
+  });
+
+  Scenario("Not found event fires for unmatched routes", ({ Given, And, When, Then }) => {
+    Given('a mock with a route "GET /items"', () => {
+      mock = schmock({ state: {} });
+      mock("GET /items", [{ id: 1 }], {});
+    });
+
+    And("I register listeners for all events", () => {
+      events = [];
+      mock.on("request:start", collectEvent("request:start"));
+      mock.on("request:match", collectEvent("request:match"));
+      mock.on("request:notfound", collectEvent("request:notfound"));
+      mock.on("request:end", collectEvent("request:end"));
+    });
+
+    When('I request "GET /missing"', async () => {
+      await mock.handle("GET", "/missing");
+    });
+
+    Then('the "request:start" event fired', () => {
+      expect(events.some((e) => e.type === "request:start")).toBe(true);
+    });
+
+    And('the "request:notfound" event fired', () => {
+      expect(events.some((e) => e.type === "request:notfound")).toBe(true);
+    });
+
+    And('the "request:end" event fired with status 404', () => {
+      const end = events.find((e) => e.type === "request:end");
+      expect(end).toBeDefined();
+      const data = end?.data as Record<string, unknown>;
+      expect(data.status).toBe(404);
+    });
+  });
+
+  Scenario("Off removes listener", ({ Given, And, When, Then }) => {
+    Given('a mock with a route "GET /items"', () => {
+      mock = schmock({ state: {} });
+      mock("GET /items", [{ id: 1 }], {});
+    });
+
+    And("I register and remove a listener", () => {
+      removedFired = false;
+      const listener = () => {
+        removedFired = true;
+      };
+      mock.on("request:start", listener);
+      mock.off("request:start", listener);
+    });
+
+    When('I request "GET /items"', async () => {
+      await mock.handle("GET", "/items");
+    });
+
+    Then("the removed listener did not fire", () => {
+      expect(removedFired).toBe(false);
+    });
+  });
+
+  Scenario("Reset clears all listeners", ({ Given, And, When, Then }) => {
+    Given('a mock with a route "GET /items"', () => {
+      mock = schmock({ state: {} });
+      mock("GET /items", [{ id: 1 }], {});
+    });
+
+    And("I register listeners for all events", () => {
+      events = [];
+      mock.on("request:start", collectEvent("request:start"));
+      mock.on("request:end", collectEvent("request:end"));
+    });
+
+    When("I reset the mock", () => {
+      mock.reset();
+      events = [];
+    });
+
+    And('I add a route "GET /items" again', () => {
+      mock("GET /items", [{ id: 1 }], {});
+    });
+
+    And('I request "GET /items" after reset', async () => {
+      await mock.handle("GET", "/items");
+    });
+
+    Then("no events were collected after reset", () => {
+      expect(events).toHaveLength(0);
+    });
+  });
+});

package/src/steps/response-delay.steps.ts

@@ -0,0 +1,85 @@
+import { describeFeature, loadFeature } from "@amiceli/vitest-cucumber";
+import { expect } from "vitest";
+import { schmock } from "../index";
+
+const feature = await loadFeature("../../features/response-delay.feature");
+
+describeFeature(feature, ({ Scenario }) => {
+  let mock: Schmock.CallableMockInstance;
+  let elapsed: number;
+  let elapsed2: number;
+
+  Scenario("Route delay overrides global delay", ({ Given, And, When, Then }) => {
+    Given("a mock with global delay of 200ms", () => {
+      mock = schmock({ delay: 200, state: {} });
+    });
+
+    And('a route "GET /fast" with delay of 10ms', () => {
+      mock("GET /fast", { ok: true }, { delay: 10 });
+    });
+
+    And('a route "GET /default" with no delay override', () => {
+      mock("GET /default", { ok: true }, {});
+    });
+
+    When('I request "GET /fast"', async () => {
+      const start = performance.now();
+      await mock.handle("GET", "/fast");
+      elapsed = performance.now() - start;
+    });
+
+    Then("the response took less than 100ms", () => {
+      expect(elapsed).toBeLessThan(100);
+    });
+
+    When('I request "GET /default" with timing', async () => {
+      const start = performance.now();
+      await mock.handle("GET", "/default");
+      elapsed2 = performance.now() - start;
+    });
+
+    Then("that response took at least 150ms", () => {
+      expect(elapsed2).toBeGreaterThanOrEqual(150);
+    });
+  });
+
+  Scenario("Route delay supports random range", ({ Given, And, When, Then }) => {
+    Given("a mock with no global delay", () => {
+      mock = schmock({ state: {} });
+    });
+
+    And('a route "GET /random" with delay range 10 to 30', () => {
+      mock("GET /random", { ok: true }, { delay: [10, 30] });
+    });
+
+    When('I request "GET /random"', async () => {
+      const start = performance.now();
+      await mock.handle("GET", "/random");
+      elapsed = performance.now() - start;
+    });
+
+    Then("the response took at least 10ms", () => {
+      expect(elapsed).toBeGreaterThanOrEqual(8); // small tolerance
+    });
+  });
+
+  Scenario("No route delay inherits global delay", ({ Given, And, When, Then }) => {
+    Given("a mock with global delay of 50ms", () => {
+      mock = schmock({ delay: 50, state: {} });
+    });
+
+    And('a route "GET /items" with no delay override', () => {
+      mock("GET /items", { ok: true }, {});
+    });
+
+    When('I request "GET /items" with timing', async () => {
+      const start = performance.now();
+      await mock.handle("GET", "/items");
+      elapsed = performance.now() - start;
+    });
+
+    Then("that response took at least 40ms", () => {
+      expect(elapsed).toBeGreaterThanOrEqual(40);
+    });
+  });
+});

package/src/steps/standalone-server.steps.ts

@@ -0,0 +1,233 @@
+import { describeFeature, loadFeature } from "@amiceli/vitest-cucumber";
+import { expect } from "vitest";
+import { schmock } from "../index";
+
+const feature = await loadFeature("../../features/standalone-server.feature");
+
+describeFeature(feature, ({ Scenario }) => {
+  let mock: Schmock.CallableMockInstance;
+  let serverInfo: Schmock.ServerInfo;
+  let httpResponse: Response;
+
+  function baseUrl(): string {
+    return `http://${serverInfo.hostname}:${serverInfo.port}`;
+  }
+
+  Scenario("Start and stop a simple server", ({ Given, When, Then, And }) => {
+    Given("I create a mock with a GET /hello route", () => {
+      mock = schmock();
+      mock("GET /hello", { message: "hello" });
+    });
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    Then("the server should be running", () => {
+      expect(serverInfo.port).toBeGreaterThan(0);
+    });
+
+    When("I fetch {string} from the server", async (_, route: string) => {
+      const [, path] = route.split(" ");
+      httpResponse = await fetch(`${baseUrl()}${path}`);
+    });
+
+    Then("the HTTP response status should be {int}", (_, status: number) => {
+      expect(httpResponse.status).toBe(status);
+    });
+
+    And(
+      "the HTTP response body should have {string} equal to {string}",
+      async (_, key: string, value: string) => {
+        const body = await httpResponse.json();
+        expect(body[key]).toBe(value);
+      },
+    );
+
+    When("I stop the server", () => {
+      mock.close();
+    });
+
+    Then("the server should not be running", async () => {
+      try {
+        await fetch(`${baseUrl()}/hello`);
+        expect.unreachable("Should not be able to connect");
+      } catch {
+        // Connection refused — server is down
+      }
+    });
+  });
+
+  Scenario("Handle POST with JSON body", ({ Given, When, Then, And }) => {
+    Given("I create a mock echoing POST at {string}", (_, path: string) => {
+      mock = schmock();
+      mock(`POST ${path}`, ({ body }) => body);
+    });
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    And(
+      "I fetch {string} with JSON body:",
+      async (_, route: string, docString: string) => {
+        const [method, path] = route.split(" ");
+        httpResponse = await fetch(`${baseUrl()}${path}`, {
+          method,
+          headers: { "content-type": "application/json" },
+          body: docString,
+        });
+      },
+    );
+
+    Then(
+      "the response status from POST should be {int}",
+      (_, status: number) => {
+        expect(httpResponse.status).toBe(status);
+      },
+    );
+
+    And(
+      "the response body from POST should have {string} equal to {string}",
+      async (_, key: string, value: string) => {
+        const body = await httpResponse.json();
+        expect(body[key]).toBe(value);
+      },
+    );
+
+    When("I stop the server", () => {
+      mock.close();
+    });
+  });
+
+  Scenario(
+    "Return 404 for unregistered routes",
+    ({ Given, When, And, Then }) => {
+      Given("I create a mock with a GET /hello route", () => {
+        mock = schmock();
+        mock("GET /hello", { message: "hello" });
+      });
+
+      When("I start the server on a random port", async () => {
+        serverInfo = await mock.listen(0);
+      });
+
+      And("I fetch {string} from the server", async (_, route: string) => {
+        const [, path] = route.split(" ");
+        httpResponse = await fetch(`${baseUrl()}${path}`);
+      });
+
+      Then("the HTTP response status should be {int}", (_, status: number) => {
+        expect(httpResponse.status).toBe(status);
+      });
+
+      When("I stop the server", () => {
+        mock.close();
+      });
+    },
+  );
+
+  Scenario("Query parameters are forwarded", ({ Given, When, And, Then }) => {
+    let parsedBody: Record<string, string>;
+
+    Given(
+      "I create a mock reflecting query params at {string}",
+      (_, route: string) => {
+        const [method, path] = route.split(" ");
+        mock = schmock();
+        mock(`${method} ${path}` as Schmock.RouteKey, ({ query }) => query);
+      },
+    );
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    And("I fetch {string} from the server", async (_, route: string) => {
+      const [, pathWithQuery] = route.split(" ");
+      httpResponse = await fetch(`${baseUrl()}${pathWithQuery}`);
+      parsedBody = await httpResponse.json();
+    });
+
+    Then("the HTTP response status should be {int}", (_, status: number) => {
+      expect(httpResponse.status).toBe(status);
+    });
+
+    And(
+      "the HTTP response body should have {string} equal to {string}",
+      (_, key: string, value: string) => {
+        expect(parsedBody[key]).toBe(value);
+      },
+    );
+
+    And(
+      "the query param {string} should equal {string}",
+      (_, key: string, value: string) => {
+        expect(parsedBody[key]).toBe(value);
+      },
+    );
+
+    When("I stop the server", () => {
+      mock.close();
+    });
+  });
+
+  Scenario("Double listen throws an error", ({ Given, When, Then }) => {
+    Given("I create a mock with a GET /hello route", () => {
+      mock = schmock();
+      mock("GET /hello", { message: "hello" });
+    });
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    Then("starting the server again should throw", () => {
+      expect(() => mock.listen(0)).toThrow("Server is already running");
+      mock.close();
+    });
+  });
+
+  Scenario("Close is idempotent", ({ Given, When, And, Then }) => {
+    Given("I create a mock with a GET /hello route", () => {
+      mock = schmock();
+      mock("GET /hello", { message: "hello" });
+    });
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    And("I stop the server", () => {
+      mock.close();
+    });
+
+    Then("stopping the server again should not throw", () => {
+      expect(() => mock.close()).not.toThrow();
+    });
+  });
+
+  Scenario("Reset stops the server", ({ Given, When, And, Then }) => {
+    Given("I create a mock with a GET /hello route", () => {
+      mock = schmock();
+      mock("GET /hello", { message: "hello" });
+    });
+
+    When("I start the server on a random port", async () => {
+      serverInfo = await mock.listen(0);
+    });
+
+    And("I reset the mock", () => {
+      mock.reset();
+    });
+
+    Then("the server should not be running", async () => {
+      try {
+        await fetch(`${baseUrl()}/hello`);
+        expect.unreachable("Should not be able to connect");
+      } catch {
+        // Connection refused — server is down
+      }
+    });
+  });
+});

package/src/types.ts

@@ -1,6 +1,6 @@
-/// <reference path="../../../types/schmock.d.ts" />
+/// <reference path="../schmock.d.ts" />
 
-// Re-export types for internal use
+// Re-export ambient types for consumers
 export type HttpMethod = Schmock.HttpMethod;
 export type RouteKey = Schmock.RouteKey;
 export type ResponseBody = Schmock.ResponseBody;
@@ -18,3 +18,5 @@ export type PluginContext = Schmock.PluginContext;
 export type PluginResult = Schmock.PluginResult;
 export type StaticData = Schmock.StaticData;
 export type RequestRecord = Schmock.RequestRecord;
+export type ServerInfo = Schmock.ServerInfo;
+export type RouteInfo = Schmock.RouteInfo;

package/src/builder.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["builder.ts"],"names":[],"mappings":"AAAA,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;AAW7B,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EAEb,YAAY,EAGZ,MAAM,EACP,MAAM,SAAS,CAAC;AAajB;;;;GAIG;AACH,qBAAa,cAAc,CAAC,MAAM,GAAG,OAAO,CAAE,YAAW,OAAO,CAAC,MAAM,CAAC;IACtE,OAAO,CAAC,OAAO,CAEb;IAEF,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAShC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKpC,KAAK,IAAI,YAAY,CAAC,MAAM,CAAC;IAQ7B;;;OAGG;IACH,OAAO,CAAC,aAAa;CA0BtB"}

package/src/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAGnB,IAAI,EAAE,MAAM;aACZ,OAAO,CAAC,EAAE,OAAO;gBAFjC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,YAAA;CAMpC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAQzC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,YAAY;gBACnC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQ7C;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;gBAC3C,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAQxC;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,YAAY;gBAC/B,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAQ7C;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQ7C;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAQnE;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,OAAO;CAQ1D;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAQ7D"}

package/src/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAGD,YAAY,EACV,OAAO,EACP,aAAa,EACb,UAAU,EACV,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,QAAQ,EACR,MAAM,GACP,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,UAAU,CAAC"}

package/src/parser.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAuC3D"}

package/src/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;AAC5C,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;AACxC,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;AAClD,MAAM,MAAM,eAAe,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;AACtE,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;AACpD,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;AACxE,MAAM,MAAM,eAAe,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;AACtE,MAAM,MAAM,MAAM,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACpD,MAAM,MAAM,OAAO,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACtD,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC"}