nuxt-api-contract 0.1.0 → 0.2.0

package/README.md

@@ -237,13 +237,38 @@ generation never fails.
 ## Mocking
 
 ```ts
-import { mockContract } from 'nuxt-api-contract/client'
+import { mockContract, autoMockContract } from 'nuxt-api-contract/client'
 
 mockContract(GetUser, { response: () => ({ id: '1', name: 'Mocked User' }) })
+autoMockContract(GetUser, { seed: 42 }) // generated from the response schema
 ```
 
-Enable `apiContract: { mocks: true }` and contract handlers return the mock
-response (still validated against the response schema).
+Enable `apiContract: { mocks: true | 'auto' }` and contract handlers return
+mock responses (still validated against the response schema). With `'auto'`,
+contracts without an explicit `mockContract()` fall back to generated data.
+
+### Standalone mock server
+
+Serve contract endpoints without a Nuxt build (frontend development against a
+not-yet-implemented backend):
+
+```bash
+npx nuxt-api-contract mock contracts/index.ts --port 4000 --seed 42
+# add --lenient to skip request validation, --delay 300 for artificial latency
+```
+
+Or programmatically:
+
+```ts
+import { startMockServer } from 'nuxt-api-contract/mock'
+
+const mock = await startMockServer({ contracts: [GetUser, ListUsers], port: 4000 })
+// GET /__mock/contracts lists available endpoints; CORS is enabled.
+await mock.close()
+```
+
+Responses are deterministic for a given `--seed`; password/token fields are
+always masked.
 
 ## Testing
 
