@schmock/core 2.0.3 → 2.1.1

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./schmock.d.ts" />
 /**
  * Create a new Schmock mock instance with callable API.
  *

package/dist/interceptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":"AAoHA;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,CACN,MAAM,EAAE,OAAO,CAAC,UAAU,EAC1B,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,OAAO,CAAC,cAAc,KACpC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,EAC9B,OAAO,GAAE,OAAO,CAAC,gBAAqB,GACrC,OAAO,CAAC,eAAe,CAiJzB"}
+{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":"AA2JA;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,CACN,MAAM,EAAE,OAAO,CAAC,UAAU,EAC1B,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,OAAO,CAAC,cAAc,KACpC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,EAC9B,OAAO,GAAE,OAAO,CAAC,gBAAqB,GACrC,OAAO,CAAC,eAAe,CA0JzB"}

package/dist/interceptor.js

@@ -19,6 +19,43 @@ function extractPathname(url) {
     }
     return urlWithoutQuery;
 }
+/**
+ * Extract origin (scheme + host + port) from a URL string, or null for
+ * relative URLs that don't carry one.
+ */
+function extractOrigin(url) {
+    if (!url.includes("://"))
+        return null;
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse the user-supplied baseUrl option into its origin and path parts.
+ * - "/api"                  → { origin: null, path: "/api" }
+ * - "https://x.com/api/v1"  → { origin: "https://x.com", path: "/api/v1" }
+ * - "https://x.com"         → { origin: "https://x.com", path: "" }
+ *
+ * Trailing slash is stripped from the path so the segment-boundary check
+ * works the same way for "/api" and "/api/".
+ */
+function parseBaseUrl(baseUrl) {
+    if (baseUrl.includes("://")) {
+        try {
+            const parsed = new URL(baseUrl);
+            const rawPath = parsed.pathname;
+            const path = rawPath === "/" ? "" : rawPath.replace(/\/$/, "");
+            return { origin: parsed.origin, path };
+        }
+        catch {
+            // Fall through to path-only handling
+        }
+    }
+    return { origin: null, path: baseUrl.replace(/\/$/, "") };
+}
 /**
  * Extract query parameters from a URL string.
  */
@@ -114,15 +151,25 @@ export function createFetchInterceptor(handle, options = {}) {
                 ? input.href
                 : input;
         const path = extractPathname(urlString);
-        // BaseUrl filter — non-matching requests go straight to real fetch
-        // Enforce segment boundary: /api must not match /apiv2
+        // BaseUrl filter — non-matching requests go straight to real fetch.
+        // Two modes:
+        //   - origin form ("https://api.example.com/v1"): require matching
+        //     origin AND matching path prefix.
+        //   - path form ("/api"): match pathname prefix only.
+        // Both enforce a segment boundary so "/api" doesn't match "/apiv2".
         if (baseUrl) {
-            const normalizedBase = baseUrl.endsWith("/")
-                ? baseUrl.slice(0, -1)
-                : baseUrl;
-            const isMatch = path === normalizedBase || path.startsWith(`${normalizedBase}/`);
-            if (!isMatch) {
-                return originalFetch(input, init);
+            const { origin: baseOrigin, path: basePath } = parseBaseUrl(baseUrl);
+            if (baseOrigin) {
+                const reqOrigin = extractOrigin(urlString);
+                if (reqOrigin !== baseOrigin) {
+                    return originalFetch(input, init);
+                }
+            }
+            if (basePath) {
+                const isMatch = path === basePath || path.startsWith(`${basePath}/`);
+                if (!isMatch) {
+                    return originalFetch(input, init);
+                }
             }
         }
         // Build adapter request

package/dist/schmock.d.ts

@@ -0,0 +1,692 @@
+/**
+ * Schmock - Schema-driven mock API generator with callable API
+ * @packageDocumentation
+ */
+
+declare namespace Schmock {
+  type JSONSchema7 = import("json-schema").JSONSchema7;
+  /**
+   * HTTP methods supported by Schmock
+   */
+  type HttpMethod =
+    | "GET"
+    | "POST"
+    | "PUT"
+    | "DELETE"
+    | "PATCH"
+    | "HEAD"
+    | "OPTIONS";
+
+  /**
+   * Route key format: 'METHOD /path'
+   *
+   * @example
+   * 'GET /users'
+   * 'POST /users/:id'
+   * 'DELETE /api/posts/:postId/comments/:commentId'
+   */
+  type RouteKey = `${HttpMethod} ${string}`;
+  
+  /**
+   * Plugin interface for extending Schmock functionality
+   */
+  interface Plugin {
+    /** Unique plugin identifier */
+    name: string;
+    /** Plugin version (semver) */
+    version?: string;
+
+    /**
+     * Called once when the plugin is added via .pipe()
+     * Use this to register routes or configure the instance at setup time
+     * @param instance - The callable mock instance
+     */
+    install?(instance: CallableMockInstance): void;
+
+    /**
+     * Process the request through this plugin
+     * First plugin to set response becomes the generator, others transform
+     * @param context - Plugin context with request details
+     * @param response - Response from previous plugin (if any)
+     * @returns Updated context and response
+     */
+    process(context: PluginContext, response?: unknown): PluginResult | Promise<PluginResult>;
+
+    /**
+     * Called when an error occurs
+     * Can handle, transform, or suppress errors
+     * @param error - The error that occurred
+     * @param context - Plugin context
+     * @returns Modified error, response data, or void to continue error propagation
+     */
+    onError?(error: Error, context: PluginContext): Error | ResponseResult | void | Promise<Error | ResponseResult | void>;
+  }
+
+  /**
+   * Alias for response body type
+   */
+  type ResponseBody = unknown;
+
+  /**
+   * Result returned by plugin process method
+   */
+  interface PluginResult {
+    /** Updated context */
+    context: PluginContext;
+    /** Response data (if generated/modified) */
+    response?: unknown;
+  }
+
+  /**
+   * Context passed through plugin pipeline
+   */
+  interface PluginContext {
+    /** Request path */
+    path: string;
+    /** Matched route configuration */
+    route: RouteConfig;
+    /** HTTP method */
+    method: HttpMethod;
+    /** Route parameters */
+    params: Record<string, string>;
+    /** Query parameters */
+    query: Record<string, string>;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request body */
+    body?: unknown;
+    /** Shared state between plugins for this request */
+    state: Map<string, unknown>;
+    /** Route-specific state */
+    routeState?: Record<string, unknown>;
+  }
+
+  // ===== Callable API Types =====
+
+  /**
+   * Global configuration options for the mock instance
+   */
+  interface GlobalConfig {
+    /** Base path prefix for all routes */
+    namespace?: string;
+    /** Response delay in ms, or [min, max] for random delay */
+    delay?: number | [number, number];
+    /** Enable debug mode for detailed logging */
+    debug?: boolean;
+    /** Initial shared state object */
+    state?: Record<string, unknown>;
+    /**
+     * Maximum number of requests retained in history (FIFO eviction).
+     * Defaults to unbounded; set this to cap memory growth in long-running servers.
+     */
+    maxHistorySize?: number;
+  }
+
+  /**
+   * Route-specific configuration options
+   */
+  interface RouteConfig {
+    /** MIME type for content type validation (auto-detected if not provided) */
+    contentType?: string;
+    /** Per-route response delay in ms, or [min, max] for random delay (overrides global) */
+    delay?: number | [number, number];
+    /** Additional route-specific options */
+    [key: string]: unknown;
+  }
+
+  /**
+   * Generator types that can be passed to route definitions
+   */
+  type Generator = 
+    | GeneratorFunction
+    | StaticData
+    | JSONSchema7;
+
+  /**
+   * Function that generates responses
+   */
+  type GeneratorFunction = (context: RequestContext) => ResponseResult | Promise<ResponseResult>;
+
+  /**
+   * Static data (non-function) that gets returned as-is
+   */
+  type StaticData = string | number | boolean | null | undefined | Record<string, unknown> | unknown[];
+
+  /**
+   * Context passed to generator functions
+   */
+  interface RequestContext {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Request path */
+    path: string;
+    /** Route parameters (e.g., :id) */
+    params: Record<string, string>;
+    /** Query string parameters */
+    query: Record<string, string>;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request body (for POST, PUT, PATCH) */
+    body?: unknown;
+    /** Shared mutable state */
+    state: Record<string, unknown>;
+  }
+
+  /**
+   * Response result types:
+   * - Any value: returns as 200 OK
+   * - [status, body]: custom status with body
+   * - [status, body, headers]: custom status, body, and headers
+   */
+  type ResponseResult =
+    | ResponseBody
+    | [number, unknown]
+    | [number, unknown, Record<string, string>];
+
+  /**
+   * Response object returned by handle method
+   */
+  interface Response {
+    status: number;
+    body: unknown;
+    headers: Record<string, string>;
+  }
+
+  /**
+   * Options for handle method
+   */
+  interface RequestOptions {
+    headers?: Record<string, string>;
+    body?: unknown;
+    query?: Record<string, string>;
+  }
+
+  /**
+   * Record of a single request handled by the mock
+   */
+  interface RequestRecord {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Request path (without namespace) */
+    path: string;
+    /** Extracted route parameters */
+    params: Record<string, string>;
+    /** Query parameters */
+    query: Record<string, string>;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request body */
+    body: unknown;
+    /** Unix timestamp (ms) when request was handled */
+    timestamp: number;
+    /** Response returned for this request */
+    response: { status: number; body: unknown };
+  }
+
+  /**
+   * Main callable mock instance interface
+   */
+  interface CallableMockInstance {
+    /**
+     * Define a route by calling the instance directly
+     * 
+     * @param route - Route pattern in format 'METHOD /path'
+     * @param generator - Response generator (function, static data, or schema)
+     * @param config - Route-specific configuration
+     * @returns The same instance for method chaining
+     * 
+     * @example
+     * ```typescript
+     * const mock = schmock()
+     * mock('GET /users', () => [...users], { contentType: 'application/json' })
+     * mock('POST /users', userData, { contentType: 'application/json' })
+     * ```
+     */
+    (route: RouteKey, generator: Generator, config?: RouteConfig): CallableMockInstance;
+
+    /**
+     * Add a plugin to the pipeline
+     * 
+     * @param plugin - Plugin to add to the pipeline
+     * @returns The same instance for method chaining
+     * 
+     * @example
+     * ```typescript
+     * mock('GET /users', generator, config)
+     *   .pipe(authPlugin())
+     *   .pipe(corsPlugin())
+     * ```
+     */
+    pipe(plugin: Plugin): CallableMockInstance;
+
+    /**
+     * Handle a request and return a response
+     *
+     * @param method - HTTP method
+     * @param path - Request path
+     * @param options - Request options (headers, body, query)
+     * @returns Promise resolving to response object
+     *
+     * @example
+     * ```typescript
+     * const response = await mock.handle('GET', '/users', {
+     *   headers: { 'Authorization': 'Bearer token' }
+     * })
+     * ```
+     */
+    handle(method: HttpMethod, path: string, options?: RequestOptions): Promise<Response>;
+
+    // ===== Request Spy / History API =====
+
+    /**
+     * Get all recorded requests, optionally filtered by method and path
+     *
+     * @param method - Filter by HTTP method
+     * @param path - Filter by request path
+     * @returns Array of request records
+     */
+    history(): RequestRecord[];
+    history(method: HttpMethod, path: string): RequestRecord[];
+
+    /**
+     * Check if any request was made, optionally for a specific route
+     *
+     * @param method - Filter by HTTP method
+     * @param path - Filter by request path
+     * @returns true if at least one matching request was recorded
+     */
+    called(): boolean;
+    called(method: HttpMethod, path: string): boolean;
+
+    /**
+     * Get the number of recorded requests, optionally for a specific route
+     *
+     * @param method - Filter by HTTP method
+     * @param path - Filter by request path
+     * @returns Number of matching requests
+     */
+    callCount(): number;
+    callCount(method: HttpMethod, path: string): number;
+
+    /**
+     * Get the most recent request, optionally for a specific route
+     *
+     * @param method - Filter by HTTP method
+     * @param path - Filter by request path
+     * @returns Most recent matching request record, or undefined
+     */
+    lastRequest(): RequestRecord | undefined;
+    lastRequest(method: HttpMethod, path: string): RequestRecord | undefined;
+
+    // ===== Reset / Lifecycle =====
+
+    /**
+     * Clear all routes, state, plugins, and history
+     */
+    reset(): void;
+
+    /**
+     * Clear only request history, keep routes and state
+     */
+    resetHistory(): void;
+
+    /**
+     * Clear only state, keep routes and history
+     */
+    resetState(): void;
+
+    // ===== Lifecycle Events =====
+
+    /**
+     * Register an event listener
+     */
+    on<E extends SchmockEvent>(event: E, listener: (data: SchmockEventMap[E]) => void): CallableMockInstance;
+
+    /**
+     * Remove an event listener
+     */
+    off<E extends SchmockEvent>(event: E, listener: (data: SchmockEventMap[E]) => void): CallableMockInstance;
+
+    // ===== Introspection =====
+
+    /**
+     * Get all registered routes as an array of route info objects
+     */
+    getRoutes(): RouteInfo[];
+
+    /**
+     * Get the current shared state object
+     */
+    getState(): Record<string, unknown>;
+
+    // ===== Standalone Server =====
+
+    /**
+     * Start a standalone HTTP server
+     *
+     * @param port - Port to listen on (0 for random)
+     * @param hostname - Hostname to bind to (default: "127.0.0.1")
+     * @returns Promise resolving to server info with actual port and hostname
+     * @throws If the server is already running
+     */
+    listen(port?: number, hostname?: string): Promise<ServerInfo>;
+
+    /**
+     * Stop the standalone server (idempotent, no-op if not running)
+     */
+    close(): void;
+
+    // ===== Fetch Interceptor =====
+
+    /**
+     * Intercept globalThis.fetch and route requests through this mock.
+     * Client-side equivalent of listen().
+     *
+     * @param options - Intercept configuration
+     * @returns Handle with restore() to stop intercepting
+     * @throws If already intercepting (call restore() first)
+     */
+    intercept(options?: InterceptOptions): InterceptHandle;
+  }
+
+  /**
+   * Information about a running standalone server
+   */
+  interface ServerInfo {
+    /** Port the server is listening on */
+    port: number;
+    /** Hostname the server is bound to */
+    hostname: string;
+  }
+
+  // ===== Response Helpers =====
+
+  interface PaginateOptions {
+    page?: number;
+    pageSize?: number;
+  }
+
+  interface PaginatedResponse<T> {
+    data: T[];
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+  }
+
+  // ===== Adapter Types =====
+
+  interface AdapterRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    query: Record<string, string>;
+  }
+
+  interface AdapterResponse {
+    status: number;
+    body: unknown;
+    headers: Record<string, string>;
+  }
+
+  interface InterceptOptions {
+    /**
+     * Only intercept URLs matching this base.
+     *
+     * Two modes:
+     * - Path form ("/api"): match request pathnames whose prefix is the
+     *   base path (with a segment-boundary check, so "/api" never
+     *   matches "/apiv2").
+     * - Origin form ("https://api.example.com" or
+     *   "https://api.example.com/v1"): require the request origin to
+     *   match the base origin AND, if a base path is present, the
+     *   request pathname to start with it. Relative-URL fetches
+     *   (no origin) won't match an origin-form base.
+     */
+    baseUrl?: string;
+    /** Pass unmatched routes to real fetch (default: true) */
+    passthrough?: boolean;
+    /** Modify request before Schmock handles it */
+    beforeRequest?: (
+      request: AdapterRequest,
+    ) => AdapterRequest | void | Promise<AdapterRequest | void>;
+    /** Modify response before returning to caller */
+    beforeResponse?: (
+      response: AdapterResponse,
+      request: AdapterRequest,
+    ) => AdapterResponse | void | Promise<AdapterResponse | void>;
+    /** Format errors into custom response bodies */
+    errorFormatter?: (error: Error) => unknown;
+  }
+
+  interface InterceptHandle {
+    /** Stop intercepting and restore original fetch */
+    restore(): void;
+    /** Whether this interceptor is currently active */
+    readonly active: boolean;
+  }
+
+  // ===== Lifecycle Events =====
+
+  interface RequestStartEvent {
+    method: HttpMethod;
+    path: string;
+    headers: Record<string, string>;
+  }
+
+  interface RequestMatchEvent {
+    method: HttpMethod;
+    path: string;
+    routePath: string;
+    params: Record<string, string>;
+  }
+
+  interface RequestNotFoundEvent {
+    method: HttpMethod;
+    path: string;
+  }
+
+  interface RequestEndEvent {
+    method: HttpMethod;
+    path: string;
+    status: number;
+    duration: number;
+  }
+
+  type SchmockEventMap = {
+    "request:start": RequestStartEvent;
+    "request:match": RequestMatchEvent;
+    "request:notfound": RequestNotFoundEvent;
+    "request:end": RequestEndEvent;
+  };
+
+  type SchmockEvent = keyof SchmockEventMap;
+
+  // ===== Introspection Types =====
+
+  interface RouteInfo {
+    method: HttpMethod;
+    path: string;
+    hasParams: boolean;
+  }
+
+  // ===== OpenAPI Plugin Types =====
+
+  /**
+   * Per-resource configuration override for OpenAPI plugin
+   */
+  interface ResourceOverride {
+    /** Override: which property in list response holds the items array (e.g. "data") */
+    listWrapProperty?: string;
+    /** Override: force flat array for list (ignores any wrapper in the spec) */
+    listFlat?: boolean;
+    /** Override: JSON Schema for error responses (404, etc.) */
+    errorSchema?: JSONSchema7;
+  }
+
+  /**
+   * Response header definition from an OpenAPI spec
+   */
+  interface ResponseHeaderDef {
+    schema?: JSONSchema7;
+    description: string;
+  }
+
+  /**
+   * Per-operation metadata auto-detected from spec or set via overrides
+   */
+  interface CrudOperationMeta {
+    /** Full success response schema (wrapper + items) */
+    responseSchema?: JSONSchema7;
+    /** Response headers from spec */
+    responseHeaders?: Record<string, ResponseHeaderDef>;
+    /** Error response schemas keyed by status code */
+    errorSchemas?: Map<number, JSONSchema7>;
+  }
+
+  // ===== Faker Plugin Types =====
+
+  /**
+   * Context for schema-based data generation
+   */
+  interface SchemaGenerationContext {
+    schema: JSONSchema7;
+    count?: number;
+    overrides?: Record<string, unknown>;
+    params?: Record<string, string>;
+    state?: Record<string, unknown>;
+    query?: Record<string, string>;
+    seed?: number;
+  }
+
+  /**
+   * Options for the faker plugin
+   */
+  interface FakerPluginOptions {
+    schema: JSONSchema7;
+    count?: number;
+    overrides?: Record<string, unknown>;
+    seed?: number;
+  }
+
+  // ===== Express Adapter Types =====
+
+  /**
+   * Override parts of a request before Schmock handles it
+   */
+  interface AdapterRequestOverride {
+    method?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    query?: Record<string, string>;
+  }
+
+  /**
+   * Configuration options for Express adapter
+   */
+  interface ExpressAdapterOptions {
+    errorFormatter?: (error: Error, req: unknown) => unknown;
+    passErrorsToNext?: boolean;
+    transformHeaders?: (
+      headers: Record<string, string | string[] | undefined>,
+    ) => Record<string, string>;
+    transformQuery?: (query: Record<string, unknown>) => Record<string, string>;
+    beforeRequest?: (
+      req: unknown,
+      res: unknown,
+    ) =>
+      | AdapterRequestOverride
+      | undefined
+      | Promise<AdapterRequestOverride | undefined>;
+    beforeResponse?: (
+      response: Response,
+      req: unknown,
+      res: unknown,
+    ) => Response | undefined | Promise<Response | undefined>;
+  }
+
+  // ===== Angular Adapter Types =====
+
+  /**
+   * Configuration options for Angular adapter
+   */
+  interface AngularAdapterOptions {
+    baseUrl?: string;
+    passthrough?: boolean;
+    errorFormatter?: (error: Error, request: unknown) => unknown;
+    transformRequest?: (request: unknown) => AdapterRequestOverride;
+    transformResponse?: (
+      response: Response,
+      request: unknown,
+    ) => Response;
+  }
+
+  // ===== OpenAPI Plugin Options =====
+
+  /**
+   * Options for the OpenAPI plugin
+   */
+  interface OpenApiOptions {
+    spec: string | object;
+    seed?: SeedConfig;
+    validateRequests?: boolean;
+    validateResponses?: boolean;
+    queryFeatures?: {
+      pagination?: boolean;
+      sorting?: boolean;
+      filtering?: boolean;
+    };
+    resources?: Record<string, ResourceOverride>;
+    debug?: boolean;
+    fakerSeed?: number;
+    security?: boolean;
+    /** Replace response schemas for specific routes. Key format: "METHOD /path" or "METHOD /path STATUS" */
+    schemas?: Record<string, import("json-schema").JSONSchema7>;
+    /** Called before generating a response body. Return a schema to replace the original, or void to keep it. */
+    onSchema?: (
+      schema: import("json-schema").JSONSchema7,
+      context: { method: string; path: string; params: Record<string, string>; query: Record<string, string>; headers: Record<string, string> },
+    ) => import("json-schema").JSONSchema7 | undefined;
+  }
+
+  /**
+   * Seed data source: inline array, file path, or auto-generate count
+   */
+  type SeedSource = unknown[] | string | { count: number };
+
+  /**
+   * Seed configuration mapping resource names to seed sources
+   */
+  type SeedConfig = Record<string, SeedSource>;
+
+  // ===== CLI Types =====
+
+  /**
+   * Options for the CLI server
+   */
+  interface CliOptions {
+    spec: string;
+    port?: number;
+    hostname?: string;
+    seed?: string;
+    cors?: boolean;
+    debug?: boolean;
+    fakerSeed?: number;
+    errors?: boolean;
+    watch?: boolean;
+    admin?: boolean;
+  }
+
+  /**
+   * Running CLI server instance
+   */
+  interface CliServer {
+    server: import("node:http").Server;
+    port: number;
+    hostname: string;
+    close(): void;
+  }
+
+}

package/package.json

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

package/src/interceptor.ts

@@ -24,6 +24,45 @@ function extractPathname(url: string): string {
   return urlWithoutQuery;
 }
 
+/**
+ * Extract origin (scheme + host + port) from a URL string, or null for
+ * relative URLs that don't carry one.
+ */
+function extractOrigin(url: string): string | null {
+  if (!url.includes("://")) return null;
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse the user-supplied baseUrl option into its origin and path parts.
+ * - "/api"                  → { origin: null, path: "/api" }
+ * - "https://x.com/api/v1"  → { origin: "https://x.com", path: "/api/v1" }
+ * - "https://x.com"         → { origin: "https://x.com", path: "" }
+ *
+ * Trailing slash is stripped from the path so the segment-boundary check
+ * works the same way for "/api" and "/api/".
+ */
+function parseBaseUrl(baseUrl: string): {
+  origin: string | null;
+  path: string;
+} {
+  if (baseUrl.includes("://")) {
+    try {
+      const parsed = new URL(baseUrl);
+      const rawPath = parsed.pathname;
+      const path = rawPath === "/" ? "" : rawPath.replace(/\/$/, "");
+      return { origin: parsed.origin, path };
+    } catch {
+      // Fall through to path-only handling
+    }
+  }
+  return { origin: null, path: baseUrl.replace(/\/$/, "") };
+}
+
 /**
  * Extract query parameters from a URL string.
  */
@@ -150,16 +189,25 @@ export function createFetchInterceptor(
 
     const path = extractPathname(urlString);
 
-    // BaseUrl filter — non-matching requests go straight to real fetch
-    // Enforce segment boundary: /api must not match /apiv2
+    // BaseUrl filter — non-matching requests go straight to real fetch.
+    // Two modes:
+    //   - origin form ("https://api.example.com/v1"): require matching
+    //     origin AND matching path prefix.
+    //   - path form ("/api"): match pathname prefix only.
+    // Both enforce a segment boundary so "/api" doesn't match "/apiv2".
     if (baseUrl) {
-      const normalizedBase = baseUrl.endsWith("/")
-        ? baseUrl.slice(0, -1)
-        : baseUrl;
-      const isMatch =
-        path === normalizedBase || path.startsWith(`${normalizedBase}/`);
-      if (!isMatch) {
-        return originalFetch(input, init);
+      const { origin: baseOrigin, path: basePath } = parseBaseUrl(baseUrl);
+      if (baseOrigin) {
+        const reqOrigin = extractOrigin(urlString);
+        if (reqOrigin !== baseOrigin) {
+          return originalFetch(input, init);
+        }
+      }
+      if (basePath) {
+        const isMatch = path === basePath || path.startsWith(`${basePath}/`);
+        if (!isMatch) {
+          return originalFetch(input, init);
+        }
       }
     }
 

package/src/steps/interceptor.steps.ts

@@ -130,6 +130,60 @@ describeFeature(feature, ({ Scenario, AfterEachScenario }) => {
     });
   });
 
+  Scenario("Origin-form baseUrl intercepts matching origin only", ({ Given, When, Then, And }) => {
+    Given("a Schmock instance with route \"GET /api/users\" returning users", () => {
+      setup();
+      mock("GET /api/users", [{ id: 1 }]);
+    });
+
+    And("fetch is intercepted with baseUrl \"https://api.example.com\"", () => {
+      handle = mock.intercept({ baseUrl: "https://api.example.com" });
+    });
+
+    When("I fetch \"https://api.example.com/api/users\"", async () => {
+      fetchResponse = await fetch("https://api.example.com/api/users");
+    });
+
+    Then("the response status should be {int}", (_, status: number) => {
+      expect(fetchResponse?.status).toBe(status);
+    });
+
+    When("I fetch \"https://other.example.com/api/users\"", async () => {
+      await fetch("https://other.example.com/api/users");
+    });
+
+    Then("the original fetch should have been called", () => {
+      expect(savedFetch).toHaveBeenCalled();
+    });
+  });
+
+  Scenario("Origin-form baseUrl with a path prefix requires both to match", ({ Given, When, Then, And }) => {
+    Given("a Schmock instance with route \"GET /v1/users\" returning users", () => {
+      setup();
+      mock("GET /v1/users", [{ id: 1 }]);
+    });
+
+    And("fetch is intercepted with baseUrl \"https://api.example.com/v1\"", () => {
+      handle = mock.intercept({ baseUrl: "https://api.example.com/v1" });
+    });
+
+    When("I fetch \"https://api.example.com/v1/users\"", async () => {
+      fetchResponse = await fetch("https://api.example.com/v1/users");
+    });
+
+    Then("the response status should be {int}", (_, status: number) => {
+      expect(fetchResponse?.status).toBe(status);
+    });
+
+    When("I fetch \"https://api.example.com/users\"", async () => {
+      await fetch("https://api.example.com/users");
+    });
+
+    Then("the original fetch should have been called", () => {
+      expect(savedFetch).toHaveBeenCalled();
+    });
+  });
+
   Scenario("beforeRequest hook modifies the request", ({ Given, When, Then, And }) => {
     Given("a Schmock instance with route \"GET /api/users\" that reads headers", () => {
       setup();