nuxt-api-contract 0.1.0 → 0.3.0

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

@@ -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.js';
+
+/**
+ * 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.DDpgZj2g.mjs → nuxt-api-contract.CAIOgncy.mjs}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { c as createApiError, B as BUILT_IN_ERROR_CODES } from './nuxt-api-contract.obS6uV8A.mjs';
+import { a as createApiError, B as BUILT_IN_ERROR_CODES } from './nuxt-api-contract.CHdRLlU7.mjs';
 import { t as toValidationIssues, s as sanitizeIssues, f as formatValidationMessage } from './nuxt-api-contract.DCAU2j7t.mjs';
 
 function readRuntimeConfig(getConfig) {

package/dist/shared/{nuxt-api-contract.CPm9WbWA.d.mts → nuxt-api-contract.CFG8gzJH.d.mts}

@@ -161,5 +161,5 @@ type ResolvedApiRequestOptions = {
  */
 type ExtractSchemaOutput<T> = T extends ZodType<infer Output, any, any> ? Output : unknown;
 
-export { API_CONTRACT_KIND as a };
-export type { AnyApiContract as A, ContractBodyInput as C, EmptyObject as E, HttpMethod as H, IsEmptyObject as I, MaybePromise as M, PathParams as P, ResolvedApiRequestOptions as R, SplitPath as S, ApiContract as b, ApiContractDefinition as c, ApiRequestOptions as d, AuthConfig as e, ContractClientResponse as f, ContractErrorCode as g, ContractFromDefinition as h, ContractHandlerResponse as i, ContractHeadersInput as j, ContractParamsInput as k, ContractPathParams as l, ContractQueryInput as m, ExtractSchemaInput as n, ExtractSchemaOutput as o };
+export { API_CONTRACT_KIND as A };
+export type { ContractBodyInput as C, EmptyObject as E, HttpMethod as H, IsEmptyObject as I, MaybePromise as M, PathParams as P, ResolvedApiRequestOptions as R, SplitPath as S, AnyApiContract as a, ApiContract as b, ApiContractDefinition as c, ApiRequestOptions as d, AuthConfig as e, ContractClientResponse as f, ContractErrorCode as g, ContractFromDefinition as h, ContractHandlerResponse as i, ContractHeadersInput as j, ContractParamsInput as k, ContractPathParams as l, ContractQueryInput as m, ExtractSchemaInput as n, ExtractSchemaOutput as o };

package/dist/shared/{nuxt-api-contract.CPm9WbWA.d.ts → nuxt-api-contract.CFG8gzJH.d.ts}

