nuxt-api-contract 0.1.0 → 0.3.0

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" },

package/dist/runtime/shared/mock.mjs

@@ -0,0 +1,188 @@
+import { mockContract } from "./contract.mjs";
+function zodDef(schema) {
+  return schema._def;
+}
+export function createRng(seed) {
+  let state = seed >>> 0;
+  return function() {
+    state = state + 1831565813 | 0;
+    let t = state;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function strHash(value) {
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function pick(items, rng) {
+  return items[Math.floor(rng() * items.length) % items.length];
+}
+function intBetween(rng, min, max) {
+  return Math.floor(min + rng() * (max - min + 1));
+}
+const FIRST_NAMES = ["John", "Jane", "Alex", "Maria", "Ivan", "Elena"];
+const LAST_NAMES = ["Doe", "Smith", "Brown", "Ivanov", "Miller"];
+const WORDS = ["mock", "demo", "sample", "alpha", "beta", "gamma"];
+const MOCK_EPOCH = Date.UTC(2024, 0, 1);
+const YEAR_MS = 365 * 24 * 3600 * 1e3;
+function mockUuid(rng) {
+  const hex = () => Math.floor(rng() * 65535).toString(16).padStart(4, "0");
+  return `${hex()}${hex()}-4${hex().slice(1)}-8${hex().slice(1)}-4${hex().slice(1)}-${hex()}${hex()}${hex()}`;
+}
+function mockString(key, def, ctx) {
+  const lower = key.toLowerCase();
+  const checks = def.checks ?? [];
+  const check = (kind) => checks.find((c) => c.kind === kind)?.value;
+  const format = checks.find((c) => c.kind === "format")?.value;
+  const hasCheck = (kind) => checks.some((c) => c.kind === kind);
+  let value;
+  if (format === "email" || hasCheck("email") || lower.includes("email")) {
+    const name = pick(FIRST_NAMES, ctx.rng).toLowerCase();
+    value = `${name}.${pick(LAST_NAMES, ctx.rng).toLowerCase()}@example.com`;
+  } else if (hasCheck("uuid")) {
+    value = mockUuid(ctx.rng);
+  } else if (hasCheck("datetime") || lower === "createdat" || lower === "updatedat" || lower.endsWith("date") || lower.endsWith("_at")) {
+    value = new Date(MOCK_EPOCH - Math.floor(ctx.rng() * YEAR_MS)).toISOString();
+  } else if (hasCheck("url") || lower.endsWith("url") || lower.endsWith("link")) {
+    value = `https://example.com/${pick(WORDS, ctx.rng)}/${intBetween(ctx.rng, 1, 999)}`;
+  } else if (lower.includes("phone") || lower.includes("tel")) {
+    value = `+1 555 010 ${intBetween(ctx.rng, 1e3, 9999)}`;
+  } else if (lower === "id" || lower.endsWith("_id") || lower.endsWith("id")) {
+    value = `id-${intBetween(ctx.rng, 1, 99999)}`;
+  } else if (lower.includes("slug")) {
+    value = `${pick(WORDS, ctx.rng)}-${intBetween(ctx.rng, 1, 999)}`;
+  } else if (lower === "name" || lower.endsWith("name")) {
+    value = `${pick(FIRST_NAMES, ctx.rng)} ${pick(LAST_NAMES, ctx.rng)}`;
+  } else if (lower === "title") {
+    value = `${pick(WORDS, ctx.rng)} title`;
+  } else if (lower.includes("password") || lower.includes("token") || lower.includes("secret")) {
+    value = "********";
+  } else if (lower.includes("description") || lower === "bio" || lower === "text") {
+    value = `Mock ${pick(WORDS, ctx.rng)} description for automated testing.`;
+  } else {
+    value = `${pick(WORDS, ctx.rng)}-${intBetween(ctx.rng, 1, 9999)}`;
+  }
+  const minLength = check("min");
+  if (minLength !== void 0) {
+    while (value.length < minLength) value += "-filler";
+  }
+  const maxLength = check("max");
+  if (maxLength !== void 0 && value.length > maxLength) {
+    value = value.slice(0, maxLength);
+  }
+  return value;
+}
+function mockNumber(def, ctx) {
+  const checks = def.checks ?? [];
+  const isInt = checks.some((c) => c.kind === "int");
+  const min = checks.find((c) => c.kind === "min")?.value ?? 1;
+  const max = checks.find((c) => c.kind === "max")?.value ?? 100;
+  const multipleOf = checks.find((c) => c.kind === "multipleOf")?.value;
+  if (multipleOf !== void 0 && multipleOf > 0) {
+    const minMul = Math.max(1, Math.ceil(min / multipleOf));
+    const maxMul = Math.max(minMul, Math.floor(max / multipleOf));
+    return intBetween(ctx.rng, minMul, maxMul) * multipleOf;
+  }
+  return isInt ? intBetween(ctx.rng, min, max) : Math.round((min + ctx.rng() * (max - min)) * 100) / 100;
+}
+function singular(key) {
+  return key.endsWith("s") && key.length > 1 ? key.slice(0, -1) : key;
+}
+export function generateMockValue(schema, key, ctx) {
+  if (ctx.depth > 6) return "mock";
+  const def = zodDef(schema);
+  const kind = def.typeName ?? "unknown";
+  ctx.depth++;
+  try {
+    switch (kind) {
+      case "ZodString":
+        return mockString(key, def, ctx);
+      case "ZodNumber":
+        return mockNumber(def, ctx);
+      case "ZodBoolean":
+        return ctx.rng() < 0.75;
+      case "ZodDate":
+        return new Date(MOCK_EPOCH - Math.floor(ctx.rng() * YEAR_MS));
+      case "ZodNull":
+        return null;
+      case "ZodLiteral":
+        return def.value;
+      case "ZodEnum":
+      case "ZodNativeEnum": {
+        const values = def.values ?? [];
+        return values.length > 0 ? pick(values, ctx.rng) : "mock";
+      }
+      case "ZodArray": {
+        const element = def.type ?? def.innerType;
+        const count = intBetween(ctx.rng, 1, 3);
+        const result = [];
+        for (let i = 0; i < count; i++) {
+          result.push(element ? generateMockValue(element, singular(key), ctx) : null);
+        }
+        return result;
+      }
+      case "ZodObject": {
+        const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+        const result = {};
+        for (const [childKey, child] of Object.entries(shape ?? {})) {
+          result[childKey] = generateMockValue(child, childKey, ctx);
+        }
+        return result;
+      }
+      case "ZodUnion":
+      case "ZodDiscriminatedUnion": {
+        const options = def.options ?? [];
+        return options.length > 0 ? generateMockValue(pick(options, ctx.rng), key, ctx) : "mock";
+      }
+      case "ZodIntersection":
+        return def.left ? generateMockValue(def.left, key, ctx) : "mock";
+      case "ZodRecord": {
+        return { [`mock${key}`]: def.valueType ? generateMockValue(def.valueType, key, ctx) : "mock" };
+      }
+      case "ZodTuple": {
+        return (def.items ?? []).map((item, index) => generateMockValue(item, `${key}${index}`, ctx));
+      }
+      case "ZodOptional":
+      case "ZodCatch":
+      case "ZodBranded": {
+        return def.innerType ? generateMockValue(def.innerType, key, ctx) : "mock";
+      }
+      case "ZodNullable": {
+        return def.innerType ? generateMockValue(def.innerType, key, ctx) : null;
+      }
+      case "ZodDefault": {
+        try {
+          return typeof def.defaultValue === "function" ? def.defaultValue() : def.defaultValue;
+        } catch {
+          return def.innerType ? generateMockValue(def.innerType, key, ctx) : "mock";
+        }
+      }
+      case "ZodEffects": {
+        const inner = def.schema ?? def.innerType;
+        return inner ? generateMockValue(inner, key, ctx) : "mock";
+      }
+      default:
+        return "mock";
+    }
+  } finally {
+    ctx.depth--;
+  }
+}
+export function generateMockResponse(contract, options) {
+  const seed = ((options?.seed ?? 42) ^ strHash(contract.name ?? contract.path)) >>> 0;
+  const ctx = { rng: createRng(seed), depth: 0 };
+  if (!contract.response) return {};
+  return generateMockValue(contract.response, contract.name ?? "response", ctx);
+}
+export function autoMockContract(contract, options) {
+  mockContract(contract, {
+    response: () => generateMockResponse(contract, options),
+    delay: options?.delay
+  });
+}

package/dist/server.d.mts

@@ -1,8 +1,9 @@
-export { ContractMock, MockResponseInput, buildRequestPath, clearContractRegistry, defineApiContract, getContractByName, getContractMock, isApiContract, listRegisteredContracts, mockContract, registerContract, serializeQuery, serializeQueryValue, stableStringify } from './client.mjs';
+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 } from './shared/nuxt-api-contract.CPm9WbWA.mjs';
-export { a as API_CONTRACT_KIND, 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.CPm9WbWA.mjs';
-export { C as ContractHandler, a as ContractHandlerContext, d as defineContractHandler } from './shared/nuxt-api-contract.B9JBCRk8.mjs';
+export { s as serializeQuery, a as serializeQueryValue, b as stableStringify } from './shared/nuxt-api-contract.DZfOzVaB.mjs';
+import { a as AnyApiContract } from './shared/nuxt-api-contract.CFG8gzJH.mjs';
+export { A as API_CONTRACT_KIND, 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 { C as ContractHandler, a as ContractHandlerContext, d as defineContractHandler } from './shared/nuxt-api-contract.VCevNWQV.mjs';
 import { z, ZodType } from 'zod';
 import 'h3';
 
@@ -10,6 +11,8 @@ type ResponseValidationMode = 'never' | 'development' | 'always';
 interface RuntimeApiContractConfig {
     validateResponse?: ResponseValidationMode;
     mocks?: boolean;
+    /** Generate mock responses for contracts without an explicit mock. */
+    mocksAuto?: boolean;
 }
 /** Reads runtime contract config from the current Nitro runtime config. */
 declare function readRuntimeConfig(getConfig: () => unknown): RuntimeApiContractConfig;

package/dist/server.d.ts

@@ -1,8 +1,9 @@
-export { ContractMock, MockResponseInput, buildRequestPath, clearContractRegistry, defineApiContract, getContractByName, getContractMock, isApiContract, listRegisteredContracts, mockContract, registerContract, serializeQuery, serializeQueryValue, stableStringify } from './client.js';
+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 } from './shared/nuxt-api-contract.CPm9WbWA.js';
-export { a as API_CONTRACT_KIND, 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.CPm9WbWA.js';
-export { C as ContractHandler, a as ContractHandlerContext, d as defineContractHandler } from './shared/nuxt-api-contract.S1zqCiJX.js';
+export { s as serializeQuery, a as serializeQueryValue, b as stableStringify } from './shared/nuxt-api-contract.DZfOzVaB.js';
+import { a as AnyApiContract } from './shared/nuxt-api-contract.CFG8gzJH.js';
+export { A as API_CONTRACT_KIND, 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 { C as ContractHandler, a as ContractHandlerContext, d as defineContractHandler } from './shared/nuxt-api-contract.B_UvrNC8.js';
 import { z, ZodType } from 'zod';
 import 'h3';
 
@@ -10,6 +11,8 @@ type ResponseValidationMode = 'never' | 'development' | 'always';
 interface RuntimeApiContractConfig {
     validateResponse?: ResponseValidationMode;
     mocks?: boolean;
+    /** Generate mock responses for contracts without an explicit mock. */
+    mocksAuto?: boolean;
 }
 /** Reads runtime contract config from the current Nitro runtime config. */
 declare function readRuntimeConfig(getConfig: () => unknown): RuntimeApiContractConfig;

package/dist/server.mjs

@@ -1,11 +1,11 @@
-import { a as getContractMock } from './shared/nuxt-api-contract.QDGSGaVY.mjs';
-export { b as buildRequestPath, c as clearContractRegistry, d as defineApiContract, g as getContractByName, 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';
-import { A as ApiError, s as serializeApiError, B as BUILT_IN_ERROR_CODES } from './shared/nuxt-api-contract.obS6uV8A.mjs';
-export { c as createApiError, i as isApiError, p as parseApiErrorPayload, t as toApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
+import { e as getContractMock, A as ApiError, s as serializeApiError, B as BUILT_IN_ERROR_CODES } from './shared/nuxt-api-contract.CHdRLlU7.mjs';
+export { b as buildRequestPath, c as clearContractRegistry, a as createApiError, d as defineApiContract, g as getContractByName, i as isApiContract, f as isApiError, l as listRegisteredContracts, m as mockContract, p as parseApiErrorPayload, r as registerContract, t as toApiError } from './shared/nuxt-api-contract.CHdRLlU7.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';
 import { defineEventHandler, getRequestHeaders, getQuery, readValidatedBody, setResponseStatus } from 'h3';
-import { v as validateContractInput, r as readRuntimeConfig, s as shouldValidateResponse, a as validateContractResponse } from './shared/nuxt-api-contract.DDpgZj2g.mjs';
-export { b as rawQuerySchema } from './shared/nuxt-api-contract.DDpgZj2g.mjs';
+import { g as generateMockResponse } from './shared/nuxt-api-contract.BWgzVTNN.mjs';
+import { v as validateContractInput, r as readRuntimeConfig, s as shouldValidateResponse, a as validateContractResponse } from './shared/nuxt-api-contract.CAIOgncy.mjs';
+export { b as rawQuerySchema } from './shared/nuxt-api-contract.CAIOgncy.mjs';
 import 'zod';
 
 const CONTRACT_HANDLER_META = Symbol.for("nuxt-api-contract.contractHandlerMeta");
@@ -52,7 +52,8 @@ function defineContractHandler(contract, handler) {
         event
       };
       const runtimeConfig = readRuntimeConfig(() => useNitroRuntimeConfig(event));
-      const mock = getContractMock(contract);
+      const explicitMock = getContractMock(contract);
+      const mock = explicitMock ?? (runtimeConfig.mocksAuto ? { response: () => generateMockResponse(contract) } : void 0);
       if (runtimeConfig.mocks && mock?.response) {
         const mocked = await mock.response();
         return finalize(contract, mocked, runtimeConfig);

package/dist/shared/nuxt-api-contract.BOxyDvRy.d.mts

@@ -0,0 +1,40 @@
+import { ZodType } from 'zod';
+import { a as AnyApiContract, i as ContractHandlerResponse } from './nuxt-api-contract.CFG8gzJH.mjs';
+import { C as ContractMock } from './nuxt-api-contract.BgPd-YXc.mjs';
+
+/**
+ * Deterministic mock-data generation from contract schemas (client-safe:
+ * only depends on zod). Used by `autoMockContract`, the `apiContract.mocks:
+ * 'auto'` mode and the standalone mock server.
+ */
+
+interface MockGenerateOptions {
+    /** Seed for deterministic generation (default: 42). */
+    seed?: number;
+}
+interface RngContext {
+    rng: () => number;
+    depth: number;
+}
+/** Mulberry32 — small, fast, deterministic PRNG. */
+declare function createRng(seed: number): () => number;
+/** Walks a Zod schema and produces a plausible mock value. */
+declare function generateMockValue(schema: ZodType, key: string, ctx: RngContext): unknown;
+/**
+ * Generates a mock response matching the contract's `response` schema.
+ * Deterministic for a given contract + seed.
+ */
+declare function generateMockResponse<C extends AnyApiContract>(contract: C, options?: MockGenerateOptions): ContractHandlerResponse<C>;
+/**
+ * Registers a generated mock for a contract — the "mock preset" produced
+ * from the contract itself:
+ *
+ * ```ts
+ * import { autoMockContract } from 'nuxt-api-contract/client'
+ * autoMockContract(GetUser) // response generated from the schema
+ * ```
+ */
+declare function autoMockContract<C extends AnyApiContract>(contract: C, options?: MockGenerateOptions & Pick<ContractMock<C>, 'delay'>): void;
+
+export { autoMockContract as a, generateMockValue as b, createRng as c, generateMockResponse as g };
+export type { MockGenerateOptions as M };

package/dist/shared/nuxt-api-contract.BWgzVTNN.mjs

@@ -0,0 +1,191 @@
+import { m as mockContract } from './nuxt-api-contract.CHdRLlU7.mjs';
+
+function zodDef(schema) {
+  return schema._def;
+}
+function createRng(seed) {
+  let state = seed >>> 0;
+  return function() {
+    state = state + 1831565813 | 0;
+    let t = state;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function strHash(value) {
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function pick(items, rng) {
+  return items[Math.floor(rng() * items.length) % items.length];
+}
+function intBetween(rng, min, max) {
+  return Math.floor(min + rng() * (max - min + 1));
+}
+const FIRST_NAMES = ["John", "Jane", "Alex", "Maria", "Ivan", "Elena"];
+const LAST_NAMES = ["Doe", "Smith", "Brown", "Ivanov", "Miller"];
+const WORDS = ["mock", "demo", "sample", "alpha", "beta", "gamma"];
+const MOCK_EPOCH = Date.UTC(2024, 0, 1);
+const YEAR_MS = 365 * 24 * 3600 * 1e3;
+function mockUuid(rng) {
+  const hex = () => Math.floor(rng() * 65535).toString(16).padStart(4, "0");
+  return `${hex()}${hex()}-4${hex().slice(1)}-8${hex().slice(1)}-4${hex().slice(1)}-${hex()}${hex()}${hex()}`;
+}
+function mockString(key, def, ctx) {
+  const lower = key.toLowerCase();
+  const checks = def.checks ?? [];
+  const check = (kind) => checks.find((c) => c.kind === kind)?.value;
+  const format = checks.find((c) => c.kind === "format")?.value;
+  const hasCheck = (kind) => checks.some((c) => c.kind === kind);
+  let value;
+  if (format === "email" || hasCheck("email") || lower.includes("email")) {
+    const name = pick(FIRST_NAMES, ctx.rng).toLowerCase();
+    value = `${name}.${pick(LAST_NAMES, ctx.rng).toLowerCase()}@example.com`;
+  } else if (hasCheck("uuid")) {
+    value = mockUuid(ctx.rng);
+  } else if (hasCheck("datetime") || lower === "createdat" || lower === "updatedat" || lower.endsWith("date") || lower.endsWith("_at")) {
+    value = new Date(MOCK_EPOCH - Math.floor(ctx.rng() * YEAR_MS)).toISOString();
+  } else if (hasCheck("url") || lower.endsWith("url") || lower.endsWith("link")) {
+    value = `https://example.com/${pick(WORDS, ctx.rng)}/${intBetween(ctx.rng, 1, 999)}`;
+  } else if (lower.includes("phone") || lower.includes("tel")) {
+    value = `+1 555 010 ${intBetween(ctx.rng, 1e3, 9999)}`;
+  } else if (lower === "id" || lower.endsWith("_id") || lower.endsWith("id")) {
+    value = `id-${intBetween(ctx.rng, 1, 99999)}`;
+  } else if (lower.includes("slug")) {
+    value = `${pick(WORDS, ctx.rng)}-${intBetween(ctx.rng, 1, 999)}`;
+  } else if (lower === "name" || lower.endsWith("name")) {
+    value = `${pick(FIRST_NAMES, ctx.rng)} ${pick(LAST_NAMES, ctx.rng)}`;
+  } else if (lower === "title") {
+    value = `${pick(WORDS, ctx.rng)} title`;
+  } else if (lower.includes("password") || lower.includes("token") || lower.includes("secret")) {
+    value = "********";
+  } else if (lower.includes("description") || lower === "bio" || lower === "text") {
+    value = `Mock ${pick(WORDS, ctx.rng)} description for automated testing.`;
+  } else {
+    value = `${pick(WORDS, ctx.rng)}-${intBetween(ctx.rng, 1, 9999)}`;
+  }
+  const minLength = check("min");
+  if (minLength !== void 0) {
+    while (value.length < minLength) value += "-filler";
+  }
+  const maxLength = check("max");
+  if (maxLength !== void 0 && value.length > maxLength) {
+    value = value.slice(0, maxLength);
+  }
+  return value;
+}
+function mockNumber(def, ctx) {
+  const checks = def.checks ?? [];
+  const isInt = checks.some((c) => c.kind === "int");
+  const min = checks.find((c) => c.kind === "min")?.value ?? 1;
+  const max = checks.find((c) => c.kind === "max")?.value ?? 100;
+  const multipleOf = checks.find((c) => c.kind === "multipleOf")?.value;
+  if (multipleOf !== void 0 && multipleOf > 0) {
+    const minMul = Math.max(1, Math.ceil(min / multipleOf));
+    const maxMul = Math.max(minMul, Math.floor(max / multipleOf));
+    return intBetween(ctx.rng, minMul, maxMul) * multipleOf;
+  }
+  return isInt ? intBetween(ctx.rng, min, max) : Math.round((min + ctx.rng() * (max - min)) * 100) / 100;
+}
+function singular(key) {
+  return key.endsWith("s") && key.length > 1 ? key.slice(0, -1) : key;
+}
+function generateMockValue(schema, key, ctx) {
+  if (ctx.depth > 6) return "mock";
+  const def = zodDef(schema);
+  const kind = def.typeName ?? "unknown";
+  ctx.depth++;
+  try {
+    switch (kind) {
+      case "ZodString":
+        return mockString(key, def, ctx);
+      case "ZodNumber":
+        return mockNumber(def, ctx);
+      case "ZodBoolean":
+        return ctx.rng() < 0.75;
+      case "ZodDate":
+        return new Date(MOCK_EPOCH - Math.floor(ctx.rng() * YEAR_MS));
+      case "ZodNull":
+        return null;
+      case "ZodLiteral":
+        return def.value;
+      case "ZodEnum":
+      case "ZodNativeEnum": {
+        const values = def.values ?? [];
+        return values.length > 0 ? pick(values, ctx.rng) : "mock";
+      }
+      case "ZodArray": {
+        const element = def.type ?? def.innerType;
+        const count = intBetween(ctx.rng, 1, 3);
+        const result = [];
+        for (let i = 0; i < count; i++) {
+          result.push(element ? generateMockValue(element, singular(key), ctx) : null);
+        }
+        return result;
+      }
+      case "ZodObject": {
+        const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+        const result = {};
+        for (const [childKey, child] of Object.entries(shape ?? {})) {
+          result[childKey] = generateMockValue(child, childKey, ctx);
+        }
+        return result;
+      }
+      case "ZodUnion":
+      case "ZodDiscriminatedUnion": {
+        const options = def.options ?? [];
+        return options.length > 0 ? generateMockValue(pick(options, ctx.rng), key, ctx) : "mock";
+      }
+      case "ZodIntersection":
+        return def.left ? generateMockValue(def.left, key, ctx) : "mock";
+      case "ZodRecord": {
+        return { [`mock${key}`]: def.valueType ? generateMockValue(def.valueType, key, ctx) : "mock" };
+      }
+      case "ZodTuple": {
+        return (def.items ?? []).map((item, index) => generateMockValue(item, `${key}${index}`, ctx));
+      }
+      case "ZodOptional":
+      case "ZodCatch":
+      case "ZodBranded": {
+        return def.innerType ? generateMockValue(def.innerType, key, ctx) : "mock";
+      }
+      case "ZodNullable": {
+        return def.innerType ? generateMockValue(def.innerType, key, ctx) : null;
+      }
+      case "ZodDefault": {
+        try {
+          return typeof def.defaultValue === "function" ? def.defaultValue() : def.defaultValue;
+        } catch {
+          return def.innerType ? generateMockValue(def.innerType, key, ctx) : "mock";
+        }
+      }
+      case "ZodEffects": {
+        const inner = def.schema ?? def.innerType;
+        return inner ? generateMockValue(inner, key, ctx) : "mock";
+      }
+      default:
+        return "mock";
+    }
+  } finally {
+    ctx.depth--;
+  }
+}
+function generateMockResponse(contract, options) {
+  const seed = ((options?.seed ?? 42) ^ strHash(contract.name ?? contract.path)) >>> 0;
+  const ctx = { rng: createRng(seed), depth: 0 };
+  if (!contract.response) return {};
+  return generateMockValue(contract.response, contract.name ?? "response", ctx);
+}
+function autoMockContract(contract, options) {
+  mockContract(contract, {
+    response: () => generateMockResponse(contract, options),
+    delay: options?.delay
+  });
+}
+
+export { autoMockContract as a, generateMockValue as b, createRng as c, generateMockResponse as g };

package/dist/shared/{nuxt-api-contract.S1zqCiJX.d.ts → nuxt-api-contract.B_UvrNC8.d.ts}

@@ -1,6 +1,6 @@
 import { H3Event, EventHandler } from 'h3';
 import { z } from 'zod';
-import { A as AnyApiContract, M as MaybePromise, i as ContractHandlerResponse } from './nuxt-api-contract.CPm9WbWA.js';
+import { a as AnyApiContract, M as MaybePromise, i as ContractHandlerResponse } from './nuxt-api-contract.CFG8gzJH.js';
 
 type Infer<T> = T extends z.ZodType ? z.infer<T> : never;
 /**

package/dist/shared/nuxt-api-contract.BgPd-YXc.d.mts

@@ -0,0 +1,53 @@
+import * as zod from 'zod';
+import { a as AnyApiContract, M as MaybePromise, i as ContractHandlerResponse, c as ApiContractDefinition, h as ContractFromDefinition } from './nuxt-api-contract.CFG8gzJH.mjs';
+
+/**
+ * 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;
+
+export { getContractMock as a, buildRequestPath as b, clearContractRegistry as c, defineApiContract as d, getContractByName as g, isApiContract as i, listRegisteredContracts as l, mockContract as m, registerContract as r };
+export type { ContractMock as C, MockResponseInput as M };

package/dist/shared/nuxt-api-contract.BuWjAHJe.d.ts

@@ -0,0 +1,40 @@
+import { ZodType } from 'zod';
+import { a as AnyApiContract, i as ContractHandlerResponse } from './nuxt-api-contract.CFG8gzJH.js';
+import { C as ContractMock } from './nuxt-api-contract.C7KxMQHa.js';
+
+/**
+ * Deterministic mock-data generation from contract schemas (client-safe:
+ * only depends on zod). Used by `autoMockContract`, the `apiContract.mocks:
+ * 'auto'` mode and the standalone mock server.
+ */
+
+interface MockGenerateOptions {
+    /** Seed for deterministic generation (default: 42). */
+    seed?: number;
+}
+interface RngContext {
+    rng: () => number;
+    depth: number;
+}
+/** Mulberry32 — small, fast, deterministic PRNG. */
+declare function createRng(seed: number): () => number;
+/** Walks a Zod schema and produces a plausible mock value. */
+declare function generateMockValue(schema: ZodType, key: string, ctx: RngContext): unknown;
+/**
+ * Generates a mock response matching the contract's `response` schema.
+ * Deterministic for a given contract + seed.
+ */
+declare function generateMockResponse<C extends AnyApiContract>(contract: C, options?: MockGenerateOptions): ContractHandlerResponse<C>;
+/**
+ * Registers a generated mock for a contract — the "mock preset" produced
+ * from the contract itself:
+ *
+ * ```ts
+ * import { autoMockContract } from 'nuxt-api-contract/client'
+ * autoMockContract(GetUser) // response generated from the schema
+ * ```
+ */
+declare function autoMockContract<C extends AnyApiContract>(contract: C, options?: MockGenerateOptions & Pick<ContractMock<C>, 'delay'>): void;
+
+export { autoMockContract as a, generateMockValue as b, createRng as c, generateMockResponse as g };
+export type { MockGenerateOptions as M };