@@ -322,6 +347,7 @@ and DevTools are not part of any runtime import chain (importing
 | `nuxt-api-contract/server` | `defineContractHandler`, validation helpers |
 | `nuxt-api-contract/testing` | `callContract` |
 | `nuxt-api-contract/openapi` | OpenAPI generator |
+| `nuxt-api-contract/mock` | Standalone mock server + mock generators |
 | `nuxt-api-contract/shared` | Shared primitives |
 
 ## Limitations
@@ -330,15 +356,14 @@ and DevTools are not part of any runtime import chain (importing
 - Request bodies are JSON; `multipart/form-data` (file uploads) is planned —
   the contract abstraction already does not assume JSON-only bodies.
 - OpenAPI conversion is best-effort for `transform` / `refine` / `preprocess`.
-- The standalone mock server (`nuxt-api-contract mock`) is not implemented yet.
 - Auto-discovery is directory-based (`contracts/`, `server/contracts/`) rather
   than a build-time scanner.
 
 ## Roadmap
 
-See [ROADMAP.md](ROADMAP.md). In short: **0.1.0 (released)** ships core
-contracts, OpenAPI generation and the DevTools panel; next: 0.2.0 standalone
-mock server, 0.3.0 extended contract testing, 0.4.0 OpenAPI client generation,
+See [ROADMAP.md](ROADMAP.md). In short: **0.1.0** core contracts + OpenAPI +
+DevTools and **0.2.0** standalone mock server / generated mocks are released;
+next: 0.3.0 extended contract testing, 0.4.0 OpenAPI client generation,
 0.5.0 external API contracts, 0.6.0 contract versioning, 1.0.0 stable API.
 
 ## Development

package/dist/chunks/server.mjs

@@ -0,0 +1,162 @@
+import { createServer } from 'node:http';
+import { B as BUILT_IN_ERROR_CODES, A as ApiError, s as serializeApiError } from '../shared/nuxt-api-contract.obS6uV8A.mjs';
+import { v as validateContractInput, a as validateContractResponse } from '../shared/nuxt-api-contract.DDpgZj2g.mjs';
+import { g as generateMockResponse } from '../shared/nuxt-api-contract.Bd2Y7Lx0.mjs';
+import 'zod';
+import '../shared/nuxt-api-contract.DCAU2j7t.mjs';
+import '../shared/nuxt-api-contract.V15soI_f.mjs';
+
+function pathToRegex(path) {
+  const names = [];
+  const source = path.split("/").map((segment) => {
+    const match = /^:([A-Za-z_][A-Za-z0-9_]*)$/.exec(segment);
+    if (!match) return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    names.push(match[1]);
+    return `(?<${match[1]}>[^/]+)`;
+  }).join("/");
+  return { regex: new RegExp(`^${source}/?$`), names };
+}
+function corsHeaders() {
+  return {
+    "access-control-allow-origin": "*",
+    "access-control-allow-methods": "GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS",
+    "access-control-allow-headers": "content-type, authorization, x-requested-with"
+  };
+}
+function send(res, status, payload, extra = {}) {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "x-mock-server": "nuxt-api-contract",
+    ...corsHeaders(),
+    ...extra
+  });
+  res.end(body);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function buildMockMatchers(contracts) {
+  return contracts.map((contract) => {
+    const { regex, names } = pathToRegex(contract.path);
+    return { contract, method: contract.method, regex, names };
+  });
+}
+async function readJsonBody(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  if (chunks.length === 0) return { ok: true, value: void 0 };
+  try {
+    return { ok: true, value: JSON.parse(Buffer.concat(chunks).toString("utf8")) };
+  } catch {
+    return { ok: false, value: void 0 };
+  }
+}
+function errorPayload(error) {
+  return serializeApiError(error);
+}
+function createMockServer(options) {
+  const matchers = buildMockMatchers(options.contracts);
+  return createServer(async (req, res) => {
+    const started = Date.now();
+    try {
+      if (req.method === "OPTIONS") {
+        res.writeHead(204, corsHeaders());
+        res.end();
+        return;
+      }
+      const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+      const method = (req.method ?? "GET").toUpperCase();
+      const pathMatch = matchers.find((matcher) => matcher.method === method && matcher.regex.test(url.pathname)) ?? matchers.find((matcher) => matcher.regex.test(url.pathname));
+      if (url.pathname === "/__mock/contracts" || url.pathname === "/__mock/contracts/") {
+        send(res, 200, {
+          contracts: options.contracts.map((contract2) => ({
+            method: contract2.method,
+            path: contract2.path,
+            name: contract2.name ?? null,
+            tags: contract2.tags ?? []
+          }))
+        });
+        return;
+      }
+      if (!pathMatch) {
+        send(res, 404, { error: { code: BUILT_IN_ERROR_CODES.notFound, message: `No mock for ${method} ${url.pathname}` } });
+        return;
+      }
+      if (pathMatch.method !== method) {
+        send(res, 405, { error: { code: BUILT_IN_ERROR_CODES.methodNotAllowed, message: `${pathMatch.method} ${pathMatch.contract.path} does not accept ${method}` } });
+        return;
+      }
+      const match = pathMatch;
+      const contract = match.contract;
+      const params = {};
+      const exec = match.regex.exec(url.pathname);
+      for (const name of match.names) {
+        params[name] = decodeURIComponent(exec?.groups?.[name] ?? "");
+      }
+      const query = {};
+      for (const [key, value] of url.searchParams.entries()) {
+        query[key] = value;
+      }
+      let body;
+      let bodyError;
+      if (method !== "GET" && method !== "HEAD") {
+        const parsed = await readJsonBody(req);
+        if (!parsed.ok) {
+          bodyError = new ApiError({ code: BUILT_IN_ERROR_CODES.validation, message: "Request body must be valid JSON", statusCode: 400 });
+        }
+        body = parsed.value;
+      }
+      if (options.delay) await sleep(options.delay);
+      if (!options.lenient) {
+        try {
+          if (bodyError) throw bodyError;
+          if (contract.params) validateContractInput(contract, "params", contract.params, params);
+          if (contract.query) validateContractInput(contract, "query", contract.query, query);
+          if (method !== "GET" && method !== "HEAD" && contract.body) {
+            validateContractInput(contract, "body", contract.body, body);
+          }
+        } catch (error) {
+          const apiError = error instanceof ApiError ? error : new ApiError({ code: BUILT_IN_ERROR_CODES.internal, message: String(error) });
+          send(res, apiError.statusCode, errorPayload(apiError));
+          return;
+        }
+      }
+      let response;
+      try {
+        response = generateMockResponse(contract, { seed: options.seed });
+        if (contract.response) {
+          validateContractResponse(contract, contract.response, response);
+        }
+      } catch (error) {
+        send(res, 500, { error: { code: BUILT_IN_ERROR_CODES.internal, message: error instanceof Error ? error.message : String(error) } });
+        return;
+      }
+      send(res, 200, response, { "x-mock-time": String(Date.now() - started) });
+    } catch (error) {
+      send(res, 500, { error: { code: BUILT_IN_ERROR_CODES.internal, message: error instanceof Error ? error.message : String(error) } });
+    }
+  });
+}
+function startMockServer(options) {
+  const server = createMockServer(options);
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port ?? 4e3, options.host ?? "127.0.0.1", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : options.port ?? 4e3;
+      const host = options.host ?? "127.0.0.1";
+      resolve({
+        server,
+        port,
+        host,
+        url: `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}`,
+        close: () => new Promise((resolveClose, rejectClose) => {
+          server.close((error) => error ? rejectClose(error) : resolveClose());
+        })
+      });
+    });
+  });
+}
+
+export { buildMockMatchers, createMockServer, startMockServer };