@@ -161,5 +161,5 @@ type ResolvedApiRequestOptions = {
  */
 type ExtractSchemaOutput<T> = T extends ZodType<infer Output, any, any> ? Output : unknown;
 
-export { API_CONTRACT_KIND as a };
-export type { AnyApiContract as A, ContractBodyInput as C, EmptyObject as E, HttpMethod as H, IsEmptyObject as I, MaybePromise as M, PathParams as P, ResolvedApiRequestOptions as R, SplitPath as S, ApiContract as b, ApiContractDefinition as c, ApiRequestOptions as d, AuthConfig as e, ContractClientResponse as f, ContractErrorCode as g, ContractFromDefinition as h, ContractHandlerResponse as i, ContractHeadersInput as j, ContractParamsInput as k, ContractPathParams as l, ContractQueryInput as m, ExtractSchemaInput as n, ExtractSchemaOutput as o };
+export { API_CONTRACT_KIND as A };
+export type { ContractBodyInput as C, EmptyObject as E, HttpMethod as H, IsEmptyObject as I, MaybePromise as M, PathParams as P, ResolvedApiRequestOptions as R, SplitPath as S, AnyApiContract as a, ApiContract as b, ApiContractDefinition as c, ApiRequestOptions as d, AuthConfig as e, ContractClientResponse as f, ContractErrorCode as g, ContractFromDefinition as h, ContractHandlerResponse as i, ContractHeadersInput as j, ContractParamsInput as k, ContractPathParams as l, ContractQueryInput as m, ExtractSchemaInput as n, ExtractSchemaOutput as o };

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

@@ -0,0 +1,152 @@
+const API_CONTRACT_KIND = "api-contract";
+
+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];
+}
+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);
+}
+function getContractByName(name) {
+  return getStore().contracts.get(name);
+}
+function listRegisteredContracts() {
+  return [...getStore().contracts.values()];
+}
+function clearContractRegistry() {
+  getStore().contracts.clear();
+}
+const MOCK_STORE_KEY = Symbol.for("nuxt-api-contract.mocks");
+const mockStore = globalThis[MOCK_STORE_KEY] ??= /* @__PURE__ */ new Map();
+function mockContract(contract, mock) {
+  mockStore.set(contract, mock);
+}
+function getContractMock(contract) {
+  return mockStore.get(contract);
+}
+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;
+}
+function isApiContract(value) {
+  return typeof value === "object" && value !== null && value.kind === API_CONTRACT_KIND;
+}
+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;
+}
+
+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);
+  }
+}
+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
+  });
+}
+function isApiError(value) {
+  return value instanceof ApiError || typeof value === "object" && value !== null && value.name === "ApiError" && typeof value.code === "string";
+}
+function serializeApiError(error) {
+  return {
+    error: {
+      code: error.code,
+      message: error.message,
+      statusCode: error.statusCode,
+      details: error.details,
+      issues: error.issues
+    }
+  };
+}
+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
+  };
+}
+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 });
+}
+const BUILT_IN_ERROR_CODES = {
+  validation: "VALIDATION_ERROR",
+  responseValidation: "API_CONTRACT_RESPONSE_VALIDATION_ERROR",
+  internal: "INTERNAL_ERROR",
+  notFound: "NOT_FOUND",
+  methodNotAllowed: "METHOD_NOT_ALLOWED"
+};
+
+export { ApiError as A, BUILT_IN_ERROR_CODES as B, createApiError as a, buildRequestPath as b, clearContractRegistry as c, defineApiContract as d, getContractMock as e, isApiError as f, getContractByName as g, isApiContract as i, listRegisteredContracts as l, mockContract as m, parseApiErrorPayload as p, registerContract as r, serializeApiError as s, toApiError as t };

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

@@ -0,0 +1,16 @@
+/**
+ * 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 { serializeQueryValue as a, stableStringify as b, serializeQuery as s };

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

@@ -0,0 +1,16 @@
+/**
+ * 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 { serializeQueryValue as a, stableStringify as b, serializeQuery as s };

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

@@ -0,0 +1,38 @@
+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;
+}
+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;
+}
+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;
+}
+
+export { serializeQueryValue as a, stableStringify as b, serializeQuery as s };

package/dist/shared/{nuxt-api-contract.B9JBCRk8.d.mts → nuxt-api-contract.VCevNWQV.d.mts}

@@ -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.mjs';
+import { a as AnyApiContract, M as MaybePromise, i as ContractHandlerResponse } from './nuxt-api-contract.CFG8gzJH.mjs';
 
 type Infer<T> = T extends z.ZodType ? z.infer<T> : never;
 /**

package/dist/shared.d.mts

@@ -1,4 +1,6 @@
-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';
-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.CPm9WbWA.mjs';
+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, c as createRng, g as generateMockResponse, b as generateMockValue } from './shared/nuxt-api-contract.BOxyDvRy.mjs';
 import 'zod';

package/dist/shared.d.ts

@@ -1,4 +1,6 @@
-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';
-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.CPm9WbWA.js';
+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, c as createRng, g as generateMockResponse, b as generateMockValue } from './shared/nuxt-api-contract.BuWjAHJe.js';
 import 'zod';

package/dist/shared.mjs

@@ -1,3 +1,4 @@
-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 { 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 { A as ApiError, B as BUILT_IN_ERROR_CODES, b as buildRequestPath, c as clearContractRegistry, a as createApiError, d as defineApiContract, g as getContractByName, e as getContractMock, i as isApiContract, f as isApiError, l as listRegisteredContracts, m as mockContract, p as parseApiErrorPayload, r as registerContract, s as serializeApiError, 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';
+export { a as autoMockContract, c as createRng, g as generateMockResponse, b as generateMockValue } from './shared/nuxt-api-contract.BWgzVTNN.mjs';

package/dist/testing.d.mts

@@ -1,5 +1,5 @@
 import { H3Event, EventHandler } from 'h3';
-import { AnyApiContract, ContractClientResponse } from './client.mjs';
+import { AnyApiContract, ContractClientResponse, HttpMethod } from './client.mjs';
 import { ApiError } from './client.mjs';
 import { ContractHandler } from './server.mjs';
 import 'zod';
@@ -20,9 +20,9 @@ interface ContractHandlerMeta {
         body: unknown;
         headers: unknown;
         event: H3Event;
-    }) => Awaitable<unknown>;
+    }) => Awaitable$1<unknown>;
 }
-type Awaitable<T> = T | Promise<T>;
+type Awaitable$1<T> = T | Promise<T>;
 /**
  * Calls a contract handler pipeline directly (no HTTP server):
  *
@@ -47,9 +47,114 @@ declare function callContract<C extends AnyApiContract>(contract: C, handler: Co
     data: null;
     error: ApiError;
 }>;
-type EventHandlerLike = (ctx: Record<string, unknown>) => Awaitable<unknown>;
+type EventHandlerLike = (ctx: Record<string, unknown>) => Awaitable$1<unknown>;
 /** Exposed so the module-level `defineContractHandler` can attach metadata. */
 declare const contractHandlerMetaKey: symbol;
 
