nuxt-api-contract 0.1.0

package/dist/openapi.mjs

@@ -0,0 +1,312 @@
+function zodDef(schema) {
+  return schema._def;
+}
+function toOpenApiPath(path) {
+  return path.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, "{$1}");
+}
+function pathParamNames(path) {
+  return [...path.matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)].map((match) => match[1]);
+}
+function zodToJsonSchema(schema, warnings, contractLabel) {
+  const def = zodDef(schema);
+  const kind = def.typeName ?? "unknown";
+  const description = def.description;
+  const base = (schema2) => description ? { ...schema2, description } : schema2;
+  switch (kind) {
+    case "ZodString": {
+      const result = { type: "string" };
+      for (const check of def.checks ?? []) {
+        switch (check.kind) {
+          case "email":
+            result.format = "email";
+            break;
+          case "uuid":
+            result.format = "uuid";
+            break;
+          case "datetime":
+            result.format = "date-time";
+            break;
+          case "url":
+            result.format = "uri";
+            break;
+          case "min":
+            result.minLength = check.value;
+            break;
+          case "max":
+            result.maxLength = check.value;
+            break;
+        }
+      }
+      return base(result);
+    }
+    case "ZodNumber": {
+      const result = { type: "number" };
+      for (const check of def.checks ?? []) {
+        switch (check.kind) {
+          case "int":
+            result.type = "integer";
+            break;
+          case "min":
+            result.minimum = check.value;
+            break;
+          case "max":
+            result.maximum = check.value;
+            break;
+          case "multipleOf":
+            result.multipleOf = check.value;
+            break;
+        }
+      }
+      return base(result);
+    }
+    case "ZodBoolean":
+      return base({ type: "boolean" });
+    case "ZodNull":
+      return base({ type: "null" });
+    case "ZodDate":
+      return base({ type: "string", format: "date-time" });
+    case "ZodLiteral":
+      return base({ enum: [def.value], type: typeof def.value });
+    case "ZodEnum":
+      return base({ enum: def.values, type: typeof def.values?.[0] });
+    case "ZodArray": {
+      const element = def.type ?? def.innerType;
+      return base({
+        type: "array",
+        items: element ? zodToJsonSchema(element, warnings, contractLabel) : {}
+      });
+    }
+    case "ZodObject": {
+      const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+      const properties = {};
+      const required = [];
+      for (const [key, value] of Object.entries(shape ?? {})) {
+        properties[key] = zodToJsonSchema(value, warnings, contractLabel);
+        if (!isOptional(value)) required.push(key);
+      }
+      const result = { type: "object", properties };
+      if (required.length > 0) result.required = required;
+      return base(result);
+    }
+    case "ZodUnion":
+    case "ZodDiscriminatedUnion": {
+      return base({
+        anyOf: (def.options ?? []).map((option) => zodToJsonSchema(option, warnings, contractLabel))
+      });
+    }
+    case "ZodIntersection": {
+      return base({
+        allOf: [def.left, def.right].filter((part) => Boolean(part)).map((part) => zodToJsonSchema(part, warnings, contractLabel))
+      });
+    }
+    case "ZodRecord": {
+      return base({
+        type: "object",
+        additionalProperties: def.valueType ? zodToJsonSchema(def.valueType, warnings, contractLabel) : {}
+      });
+    }
+    case "ZodTuple": {
+      return base({
+        type: "array",
+        items: { anyOf: (def.items ?? []).map((item) => zodToJsonSchema(item, warnings, contractLabel)) }
+      });
+    }
+    case "ZodOptional": {
+      if (def.innerType) return zodToJsonSchema(def.innerType, warnings, contractLabel);
+      return base({});
+    }
+    case "ZodNullable": {
+      const inner = def.innerType ? zodToJsonSchema(def.innerType, warnings, contractLabel) : {};
+      return base({ ...inner, nullable: true });
+    }
+    case "ZodDefault": {
+      const inner = def.innerType ? zodToJsonSchema(def.innerType, warnings, contractLabel) : {};
+      let defaultValue;
+      try {
+        defaultValue = typeof def.defaultValue === "function" ? def.defaultValue() : def.defaultValue;
+      } catch {
+        defaultValue = void 0;
+      }
+      return base({ ...inner, default: defaultValue });
+    }
+    case "ZodCatch":
+    case "ZodBranded": {
+      return def.innerType ? zodToJsonSchema(def.innerType, warnings, contractLabel) : base({});
+    }
+    case "ZodEffects": {
+      warnings.push({
+        contract: contractLabel,
+        message: `Zod effects (${def.effect?.type ?? "unknown"}) cannot be represented in OpenAPI; the inner schema is used.`
+      });
+      const inner = def.schema ?? def.innerType;
+      return inner ? zodToJsonSchema(inner, warnings, contractLabel) : base({});
+    }
+    default: {
+      warnings.push({
+        contract: contractLabel,
+        message: `Unsupported Zod kind "${kind}" cannot be represented in OpenAPI; an empty schema is emitted.`
+      });
+      return base({});
+    }
+  }
+}
+function isOptional(schema) {
+  const typeName = zodDef(schema).typeName;
+  return typeName === "ZodOptional" || typeName === "ZodDefault";
+}
+function extractShapeProperty(schema, name, warnings, label) {
+  const def = zodDef(schema);
+  const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+  if (def.typeName === "ZodObject" && shape?.[name]) {
+    return zodToJsonSchema(shape[name], warnings, label);
+  }
+  warnings.push({
+    contract: label,
+    message: `Params schema is not a plain ZodObject; path parameter "${name}" defaults to { type: string }.`
+  });
+  return void 0;
+}
+function hasOptionalTopLevel(schema) {
+  const json = zodToJsonSchema(schema, [], "(internal)");
+  return !json.required?.length;
+}
+function contractToOperation(contract, warnings) {
+  const label = contract.name ?? `${contract.method} ${contract.path}`;
+  const parameters = [];
+  const operation = {
+    operationId: contract.name ?? `${contract.method.toLowerCase()}_${toOpenApiPath(contract.path).replace(/[^A-Za-z0-9]/g, "_")}`,
+    summary: contract.summary ?? label,
+    parameters
+  };
+  if (contract.description) operation.description = contract.description;
+  if (contract.tags?.length) operation.tags = [...contract.tags];
+  for (const name of pathParamNames(contract.path)) {
+    const schema = contract.params ? extractShapeProperty(contract.params, name, warnings, label) : void 0;
+    parameters.push({
+      name,
+      in: "path",
+      required: true,
+      schema: schema ?? { type: "string" }
+    });
+  }
+  if (contract.query) {
+    const querySchema = zodToJsonSchema(contract.query, warnings, label);
+    const properties = querySchema.properties ?? {};
+    const required = querySchema.required ?? [];
+    for (const [name, schema] of Object.entries(properties)) {
+      parameters.push({ name, in: "query", required: required.includes(name), schema });
+    }
+  }
+  if (contract.headers) {
+    const headersSchema = zodToJsonSchema(contract.headers, warnings, label);
+    const properties = headersSchema.properties ?? {};
+    const required = headersSchema.required ?? [];
+    for (const [name, schema] of Object.entries(properties)) {
+      parameters.push({ name, in: "header", required: required.includes(name), schema });
+    }
+  }
+  if (contract.body) {
+    operation.requestBody = {
+      required: !hasOptionalTopLevel(contract.body),
+      content: { "application/json": { schema: zodToJsonSchema(contract.body, warnings, label) } }
+    };
+  }
+  const responses = {};
+  responses["200"] = contract.response ? {
+    description: contract.summary ?? "Successful response",
+    content: { "application/json": { schema: zodToJsonSchema(contract.response, warnings, label) } }
+  } : { description: "Successful response" };
+  if (contract.params || contract.query || contract.body || contract.headers) {
+    responses["400"] = {
+      description: "Request validation error",
+      content: { "application/json": { schema: { $ref: "#/components/schemas/ApiValidationError" } } }
+    };
+  }
+  responses.default = {
+    description: "Unified API error",
+    content: { "application/json": { schema: { $ref: "#/components/schemas/ApiError" } } }
+  };
+  operation.responses = responses;
+  if (contract.errors) {
+    operation["x-error-codes"] = Object.keys(contract.errors);
+  }
+  return operation;
+}
+function generateOpenApiDocument(contracts, options = {}) {
+  const warnings = [];
+  const paths = {};
+  for (const contract of contracts) {
+    const openApiPath = toOpenApiPath(contract.path);
+    paths[openApiPath] ??= {};
+    const key = contract.method.toLowerCase();
+    if (paths[openApiPath][key]) {
+      warnings.push({
+        contract: contract.name ?? contract.path,
+        message: `Duplicate operation ${contract.method} ${openApiPath}; the previous definition is overwritten.`
+      });
+    }
+    paths[openApiPath][key] = contractToOperation(contract, warnings);
+  }
+  const document = {
+    openapi: "3.0.3",
+    info: {
+      title: options.title ?? "API Contracts",
+      version: options.version ?? "0.1.0",
+      ...options.description ? { description: options.description } : {}
+    },
+    paths,
+    components: {
+      schemas: {
+        ApiError: {
+          type: "object",
+          properties: {
+            error: {
+              type: "object",
+              properties: {
+                code: { type: "string" },
+                message: { type: "string" },
+                statusCode: { type: "number" }
+              },
+              required: ["code", "message"]
+            }
+          },
+          required: ["error"]
+        },
+        ApiValidationError: {
+          type: "object",
+          properties: {
+            error: {
+              type: "object",
+              properties: {
+                code: { type: "string", enum: ["VALIDATION_ERROR"] },
+                message: { type: "string" },
+                issues: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      path: { type: "string" },
+                      message: { type: "string" },
+                      expected: { type: "string" }
+                    },
+                    required: ["path", "message"]
+                  }
+                }
+              },
+              required: ["code", "message"]
+            }
+          },
+          required: ["error"]
+        }
+      }
+    }
+  };
+  return { document, warnings };
+}
+function pickContracts(values) {
+  return values.filter(
+    (value) => typeof value === "object" && value !== null && value.kind === "api-contract"
+  );
+}
+
+export { contractToOperation, generateOpenApiDocument, pickContracts, toOpenApiPath, zodToJsonSchema };

