nuxt-api-contract 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nuxt-api-contract contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,385 @@
+# nuxt-api-contract
+
+Type-safe API contracts between Nitro server routes and the Nuxt client.
+
+Define a contract **once** — get runtime validation, fully typed client calls,
+a unified error format, OpenAPI generation, mocks, contract tests and a
+DevTools panel from the same source of truth.
+
+> Status: `0.x` (pre-1.0, SemVer). The public API is intentionally small.
+
+## Why
+
+Without contracts, the request/response agreement between server and client
+lives in three disconnected places: a Zod schema (or nothing), a TS interface
+(or nothing) and documentation (or nothing). `nuxt-api-contract` collapses all
+of them into one object:
+
+```text
+                 ┌── runtime validation (server AND response)
+                 │
+Contract ─────────┼── TypeScript types (params / query / body / response)
+                 │
+                 ├── OpenAPI document
+                 │
+                 ├── DevTools panel
+                 │
+                 └── mocks + contract tests
+```
+
+## Installation
+
+```bash
+npm install nuxt-api-contract zod
+```
+
+Add the module:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-api-contract'],
+  apiContract: {
+    validateResponse: 'development',
+    openapi: { enabled: true, entry: 'contracts/index.ts' },
+    devtools: true,
+    mocks: false,
+  },
+})
+```
+
+Zod (`^3.23`) is a peer dependency.
+
+## Quick start
+
+```ts
+// contracts/users.ts
+import { z } from 'zod'
+import { defineApiContract } from 'nuxt-api-contract/client'
+
+export const GetUser = defineApiContract({
+  name: 'GetUser',
+  method: 'GET',
+  path: '/api/users/:id',
+  params: z.object({ id: z.string() }),
+  response: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string().email(),
+  }),
+})
+```
+
+```ts
+// server/api/users/[id].get.ts
+import { GetUser } from '../../../contracts/users'
+import { createApiError, defineContractHandler } from 'nuxt-api-contract/server'
+
+export default defineContractHandler(GetUser, async ({ params }) => {
+  const user = await db.find(params.id) // params is typed & validated
+  if (!user) throw createApiError('USER_NOT_FOUND', 'User not found', 404)
+  return user
+})
+```
+
+```vue
+<!-- pages/users/[id].vue -->
+<script setup lang="ts">
+const route = useRoute()
+const { data, error, pending } = await useApi(GetUser, {
+  params: { id: route.params.id as string },
+})
+// data.value?.name -> string | undefined (fully typed)
+</script>
+```
+
+Passing `params: { id: 123 }` is a **TypeScript error**; an invalid request is
+rejected at runtime with a `VALIDATION_ERROR`.
+
+## Defining contracts
+
+```ts
+defineApiContract({
+  name: 'CreateUser',          // optional; registers in the registry
+  version: 1,                  // optional metadata
+  method: 'POST',              // GET | POST | PUT | PATCH | DELETE | HEAD | OPTIONS
+  path: '/api/users',          // `:param` segments become required params
+  params: z.object({}),        // path params schema
+  query: z.object({}),         // query schema (use z.coerce for numbers)
+  body: z.object({}),          // JSON body schema
+  headers: z.object({}),       // raw header schema
+  response: z.object({}),      // success response schema
+  errors: { EMAIL_TAKEN: z.object({}) }, // known error payloads by code
+  summary / description / tags, // OpenAPI metadata
+  auth: true,                  // informational / extension point
+  metadata: {},                // free-form, consumed by tooling
+})
+```
+
+Types are always **inferred** — you never write generics by hand. Path
+parameters are extracted from the path itself: a contract for
+`/api/posts/:postId/comments/:commentId` requires
+`params: { postId: string, commentId: string }` even without a params schema.
+
+### Query values
+
+The browser sends query values as strings. Use `z.coerce.number()` (and
+friends) for numeric query parameters; validation always happens on the server.
+
+## Server handlers
+
+`defineContractHandler(contract, handler)` performs, in order:
+
+1. validation of `headers`, `params`, `query`, `body` against the schemas;
+2. invocation of your handler with **validated, typed** data + the raw `H3Event`;
+3. optional response validation (see configuration);
+4. conversion of thrown `ApiError`s into the unified error payload.
+
+Handler context:
+
+```ts
+interface ContractHandlerContext {
+  params   // validated path params
+  query    // validated query
+  body     // validated body (undefined for GET/HEAD without body schema)
+  headers  // validated headers (raw record when no schema)
+  event    // H3Event
+  user?    // reserved for auth integrations
+}
+```
+
+## Client usage
+
+```ts
+// Reactive (SSR-aware, no hydration mismatch):
+const { data, error, pending, refresh } = await useApi(GetUser, { params: { id } })
+
+// Imperative (actions, Pinia, event handlers):
+const api = await useApiClient()
+const user = await api.request(GetUser, { params: { id } })            // throws ApiError
+const { data, error } = await api.tryRequest(GetUser, { params: { id } })
+```
+
+Both work in the browser, during SSR and after hydration. During SSR the
+request is executed **inside Nitro** (`event.$fetch`) — no HTTP round-trip to
+itself; the payload is transferred to the client automatically.
+
+## Error handling
+
+```ts
+throw createApiError('USER_NOT_FOUND', 'User not found', 404)
+// or
+throw createApiError({ code: 'VALIDATION_ERROR', statusCode: 400, details })
+```
+
+Wire format:
+
+```json
+{ "error": { "code": "USER_NOT_FOUND", "message": "User not found" } }
+```
+
+On the client, `error` (from `useApi`) or the caught value (from
+`useApiClient().request`) is a reconstructed `ApiError` with `code`,
+`statusCode`, `details` and `issues`. Check it with `isApiError(value)`.
+
+Validation errors are readable:
+
+```text
+[nuxt-api-contract]
+
+Invalid query for GET /api/users
+
+query.limit:
+  Expected number
+  Received string
+```
+
+In production, `received` values are stripped (they may contain passwords or
+tokens) and internal error messages are never leaked.
+
+## SSR
+
+Handled automatically by the transport layer:
+
+```text
+Browser          → HTTP $fetch
+SSR              → internal Nitro call (event.$fetch)
+After hydration  → payload from useAsyncData, no refetch, no mismatch
+```
+
+## OpenAPI
+
+Configure the module (build-time generation from a contracts entry file):
+
+```ts
+apiContract: {
+  openapi: {
+    enabled: true,
+    entry: 'contracts/index.ts',   // default array or named exports
+    path: '/_api-contracts/openapi.json',
+    title: 'My API',
+  },
+}
+```
+
+Or from the CLI (works without a Nuxt build):
+
+```bash
+npx nuxt-api-contract openapi contracts/index.ts --output openapi.json
+npx nuxt-api-contract openapi contracts/index.ts --output openapi.yaml
+```
+
+Zod → OpenAPI conversion is a separate abstraction layer
+(`nuxt-api-contract/openapi`). Unsupported Zod features (transform, refine,
+preprocess) degrade to the closest representable schema with a warning —
+generation never fails.
+
+## Mocking
+
+```ts
+import { mockContract } from 'nuxt-api-contract/client'
+
+mockContract(GetUser, { response: () => ({ id: '1', name: 'Mocked User' }) })
+```
+
+Enable `apiContract: { mocks: true }` and contract handlers return the mock
+response (still validated against the response schema).
+
+## Testing
+
+Full pipeline without an HTTP server:
+
+```ts
+import { callContract } from 'nuxt-api-contract/testing'
+
+const { data, error } = await callContract(GetUser, handler, { params: { id: '1' } })
+expect(error).toBeNull()
+expect(data.id).toBe('1')
+```
+
+Validation → handler → response-validation run exactly like in production.
+See `test/integration/playground.test.ts` for full-stack tests with
+`@nuxt/test-utils`.
+
+## DevTools
+
+When `apiContract.devtools` is enabled in development, a panel lists all
+contracts (method, path, params, tags, error codes) and includes a
+"Try request" form. DevTools is optional — the module works normally without
+it. `@nuxt/devtools-kit` is imported dynamically and guarded.
+
+## Configuration
+
+```ts
+apiContract: {
+  validateResponse: 'development', // 'never' | 'development' | 'always'
+  mocks: false,
+  devtools: true,
+  contractsDirs: ['contracts', 'server/contracts'], // contract auto-import dirs
+  openapi: {
+    enabled: false,
+    path: '/_api-contracts/openapi.json',
+    entry: 'contracts/index.ts',
+    title: undefined, version: undefined, description: undefined,
+  },
+}
+```
+
+Runtime config (private, never in `public`):
+
+```json
+{ "apiContract": { "validateResponse": "development", "mocks": false } }
+```
+
+## Architecture
+
+```text
+src/
+├── module.ts            # Nuxt module (build-time)
+├── cli.ts               # `nuxt-api-contract openapi` CLI
+├── openapi/             # Zod -> OpenAPI (isolated, build-time only)
+├── client.ts            # client-safe barrel (contracts, errors, helpers)
+├── composables.ts       # useApi / useApiClient (requires Nuxt context)
+├── server.ts            # server barrel (handler, validation)
+├── testing.ts           # callContract test helper
+└── runtime/
+    ├── shared/          # contract, types, errors, format, serialization
+    ├── client/          # transport, useApi
+    └── server/          # defineContractHandler, validation, routes
+```
+
+Server-only code never reaches the client bundle; the OpenAPI generator, CLI
+and DevTools are not part of any runtime import chain (importing
+`useApi` adds ~4 kB). See [docs/architecture.md](docs/architecture.md).
+
+## Package exports
+
+| Export | Purpose |
+| --- | --- |
+| `nuxt-api-contract` | Module definition (for `modules: []`) |
+| `nuxt-api-contract/client` | Client-safe: `defineApiContract`, `createApiError`, registry, mocks |
+| `nuxt-api-contract/composables` | `useApi`, `useApiClient` (Nuxt context required) |
+| `nuxt-api-contract/server` | `defineContractHandler`, validation helpers |
+| `nuxt-api-contract/testing` | `callContract` |
+| `nuxt-api-contract/openapi` | OpenAPI generator |
+| `nuxt-api-contract/shared` | Shared primitives |
+
+## Limitations
+
+- Zod 3.x only (`^3.23`); Zod 4 support is on the roadmap.
+- Request bodies are JSON; `multipart/form-data` (file uploads) is planned —
+  the contract abstraction already does not assume JSON-only bodies.
+- OpenAPI conversion is best-effort for `transform` / `refine` / `preprocess`.
+- The standalone mock server (`nuxt-api-contract mock`) is not implemented yet.
+- Auto-discovery is directory-based (`contracts/`, `server/contracts/`) rather
+  than a build-time scanner.
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md). In short: **0.1.0 (released)** ships core
+contracts, OpenAPI generation and the DevTools panel; next: 0.2.0 standalone
+mock server, 0.3.0 extended contract testing, 0.4.0 OpenAPI client generation,
+0.5.0 external API contracts, 0.6.0 contract versioning, 1.0.0 stable API.
+
+## Development
+
+```bash
+npm run build        # build the package (unbuild)
+npm run test         # unit + integration tests
+npm run test:type    # type tests (vitest typecheck)
+npm run typecheck    # tsc --noEmit
+npm run lint         # eslint
+```
+
+## Publishing & Versioning
+
+Versioning follows SemVer with the usual 0.x semantics:
+
+- **0.x.y** (current): `y` (patch) — bug fixes; `x` (minor) — features **and**
+  documented breaking changes (pre-1.0 policy, always listed in CHANGELOG.md).
+- **1.0.0+**: strict SemVer — breaking changes only in major releases.
+
+Release flow:
+
+```bash
+# 1. Bump the version (updates package.json, creates a git tag):
+npm version patch   # or: minor | major | prerelease --preid=rc
+
+# 2. Push with tags:
+git push --follow-tags
+
+# 3. Publish (prepublishOnly runs lint + typecheck + unit/type tests + build):
+npm publish
+
+# Pre-release dist-tag (e.g. 0.2.0-rc.1):
+npm publish --tag next
+```
+
+The package name `nuxt-api-contract` is published unscoped with public access.
+`npm pack --dry-run` shows exactly what ships: `dist/**` (bundled entries +
+`dist/runtime` for Nitro routes) plus README/LICENSE/CHANGELOG — no sources,
+tests or playground.
+
+## License
+
+[MIT](./LICENSE) © modeusweb

package/dist/cli.d.mts

@@ -0,0 +1 @@
+

package/dist/cli.d.ts

@@ -0,0 +1 @@
+

package/dist/cli.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { createJiti } from 'jiti';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { generateOpenApiDocument, pickContracts } from './openapi.mjs';
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  let command;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else if (!command) {
+      command = arg;
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { command, positional, flags };
+}
+async function loadContractsFromEntry(entry) {
+  const jiti = createJiti(import.meta.url, { interopDefault: true });
+  const loaded = await jiti.import(entry);
+  const values = [];
+  if (Array.isArray(loaded)) {
+    values.push(...loaded);
+  } else if (loaded !== null && typeof loaded === "object") {
+    values.push(...Object.values(loaded));
+  } else {
+    throw new Error(`[nuxt-api-contract] Entry "${entry}" must export an array of contracts or named contract exports.`);
+  }
+  const contracts = pickContracts(values);
+  if (contracts.length === 0) {
+    throw new Error(`[nuxt-api-contract] No contracts (kind === 'api-contract') found in "${entry}".`);
+  }
+  return contracts;
+}
+async function main() {
+  const { command, positional, flags } = parseArgs(process.argv.slice(2));
+  if (command === "openapi") {
+    const entry = positional[0];
+    if (!entry || !existsSync(entry)) {
+      console.error("[nuxt-api-contract] Usage: nuxt-api-contract openapi <entry> [--output openapi.json]");
+      process.exitCode = 1;
+      return;
+    }
+    const contracts = await loadContractsFromEntry(resolve(entry));
+    const { document, warnings } = generateOpenApiDocument(contracts, {
+      title: typeof flags.title === "string" ? flags.title : void 0,
+      version: typeof flags.version === "string" ? flags.version : void 0
+    });
+    for (const warning of warnings) {
+      console.warn(`[nuxt-api-contract] OpenAPI warning (${warning.contract}): ${warning.message}`);
+    }
+    const output = typeof flags.output === "string" ? flags.output : flags.yaml === true ? "openapi.yaml" : "openapi.json";
+    const content = flags.yaml === true ? toMinimalYaml(document) : `${JSON.stringify(document, null, 2)}
+`;
+    mkdirSync(dirname(resolve(output)), { recursive: true });
+    writeFileSync(resolve(output), content, "utf8");
+    console.log(`[nuxt-api-contract] OpenAPI document with ${contracts.length} contract(s) written to ${output}`);
+    return;
+  }
+  console.error(`[nuxt-api-contract] Unknown command "${command ?? ""}". Available commands: openapi`);
+  process.exitCode = 1;
+}
+function toMinimalYaml(value, indent = 0) {
+  const pad = " ".repeat(indent);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    return value.map((item) => `${pad}- ${toMinimalYaml(item, indent + 2).trimStart()}`).join("\n");
+  }
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+    return entries.map(([key, item]) => {
+      const rendered = toMinimalYaml(item, indent + 2);
+      if (item !== null && typeof item === "object" && (Array.isArray(item) && item.length > 0 || Object.keys(item).length > 0)) {
+        return `${pad}${key}:
+${rendered}`;
+      }
+      return `${pad}${key}: ${rendered.trimStart()}`;
+    }).join("\n");
+  }
+  if (typeof value === "string") return JSON.stringify(value);
+  return String(value);
+}
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

package/dist/client.d.mts

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

package/dist/client.d.ts

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

package/dist/client.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';