-export { callContract, contractHandlerMetaKey };
-export type { ContractHandlerMeta };
+/**
+ * `testContract` — a testing suite bound to a contract + handler.
+ *
+ * Framework-agnostic: every `expect*` method throws a
+ * `ContractAssertionError` on failure, so it works with Vitest, Jest,
+ * `node:assert` and any other runner that treats thrown errors as failures.
+ *
+ * ```ts
+ * import { testContract } from 'nuxt-api-contract/testing'
+ *
+ * const user = testContract(GetUser, handler)
+ *
+ * it('returns the user', async () => {
+ *   await user.expectSuccess({ params: { id: '1' } })
+ * })
+ * ```
+ */
+
+type Awaitable<T> = T | Promise<T>;
+type TestHandler<C extends AnyApiContract> = ContractHandler<C> | EventHandler | ((ctx: Record<string, unknown>) => Awaitable<unknown>);
+interface ContractTestInput {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** Thrown by every failed `testContract` assertion. */
+declare class ContractAssertionError extends Error {
+    constructor(message: string);
+}
+interface ContractTestSuite<C extends AnyApiContract> {
+    /** Runs the full pipeline (validation -> handler -> response validation). */
+    call(input?: ContractTestInput): Promise<{
+        data: ContractClientResponse<C> | null;
+        error: ApiError | null;
+    }>;
+    /** Asserts the call succeeds; returns the typed response data. */
+    expectSuccess(input?: ContractTestInput): Promise<ContractClientResponse<C>>;
+    /** Asserts the call fails with (optionally) the given code and status. */
+    expectError(input?: ContractTestInput, code?: string, statusCode?: number): Promise<ApiError>;
+    /** Asserts a `VALIDATION_ERROR`; optionally checks that issues cover the given paths. */
+    expectValidationError(input?: ContractTestInput, issuePaths?: string[]): Promise<ApiError>;
+    /** Asserts the response validation catches a bad handler output. */
+    expectResponseValidationError(input: ContractTestInput, badResponse: unknown | ((ctx: Record<string, unknown>) => unknown)): Promise<ApiError>;
+    /** Validates an arbitrary value against the contract's response schema. */
+    validateResponse(value: unknown): void;
+}
+/**
+ * Creates a test suite for a contract + handler pair.
+ *
+ * ```ts
+ * const suite = testContract(GetUser, handler)
+ *
+ * await suite.expectSuccess({ params: { id: '1' } })
+ * await suite.expectError({ params: { id: 'missing' } }, 'USER_NOT_FOUND', 404)
+ * await suite.expectValidationError({ params: { id: '' } }, ['params.id'])
+ * ```
+ */
+declare function testContract<C extends AnyApiContract>(contract: C, handler: TestHandler<C>): ContractTestSuite<C>;
+
+/**
+ * Contract coverage tracking: records which registered contracts have been
+ * exercised through `callContract` / `testContract` (and with which outcome).
+ * Enable it in a test setup hook and print the report in an after-hook:
+ *
+ * ```ts
+ * import { startContractCoverage, formatContractCoverage, getContractCoverage } from 'nuxt-api-contract/testing'
+ *
+ * beforeAll(() => startContractCoverage())
+ * afterAll(() => console.log(formatContractCoverage(getContractCoverage())))
+ * ```
+ */
+
+interface ContractCoverageEntry {
+    /** Contract name, or `METHOD path` for anonymous contracts. */
+    key: string;
+    name?: string;
+    method: HttpMethod;
+    path: string;
+    calls: number;
+    failures: number;
+}
+interface ContractCoverageReport {
+    /** Named contracts registered in the registry at report time. */
+    total: number;
+    coveredCount: number;
+    percent: number;
+    covered: ContractCoverageEntry[];
+    uncovered: Array<{
+        name?: string;
+        method: HttpMethod;
+        path: string;
+    }>;
+}
+/** Starts (and resets) coverage recording. */
+declare function startContractCoverage(): void;
+/** Stops recording and returns the final report. */
+declare function stopContractCoverage(): ContractCoverageReport;
+/** Clears recorded stats without changing the active state. */
+declare function resetContractCoverage(): void;
+/** Builds the coverage report against the currently registered contracts. */
+declare function getContractCoverage(): ContractCoverageReport;
+/** Formats the report as a human-readable table for test output. */
+declare function formatContractCoverage(report: ContractCoverageReport): string;
+
+export { ContractAssertionError, callContract, contractHandlerMetaKey, formatContractCoverage, getContractCoverage, resetContractCoverage, startContractCoverage, stopContractCoverage, testContract };
+export type { ContractCoverageEntry, ContractCoverageReport, ContractHandlerMeta, ContractTestInput, ContractTestSuite, TestHandler };

package/dist/testing.d.ts

@@ -1,5 +1,5 @@
 import { H3Event, EventHandler } from 'h3';
-import { AnyApiContract, ContractClientResponse } from './client.js';
+import { AnyApiContract, ContractClientResponse, HttpMethod } from './client.js';
 import { ApiError } from './client.js';
 import { ContractHandler } from './server.js';
 import 'zod';
@@ -20,9 +20,9 @@ interface ContractHandlerMeta {
         body: unknown;
         headers: unknown;
         event: H3Event;
-    }) => Awaitable<unknown>;
+    }) => Awaitable$1<unknown>;
 }