package/dist/runtime/server/devtoolsRoute.mjs

@@ -0,0 +1,6 @@
+import { html } from "#api-contracts-devtools";
+import { defineEventHandler, setHeader } from "h3";
+export default defineEventHandler((event) => {
+  setHeader(event, "content-type", "text/html");
+  return html;
+});

package/dist/runtime/server/openapiRoute.mjs

@@ -0,0 +1,6 @@
+import { document } from "#api-contracts-openapi";
+import { defineEventHandler, setHeader } from "h3";
+export default defineEventHandler((event) => {
+  setHeader(event, "content-type", "application/json");
+  return document;
+});

package/dist/runtime/shared/contract.mjs

@@ -0,0 +1,77 @@
+import { API_CONTRACT_KIND } from "./types.mjs";
+const REGISTRY_KEY = Symbol.for("nuxt-api-contract.registry");
+function getStore() {
+  const globalThis_ = globalThis;
+  if (!globalThis_[REGISTRY_KEY]) {
+    globalThis_[REGISTRY_KEY] = { contracts: /* @__PURE__ */ new Map() };
+  }
+  return globalThis_[REGISTRY_KEY];
+}
+export function registerContract(contract) {
+  if (!contract.name) return;
+  const store = getStore();
+  const existing = store.contracts.get(contract.name);
+  if (existing && existing !== contract) {
+    console.warn(
+      `[nuxt-api-contract] Duplicate contract name "${contract.name}" registered. The latest definition wins.`
+    );
+  }
+  store.contracts.set(contract.name, contract);
+}
+export function getContractByName(name) {
+  return getStore().contracts.get(name);
+}
+export function listRegisteredContracts() {
+  return [...getStore().contracts.values()];
+}
+export function clearContractRegistry() {
+  getStore().contracts.clear();
+}
+const MOCK_STORE_KEY = Symbol.for("nuxt-api-contract.mocks");
+const mockStore = globalThis[MOCK_STORE_KEY] ??= /* @__PURE__ */ new Map();
+export function mockContract(contract, mock) {
+  mockStore.set(contract, mock);
+}
+export function getContractMock(contract) {
+  return mockStore.get(contract);
+}
+export function defineApiContract(definition) {
+  const contract = {
+    kind: API_CONTRACT_KIND,
+    name: definition.name,
+    version: definition.version,
+    method: definition.method,
+    path: definition.path,
+    params: definition.params,
+    query: definition.query,
+    body: definition.body,
+    headers: definition.headers,
+    response: definition.response,
+    errors: definition.errors ? Object.freeze({ ...definition.errors }) : void 0,
+    summary: definition.summary,
+    description: definition.description,
+    tags: definition.tags ? Object.freeze([...definition.tags]) : void 0,
+    auth: definition.auth,
+    metadata: definition.metadata ? Object.freeze({ ...definition.metadata }) : void 0
+  };
+  Object.freeze(contract);
+  if (definition.name) {
+    registerContract(contract);
+  }
+  return contract;
+}
+export function isApiContract(value) {
+  return typeof value === "object" && value !== null && value.kind === API_CONTRACT_KIND;
+}
+export function buildRequestPath(path, params) {
+  let url = path;
+  for (const match of path.matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)) {
+    const name = match[1];
+    const value = params?.[name];
+    if (value === void 0 || value === null) {
+      throw new Error(`[nuxt-api-contract] Missing path parameter ":${name}" for ${path}`);
+    }
+    url = url.replace(`:${name}`, encodeURIComponent(String(value)));
+  }
+  return url;
+}

