nuxt-api-contract 0.1.0

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

@@ -0,0 +1,109 @@
+import { ZodError } from 'zod';
+
+/**
+ * A sanitized validation issue that is safe to send to the client.
+ */
+interface ValidationIssue {
+    /** Dotted path inside the validated value, e.g. `query.limit`. */
+    path: string;
+    /** Human readable message. */
+    message: string;
+    /** Expected type/shape description, when available. */
+    expected?: string;
+    /** Short serialized received value. Only populated outside production. */
+    received?: string;
+}
+/** Maps a Zod error into sanitized validation issues. */
+declare function toValidationIssues(error: ZodError): ValidationIssue[];
+/**
+ * Builds a developer-friendly multi-line message:
+ *
+ * ```
+ * [nuxt-api-contract]
+ *
+ * Invalid query for GET /api/users
+ *
+ * query.limit:
+ *   Expected number
+ *   Received string
+ * ```
+ */
+declare function formatValidationMessage(options: {
+    subject: string;
+    method: string;
+    path: string;
+    issues: ValidationIssue[];
+    includeReceived?: boolean;
+}): string;
+/**
+ * Strips received values from issues (used before exposing issues in
+ * production, where they may contain sensitive data such as passwords).
+ */
+declare function sanitizeIssues(issues: ValidationIssue[]): ValidationIssue[];
+
+/**
+ * Stable, machine-readable error payload sent over the wire.
+ */
+interface ApiErrorPayload {
+    error: {
+        code: string;
+        message: string;
+        statusCode?: number;
+        details?: unknown;
+        issues?: ValidationIssue[];
+    };
+}
+/**
+ * Unified API error. Thrown on the server (and converted to an h3 error),
+ * reconstructed on the client from the error payload.
+ */
+declare class ApiError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: unknown;
+    readonly issues?: ValidationIssue[];
+    constructor(options: {
+        code: string;
+        message: string;
+        statusCode?: number;
+        details?: unknown;
+        issues?: ValidationIssue[];
+    });
+    toJSON(): ApiErrorPayload;
+}
+type CreateApiErrorInput = {
+    code: string;
+    message?: string;
+    statusCode?: number;
+    details?: unknown;
+    issues?: ValidationIssue[];
+};
+/**
+ * Creates a unified API error.
+ *
+ * ```ts
+ * throw createApiError('USER_NOT_FOUND', 'User not found', 404)
+ * throw createApiError({ code: 'VALIDATION_ERROR', statusCode: 400, details })
+ * ```
+ */
+declare function createApiError(input: CreateApiErrorInput): ApiError;
+declare function createApiError(code: string, message?: string, statusCode?: number, details?: unknown): ApiError;
+/** Type guard for `ApiError` (works across module instances / payload objects). */
+declare function isApiError(value: unknown): value is ApiError;
+/** Serializes an `ApiError` into the wire payload. */
+declare function serializeApiError(error: ApiError): ApiErrorPayload;
+/** Narrows an unknown parsed payload into an `ApiError` payload, if it matches. */
+declare function parseApiErrorPayload(value: unknown): ApiErrorPayload['error'] | undefined;
+/** Wraps an unknown thrown value into an `ApiError`. */
+declare function toApiError(value: unknown, fallbackMessage?: string): ApiError;
+/** Built-in error codes. */
+declare const BUILT_IN_ERROR_CODES: {
+    readonly validation: "VALIDATION_ERROR";
+    readonly responseValidation: "API_CONTRACT_RESPONSE_VALIDATION_ERROR";
+    readonly internal: "INTERNAL_ERROR";
+    readonly notFound: "NOT_FOUND";
+    readonly methodNotAllowed: "METHOD_NOT_ALLOWED";
+};
+
+export { ApiError as A, BUILT_IN_ERROR_CODES as B, serializeApiError as b, createApiError as c, toValidationIssues as d, formatValidationMessage as f, isApiError as i, parseApiErrorPayload as p, sanitizeIssues as s, toApiError as t };
+export type { CreateApiErrorInput as C, ValidationIssue as V, ApiErrorPayload as a };

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

