llm-mock-server 1.0.4 → 1.0.6

package/src/types/request.ts

@@ -1,32 +1,45 @@
 /** The LLM API wire format that was detected for a request. */
 export type FormatName = "openai" | "anthropic" | "responses";
 
-/** A normalised view of an incoming request, regardless of the original wire format. */
+/**
+ * A normalised view of an incoming request, regardless of the original wire format.
+ * This is what rule matchers and resolvers receive.
+ */
 export interface MockRequest {
+  /** Which API format route the request came in on. */
   readonly format: FormatName;
+  /** The model string from the request, e.g. `"gpt-5.4"` or `"claude-sonnet-4-6"`. */
   readonly model: string;
+  /**
+   * Whether the client asked for SSE streaming (from the `stream` field).
+   * @defaultValue `true`
+   */
   readonly streaming: boolean;
   /** Full conversation, normalised from whatever format came in. */
   readonly messages: readonly Message[];
   /** The last user message's text. This is what most matchers check. */
   readonly lastMessage: string;
-  /** Empty string if there wasn't one. */
+  /** System prompt text, or empty string if there wasn't one. */
   readonly systemMessage: string;
+  /** Tool definitions from the request, if any were sent. */
   readonly tools?: readonly ToolDef[] | undefined;
-  /** Pulled out from `tools` for quick lookups. */
+  /** Tool names pulled out from `tools` for quick lookups via `whenTool()`. */
   readonly toolNames: readonly string[];
-  /** Set when the last message was a tool result. */
+  /** Set when the last message was a tool result. Used by `whenToolResult()`. */
   readonly lastToolCallId: string | undefined;
   /** The raw request body, for anything we don't extract. */
   readonly raw: unknown;
+  /** HTTP headers from the incoming request. */
   readonly headers: Readonly<Record<string, string | undefined>>;
-  /** e.g. `/v1/chat/completions` */
+  /** The URL path that was hit, e.g. `/v1/chat/completions`. */
   readonly path: string;
 }
 
 /** A single conversation message, normalised across all supported formats. */
 export interface Message {
+  /** The role of the message sender. */
   readonly role: "system" | "user" | "assistant" | "tool";
+  /** The text content of the message. */
   readonly content: string;
   /** Links the result back to its tool call. Only set on `"tool"` messages. */
   readonly toolCallId?: string | undefined;
@@ -34,8 +47,10 @@ export interface Message {
 
 /** A tool definition from the request's `tools` array, normalised across formats. */
 export interface ToolDef {
+  /** The tool function name. */
   readonly name: string;
+  /** A description of what the tool does. */
   readonly description?: string | undefined;
-  /** JSON Schema, passed through as-is. */
+  /** JSON Schema for the tool's parameters, passed through as-is. */
   readonly parameters?: unknown;
 }

package/src/types/rule.ts

@@ -8,6 +8,14 @@ import type { Resolver, ReplyOptions, Reply, SequenceEntry } from "./reply.js";
  * A `RegExp` gets tested against the last user message.
  * A `MatchObject` checks multiple fields at once with AND logic.
  * A function receives the normalised request and returns a boolean.
+ *
+ * @example
+ * ```ts
+ * server.when("hello").reply("Hi!");
+ * server.when(/explain (\w+)/i).reply("Here's an explanation.");
+ * server.when({ model: /claude/, format: "anthropic" }).reply("Bonjour!");
+ * server.when((req) => req.messages.length > 5).reply("Long conversation!");
+ * ```
  */
 export type Match =
   | string
@@ -15,46 +23,96 @@ export type Match =
   | MatchObject
   | ((req: MockRequest) => boolean);
 
-/** A structured matcher. Every field you set must match for the rule to fire. */
+/**
+ * A structured matcher. Every field you set must match for the rule to fire.
+ *
+ * @example
+ * ```ts
+ * server.when({
+ *   model: /gpt/,
+ *   format: "openai",
+ *   system: /translator/i,
+ *   predicate: (req) => req.messages.length > 2,
+ * }).reply("Translated output.");
+ * ```
+ */
 export interface MatchObject {
+  /** Substring or regex against the last user message. */
   readonly message?: string | RegExp;
+  /** Substring or regex against the model name. */
   readonly model?: string | RegExp;
+  /** Substring or regex against the system prompt. */
   readonly system?: string | RegExp;
+  /** Only match requests from this API format. */
   readonly format?: FormatName;
   /** Match when the request includes a tool definition with this name. */
   readonly toolName?: string;
   /** Match when the last tool-result message has this `tool_call_id`. */
   readonly toolCallId?: string;
-  /** Extra check that runs after all other fields pass. */
+  /** Extra predicate that runs after all other fields pass. */
   readonly predicate?: (req: MockRequest) => boolean;
 }
 
-/** Returned by `when()`. Call `.reply()` or `.replySequence()` on it to complete the rule. */
+/**
+ * Returned by `when()`. Call `.reply()` or `.replySequence()` on it to complete the rule.
+ *
+ * @example
+ * ```ts
+ * server.when("hello").reply("Hi!");
+ * server.when("step").replySequence(["First.", "Second.", "Done."]);
+ * ```
+ */
 export interface PendingRule {
+  /** Set the response for this rule. Accepts a static value, object, or resolver function. */
   reply(response: Resolver, options?: ReplyOptions): RuleHandle;
-  /** Each match advances through the array. The last entry repeats once exhausted. */
+  /** Set a sequence of replies. Each match advances through the array. */
   replySequence(entries: readonly SequenceEntry[]): RuleHandle;
 }
 
-/** A handle to a registered rule. All methods return `this` for chaining. */
+/**
+ * A handle to a registered rule. All methods return `this` for chaining.
+ *
+ * @example
+ * ```ts
+ * server.when("hello").reply("Hi!").times(3);
+ * server.when("urgent").reply("On it!").first();
+ * ```
+ */
 export interface RuleHandle {
+  /** Auto-expire the rule after `n` matches. */
   times(n: number): RuleHandle;
+  /** Move this rule to the front of the list so it matches first. */
   first(): RuleHandle;
 }
 
 /**
  * The shape of a handler file's default export.
  * You can export a single handler or an array of them.
+ *
+ * @example
+ * ```ts
+ * import type { Handler } from "llm-mock-server";
+ * export default {
+ *   match: (req) => req.lastMessage.includes("echo"),
+ *   respond: (req) => `Echo: ${req.lastMessage}`,
+ * } satisfies Handler;
+ * ```
  */
 export interface Handler {
+  /** Return `true` if this handler should respond to the request. */
   match: (req: MockRequest) => boolean;
+  /** Produce the reply for a matched request. Can be async. */
   respond: (req: MockRequest) => Reply | Promise<Reply>;
 }
 
-/** A summary of a registered rule, for inspection. */
+/** A summary of a registered rule, for inspection via `server.rules`. */
 export interface RuleSummary {
+  /** Human-readable description of what the rule matches. */
   readonly description: string;
-  /** `Infinity` means unlimited. */
+  /**
+   * How many matches are left.
+   * @defaultValue `Infinity` (unlimited)
+   */
   readonly remaining: number;
 }
 

package/test/cli-validators.test.ts

@@ -5,7 +5,7 @@ import {
   parseChunkSize,
   parseLogLevel,
   parseLatency,
-} from "../src/cli-validators.js";
+} from "#/cli/validators.js";
 
 describe("parsePort", () => {
   it("parses a valid port", () => {
@@ -40,8 +40,12 @@ describe("parsePort", () => {
     expect(() => parsePort("")).toThrow('Invalid port ""');
   });
 
-  it("truncates floating point to integer", () => {
-    expect(parsePort("80.5")).toBe(80);
+  it("throws on floating point", () => {
+    expect(() => parsePort("80.5")).toThrow('Invalid port "80.5"');
+  });
+
+  it("throws on numeric string with trailing chars", () => {
+    expect(() => parsePort("80abc")).toThrow('Invalid port "80abc"');
   });
 });
 
@@ -119,8 +123,12 @@ describe("parseLatency", () => {
     expect(() => parseLatency("")).toThrow('Invalid latency ""');
   });
 
-  it("truncates floating point to integer", () => {
-    expect(parseLatency("50.7")).toBe(50);
+  it("throws on floating point", () => {
+    expect(() => parseLatency("50.7")).toThrow('Invalid latency "50.7"');
+  });
+
+  it("throws on numeric string with trailing chars", () => {
+    expect(() => parseLatency("50abc")).toThrow('Invalid latency "50abc"');
   });
 });
 

package/test/formats/openai.test.ts

@@ -1,10 +1,10 @@
 import { describe, it, expect } from "vitest";
-import { openaiFormat } from "../../src/formats/openai/index.js";
+import { chatCompletionsFormat } from "../../src/formats/openai/chat-completions/index.js";
 import type {
   OpenAIChunk,
   OpenAIComplete,
   OpenAIError,
-} from "../../src/formats/openai/schema.js";
+} from "../../src/formats/openai/chat-completions/schema.js";
 
 function parse<T>(chunk: { data: string }): T {
   return JSON.parse(chunk.data) as T;
@@ -13,7 +13,7 @@ function parse<T>(chunk: { data: string }): T {
 describe("OpenAI Format", () => {
   describe("parseRequest", () => {
     it("parses a basic chat completion request", () => {
-      const req = openaiFormat.parseRequest({
+      const req = chatCompletionsFormat.parseRequest({
         model: "gpt-5.4",
         messages: [
           { role: "system", content: "You are helpful" },
@@ -30,7 +30,7 @@ describe("OpenAI Format", () => {
     });
 
     it("defaults stream to true", () => {
-      const req = openaiFormat.parseRequest({
+      const req = chatCompletionsFormat.parseRequest({
         model: "gpt-5.4",
         messages: [{ role: "user", content: "hi" }],
       });
@@ -38,7 +38,7 @@ describe("OpenAI Format", () => {
     });
 
     it("detects stream: false", () => {
-      const req = openaiFormat.parseRequest({
+      const req = chatCompletionsFormat.parseRequest({
         model: "gpt-5.4",
         messages: [{ role: "user", content: "hi" }],
         stream: false,
@@ -47,7 +47,7 @@ describe("OpenAI Format", () => {
     });
 
     it("parses tools with function wrapper", () => {
-      const req = openaiFormat.parseRequest({
+      const req = chatCompletionsFormat.parseRequest({
         model: "gpt-5.4",
         messages: [{ role: "user", content: "read file" }],
         tools: [
@@ -66,7 +66,7 @@ describe("OpenAI Format", () => {
     });
 
     it("extracts toolNames from tools array", () => {
-      const req = openaiFormat.parseRequest({
+      const req = chatCompletionsFormat.parseRequest({
         model: "gpt-5.4",
         messages: [{ role: "user", content: "hi" }],
         tools: [
@@ -78,7 +78,7 @@ describe("OpenAI Format", () => {
     });
 
     it("extracts lastToolCallId from tool messages", () => {
-      const req = openaiFormat.parseRequest({
+      const req = chatCompletionsFormat.parseRequest({
         model: "gpt-5.4",
         messages: [
           { role: "user", content: "hi" },
@@ -89,7 +89,7 @@ describe("OpenAI Format", () => {
     });
 
     it("handles non-string content (array of content parts)", () => {
-      const req = openaiFormat.parseRequest({
+      const req = chatCompletionsFormat.parseRequest({
         model: "gpt-5.4",
         messages: [
           { role: "user", content: [{ type: "text", text: "Hello" }] },
@@ -100,7 +100,7 @@ describe("OpenAI Format", () => {
 
     it("rejects requests with invalid role values", () => {
       expect(() =>
-        openaiFormat.parseRequest({
+        chatCompletionsFormat.parseRequest({
           model: "gpt-5.4",
           messages: [{ role: "banana", content: "hi" }],
         }),
@@ -109,7 +109,7 @@ describe("OpenAI Format", () => {
 
     it("rejects requests missing model", () => {
       expect(() =>
-        openaiFormat.parseRequest({
+        chatCompletionsFormat.parseRequest({
           messages: [{ role: "user", content: "hi" }],
         }),
       ).toThrow();
@@ -118,14 +118,20 @@ describe("OpenAI Format", () => {
 
   describe("serialize (streaming)", () => {
     it("starts with role delta and ends with [DONE]", () => {
-      const chunks = openaiFormat.serialize({ text: "Hello world" }, "gpt-5.4");
+      const chunks = chatCompletionsFormat.serialize(
+        { text: "Hello world" },
+        "gpt-5.4",
+      );
       const first = parse<OpenAIChunk>(chunks[0]!);
       expect(first.choices[0]!.delta).toEqual({ role: "assistant" });
       expect(chunks.at(-1)!.data).toBe("[DONE]");
     });
 
     it("content delta has correct structure", () => {
-      const chunks = openaiFormat.serialize({ text: "Hello world" }, "gpt-5.4");
+      const chunks = chatCompletionsFormat.serialize(
+        { text: "Hello world" },
+        "gpt-5.4",
+      );
       const content = parse<OpenAIChunk>(chunks[1]!);
       expect(content.object).toBe("chat.completion.chunk");
       expect(content.model).toBe("gpt-5.4");
@@ -134,13 +140,16 @@ describe("OpenAI Format", () => {
     });
 
     it("finish chunk has finish_reason: stop for text", () => {
-      const chunks = openaiFormat.serialize({ text: "Hello" }, "gpt-5.4");
+      const chunks = chatCompletionsFormat.serialize(
+        { text: "Hello" },
+        "gpt-5.4",
+      );
       const finish = parse<OpenAIChunk>(chunks.at(-3)!);
       expect(finish.choices[0]!.finish_reason).toBe("stop");
     });
 
     it("finish chunk has finish_reason: tool_calls for tools", () => {
-      const chunks = openaiFormat.serialize(
+      const chunks = chatCompletionsFormat.serialize(
         { tools: [{ name: "read_file", args: { path: "/tmp" } }] },
         "gpt-5.4",
       );
@@ -149,7 +158,7 @@ describe("OpenAI Format", () => {
     });
 
     it("includes usage chunk before [DONE]", () => {
-      const chunks = openaiFormat.serialize(
+      const chunks = chatCompletionsFormat.serialize(
         { text: "Hello", usage: { input: 10, output: 5 } },
         "gpt-5.4",
       );
@@ -166,7 +175,7 @@ describe("OpenAI Format", () => {
     });
 
     it("tool call delta has correct structure", () => {
-      const chunks = openaiFormat.serialize(
+      const chunks = chatCompletionsFormat.serialize(
         { tools: [{ name: "read_file", args: { path: "/tmp" } }] },
         "gpt-5.4",
       );
@@ -183,14 +192,14 @@ describe("OpenAI Format", () => {
     });
 
     it("no named events (openai uses data-only SSE)", () => {
-      const chunks = openaiFormat.serialize({ text: "hi" }, "gpt-5.4");
+      const chunks = chatCompletionsFormat.serialize({ text: "hi" }, "gpt-5.4");
       for (const chunk of chunks) {
         expect(chunk.event).toBeUndefined();
       }
     });
 
     it("splits text into multiple delta chunks with chunkSize", () => {
-      const chunks = openaiFormat.serialize(
+      const chunks = chatCompletionsFormat.serialize(
         { text: "Hello, world!" },
         "gpt-5.4",
         { chunkSize: 5 },
@@ -204,7 +213,10 @@ describe("OpenAI Format", () => {
     });
 
     it("all chunks share same id and created timestamp", () => {
-      const chunks = openaiFormat.serialize({ text: "Hello" }, "gpt-5.4");
+      const chunks = chatCompletionsFormat.serialize(
+        { text: "Hello" },
+        "gpt-5.4",
+      );
       const dataChunks = chunks
         .filter((c) => c.data !== "[DONE]")
         .map((c) => parse<OpenAIChunk>(c));
@@ -217,7 +229,7 @@ describe("OpenAI Format", () => {
 
   describe("serializeComplete (non-streaming)", () => {
     it("produces correct top-level structure", () => {
-      const result = openaiFormat.serializeComplete(
+      const result = chatCompletionsFormat.serializeComplete(
         { text: "Hello, world!" },
         "gpt-5.4",
       ) as OpenAIComplete;
@@ -228,7 +240,7 @@ describe("OpenAI Format", () => {
     });
 
     it("message has correct content and finish_reason", () => {
-      const result = openaiFormat.serializeComplete(
+      const result = chatCompletionsFormat.serializeComplete(
         { text: "Hello, world!" },
         "gpt-5.4",
       ) as OpenAIComplete;
@@ -238,7 +250,7 @@ describe("OpenAI Format", () => {
     });
 
     it("includes tool_calls with correct structure", () => {
-      const result = openaiFormat.serializeComplete(
+      const result = chatCompletionsFormat.serializeComplete(
         { tools: [{ name: "read_file", args: { path: "/tmp" } }] },
         "gpt-5.4",
       ) as OpenAIComplete;
@@ -250,7 +262,7 @@ describe("OpenAI Format", () => {
     });
 
     it("includes usage tokens with details", () => {
-      const result = openaiFormat.serializeComplete(
+      const result = chatCompletionsFormat.serializeComplete(
         { text: "hi", usage: { input: 20, output: 15 } },
         "gpt-5.4",
       ) as OpenAIComplete;
@@ -264,7 +276,7 @@ describe("OpenAI Format", () => {
     });
 
     it("includes service_tier and system_fingerprint", () => {
-      const result = openaiFormat.serializeComplete(
+      const result = chatCompletionsFormat.serializeComplete(
         { text: "hi" },
         "gpt-5.4",
       ) as OpenAIComplete;
@@ -273,7 +285,7 @@ describe("OpenAI Format", () => {
     });
 
     it("includes logprobs: null on choices", () => {
-      const result = openaiFormat.serializeComplete(
+      const result = chatCompletionsFormat.serializeComplete(
         { text: "hi" },
         "gpt-5.4",
       ) as OpenAIComplete;
@@ -283,7 +295,7 @@ describe("OpenAI Format", () => {
 
   describe("serializeError", () => {
     it("produces OpenAI error format", () => {
-      const result = openaiFormat.serializeError({
+      const result = chatCompletionsFormat.serializeError({
         status: 429,
         message: "Rate limited",
         type: "rate_limit_error",
@@ -294,7 +306,7 @@ describe("OpenAI Format", () => {
     });
 
     it("defaults type to server_error", () => {
-      const result = openaiFormat.serializeError({
+      const result = chatCompletionsFormat.serializeError({
         status: 500,
         message: "Internal",
       }) as OpenAIError;

package/test/formats/responses.test.ts

@@ -1,10 +1,10 @@
 import { describe, it, expect } from "vitest";
-import { responsesFormat } from "../../src/formats/responses/index.js";
+import { responsesFormat } from "../../src/formats/openai/responses/index.js";
 import type {
   ResponsesEvent,
   ResponsesComplete,
   ResponsesError,
-} from "../../src/formats/responses/schema.js";
+} from "../../src/formats/openai/responses/schema.js";
 
 function parse<T>(chunk: { data: string }): T {
   return JSON.parse(chunk.data) as T;

package/test/history.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import { RequestHistory, type RecordedRequest } from "../src/history.js";
+import { RequestHistory, type RecordedRequest } from "#/history.js";
 import { makeReq } from "./helpers/make-req.js";
 
 describe("RequestHistory", () => {

package/test/loader.test.ts

@@ -1,9 +1,9 @@
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { writeFile, mkdir, rm } from "node:fs/promises";
 import { join } from "node:path";
-import { RuleEngine } from "../src/rule-engine.js";
-import { loadRulesFromPath } from "../src/loader.js";
-import type { MockRequest } from "../src/types.js";
+import { RuleEngine } from "#/rule-engine.js";
+import { loadRulesFromPath } from "#/loader.js";
+import type { MockRequest } from "#/types.js";
 import { makeReq } from "./helpers/make-req.js";
 
 const tmpDir = join(import.meta.dirname, ".tmp-loader-test");

package/test/logger.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, afterEach } from "vitest";
-import { Logger, LEVEL_PRIORITY } from "../src/logger.js";
-import type { LogLevel } from "../src/logger.js";
+import { Logger, LEVEL_PRIORITY } from "#/logger.js";
+import type { LogLevel } from "#/logger.js";
 
 afterEach(() => {
   vi.restoreAllMocks();

package/test/mock-server.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { createMock, MockServer } from "../src/index.js";
+import { createMock, MockServer } from "#/index.js";
 
 interface OpenAIResponse {
   choices: {

package/test/rule-engine.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import { RuleEngine } from "../src/rule-engine.js";
+import { RuleEngine } from "#/rule-engine.js";
 import { makeReq } from "./helpers/make-req.js";
 
 describe("RuleEngine", () => {

package/tsconfig.json

@@ -1,16 +1,14 @@
 {
   "compilerOptions": {
-    "target": "ES2024",
+    "target": "ES2025",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
-    "lib": ["ES2024"],
+    "lib": ["ES2025"],
     "outDir": "./dist",
     "rootDir": "./src",
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
-    "strict": true,
-    "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "verbatimModuleSyntax": true,

package/typedoc.json

@@ -0,0 +1,9 @@
+{
+  "plugin": ["typedoc-theme-oxide"],
+  "theme": "oxide",
+  "entryPoints": ["src/index.ts"],
+  "out": "./docs/api",
+  "readme": "./README.md",
+  "excludePrivate": true,
+  "excludeInternal": true
+}