package/dist/runtime/shared/errors.mjs

@@ -0,0 +1,71 @@
+export class ApiError extends Error {
+  code;
+  statusCode;
+  details;
+  issues;
+  constructor(options) {
+    super(options.message);
+    this.name = "ApiError";
+    this.code = options.code;
+    this.statusCode = options.statusCode ?? 500;
+    this.details = options.details;
+    this.issues = options.issues;
+  }
+  toJSON() {
+    return serializeApiError(this);
+  }
+}
+export function createApiError(codeOrOptions, message, statusCode, details) {
+  if (typeof codeOrOptions === "string") {
+    return new ApiError({ code: codeOrOptions, message: message ?? codeOrOptions, statusCode, details });
+  }
+  return new ApiError({
+    code: codeOrOptions.code,
+    message: codeOrOptions.message ?? codeOrOptions.code,
+    statusCode: codeOrOptions.statusCode,
+    details: codeOrOptions.details,
+    issues: codeOrOptions.issues
+  });
+}
+export function isApiError(value) {
+  return value instanceof ApiError || typeof value === "object" && value !== null && value.name === "ApiError" && typeof value.code === "string";
+}
+export function serializeApiError(error) {
+  return {
+    error: {
+      code: error.code,
+      message: error.message,
+      statusCode: error.statusCode,
+      details: error.details,
+      issues: error.issues
+    }
+  };
+}
+export function parseApiErrorPayload(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const error = value.error;
+  if (typeof error !== "object" || error === null) return void 0;
+  const { code, message, statusCode, details, issues } = error;
+  if (typeof code !== "string" || typeof message !== "string") return void 0;
+  return {
+    code,
+    message,
+    statusCode: typeof statusCode === "number" ? statusCode : void 0,
+    details,
+    issues: Array.isArray(issues) ? issues : void 0
+  };
+}
+export function toApiError(value, fallbackMessage = "Internal server error") {
+  if (isApiError(value)) return value;
+  if (value instanceof Error) {
+    return new ApiError({ code: "INTERNAL_ERROR", message: value.message || fallbackMessage, statusCode: 500 });
+  }
+  return new ApiError({ code: "INTERNAL_ERROR", message: fallbackMessage, statusCode: 500 });
+}
+export const BUILT_IN_ERROR_CODES = {
+  validation: "VALIDATION_ERROR",
+  responseValidation: "API_CONTRACT_RESPONSE_VALIDATION_ERROR",
+  internal: "INTERNAL_ERROR",
+  notFound: "NOT_FOUND",
+  methodNotAllowed: "METHOD_NOT_ALLOWED"
+};