@@ -0,0 +1,34 @@
+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
+  }));
+}
+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;
+}
+function sanitizeIssues(issues) {
+  return issues.map((issue) => ({ ...issue, received: void 0 }));
+}
+
+export { formatValidationMessage as f, sanitizeIssues as s, toValidationIssues as t };

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

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { c as createApiError, B as BUILT_IN_ERROR_CODES } from './nuxt-api-contract.obS6uV8A.mjs';
+import { t as toValidationIssues, s as sanitizeIssues, f as formatValidationMessage } from './nuxt-api-contract.DCAU2j7t.mjs';
+
+function readRuntimeConfig(getConfig) {
+  const config = getConfig();
+  return config?.apiContract ?? {};
+}
+function shouldValidateResponse(mode) {
+  if (mode === "always") return true;
+  if (mode === "development") return process.env.NODE_ENV !== "production";
+  return false;
+}
+function validateContractInput(contract, subject, schema, value) {
+  const result = schema.safeParse(value);
+  if (result.success) {
+    return result.data;
+  }
+  const issues = toValidationIssues(result.error);
+  const isProduction = process.env.NODE_ENV === "production";
+  throw createApiError({
+    code: BUILT_IN_ERROR_CODES.validation,
+    statusCode: 400,
+    message: formatValidationMessage({
+      subject,
+      method: contract.method,
+      path: contract.path,
+      issues: isProduction ? sanitizeIssues(issues) : issues,
+      includeReceived: !isProduction
+    }),
+    details: { subject, issues: isProduction ? sanitizeIssues(issues) : issues },
+    issues: isProduction ? sanitizeIssues(issues) : issues
+  });
+}
+function validateContractResponse(contract, schema, value) {
+  const result = schema.safeParse(value);
+  if (result.success) {
+    return result.data;
+  }
+  const issues = toValidationIssues(result.error);
+  const isProduction = process.env.NODE_ENV === "production";
+  const safeIssues = isProduction ? sanitizeIssues(issues) : issues;
+  throw createApiError({
+    code: BUILT_IN_ERROR_CODES.responseValidation,
+    statusCode: 500,
+    message: formatValidationMessage({
+      subject: "response",
+      method: contract.method,
+      path: contract.path,
+      issues: safeIssues,
+      includeReceived: !isProduction
+    }),
+    details: {
+      contract: contract.name ?? "(anonymous)",
+      path: contract.path,
+      method: contract.method,
+      issues: safeIssues
+    },
+    issues: safeIssues
+  });
+}
+function rawQuerySchema() {
+  return z.record(z.string(), z.unknown());
+}
+
+export { validateContractResponse as a, rawQuerySchema as b, readRuntimeConfig as r, shouldValidateResponse as s, validateContractInput as v };

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

@@ -0,0 +1,117 @@
+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;
+}
+
+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 { getContractMock as a, buildRequestPath as b, clearContractRegistry as c, defineApiContract as d, serializeQueryValue as e, stableStringify as f, getContractByName as g, isApiContract as i, listRegisteredContracts as l, mockContract as m, registerContract as r, serializeQuery as s };

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