-type Awaitable<T> = T | Promise<T>;
+type Awaitable$1<T> = T | Promise<T>;
 /**
  * Calls a contract handler pipeline directly (no HTTP server):
  *
@@ -47,9 +47,114 @@ declare function callContract<C extends AnyApiContract>(contract: C, handler: Co
     data: null;
     error: ApiError;
 }>;
-type EventHandlerLike = (ctx: Record<string, unknown>) => Awaitable<unknown>;
+type EventHandlerLike = (ctx: Record<string, unknown>) => Awaitable$1<unknown>;
 /** Exposed so the module-level `defineContractHandler` can attach metadata. */
 declare const contractHandlerMetaKey: symbol;
 
-export { callContract, contractHandlerMetaKey };
-export type { ContractHandlerMeta };
+/**
+ * `testContract` — a testing suite bound to a contract + handler.
+ *
+ * Framework-agnostic: every `expect*` method throws a
+ * `ContractAssertionError` on failure, so it works with Vitest, Jest,
+ * `node:assert` and any other runner that treats thrown errors as failures.
+ *
+ * ```ts
+ * import { testContract } from 'nuxt-api-contract/testing'
+ *
+ * const user = testContract(GetUser, handler)
+ *
+ * it('returns the user', async () => {
+ *   await user.expectSuccess({ params: { id: '1' } })
+ * })
+ * ```
+ */
+
+type Awaitable<T> = T | Promise<T>;
+type TestHandler<C extends AnyApiContract> = ContractHandler<C> | EventHandler | ((ctx: Record<string, unknown>) => Awaitable<unknown>);
+interface ContractTestInput {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** Thrown by every failed `testContract` assertion. */
+declare class ContractAssertionError extends Error {
+    constructor(message: string);
+}
+interface ContractTestSuite<C extends AnyApiContract> {
+    /** Runs the full pipeline (validation -> handler -> response validation). */
+    call(input?: ContractTestInput): Promise<{
+        data: ContractClientResponse<C> | null;
+        error: ApiError | null;
+    }>;
+    /** Asserts the call succeeds; returns the typed response data. */
+    expectSuccess(input?: ContractTestInput): Promise<ContractClientResponse<C>>;
+    /** Asserts the call fails with (optionally) the given code and status. */
+    expectError(input?: ContractTestInput, code?: string, statusCode?: number): Promise<ApiError>;
+    /** Asserts a `VALIDATION_ERROR`; optionally checks that issues cover the given paths. */
+    expectValidationError(input?: ContractTestInput, issuePaths?: string[]): Promise<ApiError>;
+    /** Asserts the response validation catches a bad handler output. */
+    expectResponseValidationError(input: ContractTestInput, badResponse: unknown | ((ctx: Record<string, unknown>) => unknown)): Promise<ApiError>;
+    /** Validates an arbitrary value against the contract's response schema. */
+    validateResponse(value: unknown): void;
+}
+/**
+ * Creates a test suite for a contract + handler pair.
+ *
+ * ```ts
+ * const suite = testContract(GetUser, handler)
+ *
+ * await suite.expectSuccess({ params: { id: '1' } })
+ * await suite.expectError({ params: { id: 'missing' } }, 'USER_NOT_FOUND', 404)
+ * await suite.expectValidationError({ params: { id: '' } }, ['params.id'])
+ * ```
+ */
+declare function testContract<C extends AnyApiContract>(contract: C, handler: TestHandler<C>): ContractTestSuite<C>;
+
+/**
+ * Contract coverage tracking: records which registered contracts have been
+ * exercised through `callContract` / `testContract` (and with which outcome).
+ * Enable it in a test setup hook and print the report in an after-hook:
+ *
+ * ```ts
+ * import { startContractCoverage, formatContractCoverage, getContractCoverage } from 'nuxt-api-contract/testing'
+ *
+ * beforeAll(() => startContractCoverage())
+ * afterAll(() => console.log(formatContractCoverage(getContractCoverage())))
+ * ```
+ */
+
+interface ContractCoverageEntry {
+    /** Contract name, or `METHOD path` for anonymous contracts. */
+    key: string;
+    name?: string;
+    method: HttpMethod;
+    path: string;
+    calls: number;
+    failures: number;
+}
+interface ContractCoverageReport {
+    /** Named contracts registered in the registry at report time. */
+    total: number;
+    coveredCount: number;
+    percent: number;
+    covered: ContractCoverageEntry[];
+    uncovered: Array<{
+        name?: string;
+        method: HttpMethod;
+        path: string;
+    }>;
+}
+/** Starts (and resets) coverage recording. */
+declare function startContractCoverage(): void;
+/** Stops recording and returns the final report. */
+declare function stopContractCoverage(): ContractCoverageReport;
+/** Clears recorded stats without changing the active state. */
+declare function resetContractCoverage(): void;
+/** Builds the coverage report against the currently registered contracts. */
+declare function getContractCoverage(): ContractCoverageReport;
+/** Formats the report as a human-readable table for test output. */
+declare function formatContractCoverage(report: ContractCoverageReport): string;
+
+export { ContractAssertionError, callContract, contractHandlerMetaKey, formatContractCoverage, getContractCoverage, resetContractCoverage, startContractCoverage, stopContractCoverage, testContract };
+export type { ContractCoverageEntry, ContractCoverageReport, ContractHandlerMeta, ContractTestInput, ContractTestSuite, TestHandler };