package/dist/runtime/shared/format.mjs

@@ -0,0 +1,32 @@
+export function toValidationIssues(error) {
+  return error.issues.map((issue) => ({
+    path: issue.path.length > 0 ? issue.path.join(".") : "(root)",
+    message: issue.message,
+    expected: "expected" in issue ? String(issue.expected) : void 0,
+    received: "received" in issue ? truncateReceived(String(issue.received)) : void 0
+  }));
+}
+export function formatValidationMessage(options) {
+  const lines = [
+    "[nuxt-api-contract]",
+    "",
+    `Invalid ${options.subject} for ${options.method} ${options.path}`,
+    ""
+  ];
+  for (const issue of options.issues) {
+    const path = issue.path === "(root)" ? options.subject : `${options.subject}.${issue.path}`;
+    lines.push(`${path}:`);
+    lines.push(`  Expected ${issue.expected ?? issue.message}`);
+    if (options.includeReceived !== false && issue.received !== void 0) {
+      lines.push(`  Received ${issue.received}`);
+    }
+  }
+  return lines.join("\n");
+}
+function truncateReceived(value, max = 80) {
+  const serialized = value.length > max ? `${value.slice(0, max)}\u2026` : value;
+  return serialized;
+}
+export function sanitizeIssues(issues) {
+  return issues.map((issue) => ({ ...issue, received: void 0 }));
+}