@@ -0,0 +1,37 @@
+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';
+
+type Infer<T> = T extends z.ZodType ? z.infer<T> : never;
+/**
+ * Context handed to contract handlers. All data is already validated.
+ */
+interface ContractHandlerContext<TParams = Record<string, unknown>, TQuery = Record<string, unknown>, TBody = undefined, THeaders = Record<string, string>> {
+    params: TParams;
+    query: TQuery;
+    body: TBody;
+    headers: THeaders;
+    /** Raw h3 event, for status codes, cookies, auth, etc. */
+    event: H3Event;
+    /** Reserved for auth integrations (populated by middleware/plugins). */
+    user?: unknown;
+}
+type ContractHandler<C extends AnyApiContract> = (ctx: ContractHandlerContext<C['params'] extends z.ZodType ? Infer<C['params']> : Record<string, unknown>, C['query'] extends z.ZodType ? Infer<C['query']> : Record<string, unknown>, C['body'] extends z.ZodType ? Infer<C['body']> : undefined, C['headers'] extends z.ZodType ? Infer<C['headers']> : Record<string, string>>) => MaybePromise<ContractHandlerResponse<C>>;
+/**
+ * Defines a Nitro event handler bound to a contract:
+ *
+ * 1. validates `params`, `query`, `body` and `headers` against the schemas;
+ * 2. invokes the handler with the validated (typed) data;
+ * 3. optionally validates the response (see `apiContract.validateResponse`);
+ * 4. converts thrown `ApiError`s into the unified error payload.
+ *
+ * ```ts
+ * export default defineContractHandler(GetUser, async ({ params }) => {
+ *   return { id: params.id, name: 'John' }
+ * })
+ * ```
+ */
+declare function defineContractHandler<C extends AnyApiContract>(contract: C, handler: ContractHandler<C>): EventHandler;
+
+export { defineContractHandler as d };
+export type { ContractHandler as C, ContractHandlerContext as a };

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

@@ -0,0 +1,73 @@
+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 c, isApiError as i, parseApiErrorPayload as p, serializeApiError as s, toApiError as t };

package/dist/shared.d.mts

@@ -0,0 +1,4 @@
+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';
+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';
+import 'zod';

package/dist/shared.d.ts

@@ -0,0 +1,4 @@
+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';
+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';
+import 'zod';

package/dist/shared.mjs

@@ -0,0 +1,3 @@
+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 { f as formatValidationMessage, s as sanitizeIssues, t as toValidationIssues } from './shared/nuxt-api-contract.DCAU2j7t.mjs';

package/dist/testing.d.mts

@@ -0,0 +1,55 @@
+import { H3Event, EventHandler } from 'h3';
+import { AnyApiContract, ContractClientResponse } from './client.mjs';
+import { ApiError } from './client.mjs';
+import { ContractHandler } from './server.mjs';
+import 'zod';
+
+/**
+ * Contract testing utilities.
+ *
+ * `callContract` executes the full pipeline — request validation, handler,
+ * response validation — without an HTTP server, which makes it usable in
+ * plain Vitest unit tests.
+ */
+
+interface ContractHandlerMeta {
+    contract: AnyApiContract;
+    handler: (ctx: {
+        params: unknown;
+        query: unknown;
+        body: unknown;
+        headers: unknown;
+        event: H3Event;
+    }) => Awaitable<unknown>;
+}
+type Awaitable<T> = T | Promise<T>;
+/**
+ * Calls a contract handler pipeline directly (no HTTP server):
+ *
+ * ```ts
+ * const { data } = await callContract(GetUserContract, handler, { params: { id } })
+ * expect(data.id).toBe(id)
+ * ```
+ *
+ * Input is validated exactly like the real handler, and the response is
+ * always validated against the contract's response schema. Throws `ApiError`
+ * with the same codes the real endpoint would produce.
+ */
+declare function callContract<C extends AnyApiContract>(contract: C, handler: ContractHandler<C> | EventHandler | EventHandlerLike, input?: {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}): Promise<{
+    data: ContractClientResponse<C>;
+    error: null;
+} | {
+    data: null;
+    error: ApiError;
+}>;
+type EventHandlerLike = (ctx: Record<string, unknown>) => Awaitable<unknown>;
+/** Exposed so the module-level `defineContractHandler` can attach metadata. */
+declare const contractHandlerMetaKey: symbol;
+
+export { callContract, contractHandlerMetaKey };
+export type { ContractHandlerMeta };

package/dist/testing.d.ts