package/dist/cli.mjs

@@ -69,7 +69,39 @@ async function main() {
     console.log(`[nuxt-api-contract] OpenAPI document with ${contracts.length} contract(s) written to ${output}`);
     return;
   }
-  console.error(`[nuxt-api-contract] Unknown command "${command ?? ""}". Available commands: openapi`);
+  if (command === "mock") {
+    const entry = positional[0];
+    if (!entry || !existsSync(entry)) {
+      console.error("[nuxt-api-contract] Usage: nuxt-api-contract mock <entry> [--port 4000] [--seed 42] [--lenient]");
+      process.exitCode = 1;
+      return;
+    }
+    const contracts = await loadContractsFromEntry(resolve(entry));
+    const { startMockServer } = await import('./chunks/server.mjs');
+    const seed = flags.seed !== void 0 && flags.seed !== true ? Number(flags.seed) : void 0;
+    const handle = await startMockServer({
+      contracts,
+      port: flags.port !== void 0 && flags.port !== true ? Number(flags.port) : 4e3,
+      host: typeof flags.host === "string" ? flags.host : "127.0.0.1",
+      seed,
+      delay: flags.delay !== void 0 && flags.delay !== true ? Number(flags.delay) : void 0,
+      lenient: flags.lenient === true
+    });
+    console.log(`[nuxt-api-contract] Mock server listening on ${handle.url} (seed: ${seed ?? "randomized per contract"}, lenient: ${flags.lenient === true})`);
+    for (const contract of contracts) {
+      console.log(`  ${contract.method.padEnd(6)} ${handle.url}${contract.path}`);
+    }
+    console.log("  GET    /__mock/contracts  (list endpoints)");
+    console.log("Press Ctrl+C to stop.");
+    const shutdown = async () => {
+      await handle.close();
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    return;
+  }
+  console.error(`[nuxt-api-contract] Unknown command "${command ?? ""}". Available commands: openapi, mock`);
   process.exitCode = 1;
 }
 function toMinimalYaml(value, indent = 0) {

package/dist/client.d.mts

@@ -1,70 +1,6 @@
+export { C as ContractMock, M as MockResponseInput, b as buildRequestPath, c as clearContractRegistry, d as defineApiContract, g as getContractByName, a as getContractMock, i as isApiContract, l as listRegisteredContracts, m as mockContract, r as registerContract } from './shared/nuxt-api-contract.BgPd-YXc.mjs';
 export { A as ApiError, a as ApiErrorPayload, B as BUILT_IN_ERROR_CODES, C as CreateApiErrorInput, V as ValidationIssue, c as createApiError, f as formatValidationMessage, i as isApiError, p as parseApiErrorPayload, s as sanitizeIssues, b as serializeApiError, t as toApiError, d as toValidationIssues } from './shared/nuxt-api-contract.D31EDcwH.mjs';
-import { A as AnyApiContract, M as MaybePromise, i as ContractHandlerResponse, c as ApiContractDefinition, h as ContractFromDefinition } from './shared/nuxt-api-contract.CPm9WbWA.mjs';
-export { a as API_CONTRACT_KIND, b as ApiContract, d as ApiRequestOptions, e as AuthConfig, C as ContractBodyInput, f as ContractClientResponse, g as ContractErrorCode, j as ContractHeadersInput, k as ContractParamsInput, l as ContractPathParams, m as ContractQueryInput, E as EmptyObject, n as ExtractSchemaInput, o as ExtractSchemaOutput, H as HttpMethod, I as IsEmptyObject, P as PathParams, R as ResolvedApiRequestOptions, S as SplitPath } from './shared/nuxt-api-contract.CPm9WbWA.mjs';
-import * as zod from 'zod';
-
-/**
- * Registers a named contract. Called automatically by `defineApiContract`
- * when a `name` is provided. Duplicate names are overwritten with a warning.
- */
-declare function registerContract(contract: AnyApiContract): void;
-declare function getContractByName(name: string): AnyApiContract | undefined;
-declare function listRegisteredContracts(): AnyApiContract[];
-/** Test helper: clears the registry. */
-declare function clearContractRegistry(): void;
-interface ContractMock<C extends AnyApiContract> {
-    /** Factory producing a (validated) response for the contract. */
-    response?: () => MaybePromise<MockResponseInput<C>>;
-    /** Simulated latency in ms. */
-    delay?: number;
-}
-type MockResponseInput<C extends AnyApiContract> = C['response'] extends zod.ZodType ? ContractHandlerResponse<C> : unknown;
-/**
- * Registers a mock implementation for a contract. When the module option
- * `apiContract.mocks` is enabled, contract handlers return the mock response
- * (still validated against the response schema).
- */
-declare function mockContract<C extends AnyApiContract>(contract: C, mock: ContractMock<C>): void;
-declare function getContractMock<C extends AnyApiContract>(contract: C): ContractMock<C> | undefined;
-/**
- * Defines a type-safe API contract.
- *
- * The contract is the single source of truth for runtime validation,
- * TypeScript types, OpenAPI generation, DevTools and mocks.
- *
- * @example
- * ```ts
- * export const GetUser = defineApiContract({
- *   method: 'GET',
- *   path: '/api/users/:id',
- *   params: z.object({ id: z.string().uuid() }),
- *   response: z.object({ id: z.string(), name: z.string() }),
- * })
- * ```
- */
-declare function defineApiContract<const TDef extends ApiContractDefinition>(definition: TDef): ContractFromDefinition<TDef>;
-/** Type guard for contract objects. */
-declare function isApiContract(value: unknown): value is AnyApiContract;
-/**
- * Builds the request URL from a contract path and concrete params.
- * Remaining params that are not part of the path are ignored.
- */
-declare function buildRequestPath(path: string, params: Record<string, unknown> | undefined): string;
-
-/**
- * Serialization helpers shared by the client transport and cache keys.
- *
- * The protocol intentionally stays minimal: standard JSON plus two common
- * edge cases (Date and bigint). Response serialization relies on Nitro's
- * built-in devalue support, which already handles Date, RegExp, etc.
- */
-/** Converts query values into URL-safe primitives (Date -> ISO, bigint -> string). */
-type SerializedQueryValue = string | number | boolean | Array<string | number | boolean>;
-declare function serializeQueryValue(value: unknown): SerializedQueryValue;
-/** Prepares a query object for `$fetch` / URL building; drops `undefined` entries. */
-declare function serializeQuery(query: Record<string, unknown> | undefined): Record<string, SerializedQueryValue> | undefined;
-/** Deterministic JSON stringify (sorted keys) for stable SSR cache keys. */
-declare function stableStringify(value: unknown): string;
-
-export { AnyApiContract, ApiContractDefinition, ContractFromDefinition, ContractHandlerResponse, MaybePromise, buildRequestPath, clearContractRegistry, defineApiContract, getContractByName, getContractMock, isApiContract, listRegisteredContracts, mockContract, registerContract, serializeQuery, serializeQueryValue, stableStringify };
-export type { ContractMock, MockResponseInput };
+export { s as serializeQuery, a as serializeQueryValue, b as stableStringify } from './shared/nuxt-api-contract.DZfOzVaB.mjs';
+export { A as API_CONTRACT_KIND, a as AnyApiContract, b as ApiContract, c as ApiContractDefinition, d as ApiRequestOptions, e as AuthConfig, C as ContractBodyInput, f as ContractClientResponse, g as ContractErrorCode, h as ContractFromDefinition, i as ContractHandlerResponse, j as ContractHeadersInput, k as ContractParamsInput, l as ContractPathParams, m as ContractQueryInput, E as EmptyObject, n as ExtractSchemaInput, o as ExtractSchemaOutput, H as HttpMethod, I as IsEmptyObject, M as MaybePromise, P as PathParams, R as ResolvedApiRequestOptions, S as SplitPath } from './shared/nuxt-api-contract.CFG8gzJH.mjs';
+export { M as MockGenerateOptions, a as autoMockContract, g as generateMockResponse } from './shared/nuxt-api-contract.BOxyDvRy.mjs';
+import 'zod';

package/dist/client.d.ts

@@ -1,70 +1,6 @@
+export { C as ContractMock, M as MockResponseInput, b as buildRequestPath, c as clearContractRegistry, d as defineApiContract, g as getContractByName, a as getContractMock, i as isApiContract, l as listRegisteredContracts, m as mockContract, r as registerContract } from './shared/nuxt-api-contract.C7KxMQHa.js';
 export { A as ApiError, a as ApiErrorPayload, B as BUILT_IN_ERROR_CODES, C as CreateApiErrorInput, V as ValidationIssue, c as createApiError, f as formatValidationMessage, i as isApiError, p as parseApiErrorPayload, s as sanitizeIssues, b as serializeApiError, t as toApiError, d as toValidationIssues } from './shared/nuxt-api-contract.D31EDcwH.js';
-import { A as AnyApiContract, M as MaybePromise, i as ContractHandlerResponse, c as ApiContractDefinition, h as ContractFromDefinition } from './shared/nuxt-api-contract.CPm9WbWA.js';
-export { a as API_CONTRACT_KIND, b as ApiContract, d as ApiRequestOptions, e as AuthConfig, C as ContractBodyInput, f as ContractClientResponse, g as ContractErrorCode, j as ContractHeadersInput, k as ContractParamsInput, l as ContractPathParams, m as ContractQueryInput, E as EmptyObject, n as ExtractSchemaInput, o as ExtractSchemaOutput, H as HttpMethod, I as IsEmptyObject, P as PathParams, R as ResolvedApiRequestOptions, S as SplitPath } from './shared/nuxt-api-contract.CPm9WbWA.js';
-import * as zod from 'zod';
-
-/**
- * Registers a named contract. Called automatically by `defineApiContract`
- * when a `name` is provided. Duplicate names are overwritten with a warning.
- */
-declare function registerContract(contract: AnyApiContract): void;
-declare function getContractByName(name: string): AnyApiContract | undefined;
-declare function listRegisteredContracts(): AnyApiContract[];
-/** Test helper: clears the registry. */
-declare function clearContractRegistry(): void;
-interface ContractMock<C extends AnyApiContract> {
-    /** Factory producing a (validated) response for the contract. */
-    response?: () => MaybePromise<MockResponseInput<C>>;
-    /** Simulated latency in ms. */
-    delay?: number;
-}
-type MockResponseInput<C extends AnyApiContract> = C['response'] extends zod.ZodType ? ContractHandlerResponse<C> : unknown;
-/**
- * Registers a mock implementation for a contract. When the module option
- * `apiContract.mocks` is enabled, contract handlers return the mock response
- * (still validated against the response schema).
- */
-declare function mockContract<C extends AnyApiContract>(contract: C, mock: ContractMock<C>): void;
-declare function getContractMock<C extends AnyApiContract>(contract: C): ContractMock<C> | undefined;
-/**
- * Defines a type-safe API contract.
- *
- * The contract is the single source of truth for runtime validation,
- * TypeScript types, OpenAPI generation, DevTools and mocks.
- *
- * @example
- * ```ts
- * export const GetUser = defineApiContract({
- *   method: 'GET',
- *   path: '/api/users/:id',
- *   params: z.object({ id: z.string().uuid() }),
- *   response: z.object({ id: z.string(), name: z.string() }),
- * })
- * ```
- */
-declare function defineApiContract<const TDef extends ApiContractDefinition>(definition: TDef): ContractFromDefinition<TDef>;
-/** Type guard for contract objects. */
-declare function isApiContract(value: unknown): value is AnyApiContract;
-/**
- * Builds the request URL from a contract path and concrete params.
- * Remaining params that are not part of the path are ignored.
- */
-declare function buildRequestPath(path: string, params: Record<string, unknown> | undefined): string;
-
-/**
- * Serialization helpers shared by the client transport and cache keys.
- *
- * The protocol intentionally stays minimal: standard JSON plus two common
- * edge cases (Date and bigint). Response serialization relies on Nitro's
- * built-in devalue support, which already handles Date, RegExp, etc.
- */
-/** Converts query values into URL-safe primitives (Date -> ISO, bigint -> string). */
-type SerializedQueryValue = string | number | boolean | Array<string | number | boolean>;
-declare function serializeQueryValue(value: unknown): SerializedQueryValue;
-/** Prepares a query object for `$fetch` / URL building; drops `undefined` entries. */
-declare function serializeQuery(query: Record<string, unknown> | undefined): Record<string, SerializedQueryValue> | undefined;
-/** Deterministic JSON stringify (sorted keys) for stable SSR cache keys. */
-declare function stableStringify(value: unknown): string;
-
-export { AnyApiContract, ApiContractDefinition, ContractFromDefinition, ContractHandlerResponse, MaybePromise, buildRequestPath, clearContractRegistry, defineApiContract, getContractByName, getContractMock, isApiContract, listRegisteredContracts, mockContract, registerContract, serializeQuery, serializeQueryValue, stableStringify };
-export type { ContractMock, MockResponseInput };
+export { s as serializeQuery, a as serializeQueryValue, b as stableStringify } from './shared/nuxt-api-contract.DZfOzVaB.js';
+export { A as API_CONTRACT_KIND, a as AnyApiContract, b as ApiContract, c as ApiContractDefinition, d as ApiRequestOptions, e as AuthConfig, C as ContractBodyInput, f as ContractClientResponse, g as ContractErrorCode, h as ContractFromDefinition, i as ContractHandlerResponse, j as ContractHeadersInput, k as ContractParamsInput, l as ContractPathParams, m as ContractQueryInput, E as EmptyObject, n as ExtractSchemaInput, o as ExtractSchemaOutput, H as HttpMethod, I as IsEmptyObject, M as MaybePromise, P as PathParams, R as ResolvedApiRequestOptions, S as SplitPath } from './shared/nuxt-api-contract.CFG8gzJH.js';
+export { M as MockGenerateOptions, a as autoMockContract, g as generateMockResponse } from './shared/nuxt-api-contract.BuWjAHJe.js';
+import 'zod';

package/dist/client.mjs

@@ -1,3 +1,5 @@
-export { b as buildRequestPath, c as clearContractRegistry, d as defineApiContract, g as getContractByName, a as getContractMock, i as isApiContract, l as listRegisteredContracts, m as mockContract, r as registerContract, s as serializeQuery, e as serializeQueryValue, f as stableStringify } from './shared/nuxt-api-contract.QDGSGaVY.mjs';
+export { b as buildRequestPath, c as clearContractRegistry, d as defineApiContract, g as getContractByName, a as getContractMock, i as isApiContract, l as listRegisteredContracts, m as mockContract, r as registerContract } from './shared/nuxt-api-contract.V15soI_f.mjs';
 export { A as ApiError, B as BUILT_IN_ERROR_CODES, c as createApiError, i as isApiError, p as parseApiErrorPayload, s as serializeApiError, t as toApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
 export { f as formatValidationMessage, s as sanitizeIssues, t as toValidationIssues } from './shared/nuxt-api-contract.DCAU2j7t.mjs';
+export { s as serializeQuery, a as serializeQueryValue, b as stableStringify } from './shared/nuxt-api-contract.Dr4tPqGB.mjs';
+export { a as autoMockContract, g as generateMockResponse } from './shared/nuxt-api-contract.Bd2Y7Lx0.mjs';

package/dist/composables.mjs

@@ -1,6 +1,7 @@
 import { useAsyncData, useNuxtApp, useRequestEvent } from '#imports';
-import { f as stableStringify, b as buildRequestPath, s as serializeQuery } from './shared/nuxt-api-contract.QDGSGaVY.mjs';
+import { b as buildRequestPath } from './shared/nuxt-api-contract.V15soI_f.mjs';
 import { p as parseApiErrorPayload, A as ApiError, t as toApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
+import { b as stableStringify, s as serializeQuery } from './shared/nuxt-api-contract.Dr4tPqGB.mjs';
 
 function createRequestKey(contract, options) {
   const { params, query, body, extraHeaders, ...rest } = options ?? {};

package/dist/mock.d.mts

@@ -0,0 +1,54 @@
+export { M as MockGenerateOptions, a as autoMockContract, c as createRng, g as generateMockResponse, b as generateMockValue } from './shared/nuxt-api-contract.BOxyDvRy.mjs';
+import { Server } from 'node:http';
+import { AnyApiContract } from './client.mjs';
+import 'zod';
+import './shared/nuxt-api-contract.BgPd-YXc.mjs';
+
+/**
+ * Standalone mock server: serves contract-defined endpoints with
+ * deterministic generated responses. Zero framework dependencies — plain
+ * `node:http`, so it can run outside Nuxt:
+ *
+ * ```bash
+ * npx nuxt-api-contract mock contracts/index.ts --port 4000 --seed 42
+ * ```
+ */
+
+interface MockServerOptions {
+    contracts: AnyApiContract[];
+    /** Listen port (default: 4000; `0` picks a random free port). */
+    port?: number;
+    /** Listen host (default: `127.0.0.1`). */
+    host?: string;
+    /** Deterministic generation seed. */
+    seed?: number;
+    /** Artificial latency in ms per request. */
+    delay?: number;
+    /** Return generated responses even for invalid requests (default: false). */
+    lenient?: boolean;
+}
+interface MockServerHandle {
+    server: Server;
+    port: number;
+    host: string;
+    url: string;
+    close: () => Promise<void>;
+}
+interface Matcher {
+    contract: AnyApiContract;
+    method: string;
+    regex: RegExp;
+    names: string[];
+}
+/** Builds an in-memory matcher index over the contracts. */
+declare function buildMockMatchers(contracts: AnyApiContract[]): Matcher[];
+/**
+ * Creates (without listening) a mock `node:http` server for the contracts.
+ * Prefer `startMockServer` for CLI / test usage.
+ */
+declare function createMockServer(options: MockServerOptions): Server;
+/** Creates the mock server and starts listening. Resolves once ready. */
+declare function startMockServer(options: MockServerOptions): Promise<MockServerHandle>;
+
+export { buildMockMatchers, createMockServer, startMockServer };
+export type { MockServerHandle, MockServerOptions };

package/dist/mock.d.ts

@@ -0,0 +1,54 @@
+export { M as MockGenerateOptions, a as autoMockContract, c as createRng, g as generateMockResponse, b as generateMockValue } from './shared/nuxt-api-contract.BuWjAHJe.js';
+import { Server } from 'node:http';
+import { AnyApiContract } from './client.js';
+import 'zod';
+import './shared/nuxt-api-contract.C7KxMQHa.js';
+
+/**
+ * Standalone mock server: serves contract-defined endpoints with
+ * deterministic generated responses. Zero framework dependencies — plain
+ * `node:http`, so it can run outside Nuxt:
+ *
+ * ```bash
+ * npx nuxt-api-contract mock contracts/index.ts --port 4000 --seed 42
+ * ```
+ */
+
+interface MockServerOptions {
+    contracts: AnyApiContract[];
+    /** Listen port (default: 4000; `0` picks a random free port). */
+    port?: number;
+    /** Listen host (default: `127.0.0.1`). */
+    host?: string;
+    /** Deterministic generation seed. */
+    seed?: number;
+    /** Artificial latency in ms per request. */
+    delay?: number;
+    /** Return generated responses even for invalid requests (default: false). */
+    lenient?: boolean;
+}
+interface MockServerHandle {
+    server: Server;
+    port: number;
+    host: string;
+    url: string;
+    close: () => Promise<void>;
+}
+interface Matcher {
+    contract: AnyApiContract;
+    method: string;
+    regex: RegExp;
+    names: string[];
+}
+/** Builds an in-memory matcher index over the contracts. */
+declare function buildMockMatchers(contracts: AnyApiContract[]): Matcher[];
+/**
+ * Creates (without listening) a mock `node:http` server for the contracts.
+ * Prefer `startMockServer` for CLI / test usage.
+ */
+declare function createMockServer(options: MockServerOptions): Server;
+/** Creates the mock server and starts listening. Resolves once ready. */
+declare function startMockServer(options: MockServerOptions): Promise<MockServerHandle>;
+
+export { buildMockMatchers, createMockServer, startMockServer };
+export type { MockServerHandle, MockServerOptions };

package/dist/mock.mjs

@@ -0,0 +1,8 @@
+export { a as autoMockContract, c as createRng, g as generateMockResponse, b as generateMockValue } from './shared/nuxt-api-contract.Bd2Y7Lx0.mjs';
+export { buildMockMatchers, createMockServer, startMockServer } from './chunks/server.mjs';
+import './shared/nuxt-api-contract.V15soI_f.mjs';
+import 'node:http';
+import './shared/nuxt-api-contract.obS6uV8A.mjs';
+import './shared/nuxt-api-contract.DDpgZj2g.mjs';
+import 'zod';
+import './shared/nuxt-api-contract.DCAU2j7t.mjs';

package/dist/module.d.mts

@@ -20,8 +20,14 @@ interface ApiContractModuleOptions {
         description?: string;
         output?: string;
     };
-    /** Enable registered contract mocks (development/testing only). */
-    mocks?: boolean;
+    /**
+     * Mock mode:
+     * - `false` (default): real handlers.
+     * - `true`: use mocks registered via `mockContract()`.
+     * - `'auto'`: use registered mocks, and generate mock responses
+     *   from the response schemas for contracts without an explicit mock.
+     */
+    mocks?: boolean | 'auto';
     /** Nuxt DevTools panel (no-op when DevTools is not installed). */
     devtools?: boolean;
     /** Directories scanned for contract auto-imports. */

package/dist/module.d.ts

@@ -20,8 +20,14 @@ interface ApiContractModuleOptions {
         description?: string;
         output?: string;
     };
-    /** Enable registered contract mocks (development/testing only). */
-    mocks?: boolean;
+    /**
+     * Mock mode:
+     * - `false` (default): real handlers.
+     * - `true`: use mocks registered via `mockContract()`.
+     * - `'auto'`: use registered mocks, and generate mock responses
+     *   from the response schemas for contracts without an explicit mock.
+     */
+    mocks?: boolean | 'auto';
     /** Nuxt DevTools panel (no-op when DevTools is not installed). */
     devtools?: boolean;
     /** Directories scanned for contract auto-imports. */

package/dist/module.mjs

@@ -47,12 +47,14 @@ const module$1 = defineNuxtModule({
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
     const rootDir = nuxt.options.rootDir;
+    const mocksEnabled = options.mocks === true || options.mocks === "auto";
     nuxt.options.runtimeConfig.apiContract = defu(nuxt.options.runtimeConfig.apiContract ?? {}, {
       validateResponse: options.validateResponse ?? "development",
-      mocks: options.mocks ?? false
+      mocks: mocksEnabled,
+      mocksAuto: options.mocks === "auto"
     });
     nuxt.options.runtimeConfig.public.apiContract = defu(nuxt.options.runtimeConfig.public.apiContract ?? {}, {
-      mocks: options.mocks ?? false
+      mocks: mocksEnabled
     });
     addImports([
       { from: "nuxt-api-contract/client", name: "defineApiContract" },