package/dist/runtime/shared/serialization.mjs

@@ -0,0 +1,36 @@
+export function serializeQueryValue(value) {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "bigint") return value.toString();
+  if (Array.isArray(value)) return value.map((item) => serializePrimitive(item));
+  if (value === void 0 || value === null) return "";
+  if (typeof value === "object") return JSON.stringify(value);
+  return value;
+}
+function serializePrimitive(value) {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "bigint") return value.toString();
+  if (value === void 0 || value === null || typeof value === "object") return JSON.stringify(value) ?? "";
+  return value;
+}
+export function serializeQuery(query) {
+  if (!query) return void 0;
+  const result = {};
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0) continue;
+    result[key] = serializeQueryValue(value);
+  }
+  return result;
+}
+export function stableStringify(value) {
+  return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map((item) => sortValue(item));
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "bigint") return value.toString();
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, item]) => item !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return Object.fromEntries(entries.map(([key, item]) => [key, sortValue(item)]));
+  }
+  return value;
+}

package/dist/runtime/shared/types.mjs

@@ -0,0 +1 @@
+export const API_CONTRACT_KIND = "api-contract";

package/dist/server.d.mts

@@ -0,0 +1,41 @@
+export { ContractMock, MockResponseInput, buildRequestPath, clearContractRegistry, defineApiContract, getContractByName, getContractMock, isApiContract, listRegisteredContracts, mockContract, registerContract, serializeQuery, serializeQueryValue, stableStringify } from './client.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';
+import { z, ZodType } from 'zod';
+import 'h3';
+
+type ResponseValidationMode = 'never' | 'development' | 'always';
+interface RuntimeApiContractConfig {
+    validateResponse?: ResponseValidationMode;
+    mocks?: boolean;
+}
+/** Reads runtime contract config from the current Nitro runtime config. */
+declare function readRuntimeConfig(getConfig: () => unknown): RuntimeApiContractConfig;
+/** Whether response validation is active for the current environment. */
+declare function shouldValidateResponse(mode: ResponseValidationMode | undefined): boolean;
+/**
+ * Validates an input (params / query / body / headers) against a schema and
+ * throws a typed, developer-friendly `VALIDATION_ERROR` on failure.
+ *
+ * In production the "received" values are stripped from issues so that
+ * sensitive data (passwords, tokens) is never echoed back.
+ */
+declare function validateContractInput<S extends ZodType>(contract: AnyApiContract, subject: 'params' | 'query' | 'body' | 'headers', schema: S, value: unknown): z.output<S>;
+/**
+ * Validates a handler response against the contract's response schema.
+ * Failures produce `API_CONTRACT_RESPONSE_VALIDATION_ERROR` with contract,
+ * path, method and issues — but never expose the received payload in
+ * production logs or responses.
+ */
+declare function validateContractResponse<S extends ZodType>(contract: AnyApiContract, schema: S, value: unknown): z.output<S>;
+/**
+ * Coerces a raw query object (all string values) before Zod validation is
+ * applied by the caller. Kept as an explicit seam so `z.coerce` usage stays
+ * documented and predictable.
+ */
+declare function rawQuerySchema(): z.ZodRecord<z.ZodString, z.ZodUnknown>;
+
+export { AnyApiContract, rawQuerySchema, readRuntimeConfig, shouldValidateResponse, validateContractInput, validateContractResponse };
+export type { ResponseValidationMode, RuntimeApiContractConfig };