@@ -0,0 +1,55 @@
+import { H3Event, EventHandler } from 'h3';
+import { AnyApiContract, ContractClientResponse } from './client.js';
+import { ApiError } from './client.js';
+import { ContractHandler } from './server.js';
+import 'zod';
+
+/**
+ * Contract testing utilities.
+ *
+ * `callContract` executes the full pipeline — request validation, handler,
+ * response validation — without an HTTP server, which makes it usable in
+ * plain Vitest unit tests.
+ */
+
+interface ContractHandlerMeta {
+    contract: AnyApiContract;
+    handler: (ctx: {
+        params: unknown;
+        query: unknown;
+        body: unknown;
+        headers: unknown;
+        event: H3Event;
+    }) => Awaitable<unknown>;
+}
+type Awaitable<T> = T | Promise<T>;
+/**
+ * Calls a contract handler pipeline directly (no HTTP server):
+ *
+ * ```ts
+ * const { data } = await callContract(GetUserContract, handler, { params: { id } })
+ * expect(data.id).toBe(id)
+ * ```
+ *
+ * Input is validated exactly like the real handler, and the response is
+ * always validated against the contract's response schema. Throws `ApiError`
+ * with the same codes the real endpoint would produce.
+ */
+declare function callContract<C extends AnyApiContract>(contract: C, handler: ContractHandler<C> | EventHandler | EventHandlerLike, input?: {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}): Promise<{
+    data: ContractClientResponse<C>;
+    error: null;
+} | {
+    data: null;
+    error: ApiError;
+}>;
+type EventHandlerLike = (ctx: Record<string, unknown>) => Awaitable<unknown>;
+/** Exposed so the module-level `defineContractHandler` can attach metadata. */
+declare const contractHandlerMetaKey: symbol;
+
+export { callContract, contractHandlerMetaKey };
+export type { ContractHandlerMeta };

package/dist/testing.mjs

@@ -0,0 +1,49 @@
+import { A as ApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
+import { v as validateContractInput, a as validateContractResponse } from './shared/nuxt-api-contract.DDpgZj2g.mjs';
+import 'zod';
+import './shared/nuxt-api-contract.DCAU2j7t.mjs';
+
+const CONTRACT_HANDLER_META = Symbol.for("nuxt-api-contract.contractHandlerMeta");
+async function callContract(contract, handler, input = {}) {
+  const runHandler = extractHandler(contract, handler);
+  try {
+    const params = contract.params ? validateContractInput(contract, "params", contract.params, input.params ?? {}) : input.params ?? {};
+    const query = contract.query ? validateContractInput(contract, "query", contract.query, input.query ?? {}) : input.query;
+    const body = contract.body ? validateContractInput(contract, "body", contract.body, input.body) : void 0;
+    const headers = contract.headers ? validateContractInput(contract, "headers", contract.headers, input.headers ?? {}) : input.headers ?? {};
+    const event = createFakeEvent(headers);
+    const rawResponse = await runHandler({ params, query, body, headers, event });
+    const data = contract.response ? validateContractResponse(contract, contract.response, rawResponse) : rawResponse;
+    return { data, error: null };
+  } catch (error) {
+    return {
+      data: null,
+      error: error instanceof ApiError ? error : new ApiError({ code: "INTERNAL_ERROR", message: String(error) })
+    };
+  }
+}
+function extractHandler(contract, handler) {
+  const meta = handler[CONTRACT_HANDLER_META];
+  if (meta && meta.contract.path === contract.path && meta.contract.method === contract.method) {
+    return meta.handler;
+  }
+  if (typeof handler === "function") {
+    return handler;
+  }
+  throw new Error("[nuxt-api-contract] callContract requires a contract handler function");
+}
+function createFakeEvent(headers) {
+  return {
+    context: {
+      params: {}
+    },
+    node: {
+      req: {
+        headers: Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]))
+      }
+    }
+  };
+}
+const contractHandlerMetaKey = CONTRACT_HANDLER_META;
+
+export { callContract, contractHandlerMetaKey };