package/dist/server.d.ts

@@ -0,0 +1,41 @@
+export { ContractMock, MockResponseInput, buildRequestPath, clearContractRegistry, defineApiContract, getContractByName, getContractMock, isApiContract, listRegisteredContracts, mockContract, registerContract, serializeQuery, serializeQueryValue, stableStringify } from './client.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';
+import { z, ZodType } from 'zod';
+import 'h3';
+
+type ResponseValidationMode = 'never' | 'development' | 'always';
+interface RuntimeApiContractConfig {
+    validateResponse?: ResponseValidationMode;
+    mocks?: boolean;
+}
+/** Reads runtime contract config from the current Nitro runtime config. */
+declare function readRuntimeConfig(getConfig: () => unknown): RuntimeApiContractConfig;
+/** Whether response validation is active for the current environment. */
+declare function shouldValidateResponse(mode: ResponseValidationMode | undefined): boolean;
+/**
+ * Validates an input (params / query / body / headers) against a schema and
+ * throws a typed, developer-friendly `VALIDATION_ERROR` on failure.
+ *
+ * In production the "received" values are stripped from issues so that
+ * sensitive data (passwords, tokens) is never echoed back.
+ */
+declare function validateContractInput<S extends ZodType>(contract: AnyApiContract, subject: 'params' | 'query' | 'body' | 'headers', schema: S, value: unknown): z.output<S>;
+/**
+ * Validates a handler response against the contract's response schema.
+ * Failures produce `API_CONTRACT_RESPONSE_VALIDATION_ERROR` with contract,
+ * path, method and issues — but never expose the received payload in
+ * production logs or responses.
+ */
+declare function validateContractResponse<S extends ZodType>(contract: AnyApiContract, schema: S, value: unknown): z.output<S>;
+/**
+ * Coerces a raw query object (all string values) before Zod validation is
+ * applied by the caller. Kept as an explicit seam so `z.coerce` usage stays
+ * documented and predictable.
+ */
+declare function rawQuerySchema(): z.ZodRecord<z.ZodString, z.ZodUnknown>;
+
+export { AnyApiContract, rawQuerySchema, readRuntimeConfig, shouldValidateResponse, validateContractInput, validateContractResponse };
+export type { ResponseValidationMode, RuntimeApiContractConfig };